@marver-design/marver 0.4.0 → 0.6.0

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)
 
@@ -391,12 +403,21 @@ export function App() {
   useEffect(() => {
     if (booted) return
     booted = true
-    if (bootHash.board && bootHash.board !== useStore.getState().board)
-      useStore.setState({ board: bootHash.board, boardAuto: bootHash.board === 'all-scenes' })
-    boot().then((ok) => {
+    const start = async () => {
+      if (bootHash.board) {
+        if (bootHash.board !== useStore.getState().board)   // a deep link wins
+          useStore.setState({ board: bootHash.board, boardAuto: bootHash.board === 'all-scenes' })
+      } else if (!PUBLISHED) {
+        // fresh open, no deep link: LAND on the first curated board (a tight, fast board = a good first
+        // impression) instead of the auto all-scenes everything-board, which renders every frame at once.
+        const first = (await fetchBoardNames().catch(() => [] as string[])).find((n) => n !== 'all-scenes')
+        if (first && first !== useStore.getState().board) useStore.setState({ board: first, boardAuto: false })
+      }
+      const ok = await boot()
       urlReady.current = true
-      if (ok && bootHash.play) enterPlay(bootHash.play)   // #/p/<board> alone = board start
-    })
+      if (ok && bootHash.play) enterPlay(bootHash.play)     // #/p/<board> alone = board start
+    }
+    void start()
   }, [])
 
   // the URL is a projection of state: design views replace in place; entering play and
@@ -501,6 +522,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 +549,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 +607,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 +660,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 +668,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 +753,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,7 +2,9 @@ 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'
+import { startCameraBroadcast, setCameraScale } from './camera-broadcast.ts'
 
 /**
  * The world. rzpp owns pan/zoom; nodes are absolutely positioned children of #sh-world.
@@ -82,12 +84,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 +141,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(); startCameraBroadcast() }, [])   // B0.4: frame-time sampler + image-LOD camera signal
 
   useEffect(() => {
     const wrap = () => document.querySelector('.sh-canvas') as HTMLElement | null
@@ -231,41 +244,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 +316,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
@@ -303,7 +332,7 @@ export function Canvas() {
     <TransformWrapper
       ref={ref}
       minScale={0.05}
-      maxScale={2}
+      maxScale={5}
       limitToBounds={false}
       doubleClick={{ disabled: true }}
       // wheelDisabled is load-bearing: rzpp's onWheelPanning is a no-op without it, and
@@ -312,13 +341,23 @@ 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)
+        setCameraScale(r.state.scale)   // keep the LOD's settle-scale current (cheap number write, no React)
+        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">

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

@@ -1,8 +1,11 @@
-import { memo, useEffect, useRef } from 'react'
+import { memo, useCallback, useEffect, useRef } from 'react'
 import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
 import { CopyIcon, IntentGlyph, ReloadIcon, XIcon } from '../icons.tsx'
 import { CommentLayer } from '../Comments.tsx'
 import { useComments } from '../comments-store.ts'
+import { registerFrame, unregisterFrame } from './frame-registry.ts'
+import { primeCameraFor } from './camera-broadcast.ts'
+import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
 
 export const HEADER = 28
 const SNAP = 12
@@ -20,7 +23,9 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const frame = useStore((s) => s.frameFor(node))
   const selected = useStore((s) => s.selection.includes(node.key))
   const interact = useStore((s) => s.interact === node.key)
-  const scale = useStore((s) => s.scale)
+  // B0.1: no reactive scale subscription - it re-rendered every FrameNode on every
+  // pan/zoom tick. gestureScale below measures the world rect (the canonical source,
+  // Law G-5); the stored scale is only a never-hit fallback, read lazily at drag time.
   const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, setGesture, toast } = useStore.getState()
   const iframeRef = useRef<HTMLIFrameElement>(null)
   const themeRef = useRef(node.theme)
@@ -30,13 +35,73 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   if (frame && initialSrc.current === null) initialSrc.current = frameUrl(frame, node.theme)
   const fileRef = useRef(frame ? `${frame.kind}:${frame.file}` : null)
 
-  // theme switch without remount
+  // theme switch without remount: the live iframe flips via message (no navigation). The lean is
+  // INVALIDATED (not mutated) - a baked mermaid SVG can't be re-themed in place, so we drop it, show
+  // live while it re-renders in the new theme, and the capture effect (theme is a dep) rebuilds a
+  // fresh lean that is only shown once ready. No light-on-dark flash.
   useEffect(() => {
     if (themeRef.current !== node.theme) {
       themeRef.current = node.theme
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:set-theme', theme: node.theme }, '*')
+      invalidateLean(node.key)
     }
-  }, [node.theme])
+  }, [node.theme, node.key])
+
+  // B0.3: register this frame's WindowProxy so the shell routes its messages in O(1)
+  // (source window -> node), instead of rescanning every iframe + walking the DOM per
+  // message. Registration runs SYNCHRONOUSLY through the ref callback (P1): a fast static
+  // HTML frame or an immediate boot failure can post sh:ready/sh:error before a passive
+  // effect would run, and the registry is the security gate that would otherwise drop it
+  // as an unknown source (misleading 10s timeout). The WindowProxy is stable across
+  // navigations; onLoad re-asserts it (idempotent) after each navigation.
+  const regWin = useRef<WindowProxy | null>(null)
+  const registerWin = () => {
+    const iframe = iframeRef.current
+    const win = iframe?.contentWindow
+    if (!iframe || !win || regWin.current === win) return
+    regWin.current = win
+    registerFrame(win, { key: node.key, iframe })
+  }
+  const bindIframe = useCallback((el: HTMLIFrameElement | null) => {
+    if (regWin.current && (!el || el.contentWindow !== regWin.current)) { unregisterFrame(regWin.current); regWin.current = null }
+    iframeRef.current = el
+    registerWin()
+  }, [node.key])
+
+  // SPEC-M5: 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),
+  // so neither is a dep - keeping captures rare. Never during a gesture; the coordinator serialises.
+  useEffect(() => {
+    // capture reads the live iframe's same-origin document - true in dev AND publish (published frames
+    // are bundled same-origin and served by `marver serve`), so the lean tier works in both via this
+    // client-side capture. Fail-soft: a frame that can't serialise stays live (publish == today's
+    // behaviour in the worst case). No headless build step / heavy dependency needed.
+    if (node.status !== 'ready' || node.missing) return
+    const iframe = iframeRef.current
+    if (!iframe) return
+    const t = setTimeout(() => scheduleCapture(node.key, iframe, { sourceRevision: String(node.nav ?? 0), theme: node.theme }), 450)
+    return () => clearTimeout(t)
+    // node.theme IS a dep: baked content (mermaid SVG) can't be re-themed by the cover's attribute
+    // flip, so a theme change re-captures after the live frame re-renders (key includes theme).
+  }, [node.status, node.nav, node.key, node.missing, node.theme])
+  useEffect(() => () => dropSnapshot(node.key), [node.key])   // drop the snapshot on unmount
+  // a reload / file-swap / error takes the frame out of 'ready': drop its cover so a stale picture
+  // never lingers (nav may not bump on a same-file reload). The next 'ready' re-captures.
+  useEffect(() => { if (node.status !== 'ready') dropSnapshot(node.key) }, [node.status, node.key])
+  // LEAN-PRIMARY focus handoff: entering interact shows the live app (drop the now-stale lean at
+  // once); leaving it recaptures the live frame's CURRENT state (the user may have typed/toggled)
+  // and only swaps back to lean once that fresh capture is admitted. force=true: same nav/theme.
+  const prevInteract = useRef(interact)
+  useEffect(() => {
+    if (prevInteract.current === interact) return
+    const wasInteract = prevInteract.current
+    prevInteract.current = interact
+    if (interact) invalidateLean(node.key)
+    else if (wasInteract && node.status === 'ready' && iframeRef.current)
+      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
   // so late loaders join an already-lasered board
@@ -56,6 +121,17 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (node.status === 'ready' || !commentMode)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:pick', on: commentMode }, location.origin)
   }, [commentMode, node.status])
+  // B0.2: the interact target owns its own wheel (app scrolls); passive frames forward
+  // wheel to the canvas. Replayed on ready like laser/pick so a reload restores truth.
+  useEffect(() => {
+    if (node.status === 'ready' || !interact)
+      iframeRef.current?.contentWindow?.postMessage({ type: 'sh:interactive', on: interact }, location.origin)
+  }, [interact, node.status])
+  // image-LOD: once the frame is ready its content listener is live, so send the settled zoom - a static
+  // board that never gets a gesture then still sharpens its images from the cheap low-res first paint.
+  useEffect(() => {
+    if (node.status === 'ready') primeCameraFor(iframeRef.current?.contentWindow)
+  }, [node.status])
 
   // a frame whose FILE actually changed (e.g. tsx -> html swap, same id) must renavigate
   useEffect(() => {
@@ -94,7 +170,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     const world = document.getElementById('sh-world')!
     // Law G-5: measured scale, never stored zoom state. #sh-world is 1px wide by design,
     // so its rendered rect width IS the scale (survives browser page-zoom too).
-    const gestureScale = world.getBoundingClientRect().width || scale || 1
+    const gestureScale = world.getBoundingClientRect().width || useStore.getState().scale || 1
     const start = { x: e.clientX, y: e.clientY, nx: node.x, ny: node.y, nw: node.w, nh: node.h }
     // group drag: moving any member moves the whole selection by the same delta
     const st = useStore.getState()
@@ -105,10 +181,21 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         if (n) groupStarts[k] = { x: n.x, y: n.y }
       }
     }
-    world.classList.add('sh-gesturing')
-    setGesture(true)
+    // Defer sh-gesturing (and its `will-change: transform` on .sh-content) until an ACTUAL drag
+    // begins - a bare click otherwise promotes then demotes the compositor layer, re-rasterising
+    // the frame's text at a fractional zoom = the "jiggle". A pure click now never toggles it.
+    let gesturing = false
+    const begin = () => {
+      if (gesturing) return
+      gesturing = true
+      world.classList.add('sh-gesturing')   // drops iframe pointer-events (sh-camera is NOT set, so no cover)
+      setGesture(true)
+    }
+    const MOVE_THRESHOLD = 3   // px in screen space before a press counts as a drag
 
     const onMove = (ev: PointerEvent) => {
+      if (!gesturing && Math.hypot(ev.clientX - start.x, ev.clientY - start.y) < MOVE_THRESHOLD) return
+      begin()
       const dx = (ev.clientX - start.x) / gestureScale
       const dy = (ev.clientY - start.y) / gestureScale
       if (mode === 'move') {
@@ -213,11 +300,20 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
           </div>
         ) : null}
         <iframe
-          ref={iframeRef}
+          ref={bindIframe}
+          className="sh-live"
           src={initialSrc.current ?? frameUrl(frame, node.theme)}
           title={frame.id}
+          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
+            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,
+            never messaged, pointer-events:none - it is NOT the live iframe (role: .sh-lean).
+            Rendered in dev AND publish (runtime client-side capture; frames are same-origin in both). */}
+        <iframe ref={bindLean} className="sh-lean" sandbox="allow-same-origin" title="" aria-hidden tabIndex={-1} />
         {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
             need the mouse INSIDE the frame for hover highlights, so it steps aside
             (drag still works via the header) */}

package/src/client/shell/canvas/camera-broadcast.ts

@@ -0,0 +1,44 @@
+// Tells every content frame when the canvas camera starts and stops moving, so each frame's image-LOD
+// (content/img-lod.ts) can freeze its bitmaps during motion and sharpen to the settled zoom afterwards.
+//
+// Fires ONCE per gesture, never per animation frame - it watches the single #sh-world.sh-camera class
+// that EVERY camera path (rzpp zoom/pan, wheel, pinch, programmatic setTransform) toggles, so one hook
+// covers them all. Posting a message to 150 frames every tick would be its own jank; two posts per
+// gesture (start, settle) is free.
+
+let lastScale = 1
+/** Fed live from onTransformed so `settle` always broadcasts the final zoom. Cheap (a number write). */
+export function setCameraScale(s: number): void { if (s > 0) lastScale = s }
+
+function frameWindows(): Window[] {
+  const out: Window[] = []
+  for (const f of document.querySelectorAll<HTMLIFrameElement>('#sh-world iframe'))
+    if (f.contentWindow) out.push(f.contentWindow)
+  return out
+}
+
+function broadcast(moving: boolean): void {
+  const msg = moving ? { type: 'sh:camera', moving: true } : { type: 'sh:camera', moving: false, scale: lastScale }
+  for (const w of frameWindows()) { try { w.postMessage(msg, location.origin) } catch { /* cross-doc timing */ } }
+}
+
+let started = false
+export function startCameraBroadcast(): void {
+  if (started) return
+  const world = document.getElementById('sh-world'); if (!world) return
+  started = true
+  let moving = false
+  new MutationObserver(() => {
+    const now = world.classList.contains('sh-camera')
+    if (now === moving) return
+    moving = now
+    broadcast(now)   // +sh-camera -> freeze; -sh-camera -> sharpen to the settled scale
+  }).observe(world, { attributes: true, attributeFilter: ['class'] })
+}
+
+/** Prime ONE freshly-ready frame with the current settled scale, so a static board that is never zoomed
+ *  still sharpens from its cheap low-res first paint to the right resolution. */
+export function primeCameraFor(win: Window | null | undefined): void {
+  if (!win) return
+  try { win.postMessage({ type: 'sh:camera', moving: false, scale: lastScale }, location.origin) } catch { /* timing */ }
+}