@immediately-run/grove 0.1.1 → 0.1.3

package/src/lib/corpusScan.ts

@@ -21,6 +21,7 @@
 
 import type { Frontmatter } from './frontmatter';
 import { parseFrontmatter } from './frontmatter';
+import { collectHeadings } from '@immediately-run/sdk';
 
 /** The metadata map shape the SDK hooks read (`FilesMetadata`). */
 export type CorpusMetadata = Record<string, Frontmatter>;
@@ -71,7 +72,14 @@ export async function listCorpusFiles(root: string, fs: ScanFs, maxDepth = 12):
   return out.sort();
 }
 
-/** Read + parse a list of entries into the metadata map, bounded-concurrently. */
+/** Read + parse a list of entries into the metadata map, bounded-concurrently.
+ *
+ * The additive headings index extension (GROVE_AGENT_SPEC §4): a dispatched row
+ * carries its entry's `headings: [{id, text, depth}]`, ids from the same
+ * mdx-plugins canon the render path emits (via the SDK's `collectHeadings` — one
+ * implementation, shared with the tool that reads the field). The author's own
+ * frontmatter `headings` key wins; a row with none of either simply lacks the
+ * field (readers degrade to body reads). */
 async function readAll(paths: string[], fs: ScanFs): Promise<CorpusMetadata> {
   const meta: CorpusMetadata = {};
   let next = 0;
@@ -82,7 +90,14 @@ async function readAll(paths: string[], fs: ScanFs): Promise<CorpusMetadata> {
       const path = paths[i];
       try {
         const raw = await fs.readFile(path, 'utf8');
-        meta[path] = parseFrontmatter(raw).data;
+        const parsed = parseFrontmatter(raw);
+        const row = parsed.data;
+        const headings = collectHeadings(parsed.body);
+        if (headings.length && !Object.prototype.hasOwnProperty.call(row, 'headings')) {
+          meta[path] = { ...row, headings } as Frontmatter & { headings?: unknown };
+        } else {
+          meta[path] = row;
+        }
       } catch {
         // One unreadable entry must not empty the whole corpus. It is simply absent from
         // the index — the same state it would be in if the author had not written it.

package/src/lib/editTarget.test.ts

@@ -0,0 +1,108 @@
+// R3-266 — dispatched content is writable, and the MOUNT decides.
+//
+// The two things these tests pin are the two things that were wrong before: a dispatched
+// viewer must send its edit to the CORPUS (never to Grove's own repo), and whether it may
+// offer one at all must be the corpus mount's CURRENT mode rather than a property of the
+// packaging or a flag latched at boot.
+import { describe, expect, it } from 'vitest';
+import { corpusWritable, editTarget, keyToSelfPath } from './editTarget';
+import type { CorpusIdentity } from './editTarget';
+import type { SandboxMount } from '@immediately-run/sdk/mounts';
+
+const fork: CorpusIdentity = {
+  dispatched: false,
+  contentRoot: '/app/content/',
+  mountId: null,
+};
+const dispatched: CorpusIdentity = {
+  dispatched: true,
+  contentRoot: '/task/t1/dir/',
+  mountId: '/task/t1/dir',
+};
+
+const mount = (over: Partial<SandboxMount> = {}): SandboxMount =>
+  ({ type: 'firestore', path: '/task/t1/dir', id: '/task/t1/dir', mode: 'rw', ...over }) as SandboxMount;
+
+describe('editTarget — the verb follows the authority, not the packaging', () => {
+  it('a FORK edits its own source through the self-scoped present→edit transition', () => {
+    expect(editTarget('/app/content/handbook/onboarding.mdx', fork)).toEqual({
+      via: 'self',
+      path: 'content/handbook/onboarding.mdx',
+    });
+  });
+
+  it('a DISPATCHED viewer delegates the CORPUS file, never a path in its own repo', () => {
+    expect(editTarget('/task/t1/dir/plot/the-rail.mdx', dispatched)).toEqual({
+      via: 'delegate',
+      mountId: '/task/t1/dir',
+      relPath: 'plot/the-rail.mdx',
+    });
+  });
+
+  it('is corpus-relative under dispatch — the mount root IS the corpus root', () => {
+    const t = editTarget('/task/t1/dir/home.mdx', dispatched);
+    expect(t).toMatchObject({ relPath: 'home.mdx' });
+    // The fork's `content/` segment must NOT leak into a corpus-relative path: the
+    // delegated chroot is minted AT the content directory.
+    expect((t as { relPath: string }).relPath.startsWith('content/')).toBe(false);
+  });
+
+  it('offers nothing for a key outside the mounted corpus (a leftover from the viewer)', () => {
+    expect(editTarget('/app/content/home.mdx', dispatched)).toBeNull();
+  });
+
+  it('offers nothing when a dispatched corpus has no mount id to delegate from', () => {
+    expect(editTarget('/task/t1/dir/home.mdx', { ...dispatched, mountId: null })).toBeNull();
+  });
+
+  it('offers nothing for the corpus root itself (a directory is not an entry)', () => {
+    expect(editTarget('/task/t1/dir/', dispatched)).toBeNull();
+  });
+
+  it('never throws on a junk key', () => {
+    expect(editTarget('', dispatched)).toBeNull();
+    expect(editTarget(undefined as unknown as string, fork)).toBeNull();
+  });
+
+  it('keyToSelfPath strips the app anchor exactly as the fork URLs require', () => {
+    expect(keyToSelfPath('/app/content/x.mdx')).toBe('content/x.mdx');
+    expect(keyToSelfPath('/content/x.mdx')).toBe('content/x.mdx');
+  });
+});
+
+describe('corpusWritable — the mount decides, live', () => {
+  it('a fork asks about its working tree, as before', () => {
+    expect(corpusWritable([{ type: 'worktree', path: '/app', mode: 'rw' } as SandboxMount], fork)).toBe(true);
+    expect(corpusWritable([{ type: 'worktree', path: '/app', mode: 'ro' } as SandboxMount], fork)).toBe(false);
+    expect(corpusWritable([], fork)).toBe(false);
+  });
+
+  it('a DISPATCHED viewer on an rw corpus is writable — packaging is not trust', () => {
+    expect(corpusWritable([mount()], dispatched)).toBe(true);
+  });
+
+  it('a ro corpus is not writable, so the affordance is hidden rather than EROFS-ing', () => {
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+  });
+
+  it('follows a LIVE downgrade: the same mount re-announced ro flips the answer', () => {
+    expect(corpusWritable([mount({ mode: 'rw' })], dispatched)).toBe(true);
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+  });
+
+  it('a corpus mount that has vanished is not writable', () => {
+    expect(corpusWritable([mount({ id: 'space:other', path: '/mnt/x' })], dispatched)).toBe(false);
+    expect(corpusWritable([], dispatched)).toBe(false);
+    expect(corpusWritable(null, dispatched)).toBe(false);
+  });
+
+  it('matches a mount that carries no id by its path (what the host publishes)', () => {
+    expect(corpusWritable([{ type: 'firestore', path: '/task/t1/dir', mode: 'rw' } as SandboxMount], dispatched)).toBe(
+      true,
+    );
+  });
+
+  it('never reports writable when there is no mount id at all', () => {
+    expect(corpusWritable([mount()], { ...dispatched, mountId: null })).toBe(false);
+  });
+});

package/src/lib/editTarget.ts

@@ -0,0 +1,93 @@
+// R3-266 — WHERE an edit goes, and whether one may be offered at all.
+//
+// Grove ships in two packagings, and the edit verb differs between them because the
+// AUTHORITY does, not because dispatched content is somehow less editable:
+//
+//   • FORK      — the corpus is this app's own repo, so "edit this entry" is the
+//                 present→edit transition on our own source: `requestEdit({ path })`,
+//                 which is **self-scoped by contract** ("v1 supports only a repo-relative
+//                 path in the CURRENT repo").
+//   • DISPATCH  — the corpus is a MOUNT somebody handed us. `requestEdit` there would
+//                 name a path in GROVE's repo, so the same call would offer to edit the
+//                 viewer instead of the wiki on screen. The right verb is the one for a
+//                 file in a mount: `invokeTask('edit-file', { file: capFile(...) })`,
+//                 attenuating the corpus delegation down to the single entry.
+//
+// The previous code withheld the affordance under dispatch and said so in a comment that
+// was careful to call it temporary. It was still the wrong outcome: dispatch changes the
+// PACKAGING, not the authority — the same corpus, forked, is editable — so a read-only
+// dispatched viewer breaks packaging-is-not-trust exactly where a reader would notice.
+//
+// **The mount decides.** Writability is a property of the delegation's current mode, not
+// of how the app was loaded. That is why `corpusWritable` takes the live mount list rather
+// than the boot-time flag: a role downgrade re-announces the mount `ro`, and the
+// affordance must disappear rather than surface `EROFS` when clicked.
+//
+// Pure — no SDK, no React — so all of the above is testable without a host.
+
+import type { SandboxMount } from '@immediately-run/sdk/mounts';
+
+/** How an edit of a content entry is delivered. */
+export type EditTarget =
+  /** The fork: our own repo, via the self-scoped present→edit transition. */
+  | { via: 'self'; path: string }
+  /** Dispatch: one file of the delegated corpus, handed to the platform editor. */
+  | { via: 'delegate'; mountId: string; relPath: string };
+
+export interface CorpusIdentity {
+  /** Whether the corpus is a mount rather than this app's own repo. */
+  dispatched: boolean;
+  /** The content root, with a trailing slash (`getContentRoot()`). */
+  contentRoot: string;
+  /** The corpus mount id, when dispatched (`getCorpusMountId()`). */
+  mountId: string | null;
+}
+
+/** `/app/content/x.mdx` → `content/x.mdx` — the fork's repo-relative path. */
+export function keyToSelfPath(key: string): string {
+  return key.replace(/^\/app\//, '').replace(/^\//, '');
+}
+
+/**
+ * Where an edit of `entryKey` should go, or null when there is nowhere to send it.
+ *
+ * Null is not "read-only" — that is {@link corpusWritable}'s question. Null means the key
+ * does not name a file in this corpus at all, or a dispatched viewer has no mount id to
+ * delegate from (an older host that published the corpus without one). Either way there is
+ * nothing to offer, and offering it anyway would produce a refusal the reader must decode.
+ */
+export function editTarget(entryKey: string, corpus: CorpusIdentity): EditTarget | null {
+  if (typeof entryKey !== 'string' || entryKey === '') return null;
+  if (!corpus.dispatched) return { via: 'self', path: keyToSelfPath(entryKey) };
+  if (!corpus.mountId) return null;
+  if (!entryKey.startsWith(corpus.contentRoot)) return null;
+  const relPath = entryKey.slice(corpus.contentRoot.length);
+  return relPath ? { via: 'delegate', mountId: corpus.mountId, relPath } : null;
+}
+
+/**
+ * May this instance offer an edit at all, given the mounts it holds RIGHT NOW?
+ *
+ * A fork asks about its working tree, as before. A dispatched viewer asks about the corpus
+ * mount — and asks the LIVE mount list, not the boot-time flag, so a live `rw → ro`
+ * downgrade (a role change the host re-announces on the same mount id) hides the
+ * affordance on the next render. That is the whole difference between "hidden because you
+ * may not" and "shown, then `EROFS` when you try".
+ *
+ * A corpus mount that has vanished from the list answers `false`: no mount, no write.
+ */
+export function corpusWritable(
+  mounts: readonly SandboxMount[] | null | undefined,
+  corpus: CorpusIdentity,
+): boolean {
+  const list = mounts ?? [];
+  if (!corpus.dispatched) {
+    return list.some((m) => m.type === 'worktree' && m.mode !== 'ro');
+  }
+  if (!corpus.mountId) return false;
+  const mount = list.find((m) => (m.id ?? m.path) === corpus.mountId);
+  // `mode` is absent on the primary repo mount and rw by default elsewhere; a corpus
+  // mount that reports nothing is treated as writable exactly as `resolveOpenWiki` reads
+  // it, so the two never disagree about the same mount.
+  return !!mount && mount.mode !== 'ro';
+}

package/src/lib/inlineProse.parity.test.ts

@@ -0,0 +1,52 @@
+// R3-531 — the parity assertion: `parseInlineProse` agrees with the SDK safe
+// renderer's actual micromark path on the supported subset.
+//
+// The canon test lives in mdx-plugins; this one runs the SAME fixture through
+// `parseSafeMdast` (the real producer — the same published bytes the sandbox
+// resolves, inlined into these tests for exactly that reason) and asserts the
+// first paragraph's inline children, normalised into `InlineProseNode`s, equal
+// what the canon parses. Agreement by parallel implementation is a promise;
+// this is the mechanism.
+import { describe, expect, it } from 'vitest';
+import { parseSafeMdast, type SafeMdastNode } from '@immediately-run/sdk';
+import { INLINE_PROSE_FIXTURE, parseInlineProse, type InlineProseNode } from '@immediately-run/mdx-plugins';
+
+// mdast inline vocabulary → InlineProseNode. Only the supported subset maps;
+// anything else (a link, raw html) the fixture never produces, and a node of
+// that shape failing the deep-equal is the drift alarm firing.
+function toInlineProse(nodes: SafeMdastNode[]): InlineProseNode[] {
+  return nodes.map((n): InlineProseNode => {
+    switch (n.type) {
+      case 'text':
+        return { type: 'text', value: n.value ?? '' };
+      case 'inlineCode':
+        return { type: 'code', value: n.value ?? '' };
+      case 'strong':
+        return { type: 'strong', children: toInlineProse(n.children ?? []) };
+      case 'emphasis':
+        return { type: 'emphasis', children: toInlineProse(n.children ?? []) };
+      default:
+        throw new Error(`unexpected mdast node in a fixture paragraph: ${n.type}`);
+    }
+  });
+}
+
+describe('parseInlineProse matches the safe renderer on the supported subset', () => {
+  for (const c of INLINE_PROSE_FIXTURE) {
+    it(`agrees with parseSafeMdast: ${JSON.stringify(c.text).slice(0, 48)}`, async () => {
+      const tree = await parseSafeMdast(`\n${c.text}\n`);
+      const paragraph = tree.children?.find((n) => n.type === 'paragraph');
+      if (!paragraph) {
+        // The one case micromark renders as NO paragraph — an empty field —
+        // and the canon agrees by returning no nodes at all.
+        expect(c.tokens).toEqual([]);
+        expect(parseInlineProse(c.text)).toEqual([]);
+        return;
+      }
+      expect(toInlineProse(paragraph.children ?? [])).toEqual(c.tokens);
+      // And the canon here in grove's own dependency graph — the version this
+      // repo actually ships — produces the same shape the fixture pins.
+      expect(parseInlineProse(c.text)).toEqual(c.tokens);
+    });
+  }
+});

package/src/lib/layout.ts

@@ -20,6 +20,35 @@ function layoutKeyForDir(dir: string): string {
   return dir + '_layout.mdx';
 }
 
+/**
+ * R3-309 — which nav arrangement the ROOT layout asks for. The root `_layout.mdx`'s
+ * frontmatter may carry `nav: top | nav: side`; anything else (absent, misspelled,
+ * another shape) falls back to `'side'`, the arrangement Grove has always shipped —
+ * an undeclared value must never render an unstyled page. The top arrangement is the
+ * base `.grove-shell` CSS; `side` is the variant, so both polarities of this choice
+ * have rules on the other side of the attribute.
+ */
+export function resolveNavMode(
+  rootLayoutMeta: Record<string, unknown> | undefined,
+): 'top' | 'side' {
+  return rootLayoutMeta?.nav === 'top' ? 'top' : 'side';
+}
+
+/**
+ * R3-309 — which page variant (bucket B) an entry selects. `layout: doc | post |
+ * full` in the entry's frontmatter; anything else — absent, misspelled, a future
+ * value the CSS does not implement — falls back to `'doc'`, the reference look,
+ * rather than rendering an unstyled page. The declared set is exactly what
+ * `GroveApp.css` carries `[data-layout]` rules for; the consistency test pins the
+ * two together.
+ */
+export function resolvePageLayout(
+  entryMeta: Record<string, unknown> | undefined,
+): 'doc' | 'post' | 'full' {
+  const v = entryMeta?.layout;
+  return v === 'post' || v === 'full' ? v : 'doc';
+}
+
 /** Does an entry/layout opt out of an inherited layout chain? `frame: none`
  *  (or `frame: false`) means "render me bare / stop inheritance above here". */
 function optsOut(meta: Record<string, unknown> | undefined): boolean {

package/src/lib/openWiki.test.ts

@@ -1,6 +1,13 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { resolveOpenWiki, OPEN_WIKI_TASK, CONTENT_MOUNT_TYPE } from './openWiki';
-import { getContentRoot, setContentRoot, resetContentRoot, isDispatched, APP_CONTENT_ROOT } from './contentRoot';
+import {
+  getContentRoot,
+  getCorpusMountId,
+  setContentRoot,
+  resetContentRoot,
+  isDispatched,
+  APP_CONTENT_ROOT,
+} from './contentRoot';
 import { slugToKey, isContentEntry, homeKey, contentDir, keyToHref, sandboxPathToKey } from './content';
 import { layoutChainForKey } from './layout';
 import type { SandboxMount } from '@immediately-run/sdk/mounts';
@@ -13,14 +20,14 @@ afterEach(resetContentRoot);
 describe('resolveOpenWiki — the delegated corpus', () => {
   it('resolves the dir param mounted at the host-minted chroot', () => {
     const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/task/t1/dir')]);
-    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: false, via: 'task' });
+    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: false, via: 'task', mountId: '/task/t1/dir' });
   });
 
   it('reports a read-only delegation without refusing it', () => {
     // Sharing a corpus read-only is legitimate — the reader still reads. Only the WRITE
     // affordances may consult this; refusing the whole open would break the ordinary case.
     const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/task/t1/dir', { mode: 'ro' })]);
-    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: true, via: 'task' });
+    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: true, via: 'task', mountId: '/task/t1/dir' });
   });
 
   it('is not a callee when there is no task input — the ordinary fork boot', () => {
@@ -48,7 +55,7 @@ describe('resolveOpenWiki — the delegated corpus', () => {
     // The host owns the `/task/<slot>/<param>` grammar; if it ever renames the segment,
     // suffix-matching alone would cancel a task the user really asked for.
     const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/mnt/abc123')]);
-    expect(r).toEqual({ ok: true, root: '/mnt/abc123', readOnly: false, via: 'task' });
+    expect(r).toEqual({ ok: true, root: '/mnt/abc123', readOnly: false, via: 'task', mountId: '/mnt/abc123' });
   });
 
   it('does not guess between two foreign mounts', () => {
@@ -72,7 +79,7 @@ describe('repo-load dispatch — a cold URL load, with no task input at all', ()
       mount('/app'),
       mount('/mnt/deadbeef', { type: CONTENT_MOUNT_TYPE, name: 'neumark/book-nine-from-here' }),
     ]);
-    expect(r).toEqual({ ok: true, root: '/mnt/deadbeef', readOnly: false, via: 'repo-load' });
+    expect(r).toEqual({ ok: true, root: '/mnt/deadbeef', readOnly: false, via: 'repo-load', mountId: '/mnt/deadbeef' });
   });
 
   it('carries a read-only delegation through', () => {
@@ -214,3 +221,37 @@ describe('routing — the URL space follows the packaging', () => {
     expect(key).toBe('/task/t1/dir/app/content/home.mdx');
   });
 });
+
+// R3-266 — the corpus mount ID, which is what an onward delegation NAMES. Without it a
+// dispatched viewer can locate the corpus and still not hand one of its files to the
+// platform editor, which is the whole of the dispatched write path.
+describe('resolveOpenWiki — the corpus mount id (the onward-delegation handle)', () => {
+  it('prefers the host-published id over the path', () => {
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [
+      mount('/task/t1/dir', { id: 'space:abc' }),
+    ]);
+    expect(r).toMatchObject({ ok: true, mountId: 'space:abc' });
+  });
+
+  it('falls back to the mount PATH, which is exactly what the host publishes for a chroot', () => {
+    // `mintDelegations` names the descriptor `{ path, type: 'task-delegation', id: path }`,
+    // so path and id coincide for a task delegation — the fallback is the same answer, not
+    // a guess, and it keeps working against a host that publishes no id at all.
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/task/t1/dir')]);
+    expect(r).toMatchObject({ ok: true, mountId: '/task/t1/dir' });
+  });
+
+  it('carries the id through the repo-load branch too', () => {
+    const r = resolveOpenWiki(null, [
+      mount('/mnt/deadbeef', { type: CONTENT_MOUNT_TYPE, id: 'github:neumark/book@main' }),
+    ]);
+    expect(r).toMatchObject({ ok: true, via: 'repo-load', mountId: 'github:neumark/book@main' });
+  });
+
+  it('reaches the contentRoot module, so the affordance can read it back', () => {
+    setContentRoot('/task/t1/dir', { readOnly: false, mountId: 'space:abc' });
+    expect(getCorpusMountId()).toBe('space:abc');
+    resetContentRoot();
+    expect(getCorpusMountId()).toBeNull();
+  });
+});

package/src/lib/openWiki.ts

@@ -25,7 +25,16 @@ export const DIR_PARAM = 'dir';
 export const CONTENT_MOUNT_TYPE = 'content';
 
 export type OpenWikiResolution =
-  | { ok: true; root: string; readOnly: boolean; via: 'task' | 'repo-load' }
+  | {
+      ok: true;
+      root: string;
+      readOnly: boolean;
+      via: 'task' | 'repo-load';
+      /** The corpus mount's id — what an onward delegation names (R3-266). Falls back to
+       *  the mount PATH, which is exactly what the host publishes as the id for a task
+       *  chroot (`mintDelegations` uses the mount point as the descriptor id). */
+      mountId: string;
+    }
   | { ok: false; reason: 'not-a-callee' | 'wrong-task' | 'no-mount' };
 
 /**
@@ -53,7 +62,13 @@ export function resolveOpenWiki(
   // input and would otherwise fall out as `not-a-callee` and render our own corpus.
   const marked = mounts.find((m) => m.type === CONTENT_MOUNT_TYPE);
   if (marked) {
-    return { ok: true, root: marked.path, readOnly: marked.mode === 'ro', via: 'repo-load' };
+    return {
+      ok: true,
+      root: marked.path,
+      readOnly: marked.mode === 'ro',
+      via: 'repo-load',
+      mountId: marked.id ?? marked.path,
+    };
   }
 
   if (!input) return { ok: false, reason: 'not-a-callee' };
@@ -67,7 +82,7 @@ export function resolveOpenWiki(
   // `mode` is absent on the primary repo mount and rw by default elsewhere. A read-only
   // delegation is a legitimate way to share a corpus — the reader still reads — so it
   // resolves normally and only the WRITE affordances consult this flag.
-  return { ok: true, root: hit.path, readOnly: hit.mode === 'ro', via: 'task' };
+  return { ok: true, root: hit.path, readOnly: hit.mode === 'ro', via: 'task', mountId: hit.id ?? hit.path };
 }
 
 /** The message a failed resolution should show, in the reader's terms rather than the

package/src/lib/pageVariants.test.tsx

@@ -0,0 +1,87 @@
+// The bucket-B gate + the value-3 invariant (R3-309): page variants are CSS
+// selected by data attributes, so the checks are consistency — every variant the
+// CSS implements is reachable, every reachable value has a rule, an undeclared
+// value falls back — plus the promise that deleting every `_layout.mdx` still
+// yields the full default shell.
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import DefaultLayout from '../components/DefaultLayout';
+import { resolveNavMode, resolvePageLayout } from './layout';
+import { GroveShellContext, OutletContext, type GroveShell } from './shell';
+
+const css = readFileSync(join(process.cwd(), 'src', 'GroveApp.css'), 'utf8');
+
+const dataLayoutRules = new Set([...css.matchAll(/\[data-layout="([^"]+)"\]/g)].map((m) => m[1]!));
+const dataNavRules = new Set([...css.matchAll(/\[data-nav="([^"]+)"\]/g)].map((m) => m[1]!));
+
+describe('page variants — every declared value has a rule, every rule is reachable (bucket B)', () => {
+  it('the CSS implements exactly the three layout variants the engine can emit', () => {
+    // resolvePageLayout is the closed emitter: doc | post | full. A CSS rule for a
+    // fourth value would be dead selectors; an emitter value without a rule would
+    // be a silently unstyled page. Pinned together so neither can drift alone.
+    expect(dataLayoutRules).toEqual(new Set(['doc', 'post', 'full']));
+    for (const v of ['doc', 'post', 'full'] as const) {
+      expect(resolvePageLayout({ layout: v })).toBe(v);
+    }
+  });
+
+  it('an undeclared layout value falls back to the reference look, never an unstyled page', () => {
+    expect(resolvePageLayout(undefined)).toBe('doc');
+    expect(resolvePageLayout({})).toBe('doc');
+    expect(resolvePageLayout({ layout: 'wide-but-unimplemented' })).toBe('doc');
+    expect(resolvePageLayout({ layout: 7 })).toBe('doc');
+  });
+
+  it('`frame: none` is the fourth variant and needs no layout rule — it removes the shell', () => {
+    // Bare-by-frontmatter is handled in GroveWiki (frameNone drops the chain); it
+    // selects no [data-layout] variant, so its absence from the CSS set is the
+    // contract, asserted here so a future "bare" CSS rule is a visible decision.
+    expect(dataLayoutRules.has('none')).toBe(false);
+  });
+});
+
+describe('nav arrangement — selectable, with both polarities real (R3-309)', () => {
+  it("'side' carries CSS rules; 'top' is the base .grove-shell grid they override", () => {
+    // The top arrangement is what .grove-shell IS (base grid); [data-nav='side'] is
+    // the variant. So the consistency check is: side has rules, and the base
+    // block exists for top to fall through to.
+    expect(dataNavRules.has('side')).toBe(true);
+    expect(css).toMatch(/^\.grove-shell\s*\{/m);
+  });
+
+  it('resolveNavMode: declared top selects top; anything else falls back to side', () => {
+    expect(resolveNavMode({ nav: 'top' })).toBe('top');
+    expect(resolveNavMode({ nav: 'side' })).toBe('side');
+    expect(resolveNavMode(undefined)).toBe('side');
+    expect(resolveNavMode({ nav: 'diagonal' })).toBe('side');
+  });
+});
+
+describe('deleting every _layout.mdx still yields the full default shell (value 3)', () => {
+  it('DefaultLayout renders nav, sidebar, footer AND frames a page at Outlet', () => {
+    // Asserted rather than assumed: the whole starter catalogue rests on the
+    // promise that starters are a convenience — remove them all and a bare folder
+    // of .mdx is still a whole site.
+    const SHELL = { navMode: 'side', vw: 'desktop', navItems: [] } as unknown as GroveShell;
+    const NAV = {
+      outerHref: 'https://example.immediately.run/app/x',
+      navigationState: { sandboxPath: '/app/x' },
+    };
+    const html = renderToStaticMarkup(
+      <TinkerableContext.Provider value={NAV as never}>
+        <GroveShellContext.Provider value={SHELL}>
+          <OutletContext.Provider value={<p>THE-PAGE</p>}>
+            <DefaultLayout />
+          </OutletContext.Provider>
+        </GroveShellContext.Provider>
+      </TinkerableContext.Provider>,
+    );
+    expect(html).toContain('grove-nav');
+    expect(html).toContain('grove-sidebar');
+    expect(html).toContain('grove-footer');
+    expect(html).toContain('THE-PAGE');
+  });
+});

package/src/lib/queries.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from 'vitest';
-import { familyTreeQuery, navQuery, searchQuery, sidebarQuery } from './queries';
+import {
+  familyTreeQuery,
+  matchesQuery,
+  navQuery,
+  searchQuery,
+  sidebarQuery,
+  toSearchEntries,
+} from './queries';
 
 // The metadata queries select records (R3-276a). These tests pin the selections
 // themselves; the components are thin wiring around them. The store shape is the
@@ -26,11 +33,36 @@ describe('navQuery', () => {
     expect(navQuery({ '/app/content/a.mdx': { title: 'A.', tags: ['ui/nav'] } })[0].label).toBe('A');
   });
 
+  it('a label is the PLAIN form — frontmatter markers dropped, content kept (R3-531)', () => {
+    const rows = navQuery({ '/app/content/a.mdx': { title: 'Run `x` now.', tags: ['ui/nav'] } });
+    expect(rows[0]!.label).toBe('Run x now');
+    // An explicit `nav` is author intent and passes through the plain form too —
+    // a stray marker there gets the same treatment one level down.
+    expect(navQuery({ '/app/content/b.mdx': { title: 'T', nav: 'The **big** door', tags: ['ui/nav'] } })[0].label).toBe('The big door');
+  });
+
   it('never tab-encodes (the R3-276a regression: fake paths are gone)', () => {
     for (const r of navQuery(fm)) expect(JSON.stringify(r)).not.toContain('\t');
   });
 });
 
+describe('the ⌘K index and matcher (R3-531)', () => {
+  it('toSearchEntries keeps the RAW title for rendering beside the plain form for matching', () => {
+    const [e] = toSearchEntries([{ path: '/app/content/a.mdx', title: 'A `cache.yml` entry.', desc: 'About **keys**.' }]);
+    expect(e.title).toBe('A `cache.yml` entry.');
+    expect(e.plain).toBe('A cache.yml entry');
+    expect(e.desc).toBe('About keys.');
+  });
+
+  it('matchesQuery reads the plain forms — a query typed over what the reader sees hits', () => {
+    const [e] = toSearchEntries([{ path: '/app/content/a.mdx', title: 'A `cache.yml` entry.', desc: '' }]);
+    expect(matchesQuery(e, 'cache.yml')).toBe(true);
+    expect(matchesQuery(e, '`cache`')).toBe(false); // the raw markers are not searchable text
+    expect(matchesQuery(e, 'entry')).toBe(true);
+    expect(matchesQuery(e, 'zzz')).toBe(false);
+  });
+});
+
 describe('searchQuery', () => {
   it('indexes every content entry with title/desc and non-ui tags', () => {
     const rows = searchQuery(fm);

package/src/lib/queries.ts

@@ -11,6 +11,7 @@
 // Every record field is derived data; `path`/`meta` are applied by the hook.
 
 import { isContentEntry } from './content';
+import { plainProse } from '@immediately-run/mdx-plugins';
 
 /** A nav item derived from `ui/nav` frontmatter. */
 export type NavRecord = {
@@ -24,7 +25,38 @@ export function navQuery(fm: Record<string, any>): NavRecord[] {
   return Object.keys(fm)
     .filter((p) => isContentEntry(p) && Array.isArray(fm[p]?.tags) && fm[p].tags.includes('ui/nav'))
     .sort((a, b) => (fm[a].order ?? 999) - (fm[b].order ?? 999))
-    .map((p) => ({ path: p, label: fm[p]?.nav || (fm[p]?.title || '').replace(/\.$/, '') }));
+    .map((p) => ({ path: p, label: plainLabel(fm[p]?.nav || fm[p]?.title || '') }));
+}
+
+/** A field bound for an attribute, a label, a prompt or an index — the plain
+ *  form (R3-531): markers dropped, content kept, then the period trimmed. */
+export function plainLabel(s: string): string {
+  return plainProse(s).replace(/\.$/, '');
+}
+
+/** One searchable entry: the RAW title (the palette renders it as inline prose)
+ *  beside the plain form the matcher reads. */
+export type SearchEntry = {
+  key: string;
+  title: string;
+  plain: string;
+  desc: string;
+};
+
+/** The ⌘K index over search records — pure, so the plain/raw split is testable. */
+export function toSearchEntries(rows: { path: string; title: string; desc: string }[]): SearchEntry[] {
+  return rows.map(({ path, title, desc }) => ({
+    key: path,
+    title: title || path,
+    plain: plainLabel(title || path),
+    desc: plainProse(desc || ''),
+  }));
+}
+
+/** Match an entry against a lowercased query on its PLAIN forms — matching the
+ *  raw markdown would miss queries typed over what the reader actually sees. */
+export function matchesQuery(e: SearchEntry, ql: string): boolean {
+  return e.plain.toLowerCase().includes(ql) || e.desc.toLowerCase().includes(ql) || e.key.toLowerCase().includes(ql);
 }
 
 /** One search index row. `tags` excludes the `ui/*` furniture namespace. */