ID:SPEC-070Status:draft
Collection rune
Name:v0.16.0Status:planning
v0.16.0 — Registry-driven sites
The v0.16.0 milestone turns the entity registry into pages and listings, declaratively. It builds directly on v0.15.0's embedding primitives (ref / expand) and delivers three connected specs:
Progress 0/13 work items
Relationships
- Collection rune (SPEC-070) — the plural counterpart to
ref/expand: queries many registry entities (filter/sort/group/limit) and projects them into lists, grids, and tables, with a shared field-match grammar, per-item$itemtemplates, heading-delimited table columns, and shared formatter functions. - Plugin-contributed routes (SPEC-069) — a
contributePagespipeline phase plus a declarativeentityRoutesconfig that synthesizes one page per registered entity, and theembed()embeddability contract. - Plan site scaffolding (SPEC-071) — the proof: a plan site built from refrakt's own
plan/viaentityRoutes+collection, shipped as acreate-refraktscaffold, retiring the bespokeplan build/plan servecommands.
Work Items
Draft 8
WORK-263 main
Collection rune: query engine and built-in layouts The collection rune core — a sentinel-emitting schema plus a postProcess resolver that queries the registry (filter/sort/group/limit) and renders the built-in layouts, with the pinned $item bound-variable contract and the per-layout body interpretation.
0/7 criteria
WORK-264 main
Collection heading-delimited table columns The rich-table path: a table collection's body uses the sections content model (heading = column separator + label, body = per-cell markdoc template with $item), with collection owning the <table>/<thead> and row alignment.
0/4 criteria
WORK-266 main
article-card reference card rune The first core plain-presentational card rune — ordinary attributes, no $item/registry knowledge — shipped as the reference implementation for collection body templates. Proves the "cards are plain runes; the template wires entity fields into attributes" model.
0/4 criteria
WORK-268 main
entityRoutes config-rules adapter The built-in adapter (in @refrakt-md/content) that turns site.entityRoutes into contributed pages: selects entities by type + filter, substitutes placeholders, renders an inline render string or a render-template partial per entity with $item bound, and back-fills sourceUrl.
0/6 criteria
WORK-270 main
Plan entity embeddability (sourceFile + extract) Make plan entities embeddable so {% expand $item.id /%} renders their bodies in entityRoutes detail pages. The plan register hook currently sets sourceUrl only; add sourceFile and an extract that returns the entity rune's transformed body. This is the prerequisite the SPEC-071 dogfood depends on.
0/4 criteria
WORK-271 main
create-refrakt plan-site scaffold Add a plan project type to create-refrakt that scaffolds a complete, runnable plan site: config (plugin + entityRoutes), a seed plan/, and a plan-site/ content dir (layout + dashboards), for a chosen adapter target.
0/5 criteria
WORK-272 main
refrakt plan site dogfood Wire refrakt's own plan/ as a sites.plan site and author its plan-site/ content, proving that entityRoutes + collection replace the bespoke plan serve. This is the milestone's proof-of-practice.
0/4 criteria
WORK-273 main
Deprecate plan build and serve commands Mark plan build and plan serve deprecated, pointing users at the site approach, once refrakt's own plan site proves the replacement. Keep the authoring CLI. Removing the bespoke render stack is a later release, out of scope here.
0/3 criteria
Ready 5
WORK-261 main
Shared field-match parser Implement the canonical field:value selector grammar from SPEC-070 as a single shared module in @refrakt-md/runes, consumed by collection, entityRoutes (SPEC-069), and backlog. The existing plugins/plan/src/filter.ts folds into it, gaining glob/regex, url resolution, and case-consistency while preserving backlog behavior.
0/7 criteria
WORK-262 main
Deferred-body capture for per-entity templates Implement the deferBody mechanism SPEC-070's prototype validated: a catalog flag plus a pre-transform pass in the content loader that captures a rune's pristine body as a source string and empties it, so postProcess can re-parse and transform it per entity with a bound variable. Capture must happen before the page transform — by schema-transform time Markdoc has already resolved the body's $item interpolations to undefined.
0/5 criteria
WORK-265 main
Shared markdoc formatter functions Register a small set of author-facing markdoc functions — currency, date, number, join — in @refrakt-md/runes as the shared value-formatting layer, usable anywhere markdoc transforms run: collection cells, body templates, and entityRoutes render strings. Keeps formatting out of fields and out of any bespoke projection DSL.
0/4 criteria
WORK-267 main
contributePages pipeline phase Add the Plugin.contributePages hook and a contribution phase in the content loader (after file-page registration, before aggregation) that collects ContributedPage[] and runs them through the normal pipeline — the underlying primitive both the entityRoutes adapter and third-party plugins build on.
0/6 criteria
WORK-269 main
embed() embeddability contract Generalize SPEC-066's sourceFile + extract into the embed() contract: an entity is embeddable if it has embed() or (sourceFile + extract). expand and the entityRoutes adapter accept either, so external plugins can make entities embeddable without a source file on disk.
0/4 criteria