@marver-design/marver 0.8.0 → 0.8.1

package/src/client/shell/App.tsx

@@ -1,5 +1,5 @@
 import { Component, useEffect, useRef, useState, type ReactNode } from 'react'
-import { useStore, CONFIG, PUBLISHED, boardLabel, cap, humanize, fetchBoardNames, type FrameEntry } from './store.ts'
+import { useStore, CONFIG, PUBLISHED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, type FrameEntry } from './store.ts'
 import { Tip } from './Tip.tsx'
 import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
@@ -8,6 +8,7 @@ import { 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, PlayIcon, PlusIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
 import { CommentsController, revealThread } from './Comments.tsx'
+import { poweredByUrl } from '../../shared/utm.ts'
 import { useComments } from './comments-store.ts'
 import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
 
@@ -126,7 +127,7 @@ function SelectionBar() {
   // frame top - the caption offset (8px screen, world-capped) - the caption's height
   // (screen-clamped 12..18px font) - the bar. Gate on the TOP edge of the selection,
   // not the last-selected frame: a mixed selection whose topmost frames are variants
-  // still has a caption to clear (codex final review P2).
+  // still has a caption to clear.
   const capAtTop = selNodes.some((n) => n.y === by0 && useStore.getState().frameFor(n)?.variantGroup)
   const rawTop = capAtTop
     ? `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - clamp(4px * var(--sh-s, 1), 8px, 40px * var(--sh-s, 1)) - (clamp(12px, 17px * var(--sh-s, 1), 18px) * 1.4) - 44px)`
@@ -309,14 +310,14 @@ export function App() {
   const selection = useStore((s) => s.selection)
   const laser = useStore((s) => s.laser)
   const commentMode = useComments((s) => s.commentMode)
-  // SPEC-M5: laser/comment paint live outlines + do element-picking INSIDE the live frame; a scriptless
+  // Laser/comment paint live outlines + do element-picking INSIDE the live frame; a scriptless
   // lean cover would hide them, so a body class suppresses the cover while either mode is active.
   useEffect(() => { document.body.classList.toggle('sh-laser', laser) }, [laser])
   useEffect(() => { document.body.classList.toggle('sh-commenting', commentMode) }, [commentMode])
   const { boot, applyManifest, togglePanel, select, setInteract, runTidy, toast, spawn } = useStore.getState()
   const [pillOpen, setPillOpen] = useState(true)
 
-  // boot honors the deep link (SPEC-M2 §3): board before load, play mode after it.
+  // boot honors the deep link: board before load, play mode after it.
   // Selection + camera intent are restored by the Canvas boot effect. The module-level
   // guard makes boot single-shot: Fast Refresh re-runs mount effects on every App edit,
   // and a re-boot would revert live state to the long-consumed deep link.
@@ -442,7 +443,7 @@ export function App() {
   useEffect(() => {
     if (!import.meta.hot) return
     import.meta.hot.on('sh:manifest', (m: any) => applyManifest(m))
-    // Live Jam presence (SPEC §10): the daemon broadcasts the set of frames Marver is editing.
+    // Live Jam presence: the daemon broadcasts the set of frames Marver is editing.
     // Camera-safe by construction - this only toggles a glow class, never moves the view.
     import.meta.hot.on('sh:jam-activity', (m: any) => useStore.getState().setWorking(Array.isArray(m?.frames) ? m.frames.filter((x: unknown) => typeof x === 'string') : []))
     // Live Jam reply delivery: the daemon just wrote to a board's log - fetch it NOW instead of
@@ -457,7 +458,7 @@ export function App() {
     })
     // multi-viewer sync: another viewer (or an agent) saved this board. A clean canvas
     // re-boots silently, keeping whatever selection survives; a dirty one keeps its
-    // edits and converges through the 409 path on its next save (disk wins, spec §8).
+    // edits and converges through the 409 path on its next save (disk wins).
     import.meta.hot.on('sh:board', (m: any) => {
       const s = useStore.getState()
       if (m?.name !== s.board || m?.sha256 === s.boardHash || s.dirty) return
@@ -470,7 +471,7 @@ export function App() {
     })
   }, [])
 
-  // frame -> shell messages (spec §6 protocol); source validated against known iframes
+  // frame -> shell messages; source validated against known iframes
   useEffect(() => {
     const onMsg = (e: MessageEvent) => {
       const data = e.data
@@ -490,7 +491,7 @@ export function App() {
       } else if (data.type === 'sh:exit-interact') {
         if (s.interact === nodeKey) setInteract(null)
       } else if (data.type === 'sh:measure') {
-        // SPEC-026 generation guard: the sender echoes ITS document's URL rev; a
+        // Generation guard: the sender echoes ITS document's URL rev; a
         // WindowProxy survives navigation, so a stale pre-navigation message would
         // otherwise route as if it came from the current document. Compare against
         // the iframe's CURRENT src - mismatched generations are dropped.
@@ -526,14 +527,16 @@ export function App() {
         if (c.commentMode) c.setDraft({ nodeKey, frame: String(data.id ?? ''), anchor: data.anchor })
       } else if (data.type === 'sh:go') {
         const target = String(data.target ?? '')
+        const carry = s.interact === nodeKey   // a goto from inside an interacting frame
+        // CARRIES interact mode to the target - walking a flow must not eject you to
+        // design mode at every hop (and must survive a board switch)
         const existing = s.nodes.find((n) => n.frame === target && !n.missing)
-        const node = existing ?? spawn(target)
-        if (!node) return toast(`unknown goto target "${target}"`)
-        select(node.key)
-        // a goto from inside an interacting frame CARRIES interact mode to the target -
-        // walking a flow must not eject you to design mode at every hop
-        if (s.interact === nodeKey) setInteract(node.key)
-        setTimeout(() => canvasCtl.fitNode(node.key), 50)
+        if (existing) {
+          gotoSeq++                                  // a local goto supersedes any cross-board one in flight
+          select(existing.key)
+          if (carry) setInteract(existing.key)
+          setTimeout(() => canvasCtl.fitNode(existing.key), 50)
+        } else void gotoAcrossBoards(target, carry)
       } else if (data.type === 'sh:wheel') {
         // B0.2: a passive frame forwarded a wheel event; the canvas owns it. Never for the
         // interact target or play (the app scrolls itself - the parent stays authoritative).
@@ -590,7 +593,7 @@ export function App() {
         if (!s.laser) commentsStore().setMode(false)
         s.setLaser(!s.laser)
       }
-      // C = comment mode (SPEC-M3 §6, the Figma/Miro convention) · Shift+C = hide/show
+      // C = comment mode (the Figma/Miro convention) · Shift+C = hide/show
       // pins · Shift+P = copy file path(s) (P alone is play; D6, changelog 0.4.0)
       if (e.key === 'c' && !e.shiftKey) {
         const c = commentsStore()
@@ -695,7 +698,7 @@ export function App() {
             {/* the mark links to the marver site; the title is the humanized repo name (C2: names
                 the project so two concurrent canvases are never confused), ellipsed if long */}
             <Tip side="bottom" label="marver.design">
-              <a className="mark-link" href="https://marver.design" target="_blank" rel="noreferrer" aria-label="marver.design" tabIndex={panelOpen ? 0 : -1}>
+              <a className="mark-link" href={poweredByUrl(CONFIG.projectName, PUBLISHED ? 'published-canvas' : 'dev-canvas', 'shell')} target="_blank" rel="noreferrer" aria-label="marver.design" tabIndex={panelOpen ? 0 : -1}>
                 <ParallelogramDuoIcon size={21} className="mark" />
               </a>
             </Tip>
@@ -716,7 +719,7 @@ export function App() {
                   canvasCtl.fitNodes(keys)
                 }}>
                 {(() => {
-                  // variant groups render as ONE surface row with A/B/C chips (SPEC-023 §5)
+                  // variant groups render as ONE surface row with A/B/C chips
                   const nodeFor = (id: string) => nodes.find((x) => x.frame === id && !x.missing) ?? nodes.find((x) => x.frame === id)
                   // sidebar order follows the CANVAS (reading order: rows top-to-bottom,
                   // left-to-right) - a story board's list must tell the same story as its
@@ -849,7 +852,7 @@ export function App() {
   )
 }
 
-/** The bottom-right notification corner (SPEC-live-jam §9). Plain toasts render as before.
+/** The bottom-right notification corner. Plain toasts render as before.
  *  Jam pills are FRAME-FIRST (icon + frame title, then Marver · preview) and stack as a DECK:
  *  1-2 show in full; 3+ collapse to the newest pill with two card edges peeking beneath and a
  *  +N badge - click to expand the full list (newest first, timestamps, Clear all). */
@@ -886,10 +889,64 @@ function JamToasts({ toasts }: { toasts: import('./store.ts').Toast[] }) {
   )
 }
 
-/** View from a notification: switch to the note's board first when needed (the thread only exists
- *  in that board's state), then reveal - retrying briefly while the board's comments load. Dismiss
- *  only on success: a cross-board note must never be a destructive no-op. */
+/** A data-goto whose target frame is not on the current board follows the frame HOME:
+ *  the first curated board (switcher rank) that pins it is switched to and the frame
+ *  focused there - a link is navigation, and navigation never edits a board. Only a
+ *  frame NO board pins spawns onto the current board (the original prototype behavior
+ *  for unpinned targets); an id the manifest doesn't know stays a toast. Every goto
+ *  bumps `gotoSeq` so a slow older resolution can never override newer navigation. */
+let gotoSeq = 0
+async function gotoAcrossBoards(target: string, carry: boolean) {
+  const s = useStore.getState()
+  // an id the manifest doesn't know resolves NOWHERE - a tombstone pin on some board
+  // must not send us on a trip that ends in a silent timeout
+  if (!s.manifest?.frames.some((f) => f.id === target)) return s.toast(`unknown goto target "${target}"`)
+  const seq = ++gotoSeq
+  let home: string | null = null
+  try {
+    const names = (await fetchBoardNames()).filter((n) => n !== s.board && n !== 'all-scenes')
+    for (const name of names) {
+      if ((await boardFrames(name)).includes(target)) { home = name; break }
+    }
+  } catch {
+    // a transport failure is NOT proof the frame is unpinned - spawning here would
+    // recreate the board mutation this function exists to prevent
+    return useStore.getState().toast(`goto: could not read the boards - try again`)
+  }
+  if (seq !== gotoSeq) return                        // superseded by newer navigation
+  if (!home) {
+    // no curated board pins it - the original prototype behavior: spawn beside you
+    const st = useStore.getState()
+    const node = st.spawn(target)
+    if (!node) return st.toast(`unknown goto target "${target}"`)
+    st.select(node.key)
+    if (carry) st.setInteract(node.key)
+    setTimeout(() => canvasCtl.fitNode(node.key), 50)
+    return
+  }
+  await s.switchBoard(home)
+  for (let i = 0; i < 12; i++) {                     // the board commits async - retry like viewNote
+    if (seq !== gotoSeq) return
+    const st = useStore.getState()
+    if (st.board === home) {                         // a cancelled/failed switch must not select here
+      const node = st.nodes.find((n) => n.frame === target && !n.missing)
+      if (node) {
+        st.select(node.key)
+        if (carry) st.setInteract(node.key)
+        setTimeout(() => canvasCtl.fitNode(node.key), 50)
+        return
+      }
+    }
+    await new Promise((r) => setTimeout(r, 250))
+  }
+}
+
+/** View from a notification: threads are frame-scoped, so first try to reveal RIGHT HERE
+ *  (the current board may show the thread's frame); only when it doesn't, switch to the
+ *  note's origin board and retry while its comments load. Dismiss only on success: a
+ *  cross-board note must never be a destructive no-op. */
 async function viewNote(note: import('./store.ts').JamNote, dismiss: () => void) {
+  if (revealThread(note.threadId)) { dismiss(); return }
   const s = useStore.getState()
   if (note.board && s.board !== note.board) await s.switchBoard(note.board)
   for (let i = 0; i < 12; i++) {

package/src/client/shell/Comments.tsx

@@ -1,5 +1,5 @@
 /**
- * Comment surfaces on the canvas (SPEC-M3 §6). Canvas-first: pins live ON the frame
+ * Comment surfaces on the canvas. Canvas-first: pins live ON the frame
  * at their anchored elements; an inactive frame collapses its open threads into a
  * top-right stack; the thread card opens beside its pin. Pins keep a screen-space
  * size via --sh-inv (the vbadge pattern) so zoom never shrinks them away.
@@ -8,6 +8,7 @@ import { useEffect, useRef, useState } from 'react'
 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 { bootHash, buildHash, parseHash, writeHash } from './hash.ts'
 import { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, ParallelogramFillIcon, PencilSimpleIcon, PlusIcon, XIcon } from './icons.tsx'
@@ -120,7 +121,11 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
   // select the stable array, filter in render - a selector returning a fresh
   // .filter() array re-renders forever (Object.is never matches)
   const allThreads = useComments((s) => s.threads)
-  const threads = allThreads.filter((t) => t.frame === frameId && (!t.nodeKey || t.nodeKey === node.key))
+  const allNodes = useStore((s) => s.nodes)
+  // one owner per thread (keys.ts): the stored anchor when it still holds, else the
+  // first node showing the frame - a stale key (pre-0.8.1 random keys, board rewrites,
+  // deleted copies) degrades to the frame, never to invisible, and never to two pins
+  const threads = allThreads.filter((t) => t.frame === frameId && threadHostKey(t, allNodes) === node.key)
   const selected = useStore((s) => s.selection.includes(node.key))
   const { setActive } = useComments.getState()
   const [rects, setRects] = useState<Record<string, { x: number; y: number; w: number; h: number } | null>>({})
@@ -167,7 +172,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
 
   // the open card's frozen side (D3) - a HOOK, so it must live above the early returns; and the
   // reset must too: a card can close via the inactive-frame early return (clicking another frame),
-  // which never reaches the render tail - reopen must still RE-PICK the side (Codex P2)
+  // which never reaches the render tail - reopen must still RE-PICK the side
   const sideRef = useRef<{ id: string; side: 'l' | 'r' } | null>(null)
   if (sideRef.current && sideRef.current.id !== active) sideRef.current = null
   // what occupies this frame's LEFT flank (drives the docked card's left gutter): a variant
@@ -177,7 +182,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
   const drafting = draft?.nodeKey === node.key
   if (!show || (!open.length && !drafting)) return null
 
-  // inactive frame: the stack - count + avatars, top-right (SPEC-M3 §6)
+  // inactive frame: the stack - count + avatars, top-right
   const engaged = selected || open.some((t) => t.id === active) || drafting
   if (!engaged && open.length) {
     return (
@@ -247,7 +252,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
 
 /** The open thread card - shared by canvas (bounds = node size, `at` in frame coords) and
  *  prototype (bounds = the on-screen stage size, `at` in screen coords). Geometry only. */
-// ---- Live Jam: @marver rendering + Marver identity (SPEC-live-jam §1, §7) ----------------------
+// ---- Live Jam: @marver rendering + Marver identity ----------------------
 
 const AT_TIP = "Read like any other comment. Marver won't act on this unless the owner promotes it."
 
@@ -273,7 +278,7 @@ function prettyModel(m: string): string {
   return cleaned.replace(/\b\w/g, (c) => c.toUpperCase())
 }
 
-/** The provenance tooltip on the Marver avatar: who orchestrated the change (SPEC §7).
+/** The provenance tooltip on the Marver avatar: who orchestrated the change.
  *  One row per fact, left-aligned, bold label + regular value - the house tooltip treatment. */
 function AgentMetaTip({ meta }: { meta?: AgentMeta }) {
   const rows = [
@@ -346,7 +351,7 @@ function CommentInput({ value, onChange, onSubmit, onCancel, placeholder, autoFo
   return (
     <div className="cm-inputwrap">
       {/* Live mention highlight: a mirror layer behind the transparent-text textarea, so @marver shows
-          its trigger colour AS YOU TYPE (owner = accent-blue "this will run"; else muted). SPEC §1. */}
+          its trigger colour AS YOU TYPE (owner = accent-blue "this will run"; else muted). */}
       <div className="cm-hl" ref={hlRef} aria-hidden>
         {parseMentions(value).map((s, i) => s.mention
           ? <span key={i} className={owner ? 'cm-at owner' : 'cm-at'}>{s.text}</span>
@@ -511,12 +516,12 @@ export function ThreadCard({ thread, at, bounds, nodeKey, side = 'r', flank, sta
     return () => ro.disconnect()
   }, [])
   // ...and after EVERY render: an edited message changes scrollHeight without resizing the
-  // height-capped box or the reply count (Codex P3). setShadows dedups, so this is free.
+  // height-capped box or the reply count. setShadows dedups, so this is free.
   useEffect(syncShadows)
   // PLAY: one static centered device, no zoom - the card docks FIXED beside it on the pin's side
   // (falling back to the roomier side), fully viewport-clamped so the composer is ALWAYS reachable
-  // whatever the device layout or theme (SPEC §14). Recomputed when the stage moves under it:
-  // a device/theme switch resizes .sh-play-stage and a window resize shifts it (Codex P2).
+  // whatever the device layout or theme. Recomputed when the stage moves under it:
+  // a device/theme switch resizes .sh-play-stage and a window resize shifts it.
   const computeStagePos = (): React.CSSProperties | null => {
     if (!stage) return null
     const W = 320, M = 12, maxH = Math.min(660, window.innerHeight - 2 * M)
@@ -542,7 +547,7 @@ export function ThreadCard({ thread, at, bounds, nodeKey, side = 'r', flank, sta
     return () => { window.removeEventListener('resize', re); ro?.disconnect() }
   }, [stage, bounds.w, bounds.h])
   const flip = !float && !stage && at.x > bounds.w * 0.55
-  // Nic's revision: the card scales EXACTLY like the pins - screen-constant via --sh-inv, pure
+  // The card scales EXACTLY like the pins - screen-constant via --sh-inv, pure
   // CSS, smooth per zoom tick with zero re-renders. Geometry in CSS math over the live vars:
   //   top: grows DOWN from the pin, then UP once its bottom reaches the frame's bottom; floor
   //        at -28 (the layer starts below the header - -28 = the frame's TOP border).
@@ -773,12 +778,13 @@ export function IdentityDialog() {
 export function revealThread(c: string): boolean {
   const t = useComments.getState().threads.find((t) => t.id === c)
   if (!t) return false
+  // resolve the host BEFORE activating: a thread whose frame is not on this board
+  // must not consume the deep link (the board switch that CAN show it comes later)
+  const key = threadHostKey(t, useStore.getState().nodes)
+  if (!key) return false
   useComments.getState().setActive(c)
-  const node = t.nodeKey && useStore.getState().nodes.find((n) => n.key === t.nodeKey)
-  if (node) {
-    useStore.getState().select(node.key)
-    setTimeout(() => canvasCtl.fitNode(node.key), 80)
-  }
+  useStore.getState().select(key)
+  setTimeout(() => canvasCtl.fitNode(key), 80)
   return true
 }
 
@@ -815,7 +821,7 @@ export function CommentsController() {
       // a cross-board deep link parks its thread id here until the target board's
       // comments have actually loaded - a timer can't know how long that takes
       if (pendingThread && revealThread(pendingThread)) { pendingThread = null; return }
-      // deep link ?c=<thread> (SPEC-M3 §6): open the thread, select its node, fit it.
+      // deep link ?c=<thread>: open the thread, select its node, fit it.
       // Consumed only on a successful find: the controller's first effect fires with
       // the pre-boot board (child effects run before the parent's boot effect), and
       // burning the flag on that empty pass would eat the link.
@@ -849,7 +855,7 @@ export function CommentsController() {
   }, [])
 
   // broadcast pick mode to every LIVE frame (laser rides along inside the bridge). Scoped to
-  // .sh-live so the SPEC-M5 lean cover (.sh-lean, a scriptless snapshot) is never messaged.
+  // .sh-live so the lean cover (.sh-lean, a scriptless snapshot) is never messaged.
   useEffect(() => {
     for (const f of document.querySelectorAll('iframe.sh-live'))
       (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode, quiet: !ctlShowAnchor }, location.origin)

package/src/client/shell/Play.tsx

@@ -1,5 +1,5 @@
 /**
- * Play mode (SPEC-M2 §1): full-window near-black backdrop, ONE device shell centered at
+ * Play mode: full-window near-black backdrop, ONE device shell centered at
  * the chosen viewport's exact CSS pixels, scaled to fit - or `fill`, where the frame IS
  * the window. The device hosts a single stage iframe that swaps frames in place.
  *
@@ -281,7 +281,7 @@ function PlayInner() {
   }
   const restart = () => { const list = playList(); if (list.length) goTo(list[0]) }
 
-  /** Variant siblings of the CURRENT frame present on this board (SPEC-023 §6): the
+  /** Variant siblings of the CURRENT frame present on this board: the
    *  review question is "which direction is better on THIS screen" - switch in place,
    *  device and theme preserved, each variant's own data-goto links drive after. */
   const variantList = () => {

package/src/client/shell/canvas/Canvas.tsx

@@ -100,7 +100,7 @@ export const canvasCtl = {
   wheel(_input: CanvasWheelInput) {},
 }
 
-/** Variant-group captions (SPEC-023 §4): "Landing · 3 variants" above each group with
+/** Variant-group captions: "Landing · 3 variants" above each group with
  *  2+ members on this board. World-space (scales with the canvas); min screen size via
  *  --sh-inv. Groups with one lone member on a curated board keep the badge, no caption. */
 function GroupCaptions() {

package/src/client/shell/canvas/FrameNode.tsx

@@ -3,6 +3,7 @@ import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
 import { CopyIcon, IntentGlyph, ParallelogramFillIcon, ReloadIcon, XIcon } from '../icons.tsx'
 import { CommentLayer } from '../Comments.tsx'
 import { useComments } from '../comments-store.ts'
+import { threadHostKey } from '../keys.ts'
 import { registerFrame, unregisterFrame } from './frame-registry.ts'
 import { primeCameraFor } from './camera-broadcast.ts'
 import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
@@ -10,7 +11,7 @@ import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from
 export const HEADER = 28
 const SNAP = 12
 
-/** Live Jam working shimmer (SPEC §10): a slim 2x6 strip of tiny marver marks on the frame's left
+/** Live Jam working shimmer: a slim 2x6 strip of tiny marver marks on the frame's left
  *  flank, top-aligned - each mark twinkles on its own scattered beat, phased per frame by
  *  --mv-w0 (set on the node) so parallel frames never pulse in sync. */
 const SHIM_DELAYS = Array.from({ length: 12 }, (_, i) => {
@@ -29,7 +30,7 @@ function WorkShimmer({ belowBadge }: { belowBadge: boolean }) {
 }
 
 /**
- * One frame on the canvas. Iframe laws (spec §7): the iframe element is created once per node key
+ * One frame on the canvas. Iframe laws: the iframe element is created once per node key
  * and never remounted - theme changes go through sh:set-theme, size changes are CSS only.
  *
  * Every interactive element carries `sh-no-pan` (rzpp's panning.excluded checks the event
@@ -88,7 +89,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     registerWin()
   }, [node.key])
 
-  // SPEC-M5: register the facade <iframe> so the lean coordinator can drive its srcdoc imperatively.
+  // Register the facade <iframe> so the lean coordinator can drive its srcdoc imperatively.
   const bindLean = useCallback((el: HTMLIFrameElement | null) => { registerLeanFrame(node.key, el) }, [node.key])
   // capture a fresh lean snapshot once the frame is ready and quiet, and whenever its CONTENT changes
   // (nav). Resize needs no re-capture (the lean doc reflows) and theme needs none (attribute flip),
@@ -107,7 +108,10 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       // otherwise capture the live DOM WITH the highlight baked in and re-cover it. The
       // hostsCard rail recaptures a clean lean once the card closes.
       const c = useComments.getState()
-      const hosting = (!!c.active && c.threads.some((th) => th.id === c.active && th.nodeKey === node.key && !th.resolved)) || c.draft?.nodeKey === node.key
+      // hosting goes through the resolver (keys.ts): an adopted thread's card renders
+      // here even though its stored nodeKey names a node that no longer exists
+      const hosting = (!!c.active && c.threads.some((th) =>
+        th.id === c.active && !th.resolved && threadHostKey(th, useStore.getState().nodes) === node.key)) || c.draft?.nodeKey === node.key
       if (hosting) return
       scheduleCapture(node.key, iframe, { sourceRevision: String(node.nav ?? 0), theme: node.theme })
     }, 450)
@@ -132,7 +136,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
   }, [interact, node.key, node.nav, node.theme, node.status])
 
-  // laser mode (SPEC-M3 §7) rides the same rail; re-sent when a frame becomes ready
+  // laser mode rides the same rail; re-sent when a frame becomes ready
   // so late loaders join an already-lasered board
   const laser = useStore((s) => s.laser)
   const commentMode = useComments((s) => s.commentMode)
@@ -140,7 +144,8 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   // neighbors - each node is a stacking context, so an overflowing card would
   // otherwise paint under the next frame
   const hostsCard = useComments((s) =>
-    (!!s.active && s.threads.some((t) => t.id === s.active && t.nodeKey === node.key && !t.resolved)) || s.draft?.nodeKey === node.key)
+    (!!s.active && s.threads.some((t) =>
+      t.id === s.active && !t.resolved && threadHostKey(t, useStore.getState().nodes) === node.key)) || s.draft?.nodeKey === node.key)
   // a frame hosting an OPEN thread or a draft must show its LIVE app, not the frozen lean
   // cover: the active-element highlight lives in the live DOM and updates in real time
   // (open -> lit, close -> cleared). Without this the cover re-freezes the moment comment
@@ -199,7 +204,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
   }, [node.nav])
 
-  // ready timeout (spec §7): 10s without sh:ready -> error card with reload
+  // ready timeout: 10s without sh:ready -> error card with reload
   useEffect(() => {
     if (node.status !== 'loading') return
     const t = setTimeout(() => setStatus(node.key, 'error', 'frame never reported ready (10s)'), 10_000)
@@ -302,7 +307,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     )
   }
 
-  // variant badge (SPEC-023 §4): letter + name floating LEFT of the frame, outside the
+  // variant badge: letter + name floating LEFT of the frame, outside the
   // artwork, world-anchored (scales with zoom) with a screen-space minimum via --sh-inv
   const variantName = frame.title
     ?? cap((frame.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' '))
@@ -312,7 +317,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       className={`sh-node${selected ? ' sel' : ''}${interact ? ' interact' : ''}${working ? ' working' : ''}`}
       data-theme={node.theme}
       style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER, zIndex: hostsCard ? 30 : undefined,
-        // phase every working animation by when THIS frame's job started (SPEC §10) - parallel
+        // phase every working animation by when THIS frame's job started - parallel
         // frames pulsing in sync would read as one fake choreography
         ...(working ? { ['--mv-w0' as string]: `${-(Date.now() - (workingSince ?? Date.now()))}ms` } : {}) }}
       data-node={node.key}
@@ -327,7 +332,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         </div>
       )}
       <div className="sh-node-head sh-no-pan" onPointerDown={(e) => drag(e, 'move')} title={frame.file}>
-        {/* content frames carry their intent glyph in the chrome (SPEC-026) */}
+        {/* content frames carry their intent glyph in the chrome */}
         {frame.intent && <IntentGlyph intent={frame.intent} size={12} className="iicon sh-no-pan" aria-label={frame.intent} />}
         <span className="id sh-no-pan">{frame.title ?? frame.id}</span>
         <span className="dim sh-no-pan">{Math.round(node.w)} · {node.theme}</span>
@@ -357,7 +362,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
           onLoad={registerWin}
           style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
         />
-        {/* SPEC-M5 lean facade: a DOM-snapshot (static html, 0 JS) covering the live iframe only while
+        {/* Lean facade: a DOM-snapshot (static html, 0 JS) covering the live iframe only while
             the canvas is gesturing (CSS), so a heavy frame never flashes white mid-transform and the
             device sweep reflows correctly. sandbox WITHOUT allow-scripts = no JS runs; allow-same-origin
             so fonts/assets resolve and the shell can flip its theme + restore scroll. Never registered,

package/src/client/shell/canvas/snapshots.ts

@@ -1,5 +1,5 @@
 /**
- * SPEC-M5 slice 1: the lean-frame facade coordinator. Imperative on purpose - the facade is a
+ * The lean-frame facade coordinator. Imperative on purpose - the facade is a
  * `<iframe class="sh-lean" sandbox="allow-same-origin">` driven by setting .srcdoc directly, so no
  * FrameNode subscribes to snapshot state and a pan/zoom tick triggers zero React renders.
  *
@@ -13,7 +13,7 @@
  * INVALIDATE the lean (never mutate a displayed one - baked mermaid can't re-theme in place) and a
  * fresh capture is admitted before it is shown again. Captures run bounded-parallel, viewport-first, at idle, never while busy.
  *
- * Correctness beats the flash-guard (codex): a frame the serialiser cannot render faithfully
+ * Correctness beats the flash-guard: a frame the serialiser cannot render faithfully
  * (canvas/video/shadow-dom/cross-origin-css, or an unrestorable scroller) is left DEGRADED - no
  * `data-ready`, no cover, live pixels stay. Every install is guarded by a per-node GENERATION token
  * so an in-flight capture can never paint a stale/wrong-node cover after a reload or unmount.
@@ -87,7 +87,7 @@ function install(nodeKey: string): void {
     const doc = iframe.contentDocument
     if (!cur || !doc) return
     if (!restoreScroll(doc, cur.scrollMap)) { cur.degraded = [...cur.degraded, 'scroll']; iframe.removeAttribute('srcdoc'); return }
-    // CSP guard (codex): if a hardened host blocked the inline <style> (style-src 'self'), the lean is
+    // CSP guard: if a hardened host blocked the inline <style> (style-src 'self'), the lean is
     // unstyled - the sentinel custom prop won't resolve. Stay live rather than show an unstyled cover.
     if (getComputedStyle(doc.documentElement).getPropertyValue('--mv-lean-ok').trim() !== '1') { iframe.removeAttribute('srcdoc'); return }
     applyTheme(doc, cur.theme)