@immediately-run/grove 0.1.10 → 0.2.2

package/src/hooks/useHeadings.ts

@@ -29,8 +29,15 @@ function headingText(node: Element): string {
 }
 
 /**
- * Scan `.grove-prose` for `h2`/`h3`, assigning the canonical id to any heading the kernel
- * did not emit one for, and re-scan as the prose mounts or swaps on navigation.
+ * Scan the entry's body for `h2`/`h3`, assigning the canonical id to any heading the
+ * kernel did not emit one for, and re-scan as the prose mounts or swaps on navigation.
+ *
+ * R3-872 (APP_CUSTOMIZATION §4.5): the scan is scoped to the ENTRY's marked body
+ * (`[data-entry="<entryKey>"]` — emitted on both render paths), never the whole
+ * document: on a multi-entry page the first `.grove-prose` is whichever entry mounted
+ * first, and its headings are the wrong entry's. Unscoped (no key, or no marked body
+ * anywhere) falls back to the document — the pre-marker behavior, for content that
+ * never renders through the marked paths.
  */
 export function useHeadings(entryKey?: string): Heading[] {
   const [heads, setHeads] = useState<Heading[]>([]);
@@ -38,9 +45,39 @@ export function useHeadings(entryKey?: string): Heading[] {
   useEffect(() => {
     // eslint-disable-next-line react-hooks/set-state-in-effect
     setHeads([]);
+    // The scan root: this entry's marked body when markers exist; the document only
+    // when NO body is marked at all (the pre-marker world). A page with markers but
+    // none for this key (the body is still compiling) scans nothing — the observer
+    // watches the DOCUMENT until this entry's marker lands, then re-scopes (a
+    // late-committing entry's ToC must not stay empty for the mount's lifetime).
+    // NOTE: the marker sits INSIDE `.grove-prose` (both render paths), so the
+    // scoped query runs over the marker's own subtree — searching the marker FOR
+    // '.grove-prose' would find nothing (review round 1, G-CUST-2 regression).
+    const markedRoot = (): HTMLElement | null =>
+      entryKey === undefined
+        ? null
+        : Array.from(document.querySelectorAll<HTMLElement>('[data-entry]')).find(
+            (n) => n.getAttribute('data-entry') === entryKey,
+          ) ?? null;
+    const anyMarked = () => document.querySelectorAll('[data-entry]').length > 0;
+    const root = (): ParentNode | null => {
+      const marked = markedRoot();
+      if (marked) return marked;
+      if (entryKey === undefined) return document;
+      return anyMarked() ? null : document;
+    };
     const scan = () => {
-      const prose = document.querySelector('.grove-prose');
-      const nodes = prose ? Array.from(prose.querySelectorAll('h2, h3')) : [];
+      const r = root();
+      // Scoped: the marker's subtree holds the entry's headings. Unscoped (no
+      // markers anywhere): the document's `.grove-prose`, as before.
+      const nodes = !r
+        ? []
+        : r === document
+          ? (() => {
+              const prose = document.querySelector('.grove-prose');
+              return prose ? Array.from(prose.querySelectorAll('h2, h3')) : [];
+            })()
+          : Array.from(r.querySelectorAll('h2, h3'));
       const found: Heading[] = nodes.map((n) => {
         const text = headingText(n);
         // Prefer the kernel-emitted id (§15.5); `headingId` reproduces the same canon
@@ -56,15 +93,29 @@ export function useHeadings(entryKey?: string): Heading[] {
         prev.length === found.length && prev.every((h, i) => h.id === found[i].id) ? prev : found
       );
     };
+    // Observe the SCOPED root when it exists; while our marker is absent (the
+    // body still compiling), observe the DOCUMENT so the marker's arrival
+    // triggers the rescan that re-scopes — then move the observer onto the
+    // marker (a whole-document watch would re-scan on every mutation anywhere,
+    // the churn the identity guard exists to absorb).
+    let observing: ParentNode | null = null;
+    const obs = new MutationObserver(() => {
+      const wanted = root() ?? document;
+      if (wanted !== observing) {
+        obs.disconnect();
+        obs.observe(wanted, { childList: true, subtree: true });
+        observing = wanted;
+      }
+      scan();
+    });
+    observing = root() ?? document;
+    obs.observe(observing, { childList: true, subtree: true });
     scan();
-    const prose = document.querySelector('.grove-prose');
-    const obs = prose ? new MutationObserver(scan) : null;
-    if (prose && obs) obs.observe(prose, { childList: true, subtree: true });
     // `<Include>` resolves asynchronously, and the observer only fires if `.grove-prose`
     // already existed — these catch the window where it did not.
     const timers = [120, 300, 600].map((d) => setTimeout(scan, d));
     return () => {
-      obs?.disconnect();
+      obs.disconnect();
       timers.forEach(clearTimeout);
     };
   }, [entryKey]);
@@ -72,12 +123,21 @@ export function useHeadings(entryKey?: string): Heading[] {
   return heads;
 }
 
-/** Which heading the reader is currently in — scroll-spied off the document. */
-export function useActiveHeading(heads: Heading[]): string {
+/** Which heading the reader is currently in — scroll-spied. R3-872: scoped to the
+ *  entry's marked body when a key is given — duplicate section ids across entries on
+ *  one page are the norm (every spec numbers from 1), and `document.getElementById`
+ *  would return the FIRST entry's heading, spying on the wrong entry. */
+export function useActiveHeading(heads: Heading[], entryKey?: string): string {
   const [cur, setCur] = useState<string>('');
 
   useEffect(() => {
     if (!heads.length) return;
+    const scope: ParentNode =
+      entryKey === undefined
+        ? document
+        : Array.from(document.querySelectorAll<HTMLElement>('[data-entry]')).find(
+            (n) => n.getAttribute('data-entry') === entryKey,
+          ) ?? document;
     const obs = new IntersectionObserver(
       (entries) => {
         const visible = entries.filter((e) => e.isIntersecting);
@@ -86,11 +146,12 @@ export function useActiveHeading(heads: Heading[]): string {
       { rootMargin: '-64px 0px -70% 0px', threshold: 0 }
     );
     heads.forEach((h) => {
-      const el = document.getElementById(h.id);
+      // find the element INSIDE the scope (a heading id is only unique per entry)
+      const el = scope === document ? document.getElementById(h.id) : scope.querySelector(`#${CSS.escape(h.id)}`);
       if (el) obs.observe(el);
     });
     return () => obs.disconnect();
-  }, [heads]);
+  }, [heads, entryKey]);
 
   return cur;
 }

package/src/lib/assetPath.ts

@@ -2,9 +2,10 @@
 // `cover:`/`img src`" into the fs path the SDK's `MountImage` reads.
 //
 // The distinction this module exists for: a body image resolves against the entry
-// CURRENTLY BEING RENDERED (`navigationState.sandboxPath` — `AssetImage`), while a
-// cover resolves against its OWNING entry — the entry the card/row/tile is ABOUT,
-// which under dispatch is usually a DIFFERENT base. Getting this wrong is not a bug
+// currently being rendered (the entry context's key via useEntryKey — AssetImage;
+// the routed key only as the no-provider fallback), while a
+// cover resolves against its owning entry — the entry the card/row/tile is about,
+// which under dispatch is usually a different base. Getting this wrong is not a bug
 // in `AssetImage`; it is the second half of design-pass gap 7: a `<DocList>` card or
 // `<Timeline>` row showing another entry's picture resolved against the wrong base
 // by construction.

package/src/lib/content.ts

@@ -286,8 +286,3 @@ export function sandboxPathToKey(sandboxPath: string): string {
   // HOME rather than becoming a key that reads some other file.
   return p.startsWith(contentDir()) ? p : homeKey();
 }
-
-/** A sandboxPath → the absolute fs base for resolving relative assets. */
-export function toFsPath(sandboxPath: string): string {
-  return keyToFsPath(sandboxPathToKey(sandboxPath));
-}

package/src/lib/editTarget.test.ts

@@ -4,21 +4,29 @@
 // viewer must send its edit to the CORPUS (never to Grove's own repo), and whether it may
 // offer one at all must be the corpus mount's CURRENT mode rather than a property of the
 // packaging or a flag latched at boot.
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, afterEach } from 'vitest';
 import { corpusWritable, editTarget, keyToSelfPath } from './editTarget';
 import type { CorpusIdentity } from './editTarget';
 import type { SandboxMount } from '@immediately-run/sdk/mounts';
-
-const fork: CorpusIdentity = {
-  dispatched: false,
-  contentRoot: '/app/content/',
-  mountId: null,
+import { getContentRoot, getCorpusMountId, isDispatched, resetContentRoot, setContentRoot } from './contentRoot';
+
+// The corpus identities come from the real producer (R3-877 round 1, R2): the
+// trailing-slash normalization every `slice` in editTarget depends on lives in
+// `setContentRoot` — a hand-typed literal would keep passing while it broke.
+const forkFor = (): CorpusIdentity => {
+  resetContentRoot();
+  return { dispatched: isDispatched(), contentRoot: getContentRoot(), mountId: getCorpusMountId() };
 };
-const dispatched: CorpusIdentity = {
-  dispatched: true,
-  contentRoot: '/task/t1/dir/',
-  mountId: '/task/t1/dir',
+const dispatchedFor = (): CorpusIdentity => {
+  setContentRoot('/task/t1/dir', { mountId: '/task/t1/dir' });
+  return { dispatched: isDispatched(), contentRoot: getContentRoot(), mountId: getCorpusMountId() };
 };
+afterEach(() => resetContentRoot());
+
+const fork: CorpusIdentity = forkFor();
+const dispatched: CorpusIdentity = dispatchedFor();
+// The dispatched entry keys, built off the producer's root — never a hand-typed prefix.
+const IN = (rel: string) => `${dispatched.contentRoot}${rel}`;
 
 const mount = (over: Partial<SandboxMount> = {}): SandboxMount =>
   ({ type: 'firestore', path: '/task/t1/dir', id: '/task/t1/dir', mode: 'rw', ...over }) as SandboxMount;
@@ -32,7 +40,7 @@ describe('editTarget — the verb follows the authority, not the packaging', ()
   });
 
   it('a DISPATCHED viewer delegates the CORPUS file, never a path in its own repo', () => {
-    expect(editTarget('/task/t1/dir/plot/the-rail.mdx', dispatched)).toEqual({
+    expect(editTarget(IN('plot/the-rail.mdx'), dispatched)).toEqual({
       via: 'delegate',
       mountId: '/task/t1/dir',
       relPath: 'plot/the-rail.mdx',
@@ -40,7 +48,7 @@ describe('editTarget — the verb follows the authority, not the packaging', ()
   });
 
   it('is corpus-relative under dispatch — the mount root IS the corpus root', () => {
-    const t = editTarget('/task/t1/dir/home.mdx', dispatched);
+    const t = editTarget(IN('home.mdx'), dispatched);
     expect(t).toMatchObject({ relPath: 'home.mdx' });
     // The fork's `content/` segment must NOT leak into a corpus-relative path: the
     // delegated chroot is minted AT the content directory.
@@ -52,11 +60,11 @@ describe('editTarget — the verb follows the authority, not the packaging', ()
   });
 
   it('offers nothing when a dispatched corpus has no mount id to delegate from', () => {
-    expect(editTarget('/task/t1/dir/home.mdx', { ...dispatched, mountId: null })).toBeNull();
+    expect(editTarget(IN('home.mdx'), { ...dispatched, mountId: null })).toBeNull();
   });
 
   it('offers nothing for the corpus root itself (a directory is not an entry)', () => {
-    expect(editTarget('/task/t1/dir/', dispatched)).toBeNull();
+    expect(editTarget(IN(''), dispatched)).toBeNull();
   });
 
   it('never throws on a junk key', () => {
@@ -81,13 +89,19 @@ describe('corpusWritable — the mount decides, live', () => {
     expect(corpusWritable([mount()], dispatched)).toBe(true);
   });
 
-  it('a ro corpus is not writable, so the affordance is hidden rather than EROFS-ing', () => {
-    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+  it('a ro corpus with no hint is still offerable (R3-877: the workbench class) — never EROFS, a refusal tells', () => {
+    // Pre-R3-877 this was `false` — an ro mount hid the affordance outright. The
+    // workbench class edits under the reader's authority, so our ro mount is the
+    // normal case, not a refusal. An explicit `false` hint still hides it (below).
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(true);
   });
 
-  it('follows a LIVE downgrade: the same mount re-announced ro flips the answer', () => {
+  it('follows a live downgrade: re-announced ro flips the delivery, and a false hint flips the offer', () => {
     expect(corpusWritable([mount({ mode: 'rw' })], dispatched)).toBe(true);
-    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+    // ro with no hint: still offerable, now via the workbench (reader's authority).
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(true);
+    // ro with the host saying the reader cannot edit: hidden.
+    expect(corpusWritable([mount({ mode: 'ro', readerCanEdit: false })], dispatched)).toBe(false);
   });
 
   it('a corpus mount that has vanished is not writable', () => {
@@ -106,3 +120,49 @@ describe('corpusWritable — the mount decides, live', () => {
     expect(corpusWritable([mount()], { ...dispatched, mountId: null })).toBe(false);
   });
 });
+
+// R3-877 — the third outcome: an ro delegation edits via the workbench, under the
+// reader's authority (`requestEdit({ bundleFile })`, R3-876). Order of preference:
+// self → delegate (rw) → workbench (ro).
+describe('editTarget — the workbench class for a read-only delegation (R3-877)', () => {
+  // The corpus identity's contentRoot mirrors the real getContentRoot() shape: the
+  // delegated chroot root, trailing slash.
+  const roCorpus: CorpusIdentity = { ...dispatched, mountMode: 'ro' };
+
+  it('an `ro` dispatched corpus yields workbench with the leading-slash bundle-relative path', () => {
+    expect(editTarget(IN('plot/the-rail.mdx'), roCorpus)).toEqual({
+      via: 'workbench',
+      relPath: '/plot/the-rail.mdx',
+    });
+  });
+
+  it('an `rw` delegation still yields delegate (the edit-file overlay is unchanged)', () => {
+    expect(editTarget(IN('plot/the-rail.mdx'), { ...dispatched, mountMode: 'rw' })).toEqual({
+      via: 'delegate',
+      mountId: '/task/t1/dir',
+      relPath: 'plot/the-rail.mdx',
+    });
+  });
+
+  it('an UNKNOWN mode (an older host announces none) keeps the pre-R3-877 delegate behavior', () => {
+    expect(editTarget(IN('home.mdx'), dispatched)).toEqual({
+      via: 'delegate',
+      mountId: '/task/t1/dir',
+      relPath: 'home.mdx',
+    });
+  });
+
+  it('the corpus root itself is still nothing to edit, workbench included', () => {
+    expect(editTarget(IN(''), roCorpus)).toBeNull();
+  });
+});
+
+describe('corpusWritable — the ro delegation is offerable on the hint (R3-877)', () => {
+  it('ro + readerCanEdit true → offered', () => {
+    expect(corpusWritable([mount({ mode: 'ro', readerCanEdit: true })], dispatched)).toBe(true);
+  });
+
+  it('ro + readerCanEdit false → not offered (never show a control that refuses)', () => {
+    expect(corpusWritable([mount({ mode: 'ro', readerCanEdit: false })], dispatched)).toBe(false);
+  });
+});

package/src/lib/editTarget.ts

@@ -20,8 +20,11 @@
 //
 // **The mount decides.** Writability is a property of the delegation's current mode, not
 // of how the app was loaded. That is why `corpusWritable` takes the live mount list rather
-// than the boot-time flag: a role downgrade re-announces the mount `ro`, and the
-// affordance must disappear rather than surface `EROFS` when clicked.
+// than the boot-time flag. Since R3-877 a role downgrade no longer hides the affordance —
+// it reroutes the delivery: `rw` hands the file to the `edit-file` overlay, `ro` asks the
+// workbench under the reader's authority (`requestEdit({ bundleFile })`). The offer hides
+// only when the host's `readerCanEdit` hint says the reader cannot edit, or a `read-only`
+// refusal proved it.
 //
 // Pure — no SDK, no React — so all of the above is testable without a host.
 
@@ -31,8 +34,14 @@ import type { SandboxMount } from '@immediately-run/sdk/mounts';
 export type EditTarget =
   /** The fork: our own repo, via the self-scoped present→edit transition. */
   | { via: 'self'; path: string }
-  /** Dispatch: one file of the delegated corpus, handed to the platform editor. */
-  | { via: 'delegate'; mountId: string; relPath: string };
+  /** Dispatch, writable delegation: one file of the corpus, handed to the platform
+   *  editor as a narrowed `edit-file` delegation (the overlay). */
+  | { via: 'delegate'; mountId: string; relPath: string }
+  /** Dispatch, read-only delegation (an app-declared opener's chroot): ask the
+   *  workbench to open the entry's source in the main-pane editor under the
+   *  reader's authority — `requestEdit({ bundleFile })` (R3-876 / APP_CUSTOMIZATION
+   *  §5a). The path is bundle-relative with a leading slash. */
+  | { via: 'workbench'; relPath: string };
 
 export interface CorpusIdentity {
   /** Whether the corpus is a mount rather than this app's own repo. */
@@ -41,6 +50,11 @@ export interface CorpusIdentity {
   contentRoot: string;
   /** The corpus mount id, when dispatched (`getCorpusMountId()`). */
   mountId: string | null;
+  /** The corpus delegation's current mode, read off the live mount list (R3-877):
+   *  `ro` routes the edit to the workbench under the reader's authority; `rw` keeps
+   *  the `edit-file` overlay. Absent/unknown keeps the pre-R3-877 behavior
+   *  (`delegate` — an `rw`-assuming host that announces no mode). */
+  mountMode?: 'ro' | 'rw' | null;
 }
 
 /** `/app/content/x.mdx` → `content/x.mdx` — the fork's repo-relative path. */
@@ -62,17 +76,25 @@ export function editTarget(entryKey: string, corpus: CorpusIdentity): EditTarget
   if (!corpus.mountId) return null;
   if (!entryKey.startsWith(corpus.contentRoot)) return null;
   const relPath = entryKey.slice(corpus.contentRoot.length);
-  return relPath ? { via: 'delegate', mountId: corpus.mountId, relPath } : null;
+  if (!relPath) return null;
+  // An `ro` delegation (the opener's chroot — the only mode an app-declared opener
+  // ever holds) goes to the workbench: the reader's authority, not ours — the mount
+  // is never upgraded and nothing is minted for us. Leading-slash, the host's
+  // `bundleFile` grammar.
+  if (corpus.mountMode === 'ro') return { via: 'workbench', relPath: `/${relPath}` };
+  return { via: 'delegate', mountId: corpus.mountId, relPath };
 }
 
 /**
  * May this instance offer an edit at all, given the mounts it holds RIGHT NOW?
  *
  * A fork asks about its working tree, as before. A dispatched viewer asks about the corpus
- * mount — and asks the LIVE mount list, not the boot-time flag, so a live `rw → ro`
- * downgrade (a role change the host re-announces on the same mount id) hides the
- * affordance on the next render. That is the whole difference between "hidden because you
- * may not" and "shown, then `EROFS` when you try".
+ * mount — and asks the live mount list, not the boot-time flag, so a live `rw → ro`
+ * downgrade (a role change the host re-announces on the same mount id) reroutes the
+ * delivery on the next render (to the workbench class) and an explicit
+ * `readerCanEdit: false` hides the offer — rather than surfacing `EROFS` on click.
+ * That is the whole difference between "hidden because you may not" and "shown, then
+ * `EROFS` when you try".
  *
  * A corpus mount that has vanished from the list answers `false`: no mount, no write.
  */
@@ -89,5 +111,12 @@ export function corpusWritable(
   // `mode` is absent on the primary repo mount and rw by default elsewhere; a corpus
   // mount that reports nothing is treated as writable exactly as `resolveOpenWiki` reads
   // it, so the two never disagree about the same mount.
-  return !!mount && mount.mode !== 'ro';
+  if (!mount) return false;
+  if (mount.mode !== 'ro') return true;
+  // R3-877 (APP_CUSTOMIZATION §5a.5): an `ro` delegation can still offer the
+  // workbench edit — the reader's authority — gated on the host's advisory
+  // `readerCanEdit` hint: offer when it is true, OR when the host sent no hint
+  // (absent = unknown — the refusal would tell, and `read-only` hides it after).
+  // Never offer on an explicit `false`.
+  return mount.readerCanEdit !== false;
 }

package/src/lib/entryContext.test.ts

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+// R3-871 — the entry context's actual behaviour, over the real key grammar.
+// The context key wins when a provider is present; the routed key (real
+// sandboxPathToKey) otherwise; and the component-level case — a relative link
+// inside a non-routed entry resolving against that entry — is driven in
+// WikiLink.test.tsx.
+import { describe, it, expect } from 'vitest';
+import { entryKeyOr } from './entryContext';
+import { sandboxPathToKey } from './content';
+
+describe('entryKeyOr — the one fallback rule (R3-871)', () => {
+  it('returns the context key when a provider is present', () => {
+    expect(entryKeyOr({ entryKey: '/app/content/teams/engineering.mdx' }, '/files/content/home.mdx')).toBe(
+      '/app/content/teams/engineering.mdx',
+    );
+  });
+
+  it('falls back to the routed key when the context is null (no provider)', () => {
+    expect(entryKeyOr(null, '/files/content/handbook/onboarding.mdx')).toBe(
+      sandboxPathToKey('/files/content/handbook/onboarding.mdx'),
+    );
+  });
+
+  it('treats an absent context the same as null', () => {
+    expect(entryKeyOr(undefined, '/files/content/handbook/onboarding.mdx')).toBe(
+      entryKeyOr(null, '/files/content/handbook/onboarding.mdx'),
+    );
+  });
+
+  it('the fallback is computed by the REAL sandboxPathToKey — the routed cases', () => {
+    // the folder URL form and the bare root both route HOME (the exact rule
+    // sandboxPathToKey encodes), so the default rendering is unchanged.
+    expect(entryKeyOr(null, '/')).toBe(sandboxPathToKey('/'));
+    expect(entryKeyOr(null, '')).toBe(sandboxPathToKey('/'));
+    // the /files-prefixed form strips to the content key
+    expect(entryKeyOr(null, '/files/content/a/b.mdx')).toBe('/app/content/a/b.mdx');
+  });
+});
+
+describe('entryKeyOr — a provider that says nothing', () => {
+  it('an empty-string entryKey is not a key: it falls back to the routed key', () => {
+    expect(entryKeyOr({ entryKey: '' }, '/files/content/handbook/onboarding.mdx')).toBe(
+      sandboxPathToKey('/files/content/handbook/onboarding.mdx'),
+    );
+  });
+});

package/src/lib/entryContext.ts

@@ -0,0 +1,35 @@
+// The entry context (APP_CUSTOMIZATION_SPEC §4.2; R3-871).
+//
+// Seven-plus Grove components used to work out "the entry I am in" from the
+// URL (`sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/')`). Inside
+// anything but the routed entry — an included fragment, a layout, and next a
+// story-river card — a relative `[[link]]` or `![](img.png)` resolved against
+// the wrong base, and "self" was judged against the URL. The provider placed
+// by `GroveWiki` (R3-872 moves it into `GroveEntry`) says which entry a
+// subtree renders; this module owns the context shape and the pure fallback
+// rule so both are testable without React.
+import { createContext } from 'react';
+import { sandboxPathToKey } from './content';
+
+/** What a provider subtree declares: the metadata key of the entry it renders. */
+export interface EntryContextValue {
+  entryKey: string;
+}
+
+/** The provider seam itself (§4.2): null — not the routed key — when no
+ *  provider is above, so the pure fallback rule below decides, exactly once.
+ *  Lives here, beside the rule it carries, per the item's placement; it is a
+ *  context object, not a component, so the Fast Refresh rule is not engaged. */
+export const EntryContext = createContext<EntryContextValue | null>(null);
+
+/**
+ * The one fallback rule: the context's entry when a provider is present, the
+ * routed key otherwise — computed by the real `sandboxPathToKey`, so the
+ * default rendering is byte-identical to before the context existed
+ * (R-CUST-3, default-preserving).
+ */
+export function entryKeyOr(contextValue: EntryContextValue | null | undefined, sandboxPath: string): string {
+  // `||` (not `??`): an empty-string entryKey is "a provider that says
+  // nothing", and falls back — '' is not a key anything can resolve against.
+  return contextValue?.entryKey || sandboxPathToKey(sandboxPath || '/');
+}

package/src/lib/fragment.test.ts

@@ -86,3 +86,24 @@ describe('resolveFragmentTarget — the stale-document guard (R3-249)', () => {
     expect(resolveFragmentTarget(doc, INCOMING, '')).toBeNull();
   });
 });
+
+describe('G-CUST-4 — entry-scoped resolution on a multi-entry page (R3-872)', () => {
+  const FIRST = '/app/content/specs/A_SPEC.mdx';
+  const SECOND = '/app/content/specs/B_SPEC.mdx';
+
+  it('two marked bodies, both with #sec-4 (one per render path — both carry data-entry since R3-872): scoping to the second lands in the second', () => {
+    const doc = makeDoc([
+      { entry: FIRST, ids: ['sec-4'] },
+      { entry: SECOND, ids: ['sec-4'] },
+    ]);
+    const el = resolveFragmentTarget(doc, SECOND, 'sec-4') as unknown as { entry: string };
+    expect(el?.entry).toBe(SECOND);
+  });
+
+  it('the document-wide fallback fires only when NO body is marked at all (pre-marker content)', () => {
+    const doc = makeDoc([]);
+    // no marked bodies → the fallback is the whole document (today's compiled-path
+    // behavior for content that never renders the marked paths)
+    expect(resolveFragmentTarget(doc, FIRST, 'sec-4')).toBeNull(); // nothing anywhere
+  });
+});

package/src/lib/fragment.ts

@@ -24,9 +24,12 @@ export function fragmentOf(hash: string | undefined | null): string {
  * about. Returns null while the previous entry is still rendered, which is the signal to
  * wait rather than to scroll.
  *
- * Falls back to the whole document when no marked body is present — the compiled
- * (`<Include>`) path does not carry the marker, and scrolling imperfectly there is better
- * than not at all.
+ * R3-872: BOTH render paths carry the `data-entry` marker now (the compiled path's
+ * omission predates entry-scoped resolution) — the marker means "this region belongs to
+ * entry X", and a fragment not yet inside it is not-found, so the caller keeps waiting
+ * through the compile window (ScrollToFragment retries; claim-too-early has no path to
+ * fire). The document-wide fallback serves only content rendered with NO marked bodies
+ * at all (pre-marker content), never a multi-entry page.
  */
 export function resolveFragmentTarget(doc: Document, entryKey: string, frag: string): HTMLElement | null {
   if (!frag) return null;
@@ -37,9 +40,9 @@ export function resolveFragmentTarget(doc: Document, entryKey: string, frag: str
   // strings has no such failure mode, and there are only a handful of marked bodies.
   const marked = Array.from(doc.querySelectorAll<HTMLElement>('[data-entry]'));
   const scope: ParentNode | null = marked.find((n) => n.getAttribute('data-entry') === entryKey) ?? null;
-  // No marked body at all: the compiled (`<Include>`) path does not carry the marker, so
-  // fall back to the document. A marked body for a DIFFERENT entry means the previous
-  // document is still on screen — return null and wait, rather than scroll the wrong page.
+  // No marked body at all (content rendered outside the marked paths): fall back to
+  // the document. A marked body for a DIFFERENT entry means the previous document is
+  // still on screen — return null and wait, rather than scroll the wrong page.
   const root: ParentNode | null = scope ?? (marked.length === 0 ? doc : null);
   if (!root) return null;
   const byId = root.querySelector<HTMLElement>(`[id="${cssEscape(frag)}"]`);

package/src/lib/navigationPolicy.test.ts

@@ -0,0 +1,65 @@
+// The navigation policy's defaults + click guard (APP_CUSTOMIZATION_SPEC §4.3,
+// R3-872): the stock policy navigates the resolved href; a plain click routes to
+// the policy with the browser default prevented; a modified click falls through
+// to the real href; a throwing policy fails LOUDLY (logged, never silently
+// retried by the default — R-CUST-5).
+import { describe, it, expect, vi } from 'vitest';
+
+const navigate = vi.fn();
+vi.mock('@immediately-run/sdk', () => ({ navigate: (...a: unknown[]) => navigate(...(a as [])) }));
+
+import { defaultFollowLink, followLinkOnClick } from './navigationPolicy';
+
+const click = (over: Partial<Parameters<ReturnType<typeof followLinkOnClick>>[0]> = {}) => ({
+  button: 0,
+  metaKey: false,
+  ctrlKey: false,
+  shiftKey: false,
+  altKey: false,
+  preventDefault: vi.fn(),
+  ...over,
+});
+
+describe('navigationPolicy', () => {
+  it('defaultFollowLink calls the SDK navigate with the resolved href', () => {
+    defaultFollowLink({ key: '/app/content/a.mdx', href: '/content/a' });
+    expect(navigate).toHaveBeenCalledWith('/content/a');
+  });
+
+  it('a plain click (primary button, no modifier) reaches the policy and prevents the default', () => {
+    const follow = vi.fn();
+    const e = click();
+    followLinkOnClick(follow, { key: 'k', fragment: 'sec-4', href: '/h#sec-4', from: 'here' })(e);
+    expect(follow).toHaveBeenCalledWith({ key: 'k', fragment: 'sec-4', href: '/h#sec-4', from: 'here' });
+    expect(e.preventDefault).toHaveBeenCalled();
+  });
+
+  it.each([
+    ['meta', { metaKey: true }],
+    ['ctrl', { ctrlKey: true }],
+    ['shift', { shiftKey: true }],
+    ['alt', { altKey: true }],
+    ['non-primary button', { button: 1 }],
+  ])('a %s click never reaches the policy — the real href handles it', (_name, over) => {
+    const follow = vi.fn();
+    const e = click(over);
+    followLinkOnClick(follow, { key: 'k', href: '/h' })(e);
+    expect(follow).not.toHaveBeenCalled();
+    expect(e.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it('a throwing policy is logged with the target and NOT silently fallen back from', () => {
+    const boom = new Error('policy broke');
+    const follow = vi.fn(() => {
+      throw boom;
+    });
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const e = click();
+    expect(() => followLinkOnClick(follow, { key: 'k', href: '/h' })(e)).not.toThrow();
+    expect(err).toHaveBeenCalledWith(expect.stringContaining('k'), boom);
+    // and no default navigation happened in place of the policy (the click was
+    // already preventDefault'd — the shell's bug is visible, never papered over)
+    expect(e.preventDefault).toHaveBeenCalled();
+    err.mockRestore();
+  });
+});