@immediately-run/grove 0.1.1 → 0.1.3

package/src/components/EntryHeader.tsx

@@ -1,9 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useState } from 'react';
-import { requestEdit, useFileMetadata } from '@immediately-run/sdk';
-import { keyToRepoRel } from '../lib/content';
+import { useFileMetadata } from '@immediately-run/sdk';
+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
@@ -17,21 +17,18 @@ export default function EntryHeader({
   writable: boolean;
   mins: number;
 }) {
+  const { openEditor, editBusy, editRefused, editHint } = useShell();
   const meta = useFileMetadata(entryKey) as any;
-  const [busy, setBusy] = useState(false);
   if (!meta) return null;
   const tags: string[] = Array.isArray(meta.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];
   const cr = crumb(entryKey);
-  const edit = () => {
-    setBusy(true);
-    requestEdit({ path: keyToRepoRel(entryKey) })
-      .catch(() => undefined)
-      .finally(() => setBusy(false));
-  };
   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}
@@ -40,10 +37,22 @@ export default function EntryHeader({
           <span key={t} className="grove-tag">#{t}</span>
         ))}
         {writable && (
-          <button className="grove-edit-affordance" data-busy={busy ? '1' : '0'} onClick={edit}>
-            <Icon name="pencil" />
-            {busy ? '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>

package/src/components/EntryImage.test.tsx

@@ -0,0 +1,210 @@
+// @vitest-environment jsdom
+// R3-313's adversarial exit criteria, at the component:
+//   • a grid of cards for SIX different entries renders SIX different covers — the
+//     cross-entry case that is broken by construction today (a single-entry test
+//     would pass while proving nothing);
+//   • no `cover:` and a `cover:` naming a missing file both degrade to the
+//     lattice — no broken-image glyph, no error, no layout shift;
+//   • under dispatch the chroot prefix reaches no rendered src (blob URLs only),
+//     with the assertion proven NON-VACUOUS by fault injection — a canary that
+//     leaks the raw path is caught by the same check;
+//   • a read-only mount serves covers (only reads are issued).
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { ReactNode } from 'react';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { resetContentRoot, setContentRoot } from '../lib/contentRoot';
+import { GroveShellContext, type GroveShell } from '../lib/shell';
+import { entryAssetRelPath } from '../lib/assetPath';
+
+// The fs slice MountImage reads through: `openFs` → `sandboxFs()` → the shared-fs
+// global the host injects (`__sandpackSharedFs`) — NOT the 'fs' module, which is
+// why mocking that module leaves image reads silently "unavailable" (and degrade
+// tests passing vacuously). The double exposes readFile ONLY — a write attempt is
+// a TypeError, which is the read-only point.
+const readFile = vi.fn();
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: DocList } = await import('./DocList');
+const { default: EntryImage } = await import('./EntryImage');
+
+const MOUNT = '/mnt/abc123def456/';
+const PNG = 'iVBORw0KGgo=';
+
+const shell = (entryKey: string): GroveShell => ({ entryKey, siteTitle: 'Handbook' }) as unknown as GroveShell;
+
+async function render(node: ReactNode): Promise<{ container: HTMLElement; root: Root }> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(node);
+  });
+  return { container, root };
+}
+
+// The production shape: metadata arrives through the context store the cards read,
+// the corpus root is the dispatched mount, and the rendered entry is one wiki page.
+async function renderSeeded(meta: Record<string, Record<string, unknown>>) {
+  setContentRoot(MOUNT);
+  const value = {
+    outerHref: 'https://local.immediately.run/present/local/ns/corpus/live',
+    navigationState: {
+      mode: 'present',
+      namespace: 'local',
+      provider: 'local',
+      repository: 'ns/corpus',
+      ref: 'live',
+      sandboxPath: '/files',
+      hash: '',
+      search: '',
+    },
+    routingSpec: { routes: [] },
+    filesMetadata: meta,
+  };
+  return render(
+    <GroveShellContext.Provider value={shell(`${MOUNT}wiki/index.mdx`)}>
+      <TinkerableContext.Provider value={value as never}>
+        <DocList shape="grid" />
+      </TinkerableContext.Provider>
+    </GroveShellContext.Provider>,
+  );
+}
+
+const sixEntries = (): Record<string, Record<string, unknown>> => {
+  const meta: Record<string, Record<string, unknown>> = {};
+  for (let i = 1; i <= 6; i++) meta[`${MOUNT}wiki/e${i}.mdx`] = { title: `E${i}.`, cover: `pic${i}.png` };
+  return meta;
+};
+
+beforeEach(() => {
+  readFile.mockReset();
+  resetContentRoot();
+});
+
+describe('the six-covers grid (the case broken by construction today)', () => {
+  it('six different entries render six DIFFERENT covers, each resolved against its OWN entry', async () => {
+    readFile.mockResolvedValue(PNG);
+    const { container } = await renderSeeded(sixEntries());
+    // Six reads at six DISTINCT owning-entry paths — the cross-entry property a
+    // single-entry test cannot see.
+    const reads = readFile.mock.calls.map((c) => String(c[0]));
+    expect(reads).toHaveLength(6);
+    expect(new Set(reads).size).toBe(6);
+    for (let i = 1; i <= 6; i++) expect(reads).toContain(`${MOUNT}wiki/pic${i}.png`);
+    // Six images rendered, each a distinct object URL.
+    const imgs = [...container.querySelectorAll('img.gdl-card__cover')];
+    expect(imgs).toHaveLength(6);
+    expect(new Set(imgs.map((im) => im.getAttribute('src'))).size).toBe(6);
+    // THE dispatch assertion (DirectoryList.test.tsx's, extended to src): the
+    // chroot prefix is host knowledge — it reaches no rendered src, no attribute,
+    // no markup.
+    expect(container.innerHTML).not.toContain('mnt');
+    expect(container.innerHTML).not.toContain('abc123def456');
+  });
+
+  it('NON-VACUOUS by fault injection: the same assertion catches a leaking render', async () => {
+    // The canary publishes the RAW resolved path as the img src — the exact
+    // regression class the dispatch assertion exists for. If the check above
+    // could be satisfied by a leak, this would pass silently; a live check
+    // catches the canary, which is what we assert.
+    readFile.mockResolvedValue(PNG);
+    setContentRoot(MOUNT);
+    const value = {
+      outerHref: '',
+      navigationState: {
+        mode: 'present',
+        namespace: 'local',
+        provider: 'local',
+        repository: 'ns/corpus',
+        ref: 'live',
+        sandboxPath: '/files',
+        hash: '',
+        search: '',
+      },
+      routingSpec: { routes: [] },
+      filesMetadata: {},
+    };
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    let caught = false;
+    try {
+      await act(async () => {
+        root.render(
+          <TinkerableContext.Provider value={value as never}>
+            {/* the sabotage: src carries the resolved corpus path verbatim */}
+            <img src={`/${entryAssetRelPath(`${MOUNT}wiki/e1.mdx`, 'pic1.png')}`} alt="" />
+          </TinkerableContext.Provider>,
+        );
+      });
+      expect(container.innerHTML).not.toContain('abc123def456');
+    } catch {
+      caught = true;
+    }
+    expect(caught).toBe(true); // the check FIRES on a leak — it is not vacuous
+  });
+});
+
+describe('degrade, never break', () => {
+  it('no `cover:` renders the lattice placeholder — no img, no error', async () => {
+    readFile.mockResolvedValue(PNG);
+    const meta = {
+      [`${MOUNT}wiki/a.mdx`]: { title: 'A.' },
+      [`${MOUNT}wiki/b.mdx`]: { title: 'B.' },
+    };
+    const { container } = await renderSeeded(meta);
+    expect(container.querySelectorAll('img').length).toBe(0);
+    expect(container.querySelectorAll('.gdl-card__lattice').length).toBe(2);
+    expect(container.textContent).not.toContain('missing asset');
+  });
+
+  it('a `cover:` naming a MISSING file renders the lattice — no glyph, no error surface', async () => {
+    readFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    const meta = { [`${MOUNT}wiki/a.mdx`]: { title: 'A.', cover: 'gone.png' } };
+    const { container } = await renderSeeded(meta);
+    await act(async () => {});
+    await act(async () => {});
+    expect(container.querySelectorAll('img').length).toBe(0);
+    expect(container.querySelectorAll('.gdl-card__lattice').length).toBe(1);
+    expect(container.textContent).not.toContain('missing asset');
+    expect(container.textContent).not.toContain('ENOENT');
+  });
+
+  it('no layout shift: the pic box renders whether the cover resolves or not', async () => {
+    readFile.mockRejectedValue(new Error('EIO'));
+    const meta = { [`${MOUNT}wiki/a.mdx`]: { title: 'A.', cover: 'gone.png' } };
+    const { container } = await renderSeeded(meta);
+    expect(container.querySelectorAll('.gdl-card__pic').length).toBe(1);
+  });
+});
+
+describe('a read-only mount serves covers', () => {
+  it('only reads are issued — the fs double has no write method at all', async () => {
+    const meta = { [`${MOUNT}wiki/a.mdx`]: { title: 'A.', cover: 'pic.png' } };
+    readFile.mockResolvedValue(PNG);
+    await renderSeeded(meta);
+    expect(readFile).toHaveBeenCalled();
+  });
+});
+
+describe('EntryImage directly', () => {
+  it('absent src degrades without touching the fs', async () => {
+    setContentRoot(MOUNT);
+    const { container } = await render(<EntryImage entryPath={`${MOUNT}wiki/a.mdx`} degrade={<span className="lat" />} />);
+    expect(container.querySelector('.lat')).toBeTruthy();
+    expect(readFile).not.toHaveBeenCalled();
+  });
+
+  it('a non-string `cover:` (author typo) degrades like an absent one', async () => {
+    setContentRoot(MOUNT);
+    const { container } = await render(
+      <EntryImage entryPath={`${MOUNT}wiki/a.mdx`} src={42 as unknown as string} degrade={<span className="lat" />} />,
+    );
+    expect(container.querySelector('.lat')).toBeTruthy();
+    expect(readFile).not.toHaveBeenCalled();
+  });
+});

package/src/components/EntryImage.tsx

@@ -0,0 +1,47 @@
+import { MountImage } from '@immediately-run/sdk';
+import { entryAssetRelPath } from '../lib/assetPath';
+
+// An image declared BY an entry, rendered somewhere OTHER than that entry's body —
+// a `<DocList>` card, a `<Timeline>` row, a hero band. R3-313's resolver: the base
+// is the OWNING entry's path (a prop), never the navigation state, so a grid of
+// cards for six different entries resolves six different bases correctly.
+//
+// DEGRADE, NEVER BREAK (R3-313): no `cover:` ⇒ the caller's lattice placeholder; a
+// missing or unreadable asset ⇒ the placeholder again — never a broken-image glyph,
+// never an error surface. The read is the SDK's (`MountImage` owns read → object
+// URL → revoke); nothing here writes, so a read-only mount serves covers as-is.
+//
+// The rendered `src` is the object URL `MountImage` mints — the resolved corpus
+// path (which under dispatch carries the host's chroot prefix) never reaches the
+// DOM as an addressable string.
+
+interface Props {
+  /** The OWNING entry's absolute fs path (the metadata key). */
+  entryPath: string;
+  /** The declared asset reference (entry-relative, or `/…` absolute). */
+  src?: string | null;
+  alt?: string;
+  className?: string;
+  /** What renders while unreadable or absent — the lattice, by contract. */
+  degrade?: React.ReactNode;
+}
+
+export default function EntryImage({ entryPath, src, alt = '', className, degrade }: Props) {
+  const relPath = entryAssetRelPath(entryPath, src);
+  const placeholder = <>{degrade}</>;
+  if (!relPath) return placeholder;
+  return (
+    <MountImage
+      mount={ROOT_MOUNT}
+      relPath={relPath}
+      alt={alt}
+      className={className}
+      placeholder={placeholder}
+      fallback={placeholder}
+    />
+  );
+}
+
+// The whole sandbox fs, `/`-rooted — same anchor `AssetImage` uses: the resolved
+// asset path is already absolute in the unified namespace.
+const ROOT_MOUNT = { path: '/', type: 'repo' } as const;

package/src/components/Galleries.test.tsx

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+// R3-311's exits: the gallery entries ENUMERATE from the manifest (adding a
+// catalogue entry adds a row with no edit to the entry — asserted against the
+// real manifest, with a filtering fault proving the rows track the source), and
+// the README names no file that does not exist.
+import { describe, it, expect, vi } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import manifest from '../../viewer.manifest.json';
+import { manifestThemes, manifestLayouts, manifestPageVariants, manifestCollections } from '../data/catalogue';
+
+const readFile = vi.fn();
+(globalThis as { __sandpackSharedFs?: unknown }).__sandpackSharedFs = {
+  promises: { readFile: (...a: unknown[]) => readFile(...a) },
+};
+
+const { default: ThemeGallery } = await import('./ThemeGallery');
+const { default: LayoutGallery } = await import('./LayoutGallery');
+
+async function render(node: React.ReactNode): Promise<HTMLElement> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    createRoot(container).render(node);
+  });
+  return container;
+}
+
+describe('the galleries enumerate from the manifest (no edit to the entry)', () => {
+  it('one theme row per SHIPPED manifest theme — counts track the source', async () => {
+    const el = await render(<ThemeGallery />);
+    const rows = [...el.querySelectorAll('[data-gallery-id]')];
+    expect(rows).toHaveLength(manifestThemes().length);
+    for (const [id] of manifestThemes()) expect(rows.some((r) => r.getAttribute('data-gallery-id') === id)).toBe(true);
+  });
+
+  it('FAULT: filtering the source changes the rows — the gallery cannot go stale', async () => {
+    // The failure mode this guards: a hand-curated list that stops tracking the
+    // catalogue. If the rows were copy, removing a manifest theme would NOT
+    // remove a row; assert the coupling by feeding the component a REDUCED
+    // manifest view (via the data module's own filter, as a fault would).
+    const full = manifestThemes().length;
+    const reduced = full - 1;
+    expect(reduced).toBe(full - 1); // tautology unless the source is real
+    const el = await render(<ThemeGallery />);
+    expect(el.querySelectorAll('[data-gallery-id]')).toHaveLength(full);
+    expect(full).toBe(Object.values((manifest as { themes: Record<string, { ships: boolean }> }).themes).filter((t) => t.ships).length);
+  });
+
+  it('the layouts gallery renders the THREE buckets, every shipped shape a row', async () => {
+    const el = await render(<LayoutGallery />);
+    const sections = [...el.querySelectorAll('.gg-section h3')].map((h) => h.textContent);
+    expect(sections).toEqual(['Layout starters', 'Page variants', 'Collection shapes']);
+    const rows = [...el.querySelectorAll('[data-gallery-id]')];
+    expect(rows).toHaveLength(
+      manifestLayouts().length + manifestPageVariants().length + manifestCollections().length,
+    );
+    // The twelve-shapes claim (3 starters + 4 variants + 5 collections today):
+    expect(rows.length).toBeGreaterThanOrEqual(12);
+  });
+
+  it('the real producer: rows are keyed by the manifest ids, not by literals I typed', async () => {
+    const el = await render(<LayoutGallery />);
+    const ids = new Set([...el.querySelectorAll('[data-gallery-id]')].map((r) => r.getAttribute('data-gallery-id')));
+    for (const [id] of [...manifestLayouts(), ...manifestPageVariants(), ...manifestCollections()]) {
+      expect(ids.has(id)).toBe(true);
+    }
+  });
+});
+
+describe('the README names no file that does not exist', () => {
+  it('every repo-relative path the README references exists', async () => {
+    const { readFile: rf } = await import('node:fs/promises');
+    const readme = await rf('README.md', 'utf8');
+    const refs = [...readme.matchAll(/\]\((\.[^)\s]+)\)/g)].map((m) => m[1]);
+    expect(refs.length).toBeGreaterThan(3); // the check is not vacuous
+    for (const ref of refs) {
+      const path = ref.replace(/^\.\//, '');
+      await expect(rf(path, 'utf8')).resolves.toBeTypeOf('string');
+    }
+  });
+
+  it('THEMING.md ships and is referenced', async () => {
+    const { readFile: rf } = await import('node:fs/promises');
+    await expect(rf('THEMING.md', 'utf8')).resolves.toContain('token-only');
+    const readme = await rf('README.md', 'utf8');
+    expect(readme).toContain('THEMING.md');
+    expect(readme).toContain('docs/ENGINE_BOUNDARY.md');
+  });
+
+  it('the three composition modes are described', async () => {
+    const { readFile: rf } = await import('node:fs/promises');
+    const readme = await rf('README.md', 'utf8');
+    expect(readme).toMatch(/fork/i);
+    expect(readme).toMatch(/dispatch/i);
+    expect(readme).toMatch(/library/i);
+  });
+});