@marver-design/marver 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components. The tool ships no AI - your coding agent is the designer.",
   "type": "module",
   "private": false,
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "src/client",
+    "src/shared",
     "templates",
     "README.md",
     "LICENSE",
@@ -32,6 +33,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^6.0.0",
     "cac": "^7.0.0",
+    "html-to-image": "^1.11.13",
     "marked": "^16.0.0",
     "mermaid": "^11.6.0",
     "react-zoom-pan-pinch": "^3.6.1",

package/src/client/content/diagram.tsx

@@ -23,6 +23,50 @@ export function cleanSource(src: string): string {
     .trim()
 }
 
+/** flowchart/graph is where classDef + markdown-string labels both apply; other diagram
+ *  types (sequence, pie, ...) don't take the family/hierarchy sugar. */
+function isFlowchart(src: string): boolean {
+  const first = src.split('\n').find((l) => l.trim())?.trim() ?? ''
+  return /^(flowchart|graph)\b/.test(first)
+}
+
+// D1: head/gloss auto-hierarchy. An agent writes a natural `Head :: gloss` label and marver
+// renders the head BOLD on top with the gloss on a lighter, smaller line below - no backticks,
+// no `**`, no `<br>` to hand-author. It expands the label into a mermaid markdown string (bold
+// head, blank line -> a second <p> the THEME_CSS styles down). ` :: ` (spaced double colon) is
+// the token: rare in prose, and distinct from the `:::family` class tag (no spaces, three colons).
+const GLOSS = ' :: '
+export function withLabelHierarchy(src: string): string {
+  if (!isFlowchart(src)) return src
+  return src.replace(/"([^"\n]*?)"/g, (m, body: string) => {
+    const at = body.indexOf(GLOSS)
+    if (at < 0 || body.startsWith('`')) return m           // no token, or already a markdown string
+    const head = body.slice(0, at).trim()
+    const gloss = body.slice(at + GLOSS.length).trim()
+    if (!head || !gloss) return m
+    const bhead = /[*`]/.test(head) ? head : `**${head}**`  // don't double-bold a hand-marked head
+    return `"\`${bhead}\n\n${gloss}\`"`                     // "`**Head**⏎⏎gloss`"
+  })
+}
+
+// D2: named family fills - the SAME colour language as the Md `:blue[...]` families, so an agent
+// tags a node `HQ:::blue` with zero classDef boilerplate and prose + diagram read as one palette.
+const DIAGRAM_FAMILIES: Record<string, string> = {
+  blue: 'fill:#0088FF,stroke:#0066CC,color:#fff',
+  orange: 'fill:#F5820A,stroke:#C96A08,color:#fff',
+  purple: 'fill:#B32BC8,stroke:#8F22A0,color:#fff',
+  green: 'fill:#1FA34A,stroke:#178139,color:#fff',
+  red: 'fill:#E5342B,stroke:#B71C13,color:#fff',
+  gray: 'fill:#E5E5EA,stroke:#C7C7CC,color:#1C1C1E',
+}
+/** Append the family classDefs to flowchart/graph diagrams (classDef is a flowchart feature).
+ *  Unused defs are harmless; `X:::blue` resolves them regardless of position. */
+export function withFamilies(src: string): string {
+  if (!isFlowchart(src)) return src
+  const defs = Object.entries(DIAGRAM_FAMILIES).map(([n, s]) => `classDef ${n} ${s}`).join('\n')
+  return `${src}\n${defs}`
+}
+
 /** Remove external URL references from rendered SVG (images, links, href attrs). */
 export function sanitizeSvg(svg: string): string {
   const doc = new DOMParser().parseFromString(svg, 'image/svg+xml')
@@ -38,9 +82,9 @@ export function sanitizeSvg(svg: string): string {
 }
 
 export function Diagram({ title, children }: { title?: string; children?: ReactNode }) {
-  const src = cleanSource(
+  const src = withFamilies(withLabelHierarchy(cleanSource(
     typeof children === 'string' ? children : Array.isArray(children) ? children.join('') : String(children ?? ''),
-  )
+  )))
   const ref = useRef<HTMLDivElement>(null)
   const [error, setError] = useState<string | null>(null)
   const uid = useRef(`mv-mmd-${++uidSeq}`)

package/src/client/content/index.tsx

@@ -9,7 +9,11 @@
  */
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { CONTENT_WIDTH } from '../const.ts'
-import { assetUrl, renderMarkdown } from './md.ts'
+import { assetUrl, renderMarkdown, FAMILIES } from './md.ts'
+
+// D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
+const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
+  `.mv-md .mv-c-${f}{color:${c.light}}.dark .mv-md .mv-c-${f},[data-theme="dark"] .mv-md .mv-c-${f}{color:${c.dark}}`).join('\n')
 
 export { Diagram } from './diagram.tsx'
 
@@ -106,7 +110,7 @@ function ensureStyles() {
   stylesIn = true
   const el = document.createElement('style')
   el.id = 'mv-content-css'
-  el.textContent = CSS
+  el.textContent = CSS + '\n' + FAMILY_CSS
   document.head.appendChild(el)
 }
 

package/src/client/content/md.ts

@@ -8,6 +8,19 @@ import { Marked } from 'marked'
 
 const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
 
+/** D3: named color families for inline Md - the SAME families the diagrams use, so prose and
+ *  the diagram beside it speak one color language. Theme pairs (light/dark). Bound to classes,
+ *  never raw HTML (raw HTML stays inert). Used by the `:family[text]` extension + the frame CSS. */
+export const FAMILIES: Record<string, { light: string; dark: string }> = {
+  blue:   { light: '#0088FF', dark: '#3B9DFF' },
+  orange: { light: '#F5820A', dark: '#FF9F33' },
+  purple: { light: '#B32BC8', dark: '#D34FE8' },
+  green:  { light: '#1FA34A', dark: '#34C759' },
+  red:    { light: '#E5342B', dark: '#FF453A' },
+  gray:   { light: '#8B95A3', dark: '#7D8794' },
+}
+const FAMILY_RE = new RegExp(`^:(${Object.keys(FAMILIES).join('|')})\\[([^\\]\\n]+)\\]`)
+
 /** Relative design/assets/ path -> served URL; null for anything else (fail closed).
  *  Decodes BEFORE validating (a %2e%2e must not sneak past the ".." check) and
  *  re-encodes per segment, so the validated path is the path the browser requests. */
@@ -45,6 +58,22 @@ const marked = new Marked({
   },
 })
 
+// D3: `:blue[shipper's world]` -> a family-colored span (inline markdown inside still parses).
+marked.use({
+  extensions: [{
+    name: 'mvcolor',
+    level: 'inline',
+    start(src: string) { return src.match(/:(?:blue|orange|purple|green|red|gray)\[/)?.index },
+    tokenizer(this: any, src: string) {
+      const m = FAMILY_RE.exec(src)
+      if (m) return { type: 'mvcolor', raw: m[0], family: m[1], tokens: this.lexer.inlineTokens(m[2]) }
+    },
+    renderer(this: any, token: any) {
+      return `<span class="mv-c-${token.family}">${this.parser.parseInline(token.tokens)}</span>`
+    },
+  }],
+})
+
 export function renderMarkdown(src: string): string {
   return marked.parse(src, { async: false }) as string
 }

package/src/client/content/palette.ts

@@ -25,6 +25,12 @@ export const THEME_CSS = `
   .nodeLabel, .cluster-label { font-weight: 600; line-height: 1.4; }
   .nodeLabel p, .edgeLabel p, .label p { margin: 0; }
   .edgeLabel, .edgeLabel .label { font-weight: 500; }
+  /* D1 head/gloss hierarchy: a "Head :: gloss" label renders as two paragraphs -
+     bold head (the strong from the markdown), lighter/smaller gloss below. */
+  .nodeLabel p + p, .cluster-label p + p {
+    font-weight: 400; font-size: 0.84em; opacity: 0.68;
+    letter-spacing: 0; margin-top: 3px;
+  }
 `
 
 /** Mermaid themeVariables for one mode. Base theme + these = the marver look. */

package/src/client/frame-host/bridge.js

@@ -4,6 +4,15 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
 const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 const id = new URLSearchParams(location.search).get('id') ?? location.pathname
 
+// SPEC-M5: the shell serialises this frame's DOM (same origin) for the lean facade. Open shadow roots
+// are walkable, but a CLOSED root is invisible after the fact - flag it at creation so the serialiser
+// degrades the frame (keeps it live) instead of shipping a lean copy missing its shadow content.
+const _attachShadow = Element.prototype.attachShadow
+if (_attachShadow) Element.prototype.attachShadow = function (init) {
+  if (init && init.mode === 'closed') window.__mvClosedShadow = true
+  return _attachShadow.call(this, init)
+}
+
 // theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
 const setTheme = (theme) => {
   document.documentElement.dataset.theme = theme
@@ -16,6 +25,9 @@ if (isHtmlFrame) {
 }
 
 document.addEventListener('click', (e) => {
+  // laser/comment mode owns every click - a goto link must not ALSO navigate
+  // (both handlers capture on document, so stopPropagation can't referee)
+  if (modeActive()) return
   const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
   if (!el) return
   e.preventDefault()
@@ -29,6 +41,8 @@ window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: St
 window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, message: `unhandled rejection: ${e.reason}` }))
 
 window.addEventListener('message', (e) => {
+  // commands come from the SHELL (parent) only - embedded app content must not flip the theme
+  if (e.source !== window.parent || window.parent === window) return
   if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
 })
 
@@ -37,7 +51,259 @@ if (isHtmlFrame) {
   document.readyState === 'loading' ? addEventListener('DOMContentLoaded', ready) : ready()
 }
 
-// pinch inside a frame must not zoom the parent PAGE (wheel events here belong to the
-// iframe's document, so the shell's blocker cannot see them). Keyboard cmd +/- untouched.
-window.addEventListener('wheel', (e) => { if (e.ctrlKey || e.metaKey) e.preventDefault() }, { passive: false })
+// B0.2 wheel ownership. A frame is either the interact/play target (the APP owns wheel -
+// its own scroll) or passive (laser/comment/plain view - the CANVAS owns wheel). Wheel
+// events land in the iframe's document, so the shell can't see them: when passive we
+// forward them to the shell, when interactive we leave them for the app (only blocking
+// the browser's own ctrl/meta page pinch-zoom). preventing here is mandatory - the parent
+// gets the forwarded message too late to cancel the iframe's own scroll.
+let interactiveOn = false
+window.addEventListener('wheel', (e) => {
+  if (interactiveOn) { if (e.ctrlKey || e.metaKey) e.preventDefault(); return }
+  e.preventDefault()
+  e.stopImmediatePropagation()
+  post({ type: 'sh:wheel', id, deltaX: e.deltaX, deltaY: e.deltaY, deltaMode: e.deltaMode,
+    ctrlKey: e.ctrlKey, metaKey: e.metaKey, clientX: e.clientX, clientY: e.clientY })
+}, { capture: true, passive: false })
 document.addEventListener('gesturestart', (e) => e.preventDefault())
+// a nested scroll container hitting its boundary must not chain into the shell page
+document.documentElement.style.overscrollBehavior = 'contain'
+
+// ---- laser mode + element picking (SPEC-M3 §5, §7) ----------------------------------
+// Laser: one injected stylesheet, outline only (zero layout shift), depth-based hue -
+// each nesting level steps 60° around the wheel, cycling at 6. Picking: laser plus a
+// click interception that captures the anchor bundle and posts it to the shell.
+
+const LASER_ID = 'mv-laser-style'
+// comment-mode cursor: the pin's teardrop in the comment green, duotone (dark rim,
+// lighter inner) with a white halo ring so it pops on any content; hotspot at the tail
+const PICK_CURSOR = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 256 256'%3E%3Cpath d='M132,24A100.11,100.11,0,0,0,32,124v84a16,16,0,0,0,16,16h84a100,100,0,0,0,0-200Z' fill='none' stroke='%23fff' stroke-width='40'/%3E%3Cpath d='M132,24A100.11,100.11,0,0,0,32,124v84a16,16,0,0,0,16,16h84a100,100,0,0,0,0-200Z' fill='%2334c759' stroke='%231f8a3d' stroke-width='12'/%3E%3Ccircle cx='138' cy='118' r='46' fill='%23fff' opacity='.32'/%3E%3C/svg%3E") 4 21, crosshair`
+// laser-mode cursor: the crosshair reticle in accent blue with a white halo ring,
+// hotspot dead center
+const LASER_CURSOR = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 256 256'%3E%3Cg stroke='%23fff' stroke-width='46' fill='none'%3E%3Ccircle cx='128' cy='128' r='56'/%3E%3Cpath d='M128 24 V56 M128 200 V232 M24 128 H56 M200 128 H232' stroke-linecap='round'/%3E%3C/g%3E%3Cg stroke='%230088ff' stroke-width='20' fill='none'%3E%3Ccircle cx='128' cy='128' r='56'/%3E%3Cpath d='M128 24 V56 M128 200 V232 M24 128 H56 M200 128 H232' stroke-linecap='round'/%3E%3C/g%3E%3Ccircle cx='128' cy='128' r='16' fill='%230088ff' stroke='%23fff' stroke-width='8'/%3E%3C/svg%3E") 12 12, crosshair`
+const laserCss = () => {
+  // depth via unrolled descendant combinators - CSS custom properties cannot cycle
+  let rules = 'body { --mv-hue: 0 }\n'
+  for (let d = 1; d <= 12; d++)
+    rules += `body ${'> * '.repeat(d)}{ --mv-hue: ${(d % 6) * 60} }\n`
+  // full rainbow only in laser mode; comment mode keeps just the hover highlight
+  // (understand what you'd click without the whole board shouting). The label and
+  // its children are chrome, never subjects - no outlines on them.
+  if (laserOn)
+    rules += 'body *:not(script):not(style):not(#mv-laser-label):not(#mv-laser-label *) { outline: 1px solid hsl(var(--mv-hue) 85% 55% / .75); outline-offset: -1px }\n'
+  // comment cursor wins when both modes are on (comment owns the click)
+  if (pickOn || laserOn)
+    rules += `body, body * { cursor: ${pickOn ? PICK_CURSOR : LASER_CURSOR} !important }\n`
+  return rules + `
+body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-offset: -2px;
+  background-image: linear-gradient(hsl(var(--mv-hue) 95% 50% / .08), hsl(var(--mv-hue) 95% 50% / .08)) }
+#mv-laser-label { position: fixed; z-index: 2147483647; pointer-events: none; outline: none !important;
+  display: flex; align-items: center; gap: 5px; width: max-content;
+  font: 600 10px -apple-system, system-ui, sans-serif; color: #fff; background: rgba(20, 20, 24, .92);
+  padding: 3px 7px; border-radius: 5px; max-width: 340px; white-space: nowrap; overflow: hidden;
+  text-overflow: ellipsis; letter-spacing: .01em }
+#mv-laser-label svg { flex: none; display: block; outline: none !important }
+#mv-laser-label.mv-copied { animation: mv-pop .22s cubic-bezier(.32, .72, .35, 1) }
+@keyframes mv-pop { from { transform: scale(.85); opacity: .5 } }
+`
+}
+
+// filled clipboard with a check inside (Phosphor clipboard-fill + check): the label
+// wears this while confirming a copy
+const COPIED_HTML = `<svg width="12" height="12" viewBox="0 0 256 256" fill="currentColor"><path d="M200,32H163.74a47.92,47.92,0,0,0-71.48,0H56A16,16,0,0,0,40,48V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V48A16,16,0,0,0,200,32Zm-72,0a32,32,0,0,1,32,32H96A32,32,0,0,1,128,32Z"/><path d="M92 150l26 26 48-54" fill="none" stroke="rgba(20,20,24,.92)" stroke-width="20" stroke-linecap="round" stroke-linejoin="round"/></svg><span>Element path copied</span>`
+
+let laserOn = false, pickOn = false, hoverEl = null, labelEl = null
+const modeActive = () => laserOn || pickOn
+
+// A6: report transient laser/comment engagement (pointer inside this frame AND a mode on) so the
+// shell leases the frame - a hot update to it then defers until the pointer leaves or the mode
+// ends, instead of yanking the user mid-inspect/mid-comment.
+let pointerInside = false
+const reportInteraction = () => post({ type: 'sh:interaction', id, laser: pointerInside && laserOn, comment: pointerInside && pickOn })
+document.addEventListener('mouseover', () => { if (!pointerInside) { pointerInside = true; reportInteraction() } })
+document.addEventListener('mouseout', (e) => { if (!e.relatedTarget) { pointerInside = false; reportInteraction() } })
+window.addEventListener('blur', () => { if (pointerInside) { pointerInside = false; reportInteraction() } })
+
+// laser and pick are independent looks over shared hover machinery: the stylesheet
+// is regenerated on every flip so each mode contributes exactly its own rules
+const applyModes = () => {
+  const cur = document.getElementById(LASER_ID)
+  if (!modeActive()) {
+    if (cur) cur.remove()
+    clearHover()
+    return
+  }
+  const s = cur ?? document.createElement('style')
+  s.id = LASER_ID
+  s.textContent = laserCss()
+  if (!cur) document.head.appendChild(s)
+}
+
+let copiedTimer = null
+
+const clearHover = () => {
+  if (hoverEl) { delete hoverEl.dataset.mvHover; hoverEl = null }
+  if (labelEl) { labelEl.remove(); labelEl = null }
+  clearTimeout(copiedTimer)
+}
+
+// the shell confirmed the clipboard write - the hover label ITSELF says so (a
+// corner toast is too far from where the eyes are), then reverts after 2s.
+// The seq + element check keeps a slow ack from decorating a DIFFERENT label
+// (pointer moved on, or laser was retoggled, before writeText resolved).
+const showCopied = (seq) => {
+  if (seq !== copySeq || hoverEl !== copyEl) return
+  if (!labelEl) return
+  labelEl.classList.add('mv-copied')
+  labelEl.innerHTML = COPIED_HTML
+  clearTimeout(copiedTimer)
+  copiedTimer = setTimeout(() => {
+    if (!labelEl) return
+    labelEl.classList.remove('mv-copied')
+    if (hoverEl) labelEl.textContent = describe(hoverEl)
+    else { labelEl.remove(); labelEl = null }
+  }, 2000)
+}
+
+const describe = (el) => {
+  const tag = el.tagName.toLowerCase()
+  const loc = el.dataset.mvLoc
+  const text = (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 40)
+  return loc ? `${tag} · ${loc}` : text ? `${tag} · “${text}”` : tag
+}
+
+document.addEventListener('mousemove', (e) => {
+  if (!modeActive()) return
+  const el = e.target instanceof Element && e.target.closest('body *:not(#mv-laser-label)')
+  if (!el || el === hoverEl) { if (labelEl && hoverEl) place(labelEl, e); return }
+  clearHover()
+  hoverEl = el
+  el.dataset.mvHover = '1'
+  labelEl = document.createElement('div')
+  labelEl.id = 'mv-laser-label'
+  labelEl.textContent = describe(el)
+  document.body.appendChild(labelEl)
+  place(labelEl, e)
+}, true)
+// label rides to the RIGHT of the cursor, vertically centered on it - below-right
+// hid the pointer's target; flips to the left when the right edge runs out
+const place = (label, e) => {
+  const pad = 18
+  const w = label.offsetWidth, h = label.offsetHeight
+  let x = e.clientX + pad
+  if (x + w > innerWidth - 4) x = Math.max(4, e.clientX - pad - w)
+  label.style.left = x + 'px'
+  label.style.top = Math.min(Math.max(4, e.clientY - h / 2), innerHeight - h - 4) + 'px'
+}
+
+// the anchor bundle (SPEC-M3 §5): every rung captured at pick time
+const cssPath = (el) => {
+  const seg = []
+  for (let cur = el; cur && cur !== document.body; cur = cur.parentElement) {
+    if (cur.id) { seg.unshift(`#${CSS.escape(cur.id)}`); break }
+    const tag = cur.tagName.toLowerCase()
+    let n = 1
+    for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling)
+      if (sib.tagName === cur.tagName) n++
+    seg.unshift(n > 1 ? `${tag}:nth-of-type(${n})` : tag)
+  }
+  return seg.join(' > ')
+}
+const anchorBundle = (el, e) => {
+  const r = el.getBoundingClientRect()
+  const text = (el.textContent ?? '').trim().replace(/\s+/g, ' ')
+  return {
+    el: {
+      semantics: {
+        tag: el.tagName.toLowerCase(),
+        role: el.getAttribute('role') ?? undefined,
+        ariaLabel: el.getAttribute('aria-label') ?? undefined,
+        testId: el.getAttribute('data-testid') ?? undefined,
+        quote: text.slice(0, 200) || undefined,
+      },
+      cssPath: cssPath(el),
+      source: el.dataset.mvLoc ?? undefined,
+    },
+    pos: {
+      fx: r.width ? Math.min(1, Math.max(0, (e.clientX - r.left) / r.width)) : .5,
+      fy: r.height ? Math.min(1, Math.max(0, (e.clientY - r.top) / r.height)) : .5,
+    },
+    rect: { x: r.left, y: r.top, w: r.width, h: r.height },   // frame-viewport coords for the shell's pin math
+  }
+}
+
+// every press is reported (tiny message, capture, nothing prevented): the shell
+// uses it to close an open thread card when the click lands INSIDE a frame -
+// shell-document listeners can never see those
+document.addEventListener('pointerdown', () => post({ type: 'sh:frame-down', id }), true)
+
+let copySeq = 0, copyEl = null
+document.addEventListener('click', (e) => {
+  if (!modeActive()) return
+  e.preventDefault()
+  e.stopPropagation()
+  const el = e.target instanceof Element && e.target.closest('body *:not(#mv-laser-label)')
+  if (!el) return
+  // comment mode wins when both are on; plain laser click hands the agent an
+  // exact address - frame file + css path (+ source loc when the build stamps one)
+  if (pickOn) post({ type: 'sh:picked', id, anchor: anchorBundle(el, e) })
+  else {
+    copyEl = el
+    post({ type: 'sh:laser-copy', id, seq: ++copySeq, path: cssPath(el), source: el.dataset.mvLoc ?? null })
+  }
+}, true)
+
+/** Resolve a stored anchor back to a rect (the ladder, §5): semantics-verified CSS
+ *  path first, then testId, then a quote scan; null = orphan. Every check compares
+ *  the FULL captured semantics - two textless buttons must not swap silently. */
+const resolveAnchor = (anchor) => {
+  const want = anchor?.el?.semantics ?? {}
+  const match = (el) => {
+    if (want.tag && el.tagName.toLowerCase() !== want.tag) return false
+    if (want.role && el.getAttribute('role') !== want.role) return false
+    if (want.ariaLabel && el.getAttribute('aria-label') !== want.ariaLabel) return false
+    if (want.testId && el.getAttribute('data-testid') !== want.testId) return false
+    const text = (el.textContent ?? '').trim().replace(/\s+/g, ' ')
+    if (want.quote && !(text.startsWith(want.quote.slice(0, 60)) || text.includes(want.quote.slice(0, 40)))) return false
+    return true
+  }
+  try {
+    const byPath = anchor?.el?.cssPath && document.querySelector(anchor.el.cssPath)
+    if (byPath && match(byPath)) return byPath
+  } catch { /* stale selector */ }
+  try {
+    if (want.testId) {
+      const el = document.querySelector(`[data-testid="${CSS.escape(want.testId)}"]`)
+      if (el && match(el)) return el
+    }
+    if (want.quote && typeof want.tag === 'string' && /^[a-z][a-z0-9-]*$/.test(want.tag)) {
+      for (const el of document.querySelectorAll(want.tag))
+        if (match(el)) return el
+    }
+  } catch { /* malformed semantics must not sink the whole batch */ }
+  return null
+}
+
+window.addEventListener('message', (e) => {
+  // commands come from the SHELL only - the parent window. Anything else (nested
+  // third-party iframes, a hijacked opener) is ignored.
+  if (e.source !== window.parent || window.parent === window) return
+  const m = e?.data
+  if (!m || typeof m !== 'object') return
+  // independent toggles - each mode contributes its own rules, applyModes composes
+  if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes(); reportInteraction() }
+  if (m.type === 'sh:pick') { pickOn = !!m.on; applyModes(); reportInteraction() }
+  // B0.2: interact/play target owns its own wheel; passive frames forward it to the canvas
+  if (m.type === 'sh:interactive') { interactiveOn = !!m.on }
+  if (m.type === 'sh:copy-ok') showCopied(m.seq)
+  if (m.type === 'sh:resolve-anchors' && Array.isArray(m.anchors)) {
+    const rects = m.anchors.slice(0, 200).map((a) => {
+      let el = null
+      try { el = resolveAnchor(a.anchor) } catch { /* one bad anchor, not the batch */ }
+      if (!el) return { key: a.key, orphan: true }
+      const r = el.getBoundingClientRect()
+      return { key: a.key, rect: { x: r.left, y: r.top, w: r.width, h: r.height } }
+    })
+    post({ type: 'sh:anchor-rects', id, rects })
+  }
+})

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

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