@immediately-run/grove 0.1.1 → 0.1.3

package/README.md

@@ -1,122 +1,50 @@
-# immediately.run — starter template
+# Grove — the wiki viewer for [immediately.run](https://immediately.run)
+
+Grove renders an MDX corpus as a wiki: plain interlinked entries with frontmatter,
+a sidebar, search, backlinks, tags, timelines — transpiled in the browser, no
+server, no build step at runtime. It ships three ways:
+
+1. **As a fork** — copy this repo, replace `content/` with your entries, push,
+   open it on immediately.run. Your corpus, your code, one repo.
+2. **As the dispatched viewer** — a corpus mounted into a running Grove via the
+   `open-wiki` task; the wiki is somebody else's directory and Grove reads it
+   through the mount (the engine never assumes it owns the corpus).
+3. **As a pinned library** — `@immediately-run/grove` as an ordinary npm
+   dependency: compose `src/lib.ts`'s helpers and the component vocabulary into
+   your own viewer.
+
+The composition surface — every component, its tier and overridability, the
+frontmatter keys the engine reads — is declared in
+[`viewer.manifest.json`](./viewer.manifest.json) and summarized in [`llms.txt`](./llms.txt).
+The themes and layouts are compared live by the `Themes` and `Layouts` entries of
+the sample corpus; the theming contract (token-only themes, declared faces,
+checked contrast) is stated in [`THEMING.md`](./THEMING.md). What the engine owns
+versus what content may reach is [`docs/ENGINE_BOUNDARY.md`](./docs/ENGINE_BOUNDARY.md).
+
+## Running locally
 
-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')
+```bash
+npm install
+npm run dev        # vite dev server — the sample handbook
+npm run verify     # lint + build + tests + the manifest/contrast/token gates
 ```
 
-`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:
+On immediately.run, open
+`https://immediately.run/present/github/<owner>/grove/main/files/content/home.mdx`
+(fork) — or dispatch it at any wiki directory with the platform's file picker.
+A GitHub Action (`.github/workflows/cache.yml`) publishes a pre-cached zip to
+this repo's own Pages on every push to `main`, so anonymous loads are fast.
 
-- **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.
+## Authoring entries
 
-## Develop
+Entries are `.mdx` files under `content/` with YAML frontmatter (`title`, `tags`,
+`date`, `nav`, `order`, plus the engine keys in the manifest: `site`, `theme`,
+`layout`, `view`, `frame`, `render`, `cover`, …). Interlink with wiki links;
+declare a picture per entry with `cover:`; group a folder with a
+`content/<dir>/_layout.mdx` starter. The built-in agent answers questions about
+the corpus over the host's chat slot — ask it where things are before editing.
 
-Requires Node.js 20.19+ or 22.12+.
+## License
 
-```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
-```
+Apache-2.0. Bundled fonts in `assets/fonts/` carry their own notices
+(OFL / USWDS) alongside.

package/llms.txt

@@ -1,6 +1,6 @@
 # @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)
+> 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.3)
 
 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
@@ -69,7 +69,7 @@ is one corpus's conventions (declared by that corpus, not this repo).
 - `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?.
+- `DocList` (engine, overridable) — A queried list of entries — the generic index primitive. paginate="infinite" windows it with a sentinel and a stated end (R3-314); the attribute must be a literal. Props: tag: string?, limit: number?, paginate: 'infinite'?, batch: 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.
@@ -79,6 +79,7 @@ is one corpus's conventions (declared by that corpus, not this repo).
 - `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?.
+- `LayoutGallery` (engine, overridable) — The layouts gallery: the starters, page variants and collection shapes grouped by their three mechanisms, enumerated from this manifest.
 - `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.
@@ -88,12 +89,14 @@ is one corpus's conventions (declared by that corpus, not this repo).
 - `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[]?.
+- `ThemeGallery` (engine, overridable) — The themes gallery: one row per shipped theme, enumerated from this manifest — adding a theme adds a row with no edit to the entry.
 - `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`
+- `theme`
 - `layout`
 - `view`
 - `frame`
@@ -101,6 +104,7 @@ is one corpus's conventions (declared by that corpus, not this repo).
 - `nav`
 - `order`
 - `tags`
+- `cover`
 
 Unknown keys pass through (carried, unread) — a corpus may keep its own vocabulary.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/grove",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {
@@ -10,7 +10,17 @@
         "task": "open-wiki",
         "version": "1.0"
       }
-    ]
+    ],
+    "invokes": [
+      {
+        "task": "edit-file",
+        "version": "^1"
+      }
+    ],
+    "requests": {
+      "task:invoke": {},
+      "llm:chat": {}
+    }
   },
   "scripts": {
     "dev": "vite",
@@ -18,17 +28,20 @@
     "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",
+    "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 check:published && npm run check:theme-contrast && npm run check:theme-token-only && npm run lint && npm run build && npm run test",
+    "check:theme-contrast": "node scripts/check-theme-contrast.mjs --self-test && node scripts/check-theme-contrast.mjs",
+    "check:theme-token-only": "node scripts/check-theme-token-only.mjs --self-test && node scripts/check-theme-token-only.mjs",
     "check:manifest": "node scripts/check-manifest.mjs",
     "check:deps": "node scripts/check-app-dependencies.mjs --self-test && node scripts/check-app-dependencies.mjs",
+    "check:published": "node scripts/check-published-parity.mjs --self-test && node scripts/check-published-parity.mjs --offline-ok",
     "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",
+    "@immediately-run/mdx-plugins": "0.7.1",
+    "@immediately-run/sdk": "^0.67.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },
@@ -48,8 +61,7 @@
     "typescript": "~6.0.2",
     "typescript-eslint": "^8.58.2",
     "vite": "^8.0.9",
-    "vitest": "^4.1.9",
-    "@immediately-run/mdx-plugins": "0.4.0"
+    "vitest": "^4.1.9"
   },
   "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",
@@ -75,7 +87,7 @@
     "llms.txt"
   ],
   "peerDependencies": {
-    "@immediately-run/sdk": "^0.52.0",
+    "@immediately-run/sdk": "^0.67.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   }

package/src/App.tsx

@@ -24,7 +24,7 @@ import { MetadataSource } from '@immediately-run/sdk';
 import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
 import { MDXProvider } from '@immediately-run/sdk/MDXProvider';
 import { useOpenWikiBoot } from './hooks/useOpenWikiBoot';
-import { useCorpusMetadata } from './hooks/useCorpusMetadata';
+import { useBundleMetadata } from './hooks/useBundleMetadata';
 import { useContentComponents } from './hooks/useContentComponents';
 import { getContentRoot } from './lib/contentRoot';
 import { viewedDocumentForTarget } from './lib/content';
@@ -69,7 +69,7 @@ export default function App() {
     }
   }, [boot.status, outerHref]);
   // Only a dispatched viewer scans; a fork's index is already in the context.
-  const corpus = useCorpusMetadata(boot.status === 'ready' ? getContentRoot() : null);
+  const bundle = useBundleMetadata(boot.status === 'ready' ? getContentRoot() : null);
   // BOTH packagings, deliberately (R3-174). A corpus's own component vocabulary must not
   // depend on how it was composed — `PLATFORM_LAYERING_SPEC` §1.1's mode-invariance rule —
   // so a fork reads its marker too; that is one cheap open of a file already in `/app`.
@@ -93,8 +93,8 @@ export default function App() {
   // invariant): rendering into a half-composed map would flash a missing-component error
   // for `<RoadmapBoard>` until registration landed — the very error content components
   // exist to remove — and a nested provider patched in afterwards would do the same.
-  // Holding here costs nothing, because the gate already exists for the corpus scan.
-  if (boot.status === 'waiting' || corpus.status === 'scanning' || contentComponents.status === 'loading') {
+  // Holding here costs nothing, because the gate already exists for the bundle scan.
+  if (boot.status === 'waiting' || bundle.status === 'scanning' || contentComponents.status === 'loading') {
     return (
       <div className="grove-boot">
         <p className="grove-boot__msg">Opening…</p>
@@ -116,14 +116,18 @@ export default function App() {
       wiki
     );
 
-  if (corpus.status === 'ready' && corpus.metadata) {
-    // Provide the scanned corpus as the metadata SOURCE through the supported
+  // R3-315/R3-310 — the declared face set mounts INSIDE GroveWiki now, keyed to
+  // the resolved theme (the catalogue looks change the reading face); nothing
+  // font-shaped waits on the scan from here.
+
+  if (bundle.status === 'ready' && bundle.metadata) {
+    // Provide the scanned bundle as the metadata SOURCE through the supported
     // surface (R3-276), not a wholesale TinkerableContext re-provision: the
     // platform stays free to grow its own state, and the hooks read the nearest
     // MetadataSource — so every consumer works unchanged, and nothing re-states
     // host fields it does not own.
     return (
-      <MetadataSource value={corpus.metadata}>{withComponents}</MetadataSource>
+      <MetadataSource value={bundle.metadata}>{withComponents}</MetadataSource>
     );
   }