@immediately-run/grove 0.1.1 → 0.1.3

package/src/GroveWiki.tsx

@@ -5,14 +5,15 @@ import fs from 'fs';
 import type { Metadata } from '@immediately-run/sdk';
 import {
   Include,
+  ScrollRestoration,
   useAllMetadata,
   useFileMetadata,
+  useHostTheme,
   useMetadataQuery,
-  useMounts,
 } 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,12 +24,16 @@ 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 { getContentRoot, isDispatched } from './lib/contentRoot';
+import { useScrollReset } from './hooks/useScrollReset';
+import { useEditAffordance } from './hooks/useEditAffordance';
+import { getContentRoot } from './lib/contentRoot';
 import type { RejectedComponent } from './lib/corpusComponents';
 import { GroveShellContext, OutletContext } from './lib/shell';
 import type { GroveShell, NavItem } from './lib/shell';
@@ -38,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;
 
@@ -56,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
@@ -114,10 +123,45 @@ export default function GroveWiki({
 }) {
   const ctx = useContext(TinkerableContext) as any;
   const sandboxPath: string = ctx?.navigationState?.sandboxPath || '/';
-  const mounts = useMounts() as any[];
+  const hash: string = ctx?.navigationState?.hash ?? '';
 
-  const [theme, setTheme] = useState(() => readPref('grove:theme') || 'default');
-  const [light, setLight] = useState(() => readPref('grove:appearance') === 'light');
+  // ── Theme selection (R3-308, 02-theme-contract §4) ─────────────────────────
+  //
+  // Two INDEPENDENT axes with three sources, resolved through ONE module
+  // (lib/themeSelection) so no surface re-derives the precedence:
+  //
+  //   palette  = reader override, else the author's `theme:` on the home entry, else default
+  //   polarity = reader override, else the host's theme, else the palette's preferred
+  //
+  // The stored prefs are OVERRIDES, nullable by nature: absent until the reader
+  // acts, which is what gives the author's declaration its turn. They are written
+  // by the user actions (chooseTheme/choosePolarity), NEVER by an effect on mount
+  // — the old effects promoted the initial value to a reader choice on first
+  // visit, which is exactly why a `theme:` declaration could never have won.
+  // (Visitors from before this change carry a mount-written pref; it stands —
+  // they are Grove readers, and a reader outranks an author.)
+  const [readerTheme, setReaderTheme] = useState<string | null>(() => readPref('grove:theme'));
+  const [readerAppearance, setReaderAppearance] = useState<Polarity | null>(() => {
+    const p = readPref('grove:appearance');
+    return p === 'light' || p === 'dark' ? p : null;
+  });
+  const chooseTheme = (id: string) => {
+    setReaderTheme(id);
+    writePref('grove:theme', id);
+  };
+  const choosePolarity = (wantLight: boolean) => {
+    const p: Polarity = wantLight ? 'light' : 'dark';
+    setReaderAppearance(p);
+    writePref('grove:appearance', p);
+  };
+  // The host drives POLARITY ONLY (`theme:read` is the one theme capability the
+  // open-wiki binding holds) — and only when there IS a host. `useHostTheme`'s
+  // channel reports an `initial: 'dark'` before any host speaks, so an unframed
+  // standalone `vite dev` render would otherwise carry a phantom host opinion
+  // and flip light-preferred themes. Framed === a host exists to have one.
+  const framed = typeof window !== 'undefined' && window.parent !== window;
+  const hostTheme = useHostTheme();
+  const hostPolarity: Polarity | null = framed ? hostTheme : null;
   const [menuOpen, setMenuOpen] = useState(false);
   const [searchOpen, setSearchOpen] = useState(false);
   const [drawerOpen, setDrawerOpen] = useState(false);
@@ -132,8 +176,6 @@ export default function GroveWiki({
     mq.addEventListener('change', on);
     return () => mq.removeEventListener('change', on);
   }, []);
-  useEffect(() => writePref('grove:theme', theme), [theme]);
-  useEffect(() => writePref('grove:appearance', light ? 'light' : 'dark'), [light]);
 
   // ⌘K / Ctrl-K opens search.
   useEffect(() => {
@@ -147,28 +189,37 @@ export default function GroveWiki({
     return () => window.removeEventListener('keydown', on);
   }, []);
 
-  // ⚠ TEMPORARY, and not a design: dispatched content IS writable — R3-266.
-  //
-  // The affordance below calls `requestEdit`, which is **self-scoped by contract** ("v1
-  // supports only a repo-relative path in the CURRENT repo … editing a file in one of your
-  // mounts is the `edit-file` task, not this"). Under dispatch the corpus is a mount, so
-  // that call would edit GROVE rather than the corpus on screen. Offering it would be
-  // wrong; withholding it *as a design* is also wrong, and this comment exists so the next
-  // reader does not conclude the second from the first.
+  // R3-266 — dispatched content IS writable, and the MOUNT decides.
   //
-  // The fix is a verb swap, not a withheld capability: delegate the entry to
-  // `invokeTask('edit-file', { file: capFile({ mountId, relPath }, { mode: 'rw' }) })`,
-  // declare `invokes: edit-file`, and gate on the CORPUS MOUNT's mode rather than on the
-  // packaging. A task callee already holds the minted delegated grant, so nothing new has
-  // to be minted. Tracked in R3-266; `docs/specs/REPO_CONTENT_DISPATCH_SPEC.mdx` §5.
-  const writable =
-    !isDispatched() && !readOnly && (mounts?.some((m) => m.type === 'worktree' && m.mode !== 'ro') ?? false);
+  // This used to read `!isDispatched() && …`, withholding every edit affordance from a
+  // dispatched viewer. The reason was real but the conclusion was not: `requestEdit` is
+  // **self-scoped by contract**, so under dispatch it names a path in GROVE's repo rather
+  // than in the corpus on screen. The fix is a verb swap, not a withheld capability — see
+  // `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, 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
   // `site` frontmatter — not the current entry's (which only home would carry),
   // else the brand flips to the 'Grove' fallback on every sub-page.
   const homeMeta = useFileMetadata(homeKey()) as any;
+  // R3-308: the author's palette declaration — `theme:` on the home entry, the
+  // wiki-wide sibling of `site:`. Like `site`, it is read from HOME and not the
+  // current entry, so a sub-page never flips the wiki's look back to `default`.
+  const authorTheme: string | null =
+    typeof homeMeta?.theme === 'string' && homeMeta.theme ? homeMeta.theme : null;
+  // The two axes, resolved through the one module that owns the precedence. `theme`
+  // and `light` below are the RESOLVED values every surface renders from — the raw
+  // reader overrides live only in state and in the menu handlers.
+  const theme = resolvePalette({ reader: readerTheme, author: authorTheme });
+  const polarity: Polarity = resolvePolarity({
+    reader: readerAppearance,
+    host: hostPolarity,
+    preferred: preferredPolarity(theme),
+  });
+  const light = polarity === 'light';
   // Existence / 404: the whole index tells us if a followed link is dead. Layout
   // files are structure, not entries, so they're excluded here (and everywhere).
   const allKeysQuery = useCallback((fm: Record<string, any>) => Object.keys(fm).filter(isContentEntry), []);
@@ -191,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.
@@ -219,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;
@@ -257,9 +356,9 @@ export default function GroveWiki({
 
   const shell: GroveShell = {
     theme,
-    setTheme,
+    setTheme: chooseTheme,
     light,
-    setLight,
+    setLight: choosePolarity,
     menuOpen,
     setMenuOpen,
     searchOpen,
@@ -269,6 +368,10 @@ export default function GroveWiki({
     vw,
     navMode,
     writable,
+    openEditor,
+    editBusy,
+    editRefused,
+    editHint,
     siteTitle,
     safe,
     navItems,
@@ -282,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:
   //
@@ -298,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.
@@ -311,34 +414,53 @@ 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"
         data-vw={vw}
         data-nav={navMode}
         data-grove-theme={theme === 'default' ? undefined : theme}
-        data-theme={theme === 'default' && light ? 'light' : undefined}
+        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>
@@ -364,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']);
+  });
+});