@immediately-run/grove 0.1.1

package/src/lib/openWiki.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { resolveOpenWiki, OPEN_WIKI_TASK, CONTENT_MOUNT_TYPE } from './openWiki';
+import { getContentRoot, setContentRoot, resetContentRoot, isDispatched, APP_CONTENT_ROOT } from './contentRoot';
+import { slugToKey, isContentEntry, homeKey, contentDir, keyToHref, sandboxPathToKey } from './content';
+import { layoutChainForKey } from './layout';
+import type { SandboxMount } from '@immediately-run/sdk/mounts';
+
+const mount = (path: string, extra: Partial<SandboxMount> = {}): SandboxMount =>
+  ({ path, type: 'task', ...extra }) as SandboxMount;
+
+afterEach(resetContentRoot);
+
+describe('resolveOpenWiki — the delegated corpus', () => {
+  it('resolves the dir param mounted at the host-minted chroot', () => {
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/task/t1/dir')]);
+    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: false, via: 'task' });
+  });
+
+  it('reports a read-only delegation without refusing it', () => {
+    // Sharing a corpus read-only is legitimate — the reader still reads. Only the WRITE
+    // affordances may consult this; refusing the whole open would break the ordinary case.
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/task/t1/dir', { mode: 'ro' })]);
+    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: true, via: 'task' });
+  });
+
+  it('is not a callee when there is no task input — the ordinary fork boot', () => {
+    expect(resolveOpenWiki(null, [mount('/app')])).toEqual({ ok: false, reason: 'not-a-callee' });
+  });
+
+  it('refuses a task it does not provide', () => {
+    expect(resolveOpenWiki({ task: 'edit-file', params: {} }, [mount('/task/t1/file')]))
+      .toEqual({ ok: false, reason: 'wrong-task' });
+  });
+
+  it('reports no-mount rather than falling back to its OWN corpus', () => {
+    // The dangerous failure: rendering the viewer's repo while the reader believes they
+    // are looking at the delegated one. Silence is not an option here — cancel instead.
+    expect(resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app')]))
+      .toEqual({ ok: false, reason: 'no-mount' });
+  });
+
+  it('never mistakes the app\'s own repo mount for the delegation', () => {
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/app/dir')]);
+    expect(r).toEqual({ ok: false, reason: 'no-mount' });
+  });
+
+  it('takes a single unambiguous foreign mount when the param segment is not the hook', () => {
+    // The host owns the `/task/<slot>/<param>` grammar; if it ever renames the segment,
+    // suffix-matching alone would cancel a task the user really asked for.
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/mnt/abc123')]);
+    expect(r).toEqual({ ok: true, root: '/mnt/abc123', readOnly: false, via: 'task' });
+  });
+
+  it('does not guess between two foreign mounts', () => {
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/mnt/a'), mount('/mnt/b')]);
+    expect(r).toEqual({ ok: false, reason: 'no-mount' });
+  });
+
+  it('honours a canonical app mount path that is not /app', () => {
+    // The repo is dual-mounted at /app and /mnt/{hash}; the host reports the canonical
+    // one. Hardcoding /app here would read the viewer's own corpus as the delegation.
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/mnt/self')], '/mnt/self');
+    expect(r).toEqual({ ok: false, reason: 'no-mount' });
+  });
+});
+
+describe('repo-load dispatch — a cold URL load, with no task input at all', () => {
+  it('resolves the corpus from the MARKED mount', () => {
+    // R3-172: the URL named a content repo; the host resolved this viewer through the
+    // binding table and published the corpus stamped `type: 'content'`.
+    const r = resolveOpenWiki(null, [
+      mount('/app'),
+      mount('/mnt/deadbeef', { type: CONTENT_MOUNT_TYPE, name: 'neumark/book-nine-from-here' }),
+    ]);
+    expect(r).toEqual({ ok: true, root: '/mnt/deadbeef', readOnly: false, via: 'repo-load' });
+  });
+
+  it('carries a read-only delegation through', () => {
+    const r = resolveOpenWiki(null, [mount('/mnt/x', { type: CONTENT_MOUNT_TYPE, mode: 'ro' })]);
+    expect(r).toMatchObject({ ok: true, readOnly: true, via: 'repo-load' });
+  });
+
+  it('answers FORK immediately when there are no mounts at all', () => {
+    // Measured, not assumed: a plain present-mode fork publishes NO mounts — worktrees,
+    // spaces and dispatched corpora are published, the app's own repo arrives as `/app`
+    // through the bundler. So an empty set must mean "fork, render now", never "wait and
+    // see", or every ordinary wiki pays a grace period for a guess that never pays off.
+    expect(resolveOpenWiki(null, [])).toEqual({ ok: false, reason: 'not-a-callee' });
+  });
+
+  it('is NOT fooled by an unmarked foreign mount when there is no task', () => {
+    // The whole reason the host marks it: a reader who holds a space has a foreign mount
+    // that is not a corpus. Guessing here would render somebody's space as a wiki.
+    expect(resolveOpenWiki(null, [mount('/app'), mount('/spaces/s1', { type: 'firestore' })]))
+      .toEqual({ ok: false, reason: 'not-a-callee' });
+    expect(resolveOpenWiki(null, [mount('/app'), mount('/mnt/wt', { type: 'worktree' })]))
+      .toEqual({ ok: false, reason: 'not-a-callee' });
+  });
+
+  it('prefers the marked mount over a task delegation, and says which', () => {
+    // Both present is not a real shape today, but the precedence must be decided rather
+    // than emergent: the mark is the host's explicit statement about THIS load.
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [
+      mount('/task/t1/dir'),
+      mount('/mnt/marked', { type: CONTENT_MOUNT_TYPE }),
+    ]);
+    expect(r).toMatchObject({ root: '/mnt/marked', via: 'repo-load' });
+  });
+});
+
+describe('contentRoot — the corpus location is a runtime value', () => {
+  it('defaults to the fork packaging and reports itself as not dispatched', () => {
+    expect(getContentRoot()).toBe(APP_CONTENT_ROOT);
+    expect(isDispatched()).toBe(false);
+  });
+
+  it('normalizes a missing trailing slash, so every startsWith/slice holds', () => {
+    setContentRoot('/task/t1/dir');
+    expect(getContentRoot()).toBe('/task/t1/dir/');
+    expect(isDispatched()).toBe(true);
+  });
+
+  it('re-points every helper built on the root, not just the constant', () => {
+    // The reason this is a function and not a constant: these helpers are what nav,
+    // routing, the sidebar and the layout chain are made of. If any one of them kept the
+    // build-time root, a dispatched Grove would render a MIXTURE of two corpora.
+    setContentRoot('/task/t1/dir');
+    expect(contentDir()).toBe('/task/t1/dir/');
+    expect(homeKey()).toBe('/task/t1/dir/home.mdx');
+    expect(slugToKey('characters/the-cast')).toBe('/task/t1/dir/characters/the-cast.mdx');
+    expect(isContentEntry('/task/t1/dir/themes.mdx')).toBe(true);
+    // …and the viewer's OWN corpus stops being content once it is not the root.
+    expect(isContentEntry('/app/content/home.mdx')).toBe(false);
+  });
+
+  it('builds the layout chain from the delegated root', () => {
+    setContentRoot('/task/t1/dir');
+    const corpus = {
+      '/task/t1/dir/_layout.mdx': {},
+      '/task/t1/dir/plot/_layout.mdx': {},
+      '/task/t1/dir/plot/the-rail.mdx': {},
+    };
+    expect(layoutChainForKey('/task/t1/dir/plot/the-rail.mdx', corpus)).toEqual([
+      '/task/t1/dir/_layout.mdx',
+      '/task/t1/dir/plot/_layout.mdx',
+    ]);
+  });
+});
+
+describe('routing — the URL space follows the packaging', () => {
+  it('leaves a FORK\'s URLs byte-identical', () => {
+    // These are published, cited and deep-linked. A "tidy-up" here breaks every shared
+    // link into the docs wiki, so the fork mapping is pinned rather than merely tested.
+    expect(keyToHref('/app/content/specs/TRUST_MODES_SPEC.mdx')).toBe('/content/specs/TRUST_MODES_SPEC.mdx');
+    expect(sandboxPathToKey('/content/specs/TRUST_MODES_SPEC.mdx')).toBe('/app/content/specs/TRUST_MODES_SPEC.mdx');
+    expect(sandboxPathToKey('/files/content/home.mdx')).toBe('/app/content/home.mdx');
+    expect(sandboxPathToKey('/')).toBe('/app/content/home.mdx');
+  });
+
+  it('makes a DISPATCHED viewer\'s URLs corpus-relative', () => {
+    // The mount is chrooted AT the content directory, so the mount root IS the corpus
+    // root — there is no app-root left to measure from.
+    setContentRoot('/task/t1/dir');
+    expect(keyToHref('/task/t1/dir/plot/the-rail.mdx')).toBe('/plot/the-rail.mdx');
+    expect(sandboxPathToKey('/plot/the-rail.mdx')).toBe('/task/t1/dir/plot/the-rail.mdx');
+    expect(sandboxPathToKey('/files/plot/the-rail.mdx')).toBe('/task/t1/dir/plot/the-rail.mdx');
+    expect(sandboxPathToKey('/')).toBe('/task/t1/dir/home.mdx');
+  });
+
+  it('round-trips key → href → key under both packagings', () => {
+    // The pair has to be symmetric or a link renders to a URL that resolves to a different
+    // entry — the R3-252 class of failure, where navigation lands on the wrong document.
+    const fork = '/app/content/plot/the-rail.mdx';
+    expect(sandboxPathToKey(keyToHref(fork))).toBe(fork);
+    setContentRoot('/task/t1/dir');
+    const dispatched = '/task/t1/dir/plot/the-rail.mdx';
+    expect(sandboxPathToKey(keyToHref(dispatched))).toBe(dispatched);
+  });
+
+  it('refuses a traversal that keeps the content-root PREFIX — the shipped-fork shape', () => {
+    // ⚠ This is the pre-existing defect, and it is a FORK bug too, not only a dispatch one.
+    // The escape needs the `..` to come AFTER the content segment, so the raw-text check
+    // passes while the path resolves elsewhere:
+    //
+    //   /files/content/../../src/App.tsx  →  /app/content/../../src/App.tsx  →  /src/App.tsx
+    //   /content/../../../spaces/s1/x.md  →  …                              →  /spaces/s1/x.md
+    //
+    // The second is the one that matters: it leaves the app's own repo for ANOTHER MOUNT.
+    // The resulting key is what `fs.readFile` gets (bodies, reading time, backlinks) and
+    // what `<Include filename>` gets on the compiled path — where it is EVALUATED.
+    expect(sandboxPathToKey('/files/content/../../src/App.tsx')).toBe('/app/content/home.mdx');
+    expect(sandboxPathToKey('/content/../../../spaces/s1/private.md')).toBe('/app/content/home.mdx');
+    expect(sandboxPathToKey('/content/../.claude/memory/x.md')).toBe('/app/content/home.mdx');
+    // A `..` that stays inside the corpus is not an escape and still resolves.
+    expect(sandboxPathToKey('/content/plot/../home.mdx')).toBe('/app/content/home.mdx');
+    expect(sandboxPathToKey('/content/plot/../themes.mdx')).toBe('/app/content/themes.mdx');
+  });
+
+  it('sends a path OUTSIDE the corpus home rather than reading it', () => {
+    // Under dispatch this is the guard that stops a crafted URL from naming a file outside
+    // the delegation: it can only ever resolve to an entry inside the content root.
+    setContentRoot('/task/t1/dir');
+    // Traversal resolves and lands outside → home. The check must run on the RESOLVED
+    // path: `/task/t1/dir/../../app/src/App.tsx` starts with the content root as a string
+    // and is a different file as a path, and this key is what `fs.readFile` receives.
+    expect(sandboxPathToKey('/../../app/src/App.tsx')).toBe('/task/t1/dir/home.mdx');
+    expect(sandboxPathToKey('/plot/../../../etc/passwd')).toBe('/task/t1/dir/home.mdx');
+
+    // A URL that merely LOOKS like the viewer's own app path is not one: under dispatch
+    // `/app` has no special meaning, so this is an ordinary corpus-relative path that
+    // stays inside the delegation and simply has no entry (the 404 index).
+    const key = sandboxPathToKey('/app/content/home.mdx');
+    expect(key.startsWith('/task/t1/dir/')).toBe(true);
+    expect(key).toBe('/task/t1/dir/app/content/home.mdx');
+  });
+});

package/src/lib/openWiki.ts

@@ -0,0 +1,84 @@
+// The `open-wiki` provider (R3-169) — Grove as a task callee.
+//
+// A caller that finds `opensWith: { task: 'open-wiki' }` on a directory it can read
+// invokes the contract with `dir: capDir(...)`. The host attenuates that against the
+// CALLER's own grants, mints a task-scoped chroot, and mounts it for us. So everything
+// below is downstream of authority we never asked for and cannot widen: the mount IS the
+// grant (`docs/specs/REPO_CONTENT_DISPATCH_SPEC.mdx` §1/§4, UI_AS_APPS_SPEC §5.7).
+//
+// The marker named the CONTRACT, not this app — the host's binding table chose Grove and
+// a user can rebind it to their own fork. Nothing here may assume it is the only viewer.
+
+import type { SandboxMount } from '@immediately-run/sdk/mounts';
+import type { TaskInput } from '@immediately-run/sdk/tasks';
+
+/** The contract this module provides, and the param carrying the corpus. */
+export const OPEN_WIKI_TASK = 'open-wiki';
+export const DIR_PARAM = 'dir';
+
+/** The mount `type` the host stamps on a corpus it dispatched by REPO LOAD (R3-172).
+ *
+ *  A cold URL load has no task invocation, so there is no `useTaskInput()` to learn from —
+ *  the mount itself has to carry the role. We key on this mark and NOT on "the only foreign
+ *  mount", which reads as clever and guesses wrong the moment the reader also holds a space
+ *  or a worktree. If the host did not mark it, we are not dispatched. */
+export const CONTENT_MOUNT_TYPE = 'content';
+
+export type OpenWikiResolution =
+  | { ok: true; root: string; readOnly: boolean; via: 'task' | 'repo-load' }
+  | { ok: false; reason: 'not-a-callee' | 'wrong-task' | 'no-mount' };
+
+/**
+ * Where the delegated corpus is, from the task input and the mount set — pure, so the
+ * whole resolution is testable without a host.
+ *
+ * The host mounts a directory delegation at `/task/<slot>/<paramKey>` (§5.7: for a DIR
+ * cap the mount point *is* the directory), so the param name is the hook. We match on the
+ * path SUFFIX rather than reconstructing the slot, because the slot is the host's to
+ * name and reconstructing it here would couple this app to a private path grammar.
+ *
+ * The single-non-app-mount fallback exists because that coupling is the failure we can't
+ * see: if the host ever renames the segment, suffix-matching alone would resolve to
+ * nothing and Grove would cancel a task the user really did ask for. One unambiguous foreign
+ * mount is not a guess.
+ */
+export function resolveOpenWiki(
+  input: TaskInput | null,
+  mounts: readonly SandboxMount[],
+  appMountPath = '/app',
+): OpenWikiResolution {
+  // REPO-LOAD dispatch (R3-172): the URL named a content repo, the host resolved this
+  // viewer through the binding table and published the corpus as a marked mount. There is
+  // no task to be a callee of — checked FIRST, because a repo-load dispatch has no task
+  // input and would otherwise fall out as `not-a-callee` and render our own corpus.
+  const marked = mounts.find((m) => m.type === CONTENT_MOUNT_TYPE);
+  if (marked) {
+    return { ok: true, root: marked.path, readOnly: marked.mode === 'ro', via: 'repo-load' };
+  }
+
+  if (!input) return { ok: false, reason: 'not-a-callee' };
+  if (input.task !== OPEN_WIKI_TASK) return { ok: false, reason: 'wrong-task' };
+
+  const foreign = mounts.filter((m) => m.path !== appMountPath && !m.path.startsWith(`${appMountPath}/`));
+  const byParam = foreign.filter((m) => m.path === `/${DIR_PARAM}` || m.path.endsWith(`/${DIR_PARAM}`));
+  const hit = byParam[0] ?? (foreign.length === 1 ? foreign[0] : undefined);
+  if (!hit) return { ok: false, reason: 'no-mount' };
+
+  // `mode` is absent on the primary repo mount and rw by default elsewhere. A read-only
+  // delegation is a legitimate way to share a corpus — the reader still reads — so it
+  // resolves normally and only the WRITE affordances consult this flag.
+  return { ok: true, root: hit.path, readOnly: hit.mode === 'ro', via: 'task' };
+}
+
+/** The message a failed resolution should show, in the reader's terms rather than the
+ *  protocol's. `not-a-callee` never surfaces — it is the ordinary fork boot. */
+export function openWikiFailureMessage(reason: Exclude<OpenWikiResolution, { ok: true }>['reason']): string {
+  switch (reason) {
+    case 'wrong-task':
+      return 'This viewer was opened with a task it does not provide.';
+    case 'no-mount':
+      return 'The folder to open was not delivered. Try opening it again.';
+    default:
+      return '';
+  }
+}

package/src/lib/queries.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { familyTreeQuery, navQuery, searchQuery, sidebarQuery } from './queries';
+
+// The metadata queries select records (R3-276a). These tests pin the selections
+// themselves; the components are thin wiring around them. The store shape is the
+// real one the hooks hand a query: absolute paths → frontmatter maps.
+
+const fm = {
+  '/app/content/index.mdx': { title: 'Home.', nav: 'Start', tags: ['ui/nav'], order: 2 },
+  '/app/content/docs.mdx': { title: 'Docs', tags: ['ui/nav'], order: 1 },
+  '/app/content/people/ada.mdx': { title: 'Ada Lovelace', team: 'Engineering', tags: ['person'] },
+  '/app/content/people/jobs.mdx': { name: 'Steve Jobs', parent: 'Home', tags: ['ui/hidden'] },
+  '/app/content/_layout.mdx': { title: 'Not an entry', tags: ['ui/nav'], team: 'X' },
+  '/app/src/App.tsx': { title: 'not content', tags: ['ui/nav'] },
+};
+
+describe('navQuery', () => {
+  it('selects ui/nav entries ordered by `order` (missing = 999), label from nav else title', () => {
+    expect(navQuery(fm)).toEqual([
+      { path: '/app/content/docs.mdx', label: 'Docs' },
+      { path: '/app/content/index.mdx', label: 'Start' },
+    ]);
+  });
+
+  it('trims a trailing period from a title-derived label', () => {
+    expect(navQuery({ '/app/content/a.mdx': { title: 'A.', tags: ['ui/nav'] } })[0].label).toBe('A');
+  });
+
+  it('never tab-encodes (the R3-276a regression: fake paths are gone)', () => {
+    for (const r of navQuery(fm)) expect(JSON.stringify(r)).not.toContain('\t');
+  });
+});
+
+describe('searchQuery', () => {
+  it('indexes every content entry with title/desc and non-ui tags', () => {
+    const rows = searchQuery(fm);
+    expect(rows).toHaveLength(4); // entries only: no _layout.mdx, no src/
+    const ada = rows.find((r) => r.path.endsWith('ada.mdx'))!;
+    expect(ada.title).toBe('Ada Lovelace');
+    expect(ada.tags).toEqual(['person']);
+  });
+
+  it('drops the ui/* furniture namespace from tags', () => {
+    expect(searchQuery(fm).find((r) => r.path.endsWith('jobs.mdx'))!.tags).toEqual([]);
+  });
+});
+
+describe('sidebarQuery', () => {
+  it('indexes every entry with title, raw tags (ui/* kept), and nav', () => {
+    const rows = sidebarQuery(fm);
+    expect(rows).toHaveLength(4);
+    const home = rows.find((r) => r.path.endsWith('index.mdx'))!;
+    expect(home.title).toBe('Home.');
+    expect(home.nav).toBe('Start');
+    expect(home.tags).toEqual(['ui/nav']);
+  });
+});
+
+describe('familyTreeQuery', () => {
+  it('groups by house/team/parent/manager in that fallback order', () => {
+    expect(familyTreeQuery(fm)).toEqual([
+      { path: '/app/content/people/ada.mdx', label: 'Ada Lovelace', group: 'Engineering' },
+      { path: '/app/content/people/jobs.mdx', label: 'Steve Jobs', group: 'Home' },
+    ]);
+  });
+
+  it('needs both a group and a name/title; layout files are not entries', () => {
+    const out = familyTreeQuery({
+      '/app/content/x.mdx': { team: 'Engineering' }, // no name/title
+      '/app/content/_layout.mdx': { team: 'X', title: 'L' }, // not an entry
+    });
+    expect(out).toEqual([]);
+  });
+});

package/src/lib/queries.ts

@@ -0,0 +1,84 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// The wiki's metadata queries, as pure functions (R3-276a).
+//
+// These were inline callbacks in GroveWiki/Search/FamilyTree that had to
+// TAB-ENCODE extra fields into fake paths (`[p, label].join('\t')`) because
+// `useMetadataQuery` could only return path strings. The SDK now returns
+// RECORDS (`{ path, ...extra }`, R3-276) and these are the same selections said
+// directly — extracted here so the selection logic is testable without React
+// and the three consumers share one definition of "entry", "label", "group".
+//
+// Every record field is derived data; `path`/`meta` are applied by the hook.
+
+import { isContentEntry } from './content';
+
+/** A nav item derived from `ui/nav` frontmatter. */
+export type NavRecord = {
+  path: string;
+  /** `nav` if the entry names itself, else its title with the trailing period trimmed. */
+  label: string;
+};
+
+/** Entries tagged `ui/nav`, ordered by `order` (missing = 999). */
+export function navQuery(fm: Record<string, any>): NavRecord[] {
+  return Object.keys(fm)
+    .filter((p) => isContentEntry(p) && Array.isArray(fm[p]?.tags) && fm[p].tags.includes('ui/nav'))
+    .sort((a, b) => (fm[a].order ?? 999) - (fm[b].order ?? 999))
+    .map((p) => ({ path: p, label: fm[p]?.nav || (fm[p]?.title || '').replace(/\.$/, '') }));
+}
+
+/** One search index row. `tags` excludes the `ui/*` furniture namespace. */
+export type SearchRecord = {
+  path: string;
+  title: string;
+  desc: string;
+  tags: string[];
+};
+
+/** Every content entry, flattened for the ⌘K palette. */
+export function searchQuery(fm: Record<string, any>): SearchRecord[] {
+  return Object.keys(fm)
+    .filter(isContentEntry)
+    .map((p) => ({
+      path: p,
+      title: fm[p]?.title || '',
+      desc: fm[p]?.description || '',
+      tags: (fm[p]?.tags || []).filter((t: string) => !t.startsWith('ui/')),
+    }));
+}
+
+/** One sidebar row: the whole entry index with the fields the tree + the
+ *  `ui/sidebar` sections derive from. */
+export type SidebarRecord = {
+  path: string;
+  title: string;
+  tags: string[];
+  nav: string;
+};
+
+/** Every content entry, for the sidebar tree + its `ui/sidebar` sections. */
+export function sidebarQuery(fm: Record<string, any>): SidebarRecord[] {
+  return Object.keys(fm)
+    .filter(isContentEntry)
+    .map((p) => ({ path: p, title: fm[p]?.title || '', tags: fm[p]?.tags || [], nav: fm[p]?.nav || '' }));
+}
+
+/** A node in the relational view: grouped by house/team/parent/manager. */
+export type FamilyNodeRecord = {
+  path: string;
+  label: string;
+  group: string;
+};
+
+/** Entries with a relationship field and something to call them. */
+export function familyTreeQuery(fm: Record<string, any>): FamilyNodeRecord[] {
+  const out: FamilyNodeRecord[] = [];
+  Object.entries(fm).forEach(([p, m]: [string, any]) => {
+    if (!isContentEntry(p)) return;
+    const group = m?.house || m?.team || m?.parent || m?.manager;
+    if (group && (m?.name || m?.title)) {
+      out.push({ path: p, label: (m.name || m.title).replace(/\.$/, ''), group: String(group) });
+    }
+  });
+  return out;
+}

package/src/lib/safeIntrinsics.test.tsx

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { parseSafeMdast, renderMdast } from '@immediately-run/sdk/safeContent/index';
+import { SAFE_INTRINSICS, filterIntrinsicProps } from './safeIntrinsics';
+
+// The structural-tag allow-list, proven against the REAL published safe renderer plus real
+// React DOM rendering — because the property at stake ("a content file cannot reach the DOM
+// with an arbitrary attribute") is only observable in the rendered markup. (R3-263)
+
+/** Parse MDX-syntax source and render it to static markup through the safe renderer. */
+async function render(src: string, components: Record<string, unknown>): Promise<string> {
+  const tree = await parseSafeMdast(src);
+  return renderToStaticMarkup(renderMdast(tree, { components: components as never }) as never);
+}
+
+/** A block-level intrinsic must be opened on its OWN line to parse as JSX — see the
+ *  micromark case below — so every fixture here uses that shape. */
+const block = (open: string, inner = 'text') => [open, `  ${inner}`, `</${open.match(/^<(\w+)/)![1]}>`].join('\n');
+
+describe('safe intrinsics — the allow-list is the barrier, not React', () => {
+  it('renders an allow-listed tag with its allow-listed attributes', async () => {
+    const html = await render(block('<main className="grove-content" id="x">'), SAFE_INTRINSICS);
+    expect(html).toContain('<main class="grove-content" id="x">');
+    expect(html).toContain('text');
+  });
+
+  it('drops `style`, which as a STRING crashes the render — and the render is the layout', async () => {
+    // React: "The `style` prop expects a mapping from style properties to values, not a
+    // string." A throw here takes down the whole shell, for every page, from one content
+    // file — so this is an availability defect, not a cosmetic one.
+    await expect(render(block('<main style="color:red">'), SAFE_INTRINSICS)).resolves.toContain('<main>');
+    // Non-vacuous: the RAW tag really does throw, which is why the wrapper exists.
+    await expect(render(block('<main style="color:red">'), { main: 'main' })).rejects.toThrow(/style/i);
+  });
+
+  it('drops `dangerouslySetInnerHTML`, which also crashes the render', async () => {
+    await expect(render(block('<main dangerouslySetInnerHTML="<b>x</b>">'), SAFE_INTRINSICS)).resolves.toContain('<main>');
+    await expect(render(block('<main dangerouslySetInnerHTML="<b>x</b>">'), { main: 'main' })).rejects.toThrow();
+  });
+
+  it('drops event handlers and URL-bearing attributes outright', async () => {
+    const html = await render(block('<main onclick="alert(1)" href="javascript:alert(2)" srcdoc="<script>x</script>">'), SAFE_INTRINSICS);
+    expect(html).toBe('<main><p>text</p></main>');
+  });
+
+  it('passes `data-*` and `aria-*` through, since they carry no behaviour', () => {
+    expect(filterIntrinsicProps({ 'data-x': '1', 'aria-label': 'y', onclick: 'z', style: 'a' }))
+      .toEqual({ 'data-x': '1', 'aria-label': 'y' });
+  });
+
+  it('does NOT register `a`/`img` — those stay the resolving, sanitizing Grove versions', () => {
+    // Registering the raw tags here would silently bypass <WikiLink>'s resolution and
+    // <AssetImage>'s mount-relative lookup, which is the whole reason they are overrides.
+    expect(SAFE_INTRINSICS.a).toBeUndefined();
+    expect(SAFE_INTRINSICS.img).toBeUndefined();
+  });
+
+  it('does NOT register `iframe` — React passes `srcdoc` straight through', async () => {
+    expect(SAFE_INTRINSICS.iframe).toBeUndefined();
+    // Recorded as the reason: with the raw tag registered, the markup really does carry it.
+    const html = await render(block('<iframe srcdoc="<script>alert(1)</script>">'), { iframe: 'iframe' });
+    expect(html).toContain('srcdoc');
+  });
+
+  it('does NOT register headings — a JSX heading would carry no `sec-…` id to cite', async () => {
+    expect(SAFE_INTRINSICS.h2).toBeUndefined();
+    // A markdown heading gets the id; that is the authoring route to keep.
+    const tree = await parseSafeMdast('## 8.9 Something');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const h = (tree.children as any[]).find((n) => n.type === 'heading');
+    expect(h?.data?.hProperties?.id).toBe('sec-8-9');
+  });
+
+  it('an UNREGISTERED tag collapses to a Fragment that keeps its children', async () => {
+    // The failure mode is silent — the wrapper and its class vanish, the content stays —
+    // which is why the tags a layout needs are registered rather than left to this.
+    const html = await render(block('<figure className="x">'), {});
+    expect(html).toBe('<p>text</p>');
+  });
+});
+
+describe('the micromark gotcha that makes intrinsics look broken', () => {
+  it('a lowercase tag opened on its own line parses as JSX', async () => {
+    const tree = await parseSafeMdast(block('<main className="x">'));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((tree.children as any[])[0]).toMatchObject({ type: 'mdxJsxFlowElement', name: 'main' });
+  });
+
+  it('the SAME tag with inline content on one line is an HTML block — inert text', async () => {
+    // Not a bug in the renderer: micromark's HTML-block rule wins. It matters because the
+    // symptom is "my layout renders as visible angle brackets" with no error anywhere, and
+    // the fix is a line break, which nobody guesses. Pinned so the two shapes stay distinct.
+    const tree = await parseSafeMdast('<main className="x">text</main>');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((tree.children as any[])[0]).toMatchObject({ type: 'html' });
+    const html = await render('<main className="x">text</main>', SAFE_INTRINSICS);
+    expect(html).not.toContain('<main');
+  });
+});

package/src/lib/safeIntrinsics.tsx

@@ -0,0 +1,77 @@
+import { createElement } from 'react';
+import type { ComponentType, ReactNode } from 'react';
+
+// The structural HTML tags a CONTENT file may use under the interpreter (safe) renderer,
+// each wrapped so only allow-listed attributes reach the DOM. (R3-263)
+//
+// WHY WRAPPERS AND NOT RAW TAGS. `renderMdast` looks a JSX tag up in the component map by
+// name and, on a hit, spreads the element's literal attributes onto it. The SDK's
+// `literalProps` does **no name filtering and no URL sanitizing** — it copies every literal
+// `mdxJsxAttribute` verbatim. So registering `main: 'main'` would hand a content author a
+// direct channel to a real DOM element's props. Measured against React 19 before choosing
+// this design:
+//
+//   <main onclick="alert(1)">      → React DROPS it (lowercase `on*` is never emitted)
+//   <a href="javascript:alert(1)"> → React BLOCKS it (replaced with a throwing sentinel)
+//   <img onerror="alert(1)">       → React DROPS it
+//   <main style="color:red">       → **THROWS** — "style prop expects a mapping … not a string"
+//   <main dangerouslySetInnerHTML="…"> → **THROWS** — cannot set with children
+//   <iframe srcdoc="<script>…">    → **PASSES THROUGH** — a live XSS
+//
+// So React defends the two vectors people think of first and defends neither of the last
+// two. The two throwing cases are not XSS but they are worse than they look: the throw is
+// in the LAYOUT, so one content file takes down the entire shell for every page. And the
+// `iframe` case is only absent here because `iframe` is not on the list — which is exactly
+// the argument for a closed list rather than a filter people extend ad hoc.
+//
+// The rule, therefore: a closed set of purely structural tags, an allow-list of inert
+// attributes, and no reliance on React's internal defenses as the only barrier.
+//
+// NOT REGISTERED, deliberately:
+//   • `a` / `img` — already in the map as <WikiLink>/<AssetImage>, which resolve and
+//     sanitize. Registering the raw tags would silently bypass both.
+//   • `iframe`, `object`, `embed`, `script`, `style`, `link`, `meta`, `form`, `input`,
+//     `button` — executable, navigational, or capable of carrying markup (`srcdoc`).
+//   • `h1`–`h6` — a JSX heading skips the shared heading-anchor plugin, so it would carry
+//     no `sec-…` id and no `data-slug`, and every citation to it would dangle. Author
+//     headings as markdown (`## 8.9 …`) and the ids come for free.
+const ALLOWED_TAGS = [
+  'main', 'section', 'article', 'aside', 'nav', 'header', 'footer',
+  'div', 'span', 'p', 'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+  'figure', 'figcaption', 'blockquote', 'strong', 'em', 'small', 'hr', 'br',
+] as const;
+
+/** Inert, presentational attributes. Anything not here — `style`, `on*`,
+ *  `dangerouslySetInnerHTML`, `href`, `src`, `srcdoc` — is dropped before React sees it. */
+const ALLOWED_ATTRS = new Set(['className', 'id', 'title', 'lang', 'dir', 'role']);
+
+/** `data-*` and `aria-*` are open-ended by design and carry no behaviour, so they pass as
+ *  a prefix rule rather than being enumerated. */
+function isAllowedAttr(name: string): boolean {
+  return ALLOWED_ATTRS.has(name) || name.startsWith('data-') || name.startsWith('aria-');
+}
+
+/** Drop every attribute not on the allow-list. Exported shape is a plain object so the
+ *  caller can spread it; the filtering is the whole point, so it is tested directly. */
+export function filterIntrinsicProps(props: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(props)) {
+    if (k === 'children') continue;
+    if (isAllowedAttr(k)) out[k] = v;
+  }
+  return out;
+}
+
+function wrap(tag: string): ComponentType<Record<string, unknown>> {
+  const Safe = ({ children, ...rest }: { children?: ReactNode } & Record<string, unknown>) =>
+    createElement(tag, filterIntrinsicProps(rest), children);
+  Safe.displayName = `Safe(${tag})`;
+  return Safe as ComponentType<Record<string, unknown>>;
+}
+
+/** `tag → sanitizing wrapper`, merged into the component map the safe renderer consumes.
+ *  A tag absent from this map is not an error: `renderMdast` collapses an unknown JSX tag
+ *  to a Fragment that KEEPS ITS CHILDREN, so an unregistered wrapper loses its element and
+ *  its styling but never its content. */
+export const SAFE_INTRINSICS: Record<string, ComponentType<Record<string, unknown>>> =
+  Object.fromEntries(ALLOWED_TAGS.map((t) => [t, wrap(t)]));