@immediately-run/grove 0.1.4 → 0.1.7

package/src/hooks/useCatalogAnswered.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+// `useCatalogAnswered` — rendered in a real React tree, driven through the SDK's REAL
+// catalog push channel against an emitting stub transport. The whole point of the hook is
+// a timing property of that channel, so a mock of either would assert nothing.
+//
+// The property under test: the push channel has no value-equality check, so a host answer
+// of `[]` — identical to the initial value — still notifies. That second notification is
+// the signal. A test that only pushed a NON-empty catalog would pass against a naive
+// `catalog.length > 0` implementation and prove nothing, which is why the empty-answer
+// case is the one that carries this file.
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+type Handler = (msg: Record<string, unknown>) => void;
+const handlers = new Set<Handler>();
+const emit = (msg: Record<string, unknown>): void => {
+  for (const h of handlers) h(msg);
+};
+
+// Installed BEFORE the SDK is imported: the channel resolves its transport lazily, and
+// the hook module subscribes at import time.
+(globalThis as { __immediatelyRun__?: unknown }).__immediatelyRun__ = {
+  transport: {
+    sendMessage: vi.fn(),
+    protocolRequest: vi.fn(async () => ({})),
+    onMessage: (handler: Handler) => {
+      handlers.add(handler);
+      return { dispose: () => handlers.delete(handler) };
+    },
+  },
+};
+
+let useCatalogAnswered: typeof import('./useCatalogAnswered').useCatalogAnswered;
+let getCatalog: typeof import('@immediately-run/sdk').getCatalog;
+
+beforeAll(async () => {
+  ({ useCatalogAnswered } = await import('./useCatalogAnswered'));
+  ({ getCatalog } = await import('@immediately-run/sdk'));
+});
+
+/** Render a probe recording the hook's value on every render. */
+const renderProbe = async () => {
+  const seen: boolean[] = [];
+  const Probe = () => {
+    seen.push(useCatalogAnswered());
+    return null;
+  };
+  const root = createRoot(document.createElement('div'));
+  await act(async () => {
+    root.render(<Probe />);
+  });
+  return { seen, unmount: () => act(async () => root.unmount()) };
+};
+
+describe('useCatalogAnswered', () => {
+  it('is false before the host answers — the subscribe-time call is not an answer', async () => {
+    // `onCatalogChange` invokes its listener once, SYNCHRONOUSLY, with the current value
+    // when you subscribe. If that counted, the flag would be true from module load and
+    // the reach card would read an unanswered catalog as "not granted" — the exact defect
+    // this hook exists to prevent.
+    getCatalog(); // start the channel the way the app does
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(false);
+    await unmount();
+  });
+
+  it('an EMPTY catalog answer flips it, and RE-RENDERS — an empty answer is still an answer', async () => {
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(false);
+    const before = seen.length;
+
+    await act(async () => {
+      emit({ type: 'api-catalog', methods: [] });
+    });
+
+    // Both halves matter: a hook that returned the flag without subscribing would show
+    // the right value only on the NEXT unrelated render.
+    expect(seen.length).toBeGreaterThan(before);
+    expect(seen[seen.length - 1]).toBe(true);
+    await unmount();
+  });
+
+  it('stays true for a probe mounted after the answer', async () => {
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(true);
+    await unmount();
+  });
+});

package/src/hooks/useCatalogAnswered.ts

@@ -0,0 +1,73 @@
+import { useSyncExternalStore } from 'react';
+import { onCatalogChange } from '@immediately-run/sdk';
+
+// Has the host actually ANSWERED the grant-filtered method catalog?
+//
+// `useCatalog()` starts `[]` and an empty catalog is a legitimate answer (a frame granted
+// nothing), so the value alone cannot distinguish "granted nothing" from "has not replied
+// yet". The reach card needs that distinction: `!chatGranted` is true in both cases, and
+// reading it as "not granted" before the host has spoken claims a consent state about a
+// frame that may well hold the grant (grove#75 round 1).
+//
+// It is derivable here with no SDK change, because the push channel has **no
+// value-equality check**: every host push notifies subscribers, including one whose value
+// equals the initial `[]`. So a notification after the subscribe means the host replied.
+//
+// THE SUBSCRIBE-TIME CALL. `onCatalogChange` invokes the listener once, SYNCHRONOUSLY,
+// with the current value before returning. That call is the subscribe, not an answer — but
+// it is not worthless either, and an earlier version of this file threw it away with a
+// blanket reset. A NON-EMPTY catalog at subscribe can only have come from the host, so it
+// is proof the answer already landed. Reading it that way is what makes this correct when
+// the module is evaluated LATE: grove is also published as a pinned library
+// (`src/lib.ts`), so "imported before any render" is an assumption about one embedding,
+// not a guarantee (grove#75 round 3).
+//
+// RESIDUALS, stated rather than implied:
+//  - a host that answers `[]` BEFORE this module is evaluated is indistinguishable from
+//    one that has not answered, and leaves the flag false for the realm's life. The Q&A
+//    row then stays neutral rather than naming a cause — the same honest "we have not been
+//    told" that the provider channel's `unknown` already renders, but it will not
+//    self-correct, because the host does not push again;
+//  - a host that never answers at all leaves it false forever, for the same reason;
+//  - importing this module is what STARTS the catalog channel and sends
+//    `REQUEST_API_CATALOG`. That used to be the first `useCatalog()` render. The channel
+//    starts at most once and the poll is idempotent, but the timing moved.
+let answered = false;
+let subscribing = true;
+const waiters = new Set<() => void>();
+
+onCatalogChange((catalog) => {
+  if (subscribing) {
+    // Synchronous, at subscribe: the current value, not an answer — except that a
+    // non-empty catalog could only have come from the host.
+    answered = catalog.length > 0;
+    return;
+  }
+  if (answered) return;
+  answered = true;
+  for (const w of waiters) w();
+});
+subscribing = false;
+
+const subscribe = (onStoreChange: () => void): (() => void) => {
+  waiters.add(onStoreChange);
+  return () => {
+    waiters.delete(onStoreChange);
+  };
+};
+const getSnapshot = (): boolean => answered;
+
+/**
+ * Whether the host has answered the method catalog. Re-renders when it flips.
+ *
+ * `useSyncExternalStore` rather than `useState` + `useEffect`, deliberately: the flag is
+ * read during render and written outside React, and a passive effect leaves a window
+ * between the two. An answer landing in that window used to be lost — the effect saw the
+ * flag already set, returned early without registering a waiter, and the component
+ * rendered a stale `false` with nothing left to wake it (grove#75 round 3, reproduced).
+ * `useSyncExternalStore` re-reads the snapshot after subscribing and re-renders if it
+ * moved, which is exactly that hole.
+ */
+export function useCatalogAnswered(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

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.
  */

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/content.test.ts

@@ -147,7 +147,7 @@ describe('linkKind — which hrefs may become a navigating <a>', () => {
 // dispatch declares CORPUS-relative (the host joins its chroot prefix — the corpus's
 // repo-side location is host knowledge this app cannot see).
 import { viewedDocumentForTarget } from './content';
-import { setContentRoot, resetContentRoot } from './contentRoot';
+import { setContentRoot, resetContentRoot, isDispatched } from './contentRoot';
 import { afterEach } from 'vitest';
 
 describe('viewedDocumentForTarget — the R3-268 declaration path space', () => {
@@ -195,6 +195,25 @@ describe('viewedDocumentForTarget — the R3-268 declaration path space', () =>
 // answer "which PATH?" as well as "which entry?" — `[the handbook](handbook)` names
 // something real and must not render as a broken link.
 describe('hrefTargetKey — resolution without the entry-file requirement', () => {
+  afterEach(resetContentRoot);
+  it('R3-184 S2 — the $fs: clamp, ON THE RENDER PATH (the join: isDispatched → resolveLinkTarget)', () => {
+    // The clamp that is in force lives in hrefTargetKey's linkSpaceOpts: the
+    // decision (isDispatched) and the emission (resolveLinkTarget) join in ONE
+    // call, and THIS is the join — ways_of_working §4's rule that a decision and
+    // an emitter can both be tested while the line joining them is not.
+    // Fork (own repo): $fs: stays mount-absolute, as shipped (R3-273).
+    expect(hrefTargetKey('$fs:/mnt/aaa/x.mdx', HOME)).toBe('/mnt/aaa/x.mdx');
+    // Dispatched (a corpus mount): the shared resolver clamps $fs: onto the
+    // bundle root (R3-319's bundleChrooted), so the app-level mount point is
+    // not nameable — the resolved target is a CORPUS path, and only a real
+    // corpus entry there resolves downstream.
+    setContentRoot('/mnt/chroot1');
+    expect(hrefTargetKey('$fs:/mnt/aaa/x.mdx', '/mnt/chroot1/h.mdx')).toBe('/mnt/chroot1/mnt/aaa/x.mdx');
+    // And the same corpus path by its ordinary spelling resolves identically —
+    // the clamp makes $fs:/p and /p the same address, which is the invariant.
+    expect(hrefTargetKey('/mnt/aaa/x.mdx', '/mnt/chroot1/h.mdx')).toBe('/mnt/chroot1/mnt/aaa/x.mdx');
+  });
+
   it('resolves a folder href the entry-candidate list rejects', () => {
     expect(hrefKeyCandidates('handbook', HOME)).toEqual([]);
     expect(hrefTargetKey('handbook', HOME)).toBe('/app/content/handbook');
@@ -275,3 +294,30 @@ describe('link-space parity (LINK_SPACE_FIXTURE, R3-277b)', () => {
     );
   });
 });
+
+describe('isDispatched — the R3-184 S2 `$fs:` clamp discriminator', () => {
+  afterEach(resetContentRoot);
+  // The clamp caller (GroveWiki's LinkSpaceContext) keys the SDK's
+  // `bundleChrooted` flag on this: a DISPATCHED corpus renders inside a
+  // host-minted chroot, so `$fs:` resolves within the corpus and a federated
+  // mount materialised beside it is not nameable from a corpus document; the
+  // fork's `$fs:` stays mount-absolute, as shipped. The flag derivation is
+  // one line over THIS module's state. The JOIN — this decision reaching the
+  // shared resolver on the render path — is pinned by the `$fs:` clamp case in
+  // the hrefTargetKey describe above (the two tests are the pair: the decision
+  // here, the emission there, and the wire between them asserted once).
+  it('fork (own repo): false — the corpus is the engine repo, not a chroot', () => {
+    expect(isDispatched()).toBe(false);
+  });
+
+  it('dispatch (a corpus mount): true', () => {
+    setContentRoot('/mnt/0a1b2c3d');
+    expect(isDispatched()).toBe(true);
+  });
+
+  it('the afterEach resets the root — a later reader sees the fork state', () => {
+    // The reset itself is the convention's job (afterEach, above); asserting it
+    // keeps the leak-visible property testable rather than assumed.
+    expect(isDispatched()).toBe(false);
+  });
+});

package/src/lib/content.ts

@@ -186,6 +186,25 @@ export function hrefKeyCandidates(href: string, fromKey: string): string[] {
  * The two callers ask different questions of the same resolution — "which entry?" and
  * "which path?" — so the resolution lives here once.
  */
+// R3-184 S2 (PERSISTENCE_SPEC §8.3) — the `$fs:` clamp ON the render path, the one
+// the spec's dated note names as the missing piece. This file's hrefTargetKey is
+// where a corpus document's link targets actually resolve (grove's own WikiLink
+// override routes here), so the clamp lives HERE: `bundleChrooted: isDispatched()`
+// makes the shared resolver treat `$fs:/p` exactly like `/p` under the bundle root
+// (R3-319), so a dispatched corpus document's `$fs:/mnt/{hash}/…` cannot name a
+// federated mount materialised beside it — the app-level mount point is not a
+// corpus path. The fork (own repo, not a corpus mount) keeps `$fs:`
+// mount-absolute, as shipped. The LinkSpaceContext field in GroveWiki carries the
+// same flag for the SDK's generic component consumers, the day a release that
+// forwards it is pinned.
+const linkSpaceOpts = (fromKey: string) => ({
+  currentFile: fromKey,
+  // The canonical spelling (mdx-plugins reads bundleRoot-else-corpusRoot; the
+  // deprecated corpusRoot opts field stays for older consumers, not for new code).
+  bundleRoot: getContentRoot(),
+  bundleChrooted: isDispatched(),
+});
+
 export function hrefTargetKey(href: string, fromKey: string): string | null {
   if (!href) return null;
   if (/^(https?:|mailto:|tel:|#)/i.test(href)) return null;
@@ -198,7 +217,7 @@ export function hrefTargetKey(href: string, fromKey: string): string | null {
   // targets resolve against the authoring file; `$fs:` targets resolve
   // mount-absolute (addressing, never reach — R3-273).
   if (!path.startsWith('/')) {
-    const rel = resolveLinkTarget(path, { currentFile: fromKey, corpusRoot: getContentRoot() });
+    const rel = resolveLinkTarget(path, linkSpaceOpts(fromKey));
     if (rel.state !== 'resolved') return null;
     // Confinement, not tidiness: an href in foreign content is untrusted, and the
     // result flows into `fs` reads. In the default space anything that lands outside
@@ -221,7 +240,7 @@ export function hrefTargetKey(href: string, fromKey: string): string | null {
     const legacy = normalizeAbsolute(legacyAnchor + path);
     if (legacy.startsWith(contentDir())) return legacy;
   }
-  const corpusAnchored = resolveLinkTarget(path, { currentFile: fromKey, corpusRoot: getContentRoot() });
+  const corpusAnchored = resolveLinkTarget(path, linkSpaceOpts(fromKey));
   if (corpusAnchored.state === 'resolved' && corpusAnchored.path.startsWith(contentDir())) {
     return corpusAnchored.path;
   }

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 } : {}),
+    },
+  };
+}