@immediately-run/grove 0.1.1 → 0.1.3

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

@@ -33,7 +33,20 @@ export interface GroveShell {
   // Environment
   vw: 'mobile' | 'desktop';
   navMode: 'top' | 'side';
+  /** Whether to render an edit affordance — the corpus MOUNT's answer, re-read live
+   *  (R3-266), never a property of how this instance was packaged. */
   writable: boolean;
+  /** Open a content entry in the platform editor. Which verb that takes differs by
+   *  packaging (`lib/editTarget`); the chrome never has to know which. */
+  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;
   siteTitle: string;
   /** Interpreter mode (TRUST_MODES §5): render this entry's body through the
    *  non-executable safe renderer (R3-213) instead of the compiled/executable `<Include>`
@@ -55,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);
+    }
+  });
+});

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();
+  });
+});