@immediately-run/grove 0.1.2 → 0.1.3

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. */

package/src/lib/reachCard.test.ts

@@ -0,0 +1,94 @@
+// R-GA-1 / G-GA-1 / G-GA-6 / G-GA-10 — the reach card is a pure function of the
+// envelope; no pixel claims a capability the session lacks, causes are distinct and
+// concrete, and state flips recompute rows AND chips.
+import { describe, it, expect } from 'vitest';
+import { computeReachRows, reachChips, showEgressDisclosure } from './reachCard';
+import type { ChatProviderState } from '@immediately-run/sdk';
+
+const configured = (tools = true): ChatProviderState => ({
+  status: 'configured',
+  provider: { providerId: 'llm.chat.anthropic', hostVouched: true, features: { vision: false, tools, jsonMode: true, reasoning: false, maxContextTokens: 100000 } },
+});
+
+const row = (rows: ReturnType<typeof computeReachRows>, key: string) => rows.find((r) => r.key === key)!;
+
+describe('G-GA-10 — the Q&A row renders the provider three-state honestly', () => {
+  it('unknown renders NEUTRAL — no cause, no connect copy (the R3-300 rule)', () => {
+    const rows = computeReachRows({ providerState: { status: 'unknown' }, chatGranted: true, writable: true, sourceShared: true });
+    expect(row(rows, 'answer').state).toBe('neutral');
+    expect(row(rows, 'answer').cause).toBeUndefined();
+  });
+
+  it('not-configured names the KEY cause; ungranted names the CONSENT cause — never conflated', () => {
+    const noKey = computeReachRows({ providerState: { status: 'not-configured' }, chatGranted: true, writable: true, sourceShared: false });
+    expect(row(noKey, 'answer').state).toBe('blocked');
+    expect(row(noKey, 'answer').cause).toContain('add one in Settings');
+
+    const forbidden = computeReachRows({ providerState: configured(), chatGranted: false, writable: true, sourceShared: false });
+    expect(row(forbidden, 'answer').state).toBe('blocked');
+    expect(row(forbidden, 'answer').cause).toContain("wasn't granted chat");
+    expect(row(forbidden, 'answer').cause).not.toContain('Settings');
+  });
+
+  it('configured + granted is ✓ and carries the read-flavored chips', () => {
+    const ok = computeReachRows({ providerState: configured(), chatGranted: true, writable: false, sourceShared: false });
+    expect(row(ok, 'answer').state).toBe('ok');
+    expect(row(ok, 'answer').chips).toBeDefined();
+  });
+});
+
+describe('G-GA-1 — the read/draft/apply rows derive from writability, never copy', () => {
+  it('read-only blocks Draft with the reader cause and yields NO write chip', () => {
+    const rows = computeReachRows({ providerState: configured(), chatGranted: true, writable: false, sourceShared: false });
+    expect(row(rows, 'draft').state).toBe('blocked');
+    expect(row(rows, 'draft').cause).toContain('reader');
+    const chips = reachChips(rows);
+    expect(chips.some((c) => /add an entry|fix broken|reorganize|timeline|suggest an edit/i.test(c))).toBe(false);
+  });
+
+  it('writable turns Draft ✓ — and its chip is a DESCRIBE, not an apply', () => {
+    const rows = computeReachRows({ providerState: configured(), chatGranted: true, writable: true, sourceShared: false });
+    expect(row(rows, 'draft').state).toBe('ok');
+    expect((row(rows, 'draft').chips ?? []).join(' ')).toMatch(/suggest an edit/i);
+  });
+
+  it('Apply is NEVER ok from this panel (R-GA-3) — the cause says where changes go', () => {
+    for (const writable of [true, false]) {
+      const rows = computeReachRows({ providerState: configured(), chatGranted: true, writable, sourceShared: false });
+      expect(row(rows, 'apply').state).toBe('blocked');
+      expect(row(rows, 'apply').cause).toContain('editor / workbench');
+    }
+  });
+
+  it('the shared-source sentence rides the Apply cause only when trust says others can write', () => {
+    const shared = computeReachRows({ providerState: configured(), chatGranted: true, writable: true, sourceShared: true });
+    expect(row(shared, 'apply').cause).toContain('treated as if others can write');
+    const solo = computeReachRows({ providerState: configured(), chatGranted: true, writable: true, sourceShared: false });
+    expect(row(solo, 'apply').cause).not.toContain('others can write');
+  });
+});
+
+describe('G-GA-6 — envelope flips recompute rows and chips together', () => {
+  it('disconnecting the provider flips answer ✓→blocked and drops its chips', () => {
+    const before = computeReachRows({ providerState: configured(), chatGranted: true, writable: true, sourceShared: false });
+    const after = computeReachRows({ providerState: { status: 'not-configured' }, chatGranted: true, writable: true, sourceShared: false });
+    expect(row(before, 'answer').state).toBe('ok');
+    expect(row(after, 'answer').state).toBe('blocked');
+    expect(reachChips(after)).not.toContain('Summarize this entry');
+  });
+
+  it('revoking write flips draft ✓→blocked on the next computation', () => {
+    const before = computeReachRows({ providerState: configured(), chatGranted: true, writable: true, sourceShared: false });
+    const after = computeReachRows({ providerState: configured(), chatGranted: true, writable: false, sourceShared: false });
+    expect(row(before, 'draft').state).toBe('ok');
+    expect(row(after, 'draft').state).toBe('blocked');
+  });
+});
+
+describe('R-GA-6 — the egress disclosure is unconditional when a provider is bound', () => {
+  it('shows for configured, not for unknown or not-configured, whatever the trust mode', () => {
+    expect(showEgressDisclosure(configured())).toBe(true);
+    expect(showEgressDisclosure({ status: 'unknown' })).toBe(false);
+    expect(showEgressDisclosure({ status: 'not-configured' })).toBe(false);
+  });
+});

package/src/lib/reachCard.ts

@@ -0,0 +1,112 @@
+// The reach card (GROVE_AGENT_SPEC §6) — the agent's envelope, rendered as rows in
+// the two-word vocabulary with a cause for every ✗ (R-SP-3). R-GA-1: every row is
+// COMPUTED from the session's envelope (provider three-state, chat grant, mount
+// writability, source trust); no capability claim on any pixel of this surface is
+// hand-written copy. The four old banners collapse into these rows; chips render
+// only for rows that are ✓ — derived, not curated.
+
+import type { ChatProviderState } from '@immediately-run/sdk';
+
+/** One reach-card row. `state: 'neutral'` renders neither ✓ nor ✗ — used only for
+ *  the unknown provider state (rendering a cause there re-creates the false banner
+ *  R3-300 fixed: `unknown` means unanswered, not ungranted). */
+export interface ReachRow {
+  key: 'answer' | 'read' | 'draft' | 'apply';
+  label: string;
+  state: 'ok' | 'blocked' | 'neutral';
+  cause?: string;
+  /** Chips this row contributes when ✓ — the panel renders exactly these. */
+  chips?: string[];
+}
+
+export interface ReachInputs {
+  providerState: ChatProviderState;
+  /** Whether the grant-filtered catalog advertises `llm:chat` (the consented
+   *  capability — absent on an ungranted fork, a distinct cause from "no key"). */
+  chatGranted: boolean;
+  writable: boolean;
+  /** Fail-closed source trust (git ⇒ indeterminate ⇒ treated as shared). */
+  sourceShared: boolean;
+}
+
+/** The rows, computed. Order is the card's display order. */
+export function computeReachRows({ providerState, chatGranted, writable, sourceShared }: ReachInputs): ReachRow[] {
+  // Row 1 — Q&A. Three provider states × the grant, with the two NOT-causes never
+  // conflated (G-GA-10): "no key" is the user's to fix in Settings; "not granted"
+  // is this copy's consent state, and reading works either way.
+  let answer: ReachRow;
+  if (providerState.status === 'unknown') {
+    answer = { key: 'answer', label: 'Answer questions about this wiki', state: 'neutral' };
+  } else if (providerState.status === 'not-configured') {
+    answer = {
+      key: 'answer',
+      label: 'Answer questions about this wiki',
+      state: 'blocked',
+      cause: 'no model key connected — add one in Settings',
+    };
+  } else if (!chatGranted) {
+    answer = {
+      key: 'answer',
+      label: 'Answer questions about this wiki',
+      state: 'blocked',
+      cause: "this Grove wasn't granted chat — reading works as normal",
+    };
+  } else {
+    answer = {
+      key: 'answer',
+      label: 'Answer questions about this wiki',
+      state: 'ok',
+      chips: ['Summarize this entry', 'What entries are tagged security?'],
+    };
+  }
+
+  // Row 2 — the body source. Both packagings define one post-S2 (the fork's own
+  // bundled corpus; the dispatched wiki mount), so this row is ✓ unless degenerate.
+  // It is computed, not assumed: the day a packaging lacks a source, the card says so.
+  const read: ReachRow = {
+    key: 'read',
+    label: 'Read entries and structure',
+    state: 'ok',
+  };
+
+  // Row 3 — drafting. Writability is the mount's answer; the chip proposes an edit
+  // the agent DESCRIBES (S4's host-confirmed diffs are not built — v1 drafts in chat).
+  const draft: ReachRow = writable
+    ? {
+        key: 'draft',
+        label: 'Draft changes',
+        state: 'ok',
+        chips: [`Suggest an edit for "${'this entry'}"`],
+      }
+    : { key: 'draft', label: 'Draft changes', state: 'blocked', cause: 'you’re a reader here' };
+
+  // Row 4 — applying. NEVER from this panel (R-GA-3): the widget renders content and
+  // is exactly the broker core_concepts §8a Axis D forbids. The cause is where
+  // changes go, plus the shared-source sentence when trust says others can write.
+  const apply: ReachRow = {
+    key: 'apply',
+    label: 'Apply changes',
+    state: 'blocked',
+    cause:
+      'changes open in the editor / workbench, where you confirm them' +
+      (sourceShared ? ' — this repo is treated as if others can write (sole authorship can’t be verified yet), so agent actions go past you first' : ''),
+  };
+
+  return [answer, read, draft, apply];
+}
+
+/** The chips the panel shows: exactly the ✓ rows' chips, in card order (R-GA-1 —
+ *  derived from the envelope, never curated). */
+export function reachChips(rows: ReachRow[]): string[] {
+  return rows.flatMap((r) => (r.state === 'ok' ? r.chips ?? [] : []));
+}
+
+/** R-GA-6's unconditional egress line — shown whenever a provider is bound,
+ *  whatever the wiki's trust mode: Q&A composes read + provider egress, and the
+ *  confidentiality axis is grant-based, not sharedness-based. */
+export const EGRESS_DISCLOSURE =
+  'answers come from your connected model provider, which receives what the agent reads here';
+
+export function showEgressDisclosure(providerState: ChatProviderState): boolean {
+  return providerState.status === 'configured';
+}

package/src/lib/shell.ts

@@ -41,6 +41,9 @@ export interface GroveShell {
   openEditor: (entryKey: string) => void;
   /** True while an editor is being summoned, for a busy label. */
   editBusy: boolean;
+  /** True when the host REFUSED the last edit request — render it where the
+   *  affordance was offered (3.3.1, R3-608); a cancelled request never sets it. */
+  editRefused: boolean;
   /** What a save actually does, for the affordance's title — under dispatch it says that
    *  proposing a change back to the content repo is not wired yet (R3-266's residual). */
   editHint: string;
@@ -65,6 +68,10 @@ export interface GroveShell {
   directory: DirectoryListing;
 }
 
+/** The refusal sentence, ONE home (R6, R3-608): every surface that offers an edit
+ *  renders this where the affordance was offered. */
+export const EDIT_REFUSED_NOTICE = 'Could not open the editor — the host refused';
+
 export const GroveShellContext = createContext<GroveShell | null>(null);
 
 /** Read the shell context. Throws if used outside App's provider — which only

package/src/lib/starterSweep.test.tsx

@@ -0,0 +1,160 @@
+// The layout-starter gate (R3-309, bucket A) — every starter under
+// `content/_layouts/` rendered through the REAL published safe renderer with
+// Grove's own SAFE_MDX map, exactly what SafeLayout sends a `_layout.mdx` through
+// in interpreter mode. Proven by fault injection on all quiet failure modes.
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSafeMdast, renderMdast } from '@immediately-run/sdk/safeContent/index';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { SAFE_MDX } from '../mdxComponents';
+import { GroveShellContext, OutletContext, type GroveShell } from './shell';
+import {
+  starterViolations,
+  STARTER_MARKERS,
+  stripStarterFrontmatter,
+} from './starterSweep';
+
+const LAYOUTS = join(process.cwd(), 'content', '_layouts');
+
+/** A complete-enough shell for the chrome primitives to render statically (they
+ *  read state through useShell; a bare render throws in the provider check, which
+ *  is correct — the sweep must run them the way the wiki does, with state). */
+const SHELL: GroveShell = {
+  theme: 'default',
+  setTheme: () => {},
+  light: false,
+  setLight: () => {},
+  menuOpen: false,
+  setMenuOpen: () => {},
+  searchOpen: false,
+  setSearchOpen: () => {},
+  drawerOpen: false,
+  setDrawerOpen: () => {},
+  vw: 'desktop',
+  navMode: 'side',
+  writable: false,
+  openEditor: () => {},
+  editBusy: false,
+  editHint: '',
+  siteTitle: 'Grove',
+  safe: false,
+  navItems: [],
+  entryKey: '/app/content/index.mdx',
+  includePath: 'index.mdx',
+  layout: 'doc',
+  showRails: true,
+  mins: 0,
+  missing: false,
+  directory: { status: 'idle' },
+} as unknown as GroveShell;
+
+/** The real interpreter render, with the Outlet sentinel a starter's `<Outlet/>`
+ *  renders — a static render has no inner page, so the sentinel is how presence
+ *  is distinguished from a tag that quietly collapsed to nothing. The host
+ *  navigation provider stands in for the sandbox, exactly as it would supply it. */
+const NAV = {
+  outerHref: 'https://example.immediately.run/app/x',
+  navigationState: { sandboxPath: '/app/x' },
+};
+
+const renderBody = async (body: string): Promise<string> => {
+  const tree = await parseSafeMdast(body);
+  const el = renderMdast(tree, { components: SAFE_MDX as never });
+  return renderToStaticMarkup(
+    <TinkerableContext.Provider value={NAV as never}>
+      <GroveShellContext.Provider value={SHELL}>
+        <OutletContext.Provider value={<p>OUTLET-SENTINEL</p>}>{el as never}</OutletContext.Provider>
+      </GroveShellContext.Provider>
+    </TinkerableContext.Provider>,
+  );
+};
+
+const knownTags = new Set(Object.keys(SAFE_MDX) as string[]);
+
+describe('the layout-starter sweep (R3-309 bucket A)', () => {
+  const starters = readdirSync(LAYOUTS).filter((f) => f.endsWith('.mdx'));
+
+  it('found the starters — a sweep that examines nothing defends nothing (checked > 0)', () => {
+    expect(starters.length).toBe(3);
+    expect(new Set(starters.map((f) => f.replace(/\.mdx$/, '')))).toEqual(
+      new Set(['shell', 'section', 'hero']),
+    );
+  });
+
+  it.each(starters)('%s survives the real safe renderer', async (file) => {
+    const src = readFileSync(join(LAYOUTS, file), 'utf8');
+    const violations = await starterViolations(src, { render: renderBody, knownTags });
+    expect(violations).toEqual([]);
+    // And the Outlet sentinel came through: the starter actually frames a page.
+    expect(await renderBody(stripStarterFrontmatter(src))).toContain('OUTLET-SENTINEL');
+  });
+
+  it('the hero starter selects the top arrangement and omits the sidebar', async () => {
+    // Exit criterion: a shell starter selecting `top` renders without the sidebar.
+    // The hero IS that starter — `nav: top` in frontmatter, no `<GroveSidebar/>`
+    // in the body.
+    const src = readFileSync(join(LAYOUTS, 'hero.mdx'), 'utf8');
+    expect(src).toMatch(/^nav:\s*top$/m);
+    expect(stripStarterFrontmatter(src)).not.toContain('<GroveSidebar');
+    const markup = await renderBody(stripStarterFrontmatter(src));
+    expect(markup).not.toContain('grove-sidebar');
+  });
+
+  // ── fault injection: each quiet failure mode, planted and caught ────────────
+  const GOOD = readFileSync(join(LAYOUTS, 'shell.mdx'), 'utf8');
+
+  it('baseline passes, so the injections below mean the PLANT', async () => {
+    expect(await starterViolations(GOOD, { render: renderBody, knownTags })).toEqual([]);
+  });
+
+  it('a planted raw-HTML block is caught (it renders as literal angle brackets, never markup)', async () => {
+    // The shape safeRender.test.ts proved: a raw `<script>` survives as ESCAPED TEXT.
+    // Starters carry no raw HTML, so ANY '<' in the visible text is this failure —
+    // and the script must not have executed, either.
+    const planted = stripStarterFrontmatter(GOOD).replace(
+      '<GroveFooter />',
+      '<script>globalThis.__pwnedByStarter = 1</script>',
+    );
+    const v = await starterViolations(planted, { render: renderBody, knownTags });
+    expect(v.some((x) => /angle brackets/.test(x))).toBe(true);
+    expect((globalThis as Record<string, unknown>).__pwnedByStarter).toBeUndefined();
+  });
+
+  it('a planted import line is caught (it renders as visible prose)', async () => {
+    const planted = stripStarterFrontmatter(GOOD).replace(
+      '<GroveNav />',
+      'import GroveNav from "./components/GroveNav"\n\n<GroveNav />',
+    );
+    const v = await starterViolations(planted, { render: renderBody, knownTags });
+    expect(v.some((x) => /import\/export line/.test(x))).toBe(true);
+  });
+
+  it('a planted off-vocabulary wrapper is caught (it collapses to its children)', async () => {
+    const planted = stripStarterFrontmatter(GOOD).replace(
+      '<GroveFooter />',
+      '<NotARealWrapper className="x">\n\nTrapped text.\n\n</NotARealWrapper>',
+    );
+    const v = await starterViolations(planted, { render: renderBody, knownTags });
+    expect(v.some((x) => /not in the component map/.test(x))).toBe(true);
+  });
+
+  it('a planted JSX comment is caught — under the interpreter its braces are prose', async () => {
+    // The shipped sample layouts carry `{/* … */}` teaching comments, which the
+    // COMPILED path drops and the interpreter renders as literal text. Starters
+    // must not teach that: their teaching lives in frontmatter, which never renders.
+    const planted = stripStarterFrontmatter(GOOD).replace(
+      '<GroveNav />',
+      '{/* a teaching comment */}\n\n<GroveNav />',
+    );
+    const v = await starterViolations(planted, { render: renderBody, knownTags });
+    expect(v.some((x) => /braces render as visible text/.test(x))).toBe(true);
+  });
+
+  it('every marker the sweep keys on exists in the vocabulary it checks', () => {
+    for (const tag of Object.keys(STARTER_MARKERS)) {
+      expect(knownTags.has(tag)).toBe(true);
+    }
+  });
+});