@marver-design/marver 0.2.0

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

@@ -0,0 +1,285 @@
+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 { FrameNode, HEADER } from './FrameNode.tsx'
+
+/**
+ * The world. rzpp owns pan/zoom; nodes are absolutely positioned children of #sh-world.
+ *
+ * Interaction model (Figma conventions):
+ *   two-finger scroll = pan · ctrl/cmd+scroll or pinch = zoom · space+drag or middle-drag = pan
+ *   dragging a frame moves the FRAME ONLY - `excluded` classes plus the store gesture
+ *   flag keep rzpp's native listeners out of it (React stopPropagation fires too late:
+ *   rzpp listens on its wrapper, below React's delegation root in the bubble path).
+ *
+ * Iframe laws: render order = store order (append-only, never sorted); will-change only during
+ * gestures (G-3); iframes lose pointer-events during any gesture (G-4).
+ */
+
+/**
+ * Fit centers content in the space the chrome leaves free, measured live at fit time:
+ * the open sidebar (or its collapsed FAB) claims a left column, the pill row claims a
+ * top band, and the screen-space selection bar needs headroom above the fitted content.
+ * Measuring instead of hardcoding keeps every fit trigger (shift+1/2, device presets,
+ * board switch) correct whether the sidebar is open or collapsed.
+ */
+const GAP = 32
+const BAR = 56
+function insets(el: HTMLElement) {
+  const c = el.getBoundingClientRect()
+  const rect = (q: string) => document.querySelector(q)?.getBoundingClientRect()
+  const side = rect('.sh-panel:not(.closed)') ?? rect('.sh-fab')
+  const pill = rect('.sh-pill')
+  return {
+    left: (side ? Math.max(0, side.right - c.left) : 0) + GAP,
+    right: GAP + 16,
+    top: (pill ? Math.max(0, pill.bottom - c.top) : 0) + 12 + BAR,
+    bottom: GAP + 16,
+  }
+}
+
+/**
+ * World-space dot grid (sense-of-scale, the Figma/tldraw recipe): the grid pans and
+ * zooms with the content, and its pitch re-quantizes in octaves so the on-screen
+ * spacing always lands in [14, 28)px - zooming out doubles the world spacing instead
+ * of dissolving into noise. Alpha fades across the octave so level switches don't pop.
+ * Painted via CSS vars on the wrapper - no React re-render per frame.
+ */
+const GRID = 20
+function paintGrid(positionX: number, positionY: number, scale: number) {
+  const el = document.querySelector('.sh-canvas') as HTMLElement | null
+  if (!el) return
+  let step = GRID * scale
+  while (step < 14) step *= 2
+  while (step >= 28) step /= 2
+  const t = (step - 14) / 14
+  el.style.setProperty('--grid-size', `${step}px ${step}px`)
+  el.style.setProperty('--grid-pos', `${positionX % step}px ${positionY % step}px`)
+  el.style.setProperty('--grid-alpha', (0.35 + 0.65 * Math.min(1, t)).toFixed(3))
+  // screen-space overlays (selection bar) position themselves from these - no re-render per frame
+  const app = document.querySelector('.sh-app') as HTMLElement | null
+  if (app) {
+    app.style.setProperty('--sh-s', String(scale))
+    app.style.setProperty('--sh-inv', String(1 / scale))   // world-units-per-screen-px, for zoom-invariant strokes
+    app.style.setProperty('--sh-tx', `${positionX}px`)
+    app.style.setProperty('--sh-ty', `${positionY}px`)
+  }
+}
+
+/**
+ * Preset transitions: device resizes and tidy moves are store mutations that commit in
+ * one React render - instant, jarring jumps. Arming this class right before the mutation
+ * lets the nodes ease to their new size/position on the same duration+curve the camera
+ * fit uses, so frames and viewport travel together. Drags stay direct (class absent).
+ */
+let presetTimer = 0
+export function animateLayout(ms = 360) {
+  const w = document.getElementById('sh-world')
+  if (!w) return
+  w.classList.add('sh-preset')
+  clearTimeout(presetTimer)
+  presetTimer = window.setTimeout(() => w.classList.remove('sh-preset'), ms)
+}
+
+export const canvasCtl = {
+  fitNode(_key: string) {},
+  fitNodes(_keys: string[]) {},
+  fitAll() {},
+  zoomTo(_scale: number) {},
+  zoom100() { canvasCtl.zoomTo(1) },
+}
+
+export function Canvas() {
+  const nodes = useStore((s) => s.nodes)
+  const gesture = useStore((s) => s.gesture)
+  const setScale = useStore((s) => s.setScale)
+  const ref = useRef<ReactZoomPanPinchContentRef>(null)
+
+  useEffect(() => {
+    const wrap = () => document.querySelector('.sh-canvas') as HTMLElement | null
+    // focus=true (selection fits): center on the TRUE viewport center for a proper focus
+    // state, then clamp back into the chrome-free band only if the content would slide
+    // under the sidebar or pill. Small frames land dead center; wide selections degrade
+    // to band-centering. fitAll stays band-centered - there everything must be visible.
+    const fitRect = (x: number, y: number, w: number, h: number, focus = false) => {
+      const el = wrap()
+      if (!el || !ref.current) return
+      const p = insets(el)
+      const vw = el.clientWidth, vh = el.clientHeight
+      const aw = vw - p.left - p.right
+      const ah = vh - p.top - p.bottom
+      const scale = Math.max(0.05, Math.min(1, aw / w, ah / h))
+      let px = p.left + (aw - w * scale) / 2
+      let py = p.top + (ah - h * scale) / 2
+      if (focus) {
+        // clamp order matters: left/top win when the band is tighter than the content
+        px = Math.max(Math.min((vw - w * scale) / 2, vw - p.right - w * scale), p.left)
+        py = Math.max(Math.min((vh - h * scale) / 2, vh - p.bottom - h * scale), p.top)
+      }
+      ref.current.setTransform(px - x * scale, py - y * scale, scale, 320, 'easeOut')
+    }
+    canvasCtl.fitNode = (key: string) => {
+      const n = useStore.getState().nodes.find((x) => x.key === key)
+      if (n) fitRect(n.x, n.y, n.w, n.h + HEADER, true)
+    }
+    const fitKeys = (keys: string[], focus: boolean) => {
+      const sel = new Set(keys)
+      const ns = useStore.getState().nodes.filter((n) => sel.has(n.key))
+      if (!ns.length) return
+      const x0 = Math.min(...ns.map((n) => n.x)), y0 = Math.min(...ns.map((n) => n.y))
+      const x1 = Math.max(...ns.map((n) => n.x + n.w)), y1 = Math.max(...ns.map((n) => n.y + n.h + HEADER))
+      fitRect(x0, y0, x1 - x0, y1 - y0, focus)
+    }
+    canvasCtl.fitNodes = (keys: string[]) => fitKeys(keys, true)
+    canvasCtl.fitAll = () => fitKeys(useStore.getState().nodes.map((n) => n.key), false)
+    canvasCtl.zoomTo = (target: number) => {
+      const el = wrap(), inst = ref.current
+      if (!el || !inst) return
+      const { positionX, positionY, scale } = inst.instance.transformState
+      const cx = el.clientWidth / 2, cy = el.clientHeight / 2
+      const k = target / scale   // zoom about the viewport center
+      inst.setTransform(cx - (cx - positionX) * k, cy - (cy - positionY) * k, target, 250, 'easeOut')
+    }
+  }, [])
+
+  // first load opens on the whole board (same as ⇧1) - the default 100% transform is an
+  // arbitrary top-left crop. A deep link with a selection (#/b/x?n=...) restores it and
+  // fits the camera to it instead. Runs once, on the first frame batch; board switches
+  // refit through their own path.
+  const booted = useRef(false)
+  useEffect(() => {
+    if (booted.current || nodes.length === 0) return
+    booted.current = true
+    const fit = () => {
+      const keys = (bootHash.n ?? []).filter((k) => useStore.getState().nodes.some((n) => n.key === k))
+      if (keys.length) {
+        useStore.setState({ selection: keys })
+        canvasCtl.fitNodes(keys)
+      } else canvasCtl.fitAll()
+    }
+    requestAnimationFrame(() => {
+      fit()
+      // published builds boot fast enough that rzpp's own init can land AFTER this fit
+      // and stomp it back to the identity transform - one verification pass re-fits
+      setTimeout(() => {
+        const st = ref.current?.instance.transformState
+        if (st && st.scale === 1 && st.positionX === 0 && st.positionY === 0) fit()
+      }, 150)
+    })
+  }, [nodes])
+
+  // click on empty canvas = deselect + exit interact (Figma convention; also covers the
+  // double-click-outside exit). Bound on the wrapper, NOT #sh-world - the world element is
+  // 1px by design, so empty-canvas clicks never hit it.
+  useEffect(() => {
+    const el = document.querySelector('.sh-canvas') as HTMLElement | null
+    if (!el) return
+    const down = (e: PointerEvent) => {
+      const t = e.target as HTMLElement | null
+      if (t?.closest('.sh-node')) return
+      const s = useStore.getState()
+      if (s.selection.length || s.interact) s.select(null)
+    }
+    el.addEventListener('pointerdown', down)
+    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.
+  useEffect(() => {
+    const app = document.querySelector('.sh-app') as HTMLElement | null
+    const el = document.querySelector('.sh-canvas') as HTMLElement | null
+    if (!app || !el) 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 inst = ref.current
+      if (!inst) 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 next = Math.min(2, Math.max(0.05, scale * f))
+      if (next === scale) return
+      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')
+    }
+    app.addEventListener('wheel', onWheel, { capture: true, passive: false })
+    return () => { app.removeEventListener('wheel', onWheel, { capture: true }); clearTimeout(settle) }
+  }, [])
+
+  // space-pan: hold space, drag anywhere - nodes drop pointer-events so the canvas takes the drag
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.code !== 'Space' || e.repeat) return
+      const t = e.target as HTMLElement
+      if (t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement) return
+      e.preventDefault()
+      document.body.classList.add('sh-space')
+    }
+    const up = (e: KeyboardEvent) => { if (e.code === 'Space') document.body.classList.remove('sh-space') }
+    const drop = () => document.body.classList.remove('sh-space')
+    window.addEventListener('keydown', down)
+    window.addEventListener('keyup', up)
+    window.addEventListener('blur', drop)
+    return () => {
+      window.removeEventListener('keydown', down)
+      window.removeEventListener('keyup', up)
+      window.removeEventListener('blur', drop)
+    }
+  }, [])
+
+  const pan = (on: boolean) => () => {
+    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing')
+    document.body.classList[on ? 'add' : 'remove']('sh-panning')
+  }
+  const zoom = (on: boolean) => () =>
+    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing')
+
+  // 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
+  // the first camera, and until it lands the default (0,0,1) is a known sentinel
+  return (
+    <TransformWrapper
+      ref={ref}
+      minScale={0.05}
+      maxScale={2}
+      limitToBounds={false}
+      doubleClick={{ disabled: true }}
+      // wheelDisabled is load-bearing: rzpp's onWheelPanning is a no-op without it, and
+      // ctrlKey wheels (pinch, ctrl/cmd+scroll via the rewrite above) still zoom
+      // wheelDisabled is load-bearing: rzpp's onWheelPanning is a no-op without it.
+      // 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 }}
+      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) }}
+      onInit={(r) => paintGrid(r.state.positionX, r.state.positionY, r.state.scale)}
+    >
+      <TransformComponent wrapperClass="sh-canvas" contentClass="sh-content">
+        <div id="sh-world">
+          {nodes.map((n) => <FrameNode key={n.key} node={n} />)}
+        </div>
+      </TransformComponent>
+    </TransformWrapper>
+  )
+}

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

@@ -0,0 +1,194 @@
+import { memo, useEffect, useRef } from 'react'
+import { frameUrl, useStore, CONFIG, type Node } from '../store.ts'
+import { CopyIcon, ReloadIcon, XIcon } from '../icons.tsx'
+
+export const HEADER = 28
+const SNAP = 12
+
+/**
+ * One frame on the canvas. Iframe laws (spec §7): the iframe element is created once per node key
+ * and never remounted - theme changes go through sh:set-theme, size changes are CSS only.
+ *
+ * Every interactive element carries `sh-no-pan` (rzpp's panning.excluded checks the event
+ * TARGET's classList, nothing else), and drags additionally raise the store gesture flag,
+ * which hard-disables canvas panning for the duration. Both are needed: the class stops the
+ * pan before it starts, the flag covers targets we missed.
+ */
+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)
+  const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, setGesture, toast } = useStore.getState()
+  const iframeRef = useRef<HTMLIFrameElement>(null)
+  const themeRef = useRef(node.theme)
+  // src is frozen at mount: theme changes ride sh:set-theme (never navigation), so
+  // frame state (forms, scroll, dialogs) survives a theme flip. Real file changes below.
+  const initialSrc = useRef<string | null>(null)
+  if (frame && initialSrc.current === null) initialSrc.current = frameUrl(frame, node.theme)
+  const fileRef = useRef(frame ? `${frame.kind}:${frame.file}` : null)
+
+  // theme switch without remount
+  useEffect(() => {
+    if (themeRef.current !== node.theme) {
+      themeRef.current = node.theme
+      iframeRef.current?.contentWindow?.postMessage({ type: 'sh:set-theme', theme: node.theme }, '*')
+    }
+  }, [node.theme])
+
+  // a frame whose FILE actually changed (e.g. tsx -> html swap, same id) must renavigate
+  useEffect(() => {
+    if (!frame) return
+    const sig = `${frame.kind}:${frame.file}`
+    if (fileRef.current !== null && fileRef.current !== sig && iframeRef.current) {
+      setStatus(node.key, 'loading')
+      iframeRef.current.src = frameUrl(frame, node.theme)
+    }
+    fileRef.current = sig
+  }, [frame?.kind, frame?.file])
+
+  // ready timeout (spec §7): 10s without sh:ready -> error card with reload
+  useEffect(() => {
+    if (node.status !== 'loading') return
+    const t = setTimeout(() => setStatus(node.key, 'error', 'frame never reported ready (10s)'), 10_000)
+    return () => clearTimeout(t)
+  }, [node.status, node.key, setStatus])
+
+  const drag = (e: React.PointerEvent, mode: 'move' | 'e' | 's' | 'se') => {
+    e.stopPropagation()
+    if (e.button !== 0) return
+    // shift-click toggles multi-selection instead of dragging (Figma convention)
+    if (e.shiftKey && mode === 'move') { select(node.key, true); return }
+    if (!(selected && useStore.getState().selection.length > 1)) select(node.key)
+    const el = e.currentTarget as HTMLElement
+    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 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()
+    const groupStarts: Record<string, { x: number; y: number }> = {}
+    if (mode === 'move' && st.selection.includes(node.key)) {
+      for (const k of st.selection) {
+        const n = st.nodes.find((x) => x.key === k)
+        if (n) groupStarts[k] = { x: n.x, y: n.y }
+      }
+    }
+    world.classList.add('sh-gesturing')
+    setGesture(true)
+
+    const onMove = (ev: PointerEvent) => {
+      const dx = (ev.clientX - start.x) / gestureScale
+      const dy = (ev.clientY - start.y) / gestureScale
+      if (mode === 'move') {
+        if (Object.keys(groupStarts).length > 1) moveSelectedBy(dx, dy, groupStarts)
+        else moveNode(node.key, start.nx + dx, start.ny + dy)
+      }
+      else {
+        let w = mode !== 's' ? start.nw + dx : start.nw
+        const h = mode !== 'e' ? start.nh + dy : start.nh
+        for (const vp of Object.values(CONFIG.viewports)) if (Math.abs(w - vp.width) < SNAP) w = vp.width
+        resizeNode(node.key, w, h)
+      }
+    }
+    // One idempotent teardown for every exit path - stuck gestures are the acceptance test.
+    let finished = false
+    const done = () => {
+      if (finished) return
+      finished = true
+      try { el.releasePointerCapture(e.pointerId) } catch { /* already released */ }
+      world.classList.remove('sh-gesturing')
+      setGesture(false)
+      el.removeEventListener('pointermove', onMove)
+      el.removeEventListener('pointerup', done)
+      el.removeEventListener('pointercancel', done)
+      el.removeEventListener('lostpointercapture', done)
+      window.removeEventListener('blur', done)
+    }
+    try { el.setPointerCapture(e.pointerId) } catch { setGesture(false); world.classList.remove('sh-gesturing'); return }
+    el.addEventListener('pointermove', onMove)
+    el.addEventListener('pointerup', done)
+    el.addEventListener('pointercancel', done)
+    el.addEventListener('lostpointercapture', done)
+    window.addEventListener('blur', done)
+  }
+
+  const gone = !frame || node.missing
+  // Spec §7: a deleted frame's node stays, with a card, until the user removes it. Explicit beats magic.
+  if (gone) {
+    return (
+      <div className={`sh-node${selected ? ' sel' : ''}`}
+        style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER }}
+        data-node={node.key}>
+        <div className="sh-node-head sh-no-pan" onPointerDown={(e) => drag(e, 'move')}>
+          <span className="id sh-no-pan">{node.frame}</span><span className="dim sh-no-pan">deleted</span>
+        </div>
+        <div className="sh-node-body" style={{ height: node.h }}>
+          <div className="sh-card warn sh-no-pan">
+            <b>file deleted</b>
+            <span className="dim">{node.frame}</span>
+            <span className="row">
+              <button className="sh-no-pan" onClick={() => useStore.getState().removeNode(node.key)}>
+                <XIcon size={12} /> remove from board
+              </button>
+            </span>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className={`sh-node${selected ? ' sel' : ''}${interact ? ' interact' : ''}`}
+      data-theme={node.theme}
+      style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER }}
+      data-node={node.key}
+    >
+      <div className="sh-node-head sh-no-pan" onPointerDown={(e) => drag(e, 'move')} title={frame.file}>
+        <span className="id sh-no-pan">{frame.title ?? frame.id}</span>
+        <span className="dim sh-no-pan">{Math.round(node.w)} · {node.theme}</span>
+      </div>
+
+      <div className="sh-node-body" style={{ height: node.h }}>
+        {node.status === 'error' ? (
+          <div className="sh-card err sh-no-pan">
+            <b>frame failed</b>
+            <span className="msg">{node.error}</span>
+            <span className="dim">{frame.file}</span>
+            <span className="row">
+              <button className="sh-no-pan" onClick={() => { setStatus(node.key, 'loading'); iframeRef.current && (iframeRef.current.src = frameUrl(frame, node.theme)) }}>
+                <ReloadIcon size={12} /> reload
+              </button>
+              <button className="sh-no-pan" onClick={() => { navigator.clipboard.writeText(`${frame.file}: ${node.error}`); toast('error copied for agent') }}>
+                <CopyIcon size={12} /> copy for agent
+              </button>
+            </span>
+          </div>
+        ) : null}
+        <iframe
+          ref={iframeRef}
+          src={initialSrc.current ?? frameUrl(frame, node.theme)}
+          title={frame.id}
+          style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
+        />
+        {!interact && (
+          <div
+            className="sh-overlay sh-no-pan"
+            onPointerDown={(e) => drag(e, 'move')}
+            onDoubleClick={(e) => { e.stopPropagation(); setInteract(node.key) }}
+          />
+        )}
+      </div>
+
+      {selected && (
+        <>
+          <div className="sh-handle e sh-no-pan" onPointerDown={(e) => drag(e, 'e')} />
+          <div className="sh-handle s sh-no-pan" onPointerDown={(e) => drag(e, 's')} />
+          <div className="sh-handle se sh-no-pan" onPointerDown={(e) => drag(e, 'se')} />
+        </>
+      )}
+    </div>
+  )
+})

package/src/client/shell/favicon/site.webmanifest

@@ -0,0 +1,11 @@
+{
+  "name": "Marver",
+  "short_name": "Marver",
+  "icons": [
+    { "src": "/__mv/favicon/android-chrome-192x192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/__mv/favicon/android-chrome-512x512.png", "sizes": "512x512", "type": "image/png" }
+  ],
+  "theme_color": "#0088ff",
+  "background_color": "#e7e9ef",
+  "display": "standalone"
+}

package/src/client/shell/hash.ts

@@ -0,0 +1,67 @@
+/**
+ * Deep links (SPEC-M2 §3). Hash-based so any static host serves them and a URL copied
+ * from dev works verbatim on a published site. The URL is a projection of state - the
+ * shell writes it as board/selection/play change and parses it once on boot; camera
+ * intent is always fit semantics (fit-all / fit-selection), never raw coordinates.
+ *
+ *   #/                     default board, fit all
+ *   #/b/<board>            board, fit all
+ *   #/b/<board>?n=k1,k2    board with nodes selected, camera fit to selection
+ *   #/p/<board>?at=<frame-id>&device=<viewport>&theme=<theme>   play mode
+ */
+
+export interface HashState {
+  board?: string
+  n?: string[]
+  play?: { at?: string; device?: string; theme?: string }
+}
+
+const BOARD_RE = /^[a-z0-9][a-z0-9-]*$/
+
+export function parseHash(hash: string = location.hash): HashState {
+  try {
+    const raw = hash.replace(/^#/, '')
+    if (!raw || raw === '/') return {}
+    const q = raw.indexOf('?')
+    const path = q === -1 ? raw : raw.slice(0, q)
+    const params = new URLSearchParams(q === -1 ? '' : raw.slice(q + 1))
+    const m = path.match(/^\/(b|p)\/([^/?]+)$/)
+    if (!m) return {}
+    const board = decodeURIComponent(m[2])
+    if (!BOARD_RE.test(board)) return {}
+    if (m[1] === 'b') {
+      const n = (params.get('n') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+      return { board, ...(n.length ? { n } : {}) }
+    }
+    return {
+      board,
+      play: {
+        at: params.get('at') ?? undefined,
+        device: params.get('device') ?? undefined,
+        theme: params.get('theme') ?? undefined,
+      },
+    }
+  } catch { return {} }   // a malformed hash (#/b/%) is a default view, never a crash
+}
+
+export function buildHash(s: HashState): string {
+  if (s.play?.at && s.board) {
+    const p = new URLSearchParams({ at: s.play.at })
+    if (s.play.device) p.set('device', s.play.device)
+    if (s.play.theme) p.set('theme', s.play.theme)
+    return `#/p/${s.board}?${p}`
+  }
+  if (!s.board || (s.board === 'all-scenes' && !s.n?.length)) return '#/'
+  return `#/b/${s.board}${s.n?.length ? `?n=${s.n.join(',')}` : ''}`
+}
+
+/** Write the hash; identical URLs are skipped so restore paths never loop. */
+export function writeHash(s: HashState, push = false) {
+  const h = buildHash(s)
+  if (h === location.hash || (h === '#/' && !location.hash)) return
+  if (push) history.pushState(null, '', h)
+  else history.replaceState(null, '', h)
+}
+
+/** The hash as it stood when the app loaded - boot intent, captured once. */
+export const bootHash = parseHash()

package/src/client/shell/icons.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode, SVGProps } from 'react'
+
+/**
+ * Phosphor icons (regular weight), path data inlined from @phosphor-icons/core
+ * (MIT (c) Phosphor Icons - phosphoricons.com). Deliberately NOT an icon package
+ * dependency: the shell ships as source into unknown hosts, and every runtime dep
+ * must resolve through the host's package-manager layout (see DECISIONS.md).
+ */
+type IconProps = SVGProps<SVGSVGElement> & { size?: number }
+
+const icon = (children: ReactNode) =>
+  function Icon({ size = 16, ...rest }: IconProps) {
+    return (
+      <svg width={size} height={size} viewBox="0 0 256 256" fill="currentColor" aria-hidden {...rest}>
+        {children}
+      </svg>
+    )
+  }
+
+export const SunIcon = icon(<path d="M120,40V16a8,8,0,0,1,16,0V40a8,8,0,0,1-16,0Zm72,88a64,64,0,1,1-64-64A64.07,64.07,0,0,1,192,128Zm-16,0a48,48,0,1,0-48,48A48.05,48.05,0,0,0,176,128ZM58.34,69.66A8,8,0,0,0,69.66,58.34l-16-16A8,8,0,0,0,42.34,53.66Zm0,116.68-16,16a8,8,0,0,0,11.32,11.32l16-16a8,8,0,0,0-11.32-11.32ZM192,72a8,8,0,0,0,5.66-2.34l16-16a8,8,0,0,0-11.32-11.32l-16,16A8,8,0,0,0,192,72Zm5.66,114.34a8,8,0,0,0-11.32,11.32l16,16a8,8,0,0,0,11.32-11.32ZM48,128a8,8,0,0,0-8-8H16a8,8,0,0,0,0,16H40A8,8,0,0,0,48,128Zm80,80a8,8,0,0,0-8,8v24a8,8,0,0,0,16,0V216A8,8,0,0,0,128,208Zm112-88H216a8,8,0,0,0,0,16h24a8,8,0,0,0,0-16Z" />)
+export const MoonIcon = icon(<path d="M233.54,142.23a8,8,0,0,0-8-2,88.08,88.08,0,0,1-109.8-109.8,8,8,0,0,0-10-10,104.84,104.84,0,0,0-52.91,37A104,104,0,0,0,136,224a103.09,103.09,0,0,0,62.52-20.88,104.84,104.84,0,0,0,37-52.91A8,8,0,0,0,233.54,142.23ZM188.9,190.34A88,88,0,0,1,65.66,67.11a89,89,0,0,1,31.4-26A106,106,0,0,0,96,56,104.11,104.11,0,0,0,200,160a106,106,0,0,0,14.92-1.06A89,89,0,0,1,188.9,190.34Z" />)
+export const CaretIcon = icon(<path d="M213.66,101.66l-80,80a8,8,0,0,1-11.32,0l-80-80A8,8,0,0,1,53.66,90.34L128,164.69l74.34-74.35a8,8,0,0,1,11.32,11.32Z" />)
+export const PlayIcon = icon(<path d="M232.4,114.49,88.32,26.35a16,16,0,0,0-16.2-.3A15.86,15.86,0,0,0,64,39.87V216.13A15.94,15.94,0,0,0,80,232a16.07,16.07,0,0,0,8.36-2.35L232.4,141.51a15.81,15.81,0,0,0,0-27ZM80,215.94V40l143.83,88Z" />)
+export const GridIcon = icon(<path d="M104,40H56A16,16,0,0,0,40,56v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V56A16,16,0,0,0,104,40Zm0,64H56V56h48v48Zm96-64H152a16,16,0,0,0-16,16v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V56A16,16,0,0,0,200,40Zm0,64H152V56h48v48Zm-96,32H56a16,16,0,0,0-16,16v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V152A16,16,0,0,0,104,136Zm0,64H56V152h48v48Zm96-64H152a16,16,0,0,0-16,16v48a16,16,0,0,0,16,16h48a16,16,0,0,0,16-16V152A16,16,0,0,0,200,136Zm0,64H152V152h48v48Z" />)
+export const CopyIcon = icon(<path d="M216,32H88a8,8,0,0,0-8,8V80H40a8,8,0,0,0-8,8V216a8,8,0,0,0,8,8H168a8,8,0,0,0,8-8V176h40a8,8,0,0,0,8-8V40A8,8,0,0,0,216,32ZM160,208H48V96H160Zm48-48H176V88a8,8,0,0,0-8-8H96V48H208Z" />)
+export const PlusIcon = icon(<path d="M224,128a8,8,0,0,1-8,8H136v80a8,8,0,0,1-16,0V136H40a8,8,0,0,1,0-16h80V40a8,8,0,0,1,16,0v80h80A8,8,0,0,1,224,128Z" />)
+export const XIcon = icon(<path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z" />)
+export const ReloadIcon = icon(<path d="M240,56v48a8,8,0,0,1-8,8H184a8,8,0,0,1,0-16H211.4L184.81,71.64l-.25-.24a80,80,0,1,0-1.67,114.78,8,8,0,0,1,11,11.63A95.44,95.44,0,0,1,128,224h-1.32A96,96,0,1,1,195.75,60L224,85.8V56a8,8,0,1,1,16,0Z" />)
+export const CheckIcon = icon(<path d="M229.66,77.66l-128,128a8,8,0,0,1-11.32,0l-56-56a8,8,0,0,1,11.32-11.32L96,188.69,218.34,66.34a8,8,0,0,1,11.32,11.32Z" />)
+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" />)
+export const DeviceTabletIcon = icon(<path d="M192,24H64A24,24,0,0,0,40,48V208a24,24,0,0,0,24,24H192a24,24,0,0,0,24-24V48A24,24,0,0,0,192,24ZM56,72H200V184H56Zm8-32H192a8,8,0,0,1,8,8v8H56V48A8,8,0,0,1,64,40ZM192,216H64a8,8,0,0,1-8-8v-8H200v8A8,8,0,0,1,192,216Z" />)
+export const LaptopIcon = icon(<path d="M232,168h-8V72a24,24,0,0,0-24-24H56A24,24,0,0,0,32,72v96H24a8,8,0,0,0-8,8v16a24,24,0,0,0,24,24H216a24,24,0,0,0,24-24V176A8,8,0,0,0,232,168ZM48,72a8,8,0,0,1,8-8H200a8,8,0,0,1,8,8v96H48ZM224,192a8,8,0,0,1-8,8H40a8,8,0,0,1-8-8v-8H224ZM152,88a8,8,0,0,1-8,8H112a8,8,0,0,1,0-16h32A8,8,0,0,1,152,88Z" />)
+export const MonitorIcon = icon(<path d="M208,40H48A24,24,0,0,0,24,64V176a24,24,0,0,0,24,24H208a24,24,0,0,0,24-24V64A24,24,0,0,0,208,40Zm8,136a8,8,0,0,1-8,8H48a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H208a8,8,0,0,1,8,8Zm-48,48a8,8,0,0,1-8,8H96a8,8,0,0,1,0-16h64A8,8,0,0,1,168,224Z" />)
+export const TvIcon = icon(<path d="M216,64H147.31l34.35-34.34a8,8,0,1,0-11.32-11.32L128,60.69,85.66,18.34A8,8,0,0,0,74.34,29.66L108.69,64H40A16,16,0,0,0,24,80V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V80A16,16,0,0,0,216,64Zm0,136H40V80H216V200Z" />)
+export const SignpostIcon = icon(<path d="M246,106.65,212.33,69.3A16,16,0,0,0,200.44,64H136V32a8,8,0,0,0-16,0V64H40A16,16,0,0,0,24,80v64a16,16,0,0,0,16,16h80v64a8,8,0,0,0,16,0V160h64.44a16,16,0,0,0,11.89-5.3L246,117.35A8,8,0,0,0,246,106.65ZM200.44,144H40V80H200.44l28.8,32Z" />)
+export const ParallelogramDuoIcon = icon(<><path d="M239.29,59.28l-64.8,144a8,8,0,0,1-7.3,4.72H24a8,8,0,0,1-7.3-11.28l64.8-144A8,8,0,0,1,88.81,48H232A8,8,0,0,1,239.29,59.28Z" opacity=".1" /><path d="M245.43,47.31A15.94,15.94,0,0,0,232,40H88.81a16,16,0,0,0-14.59,9.43l-64.8,144A16,16,0,0,0,24,216H167.19a16,16,0,0,0,14.59-9.43l64.8-144A16,16,0,0,0,245.43,47.31ZM167.19,200H24L88.81,56H232Z" /></>)
+/** Sidebar trigger, custom in Phosphor 256-space: outer frame + panel pill -
+ *  pill filled while the sidebar is open, hollow while collapsed. */
+export const PanelFilledIcon = icon(<><rect x="32" y="48" width="192" height="160" rx="32" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="72" y="88" width="48" height="80" rx="24" /></>)
+export const PanelHollowIcon = icon(<><rect x="32" y="48" width="192" height="160" rx="32" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="72" y="88" width="48" height="80" rx="24" fill="none" stroke="currentColor" strokeWidth="14" /></>)
+/** Board glyphs: CardsThree = the built-in `all-scenes` board; Cards = curated boards. */
+export const CardsThreeIcon = icon(<path d="M208,88H48a16,16,0,0,0-16,16v96a16,16,0,0,0,16,16H208a16,16,0,0,0,16-16V104A16,16,0,0,0,208,88Zm0,112H48V104H208v96ZM48,64a8,8,0,0,1,8-8H200a8,8,0,0,1,0,16H56A8,8,0,0,1,48,64ZM64,32a8,8,0,0,1,8-8H184a8,8,0,0,1,0,16H72A8,8,0,0,1,64,32Z" />)
+export const FrameCornersIcon = icon(<path d="M160 48h40a8 8 0 0 1 8 8v40M208 160v40a8 8 0 0 1-8 8h-40M96 208H56a8 8 0 0 1-8-8v-40M48 96V56a8 8 0 0 1 8-8h40" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" strokeLinejoin="round" />)
+export const ArrowLeftIcon = icon(<path d="M224,128a8,8,0,0,1-8,8H59.31l58.35,58.34a8,8,0,0,1-11.32,11.32l-72-72a8,8,0,0,1,0-11.32l72-72a8,8,0,0,1,11.32,11.32L59.31,120H216A8,8,0,0,1,224,128Z" />)
+export const ArrowRightIcon = icon(<path d="M221.66,133.66l-72,72a8,8,0,0,1-11.32-11.32L196.69,136H40a8,8,0,0,1,0-16H196.69L138.34,61.66a8,8,0,0,1,11.32-11.32l72,72A8,8,0,0,1,221.66,133.66Z" />)
+export const CardsIcon = icon(<path d="M184,72H40A16,16,0,0,0,24,88V200a16,16,0,0,0,16,16H184a16,16,0,0,0,16-16V88A16,16,0,0,0,184,72Zm0,128H40V88H184V200ZM232,56V176a8,8,0,0,1-16,0V56H64a8,8,0,0,1,0-16H216A16,16,0,0,1,232,56Z" />)
+/** Viewport-name -> device glyph; unknown custom names fall back to the generic Devices. */
+export function deviceIcon(name: string | null, size = 14) {
+  const Icon = ({ mobile: DeviceMobileIcon, tablet: DeviceTabletIcon, laptop: LaptopIcon, monitor: MonitorIcon, tv: TvIcon } as Record<string, typeof DevicesIcon>)[name ?? ''] ?? DevicesIcon
+  return <Icon size={size} />
+}
+