@marver-design/marver 0.5.0 → 0.7.0

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

@@ -1,7 +1,15 @@
 // Shared frame bridge. TSX frames import it plainly; the plugin injects it into HTML frames
 // with ?html=1, which turns on theme-from-query and auto-ready (TSX posts its own ready after boot).
+//
+// The laser / comment-pick / anchor / highlight machinery lives in ./inspect.js and is
+// shared with the prototype stage; this bridge owns the canvas-frame concerns around it:
+// theme, wheel ownership, the interaction lease, data-goto, and error reporting.
+import { createInspect } from './inspect.js'
+
 const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
-const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
+// same-origin parent (the shell): a fixed target origin keeps posts (incl. picked anchor
+// bundles) from leaking if this frame is ever navigated cross-origin
+const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, location.origin) }
 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
@@ -24,10 +32,25 @@ if (isHtmlFrame) {
   if (theme) setTheme(theme)
 }
 
+// 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
+let interactiveOn = false            // B0.2: set by sh:interactive - the play/interact target owns its own wheel
+const reportInteraction = () => post({ type: 'sh:interaction', id, laser: pointerInside && inspect.isLaser(), comment: pointerInside && inspect.isPick() })
+
+// laser / pick / anchor / highlight - one shared controller (see inspect.js). The id is
+// static here (one iframe per frame); onModeChange re-reports the lease when a mode flips.
+const inspect = createInspect({ post, getId: () => id, onModeChange: () => reportInteraction() })
+
+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() } })
+
 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
+  if (inspect.modeActive()) return
   const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
   if (!el) return
   e.preventDefault()
@@ -43,7 +66,10 @@ window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id
 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.origin && e.origin !== location.origin) return   // a navigated frame must not spoof commands
   if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
+  // B0.2: interact/play target owns its own wheel; passive frames forward it to the canvas
+  if (e?.data?.type === 'sh:interactive') { interactiveOn = !!e.data.on }
 })
 
 if (isHtmlFrame) {
@@ -57,7 +83,6 @@ if (isHtmlFrame) {
 // 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()
@@ -68,242 +93,3 @@ window.addEventListener('wheel', (e) => {
 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/inspect.d.ts

@@ -0,0 +1,6 @@
+// Types for inspect.js (kept as plain JS so it serves into frames like bridge.js).
+export function createInspect(opts: {
+  post: (msg: Record<string, unknown>) => void
+  getId: () => string
+  onModeChange?: (laser: boolean, pick: boolean) => void
+}): { modeActive: () => boolean; isLaser: () => boolean; isPick: () => boolean; dispose: () => void }

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

@@ -0,0 +1,346 @@
+// Shared frame-inspect controller (SPEC-M3 §5/§7 + prototype-review #4/#5).
+//
+// Laser outlines, comment-pick, anchor capture/resolve, and a persistent element
+// lock ("highlight") - the review machinery shared by the canvas frame bridge
+// (bridge.js, one iframe per frame) AND the prototype stage (stage/main.tsx, one
+// persistent tree that swaps frames in place). Keeping ONE source means the two
+// surfaces never drift.
+//
+// The HOST owns wheel + navigation ownership, theme, and error wiring; inspect only
+// touches laser/pick/anchor/highlight. It self-installs the pointer + message
+// listeners and returns { modeActive } so the host can guard its own nav clicks.
+//
+//   createInspect({ post, getId, onModeChange? })
+//     post(msg)        send a message up to the shell (parent)
+//     getId()          the frame id to stamp on posts (static on canvas, the
+//                      current stage frame in play - it swaps without reload)
+//     onModeChange?()  called after any laser/pick flip (the canvas bridge uses it
+//                      to report its interaction lease; the stage ignores it)
+//
+//   shell -> frame : sh:laser · sh:pick · sh:copy-ok · sh:resolve-anchors · sh:highlight-anchor
+//   frame -> shell : sh:frame-down · sh:picked · sh:laser-copy · sh:anchor-rects
+
+// 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`
+
+// 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>`
+
+const LASER_ID = 'mv-laser-style'
+const BASE_ID = 'mv-inspect-base'
+
+// hue-tinted highlight (an element's OWN depth hue - the same rainbow laser uses):
+// 2px outline + soft fill + ring, driven by whatever hue CSS var the caller names. The
+// comment-mode hover reads the LIVE depth hue (--mv-hue, mode-only); the persistent lock
+// reads a STORED hue (--mv-lock-hue, set inline per element) so the frame outline never
+// diverges from the pin/card colour if the DOM reparents.
+const HUE_HL = (sel, hueVar, imp = '') => `
+body ${sel} { outline: 2px solid hsl(var(${hueVar}) 95% 45%)${imp}; outline-offset: -2px;
+  background-image: linear-gradient(hsl(var(${hueVar}) 95% 50% / .10), hsl(var(${hueVar}) 95% 50% / .10));
+  box-shadow: 0 0 0 3px hsl(var(${hueVar}) 95% 50% / .32) }`
+// depth hue for every element (role/nesting colour) - only injected while a mode is active
+const DEPTH_HUE = (() => {
+  let r = 'body { --mv-hue: 0 }\n'
+  for (let d = 1; d <= 12; d++) r += `body ${'> * '.repeat(d)}{ --mv-hue: ${(d % 6) * 60} }\n`
+  return r
+})()
+
+export function createInspect({ post, getId, onModeChange }) {
+  let laserOn = false, pickOn = false
+  let hoverEl = null, labelEl = null
+  let lockedEl = null, highlightAnchor = null   // the persistent outline (#4 lock / #5 open)
+  let copiedTimer = null, copySeq = 0, copyEl = null
+
+  // every listener goes through `on` so dispose() can remove them all - a stage remount
+  // (Fast Refresh) would otherwise stack duplicate controllers posting duplicate picks
+  const removers = []
+  const on = (target, type, fn, opts) => { target.addEventListener(type, fn, opts); removers.push(() => target.removeEventListener(type, fn, opts)) }
+
+  const modeActive = () => laserOn || pickOn
+
+  // the mode stylesheet: laser's full-board rainbow, or comment's single-element hover.
+  // Both colour by the element's depth hue (--mv-hue lives in the always-on base sheet).
+  const laserCss = () => {
+    let rules = DEPTH_HUE               // depth hues live only while a mode is active
+    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'
+    if (pickOn || laserOn)
+      rules += `body, body * { cursor: ${pickOn ? PICK_CURSOR : LASER_CURSOR} !important }\n`
+    // comment mode: the hovered element pops in its OWN hue (outline + fill + ring), so it
+    // reads as "the thing you'll comment on" in the same colour it wears in laser. Laser
+    // keeps its lighter single outline so the whole board stays legible.
+    const hover = pickOn ? HUE_HL('[data-mv-hover]', '--mv-hue') : `
+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)) }`
+    return rules + hover + `
+#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 } }
+`
+  }
+
+  // the lock outline is always available (a thread can be opened while NOT in a mode),
+  // so its rule lives in a tiny base sheet injected once - comment green, distinct from
+  // the mode hover, and it wins by being 2px with an offset.
+  const injectBase = () => {
+    if (document.getElementById(BASE_ID)) return
+    const s = document.createElement('style')
+    s.id = BASE_ID
+    // the persistent lock, tinted in the anchored element's stored hue (set inline as
+    // --mv-lock-hue by applyLock; fallback to a calm blue for any pre-hue anchor)
+    s.textContent = HUE_HL('[data-mv-locked]', '--mv-lock-hue, 210', ' !important')
+    document.head.appendChild(s)
+  }
+
+  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)
+  }
+
+  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
+  }
+
+  const clearHover = () => {
+    if (hoverEl) { delete hoverEl.dataset.mvHover; hoverEl = null }
+    if (labelEl) { labelEl.remove(); labelEl = null }
+    clearTimeout(copiedTimer)
+  }
+
+  // the persistent lock (#4/#5): one element at a time, its own attribute so a
+  // hover clear never touches it and the mode-off teardown leaves it alone.
+  const applyLock = (el, hue) => {
+    // stamp the stored hue first, so re-confirming the SAME element still refreshes its
+    // colour; a missing/invalid hue REMOVES the var so the CSS fallback (210) applies
+    if (el) {
+      if (Number.isFinite(hue)) el.style.setProperty('--mv-lock-hue', String(hue))
+      else el.style.removeProperty('--mv-lock-hue')
+    }
+    if (lockedEl === el) return
+    if (lockedEl) { delete lockedEl.dataset.mvLocked; lockedEl.style.removeProperty('--mv-lock-hue') }
+    lockedEl = el
+    if (el) el.dataset.mvLocked = '1'
+  }
+  const clearLock = () => {
+    if (lockedEl) { delete lockedEl.dataset.mvLocked; lockedEl.style.removeProperty('--mv-lock-hue') }
+    lockedEl = null; highlightAnchor = null
+  }
+
+  const showCopied = (seq) => {
+    if (seq !== copySeq || hoverEl !== copyEl || !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)
+  }
+
+  // the label hangs BELOW the cursor with a gap, left-aligned under it - never over the
+  // element you are trying to click. It only shifts left when it would run off the right
+  // edge (so the text is never clipped), and flips ABOVE the cursor near the bottom edge.
+  const place = (label, e) => {
+    const gap = 18
+    const w = label.offsetWidth, h = label.offsetHeight
+    let x = e.clientX                                    // left edge under the cursor
+    if (x + w > innerWidth - 4) x = innerWidth - 4 - w   // keep fully in view instead of clipping
+    x = Math.max(4, x)
+    let y = e.clientY + gap                              // below, clear of the cursor
+    if (y + h > innerHeight - 4) y = e.clientY - gap - h // no room below -> flip above
+    y = Math.max(4, y)
+    label.style.left = x + 'px'
+    label.style.top = y + 'px'
+  }
+
+  // hover-follow: the label chases the cursor while a mode is on - BUT a locked
+  // element (#4 composing / #5 thread open) freezes it: the lit element is the one
+  // being discussed, not whatever the pointer grazes.
+  on(document, 'mousemove', (e) => {
+    if (!modeActive() || lockedEl) 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)
+
+  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(' > ')
+  }
+  // the element's live depth hue (0..300) - so the shell can tint the pin / composer /
+  // thread card in the same colour the element wears in laser, and keep it after a reload
+  const hueOf = (el) => {
+    const raw = getComputedStyle(el).getPropertyValue('--mv-hue').trim()   // set by the mode sheet
+    const n = raw === '' ? NaN : Number(raw)
+    return Number.isFinite(n) ? ((n % 360) + 360) % 360 : 210              // fallback: a calm blue
+  }
+  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,
+        hue: hueOf(el),
+      },
+      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 },
+    }
+  }
+
+  // every press is reported so the shell can close an open thread card when the click
+  // lands INSIDE a frame (shell-document listeners never see those)
+  on(document, 'pointerdown', () => post({ type: 'sh:frame-down', id: getId() }), true)
+
+  on(document, '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
+    if (pickOn) {
+      // #4: lock the chosen element the instant it is picked - no round-trip flicker.
+      // The shell re-confirms via sh:highlight-anchor once the draft is staged.
+      applyLock(el, hueOf(el))
+      clearHover()
+      post({ type: 'sh:picked', id: getId(), anchor: anchorBundle(el, e) })
+    } else {
+      copyEl = el
+      post({ type: 'sh:laser-copy', id: getId(), seq: ++copySeq, path: cssPath(el), source: el.dataset.mvLoc ?? null })
+    }
+  }, true)
+
+  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
+  }
+
+  // re-resolve + re-apply the shell-driven highlight. Called on set and on every
+  // resolve-anchors pass, so a stage frame swapped in AFTER the highlight arrived
+  // (the DOM had not committed yet) still lights up on the next cycle - and, just as
+  // important, a target that has SINCE detached clears the lock (applyLock(null))
+  // instead of stranding a stale outline / a stuck hover-suppression.
+  const reapplyHighlight = () => {
+    if (!highlightAnchor) return
+    applyLock(resolveAnchor(highlightAnchor), highlightAnchor?.el?.hue)
+  }
+
+  const onMessage = (e) => {
+    if (e.source !== window.parent || window.parent === window) return
+    if (e.origin && e.origin !== location.origin) return   // a navigated frame must not spoof shell commands
+    const m = e?.data
+    if (!m || typeof m !== 'object') return
+    if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes(); onModeChange?.(laserOn, pickOn) }
+    else if (m.type === 'sh:pick') {
+      pickOn = !!m.on; applyModes()
+      // leaving comment mode drops a provisional self-lock the shell never confirmed;
+      // a shell-owned highlight (highlightAnchor set, e.g. #5) survives
+      if (!pickOn && !highlightAnchor) clearLock()
+      onModeChange?.(laserOn, pickOn)
+    }
+    else if (m.type === 'sh:copy-ok') showCopied(m.seq)
+    else if (m.type === 'sh:highlight-anchor') {
+      // null clears; an anchor locks its element (the pick draft #4, or the opened thread
+      // #5). No frame-id guard: a canvas frame only ever receives its OWN highlights (the
+      // shell posts to that one iframe), and an HTML frame reports id=pathname != frame.id
+      // so a guard would wrongly drop every one. Stage-swap staleness is handled instead by
+      // resolveAnchor failing on the wrong DOM (-> clear) and reapplyHighlight relighting on
+      // the next resolve tick once the new frame has committed.
+      if (!m.anchor) { clearLock(); return }
+      highlightAnchor = m.anchor
+      applyLock(resolveAnchor(m.anchor), m.anchor?.el?.hue)
+    }
+    else 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 } }
+      })
+      reapplyHighlight()
+      post({ type: 'sh:anchor-rects', id: getId(), rects })
+    }
+  }
+  on(window, 'message', onMessage)
+
+  injectBase()
+  return {
+    modeActive, isLaser: () => laserOn, isPick: () => pickOn,
+    // remove every listener + injected style + clear timers/locks (stage remount safety)
+    dispose() {
+      removers.forEach((f) => f())
+      clearTimeout(copiedTimer)
+      clearHover(); clearLock()
+      document.getElementById(LASER_ID)?.remove()
+      document.getElementById(BASE_ID)?.remove()
+    },
+  }
+}