@immediately-run/grove 0.1.1 → 0.1.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.1.1)
+> 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.1.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
@@ -94,6 +94,7 @@ is one corpus's conventions (declared by that corpus, not this repo).
 ## Frontmatter keys the engine reads
 
 - `site`
+- `theme`
 - `layout`
 - `view`
 - `frame`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/grove",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "src/main.tsx",
   "immediately.run": {
@@ -10,7 +10,16 @@
         "task": "open-wiki",
         "version": "1.0"
       }
-    ]
+    ],
+    "invokes": [
+      {
+        "task": "edit-file",
+        "version": "^1"
+      }
+    ],
+    "requests": {
+      "task:invoke": {}
+    }
   },
   "scripts": {
     "dev": "vite",
@@ -18,7 +27,8 @@
     "lint": "eslint .",
     "test": "vitest run",
     "preview": "vite preview",
-    "verify": "npm run check:llms && npm run check:engine-api:selftest && npm run check:engine-api && npm run check:manifest && npm run check:deps && npm run lint && npm run build && npm run test",
+    "verify": "npm run check:llms && npm run check:engine-api:selftest && npm run check:engine-api && npm run check:manifest && npm run check:deps && npm run check:theme-contrast && npm run lint && npm run build && npm run test",
+    "check:theme-contrast": "node scripts/check-theme-contrast.mjs --self-test && node scripts/check-theme-contrast.mjs",
     "check:manifest": "node scripts/check-manifest.mjs",
     "check:deps": "node scripts/check-app-dependencies.mjs --self-test && node scripts/check-app-dependencies.mjs",
     "check:engine-api": "node scripts/check-engine-api.mjs",

package/src/GroveApp.css

@@ -67,6 +67,11 @@
 }
 
 /* —— alternate themes: identical DOM, CSS-only re-skin —— */
+/* R3-308: every theme ships BOTH polarities. The bare [data-grove-theme] block is
+   the theme's PREFERRED polarity (the one it opens in absent other opinions); the
+   paired block with an explicit [data-theme] is the other one. GroveWiki always
+   emits data-theme, so a wiki follows the reader or the host into either polarity
+   of ANY theme — alternates are no longer single-polarity by construction. */
 .grove-root[data-grove-theme="pixies"] {
   --bg: #0c0410;
   --panel: #1a0a1e;
@@ -88,6 +93,27 @@
   --radius-shape: 8px;
   --wash: radial-gradient(70% 55% at 85% -5%, rgba(255, 45, 142, .2), transparent 60%), radial-gradient(55% 45% at 4% 2%, rgba(157, 41, 255, .16), transparent 60%);
 }
+.grove-root[data-grove-theme="pixies"][data-theme="light"] {
+  --bg: #fdf6fb;
+  --panel: #ffffff;
+  --panel-2: #f9edf7;
+  --line: rgba(123, 47, 247, .18);
+  --line-2: rgba(123, 47, 247, .32);
+  --ink: #2c1030;
+  --ink-2: #6d3f76;
+  --ink-3: #7d5f84;
+  --accent: #d10f74;
+  --accent-2: #6b21c9;
+  --accent-3: #8a5a00;
+  --grad: linear-gradient(96deg, #ffe14d 0%, #ff2d8e 50%, #9d29ff 100%);
+  --glow: 0 0 0 1px rgba(209, 15, 116, .35), 0 8px 22px rgba(209, 15, 116, .18);
+  --accent-pink: #d10f74;
+  --accent-violet: #6b21c9;
+  --disp-weight: 900;
+  --prose-measure: 66ch;
+  --radius-shape: 8px;
+  --wash: radial-gradient(70% 55% at 85% -5%, rgba(209, 15, 116, .08), transparent 60%), radial-gradient(55% 45% at 4% 2%, rgba(107, 33, 201, .06), transparent 60%);
+}
 .grove-root[data-grove-theme="family"] {
   --bg: #faf6f1;
   --panel: #fffdfa;
@@ -95,7 +121,7 @@
   --line: rgba(120, 90, 60, .16);
   --line-2: rgba(120, 90, 60, .28);
   --ink: #3b342c;
-  --ink-2: #7c7062;
+  --ink-2: #6b5f51;
   --ink-3: #a89c8c;
   --accent: #c8744f;
   --accent-2: #9a8f5e;
@@ -109,6 +135,27 @@
   --radius-shape: 20px;
   --wash: radial-gradient(60% 50% at 82% -2%, rgba(224, 154, 106, .14), transparent 60%);
 }
+.grove-root[data-grove-theme="family"][data-theme="dark"] {
+  --bg: #241d16;
+  --panel: #2d251c;
+  --panel-2: #372c21;
+  --line: rgba(224, 154, 106, .16);
+  --line-2: rgba(224, 154, 106, .3);
+  --ink: #f2e9de;
+  --ink-2: #c9b8a5;
+  --ink-3: #a2937f;
+  --accent: #e09a6a;
+  --accent-2: #c8a06a;
+  --accent-3: #d9b98a;
+  --grad: linear-gradient(96deg, #f3cf9a 0%, #e09a6a 50%, #c8744f 100%);
+  --glow: 0 0 0 1px rgba(224, 154, 106, .4), 0 10px 26px rgba(224, 154, 106, .2);
+  --accent-pink: #e09a6a;
+  --accent-violet: #c8a06a;
+  --disp-weight: 700;
+  --prose-measure: 64ch;
+  --radius-shape: 20px;
+  --wash: radial-gradient(60% 50% at 82% -2%, rgba(224, 154, 106, .1), transparent 60%);
+}
 .grove-root[data-grove-theme="lotr"] {
   --bg: #ece2cc;
   --panel: #f4ebd6;
@@ -130,6 +177,27 @@
   --radius-shape: 4px;
   --wash: radial-gradient(70% 60% at 50% -5%, rgba(122, 90, 42, .1), transparent 65%);
 }
+.grove-root[data-grove-theme="lotr"][data-theme="dark"] {
+  --bg: #1d1810;
+  --panel: #262014;
+  --panel-2: #302818;
+  --line: rgba(184, 154, 86, .18);
+  --line-2: rgba(184, 154, 86, .32);
+  --ink: #ede2c8;
+  --ink-2: #c4b48e;
+  --ink-3: #9a8a6c;
+  --accent: #c9a45c;
+  --accent-2: #8aa468;
+  --accent-3: #b08a48;
+  --grad: linear-gradient(96deg, #b89a56 0%, #8a6a36 50%, #4a5a38 100%);
+  --glow: 0 0 0 1px rgba(201, 164, 92, .4), 0 8px 20px rgba(201, 164, 92, .22);
+  --accent-pink: #c9a45c;
+  --accent-violet: #8aa468;
+  --disp-weight: 700;
+  --prose-measure: 72ch;
+  --radius-shape: 4px;
+  --wash: radial-gradient(70% 60% at 50% -5%, rgba(201, 164, 92, .08), transparent 65%);
+}
 
 /* ============ SHELL ============ */
 .grove-root a {

package/src/GroveWiki.tsx

@@ -7,8 +7,8 @@ import {
   Include,
   useAllMetadata,
   useFileMetadata,
+  useHostTheme,
   useMetadataQuery,
-  useMounts,
 } from '@immediately-run/sdk';
 import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
 import { LinkSpaceContext } from '@immediately-run/sdk/linkSpace';
@@ -27,8 +27,11 @@ import { navQuery } from './lib/queries';
 import type { NavRecord } from './lib/queries';
 import { layoutChainForKey } from './lib/layout';
 import { folderIndexKey } from './lib/directory';
+import { resolvePalette, resolvePolarity, type Polarity } from './lib/themeSelection';
+import { preferredPolarity } from './data/themes';
 import { useDirectoryListing } from './hooks/useDirectoryListing';
-import { getContentRoot, isDispatched } from './lib/contentRoot';
+import { useEditAffordance } from './hooks/useEditAffordance';
+import { getContentRoot } from './lib/contentRoot';
 import type { RejectedComponent } from './lib/corpusComponents';
 import { GroveShellContext, OutletContext } from './lib/shell';
 import type { GroveShell, NavItem } from './lib/shell';
@@ -114,10 +117,44 @@ export default function GroveWiki({
 }) {
   const ctx = useContext(TinkerableContext) as any;
   const sandboxPath: string = ctx?.navigationState?.sandboxPath || '/';
-  const mounts = useMounts() as any[];
 
-  const [theme, setTheme] = useState(() => readPref('grove:theme') || 'default');
-  const [light, setLight] = useState(() => readPref('grove:appearance') === 'light');
+  // ── Theme selection (R3-308, 02-theme-contract §4) ─────────────────────────
+  //
+  // Two INDEPENDENT axes with three sources, resolved through ONE module
+  // (lib/themeSelection) so no surface re-derives the precedence:
+  //
+  //   palette  = reader override, else the author's `theme:` on the home entry, else default
+  //   polarity = reader override, else the host's theme, else the palette's preferred
+  //
+  // The stored prefs are OVERRIDES, nullable by nature: absent until the reader
+  // acts, which is what gives the author's declaration its turn. They are written
+  // by the user actions (chooseTheme/choosePolarity), NEVER by an effect on mount
+  // — the old effects promoted the initial value to a reader choice on first
+  // visit, which is exactly why a `theme:` declaration could never have won.
+  // (Visitors from before this change carry a mount-written pref; it stands —
+  // they are Grove readers, and a reader outranks an author.)
+  const [readerTheme, setReaderTheme] = useState<string | null>(() => readPref('grove:theme'));
+  const [readerAppearance, setReaderAppearance] = useState<Polarity | null>(() => {
+    const p = readPref('grove:appearance');
+    return p === 'light' || p === 'dark' ? p : null;
+  });
+  const chooseTheme = (id: string) => {
+    setReaderTheme(id);
+    writePref('grove:theme', id);
+  };
+  const choosePolarity = (wantLight: boolean) => {
+    const p: Polarity = wantLight ? 'light' : 'dark';
+    setReaderAppearance(p);
+    writePref('grove:appearance', p);
+  };
+  // The host drives POLARITY ONLY (`theme:read` is the one theme capability the
+  // open-wiki binding holds) — and only when there IS a host. `useHostTheme`'s
+  // channel reports an `initial: 'dark'` before any host speaks, so an unframed
+  // standalone `vite dev` render would otherwise carry a phantom host opinion
+  // and flip light-preferred themes. Framed === a host exists to have one.
+  const framed = typeof window !== 'undefined' && window.parent !== window;
+  const hostTheme = useHostTheme();
+  const hostPolarity: Polarity | null = framed ? hostTheme : null;
   const [menuOpen, setMenuOpen] = useState(false);
   const [searchOpen, setSearchOpen] = useState(false);
   const [drawerOpen, setDrawerOpen] = useState(false);
@@ -132,8 +169,6 @@ export default function GroveWiki({
     mq.addEventListener('change', on);
     return () => mq.removeEventListener('change', on);
   }, []);
-  useEffect(() => writePref('grove:theme', theme), [theme]);
-  useEffect(() => writePref('grove:appearance', light ? 'light' : 'dark'), [light]);
 
   // ⌘K / Ctrl-K opens search.
   useEffect(() => {
@@ -147,28 +182,37 @@ export default function GroveWiki({
     return () => window.removeEventListener('keydown', on);
   }, []);
 
-  // ⚠ TEMPORARY, and not a design: dispatched content IS writable — R3-266.
-  //
-  // The affordance below calls `requestEdit`, which is **self-scoped by contract** ("v1
-  // supports only a repo-relative path in the CURRENT repo … editing a file in one of your
-  // mounts is the `edit-file` task, not this"). Under dispatch the corpus is a mount, so
-  // that call would edit GROVE rather than the corpus on screen. Offering it would be
-  // wrong; withholding it *as a design* is also wrong, and this comment exists so the next
-  // reader does not conclude the second from the first.
+  // R3-266 — dispatched content IS writable, and the MOUNT decides.
   //
-  // The fix is a verb swap, not a withheld capability: delegate the entry to
-  // `invokeTask('edit-file', { file: capFile({ mountId, relPath }, { mode: 'rw' }) })`,
-  // declare `invokes: edit-file`, and gate on the CORPUS MOUNT's mode rather than on the
-  // packaging. A task callee already holds the minted delegated grant, so nothing new has
-  // to be minted. Tracked in R3-266; `docs/specs/REPO_CONTENT_DISPATCH_SPEC.mdx` §5.
-  const writable =
-    !isDispatched() && !readOnly && (mounts?.some((m) => m.type === 'worktree' && m.mode !== 'ro') ?? false);
+  // This used to read `!isDispatched() && …`, withholding every edit affordance from a
+  // dispatched viewer. The reason was real but the conclusion was not: `requestEdit` is
+  // **self-scoped by contract**, so under dispatch it names a path in GROVE's repo rather
+  // than in the corpus on screen. The fix is a verb swap, not a withheld capability — see
+  // `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, openEditor, editHint } = useEditAffordance(readOnly);
 
   const routeKey = sandboxPathToKey(sandboxPath) || homeKey();
   // The site brand is a wiki-wide constant, so read it from the home entry's
   // `site` frontmatter — not the current entry's (which only home would carry),
   // else the brand flips to the 'Grove' fallback on every sub-page.
   const homeMeta = useFileMetadata(homeKey()) as any;
+  // R3-308: the author's palette declaration — `theme:` on the home entry, the
+  // wiki-wide sibling of `site:`. Like `site`, it is read from HOME and not the
+  // current entry, so a sub-page never flips the wiki's look back to `default`.
+  const authorTheme: string | null =
+    typeof homeMeta?.theme === 'string' && homeMeta.theme ? homeMeta.theme : null;
+  // The two axes, resolved through the one module that owns the precedence. `theme`
+  // and `light` below are the RESOLVED values every surface renders from — the raw
+  // reader overrides live only in state and in the menu handlers.
+  const theme = resolvePalette({ reader: readerTheme, author: authorTheme });
+  const polarity: Polarity = resolvePolarity({
+    reader: readerAppearance,
+    host: hostPolarity,
+    preferred: preferredPolarity(theme),
+  });
+  const light = polarity === 'light';
   // Existence / 404: the whole index tells us if a followed link is dead. Layout
   // files are structure, not entries, so they're excluded here (and everywhere).
   const allKeysQuery = useCallback((fm: Record<string, any>) => Object.keys(fm).filter(isContentEntry), []);
@@ -257,9 +301,9 @@ export default function GroveWiki({
 
   const shell: GroveShell = {
     theme,
-    setTheme,
+    setTheme: chooseTheme,
     light,
-    setLight,
+    setLight: choosePolarity,
     menuOpen,
     setMenuOpen,
     searchOpen,
@@ -269,6 +313,9 @@ export default function GroveWiki({
     vw,
     navMode,
     writable,
+    openEditor,
+    editBusy,
+    editHint,
     siteTitle,
     safe,
     navItems,
@@ -336,7 +383,7 @@ export default function GroveWiki({
         data-vw={vw}
         data-nav={navMode}
         data-grove-theme={theme === 'default' ? undefined : theme}
-        data-theme={theme === 'default' && light ? 'light' : undefined}
+        data-theme={polarity}
       >
         <div className="device__scroll">
           {rejectedComponents.length > 0 ? (

package/src/components/EntryHeader.tsx

@@ -1,7 +1,6 @@
 /* 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 } from '../lib/shell';
 import { crumb } from '../lib/wiki';
 import Icon from './Icon';
 
@@ -17,17 +16,11 @@ export default function EntryHeader({
   writable: boolean;
   mins: number;
 }) {
+  const { openEditor, editBusy, 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}
@@ -40,9 +33,14 @@ 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}>
+          <button
+            className="grove-edit-affordance"
+            data-busy={editBusy ? '1' : '0'}
+            title={editHint}
+            onClick={() => openEditor(entryKey)}
+          >
             <Icon name="pencil" />
-            {busy ? 'Opening editor…' : 'Edit'}
+            {editBusy ? 'Opening editor…' : 'Edit'}
           </button>
         )}
       </div>

package/src/components/GroveAgent.tsx

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useEffect, useRef, useState } from 'react';
-import { chat, requestEdit, useChatProvider } from '@immediately-run/sdk';
-import { keyToRepoRel } from '../lib/content';
+import { chat, useChatProvider } from '@immediately-run/sdk';
+import { useShell } from '../lib/shell';
 import Icon from './Icon';
 
 interface Msg {
@@ -27,6 +27,7 @@ const CHIPS = [
 // banners rather than faking a host surface.
 export default function GroveAgent({ writable, entryKey, entryTitle }: { writable: boolean; entryKey: string; entryTitle: string }) {
   const provider = useChatProvider();
+  const { openEditor } = useShell();
   const [open, setOpen] = useState(false);
   const [detent, setDetent] = useState<'half' | 'full'>('half');
   const [resting, setResting] = useState('');
@@ -212,7 +213,7 @@ export default function GroveAgent({ writable, entryKey, entryTitle }: { writabl
                 <div className="ga-foot__hand">
                   <span>Grove's own agent · scoped to your grants</span>
                   <a
-                    onClick={() => requestEdit({ path: keyToRepoRel(entryKey) }).catch(() => undefined)}
+                    onClick={() => openEditor(entryKey)}
                     role="button"
                     tabIndex={0}
                   >

package/src/components/GroveNav.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+// The appearance control is offered for EVERY theme (R3-308) — the bug this pins
+// is "single-polarity by construction": the control used to render only when
+// `theme === 'default'`, which is precisely how the alternates stayed
+// light/dark-or-nothing. Rendered for a NON-default theme through the real
+// component, so the gate cannot quietly come back.
+import { describe, it, expect, vi } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { GroveShellContext, type GroveShell } from '../lib/shell';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+
+const { default: GroveNav } = await import('./GroveNav');
+
+// The SDK's <Link> resolves hrefs against the host navigation state; without a
+// provider `outerHref` is undefined and URL construction throws before any
+// assertion runs. A minimal provider stands in for the host, exactly as the
+// sandbox would supply it.
+const NAV = {
+  outerHref: 'https://example.immediately.run/app/x',
+  navigationState: { sandboxPath: '/app/x' },
+};
+
+const mount = async (shell: Partial<GroveShell>) => {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const full: GroveShell = {
+    theme: 'default',
+    setTheme: vi.fn(),
+    light: false,
+    setLight: vi.fn(),
+    menuOpen: false,
+    setMenuOpen: vi.fn(),
+    searchOpen: false,
+    setSearchOpen: vi.fn(),
+    drawerOpen: false,
+    setDrawerOpen: vi.fn(),
+    vw: 'desktop',
+    navMode: 'top',
+    writable: false,
+    openEditor: vi.fn(),
+    editBusy: false,
+    editHint: '',
+    siteTitle: 'Grove',
+    safe: false,
+    navItems: [{ key: 'a', href: '/a', label: 'A' }],
+    entryKey: '/a',
+    includePath: 'a.mdx',
+    layout: 'doc',
+    showRails: false,
+    mins: 0,
+    missing: false,
+    directory: { status: 'idle' },
+    ...shell,
+  } as unknown as GroveShell;
+  await act(async () => {
+    createRoot(host).render(
+      <TinkerableContext.Provider value={NAV as never}>
+        <GroveShellContext.Provider value={full}>
+          <GroveNav />
+        </GroveShellContext.Provider>
+      </TinkerableContext.Provider>,
+    );
+  });
+  return host;
+};
+
+describe('the theme menu (R3-308 — two independent axes)', () => {
+  it('offers the appearance control for a NON-default theme', async () => {
+    const host = await mount({ theme: 'pixies', menuOpen: true, light: false });
+    const seg = host.querySelector('.gtm__seg');
+    expect(seg).not.toBeNull();
+    expect(seg!.querySelectorAll('button')).toHaveLength(2);
+  });
+
+  it('marks the RESOLVED polarity, not only a reader override', async () => {
+    // `light` is the resolved value the shell hands down (lib/themeSelection) —
+    // the control must reflect whatever the resolution produced, including the
+    // host-driven or preferred cases where no reader override exists.
+    const host = await mount({ theme: 'family', menuOpen: true, light: true });
+    const on = [...host.querySelectorAll('.gtm__seg button')].find((b) => b.getAttribute('data-on') === '1');
+    expect(on?.textContent).toMatch(/Light/);
+  });
+
+  it('lists every catalogue theme — the menu is how a reader reaches them', async () => {
+    const host = await mount({ menuOpen: true });
+    expect(host.querySelectorAll('.gtm__row').length).toBeGreaterThan(1);
+  });
+});

package/src/components/GroveNav.tsx

@@ -1,5 +1,6 @@
-import { Link, requestEdit } from '@immediately-run/sdk';
+import { Link } from '@immediately-run/sdk';
 import { useShell } from '../lib/shell';
+import { getContentRoot } from '../lib/contentRoot';
 import { THEMES } from '../data/themes';
 import Icon from './Icon';
 
@@ -12,6 +13,7 @@ export default function GroveNav() {
     navItems,
     entryKey,
     writable,
+    openEditor,
     theme,
     setTheme,
     light,
@@ -26,7 +28,10 @@ export default function GroveNav() {
     const el = (document.querySelector('.ga-foot input') || document.querySelector('.ga-line input')) as HTMLElement | null;
     el?.focus();
   };
-  const newEntry = () => requestEdit({ path: 'content/untitled.mdx' }).catch(() => undefined);
+  // The new entry belongs to whichever corpus is mounted, so it is named from the
+  // content ROOT rather than the fork's `content/` literal — under dispatch the latter
+  // would create a file in Grove's own repo (R3-266).
+  const newEntry = () => openEditor(`${getContentRoot()}untitled.mdx`);
 
   return (
     <nav className="grove-nav">
@@ -79,19 +84,20 @@ export default function GroveNav() {
                     </button>
                   ))}
                 </div>
-                {theme === 'default' ? (
-                  <div className="gtm__appearance">
-                    <div className="gtm__sub">Appearance</div>
-                    <div className="gtm__seg">
-                      <button data-on={!light ? '1' : '0'} onClick={() => setLight(false)}>
-                        <Icon name="moon" /> Dark
-                      </button>
-                      <button data-on={light ? '1' : '0'} onClick={() => setLight(true)}>
-                        <Icon name="sun" /> Light
-                      </button>
-                    </div>
+                {/* R3-308: the appearance control is offered for EVERY theme — each
+                    catalogue entry ships both polarities, so gating it on
+                    `default` would be single-polarity by construction again. */}
+                <div className="gtm__appearance">
+                  <div className="gtm__sub">Appearance</div>
+                  <div className="gtm__seg">
+                    <button data-on={!light ? '1' : '0'} onClick={() => setLight(false)}>
+                      <Icon name="moon" /> Dark
+                    </button>
+                    <button data-on={light ? '1' : '0'} onClick={() => setLight(true)}>
+                      <Icon name="sun" /> Light
+                    </button>
                   </div>
-                ) : null}
+                </div>
               </div>
             </>
           ) : null}

package/src/components/PageView.tsx

@@ -3,7 +3,6 @@ import { Include, Link } from '@immediately-run/sdk';
 import { useShell } from '../lib/shell';
 import { keyToHref, keyToRepoRel } from '../lib/content';
 import { crumb } from '../lib/wiki';
-import { requestEdit } from '@immediately-run/sdk';
 import DirectoryView from './DirectoryView';
 import EntryHeader from './EntryHeader';
 import SafeEntryBody from './SafeEntryBody';
@@ -20,7 +19,8 @@ declare const module: any;
 // site chrome (nav / sidebar / footer) — that's the layout's job — so the page
 // stays free of shell concerns.
 export default function PageView() {
-  const { entryKey, includePath, layout, showRails, mins, missing, suggestion, writable, vw, safe, directory } = useShell();
+  const { entryKey, includePath, layout, showRails, mins, missing, suggestion, writable, openEditor, vw, safe, directory } =
+    useShell();
 
   // A folder URL. `checking` renders nothing rather than the 404: the readdir that
   // decides between them is one RPC away, and a 404 that appears and then turns into a
@@ -39,7 +39,7 @@ export default function PageView() {
         </p>
         <div className="grove-state__actions">
           <Link className="btn-ghost" href="/"><Icon name="chevron-right" /> Back to home</Link>
-          {writable ? <button className="btn-primary" onClick={() => requestEdit({ path: keyToRepoRel(entryKey) }).catch(() => undefined)}><Icon name="file-plus" /> Create it</button> : null}
+          {writable ? <button className="btn-primary" onClick={() => openEditor(entryKey)}><Icon name="file-plus" /> Create it</button> : null}
         </div>
       </div>
     );

package/src/data/themes.ts

@@ -1,14 +1,45 @@
 // The theme catalogue for the theme menu (id → label + swatch gradient). Data,
 // not components — kept out of the chrome components per the Fast-Refresh rule.
+//
+// R3-308: every theme declares BOTH polarities (its CSS block pair) and a
+// `preferred` one — the polarity a wiki opens in when neither the reader nor the
+// host has said otherwise (02-theme-contract §4). The catalogue ids must match
+// the `[data-grove-theme="…"]` selectors in GroveApp.css; the contrast check in
+// `scripts/check-theme-contrast.mjs` reads both and fails if they drift apart.
+import type { Polarity } from '../lib/themeSelection';
+
 export interface Theme {
   id: string;
   label: string;
   swatch: string;
+  /** The polarity this theme opens in absent a reader/host opinion. */
+  preferred: Polarity;
 }
 
 export const THEMES: Theme[] = [
-  { id: 'default', label: 'immediately.run', swatch: 'linear-gradient(96deg,#f6f1fb,#f49ad4 46%,#b285f2)' },
-  { id: 'pixies', label: 'Pixies', swatch: 'linear-gradient(96deg,#ffe14d,#ff2d8e 50%,#9d29ff)' },
-  { id: 'family', label: 'Family journal', swatch: 'linear-gradient(96deg,#f3cf9a,#e09a6a 50%,#c8744f)' },
-  { id: 'lotr', label: 'Middle-earth', swatch: 'linear-gradient(96deg,#b89a56,#8a6a36 50%,#4a5a38)' },
+  {
+    id: 'default',
+    label: 'immediately.run',
+    swatch: 'linear-gradient(96deg,#f6f1fb,#f49ad4 46%,#b285f2)',
+    preferred: 'dark',
+  },
+  { id: 'pixies', label: 'Pixies', swatch: 'linear-gradient(96deg,#ffe14d,#ff2d8e 50%,#9d29ff)', preferred: 'dark' },
+  {
+    id: 'family',
+    label: 'Family journal',
+    swatch: 'linear-gradient(96deg,#f3cf9a,#e09a6a 50%,#c8744f)',
+    preferred: 'light',
+  },
+  {
+    id: 'lotr',
+    label: 'Middle-earth',
+    swatch: 'linear-gradient(96deg,#b89a56,#8a6a36 50%,#4a5a38)',
+    preferred: 'light',
+  },
 ];
+
+/** The preferred polarity of a palette id — unknown ids fall back to dark, the
+ * long-standing Grove default, rather than throwing in a render path. */
+export function preferredPolarity(id: string): Polarity {
+  return THEMES.find((t) => t.id === id)?.preferred ?? 'dark';
+}

package/src/devfs.d.ts

@@ -1,4 +1,5 @@
-// Pull in the `fs` module types provided by @immediately-run/dev-fs, so app
-// code can `import fs from 'fs'` and type-check against the async-only surface
-// immediately.run exposes. See https://github.com/immediately-run/dev-fs
-/// <reference types="@immediately-run/dev-fs/fs" />
+// The ambient `fs` + `module` types the immediately.run SANDBOX provides to app
+// code — declared by the package that owns the surface: `@immediately-run/sdk`
+// (R3-276b moved them there from `@immediately-run/dev-fs`, whose job is the local
+// `vite dev` disk bridge, not the contract). One line, complete from sdk 0.49.0.
+/// <reference types="@immediately-run/sdk/ambient" />

package/src/hooks/useEditAffordance.ts

@@ -0,0 +1,86 @@
+// R3-266 — the one place Grove decides whether to offer an edit, and how to deliver it.
+//
+// Every edit affordance in the wiki (the entry header's pencil, the 404's "Create it",
+// the agent panel's link, the nav's "New entry") used to call `requestEdit` directly with
+// a repo-relative path. That is correct for a FORK and wrong under DISPATCH, where it
+// names a path in Grove's own repo rather than in the corpus on screen — so the affordance
+// 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
+// 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';
+
+export interface EditAffordance {
+  /** Whether to render an edit affordance at all — the MOUNT's answer, live. */
+  writable: boolean;
+  /** True while an editor is being summoned (for a busy label). */
+  busy: boolean;
+  /** Open `entryKey` in the platform editor. Never throws; a refusal is a no-op. */
+  openEditor: (entryKey: string) => void;
+  /**
+   * What a save actually does, so the affordance can say so.
+   *
+   * **A stated residual (2026-08-27, R3-266).** The CoW overlay and the contribute (PR)
+   * flow are anchored on the APP's repo. Under a fork the app and the corpus are one
+   * repo, so "save" and "propose a change" are one story. Under dispatch they are two:
+   * the write lands in the corpus mount correctly, and *"open a PR against the content
+   * repo"* has no wired target. That is real remaining work — and it is not a reason to
+   * withhold editing, because a viewer that saves but cannot yet propose is strictly
+   * better than one that refuses to save. It IS a reason not to imply otherwise, so the
+   * chrome labels the dispatched case for what it is.
+   */
+  editHint: string;
+}
+
+export function useEditAffordance(readOnly: boolean): EditAffordance {
+  const mounts = useMounts();
+  const [busy, setBusy] = useState(false);
+
+  // 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],
+  );
+
+  const writable = !readOnly && corpusWritable(mounts, corpus);
+
+  const openEditor = useCallback(
+    (entryKey: string) => {
+      const target = editTarget(entryKey, corpus);
+      if (!target) return;
+      setBusy(true);
+      const done = () => setBusy(false);
+      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(() => undefined).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.
+      invokeTask('edit-file', {
+        file: capFile({ mountId: target.mountId, relPath: target.relPath }, { mode: 'rw' }),
+      })
+        .catch(() => undefined) // `cancelled` is how a reader closes the editor
+        .finally(done);
+    },
+    [corpus],
+  );
+
+  const editHint = corpus.dispatched
+    ? 'Edits save to the mounted content. Proposing a change back to its repository is not wired yet.'
+    : 'Edit this entry';
+
+  return { writable, busy, openEditor, editHint };
+}

package/src/hooks/useOpenWikiBoot.ts

@@ -44,7 +44,7 @@ export function useOpenWikiBoot(): OpenWikiBoot {
     // effect would run AFTER the first content render, which is the whole failure this
     // gate exists to prevent. Idempotent and purely derived, so a StrictMode double
     // render sets the same value twice.
-    setContentRoot(resolution.root, { readOnly: resolution.readOnly });
+    setContentRoot(resolution.root, { readOnly: resolution.readOnly, mountId: resolution.mountId });
   }
 
   // The module IS the latch: once a root is set, the delegation is final for the life of

package/src/lib/contentRoot.ts

@@ -24,6 +24,7 @@ export const APP_CONTENT_ROOT = '/app/content/';
 
 let root: string = APP_CONTENT_ROOT;
 let readOnly = false;
+let mountId: string | null = null;
 
 /** Where this instance's corpus lives, with a trailing slash. Read at CALL time. */
 export function getContentRoot(): string {
@@ -35,10 +36,23 @@ export function getContentRoot(): string {
  * with the delegated directory, or not at all (the fork, which keeps the default).
  * Normalizes the trailing slash so every `startsWith`/`slice` in the helpers holds.
  */
-export function setContentRoot(dir: string, opts: { readOnly?: boolean } = {}): void {
+export function setContentRoot(dir: string, opts: { readOnly?: boolean; mountId?: string | null } = {}): void {
   if (!dir) return;
   root = dir.endsWith('/') ? dir : `${dir}/`;
   readOnly = opts.readOnly ?? false;
+  mountId = opts.mountId ?? null;
+}
+
+/**
+ * The mount id of the corpus, or null for a fork (whose corpus is its own repo, not a
+ * mount). R3-266: this is what an onward delegation NAMES — `capFile({ mountId, relPath })`
+ * — when Grove hands a content file to the platform editor. It lives here with the root
+ * for the same reason the read-only flag does: it is the same fact, decided once by the
+ * same delegation, and every consumer that asks "may I offer an edit, and of what?"
+ * already reads the root.
+ */
+export function getCorpusMountId(): string | null {
+  return mountId;
 }
 
 /** Whether the mounted corpus was delegated read-only. Lives here rather than in React
@@ -58,4 +72,5 @@ export function isDispatched(): boolean {
 export function resetContentRoot(): void {
   root = APP_CONTENT_ROOT;
   readOnly = false;
+  mountId = null;
 }

package/src/lib/editTarget.test.ts

@@ -0,0 +1,108 @@
+// R3-266 — dispatched content is writable, and the MOUNT decides.
+//
+// The two things these tests pin are the two things that were wrong before: a dispatched
+// 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 { 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,
+};
+const dispatched: CorpusIdentity = {
+  dispatched: true,
+  contentRoot: '/task/t1/dir/',
+  mountId: '/task/t1/dir',
+};
+
+const mount = (over: Partial<SandboxMount> = {}): SandboxMount =>
+  ({ type: 'firestore', path: '/task/t1/dir', id: '/task/t1/dir', mode: 'rw', ...over }) as SandboxMount;
+
+describe('editTarget — the verb follows the authority, not the packaging', () => {
+  it('a FORK edits its own source through the self-scoped present→edit transition', () => {
+    expect(editTarget('/app/content/handbook/onboarding.mdx', fork)).toEqual({
+      via: 'self',
+      path: 'content/handbook/onboarding.mdx',
+    });
+  });
+
+  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({
+      via: 'delegate',
+      mountId: '/task/t1/dir',
+      relPath: 'plot/the-rail.mdx',
+    });
+  });
+
+  it('is corpus-relative under dispatch — the mount root IS the corpus root', () => {
+    const t = editTarget('/task/t1/dir/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.
+    expect((t as { relPath: string }).relPath.startsWith('content/')).toBe(false);
+  });
+
+  it('offers nothing for a key outside the mounted corpus (a leftover from the viewer)', () => {
+    expect(editTarget('/app/content/home.mdx', dispatched)).toBeNull();
+  });
+
+  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();
+  });
+
+  it('offers nothing for the corpus root itself (a directory is not an entry)', () => {
+    expect(editTarget('/task/t1/dir/', dispatched)).toBeNull();
+  });
+
+  it('never throws on a junk key', () => {
+    expect(editTarget('', dispatched)).toBeNull();
+    expect(editTarget(undefined as unknown as string, fork)).toBeNull();
+  });
+
+  it('keyToSelfPath strips the app anchor exactly as the fork URLs require', () => {
+    expect(keyToSelfPath('/app/content/x.mdx')).toBe('content/x.mdx');
+    expect(keyToSelfPath('/content/x.mdx')).toBe('content/x.mdx');
+  });
+});
+
+describe('corpusWritable — the mount decides, live', () => {
+  it('a fork asks about its working tree, as before', () => {
+    expect(corpusWritable([{ type: 'worktree', path: '/app', mode: 'rw' } as SandboxMount], fork)).toBe(true);
+    expect(corpusWritable([{ type: 'worktree', path: '/app', mode: 'ro' } as SandboxMount], fork)).toBe(false);
+    expect(corpusWritable([], fork)).toBe(false);
+  });
+
+  it('a DISPATCHED viewer on an rw corpus is writable — packaging is not trust', () => {
+    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('follows a LIVE downgrade: the same mount re-announced ro flips the answer', () => {
+    expect(corpusWritable([mount({ mode: 'rw' })], dispatched)).toBe(true);
+    expect(corpusWritable([mount({ mode: 'ro' })], dispatched)).toBe(false);
+  });
+
+  it('a corpus mount that has vanished is not writable', () => {
+    expect(corpusWritable([mount({ id: 'space:other', path: '/mnt/x' })], dispatched)).toBe(false);
+    expect(corpusWritable([], dispatched)).toBe(false);
+    expect(corpusWritable(null, dispatched)).toBe(false);
+  });
+
+  it('matches a mount that carries no id by its path (what the host publishes)', () => {
+    expect(corpusWritable([{ type: 'firestore', path: '/task/t1/dir', mode: 'rw' } as SandboxMount], dispatched)).toBe(
+      true,
+    );
+  });
+
+  it('never reports writable when there is no mount id at all', () => {
+    expect(corpusWritable([mount()], { ...dispatched, mountId: null })).toBe(false);
+  });
+});

package/src/lib/editTarget.ts

@@ -0,0 +1,93 @@
+// R3-266 — WHERE an edit goes, and whether one may be offered at all.
+//
+// Grove ships in two packagings, and the edit verb differs between them because the
+// AUTHORITY does, not because dispatched content is somehow less editable:
+//
+//   • FORK      — the corpus is this app's own repo, so "edit this entry" is the
+//                 present→edit transition on our own source: `requestEdit({ path })`,
+//                 which is **self-scoped by contract** ("v1 supports only a repo-relative
+//                 path in the CURRENT repo").
+//   • DISPATCH  — the corpus is a MOUNT somebody handed us. `requestEdit` there would
+//                 name a path in GROVE's repo, so the same call would offer to edit the
+//                 viewer instead of the wiki on screen. The right verb is the one for a
+//                 file in a mount: `invokeTask('edit-file', { file: capFile(...) })`,
+//                 attenuating the corpus delegation down to the single entry.
+//
+// The previous code withheld the affordance under dispatch and said so in a comment that
+// was careful to call it temporary. It was still the wrong outcome: dispatch changes the
+// PACKAGING, not the authority — the same corpus, forked, is editable — so a read-only
+// dispatched viewer breaks packaging-is-not-trust exactly where a reader would notice.
+//
+// **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.
+//
+// Pure — no SDK, no React — so all of the above is testable without a host.
+
+import type { SandboxMount } from '@immediately-run/sdk/mounts';
+
+/** How an edit of a content entry is delivered. */
+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 };
+
+export interface CorpusIdentity {
+  /** Whether the corpus is a mount rather than this app's own repo. */
+  dispatched: boolean;
+  /** The content root, with a trailing slash (`getContentRoot()`). */
+  contentRoot: string;
+  /** The corpus mount id, when dispatched (`getCorpusMountId()`). */
+  mountId: string | null;
+}
+
+/** `/app/content/x.mdx` → `content/x.mdx` — the fork's repo-relative path. */
+export function keyToSelfPath(key: string): string {
+  return key.replace(/^\/app\//, '').replace(/^\//, '');
+}
+
+/**
+ * Where an edit of `entryKey` should go, or null when there is nowhere to send it.
+ *
+ * Null is not "read-only" — that is {@link corpusWritable}'s question. Null means the key
+ * does not name a file in this corpus at all, or a dispatched viewer has no mount id to
+ * delegate from (an older host that published the corpus without one). Either way there is
+ * nothing to offer, and offering it anyway would produce a refusal the reader must decode.
+ */
+export function editTarget(entryKey: string, corpus: CorpusIdentity): EditTarget | null {
+  if (typeof entryKey !== 'string' || entryKey === '') return null;
+  if (!corpus.dispatched) return { via: 'self', path: keyToSelfPath(entryKey) };
+  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;
+}
+
+/**
+ * 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".
+ *
+ * A corpus mount that has vanished from the list answers `false`: no mount, no write.
+ */
+export function corpusWritable(
+  mounts: readonly SandboxMount[] | null | undefined,
+  corpus: CorpusIdentity,
+): boolean {
+  const list = mounts ?? [];
+  if (!corpus.dispatched) {
+    return list.some((m) => m.type === 'worktree' && m.mode !== 'ro');
+  }
+  if (!corpus.mountId) return false;
+  const mount = list.find((m) => (m.id ?? m.path) === corpus.mountId);
+  // `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';
+}

package/src/lib/openWiki.test.ts

@@ -1,6 +1,13 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { resolveOpenWiki, OPEN_WIKI_TASK, CONTENT_MOUNT_TYPE } from './openWiki';
-import { getContentRoot, setContentRoot, resetContentRoot, isDispatched, APP_CONTENT_ROOT } from './contentRoot';
+import {
+  getContentRoot,
+  getCorpusMountId,
+  setContentRoot,
+  resetContentRoot,
+  isDispatched,
+  APP_CONTENT_ROOT,
+} from './contentRoot';
 import { slugToKey, isContentEntry, homeKey, contentDir, keyToHref, sandboxPathToKey } from './content';
 import { layoutChainForKey } from './layout';
 import type { SandboxMount } from '@immediately-run/sdk/mounts';
@@ -13,14 +20,14 @@ afterEach(resetContentRoot);
 describe('resolveOpenWiki — the delegated corpus', () => {
   it('resolves the dir param mounted at the host-minted chroot', () => {
     const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/task/t1/dir')]);
-    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: false, via: 'task' });
+    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: false, via: 'task', mountId: '/task/t1/dir' });
   });
 
   it('reports a read-only delegation without refusing it', () => {
     // Sharing a corpus read-only is legitimate — the reader still reads. Only the WRITE
     // affordances may consult this; refusing the whole open would break the ordinary case.
     const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/task/t1/dir', { mode: 'ro' })]);
-    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: true, via: 'task' });
+    expect(r).toEqual({ ok: true, root: '/task/t1/dir', readOnly: true, via: 'task', mountId: '/task/t1/dir' });
   });
 
   it('is not a callee when there is no task input — the ordinary fork boot', () => {
@@ -48,7 +55,7 @@ describe('resolveOpenWiki — the delegated corpus', () => {
     // The host owns the `/task/<slot>/<param>` grammar; if it ever renames the segment,
     // suffix-matching alone would cancel a task the user really asked for.
     const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/app'), mount('/mnt/abc123')]);
-    expect(r).toEqual({ ok: true, root: '/mnt/abc123', readOnly: false, via: 'task' });
+    expect(r).toEqual({ ok: true, root: '/mnt/abc123', readOnly: false, via: 'task', mountId: '/mnt/abc123' });
   });
 
   it('does not guess between two foreign mounts', () => {
@@ -72,7 +79,7 @@ describe('repo-load dispatch — a cold URL load, with no task input at all', ()
       mount('/app'),
       mount('/mnt/deadbeef', { type: CONTENT_MOUNT_TYPE, name: 'neumark/book-nine-from-here' }),
     ]);
-    expect(r).toEqual({ ok: true, root: '/mnt/deadbeef', readOnly: false, via: 'repo-load' });
+    expect(r).toEqual({ ok: true, root: '/mnt/deadbeef', readOnly: false, via: 'repo-load', mountId: '/mnt/deadbeef' });
   });
 
   it('carries a read-only delegation through', () => {
@@ -214,3 +221,37 @@ describe('routing — the URL space follows the packaging', () => {
     expect(key).toBe('/task/t1/dir/app/content/home.mdx');
   });
 });
+
+// R3-266 — the corpus mount ID, which is what an onward delegation NAMES. Without it a
+// dispatched viewer can locate the corpus and still not hand one of its files to the
+// platform editor, which is the whole of the dispatched write path.
+describe('resolveOpenWiki — the corpus mount id (the onward-delegation handle)', () => {
+  it('prefers the host-published id over the path', () => {
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [
+      mount('/task/t1/dir', { id: 'space:abc' }),
+    ]);
+    expect(r).toMatchObject({ ok: true, mountId: 'space:abc' });
+  });
+
+  it('falls back to the mount PATH, which is exactly what the host publishes for a chroot', () => {
+    // `mintDelegations` names the descriptor `{ path, type: 'task-delegation', id: path }`,
+    // so path and id coincide for a task delegation — the fallback is the same answer, not
+    // a guess, and it keeps working against a host that publishes no id at all.
+    const r = resolveOpenWiki({ task: OPEN_WIKI_TASK, params: {} }, [mount('/task/t1/dir')]);
+    expect(r).toMatchObject({ ok: true, mountId: '/task/t1/dir' });
+  });
+
+  it('carries the id through the repo-load branch too', () => {
+    const r = resolveOpenWiki(null, [
+      mount('/mnt/deadbeef', { type: CONTENT_MOUNT_TYPE, id: 'github:neumark/book@main' }),
+    ]);
+    expect(r).toMatchObject({ ok: true, via: 'repo-load', mountId: 'github:neumark/book@main' });
+  });
+
+  it('reaches the contentRoot module, so the affordance can read it back', () => {
+    setContentRoot('/task/t1/dir', { readOnly: false, mountId: 'space:abc' });
+    expect(getCorpusMountId()).toBe('space:abc');
+    resetContentRoot();
+    expect(getCorpusMountId()).toBeNull();
+  });
+});

package/src/lib/openWiki.ts

@@ -25,7 +25,16 @@ export const DIR_PARAM = 'dir';
 export const CONTENT_MOUNT_TYPE = 'content';
 
 export type OpenWikiResolution =
-  | { ok: true; root: string; readOnly: boolean; via: 'task' | 'repo-load' }
+  | {
+      ok: true;
+      root: string;
+      readOnly: boolean;
+      via: 'task' | 'repo-load';
+      /** The corpus mount's id — what an onward delegation names (R3-266). Falls back to
+       *  the mount PATH, which is exactly what the host publishes as the id for a task
+       *  chroot (`mintDelegations` uses the mount point as the descriptor id). */
+      mountId: string;
+    }
   | { ok: false; reason: 'not-a-callee' | 'wrong-task' | 'no-mount' };
 
 /**
@@ -53,7 +62,13 @@ export function resolveOpenWiki(
   // input and would otherwise fall out as `not-a-callee` and render our own corpus.
   const marked = mounts.find((m) => m.type === CONTENT_MOUNT_TYPE);
   if (marked) {
-    return { ok: true, root: marked.path, readOnly: marked.mode === 'ro', via: 'repo-load' };
+    return {
+      ok: true,
+      root: marked.path,
+      readOnly: marked.mode === 'ro',
+      via: 'repo-load',
+      mountId: marked.id ?? marked.path,
+    };
   }
 
   if (!input) return { ok: false, reason: 'not-a-callee' };
@@ -67,7 +82,7 @@ export function resolveOpenWiki(
   // `mode` is absent on the primary repo mount and rw by default elsewhere. A read-only
   // delegation is a legitimate way to share a corpus — the reader still reads — so it
   // resolves normally and only the WRITE affordances consult this flag.
-  return { ok: true, root: hit.path, readOnly: hit.mode === 'ro', via: 'task' };
+  return { ok: true, root: hit.path, readOnly: hit.mode === 'ro', via: 'task', mountId: hit.id ?? hit.path };
 }
 
 /** The message a failed resolution should show, in the reader's terms rather than the

package/src/lib/shell.ts

@@ -33,7 +33,17 @@ export interface GroveShell {
   // Environment
   vw: 'mobile' | 'desktop';
   navMode: 'top' | 'side';
+  /** Whether to render an edit affordance — the corpus MOUNT's answer, re-read live
+   *  (R3-266), never a property of how this instance was packaged. */
   writable: boolean;
+  /** Open a content entry in the platform editor. Which verb that takes differs by
+   *  packaging (`lib/editTarget`); the chrome never has to know which. */
+  openEditor: (entryKey: string) => void;
+  /** True while an editor is being summoned, for a busy label. */
+  editBusy: boolean;
+  /** What a save actually does, for the affordance's title — under dispatch it says that
+   *  proposing a change back to the content repo is not wired yet (R3-266's residual). */
+  editHint: string;
   siteTitle: string;
   /** Interpreter mode (TRUST_MODES §5): render this entry's body through the
    *  non-executable safe renderer (R3-213) instead of the compiled/executable `<Include>`

package/src/lib/themeSelection.test.ts

@@ -0,0 +1,52 @@
+// The selection precedence (02-theme-contract §4), pinned as a decision table —
+// pure, so the whole cross-product of sources is cheap to assert. R3-308.
+import { describe, expect, it } from 'vitest';
+import { resolvePalette, resolvePolarity } from './themeSelection';
+import { preferredPolarity, THEMES } from '../data/themes';
+
+describe('resolvePalette — reader, else author, else default', () => {
+  it('a reader override wins over the author declaration', () => {
+    expect(resolvePalette({ reader: 'pixies', author: 'lotr' })).toBe('pixies');
+  });
+
+  it("a reader's explicit 'default' outranks a declaration — it is a choice, not an absence", () => {
+    expect(resolvePalette({ reader: 'default', author: 'lotr' })).toBe('default');
+  });
+
+  it('the author declaration is the default a reader falls into', () => {
+    expect(resolvePalette({ reader: null, author: 'family' })).toBe('family');
+  });
+
+  it('no reader, no author → default', () => {
+    expect(resolvePalette({})).toBe('default');
+    expect(resolvePalette({ reader: '', author: null })).toBe('default');
+  });
+});
+
+describe('resolvePolarity — reader, else host, else the palette’s own preference', () => {
+  it('a reader override wins over the host', () => {
+    expect(resolvePolarity({ reader: 'light', host: 'dark', preferred: 'dark' })).toBe('light');
+  });
+
+  it('the host drives polarity when the reader is silent — palette untouched (theme:read is polarity-only)', () => {
+    expect(resolvePolarity({ reader: null, host: 'light', preferred: 'dark' })).toBe('light');
+    expect(resolvePolarity({ reader: null, host: 'dark', preferred: 'light' })).toBe('dark');
+  });
+
+  it('no reader, no host → the palette’s preferred polarity', () => {
+    expect(resolvePolarity({ reader: null, host: null, preferred: 'light' })).toBe('light');
+  });
+
+  it('an unparseable stored override is silence, not a crash', () => {
+    expect(resolvePolarity({ reader: null, host: 'light', preferred: 'dark' })).toBe('light');
+  });
+});
+
+describe('the catalogue carries a preferred polarity for every theme (R3-308)', () => {
+  it('every theme declares one, and unknown ids fall back to dark', () => {
+    for (const t of THEMES) expect(['light', 'dark']).toContain(t.preferred);
+    expect(preferredPolarity('pixies')).toBe('dark');
+    expect(preferredPolarity('family')).toBe('light');
+    expect(preferredPolarity('never-heard-of')).toBe('dark');
+  });
+});

package/src/lib/themeSelection.ts

@@ -0,0 +1,59 @@
+// Theme selection — the ONE resolution of who picks what a reader sees
+// (plans/grove-layouts-and-themes/02-theme-contract.mdx §4, R3-308).
+//
+// Two INDEPENDENT axes, three sources, stated once here so no surface re-derives
+// them (ways_of_working §5: one resolution entry point per concern):
+//
+//   palette  = reader override, else author declaration, else 'default'
+//   polarity = reader override, else host theme,        else the theme's own preferred
+//
+// The host has an opinion about POLARITY ONLY — it holds `theme:read` for exactly
+// that and nothing else, so it never appears in the palette chain. A reader's
+// choice outranks everyone and persists; an author's declaration is the default a
+// reader falls into, not a wall.
+//
+// PURE: takes already-read inputs, returns a decision. Where each input comes from
+// (localStorage, home-entry frontmatter, the host channel) is wiring, not policy,
+// and lives in the components.
+
+/** Light/dark — the axis that selects WITHIN a palette family. */
+export type Polarity = 'light' | 'dark';
+
+/** A palette family id — a `Theme['id']`, or any string a reader's override holds. */
+export type PaletteId = string;
+
+export interface PaletteInputs {
+  /** The reader's stored override (`grove:theme`), if any. */
+  reader?: PaletteId | null;
+  /** The author's `theme:` declaration on the home entry, if any. */
+  author?: PaletteId | null;
+}
+
+/**
+ * Resolve the palette. An empty/absent override is NOT an override — `''` would
+ * otherwise beat a real declaration while meaning nothing. `'default'` as a READER
+ * choice is meaningful ("the brand palette, even though this wiki declares another"),
+ * so any explicit reader value — `default` included — outranks the author.
+ */
+export function resolvePalette({ reader, author }: PaletteInputs): PaletteId {
+  if (reader) return reader;
+  if (author) return author;
+  return 'default';
+}
+
+export interface PolarityInputs {
+  /** The reader's stored override (`grove:appearance`), if any. */
+  reader?: Polarity | null;
+  /** The host's current theme, when the host has one (standalone: the channel's
+   *  initial — the host axis simply has no live source there). */
+  host?: Polarity | null;
+  /** The resolved palette's own preferred polarity. */
+  preferred: Polarity;
+}
+
+/** Resolve the polarity. Reader, then host, then the palette's own preference. */
+export function resolvePolarity({ reader, host, preferred }: PolarityInputs): Polarity {
+  if (reader === 'light' || reader === 'dark') return reader;
+  if (host === 'light' || host === 'dark') return host;
+  return preferred;
+}

package/viewer.manifest.json

@@ -254,6 +254,7 @@
   "frontmatter": {
     "engine": [
       "site",
+      "theme",
       "layout",
       "view",
       "frame",