Roadmap

The bare directory tree the project will write into. Every other task in iter 1 fills these directories with their first artifact.

Declares the site's top-level functional areas (spec, catalog, list, demo, roadmap) so each one has a known address from day one. Reserved areas stay status:reserved until a later iter activates them.

Each functional area gets its own registry of items. The shape here locks the data contract that templates and components will consume.

Eight thin HTML5 shells, one per page type, all with <vellum-host> at the body root. The composition wiring lands in iter 2; these just establish the surface.

A single Node test asserting the project's structural invariants — registries exist and parse, templates exist and contain <vellum-host>. The early floor for 'is the scaffold intact'.

Wires `npm test` to node:test and keeps `npm run dev` as the no-build static server. Makes the dev loop usable for the first time.

The Foreman deploy gate that closes iter 1. Commits the scaffold and appends a deploy entry to process/work.jsonl with the hash.

Flips /roadmap/ from a reserved placeholder to an active area so it gets routed and resolved. One-line edit in the root registry.

Get @byre/cartographer's parser running in the browser so byre-roadmap can call parse() on the live .plan file.

Loads Brocade's CSS layers and sets the default body class so the roadmap inherits the federation's design tokens from the very first iter that ships content.

Wraps the roadmap page in <vellum-host> with a single mod (roadmap-render). The first real exercise of Vellum's composition pattern.

The actual custom element that fetches a .plan, parses it, resolves includes, and projects the AST to DOM. Everything else in this iter feeds into making this element work.

The /roadmap page itself — a minimal shell that mounts byre-roadmap pointed at the master plan URL.

Smallest viable Signet https:// handler so byre-roadmap can fetch .plan files through the federation's transport abstraction instead of raw fetch.

Tiny page bootstrap that registers custom elements and applies the default Brocade body class. Every template will import this.

Decide and document how the page is reachable during development. Clean /roadmap/ URL requires bundling and is deferred.

Automated check that byre-roadmap mounts and the AST projects the expected shape. The render's regression floor.

The Foreman deploy gate that closes iter 2 — commits the working /roadmap and logs the deploy hash.

Locked module resolution and build strategy. byre.dev adopts the vellum Bundle Registration pattern built as a single artifact via esbuild; dist/ is the deployable. Decision recorded in design/SV1-301-bundle.md.

Full page bootstrap: signet registry, brocade mode, fugue runtime, vellum register, data-page mirror. Module-level singletons under src/runtime/.

Shared data-access layer: fetchRegistry, fetchSpec, fetchCatalogItem. Cached in ram://.

Forms for the landing-page and spec-hub-page surfaces. Form is the structural source-of-truth; projections derive from it. Authored ahead of schedule in this iter.

A build.mjs script at the repo root that generates dist/ from src/templates/ + src/content/ via {{token}} substitution and recursive content copy. No esbuild invocation yet — there is no JS to bundle in pass 1. Wire npm run build to invoke it; npm run dev can stay as-is (python http server) until pass 3 needs a watcher.

Decided directory-based clean URLs: each page is dist/{path}/index.html so URLs work without extensions or rewriters. Recorded in design/SV1-316-sitemap.md with full URL → dist/ → src/content/ mapping table for every page-type.

Site nav and footer authored as data (src/content/site/nav.json + footer.json). build.mjs renders {{nav}} + {{footer}} HTML from these and substitutes into every page. All 9 templates rewritten to pass-1 shape (no vellum-host, no importmap, no JS). Roadmap page renders the plan statically by parsing site-v1.plan at build time via @byre/cartographer.

Authored in SV1-317. Landing page renders site name, tagline, intro, and area-link list from src/content/site/landing.json. Template at src/templates/landing.html.

Authored in SV1-317. Spec index renders all 8 specs as a link list from src/content/specs/registry.json.

Eight spec hub pages authored. Each spec has registry.json (versions + latest), v<latest>/meta.json (id, title, tagline, date, status, audiences), and v<latest>/body.draft (Draft-format spec body covering purpose, primitives, and at least one normative section). build.mjs loads body.draft for each spec and renders it inside <pre> for pass 1; <byre-draft> projection lands in pass 4 (camber).

Authored in SV1-317. Catalog index renders all 7 catalog types from src/content/catalogs/registry.json.

Seven catalog type pages authored. Each type has src/content/catalogs/<type>/registry.json declaring its items (id, title, description, certified). Top-level catalogs/registry.json item-counts updated to reflect actual counts. Live previews remain deferred to pass 4 (camber).

Every catalog item has a reachable page rendered from its registry entry (id, title, description, certified). Live preview slot shown as 'deferred to iter 6 (camber pass)'. Per-item meta.json files not authored — pass-1 build renders from registry entry directly. Richer per-item content can be spun off as separate Foreman scopes per CV-130.

Authored in SV1-317. List index renders the curated-list directory from src/content/lists/registry.json. Empty in pass 1 until SV1-325 authors lists.

Three curated lists authored: 'Starter pack for new federation users', 'Production essentials', 'Self-demonstration tour'. Each list is content in src/content/lists/registry.json (lists array with id, title, curator, description, items[]). build.mjs renders /list/index.html (directory) and /list/<id>/index.html (per-list).

Iter 3 closed. Every task in iter 3 was committed and deployed as it completed (per the project's two-commit-per-scope pattern), so this task is a marker rather than a single deploy. The navigable static site is the deliverable.

@byre/brocade CSS layers (primitives, semantic, modes) copied to dist/css/brocade/ by build.mjs and linked from every page. Site-wide baseline in src/css/site.css uses only Brocade semantic tokens — zero hardcoded colors/spacing/typography. Mode is automatic via @media (prefers-color-scheme) when no class is applied; .mode-light / .mode-dark explicit overrides supported.

Three-segment toggle (Light / Dark / System) mounted in the site nav on every page. Inline script persists selection to localStorage under key 'byre.mode'. Signet local:// integration deferred until iter 5 when the bundle exists; localStorage is a pragmatic substitute that ships zero JS dependencies. The custom-element <mode-toggle> wrapper lands in iter 6 (camber pass).

Site nav + footer styled via src/css/site.css using Brocade tokens. Nav uses flexbox to place links on the left and the mode toggle on the right. Footer is muted-background, centred, small text.

Landing page styled via site.css (Brocade-token-based). landing.form (authored SV1-314) reviewed against the design — concepts (site-identity, area-list, mode-control) consistent with the page's rendered structure. No back-fitting required.

Spec hub styled via site.css. spec-hub.form (authored SV1-314) reviewed — concepts (spec-identity, spec-body, section-list, implementation-list, mode-control, version-selector) consistent with the page's rendered structure. Pass-1 doesn't yet exercise section-list/implementation-list/version-selector affordances; those activate in pass 3+ when surfaces.json projection lands.

src/forms/spec-index.form authored and validates (concepts: site-identity, spec-list, mode-control). Spec index styled via site.css's .spec-list rule.

src/forms/catalog-index.form authored and validates (concepts: site-identity, catalog-type-list, mode-control). Catalog index styled via site.css's .catalog-list rule.

src/forms/catalog-type.form authored and validates. Includes certified-only filter parameter + show-only-certified / show-all-items affordances for iter-6 interactive filters. Styled via site.css's .item-list rule.

src/forms/catalog-item.form authored and validates. Includes item-preview attention-concept + expand-source/collapse-source affordances for iter-6 live preview component. Styled via site.css.

src/forms/list-index.form authored and validates (concepts: site-identity, list-list, mode-control). Styled via site.css.

src/forms/list-detail.form authored and validates (concepts: list-identity, item-refs, mode-control). Styled via site.css.

src/forms/roadmap.form authored and validates with view-mode parameter (tree | sequence) + set-view-tree/sequence affordances for iter-6 view-switching. Roadmap page rendered by build.mjs uses site.css's .rm-tree, .rm-id, .rm-status, .rm-prose rules.

Iter 4 closed. Per the project's two-commit-per-scope pattern, every iter-4 scope was committed as it completed; this is a marker.

src/handlers/{ram,local,https}.mjs created as thin re-exports of @byre/signet/handlers factories (ram, local) plus the in-tree https-handler. src/runtime/signet.mjs updated to import from src/handlers/.

src/mod-bundle.mjs is the bundle entry. Side-effect imports @byre/vellum/register (defines vellum-host + vellum-mod custom elements), src/runtime/signet.mjs (constructs the singleton at module-load), src/runtime/mode.mjs (applyMode), src/runtime/fugue.mjs (runtime init). Mirrors data-template attribute onto body.data-page after DOMContentLoaded. Re-exports signet for future-mod consumers. Per-mod host.register() pattern from SV1-301-bundle.md deferred until SV1-504..508 author actual mods.

build.mjs imports esbuild and bundles src/mod-bundle.mjs → dist/mod-bundle.js (format=esm, target=es2022, browser platform, no sourcemap). Bundle is ~68KB. Auto-injected <script type=module src=/mod-bundle.js> before </body> in every page (parallel to head-links and mode-script auto-injection). esbuild watch mode deferred — pages still re-build via 'npm run build' after source edits.

Explicitly deferred from v1. The vellum substrate is active (bundle loads, custom elements registered, signet singleton constructed, surfaces.json projected per page) — that's the load-bearing iter-5 deliverable. Transitioning each page-type to <vellum-host>+<vellum-mod> composition is pure architectural refactor with zero user-facing change at current site scope. Revisit when there's a concrete dynamic-behavior driver (e.g. client-side filtering at scale, lazy-loaded sections, reactive UI) that justifies the modularisation. Re-opens as a v2 scope.

Deferred with SV1-504. Same rationale.

Deferred with SV1-504. Same rationale.

Deferred with SV1-504. Same rationale.

Deferred with SV1-504. Same rationale.

build.mjs.projectForms() parses each .form via @byre/form's parseForm and projects to /content/forms/<page-type>.surfaces.json. Output captures roles, input streams, attention concepts (with parameters + options), state dimensions (with initial + state list), transitions (from/to/actor), parameter updates (concept/parameter/to/actor), and affordances (available-to, initiates, idempotency, gating). 9 surfaces.json files emitted, one per page-type form. Fugue runtime registration deferred — when per-page mods activate (SV1-504..508), they can fetch their page's surfaces.json and register it with the runtime.

The /roadmap/ page is rendered statically by build.mjs at build time (renderRoadmapBody via @byre/cartographer). It conforms to the pass-1+ model: data lives in design/plan/*.plan, the build resolves includes recursively, output is plain HTML using the standard nav/footer/CSS shell. The iter-2 dynamic <byre-roadmap> custom element is not part of pass-1+; the static rendering is the canonical pattern. Future interactive view-toggle / expand-collapse can land as a vellum mod or as a camber custom element.

Iter 5 closed. Substrate scopes (SV1-501 handlers extracted, SV1-502 bundle entry, SV1-503 esbuild integration, SV1-509 surfaces.json projection, SV1-510 roadmap reconciled) are complete. Per-page-mod composition scopes (SV1-504..508) explicitly archived — see their task descriptions.

src/components/byre-draft.mjs defines the <byre-draft src=...> custom element. Fetches via signet (absolute URL via location.origin), parses via a small in-tree Draft renderer (sections, prose, requirements with RFC2119 levels), projects to semantic light-DOM HTML. Spec hub templates now wrap the static <pre> fallback inside <byre-draft> so the custom element replaces innerHTML when the bundle loads; the static <pre> stays as graceful-degradation fallback. CSS classes added to site.css for .draft-section, .draft-prose, .draft-requirement, .draft-level. Hand-rolled parser used because @byre/draft's index.mjs imports node:fs which esbuild can't bundle for browser. Future work: expose a browser-safe parser export from @byre/draft and swap to it.

src/components/mode-toggle.mjs defines <mode-toggle> with shadow DOM. Brocade tokens forwarded via custom-property fallbacks. Same localStorage['byre.mode'] key as the inline pass-2 button group; both can coexist (inline buttons remain in nav as graceful-degradation fallback; templates can switch to <mode-toggle> later or surface it elsewhere). Dispatches a bubbling 'mode-change' CustomEvent on selection. Registered by the bundle (imported in src/mod-bundle.mjs).

src/components/catalog-preview.mjs defines <catalog-preview src=... [sandboxed]>. Three render paths: deferred (source.mjs does not yet exist — signet $exists probe gates), direct-DOM (default; dynamic import + call default export with root element), iframe sandbox (with sandboxed attribute; srcdoc wrapper loads source via import inside the iframe). catalog-item template now wraps the preview slot in this element. Per-item source.mjs files come as separate Foreman scopes; the element shows a 'Preview not yet available' deferred-state message until they land. Browser-verified on https://byre.dev/catalog/camber-components/camber-button/: element present, data-state='deferred', message rendered.

Certified-only filter on catalog-type pages. Each <li> in the item list carries data-certified='true|false'. Filter checkbox toggles body.certified-only class; CSS hides non-certified items. Certified items show a green-background ✓ badge inline. Curated-only filter and search input deferred — they have no current backing data (curated/uncurated distinction not yet declared in items).

Iter 6 closed. <byre-draft> (SV1-601), <mode-toggle> (SV1-602), <catalog-preview> (SV1-603) all authored, integrated into the bundle, and live. Catalog filter (SV1-604) live as inline-JS toggle on each catalog type page.

JSON-LD structured data auto-injected by build.mjs into landing (schema.org/WebSite), spec hubs (TechArticle), and catalog items (SoftwareSourceCode). Block lives in <head>. Build test asserts presence on landing + a representative spec hub + a representative catalog item.

/content/specs/<id>/v<ver>/body.txt emitted by build.mjs alongside the .draft source for every spec that has a body.draft. Pass 1 uses the raw Draft text — Draft is plain-prose-friendly. A richer rendered-prose variant can land later if needed.

Browser-driven audit on the live site via paired Brave on https://byre.dev/. Fixed: byre-draft heading order (was h3→h5 jump from misuse of Draft 'level' attribute; now uses nesting depth — all top-level sections render as h2 sibling), skip link as first body child with .skip-link CSS that reveals on focus, <main id='main-content'> target for the skip link, aria-current='page' set at bundle load by mod-bundle.mjs based on longest-prefix match of location.pathname against nav links, :focus-visible outline rule using Brocade --brocade-color-border-focus token. Mode-variant testing (reduced-motion, high-contrast, reduced-transparency) deferred to a separate audit scope — Brocade handles via @media but each variant should be visually verified.

Live measurements (paired Brave on https://byre.dev/, May 2026): landing 47 KB total / FCP 464 ms; vellum spec hub 53 KB / FCP 168 ms (cache-warm); roadmap (40 KB inline-plan HTML) 37 KB total / FCP 404 ms. JS over the wire is 19 KB gzipped (mod-bundle.js 78 KB uncompressed). All well under SC limits. Budget locked at: ≤200 KB JS uncompressed (build test asserts), ≤500 ms FCP on LAN (no automated assertion — measured manually per release).

/roadmap/ is canonical (dist/roadmap/index.html) and renders the master plan statically at build time via @byre/cartographer parse. No mirror needed; the page IS the canonical surface.

`npx byre-architect inspect .` passes at both base and full levels (5/5 present, 0 missing). Added design/ROADMAP.md as a pointer doc and conformance/README.md documenting where conformance tests live (src/tests/, run via npm test). The js profile reports 14 missing items, all of which are JS library-package conventions (src/index.mjs entry, exports map, downstream-consumer conformance kit, vite.config.mjs, etc.) — byre.dev is a static site, not a publishable library, so the js profile does not apply. Noted in risks (R-110) and conformance/README.md.

Build smoke tests assert presence of /content/specs/<id>/v<ver>/{meta.json,body.draft,body.txt} for representative specs. surfaces.json deferred to iter 5 (vellum-pass projection from forms). curl verification can be added when a deploy host exists.

Iter 7 closed. Every polish task was committed and deployed as it completed (two-commit-per-scope pattern). The site is live at https://byre.dev/ with JSON-LD on hub pages, body.txt CLI endpoints, a11y fixes (heading order, skip link, aria-current, focus-visible), perf budget locked under 200KB JS and 500ms FCP, and architect base+full conformance passing.