@marver-design/marver 0.3.1 → 0.5.0

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 */
 }
@@ -112,6 +122,13 @@ button { font-family: inherit }
 button svg { pointer-events: none }   /* event targets stay on the button - pan exclusion depends on it */
 @media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition: none !important } }
 
+/* Default app pointer: the marver arrowhead (tilted left, rounded, thick border, soft shadow),
+   theme-adaptive - black/white on light, white/dark on dark. Hotspot at its tip (5,2). Overridden by
+   the state cursors: grab (space-pan), resize handles, comment-pin / laser-crosshair (set in-frame by
+   the bridge), and a normal pointer in interact / prototype mode. */
+.sh-app { --sh-cursor: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='22' height='22' viewBox='0 0 26 26'%3E%3Cdefs%3E%3Cfilter id='s' x='-40%' y='-40%' width='180%' height='180%'%3E%3CfeDropShadow dx='0.4' dy='0.9' stdDeviation='0.7' flood-color='%23000000' flood-opacity='0.4'/%3E%3C/filter%3E%3C/defs%3E%3Cg filter='url(%23s)'%3E%3Cg transform='rotate(-20 6 3)'%3E%3Cpath fill='%23000000' stroke='%23FFFFFF' stroke-width='1.6' stroke-linejoin='round' stroke-linecap='round' d='M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a1 1 0 0 1 .7-.3h6.87a1 1 0 0 0 .7-1.7L6.35 2.85a.5.5 0 0 0-.85.35Z'/%3E%3C/g%3E%3C/g%3E%3C/svg%3E") 5 2, default; cursor: var(--sh-cursor) }
+.sh-app.dark { --sh-cursor: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='22' height='22' viewBox='0 0 26 26'%3E%3Cdefs%3E%3Cfilter id='s' x='-40%' y='-40%' width='180%' height='180%'%3E%3CfeDropShadow dx='0.4' dy='0.9' stdDeviation='0.7' flood-color='%23000000' flood-opacity='0.4'/%3E%3C/filter%3E%3C/defs%3E%3Cg filter='url(%23s)'%3E%3Cg transform='rotate(-20 6 3)'%3E%3Cpath fill='%23FFFFFF' stroke='%2318181b' stroke-width='1.6' stroke-linejoin='round' stroke-linecap='round' d='M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a1 1 0 0 1 .7-.3h6.87a1 1 0 0 0 .7-1.7L6.35 2.85a.5.5 0 0 0-.85.35Z'/%3E%3C/g%3E%3C/g%3E%3C/svg%3E") 5 2, default }
+.sh-app.interacting { cursor: auto }
 .sh-app { position: relative; height: 100%; color: var(--glass-ink); outline: none;
   transition: --accent .4s ease, --accent-ring .4s ease, --beam .4s ease,
     --edge-accent .4s ease, --inner-tint .4s ease, --accent-wash .4s ease,
@@ -131,15 +148,20 @@ button svg { pointer-events: none }   /* event targets stay on the button - pan
   opacity: var(--grid-alpha, 1) }
 .sh-content { will-change: auto }
 #sh-world { position: relative; width: 1px; height: 1px }
-#sh-world.sh-gesturing iframe { pointer-events: none }            /* law G-4 */
+#sh-world.sh-gesturing .sh-live { pointer-events: none }          /* law G-4 (live iframe only; lean is always pe:none) */
 .sh-gesturing .sh-content { will-change: transform }              /* law G-3: gesture-scoped only */
 /* preset transitions: armed by animateLayout() around device/tidy mutations - nodes ease
    to their new frame on the same 320ms ease-out the camera fit animates with */
 #sh-world.sh-preset .sh-node { transition: transform .32s cubic-bezier(.25,.46,.45,.94),
   width .32s cubic-bezier(.25,.46,.45,.94), height .32s cubic-bezier(.25,.46,.45,.94) }
 #sh-world.sh-preset .sh-node-body,
-#sh-world.sh-preset .sh-node iframe { transition: width .32s cubic-bezier(.25,.46,.45,.94),
+#sh-world.sh-preset .sh-node .sh-live { transition: width .32s cubic-bezier(.25,.46,.45,.94),
   height .32s cubic-bezier(.25,.46,.45,.94) }
+/* SPEC-M5 device-sweep: a frame WITH a ready lean cover jumps its LIVE iframe straight to the final
+   width (ONE reflow, hidden under the cover) while the lean cover - being width:100% of the animating
+   body - reflows smoothly every frame (real CSS, the device-sweep fix). A frame WITHOUT a usable
+   cover keeps the live width animation above. */
+body:not(.sh-laser):not(.sh-commenting) #sh-world.sh-preset .sh-node:has(.sh-lean[data-ready]):not(.interact) .sh-live { transition: none }
 
 /* cursor conventions (Figma): arrow everywhere; grab only while space is held */
 body.sh-space .sh-canvas { cursor: grab }
@@ -173,7 +195,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
   box-shadow: 0 0 0 calc(4px * var(--sh-inv, 1)) var(--accent-ring), var(--shadow-node) }
 .sh-node-head { height: 28px; display: flex; align-items: center; gap: 8px; padding: 0 11px;
   font-size: 11px; color: var(--head-dim);
-  border-bottom: 1px solid var(--node-brd); cursor: default; user-select: none;
+  border-bottom: 1px solid var(--node-brd); user-select: none;
   border-radius: var(--r-node) var(--r-node) 0 0;
   background-color: var(--head-bg); background-image: var(--head-sheen);
   backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur) }
@@ -187,7 +209,20 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-node-head .dim { margin-left: auto; color: var(--head-dim); flex: none; font-variant-numeric: tabular-nums }
 .sh-node-body { position: relative; background: var(--node-bg); border-radius: 0 0 var(--r-node) var(--r-node); overflow: hidden }
 .sh-node iframe { border: 0; display: block }
-.sh-overlay { position: absolute; inset: 0; cursor: default }
+/* SPEC-M5 LEAN-PRIMARY: the lean DOM-snapshot <iframe> (static html, 0 JS) is what you SEE for a
+   passive frame - at rest AND during pan/zoom/resize. There is NO per-gesture swap between the lean
+   and the live iframe (the swap shifted text ~1-2px = "jiggle", and flashed mermaid/theme colors,
+   because two documents never render pixel-identically). The live app (.sh-live) sits underneath and
+   shows ONLY when: the frame is interacted (.interact), laser/comment mode is on, or the lean is not
+   yet built (no data-ready = live-fallback). Hard cut, never a crossfade - two ~1px-offset text docs
+   would ghost into double text. */
+.sh-lean { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; z-index: 1;
+  opacity: 0; pointer-events: none; transition: none; background: var(--node-bg) }
+.sh-lean[data-ready] { opacity: 1 }
+.sh-node.interact .sh-lean,
+body.sh-laser .sh-lean,
+body.sh-commenting .sh-lean { opacity: 0 }
+.sh-overlay { position: absolute; inset: 0; z-index: 2 }   /* above the lean (z1) so drag-by-body works; inherits the app arrow cursor */
 .sh-node.interact { border-color: var(--interact);
   outline: calc(2px * var(--sh-inv, 1)) solid var(--interact);
   outline-offset: calc(-1px * var(--sh-inv, 1));
@@ -309,8 +344,11 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
   transform-origin: 22px 22px; transition: transform var(--morph), opacity .2s ease }
 .sh-panel.closed { transform: scale(.16); opacity: 0; pointer-events: none }
 .sh-panel-top { display: flex; align-items: center; gap: 8px; padding: 2px 2px 8px 8px }
-.sh-panel-top .mark { flex: none; color: var(--accent) }
-.sh-panel-top .name { font-weight: 700; font-size: 15px; flex: 1; letter-spacing: -0.01em }
+.sh-panel-top .mark-link { flex: none; display: flex; border-radius: 6px; outline-offset: 2px; transition: opacity .15s ease }
+.sh-panel-top .mark-link:hover { opacity: .72 }
+.sh-panel-top .mark { flex: none; color: var(--accent); display: block }
+.sh-panel-top .name { margin-right: auto; min-width: 0; font-weight: 700; font-size: 15px; letter-spacing: -0.01em;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
 .sh-panel-scroll { overflow-y: auto; min-height: 0; padding-bottom: 2px; scrollbar-width: thin;
   scrollbar-color: var(--glass-ink-3) transparent }
 /* Sidebar list system (macOS-sidebar conventions): every row is 28px tall with an
@@ -373,6 +411,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 */
@@ -437,7 +477,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 /* ---- Play mode (SPEC-M2 §1): near-black stage, one centered device, auto-hiding bar.
    Fixed dark palette - the backdrop never follows the board theme, so no tokens here. */
 .sh-play { position: absolute; inset: 0; z-index: 30; background: #0a0a0b; display: flex;
-  align-items: center; justify-content: center; animation: sh-play-in .28s ease-out }
+  align-items: center; justify-content: center; animation: sh-play-in .28s ease-out; cursor: auto }
 @keyframes sh-play-in { from { opacity: 0 } }
 /* the device wears the frame-node card language: same theme border tokens, the same
    masked 1px edge-light gradient ring (glass catching light), and a real drop shadow
@@ -486,6 +526,8 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 /* board switcher */
 .sh-play-bar .bd-wrap { position: relative }
 .sh-play-bar .bd { width: auto; gap: 6px; padding: 0 10px 0 12px; white-space: nowrap; font: inherit }
+.sh-play-bar .sh-play-update { width: auto; gap: 5px; padding: 0 11px; font-size: 12px; font-weight: 600; color: #6db3ff; white-space: nowrap }
+.sh-play-bar .sh-play-update:hover { background: rgba(109, 179, 255, .16); color: #8ec5ff }
 /* no backdrop-filter here: the menu nests inside the blurred bar, and glass never nests
    (a nested backdrop-filter samples the bar, not the page) - near-opaque ink instead */
 .sh-play-menu { position: absolute; top: calc(100% + 10px); left: 0; min-width: 150px; padding: 4px;
@@ -633,3 +675,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/client/stage/main.tsx

@@ -31,6 +31,8 @@ window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:stage-erro
 // pinch inside the stage must not zoom the parent page (same rule as the frame bridge)
 window.addEventListener('wheel', (e) => { if (e.ctrlKey || e.metaKey) e.preventDefault() }, { passive: false })
 document.addEventListener('gesturestart', (e) => e.preventDefault())
+// B0.2: a nested scroll container hitting its boundary must not chain into the shell page
+document.documentElement.style.overscrollBehavior = 'contain'
 
 interface Mounted { id: string; Frame: ComponentType; wrappers: ComponentType[] }
 

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,

package/templates/instructions/configure.md

@@ -39,6 +39,34 @@ canvas, the tour - that flow lives in instructions/welcome.md, run it alongside.
   several half-brands - document the one the app actually ships in DESIGN.md and
   name the others as legacy.
 
+## Working with teammates (branches, merges, a second engineer)
+
+The whole `design/` folder is git-tracked - boards, scenes, comment logs, the
+publish policy, these instructions. Only `design/.local/` (this machine's
+connect credential) and `design/.dist/` (built on the host) are ignored. So a
+teammate gets the exact canvas by pulling the branch: `pnpm install` →
+`npx marver dev`. Nothing else to sync.
+
+How the three kinds of design state merge across branches:
+
+- **Comment logs (`design/comments/*.jsonl`) merge themselves.** They're
+  append-only and keyed by event id, and init writes a `merge=union` git
+  attribute for them - two branches that both collected feedback union
+  cleanly, no conflict. Even a hand-botched merge self-heals: replay dedupes
+  by id. This is the point of the event-log design - multiplayer comments
+  Just Work through plain git.
+- **Scenes (`design/scenes/**.tsx`) merge like any code** - they're React
+  components. Standard review, standard conflicts.
+- **Boards (`design/boards/*.json`) are the one friction** - they're node
+  positions, so two people rearranging the same board conflict on x/y. It's
+  cosmetic: take either side and re-run Tidy, or give features their own
+  boards so layouts don't overlap. Never let a boards conflict block a merge.
+
+If collaboration is deployed, each engineer runs `marver comments connect
+<url>` ONCE with their own account (the owner invites them) to get the live
+cloud sync on top of git. Git carries the committed comments; `connect` adds
+the real-time stream from published viewers.
+
 ## When it breaks mid-project
 
 Frames suddenly unstyled → the theme import path moved: fix `design/theme.css`.

package/templates/instructions/iterate.md

@@ -48,3 +48,41 @@ The human picks a direction; then, in one pass:
 Archived frames are history, not options: never link them from live flows,
 never count them as current design. They exist so "what did we try for the
 editor?" has a visual answer.
+
+## Comments are your work queue
+
+When collaboration is on, humans pin comments to specific elements inside
+frames. Those threads are addressed to YOU as much as to the designer - treat
+the open list as a queue:
+
+```bash
+npx marver comments list --open --json     # what needs you (anchors included)
+npx marver comments reply <thread> --body "…"
+npx marver comments resolve <thread> --addressed-in <scene/frame>
+```
+
+The discipline:
+
+1. **Read the anchor before the words.** Each thread carries the element it
+   points at - tag, quote, source hint, position. "Too cramped" pinned to a
+   button is a different task than "too cramped" on the whole frame.
+2. **Fork, don't overwrite.** Address feedback by creating a NEW variant of the
+   frame (the letter convention above) and iterating there. The commented
+   frame stays as the before; your variant is the after.
+3. **Resolve with the receipt.** `--addressed-in <the-new-variant>` records
+   WHICH frame answered the feedback - the thread becomes an auditable link
+   from complaint to fix. Reply first when the change deserves a sentence of
+   explanation; resolve silently only for trivial mechanical fixes.
+4. **Never resolve what you didn't address.** Disagree? Reply with your
+   reasoning and leave the thread open - the human closes debates, you close
+   completed work.
+5. **A frame with open comments is load-bearing - never delete, rename, or
+   gut it.** Its threads are anchored to elements INSIDE it; restructure the
+   frame and the anchors strand (a dead anchor parks the pin at the frame
+   edge; deleting the whole frame strands the thread off-canvas entirely -
+   never lost from the log, but invisible until the frame returns). So: fork
+   the variant and iterate THERE, leave the commented frame untouched as the
+   before, and only once you `resolve --addressed-in <variant>` its threads
+   may it move to `archive/`. Resolve first, restructure second - never the
+   reverse. Check `comments list --board <b>` (no `--open`) to see resolved
+   threads too; the full history lives in the append-only log and in git.