@immediately-run/grove 0.1.4 → 0.1.5

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.4)
+> 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.5)
 
 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
@@ -97,6 +97,7 @@ is one corpus's conventions (declared by that corpus, not this repo).
 
 - `site`
 - `theme`
+- `stylesheets`
 - `layout`
 - `view`
 - `frame`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/grove",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {

package/src/App.tsx

@@ -12,8 +12,12 @@
 // Every helper the wiki is made of — which keys are entries, what their hrefs are, which
 // layouts wrap them — is a function of the root; every surface a reader sees — nav,
 // sidebar, search, backlinks, routing, the 404 index — is a function of the index. A
-// component that rendered before either was settled would show the VIEWER's corpus, or an
-// empty one, and then not correct itself. Both are outcomes dispatch may never produce.
+// component that rendered before the root was settled would show the VIEWER's corpus, and
+// then not correct itself; so would one that rendered with no index in scope, because the
+// metadata hooks fall back to the host's store. So this file holds until the root is
+// settled and the bundle is LISTED — every key known, rows filling in — and from then on
+// always provides the bundle's index. Which rows an entry needs READ before it paints is
+// GroveWiki's call (MDX_FROM_MOUNT_SPEC D8).
 //
 // Hence the split: this file resolves, `GroveWiki` renders.
 
@@ -29,6 +33,8 @@ import { useContentComponents } from './hooks/useContentComponents';
 import { getContentRoot } from './lib/contentRoot';
 import { viewedDocumentForTarget } from './lib/content';
 import GroveWiki from './GroveWiki';
+import BootMessage from './components/BootMessage';
+import { CorpusScanContext } from './lib/corpusScanContext';
 
 // R3-268 — the viewed-document rule, registered ONCE at module load: every
 // `navigate()`/`<Link>` navigation declares which file the destination renders,
@@ -81,25 +87,18 @@ export default function App() {
     boot.status === 'ready' || boot.status === 'fork' ? getContentRoot() : null,
   );
 
-  if (boot.status === 'failed') {
-    return (
-      <div className="grove-boot">
-        <p className="grove-boot__msg">{boot.message}</p>
-      </div>
-    );
-  }
+  if (boot.status === 'failed') return <BootMessage>{boot.message}</BootMessage>;
 
   // The provider must be COMPLETE before content paints (MDX_FROM_MOUNT_SPEC §2's
   // 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 bundle scan.
-  if (boot.status === 'waiting' || bundle.status === 'scanning' || contentComponents.status === 'loading') {
-    return (
-      <div className="grove-boot">
-        <p className="grove-boot__msg">Opening…</p>
-      </div>
-    );
+  //
+  // The frontmatter index is NOT held for (D8). Once the bundle is listed every key is
+  // known; the rows the requested entry needs are GroveWiki's to wait for, and the rest
+  // fill in around a painted page.
+  if (boot.status === 'waiting' || bundle.status === 'listing' || contentComponents.status === 'loading') {
+    return <BootMessage />;
   }
 
   // Corpus-declared components (R3-174) go on as a nested provider, which the SDK's
@@ -120,14 +119,17 @@ export default function App() {
   // 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) {
+  if (bundle.metadata && bundle.scan) {
     // 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.
+    // host fields it does not own. Provided from the first partial index on, so the
+    // tree keeps its shape when the scan completes rather than remounting the wiki.
     return (
-      <MetadataSource value={bundle.metadata}>{withComponents}</MetadataSource>
+      <CorpusScanContext value={bundle.scan}>
+        <MetadataSource value={bundle.metadata}>{withComponents}</MetadataSource>
+      </CorpusScanContext>
     );
   }
 

package/src/GroveApp.css

@@ -8,7 +8,7 @@
 
 /* R3-316 — the escape hatch, pinned where content cannot reach: for !important
    declarations EARLIER layers win, so grove.reset (the first layer, ordered in
-   index.css) beats grove.content no matter what a ui/stylesheet tries. A reader
+   index.css) beats grove.content no matter what a content stylesheet tries. A reader
    can always reach a shipped theme without clearing storage — the one guarantee
    the content layer must not be able to revoke. Proven by test (the hiding
    vectors are enumerated), not by reading this comment. */
@@ -2994,9 +2994,9 @@ button.grove-search__row {
   padding: 0 18px;
 }
 
-/* Boot gate (R3-169) — shown only while a dispatched viewer resolves its delegated
-   corpus, or when that delegation never arrived. Deliberately plain: at this point the
-   corpus is not readable, so none of its theming applies. */
+/* Boot gate (R3-169) — shown while a dispatched viewer resolves its delegated corpus,
+   lists it, or reads the few files the requested entry needs; and when that delegation
+   never arrived. Deliberately plain: the corpus's own theming is not applied yet. */
 .grove-boot {
   display: grid;
   place-items: center;

package/src/GroveWiki.entryGate.test.tsx

@@ -0,0 +1,216 @@
+// @vitest-environment jsdom
+// The entry gate and declared stylesheets, rendered (MDX_FROM_MOUNT_SPEC D7, D8):
+//   • while a file the entry needs is unread, the body is the boot line and the layers are
+//     not rendered — and those files are asked for first;
+//   • once they are read, the entry renders in the same mounted shell;
+//   • the stylesheets home declares hold the body until they are read, then apply;
+//   • a declaration that names no entry is shown to the reader.
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { CorpusScanContext } from './lib/corpusScanContext';
+import type { CorpusScanGate } from './lib/corpusScan';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (q: string) => ({ matches: false, media: q, addEventListener: () => {}, removeEventListener: () => {}, addListener: () => {}, removeListener: () => {}, dispatchEvent: () => false, onchange: null }),
+  });
+});
+
+// One read double behind both doors: the `fs` module (entry bodies, declared stylesheets)
+// and the SDK's shared fs (layouts, theme faces).
+const { readFile } = vi.hoisted(() => ({ readFile: vi.fn() }));
+vi.mock('fs', () => ({ default: { promises: { readFile: (...a: unknown[]) => readFile(...a) } } }));
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: GroveWiki } = await import('./GroveWiki');
+
+const ENTRY = '/app/content/wiki/a.mdx';
+const HOME = '/app/content/home.mdx';
+const LAYOUT = '/app/content/_layout.mdx';
+const SHEET = '/app/content/themes/paper.mdx';
+
+const NAV = {
+  mode: 'github',
+  namespace: 'immediately-run',
+  provider: 'github',
+  repository: 'corpus',
+  ref: 'main',
+  sandboxPath: ENTRY,
+  hash: '',
+  search: '',
+};
+
+// `render: safe` renders the body through the real safe renderer over the fs double (the
+// compiled evaluator exists only inside the sandbox bundler).
+function meta(home: Record<string, unknown> = {}) {
+  return {
+    [ENTRY]: { title: 'Reference entry.', render: 'safe' },
+    [HOME]: { title: 'Home', ...home },
+    [LAYOUT]: { site: 'Gate fixture' },
+    [SHEET]: {},
+  };
+}
+
+function gate(settled: Set<string> | 'all', failed: Record<string, string> = {}) {
+  return {
+    isSettled: (k: string) => settled === 'all' || settled.has(k),
+    prioritize: vi.fn<CorpusScanGate['prioritize']>(),
+    readFailure: (k: string) => failed[k] ?? null,
+  } satisfies CorpusScanGate;
+}
+
+async function render(root: Root, scan: CorpusScanGate, filesMetadata: Record<string, unknown>) {
+  await act(async () => {
+    root.render(
+      <TinkerableContext.Provider
+        value={{ outerHref: 'https://immediately.run/x', navigationState: NAV, routingSpec: { routes: [] } as never, filesMetadata } as never}
+      >
+        <CorpusScanContext value={scan}>
+          <GroveWiki />
+        </CorpusScanContext>
+      </TinkerableContext.Provider>,
+    );
+  });
+  for (let i = 0; i < 6; i++) await act(async () => {});
+}
+
+function mount(): { container: HTMLElement; root: Root } {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  return { container, root: createRoot(container) };
+}
+
+const bootLine = (c: HTMLElement) => c.querySelector('.grove-shell .grove-boot__msg')?.textContent ?? null;
+
+beforeEach(() => {
+  readFile.mockReset();
+  readFile.mockImplementation(async (path: string) =>
+    path === SHEET ? '---\ntitle: Paper\n---\n--bg: #123456;\n' : '---\ntitle: Reference entry.\nrender: safe\n---\n\nThe body text.\n',
+  );
+  localStorage.clear();
+});
+
+describe('the entry gate (D8)', () => {
+  it('holds the body on the boot line while the entry is unread, and asks for its files first', async () => {
+    const { container, root } = mount();
+    const scan = gate(new Set([HOME, LAYOUT]));
+    await render(root, scan, meta());
+    expect(bootLine(container)).toBe('Opening…');
+    expect(container.textContent).not.toContain('The body text.');
+    expect(container.querySelector('.grove-root')).toBeTruthy(); // the shell is mounted
+    expect(scan.prioritize).toHaveBeenCalledWith([HOME, ENTRY, LAYOUT]);
+    await act(async () => root.unmount());
+  });
+
+  it('renders the entry in the same shell once its files are read', async () => {
+    const { container, root } = mount();
+    await render(root, gate(new Set([HOME, LAYOUT])), meta());
+    const shell = container.querySelector('.grove-root');
+    await render(root, gate('all'), meta());
+    expect(bootLine(container)).toBeNull();
+    expect(container.textContent).toContain('The body text.');
+    expect(container.querySelector('.grove-root')).toBe(shell); // not remounted
+    await act(async () => root.unmount());
+  });
+
+  it('a critical file that failed to read fails closed: the reason, never the layers', async () => {
+    const { container, root } = mount();
+    await render(root, gate('all', { [HOME]: 'EIO' }), meta());
+    expect(bootLine(container)).toBe(`Could not read ${HOME} (EIO). Reload to try again.`);
+    expect(container.textContent).not.toContain('The body text.');
+    await act(async () => root.unmount());
+  });
+
+  it('an unread HOME holds the body too — its `render: safe` is not known yet', async () => {
+    const { container, root } = mount();
+    await render(root, gate(new Set([ENTRY, LAYOUT])), meta());
+    expect(bootLine(container)).toBe('Opening…');
+    await act(async () => root.unmount());
+  });
+});
+
+describe('declared stylesheets (D7)', () => {
+  it('hold the body until read, then apply into the content layer', async () => {
+    let release!: () => void;
+    const held = new Promise<void>((r) => (release = r));
+    readFile.mockImplementation(async (path: string) => {
+      if (path === SHEET) {
+        await held;
+        return '---\ntitle: Paper\n---\n--bg: #123456;\n';
+      }
+      return '---\ntitle: Reference entry.\nrender: safe\n---\n\nThe body text.\n';
+    });
+    const { container, root } = mount();
+    await render(root, gate('all'), meta({ stylesheets: ['themes/paper.mdx'] }));
+    expect(bootLine(container)).toBe('Opening…');
+    expect(readFile).toHaveBeenCalledWith(SHEET, 'utf8');
+    await act(async () => release());
+    for (let i = 0; i < 6; i++) await act(async () => {});
+    expect(bootLine(container)).toBeNull();
+    expect(container.querySelector('style[data-grove-content-theme]')?.textContent).toContain('--bg: #123456;');
+    await act(async () => root.unmount());
+  });
+
+  it('a tagged entry that home does not declare is NOT applied — tag discovery is gone', async () => {
+    const { container, root } = mount();
+    const m = meta();
+    m[SHEET] = { tags: ['ui/stylesheet'] };
+    await render(root, gate('all'), m);
+    expect(container.querySelector('style[data-grove-content-theme]')).toBeNull();
+    expect(readFile).not.toHaveBeenCalledWith(SHEET, 'utf8');
+    await act(async () => root.unmount());
+  });
+
+  it('a declaration that names no entry is shown, and does not hold the page', async () => {
+    const { container, root } = mount();
+    await render(root, gate('all'), meta({ stylesheets: ['../outside.mdx'] }));
+    const error = container.querySelector('.grove-decl-error');
+    expect(error?.textContent).toContain('../outside.mdx');
+    expect(bootLine(container)).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it('a declared sheet that will not read is shown with its path', async () => {
+    // Its own path: `safeSources` is the session-wide source cache, and a sheet an earlier
+    // case read successfully stays read.
+    const broken = '/app/content/themes/broken.mdx';
+    readFile.mockImplementation(async (path: string) => {
+      if (path === broken) throw new Error('ENOENT');
+      return '---\ntitle: Reference entry.\nrender: safe\n---\n\nThe body text.\n';
+    });
+    const { container, root } = mount();
+    await render(root, gate('all'), { ...meta({ stylesheets: ['themes/broken.mdx'] }), [broken]: {} });
+    expect(container.querySelector('.grove-decl-error')?.textContent).toContain(`${broken} — could not be read`);
+    expect(container.textContent).toContain('The body text.');
+    await act(async () => root.unmount());
+  });
+});
+
+describe('declared stylesheets — the deadline', () => {
+  it('a sheet read that never answers stops holding the page, and says so', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    try {
+      const stalled = '/app/content/themes/stalled.mdx';
+      readFile.mockImplementation((path: string) =>
+        path === stalled ? new Promise(() => undefined) : Promise.resolve('---\ntitle: Reference entry.\nrender: safe\n---\n\nThe body text.\n'),
+      );
+      const { container, root } = mount();
+      await render(root, gate('all'), { ...meta({ stylesheets: ['themes/stalled.mdx'] }), [stalled]: {} });
+      expect(bootLine(container)).toBe('Opening…');
+      await act(async () => {
+        vi.advanceTimersByTime(15_000);
+      });
+      for (let i = 0; i < 6; i++) await act(async () => {});
+      expect(bootLine(container)).toBeNull();
+      expect(container.querySelector('.grove-decl-error')?.textContent).toContain(`${stalled} — could not be read (no answer after 15 s)`);
+      await act(async () => root.unmount());
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/GroveWiki.tsx

@@ -44,9 +44,13 @@ import Search from './components/Search';
 import Drawer from './components/Drawer';
 import GroveAgent from './components/GroveAgent';
 import ThemeAssets from './components/ThemeAssets';
-import ContentTheme, { type ContentStylesheet } from './components/ContentTheme';
+import ContentTheme from './components/ContentTheme';
+import BootMessage from './components/BootMessage';
 import { themeAssetsFor } from './data/themeFonts';
-import { parseFrontmatter } from './lib/frontmatter';
+import { useContentStylesheets } from './hooks/useContentStylesheets';
+import { criticalKeys } from './lib/criticalKeys';
+import { criticalFailure, entryPending } from './lib/entryGate';
+import { CorpusScanContext } from './lib/corpusScanContext';
 
 declare const module: any;
 
@@ -270,44 +274,29 @@ export default function GroveWiki({
   // metadata store and re-derives when the content set or the entry changes.
   const allMeta = useAllMetadata() as Record<string, Record<string, unknown>>;
 
-  // ── Content-carried themes (R3-316) ────────────────────────────────────────
-  // `ui/stylesheet` entries discovered from the SAME index every other surface
-  // reads (mode-invariant: fork, dispatch and library all fill it); bodies are
-  // raw CSS behind frontmatter, gated by the grammar inside ContentTheme and
-  // admitted only into the lowest cascade layer. A rejected sheet degrades to a
-  // status line naming the line — never a silent drop, never a crash.
-  const [contentSheets, setContentSheets] = useState<ContentStylesheet[]>([]);
+  // ── Content-carried themes (R3-316; MDX_FROM_MOUNT_SPEC D7) ─────────────────
+  // The stylesheets the home entry declares (`stylesheets:`); bodies are raw CSS
+  // behind frontmatter, gated by the grammar inside ContentTheme and admitted only
+  // into the lowest cascade layer. A declaration that names no entry, a sheet that
+  // will not read, and a sheet the grammar rejects all degrade to a status line
+  // naming it — never a silent drop, never a crash.
+  const stylesheets = useContentStylesheets(homeMeta?.stylesheets, homeKey());
   const [rejectedSheet, setRejectedSheet] = useState<string | null>(null);
+  const sheetErrors = rejectedSheet ? [...stylesheets.errors, rejectedSheet] : stylesheets.errors;
+
+  // ── The entry gate (MDX_FROM_MOUNT_SPEC D8) ─────────────────────────────────
+  // Under dispatch the index fills in while the wiki is already on screen. The files
+  // that decide how THIS entry renders — itself, home, its layouts, its `frame:` — are
+  // read ahead of the rest, and the body waits for them: an unread row reads as
+  // `render` unset, which is the executing path. The chrome around it stays mounted.
+  const scanGate = useContext(CorpusScanContext);
+  const critical = criticalKeys(entryKey, allMeta, scanGate.readFailure);
+  const criticalSig = critical.join('|');
   useEffect(() => {
-    let alive = true;
-    const found: ContentStylesheet[] = [];
-    const paths = Object.keys(allMeta).filter((p) => {
-      const tags = allMeta[p]?.tags;
-      return Array.isArray(tags) && tags.includes('ui/stylesheet');
-    });
-    (async () => {
-      for (const p of paths) {
-        try {
-          const raw = await (await import('./lib/safeSources')).safeSources.read(p);
-          const parsed = parseFrontmatter(raw);
-          found.push({
-            path: p,
-            css: parsed.body,
-            declarations: {
-              ...(Array.isArray(parsed.data.fonts) ? { fonts: parsed.data.fonts as never } : {}),
-              ...(parsed.data.assets && typeof parsed.data.assets === 'object' ? { assets: parsed.data.assets as never } : {}),
-            },
-          });
-        } catch {
-          /* an unreadable stylesheet contributes nothing — same as an absent one */
-        }
-      }
-      if (alive) setContentSheets(found);
-    })();
-    return () => {
-      alive = false;
-    };
-  }, [allMeta]);
+    scanGate.prioritize(criticalSig.split('|'));
+  }, [scanGate, criticalSig]);
+  const pending = entryPending(critical, scanGate.isSettled, stylesheets.status);
+  const failure = criticalFailure(critical, scanGate.readFailure);
   const chain: string[] = layoutChainForKey(entryKey, allMeta);
   const frameNone = meta?.frame === 'none' || meta?.frame === false;
 
@@ -448,17 +437,21 @@ export default function GroveWiki({
             @font-face rules (R3-315's mechanism); switching themes revokes the
             outgoing set and re-mints. */}
         <ThemeAssets declarations={themeAssetsFor(theme)} />
-        <ContentTheme sheets={contentSheets} onRejected={(path, v) => setRejectedSheet(`${path}:${v.line} — ${v.reason}`)} />
+        <ContentTheme sheets={stylesheets.sheets} onRejected={(path, v) => setRejectedSheet(`${path}:${v.line} — ${v.reason}`)} />
         {/* R3-627: remember where the reader was on the entry they leave, and put
             them back there on Back. Grove's scroller is its own container, so the
             ref goes across; `useScrollReset` above stands down on the same
             traversal so the two do not fight. */}
         <ScrollRestoration scroller={scrollRef} />
         <div className="device__scroll" ref={scrollRef}>
-          {rejectedSheet ? (
+          {sheetErrors.length > 0 ? (
             <div className="grove-decl-error" role="status">
-              <strong>A stylesheet entry was rejected by the theme grammar.</strong>
-              <div>{rejectedSheet}</div>
+              <strong>A stylesheet this corpus declares could not be applied.</strong>
+              <ul>
+                {sheetErrors.map((e, i) => (
+                  <li key={i}>{e}</li>
+                ))}
+              </ul>
             </div>
           ) : null}
           {rejectedComponents.length > 0 ? (
@@ -474,7 +467,7 @@ export default function GroveWiki({
             </div>
           ) : null}
           <div className="grove-shell" data-nav={frameNone ? undefined : navMode}>
-            {renderLayers(chain, useDefault, safe)}
+            {failure ? <BootMessage>{failure}</BootMessage> : pending ? <BootMessage /> : renderLayers(chain, useDefault, safe)}
           </div>
         </div>
 

package/src/components/BootMessage.tsx

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+
+/** The single line Grove shows while it cannot paint an entry yet — booting, listing the
+ *  bundle, or waiting on the files an entry needs — and, given a message, when boot fails. */
+export default function BootMessage({ children = 'Opening…' }: { children?: ReactNode }) {
+  return (
+    <div className="grove-boot">
+      <p className="grove-boot__msg">{children}</p>
+    </div>
+  );
+}

package/src/components/ContentTheme.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 // R3-316's component + escape-hatch exits:
-//   • a clean ui/stylesheet renders into @layer grove.content (and its declared
+//   • a clean content stylesheet renders into @layer grove.content (and its declared
 //     faces mint through the R3-315 path — never a url());
 //   • a rejected sheet names the line and degrades (no style element for it);
 //   • THE ESCAPE HATCH: the hiding vectors a content stylesheet would try are

package/src/components/ContentTheme.tsx

@@ -1,12 +1,12 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
-import { gateStylesheet } from '../lib/contentStylesheet';
+import { gateStylesheet, type ContentStylesheet } from '../lib/contentStylesheet';
 import { mintThemeAssets, type MintedThemeAssets } from '../lib/themeAssets';
 import { openFs } from '@immediately-run/sdk';
 
-// A bundle's own look, carried as content (R3-316): each `ui/stylesheet` entry's
-// body is gated by the grammar (declarations only — a selector, at-rule, `url(`,
-// `@import` or `@font-face` is rejected with the line named, never silently
-// dropped) and admitted ONLY into the lowest cascade layer (`grove.content`),
+// A bundle's own look, carried as content (R3-316): each stylesheet the home entry
+// declares (`stylesheets:`, MDX_FROM_MOUNT_SPEC D7) has its body gated by the grammar
+// (declarations only — a selector, at-rule, `url(`, `@import` or `@font-face` is
+// rejected with the line named, never silently dropped) and admitted ONLY into the lowest cascade layer (`grove.content`),
 // where it can style tokens and nothing else. The entry's frontmatter may
 // declare `fonts:`/`assets:` — minted by the engine exactly as an engine theme's
 // are, so a content theme can change the reading face without naming a location.
@@ -22,15 +22,6 @@ import { openFs } from '@immediately-run/sdk';
 
 const ROOT_MOUNT = { path: '/', type: 'repo' } as const;
 
-export interface ContentStylesheet {
-  /** The entry's absolute fs path (the declaring file for its asset refs). */
-  path: string;
-  /** The raw body bytes (CSS). */
-  css: string;
-  /** The entry's declared fonts/assets, if any. */
-  declarations: { fonts?: unknown; assets?: unknown };
-}
-
 interface Props {
   sheets: ContentStylesheet[];
   /** Where a rejected sheet's verdict goes (the reader-facing degrade). */

package/src/hooks/useBundleMetadata.ts

@@ -5,39 +5,56 @@
 // wiki renders with empty nav, empty sidebar, no search, no backlinks and no routing —
 // silently, because an absent index is indistinguishable from an empty bundle.
 //
-// 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.
+// The index is PROGRESSIVE (MDX_FROM_MOUNT_SPEC D8): once the listing is done every key is
+// present, and rows fill in as files are read. The caller hands `metadata` to a
+// `MetadataSource`, which is where `useMetadataQuery` / `useFileMetadata` / `useAllMetadata`
+// read from, and hands `scan` to the entry gate, which asks whether the rows it needs have
+// been read.
 
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useSyncExternalStore } from 'react';
 import fs from 'fs';
-import { scanCorpus, type CorpusMetadata, type ScanFs } from '../lib/corpusScan';
+import {
+  createCorpusScan,
+  type CorpusMetadata,
+  type CorpusScan,
+  type CorpusScanSnapshot,
+  type CorpusScanStatus,
+  type ScanFs,
+} from '../lib/corpusScan';
 
 export interface BundleIndex {
-  /** `idle` — a fork, nothing to scan · `scanning` — hold the render · `ready` — use it. */
-  status: 'idle' | 'scanning' | 'ready';
+  /** `idle` — a fork, nothing to scan · `listing` — hold the render, no key is known yet ·
+   *  `reading` — every key is known, rows are filling in · `complete` — every row is read. */
+  status: 'idle' | CorpusScanStatus;
+  /** Null until the listing is done (and always for a fork). */
   metadata: CorpusMetadata | null;
+  /** The running scan, for the entry gate. Null for a fork and before the scan starts. */
+  scan: CorpusScan | null;
 }
 
+const LISTING: CorpusScanSnapshot = { status: 'listing', metadata: {} };
+const noSubscribe = () => () => undefined;
+const listingSnapshot = () => LISTING;
+
 /** Scan `root`, or do nothing when it is null (the fork packaging). */
 export function useBundleMetadata(root: string | null): BundleIndex {
-  const [index, setIndex] = useState<{ root: string; metadata: CorpusMetadata } | null>(null);
+  const [owned, setOwned] = useState<{ root: string; scan: CorpusScan } | null>(null);
 
   useEffect(() => {
-    if (!root || index?.root === root) return;
-    let cancelled = false;
-    void scanCorpus(root, fs.promises as unknown as ScanFs).then((metadata) => {
-      // A bundle 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;
+    const scan = createCorpusScan(root, fs.promises as unknown as ScanFs);
+    // The scan is an external resource this effect owns: created here, disposed below.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setOwned({ root, scan });
+    return () => scan.dispose();
+  }, [root]);
+
+  const scan = owned && owned.root === root ? owned.scan : null;
+  const snap = useSyncExternalStore(scan ? scan.subscribe : noSubscribe, scan ? scan.snapshot : listingSnapshot);
 
-  if (!root) return { status: 'idle', metadata: null };
-  if (index?.root === root) return { status: 'ready', metadata: index.metadata };
-  return { status: 'scanning', metadata: null };
+  if (!root) return { status: 'idle', metadata: null, scan: null };
+  // A bundle that resolves to nothing is still a result: `complete` with an empty map
+  // renders the 404 index, which tells the reader the folder has no entries.
+  if (snap.status === 'listing') return { status: 'listing', metadata: null, scan };
+  return { status: snap.status, metadata: snap.metadata, scan };
 }

package/src/hooks/useContentComponents.ts

@@ -95,8 +95,8 @@ async function loadDeclared(root: string): Promise<Omit<ContentComponents, 'stat
  *
  * 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 `useBundleMetadata`. Rendering into a
+ * paints, never render into a partial one — and it costs little here because Grove
+ * already gates on `useOpenWikiBoot` and on the bundle listing. 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.
  */