@immediately-run/grove 0.1.7 → 0.1.10

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.7)
+> 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)
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/grove",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {
@@ -28,7 +28,7 @@
     "lint": "eslint . --max-warnings 0",
     "test": "vitest run",
     "preview": "vite preview",
-    "verify": "npm run check:llms && npm run check:engine-api:selftest && npm run check:engine-api && npm run check:manifest && npm run check:deps && npm run check:published && npm run check:theme-contrast && npm run check:theme-token-only && npm run lint && npm run build && npm run test",
+    "verify": "npm run check:llms && npm run check:engine-api:selftest && npm run check:engine-api && npm run check:manifest && npm run check:deps && npm run check:published && npm run check:theme-contrast && npm run check:theme-token-only && npm run check:lock-version && npm run lint && npm run build && npm run test",
     "check:theme-contrast": "node scripts/check-theme-contrast.mjs --self-test && node scripts/check-theme-contrast.mjs",
     "check:theme-token-only": "node scripts/check-theme-token-only.mjs --self-test && node scripts/check-theme-token-only.mjs",
     "check:manifest": "node scripts/check-manifest.mjs --self-test && node scripts/check-manifest.mjs",
@@ -37,7 +37,8 @@
     "check:engine-api": "node scripts/check-engine-api.mjs",
     "check:engine-api:selftest": "node scripts/check-engine-api.mjs --self-test",
     "gen:llms": "node scripts/gen-llms.mjs",
-    "check:llms": "node scripts/gen-llms.mjs --check"
+    "check:llms": "node scripts/gen-llms.mjs --check",
+    "check:lock-version": "node scripts/check-lock-version.mjs --self-test && node scripts/check-lock-version.mjs"
   },
   "dependencies": {
     "@immediately-run/mdx-plugins": "0.7.1",

package/src/GroveApp.css

@@ -2686,6 +2686,26 @@ button.grove-search__row {
 .ga-reach__cause {
   color: var(--ink-2);
 }
+/* R3-790 — the ✗ chat row's earning affordance: a small token'd control inside
+   the reach card (the .ga-chip vocabulary, scaled to the card's 12.5px context). */
+.ga-reach__enable {
+  font-family: var(--sans);
+  font-weight: 600;
+  font-size: 12px;
+  color: var(--ink);
+  background: var(--panel-2);
+  border: 1px solid var(--line-2);
+  border-radius: var(--r-pill);
+  padding: 3px 10px;
+  margin-left: 8px;
+  cursor: pointer;
+  transition: .14s;
+}
+.ga-reach__enable:hover,
+.ga-reach__enable:focus-visible {
+  border-color: var(--accent-2);
+  color: var(--accent-2);
+}
 .ga-egress {
   margin: 0;
   padding: 8px 16px;

package/src/components/GroveAgent.test.tsx

@@ -367,3 +367,155 @@ describe('R3-608 round 2 — the panel returns focus to its (unmounted) trigger'
     expect(container.querySelector('.ga-panel')).toBeNull(); // focus did not reopen
   });
 });
+
+// ── R3-790 — the ungranted chat row's earning affordance ──────────────────────
+
+describe("R3-790 — the ✗ chat row offers its earning affordance (click invokes; the host gesture mints)", () => {
+  beforeAll(() => {
+    HTMLElement.prototype.scrollTo = () => undefined as unknown as void;
+  });
+
+  it('renders Enable chat on the ungranted row — the host-marked forbidden cause', async () => {
+    const { container } = await renderAgent({ writable: false });
+    // The cold mark — no prior configured push: the host strips the provider from
+    // every answer to an ungranted frame (the R3-688 test's shape).
+    await push({ type: 'llm-provider', provider: null, ungranted: true });
+    await push({ type: 'api-catalog', methods: [] }); // answered: nothing granted
+    await openPanel(container);
+    const enable = container.querySelector('.ga-reach__enable');
+    expect(enable).toBeTruthy(); // the affordance exists on the ✗ row
+    expect((enable as HTMLElement).textContent).toBe('Enable chat');
+    // …and the row itself still tells the honest cause.
+    expect(container.querySelector('.ga-reach__row--blocked')?.textContent).toContain(
+      "this Grove wasn't granted chat",
+    );
+  });
+
+  it('renders NO affordance when the provider is not configured (that row points at Settings)', async () => {
+    const { container } = await renderAgent({ writable: false });
+    await push({ type: 'llm-provider', provider: null }); // not-configured, not ungranted
+    await push({ type: 'api-catalog', methods: [] });
+    await openPanel(container);
+    expect(container.querySelector('.ga-reach__enable')).toBeNull();
+  });
+
+  it("a click invokes; a DECLINED dialog ('cancelled') keeps the honest row and says so", async () => {
+    runAgentMock.mockClear();
+    runAgentMock.mockImplementationOnce(() => {
+      const e = new Error('declined') as Error & { code?: string };
+      e.code = 'cancelled';
+      throw e;
+    });
+    const { container } = await renderAgent({ writable: false });
+    // The cold mark — no prior configured push: the host strips the provider from
+    // every answer to an ungranted frame (the R3-688 test's shape).
+    await push({ type: 'llm-provider', provider: null, ungranted: true });
+    await push({ type: 'api-catalog', methods: [] });
+    await openPanel(container);
+    await act(async () => {
+      (container.querySelector('.ga-reach__enable') as HTMLButtonElement).click();
+    });
+    // The invoke RAN (runAgent was called once — the gesture's trigger)…
+    expect(runAgentMock).toHaveBeenCalledTimes(1);
+    // …the decline surfaced honestly…
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 16));
+    });
+    expect(container.querySelector('.ga-toast')?.textContent).toContain("chat didn't start — reading works as normal; you can try again anytime");
+    // …and the row still reads the forbidden cause with the affordance for the next click.
+    expect(container.querySelector('.ga-reach__row--blocked')?.textContent).toContain(
+      "this Grove wasn't granted chat",
+    );
+    expect(container.querySelector('.ga-reach__enable')).toBeTruthy();
+  });
+
+  it('a click invokes; a still-FORBIDDEN answer surfaces the refusal toast (pre-gesture hosts)', async () => {
+    runAgentMock.mockImplementationOnce(() => {
+      const e = new Error('forbidden') as Error & { code?: string };
+      e.code = 'forbidden';
+      throw e;
+    });
+    const { container } = await renderAgent({ writable: false });
+    // The cold mark — no prior configured push: the host strips the provider from
+    // every answer to an ungranted frame (the R3-688 test's shape).
+    await push({ type: 'llm-provider', provider: null, ungranted: true });
+    await push({ type: 'api-catalog', methods: [] });
+    await openPanel(container);
+    await act(async () => {
+      (container.querySelector('.ga-reach__enable') as HTMLButtonElement).click();
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 16));
+    });
+    expect(container.querySelector('.ga-toast')?.textContent).toContain("this Grove wasn't granted chat");
+  });
+});
+
+// ── R3-790 round 1 — the GRANTED leg: the click's invoke proceeds when the grant lands ──
+
+describe("R3-790 — the granted leg (click → invoke → the grant lands → the ask proceeds, the row flips)", () => {
+  beforeAll(() => {
+    HTMLElement.prototype.scrollTo = () => undefined as unknown as void;
+  });
+  const configured = {
+    type: 'llm-provider',
+    provider: {
+      providerId: 'llm.chat.anthropic',
+      hostVouched: true,
+      features: { vision: false, tools: true, jsonMode: true, reasoning: false, maxContextTokens: 100000 },
+    },
+  } as const;
+  const grantedCatalog = {
+    type: 'api-catalog',
+    methods: [{ name: 'llm:chat', capability: 'llm:chat', stream: true }],
+  } as const;
+
+  it("the affordance's click drives the invoke; the granted catalog flips the row ✓ and the input enables", async () => {
+    runAgentMock.mockClear();
+    runAgentMock.mockImplementationOnce(async () => [
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'Answer in one sentence: what can you tell me about this wiki?' }],
+      },
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'This wiki is a small corpus about enabling chat.' }],
+      },
+    ]);
+    const { container } = await renderAgent({ writable: false });
+    await push({ type: 'llm-provider', provider: null, ungranted: true });
+    await push({ type: 'api-catalog', methods: [] });
+    await openPanel(container);
+    // Before: the honest ✗ row + the affordance.
+    expect(container.querySelector('.ga-reach__row--blocked')?.textContent).toContain(
+      "this Grove wasn't granted chat",
+    );
+    await act(async () => {
+      (container.querySelector('.ga-reach__enable') as HTMLButtonElement).click();
+    });
+    // The invoke RAN (the gesture's trigger).
+    expect(runAgentMock).toHaveBeenCalledTimes(1);
+    // The grant lands (the host's mint + lift answers the channels): push the
+    // granted catalog + the configured provider — the envelope recomputes.
+    await push(grantedCatalog);
+    await push(configured);
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 16));
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 16));
+    });
+    // The ask PROCEEDED: the assistant answer is in the body…
+    expect(container.querySelector('.ga-body')?.textContent).toContain('enabling chat');
+    // …the ANSWER row flipped ✓ (the read-only draft row stays honestly ✗ — that is
+    // its own row, not this one)…
+    const answerRow = [...container.querySelectorAll('.ga-reach__row')].find((r) =>
+      r.textContent?.includes('Answer questions about this wiki'),
+    );
+    expect(answerRow?.className).not.toContain('blocked');
+    expect(container.querySelector('.ga-reach__enable')).toBeNull();
+    // …and the composer input is ENABLED (canAsk true).
+    const input = container.querySelector('.ga-foot input') as HTMLInputElement;
+    expect(input?.disabled).toBe(false);
+  });
+});

package/src/components/GroveAgent.tsx

@@ -15,7 +15,7 @@ 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, sourceTrustLine, stateWord, 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';
@@ -236,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,
@@ -316,6 +318,22 @@ export default function GroveAgent({
                     <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>

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

package/src/hooks/useHeadingFragmentUrl.ts

@@ -0,0 +1,98 @@
+import { useCallback, useEffect } from 'react';
+import { useContext } from 'react';
+import { navigate } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { constructOuterUrl } from '@immediately-run/sdk/urlUtils';
+import { fragmentOf } from '../lib/fragment';
+
+/**
+ * Reflect same-page heading navigation in the ADDRESS BAR.
+ *
+ * The deep-linking pair has exactly one half so far: the host forwards the outer URL's
+ * `#fragment` in (R3-249, Capability C §13.5) and `<ScrollToFragment>` lands it — but
+ * nothing ever WRITES a fragment, so a reader who follows the contents rail, clicks a
+ * heading permalink or lands on a section has a URL bar that still names no section.
+ * Copying the address gives someone else the top of the page.
+ *
+ * This hook is the outgoing half. A delegated `click` listener on the document covers
+ * every way a heading is reached without each surface wiring its own handler:
+ *
+ *  - the contents rail's `<a href="#id">` (grove's `<TableOfContents>` smooth-scrolls
+ *    itself; the URL simply never heard about it);
+ *  - the SDK's `<HeadingAnchor>` permalinks — absolute host URLs whose own pathname
+ *    (a `/files/…` subpath) must NOT be navigated to, so only the FRAGMENT is taken and
+ *    the target is rebuilt on the reader's current path;
+ *  - a click on a heading element with an id (any depth).
+ *
+ * `navigate()` is the sanctioned app→host URL channel: an in-prefix `urlchange` whose
+ * target carries a hash is pushed onto the browser's address bar without a reload, and
+ * the echoed navigation sets `navigationState.hash`, which is what `<ScrollToFragment>`
+ * re-runs on — the platform's own loop completes the landing. Modifier clicks are the
+ * browser's (open-in-new-tab and copy-link are what the permalink's absolute href is
+ * FOR); a fragment naming nothing on the page is ignored rather than pushed; and a
+ * fragment equal to the one already in the URL does not stack another history entry.
+ *
+ * Off-host (`vite dev`, an empty `outerHref`) there is no host to tell, so the fragment
+ * is written to the frame's own URL with `history.replaceState` — a reload then lands
+ * where the reader was, and no history is spent.
+ */
+export function useHeadingFragmentUrl(): void {
+  // Deep import per <ScrollToFragment>'s precedent: the context is not on the SDK's
+  // index surface, and this app reads it for `outerHref`/`navigationState` only.
+  const ctx = useContext(TinkerableContext) as {
+    outerHref?: string;
+    navigationState?: { hash?: string };
+  };
+
+  const sync = useCallback(
+    (fragment: string) => {
+      const navigationState = ctx?.navigationState;
+      if (!ctx?.outerHref || !navigationState) {
+        try {
+          history.replaceState(null, '', `#${fragment}`);
+        } catch {
+          // a history the browser refuses is dev noise, not an error
+        }
+        return;
+      }
+      navigate(constructOuterUrl(ctx.outerHref, `#${fragment}`, navigationState as never));
+    },
+    [ctx],
+  );
+
+  useEffect(() => {
+    const onClick = (event: MouseEvent) => {
+      if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      const fragment = clickedFragment(event.target as HTMLElement | null, ctx?.outerHref ?? '');
+      if (!fragment) return;
+      // Already shown (locator-glued dev hashes included — `fragmentOf` takes the
+      // leading component): a second push would only stack a history entry.
+      if (fragmentOf(ctx?.navigationState?.hash) === fragment) return;
+      if (!document.getElementById(fragment) && !document.querySelector(`[data-slug="${fragment}"]`)) return;
+      sync(fragment);
+    };
+    document.addEventListener('click', onClick);
+    return () => document.removeEventListener('click', onClick);
+  }, [sync, ctx]);
+}
+
+/** The fragment this click addresses, or null when it is not heading navigation. */
+function clickedFragment(element: HTMLElement | null, outerHref: string): string | null {
+  const anchor = element?.closest('a');
+  if (anchor) {
+    const href = anchor.getAttribute('href') ?? '';
+    if (href.startsWith('#')) return fragmentOf(href);
+    try {
+      const url = new URL(href, window.location.href);
+      // Absolute hrefs: only the app's OWN permalink URLs count. Their origin is the
+      // outer origin — the sandbox frame's `location.origin` is different, so compare
+      // against the outer href, never against the frame.
+      const ownOrigin = outerHref ? new URL(outerHref).origin : window.location.origin;
+      if (!url.hash || url.origin !== ownOrigin) return null;
+      return fragmentOf(url.hash);
+    } catch {
+      return null;
+    }
+  }
+  return element?.closest('h1[id], h2[id], h3[id], h4[id]')?.id ?? null;
+}

package/src/lib/reachCard.test.ts

@@ -510,3 +510,31 @@ describe("R-GA-6 — the egress disclosure is unconditional when a provider is b
     expect(showEgressDisclosure({ status: "not-configured" })).toBe(false);
   });
 });
+
+
+// ── R3-790 — the earning affordance's arms ────────────────────────────────────
+
+describe('R3-790 — the ✗ chat row carries the earning affordance on its arms', () => {
+  const configured: ChatProviderState = {
+    status: 'configured',
+    provider: { providerId: 'llm.chat.anthropic', hostVouched: true, features: { vision: false, tools: true, jsonMode: true, reasoning: false, maxContextTokens: 100000 } },
+  };
+  const base = { writable: true, sourceShared: false, catalogAnswered: true, mountId: null };
+
+  it('the host-marked ungranted arm carries it', () => {
+    const rows = computeReachRows({ ...base, providerState: { status: 'ungranted' } as ChatProviderState, chatGranted: false, toolsSupported: true });
+    expect(rows.find((r) => r.key === 'answer')?.action).toBe('enable-chat');
+  });
+
+  it("the belt arm carries it when the provider RESOLVES (configured, catalog answered, grant missing)", () => {
+    const rows = computeReachRows({ ...base, providerState: configured, chatGranted: false, toolsSupported: true });
+    expect(rows.find((r) => r.key === 'answer')?.action).toBe('enable-chat');
+  });
+
+  it('no arm carries it when the catalog is unanswered, or the provider is keyless', () => {
+    const neutral = computeReachRows({ ...base, catalogAnswered: false, providerState: configured, chatGranted: false, toolsSupported: true });
+    expect(neutral.find((r) => r.key === 'answer')?.action).toBeUndefined();
+    const keyless = computeReachRows({ ...base, providerState: { status: 'not-configured' } as ChatProviderState, chatGranted: false, toolsSupported: true });
+    expect(keyless.find((r) => r.key === 'answer')?.action).toBeUndefined();
+  });
+});

package/src/lib/reachCard.ts

@@ -39,11 +39,24 @@ export function stateWord(state: ReachRow['state']): string {
  *
  *  `state: 'elsewhere'` is the apply row: the outcome happens at another surface, which is
  *  where to go — never a ✗. */
+/** R3-790 — the one spelling of the ungranted-chat cause: the row renders it and
+ *  the composer's refusal toast composes from it, so a reword cannot drift the
+ *  two surfaces R-GA-1 holds to agreement. The tail is its own constant so the
+ *  cancelled toast composes the SAME clause without splitting a literal at
+ *  runtime (a reword of the cause must never render 'undefined' into copy). */
+export const READING_WORKS_NORMAL = 'reading works as normal';
+export const UNGRANTED_CHAT_CAUSE = `this Grove wasn't granted chat — ${READING_WORKS_NORMAL}`;
+
 export interface ReachRow {
   key: 'packaging' | 'answer' | 'read' | 'draft' | 'apply';
   label: string;
   state: 'ok' | 'blocked' | 'neutral' | 'elsewhere';
   cause?: string;
+  /** R3-790 — the row's earning affordance: on the ✗ chat row, an 'Enable chat'
+   *  control whose CLICK invokes (the host's lazy consent gesture mints on that
+   *  same activation, site-main#612). Declared here so the card stays the one
+   *  computed surface; the panel renders it, never invents it. */
+  action?: 'enable-chat';
   /** Where a `'elsewhere'` row's outcome happens — rendered after `→`, never a ✗. */
   destination?: string;
   /** Chips this row contributes when ✓ — the panel renders exactly these. */
@@ -150,7 +163,11 @@ export function computeReachRows({
       key: 'answer',
       label: 'Answer questions about this wiki',
       state: 'blocked',
-      cause: "this Grove wasn't granted chat — reading works as normal",
+      cause: UNGRANTED_CHAT_CAUSE,
+      // R3-790: the host's MARK says the grant is missing (provider and key state
+      // unknown — the mark does not tell); the invoke this row's own click makes is
+      // what the host's lazy gesture earns on that same activation.
+      action: 'enable-chat',
     };
   } else if (!chatGranted) {
     answer = catalogAnswered
@@ -158,7 +175,13 @@ export function computeReachRows({
           key: 'answer',
           label: 'Answer questions about this wiki',
           state: 'blocked',
-          cause: "this Grove wasn't granted chat — reading works as normal",
+          cause: UNGRANTED_CHAT_CAUSE,
+          // R3-790: the affordance only when a provider RESOLVES (status
+          // 'configured' with the grant missing) — on a keyless host the invoke's
+          // earning path is the SP-7 connect flow, which the not-configured copy
+          // already names (Settings); offering both rows' affordances here would
+          // blur which half is missing.
+          ...(providerState.status === 'configured' ? { action: 'enable-chat' as const } : {}),
         }
       : // The host has not answered the catalog. We know nothing about the grant, so name
         // nothing — the same shape `unknown` uses for an unanswered provider.

package/src/lib/shell.ts

@@ -44,8 +44,9 @@ export interface GroveShell {
   /** True when the host REFUSED the last edit request — render it where the
    *  affordance was offered (3.3.1, R3-608); a cancelled request never sets it. */
   editRefused: boolean;
-  /** What a save actually does, for the affordance's title — under dispatch it says that
-   *  proposing a change back to the content repo is not wired yet (R3-266's residual). */
+  /** What a save actually does, for the affordance's title — under dispatch it says
+   *  the write lands in the mounted content and can be proposed back as a PR
+   *  (R3-643 / site-main #576 wired the contribute flow to the content repo). */
   editHint: string;
   siteTitle: string;
   /** Interpreter mode (TRUST_MODES §5): render this entry's body through the