@marver-design/marver 0.3.1 → 0.4.0

package/src/client/shell/comments-store.ts

@@ -0,0 +1,180 @@
+/**
+ * Comment state for the shell (SPEC-M3 §6) - its own small store beside the canvas
+ * store. One API client for both worlds: `marver dev` (api.ts mirror, local profile,
+ * poll) and the published serve (collab.ts, sessions, SSE). The shell never branches
+ * on which one it is beyond capability flags the endpoints themselves report.
+ */
+import { create } from 'zustand'
+import { replay, type CommentEvent, type Thread } from '../../shared/events.ts'
+import { ROUTE } from '../const.ts'
+
+export interface Me { email: string; name: string; avatar?: string }
+
+interface CommentsState {
+  events: CommentEvent[]              // the active board's log
+  threads: Thread[]                   // derived on every change
+  board: string | null
+  me: Me | null                       // null on published until signed in
+  local: boolean                      // dev mirror (identity is the local profile)
+  commentMode: boolean                // C - picking + composing
+  show: boolean                       // Shift+C - pins visible at all
+  active: string | null               // open thread id
+  draft: { nodeKey: string; frame: string; anchor: unknown } | null   // picked, composing
+  needsIdentity: boolean              // published viewer tried to comment while signed out
+  inviteToken: string | null          // arrived via an invite link - claim flow, token known
+
+  load(board: string): Promise<void>
+  live(board: string): () => void
+  send(events: CommentEvent[]): Promise<boolean>
+  create(body: string): Promise<void>
+  reply(threadId: string, body: string): Promise<void>
+  replyOk(threadId: string, body: string): Promise<boolean>
+  resolve(threadId: string, reopen?: boolean): Promise<void>
+  setMode(on: boolean): void
+  setShow(show: boolean): void
+  setActive(id: string | null): void
+  setDraft(d: CommentsState['draft']): void
+  signIn(email: string, password: string): Promise<string | null>
+  claim(token: string, password: string, name: string, avatar?: string): Promise<string | null>
+  saveProfile(patch: Partial<Me>): Promise<void>
+  dismissIdentity(): void
+}
+
+const uuid = () => crypto.randomUUID()
+const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
+const api = async (path: string, body?: unknown) => {
+  const res = await fetch(`${ROUTE}/api/${path}`, body === undefined ? undefined : {
+    method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
+    body: JSON.stringify(body),
+  })
+  return { ok: res.ok, status: res.status, data: await res.json().catch(() => ({})) }
+}
+
+export const useComments = create<CommentsState>((set, get) => {
+  const derive = (events: CommentEvent[]) => ({ events, threads: replay(events) })
+  const union = (events: CommentEvent[]) => {
+    const have = new Set(get().events.map((e) => e.id))
+    const fresh = events.filter((e) => !have.has(e.id))
+    if (fresh.length) set(derive([...get().events, ...fresh]))
+  }
+
+  return {
+    events: [], threads: [], board: null, me: null, local: false,
+    commentMode: false, show: true, active: null, draft: null, needsIdentity: false, inviteToken: null,
+
+    async load(board) {
+      set({ board })
+      const me = await api('me')
+      if (me.ok) set({ me: me.data.user ?? null, local: !!me.data.local })
+      const res = await api(`comments/${board}`)
+      if (res.ok && get().board === board) set(derive(res.data.events ?? []))
+    },
+
+    /** Liveness: SSE on the published serve; dev has no event rail (its sync loop
+     *  writes files) so it polls only - an EventSource there would 404-retry forever. */
+    live(board) {
+      const stops: (() => void)[] = []
+      let es: EventSource | null = null
+      const wantSSE = () => {
+        if (es || get().local) return
+        es = new EventSource(`${ROUTE}/api/events`)
+        es.addEventListener('comment', (e) => {
+          try {
+            const { board: b, ev } = JSON.parse((e as MessageEvent).data)
+            if (b === get().board) union([ev])
+          } catch { /* ignore */ }
+        })
+        es.addEventListener('resync', () => { void get().load(board) })
+        es.onerror = () => { /* EventSource retries itself; the poll covers the gap */ }
+      }
+      // `local` is only known once load() has answered - defer the SSE decision past it
+      const t = setTimeout(wantSSE, 1500)
+      stops.push(() => { clearTimeout(t); es?.close() })
+      const poll = () => { if (get().board === board) void api(`comments/${board}`).then((r) => r.ok && union(r.data.events ?? [])) }
+      const iv = setInterval(poll, 30_000)
+      const onFocus = () => poll()
+      window.addEventListener('focus', onFocus)
+      stops.push(() => { clearInterval(iv); window.removeEventListener('focus', onFocus) })
+      return () => stops.forEach((f) => f())
+    },
+
+    async send(events) {
+      const { board } = get()
+      if (!board) return false
+      const res = await api(`comments/${board}`, { events })
+      if (res.status === 401) { set({ needsIdentity: true }); return false }
+      // any other refusal gets said out loud - a silent dead Enter key reads as a bug
+      // (the canonical case: a signed-in viewer on a read-only board)
+      if (!res.ok) {
+        const { useStore } = await import('./store.ts')
+        useStore.getState().toast(String((res.data as any)?.error ?? 'comment rejected'))
+      }
+      // union only what the server took - a rejected send must not leave phantoms -
+      // and only if the user is still LOOKING at that board (a slow response after a
+      // board switch must not leak events into the wrong client state); client ids
+      // keep the eventual SSE/poll echo idempotent either way
+      if (res.ok && get().board === board) union(events)
+      return res.ok
+    },
+
+    async create(body) {
+      const { draft, me } = get()
+      if (!draft || !body.trim()) return
+      const id = uuid()
+      const ok = await get().send([{
+        id: uuid(), ts: Date.now(), type: 'create', commentId: id,
+        nodeKey: draft.nodeKey, frame: draft.frame, anchor: draft.anchor,
+        author: me ?? undefined, body: body.trim(),
+      }])
+      if (ok) set({ draft: null, active: id, commentMode: false })
+    },
+
+    async reply(threadId, body) { await get().replyOk(threadId, body) },
+    async replyOk(threadId, body) {
+      if (!body.trim()) return false
+      return get().send([{
+        id: uuid(), ts: Date.now(), type: 'reply', commentId: uuid(), parentId: threadId,
+        author: get().me ?? undefined, body: body.trim(),
+      }])
+    },
+
+    async resolve(threadId, reopen = false) {
+      await get().send([{ id: uuid(), ts: Date.now(), type: reopen ? 'reopen' : 'resolve', commentId: threadId }])
+    },
+
+    setMode(on) { set({ commentMode: on, ...(on ? { show: true } : { draft: null }) }) },
+    setShow(show) { set({ show }) },
+    setActive(active) { set({ active }) },
+    setDraft(draft) { set({ draft }) },
+    dismissIdentity() { set({ needsIdentity: false }) },   // inviteToken survives dismissal - commenting later reopens the claim
+
+    async signIn(email, password) {
+      const res = await api('auth/signin', { email, password })
+      if (!res.ok) return res.data?.error ?? 'sign-in failed'
+      set({ me: res.data.user, needsIdentity: false })
+      return null
+    },
+    async claim(token, password, name, avatar) {
+      const res = await api('auth/claim', { token, password, name, avatar })
+      if (!res.ok) return res.data?.error ?? 'claim failed'
+      set({ me: res.data.user, needsIdentity: false, inviteToken: null })
+      return null
+    },
+    async saveProfile(patch) {
+      const res = await api('profile', patch)
+      if (res.ok) set({ me: res.data.user })
+    },
+  }
+})
+
+// dev-only debug handle - the canvas store exposes the same
+if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) (window as any).__mvComments = useComments
+
+/** Initials + deterministic hue for avatarless authors - the whole fallback ladder. */
+export const avatarFallback = (author?: { email?: string; name?: string }) => {
+  const name = author?.name || author?.email || '?'
+  const initials = name.split(/\s+/).map((w) => w[0]).slice(0, 2).join('').toUpperCase()
+  let h = 0
+  for (const c of (author?.email || name)) h = (h * 31 + c.charCodeAt(0)) % 360
+  return { initials, hue: h }
+}

package/src/client/shell/hash.ts

@@ -7,12 +7,16 @@
  *   #/                     default board, fit all
  *   #/b/<board>            board, fit all
  *   #/b/<board>?n=k1,k2    board with nodes selected, camera fit to selection
+ *   #/b/<board>?c=<id>     board with a comment thread open (SPEC-M3 §6)
+ *   #/i/<token>            invite link - opens the claim dialog with the token
  *   #/p/<board>?at=<frame-id>&device=<viewport>&theme=<theme>   play mode
  */
 
 export interface HashState {
   board?: string
   n?: string[]
+  c?: string
+  invite?: string
   play?: { at?: string; device?: string; theme?: string }
 }
 
@@ -25,13 +29,16 @@ export function parseHash(hash: string = location.hash): HashState {
     const q = raw.indexOf('?')
     const path = q === -1 ? raw : raw.slice(0, q)
     const params = new URLSearchParams(q === -1 ? '' : raw.slice(q + 1))
+    const mi = path.match(/^\/i\/([\w-]{8,128})$/)
+    if (mi) return { invite: mi[1] }
     const m = path.match(/^\/(b|p)\/([^/?]+)$/)
     if (!m) return {}
     const board = decodeURIComponent(m[2])
     if (!BOARD_RE.test(board)) return {}
     if (m[1] === 'b') {
       const n = (params.get('n') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
-      return { board, ...(n.length ? { n } : {}) }
+      const c = params.get('c') ?? undefined
+      return { board, ...(n.length ? { n } : {}), ...(c && /^[\w-]+$/.test(c) ? { c } : {}) }
     }
     return {
       board,
@@ -51,8 +58,12 @@ export function buildHash(s: HashState): string {
     if (s.play.theme) p.set('theme', s.play.theme)
     return `#/p/${s.board}?${p}`
   }
-  if (!s.board || (s.board === 'all-scenes' && !s.n?.length)) return '#/'
-  return `#/b/${s.board}${s.n?.length ? `?n=${s.n.join(',')}` : ''}`
+  if (!s.board || (s.board === 'all-scenes' && !s.n?.length && !s.c)) return '#/'
+  const p = new URLSearchParams()
+  if (s.n?.length) p.set('n', s.n.join(','))
+  if (s.c) p.set('c', s.c)
+  const q = p.toString()
+  return `#/b/${s.board}${q ? `?${decodeURIComponent(q)}` : ''}`
 }
 
 /** Write the hash; identical URLs are skipped so restore paths never loop. */

package/src/client/shell/icons.tsx

@@ -27,6 +27,10 @@ export const PlusIcon = icon(<path d="M224,128a8,8,0,0,1-8,8H136v80a8,8,0,0,1-16
 export const XIcon = icon(<path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z" />)
 export const ReloadIcon = icon(<path d="M240,56v48a8,8,0,0,1-8,8H184a8,8,0,0,1,0-16H211.4L184.81,71.64l-.25-.24a80,80,0,1,0-1.67,114.78,8,8,0,0,1,11,11.63A95.44,95.44,0,0,1,128,224h-1.32A96,96,0,1,1,195.75,60L224,85.8V56a8,8,0,1,1,16,0Z" />)
 export const CheckIcon = icon(<path d="M229.66,77.66l-128,128a8,8,0,0,1-11.32,0l-56-56a8,8,0,0,1,11.32-11.32L96,188.69,218.34,66.34a8,8,0,0,1,11.32,11.32Z" />)
+export const ColumnsIcon = icon(<path d="M104,32H64A16,16,0,0,0,48,48V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,104,32Zm0,176H64V48h40ZM192,32H152a16,16,0,0,0-16,16V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,192,32Zm0,176H152V48h40Z" />)
+export const ArrowUpIcon = icon(<path d="M205.66,117.66a8,8,0,0,1-11.32,0L136,59.31V216a8,8,0,0,1-16,0V59.31L61.66,117.66a8,8,0,0,1-11.32-11.32l72-72a8,8,0,0,1,11.32,0l72,72A8,8,0,0,1,205.66,117.66Z" />)
+export const CommentIcon = icon(<path d="M132,24A100.11,100.11,0,0,0,32,124v84a16,16,0,0,0,16,16h84a100,100,0,0,0,0-200Zm0,184H48V124a84,84,0,1,1,84,84Z" />)
+export const CheckSquareOffsetIcon = icon(<path d="M224,48V208a16,16,0,0,1-16,16H136a8,8,0,0,1,0-16h72V48H48v96a8,8,0,0,1-16,0V48A16,16,0,0,1,48,32H208A16,16,0,0,1,224,48ZM125.66,154.34a8,8,0,0,0-11.32,0L64,204.69,45.66,186.34a8,8,0,0,0-11.32,11.32l24,24a8,8,0,0,0,11.32,0l56-56A8,8,0,0,0,125.66,154.34Z" />)
 export const DevicesIcon = icon(<path d="M224,72H208V64a24,24,0,0,0-24-24H40A24,24,0,0,0,16,64v96a24,24,0,0,0,24,24H152v8a24,24,0,0,0,24,24h48a24,24,0,0,0,24-24V96A24,24,0,0,0,224,72ZM40,168a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H184a8,8,0,0,1,8,8v8H176a24,24,0,0,0-24,24v72Zm192,24a8,8,0,0,1-8,8H176a8,8,0,0,1-8-8V96a8,8,0,0,1,8-8h48a8,8,0,0,1,8,8Zm-96,16a8,8,0,0,1-8,8H88a8,8,0,0,1,0-16h40A8,8,0,0,1,136,208Zm80-96a8,8,0,0,1-8,8H192a8,8,0,0,1,0-16h16A8,8,0,0,1,216,112Z" />)
 export const DeviceMobileIcon = icon(<path d="M176,16H80A24,24,0,0,0,56,40V216a24,24,0,0,0,24,24h96a24,24,0,0,0,24-24V40A24,24,0,0,0,176,16ZM72,64H184V192H72Zm8-32h96a8,8,0,0,1,8,8v8H72V40A8,8,0,0,1,80,32Zm96,192H80a8,8,0,0,1-8-8v-8H184v8A8,8,0,0,1,176,224Z" />)
 export const DeviceTabletIcon = icon(<path d="M192,24H64A24,24,0,0,0,40,48V208a24,24,0,0,0,24,24H192a24,24,0,0,0,24-24V48A24,24,0,0,0,192,24ZM56,72H200V184H56Zm8-32H192a8,8,0,0,1,8,8v8H56V48A8,8,0,0,1,64,40ZM192,216H64a8,8,0,0,1-8-8v-8H200v8A8,8,0,0,1,192,216Z" />)
@@ -41,6 +45,8 @@ export const PanelFilledIcon = icon(<><rect x="32" y="48" width="192" height="16
 
 /** Plain UI frame - the rectangle every non-content sidebar row leads with. */
 export const FrameRectIcon = icon(<rect x="40" y="52" width="176" height="152" rx="20" fill="none" stroke="currentColor" strokeWidth="16" />)
+export const LinkIcon = icon(<path d="M137.54,186.36a8,8,0,0,1,0,11.31l-9.94,10A56,56,0,0,1,48.38,128.4L72.5,104.28A56,56,0,0,1,149.31,102a8,8,0,1,1-10.64,12,40,40,0,0,0-54.85,1.63L59.7,139.72a40,40,0,0,0,56.58,56.58l9.94-9.94A8,8,0,0,1,137.54,186.36Zm70.08-138a56.08,56.08,0,0,0-79.22,0l-9.94,9.95a8,8,0,0,0,11.32,11.31l9.94-9.94a40,40,0,0,1,56.58,56.58L172.18,140.4a40,40,0,0,1-54.85,1.6,8,8,0,1,0-10.64,12,56,56,0,0,0,76.81-2.26l24.12-24.12A56.08,56.08,0,0,0,207.62,48.38Z" />)
+export const LaserIcon = icon(<><circle cx="128" cy="128" r="56" fill="none" stroke="currentColor" strokeWidth="16" /><path d="M128 24 V56 M128 200 V232 M24 128 H56 M200 128 H232" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" /><circle cx="128" cy="128" r="12" /></>)
 
 /* Content-frame intent glyphs (SPEC-026), custom in the same 256-space. */
 export const DiagramShapeIcon = icon(<><rect x="28" y="36" width="88" height="64" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="140" y="156" width="88" height="64" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><path d="M116 68 H184 V156" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" strokeLinejoin="round" /></>)

package/src/client/shell/store.ts

@@ -112,6 +112,7 @@ interface State {
   viewTheme: string                   // the global theme preference; sticky across boards and reloads
   play: { at: string; device: string; theme: string } | null   // play mode (SPEC-M2 §1); at = current frame id
   gesture: boolean                    // a frame drag/resize is in progress - canvas panning is disabled
+  laser: boolean                      // laser/inspect mode (SPEC-M3 §7): frames outline their structure
   board: string                       // active board name; 'all-scenes' is the auto board
   boardAuto: boolean                  // auto boards gain new frames on arrival; curated boards never do
   deviceView: string | null           // board-wide device preview (viewport name), null = free-form layout
@@ -139,6 +140,7 @@ interface State {
   setInteract(key: string | null): void
   setPlay(p: State['play']): void
   setGesture(g: boolean): void
+  setLaser(on: boolean): void
   moveSelectedBy(dx: number, dy: number, starts: Record<string, { x: number; y: number }>): void
   setSelectedTheme(theme: string): void
   setDeviceView(name: string | null): void
@@ -388,7 +390,7 @@ export const useStore = create<State>((set, get) => {
   }
 
   return {
-    manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false,
+    manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false, laser: false,
     board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null,
     panelOpen: true, scale: 1, toasts: [], boardHash: null, dirty: false,
 
@@ -687,6 +689,7 @@ export const useStore = create<State>((set, get) => {
     // painted as "interactive"). Exiting keeps the frame selected for continuity.
     setInteract(key) { set((s) => ({ interact: key, selection: key ? [key] : s.selection })) },
     setPlay(play) { set({ play }) },
+    setLaser(laser) { set({ laser }) },
     setGesture(gesture) {
       set({ gesture })
       // SPEC-024 §4: a board WITH a layout recipe re-applies it when a resize

package/src/client/shell/styles.css

@@ -28,6 +28,13 @@
   --interact: #db35f2; --interact-ring: rgba(219, 53, 242, .16);
   --interact-strong: rgba(219, 53, 242, 1); --interact-soft: rgba(234, 141, 255, .95);
   --interact-deep: rgba(176, 47, 194, .85); --interact-spark: rgba(255, 255, 255, .95);
+  /* comments own a third mode color (Apple systemGreen): selection = blue,
+     interact = purple, comments = green - same geometry, unique hue per mode */
+  --comment: #34c759; --comment-ring: rgba(52, 199, 89, .22);
+  /* comment-card field surface: APP-scoped on purpose - the card keys to the board
+     theme, and node-scoped --node-bg would flip with the frame underneath it */
+  --cm-field: #fff;
+  --cm-modal-bg: rgba(255, 255, 255, .95);
 
   --r-node: 10px; --r-panel: 24px; --edge: 10px;
   --blur: blur(20px) saturate(150%);
@@ -60,6 +67,9 @@
   --interact: #ea8dff; --interact-ring: rgba(219, 53, 242, .3);
   --interact-strong: rgba(219, 53, 242, 1); --interact-soft: rgba(234, 141, 255, .95);
   --interact-deep: rgba(203, 48, 224, .8); --interact-spark: rgba(255, 255, 255, .9);
+  --comment: #30d158; --comment-ring: rgba(48, 209, 88, .34);
+  --cm-field: #0f1015;
+  --cm-modal-bg: rgba(22, 22, 27, .96);
 
   --shadow-node: 0 1px 2px rgba(0, 0, 0, .35);   /* shadow-sm, alpha raised to read on dark */
 }
@@ -373,6 +383,8 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-pill-btn.pct { font-variant-numeric: tabular-nums; min-width: 46px }
 .sh-pill-btn.off { color: var(--glass-ink-3); cursor: default }
 .sh-pill-btn.off:hover { background: none; color: var(--glass-ink-3) }
+.sh-pill-btn.on { color: var(--accent); background: color-mix(in srgb, var(--accent) 12%, transparent) }
+.sh-pill-btn.on:hover { color: var(--accent); background: color-mix(in srgb, var(--accent) 18%, transparent) }
 .sh-pill .sep { width: 1px; height: 16px; background: var(--glass-brd); margin: 0 3px }
 
 /* dropdown menu (theme) - portaled to .sh-app (its own backdrop root), left-aligned to its trigger */
@@ -633,3 +645,150 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
 .sub.vgroup { cursor: pointer }
 .sub.vgroup.held { background: color-mix(in srgb, var(--glass-hover) 55%, transparent) }
 .sub.vgroup.held .gicon { color: var(--glass-ink-2) }
+
+/* ---- comments (SPEC-M3 §6) ----------------------------------------------------------
+   The marker family (pins, stacks) is SOLID with the Figma teardrop silhouette - a
+   marker must hold contrast on any artwork. The surfaces (card, composer, dialog)
+   are OUR glass - the shell's own token language, theme-aware where Figma is flat. */
+.cm-avatar { display: inline-flex; align-items: center; justify-content: center; border-radius: 50%;
+  color: #fff; font-weight: 700; font-family: -apple-system, system-ui, sans-serif;
+  object-fit: cover; flex: none; user-select: none }
+
+/* markers - pins and stacks share one face: overlapping avatars + a total count.
+   A pin shows one thread's participants (tail points at its div); a stack shows
+   everyone across the frame's threads (tail points up-right at the frame corner). */
+.cm-pin, .cm-stack { display: inline-flex; align-items: center; padding: 4px;
+  background: #fff; border: 1px solid rgba(24,24,27,.1); cursor: pointer;
+  font: 700 11px -apple-system, system-ui, sans-serif; color: #18181b }
+.cm-pin .cm-avatar, .cm-stack .cm-avatar { border: 2px solid #fff }
+.cm-pin .cm-avatar + .cm-avatar, .cm-stack .cm-avatar + .cm-avatar { margin-left: -8px }
+.cm-pin b, .cm-stack b { padding: 0 8px 0 6px }
+
+/* pin: the teardrop. Bottom-left tail points at the anchored element. */
+.cm-pin { position: absolute; z-index: 30; transform: translate(-2px, -100%) scale(var(--sh-inv, 1));
+  transform-origin: bottom left; border-radius: 18px 18px 18px 4px;
+  box-shadow: 0 1px 2px rgba(24,24,27,.18), 0 6px 16px -6px rgba(24,24,27,.35);
+  transition: box-shadow .15s, transform .15s }
+.cm-pin:hover { box-shadow: 0 1px 3px rgba(24,24,27,.22), 0 10px 24px -6px rgba(24,24,27,.45) }
+/* selected pin wears the selected frame's exact geometry - border, 2px
+   outline hugging the edge, 4px ring halo - in the comment green (the pin
+   is already screen-space via scale(--sh-inv), so plain px match the
+   frame's calc'd screen px) */
+.cm-pin.on { border-color: var(--comment);
+  outline: 2px solid var(--comment); outline-offset: -1px;
+  box-shadow: 0 0 0 4px var(--comment-ring), 0 1px 2px rgba(24,24,27,.18), 0 6px 16px -6px rgba(24,24,27,.35) }
+.cm-pin.orphan { border-style: dashed; opacity: .75 }
+
+/* stack: the frame-corner cluster - everyone across the frame's threads */
+.cm-stack { position: absolute; top: 10px; right: 10px; z-index: 30;
+  transform: scale(var(--sh-inv, 1)); transform-origin: top right; border-radius: 18px 18px 4px 18px;
+  box-shadow: 0 1px 2px rgba(24,24,27,.15), 0 6px 16px -6px rgba(24,24,27,.3);
+  transition: box-shadow .15s }
+.cm-stack:hover { box-shadow: 0 1px 3px rgba(24,24,27,.2), 0 10px 24px -6px rgba(24,24,27,.4) }
+
+/* card: OUR glass - the floating-menu language, theme-aware */
+.cm-card { position: absolute; z-index: 40; width: 300px; padding: 16px;
+  transform: scale(var(--sh-inv, 1)); transform-origin: top left;
+  background: var(--glass); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+  /* an open card is the active selection - the frame's exact geometry, comment green */
+  color: var(--glass-ink); border-radius: 20px; border: 1px solid var(--comment);
+  outline: 2px solid var(--comment); outline-offset: -1px;
+  box-shadow: 0 0 0 4px var(--comment-ring), var(--shadow-glass), 0 16px 40px -12px rgba(24,24,27,.35);
+  display: flex; flex-direction: column; gap: 12px;
+  font: 400 13px -apple-system, system-ui, sans-serif; letter-spacing: -.005em; text-align: left }
+.cm-card.flip { transform: translateX(-100%) scale(var(--sh-inv, 1)); transform-origin: top right }
+.cm-card header { display: flex; align-items: center; gap: 9px }
+.cm-card header b { font-size: 14px; font-weight: 600; letter-spacing: -.01em }
+.cm-card .dim { color: var(--glass-ink-3); font-size: 11.5px; font-variant-numeric: tabular-nums }
+.cm-actions { position: absolute; top: 13px; right: 12px; display: flex; gap: 2px }
+/* the root header shares its line with the pinned actions - reserve their width
+   so a long display name ellipsizes instead of running under the icons */
+.cm-card > header { padding-right: 84px }
+.cm-card > header b { overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
+/* every message - root and replies - is the same unit: avatar + name + time,
+   body indented to the name column (24px avatar + 9px gap) */
+.cm-card .cm-body { margin: 0; padding-left: 33px; font-size: 13px; line-height: 1.55;
+  color: var(--glass-ink); white-space: pre-wrap; overflow-wrap: break-word }
+.cm-card > .cm-body { margin-top: -10px }  /* pulls against the card's 12px gap -> 2px under the header */
+.cm-msg { display: flex; flex-direction: column; gap: 2px }
+.cm-icon { display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 26px;
+  border: 0; border-radius: 8px; background: none; color: var(--glass-ink-3); cursor: pointer;
+  transition: background .12s, color .12s }
+.cm-icon:hover { background: var(--glass-hover); color: var(--glass-ink) }
+/* copy-link morphs into a check on the shell's morph curve, then reverts */
+.cm-copy { position: relative }
+.cm-copy .a, .cm-copy .b { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+  transition: transform var(--morph), opacity .2s ease }
+.cm-copy .b { transform: scale(.4); opacity: 0; color: var(--comment) }
+.cm-copy.ok .a { transform: scale(.4); opacity: 0 }
+.cm-copy.ok .b { transform: scale(1); opacity: 1 }
+/* composer row: my avatar (list size) + a pill input with a round send button inside */
+.cm-compose { display: flex; align-items: center; gap: 8px }
+.cm-inputwrap { position: relative; flex: 1; min-width: 0 }
+.cm-compose input { width: 100%; height: 36px; padding: 0 42px 0 15px; border-radius: 999px;
+  border: 1px solid var(--glass-brd); background: var(--cm-field); color: var(--glass-ink);
+  font: 400 13px -apple-system, system-ui, sans-serif; outline: none;
+  transition: border-color .15s, box-shadow .15s }
+.cm-compose input::placeholder { color: var(--glass-ink-3) }
+.cm-compose input:focus { border-color: var(--comment); box-shadow: 0 0 0 3px var(--comment-ring) }
+.cm-send { position: absolute; right: 4px; top: 50%; transform: translateY(-50%);
+  width: 28px; height: 28px; border-radius: 50%; border: 0; display: flex; align-items: center; justify-content: center;
+  background: var(--comment); color: #fff; cursor: pointer; transition: background .15s, opacity .15s }
+.cm-send:hover:not(:disabled) { filter: brightness(1.08) }
+.cm-send:disabled { background: var(--glass-ink-3); opacity: .5; cursor: default }
+/* signed-out viewer: one clear button in place of the composer */
+.cm-signin-cta { width: 100%; height: 40px; border: 0; border-radius: 999px;
+  background: var(--comment); color: #fff; cursor: pointer;
+  font: 600 13px -apple-system, system-ui, sans-serif; transition: filter .15s }
+.cm-signin-cta:hover { filter: brightness(1.06) }
+/* the draft composer is JUST the pill - no card chrome around a single input */
+.cm-draft { padding: 0; width: 272px; background: none; border: none; box-shadow: none; outline: none;
+  backdrop-filter: none; -webkit-backdrop-filter: none }
+.cm-draft input { height: 40px; box-shadow: 0 2px 6px rgba(24,24,27,.15), 0 12px 32px -8px rgba(24,24,27,.35) }
+.cm-draft .cm-send { right: 6px }   /* nudge in for the taller draft pill */
+/* identity modal - same glass family */
+.cm-modal-wrap { position: fixed; inset: 0; z-index: 300; display: flex; align-items: center; justify-content: center;
+  background: rgba(24,24,27,.45); backdrop-filter: blur(5px) }
+/* the auth modal is a focused surface, not a floating glass panel - near-solid so
+   the canvas behind never bleeds through the fields */
+.cm-modal { width: 344px; padding: 26px; border-radius: 24px;
+  background: var(--cm-modal-bg); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
+  color: var(--glass-ink); border: 1px solid var(--glass-brd);
+  display: flex; flex-direction: column; gap: 8px; font: 400 13px -apple-system, system-ui, sans-serif;
+  box-shadow: 0 1px 2px rgba(24,24,27,.1), 0 20px 60px -12px rgba(24,24,27,.5) }
+.cm-modal h2 { margin: 0; font-size: 16px; letter-spacing: -.01em }
+.cm-modal .dim { margin: 0 0 8px; color: var(--glass-ink-2); font-size: 12.5px; line-height: 1.5 }
+.cm-fields { display: flex; flex-direction: column; gap: 9px }
+.cm-modal input { height: 38px; padding: 0 14px; border-radius: 999px; border: 1px solid var(--glass-brd);
+  background: var(--cm-field); color: var(--glass-ink); font: inherit; outline: none }
+.cm-modal input:focus { border-color: var(--comment); box-shadow: 0 0 0 3px var(--comment-ring) }
+.cm-err { color: #b42318; font-size: 12px }
+.cm-chip { height: 38px; box-sizing: border-box; padding: 0 14px; border-radius: 999px;
+  border: 1px solid transparent; background: var(--glass-hover);
+  display: flex; align-items: center; justify-content: space-between; gap: 10px; overflow: hidden }
+.cm-div { border: 0; height: 1px; background: var(--glass-brd); margin: 1px 2px; align-self: stretch }
+.cm-chip b { font-weight: 500; font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
+.cm-chip span { font-size: 10.5px; font-weight: 600; letter-spacing: .04em; color: var(--glass-ink-3); flex: none }
+.cm-idrow { display: flex; align-items: center; gap: 10px }
+.cm-pfp { width: 44px; height: 44px; border-radius: 50%; border: 1.5px dashed var(--glass-ink-3);
+  background: var(--cm-field) center/cover no-repeat; color: var(--glass-ink-3); font-size: 18px; flex: none;
+  display: flex; align-items: center; justify-content: center; cursor: pointer; padding: 0;
+  transition: border-color .15s, color .15s }
+.cm-pfp:hover { border-color: var(--comment); color: var(--comment) }
+.cm-pfp.set { border-style: solid; border-color: var(--glass-brd); color: transparent }
+.cm-row { display: flex; gap: 8px; margin-top: 12px }
+.cm-row button:disabled, .cm-row button.cm-primary:disabled {
+  background: var(--glass-ink-3); color: var(--glass); cursor: default; opacity: 1 }
+.cm-switch { margin: 2px auto 0; border: 0; background: none; padding: 4px 8px; cursor: pointer;
+  font: 500 12px -apple-system, system-ui, sans-serif; color: var(--glass-ink-3); border-radius: 999px }
+.cm-switch:hover { color: var(--glass-ink); background: var(--glass-hover) }
+.cm-row button { height: 36px; padding: 0 16px; border-radius: 999px; border: 1px solid var(--glass-brd);
+  background: none; color: var(--glass-ink); font: 600 12.5px -apple-system, system-ui, sans-serif; cursor: pointer }
+.cm-row button:hover { background: var(--glass-hover) }
+.cm-row button.cm-primary { background: var(--glass-ink); color: var(--glass); border-color: transparent; flex: 1 }
+.cm-row button.cm-primary:hover { opacity: .88 }
+
+/* the unclipped comment plane over each frame: itself transparent to the pointer,
+   its children (pins, cards, stacks) fully interactive */
+.cm-layer { position: absolute; left: 0; width: 100%; pointer-events: none; z-index: 25 }
+.cm-layer > * { pointer-events: auto }

package/src/shared/events.ts

@@ -0,0 +1,103 @@
+/**
+ * Comment events - the PURE half of the store (SPEC-M3 §1), shared by the node side
+ * (JSONL persistence in server/comments.ts) and the browser shell (thread state from
+ * fetched events). No node imports here, ever.
+ */
+
+export type EventType = 'create' | 'reply' | 'edit' | 'resolve' | 'reopen' | 'react' | 'profile'
+
+export interface CommentEvent {
+  id: string                      // client-generated UUID - the idempotency key
+  ts: number                      // ms epoch at creation
+  type: EventType
+  commentId?: string              // the comment this event belongs to (root id = thread id)
+  parentId?: string               // replies: the ROOT comment id (threads are flat)
+  board?: string
+  nodeKey?: string                // a frame can sit on a board twice - comments are node-scoped
+  frame?: string
+  anchor?: unknown                // SPEC-M3 §5 bundle; absent = frame-level comment
+  author?: { email: string; name?: string; avatar?: string }
+  body?: string                   // plain text in v1
+  emoji?: string                  // react events
+  addressedIn?: string            // resolve events: the variant frame that answered
+}
+
+export interface Thread {
+  id: string
+  board?: string; nodeKey?: string; frame?: string
+  anchor?: unknown
+  author?: CommentEvent['author']
+  body?: string
+  ts: number
+  resolved: boolean
+  addressedIn?: string
+  replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number }[]
+  reactions: Record<string, string[]>   // emoji -> author emails (toggle semantics)
+}
+
+/** Events the other side lacks, by id - the sync payload in either direction. */
+export function diffEvents(mine: CommentEvent[], theirIds: Iterable<string>): CommentEvent[] {
+  const have = new Set(theirIds)
+  return mine.filter((e) => !have.has(e.id))
+}
+
+/** Replay a board's events into current thread state. Deterministic: replay order is
+ *  (ts, id) so two stores holding the same event SET always derive the same state.
+ *  TWO passes - creates first, then everything else - so a reply whose author's clock
+ *  ran ahead of the creator's still lands instead of being dropped forever. */
+export function replay(events: CommentEvent[]): Thread[] {
+  const ordered = [...events].sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : 1))
+  const threads = new Map<string, Thread>()
+  for (const ev of ordered) {
+    if (ev.type !== 'create') continue
+    if (!ev.commentId || threads.has(ev.commentId)) continue
+    threads.set(ev.commentId, {
+      id: ev.commentId, board: ev.board, nodeKey: ev.nodeKey, frame: ev.frame,
+      anchor: ev.anchor, author: ev.author, body: ev.body, ts: ev.ts,
+      resolved: false, replies: [], reactions: {},
+    })
+  }
+  for (const ev of ordered) {
+    switch (ev.type) {
+      case 'reply': {
+        const t = ev.parentId ? threads.get(ev.parentId) : undefined
+        if (!t || !ev.commentId || t.replies.some((r) => r.id === ev.commentId)) break
+        t.replies.push({ id: ev.commentId, author: ev.author, body: ev.body, ts: ev.ts })
+        break
+      }
+      case 'edit': {
+        if (!ev.commentId || ev.body === undefined) break
+        const t = threads.get(ev.commentId)
+        if (t) { t.body = ev.body; break }
+        for (const th of threads.values()) {
+          const r = th.replies.find((r) => r.id === ev.commentId)
+          if (r) { r.body = ev.body; break }
+        }
+        break
+      }
+      case 'resolve': {
+        const t = ev.commentId ? threads.get(ev.commentId) : undefined
+        if (t) { t.resolved = true; if (ev.addressedIn) t.addressedIn = ev.addressedIn }
+        break
+      }
+      case 'reopen': {
+        const t = ev.commentId ? threads.get(ev.commentId) : undefined
+        if (t) { t.resolved = false; t.addressedIn = undefined }
+        break
+      }
+      case 'react': {
+        // toggle keyed on comment+author+emoji: present removes, absent adds
+        const t = ev.commentId ? threads.get(ev.commentId) : undefined
+        const who = ev.author?.email
+        if (!t || !who || !ev.emoji) break
+        const users = (t.reactions[ev.emoji] ??= [])
+        const at = users.indexOf(who)
+        if (at === -1) users.push(who)
+        else { users.splice(at, 1); if (!users.length) delete t.reactions[ev.emoji] }
+        break
+      }
+      // 'profile' events update author snapshots at write time on the client - replay ignores them
+    }
+  }
+  return [...threads.values()]
+}

package/templates/AGENTS-embedded.md

@@ -21,7 +21,8 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Build | hi-fi frames from real components | instructions/craft.md + components.md |
 | Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
-| Boards | creating a board or publishing | instructions/boards.md |
+| Boards | creating a board, choosing what ships | instructions/boards.md |
+| Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 
 Refining an existing screen: Configure must hold, then Build + Review. New work runs
 the full ladder. Unsure which phase you are in? Ask the human - one question beats a
@@ -37,6 +38,17 @@ Stuck, or the human is unhappy with a result? instructions/reference/ holds the
 guides (layout, typography, color, motion, copy, states, tuning, critique, concepts) -
 the routing index is at the top of instructions/craft.md. Pull ONE file, apply, return.
 
+## When the human points at a specific element
+
+Two channels carry element-precise feedback - honor both:
+- **A pasted address** like `design/scenes/hero/a.tsx · #root > div > h1 (a.tsx:12)` is
+  a LASER-COPIED pointer: the human pressed L (laser mode), hovered to see the element,
+  clicked it, and its exact address landed on their clipboard. Open that frame file and
+  go straight to that element - the css path (and source location, when present) are exact.
+- **A pinned comment** on an element: run `npx marver comments list --open --json` - each
+  thread carries the anchored element (tag, quoted text, css path, frame). Work that queue
+  per instructions/iterate.md; the comment names the div, so read the anchor before the words.
+
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:

package/templates/AGENTS-studio.md

@@ -21,7 +21,8 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Build | hi-fi frames from real components | instructions/craft.md + components.md |
 | Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
-| Boards | creating a board or publishing | instructions/boards.md |
+| Boards | creating a board, choosing what ships | instructions/boards.md |
+| Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 
 Refining an existing screen: Configure must hold, then Build + Review. New work runs
 the full ladder. Unsure which phase you are in? Ask the human - one question beats a
@@ -37,6 +38,17 @@ Stuck, or the human is unhappy with a result? instructions/reference/ holds the
 guides (layout, typography, color, motion, copy, states, tuning, critique, concepts) -
 the routing index is at the top of instructions/craft.md. Pull ONE file, apply, return.
 
+## When the human points at a specific element
+
+Two channels carry element-precise feedback - honor both:
+- **A pasted address** like `design/scenes/hero/a.tsx · #root > div > h1 (a.tsx:12)` is
+  a LASER-COPIED pointer: the human pressed L (laser mode), hovered to see the element,
+  clicked it, and its exact address landed on their clipboard. Open that frame file and
+  go straight to that element - the css path (and source location, when present) are exact.
+- **A pinned comment** on an element: run `npx marver comments list --open --json` - each
+  thread carries the anchored element (tag, quoted text, css path, frame). Work that queue
+  per instructions/iterate.md; the comment names the div, so read the anchor before the words.
+
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:

package/templates/instructions/boards.md

@@ -78,9 +78,12 @@ ordered list of atoms and `{ "space": n }` tokens.
 
 ## Publishing
 
-Boards are the unit of publishing (`marver build --boards <name>`): every frame a
-published flow data-gotos must be ON that board - unlisted frames are excluded from
-the bundle at build time.
+Boards are the unit of publishing: `design/publish.json` names each shipped board
+with `read` or `comment` rights (`marver build` fails without it - default-closed;
+`--boards <name>` overrides ad hoc). Every frame a published flow data-gotos must
+be ON a published board - unlisted frames are excluded from the bundle at build
+time. Deploying the built canvas - gate password, the collaboration volume,
+accounts and invites - is its own phase: **instructions/publish.md**.
 
 The published gate page shows the app's identity: `design/logo.svg` + the host
 package name (overridable via config `share`). If the app has no logo asset yet,