@immediately-run/grove 0.2.2 → 0.2.3

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.2)
+> 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.3)
 
 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.2",
+  "version": "0.2.3",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {
@@ -17,6 +17,12 @@
         "version": "^1"
       }
     ],
+    "opens": [
+      {
+        "app": "self",
+        "version": "^1"
+      }
+    ],
     "requests": {
       "task:invoke": {},
       "llm:chat": {}

package/src/App.tsx

@@ -107,7 +107,7 @@ export default function App() {
   // hackability). §2's "single-map merge, never provider nesting" was written against
   // patching a provider in AFTER a partial render; nesting it INSIDE the gate above is
   // that same merge, composed before anything paints.
-  const wiki = <GroveWiki readOnly={boot.readOnly} rejectedComponents={contentComponents.rejected} />;
+  const wiki = <GroveWiki rejectedComponents={contentComponents.rejected} />;
   const withComponents =
     contentComponents.status === 'ready' && Object.keys(contentComponents.components).length > 0 ? (
       <MDXProvider components={contentComponents.components}>{wiki}</MDXProvider>

package/src/GroveWiki.tsx

@@ -80,10 +80,8 @@ function bundleHref(bundlePath: string): string {
  * (R3-169: under dispatch the root is a runtime value, not `/app/content/`).
  */
 export default function GroveWiki({
-  readOnly = false,
   rejectedComponents = [],
 }: {
-  readOnly?: boolean;
   /** Corpus component declarations that could not be loaded (R3-174). Shown, not
    *  swallowed: a `<RoadmapBoard/>` that silently never appears is indistinguishable from
    *  one nobody wrote, and the author has no other channel to learn which it was. */
@@ -166,7 +164,7 @@ export default function GroveWiki({
   // `lib/editTarget` — and the gate is the corpus mount's CURRENT mode, re-read on every
   // mount change so a live role downgrade hides the affordance instead of producing
   // `EROFS` on click.
-  const { writable, busy: editBusy, refused: editRefused, openEditor, editHint } = useEditAffordance(readOnly);
+  const { writable, busy: editBusy, refused: editRefused, openEditor, editHint } = useEditAffordance();
 
   const routeKey = sandboxPathToKey(sandboxPath) || homeKey();
   // The site brand is a wiki-wide constant, so read it from the home entry's

package/src/components/EntryBody.tsx

@@ -126,7 +126,7 @@ export default function EntryBody({ entryKey }: { entryKey: string }) {
  *  from the live mount set (the hook only runs on this path — no double
  *  subscription on the stock page). */
 function StandaloneHeader({ entryKey, mins }: { entryKey: string; mins: number }) {
-  const local = useEditAffordance(false);
+  const local = useEditAffordance();
   return (
     <EntryHeader
       entryKey={entryKey}

package/src/components/GroveAgent.test.tsx

@@ -288,7 +288,7 @@ describe('R3-608 — the composer stops the run; a refusal surfaces, a cancel do
     const { useEditAffordance } = await import('../hooks/useEditAffordance');
     const refusedStates: boolean[] = [];
     function Probe() {
-      const aff = useEditAffordance(false);
+      const aff = useEditAffordance();
       refusedStates.push(aff.refused);
       return (
         <div>

package/src/hooks/useEditAffordance.test.tsx

@@ -3,36 +3,51 @@
 // 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 { 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';
+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', () => ({
+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) }),
+  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 };
+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);
+  const affordance = useEditAffordance();
   useEffect(() => {
     latest = affordance;
   });
@@ -43,12 +58,12 @@ let container: HTMLDivElement;
 let root: Root;
 
 beforeEach(() => {
-  setContentRoot('/task/t1/dir', { mountId: '/task/t1/dir' });
+  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');
+  container = document.createElement("div");
   document.body.appendChild(container);
   root = createRoot(container);
   act(() => root.render(<Probe />));
@@ -69,23 +84,42 @@ const open = async (key = `${getContentRoot()}plot/the-rail.mdx`) => {
   rerender();
 };
 
-describe('useEditAffordance — the workbench delivery (R3-877)', () => {
-  it('an ro delegation offers Edit and delivers it as requestEdit({ bundleFile })', async () => {
+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(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', () => {
+  it("the ro corpus latch (the boot path of every opener delegation) does not hide the offer — R3-878 regression", async () => {
+    // The bug the venue leg caught: the boot latches the corpus's `ro` mode as the
+    // contentRoot readOnly flag, and the pre-fix hook gated `writable` on it — so an
+    // app-declared opener's chroot (always `ro`, APP_CUSTOMIZATION §5a) never showed
+    // the pencil, although the reader's authority may well edit the source.
+    resetContentRoot();
+    setContentRoot("/task/t1/dir", { readOnly: true, mountId: "/task/t1/dir" });
+    rerender();
+    expect(latest!.writable).toBe(true);
+    await open();
+    expect(requestEditMock).toHaveBeenCalledWith({
+      bundleFile: "/plot/the-rail.mdx",
+    });
+  });
+
+  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' }));
+  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…
@@ -94,15 +128,19 @@ describe('useEditAffordance — the workbench delivery (R3-877)', () => {
     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' }));
+  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' }));
+  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

@@ -13,10 +13,19 @@
 // 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';
-import { getContentRoot, getCorpusMountId, isDispatched } from '../lib/contentRoot';
-import { corpusWritable, editTarget } from '../lib/editTarget';
+import { useCallback, useMemo, useState } from "react";
+import {
+  capFile,
+  invokeTask,
+  requestEdit,
+  useMounts,
+} from "@immediately-run/sdk";
+import {
+  getContentRoot,
+  getCorpusMountId,
+  isDispatched,
+} from "../lib/contentRoot";
+import { corpusWritable, editTarget } from "../lib/editTarget";
 
 export interface EditAffordance {
   /** Whether to render an edit affordance at all — the MOUNT's answer, live. */
@@ -41,7 +50,7 @@ export interface EditAffordance {
   editHint: string;
 }
 
-export function useEditAffordance(readOnly: boolean): EditAffordance {
+export function useEditAffordance(): EditAffordance {
   const mounts = useMounts();
   const [busy, setBusy] = useState(false);
   const [refused, setRefused] = useState(false);
@@ -54,7 +63,12 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
   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 };
+    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
@@ -69,12 +83,18 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
     setReaderReadOnly(false);
   }
 
-  const writable = !readOnly && !readerReadOnly && corpusWritable(mounts, corpus);
+  // No `readOnly` veto here (there was one until R3-878's live leg): the boot-time
+  // read-only latch is the corpus delegation's `ro` mode, so gating on it hid the
+  // affordance in exactly the one case the workbench delivery exists for — an
+  // app-declared opener's chroot is always `ro` (APP_CUSTOMIZATION §5a). The live
+  // mount list already answers writability (`corpusWritable`), re-read on every
+  // announcement, and a `read-only` refusal latches the offer off above.
+  const writable = !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.
   const refusedUnlessCancelled = (e: unknown): undefined => {
-    if ((e as { code?: string } | null)?.code !== 'cancelled') setRefused(true);
+    if ((e as { code?: string } | null)?.code !== "cancelled") setRefused(true);
     return undefined;
   };
 
@@ -85,10 +105,12 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
       setBusy(true);
       setRefused(false);
       const done = () => setBusy(false);
-      if (target.via === 'self') {
+      if (target.via === "self") {
         // The fork: the present→edit transition on our own source. Self-scoped by
         // contract, which is exactly right when the corpus IS our repo.
-        requestEdit({ path: target.path }).catch(refusedUnlessCancelled).finally(done);
+        requestEdit({ path: target.path })
+          .catch(refusedUnlessCancelled)
+          .finally(done);
         return;
       }
       // Dispatch, read-only delegation: ask the workbench to open the entry's source
@@ -97,12 +119,12 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
       // 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') {
+      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') {
+            if (code === "cancelled") return;
+            if (code === "read-only") {
               setReaderReadOnly(true);
               return;
             }
@@ -116,8 +138,11 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
       // 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' }),
+      invokeTask("edit-file", {
+        file: capFile(
+          { mountId: target.mountId, relPath: target.relPath },
+          { mode: "rw" },
+        ),
       })
         .catch(refusedUnlessCancelled) // `cancelled` is how a reader closes the editor
         .finally(done);
@@ -126,8 +151,8 @@ export function useEditAffordance(readOnly: boolean): EditAffordance {
   );
 
   const editHint = corpus.dispatched
-    ? 'Edits save to the mounted content, and can be proposed back to its repository as a PR.'
-    : 'Edit this entry';
+    ? "Edits save to the mounted content, and can be proposed back to its repository as a PR."
+    : "Edit this entry";
 
   return { writable, busy, refused, openEditor, editHint };
 }