@immediately-run/grove 0.1.3 → 0.1.5

package/src/hooks/useContentStylesheets.ts

@@ -0,0 +1,67 @@
+// The stylesheets a corpus declares on its home entry, read (MDX_FROM_MOUNT_SPEC D7).
+//
+// `loading` is DERIVED in render — the loaded set is compared with the declared one — not
+// set by an effect, so the render in which a declaration first appears (home was just read)
+// already reports `loading`. The entry gate reads it; a render that saw `ready` there would
+// paint the entry once unstyled.
+import { useEffect, useState } from 'react';
+import { declaredStylesheets, sheetFromSource, type ContentStylesheet } from '../lib/contentStylesheet';
+import { safeSources } from '../lib/safeSources';
+
+export interface ContentStylesheets {
+  status: 'loading' | 'ready';
+  sheets: ContentStylesheet[];
+  /** Reader-facing lines: a declaration that names no entry, or a sheet that did not read. */
+  errors: string[];
+}
+
+interface Loaded {
+  sig: string;
+  sheets: ContentStylesheet[];
+  errors: string[];
+}
+
+const NONE: Loaded = { sig: '', sheets: [], errors: [] };
+
+/** How long first paint waits for one declared sheet. A sheet read is one file over the
+ *  host channel — well under a second even as a cold GitHub blob — so a read still open
+ *  after this is stalled, and the page paints without it and says so. */
+const SHEET_READ_DEADLINE_MS = 15_000;
+
+function withDeadline<T>(read: Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`no answer after ${SHEET_READ_DEADLINE_MS / 1000} s`)), SHEET_READ_DEADLINE_MS);
+  });
+  return Promise.race([read, deadline]).finally(() => clearTimeout(timer));
+}
+
+export function useContentStylesheets(declared: unknown, homeKey: string): ContentStylesheets {
+  const { keys, errors: declarationErrors } = declaredStylesheets(declared, homeKey);
+  const sig = keys.join('|');
+  const [loaded, setLoaded] = useState<Loaded>(NONE);
+
+  useEffect(() => {
+    if (!sig) return;
+    let alive = true;
+    const paths = sig.split('|');
+    // `allSettled` never rejects, so this chain has no rejection to lose.
+    void Promise.allSettled(paths.map((p) => withDeadline(safeSources.read(p)))).then((results) => {
+      if (!alive) return;
+      const sheets: ContentStylesheet[] = [];
+      const errors: string[] = [];
+      results.forEach((r, i) => {
+        if (r.status === 'fulfilled') sheets.push(sheetFromSource(paths[i], r.value));
+        else errors.push(`${paths[i]} — could not be read (${r.reason instanceof Error ? r.reason.message : String(r.reason)})`);
+      });
+      setLoaded({ sig, sheets, errors });
+    });
+    return () => {
+      alive = false;
+    };
+  }, [sig]);
+
+  if (!sig) return { status: 'ready', sheets: [], errors: declarationErrors };
+  if (loaded.sig !== sig) return { status: 'loading', sheets: [], errors: declarationErrors };
+  return { status: 'ready', sheets: loaded.sheets, errors: [...declarationErrors, ...loaded.errors] };
+}

package/src/lib/contentStylesheet.test.ts

@@ -2,7 +2,7 @@
 // NAMED; comment- and string-hidden attempts do not change the verdict; clean
 // declarations pass with their quoted values intact.
 import { describe, it, expect } from 'vitest';
-import { gateStylesheet, blankCssNoise } from './contentStylesheet';
+import { gateStylesheet, blankCssNoise, declaredStylesheets, sheetFromSource } from './contentStylesheet';
 
 describe('clean sheets pass', () => {
   it('declarations-only CSS is admitted, quoted values intact', () => {
@@ -78,3 +78,59 @@ describe('the existence-oracle payload — the attack the grammar exists for', (
     if (!v.ok) expect(v.reason).toMatch(/selector|url\(/);
   });
 });
+
+describe('declaredStylesheets — the home entry names its sheets (MDX_FROM_MOUNT_SPEC D7)', () => {
+  const HOME = '/app/content/home.mdx';
+
+  it('resolves each value like a link in the home entry', () => {
+    expect(declaredStylesheets(['themes/paper.mdx', './themes/ink.md'], HOME)).toEqual({
+      keys: ['/app/content/themes/paper.mdx', '/app/content/themes/ink.md'],
+      errors: [],
+    });
+  });
+
+  it('absent means none, silently', () => {
+    expect(declaredStylesheets(undefined, HOME)).toEqual({ keys: [], errors: [] });
+  });
+
+  it('a value that is not a list is an error naming the key, not a guess', () => {
+    const { keys, errors } = declaredStylesheets('themes/paper.mdx', HOME);
+    expect(keys).toEqual([]);
+    expect(errors).toEqual([expect.stringContaining('`stylesheets:`')]);
+  });
+
+  it('a value that names no entry inside the corpus is an error naming the value', () => {
+    const { keys, errors } = declaredStylesheets(['../outside.mdx', 'themes/paper.css', 42, 'themes/paper.mdx'], HOME);
+    expect(keys).toEqual(['/app/content/themes/paper.mdx']);
+    expect(errors).toHaveLength(3);
+    expect(errors[0]).toContain('../outside.mdx');
+    expect(errors[1]).toContain('themes/paper.css');
+    expect(errors[2]).toContain('42');
+  });
+
+  it('a `$fs:` value may address outside the corpus as a link; as a stylesheet it may not', () => {
+    const { keys, errors } = declaredStylesheets(['$fs:/app/src/evil.mdx', '$fs:/mnt/0123abcd/secret.mdx'], HOME);
+    expect(keys).toEqual([]);
+    expect(errors).toHaveLength(2);
+    expect(errors[0]).toContain('$fs:/app/src/evil.mdx');
+  });
+
+  it('a sheet declared twice is read once', () => {
+    expect(declaredStylesheets(['themes/paper.mdx', './themes/paper.mdx'], HOME).keys).toEqual([
+      '/app/content/themes/paper.mdx',
+    ]);
+  });
+});
+
+describe('sheetFromSource', () => {
+  it('splits the body CSS from the declared fonts and assets', () => {
+    const sheet = sheetFromSource(
+      '/app/content/themes/paper.mdx',
+      '---\nfonts:\n  - family: Lora\nassets:\n  paper: ./paper.jpg\n---\n--wash: var(--asset-paper);\n',
+    );
+    expect(sheet.path).toBe('/app/content/themes/paper.mdx');
+    expect(sheet.css.trim()).toBe('--wash: var(--asset-paper);');
+    expect(sheet.declarations.assets).toEqual({ paper: './paper.jpg' });
+    expect(Array.isArray(sheet.declarations.fonts)).toBe(true);
+  });
+});

package/src/lib/contentStylesheet.ts

@@ -1,7 +1,13 @@
-// The content-stylesheet grammar gate (R3-316; plan 05-content-carried-themes).
+// Content stylesheets (R3-316; plan 05-content-carried-themes): how a corpus declares them
+// and the grammar gate every one passes.
 //
-// Author-supplied CSS is contained by a GRAMMAR, not by the CSP: a `ui/stylesheet`
-// entry may carry declarations and NOTHING else. A selector would let it reach
+// DECLARATION (MDX_FROM_MOUNT_SPEC D7). The home entry lists them — `stylesheets:
+// [themes/paper.mdx]` — resolved like a link in the home entry: relative to it, confined to
+// the corpus. They used to be discovered by a frontmatter tag, which made the wiki's look
+// depend on reading every file in the corpus before the first page could paint.
+//
+// GRAMMAR. Author-supplied CSS is contained by a GRAMMAR, not by the CSP: a content
+// stylesheet may carry declarations and NOTHING else. A selector would let it reach
 // the DOM (and hide the theme control); `url(`/`@import`/`@font-face` would let
 // it name a network location — the existence-oracle channel the CSP does not
 // close for an INTERPRETED, SHARED space (no CSP at all there), which is the gap
@@ -14,6 +20,9 @@
 // values are legitimate: `--font-body: "Lora", serif;`), which is safe precisely
 // because the blanked scan already proved every line is a declaration.
 
+import { hrefTargetKey, isEntryKey } from './content';
+import { parseFrontmatter } from './frontmatter';
+
 export type GateResult =
   | { ok: true; declarations: string }
   | { ok: false; line: number; reason: string; excerpt: string };
@@ -81,7 +90,7 @@ export function gateStylesheet(css: string): GateResult {
     return {
       ok: false,
       line,
-      reason: 'a selector/rule block — a ui/stylesheet carries declarations only',
+      reason: 'a selector/rule block — a content stylesheet carries declarations only',
       excerpt: css.split('\n')[line - 1]?.trim().slice(0, 80) ?? '',
     };
   }
@@ -101,3 +110,52 @@ export function gateStylesheet(css: string): GateResult {
   }
   return { ok: true, declarations: origLines.map((l) => l.trim()).filter(Boolean).join('\n') };
 }
+
+/** A declared stylesheet, read: the body is the CSS the grammar gates. */
+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 };
+}
+
+/**
+ * The stylesheet keys a home entry's `stylesheets:` value declares, resolved against the
+ * home entry, plus a reader-facing error for every value that cannot be one. Absent means
+ * none; any other non-list is an error rather than a guess, because the author has no
+ * other way to learn their theme did not load.
+ */
+export function declaredStylesheets(value: unknown, homeKey: string): { keys: string[]; errors: string[] } {
+  if (value === undefined || value === null) return { keys: [], errors: [] };
+  if (!Array.isArray(value)) {
+    return { keys: [], errors: ['`stylesheets:` on the home entry must be a list of entry paths'] };
+  }
+  const keys: string[] = [];
+  const errors: string[] = [];
+  for (const item of value) {
+    // `hrefTargetKey` deliberately lets a `$fs:` link address outside the corpus; a
+    // stylesheet may not, so the result must also be an entry key of THIS corpus.
+    const key = typeof item === 'string' && item ? hrefTargetKey(item, homeKey) : null;
+    if (key === null || !isEntryKey(key)) {
+      errors.push(`${String(item)} — does not name an entry inside this corpus`);
+    } else if (!keys.includes(key)) {
+      keys.push(key);
+    }
+  }
+  return { keys, errors };
+}
+
+/** A stylesheet entry's source → its body CSS and declared `fonts:`/`assets:`. */
+export function sheetFromSource(path: string, raw: string): ContentStylesheet {
+  const { data, body } = parseFrontmatter(raw);
+  return {
+    path,
+    css: body,
+    declarations: {
+      ...(Array.isArray(data.fonts) ? { fonts: data.fonts } : {}),
+      ...(data.assets && typeof data.assets === 'object' ? { assets: data.assets } : {}),
+    },
+  };
+}

package/src/lib/corpusScan.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { scanCorpus, listCorpusFiles, type ScanFs } from './corpusScan';
+import { describe, it, expect, vi } from 'vitest';
+import { createCorpusScan, scanCorpus, listCorpusFiles, type ScanFs } from './corpusScan';
 import { parseFrontmatter } from './frontmatter';
 
 /** An in-memory tree, shaped like the fs slice the scan injects. */
@@ -189,3 +189,183 @@ describe('scanCorpus — the additive headings index (GROVE_AGENT_SPEC §4)', ()
     expect(meta['/mnt/c/a.mdx']).toEqual({ title: 'A' });
   });
 });
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+/** The same tree as `fakeFs`, but every `readFile` waits until the test releases it — so
+ *  a test can observe the scan between the listing and the reads, and see read order. */
+function heldFs(files: Record<string, string>, opts: { unreadable?: string[] } = {}) {
+  const base = fakeFs(files, opts);
+  const calls: string[] = [];
+  const held = new Map<string, () => void>();
+  const fs: ScanFs = {
+    readdir: base.readdir,
+    readFile(path, enc) {
+      calls.push(path);
+      return new Promise<void>((resolve) => held.set(path, resolve)).then(() => base.readFile(path, enc));
+    },
+  };
+  const release = async (path: string) => {
+    held.get(path)!();
+    held.delete(path);
+    await tick(); // let the settle + pump run
+  };
+  return { fs, calls, held, release };
+}
+
+
+describe('createCorpusScan — the progressive index (MDX_FROM_MOUNT_SPEC D8)', () => {
+  const tree = {
+    '/mnt/c/home.mdx': entry('Home'),
+    '/mnt/c/a.mdx': entry('A'),
+    '/mnt/c/z.mdx': entry('Z'),
+  };
+
+  it('seeds EVERY listed key with an empty row before any file is read', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { flushMs: 60_000 });
+    expect(scan.snapshot().status).toBe('listing');
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    expect(scan.snapshot().metadata).toEqual({ '/mnt/c/a.mdx': {}, '/mnt/c/home.mdx': {}, '/mnt/c/z.mdx': {} });
+    expect(h.held.size).toBeGreaterThan(0); // reads started, none resolved
+    scan.dispose();
+  });
+
+  it('isSettled: false while listing and for a listed-unread key; true once read, once failed, or never listed', async () => {
+    const h = heldFs(tree, { unreadable: ['/mnt/c/z.mdx'] });
+    const scan = createCorpusScan('/mnt/c', h.fs, { flushMs: 0 }); // settled = read AND published
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(false);
+    expect(scan.isSettled('/mnt/c/missing.mdx')).toBe(false); // the listing has not answered yet
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(false);
+    expect(scan.isSettled('/mnt/c/missing.mdx')).toBe(true);
+    await h.release('/mnt/c/a.mdx');
+    await vi.waitFor(() => expect(scan.isSettled('/mnt/c/a.mdx')).toBe(true));
+    await h.release('/mnt/c/z.mdx');
+    await vi.waitFor(() => expect(scan.isSettled('/mnt/c/z.mdx')).toBe(true));
+    await h.release('/mnt/c/home.mdx');
+    await scan.done;
+    // The unreadable entry leaves the index, exactly as the whole-corpus scan always did.
+    expect(Object.keys(scan.snapshot().metadata).sort()).toEqual(['/mnt/c/a.mdx', '/mnt/c/home.mdx']);
+    expect(scan.snapshot().status).toBe('complete');
+  });
+
+  it('prioritize: a key asked for is the NEXT read, ahead of the rest of the corpus', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    await vi.waitFor(() => expect(h.calls).toEqual(['/mnt/c/a.mdx'])); // sorted order, one at a time
+    scan.prioritize(['/mnt/c/z.mdx']);
+    await h.release('/mnt/c/a.mdx');
+    await vi.waitFor(() => expect(h.calls).toEqual(['/mnt/c/a.mdx', '/mnt/c/z.mdx']));
+    scan.dispose();
+  });
+
+  it('prioritize before the listing finishes: the wanted key is read first', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    scan.prioritize(['/mnt/c/z.mdx']);
+    await vi.waitFor(() => expect(h.calls).toEqual(['/mnt/c/z.mdx']));
+    scan.dispose();
+  });
+
+  it('a prioritized key publishes as soon as it settles, without waiting for the flush timer', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    const before = scan.snapshot();
+    const seen = vi.fn();
+    scan.subscribe(seen);
+    scan.prioritize(['/mnt/c/a.mdx']); // already in flight — still wanted
+    await h.release('/mnt/c/a.mdx');
+    await vi.waitFor(() => expect(seen).toHaveBeenCalledTimes(1));
+    expect(scan.snapshot()).not.toBe(before);
+    expect(scan.snapshot().metadata['/mnt/c/a.mdx'].title).toBe('A');
+    scan.dispose();
+  });
+
+  it('a read key is not settled until its row is published — the gate never runs ahead of the index', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 60_000 });
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    await h.release('/mnt/c/a.mdx'); // read, nobody asked for it: waits for the flush
+    expect(scan.snapshot().metadata['/mnt/c/a.mdx']).toEqual({});
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(false);
+    scan.prioritize(['/mnt/c/a.mdx']); // now it is wanted: published at once
+    expect(scan.isSettled('/mnt/c/a.mdx')).toBe(true);
+    expect(scan.snapshot().metadata['/mnt/c/a.mdx'].title).toBe('A');
+    scan.dispose();
+  });
+
+  it('an unprioritized read is batched into the next flush', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 20 });
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    const seen = vi.fn();
+    scan.subscribe(seen);
+    await h.release('/mnt/c/a.mdx');
+    await tick();
+    expect(seen).not.toHaveBeenCalled(); // not per file
+    await vi.waitFor(() => expect(seen).toHaveBeenCalledTimes(1)); // the timer's flush
+    scan.dispose();
+  });
+
+  it('dispose stops handing out reads and cancels the pending publish', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { concurrency: 1, flushMs: 5 });
+    await vi.waitFor(() => expect(h.calls).toHaveLength(1));
+    const seen = vi.fn();
+    scan.subscribe(seen);
+    scan.dispose();
+    await h.release(h.calls[0]!);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(h.calls).toHaveLength(1);
+    expect(seen).not.toHaveBeenCalled();
+    await scan.done; // resolves on dispose rather than hanging
+  });
+
+  it('unsubscribe removes exactly that listener', async () => {
+    const h = heldFs(tree);
+    const scan = createCorpusScan('/mnt/c', h.fs, { flushMs: 60_000 });
+    const kept = vi.fn();
+    const dropped = vi.fn();
+    scan.subscribe(kept);
+    const off = scan.subscribe(dropped);
+    off();
+    await vi.waitFor(() => expect(scan.snapshot().status).toBe('reading'));
+    expect(kept).toHaveBeenCalledTimes(1);
+    expect(dropped).not.toHaveBeenCalled();
+    scan.dispose();
+  });
+
+  it('an empty bundle completes straight from the listing', async () => {
+    const scan = createCorpusScan('/mnt/c', fakeFs({ '/mnt/c/notes.txt': 'x' }));
+    await scan.done;
+    expect(scan.snapshot()).toEqual({ status: 'complete', metadata: {} });
+  });
+});
+
+describe('createCorpusScan — read failures', () => {
+  const notFound = () => Object.assign(new Error('no such file'), { code: 'ENOENT' });
+
+  it('a transient failure is reported for the key once settled; a missing file is not a failure', async () => {
+    const files = { '/mnt/c/a.mdx': entry('A'), '/mnt/c/b.mdx': entry('B') };
+    const base = fakeFs(files);
+    const fs: ScanFs = {
+      readdir: base.readdir,
+      async readFile(path) {
+        if (path === '/mnt/c/a.mdx') throw new Error('EIO: the channel dropped the request');
+        if (path === '/mnt/c/b.mdx') throw notFound();
+        return base.readFile(path, 'utf8');
+      },
+    };
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const scan = createCorpusScan('/mnt/c', fs, { flushMs: 0 });
+    expect(scan.readFailure('/mnt/c/a.mdx')).toBeNull(); // nothing is known yet
+    await scan.done;
+    expect(scan.readFailure('/mnt/c/a.mdx')).toBe('EIO: the channel dropped the request');
+    expect(scan.readFailure('/mnt/c/b.mdx')).toBeNull();
+    expect(scan.snapshot().metadata).toEqual({}); // both rows leave the index either way
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+});