@immediately-run/grove 0.1.10 → 0.2.2

package/src/components/navigationPolicy.sweep.test.tsx

@@ -0,0 +1,261 @@
+// @vitest-environment jsdom
+// G-CUST-3 (APP_CUSTOMIZATION_SPEC §4.3, R3-872) — the sweep: EVERY component under
+// src/components/ that renders the SDK `<Link>` (or calls `navigate(`) is
+// enumerated FROM DISK (never a hand-list — a new component that skips the policy
+// fails this suite on arrival), rendered with a recording policy over a real
+// corpus entry, and plain-clicked: the policy must receive the resolved target
+// `{ key, href, fragment?, from? }` and the browser default must be prevented.
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { ReactNode } from 'react';
+// The enumeration reads the components directory through a DIRECT require of
+// node:fs (createRequire), not the test graph's `fs` — the file mocks `fs` for
+// the components under test, and the enumeration must not eat its own mock.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+const { readFileSync, readdirSync } = createRequire(import.meta.url)('node:fs') as typeof import('node:fs');
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { GroveShellContext, type GroveShell } from '../lib/shell';
+import { NavigationPolicyContext, type FollowLinkTarget } from '../lib/navigationPolicy';
+import { keyToHref } from '../lib/content';
+import { setContentRoot } from '../lib/contentRoot';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (q: string) => ({ matches: false, media: q, addEventListener: () => {}, removeEventListener: () => {}, addListener: () => {}, removeListener: () => {}, dispatchEvent: () => false, onchange: null }),
+  });
+  setContentRoot('/app/content/');
+});
+
+// ── The corpus fixture (a real two-entry shape) ──────────────────────────────
+const ENTRY = '/app/content/wiki/a.mdx';
+const OTHER = '/app/content/wiki/b.mdx';
+const PERSON = '/app/content/people/ada.mdx';
+const INDEX = '/app/content/wiki/index.mdx';
+const WIKI_C = '/app/content/wiki/c.mdx';
+const META: Record<string, Record<string, unknown>> = {
+  [ENTRY]: { title: 'Reference entry.', render: 'safe', date: '2026-06-22' },
+  [INDEX]: { title: 'The wiki index.', render: 'safe' },
+  [WIKI_C]: { title: 'A third entry.', render: 'safe' },
+  [OTHER]: { title: 'The other entry.', render: 'safe', date: '2026-06-22' },
+  [PERSON]: { name: 'Ada', role: 'eng', team: 'core', phone: '555-1', email: 'a@b.c' },
+  '/app/content/home.mdx': { title: 'Home', render: 'safe' },
+};
+
+const { readFile, readdirFs } = vi.hoisted(() => ({ readFile: vi.fn(), readdirFs: vi.fn() }));
+vi.mock('fs', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...actual,
+    default: {
+      ...(actual.default as Record<string, unknown>),
+      promises: {
+        ...((actual.default as { promises: Record<string, unknown> }).promises),
+        readFile: (...a: unknown[]) => readFile(...(a as [])),
+        readdir: (...a: unknown[]) => readdirFs(...(a as [])),
+      },
+    },
+  };
+});
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...(a as [])) },
+};
+
+const NAV = {
+  mode: 'github',
+  namespace: 'immediately-run',
+  provider: 'github',
+  repository: 'corpus',
+  ref: 'main',
+  sandboxPath: ENTRY,
+  hash: '',
+  search: '',
+};
+
+/** The shell slice the chrome components read (DirectoryView/PageView read the page
+ *  states; GroveNav/Footer read nav; every entry link's `from` reads the route key). */
+const shell: GroveShell = {
+  siteTitle: 'Fixture',
+  navItems: [{ key: OTHER, href: keyToHref(OTHER), label: 'The other entry.' }],
+  entryKey: ENTRY,
+  vw: 'desktop',
+  navMode: 'top',
+  writable: false,
+  openEditor: () => {},
+  editBusy: false,
+  editRefused: false,
+  editHint: '',
+  directory: { status: 'none' },
+  missing: true,
+  suggestion: OTHER,
+  mins: 0,
+  safe: true,
+  includePath: ENTRY,
+  layout: 'doc',
+  showRails: false,
+} as unknown as GroveShell;
+
+// ── The disk enumeration (G-CUST-3's "never a hand-list") ────────────────────
+const COMPONENTS_DIR = join(__dirname);
+const linkComponents = readdirSync(COMPONENTS_DIR)
+  .filter((f) => f.endsWith('.tsx') && !f.includes('.test.'))
+  .filter((f) => /<Link\b|navigate\(/.test(readFileSync(join(COMPONENTS_DIR, f), 'utf8')))
+  .map((f) => f.replace(/\.tsx$/, ''));
+
+// Per-component minimal render context (props, and a sandboxPath when the
+// component's content depends on which entry it renders inside).
+const FIXTURES: Record<string, { props?: Record<string, unknown>; sandboxPath?: string }> = {
+  WikiLink: { props: { href: '/wiki/b.mdx#sec-4', children: 'the other' } },
+  Search: { props: { onClose: () => {} } },
+  Drawer: { props: { siteTitle: 'Fixture', nav: [{ key: OTHER, href: keyToHref(OTHER), label: 'Other', cur: false }], onClose: () => {} } },
+  // ChildPages lists the current entry's INDEX siblings — the current entry must
+  // be the namespace's index for the listing to have rows.
+  ChildPages: { sandboxPath: '/app/content/wiki/index.mdx' },
+  // DirectoryList reads the current entry's folder — the readdir mock answers it
+  // (see beforeEach), and the rows link to entries the index knows.
+  DirectoryList: { sandboxPath: '/app/content/wiki/index.mdx' },
+};
+
+// ── Harness ──────────────────────────────────────────────────────────────────
+
+function Harness({ children, record, sandboxPath }: { children: ReactNode; record: (t: FollowLinkTarget) => void; sandboxPath?: string }) {
+  return (
+    <TinkerableContext.Provider
+      value={{
+        outerHref: 'https://immediately.run/x',
+        navigationState: { ...NAV, sandboxPath: sandboxPath ?? NAV.sandboxPath },
+        routingSpec: { routes: [] } as never,
+        filesMetadata: META,
+      } as never}
+    >
+      <GroveShellContext.Provider value={shell}>
+        <NavigationPolicyContext.Provider value={record}>{children}</NavigationPolicyContext.Provider>
+      </GroveShellContext.Provider>
+    </TinkerableContext.Provider>
+  );
+}
+
+/** Render once and read the anchor hrefs on screen (each href re-rendered + clicked
+ *  on its own mount — overlay components unmount after their first click). */
+async function renderAndClickAll(
+  name: string,
+  build: () => ReactNode,
+): Promise<{ perHref: Array<{ href: string; calls: FollowLinkTarget[]; prevented: boolean }> }> {
+  // first pass: which hrefs does it render?
+  const probe = document.createElement('div');
+  document.body.appendChild(probe);
+  const probeRoot: Root = createRoot(probe);
+  await act(async () => {
+    probeRoot.render(<Harness record={() => {}} sandboxPath={FIXTURES[name]?.sandboxPath}>{build()}</Harness>);
+  });
+  for (let i = 0; i < 8; i++) await act(async () => {});
+  // Every anchor OCCURRENCE, not every distinct href (round 2 nit): a second
+  // same-href anchor reverted to direct navigation must fail too.
+  const hrefs = [...probe.querySelectorAll('a[href]')].map((a) => a.getAttribute('href')!);
+  expect(hrefs.length, `${name} renders at least one link`).toBeGreaterThan(0);
+  await act(async () => {
+    probeRoot.unmount();
+  });
+  probe.remove();
+
+  const perHref: Array<{ href: string; calls: FollowLinkTarget[]; prevented: boolean }> = [];
+  for (let occurrence = 0; occurrence < hrefs.length; occurrence++) {
+    const href = hrefs[occurrence];
+    const ordinal = hrefs.slice(0, occurrence).filter((h) => h === href).length;
+    const calls: FollowLinkTarget[] = [];
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root: Root = createRoot(container);
+    await act(async () => {
+      root.render(
+        <Harness
+          record={(t) => {
+            calls.push(t);
+          }}
+          sandboxPath={FIXTURES[name]?.sandboxPath}
+        >
+          {build()}
+        </Harness>,
+      );
+    });
+    for (let i = 0; i < 8; i++) await act(async () => {});
+    const anchor = container.querySelectorAll(`a[href="${href.replace(/"/g, '\\"')}"]`)[ordinal];
+    expect(anchor, `${name}: the ${href} link still renders`).toBeTruthy();
+    let prevented = false;
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 });
+    const origPrevent = event.preventDefault.bind(event);
+    event.preventDefault = () => {
+      prevented = true;
+      origPrevent();
+    };
+    await act(async () => {
+      anchor!.dispatchEvent(event);
+    });
+    await act(async () => {
+      root.unmount();
+    });
+    container.remove();
+    perHref.push({ href, calls, prevented });
+  }
+  return { perHref };
+}
+
+beforeEach(() => {
+  readFile.mockReset();
+  readFile.mockImplementation(async (p: unknown) =>
+    // Backlinks scans bodies for links TO the rendered entry: b's body links a.
+    String(p).endsWith('/b.mdx')
+      ? '---\ntitle: B\nrender: safe\n---\n\n[the first](/wiki/a.mdx)\n'
+      : '---\ntitle: T\nrender: safe\n---\n\nplain body\n',
+  );
+  readdirFs.mockReset();
+  const dirent = (name: string, isDir = false) => ({ name, isDirectory: () => isDir });
+  readdirFs.mockImplementation(async () => [dirent('c.mdx'), dirent('assets', true)]);
+  void readdirFs;
+});
+
+describe('G-CUST-3 — every entry link rides the navigation policy', () => {
+  it('the enumeration covers the known link components (non-vacuity)', () => {
+    for (const name of ['WikiLink', 'Backlinks', 'ChildPages', 'Directory', 'DirectoryList', 'DirectoryView', 'DocList', 'Drawer', 'GroveFooter', 'GroveNav', 'PageView', 'Search', 'Sidebar', 'Timeline']) {
+      expect(linkComponents, `${name} is enumerated`).toContain(name);
+    }
+  });
+
+  it.each(linkComponents)('%s: a plain click reaches the policy with a resolved target', async (name) => {
+    const mod = await import(`./${name}`);
+    const Component = mod.default;
+    const props = FIXTURES[name]?.props ?? {};
+    // EVERY anchor the component renders, each clicked on its own mount (an
+    // overlay's first click closes it) — the item's do-not carve-out is a second
+    // link navigating directly 'because it's chrome', and only probing the first
+    // anchor would miss exactly that.
+    const { perHref } = await renderAndClickAll(name, () => <Component {...props} />);
+    for (const { href, calls, prevented } of perHref) {
+      expect(calls.length, `${name}: the plain click on ${href} reaches the policy`).toBeGreaterThan(0);
+      const t = calls[0];
+      expect(typeof t.href, 'the target carries the concrete href').toBe('string');
+      expect(t.href.length).toBeGreaterThan(0);
+      // the DOM anchor carries the SDK's outer-URL resolution of the href the
+      // component passed; the policy receives the component-level one
+      expect(href === t.href || href.endsWith(t.href), `${name}: the DOM href ${href} resolves the policy's ${t.href}`).toBe(true);
+      expect(typeof t.key, 'the target carries the resolved key').toBe('string');
+      expect(t.key.length).toBeGreaterThan(0);
+      // §4.3's shape: fragment is absent or a bare id, never '#'-prefixed
+      if (t.fragment !== undefined) expect(t.fragment.startsWith('#'), `fragment carries no '#' (${t.fragment})`).toBe(false);
+      // `from` is the entry key when the link renders inside one (content
+      // components), absent for the chrome (nav/footer/drawer/sidebar render
+      // outside an entry) — the shape pinned, not the value guessed.
+      if (t.from !== undefined) expect(typeof t.from).toBe('string');
+      // the WikiLink fixture is fragment-bearing: the rendered href KEEPS the
+      // '#sec-4' (round 2's regression — the '#' strip corrupted hrefs), and the
+      // policy's fragment is the bare id
+      if (name === 'WikiLink') {
+        expect(href).toContain('#sec-4');
+        expect(t.fragment).toBe('sec-4');
+      }
+      expect(prevented, `${name}: the plain click on ${href} prevents the browser default`).toBe(true);
+    }
+  });
+});

package/src/hooks/useEditAffordance.test.tsx

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+// R3-877 — the workbench delivery of the edit affordance for a read-only opener
+// delegation: `requestEdit({ bundleFile })`, with the refusal contract pinned:
+// `read-only` hides the affordance until the next mount announcement, `cancelled`
+// stays silent, `forbidden` (and anything else) sets `refused`.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act, useEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+import type { EditAffordance } from './useEditAffordance';
+
+const requestEditMock = vi.fn<(t?: unknown) => Promise<void>>();
+const invokeTaskMock = vi.fn<(a: unknown) => Promise<void>>();
+const useMountsMock = vi.fn<() => unknown[]>();
+
+vi.mock('@immediately-run/sdk', () => ({
+  requestEdit: (a?: unknown) => requestEditMock(a),
+  invokeTask: (a: unknown) => invokeTaskMock(a),
+  capFile: (ref: unknown, opts: unknown) => ({ ...(ref as object), ...(opts as object) }),
+  useMounts: () => useMountsMock(),
+}));
+
+// The corpus identity comes from the real contentRoot module, driven through its
+// own producer (R3-877 round 1, R2) — never a hand-typed shape.
+import { getContentRoot, resetContentRoot, setContentRoot } from '../lib/contentRoot';
+
+import { useEditAffordance } from './useEditAffordance';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const RO_MOUNT = { type: 'task-delegation', path: '/task/t1/dir', id: '/task/t1/dir', mode: 'ro', readerCanEdit: true };
+
+let latest: EditAffordance | null = null;
+function Probe() {
+  const affordance = useEditAffordance(false);
+  useEffect(() => {
+    latest = affordance;
+  });
+  return null;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  setContentRoot('/task/t1/dir', { mountId: '/task/t1/dir' });
+  requestEditMock.mockReset().mockResolvedValue(undefined);
+  invokeTaskMock.mockReset().mockResolvedValue(undefined);
+  useMountsMock.mockReset().mockReturnValue([RO_MOUNT]);
+  latest = null;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => root.render(<Probe />));
+});
+
+const rerender = () => act(() => root.render(<Probe />));
+
+afterEach(() => {
+  resetContentRoot();
+  act(() => root.unmount());
+  container.remove();
+});
+const open = async (key = `${getContentRoot()}plot/the-rail.mdx`) => {
+  await act(async () => {
+    latest!.openEditor(key);
+    await Promise.resolve();
+  });
+  rerender();
+};
+
+describe('useEditAffordance — the workbench delivery (R3-877)', () => {
+  it('an ro delegation offers Edit and delivers it as requestEdit({ bundleFile })', async () => {
+    expect(latest!.writable).toBe(true);
+    await open();
+    expect(requestEditMock).toHaveBeenCalledWith({ bundleFile: '/plot/the-rail.mdx' });
+    expect(invokeTaskMock).not.toHaveBeenCalled();
+    expect(latest!.refused).toBe(false);
+  });
+
+  it('an ro delegation with `readerCanEdit: false` does not offer the control', () => {
+    useMountsMock.mockReturnValue([{ ...RO_MOUNT, readerCanEdit: false }]);
+    rerender();
+    expect(latest!.writable).toBe(false);
+  });
+
+  it('a `read-only` refusal hides the affordance until the next mount announcement', async () => {
+    requestEditMock.mockRejectedValue(Object.assign(new Error('no'), { code: 'read-only' }));
+    await open();
+    expect(latest!.refused).toBe(false); // not a render-in-place refusal
+    expect(latest!.writable).toBe(false); // hidden…
+    useMountsMock.mockReturnValue([{ ...RO_MOUNT }]); // …until the next announcement…
+    rerender();
+    expect(latest!.writable).toBe(true); // …unlatches it.
+  });
+
+  it('a `cancelled` rejection stays silent (the reader closed the editor)', async () => {
+    requestEditMock.mockRejectedValue(Object.assign(new Error('closed'), { code: 'cancelled' }));
+    await open();
+    expect(latest!.refused).toBe(false);
+    expect(latest!.writable).toBe(true);
+  });
+
+  it('a `forbidden` refusal sets `refused` (rendered as text in place) and never retries via edit-file', async () => {
+    requestEditMock.mockRejectedValue(Object.assign(new Error('no'), { code: 'forbidden' }));
+    await open();
+    expect(latest!.refused).toBe(true);
+    expect(invokeTaskMock).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useEditAffordance.ts

@@ -7,9 +7,11 @@
 // 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
+// The decision is pure (`lib/editTarget`); this hook is the wiring: it reads the live
+// mount list so a role downgrade reroutes the delivery on the next render (rw → the
+// `edit-file` overlay; ro → the workbench under the reader's authority, R3-877) rather
+// than producing `EROFS` on click — and a `readerCanEdit: false` hint or a `read-only`
+// refusal hides the offer — 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';
@@ -46,14 +48,28 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
 
   // 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],
-  );
+  // the MODE is not, and that is the half this hook exists to keep current. R3-877: the
+  // delegation's live MODE now also routes the delivery (rw → the edit-file overlay,
+  // ro → the workbench under the reader's authority).
+  const corpus = useMemo(() => {
+    const mountId = getCorpusMountId();
+    const mount = mounts?.find((m) => (m.id ?? m.path) === mountId);
+    return { dispatched: isDispatched(), contentRoot: getContentRoot(), mountId, mountMode: mount?.mode ?? null };
+  }, [mounts]);
+
+  // R3-877: a `read-only` refusal (the reader cannot edit the source) hides the
+  // affordance until the next mount announcement — the hint's re-announcement is
+  // exactly what unlatches it. Reset on every mount-list change — the
+  // render-adjusted-state pattern (not an effect, which would paint one frame
+  // stale), the React-sanctioned form.
+  const [readerReadOnly, setReaderReadOnly] = useState(false);
+  const [resetFor, setResetFor] = useState(mounts);
+  if (resetFor !== mounts) {
+    setResetFor(mounts);
+    setReaderReadOnly(false);
+  }
 
-  const writable = !readOnly && corpusWritable(mounts, corpus);
+  const writable = !readOnly && !readerReadOnly && 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.
@@ -75,10 +91,31 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
         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.
+      // Dispatch, read-only delegation: ask the workbench to open the entry's source
+      // under the reader's authority (R3-876 / APP_CUSTOMIZATION §5a). Our chroot is
+      // never upgraded and nothing is minted for us; the host needs a real gesture,
+      // which this click is. `cancelled` stays silent; `read-only` hides the
+      // affordance until the next mount announcement; anything else renders in place
+      // as text (the `refused` flag) — and is never retried through `edit-file`.
+      if (target.via === 'workbench') {
+        requestEdit({ bundleFile: target.relPath })
+          .catch((e: unknown) => {
+            const code = (e as { code?: string } | null)?.code;
+            if (code === 'cancelled') return;
+            if (code === 'read-only') {
+              setReaderReadOnly(true);
+              return;
+            }
+            setRefused(true);
+          })
+          .finally(done);
+        return;
+      }
+      // Dispatch, writable delegation: 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' }),
       })

package/src/hooks/useEntryKey.ts

@@ -0,0 +1,21 @@
+// useEntryKey — "which entry am I rendered inside?" (R3-871).
+//
+// The one place the URL→key expression survives (R6): every component that
+// needs the current entry reads this hook, so an included fragment or a
+// layout resolves relative links against the entry it renders, not whatever
+// the address bar happens to say. Falls back to the routed key when no
+// provider is present — the default-preserving seam of APP_CUSTOMIZATION §3
+// (R-CUST-2/3). Internal for now; R3-872 exports it with the other seams.
+import { useContext } from 'react';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { entryKeyOr, EntryContext } from '../lib/entryContext';
+
+export { EntryContext };
+
+/** The metadata key of the entry this subtree renders (the routed key when
+ *  no provider is present). */
+export function useEntryKey(): string {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ctx = useContext(TinkerableContext) as any;
+  return entryKeyOr(useContext(EntryContext), ctx?.navigationState?.sandboxPath || '/');
+}

package/src/hooks/useFollowLink.ts

@@ -0,0 +1,11 @@
+// `useFollowLink` — read the active navigation policy (APP_CUSTOMIZATION §4.3,
+// R3-872). The hook lives in its own file per the repo's one-hook-per-file
+// convention; the context + the stock default live in `lib/navigationPolicy.ts`
+// (no components there — the Fast-Refresh rule).
+import { useContext } from 'react';
+import { NavigationPolicyContext, type FollowLink } from '../lib/navigationPolicy';
+
+/** The active navigation policy — the provider's, or the stock `navigate(href)`. */
+export function useFollowLink(): FollowLink {
+  return useContext(NavigationPolicyContext);
+}

package/src/hooks/useHeadings.test.tsx

@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+// R3-872 (APP_CUSTOMIZATION §4.5) — the scoped branch of useHeadings, the one
+// that shipped broken at the first review (the marker sits INSIDE .grove-prose,
+// so a scoped `.grove-prose` lookup found nothing). These cases plant MARKED
+// bodies — the shape the stock DOM always has — and assert the scoped read.
+import { describe, it, expect, beforeAll } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { useHeadings } from './useHeadings';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (q: string) => ({ matches: false, media: q, addEventListener: () => {}, removeEventListener: () => {}, addListener: () => {}, removeListener: () => {}, dispatchEvent: () => false, onchange: null }),
+  });
+});
+
+const A = '/app/content/specs/a.mdx';
+const B = '/app/content/specs/b.mdx';
+
+/** Two marked bodies, each with its own headings — the multi-entry page shape
+ *  (both paths carry the marker since R3-872, and the safe path's marker wraps
+ *  the body inside .grove-prose, as EntryBody renders it). */
+function plantTwoBodies() {
+  // A carries one ID-LESS heading (the kernel assigns none sometimes) — B's scan
+  // must never write an id onto it (the side effect is scoped, not just the read).
+  document.body.innerHTML = `
+    <div class="grove-prose"><div data-entry="${A}"><h2 id="sec-1">A one</h2><h2>A two (no id)</h2></div></div>
+    <div class="grove-prose"><div data-entry="${B}"><h2 id="sec-1">B one</h2><h3 id="sec-2-1">B two-one</h3></div></div>
+  `;
+}
+
+function Probe({ entryKey, seen }: { entryKey: string; seen: (h: { id: string }[]) => void }) {
+  const heads = useHeadings(entryKey);
+  seen(heads);
+  return null;
+}
+
+describe('useHeadings — entry-scoped (R3-872)', () => {
+  it("reads only the named entry's headings when both bodies are marked", async () => {
+    plantTwoBodies();
+    let latest: { id: string }[] = [];
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<Probe entryKey={B} seen={(h) => (latest = h)} />);
+    });
+    expect(latest.map((h) => h.id)).toEqual(['sec-1', 'sec-2-1']);
+    // the OTHER entry's id-less heading stays id-less — the scan's id-assignment
+    // side effect is scoped, not just the read
+    expect(document.querySelector(`[data-entry="${A}"] h2:nth-of-type(2)`)?.id ?? '').toBe('');
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it('a late-committing marked body is found by the document observer (no empty ToC for life)', async () => {
+    document.body.innerHTML = '';
+    let latest: { id: string }[] = [];
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<Probe entryKey={B} seen={(h) => (latest = h)} />);
+    });
+    expect(latest).toEqual([]); // no marker yet — nothing found, not a wrong read
+    // the body lands late (the compile window)
+    await act(async () => {
+      plantTwoBodies();
+    });
+    // the observer's mutation callback is async — flush it
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 20));
+    });
+    expect(latest.map((h) => h.id)).toEqual(['sec-1', 'sec-2-1']);
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it('no marked bodies anywhere → the document fallback (the pre-marker world)', async () => {
+    document.body.innerHTML = '<div class="grove-prose"><h2 id="sec-1">Only one</h2></div>';
+    let latest: { id: string }[] = [];
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<Probe entryKey={B} seen={(h) => (latest = h)} />);
+    });
+    expect(latest.map((h) => h.id)).toEqual(['sec-1']);
+    await act(async () => root.unmount());
+    container.remove();
+  });
+});