@immediately-run/grove 0.1.1

package/src/lib/content.ts

@@ -0,0 +1,267 @@
+import { isContentEntryPath } from '@immediately-run/mdx-plugins';
+import { FS_PREFIX, normalizeAbsolute, resolveLinkTarget } from '@immediately-run/sdk/linkSpace';
+
+// Path conventions for Grove content.
+//
+// The CANONICAL KEY in this app is the file's ABSOLUTE module/fs path, e.g.
+// `/app/content/handbook/onboarding.mdx`. This is the SAME identifier used by:
+//   • the metadata store — `useFileMetadata(key)` / `useMetadataQuery` are keyed
+//     by it (since the bundler change "Key MDX metadata by the absolute /app
+//     module path", sandbox #41 — metadata and modules now share one path);
+//   • the fs / `<Include>` / `module.dynamicImport` / `fs.readFile` path space.
+//
+// So an entry's metadata is read and its body is rendered with the identical
+// string — no more juggling two path spaces. The ONLY place a different space
+// appears is the URL/href layer, which owns the `/files`↔APP_ROOT translation:
+// `keyToHref` strips `/app` (the runtime <Link> then prepends `/files`), and
+// `keyToRepoRel` strips `/app/` for requestEdit. Pure helpers — no components.
+
+import { getContentRoot, isDispatched } from './contentRoot';
+
+export const APP_PREFIX = '/app';
+export const FILES_PREFIX = '/files';
+
+/** Where this instance's corpus lives — `/app/content/` for a fork, the delegated
+ *  directory for a dispatched viewer. A FUNCTION, not a constant: see
+ *  [[contentRoot]] for why capturing it at module scope is the bug it replaces. */
+export function contentDir(): string {
+  return getContentRoot();
+}
+
+/** The site root entry — the home page of whichever corpus is mounted. */
+export function homeKey(): string {
+  return `${getContentRoot()}home.mdx`;
+}
+
+/** Is this a content-entry metadata key? */
+export function isEntryKey(key: string): boolean {
+  return key.startsWith(contentDir()) && /\.mdx?$/.test(key);
+}
+
+/** Is this a folder-convention layout file (`…/_layout.mdx`)? These are structure,
+ *  not entries: they wrap pages at an `<Outlet/>` and are excluded from every
+ *  content enumeration (routing, nav, sidebar tree, index, search, backlinks). */
+export function isLayoutKey(key: string): boolean {
+  return /(^|\/)_layout\.mdx?$/.test(key);
+}
+
+/** Is this a *content entry* — an `.mdx` under content that a reader can navigate to?
+ *  Excludes layout files and any other `_`-prefixed structural file. This is the
+ *  single predicate every enumeration (nav, sidebar, 404 index, search, indexes)
+ *  should filter on, so layout files never leak into reader-facing surfaces. */
+export function isContentEntry(key: string): boolean {
+  // The ROOTING is this viewer's (a metadata key under whichever corpus is mounted);
+  // the ENTRY RULE is shared with the corpus tooling (R3-277a), because a file that
+  // counts as an entry in one and not the other is a page that exists but cannot be
+  // found — or an index row pointing at a layout wrapper.
+  if (!key.startsWith(contentDir())) return false;
+  return isContentEntryPath(key);
+}
+
+/** `handbook/onboarding` → `/app/content/handbook/onboarding.mdx` (the canonical key). */
+export function slugToKey(slug: string): string {
+  return contentDir() + slug.replace(/^\//, '') + '.mdx';
+}
+
+/**
+ * The prefix the URL space is measured FROM — the one place the two packagings differ in
+ * how a key becomes a link, and vice versa.
+ *
+ * A FORK's URLs are anchored at the app root, so a key `/app/content/x.mdx` is the href
+ * `/content/x.mdx` — `content/` included. That is not a detail to tidy up: those URLs are
+ * published, cited and deep-linked, so the fork's mapping must stay byte-identical.
+ *
+ * A DISPATCHED viewer has no app-root to measure from — the corpus is a chroot minted AT
+ * the content directory, so the mount root IS the corpus root and hrefs are corpus-relative
+ * (`/plot/the-rail.mdx`). Nothing is published against that space yet, which is why it can
+ * be defined here rather than negotiated.
+ *
+ * (The repo-load URL space — where a dispatched entry's URL must name a path in the CONTENT
+ * repo, `content/` segment and all — is R3-172's, and is decided when that space exists.
+ * Under the task/overlay dispatch that ships today there is no external URL to preserve.)
+ */
+function urlAnchor(): string {
+  return isDispatched() ? contentDir().replace(/\/+$/, '') : APP_PREFIX;
+}
+
+/** Canonical key → href for the runtime <Link>. The key is the absolute fs path; the URL
+ *  space drops the anchor and <Link> prepends `/files` itself. */
+export function keyToHref(key: string): string {
+  const anchor = urlAnchor();
+  return key.startsWith(anchor) ? key.slice(anchor.length) : key;
+}
+
+/** Canonical key → the absolute fs/module path for <Include> / dynamicImport /
+ *  fs.readFile. The canonical key already IS that path, so this is identity. */
+export function keyToInclude(key: string): string {
+  return key;
+}
+
+/** Canonical key → absolute fs path (alias of {@link keyToInclude}, for reads). */
+export function keyToFsPath(key: string): string {
+  return key;
+}
+
+/** Canonical key → repo-relative path for requestEdit (`content/…`). */
+export function keyToRepoRel(key: string): string {
+  return key.replace(/^\/app\//, '').replace(/^\//, '');
+}
+
+/**
+ * R3-268 — the viewed-document declaration for a navigation target (the value the
+ * resolver hands the SDK): the destination entry's path in this app's VISIBLE tree.
+ *
+ * Two path spaces, one per packaging:
+ *  - **Fork**: the engine repo IS the working tree, so the `/app/`-anchored key strips
+ *    to a repo-relative path (`content/themes.mdx`) — `keyToRepoRel`, unchanged.
+ *  - **Dispatch**: the delegated corpus mount is ALL this app can see or name, so the
+ *    declaration is CORPUS-relative (`themes.mdx` — the key minus the content root).
+ *    The host owns the corpus→repo translation and joins its chroot prefix before the
+ *    existence check. `keyToRepoRel` here was the bug: it only knows the `/app/`
+ *    anchor, so a dispatched key leaked its sandbox MOUNT path (`mnt/<hash>/…`) into
+ *    the declaration, the host's existence check missed, and the highlight silently
+ *    degraded to none.
+ *
+ * A non-entry view declares `null` (clear the highlight).
+ */
+export function viewedDocumentForTarget(targetHref: string): string | null {
+  const path = new URL(targetHref, 'https://placeholder.invalid').pathname;
+  const i = path.indexOf(`${FILES_PREFIX}/`);
+  const sandboxPath = i >= 0 ? path.slice(i) : '';
+  const key = sandboxPathToKey(sandboxPath);
+  if (!isEntryKey(key)) return null;
+  // isEntryKey guarantees the key starts with the content root, so the slice is total.
+  return isDispatched() ? key.slice(getContentRoot().length) : keyToRepoRel(key);
+}
+
+/** Split a link target into its path part and its `#fragment` (the `#` kept), e.g.
+ *  `"FOO.mdx#sec-8-9"` → `["FOO.mdx", "#sec-8-9"]`. Only the FIRST `#` splits. */
+export function splitFragment(href: string): [string, string] {
+  const i = href.indexOf('#');
+  return i === -1 ? [href, ''] : [href.slice(0, i), href.slice(i)];
+}
+
+/** Collapse `.` and `..` segments in an absolute key — the shared normalizer
+ *  (R3-277b; was a local copy of the same arithmetic). */
+const normalizeKey = normalizeAbsolute;
+
+/**
+ * The canonical keys a link href may denote, most-specific first — empty when the href
+ * is external, a bare anchor, or doesn't name a content entry.
+ *
+ * An author writes links RELATIVE to the entry they are in (`[Roadmap](roadmap/index.mdx)`
+ * from `content/home.mdx`), which is the same rule `scripts/lib/wiki.mjs` `contentResolve`
+ * applies to `[[…]]` links and `check-docs-wiki` audits them by. Resolving markdown links
+ * the same way is what keeps the rendered wiki and the corpus gate agreeing: before this,
+ * a relative href fell through to a plain `<a>`, the sandbox performed a real navigation,
+ * and the app died with "Failed to construct 'URL': Invalid URL".
+ *
+ * Two candidates rather than one, so a `foo.md` still finds `foo.mdx`. R3-252 rewrote the
+ * corpus off those pre-cutover names and `check-docs-wiki` now refuses new ones, so this
+ * fallback should never fire from committed content — it is kept because the gate being
+ * STRICTER than the renderer is the right asymmetry: a stale hand-typed link should still
+ * land a reader somewhere, and only the corpus is held to the canonical name. The CALLER
+ * picks the first candidate that exists, so this stays pure and testable.
+ */
+export function hrefKeyCandidates(href: string, fromKey: string): string[] {
+  const abs = hrefTargetKey(href, fromKey);
+  if (!abs || !/\.mdx?$/.test(abs)) return [];
+  return abs.endsWith('.md') ? [abs, abs + 'x'] : [abs];
+}
+
+/**
+ * The corpus path an in-app href denotes — WITHOUT requiring it to name a file. Null for
+ * an external scheme, a bare anchor, or a path that resolves outside the corpus.
+ *
+ * Split out from {@link hrefKeyCandidates} because a folder is a destination now: since
+ * directory listings landed, `[the handbook](handbook)` names something real, and the
+ * extension test that makes an entry an entry would have rendered it as a broken link.
+ * The two callers ask different questions of the same resolution — "which entry?" and
+ * "which path?" — so the resolution lives here once.
+ */
+export function hrefTargetKey(href: string, fromKey: string): string | null {
+  if (!href) return null;
+  if (/^(https?:|mailto:|tel:|#)/i.test(href)) return null;
+  const [rawPath] = splitFragment(href);
+  if (!rawPath) return null;
+  const path = rawPath.replace(/^\/files/, '');
+  // R3-277b: resolution is the SHARED resolver (`@immediately-run/sdk/linkSpace`,
+  // R3-273) — the same function the platform's own WikiLink and the docs corpus
+  // checker route through, so the runtime and the gate cannot drift. Relative
+  // targets resolve against the authoring file; `$fs:` targets resolve
+  // mount-absolute (addressing, never reach — R3-273).
+  if (!path.startsWith('/')) {
+    const rel = resolveLinkTarget(path, { currentFile: fromKey, corpusRoot: getContentRoot() });
+    if (rel.state !== 'resolved') return null;
+    // Confinement, not tidiness: an href in foreign content is untrusted, and the
+    // result flows into `fs` reads. In the default space anything that lands outside
+    // the corpus denotes nothing (`$fs:` is exempt by design; the entry checks
+    // downstream decide what renders).
+    return rel.path.startsWith(contentDir()) || path.startsWith(FS_PREFIX) ? rel.path : null;
+  }
+  // Absolute spellings come in two generations, both accepted INBOUND (the R3-272
+  // rule; emission via keyToHref stays canonical): the legacy repo-root spelling
+  // ('/content/handbook/x.mdx' — anchored where the corpus's own repo keeps it,
+  // under 'content/') and the canonical corpus-absolute ('/handbook/x.mdx' —
+  // anchored at the corpus root by the shared resolver). The legacy spelling is
+  // recognized by its prefix and wins when it matches, because that is the only
+  // form a repo-shaped corpus could have meant by it; anything else is
+  // corpus-absolute, closed under traversal ('..' clamps INSIDE the corpus —
+  // R3-273's rule, which supersedes this file's old escape-to-null behavior).
+  const legacyPrefix = contentDir().endsWith('/content/') ? '/content' : null;
+  if (legacyPrefix && (path === legacyPrefix || path.startsWith(`${legacyPrefix}/`))) {
+    const legacyAnchor = contentDir().slice(0, -'content/'.length);
+    const legacy = normalizeAbsolute(legacyAnchor + path);
+    if (legacy.startsWith(contentDir())) return legacy;
+  }
+  const corpusAnchored = resolveLinkTarget(path, { currentFile: fromKey, corpusRoot: getContentRoot() });
+  if (corpusAnchored.state === 'resolved' && corpusAnchored.path.startsWith(contentDir())) {
+    return corpusAnchored.path;
+  }
+  return null;
+}
+
+/**
+ * What an href in an entry body IS, which decides whether it may become a real `<a>`.
+ *
+ * A real `<a href>` performs a REAL NAVIGATION on click, which takes the sandboxed frame
+ * out of the app — the R3-252 crash (`Failed to construct 'URL': Invalid URL`). So an
+ * anchor is only ever correct for an href that genuinely means to leave the document:
+ *
+ * - `'external'` — an absolute scheme (`https:`, `mailto:`, `tel:`). Leaving is the point.
+ * - `'anchor'`   — a bare `#fragment`. Same document; navigates nowhere.
+ * - `'content'`  — anything else: a link INTO the corpus. It must be routed, and if it
+ *   cannot be resolved to an entry it is BROKEN — never "external by default". That
+ *   fallthrough is what made an unresolvable body link lethal instead of merely wrong,
+ *   and it is the class the wiki still contains (`../scripts/x.mjs`, `.claude/…`).
+ */
+export function linkKind(href: string): 'external' | 'anchor' | 'content' {
+  if (/^(https?:|mailto:|tel:)/i.test(href)) return 'external';
+  if (href.startsWith('#')) return 'anchor';
+  return 'content';
+}
+
+/** Current navigation sandboxPath → the canonical metadata/Include key. */
+export function sandboxPathToKey(sandboxPath: string): string {
+  if (!sandboxPath || sandboxPath === '/') return homeKey();
+  const anchor = urlAnchor();
+  let p = sandboxPath;
+  if (p.startsWith(FILES_PREFIX)) p = p.slice(FILES_PREFIX.length); // /files/content/x → /content/x
+  if (!p.startsWith(anchor + '/')) p = anchor + p; // relative → anchored (an anchored path stays)
+  // NORMALIZE BEFORE CHECKING. The containment test below used to run on the raw text, so
+  // `/../../app/src/App.tsx` anchored to `/task/t1/dir/../../app/src/App.tsx` — which
+  // starts with the content root as a STRING and resolves somewhere else entirely as a
+  // PATH. The key flows straight into `fs.readFile` (entry bodies, reading time,
+  // backlinks), and under dispatch the URL is attacker-influenceable: a link in foreign
+  // content, or a crafted address. Resolve the traversal first, then ask where it landed.
+  p = normalizeKey(p);
+  if (p === anchor || p === anchor + '/') return homeKey();
+  // The guard, not a formality: anything that does not land inside the corpus resolves
+  // HOME rather than becoming a key that reads some other file.
+  return p.startsWith(contentDir()) ? p : homeKey();
+}
+
+/** A sandboxPath → the absolute fs base for resolving relative assets. */
+export function toFsPath(sandboxPath: string): string {
+  return keyToFsPath(sandboxPathToKey(sandboxPath));
+}

package/src/lib/contentRoot.ts

@@ -0,0 +1,61 @@
+// WHERE THE CORPUS IS — the one place that answers it.
+//
+// Grove was written for a single packaging (Mode A, the FORK): engine and corpus ship
+// from one repo, so the content root was the module constant `/app/content/` and every
+// helper built on it inherited that assumption. Under DISPATCH the corpus is somebody
+// else's repo, mounted at a host-minted chroot, and the engine is loaded from Grove's
+// own repo — so the root is a RUNTIME value, and a constant is not merely inconvenient,
+// it is wrong in a way that renders the viewer's own corpus while claiming to render
+// yours (`docs/specs/REPO_CONTENT_DISPATCH_SPEC.mdx` §3; R3-169/R3-265).
+//
+// The root is resolved ONCE, before the first render, and never changes for the life of
+// the instance: a task callee is invoked with one directory, and a fork reads its own.
+// Deliberately module state rather than React context — the consumers are pure helpers
+// (`lib/content.ts`, `lib/layout.ts`, `lib/wiki.ts`) that components call during render,
+// and threading a context through them would put the render tree in the middle of a
+// question that is settled at boot.
+//
+// **Call it, don't capture it.** `const dir = getContentRoot()` at module scope freezes
+// the default before `setContentRoot` runs and silently restores the old bug — read it
+// inside the function that needs it. `contentRoot.test.ts` pins that.
+
+/** The fork packaging's root: the engine's own repo, at the sandbox's APP_ROOT. */
+export const APP_CONTENT_ROOT = '/app/content/';
+
+let root: string = APP_CONTENT_ROOT;
+let readOnly = false;
+
+/** Where this instance's corpus lives, with a trailing slash. Read at CALL time. */
+export function getContentRoot(): string {
+  return root;
+}
+
+/**
+ * Point this instance at a corpus. Called once at boot — by the `open-wiki` task handler
+ * with the delegated directory, or not at all (the fork, which keeps the default).
+ * Normalizes the trailing slash so every `startsWith`/`slice` in the helpers holds.
+ */
+export function setContentRoot(dir: string, opts: { readOnly?: boolean } = {}): void {
+  if (!dir) return;
+  root = dir.endsWith('/') ? dir : `${dir}/`;
+  readOnly = opts.readOnly ?? false;
+}
+
+/** Whether the mounted corpus was delegated read-only. Lives here rather than in React
+ *  state because it is the same fact as the root — one delegation, decided at boot — and
+ *  every consumer that asks "may I offer an edit?" already reads the root. */
+export function isContentReadOnly(): boolean {
+  return readOnly;
+}
+
+/** True when the corpus is NOT this app's own repo — i.e. we are a dispatched viewer.
+ *  Surfaces where the two packagings genuinely differ (provenance, the edit target). */
+export function isDispatched(): boolean {
+  return root !== APP_CONTENT_ROOT;
+}
+
+/** Test-only: restore the fork default so cases don't leak into each other. */
+export function resetContentRoot(): void {
+  root = APP_CONTENT_ROOT;
+  readOnly = false;
+}

package/src/lib/corpusComponents.test.ts

@@ -0,0 +1,101 @@
+// The corpus component DECLARATION (R3-174; MDX_FROM_MOUNT_SPEC §7 1b).
+//
+// Two properties matter here and neither is about the happy path. First, a bad
+// declaration is NAMED, not swallowed — a `<RoadmapBoard/>` that silently never renders
+// is indistinguishable from one nobody wrote, and the author has no other channel to find
+// out which. Second, one bad declaration does not cost the corpus its other components.
+
+import { describe, it, expect } from 'vitest';
+import { parseCorpusComponents, resolveComponentPath } from './corpusComponents';
+
+const ROOT = '/mnt/ec1210aa4dfa0067260861b1eeb31a9b';
+
+describe('resolveComponentPath', () => {
+  it('resolves a corpus-relative path, with or without ./', () => {
+    expect(resolveComponentPath('./components/X.jsx', ROOT)).toBe(`${ROOT}/components/X.jsx`);
+    expect(resolveComponentPath('components/X.jsx', ROOT)).toBe(`${ROOT}/components/X.jsx`);
+  });
+
+  it('tolerates a trailing slash on the root', () => {
+    expect(resolveComponentPath('./x.jsx', `${ROOT}/`)).toBe(`${ROOT}/x.jsx`);
+  });
+
+  it('rejects an absolute path — that is a different space, not a corpus path', () => {
+    expect(resolveComponentPath('/app/src/App.tsx', ROOT)).toBeNull();
+  });
+
+  it('rejects traversal out of the corpus, checked on the NORMALIZED path', () => {
+    // `x/../../y` starts with the root as a STRING and resolves outside it as a PATH —
+    // the hazard `sandboxPathToKey` documents. A marker must not be able to point the
+    // engine at its own modules and have them register under a corpus name.
+    expect(resolveComponentPath('../../app/src/App.tsx', ROOT)).toBeNull();
+    expect(resolveComponentPath('components/../../escape.jsx', ROOT)).toBeNull();
+  });
+
+  it('rejects NUL and backslash smuggling, and the empty path', () => {
+    expect(resolveComponentPath('x\0.jsx', ROOT)).toBeNull();
+    expect(resolveComponentPath('..\\escape.jsx', ROOT)).toBeNull();
+    expect(resolveComponentPath('', ROOT)).toBeNull();
+  });
+
+  it('rejects the corpus root itself — it is not a module', () => {
+    expect(resolveComponentPath('.', ROOT)).toBeNull();
+  });
+
+  it('rejects a non-string', () => {
+    expect(resolveComponentPath(42, ROOT)).toBeNull();
+    expect(resolveComponentPath(null, ROOT)).toBeNull();
+  });
+});
+
+describe('parseCorpusComponents', () => {
+  it('reads a well-formed map', () => {
+    const { components, rejected } = parseCorpusComponents(
+      { components: { ProjectIndex: './components/ProjectIndex.jsx' } },
+      ROOT,
+    );
+    expect(rejected).toEqual([]);
+    expect(components).toEqual([{ name: 'ProjectIndex', path: `${ROOT}/components/ProjectIndex.jsx` }]);
+  });
+
+  it('is silent for a marker with no components key — the ordinary case', () => {
+    expect(parseCorpusComponents({ opensWith: { task: 'open-wiki' } }, ROOT)).toEqual({
+      components: [],
+      rejected: [],
+    });
+    expect(parseCorpusComponents(null, ROOT)).toEqual({ components: [], rejected: [] });
+  });
+
+  it('rejects a lowercase name — MDX would resolve it as an intrinsic and never consult the provider', () => {
+    const { components, rejected } = parseCorpusComponents({ components: { board: './b.jsx' } }, ROOT);
+    expect(components).toEqual([]);
+    expect(rejected).toEqual([{ name: 'board', reason: 'not a capitalized component name' }]);
+  });
+
+  it('rejects a name that is not a component reference at all', () => {
+    const { rejected } = parseCorpusComponents({ components: { 'My-Board': './b.jsx' } }, ROOT);
+    expect(rejected.map((r) => r.name)).toEqual(['My-Board']);
+  });
+
+  it('keeps the good declarations when one is bad', () => {
+    const { components, rejected } = parseCorpusComponents(
+      {
+        components: {
+          Good: './components/Good.jsx',
+          Escapes: '../../app/src/App.tsx',
+          AlsoGood: './components/AlsoGood.jsx',
+        },
+      },
+      ROOT,
+    );
+    expect(components.map((c) => c.name)).toEqual(['Good', 'AlsoGood']);
+    expect(rejected.map((r) => r.name)).toEqual(['Escapes']);
+    expect(rejected[0].reason).toContain('inside the corpus');
+  });
+
+  it('rejects a components value that is not an object', () => {
+    expect(parseCorpusComponents({ components: ['./x.jsx'] }, ROOT).rejected).toEqual([
+      { name: '(components)', reason: 'not an object' },
+    ]);
+  });
+});

package/src/lib/corpusComponents.ts

@@ -0,0 +1,117 @@
+// Corpus-declared components — the parse half (R3-174; MDX_FROM_MOUNT_SPEC §2, §7 1b).
+//
+// A corpus may ship its own component vocabulary and have the viewer register it
+// import-free, so `<ProjectIndex/>` works with no engine fork. This module owns the
+// DECLARATION: reading `components` out of the corpus's own `immediately.run.json` and
+// deciding which entries are usable. Evaluating them is `hooks/useContentComponents`.
+//
+// **Why the marker file and not a frontmatter scan.** §7 1b left the declaration form
+// open and named three candidates (an `.mdx` module with `type: component` frontmatter, a
+// per-component metadata entry, a `components/` path convention). The marker wins on four
+// counts: it is already IN the corpus and already read, so discovery costs no scan and no
+// sidecar — which matters because a private corpus has neither (the docs wiki has no Pages
+// site, so no cache zip and no frontmatter sidecar; it loads over the REST API); a raw
+// `.jsx` carries no frontmatter, so the frontmatter form would force a wrapper module for
+// every component; it is one greppable place that states the corpus's whole vocabulary,
+// which is what `viewer.manifest.json`'s `tier: "corpus"` entries were already reaching
+// for; and it adds no non-component module export anywhere, so it cannot break Fast
+// Refresh (the constraint §7 1b is bounded by).
+//
+// **The host does not read this key and must not start.** `site-main`'s
+// `contentMarker.ts` parses `opensWith` and `kind` and ignores everything else, so the
+// vocabulary is viewer policy, not part of the host's authority decision. That separation
+// is the point: the marker names a CONTRACT to the host, and a component list to whoever
+// honours the contract.
+
+/** One usable declaration: an MDX component name bound to an absolute module path. */
+export interface CorpusComponent {
+  /** The name an entry writes as `<Name/>`. */
+  name: string;
+  /** Absolute module path inside the corpus, ready for `getModuleEvaluationContext`. */
+  path: string;
+}
+
+/** A declaration that was thrown out, and why — surfaced, never silently dropped. */
+export interface RejectedComponent {
+  name: string;
+  reason: string;
+}
+
+export interface CorpusComponentDecls {
+  components: CorpusComponent[];
+  rejected: RejectedComponent[];
+}
+
+/** MDX resolves a lowercase tag as an intrinsic element and only consults the provider for
+ *  a CAPITALIZED reference, so a lowercase name could never be reached — and a name with a
+ *  dot or a dash would not parse as a component reference at all. Rejecting them is the
+ *  difference between "your component silently never renders" and a named error. */
+const COMPONENT_NAME = /^[A-Z][A-Za-z0-9_]*$/;
+
+/** Collapse `.`/`..`/empty segments. `..` cannot climb above the root: a virtual root's
+ *  parent is itself, which is what keeps the corpus space closed under traversal (the same
+ *  rule as the SDK's `normalizeAbsolute` and `lib/content`'s `normalizeKey`). */
+function normalizeAbsolute(abs: string): string {
+  const out: string[] = [];
+  for (const seg of abs.split('/')) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') out.pop();
+    else out.push(seg);
+  }
+  return '/' + out.join('/');
+}
+
+/**
+ * Resolve one declared path against the corpus root, or null if it does not name a file
+ * inside the corpus.
+ *
+ * Under decision B (2026-08-26) a content component may import anything the viewer can,
+ * so this containment check is **coherence, not confinement** — it stops a marker naming
+ * `/app/src/App.tsx` and having the engine register its own module under a corpus name,
+ * which would be baffling rather than dangerous. The confinement argument is recorded in
+ * `MDX_FROM_MOUNT_SPEC` §2: inside an executor there is nothing to confine, because the
+ * module reaches `globalThis.fetch` whatever the resolver allows.
+ */
+export function resolveComponentPath(raw: unknown, root: string): string | null {
+  if (typeof raw !== 'string' || raw === '') return null;
+  if (raw.includes('\0') || raw.includes('\\')) return null;
+  if (raw.startsWith('/')) return null; // corpus-relative only — an absolute path is a different space
+  const base = root.endsWith('/') ? root : `${root}/`;
+  const resolved = normalizeAbsolute(base + raw.replace(/^\.\//, ''));
+  // Containment, checked on the NORMALIZED path: `a/../../x` starts with the root as a
+  // STRING and resolves outside it as a PATH (the hazard `sandboxPathToKey` documents).
+  const contained = normalizeAbsolute(base);
+  if (resolved !== contained && !resolved.startsWith(`${contained}/`)) return null;
+  if (resolved === contained) return null; // the root itself is not a module
+  return resolved;
+}
+
+/**
+ * Read the `components` map out of a parsed `immediately.run.json`.
+ *
+ * Fails soft per entry: one bad declaration is reported and skipped, it never costs the
+ * corpus its other components. A marker with no `components` key is the ordinary case and
+ * yields an empty list with nothing rejected.
+ */
+export function parseCorpusComponents(marker: unknown, root: string): CorpusComponentDecls {
+  const components: CorpusComponent[] = [];
+  const rejected: RejectedComponent[] = [];
+  const raw = (marker as { components?: unknown } | null | undefined)?.components;
+  if (raw === undefined || raw === null) return { components, rejected };
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return { components, rejected: [{ name: '(components)', reason: 'not an object' }] };
+  }
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!COMPONENT_NAME.test(name)) {
+      rejected.push({ name, reason: 'not a capitalized component name' });
+      continue;
+    }
+    const path = resolveComponentPath(value, root);
+    if (path === null) {
+      rejected.push({ name, reason: `not a corpus-relative path inside the corpus: ${String(value)}` });
+      continue;
+    }
+    components.push({ name, path });
+  }
+  return { components, rejected };
+}