@immediately-run/grove 0.1.8 → 0.2.0

package/src/components/EntryBody.tsx

@@ -0,0 +1,138 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// `<EntryBody/>` — ONE entry's content region (R3-872, APP_CUSTOMIZATION §4.1):
+// the header (with its edit affordance), the body on the safe or compiled path
+// exactly as the stock page renders it, the metadata line and the tags. Carved
+// out of PageView so `GroveEntry` (and any shell composing several entries on one
+// page) renders the same thing the stock page does — there is one entry renderer.
+//
+// Reads the shell context NON-throwing (the stock page provides it; a bare
+// library-mode composition does not) and derives anything missing from the
+// entryKey itself — one derivation, two possible readers.
+import { useEffect, useState } from 'react';
+import { useContext } from 'react';
+import { Include, useFileMetadata } from '@immediately-run/sdk';
+import { GroveShellContext } from '../lib/shell';
+import { keyToInclude, homeKey } from '../lib/content';
+import { resolvePageLayout } from '../lib/layout';
+import { readingTime, stripFrontmatter } from '../lib/wiki';
+import { keyToFsPath } from '../lib/content';
+import { resolveSafeRender } from '../lib/renderMode';
+import { useEditAffordance } from '../hooks/useEditAffordance';
+import fs from 'fs';
+import EntryHeader from './EntryHeader';
+import SafeEntryBody from './SafeEntryBody';
+import ScrollToFragment from './ScrollToFragment';
+import Toc from './Toc';
+import Backlinks from './Backlinks';
+
+declare const module: any;
+
+/** The reading-time minutes for one entry — read the body once per entry.
+ *  `enabled` gates the read (hooks may not be conditional): the stock page's shell
+ *  computes `mins` once already, and a second read per navigation is the
+ *  double-read this flag exists to prevent (review round 1). */
+function useReadingTimeMins(entryKey: string, enabled: boolean): number {
+  const [mins, setMins] = useState(0);
+  useEffect(() => {
+    if (!enabled) return;
+    let active = true;
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setMins(0);
+    fs.promises
+      .readFile(keyToFsPath(entryKey), 'utf8')
+      .then((b: unknown) => {
+        if (active) setMins(readingTime(stripFrontmatter(String(b))));
+      })
+      .catch(() => undefined);
+    return () => {
+      active = false;
+    };
+  }, [entryKey, enabled]);
+  return mins;
+}
+
+export default function EntryBody({ entryKey }: { entryKey: string }) {
+  const sh = useContext(GroveShellContext);
+  const meta = useFileMetadata(entryKey) as any;
+  const homeMeta = useFileMetadata(homeKey()) as any;
+  // The shell's values win when present (the stock page derives them once);
+  // standalone, the same expressions run here.
+  const includePath = sh?.includePath ?? keyToInclude(entryKey);
+  const layout = sh?.layout ?? resolvePageLayout(meta);
+  const showRails = sh?.showRails ?? (layout === 'doc' && !meta?.view);
+  const safe = sh?.safe ?? resolveSafeRender(homeMeta, meta);
+  const vw = sh?.vw ?? 'desktop';
+  const localMins = useReadingTimeMins(entryKey, !sh); // the shell computes it on the stock page
+  const mins = sh?.mins ?? localMins;
+
+  return (
+    <article className="grove-page" data-layout={layout}>
+      <div className="gp-main">
+        {sh ? (
+          <EntryHeader
+            entryKey={entryKey}
+            writable={sh.writable}
+            mins={mins}
+            affordance={{ busy: sh.editBusy, refused: sh.editRefused, openEditor: sh.openEditor, hint: sh.editHint }}
+          />
+        ) : (
+          // Standalone (library mode): the header's affordance derives itself —
+          // the mount's live answer, exactly what the shell would have carried.
+          <StandaloneHeader entryKey={entryKey} 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.
+
+              `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).
+
+              R3-872: BOTH paths now carry the `data-entry` marker (the compiled path's
+              omission predates entry-scoped fragment resolution). On the compiled path
+              the marker is present while the body compiles — that reads as "scoped, not
+              yet found", and `resolveFragmentTarget`'s null-until-found is exactly the
+              wait the caller needs; the marker means "this subtree is entry X's region",
+              and an uncommitted body contains no fragment target to find, so the old
+              claim-too-early failure has no path to fire. */}
+          {safe ? (
+            <SafeEntryBody entryKey={entryKey} />
+          ) : (
+            <div className="grove-entry-body" key={entryKey} data-entry={entryKey}>
+              <Include filename={includePath} baseModule={module} />
+              <ScrollToFragment entryKey={entryKey} />
+            </div>
+          )}
+        </div>
+        {showRails ? <Backlinks /> : null}
+      </div>
+      {showRails && vw === 'desktop' ? <Toc entryKey={entryKey} /> : null}
+    </article>
+  );
+}
+
+/** The header for a shell-less composition: the edit affordance derives itself
+ *  from the live mount set (the hook only runs on this path — no double
+ *  subscription on the stock page). */
+function StandaloneHeader({ entryKey, mins }: { entryKey: string; mins: number }) {
+  const local = useEditAffordance(false);
+  return (
+    <EntryHeader
+      entryKey={entryKey}
+      writable={local.writable}
+      mins={mins}
+      affordance={{ busy: local.busy, refused: local.refused, openEditor: local.openEditor, hint: local.editHint }}
+    />
+  );
+}

package/src/components/EntryHeader.tsx

@@ -1,23 +1,36 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useFileMetadata } from '@immediately-run/sdk';
-import { useShell, EDIT_REFUSED_NOTICE } from '../lib/shell';
+import { EDIT_REFUSED_NOTICE } from '../lib/shell';
 import { crumb } from '../lib/wiki';
 import Icon from './Icon';
 import InlineProse from './InlineProse';
 
 // The entry's header block: breadcrumb, title (optional gradient), meta row
 // (date · reading time · tags) and the unobtrusive edit affordance. Rendered by
-// <PageView> at the top of every entry.
+// <EntryBody> at the top of every entry (R3-872) — on the stock page (inside
+// PageView inside the chain) and standalone, identically.
+export interface EntryHeaderAffordance {
+  busy: boolean;
+  refused: boolean;
+  openEditor: (entryKey: string) => void;
+  hint: string;
+}
+
 export default function EntryHeader({
   entryKey,
   writable,
   mins,
+  affordance,
 }: {
   entryKey: string;
   writable: boolean;
   mins: number;
+  /** The edit affordance's live state — R3-872: passed in (the shell's on the
+   *  stock page, self-derived standalone), never read off a context here, so the
+   *  header renders inside any entry composition. */
+  affordance: EntryHeaderAffordance;
 }) {
-  const { openEditor, editBusy, editRefused, editHint } = useShell();
+  const { openEditor, busy: editBusy, refused: editRefused, hint: editHint } = affordance;
   const meta = useFileMetadata(entryKey) as any;
   if (!meta) return null;
   const tags: string[] = Array.isArray(meta.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];

package/src/components/FamilyTree.tsx

@@ -1,9 +1,8 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useContext } from 'react';
 import { useMetadataQuery } from '@immediately-run/sdk';
 import type { Metadata } from '@immediately-run/sdk';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
-import { sandboxPathToKey } from '../lib/content';
+
+import { useEntryKey } from '../hooks/useEntryKey';
 import { familyTreeQuery } from '../lib/queries';
 import type { FamilyNodeRecord } from '../lib/queries';
 
@@ -20,8 +19,7 @@ interface Node {
 // literal: group hubs joined by hairline edges to their members. Genealogy
 // (`parent`/`house`) and org charts (`team`/`manager`) share the same rendering.
 export default function FamilyTree() {
-  const ctx = useContext(TinkerableContext) as any;
-  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const currentKey = useEntryKey();
 
   // Records, not tab-encoded paths (R3-276a).
   const q = useMetadataQuery<Metadata, FamilyNodeRecord>(familyTreeQuery);

package/src/components/GroveAgent.tsx

@@ -48,7 +48,7 @@ export default function GroveAgent({
   const catalog = useCatalog();
   const index = useAllMetadata();
   const headings = useHeadings(entryKey);
-  const activeHeading = useActiveHeading(headings);
+  const activeHeading = useActiveHeading(headings, entryKey);
   const { openEditor, editRefused } = useShell();
   const [open, setOpen] = useState(false);
   const [detent, setDetent] = useState<'half' | 'full'>('half');

package/src/components/GroveEntry.test.tsx

@@ -0,0 +1,200 @@
+// @vitest-environment jsdom
+// R3-872 (APP_CUSTOMIZATION_SPEC §4.1) — GroveEntry: one entry from a key.
+//   • frame 'none' renders the bare entry — header + body + metadata — with NO
+//     layout-chain wrapper;
+//   • frame 'chain' renders through the layout chain (the stock page's shape);
+//   • both publish the entry context (a WikiLink inside resolves relative to the
+//     entry, not the URL) and both carry the data-entry marker on the body
+//     region (§4.5's scoping contract, both render paths);
+//   • the stock page renders through GroveEntry with today's DOM landmarks.
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { CorpusScanContext } from '../lib/corpusScanContext';
+import type { CorpusScanGate } from '../lib/corpusScan';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (q: string) => ({ matches: false, media: q, addEventListener: () => {}, removeEventListener: () => {}, addListener: () => {}, removeListener: () => {}, dispatchEvent: () => false, onchange: null }),
+  });
+});
+
+// The fs double: entry bodies read through it. `render: safe` in the metadata keeps the
+// body on the interpreter path (the compiled evaluator only exists in the sandbox
+// bundler) — the marker assertions below pin the WRAPPER, which both paths mount.
+const { readFile } = vi.hoisted(() => ({ readFile: vi.fn() }));
+vi.mock('fs', () => ({ default: { promises: { readFile: (...a: unknown[]) => readFile(...a) } } }));
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: GroveEntry } = await import('./GroveEntry');
+const { default: GroveWiki } = await import('../GroveWiki');
+
+const ENTRY = '/app/content/wiki/a.mdx';
+const HOME = '/app/content/home.mdx';
+const LAYOUT = '/app/content/_layout.mdx';
+
+const NAV = {
+  mode: 'github',
+  namespace: 'immediately-run',
+  provider: 'github',
+  repository: 'corpus',
+  ref: 'main',
+  sandboxPath: ENTRY,
+  hash: '',
+  search: '',
+};
+
+const META = {
+  [ENTRY]: { title: 'Reference entry.', render: 'safe', date: '2026-06-22', tags: ['handbook'] },
+  [HOME]: { title: 'Home', render: 'safe' },
+  [LAYOUT]: { site: 'Fixture' },
+};
+
+beforeEach(() => {
+  readFile.mockReset();
+  readFile.mockImplementation(async (path: string) =>
+    // A layout carries <Outlet /> where the page goes (a layout body without one
+    // swallows the page — pre-existing harness behavior, not under test here).
+    path === LAYOUT
+      ? '---\nlayoutRole: root\n---\n\nCHAIN-MARKER\n\n<Outlet />\n'
+      : '---\ntitle: Reference entry.\nrender: safe\n---\n\nThe body text.\n',
+  );
+});
+
+const gateAll: CorpusScanGate = {
+  isSettled: () => true,
+  prioritize: () => undefined,
+  readFailure: () => null,
+};
+
+function mount(): { container: HTMLElement; root: Root } {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  return { container, root: createRoot(container) };
+}
+
+async function renderInto(root: Root, node: React.ReactNode) {
+  await act(async () => {
+    root.render(
+      <TinkerableContext.Provider
+        value={{ outerHref: 'https://immediately.run/x', navigationState: NAV, routingSpec: { routes: [] } as never, filesMetadata: META } as never}
+      >
+        <CorpusScanContext value={gateAll}>{node}</CorpusScanContext>
+      </TinkerableContext.Provider>,
+    );
+  });
+  for (let i = 0; i < 6; i++) await act(async () => {});
+}
+
+describe('GroveEntry (R3-872)', () => {
+  it("frame 'none' renders the bare entry — no layout chain, the landmarks intact", async () => {
+    const { container, root } = mount();
+    await renderInto(root, <GroveEntry entryKey={ENTRY} frame="none" />);
+    // the entry renders
+    const article = container.querySelector('article.grove-page');
+    expect(article).toBeTruthy();
+    expect(container.querySelector('.grove-entry-header h1')?.textContent).toContain('Reference entry');
+    expect(container.querySelector('.grove-tag')?.textContent).toBe('#handbook');
+    // no layout chain: no shell wrapper, no default-layout landmarks
+    expect(container.querySelector('.grove-shell')).toBeNull();
+    expect(container.textContent).not.toContain('CHAIN-MARKER');
+    // the body region carries the marker (the safe path — SafeEntryBody — and the
+    // compiled path's wrapper both carry it; here the safe path renders)
+    expect(container.querySelector('[data-entry]')).toBeTruthy();
+    expect(container.querySelector('[data-entry]')?.getAttribute('data-entry')).toBe(ENTRY);
+    await act(async () => root.unmount());
+  });
+
+  it("frame 'chain' renders the layout chain around the entry (the stock page's shape)", async () => {
+    // The chain's chrome reads the shell — the same shape GroveNav.test.tsx
+    // builds (a composer rendering 'chain' provides the shell; the stock page
+    // is exactly that).
+    const { GroveShellContext } = await import('../lib/shell');
+    const shell = {
+      siteTitle: 'Fixture',
+      navItems: [],
+      entryKey: ENTRY,
+      vw: 'desktop',
+      navMode: 'top',
+      writable: false,
+      openEditor: () => {},
+      editBusy: false,
+      editRefused: false,
+      editHint: '',
+      // PageView's page-level states read these (the shell owns them).
+      directory: { status: 'none' },
+      missing: false,
+      suggestion: undefined,
+      mins: 0,
+      safe: true,
+      includePath: '/app/content/wiki/a.mdx',
+      layout: 'doc',
+      showRails: false,
+    };
+    const { container, root } = mount();
+    await act(async () => {
+      root.render(
+        <TinkerableContext.Provider
+          value={{ outerHref: 'https://immediately.run/x', navigationState: NAV, routingSpec: { routes: [] } as never, filesMetadata: META } as never}
+        >
+          <CorpusScanContext value={gateAll}>
+            <GroveShellContext.Provider value={shell as never}>
+              <GroveEntry entryKey={ENTRY} frame="chain" />
+            </GroveShellContext.Provider>
+          </CorpusScanContext>
+        </TinkerableContext.Provider>,
+      );
+    });
+    for (let i = 0; i < 6; i++) await act(async () => {});
+    // the chain's own evidence (the mocked layout carries the marker text
+    // around its <Outlet/>) + the entry inside it
+    expect(container.textContent).toContain('CHAIN-MARKER');
+    const article = container.querySelector('article.grove-page');
+    expect(article).toBeTruthy();
+    expect(container.querySelector('.grove-entry-header h1')?.textContent).toContain('Reference entry');
+    expect(container.querySelector('[data-entry]')?.getAttribute('data-entry')).toBe(ENTRY);
+    await act(async () => root.unmount());
+  });
+
+  it('the compiled path carries the marker too (§4.5: both render paths, so fragment scoping never falls document-wide on a multi-entry page)', async () => {
+    // render: safe removed from the entry's metadata → the compiled branch. The
+    // marker sits on EntryBody's wrapper div, mounted before <Include> resolves —
+    // the marker means "this region belongs to entry X"; a fragment not yet in it
+    // reads as not-found and the caller keeps waiting (the commit-timing rule).
+    const metaCompiled = { ...META, [ENTRY]: { title: 'Reference entry.', date: '2026-06-22', tags: ['handbook'] } };
+    const { container, root } = mount();
+    await act(async () => {
+      root.render(
+        <TinkerableContext.Provider
+          value={{ outerHref: 'https://immediately.run/x', navigationState: NAV, routingSpec: { routes: [] } as never, filesMetadata: metaCompiled } as never}
+        >
+          <CorpusScanContext value={gateAll}>
+            <GroveEntry entryKey={ENTRY} frame="none" />
+          </CorpusScanContext>
+        </TinkerableContext.Provider>,
+      );
+    });
+    for (let i = 0; i < 6; i++) await act(async () => {});
+    const marked = container.querySelector('[data-entry]');
+    expect(marked?.getAttribute('data-entry')).toBe(ENTRY);
+    await act(async () => root.unmount());
+  });
+
+  it('the stock page renders through GroveEntry with the same DOM landmarks (content/home.mdx)', async () => {
+    const { container, root } = mount();
+    await renderInto(root, <GroveWiki />);
+    // the landmarks every reader path depends on: shell, the article, header,
+    // prose, the marker naming the rendered entry
+    expect(container.querySelector('.grove-shell')).toBeTruthy();
+    expect(container.querySelector('article.grove-page')).toBeTruthy();
+    expect(container.querySelector('.grove-entry-header')).toBeTruthy();
+    expect(container.querySelector('.grove-prose')).toBeTruthy();
+    const marked = container.querySelector('[data-entry]');
+    expect(marked?.getAttribute('data-entry')).toBe(ENTRY);
+    await act(async () => root.unmount());
+  });
+});

package/src/components/GroveEntry.tsx

@@ -0,0 +1,108 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// `<GroveEntry/>` — one entry from a key (APP_CUSTOMIZATION_SPEC §4.1, R3-872):
+// the header with its edit affordance, the body on the safe or compiled path
+// exactly as the stock page renders it, the metadata line and the tags, with
+// `frame: 'chain' | 'none'` — 'chain' renders through the layout chain (the
+// stock page's shape), 'none' renders the bare entry for shells composing
+// several entries on one page. Either way it PUBLISHES the entry context, so
+// everything inside resolves relative links and anchors against THIS entry
+// (R3-871), and the fragment/heading scopes find its body (§4.5).
+//
+// The stock page renders through GroveEntry fed by the route key — one entry
+// renderer, no fork.
+
+import { useContext, useEffect } from 'react';
+import type { ReactNode } from 'react';
+import { Include, useAllMetadata, useFileMetadata } from '@immediately-run/sdk';
+import { EntryContext } from '../hooks/useEntryKey';
+import { layoutChainForKey } from '../lib/layout';
+import { criticalKeys } from '../lib/criticalKeys';
+import { criticalFailure, entryPending } from '../lib/entryGate';
+import { CorpusScanContext } from '../lib/corpusScanContext';
+import { homeKey } from '../lib/content';
+import { resolveSafeRender } from '../lib/renderMode';
+import BootMessage from './BootMessage';
+import DefaultLayout from './DefaultLayout';
+import SafeLayout from './SafeLayout';
+import PageView from './PageView';
+import EntryBody from './EntryBody';
+import { GroveShellContext, OutletContext } from '../lib/shell';
+
+declare const module: any;
+
+// 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
+// <EntryBody/> (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 'chain' frame: the entry inside its layout chain, with the entry gate
+ *  (critical-file scan) waiting the body until its render inputs are read. */
+function EntryFrame({ entryKey }: { entryKey: string }) {
+  const meta = useFileMetadata(entryKey) as any;
+  const homeMeta = useFileMetadata(homeKey()) as any;
+  const allMeta = useAllMetadata() as Record<string, Record<string, unknown>>;
+  // Interpreter mode (TRUST_MODES §5 / R3-213) — the decision lives in ONE
+  // module (lib/renderMode.ts): the chain renderer, the body renderer and the
+  // shell's `safe` field must never disagree.
+  const safe: boolean = resolveSafeRender(homeMeta, meta);
+  const chain: string[] = layoutChainForKey(entryKey, allMeta);
+  const frameNone = meta?.frame === 'none' || meta?.frame === false;
+  const useDefault = chain.length === 0 && !frameNone;
+
+  // ── The entry gate (MDX_FROM_MOUNT_SPEC D8) ────────────────────────────────
+  // The files 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. The prioritize effect lives HERE now (moved with the gate) —
+  // the shell carries the stylesheets' read state (wiki-wide), 'ready' standalone.
+  const scanGate = useContext(CorpusScanContext);
+  const sheets = useContext(GroveShellContext)?.stylesheetsStatus ?? 'ready';
+  const critical = criticalKeys(entryKey, allMeta, scanGate.readFailure);
+  const criticalSig = critical.join('|');
+  useEffect(() => {
+    scanGate.prioritize(criticalSig.split('|'));
+  }, [scanGate, criticalSig]);
+  const pending = entryPending(critical, scanGate.isSettled, sheets);
+  const failure = criticalFailure(critical, scanGate.readFailure);
+
+  return <>{failure ? <BootMessage>{failure}</BootMessage> : pending ? <BootMessage /> : renderLayers(chain, useDefault, safe)}</>;
+}
+
+export default function GroveEntry({
+  entryKey,
+  frame = 'chain',
+}: {
+  entryKey: string;
+  /** 'chain' (default): the entry inside its layout chain — the stock page's
+   *  shape. 'none': the bare entry (header + body + rails), for shells that
+   *  compose several entries on one page. */
+  frame?: 'chain' | 'none';
+}) {
+  return (
+    <EntryContext.Provider value={{ entryKey }}>
+      {frame === 'none' ? <EntryBody entryKey={entryKey} /> : <EntryFrame entryKey={entryKey} />}
+    </EntryContext.Provider>
+  );
+}

package/src/components/GroveFooter.tsx

@@ -1,15 +1,18 @@
 import { Link } from '@immediately-run/sdk';
 import { useShell } from '../lib/shell';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 
 // `<GroveFooter/>` — the site footer. Import-free in MDX; reads the nav items from
 // the shell context so a layout just places `<GroveFooter/>`.
 export default function GroveFooter() {
-  const { navItems } = useShell();
+  const { navItems, entryKey } = useShell();
+  const follow = useFollowLink();
   return (
     <footer className="grove-footer">
       <div className="grove-footer__links">
         {navItems.slice(0, 4).map((n) => (
-          <Link key={n.key} href={n.href}>
+          <Link key={n.key} href={n.href} onClick={followLinkOnClick(follow, { key: n.key, href: n.href, from: entryKey })}>
             {n.label}
           </Link>
         ))}

package/src/components/GroveNav.tsx

@@ -1,6 +1,9 @@
 import { Link } from '@immediately-run/sdk';
 import { useShell, EDIT_REFUSED_NOTICE } from '../lib/shell';
 import { getContentRoot } from '../lib/contentRoot';
+import { homeKey } from '../lib/content';
+import { useFollowLink } from '../hooks/useFollowLink';
+import { followLinkOnClick } from '../lib/navigationPolicy';
 import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
 import { THEMES } from '../data/themes';
 import Icon from './Icon';
@@ -27,6 +30,7 @@ export default function GroveNav() {
     setSearchOpen,
     setDrawerOpen,
   } = useShell();
+  const follow = useFollowLink();
 
   const askGrove = () => {
     const el = (document.querySelector('.ga-foot input') || document.querySelector('.ga-line input')) as HTMLElement | null;
@@ -64,13 +68,18 @@ export default function GroveNav() {
       <button className="grove-hamburger icbtn" aria-label="Menu" onClick={() => setDrawerOpen(true)}>
         <Icon name="list" />
       </button>
-      <Link href="/" className="grove-brand">
+      <Link href="/" className="grove-brand" onClick={followLinkOnClick(follow, { key: homeKey(), href: '/', from: entryKey })}>
         <span className="tile" style={{ background: 'var(--grad)' }} />
         {siteTitle}
       </Link>
       <div className="grove-nav__links">
         {navItems.map((n) => (
-          <Link key={n.key} href={n.href} data-cur={n.key === entryKey ? '1' : '0'}>
+          <Link
+            key={n.key}
+            href={n.href}
+            data-cur={n.key === entryKey ? '1' : '0'}
+            onClick={followLinkOnClick(follow, { key: n.key, href: n.href, from: entryKey })}
+          >
             {n.label}
           </Link>
         ))}

package/src/components/PageMeta.tsx

@@ -1,14 +1,12 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useContext } from 'react';
 import { useFileMetadata } from '@immediately-run/sdk';
-import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
-import { sandboxPathToKey } from '../lib/content';
+
+import { useEntryKey } from '../hooks/useEntryKey';
 
 // `<PageMeta/>` — the current entry's date + tags as a styled strip, for authors
 // who want the meta inside the body (the entry header already renders one).
 export default function PageMeta() {
-  const ctx = useContext(TinkerableContext) as any;
-  const key = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const key = useEntryKey();
   const meta = useFileMetadata(key) as any;
   if (!meta) return null;
   const tags: string[] = Array.isArray(meta.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];