@immediately-run/grove 0.1.10 → 0.2.0

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

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

package/src/lib/navigationPolicy.ts

@@ -0,0 +1,57 @@
+// The navigation policy (APP_CUSTOMIZATION_SPEC §4.3, R3-872) — every in-bundle entry
+// link's plain click goes through ONE replaceable function, so a shell that composes
+// GroveEntry decides what "follow" means (route, open elsewhere, intercept) without
+// forking a component.
+//
+// This file exports no component (the Fast-Refresh rule), so the context lives here
+// beside the default it falls back to.
+
+import { createContext } from 'react';
+import { navigate } from '@immediately-run/sdk';
+
+/** A resolved link target: the corpus key, any `#fragment`, the concrete href the
+ *  anchor already renders (modifier-/middle-click still open it in a new tab), and
+ *  the entry the link was rendered inside (`from`). Resolution happens at the call
+ *  site — the policy receives the ANSWER, never a string to re-derive. */
+export interface FollowLinkTarget {
+  key: string;
+  fragment?: string;
+  href: string;
+  from?: string;
+}
+
+/** What a plain click on an entry link does. */
+export type FollowLink = (target: FollowLinkTarget) => void;
+
+/** The stock behaviour: navigate to the resolved href, exactly as the SDK's Link
+ *  would have. */
+export const defaultFollowLink: FollowLink = ({ href }) => navigate(href);
+
+/**
+ * The active policy. Read via `useFollowLink()` (the hook file keeps the
+ * component-tree rule); the context's default is the stock behaviour, so an
+ * unprovided tree behaves exactly as before (R-CUST-2).
+ */
+export const NavigationPolicyContext = createContext<FollowLink>(defaultFollowLink);
+
+/**
+ * The anchor `onClick` half of the policy (R-CUST-3): a PLAIN click (no modifier,
+ * primary button) goes to the policy and never to the browser; a modified click
+ * falls through to the anchor's real `href` (new tab/window semantics are the
+ * browser's, and an anchor that lost them is a bug). A policy that throws is caught,
+ * logged with the target, and NOT silently fallen back from (R-CUST-5: fail loudly).
+ */
+export function followLinkOnClick(
+  follow: FollowLink,
+  target: FollowLinkTarget,
+): (e: { button: number; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void {
+  return (e) => {
+    if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    try {
+      follow(target);
+    } catch (err) {
+      console.error(`[grove] the navigation policy threw for ${target.key}${target.fragment ?? ''}`, err);
+    }
+  };
+}

package/src/lib/renderMode.ts

@@ -0,0 +1,17 @@
+// The safe-vs-compiled render decision, in ONE place (R3-872 review, round 1):
+// interpreter mode is read from the HOME entry (wiki-wide) OR the current entry
+// (per-entry), and the two answer different questions — wiki-wide is the
+// interpreter declaration for foreign content; per-entry exists for the document
+// that is only correct as data (R3-252's proof page). Three renderers decide on
+// this — the layout chain's renderer pick, the entry body's pick, and the shell's
+// `safe` field — and drift between them is a trust-boundary hole (an executing
+// body inside a safe chain), never a style issue. Pure, so the rule is testable
+// without a render.
+
+/** True when the entry renders through the non-executable interpreter path. */
+export function resolveSafeRender(
+  homeMeta: Record<string, unknown> | null | undefined,
+  entryMeta: Record<string, unknown> | null | undefined,
+): boolean {
+  return homeMeta?.render === 'safe' || entryMeta?.render === 'safe';
+}

package/src/lib/shell.ts

@@ -67,6 +67,10 @@ export interface GroveShell {
    *  `checking` while the readdir is in flight — <PageView> must render neither the
    *  entry nor the 404 then, or a folder URL flashes "No entry at …" before healing. */
   directory: DirectoryListing;
+  /** R3-872 — the entry frame's gate input: the content stylesheets' read state.
+   *  Wiki-wide (the home entry's declaration), provided by the engine root;
+   *  standalone compositions default to 'ready' (no sheets declared). */
+  stylesheetsStatus?: 'loading' | 'ready';
 }
 
 /** The refusal sentence, ONE home (R6, R3-608): every surface that offers an edit

package/src/lib.ts

@@ -52,3 +52,21 @@ export {
 export { getContentRoot, isDispatched } from './lib/contentRoot';
 export { layoutChainForKey } from './lib/layout';
 export { queryPaths, readingTime, stripFrontmatter } from './lib/wiki';
+
+// The entry composition seam (R3-872, APP_CUSTOMIZATION_SPEC §4.1): render one entry
+// from a key — header + body + metadata + tags — framed by its layout chain or bare,
+// publishing the entry context either way.
+export { default as GroveEntry } from './components/GroveEntry';
+export { useEntryKey } from './hooks/useEntryKey';
+
+// The navigation policy (§4.3): every in-bundle entry link's plain click rides one
+// replaceable function; the href stays real for modifier/middle clicks.
+export { NavigationPolicyContext, defaultFollowLink, followLinkOnClick } from './lib/navigationPolicy';
+export type { FollowLink, FollowLinkTarget } from './lib/navigationPolicy';
+export { useFollowLink } from './hooks/useFollowLink';
+
+// The entry-scoped helpers (§4.5): fragment resolution and heading collection scoped
+// to one entry's marked body.
+export { fragmentOf, resolveFragmentTarget } from './lib/fragment';
+export { useHeadings } from './hooks/useHeadings';
+export type { Heading } from './hooks/useHeadings';