@immediately-run/grove 0.1.10 → 0.2.0

package/src/components/PageView.tsx

@@ -1,27 +1,26 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { Include, Link } from '@immediately-run/sdk';
+import { Link } from '@immediately-run/sdk';
 import { useShell, EDIT_REFUSED_NOTICE } from '../lib/shell';
-import { keyToHref, keyToRepoRel } from '../lib/content';
+import { keyToHref, keyToRepoRel, homeKey } from '../lib/content';
 import { crumb } from '../lib/wiki';
 import { useHeadingFragmentUrl } from '../hooks/useHeadingFragmentUrl';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import DirectoryView from './DirectoryView';
-import EntryHeader from './EntryHeader';
-import SafeEntryBody from './SafeEntryBody';
-import ScrollToFragment from './ScrollToFragment';
-import Toc from './Toc';
-import Backlinks from './Backlinks';
+import EntryBody from './EntryBody';
 import Icon from './Icon';
 
-declare const module: any;
-
 // `<PageView/>` — the reading view for the current entry: the 404/missing state,
 // or the entry header + prose body (+ ToC / backlinks rails). This is what the
 // INNERMOST `<Outlet/>` renders at the bottom of the layout chain. It carries no
 // site chrome (nav / sidebar / footer) — that's the layout's job — so the page
 // stays free of shell concerns.
 export default function PageView() {
-  const { entryKey, includePath, layout, showRails, mins, missing, suggestion, writable, openEditor, editBusy, editRefused, editHint, vw, safe, directory } =
+  // R3-872: the entry content lives in EntryBody (one renderer, shared with
+  // GroveEntry); the page keeps only the page-level states (checking /
+  // directory / missing) and the deep-link half it owns.
+  const { entryKey, missing, suggestion, writable, openEditor, editBusy, editRefused, editHint, directory } =
     useShell();
+  const follow = useFollowLink();
 
   // The reading view owns the headings, so it owns the outgoing half of deep
   // linking: same-page heading navigation writes the fragment into the host's
@@ -41,10 +40,10 @@ export default function PageView() {
         <h2>No entry at <code>{keyToRepoRel(entryKey).replace(/^content/, '')}</code>.</h2>
         <p>
           That link points to an entry that doesn’t exist yet.
-          {suggestion ? <> Did you mean <Link className="grove-wikilink" data-state="ok" href={keyToHref(suggestion)}>{crumb(suggestion)}</Link>?</> : null}
+          {suggestion ? <> Did you mean <Link className="grove-wikilink" data-state="ok" href={keyToHref(suggestion)} onClick={followLinkOnClick(follow, { key: suggestion, href: keyToHref(suggestion), from: entryKey })}>{crumb(suggestion)}</Link>?</> : null}
         </p>
         <div className="grove-state__actions">
-          <Link className="btn-ghost" href="/"><Icon name="chevron-right" /> Back to home</Link>
+          <Link className="btn-ghost" href="/" onClick={followLinkOnClick(follow, { key: homeKey(), href: '/', from: entryKey })}><Icon name="chevron-right" /> Back to home</Link>
           {writable ? (
             <>
             <button
@@ -66,54 +65,5 @@ export default function PageView() {
     );
   }
 
-  return (
-    <article className="grove-page" data-layout={layout}>
-      <div className="gp-main">
-        <EntryHeader entryKey={entryKey} writable={writable} mins={mins} />
-        {showRails && vw === 'mobile' ? (
-          <details className="grove-toc__disclosure">
-            <summary>On this page</summary>
-            <Toc entryKey={entryKey} />
-          </details>
-        ) : null}
-        <div className="grove-prose">
-          {/* Interpreter mode (R3-213) renders the raw entry as data — no author JS runs;
-              executable mode compiles + runs the MDX via <Include>. Both are supported,
-              and since R3-252 the choice is per-entry as well as wiki-wide.
-
-              The compiled branch mounts <ScrollToFragment> too — deep-link landing is not
-              a safe-path feature — but deliberately carries NO `data-entry` marker, and
-              both halves of that are load-bearing (R3-252).
-
-              `key={entryKey}` forces an unmount across a client-side navigation. Without
-              it React reuses this subtree and keeps the PREVIOUS document mounted while
-              the new one compiles, so `#sec-4` resolves against the wrong entry — every
-              entry here numbers its sections from 1, so that lookup always succeeds and
-              always lands wrong. Measured on the host: a citation to core_concepts §4
-              ("4 — Principal") scrolled to a different document's "4. The provider-facing
-              contract" (R3-249's hazard, reintroduced).
-
-              No marker, because `<Include>` owns an internal <Suspense> and this wrapper
-              is OUTSIDE it — so a marker here would appear the instant we navigate, while
-              the body is still compiling, and claim a commit that has not happened. That
-              is worse than no signal: `data-entry` means "this subtree holds entry X's
-              committed body" everywhere else (`SafeEntryBody` puts it inside the suspended
-              subtree, so it is true there), and the on-host harness waits on it. Keying
-              already removes the hazard the marker defended against — the outgoing
-              document is gone from the DOM, not lingering — so `resolveFragmentTarget`'s
-              documented document-wide fallback for the compiled path is safe here. */}
-          {safe ? (
-            <SafeEntryBody entryKey={entryKey} />
-          ) : (
-            <div className="grove-entry-body" key={entryKey}>
-              <Include filename={includePath} baseModule={module} />
-              <ScrollToFragment entryKey={entryKey} />
-            </div>
-          )}
-        </div>
-        {showRails ? <Backlinks /> : null}
-      </div>
-      {showRails && vw === 'desktop' ? <Toc entryKey={entryKey} /> : null}
-    </article>
-  );
+  return <EntryBody entryKey={entryKey} />;
 }

package/src/components/Search.tsx

@@ -4,6 +4,8 @@ import type { Metadata } from '@immediately-run/sdk';
 import { keyToHref } from '../lib/content';
 import { crumb } from '../lib/wiki';
 import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import InlineProse from './InlineProse';
 import { matchesQuery, searchQuery, toSearchEntries } from '../lib/queries';
 import type { SearchRecord } from '../lib/queries';
@@ -75,6 +77,7 @@ export default function Search({ onClose }: { onClose: () => void }) {
     }
   };
 
+  const follow = useFollowLink();
   const activeId = total > 0 ? `${listId}-opt-${sel}` : undefined;
 
   return (
@@ -125,7 +128,13 @@ export default function Search({ onClose }: { onClose: () => void }) {
                   id={`${listId}-opt-${i}`}
                   role="option"
                   aria-selected={sel === i}
-                  onClick={onClose}
+                  onClick={(e) => {
+                    // R3-872: the policy first (it preventDefaults plain clicks and
+                    // no-ops modified ones), then the overlay's own close — the
+                    // same order the bare onClick={onClose} had with no policy.
+                    followLinkOnClick(follow, { key: h.key, href: keyToHref(h.key) })(e);
+                    onClose();
+                  }}
                 >
                   <Icon name="file" />
                   <span className="t">

package/src/components/Sidebar.tsx

@@ -1,9 +1,10 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { useContext, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { Link, useMetadataQuery } from '@immediately-run/sdk';
 import type { Metadata } from '@immediately-run/sdk';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
-import { contentDir, keyToHref, sandboxPathToKey } from '../lib/content';
+import { contentDir, keyToHref } from '../lib/content';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import { sidebarQuery } from '../lib/queries';
 import { plainLabel } from '../lib/queries';
 import InlineProse from './InlineProse';
@@ -77,6 +78,7 @@ function Branch({
   const isFolder = childKeys.length > 0;
   const containsCurrent = !!currentKey && (node.key === currentKey || hasDescendant(node, currentKey));
   const [open, setOpen] = useState(depth < 1 || containsCurrent);
+  const follow = useFollowLink();
 
   if (!isFolder) {
     return (
@@ -89,6 +91,7 @@ function Branch({
         aria-level={depth + 1}
         aria-current={node.key === currentKey ? 'page' : undefined}
         tabIndex={node.key === stopRowId ? 0 : -1}
+        onClick={followLinkOnClick(follow, { key: node.key!, href: keyToHref(node.key!), from: currentKey })}
       >
         <Icon name="file" />
         <InlineProse text={node.title || node.name} trimPeriod />
@@ -141,8 +144,8 @@ function Branch({
 // `.grove-sidebar` — the wiki shell's left rail: a namespace tree + author-defined
 // `ui/sidebar` sections (a header + a link into the tagged entry).
 export default function Sidebar() {
-  const ctx = useContext(TinkerableContext) as any;
-  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const currentKey = useEntryKey();
+  const follow = useFollowLink();
 
   // Records, not tab-encoded paths (R3-276a).
   const q = useMetadataQuery<Metadata, SidebarRecord>(sidebarQuery);
@@ -209,7 +212,12 @@ export default function Sidebar() {
         <div className="gs-block" key={s.key}>
           <div className="gs-block__h">{s.label}</div>
           <div className="gs-section__body">
-            <Link href={keyToHref(s.key)} className="grove-wikilink" data-state="ok">
+            <Link
+              href={keyToHref(s.key)}
+              className="grove-wikilink"
+              data-state="ok"
+              onClick={followLinkOnClick(follow, { key: s.key, href: keyToHref(s.key), from: currentKey })}
+            >
               Open
             </Link>
           </div>

package/src/components/TableOfContents.tsx

@@ -42,7 +42,7 @@ const MANUAL_SCROLL_GRACE_MS = 2000;
  */
 export default function TableOfContents({ entryKey, title = 'On this page', className }: Props) {
   const heads = useHeadings(entryKey);
-  const cur = useActiveHeading(heads);
+  const cur = useActiveHeading(heads, entryKey);
   const listRef = useRef<HTMLElement | null>(null);
   const itemsRef = useRef(new Map<string, HTMLAnchorElement>());
   const manualUntilRef = useRef(0);

package/src/components/Timeline.tsx

@@ -4,15 +4,20 @@ import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
 import { isContentEntry, keyToHref } from '../lib/content';
 import InlineProse from './InlineProse';
 import { queryPaths } from '../lib/wiki';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import EntryImage from './EntryImage';
 
 // One dated entry on the axis: mono date · node · card.
 function Row({ path }: { path: string }) {
   const m = useFileMetadata(path) as any;
+  const from = useEntryKey();
+  const follow = useFollowLink();
   if (!m) return null;
   const tags: string[] = Array.isArray(m.tags) ? m.tags.filter((t: string) => !t.startsWith('ui/')) : [];
   return (
-    <Link href={keyToHref(path)} className="gtl-row">
+    <Link href={keyToHref(path)} className="gtl-row" onClick={followLinkOnClick(follow, { key: path, href: keyToHref(path), from })}>
       <div className="gtl-date">{m.date}</div>
       <div className="gtl-node" />
       <div className="gtl-card">

package/src/components/WikiLink.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+// R3-871 — WikiLink resolves against the entry it renders inside, not the URL.
+// The URL routes to content/home.mdx while an EntryContext provider says this
+// subtree renders content/teams/engineering.mdx: a relative link must resolve
+// from engineering's directory, and "self" must be judged against engineering.
+// Keys come from the real key grammar (sandboxPathToKey/hrefKeyCandidates), the
+// same fixtures shape the other component tests use.
+import { describe, it, expect, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import type { ReactNode } from 'react';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { resetContentRoot, setContentRoot } from '../lib/contentRoot';
+
+const { default: WikiLink } = await import('./WikiLink');
+const { EntryContext } = await import('../hooks/useEntryKey');
+
+const METADATA = {
+  '/app/content/home.mdx': { title: 'Home' },
+  '/app/content/teams/engineering.mdx': { title: 'Engineering' },
+  '/app/content/people/ada-lovelace.mdx': { title: 'Ada Lovelace' },
+};
+
+/** The URL routes HOME; the provider (when given) says which entry we render. */
+function host(children: ReactNode, entryKey?: string, sandboxPath = '/files/content/home.mdx') {
+  const value = {
+    outerHref: 'https://immediately.run/present/github/o/r/main/files/content/home.mdx',
+    navigationState: { mode: 'present', namespace: 'github', provider: 'github', repository: 'o/r', ref: 'main', sandboxPath, hash: '', search: '' },
+    routingSpec: { routes: [] },
+    filesMetadata: METADATA,
+  };
+  const inner = <TinkerableContext.Provider value={value as never}>{children}</TinkerableContext.Provider>;
+  return entryKey === undefined ? inner : <EntryContext.Provider value={{ entryKey }}>{inner}</EntryContext.Provider>;
+}
+
+async function render(node: ReactNode): Promise<HTMLElement> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    createRoot(container).render(node);
+  });
+  return container;
+}
+
+describe('WikiLink — the entry context decides the base (R3-871)', () => {
+  beforeEach(() => {
+    setContentRoot('/app/content/');
+    return () => resetContentRoot();
+  });
+
+  it('a relative link inside a non-routed entry resolves against that entry', async () => {
+    // the URL routes home; the subtree renders engineering (teams/engineering.mdx).
+    const el = await render(
+      host(
+        <WikiLink href="../people/ada-lovelace.mdx">Ada</WikiLink>,
+        '/app/content/teams/engineering.mdx',
+      ),
+    );
+    const link = el.querySelector('.grove-wikilink') as HTMLElement;
+    expect(link).not.toBeNull();
+    expect(link.getAttribute('data-state')).toBe('ok');
+    expect(link.getAttribute('href')).toContain('people/ada-lovelace.mdx');
+  });
+
+  it('the same relative link with no provider resolves against the routed entry (home)', async () => {
+    // From home/, ../people/ada-lovelace.mdx lands outside the corpus → broken.
+    // This is the default-preserving seam: same input, different base, by design.
+    const el = await render(host(<WikiLink href="../people/ada-lovelace.mdx">Ada</WikiLink>));
+    const link = el.querySelector('.grove-wikilink') as HTMLElement;
+    expect(link.getAttribute('data-state')).toBe('broken');
+  });
+
+  it('a link to the context entry\'s own entry is self — judged against the entry, not the URL', async () => {
+    const el = await render(
+      host(
+        <WikiLink href="engineering.mdx">this very page</WikiLink>,
+        '/app/content/teams/engineering.mdx',
+      ),
+    );
+    const link = el.querySelector('.grove-wikilink') as HTMLElement;
+    expect(link.getAttribute('data-state')).toBe('self');
+  });
+});

package/src/components/WikiLink.tsx

@@ -1,10 +1,12 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useCallback, useContext } from 'react';
+import { useCallback } from 'react';
 import { Link, useMetadataQuery } from '@immediately-run/sdk';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
-import { hrefKeyCandidates, hrefTargetKey, isContentEntry, keyToHref, linkKind, sandboxPathToKey, splitFragment } from '../lib/content';
+import { hrefKeyCandidates, hrefTargetKey, isContentEntry, keyToHref, linkKind, splitFragment } from '../lib/content';
 import { isFolderKey } from '../lib/directory';
 import { queryPaths } from '../lib/wiki';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import Icon from './Icon';
 
 interface Props {
@@ -19,8 +21,10 @@ interface Props {
 // glance. Those are the ONLY two shapes: an in-app href that resolves to nothing renders
 // broken, never as a bare `<a>` (see `linkKind` — R3-252).
 export default function WikiLink({ href = '', children, ...rest }: Props) {
-  const ctx = useContext(TinkerableContext) as any;
-  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  // R3-871: the entry this link renders inside, not whatever the URL says.
+  const currentKey = useEntryKey();
+  // R3-872: plain clicks ride the navigation policy; the href stays real.
+  const follow = useFollowLink();
 
   // Resolve existence against the whole in-memory index (so a missing target is
   // *definitively* broken, not a load-time flash).
@@ -45,7 +49,12 @@ export default function WikiLink({ href = '', children, ...rest }: Props) {
   const targetKey = candidates.find((k) => keys.includes(k)) ?? candidates[0] ?? null;
   // Route on the RESOLVED key, not the author's text: handing `<Link>` a relative href
   // would make it resolve against the outer page URL rather than the content tree.
-  const [, fragment] = splitFragment(href);
+  const [, fragmentRaw] = splitFragment(href);
+  // `fragmentRaw` keeps the '#' for the hrefs (they concatenate it); the policy
+  // target carries the bare id (the FollowLinkTarget shape and
+  // resolveFragmentTarget's convention agree — never '#' + id).
+  const fragment = fragmentRaw || '';
+  const policyFragment = fragmentRaw ? fragmentRaw.replace(/^#/, '') : undefined;
   const resolvedHref = targetKey ? keyToHref(targetKey) + fragment : href;
 
   // Only an href that MEANS to leave the document becomes a real `<a>` — see `linkKind`.
@@ -60,7 +69,13 @@ export default function WikiLink({ href = '', children, ...rest }: Props) {
     const dirKey = kind === 'content' ? hrefTargetKey(href, currentKey) : null;
     if (dirKey && loaded && isFolderKey(dirKey, keys)) {
       return (
-        <Link href={keyToHref(dirKey) + fragment} className="grove-wikilink" data-state="ok" {...rest}>
+        <Link
+          href={keyToHref(dirKey) + fragment}
+          className="grove-wikilink"
+          data-state="ok"
+          onClick={followLinkOnClick(follow, { key: dirKey, fragment: policyFragment, href: keyToHref(dirKey) + fragment, from: currentKey })}
+          {...rest}
+        >
           {children}
         </Link>
       );
@@ -105,7 +120,13 @@ export default function WikiLink({ href = '', children, ...rest }: Props) {
   }
 
   return (
-    <Link href={resolvedHref} className="grove-wikilink" data-state="ok" {...rest}>
+    <Link
+      href={resolvedHref}
+      className="grove-wikilink"
+      data-state="ok"
+      onClick={followLinkOnClick(follow, { key: targetKey, fragment: policyFragment, href: resolvedHref, from: currentKey })}
+      {...rest}
+    >
       {children}
     </Link>
   );

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