@marver-design/marver 0.11.0 → 0.12.0

package/dist/summary-Bf9tiGrE.mjs

@@ -0,0 +1,211 @@
+import { n as replay } from "./events-C9k-ceOj.mjs";
+import { x as withLock } from "./auth-DdUKeVKt.mjs";
+import { closeSync, fsyncSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, createPrivateKey, createPublicKey, createVerify, generateKeyPairSync, randomBytes, sign } from "node:crypto";
+//#region src/server/summary.ts
+/**
+* The front door's canvas half (02-home §3, 04-solution §9.1-9.2).
+*
+* Three pieces live here: the canvas identity keypair (generated once onto the
+* volume - the private half never leaves it), the JWS the summary endpoint
+* answers with (origin alone is not a durable identity; possession of the key
+* is what makes a front-door row light up), and the per-user seen marks that
+* make `unread` a real number instead of a bookmark.
+*/
+const idCache = /* @__PURE__ */ new Map();
+/** RFC 7638 thumbprint input: the required EC members, lexicographic, no space. */
+const thumbprint = (jwk) => createHash("sha256").update(JSON.stringify({
+	crv: jwk.crv,
+	kty: jwk.kty,
+	x: jwk.x,
+	y: jwk.y
+})).digest("hex");
+/**
+* The keypair, generated on first boot with a data dir. ES256 (P-256), the
+* same suite the identity service already signs with. Stored as one JSON file
+* at 0600; a half-written file from a crashed boot is regenerated - nothing
+* has pinned a kid the canvas never served.
+*/
+function canvasIdentity(dir) {
+	const hit = idCache.get(dir);
+	if (hit) return hit;
+	const file = join(dir, "identity.json");
+	const read = () => {
+		try {
+			const p = JSON.parse(readFileSync(file, "utf8"));
+			if (typeof p?.privatePem !== "string" || typeof p?.publicJwk?.x !== "string") return null;
+			return {
+				kid: thumbprint(p.publicJwk),
+				publicJwk: p.publicJwk,
+				privatePem: p.privatePem
+			};
+		} catch {
+			return null;
+		}
+	};
+	const identity = read() ?? withLock(dir, () => {
+		const again = read();
+		if (again) return again;
+		const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+		const publicJwk = publicKey.export({ format: "jwk" });
+		const privatePem = privateKey.export({
+			format: "pem",
+			type: "pkcs8"
+		}).toString();
+		const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+		const fd = openSync(tmp, "wx", 384);
+		try {
+			writeSync(fd, JSON.stringify({
+				publicJwk,
+				privatePem
+			}));
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(tmp, file);
+		return {
+			kid: thumbprint(publicJwk),
+			publicJwk,
+			privatePem
+		};
+	}, ".identity.lock");
+	idCache.set(dir, identity);
+	return identity;
+}
+const b64u = (b) => Buffer.from(b).toString("base64url");
+/** A compact JWS over `payload`, signed by the canvas identity key. The header
+*  carries the kid, never the key - discovery is `GET /__mv/api/identity`. */
+function signCanvasJws(dir, payload, typ = "marver-summary+jwt") {
+	const id = canvasIdentity(dir);
+	const head = b64u(JSON.stringify({
+		alg: "ES256",
+		typ,
+		kid: id.kid
+	}));
+	const body = b64u(JSON.stringify(payload));
+	const sig = sign("sha256", Buffer.from(`${head}.${body}`), {
+		key: createPrivateKey(id.privatePem),
+		dsaEncoding: "ieee-p1363"
+	});
+	return `${head}.${body}.${b64u(sig)}`;
+}
+/** The public half, exported for tests that verify the JWS end to end. */
+function canvasPublicKey(dir) {
+	return createPublicKey({
+		key: canvasIdentity(dir).publicJwk,
+		format: "jwk"
+	});
+}
+function loadSeen(dir) {
+	try {
+		const p = JSON.parse(readFileSync(join(dir, "seen.json"), "utf8"));
+		return typeof p === "object" && p !== null ? p : {};
+	} catch {
+		return {};
+	}
+}
+function markSeen(dir, emailNorm, board, eventId) {
+	withLock(dir, () => {
+		const store = loadSeen(dir);
+		(store[emailNorm] ??= {})[board] = eventId;
+		const file = join(dir, "seen.json");
+		const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+		const fd = openSync(tmp, "wx", 384);
+		try {
+			writeSync(fd, JSON.stringify(store));
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(tmp, file);
+	}, ".seen.lock");
+}
+function deriveThreads(events) {
+	return {
+		events,
+		open: new Set(replay(events).filter((t) => !t.resolved).map((t) => t.id))
+	};
+}
+/** Unread for one board = open-thread events after the caller's mark; no mark
+*  (or a mark the log no longer holds) = every open-thread event counts. */
+function unreadCount(state, markId) {
+	const from = markId ? state.events.findIndex((e) => e.id === markId) : -1;
+	let n = 0;
+	for (let i = from + 1; i < state.events.length; i++) {
+		const e = state.events[i];
+		const root = e.type === "reply" ? e.parentId : e.commentId;
+		if (root && state.open.has(root)) n++;
+	}
+	return n;
+}
+const spentJti = /* @__PURE__ */ new Map();
+let jtiLoaded = false;
+const jtiFile = (dir) => join(dir, "spent-jti.json");
+function loadSpentJti(dir) {
+	if (jtiLoaded) return;
+	jtiLoaded = true;
+	try {
+		const p = JSON.parse(readFileSync(jtiFile(dir), "utf8"));
+		const now = Math.floor(Date.now() / 1e3);
+		if (typeof p === "object" && p !== null) {
+			for (const [k, e] of Object.entries(p)) if (typeof e === "number" && e > now) spentJti.set(k, e);
+		}
+	} catch {}
+}
+function persistSpentJti(dir) {
+	const now = Math.floor(Date.now() / 1e3);
+	for (const [k, e] of spentJti) if (e < now) spentJti.delete(k);
+	const file = jtiFile(dir);
+	const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	const fd = openSync(tmp, "wx", 384);
+	try {
+		writeSync(fd, JSON.stringify(Object.fromEntries(spentJti)));
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(tmp, file);
+}
+function verifyCanvasJws(dir, token, typ, aud) {
+	const parts = token.split(".");
+	if (parts.length !== 3 || token.length > 8192) return { ok: false };
+	let header, claims;
+	try {
+		header = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+		claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+	} catch {
+		return { ok: false };
+	}
+	if (typeof header !== "object" || header === null || typeof claims !== "object" || claims === null) return { ok: false };
+	if (header.alg !== "ES256" || header.typ !== typ) return { ok: false };
+	const id = canvasIdentity(dir);
+	if (header.kid !== id.kid) return { ok: false };
+	if (claims.aud !== aud) return { ok: false };
+	const now = Math.floor(Date.now() / 1e3);
+	if (typeof claims.exp !== "number" || claims.exp < now) return { ok: false };
+	const sig = Buffer.from(parts[2], "base64url");
+	if (sig.length !== 64) return { ok: false };
+	const v = createVerify("SHA256");
+	v.update(`${parts[0]}.${parts[1]}`);
+	v.end();
+	if (!v.verify({
+		key: canvasPublicKey(dir),
+		dsaEncoding: "ieee-p1363"
+	}, sig)) return { ok: false };
+	if (typeof claims.jti === "string") {
+		loadSpentJti(dir);
+		if (spentJti.has(claims.jti)) return { ok: false };
+		spentJti.set(claims.jti, claims.exp);
+		try {
+			persistSpentJti(dir);
+		} catch {}
+	}
+	return {
+		ok: true,
+		claims
+	};
+}
+//#endregion
+export { canvasIdentity, deriveThreads, loadSeen, markSeen, signCanvasJws, unreadCount, verifyCanvasJws };

package/dist/{sync-DELGomPk.mjs → sync-WYxDN9IT.mjs}

@@ -1,110 +1,11 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { t as diffEvents } from "./events-C9k-ceOj.mjs";
 import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
-import { t as CLI_TOKEN_CHARS } from "./auth-B5yuwnOq.mjs";
+import { t as CLI_TOKEN_CHARS } from "./auth-DdUKeVKt.mjs";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-//#region src/shared/events.ts
-/** Events the other side lacks, by id - the sync payload in either direction. */
-function diffEvents(mine, theirIds) {
-	const have = new Set(theirIds);
-	return mine.filter((e) => !have.has(e.id));
-}
-/** Replay a board's events into current thread state. Deterministic: replay order is
-*  (ts, id) so two stores holding the same event SET always derive the same state.
-*  TWO passes - creates first, then everything else - so a reply whose author's clock
-*  ran ahead of the creator's still lands instead of being dropped forever. */
-function replay(events) {
-	const ordered = [...events].sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : 1));
-	const threads = /* @__PURE__ */ new Map();
-	for (const ev of ordered) {
-		if (ev.type !== "create") continue;
-		if (!ev.commentId || threads.has(ev.commentId)) continue;
-		threads.set(ev.commentId, {
-			id: ev.commentId,
-			board: ev.board,
-			nodeKey: ev.nodeKey,
-			frame: ev.frame,
-			anchor: ev.anchor,
-			author: ev.author,
-			body: ev.body,
-			ts: ev.ts,
-			resolved: false,
-			agent: ev.agent,
-			agentMeta: ev.agentMeta,
-			replies: [],
-			reactions: {}
-		});
-	}
-	for (const ev of ordered) switch (ev.type) {
-		case "reply": {
-			const t = ev.parentId ? threads.get(ev.parentId) : void 0;
-			if (!t || !ev.commentId || t.replies.some((r) => r.id === ev.commentId)) break;
-			t.replies.push({
-				id: ev.commentId,
-				author: ev.author,
-				body: ev.body,
-				ts: ev.ts,
-				agent: ev.agent,
-				agentMeta: ev.agentMeta
-			});
-			break;
-		}
-		case "edit": {
-			if (!ev.commentId || ev.body === void 0) break;
-			const t = threads.get(ev.commentId);
-			if (t) {
-				t.body = ev.body;
-				break;
-			}
-			for (const th of threads.values()) {
-				const r = th.replies.find((r) => r.id === ev.commentId);
-				if (r) {
-					r.body = ev.body;
-					break;
-				}
-			}
-			break;
-		}
-		case "resolve": {
-			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
-			if (t) {
-				t.resolved = true;
-				if (ev.addressedIn) t.addressedIn = ev.addressedIn;
-			}
-			break;
-		}
-		case "reopen": {
-			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
-			if (t) {
-				t.resolved = false;
-				t.addressedIn = void 0;
-			}
-			break;
-		}
-		case "reanchor": {
-			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
-			if (t && ev.anchor != null) t.anchor = ev.anchor;
-			break;
-		}
-		case "react": {
-			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
-			const who = ev.author?.email;
-			if (!t || !who || !ev.emoji) break;
-			const users = t.reactions[ev.emoji] ??= [];
-			const at = users.indexOf(who);
-			if (at === -1) users.push(who);
-			else {
-				users.splice(at, 1);
-				if (!users.length) delete t.reactions[ev.emoji];
-			}
-			break;
-		}
-	}
-	return [...threads.values()];
-}
-//#endregion
 //#region src/server/sync.ts
 /**
 * Dev ↔ published comment sync - one merge rule, run from the dev side.
@@ -394,4 +295,4 @@ async function connectToken(root, url, token) {
 	});
 }
 //#endregion
-export { syncOnce as a, loadCollab as i, connectClaim as n, sync_exports as o, connectToken as r, replay as s, connect as t };
+export { syncOnce as a, loadCollab as i, connectClaim as n, sync_exports as o, connectToken as r, connect as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/shell/App.tsx

@@ -1,11 +1,11 @@
 import { Component, useEffect, useRef, useState, type MouseEvent as ReactMouseEvent, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useStore, CONFIG, PUBLISHED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, type FrameEntry } from './store.ts'
+import { useStore, CONFIG, LOCKED_SHELL, PUBLISHED, SOURCE_REVEALED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, landingMode, type FrameEntry } from './store.ts'
 import { Tip } from './Tip.tsx'
 import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { frameByWindow } from './canvas/frame-registry.ts'
-import { enterPlay, playCtl, PlayOverlay } from './Play.tsx'
+import { enterFocus, enterPlay, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
 import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, ColumnsIcon, FrameRectIcon, IntentGlyph, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, ParallelogramFillIcon, PencilSimpleIcon, PlayIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
 import { CommentsController, revealThread } from './Comments.tsx'
@@ -26,7 +26,10 @@ function copyToClipboard(text: string, okMsg: string) {
 
 /** The address a frame copies - the same string from the sidebar right-click, the floating
  *  toolbar, and ⇧P: the board it sits on, the frame id, and its file. */
-const framePath = (board: string, f: { id: string; file: string }) => `board: ${board} · frame: ${f.id}  (${f.file})`
+// stripped build: the file column would only show the opaque token, so the
+// copy keeps what is still honest - the board and the frame id
+const framePath = (board: string, f: { id: string; file: string }) =>
+  SOURCE_REVEALED ? `board: ${board} · frame: ${f.id}  (${f.file})` : `board: ${board} · frame: ${f.id}`
 
 type MenuItem = { label: string; icon: ReactNode; onClick: () => void }
 type MenuState = { x: number; y: number; items: MenuItem[] }
@@ -561,7 +564,20 @@ export function App() {
       }
       const ok = await boot()
       urlReady.current = true
-      if (ok && bootHash.play) enterPlay(bootHash.play)     // #/p/<board> alone = board start
+      if (ok && bootHash.focus) {
+        // a frame deep link forces focus for that visit, over every other rule
+        // (01-sharing §6.1 step 3) - the stage mounts any manifest frame, so no
+        // board lookup is needed
+        enterFocus(bootHash.focus.at, { ...bootHash.focus, deep: true })
+      } else if (ok && bootHash.play) enterPlay(bootHash.play)     // #/p/<board> alone = board start
+      else if (ok && PUBLISHED) {
+        // published landing: explicit `open` beats the type default; canvas and
+        // board land on the canvas surface (board-scoped already); a lock will
+        // then hold the mode by hiding every door (04-solution §2.35)
+        const mode = landingMode(useStore.getState().board)
+        if (mode === 'present') enterPlay()
+        else if (mode === 'focus') enterFocus()
+      }
     }
     void start()
   }, [])
@@ -574,11 +590,15 @@ export function App() {
   useEffect(() => {
     if (!urlReady.current) return
     const s = useStore.getState()
-    if (playState) {
+    if (playState?.focus && playState.deep) {
+      // a deep-link focus visit keeps its frame URL - the shareable form
+      writeHash({ focus: { at: playState.at, device: playState.device, theme: playState.theme } })
+    } else if (playState && !playState.focus) {
       const push = !prevPlay.current || prevPlay.current.at !== playState.at
       writeHash({ board: s.board, play: playState }, push)
     } else {
-      writeHash({ board: s.board, n: s.selection })
+      // type-default focus keeps the board URL the visitor arrived on
+      writeHash({ board: s.board, n: playState ? [] : s.selection })
     }
     prevPlay.current = playState
   })
@@ -596,7 +616,9 @@ export function App() {
         s = useStore.getState()
         if (s.board !== h.board) return        // switch failed; the projection effect will re-sync the URL
       }
-      if (h.play) {
+      if (h.focus) {
+        enterFocus(h.focus.at, { ...h.focus, deep: true })
+      } else if (h.play) {
         if (s.play) playCtl.sync(h.play)
         else enterPlay(h.play)
       } else {
@@ -820,7 +842,7 @@ export function App() {
       if (e.key === 't') { animateLayout(); runTidy() }
       // laser and comment mode are one-at-a-time: comment mode already highlights
       // what you'd click, so stacking the full rainbow on top only adds noise
-      if (e.key === 'l') {
+      if (e.key === 'l' && SOURCE_REVEALED) {
         if (!s.laser) commentsStore().setMode(false)
         s.setLaser(!s.laser)
       }
@@ -919,6 +941,19 @@ export function App() {
     if (!interacting) appRef.current?.focus({ preventScroll: true })
   }, [interacting])
 
+  // Every published board is locked to a stage mode: the canvas shell is never
+  // offered - no sidebar, no canvas surface, no toolbar. The bundle IS the
+  // locked view (the Publish-to-web shape). Boot still ran above; the landing
+  // effect entered the mode, and PlayOverlay's noDoor keeps it there.
+  if (LOCKED_SHELL) {
+    return (
+      <div ref={appRef} tabIndex={-1} className={`sh-app${dark ? ' dark' : ''}`}>
+        <PlayOverlay />
+        <div className="sh-toasts">{toasts.map((t) => <div className="sh-toast" key={t.id}>{t.text}</div>)}</div>
+      </div>
+    )
+  }
+
   return (
     <div ref={appRef} tabIndex={-1} className={`sh-app${dark ? ' dark' : ''}${interacting ? ' interacting' : ''}`}>
       <Canvas />

package/src/client/shell/Comments.tsx

@@ -9,7 +9,7 @@ import { createPortal } from 'react-dom'
 import { avatarFallback, useComments } from './comments-store.ts'
 import { useStore, type Node } from './store.ts'
 import { threadHostKey } from './keys.ts'
-import { canvasCtl } from './canvas/Canvas.tsx'
+import { canvasCtl } from './canvas/ctl.ts'
 import { bootHash, buildHash, parseHash, writeHash } from './hash.ts'
 import { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, ParallelogramFillIcon, PencilSimpleIcon, PlusIcon, XIcon } from './icons.tsx'
 import { Tip } from './Tip.tsx'
@@ -74,7 +74,7 @@ export function Avatar({ author, size = 22 }: { author?: { email?: string; name?
   )
 }
 
-type Face = { email?: string; name?: string; avatar?: string; agent?: boolean }
+type Face = { email?: string; id?: string; name?: string; avatar?: string; agent?: boolean }
 
 /** The signal a marker (pin or stack) carries: WHO took part and HOW MANY comments
  *  in total - root + every reply, across all the given threads. Unique participants
@@ -89,7 +89,9 @@ function markerDigest(threads: Thread[]): { faces: Face[]; count: number } {
   // Avatar renders them all as the live identity - two keys would show identical twin faces.
   const add = (a: Face | undefined, agent?: boolean) => {
     const face: Face | undefined = agent ? { agent: true } : a
-    const k = agent ? 'marver' : a?.email ? `e:${a.email.toLowerCase()}` : 'local'
+    // published transport carries the opaque id instead of an email - same
+    // namespacing rule, different stable key
+    const k = agent ? 'marver' : a?.email ? `e:${a.email.toLowerCase()}` : a?.id ? `i:${a.id}` : 'local'
     if (face && !seen.has(k)) seen.set(k, face)
   }
   for (const t of threads) {
@@ -465,8 +467,10 @@ export function ThreadCard({ thread, at, bounds, nodeKey, side = 'r', flank, sta
   const local = useComments((s) => s.local)
   const canComment = local || !!me      // dev is always "me"; published needs a session
   // Owner-authored @marver is a live trigger (bold accent); anyone else's is context (plain + tooltip).
-  // Match by email when we know the owner's; in dev without a profile, local writes are the owner.
-  const isOwner = (a?: { email?: string }) => (me?.email ? a?.email === me.email : local)
+  // Match by opaque id on the projected transport, by email locally; in dev
+  // without a profile, local writes are the owner.
+  const isOwner = (a?: { email?: string; id?: string }) =>
+    me?.id && a?.id ? a.id === me.id : me?.email ? a?.email === me.email : local
   const [text, setText] = useState('')
   const [copied, setCopied] = useState(false)
   const copyTimer = useRef<ReturnType<typeof setTimeout>>(undefined)

package/src/client/shell/LockedApp.tsx

@@ -0,0 +1,113 @@
+/**
+ * The locked-shell entry (01-sharing §5.1's all-boards rule) - what a bundle
+ * whose every published board is locked to a stage mode boots into INSTEAD of
+ * the canvas shell. The build swaps this module in for App.tsx, so the canvas
+ * surface (sidebar, board grid, toolbar) is not hidden - its code never enters
+ * the bundle. Publish-to-web, as an artifact rather than a flag.
+ *
+ * What remains is exactly the locked surface: boot, the landing rule, the play
+ * or focus overlay (whose lock already refuses every exit), and deep links
+ * within what the lock allows.
+ */
+import { Component, useEffect, useRef, type ReactNode } from 'react'
+import { useStore, boardLabel, landingMode } from './store.ts'
+import { enterFocus, enterPlay, PlayOverlay, playCtl } from './Play.tsx'
+import { bootHash, parseHash, writeHash } from './hash.ts'
+import { useComments } from './comments-store.ts'
+
+export class ShellBoundary extends Component<{ children: ReactNode }, { err: Error | null }> {
+  state = { err: null as Error | null }
+  static getDerivedStateFromError(err: Error) { return { err } }
+  render() {
+    if (!this.state.err) return this.props.children
+    return (
+      <div style={{ fontFamily: 'ui-monospace, monospace', padding: 32 }}>
+        <b style={{ color: '#a81f16' }}>shell crashed</b>
+        <pre style={{ whiteSpace: 'pre-wrap', fontSize: 12 }}>{this.state.err.message}</pre>
+        <button onClick={() => location.reload()}>reload</button>
+      </div>
+    )
+  }
+}
+
+let booted = false
+
+export function App() {
+  const toasts = useStore((s) => s.toasts)
+  const board = useStore((s) => s.board)
+
+  /** The landing rule, enforced: the mode the lock pinned, entered on boot and
+   *  re-entered if anything ever drops the overlay - there is no other surface. */
+  const land = () => {
+    const s = useStore.getState()
+    if (s.play) return
+    const mode = landingMode(s.board)
+    if (mode === 'focus') enterFocus()
+    else enterPlay()
+  }
+
+  useEffect(() => {
+    if (booted) return
+    booted = true
+    const start = async () => {
+      if (bootHash.board && bootHash.board !== useStore.getState().board)
+        useStore.setState({ board: bootHash.board, boardAuto: false })
+      const ok = await boot()
+      urlReady.current = true
+      if (!ok) return
+      if (bootHash.focus) enterFocus(bootHash.focus.at, { ...bootHash.focus, deep: true })
+      else if (bootHash.play) enterPlay(bootHash.play)
+      else land()
+    }
+    const boot = useStore.getState().boot
+    void start()
+  }, [])
+
+  // the overlay IS the surface: if it ever closes, land again
+  const play = useStore((s) => s.play)
+  useEffect(() => { if (!play) setTimeout(land, 30) }, [play])
+
+  // the URL projection, minimal: stage state only (there is no selection here)
+  const urlReady = useRef(false)
+  useEffect(() => {
+    if (!urlReady.current || !play) return
+    if (play.focus && play.deep) writeHash({ focus: { at: play.at, device: play.device, theme: play.theme } })
+    else if (!play.focus) writeHash({ board: useStore.getState().board, play })
+  })
+
+  // back/forward + pasted links, within what the lock allows
+  useEffect(() => {
+    const onPop = async () => {
+      const h = parseHash()
+      const s = useStore.getState()
+      if (h.board && h.board !== s.board) {
+        await s.switchBoard(h.board)
+        land()
+        return
+      }
+      if (h.focus) enterFocus(h.focus.at, { ...h.focus, deep: true })
+      else if (h.play && s.play) playCtl.sync(h.play)
+      else if (h.play) enterPlay(h.play)
+    }
+    window.addEventListener('popstate', onPop)
+    window.addEventListener('hashchange', onPop)
+    return () => { window.removeEventListener('popstate', onPop); window.removeEventListener('hashchange', onPop) }
+  }, [])
+
+  // comment liveness for the stage overlay - same wiring the canvas shell does
+  useEffect(() => {
+    if (!board) return
+    const c = useComments.getState()
+    void c.load(board)
+    return c.live(board)
+  }, [board])
+
+  useEffect(() => { document.title = board ? `${boardLabel(board)} - Marver` : 'Marver' }, [board])
+
+  return (
+    <div tabIndex={-1} className="sh-app dark">
+      <PlayOverlay />
+      <div className="sh-toasts">{toasts.map((t) => <div className="sh-toast" key={t.id}>{t.text}</div>)}</div>
+    </div>
+  )
+}