@immediately-run/grove 0.1.2 → 0.1.4

package/src/GroveWiki.tsx

@@ -5,6 +5,7 @@ import fs from 'fs';
 import type { Metadata } from '@immediately-run/sdk';
 import {
   Include,
+  ScrollRestoration,
   useAllMetadata,
   useFileMetadata,
   useHostTheme,
@@ -12,7 +13,7 @@ import {
 } from '@immediately-run/sdk';
 import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
 import { LinkSpaceContext } from '@immediately-run/sdk/linkSpace';
-import { CorpusContext, toCorpusPath, fromCorpusPath } from '@immediately-run/sdk/corpus';
+import { BundleContext, toBundlePath, fromBundlePath } from '@immediately-run/sdk/bundle';
 import {
   contentDir,
   homeKey,
@@ -23,13 +24,14 @@ import {
   sandboxPathToKey,
 } from './lib/content';
 import { queryPaths, queryRecords, readingTime, stripFrontmatter } from './lib/wiki';
-import { navQuery } from './lib/queries';
+import { navQuery, plainLabel } from './lib/queries';
 import type { NavRecord } from './lib/queries';
-import { layoutChainForKey } from './lib/layout';
+import { layoutChainForKey, resolveNavMode, resolvePageLayout } from './lib/layout';
 import { folderIndexKey } from './lib/directory';
 import { resolvePalette, resolvePolarity, type Polarity } from './lib/themeSelection';
 import { preferredPolarity } from './data/themes';
 import { useDirectoryListing } from './hooks/useDirectoryListing';
+import { useScrollReset } from './hooks/useScrollReset';
 import { useEditAffordance } from './hooks/useEditAffordance';
 import { getContentRoot } from './lib/contentRoot';
 import type { RejectedComponent } from './lib/corpusComponents';
@@ -41,6 +43,10 @@ import DefaultLayout from './components/DefaultLayout';
 import Search from './components/Search';
 import Drawer from './components/Drawer';
 import GroveAgent from './components/GroveAgent';
+import ThemeAssets from './components/ThemeAssets';
+import ContentTheme, { type ContentStylesheet } from './components/ContentTheme';
+import { themeAssetsFor } from './data/themeFonts';
+import { parseFrontmatter } from './lib/frontmatter';
 
 declare const module: any;
 
@@ -59,17 +65,17 @@ function writePref(k: string, v: string): void {
   }
 }
 
-// Corpus-absolute path → the href that navigates to it, for CONTENT (R3-174).
+// Bundle-absolute path → the href that navigates to it, for CONTENT (R3-174).
 //
 // Module scope, and that is load-bearing rather than tidiness: this function is handed to
-// content through `CorpusContext`, and the SDK's `useCorpusEntries` memoizes on its
+// content through `BundleContext`, and the SDK's `useBundleEntries` memoizes on its
 // identity. A closure rebuilt each render would make that memo never hold, so the hook the
 // SDK documents as "safe in a dependency array" would quietly stop being one — from the
 // PROVIDER's side, where nobody using it would think to look. Nothing here is reactive:
 // `contentDir()` is boot-settled module state and `keyToHref` is a pure function of it.
-function corpusHref(corpusPath: string): string {
-  const absolute = fromCorpusPath(corpusPath, contentDir().replace(/\/+$/, ''));
-  return absolute === null ? corpusPath : keyToHref(absolute);
+function bundleHref(bundlePath: string): string {
+  const absolute = fromBundlePath(bundlePath, contentDir().replace(/\/+$/, ''));
+  return absolute === null ? bundlePath : keyToHref(absolute);
 }
 
 // Build the nested render for a layout chain (outermost first). Each layer wraps
@@ -117,6 +123,7 @@ export default function GroveWiki({
 }) {
   const ctx = useContext(TinkerableContext) as any;
   const sandboxPath: string = ctx?.navigationState?.sandboxPath || '/';
+  const hash: string = ctx?.navigationState?.hash ?? '';
 
   // ── Theme selection (R3-308, 02-theme-contract §4) ─────────────────────────
   //
@@ -191,7 +198,7 @@ export default function GroveWiki({
   // `lib/editTarget` — and the gate is the corpus mount's CURRENT mode, re-read on every
   // mount change so a live role downgrade hides the affordance instead of producing
   // `EROFS` on click.
-  const { writable, busy: editBusy, openEditor, editHint } = useEditAffordance(readOnly);
+  const { writable, busy: editBusy, refused: editRefused, openEditor, editHint } = useEditAffordance(readOnly);
 
   const routeKey = sandboxPathToKey(sandboxPath) || homeKey();
   // The site brand is a wiki-wide constant, so read it from the home entry's
@@ -235,8 +242,7 @@ export default function GroveWiki({
   const includePath = keyToInclude(entryKey);
   const meta = useFileMetadata(entryKey) as any;
 
-  const layout: string = meta?.layout || 'doc';
-  const navMode: 'top' | 'side' = 'side';
+  const layout = resolvePageLayout(meta);
   const siteTitle: string = meta?.site || homeMeta?.site || 'Grove';
   // Interpreter mode (TRUST_MODES §5 / R3-213): render this entry's body through the
   // non-executable safe renderer instead of the compiled `<Include>` path.
@@ -263,10 +269,59 @@ export default function GroveWiki({
   // frontmatter map (folder convention + `frame` override), so it reads the whole
   // metadata store and re-derives when the content set or the entry changes.
   const allMeta = useAllMetadata() as Record<string, Record<string, unknown>>;
+
+  // ── Content-carried themes (R3-316) ────────────────────────────────────────
+  // `ui/stylesheet` entries discovered from the SAME index every other surface
+  // reads (mode-invariant: fork, dispatch and library all fill it); bodies are
+  // raw CSS behind frontmatter, gated by the grammar inside ContentTheme and
+  // admitted only into the lowest cascade layer. A rejected sheet degrades to a
+  // status line naming the line — never a silent drop, never a crash.
+  const [contentSheets, setContentSheets] = useState<ContentStylesheet[]>([]);
+  const [rejectedSheet, setRejectedSheet] = useState<string | null>(null);
+  useEffect(() => {
+    let alive = true;
+    const found: ContentStylesheet[] = [];
+    const paths = Object.keys(allMeta).filter((p) => {
+      const tags = allMeta[p]?.tags;
+      return Array.isArray(tags) && tags.includes('ui/stylesheet');
+    });
+    (async () => {
+      for (const p of paths) {
+        try {
+          const raw = await (await import('./lib/safeSources')).safeSources.read(p);
+          const parsed = parseFrontmatter(raw);
+          found.push({
+            path: p,
+            css: parsed.body,
+            declarations: {
+              ...(Array.isArray(parsed.data.fonts) ? { fonts: parsed.data.fonts as never } : {}),
+              ...(parsed.data.assets && typeof parsed.data.assets === 'object' ? { assets: parsed.data.assets as never } : {}),
+            },
+          });
+        } catch {
+          /* an unreadable stylesheet contributes nothing — same as an absent one */
+        }
+      }
+      if (alive) setContentSheets(found);
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [allMeta]);
   const chain: string[] = layoutChainForKey(entryKey, allMeta);
   const frameNone = meta?.frame === 'none' || meta?.frame === false;
+
+  // R3-309 — the nav arrangement is the ROOT layout's to choose (`nav: top` in the
+  // outermost _layout.mdx's frontmatter; the default shell and the starters read the
+  // same value through the shell). Undeclared or unknown → 'side', the arrangement
+  // Grove has always shipped — never an unstyled page.
+  const navMode = resolveNavMode(chain.length ? (allMeta[chain[0]!] as Record<string, unknown>) : undefined);
   const useDefault = chain.length === 0 && !frameNone;
 
+  // Every navigation starts at the top of the entry, except one aimed at a section. The
+  // ref goes on `.device__scroll` below — the only thing on the page that scrolls.
+  const scrollRef = useScrollReset(entryKey, hash);
+
   // Reading time: read the entry body once per entry.
   useEffect(() => {
     let active = true;
@@ -315,6 +370,7 @@ export default function GroveWiki({
     writable,
     openEditor,
     editBusy,
+    editRefused,
     editHint,
     siteTitle,
     safe,
@@ -329,11 +385,11 @@ export default function GroveWiki({
     directory,
   };
 
-  // The corpus scope handed to CONTENT (R3-174; MDX_FROM_MOUNT_SPEC §2, §7 1a).
+  // The bundle scope handed to CONTENT (R3-174; MDX_FROM_MOUNT_SPEC §2, §7 1a).
   //
-  // A component the corpus ships cannot import this engine — it would resolve a second
+  // A component the bundle ships cannot import this engine — it would resolve a second
   // copy from the registry, with its own `contentRoot` module state, and answer about the
-  // wrong corpus — so everything it needs about the corpus arrives through the SDK, which
+  // wrong bundle — so everything it needs about the bundle arrives through the SDK, which
   // both sides genuinely share (one `/node_modules` per frame). Three facts, and each is
   // one a content component cannot derive for itself:
   //
@@ -345,7 +401,7 @@ export default function GroveWiki({
   //    a `_layout.mdx` wraps the entry, so `<Include>`'s own module identity would name
   //    the layout; furniture in the layout chain (a status line, a dependency rail) needs
   //    the page it is describing.
-  //  • `toHref` — because corpus-path→URL is this VIEWER's policy and the two packagings
+  //  • `toHref` — because bundle-path→URL is this VIEWER's policy and the two packagings
   //    genuinely disagree (`urlAnchor`). Content that computed its own hrefs would be
   //    correct in exactly one packaging, which is the mode-invariance rule
   //    (PLATFORM_LAYERING §1.1) broken in the least visible possible way.
@@ -358,25 +414,28 @@ export default function GroveWiki({
   // rejects one here because `entryKey` derives from the metadata query's array).
   //
   // That is safe because the EXPENSIVE half does not key on this object's identity: the
-  // SDK's `useCorpusEntries` destructures `{root, toHref}` and memoizes on those, and both
+  // SDK's `useBundleEntries` destructures `{root, toHref}` and memoizes on those, and both
   // are stable — `root` is a string compared by value, `toHref` is the module-scope
-  // `corpusHref` above. A new wrapper re-renders consumers (cheap); it does not re-derive
+  // `bundleHref` above. A new wrapper re-renders consumers (cheap); it does not re-derive
   // 800-odd entries. Making `toHref` a closure would silently undo that, which is the
   // whole reason it is not one.
-  const corpusRoot = contentDir().replace(/\/+$/, '');
-  const corpusEntry = toCorpusPath(entryKey, corpusRoot);
-  const corpusScope = { root: corpusRoot, entry: corpusEntry, toHref: corpusHref };
+  const bundleRoot = contentDir().replace(/\/+$/, '');
+  const bundleEntry = toBundlePath(entryKey, bundleRoot);
+  const bundleScope = { root: bundleRoot, entry: bundleEntry, toHref: bundleHref };
 
   return (
-    // R3-277b: declare the enclosing corpus for the platform's link-space consumers
-    // (the shared resolver's corpus-anchored absolute + `$fs:` handling read this).
+    // R3-277b: declare the enclosing bundle for the platform's link-space consumers
+    // (the shared resolver's bundle-anchored absolute + `$fs:` handling read this).
+    // R3-482: the field keeps the deprecated `corpusRoot` spelling until grove's SDK
+    // pin reaches a release whose WikiLink reads `bundleRoot` (sdk#171 / 0.68.1) —
+    // stating only the new spelling now would silently un-anchor every absolute link.
     <LinkSpaceContext.Provider value={{ corpusRoot: getContentRoot() }}>
-    {/* R3-174: the corpus scope CONTENT reads — sibling to the link space, not a
+    {/* R3-174: the bundle scope CONTENT reads — sibling to the link space, not a
         replacement for it. The two answer different questions: `LinkSpaceContext` tells
-        the platform's link resolver where absolute hrefs are anchored; `CorpusContext`
-        tells a component the corpus ships which entries exist, which one is being read,
-        and how to turn a corpus path into a URL. */}
-    <CorpusContext value={corpusScope}>
+        the platform's link resolver where absolute hrefs are anchored; `BundleContext`
+        tells a component the bundle ships which entries exist, which one is being read,
+        and how to turn a bundle path into a URL. */}
+    <BundleContext value={bundleScope}>
     <GroveShellContext.Provider value={shell}>
       <div
         className="grove-root"
@@ -385,7 +444,23 @@ export default function GroveWiki({
         data-grove-theme={theme === 'default' ? undefined : theme}
         data-theme={polarity}
       >
-        <div className="device__scroll">
+        {/* R3-310: the ACTIVE theme's declared faces — the engine mints blob:
+            @font-face rules (R3-315's mechanism); switching themes revokes the
+            outgoing set and re-mints. */}
+        <ThemeAssets declarations={themeAssetsFor(theme)} />
+        <ContentTheme sheets={contentSheets} onRejected={(path, v) => setRejectedSheet(`${path}:${v.line} — ${v.reason}`)} />
+        {/* R3-627: remember where the reader was on the entry they leave, and put
+            them back there on Back. Grove's scroller is its own container, so the
+            ref goes across; `useScrollReset` above stands down on the same
+            traversal so the two do not fight. */}
+        <ScrollRestoration scroller={scrollRef} />
+        <div className="device__scroll" ref={scrollRef}>
+          {rejectedSheet ? (
+            <div className="grove-decl-error" role="status">
+              <strong>A stylesheet entry was rejected by the theme grammar.</strong>
+              <div>{rejectedSheet}</div>
+            </div>
+          ) : null}
           {rejectedComponents.length > 0 ? (
             <div className="grove-decl-error" role="status">
               <strong>This corpus declares components that could not be loaded.</strong>
@@ -411,10 +486,10 @@ export default function GroveWiki({
             onClose={() => setDrawerOpen(false)}
           />
         ) : null}
-        <GroveAgent writable={writable} entryKey={entryKey} entryTitle={(meta?.title || 'this entry').replace(/\.$/, '')} />
+        <GroveAgent writable={writable} entryKey={entryKey} entryTitle={plainLabel(meta?.title || 'this entry')} />
       </div>
     </GroveShellContext.Provider>
-    </CorpusContext>
+    </BundleContext>
     </LinkSpaceContext.Provider>
   );
 }

package/src/components/AssetImage.tsx

@@ -3,6 +3,7 @@ import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
 import { MountImage } from '@immediately-run/sdk';
 import type { SandboxMount } from '@immediately-run/sdk';
 import { toFsPath } from '../lib/content';
+import { resolvePath } from '../lib/assetPath';
 
 // MDX `img` override: display a mount-relative image by reading its bytes off the
 // sandbox fs (the opaque-origin iframe can't fetch a relative path). Resolves the
@@ -10,18 +11,6 @@ import { toFsPath } from '../lib/content';
 // then hands the file to the SDK's `MountImage`, which owns the read → object URL →
 // revoke lifecycle we used to hand-roll here.
 
-function resolvePath(basePath: string, relativePath: string): string {
-  if (relativePath.startsWith('/')) return relativePath;
-  const parts = basePath.split('/');
-  parts.pop();
-  for (const part of relativePath.split('/')) {
-    if (part === '.' || part === '') continue;
-    if (part === '..') parts.pop();
-    else parts.push(part);
-  }
-  return parts.join('/');
-}
-
 // The whole sandbox fs, `/`-rooted. The resolved asset path is already absolute
 // (`/app/content/…`), so anchor at root and pass it as the mount-relative path
 // (leading slash stripped) — preserving the exact paths the old `fs.readFile` read.

package/src/components/Backlinks.tsx

@@ -5,6 +5,7 @@ import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
 import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
 import { isContentEntry, keyToFsPath, keyToHref, sandboxPathToKey } from '../lib/content';
 import { backlinkSnippet, bodyLinksTo, crumb, queryPaths } from '../lib/wiki';
+import InlineProse from './InlineProse';
 
 interface Hit {
   key: string;
@@ -14,11 +15,10 @@ interface Hit {
 // One linking entry: title + namespace crumb + the snippet around the link.
 function Row({ hit }: { hit: Hit }) {
   const meta = useFileMetadata(hit.key) as any;
-  const title = (meta?.title || crumb(hit.key)).replace(/\.$/, '');
   return (
     <Link href={keyToHref(hit.key)} className="grove-bl">
       <div className="grove-bl__t">
-        {title}
+        <InlineProse text={meta?.title || crumb(hit.key)} trimPeriod />
         <span className="crumb">/{crumb(hit.key)}</span>
       </div>
       <div className="grove-bl__snip" dangerouslySetInnerHTML={{ __html: hit.snippet }} />

package/src/components/Catalogue.test.tsx

@@ -0,0 +1,157 @@
+// @vitest-environment jsdom
+// R3-310's catalogue exits at the component:
+//   • BYTE-IDENTICAL MARKUP under all four themes — the claim the catalogue is
+//     for ("assert it, do not eyeball it"): the same wiki renders the same DOM,
+//     the theme being the single root-level attribute that differs;
+//   • the webfont looks declare their faces and mint them from LOCAL bytes
+//     (network-off rendering is byte-for-byte the same mechanism);
+//   • the catalogue exposes exactly the four shippable looks.
+import { describe, it, expect, vi, beforeEach, beforeAll } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { mintThemeAssets } from '../lib/themeAssets';
+import { themeAssetsFor, ARCHIVE_THEME_ASSETS, JOURNAL_THEME_ASSETS } from '../data/themeFonts';
+import { THEMES } from '../data/themes';
+
+// GroveWiki reads viewport state at mount; jsdom has no matchMedia.
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (q: string) => ({ matches: false, media: q, addEventListener: () => {}, removeEventListener: () => {}, addListener: () => {}, removeListener: () => {}, dispatchEvent: () => false, onchange: null }),
+  });
+});
+
+const readFile = vi.fn();
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: GroveWiki } = await import('../GroveWiki');
+
+const NAV = {
+  mode: 'github',
+  namespace: 'immediately-run',
+  provider: 'github',
+  repository: 'corpus',
+  ref: 'main',
+  sandboxPath: '/app/content/wiki/a.mdx',
+  hash: '',
+  search: '',
+};
+
+// `render: safe` — the interpreter body path, so the render exercises the real
+// safe renderer over the fs double instead of the compiled-MDX evaluator, which
+// exists only inside the sandbox bundler. (Both paths produce the same DOM shape;
+// the compiled one is the bundler's, not the theme's.)
+const META = {
+  '/app/content/wiki/a.mdx': { title: 'Reference entry.', tags: ['x'], render: 'safe' },
+  '/app/content/_layout.mdx': { site: 'Catalogue fixture' },
+};
+
+async function renderWiki(): Promise<{ container: HTMLElement; root: Root }> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(
+      <TinkerableContext.Provider
+        value={{
+          outerHref: 'https://immediately.run/x',
+          navigationState: NAV,
+          routingSpec: { routes: [] } as never,
+          filesMetadata: META,
+        } as never}
+      >
+        <GroveWiki />
+      </TinkerableContext.Provider>,
+    );
+  });
+  // Flush the async bits the wiki mounts (the scan, the asset mint, observers).
+  for (let i = 0; i < 6; i++) await act(async () => {});
+  return { container, root };
+}
+
+/** Serialize the wiki with the THEME ATTRIBUTES MASKED — everything else must be
+ *  byte-identical across themes. */
+function serialized(container: HTMLElement, maskAttr: string[]): string {
+  const clone = container.querySelector('.grove-root')?.cloneNode(true) as HTMLElement | null;
+  if (!clone) return '(no .grove-root)';
+  // Drop engine-minted style URLs (they are per-mount object URLs by design).
+  clone.querySelectorAll('style[data-grove-theme-assets]').forEach((s) => s.remove());
+  const rootEl = clone;
+  for (const a of maskAttr) rootEl.removeAttribute(a);
+  return rootEl.innerHTML;
+}
+
+beforeEach(() => {
+  readFile.mockReset();
+  readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+  localStorage.clear();
+});
+
+describe('byte-identical markup under all four themes', () => {
+  for (const theme of ['default', 'archive', 'journal', 'editorial']) {
+    it(`theme=${theme}: the same wiki, the same DOM`, async () => {
+      localStorage.setItem('grove:theme', theme);
+      const { container, root } = await renderWiki();
+      const html = serialized(container, ['data-grove-theme', 'data-theme']);
+      expect(container.querySelector('.grove-root')).toBeTruthy();
+      // The theme actually applied (the one assertion attr-specific):
+      const applied = container.querySelector('.grove-root')?.getAttribute('data-grove-theme');
+      expect(applied ?? 'default').toBe(theme);
+      (globalThis as unknown as Record<string, string>)[`__wiki_${theme}`] = html;
+      await act(async () => {
+        root.unmount();
+      });
+    });
+  }
+
+  it('all four serializations are byte-identical', () => {
+    const g = globalThis as unknown as Record<string, string>;
+    const set = new Set(['default', 'archive', 'journal', 'editorial'].map((t) => g[`__wiki_${t}`]));
+    expect(set.size).toBe(1);
+  });
+});
+
+describe('the webfont looks declare and mint their faces from local bytes', () => {
+  it('archive mints Source Serif 4 from the in-repo bytes (network-off by construction)', async () => {
+    const m = await mintThemeAssets(ARCHIVE_THEME_ASSETS, '/app/src/index.css', async (p) => {
+      // Only the theme's OWN additions resolve here; the default-set faces share
+      // the same mechanism (proven in ThemeAssets.test) — assert the serif legs.
+      if (!p.includes('source-serif-4')) throw new Error('ENOENT');
+      return new Uint8Array([1]);
+    });
+    expect(m.minted).toBe(4); // 400/500/600/700
+    expect(m.fontFaceCss).toContain('"Source Serif 4"');
+  });
+
+  it('journal mints Lora the same way', async () => {
+    const m = await mintThemeAssets(JOURNAL_THEME_ASSETS, '/app/src/index.css', async (p) => {
+      if (!p.includes('lora')) throw new Error('ENOENT');
+      return new Uint8Array([1]);
+    });
+    expect(m.minted).toBe(4);
+    expect(m.fontFaceCss).toContain('"Lora"');
+  });
+
+  it('editorial keeps the default set — loud through weight and colour, not a new face', () => {
+    expect(themeAssetsFor('editorial')).toEqual(themeAssetsFor('default'));
+  });
+
+  it('every declared face file actually ships in the repo (the offline guarantee)', async () => {
+    const { readdir } = await import('node:fs/promises');
+    const shipped = new Set(await readdir('assets/fonts'));
+    for (const set of [themeAssetsFor('default'), ARCHIVE_THEME_ASSETS, JOURNAL_THEME_ASSETS]) {
+      for (const f of set.fonts ?? []) {
+        expect(shipped.has(f.src.split('/').pop() as string)).toBe(true);
+      }
+    }
+  });
+});
+
+describe('the catalogue', () => {
+  it('is exactly the four shippable looks; the showcase skins are retired', () => {
+    expect(THEMES.map((t) => t.id)).toEqual(['default', 'archive', 'journal', 'editorial']);
+  });
+});

package/src/components/ContentTheme.test.tsx

@@ -0,0 +1,146 @@
+// @vitest-environment jsdom
+// R3-316's component + escape-hatch exits:
+//   • a clean ui/stylesheet renders into @layer grove.content (and its declared
+//     faces mint through the R3-315 path — never a url());
+//   • a rejected sheet names the line and degrades (no style element for it);
+//   • THE ESCAPE HATCH: the hiding vectors a content stylesheet would try are
+//     each answered by a grove.reset !important pin — and the layer ORDER puts
+//     grove.reset first (for !important, earlier layers win), so grove.content
+//     cannot out-priority it. Proven against the SHIPPED css bytes.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { join } from 'node:path';
+
+const readFile = vi.fn();
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: ContentTheme } = await import('./ContentTheme');
+
+async function render(node: React.ReactNode): Promise<HTMLElement> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    createRoot(container).render(node);
+  });
+  for (let i = 0; i < 4; i++) await act(async () => {});
+  return container;
+}
+
+const SHEET = (css: string, extra: Record<string, unknown> = {}) => ({
+  path: '/app/content/style.mdx',
+  css,
+  declarations: extra as never,
+});
+
+beforeEach(() => readFile.mockReset());
+
+describe('admission into the lowest layer', () => {
+  it('a clean sheet renders as @layer grove.content on .grove-root', async () => {
+    const el = await render(<ContentTheme sheets={[SHEET('--bg: #123;\n')]} />);
+    const style = el.querySelector('style[data-grove-content-theme]');
+    expect(style?.textContent).toContain('@layer grove.content');
+    expect(style?.textContent).toContain('--bg: #123');
+  });
+
+  it('a rejected sheet degrades — no style element, verdict delivered to the caller', async () => {
+    const onRejected = vi.fn();
+    const el = await render(
+      <ContentTheme sheets={[SHEET('.evil { display: none; }')]} onRejected={onRejected} />,
+    );
+    expect(el.querySelector('style[data-grove-content-theme]')).toBeNull();
+    expect(onRejected).toHaveBeenCalledWith(
+      '/app/content/style.mdx',
+      expect.objectContaining({ line: 1, reason: expect.stringMatching(/selector/) }),
+    );
+  });
+
+  it('declared faces mint through the engine path (blob:), never a url()', async () => {
+    readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+    const el = await render(
+      <ContentTheme
+        sheets={[
+          SHEET('--bg: #123;\n', {
+            fonts: [{ family: 'Lora', src: './lora.woff2', weight: '400' }],
+          }),
+        ]}
+      />,
+    );
+    const assets = el.querySelector('style[data-grove-content-assets]');
+    expect(assets?.textContent).toContain('"Lora"');
+    expect(assets?.textContent).toMatch(/blob:/);
+    expect(assets?.textContent).not.toContain('/app/content');
+  });
+});
+
+// Read the shipped bytes via node:fs/promises (node:fs's readFileSync resolves
+// through the dev-fs bridge under jsdom, which is not what these read).
+const { readFile: readFileAsync } = await import('node:fs/promises');
+const css = await readFileAsync(join('src', 'GroveApp.css'), 'utf8');
+const indexCss = await readFileAsync(join('src', 'index.css'), 'utf8');
+const readNav = async () => readFileAsync(join('src', 'components', 'GroveNav.tsx'), 'utf8');
+
+describe('THE ESCAPE HATCH — a planted stylesheet cannot hide the theme control', () => {
+
+  /** Extract one `@layer grove.reset { … }` block's body. */
+  const resetBlock = (() => {
+    const i = css.indexOf('@layer grove.reset {');
+    if (i === -1) return '';
+    let depth = 0;
+    let end = i + '@layer grove.reset '.length;
+    for (; end < css.length; end++) {
+      if (css[end] === '{') depth++;
+      else if (css[end] === '}') {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    return css.slice(i, end);
+  })();
+
+  it('the layer order puts grove.reset FIRST — for !important, earlier layers win', () => {
+    const order = indexCss.match(/@layer\s+([^;]+);/)?.[1] ?? '';
+    const layers = order.split(',').map((l) => l.trim());
+    expect(layers[0]).toBe('grove.reset');
+    expect(layers.indexOf('grove.content')).toBeGreaterThan(layers.indexOf('grove.reset'));
+  });
+
+  it('every hiding vector a content stylesheet would try is answered by a reset pin', () => {
+    expect(resetBlock).toContain('.grove-theme-control');
+    // The vectors: display/visibility/opacity/pointer-events (the obvious four),
+    // clip-path/transform/position/z-index (the geometric ones),
+    // width/height/overflow (collapse), filter (blur-to-nothing).
+    for (const vector of [
+      'display',
+      'visibility',
+      'opacity',
+      'pointer-events',
+      'clip-path',
+      'transform',
+      'position',
+      'z-index',
+      'width',
+      'height',
+      'overflow',
+      'filter',
+    ]) {
+      expect(resetBlock).toContain(`${vector}:`);
+    }
+    // And every pin is !important — plain declarations in grove.reset would LOSE
+    // to grove.content's own !important for normal... they need the important flag.
+    const pins = resetBlock.match(/\w[\w-]*:\s*[^;]+!/g) ?? [];
+    expect(pins.length).toBeGreaterThanOrEqual(12);
+  });
+
+  it('the control carries the protected class in the shipped markup', async () => {
+    const nav = await readNav();
+    expect(nav).toContain('grove-theme-control');
+  });
+
+  it('FAULT: a reset block missing the vector list fails this check (not vacuous)', () => {
+    const sabotage = resetBlock.replace('visibility: visible !important;', '');
+    expect(sabotage).not.toContain('visibility: visible !important;');
+  });
+});