@immediately-run/grove 0.1.1

package/README.md

@@ -0,0 +1,122 @@
+# immediately.run — starter template
+
+A ready-to-run starter for building apps on
+[immediately.run](https://immediately.run): React + TypeScript + Vite, wired to
+the brand design system, with the project layout immediately.run expects.
+
+## Try it instantly
+
+Try this template on [immediately.run](https://immediately.run/present/github/immediately-run/new-project-template/main/files/src/App.tsx)
+
+> Using this as a starting point for your own app? After you push to your repo,
+> update the link above to
+> `https://immediately.run/present/github/<owner>/<repo>/<ref>/files/src/App.tsx`.
+
+## Use this template
+
+1. Create a new repo from this template (or copy the files).
+2. `npm install`
+3. `npm run dev` and start editing `src/App.tsx`.
+4. Push to GitHub and open it on immediately.run with the link above.
+
+## Fast loading on immediately.run (auto-cache)
+
+immediately.run normally reads your sources from the GitHub API, which is slow
+and rate-limited for anonymous visitors. This template ships a GitHub Action
+([`.github/workflows/cache.yml`](./.github/workflows/cache.yml)) that, on every
+push to `main`, builds a pre-cached zip of your repo and publishes it to your
+repo's **own GitHub Pages**. immediately.run finds it automatically at
+`https://<owner>.github.io/<repo>/cached_repositories/main.zip` and loads from
+there — falling back to the API if it's missing.
+
+The cache also embeds a manifest sidecar, so visitors can push edits back to
+GitHub even when the app was loaded from the zip.
+
+**Setup:** push to `main` and the workflow does the rest. When the immediately-run
+org's **deploy GitHub App** has **Pages: write** + **Administration: write** and its
+`DEPLOY_APP_ID` / `DEPLOY_APP_PRIVATE_KEY` are org secrets, the workflow **enables
+Pages for you** on the first run — no manual step. Otherwise, do it once:
+**Settings → Pages → Build and deployment → Source: GitHub Actions**. (The cache may
+lag a push by up to ~10 minutes of GitHub Pages CDN caching.)
+
+### Always run the newest commit
+
+By default the cached version is served even if it's a few minutes behind
+`main`. If your app must always reflect the very latest commit, add this to
+`package.json`:
+
+```jsonc
+{
+  "immediately.run": {
+    "requireLatest": true
+  }
+}
+```
+
+immediately.run still boots instantly from the cache, then checks in the
+background (one API request) whether the cache is current and, if not, reloads
+from GitHub.
+
+## How it's organized
+
+immediately.run renders the **default export of `src/App.tsx`** — that's the
+entry point, not `main.tsx`.
+
+```
+src/
+  main.tsx              # local vite dev/build entry only — immediately.run IGNORES this
+  App.tsx               # ROOT: default export + imports the global CSS
+  index.css             # fonts, design tokens (dark + light), resets
+  App.css               # layout + component styles
+  mdx.d.ts              # type shim so `import X from './x.mdx'` works
+  components/           # one default-exported React component per file
+  data/                 # typed data arrays (NO components/JSX here)
+  hooks/                # custom hooks (NO components here)
+  assets/               # images you import, e.g. import logo from './assets/logo.png'
+```
+
+The included page shows the core patterns: a data array mapped to cards
+(`data/features.ts` → `components/Features.tsx`), a custom hook
+(`hooks/useTheme.ts` → `components/ThemeSwitch.tsx`), and local React state
+(`components/Counter.tsx`).
+
+## Filesystem access (`fs`)
+
+immediately.run apps can read and write a filesystem by importing `fs` (async
+only — `fs.promises.*` and callback style). This template has local-dev support
+for it built in via [`@immediately-run/dev-fs`](https://github.com/immediately-run/dev-fs),
+a Vite plugin (already wired into `vite.config.ts`) that bridges the same
+filesystem to your real local disk during `vite dev`. See that repo for the
+supported API and details.
+
+```ts
+import fs from 'fs'
+
+await fs.promises.writeFile('/data/notes.txt', 'hello', 'utf8')
+const text = await fs.promises.readFile('/data/notes.txt', 'utf8')
+```
+
+`main.tsx` runs a one-off round-trip smoke test in dev — check the browser
+console for the `[dev-fs]` group, and delete it freely.
+
+## The rules that keep it working on immediately.run
+
+See [`CLAUDE.md`](./CLAUDE.md) for the full list. The essentials:
+
+- **Global CSS is imported from `App.tsx`, never only from `main.tsx`.**
+- **A file that exports a component exports *only* components** — data, consts,
+  and helpers go in `data/`, `hooks/`, or `lib/`. `npm run lint` enforces this.
+- **Pull colors, fonts, radii, and shadows from the tokens in `index.css`**
+  rather than hard-coding values.
+
+## Develop
+
+Requires Node.js 20.19+ or 22.12+.
+
+```bash
+npm install
+npm run dev      # local dev server
+npm run build    # tsc -b && vite build — must pass with no type errors
+npm run lint     # eslint — enforces the React Fast Refresh / HMR rule
+npm run preview  # serve the production build
+```

package/docs/ENGINE_BOUNDARY.md

@@ -0,0 +1,233 @@
+# The Grove engine boundary — what lives here, what lives in a corpus
+
+**Status:** decision record · **Recorded:** 2026-08-13 · **Item:** R3-262
+
+This repo is the **canonical Grove engine**. This document records why, what belongs in it,
+and what deliberately does not — so the fork that exists downstream is a known specialization
+rather than drift nobody is tracking. It exists because the drift already happened once: see
+§4.
+
+## 1. Canonical home — this repo
+
+`immediately-run/grove` is the engine. The `immediately-run/docs` wiki carries a **fork** of
+it at its own repo root, and that fork is a recorded specialization, not a second engine.
+
+The reason is dispatch. `REPO_CONTENT_DISPATCH_SPEC` resolves a content repo's
+`opensWith: { task: 'open-wiki' }` marker through the binding registry to **a Grove repo**,
+which then renders that repo's content. Self-dispatch is refused — the viewer must be a
+*different program* than the content it renders — so the engine has to be a repo of its own.
+There is no arrangement where "the docs wiki" is the thing a stranger's content dispatches to.
+
+The reason the fork exists anyway is the kernel: `APP_ROOT` is hard-coded to `/app` (the repo
+root) with no subdirectory anchoring (`sandbox/src/fsLayout.ts`), so the bare
+`github/immediately-run/docs/main` URL only boots if the engine sits at the *docs* repo root.
+That constraint is real and unresolved; it is why the fork is tolerated rather than deleted.
+
+**The follow-through, not yet done:** once a viewer can render content from a mount
+(R3-168/R3-169), `docs` becomes an ordinary content corpus dispatched to this engine and the
+fork can go. Until then, an engine change lands **here first** and is ported to `docs`.
+
+## 1a. What Grove IS (R3-280, recorded 2026-08-19)
+
+Packaging the engine as a library forced the question, so record the answer: **Grove is a
+(plugin-extensible) kit of React components, prebuilt layouts and themes that together make
+a wiki easy to build and good-looking by default — not a wiki engine in the traditional
+sense.**
+
+Most of what a traditional wiki engine owns is not here, and should not be. Routing
+(`Routes`/`Route`, `sandboxPath`), MDX compilation, the frontmatter metadata index and its
+sidecar, link spaces (`corpusRoot` + `$fs:`), `Include`, and heading anchors are all
+**sandbox + SDK**, because they are cross-cutting concerns of *every* immediately.run app,
+not of wikis. What is left for Grove to own — and it is a real thing to own — is the
+component vocabulary, the chrome, the layout chain, the themes, and the defaults that make
+the result look considered without anyone tuning it.
+
+Future scope stays inside that boundary. Author-facing collaboration features (Google-Docs
+style comment threads between authors, say) belong here because they are wiki-shaped
+presentation and interaction. Anything a second viewer would also need belongs one layer
+down — that is `PLATFORM_LAYERING_SPEC §5.1`'s tier test ("would Lodestar need to change it
+to use it?"), and this framing is what makes it decidable rather than a judgement call.
+
+## 1b. The three composition modes, and what each needs from this repo
+
+`PLATFORM_LAYERING_SPEC §1.1` names three modes, and since R3-280 all three are real:
+
+| Mode | What it is | What it needs here |
+|---|---|---|
+| **M1 dispatch** | a content repo's marker resolves to this repo through the binding registry | `immediately.run.provides: open-wiki`, and `src/App.tsx` as the entry |
+| **M2 fork** | engine + corpus in one repo under one identity (the docs wiki) | nothing extra — this is the historical shape (§1, §4) |
+| **M3 library** | a thin shell imports the engine pinned and arranges it | the package name, the `exports` map, and **`viewer.manifest.json`** |
+
+**The manifest is the override contract.** `viewer.manifest.json` declares the component
+vocabulary — name, tier, whether a shell may override it, its props, whether it is a
+sanitizing wrapper — and `composeComponents()` enforces it: overriding a name that is not
+declared, or one declared `overridable: false`, throws rather than silently doing nothing.
+Silence is the accident worth engineering against; a plain `{...base, ...overrides}` accepts
+every typo, and a shell then ships an override that quietly stopped working when the engine
+renamed something. `Outlet` is the standing locked case — replacing it detaches every layout
+layer from the page it wraps, and the symptom is a blank body with no error.
+
+`scripts/check-manifest.mjs` runs first in `npm run verify` and fails on drift in either
+direction: a component in `GROVE_MDX` but not the manifest, or vice versa. It brace-matches
+the object literal over a comment- and string-blanked copy of the source, so reformatting
+`mdxComponents.ts` cannot change the outcome — the property R3-277c asks for, and one the
+first draft of that script got wrong (a `}` inside a comment ended the scan early and the
+gate reported the whole manifest as drifted).
+
+The manifest FORMAT is viewer-generic (`viewer-manifest.schema.json`): a Lodestar manifest
+with a node/edge vocabulary validates through the same schema. Only the entries are
+per-viewer — which is also how corpus furniture (§3) becomes checkable, as `tier: "corpus"`
+entries declared by the corpus rather than by this repo.
+
+## 2. What is engine
+
+Anything that renders *any* corpus, and holds no opinion about what the corpus is about:
+
+- the two render paths — compiled MDX via `<Include>`, and the **interpreter** path
+  (`SafeEntryBody` → the SDK's `parseSafeMdast`/`renderMdast`), selected by `render: safe` on
+  the home entry (wiki-wide) or a single entry;
+- routing, path helpers and link classification (`lib/content.ts` — `hrefKeyCandidates`,
+  `linkKind`, `splitFragment`), and `<WikiLink>`'s resolution of author-relative hrefs;
+- deep-linking (`lib/fragment.ts`, `ScrollToFragment`) and the raw-source read cache
+  (`lib/sourceCache.ts`);
+- the layout chain (`lib/layout.ts`, `_layout.mdx` + `<Outlet/>`) and the shell primitives;
+- the generic content vocabulary registered in `mdxComponents.ts` — `<DocList>`, `<TagCloud>`,
+  `<Backlinks>`, `<Timeline>`, `<FamilyTree>`, `<DirectoryList>`, and friends;
+- **folder routing** (`lib/directory.ts`, `hooks/useDirectoryListing`, `<DirectoryView>`):
+  a URL naming a directory renders its `index.mdx` if the corpus wrote one, else the
+  generated listing. The route resolves `DirectoryList` **through the MDX component map**
+  rather than importing it, so a fork's or (with R3-174) a corpus's replacement reaches the
+  route as well as the tag — a half-override that only reached MDX bodies would be
+  invisible to whoever installed it.
+
+## 3. What is corpus furniture
+
+Components that encode **one corpus's frontmatter conventions**. They live with that corpus,
+not here. In the docs wiki that is `RoadmapBoard`, `RoadmapMeta`, `NextAvailable`,
+`Dependencies`, `ProjectIndex`/`ProjectItems`/`ProjectMeta`, `TopicIndex`, `StatusBadge`,
+`ItemCard`, plus `data/roadmap.ts`, `lib/roadmap.ts`, their `.rm-*` stylesheet block, the
+`<Dependencies/>` slot in `PageView`, and `EntryHeader`'s `isItemMeta` → `<RoadmapMeta>` hook.
+Every one of them reads `status:` / `project:` / `prs:` / `depends_on:` — fields that mean
+something only to an engineering roadmap.
+
+The measured shape of that boundary, taken 2026-08-13: the docs fork's `GroveApp.css` delta is
+a **pure append** of 221 `.rm-*` lines, and its `mdxComponents.ts` and `EntryHeader.tsx` deltas
+are *entirely* roadmap wiring. Nothing about the engine's own rendering had diverged. That is
+what makes the split cheap to state and cheap to keep.
+
+**How furniture is meant to travel, eventually.** R3-174 (frontmatter-discovered content
+components, `type: component`, content-wins on a name clash) is the mechanism: a corpus ships
+its own components and the viewer registers them, no fork. Note the constraint that follows —
+**a content component is author JavaScript, so R3-174 is available only to a corpus rendered
+on the compiled path.** The docs wiki qualifies (it left interpreter mode in R3-252). An
+**interpreter-mode** wiki cannot have content components at all, and must use the engine's
+vocabulary or extend the engine.
+
+## 4. Why this document exists
+
+Between 2026-07-10 and 2026-08-13 every engine change landed only in the `docs` fork, and
+nobody noticed. By the time it was measured, this repo had **no interpreter path at all** —
+`grep -rn safe src/` returned zero matches — while the specs described Grove as an interpreter
+and a planned dispatch feature assumed stock Grove would render foreign content
+non-executably. It would have rendered it as *code*.
+
+The engine's tests had drifted the same way, and unevenly: `fragment.ts` and `sourceCache.ts`
+arrived with their tests in the same commit, but `lib/content.ts` and `SafeEntryBody.tsx` both
+shipped bare and were untested for three weeks, gaining coverage only when a bug forced it. If
+you add to this engine, the test goes in the same commit as the source.
+
+## 5. Test posture
+
+`npm run verify` = `lint` + `build` (`tsc -b`, all three TS projects) + `test`.
+
+`src/lib/safeRender.test.ts` drives the **real published** SDK safe renderer — the same bytes
+the sandbox resolves on immediately.run — and proves the non-executable property: planted
+`{fetch()}` / `<script>` / `import` stay inert, unknown components collapse to their children,
+and heading ids exist for citations to land on.
+
+`src/components/DirectoryList.test.tsx` carries a **dispatch packaging** block. The fork and
+dispatch packagings differ in exactly one thing — `getContentRoot()` — and directory listings
+touch both path spaces at once: they READ through the mount and LINK through the URL space.
+Its load-bearing assertion is that the chroot prefix reaches **no** rendered href
+(`expect(el.innerHTML).not.toContain('mnt')`); that is host knowledge the viewer may read
+through but never publish, and the same mapping already leaked it once (R3-268). Proven
+non-vacuous by fault injection — freezing `urlAnchor()` at the fork root, and stopping
+`keyToHref` from stripping the anchor, each fail it.
+
+**Driving the dispatch packaging locally** (how that block was checked against the real host,
+2026-08-18): serve the corpus and the viewer as **two** `immediately.run dev` servers, seed the
+VIEWER's locator into `sessionStorage` under `ir-local-locator:<ns>/<repo>/<ref>` (the fragment
+can only carry one endpoint/token, and it has to be the corpus's), and re-point the binding with
+`#ir-dev-region=task.open-wiki&ir-dev-source=local/<ns>/<repo>/<ref>` — `ContentViewer`'s
+`resolveViewerBinding` honours the §6.8 ephemeral layer for `task.<name>` exactly as it does for
+a chrome region. Without that override, dispatch resolves to *published* Grove and the local
+build is never exercised.
+
+Two of its cases are **fixture-backed here and corpus-backed in `docs`**, deliberately. This
+repo's sample corpus writes no `[[…]]` citations and no `#sec-…` deep-links, so a corpus read
+would assert nothing — and the sweeps carry non-vacuity guards (`checked > 0`) that correctly
+*fail* on an empty sweep rather than passing quietly. The fixtures make the property
+deterministic here; the docs wiki keeps the large-corpus sweep, which is what R3-252 says that
+harness is for. Do not "fix" a fixture by pointing it back at the corpus, and do not delete a
+non-vacuity guard to make a sweep green.
+
+## 6. Authoring a layout under the interpreter (R3-263)
+
+`_layout.mdx` renders through the **safe** renderer whenever the wiki declares `render: safe`
+— it used to go through `<Include>` (the compiled path) regardless, which meant an
+"interpreter" wiki still executed author JavaScript out of its shell. Four things an author
+needs to know, all of which fail *quietly*:
+
+1. **Literal attributes only.** The renderer copies literal attributes and drops expression
+   ones, so `<Foo n={3}/>` arrives with no `n`.
+2. **Only allow-listed structural tags render as elements.** `src/lib/safeIntrinsics.tsx`
+   holds the closed set (`main`, `section`, `div`, …) with an attribute allow-list
+   (`className`, `id`, `data-*`, `aria-*`, …). A tag outside it collapses to a Fragment that
+   **keeps its children** — content survives, the wrapper and its class do not.
+3. **`import` lines are not resolved — and they are not silently dropped either.** The ESM
+   extension is off, so no ESM node is produced and the line renders as ordinary paragraph
+   **text, printed on the page**. Layouts are import-free by design; the vocabulary arrives
+   through the component map.
+4. **A block tag must open on its own line.** `<main className="x">text</main>` on one line is
+   consumed by micromark as an **HTML block** and renders as literal angle brackets; the same
+   tag opened on its own line parses as JSX. The symptom is "my layout is visible as markup"
+   with no error anywhere, and the fix is a line break, which nobody guesses.
+
+**Why the allow-list rather than raw tags.** The SDK's `literalProps` does no name filtering
+and no URL sanitizing — it copies every literal attribute verbatim onto whatever the map
+resolves. Measured against React 19: `onclick=` and `onerror=` are dropped by React, and a
+`javascript:` URL is blocked by React — but `style="…"` **throws** ("expects a mapping … not a
+string"), `dangerouslySetInnerHTML="…"` **throws**, and `iframe srcdoc="<script>…"` **passes
+straight through**. The two throwing cases are worse than they look: the throw is in the
+*layout*, so one content file takes down the shell for every page. So the barrier is the
+allow-list, and React's own defenses are a second layer rather than the only one.
+`src/lib/safeIntrinsics.test.tsx` pins every one of those cases, including the raw-tag
+behaviour that motivates the wrapper.
+
+## 7. Fork delta, re-measured after the R3-276a port (2026-08-25)
+
+The R3-276a port (record queries + `MetadataSource`, grove #45) landed in both trees in
+the same window. Measured immediately after, engine `src/` vs the docs fork's `src/`:
+
+- **Byte-identical after the port:** `lib/queries.ts` + its tests, `Search.tsx`,
+  `FamilyTree.tsx` — the shared metadata-query surfaces have zero fork divergence.
+- **Fork-only (the furniture, unchanged in kind):** the roadmap components
+  (`RoadmapBoard`, `RoadmapMeta`, `NextAvailable`, `Dependencies`, `ProjectIndex`,
+  `ProjectItems`, `ProjectMeta`, `TopicIndex`, `ItemCard`, `StatusBadge`), `data/roadmap.ts`,
+  `lib/roadmap.ts`, plus the `.rm-*` css block. Every one reads `status:`/`project:`/
+  `prs:`/`depends_on:` — corpus tooling, not engine.
+- **Fork naming specialization:** `CONTENT_DIR` constant vs the engine's
+  `contentDir()` runtime call (the fork is single-packaging and knows its root at build
+  time); visible as ~8-line diffs in `Sidebar.tsx`, `TagCloud.tsx`, `ChildPages.tsx`.
+- **Engine-ahead (NOT ported by R3-276a, pre-existing):** the fork's `App.tsx` is still
+  the pre-R3-169 monolith — it never needed the dispatch gate — and it lacks the newer
+  engine features (`GroveWiki` split, `DirectoryList`/`DirectoryView` folder routing,
+  `SafeLayout`, `TableOfContents`). That is drift the fork OWNS catching up on, tracked
+  separately from this boundary record; the fork renders the docs corpus on the surfaces
+  it has.
+
+The R3-276a fork/dispatch parity drill (headless Chrome on `local.immediately.run`, same
+throwaway corpus rendered both ways) found nav, search, and family-tree **identical**
+between the modes: same labels, same in-corpus hrefs, same family labels
+(`Engineering · Operations · Ada Lovelace · Alan Turing · Dorothy Vaughan`), with 83
+viewer-dev-server requests proving the dispatch render exercised the local engine build.

package/llms.txt

@@ -0,0 +1,115 @@
+# @immediately-run/grove — the viewer kit for directory-as-content wikis
+
+> The Grove viewer: a kit of React components, layouts and themes for building immediately.run wikis. Composable as a fork, a dispatch target, or a pinned library. (v0.1.1)
+
+Grove is NOT a wiki engine: routing, MDX compilation, the frontmatter index, link
+spaces and heading anchors live in the sandbox + `@immediately-run/sdk`. What this
+package owns is the component vocabulary, the chrome, the layout chain, the themes,
+and the defaults. Three composition modes (PLATFORM_LAYERING_SPEC §1.1):
+
+- **M1 dispatch** — a content repo with `opensWith: {task: "open-wiki"}` resolves here;
+  you write no code, the host mounts the corpus.
+- **M2 fork** — engine + corpus in one repo (the docs wiki shape).
+- **M3 library** — a thin shell imports this package pinned and composes it:
+  see `examples/thin-shell/`, and the override contract below.
+
+## Import surface (package.json exports)
+
+- `@immediately-run/grove` → ./src/lib.ts
+- `@immediately-run/grove/app` → ./src/App.tsx
+- `@immediately-run/grove/manifest` → ./viewer.manifest.json
+- `@immediately-run/grove/components` → ./src/mdxComponents.ts
+- `@immediately-run/grove/styles.css` → ./src/GroveApp.css
+- `@immediately-run/grove/theme.css` → ./src/index.css
+- `@immediately-run/grove/package.json` → ./package.json
+
+## Composition entry (src/lib.ts)
+
+- `GROVE_MDX`
+- `GroveApp`
+- `GroveShell`
+- `GroveShellContext`
+- `GroveWiki`
+- `ManifestComponent`
+- `ManifestOverrideError`
+- `NavItem`
+- `OutletContext`
+- `SAFE_MDX`
+- `VIEWER_MANIFEST`
+- `ViewerManifest`
+- `composeComponents`
+- `contentDir`
+- `getContentRoot`
+- `homeKey`
+- `isContentEntry`
+- `isDispatched`
+- `keyToFsPath`
+- `keyToHref`
+- `keyToInclude`
+- `layoutChainForKey`
+- `manifestNames`
+- `overridableNames`
+- `queryPaths`
+- `readingTime`
+- `sandboxPathToKey`
+- `stripFrontmatter`
+- `useShell`
+
+## Component vocabulary — the override contract (viewer.manifest.json)
+
+This is THE two-way surface: what a corpus may use, and what a library-composing
+shell may override. `composeComponents(base, overrides)` THROWS on a name that is
+not declared here or is declared `overridable: false` — overriding never silently
+no-ops. Tiers: `engine` renders any corpus · `chrome` is site furniture · `corpus`
+is one corpus's conventions (declared by that corpus, not this repo).
+
+- `a` (engine, overridable) — Wiki-link resolver: renders the resolved / broken / self states for an in-corpus href. Props: href: string?, children: node?.
+- `Backlinks` (engine, overridable) — Entries linking to this one.
+- `Callout` (engine, overridable) — An aside block with a kind (note / warning / …). Props: kind: string?, title: string?, children: node?.
+- `ChildPages` (engine, overridable) — The entries nested under this one.
+- `Directory` (engine, overridable) — The entries under one corpus directory. Props: path: string?.
+- `DirectoryList` (engine, overridable) — A folder listing as a table, with metadata columns chosen by `columns` and narrowed to those the rows actually carry. Props: path: string?, title: string?, columns: string?, sort: string?, hidden: boolean?.
+- `DocList` (engine, overridable) — A queried list of entries — the generic index primitive. Props: tag: string?, limit: number?.
+- `DocsByTag` (engine, overridable) — Entries grouped under one tag. Props: tag: string?.
+- `FamilyTree` (engine, overridable) — A relationship graph rendered from frontmatter links. Props: children: node?.
+- `GroveFooter` (chrome, overridable) — The site footer.
+- `GroveNav` (chrome, overridable) — Top/side navigation. Reads the shell context, so an override must too (or render its own).
+- `GroveSidebar` (chrome, overridable) — The corpus tree sidebar.
+- `img` (engine, overridable) — Resolves a mount-relative asset off the filesystem. Props: src: string?, alt: string?.
+- `Infobox` (engine, overridable) — The boxed summary panel a wiki entry carries beside its lede. Props: title: string?, children: node?.
+- `Kbd` (engine, overridable) — A keyboard key. Props: children: node?.
+- `KeyValue` (engine, overridable) — A definition-list row for infobox-style facts. Props: children: node?.
+- `Lede` (engine, overridable) — The opening paragraph, set apart typographically. Props: children: node?.
+- `More` (engine, overridable) — A 'read more' pointer to a related entry. Props: href: string?, children: node?.
+- `Outlet` (engine, LOCKED) — The layout chain's inward slot. NOT overridable — the chain's nesting is engine mechanics, and replacing it detaches every layer from the page it wraps.
+- `PageMeta` (engine, overridable) — The entry's own metadata line (updated, reading time, …).
+- `Quote` (engine, overridable) — A pull quote with an optional citation. Props: cite: string?, children: node?.
+- `RecentlyUpdated` (engine, overridable) — The most recently updated entries. Props: limit: number?.
+- `TableOfContents` (engine, overridable) — The on-this-page heading list, which keeps the active entry in view as the reader scrolls. Props: entryKey: string?, title: string?, className: string?.
+- `TagCloud` (engine, overridable) — Every tag in the corpus, weighted by use. Props: limit: number?.
+- `TagList` (engine, overridable) — The tags of one entry, as links to their indexes. Props: tags: string[]?.
+- `Timeline` (engine, overridable) — A dated sequence of entries or events. Props: children: node?.
+- `Toc` (engine, overridable) — The table of contents derived from the entry's heading anchors. Props: depth: number?.
+
+## Frontmatter keys the engine reads
+
+- `site`
+- `layout`
+- `view`
+- `frame`
+- `render`
+- `nav`
+- `order`
+- `tags`
+
+Unknown keys pass through (carried, unread) — a corpus may keep its own vocabulary.
+
+## What lives one layer down (do not reimplement here)
+
+- Platform client (RPC, capabilities, mounts, fs, editor, LLM): `@immediately-run/sdk`
+  — its llms.txt: https://immediately-run.github.io/immediately-run-sdk/llms.txt
+- Link-space resolver + grammar canon: `@immediately-run/mdx-plugins`
+- Non-executable MDX rendering: `@immediately-run/safe-content`
+
+---
+_Generated from viewer.manifest.json + package.json by `scripts/gen-llms.mjs`; regenerate on vocabulary changes (verify checks freshness)._

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@immediately-run/grove",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "src/main.tsx",
+  "immediately.run": {
+    "$schema": "https://immediately.run/immediately-run-config.schema.json",
+    "provides": [
+      {
+        "task": "open-wiki",
+        "version": "1.0"
+      }
+    ]
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "preview": "vite preview",
+    "verify": "npm run check:llms && npm run check:engine-api:selftest && npm run check:engine-api && npm run check:manifest && npm run check:deps && npm run lint && npm run build && npm run test",
+    "check:manifest": "node scripts/check-manifest.mjs",
+    "check:deps": "node scripts/check-app-dependencies.mjs --self-test && node scripts/check-app-dependencies.mjs",
+    "check:engine-api": "node scripts/check-engine-api.mjs",
+    "check:engine-api:selftest": "node scripts/check-engine-api.mjs --self-test",
+    "gen:llms": "node scripts/gen-llms.mjs",
+    "check:llms": "node scripts/gen-llms.mjs --check"
+  },
+  "dependencies": {
+    "@immediately-run/mdx-plugins": "0.4.0",
+    "@immediately-run/sdk": "^0.52.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@immediately-run/dev-fs": "^0.1.0",
+    "@mdx-js/rollup": "^3.1.0",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.5.0",
+    "jsdom": "^30.0.1",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.58.2",
+    "vite": "^8.0.9",
+    "vitest": "^4.1.9",
+    "@immediately-run/mdx-plugins": "0.4.0"
+  },
+  "description": "The Grove viewer: a kit of React components, layouts and themes for building immediately.run wikis. Composable as a fork, a dispatch target, or a pinned library.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/immediately-run/grove.git"
+  },
+  "exports": {
+    ".": "./src/lib.ts",
+    "./app": "./src/App.tsx",
+    "./manifest": "./viewer.manifest.json",
+    "./components": "./src/mdxComponents.ts",
+    "./styles.css": "./src/GroveApp.css",
+    "./theme.css": "./src/index.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "viewer.manifest.json",
+    "viewer-manifest.schema.json",
+    "README.md",
+    "docs/ENGINE_BOUNDARY.md",
+    "llms.txt"
+  ],
+  "peerDependencies": {
+    "@immediately-run/sdk": "^0.52.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
+  }
+}