@immediately-run/grove 0.1.1

package/src/lib/tocScroll.ts

@@ -0,0 +1,93 @@
+// "Scroll the selected entry into view — when necessary."
+//
+// The arithmetic is here, as a pure function, for two reasons.
+//
+// **It is the part that is easy to get subtly wrong**, and the failure is invisible in a
+// screenshot: scrolling when the entry was already visible (the list twitches on every
+// heading the reader passes), or leaving it just under the fold because the margin was
+// measured against the wrong edge.
+//
+// **The obvious API is a trap.** `element.scrollIntoView()` — even with
+// `block: 'nearest'` — walks EVERY scrollable ancestor, so calling it on a table-of-
+// contents link also scrolls the document that contains it. The reader passes a heading,
+// the page jumps: the exact opposite of the feature. So this returns a `scrollTop` for ONE
+// container and the caller assigns it, and no ancestor can move.
+
+/** The measurements this needs, in one object — so it can be called from a real DOM
+ *  (`clientHeight`/`scrollTop`/`offsetTop`) and from a test with plain numbers. */
+export interface ScrollView {
+  /** The scroll container's visible height. */
+  viewHeight: number;
+  /** Its current scroll offset. */
+  scrollTop: number;
+  /** Its total scrollable height. */
+  scrollHeight: number;
+}
+
+export interface ScrollItem {
+  /** The item's offset from the top of the container's content. */
+  top: number;
+  height: number;
+}
+
+export interface ScrollOptions {
+  /** Breathing room kept between the item and the edge it is being pulled away from.
+   *  An item flush against the fold reads as "the last one" — the margin is what tells
+   *  the reader there is more list in that direction. */
+  margin?: number;
+}
+
+/**
+ * The `scrollTop` that brings `item` into view inside `view`, or **null when no scroll is
+ * needed** — the "when necessary" half, and the reason this returns null rather than the
+ * current offset: a caller that assigned an unchanged value would still cancel a smooth
+ * scroll already in flight and re-fire scroll events.
+ *
+ * Nearest-edge, not centred: an entry one line below the fold should rise one line, not
+ * jump to the middle. Centring would move the list on almost every step and destroy the
+ * reader's sense of place in it.
+ */
+export function scrollOffsetFor(
+  view: ScrollView,
+  item: ScrollItem,
+  opts: ScrollOptions = {}
+): number | null {
+  const margin = opts.margin ?? 0;
+  const maxScroll = Math.max(0, view.scrollHeight - view.viewHeight);
+  // Nothing to scroll: the whole list fits. Every item is already in view by definition,
+  // and clamping below would otherwise return 0 for an item at the top and read as "scroll".
+  if (maxScroll <= 0) return null;
+
+  const top = item.top;
+  const bottom = item.top + item.height;
+  const viewTop = view.scrollTop;
+  const viewBottom = view.scrollTop + view.viewHeight;
+
+  let target: number;
+  if (top - margin < viewTop) {
+    target = top - margin; // above the fold — pull it down to the top edge
+  } else if (bottom + margin > viewBottom) {
+    target = bottom + margin - view.viewHeight; // below — pull it up to the bottom edge
+  } else {
+    return null; // already visible with room to spare
+  }
+
+  const clamped = Math.max(0, Math.min(target, maxScroll));
+  // The clamp can land exactly where we already are — an item inside the top margin when
+  // the list is already scrolled to 0. That is "already in view", not a scroll.
+  return clamped === view.scrollTop ? null : clamped;
+}
+
+/** Read a live element pair into the shapes above. `offsetTop` is relative to the nearest
+ *  positioned ancestor, so the container must be a positioning context (the stylesheet
+ *  gives it `position: relative`) or the arithmetic is measured from the wrong origin. */
+export function measure(container: HTMLElement, item: HTMLElement): [ScrollView, ScrollItem] {
+  return [
+    {
+      viewHeight: container.clientHeight,
+      scrollTop: container.scrollTop,
+      scrollHeight: container.scrollHeight,
+    },
+    { top: item.offsetTop, height: item.offsetHeight },
+  ];
+}

package/src/lib/wiki.test.ts

@@ -0,0 +1,194 @@
+import { SLUG_PARITY_FIXTURE } from '@immediately-run/mdx-plugins';
+import { describe, it, expect } from 'vitest';
+import { backlinkSnippet, bodyLinks, bodyLinksTo, headingId, sectionId, textSlug } from './wiki';
+
+// The heading ids Grove computes MUST match the kernel's heading-slug plugin
+// (`@immediately-run/mdx-plugins` remarkHeadingAnchors, MARKDOWN_SYNTAX_SPEC §15.1 /
+// R3-186 + R3-211) so a `<Toc>` link and the heading's own autolink anchor resolve
+// to the same target (§15.5).
+//
+// Since R3-277 that is true by CONSTRUCTION — `wiki.ts` re-exports the canon rather
+// than reproducing it — and the fixture below is what makes the claim testable
+// instead of merely structural: if a future change reintroduces a local copy, or the
+// canon moves under us, this fails here rather than in a reader's broken TOC link.
+describe('the shared slug parity fixture (R3-277)', () => {
+  it('grove agrees with the canon on every case', () => {
+    for (const c of SLUG_PARITY_FIXTURE) {
+      expect(textSlug(c.text), c.why).toBe(c.slug);
+      expect(sectionId(c.text), c.why).toBe(c.section);
+      expect(headingId(c.text), c.why).toBe(c.id);
+    }
+  });
+
+  it('the fixture actually arrived (a vacuous loop would pass silently)', () => {
+    expect(SLUG_PARITY_FIXTURE.length).toBeGreaterThan(10);
+  });
+});
+
+// The cases below predate the fixture and are kept: they read as documentation of
+// the grammar at the call site, and they would catch a fixture that lost a case.
+describe('headingId — byte-identical with the kernel (§15.5)', () => {
+  it('prose heading → GitHub text slug', () => {
+    expect(headingId('Getting started')).toBe('getting-started');
+    expect(headingId('The **bold** heading'.replace(/\*\*/g, ''))).toBe('the-bold-heading');
+  });
+
+  it('numbered heading → prose-independent section id (R3-211)', () => {
+    expect(headingId('8.9 Powerbox')).toBe('sec-8-9');
+    expect(headingId('8.9 Renamed entirely')).toBe('sec-8-9'); // prose-independent
+    expect(headingId('7. The guarantee')).toBe('sec-7');
+    expect(headingId('7A. Filesystem trust mode')).toBe('sec-7a'); // distinct from sec-7
+    expect(headingId('A.0 Branding')).toBe('sec-a-0');
+    expect(headingId('3.2.1 Something')).toBe('sec-3-2-1');
+  });
+
+  it('sectionId is null for prose (no false positives)', () => {
+    expect(sectionId('Decisions & rejected alternatives')).toBeNull();
+    expect(sectionId('Getting started')).toBeNull();
+  });
+
+  it('textSlug matches GitHub slugging (drops `.`, collapses hyphens)', () => {
+    expect(textSlug('8.9 Powerbox')).toBe('89-powerbox'); // GitHub drops the dot
+    expect(textSlug('Q & A: notes!')).toBe('q-a-notes');
+    expect(textSlug('  spaced   out  ')).toBe('spaced-out');
+  });
+});
+
+// ── Backlinks (R3-283) ───────────────────────────────────────────────────────
+//
+// The index was dead: 9,030 wiki-links in the corpus, 0 of 710 entries with a
+// backlink, because `bodyLinksTo` matched three literal link forms the corpus never
+// writes. The failure shape is why it survived — a feature that renders its empty
+// state perfectly, where "nothing links here yet" is indistinguishable from a correct
+// answer. So these assert SPECIFIC counts per supported form: a matcher that resolves
+// only one form fails here rather than looking plausible.
+describe('bodyLinksTo — every link form the corpus actually writes (R3-283)', () => {
+  const FROM = '/app/content/roadmap/R3-283.mdx';
+  const SPEC = '/app/content/specs/PLATFORM_LAYERING_SPEC.mdx';
+  const SIBLING = '/app/content/roadmap/R3-282.mdx';
+
+  const forms: Array<{ why: string; body: string; target: string }> = [
+    { why: 'relative wiki-link with ../ and the extension', body: 'see [[../specs/PLATFORM_LAYERING_SPEC.mdx]]', target: SPEC },
+    { why: '…and with a #fragment', body: 'see [[../specs/PLATFORM_LAYERING_SPEC.mdx#sec-2]]', target: SPEC },
+    { why: '…and with an explicit label (label|target, §13.1 order)', body: 'see [[layering|../specs/PLATFORM_LAYERING_SPEC.mdx#sec-2]]', target: SPEC },
+    { why: 'sibling wiki-link, no path prefix', body: 'see [[R3-282.mdx]]', target: SIBLING },
+    { why: 'extension-less target — the legacy [[slug]] form', body: 'see [[R3-282]]', target: SIBLING },
+    { why: 'markdown link, relative', body: 'see [the spec](../specs/PLATFORM_LAYERING_SPEC.mdx)', target: SPEC },
+    { why: 'markdown link, corpus-absolute', body: 'see [x](/content/specs/PLATFORM_LAYERING_SPEC.mdx)', target: SPEC },
+    { why: 'markdown link, /files-prefixed', body: 'see [x](/files/content/specs/PLATFORM_LAYERING_SPEC.mdx)', target: SPEC },
+    { why: 'markdown link with a fragment', body: 'see [x](../specs/PLATFORM_LAYERING_SPEC.mdx#sec-2)', target: SPEC },
+  ];
+
+  for (const f of forms) {
+    it(`resolves: ${f.why}`, () => {
+      expect(bodyLinksTo(f.body, f.target, FROM)).toBe(true);
+    });
+  }
+
+  it('finds ALL of them in one body — the count is specific, not ">= 1"', () => {
+    const body = forms.map((f) => f.body).join('\n\n');
+    expect(bodyLinks(body)).toHaveLength(forms.length);
+    expect(bodyLinksTo(body, SPEC, FROM)).toBe(true);
+    expect(bodyLinksTo(body, SIBLING, FROM)).toBe(true);
+  });
+});
+
+describe('bodyLinksTo — what must NOT count as a backlink (R3-283)', () => {
+  const FROM = '/app/content/roadmap/R3-283.mdx';
+  const OTHER = '/app/content/specs/OTHER_SPEC.mdx';
+
+  it('a PREFIX of the target key is not the target', () => {
+    // The bug this guards: substring matching would call these the same entry.
+    expect(bodyLinksTo('see [[../specs/OTHER.mdx]]', OTHER, FROM)).toBe(false);
+    expect(bodyLinksTo('see [[../specs/OTHER_SPEC_V2.mdx]]', OTHER, FROM)).toBe(false);
+    expect(bodyLinksTo('see [[../specs/OTHER_SPEC.mdx]]', OTHER, FROM)).toBe(true);
+  });
+
+  it('a link inside a fenced code block is being QUOTED, not written', () => {
+    const body = ['```ts', 'body.includes(`[[../specs/OTHER_SPEC.mdx]]`)', '```'].join('\n');
+    expect(bodyLinksTo(body, OTHER, FROM)).toBe(false);
+  });
+
+  it('a link inside an inline code span is quoted too', () => {
+    // Verbatim from this very item's prose, which documents the forms it fixes.
+    expect(bodyLinksTo('it wants `[[../specs/OTHER_SPEC.mdx]]` instead', OTHER, FROM)).toBe(false);
+  });
+
+  it('a link in the frontmatter is metadata, not body prose', () => {
+    const body = ['---', 'reads-first:', '  - ../specs/OTHER_SPEC.mdx', 'title: "[[../specs/OTHER_SPEC.mdx]]"', '---', 'nothing here'].join('\n');
+    expect(bodyLinksTo(body, OTHER, FROM)).toBe(false);
+  });
+
+  it('an image is not a link, and an external href is not a corpus link', () => {
+    expect(bodyLinksTo('![alt](../specs/OTHER_SPEC.mdx)', OTHER, FROM)).toBe(false);
+    expect(bodyLinksTo('[x](https://example.com/specs/OTHER_SPEC.mdx)', OTHER, FROM)).toBe(false);
+  });
+
+  it('relative means relative TO THE LINKING ENTRY, not to the corpus root', () => {
+    // `[[specs/X.mdx]]` written in roadmap/ denotes roadmap/specs/X.mdx. Reading it as
+    // corpus-relative (what the old matcher did for `[[slug]]`) would credit a backlink
+    // to an entry the link does not navigate to.
+    expect(bodyLinksTo('see [[specs/OTHER_SPEC.mdx]]', OTHER, FROM)).toBe(false);
+    expect(bodyLinksTo('see [[specs/OTHER_SPEC.mdx]]', '/app/content/roadmap/specs/OTHER_SPEC.mdx', FROM)).toBe(true);
+  });
+});
+
+describe('backlinkSnippet — marks the linking phrase, not the first 160 chars (R3-283)', () => {
+  const FROM = '/app/content/roadmap/R3-283.mdx';
+  const SPEC = '/app/content/specs/PLATFORM_LAYERING_SPEC.mdx';
+  const lead = 'A paragraph of preamble that exists only to push the link past the first 160 characters of the entry, so a snippet that fell back to a prefix would be visibly wrong. ';
+
+  it('uses the markdown label', () => {
+    const snip = backlinkSnippet(`${lead}and then [the layering spec](../specs/PLATFORM_LAYERING_SPEC.mdx) closes it.`, SPEC, FROM);
+    expect(snip).toContain('<mark>the layering spec</mark>');
+    expect(snip).toContain('closes it');
+  });
+
+  it('uses the wiki label when one is given', () => {
+    const snip = backlinkSnippet(`${lead}and then [[the layering spec|../specs/PLATFORM_LAYERING_SPEC.mdx]] closes it.`, SPEC, FROM);
+    expect(snip).toContain('<mark>the layering spec</mark>');
+  });
+
+  it('falls back to a prefix only when the phrase is not in the rendered text', () => {
+    const snip = backlinkSnippet(`${lead}[[../specs/PLATFORM_LAYERING_SPEC.mdx]]`, SPEC, FROM);
+    // An unlabelled wiki-link's "phrase" is its target path, which the stripped text
+    // does contain — so this marks it rather than degrading.
+    expect(snip).toContain('<mark>');
+  });
+});
+
+describe('backlinkSnippet — a snippet is prose, not source (R3-283)', () => {
+  const FROM = '/app/content/roadmap/R3-283.mdx';
+  const SPEC = '/app/content/specs/TARGET_SPEC.mdx';
+
+  it('drops the link syntax around the marked phrase', () => {
+    const snip = backlinkSnippet(
+      'The link itself calls the target [[the layering contract|../specs/TARGET_SPEC.mdx#sec-2]] and carries a fragment.',
+      SPEC,
+      FROM,
+    );
+    expect(snip).toContain('calls the target <mark>the layering contract</mark> and carries');
+    for (const noise of ['[[', ']]', '../specs/TARGET_SPEC.mdx']) expect(snip).not.toContain(noise);
+  });
+
+  it('does the same for a markdown link', () => {
+    const snip = backlinkSnippet('This entry links to [the target spec](../specs/TARGET_SPEC.mdx) with ordinary markdown.', SPEC, FROM);
+    expect(snip).toContain('links to <mark>the target spec</mark> with ordinary markdown');
+    expect(snip).not.toContain('](');
+  });
+
+  it('an UNLABELLED wiki-link renders as its target, and that is what gets marked', () => {
+    const snip = backlinkSnippet('This entry mentions [[../specs/TARGET_SPEC.mdx]] once.', SPEC, FROM);
+    expect(snip).toContain('mentions <mark>../specs/TARGET_SPEC.mdx</mark> once');
+    expect(snip).not.toContain('[[');
+  });
+
+  it('other links in the same sentence are reduced too, not just the matched one', () => {
+    const snip = backlinkSnippet(
+      'See [the other one](../specs/OTHER.mdx) and then [the target spec](../specs/TARGET_SPEC.mdx).',
+      SPEC,
+      FROM,
+    );
+    expect(snip).toContain('See the other one and then <mark>the target spec</mark>');
+  });
+});

package/src/lib/wiki.ts

@@ -0,0 +1,175 @@
+// Pure wiki helpers — no React, no components (kept out of component files per the
+// Fast-Refresh rule). Shared by the reading-view, index, and agent surfaces.
+import { contentDir, hrefKeyCandidates, splitFragment } from './content';
+// The canonical `[[label|target]]` grammar (MARKDOWN_SYNTAX_SPEC §13.1) — the SAME
+// parser the safe renderer splits wiki-links with, so the backlink index and the link
+// a reader clicks can never disagree about what a target is.
+import { parseWikiInner } from '@immediately-run/sdk/safeContent/index';
+
+/** Extract the path strings from a `useMetadataQuery` result. The hook returns a
+ *  `{ path, meta }[]` array directly (or `{ error }`), NOT a `{ result }` wrapper —
+ *  centralising the unwrap here keeps every consumer honest. */
+export function queryPaths(q: unknown): string[] {
+  return Array.isArray(q) ? (q as { path: string }[]).map((e) => e.path) : [];
+}
+
+/** Records from a metadata query that returned records: the entries as given, or
+ *  `[]` when the query threw (`{ error }` result). The record-shape twin of
+ *  {@link queryPaths}. */
+export function queryRecords<E extends object>(q: unknown): ({ path: string } & E)[] {
+  return Array.isArray(q) ? (q as ({ path: string } & E)[]) : [];
+}
+
+/** Average adult reading speed; `→ N min read` is rounded up, min 1. */
+export function readingTime(body: string): number {
+  const words = body.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.round(words / 220));
+}
+
+// Heading ids come from the CANON (R3-277). `@immediately-run/mdx-plugins` owns the
+// slug grammar — it is the plugin the compiled and safe render paths both run, so its
+// `headingId` is by definition the id a reader lands on. Grove reproduced it locally
+// (per §15.5 "specified precisely so a consumer can reproduce it") and the two agreed
+// because they were written from the same paragraph, which is a promise rather than a
+// mechanism: the failure mode is a `<Toc>` entry that scrolls nowhere, silently.
+//
+// This deliberately relaxes "grove depends on the SDK, not the transpiler" for the
+// PLUGINS package only. That package is the byte-canon, is dependency-free, and is
+// consumed here for a pure function — none of the transpiler's machinery comes with
+// it. Re-exported so every existing import site in this repo is unchanged.
+export { textSlug, sectionId, headingId } from '@immediately-run/mdx-plugins';
+
+/** A content key → its namespace breadcrumb, e.g.
+ *  `/app/content/handbook/onboarding.mdx` → `handbook / onboarding`. */
+export function crumb(key: string): string {
+  return key
+    .replace(contentDir(), '')
+    .replace(/\.mdx?$/, '')
+    .split('/')
+    .join(' / ');
+}
+
+/** The namespace folder of a key, e.g. `handbook` (or '' for a root entry). */
+export function namespaceOf(key: string): string {
+  const rel = key.replace(contentDir(), '').replace(/\.mdx?$/, '');
+  const parts = rel.split('/');
+  return parts.length > 1 ? parts.slice(0, -1).join('/') : '';
+}
+
+/** Drop a leading `--- … ---` YAML frontmatter block from raw MDX source. */
+export function stripFrontmatter(src: string): string {
+  const m = src.match(/^---\n[\s\S]*?\n---\n?/);
+  return m ? src.slice(m[0].length) : src;
+}
+
+// ── Backlinks (R3-283) ───────────────────────────────────────────────────────
+//
+// `bodyLinksTo` used to string-match three literal forms — `(/content/X.mdx)`,
+// `(/files/content/X.mdx)` and `[[X]]` (corpus-relative, extension-less). The corpus
+// writes NONE of them: it writes `[[../specs/X.mdx#sec-2]]` and `(ways_of_working.mdx)`,
+// both RELATIVE to the linking entry, with the extension, sometimes with a fragment.
+// Result: 9,030 wiki-links, 0 of 710 entries with a backlink — `<Backlinks/>`, the
+// signature wiki affordance, had never worked on this corpus and rendered its empty
+// state perfectly while doing so.
+//
+// So these do not pattern-match link SYNTAX any more. They EXTRACT each link and
+// resolve it through `hrefKeyCandidates` — the same function the renderer routes
+// clicks through, and the same rule `check-docs-wiki`'s `contentResolve` audits the
+// corpus by. A backlink now means exactly "a link that would navigate here", which is
+// the only definition that cannot drift from the links themselves.
+//
+// Deliberately DROPPED: the old corpus-relative reading of `[[specs/X]]`. Under the one
+// resolution rule that link, written in `content/roadmap/foo.mdx`, denotes
+// `content/roadmap/specs/X.mdx` — so honouring the old reading would credit a backlink
+// to an entry the link does not go to. An extension-less target still works; it is just
+// resolved like every other link.
+
+/** Frontmatter, fenced code and inline code spans removed — the regions where a
+ *  `[[…]]` or `[…](…)` is being QUOTED rather than linked. Without this the roadmap
+ *  items that document link forms would manufacture backlinks out of their own prose. */
+export function linkScannableBody(body: string): string {
+  return stripFrontmatter(body)
+    .replace(/^[ \t]*(```|~~~)[^\n]*\n[\s\S]*?^[ \t]*\1[^\n]*$/gm, '')
+    .replace(/`[^`\n]*`/g, '');
+}
+
+/** One extracted link: the raw href, plus the text a reader sees (the wiki label or
+ *  the markdown label) — what `backlinkSnippet` marks. */
+export interface BodyLink {
+  href: string;
+  label: string;
+}
+
+/** Every corpus link in `body`, in source order. Wiki targets are parsed with the SDK's
+ *  canonical `parseWikiInner` (`[[label|target]]`, label first — MARKDOWN_SYNTAX §13.1)
+ *  rather than a local regex, so this cannot drift from what the renderer links. */
+export function bodyLinks(body: string): BodyLink[] {
+  const scannable = linkScannableBody(body);
+  const out: BodyLink[] = [];
+  for (const m of scannable.matchAll(/\[\[([^[\]]+)\]\]/g)) {
+    const token = parseWikiInner(m[1]);
+    if (token) out.push({ href: token.target, label: token.label ?? token.target });
+  }
+  // `[label](href)`, skipping images (`![alt](src)`) and an optional "title".
+  for (const m of scannable.matchAll(/(!?)\[([^\]]*)\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g)) {
+    if (m[1] === '!') continue;
+    out.push({ href: m[3], label: m[2] });
+  }
+  return out;
+}
+
+/** The entry keys a body link denotes. An extension-less target also gets an `.mdx`
+ *  candidate, so the legacy `[[slug]]` form keeps resolving — by the same rule, not a
+ *  special case. */
+function linkTargetKeys(href: string, fromKey: string): string[] {
+  const keys = hrefKeyCandidates(href, fromKey);
+  if (keys.length) return keys;
+  const [path, frag] = splitFragment(href);
+  return /\.mdx?$/.test(path) || !path ? [] : hrefKeyCandidates(`${path}.mdx${frag}`, fromKey);
+}
+
+/** Does the entry at `fromKey` link to the entry at `targetKey`? Resolves every link
+ *  in the body the way the renderer does, then compares KEYS — so a near-miss
+ *  (`[[specs/OTHER.mdx]]` against `specs/OTHER_SPEC.mdx`) cannot match. */
+export function bodyLinksTo(body: string, targetKey: string, fromKey: string): boolean {
+  return bodyLinks(body).some((l) => linkTargetKeys(l.href, fromKey).includes(targetKey));
+}
+
+/** Body prose as a READER sees it: HTML tags dropped, and a link reduced to the text
+ *  it renders as. Without the second half a snippet reads
+ *  `calls the target [[the layering contract|../specs/X.mdx#sec-2]] and carries`, which
+ *  is the source, not the sentence — the noise was invisible while the index was empty
+ *  and appeared the moment backlinks started resolving (R3-283). */
+export function renderedText(body: string): string {
+  return stripFrontmatter(body)
+    .replace(/<[^>]+>/g, ' ')
+    // `[[label|target]]` → label, `[[target]]` → target (the §13.1 order).
+    .replace(/\[\[([^[\]]+)\]\]/g, (_, inner: string) => {
+      const token = parseWikiInner(inner);
+      return token ? (token.label ?? token.target) : inner;
+    })
+    // `[label](href)` → label; an image renders as its alt text.
+    .replace(/!?\[([^\]]*)\]\(\s*[^)\s]+(?:\s+"[^"]*")?\s*\)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** A ~160-char snippet of `body` around the first link to `targetKey`, with the
+ *  linking phrase wrapped in <mark>… (returned as an HTML string for the snippet). */
+export function backlinkSnippet(body: string, targetKey: string, fromKey: string): string {
+  const text = renderedText(body);
+  // The MARK is the linking phrase as the reader sees it: a wiki label (or its target
+  // when unlabelled), or the markdown label. Matching on the resolved link rather than
+  // on a literal href is what stops every hit falling back to "first 160 chars".
+  const link = bodyLinks(body).find((l) => linkTargetKeys(l.href, fromKey).includes(targetKey));
+  const phrase = link?.label.trim();
+  const idx = phrase ? text.toLowerCase().indexOf(phrase.toLowerCase()) : -1;
+  if (!phrase || idx === -1) {
+    return text.slice(0, 160) + (text.length > 160 ? '…' : '');
+  }
+  const start = Math.max(0, idx - 70);
+  const end = Math.min(text.length, idx + phrase.length + 70);
+  const before = (start > 0 ? '…' : '') + text.slice(start, idx);
+  const after = text.slice(idx + phrase.length, end) + (end < text.length ? '…' : '');
+  return `${before}<mark>${phrase}</mark>${after}`;
+}

package/src/lib.ts

@@ -0,0 +1,54 @@
+// The library entry (PLATFORM_LAYERING_SPEC §1.1 mode M3, R3-280).
+//
+// Grove composes with a corpus in three modes and this is the third: a thin shell — an
+// ordinary `App.tsx` — imports the engine as a pinned dependency and arranges it, keeping
+// ownership of composition without forking engine source. The other two modes are
+// unchanged by this file: `src/App.tsx` is still the fork/dispatch entry immediately.run
+// renders, and it is exported here too, so a shell that wants the whole wiki (gate
+// included) mounts one component.
+//
+// What Grove IS, stated once because the packaging makes it answerable: a kit of React
+// components, prebuilt layouts and themes that make a wiki easy to build and good-looking
+// by default — NOT a wiki engine in the traditional sense. The parts a traditional wiki
+// engine owns are cross-cutting platform concerns and live below this package: routing,
+// MDX compilation, the frontmatter metadata index, link spaces, includes and heading
+// anchors are sandbox + SDK, because every immediately.run app needs them and not only
+// wikis. What is left here — and it is a real thing to own — is the vocabulary, the
+// chrome, and the defaults.
+//
+// Exports only. No component is DEFINED here, so the Fast-Refresh rule is satisfied by
+// re-export; the components themselves live one per file as they always did.
+
+export { default as GroveApp } from './App';
+export { default as GroveWiki } from './GroveWiki';
+
+// The component vocabulary + the two render maps.
+export { GROVE_MDX, SAFE_MDX } from './mdxComponents';
+
+// The override contract of library composition.
+export {
+  VIEWER_MANIFEST,
+  ManifestOverrideError,
+  composeComponents,
+  manifestNames,
+  overridableNames,
+} from './lib/compose';
+export type { ViewerManifest, ManifestComponent } from './lib/compose';
+
+// Shell state, so an overriding chrome component can read what the stock one reads.
+export { GroveShellContext, OutletContext, useShell } from './lib/shell';
+export type { GroveShell, NavItem } from './lib/shell';
+
+// Corpus helpers a shell needs to address entries the way the engine does.
+export {
+  contentDir,
+  homeKey,
+  isContentEntry,
+  keyToFsPath,
+  keyToHref,
+  keyToInclude,
+  sandboxPathToKey,
+} from './lib/content';
+export { getContentRoot, isDispatched } from './lib/contentRoot';
+export { layoutChainForKey } from './lib/layout';
+export { queryPaths, readingTime, stripFrontmatter } from './lib/wiki';

package/src/main.tsx

@@ -0,0 +1,19 @@
+// Entry point. immediately.run runs this module (package.json "main") and
+// boot() installs the host runtime providers (module cache, MDX provider,
+// TinkerableContext, router) and renders into #root. Global CSS is imported
+// here so it is present at runtime.
+import './index.css';
+import './GroveApp.css';
+import { boot } from '@immediately-run/sdk/boot';
+import { GROVE_MDX } from './mdxComponents';
+import App from './App';
+
+// A single catch-all route renders the Grove shell for every URL; the shell
+// reads the current path from TinkerableContext and renders the matching entry,
+// so the nav/footer/theme chrome persists across navigation.
+boot({
+  mdxComponents: GROVE_MDX as never,
+  routingSpec: {
+    routes: [{ name: 'grove', pattern: /.*/, reactNode: <App /> }],
+  },
+});

package/src/mdx.d.ts

@@ -0,0 +1,9 @@
+// Lets TypeScript treat `import Article from './x.mdx'` as a React component.
+// immediately.run renders .mdx natively; the Vite MDX plugin (vite.config.ts)
+// keeps local build/lint in sync. Use .mdx ONLY for long-form prose, never for
+// structured/repeated data (that belongs in src/data/*.ts).
+declare module '*.mdx' {
+  import type { ComponentType } from 'react';
+  const MDXComponent: ComponentType;
+  export default MDXComponent;
+}

package/src/mdxComponents.ts

@@ -0,0 +1,89 @@
+import { DEFAULT_MDX_COMPONENTS } from '@immediately-run/sdk';
+import { SAFE_INTRINSICS } from './lib/safeIntrinsics';
+import AssetImage from './components/AssetImage';
+import Callout from './components/Callout';
+import Lede from './components/Lede';
+import Infobox from './components/Infobox';
+import More from './components/More';
+import DocList from './components/DocList';
+import TagCloud from './components/TagCloud';
+import TagList from './components/TagList';
+import Directory from './components/Directory';
+import DirectoryList from './components/DirectoryList';
+import WikiLink from './components/WikiLink';
+import Quote from './components/Quote';
+import KeyValue from './components/KeyValue';
+import Kbd from './components/Kbd';
+import Toc from './components/Toc';
+import TableOfContents from './components/TableOfContents';
+import Backlinks from './components/Backlinks';
+import PageMeta from './components/PageMeta';
+import RecentlyUpdated from './components/RecentlyUpdated';
+import DocsByTag from './components/DocsByTag';
+import ChildPages from './components/ChildPages';
+import Timeline from './components/Timeline';
+import FamilyTree from './components/FamilyTree';
+import Outlet from './components/Outlet';
+import GroveNav from './components/GroveNav';
+import GroveFooter from './components/GroveFooter';
+import Sidebar from './components/Sidebar';
+
+// The import-free component vocabulary every entry shares (Grove's "engine
+// components" tier). Registered into the MDXProvider by boot(), so MDX uses them
+// with no import line. `a` is overridden with the wiki-link resolver (resolved /
+// broken / self states); `img` resolves mount-relative assets off the fs.
+//
+// boot() merges this map OVER the SDK's DEFAULT_MDX_COMPONENTS (@immediately-run/sdk
+// ≥ 0.23.0, MARKDOWN_SYNTAX_SPEC §11.3), so the platform defaults (default `a`,
+// `Admonition`, `WikiLink`) are inherited automatically — do NOT re-add a manual
+// `...DEFAULT_MDX_COMPONENTS` spread here (redundant under merge semantics).
+export const GROVE_MDX = {
+  a: WikiLink,
+  img: AssetImage,
+  Callout,
+  Lede,
+  Infobox,
+  More,
+  DocList,
+  TagCloud,
+  TagList,
+  Directory,
+  DirectoryList,
+  Quote,
+  KeyValue,
+  Kbd,
+  Toc,
+  TableOfContents,
+  Backlinks,
+  PageMeta,
+  RecentlyUpdated,
+  DocsByTag,
+  ChildPages,
+  Timeline,
+  FamilyTree,
+  // Layout primitives — a `_layout.mdx` arranges the shell out of these around an
+  // <Outlet/>, so the site chrome is content (see src/lib/layout.ts).
+  Outlet,
+  GroveNav,
+  GroveSidebar: Sidebar,
+  GroveFooter,
+};
+
+// The map the INTERPRETER (safe) renderer consumes — one definition, used by both
+// `SafeEntryBody` (entry bodies) and `SafeLayout` (the `_layout.mdx` chain), so the two
+// halves of a safe-rendered page can never drift apart in what they resolve. (R3-263)
+//
+// Layered exactly as `boot()` layers the compiled path, so a document renders identically
+// under either standard: the SDK's platform defaults (Admonition / WikiLink / HeadingAnchor,
+// carrying the deep-link resolver) UNDER the Grove vocabulary above — plus the sanitizing
+// structural tags (`src/lib/safeIntrinsics.tsx`), which the compiled path gets for free from
+// JSX and the safe path must be handed explicitly.
+//
+// Precedence is deliberate: intrinsics go on the BOTTOM. `GROVE_MDX` overrides `a` and `img`
+// with <WikiLink>/<AssetImage>, and those must win — SAFE_INTRINSICS does not register `a`
+// or `img` at all, but ordering it last would be a trap for whoever adds them.
+export const SAFE_MDX = {
+  ...SAFE_INTRINSICS,
+  ...(DEFAULT_MDX_COMPONENTS as Record<string, unknown>),
+  ...GROVE_MDX,
+};

package/src/test/setup.ts

@@ -0,0 +1,19 @@
+// A stub host transport, installed before any test imports the SDK.
+//
+// `@immediately-run/sdk`'s root module wires a debug push-channel at import time, and with
+// no transport that THROWS during module evaluation — so a component test fails at import
+// with "no host transport" before a single assertion runs, which reads like a broken test
+// file rather than a missing environment. Inside immediately.run the host injects this
+// object; here it is inert (nothing under test sends a message).
+//
+// Deliberately not a mock of anything: tests that care about host traffic should inject
+// their own doubles rather than reach for this.
+const noop = (): void => undefined;
+
+(globalThis as { __immediatelyRun__?: unknown }).__immediatelyRun__ = {
+  transport: {
+    sendMessage: noop,
+    protocolRequest: async () => ({}),
+    onMessage: () => ({ dispose: noop }),
+  },
+};