@immediately-run/grove 0.2.0 → 0.2.2

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.2.0)
+> 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.2.2)
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/grove",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@immediately-run/mdx-plugins": "0.7.1",
-    "@immediately-run/sdk": "^0.72.0",
+    "@immediately-run/sdk": "^0.80.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },
@@ -88,7 +88,7 @@
     "llms.txt"
   ],
   "peerDependencies": {
-    "@immediately-run/sdk": "^0.72.0",
+    "@immediately-run/sdk": "^0.80.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   }

package/src/GroveApp.css

@@ -1677,6 +1677,17 @@ a.gdl-row {
   gap: 8px;
   align-items: center;
 }
+/* The weighted cloud's pixel range lives HERE and nowhere else (the component
+   only sets --tag-weight): 11.5px (the plain .grove-tag size) to 22px. The rule
+   hangs off the --weighted modifier because TagList shares the .grove-tagcloud
+   wrapper and must stay unweighted. */
+.grove-tagcloud--weighted .grove-tag {
+  font-size: calc(11.5px + var(--tag-weight, 0) * 10.5px);
+}
+.grove-tag__count {
+  opacity: 0.5;
+  margin-left: 4px;
+}
 
 /* ============ skeleton ============ */
 @keyframes gshimmer {

package/src/GroveWiki.tsx

@@ -373,8 +373,8 @@ export default function GroveWiki({
   return (
     // R3-277b: declare the enclosing bundle for the platform's link-space consumers
     // (the shared resolver's bundle-anchored absolute + `$fs:` handling read this).
-    // R3-482: the SDK pin (^0.72.0, #75) reads `bundleRoot` new-then-old, so the new
-    // spelling is stated alone — the deprecated `corpusRoot` stays in the type for
+    // R3-482: the SDK pin (since ^0.72.0, #75) reads `bundleRoot` new-then-old, so the
+    // new spelling is stated alone — the deprecated `corpusRoot` stays in the type for
     // older consumers (mdx-plugins' forever-compat) but no longer here.
     <LinkSpaceContext.Provider
       value={{
@@ -387,12 +387,10 @@ export default function GroveWiki({
         // chroot), 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 — and the fork's `$fs:` stays
-        // mount-absolute. THIS field carries the same flag for the SDK's generic
-        // component consumers (WikiLink/MDXComponents): the pinned SDK 0.72.0
-        // does not forward it, so it is decided-but-not-consumed until a
-        // forwarding release is published and pinned — the booked follow-up,
-        // stated here rather than blurred (§8.3's dated note:
-        // built-but-not-in-force is a materially different state from done).
+        // mount-absolute. This field carries the same flag for the SDK's generic
+        // component consumers (WikiLink/MDXComponents) — consumed since the
+        // 0.79.0 pin (R3-783): those components forward it to the shared
+        // resolver, so the clamp is load-bearing on the generic path too.
         bundleChrooted: isDispatched(),
       }}
     >

package/src/components/TagCloud.test.tsx

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+// TagCloud's render contract: chips carry a 0..1 `--tag-weight` and NO inline
+// font-size (the pixel range is GroveApp.css's), the wrapper carries the
+// --weighted modifier, and `limit` keeps the N most-used tags (a bad limit is
+// ignored with one warning). Metadata is supplied through TinkerableContext, the
+// way Sidebar.test.tsx supplies its map. The rendered pixel size itself is
+// jsdom-untestable (no calc()/custom-property resolution) — that leg is R3-946.
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+
+const { default: TagCloud } = await import('./TagCloud');
+
+// One tag on 191 entries (the real docs corpus's `bug` scale) and one on a
+// single entry.
+const FILES = {
+  ...Object.fromEntries(
+    Array.from({ length: 191 }, (_, i) => [`/app/content/e${i}.mdx`, { title: `E${i}`, tags: ['bug'] }]),
+  ),
+  '/app/content/single.mdx': { title: 'Single.', tags: ['doc'] },
+};
+
+const NAV = {
+  outerHref: 'https://example.immediately.run/app/x',
+  navigationState: {
+    sandboxPath: '/app/x',
+    provider: 'github',
+    namespace: 'immediately-run',
+    repository: 'docs',
+    ref: 'main',
+    hash: '',
+    search: '',
+  },
+  routingSpec: {} as never,
+  filesMetadata: FILES,
+};
+
+let mounted: { root: Root; container: HTMLElement } | null = null;
+
+async function mountCloud(limit?: number): Promise<HTMLElement> {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(
+      <TinkerableContext.Provider value={NAV as never}>
+        <TagCloud limit={limit} />
+      </TinkerableContext.Provider>,
+    );
+  });
+  mounted = { root, container };
+  return container;
+}
+
+afterEach(() => {
+  if (mounted) {
+    act(() => mounted!.root.unmount());
+    mounted!.container.remove();
+    mounted = null;
+  }
+});
+
+const chips = (container: HTMLElement): HTMLElement[] =>
+  [...container.querySelectorAll('.grove-tag')] as HTMLElement[];
+
+describe('TagCloud', () => {
+  it('weights every chip between 0 and 1 with no inline font-size, on a --weighted wrapper', async () => {
+    const container = await mountCloud();
+    expect(container.querySelector('.grove-tagcloud')!.classList.contains('grove-tagcloud--weighted')).toBe(true);
+    const all = chips(container);
+    expect(all.length).toBe(2);
+    const weights = all.map((chip) => Number.parseFloat(chip.style.getPropertyValue('--tag-weight')));
+    for (const w of weights) {
+      expect(Number.isFinite(w)).toBe(true);
+      expect(w).toBeGreaterThanOrEqual(0);
+      expect(w).toBeLessThanOrEqual(1);
+    }
+    // Chips read alphabetically: `bug` (191 entries, the maximum) then `doc`
+    // (one entry, the minimum).
+    expect(weights).toEqual([1, 0]);
+    for (const chip of all) expect(chip.style.fontSize).toBe('');
+  });
+
+  it('limit={1} renders only the most-used tag, still scaled against the corpus', async () => {
+    const container = await mountCloud(1);
+    const all = chips(container);
+    expect(all.length).toBe(1);
+    expect(all[0]!.textContent).toContain('bug');
+    // Corpus-relative (not subset-relative): the corpus maximum keeps weight 1
+    // under the limit — subset scaling would give it min === max → 0.
+    expect(all[0]!.style.getPropertyValue('--tag-weight')).toBe('1');
+  });
+
+  it('limit={0} is treated as absent and warns once', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const container = await mountCloud(0);
+    expect(chips(container).length).toBe(2);
+    expect(warn.mock.calls.length).toBe(1);
+    expect(String(warn.mock.calls[0]![0])).toContain('0');
+    warn.mockRestore();
+  });
+});

package/src/components/TagCloud.tsx

@@ -1,46 +1,64 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
+import type { CSSProperties } from 'react';
 import { useMetadataQuery } from '@immediately-run/sdk';
 import { contentDir } from '../lib/content';
 import { queryPaths } from '../lib/wiki';
+import { countTags, tagWeight, topTags, type TagCount } from '../lib/tagCloud';
 
 // Import-free engine component: every tag across the site, sized by frequency.
 // Chrome tags (`ui/*`) are excluded — they drive layout, not classification.
-export default function TagCloud() {
+//
+// Sizing: each chip carries its weight as `--tag-weight` and the CSS owns the
+// pixels (11.5–22px) — the old `11 + count * 2 + 'px'` inline style had no
+// ceiling and let a frequent tag fill the viewport. The wrapper carries the
+// `--weighted` modifier so the rule never touches TagList's plain chips, which
+// share the `.grove-tagcloud` wrapper class.
+
+// A bad `limit` warns once per distinct value per session — an authored page
+// never goes blank over a prop.
+const warnedLimits = new Set<string>();
+
+export default function TagCloud({ limit }: { limit?: number }) {
+  const limitOk = limit === undefined || (Number.isInteger(limit) && limit > 0);
+  useEffect(() => {
+    if (limitOk) return;
+    const key = String(limit);
+    if (warnedLimits.has(key)) return;
+    warnedLimits.add(key);
+    console.warn(`TagCloud: limit must be a positive integer, got ${key} — showing every tag`);
+  }, [limit, limitOk]);
+
   const queryFn = useCallback((filesMetadata: Record<string, any>) => {
-    const counts: Record<string, number> = {};
-    Object.entries(filesMetadata).forEach(([p, m]) => {
-      if (!p.startsWith(contentDir())) return;
-      if (m && Array.isArray(m.tags)) {
-        m.tags.forEach((t: string) => {
-          if (t.startsWith('ui/')) return;
-          counts[t] = (counts[t] || 0) + 1;
-        });
-      }
-    });
-    // Encode counts into the string[] the query contract returns.
-    return Object.keys(counts)
-      .sort()
-      .map((t) => `${t}:${counts[t]}`);
+    // The query contract is string-valued, so the pairs ride as `tag:count`
+    // (the encoding is unchanged).
+    return countTags(filesMetadata, contentDir()).map(({ tag, count }) => `${tag}:${count}`);
   }, []);
 
   const result = useMetadataQuery(queryFn);
   const entries: string[] = queryPaths(result);
+  const pairs: TagCount[] = entries.map((e) => {
+    const [tag, count] = e.split(':');
+    return { tag: tag!, count: Number(count) };
+  });
+  const shown = topTags(pairs, limitOk ? limit : undefined);
+  // The scale is relative to the CORPUS (every tag), not the shown subset —
+  // under a limit the corpus's most-used tag must still read as the largest.
+  const counts = pairs.map((p) => p.count);
+  const min = Math.min(...counts);
+  const max = Math.max(...counts);
 
   return (
-    <div className="grove-tagcloud">
-      {entries.map((e) => {
-        const [tag, count] = e.split(':');
-        return (
-          <span
-            key={tag}
-            className="grove-tag"
-            style={{ fontSize: 11 + Number(count) * 2 + 'px', padding: '4px 12px' }}
-          >
-            #{tag} <span style={{ opacity: 0.5, marginLeft: 4 }}>{count}</span>
-          </span>
-        );
-      })}
+    <div className="grove-tagcloud grove-tagcloud--weighted">
+      {shown.map(({ tag, count }) => (
+        <span
+          key={tag}
+          className="grove-tag"
+          style={{ '--tag-weight': String(tagWeight(count, min, max)) } as CSSProperties}
+        >
+          #{tag} <span className="grove-tag__count">{count}</span>
+        </span>
+      ))}
     </div>
   );
 }

package/src/hooks/useEditAffordance.test.tsx

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+// R3-877 — the workbench delivery of the edit affordance for a read-only opener
+// delegation: `requestEdit({ bundleFile })`, with the refusal contract pinned:
+// `read-only` hides the affordance until the next mount announcement, `cancelled`
+// stays silent, `forbidden` (and anything else) sets `refused`.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act, useEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+import type { EditAffordance } from './useEditAffordance';
+
+const requestEditMock = vi.fn<(t?: unknown) => Promise<void>>();
+const invokeTaskMock = vi.fn<(a: unknown) => Promise<void>>();
+const useMountsMock = vi.fn<() => unknown[]>();
+
+vi.mock('@immediately-run/sdk', () => ({
+  requestEdit: (a?: unknown) => requestEditMock(a),
+  invokeTask: (a: unknown) => invokeTaskMock(a),
+  capFile: (ref: unknown, opts: unknown) => ({ ...(ref as object), ...(opts as object) }),
+  useMounts: () => useMountsMock(),
+}));
+
+// The corpus identity comes from the real contentRoot module, driven through its
+// own producer (R3-877 round 1, R2) — never a hand-typed shape.
+import { getContentRoot, resetContentRoot, setContentRoot } from '../lib/contentRoot';
+
+import { useEditAffordance } from './useEditAffordance';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const RO_MOUNT = { type: 'task-delegation', path: '/task/t1/dir', id: '/task/t1/dir', mode: 'ro', readerCanEdit: true };
+
+let latest: EditAffordance | null = null;
+function Probe() {
+  const affordance = useEditAffordance(false);
+  useEffect(() => {
+    latest = affordance;
+  });
+  return null;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  setContentRoot('/task/t1/dir', { mountId: '/task/t1/dir' });
+  requestEditMock.mockReset().mockResolvedValue(undefined);
+  invokeTaskMock.mockReset().mockResolvedValue(undefined);
+  useMountsMock.mockReset().mockReturnValue([RO_MOUNT]);
+  latest = null;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => root.render(<Probe />));
+});
+
+const rerender = () => act(() => root.render(<Probe />));
+
+afterEach(() => {
+  resetContentRoot();
+  act(() => root.unmount());
+  container.remove();
+});
+const open = async (key = `${getContentRoot()}plot/the-rail.mdx`) => {
+  await act(async () => {
+    latest!.openEditor(key);
+    await Promise.resolve();
+  });
+  rerender();
+};
+
+describe('useEditAffordance — the workbench delivery (R3-877)', () => {
+  it('an ro delegation offers Edit and delivers it as requestEdit({ bundleFile })', async () => {
+    expect(latest!.writable).toBe(true);
+    await open();
+    expect(requestEditMock).toHaveBeenCalledWith({ bundleFile: '/plot/the-rail.mdx' });
+    expect(invokeTaskMock).not.toHaveBeenCalled();
+    expect(latest!.refused).toBe(false);
+  });
+
+  it('an ro delegation with `readerCanEdit: false` does not offer the control', () => {
+    useMountsMock.mockReturnValue([{ ...RO_MOUNT, readerCanEdit: false }]);
+    rerender();
+    expect(latest!.writable).toBe(false);
+  });
+
+  it('a `read-only` refusal hides the affordance until the next mount announcement', async () => {
+    requestEditMock.mockRejectedValue(Object.assign(new Error('no'), { code: 'read-only' }));
+    await open();
+    expect(latest!.refused).toBe(false); // not a render-in-place refusal
+    expect(latest!.writable).toBe(false); // hidden…
+    useMountsMock.mockReturnValue([{ ...RO_MOUNT }]); // …until the next announcement…
+    rerender();
+    expect(latest!.writable).toBe(true); // …unlatches it.
+  });
+
+  it('a `cancelled` rejection stays silent (the reader closed the editor)', async () => {
+    requestEditMock.mockRejectedValue(Object.assign(new Error('closed'), { code: 'cancelled' }));
+    await open();
+    expect(latest!.refused).toBe(false);
+    expect(latest!.writable).toBe(true);
+  });
+
+  it('a `forbidden` refusal sets `refused` (rendered as text in place) and never retries via edit-file', async () => {
+    requestEditMock.mockRejectedValue(Object.assign(new Error('no'), { code: 'forbidden' }));
+    await open();
+    expect(latest!.refused).toBe(true);
+    expect(invokeTaskMock).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useEditAffordance.ts

@@ -7,9 +7,11 @@
 // was withheld entirely and the wiki became read-only for the one packaging where the
 // content is most obviously somebody's to edit.
 //
-// The decision is pure (`lib/editTarget`); this hook is the wiring: it reads the LIVE
-// mount list so a role downgrade hides the affordance on the next render rather than
-// producing `EROFS` on click, and it hands back one `openEditor(entryKey)` the chrome
+// The decision is pure (`lib/editTarget`); this hook is the wiring: it reads the live
+// mount list so a role downgrade reroutes the delivery on the next render (rw → the
+// `edit-file` overlay; ro → the workbench under the reader's authority, R3-877) rather
+// than producing `EROFS` on click — and a `readerCanEdit: false` hint or a `read-only`
+// refusal hides the offer — and it hands back one `openEditor(entryKey)` the chrome
 // calls without knowing which packaging it is in.
 import { useCallback, useMemo, useState } from 'react';
 import { capFile, invokeTask, requestEdit, useMounts } from '@immediately-run/sdk';
@@ -46,14 +48,28 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
 
   // Read the corpus identity through the mount list's identity, so the memo re-runs when
   // the host re-announces a mount. The root itself is latched at boot (see `contentRoot`);
-  // the MODE is not, and that is the half this hook exists to keep current.
-  const corpus = useMemo(
-    () => ({ dispatched: isDispatched(), contentRoot: getContentRoot(), mountId: getCorpusMountId() }),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [mounts],
-  );
+  // the MODE is not, and that is the half this hook exists to keep current. R3-877: the
+  // delegation's live MODE now also routes the delivery (rw → the edit-file overlay,
+  // ro → the workbench under the reader's authority).
+  const corpus = useMemo(() => {
+    const mountId = getCorpusMountId();
+    const mount = mounts?.find((m) => (m.id ?? m.path) === mountId);
+    return { dispatched: isDispatched(), contentRoot: getContentRoot(), mountId, mountMode: mount?.mode ?? null };
+  }, [mounts]);
+
+  // R3-877: a `read-only` refusal (the reader cannot edit the source) hides the
+  // affordance until the next mount announcement — the hint's re-announcement is
+  // exactly what unlatches it. Reset on every mount-list change — the
+  // render-adjusted-state pattern (not an effect, which would paint one frame
+  // stale), the React-sanctioned form.
+  const [readerReadOnly, setReaderReadOnly] = useState(false);
+  const [resetFor, setResetFor] = useState(mounts);
+  if (resetFor !== mounts) {
+    setResetFor(mounts);
+    setReaderReadOnly(false);
+  }
 
-  const writable = !readOnly && corpusWritable(mounts, corpus);
+  const writable = !readOnly && !readerReadOnly && corpusWritable(mounts, corpus);
 
   // A refusal surfaces where the affordance was offered (3.3.1, R3-608);
   // `cancelled` — the reader closing the editor — stays silent by contract.
@@ -75,10 +91,31 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
         requestEdit({ path: target.path }).catch(refusedUnlessCancelled).finally(done);
         return;
       }
-      // Dispatch: attenuate the corpus delegation down to this one file and hand it to
-      // the platform editor. Nothing new is minted — we already hold the directory, and
-      // `edit-file` is one hop further along a chain §5.7.1 bounds at depth 4. The host
-      // resolves the cap against OUR grants, so this can only ever narrow.
+      // Dispatch, read-only delegation: ask the workbench to open the entry's source
+      // under the reader's authority (R3-876 / APP_CUSTOMIZATION §5a). Our chroot is
+      // never upgraded and nothing is minted for us; the host needs a real gesture,
+      // which this click is. `cancelled` stays silent; `read-only` hides the
+      // affordance until the next mount announcement; anything else renders in place
+      // as text (the `refused` flag) — and is never retried through `edit-file`.
+      if (target.via === 'workbench') {
+        requestEdit({ bundleFile: target.relPath })
+          .catch((e: unknown) => {
+            const code = (e as { code?: string } | null)?.code;
+            if (code === 'cancelled') return;
+            if (code === 'read-only') {
+              setReaderReadOnly(true);
+              return;
+            }
+            setRefused(true);
+          })
+          .finally(done);
+        return;
+      }
+      // Dispatch, writable delegation: attenuate the corpus delegation down to this
+      // one file and hand it to the platform editor. Nothing new is minted — we
+      // already hold the directory, and `edit-file` is one hop further along a chain
+      // §5.7.1 bounds at depth 4. The host resolves the cap against our grants, so
+      // this can only ever narrow.
       invokeTask('edit-file', {
         file: capFile({ mountId: target.mountId, relPath: target.relPath }, { mode: 'rw' }),
       })

package/src/lib/editTarget.test.ts

@@ -4,21 +4,29 @@
 // viewer must send its edit to the CORPUS (never to Grove's own repo), and whether it may
 // offer one at all must be the corpus mount's CURRENT mode rather than a property of the
 // packaging or a flag latched at boot.
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, afterEach } from 'vitest';
 import { corpusWritable, editTarget, keyToSelfPath } from './editTarget';
 import type { CorpusIdentity } from './editTarget';
 import type { SandboxMount } from '@immediately-run/sdk/mounts';
-
-const fork: CorpusIdentity = {
-  dispatched: false,
-  contentRoot: '/app/content/',
-  mountId: null,
+import { getContentRoot, getCorpusMountId, isDispatched, resetContentRoot, setContentRoot } from './contentRoot';
+
+// The corpus identities come from the real producer (R3-877 round 1, R2): the
+// trailing-slash normalization every `slice` in editTarget depends on lives in
+// `setContentRoot` — a hand-typed literal would keep passing while it broke.
+const forkFor = (): CorpusIdentity => {
+  resetContentRoot();
+  return { dispatched: isDispatched(), contentRoot: getContentRoot(), mountId: getCorpusMountId() };
 };
-const dispatched: CorpusIdentity = {
-  dispatched: true,
-  contentRoot: '/task/t1/dir/',
-  mountId: '/task/t1/dir',
+const dispatchedFor = (): CorpusIdentity => {
+  setContentRoot('/task/t1/dir', { mountId: '/task/t1/dir' });
+  return { dispatched: isDispatched(), contentRoot: getContentRoot(), mountId: getCorpusMountId() };
 };
+afterEach(() => resetContentRoot());
+
+const fork: CorpusIdentity = forkFor();
+const dispatched: CorpusIdentity = dispatchedFor();
+// The dispatched entry keys, built off the producer's root — never a hand-typed prefix.
+const IN = (rel: string) => `${dispatched.contentRoot}${rel}`;
 
 const mount = (over: Partial<SandboxMount> = {}): SandboxMount =>
   ({ type: 'firestore', path: '/task/t1/dir', id: '/task/t1/dir', mode: 'rw', ...over }) as SandboxMount;
@@ -32,7 +40,7 @@ describe('editTarget — the verb follows the authority, not the packaging', ()
   });
 
   it('a DISPATCHED viewer delegates the CORPUS file, never a path in its own repo', () => {
-    expect(editTarget('/task/t1/dir/plot/the-rail.mdx', dispatched)).toEqual({
+    expect(editTarget(IN('plot/the-rail.mdx'), dispatched)).toEqual({
       via: 'delegate',
       mountId: '/task/t1/dir',
       relPath: 'plot/the-rail.mdx',
@@ -40,7 +48,7 @@ describe('editTarget — the verb follows the authority, not the packaging', ()
   });
 
   it('is corpus-relative under dispatch — the mount root IS the corpus root', () => {
-    const t = editTarget('/task/t1/dir/home.mdx', dispatched);
+    const t = editTarget(IN('home.mdx'), dispatched);
     expect(t).toMatchObject({ relPath: 'home.mdx' });
     // The fork's `content/` segment must NOT leak into a corpus-relative path: the
     // delegated chroot is minted AT the content directory.
@@ -52,11 +60,11 @@ describe('editTarget — the verb follows the authority, not the packaging', ()
   });
 
   it('offers nothing when a dispatched corpus has no mount id to delegate from', () => {
-    expect(editTarget('/task/t1/dir/home.mdx', { ...dispatched, mountId: null })).toBeNull();
+    expect(editTarget(IN('home.mdx'), { ...dispatched, mountId: null })).toBeNull();
   });
 
   it('offers nothing for the corpus root itself (a directory is not an entry)', () => {
-    expect(editTarget('/task/t1/dir/', dispatched)).toBeNull();
+    expect(editTarget(IN(''), dispatched)).toBeNull();
   });
 
   it('never throws on a junk key', () => {
@@ -81,13 +89,19 @@ describe('corpusWritable — the mount decides, live', () => {
     expect(corpusWritable([mount()], dispatched)).toBe(true);
   });
 
-  it('a ro corpus is not writable, so the affordance is hidden rather than EROFS-ing', () => {
-    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+  it('a ro corpus with no hint is still offerable (R3-877: the workbench class) — never EROFS, a refusal tells', () => {
+    // Pre-R3-877 this was `false` — an ro mount hid the affordance outright. The
+    // workbench class edits under the reader's authority, so our ro mount is the
+    // normal case, not a refusal. An explicit `false` hint still hides it (below).
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(true);
   });
 
-  it('follows a LIVE downgrade: the same mount re-announced ro flips the answer', () => {
+  it('follows a live downgrade: re-announced ro flips the delivery, and a false hint flips the offer', () => {
     expect(corpusWritable([mount({ mode: 'rw' })], dispatched)).toBe(true);
-    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+    // ro with no hint: still offerable, now via the workbench (reader's authority).
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(true);
+    // ro with the host saying the reader cannot edit: hidden.
+    expect(corpusWritable([mount({ mode: 'ro', readerCanEdit: false })], dispatched)).toBe(false);
   });
 
   it('a corpus mount that has vanished is not writable', () => {
@@ -106,3 +120,49 @@ describe('corpusWritable — the mount decides, live', () => {
     expect(corpusWritable([mount()], { ...dispatched, mountId: null })).toBe(false);
   });
 });
+
+// R3-877 — the third outcome: an ro delegation edits via the workbench, under the
+// reader's authority (`requestEdit({ bundleFile })`, R3-876). Order of preference:
+// self → delegate (rw) → workbench (ro).
+describe('editTarget — the workbench class for a read-only delegation (R3-877)', () => {
+  // The corpus identity's contentRoot mirrors the real getContentRoot() shape: the
+  // delegated chroot root, trailing slash.
+  const roCorpus: CorpusIdentity = { ...dispatched, mountMode: 'ro' };
+
+  it('an `ro` dispatched corpus yields workbench with the leading-slash bundle-relative path', () => {
+    expect(editTarget(IN('plot/the-rail.mdx'), roCorpus)).toEqual({
+      via: 'workbench',
+      relPath: '/plot/the-rail.mdx',
+    });
+  });
+
+  it('an `rw` delegation still yields delegate (the edit-file overlay is unchanged)', () => {
+    expect(editTarget(IN('plot/the-rail.mdx'), { ...dispatched, mountMode: 'rw' })).toEqual({
+      via: 'delegate',
+      mountId: '/task/t1/dir',
+      relPath: 'plot/the-rail.mdx',
+    });
+  });
+
+  it('an UNKNOWN mode (an older host announces none) keeps the pre-R3-877 delegate behavior', () => {
+    expect(editTarget(IN('home.mdx'), dispatched)).toEqual({
+      via: 'delegate',
+      mountId: '/task/t1/dir',
+      relPath: 'home.mdx',
+    });
+  });
+
+  it('the corpus root itself is still nothing to edit, workbench included', () => {
+    expect(editTarget(IN(''), roCorpus)).toBeNull();
+  });
+});
+
+describe('corpusWritable — the ro delegation is offerable on the hint (R3-877)', () => {
+  it('ro + readerCanEdit true → offered', () => {
+    expect(corpusWritable([mount({ mode: 'ro', readerCanEdit: true })], dispatched)).toBe(true);
+  });
+
+  it('ro + readerCanEdit false → not offered (never show a control that refuses)', () => {
+    expect(corpusWritable([mount({ mode: 'ro', readerCanEdit: false })], dispatched)).toBe(false);
+  });
+});

package/src/lib/editTarget.ts

@@ -20,8 +20,11 @@
 //
 // **The mount decides.** Writability is a property of the delegation's current mode, not
 // of how the app was loaded. That is why `corpusWritable` takes the live mount list rather
-// than the boot-time flag: a role downgrade re-announces the mount `ro`, and the
-// affordance must disappear rather than surface `EROFS` when clicked.
+// than the boot-time flag. Since R3-877 a role downgrade no longer hides the affordance —
+// it reroutes the delivery: `rw` hands the file to the `edit-file` overlay, `ro` asks the
+// workbench under the reader's authority (`requestEdit({ bundleFile })`). The offer hides
+// only when the host's `readerCanEdit` hint says the reader cannot edit, or a `read-only`
+// refusal proved it.
 //
 // Pure — no SDK, no React — so all of the above is testable without a host.
 
@@ -31,8 +34,14 @@ import type { SandboxMount } from '@immediately-run/sdk/mounts';
 export type EditTarget =
   /** The fork: our own repo, via the self-scoped present→edit transition. */
   | { via: 'self'; path: string }
-  /** Dispatch: one file of the delegated corpus, handed to the platform editor. */
-  | { via: 'delegate'; mountId: string; relPath: string };
+  /** Dispatch, writable delegation: one file of the corpus, handed to the platform
+   *  editor as a narrowed `edit-file` delegation (the overlay). */
+  | { via: 'delegate'; mountId: string; relPath: string }
+  /** Dispatch, read-only delegation (an app-declared opener's chroot): ask the
+   *  workbench to open the entry's source in the main-pane editor under the
+   *  reader's authority — `requestEdit({ bundleFile })` (R3-876 / APP_CUSTOMIZATION
+   *  §5a). The path is bundle-relative with a leading slash. */
+  | { via: 'workbench'; relPath: string };
 
 export interface CorpusIdentity {
   /** Whether the corpus is a mount rather than this app's own repo. */
@@ -41,6 +50,11 @@ export interface CorpusIdentity {
   contentRoot: string;
   /** The corpus mount id, when dispatched (`getCorpusMountId()`). */
   mountId: string | null;
+  /** The corpus delegation's current mode, read off the live mount list (R3-877):
+   *  `ro` routes the edit to the workbench under the reader's authority; `rw` keeps
+   *  the `edit-file` overlay. Absent/unknown keeps the pre-R3-877 behavior
+   *  (`delegate` — an `rw`-assuming host that announces no mode). */
+  mountMode?: 'ro' | 'rw' | null;
 }
 
 /** `/app/content/x.mdx` → `content/x.mdx` — the fork's repo-relative path. */
@@ -62,17 +76,25 @@ export function editTarget(entryKey: string, corpus: CorpusIdentity): EditTarget
   if (!corpus.mountId) return null;
   if (!entryKey.startsWith(corpus.contentRoot)) return null;
   const relPath = entryKey.slice(corpus.contentRoot.length);
-  return relPath ? { via: 'delegate', mountId: corpus.mountId, relPath } : null;
+  if (!relPath) return null;
+  // An `ro` delegation (the opener's chroot — the only mode an app-declared opener
+  // ever holds) goes to the workbench: the reader's authority, not ours — the mount
+  // is never upgraded and nothing is minted for us. Leading-slash, the host's
+  // `bundleFile` grammar.
+  if (corpus.mountMode === 'ro') return { via: 'workbench', relPath: `/${relPath}` };
+  return { via: 'delegate', mountId: corpus.mountId, relPath };
 }
 
 /**
  * May this instance offer an edit at all, given the mounts it holds RIGHT NOW?
  *
  * A fork asks about its working tree, as before. A dispatched viewer asks about the corpus
- * mount — and asks the LIVE mount list, not the boot-time flag, so a live `rw → ro`
- * downgrade (a role change the host re-announces on the same mount id) hides the
- * affordance on the next render. That is the whole difference between "hidden because you
- * may not" and "shown, then `EROFS` when you try".
+ * mount — and asks the live mount list, not the boot-time flag, so a live `rw → ro`
+ * downgrade (a role change the host re-announces on the same mount id) reroutes the
+ * delivery on the next render (to the workbench class) and an explicit
+ * `readerCanEdit: false` hides the offer — rather than surfacing `EROFS` on click.
+ * That is the whole difference between "hidden because you may not" and "shown, then
+ * `EROFS` when you try".
  *
  * A corpus mount that has vanished from the list answers `false`: no mount, no write.
  */
@@ -89,5 +111,12 @@ export function corpusWritable(
   // `mode` is absent on the primary repo mount and rw by default elsewhere; a corpus
   // mount that reports nothing is treated as writable exactly as `resolveOpenWiki` reads
   // it, so the two never disagree about the same mount.
-  return !!mount && mount.mode !== 'ro';
+  if (!mount) return false;
+  if (mount.mode !== 'ro') return true;
+  // R3-877 (APP_CUSTOMIZATION §5a.5): an `ro` delegation can still offer the
+  // workbench edit — the reader's authority — gated on the host's advisory
+  // `readerCanEdit` hint: offer when it is true, OR when the host sent no hint
+  // (absent = unknown — the refusal would tell, and `read-only` hides it after).
+  // Never offer on an explicit `false`.
+  return mount.readerCanEdit !== false;
 }

package/src/lib/tagCloud.test.ts

@@ -0,0 +1,115 @@
+// countTags / tagWeight / topTags — the pure half of TagCloud. The counting case
+// runs over the repo's REAL content tree, parsed with the real frontmatter parser,
+// so a drifted fixture cannot agree with the code by accident (ways_of_working §4).
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { parseFrontmatter } from './frontmatter';
+import { countTags, tagWeight, topTags, type TagCount } from './tagCloud';
+
+const CONTENT_ROOT = '/app/content/';
+
+/** Every .mdx under the repo's content/ as a metadata map keyed the way the
+ *  store keys it (absolute module path under the app root). */
+const realCorpusMetadata = (): Record<string, { tags?: unknown }> => {
+  const dir = join(process.cwd(), 'content');
+  const walk = (d: string): string[] =>
+    readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+      e.isDirectory() ? walk(join(d, e.name)) : e.name.endsWith('.mdx') ? [join(d, e.name)] : [],
+    );
+  const files: Record<string, { tags?: unknown }> = {};
+  for (const abs of walk(dir)) {
+    const { data } = parseFrontmatter(readFileSync(abs, 'utf8'));
+    files[CONTENT_ROOT + abs.slice(dir.length + 1)] = { tags: (data as { tags?: unknown }).tags };
+  }
+  return files;
+};
+
+/** The same count, computed independently in the test from the same parsed map. */
+const expectCounts = (files: Record<string, { tags?: unknown }>): TagCount[] => {
+  const counts = new Map<string, number>();
+  for (const [p, m] of Object.entries(files)) {
+    if (!p.startsWith(CONTENT_ROOT)) continue;
+    for (const t of Array.isArray(m.tags) ? (m.tags as string[]) : []) {
+      if (t.startsWith('ui/')) continue;
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+  }
+  return [...counts.keys()].sort().map((tag) => ({ tag, count: counts.get(tag)! }));
+};
+
+describe('countTags', () => {
+  it('over the real corpus, equals the independent count and carries no ui/ tag', () => {
+    const files = realCorpusMetadata();
+    expect(Object.keys(files).length).toBeGreaterThan(0);
+    const result = countTags(files, CONTENT_ROOT);
+    expect(result).toEqual(expectCounts(files));
+    expect(result.some(({ tag }) => tag.startsWith('ui/'))).toBe(false);
+  });
+
+  it('ignores entries outside the content root and non-array tags', () => {
+    const result = countTags(
+      {
+        '/app/content/a.mdx': { tags: ['x'] },
+        '/other/b.mdx': { tags: ['x'] },
+        '/app/content/c.mdx': { tags: 'x' },
+        '/app/content/d.mdx': null,
+      },
+      CONTENT_ROOT,
+    );
+    expect(result).toEqual([{ tag: 'x', count: 1 }]);
+  });
+});
+
+describe('tagWeight', () => {
+  it('gives the minimum 0 and the maximum 1', () => {
+    expect(tagWeight(1, 1, 191)).toBe(0);
+    expect(tagWeight(191, 1, 191)).toBe(1);
+  });
+
+  it('is strictly increasing over the real corpus spread (1, 15, 191)', () => {
+    const w = [1, 15, 191].map((c) => tagWeight(c, 1, 191));
+    expect(w[0]!).toBeLessThan(w[1]!);
+    expect(w[1]!).toBeLessThan(w[2]!);
+    // Logarithmic: a tag 15x the minimum sits well under the arithmetic midpoint.
+    expect(w[1]!).toBeLessThan(0.6);
+  });
+
+  it('clamps a count beyond the range', () => {
+    expect(tagWeight(10_000, 1, 191)).toBe(1);
+  });
+
+  it('returns 0 when there is no spread (one tag, or all equal)', () => {
+    expect(tagWeight(7, 7, 7)).toBe(0);
+  });
+
+  it('returns 0 for a count below 1 or a non-finite count', () => {
+    expect(tagWeight(0, 1, 10)).toBe(0);
+    expect(tagWeight(Number.NaN, 1, 10)).toBe(0);
+  });
+});
+
+describe('topTags', () => {
+  const five: TagCount[] = [
+    { tag: 'alpha', count: 3 },
+    { tag: 'beta', count: 9 },
+    { tag: 'gamma', count: 12 },
+    { tag: 'delta', count: 12 },
+    { tag: 'epsilon', count: 1 },
+  ];
+
+  it('keeps the N highest counts and returns them in tag order', () => {
+    expect(topTags(five, 2).map((t) => t.tag)).toEqual(['delta', 'gamma']);
+  });
+
+  it('breaks a tie at the cut by tag name', () => {
+    // beta(9) and a tie between gamma/delta(12): limit 2 takes delta+gamma; a
+    // tie AT the cut (limit 3 leaves beta out) — add a second 9 to force it.
+    const withTie: TagCount[] = [...five.slice(0, 2), { tag: 'zed', count: 9 }, ...five.slice(2)];
+    expect(topTags(withTie, 3).map((t) => t.tag)).toEqual(['beta', 'delta', 'gamma']);
+  });
+
+  it('returns the input when no limit is given', () => {
+    expect(topTags(five)).toBe(five);
+  });
+});

package/src/lib/tagCloud.ts

@@ -0,0 +1,58 @@
+// TagCloud's counting and scaling, extracted from the component so the cases are
+// unit-testable (the component is a thin wiring shell). The chip's pixel range is
+// NOT here — it lives in GroveApp.css, and the component only hands each chip a
+// 0..1 weight via `--tag-weight`.
+
+/** One tag and how many content entries carry it. */
+export interface TagCount {
+  tag: string;
+  count: number;
+}
+
+interface TaggedMeta {
+  tags?: unknown;
+}
+
+/** Every tag across the corpus with its count, sorted by tag. Only entries under
+ *  the content root count; `ui/` tags are chrome (they drive layout, not
+ *  classification) and are skipped. */
+export function countTags(filesMetadata: Record<string, TaggedMeta | null>, contentRoot: string): TagCount[] {
+  const counts: Record<string, number> = {};
+  Object.entries(filesMetadata).forEach(([p, m]) => {
+    if (!p.startsWith(contentRoot)) return;
+    if (m && Array.isArray(m.tags)) {
+      (m.tags as string[]).forEach((t) => {
+        if (t.startsWith('ui/')) return;
+        counts[t] = (counts[t] || 0) + 1;
+      });
+    }
+  });
+  return Object.keys(counts)
+    .sort()
+    .map((tag) => ({ tag, count: counts[tag]! }));
+}
+
+/** A tag's weight in the closed range 0..1: logarithmic and relative to THIS
+ *  corpus's own minimum and maximum, so the scale holds at 10 entries and at
+ *  10,000 — the least-used tag renders 0, the most-used 1, and a tag used ten
+ *  times as often is visibly but not ten times larger. No spread (`max === min`)
+ *  returns 0, so a uniform corpus renders plain chips; a count below 1 or a
+ *  non-finite count returns 0. */
+export function tagWeight(count: number, min: number, max: number): number {
+  if (!Number.isFinite(count) || count < 1) return 0;
+  if (max <= min) return 0;
+  const w = (Math.log(count) - Math.log(min)) / (Math.log(max) - Math.log(min));
+  return Math.min(1, Math.max(0, w));
+}
+
+/** The `limit` most-used tags, ties at the cut broken by tag name, re-sorted by
+ *  tag for display (the cloud reads alphabetically). An absent limit returns the
+ *  input unchanged — validating a bad limit is the component's job (it warns). */
+export function topTags(entries: TagCount[], limit?: number): TagCount[] {
+  if (limit === undefined) return entries;
+  return entries
+    .slice()
+    .sort((a, b) => b.count - a.count || (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0))
+    .slice(0, limit)
+    .sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0));
+}