@immediately-run/grove 0.1.1 → 0.1.3

package/src/components/Search.tsx

@@ -3,7 +3,9 @@ import { Link, useMetadataQuery } from '@immediately-run/sdk';
 import type { Metadata } from '@immediately-run/sdk';
 import { keyToHref } from '../lib/content';
 import { crumb } from '../lib/wiki';
-import { searchQuery } from '../lib/queries';
+import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
+import InlineProse from './InlineProse';
+import { matchesQuery, searchQuery, toSearchEntries } from '../lib/queries';
 import type { SearchRecord } from '../lib/queries';
 import Icon from './Icon';
 
@@ -13,13 +15,19 @@ interface Hit {
   ns: string;
 }
 
+let searchListSeq = 0;
+
 // `.grove-search` — the ⌘K command palette: client-side fuzzy filter over the
-// in-memory index, grouped into entries + tags, keyboard-navigable.
+// in-memory index, grouped into entries + tags, keyboard-navigable. The input
+// carries combobox semantics (aria-activedescendant tracks the highlight the
+// filter maintains) and the box the dialog contract via the shared overlay
+// hook (focus in, trap, Escape, focus return — R3-608).
 export default function Search({ onClose }: { onClose: () => void }) {
   const [query, setQuery] = useState('');
   const [sel, setSel] = useState(0);
-  const boxRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
+  const dialogRef = useOverlayFocusDismiss(true, onClose);
+  const listId = useMemo(() => `grove-search-list-${++searchListSeq}`, []);
 
   // Records, not tab-encoded paths (R3-276a): `tags` is the array itself, so the
   // join/split round-trip is gone.
@@ -28,12 +36,10 @@ export default function Search({ onClose }: { onClose: () => void }) {
 
   const rowsKey = rows.map((r) => r.path).join('|');
   const { entries, tags } = useMemo(() => {
-    const es = rows.map(({ path, title, desc, tags: entryTags }) => ({
-      key: path,
-      title: (title || path).replace(/\.$/, ''),
-      desc: desc || '',
-      tags: entryTags.join(','),
-    }));
+    const es = rows.map(({ path, title, desc, tags: entryTags }) => {
+      const entry = toSearchEntries([{ path, title, desc }])[0]!;
+      return { ...entry, tags: entryTags.join(',') };
+    });
     const tagSet = new Set<string>();
     es.forEach((e) => e.tags.split(',').filter(Boolean).forEach((t) => tagSet.add(t)));
     return { entries: es, tags: Array.from(tagSet).sort() };
@@ -43,7 +49,7 @@ export default function Search({ onClose }: { onClose: () => void }) {
   const ql = query.trim().toLowerCase();
   const matchedEntries: Hit[] = (ql
     ? entries.filter(
-        (e) => e.title.toLowerCase().includes(ql) || e.desc.toLowerCase().includes(ql) || e.key.toLowerCase().includes(ql)
+        (e) => matchesQuery(e, ql)
       )
     : entries.slice(0, 6)
   ).map((e) => ({ key: e.key, title: e.title, ns: crumb(e.key) }));
@@ -55,7 +61,8 @@ export default function Search({ onClose }: { onClose: () => void }) {
   }, []);
 
   const onKey = (e: React.KeyboardEvent) => {
-    if (e.key === 'Escape') return onClose();
+    // Escape is owned by the overlay hook (document capture); only the list
+    // navigation lives here.
     if (e.key === 'ArrowDown') {
       e.preventDefault();
       setSel((s) => Math.min(s + 1, Math.max(0, total - 1)));
@@ -64,17 +71,33 @@ export default function Search({ onClose }: { onClose: () => void }) {
       setSel((s) => Math.max(0, s - 1));
     } else if (e.key === 'Enter') {
       e.preventDefault();
-      (boxRef.current?.querySelector('.grove-search__row[data-sel="1"]') as HTMLElement | null)?.click();
+      (dialogRef.current?.querySelector('.grove-search__row[data-sel="1"]') as HTMLElement | null)?.click();
     }
   };
 
+  const activeId = total > 0 ? `${listId}-opt-${sel}` : undefined;
+
   return (
     <div className="grove-search" onClick={onClose}>
-      <div className="grove-search__box" ref={boxRef} onClick={(e) => e.stopPropagation()}>
+      <div
+        className="grove-search__box"
+        ref={dialogRef}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search entries and tags"
+        onClick={(e) => e.stopPropagation()}
+      >
         <div className="grove-search__in">
           <Icon name="search" />
           <input
             ref={inputRef}
+            role="combobox"
+            aria-expanded="true"
+            aria-controls={listId}
+            aria-activedescendant={activeId}
+            aria-autocomplete="list"
+            aria-label="Search entries and tags"
             value={query}
             placeholder="Search entries and tags…"
             onChange={(e) => {
@@ -85,7 +108,7 @@ export default function Search({ onClose }: { onClose: () => void }) {
           />
           <kbd>esc</kbd>
         </div>
-        <div className="grove-search__res">
+        <div className="grove-search__res" role="listbox" id={listId} aria-label="Results">
           {total === 0 ? (
             <div className="grove-search__empty">
               No entry matches <code>{query}</code>.
@@ -99,24 +122,36 @@ export default function Search({ onClose }: { onClose: () => void }) {
                   href={keyToHref(h.key)}
                   className="grove-search__row"
                   data-sel={sel === i ? '1' : '0'}
+                  id={`${listId}-opt-${i}`}
+                  role="option"
+                  aria-selected={sel === i}
                   onClick={onClose}
                 >
                   <Icon name="file" />
-                  <span className="t">{h.title}</span>
+                  <span className="t">
+                    <InlineProse text={h.title} trimPeriod />
+                  </span>
                   <span className="c">/{h.ns}</span>
                 </Link>
               ))}
               {matchedTags.length ? <div className="grove-search__grp">Tags</div> : null}
               {matchedTags.map((t, i) => (
-                <div
+                <button
                   key={t}
+                  type="button"
                   className="grove-search__row"
                   data-sel={sel === matchedEntries.length + i ? '1' : '0'}
-                  onClick={onClose}
+                  id={`${listId}-opt-${matchedEntries.length + i}`}
+                  role="option"
+                  aria-selected={sel === matchedEntries.length + i}
+                  onClick={() => {
+                    setQuery(t);
+                    setSel(0);
+                  }}
                 >
                   <Icon name="list" />
                   <span className="t">#{t}</span>
-                </div>
+                </button>
               ))}
             </>
           )}

package/src/components/Sidebar.test.tsx

@@ -0,0 +1,135 @@
+// @vitest-environment jsdom
+// Sidebar tree navigation (R3-608, APG Tree View): exactly ONE tabbable row
+// over a real filesMetadata fixture (the producers `lib/directory.test.ts`
+// exercises build this same map), Down walks the rendered rows, and Right
+// expands a collapsed folder through the SAME handler #63's toggle button
+// uses.
+import { describe, expect, it } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+
+const { default: Sidebar } = await import('./Sidebar');
+
+// A real corpus shape: home + a wiki folder holding a leaf and a nested
+// (initially collapsed) guide folder.
+const FILES = {
+  '/app/content/home.mdx': { title: 'Home.' },
+  '/app/content/wiki/security.mdx': { title: 'Security.' },
+  '/app/content/wiki/guide/api.mdx': { title: 'API guide.' },
+  '/app/content/wiki/guide/deploy.mdx': { title: 'Deploying.' },
+};
+
+const NAV = {
+  outerHref: 'https://example.immediately.run/app/x',
+  navigationState: { sandboxPath: '/app/x', provider: 'github', namespace: 'immediately-run', repository: 'docs', ref: 'main', hash: '', search: '' },
+  routingSpec: {} as never,
+  filesMetadata: FILES,
+};
+
+async function mountSidebar(): Promise<{ root: Root; container: HTMLElement }> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(
+      <TinkerableContext.Provider value={NAV as never}>
+        <Sidebar />
+      </TinkerableContext.Provider>,
+    );
+  });
+  return { root, container };
+}
+
+const rows = (container: HTMLElement): HTMLElement[] =>
+  [...container.querySelectorAll('[data-tree-row]')] as HTMLElement[];
+
+describe('Sidebar tree navigation (R3-608)', () => {
+  it('exposes exactly ONE tabbable row — the roving stop', async () => {
+    const { container } = await mountSidebar();
+    const stops = container.querySelectorAll('.gs-tree [tabindex="0"]');
+    expect(stops.length).toBe(1);
+  });
+
+  it('Down moves focus through the rendered rows in order', async () => {
+    const { container } = await mountSidebar();
+    const list = rows(container);
+    expect(list.length).toBeGreaterThanOrEqual(3); // home, wiki folder, security
+    list[0].focus();
+    await act(async () => {
+      list[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true, cancelable: true }));
+    });
+    expect(document.activeElement).toBe(list[1]);
+    await act(async () => {
+      list[1].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true, cancelable: true }));
+    });
+    expect(document.activeElement).toBe(list[2]);
+    // Home returns to the first row.
+    await act(async () => {
+      list[2].dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true, cancelable: true }));
+    });
+    expect(document.activeElement).toBe(list[0]);
+  });
+
+  it('Right expands a collapsed folder through the #63 toggle handler', async () => {
+    const { container } = await mountSidebar();
+    // Rows: home, [wiki folder], security, [guide folder — depth 1, collapsed].
+    const guide = rows(container).find((r) => r.getAttribute('aria-expanded') === 'false');
+    expect(guide).toBeTruthy();
+    const before = rows(container).length;
+    guide!.focus();
+    await act(async () => {
+      guide!.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true, cancelable: true }));
+    });
+    // The folder opened: its two leaf rows joined the rendered set, and the
+    // same row now announces expanded.
+    expect(rows(container).length).toBe(before + 2);
+    expect(guide!.getAttribute('aria-expanded')).toBe('true');
+    // Left collapses it again.
+    await act(async () => {
+      guide!.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true, cancelable: true }));
+    });
+    expect(rows(container).length).toBe(before);
+    expect(guide!.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('the rows carry treeitem semantics under a tree', async () => {
+    const { container } = await mountSidebar();
+    const tree = container.querySelector('[role="tree"]');
+    expect(tree).toBeTruthy();
+    expect(container.querySelectorAll('[role="treeitem"]').length).toBe(rows(container).length);
+  });
+
+  it('collapsing the branch that holds the current entry never strands the tab stop', async () => {
+    // Current entry = the api leaf deep in wiki/guide: its branch renders open.
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(
+        <TinkerableContext.Provider value={{ ...NAV, navigationState: { ...NAV.navigationState, sandboxPath: '/app/content/wiki/guide/api.mdx' } } as never}>
+          <Sidebar />
+        </TinkerableContext.Provider>,
+      );
+    });
+    // The current row IS the roving stop.
+    expect(container.querySelectorAll('.gs-tree [tabindex="0"]').length).toBe(1);
+    expect((container.querySelector('.gs-tree [tabindex="0"]') as HTMLElement).getAttribute('data-cur')).toBe('1');
+    // Collapse the guide folder (it contains the current entry): its button
+    // becomes the stop — the nearest rendered ancestor — and the tree keeps
+    // exactly one tabbable row.
+    const guide = rows(container).find((r) => r.getAttribute('aria-expanded') === 'true' && r.textContent?.includes('guide'));
+    expect(guide).toBeTruthy();
+    guide!.focus();
+    await act(async () => {
+      guide!.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true, cancelable: true }));
+    });
+    expect(guide!.getAttribute('aria-expanded')).toBe('false');
+    const stops = container.querySelectorAll('.gs-tree [tabindex="0"]');
+    expect(stops.length).toBe(1);
+    expect(stops[0]).toBe(guide);
+    await act(async () => {
+      root.unmount();
+    });
+  });
+});

package/src/components/Sidebar.tsx

@@ -5,6 +5,8 @@ import type { Metadata } from '@immediately-run/sdk';
 import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
 import { contentDir, keyToHref, sandboxPathToKey } from '../lib/content';
 import { sidebarQuery } from '../lib/queries';
+import { plainLabel } from '../lib/queries';
+import InlineProse from './InlineProse';
 import type { SidebarRecord } from '../lib/queries';
 import Icon from './Icon';
 
@@ -34,9 +36,43 @@ function hasDescendant(node: TreeNode, key: string): boolean {
   return Object.values(node.children).some((c) => c.key === key || hasDescendant(c, key));
 }
 
+function treeHoldsKey(node: TreeNode, key: string): boolean {
+  return node.key === key || hasDescendant(node, key);
+}
+
+/** A row's stable id: a leaf is its entry key; a folder is its names-path
+ *  (the `#dir:` prefix cannot collide with an entry key). `dirPath` is the
+ *  accumulated folder names from the tree root, trailing slash included. */
+function folderRowId(dirPath: string, name: string): string {
+  return `#dir:${dirPath}${name}`;
+}
+
+/** The FIRST rendered row under a node (children in sorted order): the top
+ *  child itself — a folder's button, or a leaf's link. */
+function firstRowIdOf(node: TreeNode, dirPath: string): string | null {
+  const childKeys = Object.keys(node.children).sort();
+  if (!childKeys.length) return node.key ?? null;
+  const first = node.children[childKeys[0]];
+  return first.key ?? folderRowId(dirPath, first.name);
+}
+
 // A folder (has children) or a leaf entry. Folders are collapsible; the branch
-// holding the current entry starts open.
-function Branch({ node, currentKey, depth }: { node: TreeNode; currentKey: string; depth: number }) {
+// holding the current entry starts open. Rows are `treeitem`s under a roving
+// tab stop (R3-608, APG Tree View): exactly one row is tabbable, arrows walk
+// the tree — the #63 folder toggle keeps its handler and its aria-expanded.
+function Branch({
+  node,
+  currentKey,
+  depth,
+  dirPath,
+  stopRowId,
+}: {
+  node: TreeNode;
+  currentKey: string;
+  depth: number;
+  dirPath: string;
+  stopRowId: string | null;
+}) {
   const childKeys = Object.keys(node.children).sort();
   const isFolder = childKeys.length > 0;
   const containsCurrent = !!currentKey && (node.key === currentKey || hasDescendant(node, currentKey));
@@ -44,24 +80,57 @@ function Branch({ node, currentKey, depth }: { node: TreeNode; currentKey: strin
 
   if (!isFolder) {
     return (
-      <Link href={keyToHref(node.key!)} className="gs-tree__row" data-cur={node.key === currentKey ? '1' : '0'}>
+      <Link
+        href={keyToHref(node.key!)}
+        className="gs-tree__row"
+        data-cur={node.key === currentKey ? '1' : '0'}
+        data-tree-row="1"
+        role="treeitem"
+        aria-level={depth + 1}
+        aria-current={node.key === currentKey ? 'page' : undefined}
+        tabIndex={node.key === stopRowId ? 0 : -1}
+      >
         <Icon name="file" />
-        {(node.title || node.name).replace(/\.$/, '')}
+        <InlineProse text={node.title || node.name} trimPeriod />
       </Link>
     );
   }
 
+  const rowId = folderRowId(dirPath, node.name);
   return (
     <div>
-      <div className="gs-tree__row gs-folder" data-open={open ? '1' : '0'} onClick={() => setOpen((o) => !o)}>
+      <button
+        type="button"
+        className="gs-tree__row gs-folder"
+        data-open={open ? '1' : '0'}
+        data-tree-row="1"
+        role="treeitem"
+        aria-level={depth + 1}
+        aria-expanded={open}
+        /* Roving stop, with the collapsed-ancestor fallback (R3-608 review):
+         * the folder holds the stop when it IS the stop's row, or when it is
+         * collapsed yet CONTAINS the current entry — collapsing the branch the
+         * reader is on must never unmount the tree's only tab stop. Exactly
+         * one row qualifies either way: the collapsed folder is the nearest
+         * rendered ancestor of the (unrendered) current row. */
+        tabIndex={rowId === stopRowId || (!open && containsCurrent) ? 0 : -1}
+        onClick={() => setOpen((o) => !o)}
+      >
         <Icon name="chevron-down" className="chev" />
         {node.name}
         <span className="ct">{childKeys.length}</span>
-      </div>
+      </button>
       {open ? (
-        <div className="gs-tree__children">
+        <div className="gs-tree__children" role="group">
           {childKeys.map((k) => (
-            <Branch key={k} node={node.children[k]} currentKey={currentKey} depth={depth + 1} />
+            <Branch
+              key={k}
+              node={node.children[k]}
+              currentKey={currentKey}
+              depth={depth + 1}
+              dirPath={`${dirPath}${node.name}/`}
+              stopRowId={stopRowId}
+            />
           ))}
         </div>
       ) : null}
@@ -85,7 +154,7 @@ export default function Sidebar() {
     const secs: { key: string; label: string }[] = [];
     rows.forEach(({ path, title, tags, nav }) => {
       insert(root, path, title);
-      if (tags.includes('ui/sidebar')) secs.push({ key: path, label: nav || title || path });
+      if (tags.includes('ui/sidebar')) secs.push({ key: path, label: plainLabel(nav || title || path) });
     });
     return { tree: root, sections: secs };
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -93,19 +162,52 @@ export default function Sidebar() {
 
   const topKeys = Object.keys(tree.children).sort();
 
+  // The roving tab stop: the current entry's own row (its branch opens by
+  // construction), else the tree's first rendered row.
+  const stopRowId = useMemo(() => {
+    if (currentKey && treeHoldsKey(tree, currentKey)) return currentKey;
+    return firstRowIdOf(tree, '');
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rowsKey, currentKey]);
+
+  // The tree's keyboard controller (R3-608): Up/Down/Home/End walk the
+  // RENDERED rows in DOM order; Right/Left expand/collapse by delegating to
+  // the folder row's own handler (the #63 button's onClick) when the row's
+  // aria-expanded says the arrow applies.
+  const onTreeKeyDown = (e: React.KeyboardEvent) => {
+    const rowsInOrder = [...(e.currentTarget as HTMLElement).querySelectorAll<HTMLElement>('[data-tree-row]')];
+    if (!rowsInOrder.length) return;
+    const activeIdx = rowsInOrder.indexOf(document.activeElement as HTMLElement);
+    const move = (idx: number) => {
+      e.preventDefault();
+      rowsInOrder[Math.max(0, Math.min(rowsInOrder.length - 1, idx))]?.focus();
+    };
+    if (e.key === 'ArrowDown') move(activeIdx + 1);
+    else if (e.key === 'ArrowUp') move(activeIdx - 1);
+    else if (e.key === 'Home') move(0);
+    else if (e.key === 'End') move(rowsInOrder.length - 1);
+    else if (e.key === 'ArrowRight' || e.key === 'ArrowLeft') {
+      const row = rowsInOrder[activeIdx];
+      const wantOpen = e.key === 'ArrowRight';
+      if (!row || row.getAttribute('aria-expanded') !== (wantOpen ? 'false' : 'true')) return;
+      e.preventDefault();
+      row.click(); // the #63 folder toggle's own handler
+    }
+  };
+
   return (
     <aside className="grove-sidebar">
       <div className="gs-block">
         <div className="gs-block__h">Browse</div>
-        <div className="gs-tree">
+        <div className="gs-tree" role="tree" aria-label="Entries" onKeyDown={onTreeKeyDown}>
           {topKeys.map((k) => (
-            <Branch key={k} node={tree.children[k]} currentKey={currentKey} depth={0} />
+            <Branch key={k} node={tree.children[k]} currentKey={currentKey} depth={0} dirPath="" stopRowId={stopRowId} />
           ))}
         </div>
       </div>
       {sections.map((s) => (
         <div className="gs-block" key={s.key}>
-          <div className="gs-block__h">{s.label.replace(/\.$/, '')}</div>
+          <div className="gs-block__h">{s.label}</div>
           <div className="gs-section__body">
             <Link href={keyToHref(s.key)} className="grove-wikilink" data-state="ok">
               Open

package/src/components/TableOfContents.test.tsx

@@ -1,7 +1,8 @@
 // @vitest-environment jsdom
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { act } from 'react';
-import { createRoot } from 'react-dom/client';
+import type { ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
 import TableOfContents from './TableOfContents';
 
 // jsdom performs no layout, so every geometry property this component reads is 0. The
@@ -54,6 +55,25 @@ function layout(nav: HTMLElement, opts: { viewHeight?: number; scrollHeight?: nu
 
 const IDS = Array.from({ length: 40 }, (_, i) => `sec-${i + 1}`);
 
+// Every root this file mounts, so `afterEach` can tear them down. Clearing `document.body`
+// is not unmounting: `useHeadings` arms 120/300/600ms re-scan timers and only clears them
+// on unmount, so an abandoned root leaves a timer that fires after the file's jsdom
+// environment is gone — an unhandled `document is not defined` attributed to whichever
+// file happened to be running.
+const roots: Root[] = [];
+
+/** Mount `node` into a fresh host and remember the root for teardown. */
+async function renderInto(node: ReactNode): Promise<HTMLElement> {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  roots.push(root);
+  await act(async () => {
+    root.render(node);
+  });
+  return host;
+}
+
 let scrollTo: ReturnType<typeof vi.fn>;
 let scrollIntoView: ReturnType<typeof vi.fn>;
 
@@ -66,17 +86,16 @@ beforeEach(() => {
   Element.prototype.scrollIntoView = scrollIntoView as never;
 });
 afterEach(() => {
+  act(() => {
+    roots.splice(0).forEach((r) => r.unmount());
+  });
   document.body.innerHTML = '';
   vi.restoreAllMocks();
 });
 
 async function mount(): Promise<HTMLElement> {
   plantProse(IDS);
-  const host = document.createElement('div');
-  document.body.appendChild(host);
-  await act(async () => {
-    createRoot(host).render(<TableOfContents entryKey="/app/content/x.mdx" />);
-  });
+  const host = await renderInto(<TableOfContents entryKey="/app/content/x.mdx" />);
   return layout(host.querySelector('nav')!);
 }
 
@@ -112,11 +131,7 @@ describe('<TableOfContents/>', () => {
 
   it('does nothing when the whole list fits', async () => {
     plantProse(IDS);
-    const host = document.createElement('div');
-    document.body.appendChild(host);
-    await act(async () => {
-      createRoot(host).render(<TableOfContents entryKey="/app/content/x.mdx" />);
-    });
+    const host = await renderInto(<TableOfContents entryKey="/app/content/x.mdx" />);
     layout(host.querySelector('nav')!, { viewHeight: 1000, scrollHeight: 1000 });
     await spyTo('sec-30');
     expect(scrollTo).not.toHaveBeenCalled();
@@ -141,11 +156,7 @@ describe('<TableOfContents/>', () => {
   });
 
   it('renders nothing for an entry with no sub-headings', async () => {
-    const host = document.createElement('div');
-    document.body.appendChild(host);
-    await act(async () => {
-      createRoot(host).render(<TableOfContents entryKey="/app/content/empty.mdx" />);
-    });
+    const host = await renderInto(<TableOfContents entryKey="/app/content/empty.mdx" />);
     expect(host.querySelector('nav')).toBeNull();
   });
 

package/src/components/ThemeAssets.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+// R3-315's component-level exits: the engine emission renders the minted
+// @font-face set inside the engine cascade layer, revokes on unmount (a switch
+// leaks nothing), degrades to nothing when the bytes are unreadable, and — the
+// offline exit — no shipped stylesheet carries a third-party @import.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { ReactNode } from 'react';
+
+const readFile = vi.fn();
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: ThemeAssets } = await import('./ThemeAssets');
+const { DEFAULT_THEME_ASSETS } = await import('../data/themeFonts');
+
+const revokeSpy = vi.spyOn(URL, 'revokeObjectURL');
+
+async function renderSwap(nodes: ReactNode[]): Promise<HTMLElement> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  for (const node of nodes) {
+    await act(async () => {
+      root.render(node);
+    });
+  }
+  return container;
+}
+
+beforeEach(() => {
+  readFile.mockReset();
+  revokeSpy.mockClear();
+});
+
+describe('the engine emission', () => {
+  it('renders the minted faces inside the ENGINE cascade layer, blob: srcs only', async () => {
+    readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+    const el = await renderSwap([<ThemeAssets declarations={DEFAULT_THEME_ASSETS} />]);
+    const style = el.querySelector('style[data-grove-theme-assets]');
+    expect(style).toBeTruthy();
+    expect(style?.textContent).toContain('@layer grove.engine{');
+    expect(style?.textContent).toContain('"Gabarito"');
+    expect(style?.textContent).toContain('"Public Sans"');
+    expect(style?.textContent).toContain('"Space Mono"');
+    expect((style?.textContent?.match(/src: url\("blob:/g) ?? []).length).toBe(12);
+    // The read set is the in-repo face set — no network fetch is involved at all.
+    // The read goes through the SDK root-mount (leading slash stripped — the
+    // root-anchored relPath, the same key space MountImage reads).
+    expect(readFile).toHaveBeenCalledWith('/app/assets/fonts/gabarito-latin-400-normal.woff2');
+  });
+
+  it('unmount revokes every minted URL — switching sets leaks nothing', async () => {
+    readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    let root: Root | null = createRoot(container);
+    await act(async () => {
+      root?.render(<ThemeAssets declarations={DEFAULT_THEME_ASSETS} />);
+    });
+    expect(revokeSpy).not.toHaveBeenCalled(); // live set holds its URLs
+    await act(async () => {
+      root?.render(<ThemeAssets declarations={{ fonts: [{ family: 'Other', src: './o.woff2' }] }} />);
+    });
+    // The DEFAULT set (12 URLs) was the OUTGOING set — revoked on the swap.
+    expect(revokeSpy).toHaveBeenCalledTimes(12);
+    await act(async () => {}); // let the incoming set's mint land (it is now live)
+    await act(async () => {
+      root?.unmount();
+    });
+    root = null;
+    expect(revokeSpy).toHaveBeenCalledTimes(13); // + the incoming set's 1
+  });
+
+  it('unreadable bytes degrade to no style element at all (the fallback stack answers)', async () => {
+    readFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    const el = await renderSwap([<ThemeAssets declarations={DEFAULT_THEME_ASSETS} />]);
+    expect(el.querySelector('style[data-grove-theme-assets]')).toBeNull();
+  });
+});
+
+describe('the offline exit — no third-party @import survives in any shipped stylesheet', () => {
+  it('grep over the shipped css: no @import names a network location', async () => {
+    const { readdir, readFile: rf } = await import('node:fs/promises');
+    const walk = async (dir: string): Promise<string[]> => {
+      const out: string[] = [];
+      for (const e of await readdir(dir, { withFileTypes: true })) {
+        const p = `${dir}/${e.name}`;
+        if (e.isDirectory()) out.push(...(await walk(p)));
+        else if (p.endsWith('.css')) out.push(p);
+      }
+      return out;
+    };
+    const files = await walk('src');
+    expect(files.length).toBeGreaterThan(0);
+    for (const f of files) {
+      const css = await rf(f, 'utf8');
+      for (const line of css.split('\n')) {
+        if (line.includes('@import')) {
+          // Only same-package/relative imports could ever be acceptable; a URL is
+          // the withdrawn exception.
+          expect(line).not.toMatch(/https?:\/\//);
+        }
+      }
+    }
+  });
+});