@immediately-run/grove 0.1.10 → 0.2.0

package/llms.txt

@@ -1,6 +1,6 @@
 # @immediately-run/grove — the viewer kit for directory-as-content wikis
 
-> The Grove viewer: a kit of React components, layouts and themes for building immediately.run wikis. Composable as a fork, a dispatch target, or a pinned library. (v0.1.10)
+> The Grove viewer: a kit of React components, layouts and themes for building immediately.run wikis. Composable as a fork, a dispatch target, or a pinned library. (v0.2.0)
 
 Grove is NOT a wiki engine: routing, MDX compilation, the frontmatter index, link
 spaces and heading anchors live in the sandbox + `@immediately-run/sdk`. What this
@@ -25,20 +25,28 @@ and the defaults. Three composition modes (PLATFORM_LAYERING_SPEC §1.1):
 
 ## Composition entry (src/lib.ts)
 
+- `FollowLink`
+- `FollowLinkTarget`
 - `GROVE_MDX`
 - `GroveApp`
+- `GroveEntry`
 - `GroveShell`
 - `GroveShellContext`
 - `GroveWiki`
+- `Heading`
 - `ManifestComponent`
 - `ManifestOverrideError`
 - `NavItem`
+- `NavigationPolicyContext`
 - `OutletContext`
 - `SAFE_MDX`
 - `VIEWER_MANIFEST`
 - `ViewerManifest`
 - `composeComponents`
 - `contentDir`
+- `defaultFollowLink`
+- `followLinkOnClick`
+- `fragmentOf`
 - `getContentRoot`
 - `homeKey`
 - `isContentEntry`
@@ -51,8 +59,12 @@ and the defaults. Three composition modes (PLATFORM_LAYERING_SPEC §1.1):
 - `overridableNames`
 - `queryPaths`
 - `readingTime`
+- `resolveFragmentTarget`
 - `sandboxPathToKey`
 - `stripFrontmatter`
+- `useEntryKey`
+- `useFollowLink`
+- `useHeadings`
 - `useShell`
 
 ## Component vocabulary — the override contract (viewer.manifest.json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/grove",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {

package/src/GroveWiki.tsx

@@ -1,10 +1,8 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useCallback, useContext, useEffect, useState } from 'react';
-import type { ReactNode } from 'react';
 import fs from 'fs';
 import type { Metadata } from '@immediately-run/sdk';
 import {
-  Include,
   ScrollRestoration,
   useAllMetadata,
   useFileMetadata,
@@ -27,7 +25,9 @@ import { queryPaths, queryRecords, readingTime, stripFrontmatter } from './lib/w
 import { navQuery, plainLabel } from './lib/queries';
 import type { NavRecord } from './lib/queries';
 import { layoutChainForKey, resolveNavMode, resolvePageLayout } from './lib/layout';
+import { resolveSafeRender } from './lib/renderMode';
 import { folderIndexKey } from './lib/directory';
+import GroveEntry from './components/GroveEntry';
 import { resolvePalette, resolvePolarity, type Polarity } from './lib/themeSelection';
 import { preferredPolarity } from './data/themes';
 import { useDirectoryListing } from './hooks/useDirectoryListing';
@@ -35,24 +35,15 @@ import { useScrollReset } from './hooks/useScrollReset';
 import { useEditAffordance } from './hooks/useEditAffordance';
 import { getContentRoot, isDispatched } from './lib/contentRoot';
 import type { RejectedComponent } from './lib/corpusComponents';
-import { GroveShellContext, OutletContext } from './lib/shell';
+import { GroveShellContext } from './lib/shell';
 import type { GroveShell, NavItem } from './lib/shell';
-import PageView from './components/PageView';
-import SafeLayout from './components/SafeLayout';
-import DefaultLayout from './components/DefaultLayout';
 import Search from './components/Search';
 import Drawer from './components/Drawer';
 import GroveAgent from './components/GroveAgent';
 import ThemeAssets from './components/ThemeAssets';
 import ContentTheme from './components/ContentTheme';
-import BootMessage from './components/BootMessage';
 import { themeAssetsFor } from './data/themeFonts';
 import { useContentStylesheets } from './hooks/useContentStylesheets';
-import { criticalKeys } from './lib/criticalKeys';
-import { criticalFailure, entryPending } from './lib/entryGate';
-import { CorpusScanContext } from './lib/corpusScanContext';
-
-declare const module: any;
 
 function readPref(k: string): string | null {
   try {
@@ -82,33 +73,6 @@ function bundleHref(bundlePath: string): string {
   return absolute === null ? bundlePath : keyToHref(absolute);
 }
 
-// Build the nested render for a layout chain (outermost first). Each layer wraps
-// its `_layout.mdx` (or the built-in <DefaultLayout/>) in an OutletContext whose
-// value is the node one level inward — so `<Outlet/>` inside a layer renders the
-// next layer, and the innermost <Outlet/> renders the page (<PageView/>).
-//
-// `safe` picks the RENDERER for each layer, exactly as it does for entry bodies in
-// <PageView/> (R3-263). Before this, every layer went through <Include> whatever the wiki
-// declared — so an interpreter-mode wiki still EXECUTED author JavaScript out of its
-// `_layout.mdx`, and the non-executable guarantee had a hole in the shell rather than in
-// the entries. It is also what makes the chain work at all under dispatch: <Include>
-// evaluates an app-source module, which a layout resident in a content mount is not.
-function renderLayers(chain: string[], useDefault: boolean, safe: boolean): ReactNode {
-  let node: ReactNode = <PageView />;
-  if (useDefault) {
-    return <OutletContext.Provider value={node}><DefaultLayout /></OutletContext.Provider>;
-  }
-  for (let i = chain.length - 1; i >= 0; i--) {
-    const inner = node;
-    node = (
-      <OutletContext.Provider value={inner} key={chain[i]}>
-        {safe ? <SafeLayout layoutKey={chain[i]} /> : <Include filename={chain[i]} baseModule={module} />}
-      </OutletContext.Provider>
-    );
-  }
-  return node;
-}
-
 /**
  * The wiki itself: routing, chrome, and the entry render. Everything here reads the
  * content root, so it may only mount once that root is settled — which is why the
@@ -257,7 +221,7 @@ export default function GroveWiki({
   // one document, the non-executable proof page, whose whole point is planted code that
   // must NOT execute: on the compiled path that page doesn't just look wrong, it runs
   // (R3-252). A document that is only correct as data says so itself.
-  const safe: boolean = homeMeta?.render === 'safe' || meta?.render === 'safe';
+  const safe: boolean = resolveSafeRender(homeMeta, meta);
   const showRails = layout === 'doc' && !meta?.view;
 
 
@@ -289,14 +253,9 @@ export default function GroveWiki({
   // that decide how THIS entry renders — itself, home, its layouts, its `frame:` — are
   // read ahead of the rest, and the body waits for them: an unread row reads as
   // `render` unset, which is the executing path. The chrome around it stays mounted.
-  const scanGate = useContext(CorpusScanContext);
-  const critical = criticalKeys(entryKey, allMeta, scanGate.readFailure);
-  const criticalSig = critical.join('|');
-  useEffect(() => {
-    scanGate.prioritize(criticalSig.split('|'));
-  }, [scanGate, criticalSig]);
-  const pending = entryPending(critical, scanGate.isSettled, stylesheets.status);
-  const failure = criticalFailure(critical, scanGate.readFailure);
+  // R3-872: the entry gate (prioritize/pending/failure) and the safe derivation
+  // moved into GroveEntry's chain frame — GroveWiki keeps only what the chrome
+  // reads (navMode's root-layout lookup needs the chain's outermost key).
   const chain: string[] = layoutChainForKey(entryKey, allMeta);
   const frameNone = meta?.frame === 'none' || meta?.frame === false;
 
@@ -305,8 +264,6 @@ export default function GroveWiki({
   // same value through the shell). Undeclared or unknown → 'side', the arrangement
   // Grove has always shipped — never an unstyled page.
   const navMode = resolveNavMode(chain.length ? (allMeta[chain[0]!] as Record<string, unknown>) : undefined);
-  const useDefault = chain.length === 0 && !frameNone;
-
   // Every navigation starts at the top of the entry, except one aimed at a section. The
   // ref goes on `.device__scroll` below — the only thing on the page that scrolls.
   const scrollRef = useScrollReset(entryKey, hash);
@@ -372,6 +329,7 @@ export default function GroveWiki({
     missing,
     suggestion,
     directory,
+    stylesheetsStatus: stylesheets.status,
   };
 
   // The bundle scope handed to CONTENT (R3-174; MDX_FROM_MOUNT_SPEC §2, §7 1a).
@@ -486,7 +444,10 @@ export default function GroveWiki({
             </div>
           ) : null}
           <div className="grove-shell" data-nav={frameNone ? undefined : navMode}>
-            {failure ? <BootMessage>{failure}</BootMessage> : pending ? <BootMessage /> : renderLayers(chain, useDefault, safe)}
+            {/* R3-872: the entry region is GroveEntry — the chain, the gate and the
+                entry context (R3-871) live inside it, so a shell composing entries
+                directly renders the same thing (APP_CUSTOMIZATION §4.1). */}
+            <GroveEntry entryKey={entryKey} frame={frameNone ? 'none' : 'chain'} />
           </div>
         </div>
 
@@ -494,7 +455,7 @@ export default function GroveWiki({
         {drawerOpen ? (
           <Drawer
             siteTitle={siteTitle}
-            nav={navItems.map((n) => ({ href: n.href, label: n.label, cur: n.key === entryKey }))}
+            nav={navItems.map((n) => ({ key: n.key, href: n.href, label: n.label, cur: n.key === entryKey }))}
             onClose={() => setDrawerOpen(false)}
           />
         ) : null}

package/src/components/AssetImage.test.tsx

@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+// R3-871 — a relative asset src resolves against the entry context's entry
+// directory, not the URL. The URL routes home while the provider says the
+// subtree renders teams/engineering.mdx: the mount-relative path handed to
+// MountImage must start from engineering's directory.
+import { describe, it, expect, vi, 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';
+
+// The fs slice MountImage reads; the assertion target is the relPath it is
+// handed, so the double only needs to serve bytes.
+const readFile = vi.fn(async (relPath: string): Promise<Uint8Array> => {
+    void relPath;
+    return new Uint8Array([1]);
+  });
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (relPath: string) => readFile(relPath) },
+};
+
+const { default: AssetImage } = await import('./AssetImage');
+const { EntryContext } = await import('../hooks/useEntryKey');
+
+function host(children: ReactNode, entryKey?: string) {
+  const value = {
+    navigationState: { mode: 'present', sandboxPath: '/files/content/home.mdx', hash: '', search: '' },
+    routingSpec: { routes: [] },
+    filesMetadata: { '/app/content/home.mdx': { title: 'Home' } },
+  };
+  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('AssetImage — the base is the entry context (R3-871)', () => {
+  beforeEach(() => {
+    setContentRoot('/app/content/');
+    return () => resetContentRoot();
+  });
+
+  it('a relative src inside a non-routed entry resolves against that entry\'s directory', async () => {
+    await render(host(<AssetImage src="posters/ada.png" alt="Ada" />, '/app/content/teams/engineering.mdx'));
+    expect(readFile).toHaveBeenCalled();
+    const relPath = (readFile.mock.calls[0] as unknown[])[0] as string;
+    expect(relPath).toBe('/app/content/teams/posters/ada.png');
+  });
+
+  it('with no provider, the routed entry (home) is the base — the default preserved', async () => {
+    readFile.mockClear();
+    await render(host(<AssetImage src="posters/ada.png" alt="Ada" />));
+    const relPath = (readFile.mock.calls[0] as unknown[])[0] as string;
+    expect(relPath).toBe('/app/content/posters/ada.png');
+  });
+});

package/src/components/AssetImage.tsx

@@ -1,15 +1,16 @@
-import { useContext, useMemo } from 'react';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { useMemo } from 'react';
 import { MountImage } from '@immediately-run/sdk';
 import type { SandboxMount } from '@immediately-run/sdk';
-import { toFsPath } from '../lib/content';
+import { keyToFsPath } from '../lib/content';
 import { resolvePath } from '../lib/assetPath';
+import { useEntryKey } from '../hooks/useEntryKey';
 
 // MDX `img` override: display a mount-relative image by reading its bytes off the
 // sandbox fs (the opaque-origin iframe can't fetch a relative path). Resolves the
-// src relative to the entry currently being rendered (navigationState.sandboxPath),
-// then hands the file to the SDK's `MountImage`, which owns the read → object URL →
-// revoke lifecycle we used to hand-roll here.
+// src relative to the entry currently being rendered — the entry context's entry,
+// not the URL (R3-871: inside an included fragment or a layout, the URL names the
+// wrong base) — then hands the file to the SDK's `MountImage`, which owns the
+// read → object URL → revoke lifecycle we used to hand-roll here.
 
 // The whole sandbox fs, `/`-rooted. The resolved asset path is already absolute
 // (`/app/content/…`), so anchor at root and pass it as the mount-relative path
@@ -23,14 +24,13 @@ interface Props {
 }
 
 export default function AssetImage({ src = '', alt = '', className }: Props) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const { navigationState } = useContext(TinkerableContext) as any;
+  const entryKey = useEntryKey();
 
   const relPath = useMemo(() => {
     // The entry's absolute fs path (/app/content/...) is the base for relative assets.
-    const base = toFsPath(navigationState?.sandboxPath || '/');
+    const base = keyToFsPath(entryKey);
     return resolvePath(base, src).replace(/^\/+/, '');
-  }, [navigationState?.sandboxPath, src]);
+  }, [entryKey, src]);
 
   return (
     <MountImage

package/src/components/Backlinks.tsx

@@ -1,9 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useCallback, useContext, useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import fs from 'fs';
 import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
-import { isContentEntry, keyToFsPath, keyToHref, sandboxPathToKey } from '../lib/content';
+import { isContentEntry, keyToFsPath, keyToHref } from '../lib/content';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import { backlinkSnippet, bodyLinksTo, crumb, queryPaths } from '../lib/wiki';
 import InlineProse from './InlineProse';
 
@@ -15,8 +17,14 @@ interface Hit {
 // One linking entry: title + namespace crumb + the snippet around the link.
 function Row({ hit }: { hit: Hit }) {
   const meta = useFileMetadata(hit.key) as any;
+  const from = useEntryKey();
+  const follow = useFollowLink();
   return (
-    <Link href={keyToHref(hit.key)} className="grove-bl">
+    <Link
+      href={keyToHref(hit.key)}
+      className="grove-bl"
+      onClick={followLinkOnClick(follow, { key: hit.key, href: keyToHref(hit.key), from })}
+    >
       <div className="grove-bl__t">
         <InlineProse text={meta?.title || crumb(hit.key)} trimPeriod />
         <span className="crumb">/{crumb(hit.key)}</span>
@@ -29,8 +37,7 @@ function Row({ hit }: { hit: Hit }) {
 // `<Backlinks/>` — the signature wiki affordance: who links here. Reads sibling
 // entry bodies off the fs and scans for a link to the current entry.
 export default function Backlinks() {
-  const ctx = useContext(TinkerableContext) as any;
-  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const currentKey = useEntryKey();
 
   const allKeys = useCallback(
     (fm: Record<string, any>) => Object.keys(fm).filter(isContentEntry),

package/src/components/ChildPages.tsx

@@ -1,15 +1,16 @@
 /* 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 { contentDir, isContentEntry, keyToHref, sandboxPathToKey } from '../lib/content';
+import { contentDir, isContentEntry, keyToHref } from '../lib/content';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import { namespaceOf, queryPaths } from '../lib/wiki';
 
 // `<ChildPages/>` — the entries that live under the current entry's namespace, as
 // a compact nested list (e.g. everything in `handbook/` from the handbook index).
 export default function ChildPages() {
-  const ctx = useContext(TinkerableContext) as any;
-  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const currentKey = useEntryKey();
   const rel = currentKey.replace(contentDir(), '').replace(/\.mdx?$/, '');
   // The folder this entry indexes: its own slug if it's a section index, else its namespace.
   const scope = rel.replace(/\/?(index|home)$/, '');
@@ -26,12 +27,13 @@ export default function ChildPages() {
   );
   const q = useMetadataQuery(queryFn);
   const paths: string[] = queryPaths(q);
+  const follow = useFollowLink();
 
   if (!paths.length) return null;
   return (
     <div className="grove-doclist" data-shape="feed">
       {paths.map((p) => (
-        <Link key={p} href={keyToHref(p)} className="gdl-row">
+        <Link key={p} href={keyToHref(p)} className="gdl-row" onClick={followLinkOnClick(follow, { key: p, href: keyToHref(p), from: currentKey })}>
           <div className="gdl-row__t">{p.replace(contentDir(), '').replace(/\.mdx?$/, '').split('/').pop()}</div>
         </Link>
       ))}

package/src/components/Directory.tsx

@@ -3,6 +3,9 @@ import { useCallback } from 'react';
 import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
 import { contentDir, keyToHref } from '../lib/content';
 import { queryPaths } from '../lib/wiki';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 
 interface Props {
   team?: string;
@@ -15,11 +18,13 @@ function isPerson(m: any): boolean {
 
 function Row({ path, compact }: { path: string; compact?: boolean }) {
   const m = useFileMetadata(path) as any;
+  const from = useEntryKey();
+  const follow = useFollowLink();
   if (!m) return null;
   return (
     <tr>
       <td style={{ fontWeight: 600 }}>
-        <Link href={keyToHref(path)}>{m.name}</Link>
+        <Link href={keyToHref(path)} onClick={followLinkOnClick(follow, { key: path, href: keyToHref(path), from })}>{m.name}</Link>
       </td>
       <td>{m.role}</td>
       {!compact && <td>{m.team}</td>}

package/src/components/DirectoryList.tsx

@@ -1,8 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useContext } from 'react';
 import { Link, useAllMetadata } from '@immediately-run/sdk';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
-import { sandboxPathToKey } from '../lib/content';
+
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import {
   buildDirectoryRows,
   columnValue,
@@ -67,6 +68,8 @@ function Cell({ row, col }: { row: DirRow; col: DirColumn }) {
 
 function Row({ row, cols }: { row: DirRow; cols: DirColumn[] }) {
   const label = rowLabel(row);
+  const from = useEntryKey();
+  const follow = useFollowLink();
   return (
     <tr data-kind={row.kind}>
       <td className="gdir__name">
@@ -79,7 +82,11 @@ function Row({ row, cols }: { row: DirRow; cols: DirColumn[] }) {
           </span>
           <span className="gdir__labels">
             {row.href ? (
-              <Link href={row.href} className="gdir__link">
+              <Link
+                href={row.href}
+                className="gdir__link"
+                onClick={followLinkOnClick(follow, { key: row.key, href: row.href, from })}
+              >
                 {label}
               </Link>
             ) : (
@@ -111,12 +118,13 @@ function Row({ row, cols }: { row: DirRow; cols: DirColumn[] }) {
  * folder route rendering the stock table would be a half-override nobody could see.
  */
 export default function DirectoryList({ path, title, columns, sort = 'name', hidden }: Props) {
-  const ctx = useContext(TinkerableContext) as any;
-  const routeKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
-  // The route key is a FILE when it names an entry; a listing anchored at an entry means
+  const entryKey = useEntryKey();
+  // The entry this listing renders inside (an entry-context key, so an included
+  // fragment or a layout anchors where it renders, not where the URL points).
+  // It is a FILE when it names an entry; a listing anchored at an entry means
   // "the folder that entry lives in", which is what an author writing `<DirectoryList/>`
   // inside a page means by "here".
-  const fromDir = /\.mdx?$/.test(routeKey) ? routeKey.slice(0, routeKey.lastIndexOf('/')) : routeKey;
+  const fromDir = /\.mdx?$/.test(entryKey) ? entryKey.slice(0, entryKey.lastIndexOf('/')) : entryKey;
   const dirKey = resolveDirKey(path, fromDir);
 
   const listing = useDirectoryListing(dirKey);

package/src/components/DirectoryView.tsx

@@ -3,6 +3,8 @@ import { Fragment } from 'react';
 import type { ComponentType } from 'react';
 import { Link, useMDXComponents } from '@immediately-run/sdk';
 import { useShell } from '../lib/shell';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import { keyToHref } from '../lib/content';
 import { dirCrumbs, dirKeyToPath } from '../lib/directory';
 import DirectoryList from './DirectoryList';
@@ -30,6 +32,7 @@ const NO_OVERRIDES = {};
  */
 export default function DirectoryView() {
   const { entryKey, siteTitle } = useShell();
+  const follow = useFollowLink();
   const components = useMDXComponents(NO_OVERRIDES) as Record<string, ComponentType<any> | undefined>;
   const List = components.DirectoryList ?? DirectoryList;
 
@@ -41,11 +44,11 @@ export default function DirectoryView() {
       <div className="gp-main">
         <header className="grove-entry-header">
           <nav className="crumb">
-            <Link href="/">{siteTitle}</Link>
+            <Link href="/" onClick={followLinkOnClick(follow, { key: crumbs[0]?.key ?? '/', href: '/', from: entryKey })}>{siteTitle}</Link>
             {crumbs.slice(0, -1).map((c) => (
               <Fragment key={c.key}>
                 <span aria-hidden="true">/</span>
-                <Link href={keyToHref(c.key)}>{c.label}</Link>
+                <Link href={keyToHref(c.key)} onClick={followLinkOnClick(follow, { key: c.key, href: keyToHref(c.key), from: entryKey })}>{c.label}</Link>
               </Fragment>
             ))}
           </nav>

package/src/components/DocList.tsx

@@ -5,6 +5,9 @@ import { isContentEntry, keyToHref, slugToKey } from '../lib/content';
 import InlineProse from './InlineProse';
 import { queryPaths } from '../lib/wiki';
 import EntryImage from './EntryImage';
+import { useEntryKey } from '../hooks/useEntryKey';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 
 interface Props {
   shape?: 'feed' | 'grid';
@@ -29,9 +32,11 @@ function tagsOf(meta: any): string[] {
 // One entry as a feed row — reads its own frontmatter so the hook count is stable.
 function Row({ path }: { path: string }) {
   const meta = useFileMetadata(path) as any;
+  const from = useEntryKey();
+  const follow = useFollowLink();
   if (!meta) return <div className="gdl-row"><div className="sk sk-line" style={{ width: '50%' }} /></div>;
   return (
-    <Link href={keyToHref(path)} className="gdl-row">
+    <Link href={keyToHref(path)} className="gdl-row" onClick={followLinkOnClick(follow, { key: path, href: keyToHref(path), from })}>
       <div>
         <div className="gdl-row__t"><InlineProse text={meta.title || path} trimPeriod /></div>
         {meta.description && <div className="gdl-row__d"><InlineProse text={meta.description} /></div>}
@@ -52,9 +57,11 @@ function Row({ path }: { path: string }) {
 // unreadable. Degrade, never break.
 function CardTile({ path }: { path: string }) {
   const meta = useFileMetadata(path) as any;
+  const from = useEntryKey();
+  const follow = useFollowLink();
   if (!meta) return <div className="gdl-card"><div className="gdl-card__pic" /></div>;
   return (
-    <Link href={keyToHref(path)} className="gdl-card">
+    <Link href={keyToHref(path)} className="gdl-card" onClick={followLinkOnClick(follow, { key: path, href: keyToHref(path), from })}>
       <div className="gdl-card__pic">
         <EntryImage entryPath={path} src={meta.cover} alt="" className="gdl-card__cover" degrade={<span className="gdl-card__lattice" />} />
       </div>

package/src/components/Drawer.tsx

@@ -1,9 +1,13 @@
 import { Link } from '@immediately-run/sdk';
 import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import Sidebar from './Sidebar';
 import Icon from './Icon';
 
 interface NavItem {
+  /** The corpus key (R3-872 — the navigation policy's target names it). */
+  key: string;
   href: string;
   label: string;
   cur: boolean;
@@ -23,6 +27,7 @@ export default function Drawer({
   onClose: () => void;
 }) {
   const dialogRef = useOverlayFocusDismiss(true, onClose);
+  const follow = useFollowLink();
   return (
     <div className="grove-drawer" onClick={onClose}>
       <div
@@ -44,7 +49,15 @@ export default function Drawer({
         {nav.length ? (
           <nav className="grove-drawer__nav">
             {nav.map((n) => (
-              <Link key={n.href} href={n.href} data-cur={n.cur ? '1' : '0'} onClick={onClose}>
+              <Link
+                key={n.href}
+                href={n.href}
+                data-cur={n.cur ? '1' : '0'}
+                onClick={(e) => {
+                  followLinkOnClick(follow, { key: n.key, href: n.href })(e);
+                  onClose();
+                }}
+              >
                 {n.label}
               </Link>
             ))}