@immediately-run/grove 0.1.1

package/src/components/WikiLink.tsx

@@ -0,0 +1,112 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback, useContext } from 'react';
+import { Link, useMetadataQuery } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { hrefKeyCandidates, hrefTargetKey, isContentEntry, keyToHref, linkKind, sandboxPathToKey, splitFragment } from '../lib/content';
+import { isFolderKey } from '../lib/directory';
+import { queryPaths } from '../lib/wiki';
+import Icon from './Icon';
+
+interface Props {
+  href?: string;
+  children?: React.ReactNode;
+  className?: string;
+}
+
+// The MDX `a` override. A link into the content space renders as a wiki-link with one of
+// three states (brief 00) — resolved / broken / self; an external scheme or a bare
+// `#anchor` renders as an ordinary markdown link, so the two are distinguishable at a
+// glance. Those are the ONLY two shapes: an in-app href that resolves to nothing renders
+// broken, never as a bare `<a>` (see `linkKind` — R3-252).
+export default function WikiLink({ href = '', children, ...rest }: Props) {
+  const ctx = useContext(TinkerableContext) as any;
+  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+
+  // Resolve existence against the whole in-memory index (so a missing target is
+  // *definitively* broken, not a load-time flash).
+  const allKeysQuery = useCallback(
+    (fm: Record<string, any>) => Object.keys(fm).filter(isContentEntry),
+    []
+  );
+  const q = useMetadataQuery(allKeysQuery);
+  const keys: string[] = queryPaths(q);
+  const loaded = keys.length > 0;
+
+  // Normalize an in-app content href to its canonical metadata key; null for
+  // external/anchor links. Handles the ABSOLUTE forms (`/content/x.mdx`,
+  // `/files/content/x.mdx`) and the RELATIVE form an author actually writes
+  // (`roadmap/index.mdx`, `../specs/FOO.mdx`), which is resolved against the current
+  // entry the same way `check-docs-wiki` resolves `[[…]]` links. A relative href used
+  // to land here as `null` and render as a bare `<a>`, so clicking it made the sandbox
+  // perform a real navigation instead of routing — the "Failed to construct 'URL'"
+  // crash. Candidates are tried in order so a pre-cutover `foo.md` still finds `foo.mdx`
+  // even though the corpus itself no longer carries those names.
+  const candidates = hrefKeyCandidates(href, currentKey);
+  const targetKey = candidates.find((k) => keys.includes(k)) ?? candidates[0] ?? null;
+  // Route on the RESOLVED key, not the author's text: handing `<Link>` a relative href
+  // would make it resolve against the outer page URL rather than the content tree.
+  const [, fragment] = splitFragment(href);
+  const resolvedHref = targetKey ? keyToHref(targetKey) + fragment : href;
+
+  // Only an href that MEANS to leave the document becomes a real `<a>` — see `linkKind`.
+  // An unresolvable in-app href renders broken rather than falling through to an anchor
+  // that would navigate the sandboxed frame away and kill the app (R3-252).
+  if (!targetKey) {
+    const kind = linkKind(href);
+    // A FOLDER is a destination too, since directory listings landed: `[the
+    // handbook](handbook)` names something real, and the extension test that decides
+    // what an *entry* is would otherwise call it broken. Judged from the index (no fs
+    // call per link) — see `isFolderKey` for what that trades away.
+    const dirKey = kind === 'content' ? hrefTargetKey(href, currentKey) : null;
+    if (dirKey && loaded && isFolderKey(dirKey, keys)) {
+      return (
+        <Link href={keyToHref(dirKey) + fragment} className="grove-wikilink" data-state="ok" {...rest}>
+          {children}
+        </Link>
+      );
+    }
+    if (kind !== 'content') {
+      const web = /^https?:/i.test(href);
+      return (
+        <a
+          className="mdlink"
+          href={href}
+          {...(web ? { target: '_blank', rel: 'noreferrer' } : {})}
+          {...rest}
+        >
+          {children}
+        </a>
+      );
+    }
+    return (
+      <span className="grove-wikilink" data-state="broken" title={`No entry at ${href}`}>
+        <Icon name="unlink" />
+        {children}
+      </span>
+    );
+  }
+
+  if (targetKey === currentKey) {
+    return (
+      <span className="grove-wikilink" data-state="self">
+        {children}
+      </span>
+    );
+  }
+
+  const exists = !loaded || keys.includes(targetKey); // optimistic until loaded
+  if (!exists) {
+    return (
+      <span className="grove-wikilink" data-state="broken" title={`No entry at ${href}`}>
+        <Icon name="unlink" />
+        {children}
+      </span>
+    );
+  }
+
+  return (
+    <Link href={resolvedHref} className="grove-wikilink" data-state="ok" {...rest}>
+      {children}
+    </Link>
+  );
+}

package/src/data/themes.ts

@@ -0,0 +1,14 @@
+// The theme catalogue for the theme menu (id → label + swatch gradient). Data,
+// not components — kept out of the chrome components per the Fast-Refresh rule.
+export interface Theme {
+  id: string;
+  label: string;
+  swatch: string;
+}
+
+export const THEMES: Theme[] = [
+  { id: 'default', label: 'immediately.run', swatch: 'linear-gradient(96deg,#f6f1fb,#f49ad4 46%,#b285f2)' },
+  { id: 'pixies', label: 'Pixies', swatch: 'linear-gradient(96deg,#ffe14d,#ff2d8e 50%,#9d29ff)' },
+  { id: 'family', label: 'Family journal', swatch: 'linear-gradient(96deg,#f3cf9a,#e09a6a 50%,#c8744f)' },
+  { id: 'lotr', label: 'Middle-earth', swatch: 'linear-gradient(96deg,#b89a56,#8a6a36 50%,#4a5a38)' },
+];

package/src/devfs.d.ts

@@ -0,0 +1,4 @@
+// Pull in the `fs` module types provided by @immediately-run/dev-fs, so app
+// code can `import fs from 'fs'` and type-check against the async-only surface
+// immediately.run exposes. See https://github.com/immediately-run/dev-fs
+/// <reference types="@immediately-run/dev-fs/fs" />

package/src/hooks/useContentComponents.ts

@@ -0,0 +1,122 @@
+// Corpus-declared components — the LOAD half (R3-174; MDX_FROM_MOUNT_SPEC §2).
+//
+// Reads the corpus's own `immediately.run.json`, evaluates each declared module out of the
+// corpus filesystem, and hands back a `name → component` map for the MDX provider. The
+// declaration half (what counts as a usable entry) is `lib/corpusComponents`.
+//
+// **Why this can evaluate a module that lives in someone else's repo.** It is the same
+// call `<Include>` already makes for every entry body: `getModuleEvaluationContext` on an
+// absolute path. Under dispatch that path is in the corpus mount, and the bundler
+// transpiles and evaluates it exactly as it does an `/app` module — the two filesystems
+// differ in where the bytes come from, not in how a module is made from them.
+//
+// **What a content component may import, and why it is not restricted** (decision B,
+// 2026-08-26; recorded in `MDX_FROM_MOUNT_SPEC` §2). `resolveAsync` walks the dirname
+// chain from the importing file, and `/node_modules` is one registryfs shared by the whole
+// frame — so a corpus module's `react` and `@immediately-run/sdk` are THE VIEWER'S
+// instances, not second copies. That is what makes `useMetadataQuery` and `<Link>` work
+// from content: same React, same context. It also means confinement would have to be
+// added deliberately, and the decision is not to: inside an executor there is nothing to
+// confine, since the module reaches `globalThis.fetch` whatever the resolver permits
+// (`MDX_FROM_MOUNT_SPEC` §4 already concedes this). A corpus that wants no code execution
+// declares `render: safe`, where no import exists at all.
+//
+// **No live re-registration in v1, deliberately.** §7 1b asks for a reactive, name-keyed
+// registry so a hot edit cannot leave a stale reference behind. The map here IS keyed by
+// name, so re-evaluation overwrites cleanly — but nothing re-triggers it: the working-tree
+// change stream (`onFsChange`) is gated on elevated `editor:read`, which a dispatched
+// viewer does not hold, so there is no signal to subscribe to. An author edit needs a
+// reload. The shape is the one that extends; the trigger is what is missing.
+
+import { useEffect, useState } from 'react';
+import fs from 'fs';
+import { parseCorpusComponents, type RejectedComponent } from '../lib/corpusComponents';
+
+declare const module: {
+  getModuleEvaluationContext: (name: string) => Promise<{ exports: Record<string, unknown> }>;
+};
+
+/** The marker file a corpus uses to declare itself content (and now its vocabulary). */
+const MARKER = 'immediately.run.json';
+
+export interface ContentComponents {
+  /** `idle` — no corpus root yet, nothing to do · `loading` — hold the render, the
+   *  provider must be complete before content paints · `ready` — use `components`. */
+  status: 'idle' | 'loading' | 'ready';
+  /** Name → component, empty when the corpus declares none (the ordinary case). */
+  components: Record<string, unknown>;
+  /** Declarations that could not be used, with the reason. Rendered by the caller as a
+   *  visible notice rather than swallowed: a component that silently never appears is the
+   *  failure mode this whole path exists to remove. */
+  rejected: RejectedComponent[];
+}
+
+const NOTHING: ContentComponents = { status: 'idle', components: {}, rejected: [] };
+
+async function loadDeclared(root: string): Promise<Omit<ContentComponents, 'status'>> {
+  const base = root.endsWith('/') ? root : `${root}/`;
+  let marker: unknown;
+  try {
+    marker = JSON.parse(await fs.promises.readFile(`${base}${MARKER}`, 'utf8'));
+  } catch {
+    // No marker, or unreadable/malformed JSON. Both mean "this corpus declares no
+    // components" — the overwhelmingly common case, and not worth a notice.
+    return { components: {}, rejected: [] };
+  }
+  const { components: declared, rejected } = parseCorpusComponents(marker, base);
+  const components: Record<string, unknown> = {};
+  const failures = [...rejected];
+  // Sequential, not parallel: the list is short (a corpus declares a vocabulary, not a
+  // dependency closure) and the bundler already dedups and queues resolution, so
+  // concurrency here buys nothing and makes a failure harder to attribute.
+  for (const { name, path } of declared) {
+    try {
+      const evaluated = await module.getModuleEvaluationContext(path);
+      // `default` is the convention every other module-from-a-path surface uses
+      // (`<Include exportedSymbol="default">`); a named export matching the declared
+      // name is accepted too, so a file exporting `export function RoadmapBoard()` and
+      // nothing else works without a redundant default re-export.
+      const component = evaluated.exports.default ?? evaluated.exports[name];
+      if (typeof component !== 'function') {
+        failures.push({ name, reason: `${path} exports no component (default or ${name})` });
+        continue;
+      }
+      components[name] = component;
+    } catch (error) {
+      failures.push({ name, reason: `${path} failed to load: ${String(error)}` });
+    }
+  }
+  return { components, rejected: failures };
+}
+
+/**
+ * Load the components `root`'s corpus declares, or do nothing when `root` is null (the
+ * boot gate has not resolved a corpus yet).
+ *
+ * Returns `loading` until every declaration has resolved, so the caller can hold the
+ * content paint. That is the §2 invariant — compose the complete provider before content
+ * paints, never render into a partial one — and it costs nothing here because Grove
+ * already gates on `useOpenWikiBoot` and `useCorpusMetadata`. Rendering into a
+ * half-composed provider would flash a missing-component error for `<RoadmapBoard>` until
+ * registration landed, which is exactly the error this path removes.
+ */
+export function useContentComponents(root: string | null): ContentComponents {
+  const [loaded, setLoaded] = useState<{ root: string } & Omit<ContentComponents, 'status'> | null>(null);
+
+  useEffect(() => {
+    if (!root || loaded?.root === root) return;
+    let cancelled = false;
+    void loadDeclared(root).then((result) => {
+      if (!cancelled) setLoaded({ root, ...result });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [root, loaded?.root]);
+
+  if (!root) return NOTHING;
+  if (loaded?.root === root) {
+    return { status: 'ready', components: loaded.components, rejected: loaded.rejected };
+  }
+  return { status: 'loading', components: {}, rejected: [] };
+}

package/src/hooks/useCorpusMetadata.ts

@@ -0,0 +1,43 @@
+// The dispatched corpus's frontmatter index (R3-265).
+//
+// A FORK gets its index from the bundler and this hook does nothing. A DISPATCHED viewer
+// has to build it: the corpus is a mount the bundler never scanned, so without this the
+// wiki renders with empty nav, empty sidebar, no search, no backlinks and no routing —
+// silently, because an absent index is indistinguishable from an empty corpus.
+//
+// The scan runs ONCE per root and the result is handed to `TinkerableContext.filesMetadata`,
+// which is where `useMetadataQuery` / `useFileMetadata` / `useAllMetadata` already read
+// from — so every consumer keeps working untouched.
+
+import { useEffect, useState } from 'react';
+import fs from 'fs';
+import { scanCorpus, type CorpusMetadata, type ScanFs } from '../lib/corpusScan';
+
+export interface CorpusIndex {
+  /** `idle` — a fork, nothing to scan · `scanning` — hold the render · `ready` — use it. */
+  status: 'idle' | 'scanning' | 'ready';
+  metadata: CorpusMetadata | null;
+}
+
+/** Scan `root`, or do nothing when it is null (the fork packaging). */
+export function useCorpusMetadata(root: string | null): CorpusIndex {
+  const [index, setIndex] = useState<{ root: string; metadata: CorpusMetadata } | null>(null);
+
+  useEffect(() => {
+    if (!root || index?.root === root) return;
+    let cancelled = false;
+    void scanCorpus(root, fs.promises as unknown as ScanFs).then((metadata) => {
+      // A corpus that resolves to nothing is still a result: `ready` with an empty map
+      // renders the 404 index, which tells the reader the folder has no entries. Staying
+      // in `scanning` forever would show a spinner and say nothing.
+      if (!cancelled) setIndex({ root, metadata });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [root, index?.root]);
+
+  if (!root) return { status: 'idle', metadata: null };
+  if (index?.root === root) return { status: 'ready', metadata: index.metadata };
+  return { status: 'scanning', metadata: null };
+}

package/src/hooks/useDirectoryListing.ts

@@ -0,0 +1,56 @@
+// Does this key name a DIRECTORY, and what is in it?
+//
+// The frontmatter index cannot answer this. It holds `.md`/`.mdx` entries only, so a
+// folder of assets is invisible to it and a folder whose only child is an image would
+// read as "nothing here". The filesystem is the authority, so this hook asks it — the
+// one effectful step in the directory feature (the rules live in `lib/directory`).
+//
+// It runs ONLY for a key the entry index already missed, which is the whole cost
+// argument: an ordinary page render performs no extra I/O, and the readdir happens on
+// the path that was about to render a 404 anyway.
+
+import { useEffect, useState } from 'react';
+import fs from 'fs';
+import type { DirEntry } from '../lib/directory';
+
+export type DirectoryListing =
+  /** Not asked (a resolved entry), or the key is a file — render the entry / the 404. */
+  | { status: 'none' }
+  /** The readdir is in flight. Callers must NOT show the 404 here: a 404 that flashes
+   *  and then becomes a listing reads as a broken link that healed itself. */
+  | { status: 'checking' }
+  | { status: 'ready'; entries: DirEntry[] };
+
+/** The `fs.promises` slice this hook needs — injectable so the effect is testable. */
+export interface ReaddirFs {
+  readdir(path: string, opts: { withFileTypes: true }): Promise<Array<{ name: string; isDirectory(): boolean }>>;
+}
+
+/** Read `dirKey`, or do nothing when it is null. A read that throws means "not a
+ *  directory" (ENOTDIR/ENOENT are the same answer to the only question asked). */
+export function useDirectoryListing(dirKey: string | null, io?: ReaddirFs): DirectoryListing {
+  const [state, setState] = useState<{ key: string; entries: DirEntry[] | null } | null>(null);
+
+  useEffect(() => {
+    if (!dirKey || state?.key === dirKey) return;
+    let cancelled = false;
+    const api = io ?? (fs.promises as unknown as ReaddirFs);
+    api
+      .readdir(dirKey, { withFileTypes: true })
+      .then((items) => {
+        if (!cancelled) {
+          setState({ key: dirKey, entries: items.map((i) => ({ name: i.name, isDirectory: i.isDirectory() })) });
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setState({ key: dirKey, entries: null });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [dirKey, state?.key, io]);
+
+  if (!dirKey) return { status: 'none' };
+  if (state?.key !== dirKey) return { status: 'checking' };
+  return state.entries ? { status: 'ready', entries: state.entries } : { status: 'none' };
+}

package/src/hooks/useHeadings.ts

@@ -0,0 +1,96 @@
+// The rendered entry's headings, and which one the reader is in.
+//
+// Extracted from `<Toc>` when `<TableOfContents>` arrived, so the two surfaces cannot
+// disagree about what a heading is — the drift ENGINE_BOUNDARY §4 exists to prevent. The
+// scan reads the DOM rather than the source because an entry is rendered through
+// `<Include>` (compiled MDX) or the safe renderer; neither hands back a heading list, and
+// the ids a citation lands on are the ones actually in the document.
+
+import { useEffect, useState } from 'react';
+import { headingId } from '../lib/wiki';
+
+export interface Heading {
+  id: string;
+  text: string;
+  level: number;
+}
+
+/** Heading text WITHOUT the kernel's autolink anchor. The SDK's HeadingAnchor (§15.4)
+ *  prepends `<a class="ir-heading-anchor">#</a>` as the first child, so `textContent`
+ *  alone would put a stray `#` in every label and in the id fallback. */
+function headingText(node: Element): string {
+  const anchor = node.querySelector('.ir-heading-anchor');
+  if (!anchor) return (node.textContent || '').trim();
+  return Array.from(node.childNodes)
+    .filter((c) => c !== anchor)
+    .map((c) => c.textContent ?? '')
+    .join('')
+    .trim();
+}
+
+/**
+ * Scan `.grove-prose` for `h2`/`h3`, assigning the canonical id to any heading the kernel
+ * did not emit one for, and re-scan as the prose mounts or swaps on navigation.
+ */
+export function useHeadings(entryKey?: string): Heading[] {
+  const [heads, setHeads] = useState<Heading[]>([]);
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setHeads([]);
+    const scan = () => {
+      const prose = document.querySelector('.grove-prose');
+      const nodes = prose ? Array.from(prose.querySelectorAll('h2, h3')) : [];
+      const found: Heading[] = nodes.map((n) => {
+        const text = headingText(n);
+        // Prefer the kernel-emitted id (§15.5); `headingId` reproduces the same canon
+        // (`@immediately-run/mdx-plugins`) for a heading that has none.
+        const id = n.id || headingId(text);
+        n.id = id;
+        return { id, text, level: n.tagName === 'H3' ? 3 : 2 };
+      });
+      // Identity-stable when nothing changed: this runs from a MutationObserver, and a
+      // fresh array every mutation would re-run every downstream effect (the spy, the
+      // scroll) on each keystroke of an editor-driven re-render.
+      setHeads((prev) =>
+        prev.length === found.length && prev.every((h, i) => h.id === found[i].id) ? prev : found
+      );
+    };
+    scan();
+    const prose = document.querySelector('.grove-prose');
+    const obs = prose ? new MutationObserver(scan) : null;
+    if (prose && obs) obs.observe(prose, { childList: true, subtree: true });
+    // `<Include>` resolves asynchronously, and the observer only fires if `.grove-prose`
+    // already existed — these catch the window where it did not.
+    const timers = [120, 300, 600].map((d) => setTimeout(scan, d));
+    return () => {
+      obs?.disconnect();
+      timers.forEach(clearTimeout);
+    };
+  }, [entryKey]);
+
+  return heads;
+}
+
+/** Which heading the reader is currently in — scroll-spied off the document. */
+export function useActiveHeading(heads: Heading[]): string {
+  const [cur, setCur] = useState<string>('');
+
+  useEffect(() => {
+    if (!heads.length) return;
+    const obs = new IntersectionObserver(
+      (entries) => {
+        const visible = entries.filter((e) => e.isIntersecting);
+        if (visible.length) setCur((visible[0].target as HTMLElement).id);
+      },
+      { rootMargin: '-64px 0px -70% 0px', threshold: 0 }
+    );
+    heads.forEach((h) => {
+      const el = document.getElementById(h.id);
+      if (el) obs.observe(el);
+    });
+    return () => obs.disconnect();
+  }, [heads]);
+
+  return cur;
+}

package/src/hooks/useOpenWikiBoot.ts

@@ -0,0 +1,95 @@
+// Boot resolution for the `open-wiki` provider (R3-169).
+//
+// Grove has two packagings and this is where they diverge, ONCE, before anything reads
+// the corpus:
+//
+//   • FORK      — engine and corpus in one repo. No task input ever arrives; the content
+//                 root stays `/app/content/` and this hook is a no-op.
+//   • DISPATCH  — a caller invoked `open-wiki` with a directory delegation. The host
+//                 mounts the corpus at a task-scoped chroot and we re-point the content
+//                 root at it before the first entry renders.
+//
+// The distinction has to be settled BEFORE render, not during it: every helper that
+// answers "is this key an entry / what is its href / which layouts wrap it" is built on
+// the root, so a component that renders while the root is still the default would resolve
+// against the VIEWER's corpus and then not re-resolve. Hence a gate, not a fallback.
+
+import { useEffect, useState } from 'react';
+import { useMounts, getAppMountPath } from '@immediately-run/sdk/mounts';
+import { useTaskInput, cancelTask } from '@immediately-run/sdk/tasks';
+import { setContentRoot, isDispatched, isContentReadOnly } from '../lib/contentRoot';
+import { resolveOpenWiki, openWikiFailureMessage } from '../lib/openWiki';
+
+/** How long a callee waits for its delegated mount before cancelling. Long enough for the
+ *  host's mount announcement to land after the overlay mounts, short enough that a reader
+ *  is not left looking at a blank frame until the §5.7.1 liveness bound fires. */
+const MOUNT_GRACE_MS = 5_000;
+
+export interface OpenWikiBoot {
+  /** `fork` — render our own corpus · `waiting` — a callee whose mount hasn't arrived ·
+   *  `ready` — the delegated root is set · `failed` — cancelled, show the message. */
+  status: 'fork' | 'waiting' | 'ready' | 'failed';
+  message: string;
+  readOnly: boolean;
+}
+
+export function useOpenWikiBoot(): OpenWikiBoot {
+  const input = useTaskInput();
+  const mounts = useMounts();
+  const [failed, setFailed] = useState('');
+
+  const resolution = resolveOpenWiki(input, mounts ?? [], getAppMountPath());
+  if (resolution.ok) {
+    // Setting the root is what makes the corpus readable, so it happens in render — an
+    // effect would run AFTER the first content render, which is the whole failure this
+    // gate exists to prevent. Idempotent and purely derived, so a StrictMode double
+    // render sets the same value twice.
+    setContentRoot(resolution.root, { readOnly: resolution.readOnly });
+  }
+
+  // The module IS the latch: once a root is set, the delegation is final for the life of
+  // the instance. Deriving "resolved" from it rather than from local state is what stops
+  // a momentarily empty mount set from cancelling a task that is already open and being
+  // read — and it needs no ref, which the render rules would not allow anyway.
+  const resolved = isDispatched();
+
+  // ⚠ THE COLD-LOAD RACE, and why this does NOT wait for it.
+  //
+  // A task callee always has a `useTaskInput()`, so "no input" reliably meant "a fork". On a
+  // cold URL load there is no input either way, so at first render "fork" and "dispatched,
+  // mount not yet announced" look identical.
+  //
+  // The obvious guard — hold the render until the mount set is non-empty — is WRONG here,
+  // and measurably so: a plain present-mode fork publishes **no mounts at all** (only
+  // worktrees, spaces and dispatched corpora are published; the app's own repo arrives as
+  // `/app` through the bundler, not through the mount channel). So "wait for mounts" would
+  // block every ordinary wiki for the full grace period on a guess that never pays off.
+  //
+  // Instead: answer immediately, and let a late mark CORRECT the answer. `resolveOpenWiki`
+  // re-runs on every mount change and `setContentRoot` latches, so a corpus announced after
+  // first paint still flips this to `ready`. The residual is a brief flash of the viewer's
+  // own corpus IF the host announces late — which it does not in practice, because the host
+  // publishes from a React effect long before the sandboxed app's bundler has finished
+  // loading it. **That ordering is a requirement on the host, not a hope**: publish the
+  // corpus mount before the app boots, exactly as task delegations are minted before the
+  // callee boots (`runTaskInvoke`).
+  const pendingReason = resolved || resolution.ok || !input ? null : resolution.reason;
+
+  useEffect(() => {
+    if (!pendingReason) return;
+    // A callee whose delegation never arrives must not silently render its OWN corpus —
+    // the reader asked for THEIR folder. Give the mount a moment (it arrives on a host
+    // message just after the overlay mounts), then cancel with a typed error so the
+    // caller's `invokeTask` rejects `cancelled` instead of hanging to the liveness bound.
+    const t = setTimeout(() => {
+      setFailed(openWikiFailureMessage(pendingReason));
+      cancelTask();
+    }, MOUNT_GRACE_MS);
+    return () => clearTimeout(t);
+  }, [pendingReason]);
+
+  if (failed) return { status: 'failed', message: failed, readOnly: false };
+  if (resolved) return { status: 'ready', message: '', readOnly: isContentReadOnly() };
+  if (!input) return { status: 'fork', message: '', readOnly: false };
+  return { status: 'waiting', message: '', readOnly: false };
+}

package/src/index.css

@@ -0,0 +1,120 @@
+/* Global foundation: brand fonts, design tokens, and base resets.
+   Imported from App.tsx (NOT main.tsx) so immediately.run applies it at runtime.
+   Tokens mirror the immediately.run design system — pull colors, fonts, radii,
+   and shadows from here rather than hard-coding values. */
+
+/* Web fonts MUST be the first line of the file. */
+@import url('https://fonts.googleapis.com/css2?family=Gabarito:wght@400;500;600;700;800;900&family=Public+Sans:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap');
+
+/* ---------------------------------------------------------------- DARK (default) */
+:root {
+  /* — Surfaces — */
+  --bg:        #0a0b11;   /* cool near-black page background */
+  --panel:     #13141d;   /* tile / card surface */
+  --panel-2:   #191b26;   /* raised / hover surface */
+
+  /* — Hairlines — */
+  --line:      rgba(180,170,225,.14);  /* default border */
+  --line-2:    rgba(180,170,225,.22);  /* stronger border / focus ring base */
+
+  /* — Text — */
+  --ink:       #ecebf4;   /* primary text (near-white, faint violet) */
+  --ink-2:     #9b97b3;   /* muted violet-gray — secondary text */
+  --ink-3:     #6a677f;   /* faint — captions, disabled */
+
+  /* — Accents — */
+  --accent:    oklch(0.74 0.17 350);   /* pink-magenta — the brand through-line */
+  --accent-2:  oklch(0.66 0.18 295);   /* violet */
+  --accent-3:  oklch(0.82 0.12 340);   /* soft pink highlight (tags, badges) */
+
+  /* — Signature gradient + glow — */
+  --grad: linear-gradient(96deg, #f6f1fb 0%, #f49ad4 46%, #b285f2 100%);
+  --glow: 0 0 0 1px rgba(150,110,240,.5), 0 0 34px rgba(150,110,240,.32);
+
+  /* — Solid accent fallbacks (for text/icons that can't take a gradient) — */
+  --accent-pink:   #f49ad4;
+  --accent-violet: #b285f2;
+  --accent-hot:    #c43d96;  /* the saturated "accent tile" magenta */
+
+  /* — Type families — */
+  --disp: "Gabarito", system-ui, sans-serif;     /* display / headings */
+  --sans: "Public Sans", system-ui, sans-serif;  /* body / UI */
+  --mono: "Space Mono", ui-monospace, monospace; /* code, stats, labels */
+
+  /* — Radii — */
+  --r-xs: 5px;    /* logo square, inline code */
+  --r-sm: 6px;    /* small tags, keycaps */
+  --r-md: 12px;   /* code blocks, inputs */
+  --r-lg: 16px;   /* cards, tiles, panels */
+  --r-xl: 18px;   /* modals */
+  --r-pill: 30px; /* buttons, nav links, badges */
+
+  /* — Elevation — */
+  --shadow-card:  6px 6px 0 var(--accent-2);   /* hard offset on tile hover */
+  --shadow-modal: 0 24px 70px rgba(0,0,0,.5);
+  --shadow-pop:   0 12px 34px rgba(0,0,0,.45);
+
+  /* — Ambient page wash (radial accents behind content) — */
+  --page-wash:
+    radial-gradient(60% 50% at 78% 0%, rgba(178,133,242,.12), transparent 60%),
+    radial-gradient(50% 40% at 12% 8%, rgba(244,154,212,.07), transparent 60%);
+}
+
+/* ---------------------------------------------------------------- LIGHT */
+html[data-theme="light"] {
+  --bg:        #f6f4fb;
+  --panel:     #ffffff;
+  --panel-2:   #f0ecf8;
+  --line:      rgba(40,24,70,.12);
+  --line-2:    rgba(40,24,70,.20);
+  --ink:       #1c1726;
+  --ink-2:     #5d5670;
+  --ink-3:     #938aa6;
+  --accent:    oklch(0.58 0.21 1);
+  --accent-2:  oklch(0.52 0.21 295);
+  --accent-3:  oklch(0.50 0.20 350);
+  --grad: linear-gradient(96deg, #c43d96 0%, #9a45e6 100%);
+  --glow: 0 0 0 1px rgba(150,90,235,.4), 0 8px 26px rgba(150,90,235,.20);
+  --shadow-modal: 0 24px 70px rgba(40,24,70,.18);
+  --shadow-pop:   0 12px 34px rgba(40,24,70,.14);
+  --page-wash:
+    radial-gradient(60% 50% at 78% 0%, rgba(154,69,230,.09), transparent 60%),
+    radial-gradient(50% 40% at 12% 8%, rgba(212,69,154,.06), transparent 60%);
+}
+
+/* ---------------------------------------------------------------- reset + base */
+* { box-sizing: border-box; margin: 0; padding: 0; }
+html { scroll-behavior: smooth; }
+body {
+  background: var(--bg);
+  background-image: var(--page-wash);
+  color: var(--ink);
+  font: 400 16px/1.5 var(--sans);
+  -webkit-font-smoothing: antialiased;
+  min-height: 100vh;
+  overflow-x: hidden;
+}
+a { color: inherit; text-decoration: none; }
+::selection { background: var(--accent); color: #16101a; }
+
+/* Keyboard key cap — <Kbd>⌘K</Kbd> in MDX. */
+.grove-kbd {
+  display: inline-flex;
+  align-items: center;
+  padding: 0 .42em;
+  border: 1px solid var(--line);
+  border-radius: var(--r-sm);
+  background: var(--panel-2);
+  color: var(--ink);
+  font: 700 .82em/1 var(--mono);
+  letter-spacing: .02em;
+  box-shadow: 0 1px 0 var(--line-2);
+}
+
+/* Apply the signature gradient to any text: <span className="grad-text">…</span> */
+.grad-text {
+  background: var(--grad);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}