@immediately-run/grove 0.1.2 → 0.1.3

package/src/lib/starterSweep.ts

@@ -0,0 +1,97 @@
+// The layout-starter sweep (R3-309, bucket A's gate) — PURE analysis over a starter's
+// source and its rendered markup, so the same checker drives the real starters from
+// disk AND fault-injected fixtures in the test.
+//
+// WHY A GATE AT ALL. A starter is a file people COPY, which makes it teaching
+// material: whatever it does, corpora will do. The safe renderer fails QUIETLY in
+// four ways (ENGINE_BOUNDARY §6 / 03-layout-catalogue §3) — expression props
+// dropped, unregistered tags collapsed to their children, `import` lines rendered
+// as visible prose, mid-line block tags eaten as literal angle brackets — and a
+// shipped starter that trips any of them teaches the failure with no error
+// anywhere. Worse than no starter.
+//
+// The render itself is INJECTED (`render(body) → markup`) because the real one is
+// the published safe renderer plus Grove's component map — exactly what
+// SafeLayout sends a `_layout.mdx` through — and the test wires that up; keeping
+// it out of this module keeps the analysis pure and runnable over strings.
+
+/** Which marker substring an ALWAYS-RENDERING primitive must leave in the markup. A
+ *  primitive whose marker is absent either collapsed (unregistered) or changed its
+ *  root — both are drift a copy would inherit. Data-dependent components
+ *  (`DocList`, `ChildPages`) are deliberately absent: with no corpus in the sweep
+ *  they render nothing BY DESIGN, and their registration is checked through
+ *  `knownTags` instead. */
+export const STARTER_MARKERS: Record<string, string> = {
+  GroveNav: 'grove-nav',
+  GroveSidebar: 'grove-sidebar',
+  GroveFooter: 'grove-footer',
+};
+
+/** Strip a leading frontmatter block — the render path never sees it (the sweep
+ *  asserts the BODY a reader would get). */
+export function stripStarterFrontmatter(src: string): string {
+  return src.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}
+
+/** Every capitalized component tag a starter uses (`<GroveNav`, `<DocList`). */
+export function componentTagsOf(body: string): string[] {
+  return [...body.matchAll(/<([A-Z][A-Za-z0-9]*)/g)].map((m) => m[1]!);
+}
+
+/** The text a reader sees, once every element is stripped away — what "visible
+ *  prose" checks run over. Entities are decoded so an eaten tag shows up as '<'. */
+export function visibleTextOf(markup: string): string {
+  return markup
+    .replace(/<[^>]+>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
+export interface StarterSweepDeps {
+  /** Render a starter BODY through the real safe renderer + component map. Async:
+   *  the real parser is. */
+  render: (body: string) => string | Promise<string>;
+  /** The component names the map actually registers (off-vocabulary detection). */
+  knownTags: ReadonlySet<string>;
+}
+
+/**
+ * Sweep one starter. Returns one violation string per finding — empty means the
+ * starter survives the interpreter.
+ */
+export async function starterViolations(
+  source: string,
+  deps: StarterSweepDeps,
+): Promise<string[]> {
+  const body = stripStarterFrontmatter(source);
+  const markup = await deps.render(body);
+  const text = visibleTextOf(markup);
+  const out: string[] = [];
+
+  // (3) an unresolved import renders as visible prose — a copy would teach it.
+  if (/^\s*(import|export)\s/m.test(text)) out.push('an import/export line renders as visible prose');
+
+  // (4) a block tag that does not open on its own line is eaten by micromark and
+  // shows up as literal angle brackets. Starters carry no raw HTML, so ANY '<' in
+  // the visible text is this failure.
+  if (text.includes('<')) out.push(`literal angle brackets in the visible text (${JSON.stringify(text.match(/.{0,24}<.{0,24}/)?.[0])})`);
+
+  // Starters are structural: braces belong to no tag we document, and under the
+  // interpreter they stay characters — a `{/* comment */}` renders as prose.
+  if (text.includes('{') || text.includes('}')) {
+    out.push('braces render as visible text (an expression or JSX comment the interpreter does not consume)');
+  }
+
+  for (const tag of componentTagsOf(body)) {
+    if (!deps.knownTags.has(tag)) {
+      out.push(`<${tag}> is not in the component map — under the interpreter it collapses to its children`);
+      continue;
+    }
+    const marker = STARTER_MARKERS[tag];
+    if (marker && !markup.includes(marker)) {
+      out.push(`<${tag}> rendered without its "${marker}" marker — the wrapper collapsed or drifted`);
+    }
+  }
+  return out;
+}

package/src/lib/themeAssets.test.ts

@@ -0,0 +1,135 @@
+// R3-315's adversarial exits, at the minter:
+//   • faces mint from LOCAL bytes — no network location is named anywhere;
+//   • switching sets revokes the outgoing URLs (no leak across a theme lifetime);
+//   • a missing font or asset degrades — skipped, never thrown, fallback answers;
+//   • minted URLs and @font-face srcs are `blob:` — no chroot prefix can reach
+//     them (proven non-vacuous by a leaking canary the same check catches).
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { mintThemeAssets } from './themeAssets';
+import type { AssetReader } from './themeAssets';
+
+const BYTES = new Uint8Array([1, 2, 3, 4]);
+const ok: AssetReader = async () => BYTES;
+const miss: AssetReader = async () => {
+  throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+};
+
+const revokeSpy = vi.spyOn(URL, 'revokeObjectURL');
+const createSpy = vi.spyOn(URL, 'createObjectURL');
+
+afterEach(() => {
+  revokeSpy.mockClear();
+  createSpy.mockClear();
+});
+
+describe('minting', () => {
+  it('emits one @font-face per declared face, blob: src, descriptors carried', async () => {
+    const m = await mintThemeAssets(
+      { fonts: [{ family: 'Source Serif 4', src: './fonts/a.woff2', weight: '400 700', style: 'normal' }] },
+      '/app/themes/x.css',
+      ok,
+    );
+    expect(m.minted).toBe(1);
+    expect(m.fontFaceCss).toContain('@font-face');
+    expect(m.fontFaceCss).toContain('"Source Serif 4"');
+    expect(m.fontFaceCss).toContain('font-weight: 400 700');
+    expect(m.fontFaceCss).toMatch(/src: url\("blob:/);
+    expect(m.fontFaceCss).toContain('format("woff2")');
+  });
+
+  it('resolves src RELATIVE TO THE DECLARING FILE and reads the resolved path', async () => {
+    const read = vi.fn(ok);
+    await mintThemeAssets({ fonts: [{ family: 'A', src: '../fonts/a.woff2' }] }, '/app/themes/x.css', read);
+    expect(read).toHaveBeenCalledWith('/app/fonts/a.woff2');
+  });
+
+  it('named assets become --asset-<name> vars on .grove-root', async () => {
+    const m = await mintThemeAssets({ assets: { paper: './textures/paper.jpg' } }, '/app/themes/x.css', ok);
+    expect(m.assetVarsCss).toMatch(/^\.grove-root\{--asset-paper: url\("blob:/);
+    expect(m.minted).toBe(1);
+  });
+
+  it('malformed names/refs are skipped, not thrown', async () => {
+    const m = await mintThemeAssets(
+      { assets: { 'bad name': './x.png', 'also__bad!': './y.png', ok: './z.png' } },
+      '/app/t.css',
+      ok,
+    );
+    expect(m.minted).toBe(1);
+    expect(m.assetVarsCss).toContain('--asset-ok');
+  });
+});
+
+describe('degrade, never break', () => {
+  it('a missing font file skips its @font-face — the token fallback answers', async () => {
+    const m = await mintThemeAssets(
+      { fonts: [{ family: 'Here', src: './here.woff2' }, { family: 'Gone', src: './gone.woff2' }] },
+      '/app/t.css',
+      async (p) => (p.endsWith('here.woff2') ? BYTES : Promise.reject(new Error('ENOENT'))),
+    );
+    expect(m.minted).toBe(1);
+    expect(m.fontFaceCss).toContain('"Here"');
+    expect(m.fontFaceCss).not.toContain('"Gone"');
+  });
+
+  it('a missing named asset skips its var — the var() fallback answers', async () => {
+    const m = await mintThemeAssets({ assets: { paper: './none.jpg' } }, '/app/t.css', miss);
+    expect(m.minted).toBe(0);
+    expect(m.assetVarsCss).toBe('');
+  });
+
+  it('nothing throws for an all-missing set', async () => {
+    const m = await mintThemeAssets({ fonts: [{ family: 'X', src: './x.woff2' }], assets: { a: './b.png' } }, '/app/t.css', miss);
+    expect(m.minted).toBe(0);
+    expect(m.fontFaceCss).toBe('');
+    expect(m.assetVarsCss).toBe('');
+  });
+});
+
+describe('the revoke scope is the theme lifetime (no leak on switch)', () => {
+  it('revoke() releases every minted URL exactly once (idempotent)', async () => {
+    const m = await mintThemeAssets(
+      { fonts: [{ family: 'A', src: './a.woff2' }], assets: { b: './b.png' } },
+      '/app/t.css',
+      ok,
+    );
+    expect(m.minted).toBe(2);
+    m.revoke();
+    m.revoke(); // idempotent
+    expect(revokeSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('mint → revoke → mint again mints FRESH URLs (a switch leaks nothing)', async () => {
+    const first = await mintThemeAssets({ fonts: [{ family: 'A', src: './a.woff2' }] }, '/app/t.css', ok);
+    const urls1 = first.fontFaceCss;
+    first.revoke();
+    const second = await mintThemeAssets({ fonts: [{ family: 'A', src: './a.woff2' }] }, '/app/t.css', ok);
+    expect(second.minted).toBe(1);
+    expect(second.fontFaceCss).not.toBe(urls1); // distinct URL per mint
+    expect(revokeSpy).toHaveBeenCalledTimes(1);
+    second.revoke();
+  });
+});
+
+describe('UNDER DISPATCH no chroot prefix reaches a minted URL or @font-face src', () => {
+  it('the minted output is blob:-only — the mount path appears nowhere in it', async () => {
+    const m = await mintThemeAssets(
+      { fonts: [{ family: 'A', src: './a.woff2' }], assets: { b: './b.png' } },
+      '/mnt/abc123def456/themes/x.css',
+      ok,
+    );
+    const all = m.fontFaceCss + m.assetVarsCss;
+    expect(all).not.toContain('mnt');
+    expect(all).not.toContain('abc123def456');
+    expect(all).toMatch(/blob:/);
+  });
+
+  it('NON-VACUOUS by fault injection: the same assertion catches a leaking src', () => {
+    // The canary: the regression class this exit exists for — an implementation
+    // that writes the resolved path into the CSS instead of the minted URL.
+    const leaky = `@font-face{src: url("/mnt/abc123def456/themes/a.woff2");}`;
+    expect(() => {
+      expect(leaky).not.toContain('abc123def456');
+    }).toThrow();
+  });
+});

package/src/lib/themeAssets.ts

@@ -0,0 +1,143 @@
+// Engine-resolved theme assets (R3-315; plan 05-content-carried-themes §4).
+//
+// A theme DECLARES its fonts and named assets (`fonts: [{family, src, weight,
+// style}]`, `assets: {<name>: <relPath>}`, resolved relative to the declaring
+// file); the ENGINE reads the bytes off the fs, mints a `blob:` URL for each, and
+// hands the result to CSS — an `@font-face` rule per font (emitted into the
+// engine-owned cascade layer) and a `--asset-<name>` custom property per asset.
+// Content never names a network location at all, which is the point: `blob:` is
+// permitted by `img-src`, `font-src` AND `style-src` in every stance including
+// M3, so one mechanism serves fork, dispatch and library modes — and the wiki
+// renders its faces with the network off, in every stance.
+//
+// The revoke scope is the THEME'S lifetime, not a component's — `useObjectUrl`'s
+// component-scoped revoke does not fit an asset set that outlives any single
+// surface, so this module owns the lifecycle explicitly: `revoke()` releases
+// every minted URL, and the switching surface calls it on teardown.
+//
+// DEGRADE, NEVER BREAK: a missing font file skips that `@font-face` (the token's
+// fallback stack answers); a missing named asset skips its var (the var()'s own
+// fallback answers). Nothing throws and nothing renders a broken glyph.
+//
+// The minted URLs carry no path information (`blob:` + origin), so under dispatch
+// the chroot prefix cannot reach a URL or a `@font-face` src by construction —
+// asserted, not assumed, in the tests.
+
+import { resolvePath } from './assetPath';
+
+/** One declared webfont. `src` is relative to the declaring file (or `/…` absolute). */
+export interface FontDeclaration {
+  family: string;
+  src: string;
+  /** CSS `font-weight` descriptor, e.g. `'400 700'` or `'700'`. */
+  weight?: string;
+  /** CSS `font-style` descriptor, e.g. `'normal'` | `'italic'`. */
+  style?: string;
+}
+
+/** The asset declarations a theme (or the engine's own default set) carries. */
+export interface ThemeAssetDeclarations {
+  fonts?: FontDeclaration[];
+  assets?: Record<string, string>;
+}
+
+/** The minted result: CSS the engine owns, plus the revoke handle. */
+export interface MintedThemeAssets {
+  /** `@font-face` rules with `blob:` srcs — the caller emits these inside the
+   *  engine cascade layer. Empty when nothing declared or everything degraded. */
+  fontFaceCss: string;
+  /** A `.grove-root` rule assigning `--asset-<name>: url(blob:…)` per minted
+   *  asset — empty when nothing declared or everything degraded. */
+  assetVarsCss: string;
+  /** How many URLs were minted (observable for leak tests). */
+  minted: number;
+  /** Release every minted URL. Idempotent. */
+  revoke(): void;
+}
+
+/** The bytes-read the minter needs — injected so tests spy and fault-inject. */
+export type AssetReader = (absPath: string) => Promise<Uint8Array<ArrayBuffer> | string>;
+
+const FONT_MIME: Record<string, string> = {
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+};
+const IMAGE_MIME: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+};
+
+function ext(p: string): string {
+  const m = /\.([a-z0-9]+)$/i.exec(p);
+  return m ? m[1].toLowerCase() : '';
+}
+
+/**
+ * Mint the blob URLs + CSS for a declaration set.
+ *
+ * @param decls   the fonts/assets the declaring file asked for
+ * @param basePath the DECLARING FILE's absolute fs path (resolution base)
+ * @param read    the bytes-read (fs)
+ */
+export async function mintThemeAssets(
+  decls: ThemeAssetDeclarations,
+  basePath: string,
+  read: AssetReader,
+): Promise<MintedThemeAssets> {
+  const urls: string[] = [];
+  const fontRules: string[] = [];
+  const varRules: string[] = [];
+
+  const mint = async (ref: string): Promise<string | null> => {
+    try {
+      const abs = resolvePath(basePath, ref);
+      const bytes = await read(abs);
+      const e = ext(abs);
+      const type = FONT_MIME[e] ?? IMAGE_MIME[e] ?? 'application/octet-stream';
+      const url = URL.createObjectURL(new Blob([bytes], { type }));
+      urls.push(url);
+      return url;
+    } catch {
+      return null; // degrade: the fallback stack / var() fallback answers
+    }
+  };
+
+  for (const f of decls.fonts ?? []) {
+    if (!f || typeof f.family !== 'string' || typeof f.src !== 'string') continue;
+    const url = await mint(f.src);
+    if (!url) continue;
+    const descriptors = [
+      `font-family: ${JSON.stringify(f.family)}`,
+      `src: url(${JSON.stringify(url)}) format(${JSON.stringify(ext(f.src) === 'woff2' ? 'woff2' : ext(f.src))})`,
+      ...(f.weight ? [`font-weight: ${f.weight}`] : []),
+      ...(f.style ? [`font-style: ${f.style}`] : []),
+      'font-display: swap',
+    ];
+    fontRules.push(`@font-face{${descriptors.join(';')}}`);
+  }
+
+  for (const [name, ref] of Object.entries(decls.assets ?? {})) {
+    if (!/^[a-z][a-z0-9-]*$/i.test(name) || typeof ref !== 'string') continue;
+    const url = await mint(ref);
+    if (!url) continue;
+    varRules.push(`--asset-${name}: url(${JSON.stringify(url)});`);
+  }
+
+  let revoked = false;
+  return {
+    fontFaceCss: fontRules.join('\n'),
+    assetVarsCss: varRules.length ? `.grove-root{${varRules.join('')}}` : '',
+    minted: urls.length,
+    revoke() {
+      if (revoked) return;
+      revoked = true;
+      for (const u of urls) URL.revokeObjectURL(u);
+    },
+  };
+}

package/src/lib/themeSelection.test.ts

@@ -45,8 +45,8 @@ describe('resolvePolarity — reader, else host, else the palette’s own prefer
 describe('the catalogue carries a preferred polarity for every theme (R3-308)', () => {
   it('every theme declares one, and unknown ids fall back to dark', () => {
     for (const t of THEMES) expect(['light', 'dark']).toContain(t.preferred);
-    expect(preferredPolarity('pixies')).toBe('dark');
-    expect(preferredPolarity('family')).toBe('light');
+    expect(preferredPolarity('editorial')).toBe('dark');
+    expect(preferredPolarity('archive')).toBe('light');
     expect(preferredPolarity('never-heard-of')).toBe('dark');
   });
 });

package/src/mdxComponents.ts

@@ -6,6 +6,8 @@ import Lede from './components/Lede';
 import Infobox from './components/Infobox';
 import More from './components/More';
 import DocList from './components/DocList';
+import ThemeGallery from './components/ThemeGallery';
+import LayoutGallery from './components/LayoutGallery';
 import TagCloud from './components/TagCloud';
 import TagList from './components/TagList';
 import Directory from './components/Directory';
@@ -61,6 +63,8 @@ export const GROVE_MDX = {
   ChildPages,
   Timeline,
   FamilyTree,
+  ThemeGallery,
+  LayoutGallery,
   // Layout primitives — a `_layout.mdx` arranges the shell out of these around an
   // <Outlet/>, so the site chrome is content (see src/lib/layout.ts).
   Outlet,

package/viewer-manifest.schema.json

@@ -57,6 +57,43 @@
         "corpusTooling": { "type": "array", "items": { "type": "string" }, "description": "Keys a corpus's own tooling reads. The engine ignores them." },
         "passThrough": { "type": "boolean", "description": "Whether unknown keys are allowed (they are carried, unread). False makes the vocabulary closed." }
       }
+    },
+    "layouts": {
+      "type": "object",
+      "description": "The layout-starters catalogue (R3-309, bucket A): `_layout.mdx` starters under `content/_layouts/` a contributor or agent copies from. Keyed by starter id (= filename); `layoutRole` is the declared kind the entry and the file must agree on — the field existed in the sample layouts for a year with nothing reading it, and the catalogue is what gives it a job.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["layoutRole", "arranges", "ships", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "layoutRole": {
+            "enum": ["root", "section"],
+            "description": "`root` is an outermost shell (selects the nav arrangement); `section` nests under a root and wraps one folder."
+          },
+          "arranges": { "type": "string", "description": "The chrome the starter arranges around `<Outlet/>`." },
+          "ships": { "type": "boolean", "description": "Whether the starter file exists today (kept false for a catalogue entry whose file lands with a later item)." },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "collections": {
+      "type": "object",
+      "description": "The collection-shapes catalogue (R3-309, bucket C): what a LIST of entries looks like. Behaviour lives here, not in a starter — an `_layout.mdx` cannot hold state, so infinite scroll is an engine component's literal prop, never a file you copy.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["ships", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "component": { "type": "string", "description": "The engine component the shape rides on (absent for shapes that are not component calls at all — a directory URL is one)." },
+          "props": {
+            "type": "object",
+            "description": "The literal attributes a corpus writes to select the shape. Expression props are dropped silently by the interpreter — every documented call must stay literal.",
+            "additionalProperties": { "type": "string" }
+          },
+          "ships": { "type": "boolean", "description": "Whether the shape renders today; a not-yet-shipping entry documents what lands with which item." },
+          "summary": { "type": "string" }
+        }
+      }
     }
   }
 }

package/viewer.manifest.json

@@ -36,7 +36,7 @@
         "title": "string?",
         "children": "node?"
       },
-      "summary": "An aside block with a kind (note / warning / \u2026)."
+      "summary": "An aside block with a kind (note / warning / …)."
     },
     "Lede": {
       "tier": "engine",
@@ -73,9 +73,11 @@
       "sanitizing": false,
       "props": {
         "tag": "string?",
-        "limit": "number?"
+        "limit": "number?",
+        "paginate": "'infinite'?",
+        "batch": "number?"
       },
-      "summary": "A queried list of entries \u2014 the generic index primitive."
+      "summary": "A queried list of entries — the generic index primitive. paginate=\"infinite\" windows it with a sentinel and a stated end (R3-314); the attribute must be a literal."
     },
     "TagCloud": {
       "tier": "engine",
@@ -177,7 +179,7 @@
       "overridable": true,
       "sanitizing": false,
       "props": {},
-      "summary": "The entry's own metadata line (updated, reading time, \u2026)."
+      "summary": "The entry's own metadata line (updated, reading time, …)."
     },
     "RecentlyUpdated": {
       "tier": "engine",
@@ -227,7 +229,7 @@
       "overridable": false,
       "sanitizing": false,
       "props": {},
-      "summary": "The layout chain's inward slot. NOT overridable \u2014 the chain's nesting is engine mechanics, and replacing it detaches every layer from the page it wraps."
+      "summary": "The layout chain's inward slot. NOT overridable — the chain's nesting is engine mechanics, and replacing it detaches every layer from the page it wraps."
     },
     "GroveNav": {
       "tier": "chrome",
@@ -249,6 +251,20 @@
       "sanitizing": false,
       "props": {},
       "summary": "The site footer."
+    },
+    "ThemeGallery": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The themes gallery: one row per shipped theme, enumerated from this manifest — adding a theme adds a row with no edit to the entry."
+    },
+    "LayoutGallery": {
+      "tier": "engine",
+      "overridable": true,
+      "sanitizing": false,
+      "props": {},
+      "summary": "The layouts gallery: the starters, page variants and collection shapes grouped by their three mechanisms, enumerated from this manifest."
     }
   },
   "frontmatter": {
@@ -261,8 +277,118 @@
       "render",
       "nav",
       "order",
-      "tags"
+      "tags",
+      "cover"
     ],
     "passThrough": true
+  },
+  "themes": {
+    "default": {
+      "label": "immediately.run",
+      "preferred": "dark",
+      "ships": true,
+      "summary": "The brand applied to a reading surface — the baseline every other look is measured against."
+    },
+    "archive": {
+      "label": "Archive",
+      "preferred": "light",
+      "ships": true,
+      "summary": "Encyclopedic reference: dense, quiet, contents-forward. Source Serif 4 reading face."
+    },
+    "journal": {
+      "label": "Journal",
+      "preferred": "light",
+      "ships": true,
+      "summary": "A personal notebook or family record: warm, short measure, soft frame. Lora reading face."
+    },
+    "editorial": {
+      "label": "Editorial",
+      "preferred": "dark",
+      "ships": true,
+      "summary": "Loud on purpose — a zine, a gig listing, a release archive. Loud through weight and colour, not a new face."
+    }
+  },
+  "pageVariants": {
+    "doc": {
+      "key": "layout",
+      "value": "doc",
+      "ships": true,
+      "summary": "The default reference page: contents rail, floated infobox, backlink index."
+    },
+    "post": {
+      "key": "layout",
+      "value": "post",
+      "ships": true,
+      "summary": "One measured column, no rails — the long-form entry."
+    },
+    "full": {
+      "key": "layout",
+      "value": "full",
+      "ships": true,
+      "summary": "The widest measure; drawn on the directory board rather than its own."
+    },
+    "bare": {
+      "key": "frame",
+      "value": "none",
+      "ships": true,
+      "summary": "No chrome at all; the entry supplies its own."
+    }
+  },
+  "layouts": {
+    "shell": {
+      "layoutRole": "root",
+      "arranges": "nav · sidebar · content · footer",
+      "ships": true,
+      "summary": "The site shell as copyable content. `nav: side` by default; flip the frontmatter to `nav: top` and drop the `<GroveSidebar/>` line for the top-nav arrangement."
+    },
+    "section": {
+      "layoutRole": "section",
+      "arranges": "shared hero + <Outlet/> + siblings rail",
+      "ships": true,
+      "summary": "A folder frame: one shared header above every entry in a subtree, `<ChildPages/>` below. Nest it under a root shell."
+    },
+    "hero": {
+      "layoutRole": "root",
+      "arranges": "a full-bleed image band over top navigation, then a short grid",
+      "ships": true,
+      "summary": "A landing root: `nav: top`, a hero band, then `<DocList shape=\"grid\" limit=\"4\"/>`. The picture slot renders the link-graph lattice until `cover:` lands."
+    }
+  },
+  "collections": {
+    "feed": {
+      "component": "DocList",
+      "props": {
+        "shape": "feed"
+      },
+      "ships": true,
+      "summary": "A dated list of entries — title, date, lede."
+    },
+    "image-excerpt": {
+      "component": "DocList",
+      "props": {
+        "shape": "grid"
+      },
+      "ships": true,
+      "summary": "Cards with a picture slot and an excerpt. The slot holds the link-graph lattice until `cover:` lands (R3-313); it is not gated on it."
+    },
+    "timeline": {
+      "component": "Timeline",
+      "props": {},
+      "ships": true,
+      "summary": "Entries on a dated spine; already matches the reference archetype."
+    },
+    "directory": {
+      "ships": true,
+      "summary": "A folder URL with no `index.mdx` of its own — the generated listing. Not a component call: the mechanism is the URL itself."
+    },
+    "infinite-scroll": {
+      "component": "DocList",
+      "props": {
+        "paginate": "infinite",
+        "batch": "20"
+      },
+      "ships": true,
+      "summary": "The list that grows as you scroll: a windowed feed with a keyboard-actionable sentinel and a stated end. Behaviour like this can ONLY be an engine component's literal prop — never a starter file."
+    }
   }
 }