@marver-design/marver 0.4.0 → 0.5.0

package/src/client/frame-host/serialize.ts

@@ -0,0 +1,195 @@
+// SPEC-M5 slice 1: the DOM-snapshot serializer. Turns a live, same-origin frame Document into a
+// self-contained STATIC html string: post-render DOM + full inlined CSS (styleSheets +
+// adoptedStyleSheets), JS stripped. Rendered in a `sandbox="allow-same-origin"` (NO allow-scripts)
+// iframe srcdoc, it reflows / theme-flips / device-sweeps with the browser's own layout engine and
+// the app's own stylesheet - so color is identical (same tokens, no raster) and layout is real CSS.
+//
+// Runs in the SHELL (same origin as every frame), reading the live iframe's contentDocument directly
+// - no bridge round-trip. Fail soft: any throw returns a `degraded` result the coordinator refuses to
+// show. Correctness beats the flash-guard: a frame we cannot serialise faithfully stays live.
+
+export interface ScrollEntry { sel: string; top: number; left: number }
+export interface SerializeResult {
+  html: string
+  scrollMap: ScrollEntry[]          // native scrollers to restore shell-side after load
+  degraded: string[]                // 'canvas' | 'video' | 'shadow-dom' | 'cross-origin-css' | 'js-layout'
+  notes: string[]
+  cssBytes: number
+}
+
+const STRIP_TAGS = new Set(['SCRIPT', 'NOSCRIPT'])
+
+/** Absolutize relative url() in a sheet's cssText against that sheet's href (codex P1: consolidating
+ *  rules into one <style> moves the url() base from each sheet to the srcdoc base). */
+function absolutizeUrls(css: string, sheetHref: string | null): string {
+  if (!sheetHref) return css
+  return css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (m, q, ref: string) => {
+    if (/^(data:|https?:|blob:|#|\/)/i.test(ref) || !ref.trim()) return m
+    try { return `url(${q}${new URL(ref, sheetHref).href}${q})` } catch { return m }
+  })
+}
+
+/** Serialise one sheet's rules, recursing into same-origin @import (so imported CSS is inlined, not
+ *  left as an invalid mid-list @import pointing at an un-inlined sheet). Bumps `xo` on any unreadable
+ *  (cross-origin) sheet or import so the caller can degrade. */
+function rulesText(rules: CSSRuleList, href: string | null, xo: { n: number }): string {
+  let text = ''
+  for (const r of Array.from(rules)) {
+    if (r.type === 3 /* CSSRule.IMPORT_RULE */) {
+      const imp = r as CSSImportRule & { supportsText?: string; layerName?: string | null }
+      const sheet = imp.styleSheet
+      if (!sheet) { xo.n++; continue }
+      let inner: string
+      try { inner = rulesText(sheet.cssRules, sheet.href ?? href, xo) } catch { xo.n++; continue }
+      // preserve the import's conditions - flattening them makes a conditional (e.g. desktop-only,
+      // layered, feature-gated) sheet globally active and mis-render the lean.
+      if (imp.layerName != null) inner = `@layer${imp.layerName ? ' ' + imp.layerName : ''}{\n${inner}\n}`
+      if (imp.supportsText) inner = `@supports (${imp.supportsText}){\n${inner}\n}`
+      const m = imp.media?.mediaText
+      if (m && m !== 'all') inner = `@media ${m}{\n${inner}\n}`
+      text += inner
+      continue
+    }
+    text += r.cssText + '\n'
+  }
+  return absolutizeUrls(text, href)
+}
+
+/** Collect every CSS rule the document renders with: <style>/<link> sheets (recursing @import) AND
+ *  constructable adoptedStyleSheets. Cross-origin sheets throw on .cssRules - record + degrade (never
+ *  claim fidelity). Honours per-sheet media (`<link media=print>`) and skips disabled sheets. */
+function collectCss(doc: Document, degraded: string[], notes: string[]): string {
+  const chunks: string[] = []
+  const xo = { n: 0 }
+  const dump = (sheet: CSSStyleSheet, href: string | null, label: string) => {
+    if (sheet.disabled) return
+    let rules: CSSRuleList | null = null
+    try { rules = sheet.cssRules } catch { xo.n++; return }
+    if (!rules) return
+    const text = rulesText(rules, href, xo)
+    if (!text) return
+    const media = sheet.media?.mediaText
+    chunks.push(`/* ${label} */\n${media && media !== 'all' ? `@media ${media}{\n${text}\n}` : text}`)
+  }
+  for (const s of Array.from(doc.styleSheets)) dump(s as CSSStyleSheet, s.href, s.href ?? 'inline')
+  const adopted = (doc as Document & { adoptedStyleSheets?: CSSStyleSheet[] }).adoptedStyleSheets ?? []
+  adopted.forEach((s, i) => dump(s, null, `adopted[${i}]`))
+  if (xo.n) { degraded.push('cross-origin-css'); notes.push(`${xo.n} cross-origin stylesheet(s)/import(s) unreadable`) }
+  if (adopted.length) notes.push(`${adopted.length} adoptedStyleSheet(s) inlined`)
+  return chunks.join('\n')
+}
+
+/** A stable-ish selector for restoring scroll in the identical-structure lean doc. */
+function selectorFor(el: Element): string {
+  const seg: string[] = []
+  for (let cur: Element | null = el; cur && cur !== el.ownerDocument.documentElement; cur = cur.parentElement) {
+    if (cur.id) { seg.unshift(`#${CSS.escape(cur.id)}`); break }
+    const tag = cur.tagName.toLowerCase()
+    let n = 1
+    for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling) if (sib.tagName === cur.tagName) n++
+    seg.unshift(`${tag}:nth-of-type(${n})`)
+  }
+  return seg.join('>')
+}
+
+/** Strip execution + inline handlers from the clone; flag content that cannot reflow as DOM. */
+function scrub(root: Element, doc: Document, degraded: string[]): void {
+  root.querySelectorAll('script, noscript, link[rel~="modulepreload"], link[rel~="preload"], link[rel~="stylesheet"]').forEach((n) => n.remove())
+  const walk = doc.createTreeWalker(root, NodeFilter.SHOW_ELEMENT)
+  const flag = { canvas: false, video: false, nested: false }
+  for (let el = walk.currentNode as Element | null; el; el = walk.nextNode() as Element | null) {
+    for (const attr of Array.from(el.attributes)) {
+      if (/^on/i.test(attr.name)) el.removeAttribute(attr.name)
+      else if (/^\s*javascript:/i.test(attr.value)) el.removeAttribute(attr.name)
+    }
+    const tag = el.tagName
+    if (tag === 'CANVAS') flag.canvas = true
+    if (tag === 'VIDEO') flag.video = true
+    // a nested iframe/object/embed can't reflow in a scriptless clone (blank/stale, and would
+    // re-fetch third-party content) - degrade to live rather than ship a broken lean.
+    if (tag === 'IFRAME' || tag === 'OBJECT' || tag === 'EMBED') flag.nested = true
+    if (STRIP_TAGS.has(tag)) el.remove()
+  }
+  if (flag.canvas) degraded.push('canvas')
+  if (flag.video) degraded.push('video')
+  if (flag.nested) degraded.push('nested-frame')
+}
+
+/** Open shadow roots must be detected on the ORIGINAL tree - cloneNode(true) drops them, so the clone
+ *  can never reveal them. A frame with any shadow DOM (open here, or closed via the boot-time flag)
+ *  degrades to live rather than shipping a lean copy missing its shadow content. */
+function hasOpenShadow(doc: Document): boolean {
+  const walk = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_ELEMENT)
+  for (let el = walk.currentNode as Element | null; el; el = walk.nextNode() as Element | null)
+    if ((el as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot) return true
+  return false
+}
+
+/** Copy live form PROPERTIES (value/checked/selected) into the clone. They are runtime state, not
+ *  attributes, so cloneNode never carries them - without this a re-captured frame shows empty inputs
+ *  and unchecked boxes. Original and clone share structure, so we pair them in document order.
+ *  tagName/type checks (not instanceof) because the clone nodes are owned by the frame's realm. */
+function syncFormState(doc: Document, clone: HTMLElement): void {
+  const live = doc.querySelectorAll('input, textarea, option')
+  const dst = clone.querySelectorAll('input, textarea, option')
+  live.forEach((src, i) => {
+    const d = dst[i]
+    if (!d || d.tagName !== src.tagName) return
+    if (src.tagName === 'INPUT') {
+      const s = src as HTMLInputElement
+      // never bake a password into the retained snapshot html; a file input can't be reconstructed
+      if (s.type === 'password' || s.type === 'file') { d.removeAttribute('value'); return }
+      if (s.type === 'checkbox' || s.type === 'radio') s.checked ? d.setAttribute('checked', '') : d.removeAttribute('checked')
+      else d.setAttribute('value', s.value)
+    } else if (src.tagName === 'TEXTAREA') { d.textContent = (src as HTMLTextAreaElement).value }
+    else if (src.tagName === 'OPTION') { (src as HTMLOptionElement).selected ? d.setAttribute('selected', '') : d.removeAttribute('selected') }
+  })
+}
+
+/**
+ * Serialize a live same-origin Document into a static, self-contained html string.
+ * @param doc       the live frame document (same origin - we read its cssRules directly)
+ * @param baseHref  the frame's real URL, injected as <base> so relative url()/img/font resolve
+ */
+export function serializeDoc(doc: Document, baseHref: string): SerializeResult {
+  const notes: string[] = []
+  const degraded: string[] = []
+
+  // shadow DOM (open detected on the original tree, closed via the boot-time attachShadow flag):
+  // either kind degrades the frame to live - cloneNode cannot carry a shadow root.
+  const win = doc.defaultView as (Window & { __mvClosedShadow?: boolean }) | null
+  if (win?.__mvClosedShadow || hasOpenShadow(doc)) { degraded.push('shadow-dom'); notes.push('shadow root(s) present') }
+
+  const css = collectCss(doc, degraded, notes)
+  const cssBytes = new Blob([css]).size
+
+  // scroll offsets to restore shell-side (native scrollers; a virtualised one that fails to resolve
+  // OR whose offset does not stick re-degrades the frame in the coordinator). != 0 catches RTL/negative.
+  const scrollMap: ScrollEntry[] = []
+  for (const el of Array.from(doc.querySelectorAll<HTMLElement>('*'))) {
+    if (el.scrollTop !== 0 || el.scrollLeft !== 0) scrollMap.push({ sel: selectorFor(el), top: el.scrollTop, left: el.scrollLeft })
+  }
+  const de = doc.documentElement
+  if (de.scrollTop !== 0 || de.scrollLeft !== 0) scrollMap.push({ sel: ':root', top: de.scrollTop, left: de.scrollLeft })
+
+  // clone the RENDERED dom (React's committed output = authored markup that reflows under CSS)
+  const html = doc.documentElement.cloneNode(true) as HTMLElement
+  scrub(html, doc, degraded)
+  syncFormState(doc, html)
+
+  // head: <meta charset> + <base> (relative url()/img/font resolve against the real frame URL) +
+  // ONE inlined stylesheet (both themes, all media queries). Drop the clone's own style nodes.
+  const head = html.querySelector('head') ?? html.insertBefore(doc.createElement('head'), html.firstChild)
+  head.querySelectorAll('style').forEach((n) => n.remove())
+  // sentinel first rule: the coordinator checks --mv-lean-ok resolves before showing the lean. If a
+  // hardened host's CSP (style-src 'self') blocked this inline <style>, the sentinel is absent and the
+  // frame stays live rather than showing an unstyled cover.
+  const style = doc.createElement('style'); style.textContent = ':root{--mv-lean-ok:1}\n' + css
+  const base = doc.createElement('base'); base.setAttribute('href', baseHref)
+  const meta = doc.createElement('meta'); meta.setAttribute('charset', 'utf-8')
+  head.insertBefore(style, head.firstChild)
+  head.insertBefore(base, head.firstChild)
+  head.insertBefore(meta, head.firstChild)
+
+  return { html: '<!doctype html>\n' + html.outerHTML, scrollMap, degraded: Array.from(new Set(degraded)), notes, cssBytes }
+}

package/src/client/shell/App.tsx

@@ -1,9 +1,10 @@
 import { Component, useEffect, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useStore, CONFIG, PUBLISHED, boardLabel, cap, fetchBoardNames, type FrameEntry } from './store.ts'
+import { useStore, CONFIG, PUBLISHED, boardLabel, 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'
+import { frameByWindow } from './canvas/frame-registry.ts'
 import { enterPlay, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
 import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, ColumnsIcon, CommentIcon, DevicesIcon, FrameRectIcon, IntentGlyph, LaserIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
@@ -23,7 +24,7 @@ function SceneGroup({ name, count, held, onPick, children }: { name: string; cou
       <button className={`it${held ? ' held' : ''}`} onClick={() => setOpen(!open)}>
         <CaretIcon size={11} className="tw" style={{ transform: open ? undefined : 'rotate(-90deg)' }} />
         {/* the NAME selects every frame in the scene; the caret/row still collapses */}
-        <span onClick={(e) => { if (!onPick) return; e.stopPropagation(); onPick() }}>{cap(name) || '(root)'}</span>
+        <span onClick={(e) => { if (!onPick) return; e.stopPropagation(); onPick() }}>{humanize(name) || '(root)'}</span>
         <small>{count}</small>
       </button>
       {open && children}
@@ -200,7 +201,7 @@ function SelectionBar() {
         </Tip>
       ))}
       <i className="sep" />
-      <Tip label={<><b>{multi ? `Copy ${selection.length} file paths` : 'Copy file path'}</b><span className="k">C</span></>}>
+      <Tip label={<><b>{multi ? `Copy ${selection.length} file paths` : 'Copy file path'}</b><span className="k">⇧P</span></>}>
         <button className="icon"
           onClick={() => { navigator.clipboard.writeText(selectedFrames().map((f) => f.file).join('\n')); toast(multi ? `${selection.length} file paths copied` : 'file path copied') }}><SignpostIcon size={15} /></button>
       </Tip>
@@ -379,8 +380,19 @@ function ThemeMenu() {
 }
 
 export function App() {
-  const { manifest, nodes, panelOpen, toasts, selection, laser } = useStore()
+  // B0.1: per-field selectors, NOT `useStore()` (which subscribes to the whole store and
+  // re-rendered the entire shell on every setScale tick during a pan/zoom).
+  const manifest = useStore((s) => s.manifest)
+  const nodes = useStore((s) => s.nodes)
+  const panelOpen = useStore((s) => s.panelOpen)
+  const toasts = useStore((s) => s.toasts)
+  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
+  // 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)
 
@@ -501,6 +513,13 @@ export function App() {
   useEffect(() => {
     if (!import.meta.hot) return
     import.meta.hot.on('sh:manifest', (m: any) => applyManifest(m))
+    // A7 controlled HMR: a frame file changed. Reload exactly the affected frames through the
+    // lease-aware path (idle frames now, leased ones deferred to a safe point) - never a shell
+    // reload, never a React Fast Refresh yanking a frame the user is in.
+    import.meta.hot.on('sh:frame-invalidated', (m: any) => {
+      const frameIds = Array.isArray(m?.frameIds) ? m.frameIds.filter((x: unknown) => typeof x === 'string') : []
+      if (frameIds.length && typeof m?.revision === 'string') useStore.getState().invalidateFrames(frameIds, m.revision)
+    })
     // 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).
@@ -521,11 +540,11 @@ export function App() {
     const onMsg = (e: MessageEvent) => {
       const data = e.data
       if (!data || typeof data.type !== 'string' || !data.type.startsWith('sh:')) return
-      const iframes = [...document.querySelectorAll('iframe')]
-      const el = iframes.find((f) => f.contentWindow === e.source) as HTMLIFrameElement | undefined
-      if (!el) return
-      const nodeKey = el.closest('[data-node]')?.getAttribute('data-node')
-      if (!nodeKey) return
+      // B0.3: O(1) registry lookup - also the security gate (unknown source = not a
+      // registered frame = dropped), replacing a per-message iframe scan + DOM walk.
+      const reg = frameByWindow(e.source)
+      if (!reg) return
+      const { key: nodeKey, iframe: el } = reg
       const s = useStore.getState()
 
       if (data.type === 'sh:ready') {
@@ -579,6 +598,29 @@ export function App() {
         // 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)
+      } 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).
+        if (s.play || s.interact === nodeKey) return
+        const nums = [data.deltaX, data.deltaY, data.clientX, data.clientY].map(Number)
+        if (!nums.every(Number.isFinite)) return
+        const [deltaX, deltaY, localX, localY] = nums
+        const rect = el.getBoundingClientRect()
+        // iframe-local (untransformed CSS px) -> shell-screen px: rect is the frame's
+        // transformed size, so rect.width/clientWidth is its effective on-screen scale.
+        // Plain rect.left+localX would put the zoom origin in the wrong place when zoomed.
+        const sx = el.clientWidth ? rect.width / el.clientWidth : 1
+        const sy = el.clientHeight ? rect.height / el.clientHeight : 1
+        canvasCtl.wheel({
+          deltaX, deltaY, deltaMode: Number(data.deltaMode) || 0,
+          ctrlKey: !!data.ctrlKey, metaKey: !!data.metaKey,
+          clientX: rect.left + localX * sx, clientY: rect.top + localY * sy,
+        })
+      } else if (data.type === 'sh:interaction') {
+        // A6: the frame reports transient laser/comment engagement (pointer inside + mode on).
+        // While engaged the frame is leased, so a hot update to it defers until disengage.
+        s.setExternalLease(nodeKey, 'laser', !!data.laser)
+        s.setExternalLease(nodeKey, 'comment', !!data.comment)
       }
     }
     window.addEventListener('message', onMsg)
@@ -609,7 +651,7 @@ export function App() {
         s.setLaser(!s.laser)
       }
       // C = comment mode (SPEC-M3 §6, the Figma/Miro convention) · Shift+C = hide/show
-      // pins · copy-file-paths moved to Y (changelog 0.4.0)
+      // 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()
         if (!c.commentMode) s.setLaser(false)
@@ -617,7 +659,7 @@ export function App() {
         toast(c.commentMode ? 'comment mode off' : 'comment mode - click an element in a frame')
       }
       if (e.key === 'C' && e.shiftKey) { const c = commentsStore(); c.setShow(!c.show) }
-      if (e.key === 'y' && s.selection.length) {
+      if (e.key === 'P' && e.shiftKey && s.selection.length) {
         const files = s.selection
           .map((k) => { const n = s.nodes.find((x) => x.key === k); return n ? s.frameFor(n)?.file : undefined })
           .filter((f): f is string => !!f)
@@ -702,8 +744,14 @@ export function App() {
           mounted so collapse/expand can crossfade-morph between them */}
       <aside className={`sh-panel${panelOpen ? '' : ' closed'}`} aria-hidden={!panelOpen}>
           <div className="sh-panel-top">
-            <ParallelogramDuoIcon size={21} className="mark" />
-            <span className="name">Marver</span>
+            {/* 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}>
+                <ParallelogramDuoIcon size={21} className="mark" />
+              </a>
+            </Tip>
+            <span className="name" title={CONFIG.projectName || 'Marver'}>{CONFIG.projectName ? humanize(CONFIG.projectName) : 'Marver'}</span>
             <Tip side="bottom" label={<><b>Collapse panel</b><span>⌘\</span></>}><button className="sh-ibtn" onClick={togglePanel} tabIndex={panelOpen ? 0 : -1}><PanelFilledIcon size={17} /></button></Tip>
           </div>
           <div className="sh-panel-scroll">

package/src/client/shell/Comments.tsx

@@ -157,7 +157,7 @@ function ThreadCard({ thread, at, node }: { thread: Thread; at: { x: number; y:
     if (sent.trim() && await useComments.getState().replyOk(thread.id, sent)) setText((cur) => (cur === sent ? '' : cur))
   }
   return (
-    <div className={`cm-card sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, node.h - 40) }}
+    <div data-sh-wheel-local className={`cm-card sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, node.h - 40) }}
       onPointerDown={(e) => e.stopPropagation()} onClick={(e) => e.stopPropagation()} onWheel={(e) => e.stopPropagation()}>
       {/* thread-level actions pin to the card corner, out of the header's flow -
           the name row never has to share its line with them */}
@@ -227,7 +227,7 @@ function DraftComposer({ at, node }: { at: { x: number; y: number }; node: Node
   useEffect(() => { ref.current?.focus() }, [])
   const flip = at.x > node.w * 0.55
   return (
-    <div className={`cm-card cm-draft sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, node.h - 40) }}
+    <div data-sh-wheel-local className={`cm-card cm-draft sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, node.h - 40) }}
       onPointerDown={(e) => e.stopPropagation()} onClick={(e) => e.stopPropagation()}>
       <div className="cm-compose">
         <div className="cm-inputwrap">
@@ -453,9 +453,10 @@ export function CommentsController() {
     return () => window.removeEventListener('hashchange', onHash)
   }, [])
 
-  // broadcast pick mode to every frame (laser rides along inside the bridge)
+  // 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.
   useEffect(() => {
-    for (const f of document.querySelectorAll('iframe'))
+    for (const f of document.querySelectorAll('iframe.sh-live'))
       (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode }, location.origin)
   }, [commentMode])
 

package/src/client/shell/Play.tsx

@@ -120,6 +120,12 @@ function BoardMenu({ current }: { current: string }) {
 function PlayInner() {
   const play = useStore((s) => s.play)
   const board = useStore((s) => s.board)
+  // A6/A7: a controlled frame edit while play is open never auto-reloads the live stage
+  // (that would destroy the user's session mid-prototype). It records playUpdateRevision;
+  // we surface an "Update ready" affordance, and applyPlayUpdate bumps playNav to reload
+  // the stage at its current position on an explicit click.
+  const playUpdateRevision = useStore((s) => s.playUpdateRevision)
+  const playNav = useStore((s) => s.playNav)
   const iframeRef = useRef<HTMLIFrameElement>(null)
   // the src is frozen at mount - navigation happens INSIDE the stage; device and theme
   // changes must never reload it (a phone does not remount when you flip dark mode)
@@ -143,6 +149,16 @@ function PlayInner() {
 
   const postStage = (msg: Record<string, unknown>) => iframeRef.current?.contentWindow?.postMessage(msg, '*')
 
+  // apply a deferred update: reload the stage iframe at its CURRENT frame + theme on a fresh
+  // rev-stamped URL. sh:stage-ready replays position; device size is shell-owned.
+  useEffect(() => {
+    if (!playNav || !iframeRef.current) return
+    const p = useStore.getState().play
+    if (!p) return
+    iframeRef.current.src = `${ROUTE}/stage/?at=${encodeURIComponent(p.at)}&theme=${encodeURIComponent(p.theme)}&r=${playNav}`
+  }, [playNav])
+  const applyUpdate = () => useStore.getState().applyPlayUpdate()
+
   const exit = () => {
     const { at } = useStore.getState().play ?? {}
     useStore.getState().setPlay(null)
@@ -378,6 +394,14 @@ function PlayInner() {
             </button>
           </Tip>
         ))}
+        {playUpdateRevision && (
+          <>
+            <i className="sep" />
+            <Tip inv side="bottom" label={<><b>Update ready</b><span>an edit landed - reload this prototype</span></>}>
+              <button className="sh-play-update" onClick={applyUpdate}><ReloadIcon size={13} /><span>Update</span></button>
+            </Tip>
+          </>
+        )}
         <i className="sep" />
         <Tip inv side="bottom" label={<><b>Collapse toolbar</b><span>H hides everything</span><span className="k">⌘/</span></>}>
           <button onClick={() => setChrome('collapsed')}>

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

@@ -2,6 +2,7 @@ import { useEffect, useRef } from 'react'
 import { TransformWrapper, TransformComponent, type ReactZoomPanPinchContentRef } from 'react-zoom-pan-pinch'
 import { CONFIG, useStore } from '../store.ts'
 import { bootHash } from '../hash.ts'
+import { startPerf } from '../perf.ts'
 import { FrameNode, HEADER } from './FrameNode.tsx'
 
 /**
@@ -82,12 +83,20 @@ export function animateLayout(ms = 360) {
   presetTimer = window.setTimeout(() => w.classList.remove('sh-preset'), ms)
 }
 
+/** B0.2: one wheel event, whatever its origin - a shell-document wheel over the canvas, or
+ *  a wheel forwarded from a passive frame's iframe. clientX/Y are shell-viewport pixels. */
+export interface CanvasWheelInput {
+  deltaX: number; deltaY: number; deltaMode: number
+  ctrlKey: boolean; metaKey: boolean; clientX: number; clientY: number
+}
+
 export const canvasCtl = {
   fitNode(_key: string) {},
   fitNodes(_keys: string[]) {},
   fitAll() {},
   zoomTo(_scale: number) {},
   zoom100() { canvasCtl.zoomTo(1) },
+  wheel(_input: CanvasWheelInput) {},
 }
 
 /** Variant-group captions (SPEC-023 §4): "Landing · 3 variants" above each group with
@@ -131,6 +140,9 @@ export function Canvas() {
   const gesture = useStore((s) => s.gesture)
   const setScale = useStore((s) => s.setScale)
   const ref = useRef<ReactZoomPanPinchContentRef>(null)
+  const scaleTimer = useRef(0)
+
+  useEffect(() => { startPerf() }, [])   // B0.4: frame-time sampler (window.__mvPerf)
 
   useEffect(() => {
     const wrap = () => document.querySelector('.sh-canvas') as HTMLElement | null
@@ -231,41 +243,55 @@ export function Canvas() {
     return () => el.removeEventListener('pointerdown', down)
   }, [])
 
-  // Zoom curve: rzpp's wheel zoom is ADDITIVE in scale - a constant scale amount per
-  // pinch, which reads as sluggish when zoomed in and runaway when zoomed out (zoom is
-  // perceptually logarithmic). So ctrl/meta wheels (trackpad pinch arrives as ctrl-wheel
-  // in Chrome; cmd+scroll folds in too) are intercepted on an ANCESTOR of the wrapper -
-  // guaranteed to run before rzpp's own listener - and applied as an exponential step:
-  // constant ratio per finger distance, uniform feel at every zoom level.
+  // B0.2: the shell is the SINGLE wheel-camera owner. rzpp's wheel-pan is disabled (below);
+  // both entry paths - a shell-document wheel over the canvas, and a wheel forwarded from a
+  // passive frame's iframe (sh:wheel) - feed one applyCanvasWheel. Plain wheel pans (mirrors
+  // rzpp's old position-delta math); ctrl/meta wheel zooms about the cursor on an exponential
+  // curve (constant ratio per finger distance - uniform feel at every zoom, unlike rzpp's
+  // additive step). setTransform drives onTransformed, which repaints the grid.
   useEffect(() => {
     const app = document.querySelector('.sh-app') as HTMLElement | null
-    const el = document.querySelector('.sh-canvas') as HTMLElement | null
-    if (!app || !el) return
+    const canvas = document.querySelector('.sh-canvas') as HTMLElement | null
+    if (!app || !canvas) return
     let settle = 0
-    const onWheel = (e: WheelEvent) => {
-      if (!e.ctrlKey && !e.metaKey) return
-      if (!(e.target as HTMLElement | null)?.closest?.('.sh-canvas')) return
-      e.preventDefault()
-      e.stopImmediatePropagation()
+    const beginGesture = (panning: boolean) => {
+      // sh-camera = a CANVAS pan/zoom (drives the snapshot cover); sh-gesturing also drops iframe
+      // pointer-events. A frame click/drag sets only sh-gesturing, so it never flashes a snapshot.
+      document.getElementById('sh-world')?.classList.add('sh-gesturing', 'sh-camera')
+      document.body.classList.toggle('sh-panning', panning)
+      clearTimeout(settle)
+      settle = window.setTimeout(() => {
+        document.getElementById('sh-world')?.classList.remove('sh-gesturing', 'sh-camera')
+        document.body.classList.remove('sh-panning')
+      }, 160)
+    }
+    const applyCanvasWheel = (w: CanvasWheelInput) => {
       const inst = ref.current
-      if (!inst) return
+      if (!inst || useStore.getState().play) return
       const { positionX, positionY, scale } = inst.instance.transformState
-      // exponent scales with input; per-event ratio capped so a discrete mouse-wheel
-      // notch (|deltaY| ~100) stays controllable while trackpad streams pass through
-      const f = Math.min(1.4, Math.max(1 / 1.4, Math.exp(-e.deltaY * 0.0075 * (CONFIG.zoomSpeed ?? 1))))
+      const zooming = w.ctrlKey || w.metaKey
+      beginGesture(!zooming)
+      if (!zooming) { inst.setTransform(positionX - w.deltaX, positionY - w.deltaY, scale, 0, 'linear'); return }
+      const f = Math.min(1.4, Math.max(1 / 1.4, Math.exp(-w.deltaY * 0.0075 * (CONFIG.zoomSpeed ?? 1))))
       const next = Math.min(2, Math.max(0.05, scale * f))
       if (next === scale) return
+      const r = canvas.getBoundingClientRect()
+      const cx = w.clientX - r.left, cy = w.clientY - r.top
       const k = next / scale
-      const r = el.getBoundingClientRect()
-      const cx = e.clientX - r.left, cy = e.clientY - r.top
-      // rzpp's zoom callbacks never fire on setTransform - manage the gesture class here
-      document.getElementById('sh-world')?.classList.add('sh-gesturing')
-      clearTimeout(settle)
-      settle = window.setTimeout(() => document.getElementById('sh-world')?.classList.remove('sh-gesturing'), 160)
       inst.setTransform(cx - (cx - positionX) * k, cy - (cy - positionY) * k, next, 0, 'linear')
     }
+    canvasCtl.wheel = applyCanvasWheel
+    const onWheel = (e: WheelEvent) => {
+      const t = e.target as HTMLElement | null
+      if (!t?.closest?.('.sh-canvas')) return
+      if (t.closest('[data-sh-wheel-local]')) return   // escape hatch for scrollable shell UI in-canvas
+      e.preventDefault()
+      e.stopImmediatePropagation()
+      applyCanvasWheel({ deltaX: e.deltaX, deltaY: e.deltaY, deltaMode: e.deltaMode,
+        ctrlKey: e.ctrlKey, metaKey: e.metaKey, clientX: e.clientX, clientY: e.clientY })
+    }
     app.addEventListener('wheel', onWheel, { capture: true, passive: false })
-    return () => { app.removeEventListener('wheel', onWheel, { capture: true }); clearTimeout(settle) }
+    return () => { canvasCtl.wheel = () => {}; app.removeEventListener('wheel', onWheel, { capture: true }); clearTimeout(settle) }
   }, [])
 
   // space-pan: hold space, drag anywhere - nodes drop pointer-events so the canvas takes the drag
@@ -289,12 +315,14 @@ export function Canvas() {
     }
   }, [])
 
+  const camera = (on: boolean) => {
+    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing', 'sh-camera')
+  }
   const pan = (on: boolean) => () => {
-    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing')
+    camera(on)
     document.body.classList[on ? 'add' : 'remove']('sh-panning')
   }
-  const zoom = (on: boolean) => () =>
-    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing')
+  const zoom = (on: boolean) => () => camera(on)
 
   // no initialPosition props on the wrapper: rzpp applies them ASYNC after mount and
   // stomps the boot fit when data is inlined (published builds) - the boot fit owns
@@ -312,13 +340,22 @@ export function Canvas() {
       // ctrl/meta wheel zoom never reaches rzpp (exponential curve above); pinch.step
       // only serves real touch-screen pinch.
       wheel={{ wheelDisabled: true, step: 0.225 * (CONFIG.zoomSpeed ?? 1) }}
-      panning={{ wheelPanning: true, velocityDisabled: true, excluded: ['sh-no-pan'], disabled: gesture }}
+      // B0.2: rzpp no longer owns wheel-pan (the shell's applyCanvasWheel does, so it works
+      // over passive frames and forwarded from iframes too). excluded still governs pointer-drag.
+      panning={{ wheelPanning: false, velocityDisabled: true, excluded: ['sh-no-pan'], disabled: gesture }}
       pinch={{ step: 7.5 * (CONFIG.zoomSpeed ?? 1) }}
       onPanningStart={pan(true)}
       onPanningStop={pan(false)}
       onZoomStart={zoom(true)}
       onZoomStop={zoom(false)}
-      onTransformed={(r) => { setScale(r.state.scale); paintGrid(r.state.positionX, r.state.positionY, r.state.scale) }}
+      // B0.1: the grid repaints live via CSS vars (no React), but the store scale - which
+      // only the zoom-% badge reads - commits after the transform SETTLES, so no React
+      // re-render happens per tick during a pan/zoom.
+      onTransformed={(r) => {
+        paintGrid(r.state.positionX, r.state.positionY, r.state.scale)
+        clearTimeout(scaleTimer.current)
+        scaleTimer.current = window.setTimeout(() => setScale(r.state.scale), 120)
+      }}
       onInit={(r) => paintGrid(r.state.positionX, r.state.positionY, r.state.scale)}
     >
       <TransformComponent wrapperClass="sh-canvas" contentClass="sh-content">