@immediately-run/grove 0.1.1 → 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,14 +1,54 @@
 // 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
+// the `[data-grove-theme="…"]` selectors in GroveApp.css; the contrast check in
+// `scripts/check-theme-contrast.mjs` reads both and fails if they drift apart.
+import type { Polarity } from '../lib/themeSelection';
+
 export interface Theme {
   id: string;
   label: string;
   swatch: string;
+  /** The polarity this theme opens in absent a reader/host opinion. */
+  preferred: Polarity;
 }
 
 export const THEMES: Theme[] = [
-  { id: 'default', label: 'immediately.run', swatch: 'linear-gradient(96deg,#f6f1fb,#f49ad4 46%,#b285f2)' },
-  { id: 'pixies', label: 'Pixies', swatch: 'linear-gradient(96deg,#ffe14d,#ff2d8e 50%,#9d29ff)' },
-  { id: 'family', label: 'Family journal', swatch: 'linear-gradient(96deg,#f3cf9a,#e09a6a 50%,#c8744f)' },
-  { id: 'lotr', label: 'Middle-earth', swatch: 'linear-gradient(96deg,#b89a56,#8a6a36 50%,#4a5a38)' },
+  {
+    id: 'default',
+    label: 'immediately.run',
+    swatch: 'linear-gradient(96deg,#f6f1fb,#f49ad4 46%,#b285f2)',
+    preferred: 'dark',
+  },
+  {
+    id: 'archive',
+    label: 'Archive',
+    swatch: 'linear-gradient(96deg,#b89a56,#7a5c20 55%,#3f5a63)',
+    preferred: 'light',
+  },
+  {
+    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
+ * long-standing Grove default, rather than throwing in a render path. */
+export function preferredPolarity(id: string): Polarity {
+  return THEMES.find((t) => t.id === id)?.preferred ?? 'dark';
+}

package/src/devfs.d.ts

@@ -1,4 +1,5 @@
-// Pull in the `fs` module types provided by @immediately-run/dev-fs, so app
-// code can `import fs from 'fs'` and type-check against the async-only surface
-// immediately.run exposes. See https://github.com/immediately-run/dev-fs
-/// <reference types="@immediately-run/dev-fs/fs" />
+// The ambient `fs` + `module` types the immediately.run SANDBOX provides to app
+// code — declared by the package that owns the surface: `@immediately-run/sdk`
+// (R3-276b moved them there from `@immediately-run/dev-fs`, whose job is the local
+// `vite dev` disk bridge, not the contract). One line, complete from sdk 0.49.0.
+/// <reference types="@immediately-run/sdk/ambient" />

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

@@ -0,0 +1,99 @@
+// R3-266 — the one place Grove decides whether to offer an edit, and how to deliver it.
+//
+// Every edit affordance in the wiki (the entry header's pencil, the 404's "Create it",
+// the agent panel's link, the nav's "New entry") used to call `requestEdit` directly with
+// a repo-relative path. That is correct for a FORK and wrong under DISPATCH, where it
+// names a path in Grove's own repo rather than in the corpus on screen — so the affordance
+// was withheld entirely and the wiki became read-only for the one packaging where the
+// content is most obviously somebody's to edit.
+//
+// The decision is pure (`lib/editTarget`); this hook is the wiring: it reads the LIVE
+// mount list so a role downgrade hides the affordance on the next render rather than
+// producing `EROFS` on click, and it hands back one `openEditor(entryKey)` the chrome
+// calls without knowing which packaging it is in.
+import { useCallback, useMemo, useState } from 'react';
+import { capFile, invokeTask, requestEdit, useMounts } from '@immediately-run/sdk';
+import { getContentRoot, getCorpusMountId, isDispatched } from '../lib/contentRoot';
+import { corpusWritable, editTarget } from '../lib/editTarget';
+
+export interface EditAffordance {
+  /** Whether to render an edit affordance at all — the MOUNT's answer, live. */
+  writable: boolean;
+  /** True while an editor is being summoned (for a busy label). */
+  busy: boolean;
+  /** 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.
+   *
+   * **A stated residual (2026-08-27, R3-266).** The CoW overlay and the contribute (PR)
+   * flow are anchored on the APP's repo. Under a fork the app and the corpus are one
+   * repo, so "save" and "propose a change" are one story. Under dispatch they are two:
+   * the write lands in the corpus mount correctly, and *"open a PR against the content
+   * repo"* has no wired target. That is real remaining work — and it is not a reason to
+   * withhold editing, because a viewer that saves but cannot yet propose is strictly
+   * better than one that refuses to save. It IS a reason not to imply otherwise, so the
+   * chrome labels the dispatched case for what it is.
+   */
+  editHint: string;
+}
+
+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`);
+  // the MODE is not, and that is the half this hook exists to keep current.
+  const corpus = useMemo(
+    () => ({ dispatched: isDispatched(), contentRoot: getContentRoot(), mountId: getCorpusMountId() }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [mounts],
+  );
+
+  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(refusedUnlessCancelled).finally(done);
+        return;
+      }
+      // Dispatch: attenuate the corpus delegation down to this one file and hand it to
+      // the platform editor. Nothing new is minted — we already hold the directory, and
+      // `edit-file` is one hop further along a chain §5.7.1 bounds at depth 4. The host
+      // resolves the cap against OUR grants, so this can only ever narrow.
+      invokeTask('edit-file', {
+        file: capFile({ mountId: target.mountId, relPath: target.relPath }, { mode: 'rw' }),
+      })
+        .catch(refusedUnlessCancelled) // `cancelled` is how a reader closes the editor
+        .finally(done);
+    },
+    [corpus],
+  );
+
+  const editHint = corpus.dispatched
+    ? 'Edits save to the mounted content. Proposing a change back to its repository is not wired yet.'
+    : 'Edit this entry';
+
+  return { writable, busy, refused, openEditor, editHint };
+}

package/src/hooks/useOpenWikiBoot.ts

@@ -44,7 +44,7 @@ export function useOpenWikiBoot(): OpenWikiBoot {
     // effect would run AFTER the first content render, which is the whole failure this
     // gate exists to prevent. Idempotent and purely derived, so a StrictMode double
     // render sets the same value twice.
-    setContentRoot(resolution.root, { readOnly: resolution.readOnly });
+    setContentRoot(resolution.root, { readOnly: resolution.readOnly, mountId: resolution.mountId });
   }
 
   // The module IS the latch: once a root is set, the delegation is final for the life of

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