@marver-design/marver 0.3.1 → 0.4.0

package/src/client/shell/Comments.tsx

@@ -0,0 +1,463 @@
+/**
+ * Comment surfaces on the canvas (SPEC-M3 §6). Canvas-first: pins live ON the frame
+ * at their anchored elements; an inactive frame collapses its open threads into a
+ * top-right stack; the thread card opens beside its pin. Pins keep a screen-space
+ * size via --sh-inv (the vbadge pattern) so zoom never shrinks them away.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { avatarFallback, useComments } from './comments-store.ts'
+import { useStore, type Node } from './store.ts'
+import { canvasCtl } from './canvas/Canvas.tsx'
+import { bootHash, buildHash, parseHash, writeHash } from './hash.ts'
+import { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, XIcon } from './icons.tsx'
+import { Tip } from './Tip.tsx'
+import { ROUTE } from '../const.ts'
+import type { Thread } from '../../shared/events.ts'
+
+const rel = (ts: number) => {
+  const m = Math.round((Date.now() - ts) / 60_000)
+  if (m < 1) return 'now'
+  if (m < 60) return `${m}m`
+  if (m < 24 * 60) return `${Math.round(m / 60)}h`
+  return `${Math.round(m / 1440)}d`
+}
+
+export function Avatar({ author, size = 22 }: { author?: { email?: string; name?: string; avatar?: string }; size?: number }) {
+  if (author?.avatar) return <img className="cm-avatar" src={author.avatar} width={size} height={size} alt="" />
+  const { initials, hue } = avatarFallback(author)
+  return (
+    <span className="cm-avatar" style={{ width: size, height: size, fontSize: size * 0.42, background: `hsl(${hue} 55% 45%)` }}>
+      {initials}
+    </span>
+  )
+}
+
+type Face = { email?: string; name?: string; avatar?: string }
+
+/** The signal a marker (pin or stack) carries: WHO took part and HOW MANY comments
+ *  in total - root + every reply, across all the given threads. Unique participants
+ *  in first-seen order; a single reply-less comment counts as 1. */
+function markerDigest(threads: Thread[]): { faces: Face[]; count: number } {
+  const seen = new Map<string, Face>()
+  let count = 0
+  // namespace the identity key so an email can never collide with someone's name,
+  // and normalize email case; authorless comments collapse to one 'anon' face
+  const add = (a?: Face) => { if (a) { const k = a.email ? `e:${a.email.toLowerCase()}` : a.name ? `n:${a.name}` : 'anon'; if (!seen.has(k)) seen.set(k, a) } }
+  for (const t of threads) {
+    count += 1 + t.replies.length
+    add(t.author)
+    for (const r of t.replies) add(r.author)
+  }
+  return { faces: [...seen.values()], count }
+}
+
+/** The face of a marker: up to `max` overlapping avatars + the total count when >1.
+ *  One shape for pins (one thread, anchored) and stacks (all threads on a frame). */
+function MarkerFace({ threads, max = 3 }: { threads: Thread[]; max?: number }) {
+  const { faces, count } = markerDigest(threads)
+  return (
+    <>
+      {faces.slice(0, max).map((a, i) => <Avatar key={i} author={a} size={24} />)}
+      {count > 1 && <b>{count}</b>}
+    </>
+  )
+}
+
+/** Lives inside FrameNode's body, over the iframe. Owns anchor resolution for its frame. */
+export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: string; iframe: React.RefObject<HTMLIFrameElement | null> }) {
+  const show = useComments((s) => s.show)
+  const active = useComments((s) => s.active)
+  const draft = useComments((s) => s.draft)
+  // select the stable array, filter in render - a selector returning a fresh
+  // .filter() array re-renders forever (Object.is never matches)
+  const allThreads = useComments((s) => s.threads)
+  const threads = allThreads.filter((t) => t.frame === frameId && (!t.nodeKey || t.nodeKey === node.key))
+  const selected = useStore((s) => s.selection.includes(node.key))
+  const { setActive } = useComments.getState()
+  const [rects, setRects] = useState<Record<string, { x: number; y: number; w: number; h: number } | null>>({})
+
+  const open = threads.filter((t) => !t.resolved)
+  const anchored = open.filter((t) => (t.anchor as any)?.el)
+
+  // resolve anchors against the live frame whenever threads or the document change
+  useEffect(() => {
+    const win = iframe.current?.contentWindow
+    if (!win || node.status !== 'ready' || !anchored.length) return
+    const ask = () => win.postMessage({ type: 'sh:resolve-anchors', anchors: anchored.map((t) => ({ key: t.id, anchor: t.anchor })) }, location.origin)
+    const onMsg = (e: MessageEvent) => {
+      if (e.source !== win || e.data?.type !== 'sh:anchor-rects') return
+      const next: typeof rects = {}
+      for (const r of e.data.rects ?? []) next[r.key] = r.orphan ? null : r.rect
+      setRects(next)
+    }
+    window.addEventListener('message', onMsg)
+    ask()
+    const iv = setInterval(ask, 4000)          // re-renders, scroll, hot reloads - cheap to re-ask
+    return () => { clearInterval(iv); window.removeEventListener('message', onMsg) }
+  }, [node.status, anchored.map((t) => t.id).join(','), iframe])
+
+  const drafting = draft?.nodeKey === node.key
+  if (!show || (!open.length && !drafting)) return null
+
+  // inactive frame: the stack - count + avatars, top-right (SPEC-M3 §6)
+  const engaged = selected || open.some((t) => t.id === active) || drafting
+  if (!engaged && open.length) {
+    return (
+      <button className="cm-stack sh-no-pan" onClick={(e) => { e.stopPropagation(); useStore.getState().select(node.key); if (open[0]) setActive(open[0].id) }}>
+        <MarkerFace threads={open} />
+      </button>
+    )
+  }
+
+  const pinPos = (t: Thread) => {
+    const a = t.anchor as any
+    const r = rects[t.id]
+    if (a?.el && r) return { x: r.x + (a.pos?.fx ?? 0.5) * r.w, y: r.y + (a.pos?.fy ?? 0.5) * r.h, orphan: false }
+    if (a?.el && r === null) return { x: node.w - 16, y: 16, orphan: true }         // orphan parks top-right
+    const p = a?.pos                                                                // frame-level: stored fraction of the frame
+    return { x: (p?.fx ?? 0.94) * node.w, y: (p?.fy ?? 0.06) * node.h, orphan: false }
+  }
+
+  return (
+    <>
+      {open.map((t) => {
+        const { x, y, orphan } = pinPos(t)
+        return (
+          <div key={t.id} className={`cm-pin sh-no-pan${t.id === active ? ' on' : ''}${orphan ? ' orphan' : ''}`}
+            style={{ left: x, top: y }}
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={(e) => { e.stopPropagation(); setActive(t.id === active ? null : t.id) }}
+            title={orphan ? 'the anchored element is gone - comment parked' : undefined}>
+            <MarkerFace threads={[t]} />
+          </div>
+        )
+      })}
+      {active && open.some((t) => t.id === active) && (
+        <ThreadCard key={active} thread={open.find((t) => t.id === active)!} at={pinPos(open.find((t) => t.id === active)!)} node={node} />
+      )}
+      {draft?.nodeKey === node.key && <DraftComposer at={{ x: ((draft.anchor as any)?.rect?.x ?? 0) + ((draft.anchor as any)?.pos?.fx ?? 0.5) * ((draft.anchor as any)?.rect?.w ?? 0), y: ((draft.anchor as any)?.rect?.y ?? 0) + ((draft.anchor as any)?.pos?.fy ?? 0.5) * ((draft.anchor as any)?.rect?.h ?? 0) }} node={node} />}
+    </>
+  )
+}
+
+function ThreadCard({ thread, at, node }: { thread: Thread; at: { x: number; y: number }; node: Node }) {
+  const { resolve, setActive } = useComments.getState()
+  const me = useComments((s) => s.me)
+  const local = useComments((s) => s.local)
+  const canComment = local || !!me      // dev is always "me"; published needs a session
+  const [text, setText] = useState('')
+  const [copied, setCopied] = useState(false)
+  const copyTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
+  useEffect(() => () => clearTimeout(copyTimer.current), [])
+  const flip = at.x > node.w * 0.55
+  // clear only after the server took it - a failed send must not eat the words,
+  // and text typed WHILE the request was in flight must survive the clear
+  const submit = async () => {
+    const sent = text
+    if (sent.trim() && await useComments.getState().replyOk(thread.id, sent)) setText((cur) => (cur === sent ? '' : cur))
+  }
+  return (
+    <div className={`cm-card sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, node.h - 40) }}
+      onPointerDown={(e) => e.stopPropagation()} onClick={(e) => e.stopPropagation()} onWheel={(e) => e.stopPropagation()}>
+      {/* thread-level actions pin to the card corner, out of the header's flow -
+          the name row never has to share its line with them */}
+      <div className="cm-actions">
+        <Tip side="bottom" label={<b>{copied ? 'Copied' : 'Copy link'}</b>}>
+          <button className={`cm-icon cm-copy${copied ? ' ok' : ''}`} onClick={() => {
+            const url = `${location.origin}${location.pathname}${buildHash({ board: useStore.getState().board, c: thread.id })}`
+            // the check means "it's on your clipboard" - only show it when that's true
+            navigator.clipboard.writeText(url).then(() => {
+              setCopied(true)
+              clearTimeout(copyTimer.current)
+              copyTimer.current = setTimeout(() => setCopied(false), 1600)
+            }, () => useStore.getState().toast('copy blocked - try again'))
+          }}>
+            <span className="a"><LinkIcon size={15} /></span>
+            <span className="b"><CheckIcon size={16} /></span>
+          </button>
+        </Tip>
+        <Tip side="bottom" label={<b>Resolve</b>}>
+          <button className="cm-icon" onClick={() => { void resolve(thread.id); setActive(null) }}><CheckSquareOffsetIcon size={16} /></button>
+        </Tip>
+        <Tip side="bottom" label={<b>Close</b>}>
+          <button className="cm-icon" onClick={() => setActive(null)}><XIcon size={15} /></button>
+        </Tip>
+      </div>
+      <header>
+        <Avatar author={thread.author} size={24} />
+        <b>{thread.author?.name ?? 'Someone'}</b>
+        <span className="dim">{rel(thread.ts)}</span>
+      </header>
+      <p className="cm-body">{thread.body}</p>
+      {/* replies repeat the root's exact message shape (Figma's pattern) - only the icons differ */}
+      {thread.replies.map((r) => (
+        <div key={r.id} className="cm-msg">
+          <header>
+            <Avatar author={r.author} size={24} />
+            <b>{r.author?.name ?? 'Someone'}</b>
+            <span className="dim">{rel(r.ts)}</span>
+          </header>
+          <p className="cm-body">{r.body}</p>
+        </div>
+      ))}
+      {canComment ? (
+        <div className="cm-compose">
+          <Avatar author={me ?? undefined} size={24} />
+          <div className="cm-inputwrap">
+            <input value={text} placeholder="Reply…" onChange={(e) => setText(e.target.value)}
+              onKeyDown={(e) => { e.stopPropagation(); if (e.key === 'Enter') void submit(); if (e.key === 'Escape') setActive(null) }} />
+            <button className="cm-send" disabled={!text.trim()} aria-label="Send" onClick={() => void submit()}>
+              <ArrowUpIcon size={15} />
+            </button>
+          </div>
+        </div>
+      ) : (
+        <button className="cm-signin-cta" onClick={() => useComments.setState({ needsIdentity: true })}>
+          Sign in to comment
+        </button>
+      )}
+    </div>
+  )
+}
+
+function DraftComposer({ at, node }: { at: { x: number; y: number }; node: Node }) {
+  const { create, setDraft } = useComments.getState()
+  const [text, setText] = useState('')
+  const ref = useRef<HTMLInputElement>(null)
+  useEffect(() => { ref.current?.focus() }, [])
+  const flip = at.x > node.w * 0.55
+  return (
+    <div className={`cm-card cm-draft sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, node.h - 40) }}
+      onPointerDown={(e) => e.stopPropagation()} onClick={(e) => e.stopPropagation()}>
+      <div className="cm-compose">
+        <div className="cm-inputwrap">
+          <input ref={ref} value={text} placeholder="Comment on this element…" onChange={(e) => setText(e.target.value)}
+            onKeyDown={(e) => {
+              e.stopPropagation()
+              if (e.key === 'Enter') void create(text)
+              if (e.key === 'Escape') setDraft(null)
+            }} />
+          <button className="cm-send" disabled={!text.trim()} aria-label="Comment" onClick={() => void create(text)}>
+            <ArrowUpIcon size={15} />
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** Avatar picker: dashed circle → file input → client-side 128px downscale →
+ *  data-URI preview. Optional everywhere it appears; never gates a CTA. */
+function AvatarPick({ value, onPick }: { value: string; onPick: (dataUri: string) => void }) {
+  const fileRef = useRef<HTMLInputElement>(null)
+  const pick = (file: File | undefined) => {
+    if (!file) return
+    const img = new Image()
+    img.onload = () => {
+      const s = Math.min(img.width, img.height)
+      const c = document.createElement('canvas')
+      c.width = c.height = 128
+      c.getContext('2d')!.drawImage(img, (img.width - s) / 2, (img.height - s) / 2, s, s, 0, 0, 128, 128)
+      onPick(c.toDataURL('image/jpeg', 0.85))
+      URL.revokeObjectURL(img.src)
+    }
+    img.src = URL.createObjectURL(file)
+  }
+  return (
+    <>
+      <Tip side="top" label={<b>{value ? 'Change your photo' : 'Select your profile picture'}</b>}>
+        <button className={`cm-pfp${value ? ' set' : ''}`} aria-label="Select your profile picture"
+          style={value ? { backgroundImage: `url(${value})` } : undefined}
+          onClick={() => fileRef.current?.click()}>{value ? '' : '+'}</button>
+      </Tip>
+      <input ref={fileRef} type="file" accept="image/*" hidden onChange={(e) => pick(e.target.files?.[0])} />
+    </>
+  )
+}
+
+/** Signed-out published viewer tried to comment (or arrived on an invite link).
+ *  Invite link: a focused claim - the token in hand, email shown as a chip.
+ *  Fallback: sign in (returning device), with a quiet switch to pasting a token.
+ *  Primary CTAs stay disabled until their mandatory fields are filled; hovering
+ *  the disabled button says what's missing (avatar never gates). */
+export function IdentityDialog() {
+  const needs = useComments((s) => s.needsIdentity)
+  const invite = useComments((s) => s.inviteToken)
+  const { signIn, claim, dismissIdentity } = useComments.getState()
+  const [mode, setMode] = useState<'signin' | 'claim'>('signin')
+  const [email, setEmail] = useState(''); const [password, setPassword] = useState('')
+  const [token, setToken] = useState(''); const [name, setName] = useState('')
+  const [avatar, setAvatar] = useState('')
+  const [invitedAs, setInvitedAs] = useState('')
+  const [err, setErr] = useState<string | null>(null)
+  // an invite link knows WHO it's for - show it (the token is the proof of holding)
+  useEffect(() => {
+    if (!needs || !invite) return setInvitedAs('')
+    fetch(`${ROUTE}/api/invite-info?token=${encodeURIComponent(invite)}`)
+      .then((r) => (r.ok ? r.json() : null))
+      .then((d) => d?.email && setInvitedAs(d.email))
+      .catch(() => { /* chip just stays hidden */ })
+  }, [needs, invite])
+  if (!needs) return null
+  const claiming = !!invite || mode === 'claim'
+  const ready = claiming
+    ? !!(password.trim() && name.trim() && (invite || token.trim()))
+    : !!(email.trim() && password.trim())
+  const missing = claiming
+    ? (invite ? 'Password and display name still needed' : 'Token, password, and display name still needed')
+    : 'Fill in email and password'
+  const go = async () => {
+    if (!ready) return
+    setErr(null)
+    const e = claiming ? await claim(invite ?? token, password, name, avatar || undefined) : await signIn(email, password)
+    if (e) return setErr(e)
+    // a consumed invite link leaves the URL - the hash becomes the plain board view
+    if (invite) writeHash({ board: useStore.getState().board })
+  }
+  const onEnter = (e: React.KeyboardEvent) => e.key === 'Enter' && void go()
+  return (
+    <div className="cm-modal-wrap" onClick={dismissIdentity}>
+      <div className="cm-modal" onClick={(e) => e.stopPropagation()}>
+        <h2>{invite ? 'You’re invited to comment' : claiming ? 'Sign up to comment' : 'Sign in to comment'}</h2>
+        <p className="dim">
+          {invite
+            ? <>Pick how you’ll appear - comments carry your name.</>
+            : claiming
+              ? <>Create your account with the invite token your admin sent you.</>
+              : <>You’re in read-only. Sign in to your account to comment on this canvas.</>}
+        </p>
+        <div className="cm-fields">
+          {claiming ? (
+            <>
+              {invite
+                ? invitedAs && <div className="cm-chip"><b>{invitedAs}</b><span>INVITED</span></div>
+                : <input placeholder="Invite token" value={token} onChange={(e) => setToken(e.target.value)} />}
+              <input placeholder="Choose a password" type="password" autoComplete="new-password"
+                value={password} onChange={(e) => setPassword(e.target.value)} />
+              <hr className="cm-div" />
+              <div className="cm-idrow">
+                <AvatarPick value={avatar} onPick={setAvatar} />
+                <input placeholder="Set a display name" style={{ flex: 1 }}
+                  value={name} onChange={(e) => setName(e.target.value)} onKeyDown={onEnter} />
+              </div>
+            </>
+          ) : (
+            <>
+              <input placeholder="Email" type="email" autoComplete="email"
+                value={email} onChange={(e) => setEmail(e.target.value)} />
+              <input placeholder="Password" type="password" autoComplete="current-password"
+                value={password} onChange={(e) => setPassword(e.target.value)} onKeyDown={onEnter} />
+            </>
+          )}
+        </div>
+        {err && <span className="cm-err">{err}</span>}
+        <div className="cm-row">
+          {ready ? (
+            <button className="cm-primary" onClick={() => void go()}>
+              {claiming ? (invite ? 'Join the canvas' : 'Create account') : 'Sign in'}
+            </button>
+          ) : (
+            <Tip side="top" label={<b>{missing}</b>}>
+              <button className="cm-primary" disabled>
+                {claiming ? (invite ? 'Join the canvas' : 'Create account') : 'Sign in'}
+              </button>
+            </Tip>
+          )}
+          <button onClick={dismissIdentity}>Not now</button>
+        </div>
+        {!invite && (
+          <button className="cm-switch" onClick={() => { setErr(null); setMode(mode === 'signin' ? 'claim' : 'signin') }}>
+            {mode === 'signin' ? 'Have an invite token instead?' : 'Already have an account? Sign in'}
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+/** Open a thread by id: activate, select its node, fit the camera. True on success. */
+function revealThread(c: string): boolean {
+  const t = useComments.getState().threads.find((t) => t.id === c)
+  if (!t) return false
+  useComments.getState().setActive(c)
+  const node = t.nodeKey && useStore.getState().nodes.find((n) => n.key === t.nodeKey)
+  if (node) {
+    useStore.getState().select(node.key)
+    setTimeout(() => canvasCtl.fitNode(node.key), 80)
+  }
+  return true
+}
+
+/** Board-level comment wiring: load + liveness + mode broadcast, one instance in App. */
+let bootThreadConsumed = false
+let pendingThread: string | null = null   // cross-board deep link awaiting its board's comments
+export function CommentsController() {
+  const board = useStore((s) => s.board)
+  const commentMode = useComments((s) => s.commentMode)
+  const active = useComments((s) => s.active)
+
+  // modal-style dismiss: any press outside the card (and outside the surfaces that
+  // legitimately manage it - pins, stacks, the identity dialog) closes the thread
+  useEffect(() => {
+    if (!active) return
+    const onDown = (e: PointerEvent) => {
+      const t = e.target instanceof Element ? e.target : null
+      if (t?.closest('.cm-card, .cm-pin, .cm-stack, .cm-modal')) return
+      useComments.getState().setActive(null)
+    }
+    document.addEventListener('pointerdown', onDown, true)
+    return () => document.removeEventListener('pointerdown', onDown, true)
+  }, [active])
+
+  useEffect(() => {
+    const { load, live } = useComments.getState()
+    void load(board).then(() => {
+      // invite link (#/i/<token>): open the claim dialog with the token in hand -
+      // unless this browser is already someone (their invite is not for this session)
+      const s = useComments.getState()
+      if (bootHash.invite && !s.local && !s.me && !s.inviteToken)
+        useComments.setState({ inviteToken: bootHash.invite, needsIdentity: true })
+      // a cross-board deep link parks its thread id here until the target board's
+      // comments have actually loaded - a timer can't know how long that takes
+      if (pendingThread && revealThread(pendingThread)) { pendingThread = null; return }
+      // deep link ?c=<thread> (SPEC-M3 §6): open the thread, select its node, fit it.
+      // Consumed only on a successful find: the controller's first effect fires with
+      // the pre-boot board (child effects run before the parent's boot effect), and
+      // burning the flag on that empty pass would eat the link.
+      if (bootThreadConsumed || !bootHash.c) return
+      if (revealThread(bootHash.c)) bootThreadConsumed = true
+    })
+    return live(board)
+  }, [board])
+
+  // a comment link pasted into an ALREADY-OPEN canvas is a hash-only navigation -
+  // no reload, no boot path. Same board: the threads are in memory, reveal now.
+  // Different board: park the id; the load effect above consumes it once the
+  // board switch has fetched that board's comments.
+  useEffect(() => {
+    const onHash = (e: HashChangeEvent) => {
+      // read the URL the EVENT carries, not location.hash: the shell's own
+      // hashchange handler resets selection, whose projection synchronously
+      // rewrites the hash - listener order decides which URL survives, and
+      // e.newURL is immune to that race
+      const h = parseHash(e.newURL ? new URL(e.newURL).hash : location.hash)
+      if (h.invite) {
+        const s = useComments.getState()
+        if (!s.local && !s.me) useComments.setState({ inviteToken: h.invite, needsIdentity: true })
+        return
+      }
+      if (!h.c) return
+      if (!revealThread(h.c)) pendingThread = h.c
+    }
+    window.addEventListener('hashchange', onHash)
+    return () => window.removeEventListener('hashchange', onHash)
+  }, [])
+
+  // broadcast pick mode to every frame (laser rides along inside the bridge)
+  useEffect(() => {
+    for (const f of document.querySelectorAll('iframe'))
+      (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode }, location.origin)
+  }, [commentMode])
+
+  return <IdentityDialog />
+}

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

@@ -1,6 +1,8 @@
 import { memo, useEffect, useRef } from 'react'
 import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
 import { CopyIcon, IntentGlyph, ReloadIcon, XIcon } from '../icons.tsx'
+import { CommentLayer } from '../Comments.tsx'
+import { useComments } from '../comments-store.ts'
 
 export const HEADER = 28
 const SNAP = 12
@@ -36,6 +38,25 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     }
   }, [node.theme])
 
+  // laser mode (SPEC-M3 §7) rides the same rail; re-sent when a frame becomes ready
+  // so late loaders join an already-lasered board
+  const laser = useStore((s) => s.laser)
+  const commentMode = useComments((s) => s.commentMode)
+  // a node hosting the OPEN thread card (or a draft composer) rises above its
+  // neighbors - each node is a stacking context, so an overflowing card would
+  // otherwise paint under the next frame
+  const hostsCard = useComments((s) =>
+    (!!s.active && s.threads.some((t) => t.id === s.active && t.nodeKey === node.key)) || s.draft?.nodeKey === node.key)
+  useEffect(() => {
+    if (node.status === 'ready' || !laser)
+      iframeRef.current?.contentWindow?.postMessage({ type: 'sh:laser', on: laser }, location.origin)
+  }, [laser, node.status])
+  // comment mode = pick mode in the frame (late loaders join like laser does)
+  useEffect(() => {
+    if (node.status === 'ready' || !commentMode)
+      iframeRef.current?.contentWindow?.postMessage({ type: 'sh:pick', on: commentMode }, location.origin)
+  }, [commentMode, node.status])
+
   // a frame whose FILE actually changed (e.g. tsx -> html swap, same id) must renavigate
   useEffect(() => {
     if (!frame) return
@@ -157,7 +178,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     <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 }}
+      style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER, zIndex: hostsCard ? 30 : undefined }}
       data-node={node.key}
     >
       {frame.variantGroup && (
@@ -197,7 +218,10 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
           title={frame.id}
           style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
         />
-        {!interact && (
+        {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
+            need the mouse INSIDE the frame for hover highlights, so it steps aside
+            (drag still works via the header) */}
+        {!interact && !commentMode && !laser && (
           <div
             className="sh-overlay sh-no-pan"
             onPointerDown={(e) => drag(e, 'move')}
@@ -206,6 +230,12 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         )}
       </div>
 
+      {/* comments live OUTSIDE the clipped body: a card or pin near the frame edge
+          hangs over it (the vbadge precedent) instead of being cut off */}
+      <div className="cm-layer" style={{ top: HEADER, height: node.h }}>
+        <CommentLayer node={node} frameId={frame.id} iframe={iframeRef} />
+      </div>
+
       {selected && (
         <>
           <div className="sh-handle e sh-no-pan" onPointerDown={(e) => drag(e, 'e')} />