@marver-design/marver 0.5.0 → 0.7.0

package/src/client/shell/Toolbar.tsx

@@ -0,0 +1,189 @@
+/**
+ * Shared top-right toolbar pieces (prototype-review Phase 1). The canvas pill and the
+ * prototype pill render the SAME controls so they never drift: laser / comment buttons
+ * (store-level, zero coupling), a Hide-UI toggle (one shared body class), and controlled
+ * Device / Theme dropdowns whose wiring stays local to each surface (canvas mutates
+ * selection/board; play mutates play.device/theme). usePopover + Popover live here too so
+ * both App and Play share the popover chrome.
+ */
+import { createPortal } from 'react-dom'
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { useStore, CONFIG, cap } from './store.ts'
+import { useComments } from './comments-store.ts'
+import { Tip } from './Tip.tsx'
+import { CaretIcon, CheckIcon, CommentIcon, DevicesIcon, EyeSlashIcon, FrameCornersIcon, LaserIcon, MoonIcon, SunIcon, deviceIcon } from './icons.tsx'
+
+const commentsStore = () => useComments.getState()
+
+/** Shared popover machinery: trigger position, outside-click close, portal to the app
+ *  root (glass never nests - a nested backdrop-filter cannot sample the page). */
+export function usePopover() {
+  const [open, setOpen] = useState(false)
+  const [pos, setPos] = useState({ left: 0, top: 0 })
+  const boxRef = useRef<HTMLDivElement>(null)
+  const menuRef = useRef<HTMLDivElement>(null)
+  const toggle = () => {
+    if (!open && boxRef.current) {
+      const r = boxRef.current.getBoundingClientRect()
+      setPos({ left: r.left, top: r.bottom + 10 })
+    }
+    setOpen(!open)
+  }
+  useEffect(() => {
+    if (!open) return
+    const close = (e: PointerEvent) => {
+      const t = e.target as globalThis.Node
+      if (!boxRef.current?.contains(t) && !menuRef.current?.contains(t)) setOpen(false)
+    }
+    window.addEventListener('pointerdown', close)
+    return () => window.removeEventListener('pointerdown', close)
+  }, [open])
+  return { open, setOpen, pos, boxRef, menuRef, toggle }
+}
+
+export function Popover({ pop, children, dark }: { pop: ReturnType<typeof usePopover>; children: ReactNode; dark?: boolean }) {
+  const app = document.querySelector('.sh-app')
+  if (!pop.open || !app) return null
+  return createPortal(
+    <div className={`sh-menu${dark ? ' sh-menu-dark' : ''}`} ref={pop.menuRef} style={{ left: pop.pos.left, top: pop.pos.top }}>{children}</div>,
+    app,
+  )
+}
+
+// ---- Hide UI: one shared, binary body class (canvas + prototype) ---------------------
+// The state IS the body class - one source of truth for both pills, so they can never
+// desync. Not persisted, so a page refresh always restores the chrome (the safety net
+// for a forgotten shortcut). toggleHideUI is the only writer; useHideUI subscribes.
+
+const hideListeners = new Set<() => void>()
+export const isHideUI = () => document.body.classList.contains('sh-hide-ui')
+export function toggleHideUI() {
+  document.body.classList.toggle('sh-hide-ui', !isHideUI())
+  hideListeners.forEach((f) => f())
+}
+export function useHideUI() {
+  const [on, setOn] = useState(isHideUI)
+  useEffect(() => {
+    const f = () => setOn(isHideUI())
+    hideListeners.add(f)
+    return () => { hideListeners.delete(f) }
+  }, [])
+  return on
+}
+
+// ---- shared controls ----------------------------------------------------------------
+
+/** Laser toggle - store-level, identical on canvas and prototype. The per-surface code
+ *  broadcasts sh:laser to its frame(s); this only flips the flag (and drops comment mode,
+ *  since the two are one-at-a-time). */
+export function LaserButton() {
+  const laser = useStore((s) => s.laser)
+  return (
+    <Tip side="bottom" label={<><b>Laser mode</b><span>L</span></>}>
+      <button className={`sh-pill-btn${laser ? ' on' : ''}`} onClick={() => {
+        if (!laser) commentsStore().setMode(false)
+        useStore.getState().setLaser(!laser)
+      }}><LaserIcon size={16} /></button>
+    </Tip>
+  )
+}
+
+/** Comment toggle - store-level, identical on canvas and prototype. */
+export function CommentButton() {
+  const commentMode = useComments((s) => s.commentMode)
+  return (
+    <Tip side="bottom" label={<><b>Comment</b><span>C · ⇧C hides pins</span></>}>
+      <button className={`sh-pill-btn${commentMode ? ' on' : ''}`} onClick={() => {
+        const c = commentsStore()
+        if (!c.commentMode) useStore.getState().setLaser(false)
+        c.setMode(!c.commentMode)
+        useStore.getState().toast(c.commentMode ? 'comment mode off' : 'comment mode - click an element in a frame')
+      }}><CommentIcon size={16} /></button>
+    </Tip>
+  )
+}
+
+/** Hide-UI toggle - the dedicated binary control (no auto-fade, no hover-reveal). Its
+ *  tooltip carries the way back; H is the shortcut, wired per-surface. */
+export function HideUIButton() {
+  const on = useHideUI()
+  return (
+    <Tip side="bottom" label={<><b>Hide all UI</b><span>press H to reveal</span></>}>
+      <button className={`sh-pill-btn${on ? ' on' : ''}`} onClick={toggleHideUI}><EyeSlashIcon size={16} /></button>
+    </Tip>
+  )
+}
+
+/** Controlled device dropdown. `value` is the active device name ('fill' allowed when
+ *  includeFill), null = default/mixed. The trigger + menu chrome is shared; the adapter
+ *  owns what select does. */
+export function DevicePicker({ value, onSelect, includeDefault, includeFill, hint, dark }: {
+  value: string | null
+  onSelect: (name: string | null) => void
+  includeDefault?: boolean
+  includeFill?: boolean
+  hint?: ReactNode
+  dark?: boolean
+}) {
+  const pop = usePopover()
+  const entries = Object.entries(CONFIG.viewports)
+  const pick = (name: string | null) => { onSelect(name); pop.setOpen(false) }
+  const triggerIcon = value === 'fill' ? <FrameCornersIcon size={16} /> : deviceIcon(value, 16)
+  return (
+    <div className="sh-theme" ref={pop.boxRef}>
+      <Tip side="bottom" label={<><b>Device view</b>{hint && <span>{hint}</span>}</>}>
+        <button className="sh-pill-btn" onClick={pop.toggle}>
+          {triggerIcon}
+          <CaretIcon size={11} style={{ transform: pop.open ? 'rotate(180deg)' : undefined }} />
+        </button>
+      </Tip>
+      <Popover pop={pop} dark={dark}>
+        {includeDefault && <>
+          <button onClick={() => pick(null)}>
+            <DevicesIcon size={15} /><span>Default</span><kbd>0</kbd>
+            {value === null && <CheckIcon size={13} className="chk" />}
+          </button>
+          <i className="div" />
+        </>}
+        {entries.map(([name, vp], i) => (
+          <button key={name} onClick={() => pick(name)} title={`${vp.width} × ${vp.height}`}>
+            {deviceIcon(name)}<span>{cap(name)}</span><kbd>{i < 9 ? i + 1 : ''}</kbd>
+            {value === name && <CheckIcon size={13} className="chk" />}
+          </button>
+        ))}
+        {includeFill && <button onClick={() => pick('fill')}>
+          <FrameCornersIcon size={15} /><span>Fill window</span><kbd>{entries.length + 1}</kbd>
+          {value === 'fill' && <CheckIcon size={13} className="chk" />}
+        </button>}
+      </Popover>
+    </div>
+  )
+}
+
+/** Controlled theme dropdown. `value` drives the trigger (the level the picker acts on -
+ *  the scope MAJORITY on the canvas); `checked` is the menu tick and can differ (undefined
+ *  = tick `value`; null = tick nothing, e.g. a mixed selection). onSelect owns the write. */
+export function ThemePicker({ value, checked, onSelect, hint, dark }: { value: string; checked?: string | null; onSelect: (t: string) => void; hint?: ReactNode; dark?: boolean }) {
+  const pop = usePopover()
+  const pick = (t: string) => { onSelect(t); pop.setOpen(false) }
+  const tick = checked === undefined ? value : checked
+  return (
+    <div className="sh-theme" ref={pop.boxRef}>
+      <Tip side="bottom" label={<><b>Theme</b>{hint && <span>{hint}</span>}</>}>
+        <button className="sh-pill-btn" onClick={pop.toggle}>
+          {value === 'dark' ? <MoonIcon size={16} /> : <SunIcon size={16} />}
+          <CaretIcon size={11} style={{ transform: pop.open ? 'rotate(180deg)' : undefined }} />
+        </button>
+      </Tip>
+      <Popover pop={pop} dark={dark}>
+        {CONFIG.themes.map((t) => (
+          <button key={t} onClick={() => pick(t)}>
+            {t === 'dark' ? <MoonIcon size={15} /> : <SunIcon size={15} />}
+            <span>{t}</span>
+            {tick === t && <CheckIcon size={13} className="chk" />}
+          </button>
+        ))}
+      </Popover>
+    </div>
+  )
+}

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

@@ -4,6 +4,7 @@ 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.
@@ -142,7 +143,7 @@ export function Canvas() {
   const ref = useRef<ReactZoomPanPinchContentRef>(null)
   const scaleTimer = useRef(0)
 
-  useEffect(() => { startPerf() }, [])   // B0.4: frame-time sampler (window.__mvPerf)
+  useEffect(() => { startPerf(); startCameraBroadcast() }, [])   // B0.4: frame-time sampler + image-LOD camera signal
 
   useEffect(() => {
     const wrap = () => document.querySelector('.sh-canvas') as HTMLElement | null
@@ -331,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
@@ -353,6 +354,7 @@ export function Canvas() {
       // 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)
       }}

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

@@ -4,6 +4,7 @@ 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
@@ -80,7 +81,16 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     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)
+    const t = setTimeout(() => {
+      // never re-admit a cover while this frame hosts an open thread / draft: the live app
+      // must stay visible (its highlight updates in real time). A status/theme change would
+      // 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
+      if (hosting) return
+      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).
@@ -110,7 +120,22 @@ 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)) || s.draft?.nodeKey === node.key)
+    (!!s.active && s.threads.some((t) => t.id === s.active && t.nodeKey === node.key && !t.resolved)) || 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
+  // mode ends and either bakes a stale highlight or hides the live one. Mirror the interact
+  // rail: drop the cover while hosting, rebuild a fresh lean once the card closes (the
+  // highlight is cleared by then, so the recapture is clean).
+  const prevHostsCard = useRef(hostsCard)
+  useEffect(() => {
+    if (prevHostsCard.current === hostsCard) return
+    const wasHosting = prevHostsCard.current
+    prevHostsCard.current = hostsCard
+    if (hostsCard) invalidateLean(node.key)
+    else if (wasHosting && node.status === 'ready' && iframeRef.current)
+      scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
+  }, [hostsCard, node.key, node.nav, node.theme, node.status])
   useEffect(() => {
     if (node.status === 'ready' || !laser)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:laser', on: laser }, location.origin)
@@ -126,6 +151,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     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(() => {

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 */ }
+}

package/src/client/shell/icons.tsx

@@ -30,6 +30,7 @@ export const CheckIcon = icon(<path d="M229.66,77.66l-128,128a8,8,0,0,1-11.32,0l
 export const ColumnsIcon = icon(<path d="M104,32H64A16,16,0,0,0,48,48V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,104,32Zm0,176H64V48h40ZM192,32H152a16,16,0,0,0-16,16V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,192,32Zm0,176H152V48h40Z" />)
 export const ArrowUpIcon = icon(<path d="M205.66,117.66a8,8,0,0,1-11.32,0L136,59.31V216a8,8,0,0,1-16,0V59.31L61.66,117.66a8,8,0,0,1-11.32-11.32l72-72a8,8,0,0,1,11.32,0l72,72A8,8,0,0,1,205.66,117.66Z" />)
 export const CommentIcon = icon(<path d="M132,24A100.11,100.11,0,0,0,32,124v84a16,16,0,0,0,16,16h84a100,100,0,0,0,0-200Zm0,184H48V124a84,84,0,1,1,84,84Z" />)
+export const EyeSlashIcon = icon(<path d="M53.92,34.62A8,8,0,1,0,42.08,45.38L61.32,66.55C25,88.84,9.38,123.2,8.69,124.76a8,8,0,0,0,0,6.5c.35.79,8.82,19.57,27.65,38.4C61.43,194.74,93.12,208,128,208a127.11,127.11,0,0,0,52.07-11.07l22,24.21a8,8,0,1,0,11.84-10.76Zm47.33,75.84,41.67,45.85a32,32,0,0,1-41.67-45.85ZM128,192c-30.78,0-57.67-11.19-79.93-33.25A133.47,133.47,0,0,1,25,128c4.69-8.79,19.66-33.39,47.35-49.38l18,19.75a48,48,0,0,0,63.66,70l14.73,16.2A112,112,0,0,1,128,192Zm6-95.43a8,8,0,0,1,3-15.72,48.16,48.16,0,0,1,38.77,42.64,8,8,0,0,1-7.22,8.71,6.39,6.39,0,0,1-.75,0,8,8,0,0,1-8-7.26A32.09,32.09,0,0,0,134,96.57Zm113.28,34.69c-.42.94-10.55,23.37-33.36,43.8a8,8,0,1,1-10.67-11.92A132.77,132.77,0,0,0,231,128a133.15,133.15,0,0,0-23.12-30.77C185.67,75.19,158.78,64,128,64a118.37,118.37,0,0,0-19.36,1.57A8,8,0,1,1,106,49.79,134,134,0,0,1,128,48c34.88,0,66.57,13.26,91.66,38.35,18.83,18.83,27.3,37.62,27.65,38.41A8,8,0,0,1,247.31,131.26Z" />)
 export const CheckSquareOffsetIcon = icon(<path d="M224,48V208a16,16,0,0,1-16,16H136a8,8,0,0,1,0-16h72V48H48v96a8,8,0,0,1-16,0V48A16,16,0,0,1,48,32H208A16,16,0,0,1,224,48ZM125.66,154.34a8,8,0,0,0-11.32,0L64,204.69,45.66,186.34a8,8,0,0,0-11.32,11.32l24,24a8,8,0,0,0,11.32,0l56-56A8,8,0,0,0,125.66,154.34Z" />)
 export const DevicesIcon = icon(<path d="M224,72H208V64a24,24,0,0,0-24-24H40A24,24,0,0,0,16,64v96a24,24,0,0,0,24,24H152v8a24,24,0,0,0,24,24h48a24,24,0,0,0,24-24V96A24,24,0,0,0,224,72ZM40,168a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H184a8,8,0,0,1,8,8v8H176a24,24,0,0,0-24,24v72Zm192,24a8,8,0,0,1-8,8H176a8,8,0,0,1-8-8V96a8,8,0,0,1,8-8h48a8,8,0,0,1,8,8Zm-96,16a8,8,0,0,1-8,8H88a8,8,0,0,1,0-16h40A8,8,0,0,1,136,208Zm80-96a8,8,0,0,1-8,8H192a8,8,0,0,1,0-16h16A8,8,0,0,1,216,112Z" />)
 export const DeviceMobileIcon = icon(<path d="M176,16H80A24,24,0,0,0,56,40V216a24,24,0,0,0,24,24h96a24,24,0,0,0,24-24V40A24,24,0,0,0,176,16ZM72,64H184V192H72Zm8-32h96a8,8,0,0,1,8,8v8H72V40A8,8,0,0,1,80,32Zm96,192H80a8,8,0,0,1-8-8v-8H184v8A8,8,0,0,1,176,224Z" />)

package/src/client/shell/store.ts

@@ -40,12 +40,17 @@ export const CONFIG: { viewports: Record<string, { width: number; height: number
 export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
 
-/** Board names for switchers: all-scenes first, the rest sorted. Throws on transport
- *  failure - callers keep their last known list. */
+/** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
+ *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
+ *  Throws on transport failure - callers keep their last known list. */
 export async function fetchBoardNames(): Promise<string[]> {
   if (DATA) return DATA.names
-  const list: { name: string }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
-  return ['all-scenes', ...list.map((b) => b.name).filter((n) => n !== 'all-scenes').sort()]
+  const list: { name: string; order?: number }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
+  const curated = list
+    .filter((b) => b.name !== 'all-scenes')
+    .sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || a.name.localeCompare(b.name))
+    .map((b) => b.name)
+  return [...curated, 'all-scenes']
 }
 /** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
 export const boardLabel = (n: string) => humanize(n)
@@ -600,27 +605,38 @@ export const useStore = create<State>((set, get) => {
     measureNode(key, frameId, ownWidth, measuredWidth, height) {
       const s = get()
       const node = s.nodes.find((n) => n.key === key)
-      if (!node || node.sizeMode !== 'auto') return       // manual/device always win
+      // Only an explicit DEVICE viewport locks a content frame's height. 'auto' and 'manual' both
+      // auto-fit height: a content frame must always grow/shrink to show ALL its content, even after
+      // the human drags its WIDTH (SPEC-026 r4). 'manual' just means the human owns the WIDTH; the
+      // HEIGHT is still measured, so resizing width reflows and refits height (no clipped/empty frame).
+      if (!node || node.sizeMode === 'device') return
       if (node.frame !== frameId) return                  // generation guard: a reused node key
                                                           // across a board switch never mis-attributes
       const f = s.manifest?.frames.find((x) => x.id === node.frame)
       if (!f?.contentWidth) return                        // not a content frame - spoof-proofing
       if (![ownWidth, measuredWidth, height].every((v) => Number.isFinite(v) && v > 0)) return
-      const maxH = Math.round(2.5 * Math.max(844, ...Object.values(CONFIG.viewports).map((v) => v.height)))
-      // declared meta.viewport WINS over the Doc layout width - the existing precedence
-      const vpw = CONFIG.viewports[f.viewport ?? '']?.width
-      const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+      // Generous cap: a reference doc with many screenshots is legitimately very tall and must fit in
+      // FULL (this was 2.5x a viewport ~= 2700px, which clipped image-heavy docs). Still bounded so a
+      // broken measurement can't mint an infinite frame.
+      const maxH = 40000
       const H = Math.min(maxH, Math.max(80, Math.round(height)))
       const curW = Math.round(node.w)
       measuredHeights.set(`${node.frame}@${Math.round(measuredWidth)}`, H)
-      if (Math.round(measuredWidth) !== curW) return      // height not true at the applied width
-      if (W !== curW) {
-        // Doc layout changed (document<->wide): adopt the new own width first; the
-        // iframe resizes, remeasures, and the height commits on the next message
-        set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
-        scheduleReflow()
-        return
+      // AUTO owns the width too - adopt the Doc's declared/own width. MANUAL keeps the human's width
+      // and only fits the height.
+      if (node.sizeMode !== 'manual') {
+        // declared meta.viewport WINS over the Doc layout width - the existing precedence
+        const vpw = CONFIG.viewports[f.viewport ?? '']?.width
+        const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+        if (W !== curW) {
+          // Doc layout changed (document<->wide): adopt the new own width first; the
+          // iframe resizes, remeasures, and the height commits on the next message
+          set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
+          scheduleReflow()
+          return
+        }
       }
+      if (Math.round(measuredWidth) !== curW) return      // height only true at the width it was measured at
       if (Math.round(node.h) === H) return
       set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
       scheduleReflow()

package/src/client/shell/styles.css

@@ -417,7 +417,9 @@ body.sh-commenting .sh-lean { opacity: 0 }
 
 /* dropdown menu (theme) - portaled to .sh-app (its own backdrop root), left-aligned to its trigger */
 .sh-theme { position: relative }
-.sh-menu { position: absolute; min-width: 136px; z-index: 20;
+/* z above the play backdrop (.sh-play is z-30): a dropdown portals to .sh-app, so in the
+   prototype it must clear the full-window overlay or it renders behind it, invisible */
+.sh-menu { position: absolute; min-width: 136px; z-index: 40;
   border-radius: 16px; padding: 5px; display: flex; flex-direction: column;
   transform-origin: top left; animation: sh-pop .14s ease }
 @keyframes sh-pop { from { opacity: 0; transform: scale(.95) translateY(-4px) } }
@@ -643,6 +645,57 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
    divider needs a touch more air before the first chip */
 .sh-play-nav .sep + .vchip { margin-left: 5px }
 
+/* --- prototype-review: shared toolbar in play, Hide-UI, comment overlay --- */
+
+/* Hide-UI: one binary body class (canvas + prototype) drops all operating chrome. Not
+   persisted - a page refresh always restores it. Comment pins/threads (the review
+   annotations) stay; only the marver chrome hides, for a clean point-and-shoot frame. */
+body.sh-hide-ui .sh-pill,
+body.sh-hide-ui .sh-pill-fab,
+body.sh-hide-ui .sh-panel,
+body.sh-hide-ui .sh-fab,
+body.sh-hide-ui .sh-ctx,
+body.sh-hide-ui .sh-update,
+body.sh-hide-ui .sh-toasts,
+body.sh-hide-ui .sh-banner,
+body.sh-hide-ui .sh-play-nav { display: none !important }
+
+/* the prototype pill reuses the shared pill LAYOUT but wears the discreet DARK skin of the
+   bottom-left navigator (not the bright canvas glass), so it recedes into the near-black
+   stage: dark translucent fill, a faint white hairline, light-on-dark controls. */
+.sh-play-pill, .sh-play .sh-pill-fab { z-index: 32 }
+.sh-play-pill.sh-pill, .sh-play .sh-pill-fab {
+  background: rgba(18, 18, 24, .8); border: 1px solid rgba(255, 255, 255, .1);
+  backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px);
+  box-shadow: 0 8px 28px rgba(0, 0, 0, .38) }
+.sh-play-pill::after, .sh-play .sh-pill-fab::after { display: none }   /* no light edge-light overlay */
+.sh-play-pill .sh-pill-btn, .sh-play .sh-pill-fab { color: rgba(245, 245, 247, .6) }
+.sh-play-pill .sh-pill-btn:hover, .sh-play .sh-pill-fab:hover { background: rgba(255, 255, 255, .1); color: #f5f5f7 }
+.sh-play-pill .sh-pill-btn.on { background: rgba(255, 255, 255, .14); color: #f5f5f7 }
+.sh-play-pill .sep { background: rgba(255, 255, 255, .12) }
+.sh-play-pill .bd { color: rgba(245, 245, 247, .82) }
+.sh-pill-btn.bd { width: auto; gap: 6px; padding: 0 8px 0 11px; white-space: nowrap; font-weight: 600 }
+.sh-play-update { width: auto !important; gap: 5px; padding: 0 11px !important; font-size: 12px; font-weight: 600 }
+/* the picker dropdowns portal to .sh-app; in play they carry .sh-menu-dark for the dark skin */
+.sh-menu-dark { background: rgba(20, 20, 26, .97); border-color: rgba(255, 255, 255, .12); box-shadow: 0 12px 40px rgba(0, 0, 0, .5) }
+.sh-menu-dark::after { display: none }
+.sh-menu-dark button { color: rgba(245, 245, 247, .82) }
+.sh-menu-dark button:hover { background: rgba(255, 255, 255, .1) }
+.sh-menu-dark .chk { color: #6db3ff }
+.sh-menu-dark kbd { color: rgba(245, 245, 247, .5) }
+.sh-menu-dark .div { background: rgba(255, 255, 255, .1) }
+
+/* device + comment overlay share one flex-centered box; the overlay is inset:0 over it, a
+   SIBLING of the clipping .dev so a thread card is never eaten by the device's overflow.
+   overflow:visible lets a card spill past the device edge; only its markers catch the
+   pointer, the stage below stays fully interactive. */
+.sh-play-stage { position: relative; flex: none }
+/* the canvas writes --sh-inv (1/zoom) for screen-constant pins; the prototype has no
+   zoom, so neutralise it or the leaked value scales every comment pin by ~12x at overview */
+.sh-play { --sh-inv: 1 }
+.sh-play-comments { position: absolute; inset: 0; z-index: 31; overflow: visible; pointer-events: none }
+.sh-play-comments > * { pointer-events: auto }
+
 /* the current variant's name trails the chips at natural width - the chips anchor,
    so a name change grows the pill rightward without shifting any control underfoot.
    A max caps runaway titles; the Tip carries the full name. */
@@ -704,9 +757,9 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
    outline hugging the edge, 4px ring halo - in the comment green (the pin
    is already screen-space via scale(--sh-inv), so plain px match the
    frame's calc'd screen px) */
-.cm-pin.on { border-color: var(--comment);
-  outline: 2px solid var(--comment); outline-offset: -1px;
-  box-shadow: 0 0 0 4px var(--comment-ring), 0 1px 2px rgba(24,24,27,.18), 0 6px 16px -6px rgba(24,24,27,.35) }
+.cm-pin.on { border-color: var(--cm-line, var(--comment));
+  outline: 2px solid var(--cm-line, var(--comment)); outline-offset: -1px;
+  box-shadow: 0 0 0 4px var(--cm-line-ring, var(--comment-ring)), 0 1px 2px rgba(24,24,27,.18), 0 6px 16px -6px rgba(24,24,27,.35) }
 .cm-pin.orphan { border-style: dashed; opacity: .75 }
 
 /* stack: the frame-corner cluster - everyone across the frame's threads */
@@ -721,9 +774,9 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
   transform: scale(var(--sh-inv, 1)); transform-origin: top left;
   background: var(--glass); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
   /* an open card is the active selection - the frame's exact geometry, comment green */
-  color: var(--glass-ink); border-radius: 20px; border: 1px solid var(--comment);
-  outline: 2px solid var(--comment); outline-offset: -1px;
-  box-shadow: 0 0 0 4px var(--comment-ring), var(--shadow-glass), 0 16px 40px -12px rgba(24,24,27,.35);
+  color: var(--glass-ink); border-radius: 20px; border: 1px solid var(--cm-line, var(--comment));
+  outline: 2px solid var(--cm-line, var(--comment)); outline-offset: -1px;
+  box-shadow: 0 0 0 4px var(--cm-line-ring, var(--comment-ring)), var(--shadow-glass), 0 16px 40px -12px rgba(24,24,27,.35);
   display: flex; flex-direction: column; gap: 12px;
   font: 400 13px -apple-system, system-ui, sans-serif; letter-spacing: -.005em; text-align: left }
 .cm-card.flip { transform: translateX(-100%) scale(var(--sh-inv, 1)); transform-origin: top right }
@@ -760,15 +813,15 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
   font: 400 13px -apple-system, system-ui, sans-serif; outline: none;
   transition: border-color .15s, box-shadow .15s }
 .cm-compose input::placeholder { color: var(--glass-ink-3) }
-.cm-compose input:focus { border-color: var(--comment); box-shadow: 0 0 0 3px var(--comment-ring) }
+.cm-compose input:focus { border-color: var(--cm-line, var(--comment)); box-shadow: 0 0 0 3px var(--cm-line-ring, var(--comment-ring)) }
 .cm-send { position: absolute; right: 4px; top: 50%; transform: translateY(-50%);
   width: 28px; height: 28px; border-radius: 50%; border: 0; display: flex; align-items: center; justify-content: center;
-  background: var(--comment); color: #fff; cursor: pointer; transition: background .15s, opacity .15s }
+  background: var(--cm-solid, var(--comment)); color: #fff; cursor: pointer; transition: background .15s, opacity .15s }
 .cm-send:hover:not(:disabled) { filter: brightness(1.08) }
 .cm-send:disabled { background: var(--glass-ink-3); opacity: .5; cursor: default }
 /* signed-out viewer: one clear button in place of the composer */
 .cm-signin-cta { width: 100%; height: 40px; border: 0; border-radius: 999px;
-  background: var(--comment); color: #fff; cursor: pointer;
+  background: var(--cm-solid, var(--comment)); color: #fff; cursor: pointer;
   font: 600 13px -apple-system, system-ui, sans-serif; transition: filter .15s }
 .cm-signin-cta:hover { filter: brightness(1.06) }
 /* the draft composer is JUST the pill - no card chrome around a single input */

package/src/client/stage/main.tsx

@@ -14,6 +14,7 @@ import { Component, createElement, useEffect, useRef, useState, type ComponentTy
 import { flushSync } from 'react-dom'
 import { createRoot } from 'react-dom/client'
 import { frameFile, frames, layoutChain, layouts, providers } from '../frame-host/registry.ts'
+import { createInspect } from '../frame-host/inspect.js'
 
 const params = new URLSearchParams(location.search)
 // Both signals, always - same pair as the frame host: [data-theme] for attribute-keyed
@@ -24,7 +25,9 @@ document.documentElement.dataset.theme = bootTheme
 document.documentElement.classList.toggle('dark', bootTheme === 'dark')
 const startId = params.get('at') ?? ''
 
-const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
+// same-origin parent (the shell): fixed target origin so anchor bundles never leak if a
+// data-goto ever navigates the stage cross-origin
+const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, location.origin) }
 
 window.addEventListener('error', (e) => post({ type: 'sh:stage-error', message: String(e.message || e.error) }))
 window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:stage-error', message: `unhandled rejection: ${e.reason}` }))
@@ -77,6 +80,7 @@ function Stage() {
   const [err, setErr] = useState<{ id: string; message: string } | null>(null)
   const current = useRef(startId)
   const swapSeq = useRef(0)
+  const readySent = useRef(false)
 
   /** Swap to a frame. `announce` posts sh:stage-at (user-driven); history restores stay silent. */
   const goto = async (id: string, announce: boolean) => {
@@ -85,10 +89,13 @@ function Stage() {
     try {
       const next = await resolve(id)
       if (seq !== swapSeq.current) return       // a newer swap superseded this one
-      current.current = id
       // startViewTransition runs its callback async - recheck the seq there too, or an
-      // older pending transition could commit stale state over a newer navigation
-      const apply = () => { if (seq === swapSeq.current) flushSync(() => { setErr(null); setMounted(next) }) }
+      // older pending transition could commit stale state over a newer navigation.
+      // current.current is advanced INSIDE apply (once the new DOM is committed), so
+      // inspect.getId() never reports the new frame while the old DOM is still live -
+      // a pick / anchor-resolve landing mid-swap then carries the old id and the shell
+      // guards drop it instead of stamping it onto the wrong frame.
+      const apply = () => { if (seq === swapSeq.current) { flushSync(() => { setErr(null); setMounted(next) }); current.current = id } }
       if (document.startViewTransition) document.startViewTransition(apply)
       else { apply(); document.getElementById('root')?.animate([{ opacity: 0.35 }, { opacity: 1 }], { duration: 180, easing: 'ease-out' }) }
       if (announce) post({ type: 'sh:stage-at', at: id })
@@ -101,13 +108,27 @@ function Stage() {
     }
   }
 
+  // sh:stage-ready fires ONCE, after the first frame actually commits to the DOM (not when
+  // goto is merely scheduled) - the shell re-drives the review highlight on it, which must
+  // resolve against a live document
+  useEffect(() => {
+    if (mounted && !readySent.current) { readySent.current = true; post({ type: 'sh:stage-ready', at: current.current }) }
+  }, [mounted])
+
   useEffect(() => {
     goto(startId, false)
-    post({ type: 'sh:stage-ready', at: startId })
+
+    // laser / comment-pick / anchor / highlight - the SAME controller the canvas
+    // frames run, so review works identically in the prototype. getId reports the
+    // CURRENT frame (the stage swaps in place). It self-installs its own listeners;
+    // we only borrow modeActive() to keep a review click from ALSO navigating.
+    const inspect = createInspect({ post, getId: () => current.current })
 
     // data-goto is handled HERE, in place - never posted up as sh:go (capture phase
-    // beats any frame handler; preventDefault stops real <a href> navigations)
+    // beats any frame handler; preventDefault stops real <a href> navigations). A
+    // laser/comment click owns the press instead - it must not navigate.
     const onClick = (e: MouseEvent) => {
+      if (inspect.modeActive()) return
       const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
       if (!el) return
       e.preventDefault()
@@ -118,19 +139,21 @@ function Stage() {
     document.addEventListener('click', onClick, true)
 
     const onKey = (e: KeyboardEvent) => {
-      // Escape always exits, even mid-typing (matches the canvas bridge)
-      if (e.key === 'Escape') { post({ type: 'sh:stage-exit' }); return }
       if ((e.metaKey || e.ctrlKey) && e.key === '/') { e.preventDefault(); post({ type: 'sh:stage-key', key: '/', code: e.code, meta: true }); return }
       if (e.metaKey || e.ctrlKey) return       // ⌘D is the browser's bookmark, not our theme
+      // Escape always reaches the shell, even mid-typing: it decides (cancel a
+      // comment/laser first, else exit) - the stage can't see review mode
+      if (e.key === 'Escape') { post({ type: 'sh:stage-key', key: 'Escape', code: e.code }); return }
       if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return
-      // every play shortcut belongs to the shell (it owns walk order + chrome) - forward
-      if (/^Digit[0-9]$/.test(e.code) || ['d', 'h', 'r', '[', ']', 'ArrowRight', 'ArrowLeft'].includes(e.key))
+      // every play shortcut belongs to the shell (it owns walk order + chrome) - forward.
+      // l/c toggle laser/comment, C (shift+c) hides pins; the shell acts and broadcasts back.
+      if (/^Digit[0-9]$/.test(e.code) || ['d', 'h', 'r', 'l', 'c', 'C', '[', ']', 'ArrowRight', 'ArrowLeft'].includes(e.key))
         post({ type: 'sh:stage-key', key: e.key, code: e.code })
     }
     window.addEventListener('keydown', onKey)
 
     const onMsg = (e: MessageEvent) => {
-      if (e.source !== window.parent) return
+      if (e.source !== window.parent || (e.origin && e.origin !== location.origin)) return
       const data = e.data
       if (data?.type === 'sh:set-theme') {
         document.documentElement.dataset.theme = data.theme
@@ -144,6 +167,7 @@ function Stage() {
       document.removeEventListener('click', onClick, true)
       window.removeEventListener('keydown', onKey)
       window.removeEventListener('message', onMsg)
+      inspect.dispose()
     }
   }, [])