@immediately-run/grove 0.1.2 → 0.1.3

package/src/components/ThemeAssets.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useRef, useState } from 'react';
+import { mintThemeAssets, type MintedThemeAssets, type ThemeAssetDeclarations } from '../lib/themeAssets';
+import { openFs } from '@immediately-run/sdk';
+
+// The engine-owned emission of a declaration set's minted assets (R3-315): one
+// `<style data-grove-theme-assets>` carrying the `@font-face` rules inside the
+// ENGINE cascade layer and the `--asset-*` assignments on `.grove-root`. The
+// revoke scope is the declaration set's lifetime — switching themes (or a reader
+// override re-resolving the set) revokes the outgoing URLs before the incoming
+// ones mint, so repeated switches leak nothing.
+//
+// Nothing here is content-styleable: the layer order in `index.css` namespaces
+// these rules as `grove.engine`, below the reset but above theme and content.
+
+/** The declaring-file anchor for the engine's own default set — the app repo root
+ *  (fork AND dispatch load the engine from this repo; `/app` is its own tree). */
+const ENGINE_DECLARING_FILE = '/app/src/index.css';
+
+// The whole sandbox fs, `/`-rooted — the same anchor `AssetImage`/`EntryImage` use.
+const ROOT_MOUNT = { path: '/', type: 'repo' } as const;
+
+interface Props {
+  declarations: ThemeAssetDeclarations;
+  /** Absolute fs path of the file the declarations live in (resolution base). */
+  basePath?: string;
+}
+
+export default function ThemeAssets({ declarations, basePath = ENGINE_DECLARING_FILE }: Props) {
+  const [minted, setMinted] = useState<MintedThemeAssets | null>(null);
+  // The CURRENT set, reached from the cleanup — a setState updater does NOT run
+  // on unmount (React 18+), so reaching the outgoing URLs only through state
+  // would leak them exactly there.
+  const mintedRef = useRef<MintedThemeAssets | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    // Read through the SDK's fs surface (the same one `MountImage` reads
+    // through): it resolves the sandbox's injected shared fs in every stance,
+    // where a bare `import fs` would only work where the bundler shims it.
+    const rootFs = openFs(ROOT_MOUNT);
+    void mintThemeAssets(declarations, basePath, async (p) => {
+      const bytes = await rootFs.readFile(p.replace(/^\/+/, ''));
+      return typeof bytes === 'string' ? new TextEncoder().encode(bytes) : new Uint8Array(bytes);
+    }).then((m) => {
+      if (!alive) {
+        m.revoke(); // the set changed/unmounted mid-mint — never leak the late arrival
+        return;
+      }
+      mintedRef.current = m;
+      setMinted(m);
+    });
+    return () => {
+      alive = false;
+      // Revoke the OUTGOING set on switch/unmount — the theme's lifetime ends here.
+      mintedRef.current?.revoke();
+      mintedRef.current = null;
+      setMinted(null);
+    };
+  }, [declarations, basePath]);
+
+  if (!minted || (!minted.fontFaceCss && !minted.assetVarsCss)) return null;
+  return <style data-grove-theme-assets="">{`@layer grove.engine{${minted.fontFaceCss}}\n${minted.assetVarsCss}`}</style>;
+}

package/src/components/ThemeGallery.tsx

@@ -0,0 +1,31 @@
+import { manifestThemes } from '../data/catalogue';
+import { THEMES } from '../data/themes';
+
+// The themes gallery (R3-311): one row per SHIPPED theme, enumerated from
+// viewer.manifest.json — adding a theme to the manifest adds a row here with no
+// edit to the entry. The swatch is the live gradient each catalogue entry
+// declares (data/themes.ts), rendered with the theme's OWN tokens applied to the
+// swatch chip, so the comparison is the real thing, not a screenshot of it.
+
+export default function ThemeGallery() {
+  const rows = manifestThemes();
+  return (
+    <div className="gg-gallery" role="list" aria-label="The shipped themes">
+      {rows.map(([id, t]) => {
+        const swatch = THEMES.find((x) => x.id === id)?.swatch ?? 'linear-gradient(96deg,#888,#555)';
+        return (
+          <div className="gg-row" role="listitem" key={id} data-gallery-id={id}>
+            <span className="gg-swatch" style={{ background: swatch }} aria-hidden />
+            <div className="gg-body">
+              <div className="gg-title">
+                <code>{id}</code> — {t.label}
+                <span className="gg-meta">opens {t.preferred}</span>
+              </div>
+              <div className="gg-summary">{t.summary}</div>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/Timeline.tsx

@@ -2,7 +2,9 @@
 import { useCallback } from 'react';
 import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
 import { isContentEntry, keyToHref } from '../lib/content';
+import InlineProse from './InlineProse';
 import { queryPaths } from '../lib/wiki';
+import EntryImage from './EntryImage';
 
 // One dated entry on the axis: mono date · node · card.
 function Row({ path }: { path: string }) {
@@ -14,8 +16,9 @@ function Row({ path }: { path: string }) {
       <div className="gtl-date">{m.date}</div>
       <div className="gtl-node" />
       <div className="gtl-card">
-        <div className="gtl-title">{(m.title || path).replace(/\.$/, '')}</div>
-        {m.description && <div className="gtl-desc">{m.description}</div>}
+        <EntryImage entryPath={path} src={m.cover} alt="" className="gtl-cover" degrade={null} />
+        <div className="gtl-title"><InlineProse text={m.title || path} trimPeriod /></div>
+        {m.description && <div className="gtl-desc"><InlineProse text={m.description} /></div>}
         {tags.length ? (
           <div className="gtl-tags">
             {tags.slice(0, 3).map((t) => (

package/src/components/WikiLink.tsx

@@ -79,7 +79,7 @@ export default function WikiLink({ href = '', children, ...rest }: Props) {
       );
     }
     return (
-      <span className="grove-wikilink" data-state="broken" title={`No entry at ${href}`}>
+      <span className="grove-wikilink" data-state="broken" title={`No entry at ${href}`} aria-label={`No entry at ${href}`}>
         <Icon name="unlink" />
         {children}
       </span>
@@ -97,7 +97,7 @@ export default function WikiLink({ href = '', children, ...rest }: Props) {
   const exists = !loaded || keys.includes(targetKey); // optimistic until loaded
   if (!exists) {
     return (
-      <span className="grove-wikilink" data-state="broken" title={`No entry at ${href}`}>
+      <span className="grove-wikilink" data-state="broken" title={`No entry at ${href}`} aria-label={`No entry at ${href}`}>
         <Icon name="unlink" />
         {children}
       </span>

package/src/data/catalogue.ts

@@ -0,0 +1,54 @@
+// Typed views over viewer.manifest.json's catalogue sections — the manifest is
+// the contract (R3-309/R3-311): every shipped theme, page variant, starter and
+// collection shape is enumerated THERE, and the gallery entries render FROM it,
+// so adding an entry to the manifest adds a row with no edit to any entry.
+
+import manifest from '../../viewer.manifest.json';
+
+export interface ManifestTheme {
+  label: string;
+  preferred: 'light' | 'dark';
+  ships: boolean;
+  summary: string;
+}
+export interface ManifestPageVariant {
+  key: string;
+  value: string;
+  ships: boolean;
+  summary: string;
+}
+export interface ManifestLayout {
+  layoutRole: string;
+  arranges: string;
+  ships: boolean;
+  summary: string;
+}
+export interface ManifestCollection {
+  component?: string;
+  props?: Record<string, string>;
+  ships: boolean;
+  summary: string;
+}
+
+const cat = manifest as unknown as {
+  themes: Record<string, ManifestTheme>;
+  pageVariants: Record<string, ManifestPageVariant>;
+  layouts: Record<string, ManifestLayout>;
+  collections: Record<string, ManifestCollection>;
+};
+
+/** The shipped themes, manifest order. */
+export const manifestThemes = (): Array<[string, ManifestTheme]> =>
+  Object.entries(cat.themes).filter(([, t]) => t.ships);
+
+/** The shipped page variants (bucket B — a frontmatter key on one entry). */
+export const manifestPageVariants = (): Array<[string, ManifestPageVariant]> =>
+  Object.entries(cat.pageVariants).filter(([, v]) => v.ships);
+
+/** The shipped layout starters (bucket A — a copyable `_layout.mdx`). */
+export const manifestLayouts = (): Array<[string, ManifestLayout]> =>
+  Object.entries(cat.layouts).filter(([, l]) => l.ships);
+
+/** The shipped collection shapes (bucket C — a component call). */
+export const manifestCollections = (): Array<[string, ManifestCollection]> =>
+  Object.entries(cat.collections).filter(([, c]) => c.ships);

package/src/data/themeFonts.ts

@@ -0,0 +1,58 @@
+// The per-theme face sets (R3-310; the R3-315 declared-asset mechanism): the
+// engine default's families plus the two catalogue looks that change the reading
+// face. `archive` puts a serif in `--sans` — the contract's documented role rule
+// ("`--sans` is the body face, whatever face that is"); `journal` reads warm in
+// Lora; `editorial` is loud through weight, tracking and colour, not through a
+// new face, so it keeps the default set. Data, not components.
+
+import type { ThemeAssetDeclarations } from '../lib/themeAssets';
+
+const F = (family: string, file: string, weight: string) => ({ family, src: `/app/assets/fonts/${file}`, weight, style: 'normal' });
+
+/** The engine default: Gabarito (display) · Public Sans (body) · Space Mono. */
+export const DEFAULT_THEME_ASSETS: ThemeAssetDeclarations = {
+  fonts: [
+    F('Gabarito', 'gabarito-latin-400-normal.woff2', '400'),
+    F('Gabarito', 'gabarito-latin-500-normal.woff2', '500'),
+    F('Gabarito', 'gabarito-latin-600-normal.woff2', '600'),
+    F('Gabarito', 'gabarito-latin-700-normal.woff2', '700'),
+    F('Gabarito', 'gabarito-latin-800-normal.woff2', '800'),
+    F('Gabarito', 'gabarito-latin-900-normal.woff2', '900'),
+    F('Public Sans', 'public-sans-latin-400-normal.woff2', '400'),
+    F('Public Sans', 'public-sans-latin-500-normal.woff2', '500'),
+    F('Public Sans', 'public-sans-latin-600-normal.woff2', '600'),
+    F('Public Sans', 'public-sans-latin-700-normal.woff2', '700'),
+    F('Space Mono', 'space-mono-latin-400-normal.woff2', '400'),
+    F('Space Mono', 'space-mono-latin-700-normal.woff2', '700'),
+  ],
+};
+
+/** `archive` — the reading face is Source Serif 4 (dense reference); display
+ *  keeps Gabarito so nav and furniture stay legible-brand. */
+export const ARCHIVE_THEME_ASSETS: ThemeAssetDeclarations = {
+  fonts: [
+    ...DEFAULT_THEME_ASSETS.fonts!,
+    F('Source Serif 4', 'source-serif-4-latin-400-normal.woff2', '400'),
+    F('Source Serif 4', 'source-serif-4-latin-500-normal.woff2', '500'),
+    F('Source Serif 4', 'source-serif-4-latin-600-normal.woff2', '600'),
+    F('Source Serif 4', 'source-serif-4-latin-700-normal.woff2', '700'),
+  ],
+};
+
+/** `journal` — the reading face is Lora (warm, personal); display keeps Gabarito. */
+export const JOURNAL_THEME_ASSETS: ThemeAssetDeclarations = {
+  fonts: [
+    ...DEFAULT_THEME_ASSETS.fonts!,
+    F('Lora', 'lora-latin-400-normal.woff2', '400'),
+    F('Lora', 'lora-latin-500-normal.woff2', '500'),
+    F('Lora', 'lora-latin-600-normal.woff2', '600'),
+    F('Lora', 'lora-latin-700-normal.woff2', '700'),
+  ],
+};
+
+/** The declaration set a theme mints — default/editorial share the engine set. */
+export function themeAssetsFor(theme: string): ThemeAssetDeclarations {
+  if (theme === 'archive') return ARCHIVE_THEME_ASSETS;
+  if (theme === 'journal') return JOURNAL_THEME_ASSETS;
+  return DEFAULT_THEME_ASSETS;
+}

package/src/data/themes.ts

@@ -1,6 +1,10 @@
 // The theme catalogue for the theme menu (id → label + swatch gradient). Data,
 // not components — kept out of the chrome components per the Fast-Refresh rule.
 //
+// R3-310: the catalogue is four shippable looks; the three showcase skins
+// (pixies/family/lotr — drawn for a fictional handbook, reading as costumes) are
+// retired. archive/journal/editorial are keyed to uses a real corpus has.
+//
 // R3-308: every theme declares BOTH polarities (its CSS block pair) and a
 // `preferred` one — the polarity a wiki opens in when neither the reader nor the
 // host has said otherwise (02-theme-contract §4). The catalogue ids must match
@@ -23,19 +27,24 @@ export const THEMES: Theme[] = [
     swatch: 'linear-gradient(96deg,#f6f1fb,#f49ad4 46%,#b285f2)',
     preferred: 'dark',
   },
-  { id: 'pixies', label: 'Pixies', swatch: 'linear-gradient(96deg,#ffe14d,#ff2d8e 50%,#9d29ff)', preferred: 'dark' },
   {
-    id: 'family',
-    label: 'Family journal',
-    swatch: 'linear-gradient(96deg,#f3cf9a,#e09a6a 50%,#c8744f)',
+    id: 'archive',
+    label: 'Archive',
+    swatch: 'linear-gradient(96deg,#b89a56,#7a5c20 55%,#3f5a63)',
     preferred: 'light',
   },
   {
-    id: 'lotr',
-    label: 'Middle-earth',
-    swatch: 'linear-gradient(96deg,#b89a56,#8a6a36 50%,#4a5a38)',
+    id: 'journal',
+    label: 'Journal',
+    swatch: 'linear-gradient(96deg,#e8c9a0,#c08552 50%,#a25a3c)',
     preferred: 'light',
   },
+  {
+    id: 'editorial',
+    label: 'Editorial',
+    swatch: 'linear-gradient(96deg,#ffd64f,#ff4d2e 55%,#37d4a8)',
+    preferred: 'dark',
+  },
 ];
 
 /** The preferred polarity of a palette id — unknown ids fall back to dark, the

package/src/hooks/{useCorpusMetadata.ts → useBundleMetadata.ts}

@@ -1,9 +1,9 @@
-// The dispatched corpus's frontmatter index (R3-265).
+// The dispatched bundle's frontmatter index (R3-265).
 //
 // A FORK gets its index from the bundler and this hook does nothing. A DISPATCHED viewer
-// has to build it: the corpus is a mount the bundler never scanned, so without this the
+// has to build it: the bundle is a mount the bundler never scanned, so without this the
 // wiki renders with empty nav, empty sidebar, no search, no backlinks and no routing —
-// silently, because an absent index is indistinguishable from an empty corpus.
+// silently, because an absent index is indistinguishable from an empty bundle.
 //
 // The scan runs ONCE per root and the result is handed to `TinkerableContext.filesMetadata`,
 // which is where `useMetadataQuery` / `useFileMetadata` / `useAllMetadata` already read
@@ -13,21 +13,21 @@ import { useEffect, useState } from 'react';
 import fs from 'fs';
 import { scanCorpus, type CorpusMetadata, type ScanFs } from '../lib/corpusScan';
 
-export interface CorpusIndex {
+export interface BundleIndex {
   /** `idle` — a fork, nothing to scan · `scanning` — hold the render · `ready` — use it. */
   status: 'idle' | 'scanning' | 'ready';
   metadata: CorpusMetadata | null;
 }
 
 /** Scan `root`, or do nothing when it is null (the fork packaging). */
-export function useCorpusMetadata(root: string | null): CorpusIndex {
+export function useBundleMetadata(root: string | null): BundleIndex {
   const [index, setIndex] = useState<{ root: string; metadata: CorpusMetadata } | null>(null);
 
   useEffect(() => {
     if (!root || index?.root === root) return;
     let cancelled = false;
     void scanCorpus(root, fs.promises as unknown as ScanFs).then((metadata) => {
-      // A corpus that resolves to nothing is still a result: `ready` with an empty map
+      // A bundle that resolves to nothing is still a result: `ready` with an empty map
       // renders the 404 index, which tells the reader the folder has no entries. Staying
       // in `scanning` forever would show a spinner and say nothing.
       if (!cancelled) setIndex({ root, metadata });

package/src/hooks/useContentComponents.ts

@@ -96,7 +96,7 @@ async function loadDeclared(root: string): Promise<Omit<ContentComponents, 'stat
  * Returns `loading` until every declaration has resolved, so the caller can hold the
  * content paint. That is the §2 invariant — compose the complete provider before content
  * paints, never render into a partial one — and it costs nothing here because Grove
- * already gates on `useOpenWikiBoot` and `useCorpusMetadata`. Rendering into a
+ * already gates on `useOpenWikiBoot` and `useBundleMetadata`. Rendering into a
  * half-composed provider would flash a missing-component error for `<RoadmapBoard>` until
  * registration landed, which is exactly the error this path removes.
  */

package/src/hooks/useEditAffordance.ts

@@ -21,7 +21,11 @@ export interface EditAffordance {
   writable: boolean;
   /** True while an editor is being summoned (for a busy label). */
   busy: boolean;
-  /** Open `entryKey` in the platform editor. Never throws; a refusal is a no-op. */
+  /** True when the host REFUSED the last edit request — callers render it as
+   *  text where the affordance was offered (3.3.1 / 4.1.3, R3-608). A
+   *  `cancelled` rejection (the reader closed the editor) never sets this. */
+  refused: boolean;
+  /** Open `entryKey` in the platform editor. Never throws; a refusal is reported. */
   openEditor: (entryKey: string) => void;
   /**
    * What a save actually does, so the affordance can say so.
@@ -41,6 +45,7 @@ export interface EditAffordance {
 export function useEditAffordance(readOnly: boolean): EditAffordance {
   const mounts = useMounts();
   const [busy, setBusy] = useState(false);
+  const [refused, setRefused] = useState(false);
 
   // Read the corpus identity through the mount list's identity, so the memo re-runs when
   // the host re-announces a mount. The root itself is latched at boot (see `contentRoot`);
@@ -53,16 +58,24 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
 
   const writable = !readOnly && corpusWritable(mounts, corpus);
 
+  // A refusal surfaces where the affordance was offered (3.3.1, R3-608);
+  // `cancelled` — the reader closing the editor — stays silent by contract.
+  const refusedUnlessCancelled = (e: unknown): undefined => {
+    if ((e as { code?: string } | null)?.code !== 'cancelled') setRefused(true);
+    return undefined;
+  };
+
   const openEditor = useCallback(
     (entryKey: string) => {
       const target = editTarget(entryKey, corpus);
       if (!target) return;
       setBusy(true);
+      setRefused(false);
       const done = () => setBusy(false);
       if (target.via === 'self') {
         // The fork: the present→edit transition on our own source. Self-scoped by
         // contract, which is exactly right when the corpus IS our repo.
-        requestEdit({ path: target.path }).catch(() => undefined).finally(done);
+        requestEdit({ path: target.path }).catch(refusedUnlessCancelled).finally(done);
         return;
       }
       // Dispatch: attenuate the corpus delegation down to this one file and hand it to
@@ -72,7 +85,7 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
       invokeTask('edit-file', {
         file: capFile({ mountId: target.mountId, relPath: target.relPath }, { mode: 'rw' }),
       })
-        .catch(() => undefined) // `cancelled` is how a reader closes the editor
+        .catch(refusedUnlessCancelled) // `cancelled` is how a reader closes the editor
         .finally(done);
     },
     [corpus],
@@ -82,5 +95,5 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
     ? 'Edits save to the mounted content. Proposing a change back to its repository is not wired yet.'
     : 'Edit this entry';
 
-  return { writable, busy, openEditor, editHint };
+  return { writable, busy, refused, openEditor, editHint };
 }

package/src/hooks/useOverlayFocusDismiss.test.tsx

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+// useOverlayFocusDismiss (R3-608): the dialog contract AND the stack — one
+// Escape closes only the TOP overlay; after it closes, the next.
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { useOverlayFocusDismiss } from './useOverlayFocusDismiss';
+
+function Overlay({ name, onClose }: { name: string; onClose: () => void }) {
+  const ref = useOverlayFocusDismiss(true, onClose);
+  return (
+    <div data-testid={name} ref={ref} tabIndex={-1}>
+      <button>{name} first</button>
+      <button>{name} last</button>
+    </div>
+  );
+}
+
+/** One open overlay with a real trigger — the contract's basics. */
+function Single({ onClose }: { onClose: () => void }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div>
+      <button
+        onClick={(e) => {
+          setOpen(true);
+          void e;
+        }}
+      >
+        open
+      </button>
+      {open ? (
+        <Overlay
+          name="one"
+          onClose={() => {
+            setOpen(false);
+            onClose();
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/** Two stacked overlays (a below, b above) — the stack discipline. */
+function Stacked({ aClose, bClose }: { aClose: () => void; bClose: () => void }) {
+  const [a, setA] = useState(true);
+  const [b, setB] = useState(true);
+  return (
+    <div>
+      {a ? (
+        <Overlay
+          name="a"
+          onClose={() => {
+            setA(false);
+            aClose();
+          }}
+        />
+      ) : null}
+      {b ? (
+        <Overlay
+          name="b"
+          onClose={() => {
+            setB(false);
+            bClose();
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+async function mount(ui: React.ReactNode): Promise<{ root: Root; container: HTMLElement }> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(ui);
+  });
+  return { root, container };
+}
+
+const esc = async (): Promise<void> => {
+  await act(async () => {
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }));
+  });
+};
+
+describe('useOverlayFocusDismiss (R3-608)', () => {
+  it('focus moves IN on open and RETURNS to the trigger on Escape-close', async () => {
+    const close = vi.fn();
+    const { container } = await mount(<Single onClose={close} />);
+    const trigger = container.querySelector('button') as HTMLButtonElement;
+    trigger.focus();
+    expect(document.activeElement).toBe(trigger);
+    await act(async () => {
+      trigger.click();
+    });
+    // Focus moved IN — to the overlay's first control.
+    expect(document.activeElement?.textContent).toBe('one first');
+    await esc();
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(container.querySelector('[data-testid="one"]')).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it('Tab is trapped at the overlay edges', async () => {
+    const close = vi.fn();
+    const { container } = await mount(<Single onClose={close} />);
+    const trigger = container.querySelector('button') as HTMLButtonElement;
+    trigger.focus();
+    await act(async () => {
+      trigger.click();
+    });
+    const buttons = [...container.querySelectorAll('[data-testid="one"] button')] as HTMLButtonElement[];
+    buttons[1].focus();
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true, cancelable: true }));
+    });
+    expect(document.activeElement).toBe(buttons[0]); // wrapped forward→first
+  });
+
+  it('one Escape closes only the TOP overlay; the next closes the one below', async () => {
+    const aClose = vi.fn();
+    const bClose = vi.fn();
+    const { container } = await mount(<Stacked aClose={aClose} bClose={bClose} />);
+    expect(container.querySelector('[data-testid="a"]')).toBeTruthy();
+    expect(container.querySelector('[data-testid="b"]')).toBeTruthy();
+    await esc();
+    expect(bClose).toHaveBeenCalledTimes(1);
+    expect(aClose).not.toHaveBeenCalled();
+    expect(container.querySelector('[data-testid="b"]')).toBeNull();
+    expect(container.querySelector('[data-testid="a"]')).toBeTruthy();
+    await esc();
+    expect(aClose).toHaveBeenCalledTimes(1);
+    expect(container.querySelector('[data-testid="a"]')).toBeNull();
+  });
+});

package/src/hooks/useOverlayFocusDismiss.ts

@@ -0,0 +1,118 @@
+// The dialog/menu contract for Grove's overlays (R3-608, R-IX-1): focus moves
+// IN on open, Tab is trapped while open (unless the surface is a menu — menus
+// do not trap Tab), Escape closes only the TOP of a module-level stack, and
+// focus RETURNS to the element that opened the overlay. The stack exists
+// because the surfaces overlap (GroveNav's own comment names drawer, search
+// and theme menu as shared interactive state): one Escape closes one overlay.
+
+import { useEffect, useRef } from 'react';
+
+/** Elements that can hold focus inside the overlay. */
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/** The open-overlay stack, newest last. Only the top entry answers Escape —
+ *  a nested pair closes one per key, never both at once. */
+const stack: { close: () => void }[] = [];
+
+interface OverlayFocusDismissOptions {
+  /** Menus do not trap Tab (the APG menu pattern keeps Tab as leave); dialogs
+   *  do. Default true. */
+  trapTab?: boolean;
+}
+
+/**
+ * Wire the contract to an overlay root. Attach the returned ref to the element
+ * that bounds the overlay (its panel/menu box).
+ *
+ * @param open    the overlay's open state — the effect arms on true and cleans
+ *                up (returning focus) on false/unmount.
+ * @param onClose Escape's meaning: close without committing.
+ */
+export function useOverlayFocusDismiss(
+  open: boolean,
+  onClose: () => void,
+  opts: OverlayFocusDismissOptions = {},
+) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  // The latest close callback, kept current in an effect (never a render-time
+  // ref write — the react-hooks compiler forbids it, correctly).
+  const onCloseRef = useRef(onClose);
+  useEffect(() => {
+    onCloseRef.current = onClose;
+  });
+  const trapTab = opts.trapTab !== false;
+
+  useEffect(() => {
+    if (!open) return;
+    // The trigger to return to, captured BEFORE focus moves in.
+    const trigger = document.activeElement as HTMLElement | null;
+    const entry = {
+      close: () => onCloseRef.current(),
+    };
+    stack.push(entry);
+    // Set when a MENU surface closes because Tab left it: the browser's own
+    // focus move must stand (APG Menu Button), so the cleanup below must NOT
+    // yank focus back to the trigger.
+    let closedViaTab = false;
+    const root = rootRef.current;
+    const focusables = root ? [...root.querySelectorAll<HTMLElement>(FOCUSABLE)] : [];
+    // Focus IN: the first control; a panel with no focusable content takes
+    // focus itself so Escape has a home.
+    (focusables[0] ?? root)?.focus();
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      const isTop = stack[stack.length - 1] === entry;
+      if (e.key === 'Escape') {
+        if (!isTop) return; // a nested overlay above owns this key
+        e.preventDefault();
+        e.stopPropagation();
+        onCloseRef.current();
+        return;
+      }
+      if (!trapTab && e.key === 'Tab') {
+        // APG Menu: Tab is LEAVE — the focus move proceeds (no preventDefault)
+        // and the menu closes behind it, never stranded over a scrim. The
+        // flag keeps the cleanup from pulling focus back to the trigger: the
+        // move the browser just made is the contract.
+        if (isTop) {
+          closedViaTab = true;
+          onCloseRef.current();
+        }
+        return;
+      }
+      if (!trapTab || e.key !== 'Tab' || !root) return;
+      const list = [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((el) => !el.hasAttribute('disabled'));
+      if (!list.length) {
+        e.preventDefault();
+        return;
+      }
+      const first = list[0];
+      const last = list[list.length - 1];
+      const active = document.activeElement;
+      if (!root.contains(active)) {
+        e.preventDefault();
+        first.focus();
+      } else if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    // Capture phase: the contract runs before any app-level key handling.
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown, true);
+      const i = stack.indexOf(entry);
+      if (i >= 0) stack.splice(i, 1);
+      // Focus RETURNS to the trigger (R-IX-1) — unless the menu closed BECAUSE
+      // Tab left it: that move is the contract and stands. Guarded: the
+      // trigger may be gone.
+      if (!closedViaTab && trigger && document.contains(trigger)) trigger.focus();
+    };
+  }, [open, trapTab]);
+
+  return rootRef;
+}