@marver-design/marver 0.7.0 → 0.8.0

package/src/client/shell/Comments.tsx

@@ -5,14 +5,16 @@
  * size via --sh-inv (the vbadge pattern) so zoom never shrinks them away.
  */
 import { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
 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 { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, ParallelogramFillIcon, PencilSimpleIcon, PlusIcon, XIcon } from './icons.tsx'
 import { Tip } from './Tip.tsx'
+import { parseMentions } from './mentions.ts'
 import { ROUTE } from '../const.ts'
-import type { Thread } from '../../shared/events.ts'
+import type { AgentMeta, Thread } from '../../shared/events.ts'
 
 /** Tint the pin / composer / thread card EDGES (border, outline, focus ring) in the anchored
  *  element's own laser hue (captured at pick as anchor.el.hue) via --cm-line/--cm-line-ring.
@@ -43,9 +45,27 @@ const rel = (ts: number) => {
   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)
+/** The Marver mark avatar: accent-blue disc + the solid white parallelogram. One place, reused
+ *  by the thread header, the pin/stack marker, and the notification pill. */
+export function MarverAvatar({ size = 24 }: { size?: number }) {
+  // 0.5 keeps clear blue padding around the mark even in the marker, where a 2px white border
+  // shrinks the visible disc (a bigger mark looked nearly cut there).
+  return (
+    <span className="cm-avatar cm-marver" style={{ width: size, height: size }} aria-label="Marver">
+      <ParallelogramFillIcon size={Math.round(size * 0.5)} />
+    </span>
+  )
+}
+
+export function Avatar({ author, size = 22 }: { author?: { email?: string; name?: string; avatar?: string; agent?: boolean }; size?: number }) {
+  const me = useComments((s) => s.me)
+  const local = useComments((s) => s.local)
+  if (author?.agent) return <MarverAvatar size={size} />   // Marver shows as its own participant
+  // dev: an account-less author IS the person at this keyboard - render the CURRENT identity,
+  // not the snapshot the event happened to store (old "Designer" events become you, live)
+  const a = local && me && !author?.email ? { ...author, ...me } : author
+  if (a?.avatar) return <img className="cm-avatar" src={a.avatar} width={size} height={size} alt="" />
+  const { initials, hue } = avatarFallback(a)
   return (
     <span className="cm-avatar" style={{ width: size, height: size, fontSize: size * 0.42, background: `hsl(${hue} 55% 45%)` }}>
       {initials}
@@ -53,7 +73,7 @@ export function Avatar({ author, size = 22 }: { author?: { email?: string; name?
   )
 }
 
-type Face = { email?: string; name?: string; avatar?: string }
+type Face = { email?: string; name?: string; avatar?: string; agent?: boolean }
 
 /** 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
@@ -61,13 +81,20 @@ type Face = { email?: string; name?: string; avatar?: string }
 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) } }
+  // namespace the identity key so an email can never collide with someone's name, and normalize
+  // email case. An AGENT message is its own participant ("Marver"), NOT the owner who authored
+  // it - so the marker shows N + Marver. Every email-less human face collapses to ONE key: in
+  // dev those snapshots ("Designer", "You", nothing) are all the person at this keyboard, and
+  // Avatar renders them all as the live identity - two keys would show identical twin faces.
+  const add = (a: Face | undefined, agent?: boolean) => {
+    const face: Face | undefined = agent ? { agent: true } : a
+    const k = agent ? 'marver' : a?.email ? `e:${a.email.toLowerCase()}` : 'local'
+    if (face && !seen.has(k)) seen.set(k, face)
+  }
   for (const t of threads) {
     count += 1 + t.replies.length
-    add(t.author)
-    for (const r of t.replies) add(r.author)
+    add(t.author, t.agent)
+    for (const r of t.replies) add(r.author, r.agent)
   }
   return { faces: [...seen.values()], count }
 }
@@ -87,6 +114,7 @@ export function MarkerFace({ threads, max = 3 }: { threads: Thread[]; max?: numb
 /** 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 showAnchor = useComments((s) => s.showAnchor)
   const active = useComments((s) => s.active)
   const draft = useComments((s) => s.draft)
   // select the stable array, filter in render - a selector returning a fresh
@@ -128,15 +156,24 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
     const win = iframe.current?.contentWindow
     if (!win || node.status !== 'ready') return
     // ONLY light an element while its thread is the active one (or a draft is composing on
-    // it) AND pins are shown - closing the thread or hiding comments (⇧C) clears it, so a
-    // stray outline never lingers on the frame.
+    // it) AND pins are shown AND element focus is on (⇧L) - closing the thread, hiding
+    // comments (⇧C), or dimming focus clears it, so a stray outline never lingers.
     const draftHere = draft?.nodeKey === node.key ? (draft.anchor as any) : null
     const activeHere = active ? open.find((t) => t.id === active && (t.anchor as any)?.el) : undefined
-    const anchor = show ? (draftHere ?? (activeHere ? (activeHere.anchor as any) : null)) : null
+    const anchor = show && showAnchor ? (draftHere ?? (activeHere ? (activeHere.anchor as any) : null)) : null
     win.postMessage({ type: 'sh:highlight-anchor', frame: frameId, anchor: anchor ?? null }, location.origin)
-    // active/draft/show/activeShown are the triggers; `open` is read fresh from the closure
-  }, [active, draft, show, activeShown, node.status, node.key, frameId, iframe])
+    // active/draft/show/showAnchor/activeShown are the triggers; `open` is read fresh from the closure
+  }, [active, draft, show, showAnchor, activeShown, node.status, node.key, frameId, iframe])
 
+  // the open card's frozen side (D3) - a HOOK, so it must live above the early returns; and the
+  // reset must too: a card can close via the inactive-frame early return (clicking another frame),
+  // which never reaches the render tail - reopen must still RE-PICK the side (Codex P2)
+  const sideRef = useRef<{ id: string; side: 'l' | 'r' } | null>(null)
+  if (sideRef.current && sideRef.current.id !== active) sideRef.current = null
+  // what occupies this frame's LEFT flank (drives the docked card's left gutter): a variant
+  // badge is widest, the working shimmer next. Reactive, so a job starting mid-read adjusts.
+  const flankBadge = useStore((s) => !!s.frameFor(node)?.variantGroup)
+  const flankShim = useStore((s) => s.working.includes(frameId))
   const drafting = draft?.nodeKey === node.key
   if (!show || (!open.length && !drafting)) return null
 
@@ -159,12 +196,38 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
     return { x: (p?.fx ?? 0.94) * node.w, y: (p?.fy ?? 0.06) * node.h, orphan: false }
   }
 
+  // The card's SIDE, chosen ONCE per open and frozen (D3 - never switches mid-read): the pin's
+  // side of the frame first, skipping a side another frame's screen rect occupies, then wherever
+  // the viewport has room. The active pin's teardrop tail flips toward this side.
+  const activeThread2 = active ? open.find((t) => t.id === active) : undefined
+  if (activeThread2 && sideRef.current?.id !== activeThread2.id) {
+    const compute = (): 'l' | 'r' => {
+      const W = 320, GAP = 30
+      const rect = document.querySelector(`[data-node="${CSS.escape(node.key)}"]`)?.getBoundingClientRect()
+      if (!rect) return 'r'
+      const occupied = (s: 'l' | 'r') => {
+        const rx = s === 'r' ? rect.right + 10 : rect.left - 10 - W
+        return [...document.querySelectorAll('.sh-node')].some((n) => {
+          if (n.getAttribute('data-node') === node.key) return false
+          const r = n.getBoundingClientRect()
+          return r.left < rx + W && r.right > rx && r.top < rect.bottom && r.bottom > rect.top
+        })
+      }
+      const room = (s: 'l' | 'r') => (s === 'r' ? window.innerWidth - rect.right : rect.left) >= W + GAP
+      const prefer: ('l' | 'r')[] = pinPos(activeThread2).x < node.w / 2 ? ['l', 'r'] : ['r', 'l']
+      return prefer.find((s) => room(s) && !occupied(s)) ?? prefer.find(room) ?? prefer[0]
+    }
+    sideRef.current = { id: activeThread2.id, side: compute() }
+  }
+  const cardSide: 'l' | 'r' = sideRef.current?.side ?? 'r'
+
   return (
     <>
       {open.map((t) => {
         const { x, y, orphan } = pinPos(t)
+        const isActive = t.id === active
         return (
-          <div key={t.id} className={`cm-pin sh-no-pan${t.id === active ? ' on' : ''}${orphan ? ' orphan' : ''}`}
+          <div key={t.id} className={`cm-pin sh-no-pan${isActive ? ' on' : ''}${isActive && cardSide === 'r' ? ' tail-r' : ''}${orphan ? ' orphan' : ''}`}
             style={{ left: x, top: y, ...hueVars(anchorHue(t.anchor)) }}
             onPointerDown={(e) => e.stopPropagation()}
             onClick={(e) => { e.stopPropagation(); setActive(t.id === active ? null : t.id) }}
@@ -173,8 +236,9 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
           </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)!)} bounds={{ w: node.w, h: node.h }} />
+      {activeThread2 && (
+        <ThreadCard key={active} thread={activeThread2} at={pinPos(activeThread2)} bounds={{ w: node.w, h: node.h }} nodeKey={node.key} side={cardSide}
+          flank={cardSide === 'l' ? (flankBadge ? 'badge' : flankShim ? 'shim' : null) : null} />
       )}
       {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) }} bounds={{ w: node.w, h: node.h }} hue={anchorHue(draft.anchor)} />}
     </>
@@ -183,24 +247,327 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
 
 /** The open thread card - shared by canvas (bounds = node size, `at` in frame coords) and
  *  prototype (bounds = the on-screen stage size, `at` in screen coords). Geometry only. */
-export function ThreadCard({ thread, at, bounds }: { thread: Thread; at: { x: number; y: number }; bounds: { w: number; h: number } }) {
+// ---- Live Jam: @marver rendering + Marver identity (SPEC-live-jam §1, §7) ----------------------
+
+const AT_TIP = "Read like any other comment. Marver won't act on this unless the owner promotes it."
+
+/** A comment body with @marver mentions styled: owner-authored → bold accent (a live trigger);
+ *  anyone else's → plain + a teaching tooltip (context, not a command). */
+function CommentBody({ body, owner }: { body?: string; owner: boolean }) {
+  if (!body) return null
+  return (
+    <p className="cm-body">
+      {parseMentions(body).map((s, i) => !s.mention
+        ? <span key={i}>{s.text}</span>
+        : owner
+          ? <span key={i} className="cm-at owner">{s.text}</span>
+          : <Tip key={i} side="top" label={<span className="cm-at-tip">{AT_TIP}</span>}><span className="cm-at">{s.text}</span></Tip>)}
+    </p>
+  )
+}
+
+const HARNESS: Record<string, string> = { claude: 'Claude Code', codex: 'Codex', cursor: 'Cursor', opencode: 'OpenCode', droid: 'Factory Droid' }
+/** claude-opus-5 → Opus 5; gpt-5.1-codex → Gpt 5.1 Codex; unknown → as-is. */
+function prettyModel(m: string): string {
+  const cleaned = m.replace(/^claude-/, '').replace(/-/g, ' ')
+  return cleaned.replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+/** The provenance tooltip on the Marver avatar: who orchestrated the change (SPEC §7).
+ *  One row per fact, left-aligned, bold label + regular value - the house tooltip treatment. */
+function AgentMetaTip({ meta }: { meta?: AgentMeta }) {
+  const rows = [
+    meta?.devUser && ['Dev user', meta.devUser],
+    meta?.harness && ['Harness', HARNESS[meta.harness] ?? meta.harness],
+    meta?.model && ['Model', prettyModel(meta.model)],
+    meta?.effort && ['Effort', meta.effort],
+  ].filter(Boolean) as [string, string][]
+  if (!rows.length) return <b>Marver</b>
+  // Toolbar-tooltip treatment: the VALUE is bold + bright (what you scan), the label is a muted
+  // qualifier after it - like "Hide all UI  press H to reveal".
+  return (
+    <span className="cm-meta-tip">
+      {rows.map(([label, value]) => <span key={label} className="cm-meta-row"><b>{value}</b><span className="k">{label}</span></span>)}
+    </span>
+  )
+}
+
+/** A message header. Agent messages render as "Marver" with the mark + provenance tooltip;
+ *  human messages keep their avatar + name. While the dev profile is still UNSET, every own
+ *  message avatar invites editing on hover (discoverability); once set, only the composer's
+ *  avatar is the door. */
+function MessageHead({ author, agent, agentMeta, ts }: { author?: Thread['author']; agent?: boolean; agentMeta?: AgentMeta; ts: number }) {
+  const me = useComments((s) => s.me)
+  const local = useComments((s) => s.local)
+  const connected = useComments((s) => s.connected)
+  if (agent) return (
+    <header>
+      <Tip side="top" label={<AgentMetaTip meta={agentMeta} />}>
+        <span className="cm-marver-wrap"><MarverAvatar size={24} /></span>
+      </Tip>
+      <b className="cm-marver-name">Marver</b>
+      <span className="dim">{rel(ts)}</span>
+    </header>
+  )
+  // own = born on this machine without an account (no email); unset = identity still the default.
+  // Own messages render the CURRENT identity, not the stored snapshot - same rule as Avatar.
+  const unset = local && !connected && (!me?.name || me.name === 'You')
+  const own = local && !author?.email
+  const shown = own && me ? { ...author, ...me } : author
+  return (
+    <header>
+      {unset && own ? <EditableAvatar author={author} size={24} /> : <Avatar author={author} size={24} />}
+      <b>{shown?.name ?? 'Someone'}</b>
+      <span className="dim">{rel(ts)}</span>
+    </header>
+  )
+}
+
+/** An auto-growing composer with the full keybindings: Enter send, Shift+Enter newline,
+ *  Cmd/Ctrl+Enter send, Escape cancel; IME-guarded, disabled while a send is in flight. */
+function CommentInput({ value, onChange, onSubmit, onCancel, placeholder, autoFocus, sendLabel, owner }: {
+  value: string; onChange: (v: string) => void; onSubmit: () => void | Promise<unknown>
+  onCancel?: () => void; placeholder: string; autoFocus?: boolean; sendLabel: string; owner: boolean
+}) {
+  const ref = useRef<HTMLTextAreaElement>(null)
+  const hlRef = useRef<HTMLDivElement>(null)
+  const [busy, setBusy] = useState(false)
+  // +2: scrollHeight excludes the 1px borders, but border-box height includes them - without
+  // it every line is squeezed 2px and the single-line pill renders off-center
+  const grow = () => { const el = ref.current; if (el) { el.style.height = 'auto'; el.style.height = Math.min(el.scrollHeight + 2, 132) + 'px' } }
+  const syncScroll = () => { if (hlRef.current && ref.current) hlRef.current.scrollTop = ref.current.scrollTop }
+  useEffect(() => { if (autoFocus) ref.current?.focus() }, [autoFocus])
+  useEffect(grow, [value])
+  const submit = async () => {
+    if (busy || !value.trim()) return
+    setBusy(true)
+    try { await onSubmit() } finally { setBusy(false) }
+  }
+  return (
+    <div className="cm-inputwrap">
+      {/* Live mention highlight: a mirror layer behind the transparent-text textarea, so @marver shows
+          its trigger colour AS YOU TYPE (owner = accent-blue "this will run"; else muted). SPEC §1. */}
+      <div className="cm-hl" ref={hlRef} aria-hidden>
+        {parseMentions(value).map((s, i) => s.mention
+          ? <span key={i} className={owner ? 'cm-at owner' : 'cm-at'}>{s.text}</span>
+          : <span key={i}>{s.text}</span>)}
+        {value.endsWith('\n') ? '​' : ''}
+      </div>
+      <textarea ref={ref} rows={1} value={value} placeholder={placeholder} disabled={busy} spellCheck={false}
+        onChange={(e) => onChange(e.target.value)} onInput={grow} onScroll={syncScroll}
+        onKeyDown={(e) => {
+          e.stopPropagation()
+          if (e.key === 'Escape') { onCancel?.(); return }
+          if (e.key === 'Enter') {
+            if ((e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) return   // IME: mid-composition Enter must not send
+            if (e.shiftKey) return                                                            // newline
+            e.preventDefault(); void submit()                                                 // Enter / Cmd·Ctrl+Enter send
+          }
+        }} />
+      <Tip side="top" label={<b>⏎ send · ⇧⏎ new line</b>}>
+        <button className="cm-send" disabled={busy || !value.trim()} aria-label={sendLabel} onClick={() => void submit()}>
+          <ArrowUpIcon size={15} />
+        </button>
+      </Tip>
+    </div>
+  )
+}
+
+/** The dev identity: a full-screen modal (the IdentityDialog treatment - same classes, same
+ *  weight) with display name + photo, saved to design/.local/profile.json (this machine only).
+ *  When a connect account provides name/email (the published server validates authors), the name
+ *  is read-only here and only the photo is editable. Portaled to body: the thread card is
+ *  transformed + overflow-hidden, so anything anchored inside it clips. */
+function ProfileDialog({ onClose }: { onClose: () => void }) {
+  const me = useComments((s) => s.me)
+  const connected = useComments((s) => s.connected)
+  const unset = !connected && (!me?.name || me.name === 'You')
+  const [name, setName] = useState(unset ? '' : me?.name ?? '')
+  const [avatar, setAvatar] = useState(me?.avatar ?? '')
+  const [busy, setBusy] = useState(false)
+  const [err, setErr] = useState<string | null>(null)
+  const ready = connected || !!name.trim()
+  const save = async () => {
+    if (busy || !ready) return
+    setBusy(true)
+    try {
+      const e = await useComments.getState().saveProfile({ ...(connected ? {} : { name: name.trim() }), avatar })
+      if (e) return setErr(e)                  // a failed save must not close as if it worked
+      onClose()
+    } finally { setBusy(false) }
+  }
+  return createPortal(
+    <div className="cm-modal-wrap" onClick={onClose} onPointerDown={(e) => e.stopPropagation()}>
+      <div className="cm-modal" onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => { e.stopPropagation(); if (e.key === 'Escape') onClose() }}>
+        <h2>{unset ? 'Set up your profile' : 'Edit your profile'}</h2>
+        <p className="dim">
+          {connected
+            ? <>Your name comes from your connect account. The photo stays on this machine.</>
+            : <>Comments carry your name and photo. Saved to design/.local on this machine - yours, nowhere else.</>}
+        </p>
+        <div className="cm-fields">
+          <div className="cm-idrow">
+            <AvatarPick value={avatar} onPick={setAvatar} />
+            {connected
+              ? <div className="cm-chip" style={{ flex: 1 }}><b>{me?.name}</b><span>CONNECT</span></div>
+              : <input placeholder="Set a display name" style={{ flex: 1 }} value={name}
+                  onChange={(e) => setName(e.target.value)}
+                  onKeyDown={(e) => e.key === 'Enter' && void save()} />}
+          </div>
+        </div>
+        {err && <span className="cm-err">{err}</span>}
+        <div className="cm-row">
+          <button className="cm-primary" disabled={busy || !ready} onClick={() => void save()}>Save</button>
+          <button onClick={onClose}>Not now</button>
+        </div>
+      </div>
+    </div>,
+    // into .sh-app, NOT body: every theme token (--cm-modal-bg, inks) lives on .sh-app,
+    // and a body-portaled modal renders transparent outside that scope
+    document.querySelector('.sh-app') ?? document.body)
+}
+
+/** An avatar that IS the door to your profile: hover morphs it into a pen on gray, click opens
+ *  the modal. The composer's own avatar is always this door (dev only); while the profile is
+ *  still unset, every own message avatar is too - discoverability until identity is real. */
+function EditableAvatar({ author, size = 24 }: { author?: Thread['author']; size?: number }) {
+  const [open, setOpen] = useState(false)
+  return (
+    <span className="cm-me">
+      <Tip side="top" label={<b>Edit your profile</b>}>
+        <button className="cm-mebtn" aria-label="Edit your profile" onClick={() => setOpen(true)}>
+          <Avatar author={author} size={size} />
+          <span className="cm-pen-face"><PencilSimpleIcon size={Math.round(size * 0.55)} /></span>
+        </button>
+      </Tip>
+      {open && <ProfileDialog onClose={() => setOpen(false)} />}
+    </span>
+  )
+}
+
+/** The composer's own avatar (dev only - published viewers already have accounts). */
+function ComposeAvatar() {
+  const me = useComments((s) => s.me)
+  const local = useComments((s) => s.local)
+  if (!local) return <Avatar author={me ?? undefined} size={24} />
+  return <EditableAvatar author={me ?? undefined} size={24} />
+}
+
+export function ThreadCard({ thread, at, bounds, nodeKey, side = 'r', flank, stage }: { thread: Thread; at: { x: number; y: number }; bounds: { w: number; h: number }; nodeKey?: string; side?: 'l' | 'r'; flank?: 'badge' | 'shim' | null; stage?: boolean }) {
   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
+  // Owner-authored @marver is a live trigger (bold accent); anyone else's is context (plain + tooltip).
+  // Match by email when we know the owner's; in dev without a profile, local writes are the owner.
+  const isOwner = (a?: { email?: string }) => (me?.email ? a?.email === me.email : local)
   const [text, setText] = useState('')
   const [copied, setCopied] = useState(false)
   const copyTimer = useRef<ReturnType<typeof setTimeout>>(undefined)
   useEffect(() => () => clearTimeout(copyTimer.current), [])
-  const flip = at.x > bounds.w * 0.55
+  // Canvas: the card is a WORLD OBJECT parked beside its frame - it stays put (panning moves
+  // frame + card together, never following the viewport). Zoom scales it with a CLAMP
+  // (0.9..1.35 of screen-constant), so it reads steady at working zooms yet never dwarfs the
+  // frame far out or shrinks away deep in. Height rules: capped at the frame's height; grows
+  // DOWNWARD from the pin until it reaches the frame's bottom, then grows UP; past the cap the
+  // messages scroll inside. The SIDE is chosen once at open (D3). Play keeps in-stage placement.
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const cardRef = useRef<HTMLDivElement>(null)
+  const float = !!nodeKey
+  const [cardH, setCardH] = useState(320)   // measured layout px (pre-transform)
+  useEffect(() => {
+    if (float && cardRef.current) {
+      const h = cardRef.current.offsetHeight
+      setCardH((c) => (Math.abs(c - h) > 2 ? h : c))
+    }
+  })
+  // scroll shadows: "there is more" above/below - recomputed on scroll + content growth
+  const [shadows, setShadows] = useState({ top: false, bot: false, can: false })
+  const syncShadows = () => {
+    const el = scrollRef.current
+    if (!el) return
+    // gate on MEANINGFUL overflow - a thread that overflows by a few px must not smear a
+    // 30px fade over its last line ("looks scrollable" when it isn't, really)
+    const can = el.scrollHeight - el.clientHeight > 12
+    const top = can && el.scrollTop > 4
+    const bot = can && el.scrollTop + el.clientHeight < el.scrollHeight - 4
+    setShadows((s) => (s.top === top && s.bot === bot && s.can === can ? s : { top, bot, can }))
+  }
+  // open at the LATEST message (what you came to read); follow new replies while open
+  useEffect(() => {
+    const el = scrollRef.current
+    if (el) el.scrollTop = el.scrollHeight
+    syncShadows()
+  }, [thread.replies.length])
+  // ...and when the scroller RESIZES without a scroll event (zoom changing the height cap, the
+  // composer growing) - a stale fade would otherwise claim "more below" at the bottom of a
+  // thread that no longer overflows
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const ro = new ResizeObserver(syncShadows)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [])
+  // ...and after EVERY render: an edited message changes scrollHeight without resizing the
+  // height-capped box or the reply count (Codex P3). setShadows dedups, so this is free.
+  useEffect(syncShadows)
+  // PLAY: one static centered device, no zoom - the card docks FIXED beside it on the pin's side
+  // (falling back to the roomier side), fully viewport-clamped so the composer is ALWAYS reachable
+  // whatever the device layout or theme (SPEC §14). Recomputed when the stage moves under it:
+  // a device/theme switch resizes .sh-play-stage and a window resize shifts it (Codex P2).
+  const computeStagePos = (): React.CSSProperties | null => {
+    if (!stage) return null
+    const W = 320, M = 12, maxH = Math.min(660, window.innerHeight - 2 * M)
+    const rect = document.querySelector('.sh-play-stage')?.getBoundingClientRect()
+    if (!rect) return { position: 'fixed', left: M, top: 72, maxHeight: maxH }
+    const roomR = window.innerWidth - rect.right >= W + 30
+    const roomL = rect.left >= W + 30
+    const s: 'l' | 'r' = at.x < bounds.w / 2 ? (roomL ? 'l' : 'r') : (roomR ? 'r' : 'l')
+    const x = Math.min(Math.max(s === 'r' ? rect.right + 18 : rect.left - 18 - W, M), window.innerWidth - W - M)
+    // worst-case clamp (content = maxH): even a full-height thread keeps its composer on screen
+    const y = Math.min(Math.max(rect.top + at.y - 36, M), Math.max(M, window.innerHeight - maxH - M))
+    return { position: 'fixed', left: x, top: y, maxHeight: maxH }
+  }
+  const [stagePos, setStagePos] = useState<React.CSSProperties | null>(computeStagePos)
+  useEffect(() => {
+    if (!stage) return
+    const re = () => setStagePos(computeStagePos())
+    re()                                       // bounds changed (device/theme switch) -> re-dock
+    window.addEventListener('resize', re)
+    const el = document.querySelector('.sh-play-stage')
+    const ro = el ? new ResizeObserver(re) : null
+    if (el && ro) ro.observe(el)
+    return () => { window.removeEventListener('resize', re); ro?.disconnect() }
+  }, [stage, bounds.w, bounds.h])
+  const flip = !float && !stage && at.x > bounds.w * 0.55
+  // Nic's revision: the card scales EXACTLY like the pins - screen-constant via --sh-inv, pure
+  // CSS, smooth per zoom tick with zero re-renders. Geometry in CSS math over the live vars:
+  //   top: grows DOWN from the pin, then UP once its bottom reaches the frame's bottom; floor
+  //        at -28 (the layer starts below the header - -28 = the frame's TOP border).
+  //   maxHeight: the visual height never exceeds the WHOLE frame (body + 28px header).
+  // Gutters live in CSS (dock margins, screen-constant; wider on the left for the shimmer).
+  const pos: React.CSSProperties = stage && stagePos
+    ? stagePos
+    : float
+      ? {
+          left: side === 'r' ? bounds.w : 0,
+          top: `max(-28px, min(${Math.round(at.y)}px - 36px * var(--sh-inv, 1), ${bounds.h}px - ${cardH}px * var(--sh-inv, 1)))`,
+          // capped at the whole frame's on-screen height, with a REAL readability floor: zoomed way
+          // out the card still shows a meaningful slice of conversation (~3 messages), even if that
+          // makes it taller than the tiny frame
+          maxHeight: `max(320px, calc(${bounds.h + 28}px * var(--sh-s, 1)))`,
+        }
+      : { left: at.x, top: Math.min(at.y + 14, bounds.h - 40) }
   // 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 data-sh-wheel-local className={`cm-card sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, bounds.h - 40), ...hueVars(anchorHue(thread.anchor)) }}
+  const card = (
+    <div ref={cardRef} data-sh-wheel-local className={`cm-card sh-no-pan${flip ? ' flip' : ''}${float ? ` parked dock-${side}` : ''}${float && flank ? ` flank-${flank}` : ''}${stage ? ' stage-dock' : ''}`} style={{ ...pos, ...hueVars(anchorHue(thread.anchor)) }}
       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 */}
@@ -226,33 +593,23 @@ export function ThreadCard({ thread, at, bounds }: { thread: Thread; at: { x: nu
           <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>
-      ))}
+      {/* "there is more": the scroller MASKS its own content at the overflowing edge - a soft fade
+          of the text itself, not a paint layer over the glass */}
+      <div className={`cm-scroll${shadows.top ? ' fade-top' : ''}${shadows.bot ? ' fade-bot' : ''}`} ref={scrollRef} onScroll={syncShadows}>
+        <MessageHead author={thread.author} agent={thread.agent} agentMeta={thread.agentMeta} ts={thread.ts} />
+        <CommentBody body={thread.body} owner={isOwner(thread.author)} />
+        {/* 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">
+            <MessageHead author={r.author} agent={r.agent} agentMeta={r.agentMeta} ts={r.ts} />
+            <CommentBody body={r.body} owner={isOwner(r.author)} />
+          </div>
+        ))}
+      </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>
+          <ComposeAvatar />
+          <CommentInput value={text} onChange={setText} onSubmit={submit} onCancel={() => setActive(null)} placeholder="Reply…" sendLabel="Send" owner={local} />
         </div>
       ) : (
         <button className="cm-signin-cta" onClick={() => useComments.setState({ needsIdentity: true })}>
@@ -261,31 +618,22 @@ export function ThreadCard({ thread, at, bounds }: { thread: Thread; at: { x: nu
       )}
     </div>
   )
+  return card
 }
 
 /** The draft composer - shared by canvas and prototype, geometry via `bounds`, tinted with
  *  the picked element's hue. */
 export function DraftComposer({ at, bounds, hue }: { at: { x: number; y: number }; bounds: { w: number; h: number }; hue?: number }) {
   const { create, setDraft } = useComments.getState()
+  const local = useComments((s) => s.local)
   const [text, setText] = useState('')
-  const ref = useRef<HTMLInputElement>(null)
-  useEffect(() => { ref.current?.focus() }, [])
   const flip = at.x > bounds.w * 0.55
   return (
     <div data-sh-wheel-local className={`cm-card cm-draft sh-no-pan${flip ? ' flip' : ''}`} style={{ left: at.x, top: Math.min(at.y + 14, bounds.h - 40), ...hueVars(hue) }}
       onPointerDown={(e) => e.stopPropagation()} onClick={(e) => e.stopPropagation()}>
+      {/* the draft is JUST the tight pill - no avatar chrome on a first comment */}
       <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>
+        <CommentInput value={text} onChange={setText} onSubmit={() => create(text)} onCancel={() => setDraft(null)} placeholder="Comment on this element…" autoFocus sendLabel="Comment" owner={local} />
       </div>
     </div>
   )
@@ -310,10 +658,11 @@ function AvatarPick({ value, onPick }: { value: string; onPick: (dataUri: string
   }
   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 side="top" label={<b>{value ? 'Change your photo' : 'Select or upload a profile picture'}</b>}>
+        <button className={`cm-pfp${value ? ' set' : ''}`} aria-label="Select or upload a profile picture"
+          onClick={() => fileRef.current?.click()}>
+          {value ? <img src={value} alt="" /> : <PlusIcon size={16} />}
+        </button>
       </Tip>
       <input ref={fileRef} type="file" accept="image/*" hidden onChange={(e) => pick(e.target.files?.[0])} />
     </>
@@ -421,7 +770,7 @@ export function IdentityDialog() {
 }
 
 /** Open a thread by id: activate, select its node, fit the camera. True on success. */
-function revealThread(c: string): boolean {
+export function revealThread(c: string): boolean {
   const t = useComments.getState().threads.find((t) => t.id === c)
   if (!t) return false
   useComments.getState().setActive(c)
@@ -437,6 +786,7 @@ function revealThread(c: string): boolean {
 let bootThreadConsumed = false
 let pendingThread: string | null = null   // cross-board deep link awaiting its board's comments
 export function CommentsController() {
+  const ctlShowAnchor = useComments((s) => s.showAnchor)
   const board = useStore((s) => s.board)
   const commentMode = useComments((s) => s.commentMode)
   const active = useComments((s) => s.active)
@@ -502,8 +852,8 @@ export function CommentsController() {
   // .sh-live so the SPEC-M5 lean cover (.sh-lean, a scriptless snapshot) is never messaged.
   useEffect(() => {
     for (const f of document.querySelectorAll('iframe.sh-live'))
-      (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode }, location.origin)
-  }, [commentMode])
+      (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode, quiet: !ctlShowAnchor }, location.origin)
+  }, [commentMode, ctlShowAnchor])
 
   return <IdentityDialog />
 }