@immediately-run/grove 0.1.2 → 0.1.3

package/src/components/ContentTheme.tsx

@@ -0,0 +1,111 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { gateStylesheet } 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`),
+// 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.
+//
+// Gating is PURE and runs in render (a rejected sheet contributes nothing that
+// frame); only the byte-reading mint is effectful.
+//
+// THE ESCAPE HATCH: the theme control (`.grove-theme-control`) is pinned by
+// protective declarations in `grove.reset` — the FIRST layer, which for
+// !important beats every later layer including `grove.content` — so a planted
+// stylesheet cannot hide the way back to a shipped theme. Proven by test, not by
+// reading the layer declaration.
+
+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). */
+  onRejected?: (path: string, verdict: { line: number; reason: string; excerpt: string }) => void;
+}
+
+export default function ContentTheme({ sheets, onRejected }: Props) {
+  // Gate per render — pure. A sheet with declarations rides; a sheet with a
+  // verdict rides its verdict to the caller instead.
+  const results = useMemo(
+    () => sheets.map((sheet) => ({ sheet, verdict: gateStylesheet(sheet.css) })),
+    [sheets],
+  );
+  const accepted = results.filter((r) => r.verdict.ok);
+  const rejected = results.filter((r) => !r.verdict.ok);
+  useEffect(() => {
+    for (const { sheet, verdict } of rejected) {
+      if (verdict.ok) continue;
+      onRejected?.(sheet.path, verdict);
+    }
+  }, [rejected, onRejected]);
+
+  // Declared faces mint through the engine path; the revoke scope is this
+  // sheet set's lifetime.
+  const [assetCss, setAssetCss] = useState<string>('');
+  const mintedRef = useRef<MintedThemeAssets | null>(null);
+  const mintKey = accepted.map((a) => a.sheet.path).join('|');
+  useEffect(() => {
+    let alive = true;
+    const sheetsWithAssets = accepted.filter((r) => {
+      const d = r.sheet.declarations;
+      return (Array.isArray(d.fonts) && d.fonts.length) || (d.assets && Object.keys(d.assets as object).length);
+    });
+    if (!sheetsWithAssets.length) {
+      mintedRef.current?.revoke();
+      mintedRef.current = null;
+      return;
+    }
+    const fsApi = openFs(ROOT_MOUNT);
+    const decl = accepted.length ? sheetsWithAssets[0].sheet.declarations : {};
+    void mintThemeAssets(
+      decl as never,
+      sheetsWithAssets[0].sheet.path,
+      async (p) => {
+        const bytes = await fsApi.readFile(p.replace(/^\/+/, ''));
+        return typeof bytes === 'string' ? new TextEncoder().encode(bytes) : new Uint8Array(bytes);
+      },
+    ).then((m) => {
+      if (!alive) {
+        m.revoke();
+        return;
+      }
+      mintedRef.current?.revoke();
+      mintedRef.current = m;
+      setAssetCss([m.fontFaceCss, m.assetVarsCss].filter(Boolean).join('\n'));
+    });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mintKey is the sheet-set identity
+  }, [mintKey]);
+
+  useEffect(
+    () => () => {
+      mintedRef.current?.revoke();
+    },
+    [],
+  );
+
+  if (!accepted.length && !assetCss) return null;
+  const decls = accepted.map((a) => (a.verdict.ok ? a.verdict.declarations : '')).filter(Boolean).join('\n');
+  return (
+    <>
+      {assetCss ? <style data-grove-content-assets="">{assetCss}</style> : null}
+      {decls ? <style data-grove-content-theme="">{`@layer grove.content{.grove-root{\n${decls}\n}}`}</style> : null}
+    </>
+  );
+}

package/src/components/DocList.infinite.test.tsx

@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+// The windowed feed (R3-314) — every adversarial exit criterion, driven through
+// the real component over a 142-entry fixture:
+//   one batch renders, then extends on scroll, append-only (no boundary shift);
+//   the sentinel is a button — reachable and actionable by keyboard alone;
+//   the end states itself ("that is all N entries"), never merely stops;
+//   no IntersectionObserver → the full list renders (proven by removing it).
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import type { GroveShell } from '../lib/shell';
+import { GroveShellContext } from '../lib/shell';
+import { resetContentRoot, setContentRoot } from '../lib/contentRoot';
+
+const { default: DocList } = await import('./DocList');
+
+// ── the fixture: 142 dated entries, frontmatter-shaped exactly as the query reads ──
+const N = 142;
+const METADATA: Record<string, Record<string, unknown>> = {};
+for (let i = 1; i <= N; i++) {
+  const day = String((i % 28) + 1).padStart(2, '0');
+  // Entry 1 carries a frontmatter code span in title AND description (R3-531):
+  // the field is markdown, and the row must render it as such.
+  const title = i === 1 ? 'Entry 1 — `cache.yml` edition.' : `Entry ${i}.`;
+  const description = i === 1 ? 'The 1st fixture entry, with a `code` span.' : `The ${i}th fixture entry.`;
+  METADATA[`/app/content/log/entry-${String(i).padStart(3, '0')}.mdx`] = {
+    title,
+    description,
+    date: `2026-01-${day}`,
+  };
+}
+
+const NAV = {
+  outerHref: 'https://example.immediately.run/app/x',
+  navigationState: { sandboxPath: '/app/x' },
+  filesMetadata: METADATA,
+};
+const SHELL = { navMode: 'side', vw: 'desktop', navItems: [] } as unknown as GroveShell;
+
+// ── a controllable IntersectionObserver stand-in (the useHeadings pattern,
+//    driven from the test instead of by a real scroll) ──────────────────────────
+let observerInstances: ControllableObserver[] = [];
+class ControllableObserver {
+  cb: IntersectionObserverCallback;
+  targets: Element[] = [];
+  constructor(cb: IntersectionObserverCallback) {
+    this.cb = cb;
+    observerInstances.push(this);
+  }
+  observe(t: Element) {
+    this.targets.push(t);
+  }
+  disconnect() {
+    this.targets = [];
+  }
+  unobserve() {
+    /* unused */
+  }
+  /** The browser's part: "the sentinel is now intersecting". */
+  intersect() {
+    for (const t of this.targets) this.cb([{ isIntersecting: true, target: t } as IntersectionObserverEntry], this as never);
+  }
+}
+
+const rowsOf = (host: HTMLElement): string[] =>
+  [...host.querySelectorAll('.gdl-row__t')].map((e) => e.textContent?.trim() ?? '');
+
+const mount = async (props: Record<string, unknown> = {}): Promise<{ host: HTMLElement; root: Root }> => {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  await act(async () => {
+    root.render(
+      <TinkerableContext.Provider value={NAV as never}>
+        <GroveShellContext.Provider value={SHELL}>
+          <DocList paginate="infinite" batch="20" {...props} />
+        </GroveShellContext.Provider>
+      </TinkerableContext.Provider>,
+    );
+  });
+  return { host, root };
+};
+
+describe('the windowed feed (R3-314)', () => {
+  beforeEach(() => {
+    setContentRoot('/app/content/');
+    observerInstances = [];
+    (window as unknown as Record<string, unknown>).IntersectionObserver = ControllableObserver as never;
+  });
+  afterEach(() => {
+    delete (window as unknown as Record<string, unknown>).IntersectionObserver;
+    resetContentRoot();
+    document.body.innerHTML = '';
+  });
+
+  it('renders ONE batch, not all 142, with the sentinel present', async () => {
+    const { host } = await mount();
+    expect(rowsOf(host)).toHaveLength(20);
+    expect(host.querySelector('.gdl-sentinel')).not.toBeNull();
+    expect(host.querySelector('.gdl-end')).toBeNull();
+  });
+
+  it('extends on intersect — append-only, so no boundary shift', async () => {
+    // "No layout shift, asserted, not eyeballed": the first batch's rows are
+    // still mounted, in the same order, and the list only ever APPENDS. Rows
+    // re-created (keys changed, order shuffled) is how a windowed list shifts.
+    const { host } = await mount();
+    const before = rowsOf(host);
+    const firstNodes = [...host.querySelectorAll('.gdl-row__t')];
+    expect(observerInstances.length).toBeGreaterThan(0);
+    await act(async () => {
+      observerInstances[0]!.intersect();
+    });
+    const after = rowsOf(host);
+    expect(after).toHaveLength(40);
+    expect(after.slice(0, 20)).toEqual(before);
+    const stillMounted = [...host.querySelectorAll('.gdl-row__t')].slice(0, 20);
+    expect(stillMounted.every((el, i) => el === firstNodes[i])).toBe(true);
+  });
+
+  it('the sentinel is a BUTTON — actionable by keyboard alone, to the very end', async () => {
+    const { host } = await mount();
+    const sentinel = host.querySelector<HTMLButtonElement>('.gdl-sentinel');
+    expect(sentinel?.tagName).toBe('BUTTON'); // focusable, Enter/Space actionable
+    let rounds = 0;
+    while (host.querySelector('.gdl-sentinel') && rounds < 20) {
+      await act(async () => {
+        host.querySelector<HTMLButtonElement>('.gdl-sentinel')?.click();
+      });
+      rounds++;
+    }
+    expect(rowsOf(host)).toHaveLength(N); // a keyboard-only user reaches the end
+    expect(host.querySelector('.gdl-sentinel')).toBeNull();
+    expect(host.querySelector('.gdl-end')?.textContent).toContain(`all ${N} entries`);
+  });
+
+  it('the end states itself — the list never merely stops', async () => {
+    const { host } = await mount();
+    for (let i = 0; i < 20 && host.querySelector('.gdl-sentinel'); i++) {
+      await act(async () => {
+        observerInstances[0]?.intersect();
+      });
+    }
+    const end = host.querySelector('.gdl-end');
+    expect(end?.getAttribute('role')).toBe('status');
+    expect(end?.textContent).toMatch(/^That is all 142 entries\.$/);
+  });
+
+  it('with no IntersectionObserver at all, the FULL list renders — proven by removing it', async () => {
+    delete (window as unknown as Record<string, unknown>).IntersectionObserver;
+    const { host } = await mount();
+    expect(rowsOf(host)).toHaveLength(N);
+    expect(host.querySelector('.gdl-sentinel')).toBeNull();
+    expect(host.querySelector('.gdl-end')).toBeNull(); // nothing was windowed
+  });
+
+  it('a frontmatter code span renders as <code>, never as a literal backtick (R3-531)', async () => {
+    // sort:'title' puts entry 1 — the code-span carrier — in the first batch.
+    const { host } = await mount({ sort: 'title' });
+    expect(host.querySelector('.gdl-row__t code')?.textContent).toBe('cache.yml');
+    expect(host.querySelector('.gdl-row__d code')?.textContent).toBe('code');
+    expect(host.textContent).not.toContain('`');
+  });
+
+  it('limit still caps the query — a pinned list is never windowed past its pin', async () => {
+    const { host } = await mount({ limit: '35' });
+    expect(rowsOf(host)).toHaveLength(20);
+    for (let i = 0; i < 3 && host.querySelector('.gdl-sentinel'); i++) {
+      await act(async () => {
+        observerInstances[0]?.intersect();
+      });
+    }
+    expect(rowsOf(host)).toHaveLength(35);
+    expect(host.querySelector('.gdl-end')?.textContent).toContain('all 35 entries');
+  });
+});

package/src/components/DocList.tsx

@@ -1,8 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useCallback } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
 import { isContentEntry, keyToHref, slugToKey } from '../lib/content';
+import InlineProse from './InlineProse';
 import { queryPaths } from '../lib/wiki';
+import EntryImage from './EntryImage';
 
 interface Props {
   shape?: 'feed' | 'grid';
@@ -11,6 +13,13 @@ interface Props {
   tag?: string;
   limit?: string | number;
   sort?: 'date' | 'title';
+  /** "infinite" — a windowed feed that grows on scroll (R3-314). A LITERAL
+   *  attribute: the safe renderer copies `paginate="infinite"` verbatim but drops
+   *  `paginate={mode}` silently, and the list then renders whole with nothing
+   *  saying why. */
+  paginate?: string;
+  /** How many entries a windowed batch adds (literal string or number). */
+  batch?: string | number;
 }
 
 function tagsOf(meta: any): string[] {
@@ -24,8 +33,8 @@ function Row({ path }: { path: string }) {
   return (
     <Link href={keyToHref(path)} className="gdl-row">
       <div>
-        <div className="gdl-row__t">{(meta.title || path).replace(/\.$/, '')}</div>
-        {meta.description && <div className="gdl-row__d">{meta.description}</div>}
+        <div className="gdl-row__t"><InlineProse text={meta.title || path} trimPeriod /></div>
+        {meta.description && <div className="gdl-row__d"><InlineProse text={meta.description} /></div>}
         <div className="gdl-row__tags">
           {tagsOf(meta).slice(0, 3).map((t) => (
             <span key={t} className="grove-tag">#{t}</span>
@@ -37,16 +46,21 @@ function Row({ path }: { path: string }) {
   );
 }
 
-// One entry as a grid card — link-graph placeholder pic + a footer of meta.
+// One entry as a grid card — the entry's `cover:` when it declares one (resolved
+// against the OWNING entry, R3-313 — a card must show its own picture, not the
+// rendered entry's), the link-graph lattice when it does not or the asset is
+// unreadable. Degrade, never break.
 function CardTile({ path }: { path: string }) {
   const meta = useFileMetadata(path) as any;
   if (!meta) return <div className="gdl-card"><div className="gdl-card__pic" /></div>;
   return (
     <Link href={keyToHref(path)} className="gdl-card">
-      <div className="gdl-card__pic" />
+      <div className="gdl-card__pic">
+        <EntryImage entryPath={path} src={meta.cover} alt="" className="gdl-card__cover" degrade={<span className="gdl-card__lattice" />} />
+      </div>
       <div className="gdl-card__foot">
-        <div className="gdl-card__t">{(meta.title || path).replace(/\.$/, '')}</div>
-        {meta.description && <div className="gdl-card__d">{meta.description}</div>}
+        <div className="gdl-card__t"><InlineProse text={meta.title || path} trimPeriod /></div>
+        {meta.description && <div className="gdl-card__d"><InlineProse text={meta.description} /></div>}
         <div className="gdl-card__tags">
           {tagsOf(meta).slice(0, 3).map((t) => (
             <span key={t} className="grove-tag">#{t}</span>
@@ -60,7 +74,26 @@ function CardTile({ path }: { path: string }) {
 // Import-free engine component: a frontmatter-driven index of entries, in a feed
 // or grid shape. `slugs` pins an explicit ordered set; otherwise it queries the
 // whole content space (optionally filtered by `tag`), excluding view/index pages.
-export default function DocList({ shape = 'feed', title, slugs, tag, limit, sort = 'date' }: Props) {
+//
+// `paginate="infinite"` (R3-314): a windowed feed with an IntersectionObserver
+// sentinel — the repo's other observer (useHeadings, the contents rail) is the
+// pattern, and this one reuses its shape rather than inventing machinery. Three
+// states beyond "rows": a skeleton batch (rows render `.sk` until their metadata
+// resolves, occupying the real box so nothing shifts), a sentinel that is a
+// BUTTON — reachable and actionable by keyboard alone, not only by scrolling —
+// and an explicit end ("that is all N entries") rather than a list that merely
+// stops. No IntersectionObserver in the environment → the full list renders;
+// that degradation is the honest fallback, not an error.
+export default function DocList({
+  shape = 'feed',
+  title,
+  slugs,
+  tag,
+  limit,
+  sort = 'date',
+  paginate,
+  batch,
+}: Props) {
   const queryFn = useCallback(
     (fm: Record<string, any>) => {
       const keys = Object.keys(fm).filter((p) => {
@@ -87,6 +120,32 @@ export default function DocList({ shape = 'feed', title, slugs, tag, limit, sort
   const n = limit ? Number(limit) : undefined;
   if (n && paths.length > n) paths = paths.slice(0, n);
 
+  // ── the windowed feed (R3-314) ─────────────────────────────────────────────
+  const windowed = paginate === 'infinite' && typeof IntersectionObserver !== 'undefined';
+  const batchSize = Math.max(1, Number(batch) || 20);
+  const [visible, setVisible] = useState(batchSize);
+  const sentinelRef = useRef<HTMLButtonElement | null>(null);
+  const more = windowed && visible < paths.length;
+  const shown = windowed ? paths.slice(0, visible) : paths;
+
+  useEffect(() => {
+    if (!more) return;
+    const el = sentinelRef.current;
+    if (!el) return;
+    // Load a little BEFORE the sentinel is fully reached, so a slow scroll never
+    // sees the end of the list — same observer shape as useHeadings' scroll-spy.
+    const obs = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) setVisible((v) => v + batchSize);
+      },
+      { rootMargin: '0px 0px 240px 0px', threshold: 0 }
+    );
+    obs.observe(el);
+    return () => obs.disconnect();
+  }, [more, batchSize]);
+
+  const loadMore = () => setVisible((v) => v + batchSize);
+
   return (
     <div className="grove-doclist-wrap">
       {title ? (
@@ -99,9 +158,23 @@ export default function DocList({ shape = 'feed', title, slugs, tag, limit, sort
         <p className="grove-search__empty">No entries yet.</p>
       ) : (
         <div className="grove-doclist" data-shape={shape}>
-          {paths.map((p: string) =>
+          {shown.map((p: string) =>
             shape === 'grid' ? <CardTile key={p} path={p} /> : <Row key={p} path={p} />
           )}
+          {more ? (
+            <button
+              ref={sentinelRef}
+              className="gdl-sentinel"
+              onClick={loadMore}
+              aria-label={`Load the next ${Math.min(batchSize, paths.length - shown.length)} entries`}
+            >
+              <span className="sk sk-line" style={{ width: '42%' }} />
+              <span className="sk sk-line" style={{ width: '68%' }} />
+            </button>
+          ) : null}
+          {windowed && !more && paths.length > batchSize ? (
+            <p className="gdl-end" role="status">That is all {paths.length} entries.</p>
+          ) : null}
         </div>
       )}
     </div>

package/src/components/Drawer.tsx

@@ -1,4 +1,5 @@
 import { Link } from '@immediately-run/sdk';
+import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
 import Sidebar from './Sidebar';
 import Icon from './Icon';
 
@@ -9,7 +10,9 @@ interface NavItem {
 }
 
 // `.grove-drawer` — the mobile nav drawer: site mark + nav items + the full
-// namespace tree, over a dismiss scrim.
+// namespace tree, over a dismiss scrim. The panel carries the dialog contract
+// (R3-608): focus in, Tab trapped, Escape, focus return — via the shared
+// overlay hook, whose stack makes nested overlays close one per Escape.
 export default function Drawer({
   siteTitle,
   nav,
@@ -19,9 +22,18 @@ export default function Drawer({
   nav: NavItem[];
   onClose: () => void;
 }) {
+  const dialogRef = useOverlayFocusDismiss(true, onClose);
   return (
     <div className="grove-drawer" onClick={onClose}>
-      <div className="grove-drawer__panel" onClick={(e) => e.stopPropagation()}>
+      <div
+        className="grove-drawer__panel"
+        ref={dialogRef}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Site menu"
+        onClick={(e) => e.stopPropagation()}
+      >
         <div className="grove-drawer__h">
           <span className="mk" />
           <span className="t">{siteTitle}</span>

package/src/components/EntryHeader.tsx

@@ -1,8 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useFileMetadata } from '@immediately-run/sdk';
-import { useShell } from '../lib/shell';
+import { useShell, EDIT_REFUSED_NOTICE } from '../lib/shell';
 import { crumb } from '../lib/wiki';
 import Icon from './Icon';
+import InlineProse from './InlineProse';
 
 // The entry's header block: breadcrumb, title (optional gradient), meta row
 // (date · reading time · tags) and the unobtrusive edit affordance. Rendered by
@@ -16,7 +17,7 @@ export default function EntryHeader({
   writable: boolean;
   mins: number;
 }) {
-  const { openEditor, editBusy, editHint } = useShell();
+  const { openEditor, editBusy, editRefused, editHint } = useShell();
   const meta = useFileMetadata(entryKey) as any;
   if (!meta) return null;
   const tags: string[] = Array.isArray(meta.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];
@@ -24,7 +25,10 @@ export default function EntryHeader({
   return (
     <header className="grove-entry-header">
       {cr.includes('/') ? <nav className="crumb">{cr}</nav> : null}
-      <h1 className={meta.grad ? 'grad' : ''}>{meta.title || cr}</h1>
+      <h1 className={meta.grad ? 'grad' : ''}>
+        {/* R3-531 — the title is frontmatter prose: code spans render as code. */}
+        <InlineProse text={meta.title || cr} />
+      </h1>
       <div className="grove-meta">
         {meta.date && <span>{meta.date}</span>}
         {mins ? <span>→ {mins} min read</span> : null}
@@ -33,15 +37,22 @@ export default function EntryHeader({
           <span key={t} className="grove-tag">#{t}</span>
         ))}
         {writable && (
-          <button
-            className="grove-edit-affordance"
-            data-busy={editBusy ? '1' : '0'}
-            title={editHint}
-            onClick={() => openEditor(entryKey)}
-          >
-            <Icon name="pencil" />
-            {editBusy ? 'Opening editor…' : 'Edit'}
-          </button>
+          <>
+            <button
+              className="grove-edit-affordance"
+              data-busy={editBusy ? '1' : '0'}
+              title={editHint}
+              onClick={() => openEditor(entryKey)}
+            >
+              <Icon name="pencil" />
+              {editBusy ? 'Opening editor…' : 'Edit'}
+            </button>
+            {editRefused && (
+              <span className="grove-edit-refused" role="status">
+                {EDIT_REFUSED_NOTICE}
+              </span>
+            )}
+          </>
         )}
       </div>
     </header>