@immediately-run/grove 0.1.5 → 0.1.8

package/src/components/GroveAgent.tsx

@@ -15,18 +15,22 @@ import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
 import { getContentRoot } from '../lib/contentRoot';
 import { createReadEntryTool, createGroveMetadataTool, groveAgentTools, toolExecutor } from '../lib/agentTools';
 import { buildSystemPrompt } from '../lib/agentPrompt';
-import { computeReachRows, reachChips, showEgressDisclosure, EGRESS_DISCLOSURE } from '../lib/reachCard';
+import { computeReachRows, reachChips, sourceTrustLine, stateWord, showEgressDisclosure, EGRESS_DISCLOSURE, UNGRANTED_CHAT_CAUSE, READING_WORKS_NORMAL } from '../lib/reachCard';
+import { getCorpusMountId } from '../lib/contentRoot';
 import { transcriptToRows, toolActivityLine, type AgentRow } from '../lib/agentTranscript';
+import { useCatalogAnswered } from '../hooks/useCatalogAnswered';
 import { safeSources } from '../lib/safeSources';
 import Icon from './Icon';
 
 // `.grove-agent` — Grove's own embedded agent (GROVE_AGENT_SPEC).
 //
 // The surface is a FUNCTION of the session's envelope (R-GA-1): the reach card in
-// the expanded header is computed from the provider three-state, the `llm:chat`
-// grant (the grant-filtered catalog), mount writability, and source trust — never
-// hand-written copy. The loop rides the workbench's seam — SDK `runAgent` over the
-// host `llm.chat` slot — and its two tools are the mount-chrooted `read_entry` and
+// the expanded header is computed from the provider four-state (R3-688 added the
+// host-marked `ungranted` — the distinct not-granted cause), the `llm:chat`
+// grant (the grant-filtered catalog), mount writability, the corpus packaging,
+// tools support, and source trust — never hand-written copy. The loop rides the
+// workbench's seam — SDK `runAgent` over the host `llm.chat` slot — and its two
+// tools are the mount-chrooted `read_entry` and
 // the index query (R-GA-2). The widget never writes (R-GA-3): every change is a
 // hand-off to the editor / workbench. Read-only never blocks Q&A (R-GA-5). When a
 // provider is bound the egress line is shown unconditionally (R-GA-6). Every
@@ -66,12 +70,40 @@ export default function GroveAgent({
   // catalog iff this app holds the consent — an ungranted fork reads a DISTINCT
   // cause from a user without a key (G-GA-10).
   const chatGranted = catalog.some((m) => m.name === 'llm:chat');
+  // Distinguishes "granted nothing" from "has not replied yet" — `catalog` alone cannot,
+  // because an empty catalog is a legitimate answer. See the hook for how it is derived.
+  const catalogAnswered = useCatalogAnswered();
   const context = useAgentContext({ entryPath: entryKey, entryTitle, heading: activeHeading || undefined });
+  // G-GA-8: a provider without `features.tools` degrades to context-stuffing.
+  // Computed ONCE at render scope — the reach card's Q&A qualifier (R3-752) and the
+  // ask() path below read the same fact, never two computations of it.
+  const toolsSupported = providerState.status === 'configured' && providerState.provider.features.tools === true;
   const reachRows = useMemo(
-    () => computeReachRows({ providerState, chatGranted, writable, sourceShared: context.sourceShared }),
-    [providerState, chatGranted, writable, context.sourceShared],
+    () =>
+      computeReachRows({
+        providerState,
+        chatGranted,
+        catalogAnswered,
+        writable,
+        sourceShared: context.sourceShared,
+        mountId: getCorpusMountId(),
+        toolsSupported,
+      }),
+    [providerState, chatGranted, catalogAnswered, writable, context.sourceShared, toolsSupported],
   );
   const chips = useMemo(() => reachChips(reachRows), [reachRows]);
+  const trustLine = useMemo(
+    () => sourceTrustLine(context.sourceShared, context.sourceSharedBasis),
+    [context.sourceShared, context.sourceSharedBasis],
+  );
+  // R-IX-7 (R3-752): a state flip is ANNOUNCED, not only re-rendered — one standing
+  // polite live region whose text is the card's computed summary. A grant flip
+  // changes the text, which is what a status region announces; the visually hidden
+  // per-row words are static text and announce nothing.
+  const reachAnnouncement = useMemo(
+    () => `What the agent can do here: ${reachRows.map((r) => `${r.label} — ${stateWord(r.state)}`).join('; ')}`,
+    [reachRows],
+  );
   const canAsk = providerState.status === 'configured' && chatGranted;
 
   // Read at CALL time (a scan may land, the reader may navigate) — refs kept fresh
@@ -121,8 +153,8 @@ export default function GroveAgent({
 
     // G-GA-8: a provider without `features.tools` degrades to context-stuffing —
     // the deixis block, an index summary, and the current entry body ride the
-    // prompt; the request carries ZERO tools.
-    const toolsSupported = providerState.status === 'configured' && providerState.provider.features.tools === true;
+    // prompt; the request carries ZERO tools. The same hoisted fact the reach
+    // card's Q&A qualifier reads (R3-752) — computed once at render scope.
     const chroot = getContentRoot();
     const currentKey = entryRef.current;
     const contextBlock = renderAgentContext({
@@ -204,8 +236,10 @@ export default function GroveAgent({
         code === 'auth-required'
           ? 'no model key connected — add one in Settings'
           : code === 'forbidden'
-            ? "this Grove wasn't granted chat — reading works as normal"
-            : 'the model or backend errored — try again in a moment',
+            ? UNGRANTED_CHAT_CAUSE
+            : code === 'cancelled'
+              ? `chat didn't start — ${READING_WORKS_NORMAL}; you can try again anytime`
+              : 'the model or backend errored — try again in a moment',
       );
       setRows((prev) =>
         prev.length && prev[prev.length - 1].kind === 'assistant' && !prev[prev.length - 1].text ? prev.slice(0, -1) : prev,
@@ -271,18 +305,44 @@ export default function GroveAgent({
                 </span>
               </div>
 
-              {/* The reach card — the envelope, computed (R-GA-1). */}
+              {/* The reach card — the envelope, computed (R-GA-1). State is text as
+                  well as glyph (R3-752): the hidden word beside the mark keeps the
+                  card from reading as four identical lines to a screen reader. */}
               <div className="ga-reach" role="list" aria-label="What the agent can do here">
                 {reachRows.map((r) => (
                   <div className={`ga-reach__row ga-reach__row--${r.state}`} role="listitem" key={r.key}>
                     <span className="ga-reach__mark" aria-hidden>
-                      {r.state === 'ok' ? '✓' : r.state === 'blocked' ? '✗' : '·'}
+                      {r.state === 'ok' ? '✓' : r.state === 'blocked' ? '✗' : r.state === 'elsewhere' ? '→' : '·'}
                     </span>
+                    <span className="ga-reach__stateword">{stateWord(r.state)}</span>
                     <span className="ga-reach__label">{r.label}</span>
                     {r.cause && <span className="ga-reach__cause">{r.cause}</span>}
+                    {r.destination && <span className="ga-reach__cause">{`→ ${r.destination}`}</span>}
+                    {r.action === 'enable-chat' && (
+                      // R3-790: the earning affordance. Its click invokes ask() — the
+                      // ungranted llm:chat invoke fires the HOST's consent dialog on this
+                      // same activation (site-main#612), Allow mints + lifts, and the
+                      // same ask proceeds to stream. A decline answers 'cancelled' (the
+                      // catch below) and the row stays honestly ✗.
+                      <button
+                        type="button"
+                        className="ga-reach__enable"
+                        onClick={() =>
+                          void ask(draft.trim() || 'Answer in one sentence: what can you tell me about this wiki?')
+                        }
+                      >
+                        Enable chat
+                      </button>
+                    )}
                   </div>
                 ))}
               </div>
+              {trustLine && <p className="ga-egress">{trustLine}</p>}
+              {/* The standing live region (R-IX-7): the computed card summary, so a
+                  state flip is announced politely and not only re-rendered. */}
+              <div className="ga-reach__stateword" role="status">
+                {reachAnnouncement}
+              </div>
               {showEgressDisclosure(providerState) && <p className="ga-egress">{EGRESS_DISCLOSURE}</p>}
               {errorToast && (
                 <div className="ga-toast" role="status">

package/src/components/GroveAgent.unanswered.test.tsx

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+// ONE case, in its own file, because it needs a module registry where the catalog has
+// never been answered.
+//
+// `useCatalogAnswered`'s flag is module-global and never resets — correct for an app, in
+// which the host answers once per realm, but it means any test that has already pushed an
+// `api-catalog` poisons this one. Every case in `GroveAgent.test.tsx` pushes one. Vitest
+// isolates by file, so a separate file IS the isolation; the harness is shared rather
+// than copied (`src/test/groveAgentHarness.tsx`).
+//
+// Why this case exists at all: round 3 showed the hook was not load-bearing for any
+// component test — replacing `useCatalogAnswered()` with the literal `true`, i.e. exactly
+// the behaviour the hook was written to replace, left all 506 tests green. The unit arm
+// (`reachCard.test.ts`) and the hook itself were covered; the wire between them was not.
+// That is round 1's blocking finding recurring one level up.
+import { describe, it, expect, vi } from 'vitest';
+
+// `useHeadings` scans the DOM; `fs` is read only on the stuffing path, never here.
+vi.mock('fs', () => ({ default: { promises: { readFile: vi.fn(async () => '') } } }));
+vi.mock('@immediately-run/sdk', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@immediately-run/sdk')>()),
+  runAgent: vi.fn(),
+}));
+
+const { renderAgent, openPanel, push } = await import('../../test/groveAgentHarness');
+
+describe('R3-688 — before the catalog answers, the Q&A row names no cause', () => {
+  it('renders neutral: not a guessed consent state, not a guessed key state, no chips', async () => {
+    // No catalog push at all. The provider HAS answered `{ provider: null }`, which on a
+    // pre-mark host is what both a keyless frame and an ungranted fork receive — so the
+    // grant is genuinely unknown and the card must say nothing rather than pick one.
+    const { container } = await renderAgent({ writable: true });
+    await push({ type: 'llm-provider', provider: null });
+    await openPanel(container);
+    const text = container.textContent ?? '';
+
+    expect(text).toContain('Answer questions about this wiki');
+    expect(text).not.toContain("wasn't granted chat");
+    expect(text).not.toContain('no model key connected');
+    // No Q&A chips. Not "no chips at all": `writable: true` makes the Draft row ✓ and it
+    // contributes its own, which is correct and has nothing to do with the catalog.
+    const chips = [...container.querySelectorAll('.ga-chip')].map((c) => c.textContent ?? '');
+    expect(chips.some((c) => /summarize|tagged security/i.test(c))).toBe(false);
+  });
+});

package/src/components/PageView.tsx

@@ -3,6 +3,7 @@ import { Include, Link } from '@immediately-run/sdk';
 import { useShell, EDIT_REFUSED_NOTICE } from '../lib/shell';
 import { keyToHref, keyToRepoRel } from '../lib/content';
 import { crumb } from '../lib/wiki';
+import { useHeadingFragmentUrl } from '../hooks/useHeadingFragmentUrl';
 import DirectoryView from './DirectoryView';
 import EntryHeader from './EntryHeader';
 import SafeEntryBody from './SafeEntryBody';
@@ -22,6 +23,11 @@ export default function PageView() {
   const { entryKey, includePath, layout, showRails, mins, missing, suggestion, writable, openEditor, editBusy, editRefused, editHint, vw, safe, directory } =
     useShell();
 
+  // 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
+  // address bar (`useHeadingFragmentUrl` for the whole story).
+  useHeadingFragmentUrl();
+
   // A folder URL. `checking` renders nothing rather than the 404: the readdir that
   // decides between them is one RPC away, and a 404 that appears and then turns into a
   // listing reads as a broken link that healed itself.

package/src/hooks/useCatalogAnswered.late.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+// The LATE-IMPORT case, in its own file because it is the one ordering the sibling suite
+// cannot produce: the host answers BEFORE this module is evaluated.
+//
+// grove is published as a pinned library (`src/lib.ts`), so "imported before any render"
+// is an assumption about one embedding, not a guarantee. If the subscribe-time call is
+// discarded with a blanket reset, a host that already answered is invisible for the
+// realm's life — and because the host does not push again, nothing corrects it.
+//
+// This file exists because round 3's own fix was untested: replacing
+// `answered = catalog.length > 0` with `answered = false` — i.e. the blanket reset the
+// fix replaced — left the whole suite green. A fix with no failing case is a guess.
+import { describe, it, expect, vi } from 'vitest';
+
+type Handler = (msg: Record<string, unknown>) => void;
+const handlers = new Set<Handler>();
+const emit = (msg: Record<string, unknown>): void => {
+  for (const h of handlers) h(msg);
+};
+
+(globalThis as { __immediatelyRun__?: unknown }).__immediatelyRun__ = {
+  transport: {
+    sendMessage: vi.fn(),
+    protocolRequest: vi.fn(async () => ({})),
+    onMessage: (handler: Handler) => {
+      handlers.add(handler);
+      return { dispose: () => handlers.delete(handler) };
+    },
+  },
+};
+
+describe('useCatalogAnswered, imported AFTER the host answered', () => {
+  it('reads a non-empty catalog at subscribe as proof the answer landed', async () => {
+    // Start and answer the channel through the SDK directly, with the hook module not yet
+    // imported — the ordering a late-mounting library consumer produces.
+    const { getCatalog } = await import('@immediately-run/sdk');
+    getCatalog();
+    emit({ type: 'api-catalog', methods: [{ name: 'llm:chat', capability: 'llm:chat', stream: true }] });
+
+    // NOW import. The listener's synchronous subscribe-time call carries the answered
+    // catalog; a blanket reset would throw it away and the flag would be false forever.
+    const { useCatalogAnswered } = await import('./useCatalogAnswered');
+
+    const { act } = await import('react');
+    const { createRoot } = await import('react-dom/client');
+    const seen: boolean[] = [];
+    const Probe = () => {
+      seen.push(useCatalogAnswered());
+      return null;
+    };
+    const root = createRoot(document.createElement('div'));
+    await act(async () => {
+      root.render(<Probe />);
+    });
+
+    expect(seen[seen.length - 1]).toBe(true);
+    await act(async () => root.unmount());
+  });
+});

package/src/hooks/useCatalogAnswered.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+// `useCatalogAnswered` — rendered in a real React tree, driven through the SDK's REAL
+// catalog push channel against an emitting stub transport. The whole point of the hook is
+// a timing property of that channel, so a mock of either would assert nothing.
+//
+// The property under test: the push channel has no value-equality check, so a host answer
+// of `[]` — identical to the initial value — still notifies. That second notification is
+// the signal. A test that only pushed a NON-empty catalog would pass against a naive
+// `catalog.length > 0` implementation and prove nothing, which is why the empty-answer
+// case is the one that carries this file.
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+type Handler = (msg: Record<string, unknown>) => void;
+const handlers = new Set<Handler>();
+const emit = (msg: Record<string, unknown>): void => {
+  for (const h of handlers) h(msg);
+};
+
+// Installed BEFORE the SDK is imported: the channel resolves its transport lazily, and
+// the hook module subscribes at import time.
+(globalThis as { __immediatelyRun__?: unknown }).__immediatelyRun__ = {
+  transport: {
+    sendMessage: vi.fn(),
+    protocolRequest: vi.fn(async () => ({})),
+    onMessage: (handler: Handler) => {
+      handlers.add(handler);
+      return { dispose: () => handlers.delete(handler) };
+    },
+  },
+};
+
+let useCatalogAnswered: typeof import('./useCatalogAnswered').useCatalogAnswered;
+let getCatalog: typeof import('@immediately-run/sdk').getCatalog;
+
+beforeAll(async () => {
+  ({ useCatalogAnswered } = await import('./useCatalogAnswered'));
+  ({ getCatalog } = await import('@immediately-run/sdk'));
+});
+
+/** Render a probe recording the hook's value on every render. */
+const renderProbe = async () => {
+  const seen: boolean[] = [];
+  const Probe = () => {
+    seen.push(useCatalogAnswered());
+    return null;
+  };
+  const root = createRoot(document.createElement('div'));
+  await act(async () => {
+    root.render(<Probe />);
+  });
+  return { seen, unmount: () => act(async () => root.unmount()) };
+};
+
+describe('useCatalogAnswered', () => {
+  it('is false before the host answers — the subscribe-time call is not an answer', async () => {
+    // `onCatalogChange` invokes its listener once, SYNCHRONOUSLY, with the current value
+    // when you subscribe. If that counted, the flag would be true from module load and
+    // the reach card would read an unanswered catalog as "not granted" — the exact defect
+    // this hook exists to prevent.
+    getCatalog(); // start the channel the way the app does
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(false);
+    await unmount();
+  });
+
+  it('an EMPTY catalog answer flips it, and RE-RENDERS — an empty answer is still an answer', async () => {
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(false);
+    const before = seen.length;
+
+    await act(async () => {
+      emit({ type: 'api-catalog', methods: [] });
+    });
+
+    // Both halves matter: a hook that returned the flag without subscribing would show
+    // the right value only on the NEXT unrelated render.
+    expect(seen.length).toBeGreaterThan(before);
+    expect(seen[seen.length - 1]).toBe(true);
+    await unmount();
+  });
+
+  it('stays true for a probe mounted after the answer', async () => {
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(true);
+    await unmount();
+  });
+});

package/src/hooks/useCatalogAnswered.ts

@@ -0,0 +1,73 @@
+import { useSyncExternalStore } from 'react';
+import { onCatalogChange } from '@immediately-run/sdk';
+
+// Has the host actually ANSWERED the grant-filtered method catalog?
+//
+// `useCatalog()` starts `[]` and an empty catalog is a legitimate answer (a frame granted
+// nothing), so the value alone cannot distinguish "granted nothing" from "has not replied
+// yet". The reach card needs that distinction: `!chatGranted` is true in both cases, and
+// reading it as "not granted" before the host has spoken claims a consent state about a
+// frame that may well hold the grant (grove#75 round 1).
+//
+// It is derivable here with no SDK change, because the push channel has **no
+// value-equality check**: every host push notifies subscribers, including one whose value
+// equals the initial `[]`. So a notification after the subscribe means the host replied.
+//
+// THE SUBSCRIBE-TIME CALL. `onCatalogChange` invokes the listener once, SYNCHRONOUSLY,
+// with the current value before returning. That call is the subscribe, not an answer — but
+// it is not worthless either, and an earlier version of this file threw it away with a
+// blanket reset. A NON-EMPTY catalog at subscribe can only have come from the host, so it
+// is proof the answer already landed. Reading it that way is what makes this correct when
+// the module is evaluated LATE: grove is also published as a pinned library
+// (`src/lib.ts`), so "imported before any render" is an assumption about one embedding,
+// not a guarantee (grove#75 round 3).
+//
+// RESIDUALS, stated rather than implied:
+//  - a host that answers `[]` BEFORE this module is evaluated is indistinguishable from
+//    one that has not answered, and leaves the flag false for the realm's life. The Q&A
+//    row then stays neutral rather than naming a cause — the same honest "we have not been
+//    told" that the provider channel's `unknown` already renders, but it will not
+//    self-correct, because the host does not push again;
+//  - a host that never answers at all leaves it false forever, for the same reason;
+//  - importing this module is what STARTS the catalog channel and sends
+//    `REQUEST_API_CATALOG`. That used to be the first `useCatalog()` render. The channel
+//    starts at most once and the poll is idempotent, but the timing moved.
+let answered = false;
+let subscribing = true;
+const waiters = new Set<() => void>();
+
+onCatalogChange((catalog) => {
+  if (subscribing) {
+    // Synchronous, at subscribe: the current value, not an answer — except that a
+    // non-empty catalog could only have come from the host.
+    answered = catalog.length > 0;
+    return;
+  }
+  if (answered) return;
+  answered = true;
+  for (const w of waiters) w();
+});
+subscribing = false;
+
+const subscribe = (onStoreChange: () => void): (() => void) => {
+  waiters.add(onStoreChange);
+  return () => {
+    waiters.delete(onStoreChange);
+  };
+};
+const getSnapshot = (): boolean => answered;
+
+/**
+ * Whether the host has answered the method catalog. Re-renders when it flips.
+ *
+ * `useSyncExternalStore` rather than `useState` + `useEffect`, deliberately: the flag is
+ * read during render and written outside React, and a passive effect leaves a window
+ * between the two. An answer landing in that window used to be lost — the effect saw the
+ * flag already set, returned early without registering a waiter, and the component
+ * rendered a stale `false` with nothing left to wake it (grove#75 round 3, reproduced).
+ * `useSyncExternalStore` re-reads the snapshot after subscribing and re-renders if it
+ * moved, which is exactly that hole.
+ */
+export function useCatalogAnswered(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/hooks/useEditAffordance.ts

@@ -30,14 +30,11 @@ export interface EditAffordance {
   /**
    * What a save actually does, so the affordance can say so.
    *
-   * **A stated residual (2026-08-27, R3-266).** The CoW overlay and the contribute (PR)
-   * flow are anchored on the APP's repo. Under a fork the app and the corpus are one
-   * repo, so "save" and "propose a change" are one story. Under dispatch they are two:
-   * the write lands in the corpus mount correctly, and *"open a PR against the content
-   * repo"* has no wired target. That is real remaining work — and it is not a reason to
-   * withhold editing, because a viewer that saves but cannot yet propose is strictly
-   * better than one that refuses to save. It IS a reason not to imply otherwise, so the
-   * chrome labels the dispatched case for what it is.
+   * Under a fork the app and the corpus are one repo, so "save" and "propose a
+   * change" are one story. Under dispatch they are two mounts — and since
+   * R3-643's host half (site-main #576) both are wired: the write lands in the
+   * corpus mount, and the contribute flow forks/branches/opens the PR against
+   * the CONTENT repo (the viewer's repo receives nothing).
    */
   editHint: string;
 }
@@ -92,7 +89,7 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
   );
 
   const editHint = corpus.dispatched
-    ? 'Edits save to the mounted content. Proposing a change back to its repository is not wired yet.'
+    ? 'Edits save to the mounted content, and can be proposed back to its repository as a PR.'
     : 'Edit this entry';
 
   return { writable, busy, refused, openEditor, editHint };

package/src/hooks/useHeadingFragmentUrl.test.tsx

@@ -0,0 +1,146 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { navigate } from '@immediately-run/sdk';
+import { useHeadingFragmentUrl } from './useHeadingFragmentUrl';
+
+vi.mock('@immediately-run/sdk', () => ({ navigate: vi.fn() }));
+
+const NAV = {
+  outerHref: 'https://immediately.run/present/github/acme/wiki/main',
+  navigationState: {
+    mode: 'present',
+    provider: 'github',
+    namespace: 'acme',
+    repository: 'wiki',
+    ref: 'main',
+    sandboxPath: '/content/guide.mdx',
+    hash: '',
+    search: '',
+  },
+  routingSpec: {},
+  filesMetadata: {},
+};
+
+/** The hook must be INSIDE the provider — in the app the host provides above
+ * `<GroveApp>`; here the probe plays that role and an inner component owns the hook. */
+function Inner() {
+  useHeadingFragmentUrl();
+  return (
+    <main className="grove-prose">
+      <h2 id="sec-2">Two</h2>
+      <h3 id="sec-2-1">Two point one</h3>
+      <a href="#sec-2" data-testid="toc-entry">Two</a>
+      <a href="https://immediately.run/present/github/acme/wiki/main/files/guide.mdx#sec-2-1" data-testid="permalink">
+        link
+      </a>
+      <a href="https://example.com/elsewhere#sec-2" data-testid="external">ext</a>
+      <a href="#sec-99" data-testid="dead">dead</a>
+    </main>
+  );
+}
+
+function Probe({ outerHref = NAV.outerHref, hash = '' }: { outerHref?: string; hash?: string }) {
+  return (
+    <TinkerableContext.Provider value={{ ...NAV, outerHref, navigationState: { ...NAV.navigationState, hash } } as never}>
+      <Inner />
+    </TinkerableContext.Provider>
+  );
+}
+
+function clickOn(testId: string, init?: MouseEventInit) {
+  const el = document.querySelector<HTMLElement>(`[data-testid="${testId}"]`)!;
+  el.dispatchEvent(new MouseEvent('click', { bubbles: true, button: 0, ...init }));
+}
+
+function mount(props: Parameters<typeof Probe>[0]) {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root: Root = createRoot(host);
+  act(() => root.render(<Probe {...props} />));
+  return () => {
+    act(() => root.unmount());
+    host.remove();
+  };
+}
+
+// A same-page fragment resolves against the current navigation state — the reader's
+// own path, hash replaced (no `/files/` join: the target is not an absolute path).
+const SAME_PAGE = 'https://immediately.run/present/github/acme/wiki/main/content/guide.mdx#sec-2';
+
+describe('useHeadingFragmentUrl', () => {
+  beforeEach(() => {
+    (navigate as unknown as ReturnType<typeof vi.fn>).mockClear();
+  });
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('navigates to the fragment when a TOC-style #anchor is clicked', () => {
+    const un = mount({});
+    act(() => clickOn('toc-entry'));
+    expect(navigate).toHaveBeenCalledWith(SAME_PAGE);
+    un();
+  });
+
+  it('navigates to the CURRENT path when a permalink is clicked — only its fragment is taken', () => {
+    const un = mount({});
+    act(() => clickOn('permalink'));
+    // Not the permalink's own URL: the fragment rides the path the reader is on.
+    expect(navigate).toHaveBeenCalledWith(
+      'https://immediately.run/present/github/acme/wiki/main/content/guide.mdx#sec-2-1',
+    );
+    un();
+  });
+
+  it('navigates when the heading element itself is clicked', () => {
+    const un = mount({});
+    act(() => {
+      document.getElementById('sec-2')!.dispatchEvent(new MouseEvent('click', { bubbles: true, button: 0 }));
+    });
+    expect(navigate).toHaveBeenCalledWith(SAME_PAGE);
+    un();
+  });
+
+  it('leaves modifier clicks to the browser (open-in-new-tab, copy-link)', () => {
+    const un = mount({});
+    act(() => clickOn('toc-entry', { metaKey: true }));
+    act(() => clickOn('toc-entry', { ctrlKey: true }));
+    act(() => clickOn('toc-entry', { button: 1 }));
+    expect(navigate).not.toHaveBeenCalled();
+    un();
+  });
+
+  it('leaves external links alone, even ones that carry a fragment', () => {
+    const un = mount({});
+    act(() => clickOn('external'));
+    expect(navigate).not.toHaveBeenCalled();
+    un();
+  });
+
+  it('does not push a history entry for the fragment the URL already shows', () => {
+    const un = mount({ hash: 'sec-2' });
+    act(() => clickOn('toc-entry'));
+    expect(navigate).not.toHaveBeenCalled();
+    un();
+  });
+
+  it('does not navigate for a fragment that names nothing on the page', () => {
+    const un = mount({});
+    act(() => clickOn('dead'));
+    expect(navigate).not.toHaveBeenCalled();
+    un();
+  });
+
+  it('off-host, writes the fragment locally instead of messaging a host that is not there', () => {
+    const replaceState = vi.spyOn(history, 'replaceState').mockImplementation(() => {});
+    const un = mount({ outerHref: '' });
+    act(() => clickOn('toc-entry'));
+    expect(navigate).not.toHaveBeenCalled();
+    expect(replaceState).toHaveBeenCalledWith(null, '', '#sec-2');
+    replaceState.mockRestore();
+    un();
+  });
+});