@marver-design/marver 0.17.0 → 0.19.0

package/src/client/shell/App.tsx

@@ -13,6 +13,8 @@ import { humanize as slugLabel, readTitle } from '../../shared/board-tree.ts'
 import { CommentsController, revealThread } from './Comments.tsx'
 import { poweredByUrl } from '../../shared/utm.ts'
 import { avatarFallback, useComments } from './comments-store.ts'
+import { goTo } from './goto.ts'
+import { useNotes } from './notes.ts'
 import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
 
 const commentsStore = () => useComments.getState()
@@ -550,11 +552,18 @@ export function App() {
         // sh:measure does, so a stale ready never marks a reloading frame ready.
         const gen = el.src.match(/[?&]r=(\d+)/)?.[1] ?? ''
         if (String(data.gen ?? '') !== gen) return
+        // a document that loaded again on its own (a full reload) is a new source revision: the
+        // sleeping override of the previous document must not be trusted for this one
+        if (s.nodes.find((n) => n.key === nodeKey)?.status === 'ready') s.bumpRev(nodeKey)
         s.setStatus(nodeKey, 'ready')
       } else if (data.type === 'sh:error') {
         s.setStatus(nodeKey, 'error', String(data.message ?? 'unknown error'))
       } else if (data.type === 'sh:exit-interact') {
         if (s.interact === nodeKey) setInteract(null)
+      } else if (data.type === 'sh:theme-applied') {
+        if (typeof data.theme === 'string') s.setThemeOn(nodeKey, data.theme)
+      } else if (data.type === 'sh:hmr') {
+        s.bumpRev(nodeKey)
       } else if (data.type === 'sh:measure') {
         // Generation guard: the sender echoes ITS document's URL rev; a
         // WindowProxy survives navigation, so a stale pre-navigation message would
@@ -592,17 +601,9 @@ export function App() {
         if (c.active) c.setActive(null)
         if (c.commentMode) c.setDraft({ nodeKey, frame: String(data.id ?? ''), anchor: data.anchor })
       } else if (data.type === 'sh:go') {
-        const target = String(data.target ?? '')
-        const carry = s.interact === nodeKey   // a goto from inside an interacting frame
-        // CARRIES interact mode to the target - walking a flow must not eject you to
-        // design mode at every hop (and must survive a board switch)
-        const existing = s.nodes.find((n) => n.frame === target && !n.missing)
-        if (existing) {
-          gotoSeq++                                  // a local goto supersedes any cross-board one in flight
-          select(existing.key)
-          if (carry) setInteract(existing.key)
-          setTimeout(() => canvasCtl.fitNode(existing.key), 50)
-        } else void gotoAcrossBoards(target, carry)
+        // a goto from inside an interacting frame CARRIES interact mode to the target - walking
+        // a flow must not eject you to design mode at every hop (and must survive a board switch)
+        goTo(String(data.target ?? ''), s.interact === nodeKey)
       } else if (data.type === 'sh:wheel') {
         // B0.2: a passive frame forwarded a wheel event; the canvas owns it. Never for the
         // interact target or play (the app scrolls itself - the parent stays authoritative).
@@ -674,6 +675,8 @@ export function App() {
         toast(c.commentMode ? 'comment mode off' : 'comment mode - click an element in a frame')
       }
       if (e.key === 'C' && e.shiftKey) { const c = commentsStore(); c.setShow(!c.show) }
+      // sticky notes (spec 18): any note visible -> hide all; none -> show all
+      if (e.key === 'n' && !e.shiftKey) { const visible = document.querySelectorAll('.sh-notes:not(.off)').length > 0; useNotes.getState().toggleAll(visible); toast(visible ? 'notes hidden' : 'notes shown'); return }
       // Shift+L = laser comment: the laser-sharp lighting on the element a comment tags
       // (pick hover, compose lock, open-thread highlight). Pins and cards stay - this
       // only dims the lighting inside the artwork.
@@ -1010,58 +1013,6 @@ function JamAvatar({ author }: { author: { name?: string; avatar?: string; id?:
     : <span className="sh-jam-ava init" style={{ background: `hsl(${hue} 55% 45%)` }}>{initials}</span>
 }
 
-/** A data-goto whose target frame is not on the current board follows the frame HOME:
- *  the first curated board (switcher rank) that pins it is switched to and the frame
- *  focused there - a link is navigation, and navigation never edits a board. Only a
- *  frame NO board pins spawns onto the current board (the original prototype behavior
- *  for unpinned targets); an id the manifest doesn't know stays a toast. Every goto
- *  bumps `gotoSeq` so a slow older resolution can never override newer navigation. */
-let gotoSeq = 0
-async function gotoAcrossBoards(target: string, carry: boolean) {
-  const s = useStore.getState()
-  // an id the manifest doesn't know resolves NOWHERE - a tombstone pin on some board
-  // must not send us on a trip that ends in a silent timeout
-  if (!s.manifest?.frames.some((f) => f.id === target)) return s.toast(`unknown goto target "${target}"`)
-  const seq = ++gotoSeq
-  let home: string | null = null
-  try {
-    const names = (await fetchBoardNames()).filter((n) => n !== s.board && n !== 'all-scenes')
-    for (const name of names) {
-      if ((await boardFrames(name)).includes(target)) { home = name; break }
-    }
-  } catch {
-    // a transport failure is NOT proof the frame is unpinned - spawning here would
-    // recreate the board mutation this function exists to prevent
-    return useStore.getState().toast(`goto: could not read the boards - try again`)
-  }
-  if (seq !== gotoSeq) return                        // superseded by newer navigation
-  if (!home) {
-    // no curated board pins it - the original prototype behavior: spawn beside you
-    const st = useStore.getState()
-    const node = st.spawn(target)
-    if (!node) return st.toast(`unknown goto target "${target}"`)
-    st.select(node.key)
-    if (carry) st.setInteract(node.key)
-    setTimeout(() => canvasCtl.fitNode(node.key), 50)
-    return
-  }
-  await s.switchBoard(home)
-  for (let i = 0; i < 12; i++) {                     // the board commits async - retry like viewNote
-    if (seq !== gotoSeq) return
-    const st = useStore.getState()
-    if (st.board === home) {                         // a cancelled/failed switch must not select here
-      const node = st.nodes.find((n) => n.frame === target && !n.missing)
-      if (node) {
-        st.select(node.key)
-        if (carry) st.setInteract(node.key)
-        setTimeout(() => canvasCtl.fitNode(node.key), 50)
-        return
-      }
-    }
-    await new Promise((r) => setTimeout(r, 250))
-  }
-}
-
 /** View from a notification: threads are frame-scoped, so first try to reveal RIGHT HERE
  *  (the current board may show the thread's frame); only when it doesn't, switch to the
  *  note's origin board and retry while its comments load. Dismiss only on success: a

package/src/client/shell/Comments.tsx

@@ -9,6 +9,7 @@ import { createPortal } from 'react-dom'
 import { avatarFallback, useComments } from './comments-store.ts'
 import { useStore, type Node } from './store.ts'
 import { threadHostKey } from './keys.ts'
+import { isNoteAnchor, resolveNoteAnchor, useNotes } from './notes.ts'
 import { canvasCtl } from './canvas/ctl.ts'
 import { bootHash, buildHash, parseHash, writeHash } from './hash.ts'
 import { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, ParallelogramFillIcon, PencilSimpleIcon, PlusIcon, XIcon } from './icons.tsx'
@@ -138,11 +139,15 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
   // a remote resolve (thread leaves `open` while `active` is unchanged) still clears the lock
   const activeShown = !!active && open.some((t) => t.id === active)
 
+  // anchors split by where they live: in the frame document (inspect.js resolves them over
+  // postMessage) or on a sticky note (spec 18: shell DOM, resolved right here)
+  const inFrame = anchored.filter((t) => !isNoteAnchor(t.anchor))
+  const onNote = anchored.filter((t) => isNoteAnchor(t.anchor))
   // resolve anchors against the live frame whenever threads or the document change
   useEffect(() => {
     const win = iframe.current?.contentWindow
-    if (!win || node.status !== 'ready' || !anchored.length) return
-    const ask = () => win.postMessage({ type: 'sh:resolve-anchors', anchors: anchored.map((t) => ({ key: t.id, anchor: t.anchor })) }, location.origin)
+    if (!win || node.status !== 'ready' || !inFrame.length) return
+    const ask = () => win.postMessage({ type: 'sh:resolve-anchors', anchors: inFrame.map((t) => ({ key: t.id, anchor: t.anchor })) }, location.origin)
     const onMsg = (e: MessageEvent) => {
       if (e.source !== win || e.origin !== location.origin || e.data?.type !== 'sh:anchor-rects') return
       const next: typeof rects = {}
@@ -153,7 +158,44 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
     ask()
     const iv = setInterval(ask, 4000)          // re-renders, scroll, hot reloads - cheap to re-ask
     return () => { clearInterval(iv); window.removeEventListener('message', onMsg) }
-  }, [node.status, anchored.map((t) => t.id).join(','), iframe])
+  }, [node.status, inFrame.map((t) => t.id).join(','), iframe])
+  // note anchors: their own map, measured in the shell, in node-body coordinates (negative x -
+  // the note is left of the frame). The composing draft is measured too (key 'draft'), so it
+  // follows a fold like a saved pin. A folded column parks pins on the fold; a note whose file
+  // is gone, or whose element the markdown no longer has, parks like an orphan. Re-measured on
+  // every fold/unfold (twice: at once and past the transition) and on the same 4 s beat.
+  const [noteRects, setNoteRects] = useState<typeof rects>({})
+  const notesState = useNotes()
+  const draftOnNote = draft?.nodeKey === node.key && isNoteAnchor(draft.anchor) ? draft.anchor : null
+  useEffect(() => {
+    if (!onNote.length && !draftOnNote) { setNoteRects((r) => (Object.keys(r).length ? {} : r)); return }
+    const measure = () => {
+      const host = document.querySelector(`[data-node="${CSS.escape(node.key)}"]`) as HTMLElement | null
+      const origin = host?.querySelector('.cm-layer')?.getBoundingClientRect()
+      if (!host || !origin) return
+      const s = origin.width ? origin.width / host.offsetWidth : 1
+      const toBody = (r: DOMRect) => ({ x: (r.left - origin.left) / s, y: (r.top - origin.top) / s, w: r.width / s, h: r.height / s })
+      const column = host.querySelector('.sh-notes')
+      const fold = column?.querySelector('.sh-notes-fold')
+      const place = (a: any) => {
+        const body = column?.querySelector(`[data-sticky="${a.el.note}"] .sh-sticky-body`)
+        if (!body) return null
+        if (column!.classList.contains('off')) return fold ? toBody(fold.getBoundingClientRect()) : null
+        const el = resolveNoteAnchor(a, body)
+        return el ? toBody(el.getBoundingClientRect()) : null
+      }
+      const next: typeof rects = {}
+      for (const t of onNote) next[t.id] = place(t.anchor)
+      if (draftOnNote) next.draft = place(draftOnNote)
+      setNoteRects(next)
+    }
+    measure()
+    const late = setTimeout(measure, 260)
+    const iv = setInterval(measure, 4000)
+    return () => { clearTimeout(late); clearInterval(iv) }
+  }, [onNote.map((t) => t.id).join(','), draftOnNote, notesState.all, notesState.hidden.join(','), node.key, node.w, node.h])
+  /** This node's sticky column when it is showing: the docked card must clear it (world px). */
+  const noteColumn = (): HTMLElement | null => document.querySelector(`[data-node-notes="${CSS.escape(node.key)}"]:not(.off)`)
 
   // #4/#5: drive the persistent element highlight into this frame - the composing draft on
   // this node (lock on pick), or the open thread anchored here (highlight on open). null
@@ -168,7 +210,15 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
     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 && showAnchor ? (draftHere ?? (activeHere ? (activeHere.anchor as any) : null)) : null
-    win.postMessage({ type: 'sh:highlight-anchor', frame: frameId, anchor: anchor ?? null }, location.origin)
+    win.postMessage({ type: 'sh:highlight-anchor', frame: frameId, anchor: isNoteAnchor(anchor) ? null : anchor ?? null }, location.origin)
+    // a note anchor lights its element in the shell the way the frame lights its own
+    const host = document.querySelector(`[data-node="${CSS.escape(node.key)}"]`)
+    for (const el of host?.querySelectorAll('[data-sh-lock]') ?? []) el.removeAttribute('data-sh-lock')
+    if (isNoteAnchor(anchor)) {
+      const body = host?.querySelector(`[data-sticky="${anchor.el.note}"] .sh-sticky-body`)
+      const el = body && resolveNoteAnchor(anchor, body)
+      if (el) el.setAttribute('data-sh-lock', '')
+    }
     // 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])
 
@@ -181,6 +231,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
   // 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))
+  // (a sticky column is read from the DOM at render: it is per viewer and per host node)
   const drafting = draft?.nodeKey === node.key
   const alertIds = useMentionAlerts()
   if (!show || (!open.length && !drafting)) return null
@@ -198,7 +249,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
 
   const pinPos = (t: Thread) => {
     const a = t.anchor as any
-    const r = rects[t.id]
+    const r = isNoteAnchor(a) ? noteRects[t.id] : rects[t.id]
     if (a?.el && r) return { x: r.x + (a.pos?.fx ?? 0.5) * r.w, y: r.y + (a.pos?.fy ?? 0.5) * r.h, orphan: false }
     if (a?.el && r === null) return { x: node.w - 16, y: 16, orphan: true }         // orphan parks top-right
     const p = a?.pos                                                                // frame-level: stored fraction of the frame
@@ -214,15 +265,23 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
       const W = 320, GAP = 30
       const rect = document.querySelector(`[data-node="${CSS.escape(node.key)}"]`)?.getBoundingClientRect()
       if (!rect) return 'r'
+      // a showing sticky column sits in the left gutter in WORLD px (its width + 36, the CSS
+      // margin): the card lands beyond it, so both room and collision use that screen offset
+      const scale = rect.width / Math.max(1, node.w)
+      const col = noteColumn()
+      const gutter = col ? col.getBoundingClientRect().width + 36 * scale : 0
       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 rx = s === 'r' ? rect.right + 10 : rect.left - gutter - 10 - W
+        return [...document.querySelectorAll('.sh-node, .sh-notes:not(.off)')].some((n) => {
+          if (n.getAttribute('data-node') === node.key || n.getAttribute('data-node-notes') === 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
+      // the left room starts at the sidebar's edge, not the window's: a card parked under the
+      // panel is a card nobody can read (a note's gutter makes that reach likelier)
+      const panelRight = document.querySelector('.sh-panel:not(.closed)')?.getBoundingClientRect().right ?? 0
+      const room = (s: 'l' | 'r') => (s === 'r' ? window.innerWidth - rect.right : rect.left - gutter - panelRight) >= 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]
     }
@@ -247,9 +306,13 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
       })}
       {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} />
+          flank={cardSide === 'l' ? (noteColumn() ? 'note' : 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)} />}
+      {draft?.nodeKey === node.key && (() => {
+        const a = draft.anchor as any
+        const r = (draftOnNote && noteRects.draft) || a?.rect
+        return <DraftComposer at={{ x: (r?.x ?? 0) + (a?.pos?.fx ?? 0.5) * (r?.w ?? 0), y: (r?.y ?? 0) + (a?.pos?.fy ?? 0.5) * (r?.h ?? 0) }} bounds={{ w: node.w, h: node.h }} hue={anchorHue(draft.anchor)} />
+      })()}
     </>
   )
 }
@@ -538,7 +601,7 @@ function ComposeAvatar() {
   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 }) {
+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' | 'note' | null; stage?: boolean }) {
   const { resolve, setActive } = useComments.getState()
   const me = useComments((s) => s.me)
   const local = useComments((s) => s.local)
@@ -935,8 +998,8 @@ export function CommentsController() {
     return () => window.removeEventListener('hashchange', onHash)
   }, [])
 
-  // broadcast pick mode to every LIVE frame (laser rides along inside the bridge). Scoped to
-  // .sh-live so the lean cover (.sh-lean, a scriptless snapshot) is never messaged.
+  // broadcast pick mode to every frame (laser rides along inside the bridge); a sleeping frame
+  // is the live document itself, so it is messaged like any other
   useEffect(() => {
     for (const f of document.querySelectorAll('iframe.sh-live'))
       (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode, quiet: !ctlShowAnchor }, location.origin)

package/src/client/shell/Play.tsx

@@ -14,6 +14,7 @@ import { useEffect, useRef, useState } from 'react'
 import { useStore, BOARD_POLICY, BRANDING, CONFIG, PUBLISHED, SOURCE_REVEALED, boardLabel, boardLocked, cap, fetchBoardNames, modeAllowed, playsAsSlides, SLIDE_INTRINSIC, type Node } from './store.ts'
 import { deckOrder } from './play-order.ts'
 import { useComments } from './comments-store.ts'
+import { isNoteAnchor } from './notes.ts'
 import { ROUTE } from '../const.ts'
 import { poweredByUrl } from '../../shared/utm.ts'
 import { canvasCtl } from './canvas/ctl.ts'
@@ -207,7 +208,9 @@ function PlayComments({ iframe, frameId, vp, dw, dh, ready }: {
   const draft = useComments((s) => s.draft)
   const allThreads = useComments((s) => s.threads)
   const { setActive } = useComments.getState()
-  const threads = allThreads.filter((t) => t.frame === frameId && !t.resolved)
+  // a thread on a sticky note (spec 18) belongs to the canvas: the stage has no notes, and its
+  // anchor must never be handed to inspect.js (a same-named frame element would match)
+  const threads = allThreads.filter((t) => t.frame === frameId && !t.resolved && !isNoteAnchor(t.anchor))
   const anchored = threads.filter((t) => (t.anchor as any)?.el)
   const [rects, setRects] = useState<Record<string, { x: number; y: number; w: number; h: number } | null>>({})
   const sx = vp.width ? dw / vp.width : 1
@@ -245,7 +248,7 @@ function PlayComments({ iframe, frameId, vp, dw, dh, ready }: {
     if (!win) return
     // only while the thread is active (or composing) AND pins are shown AND element focus is
     // on (⇧L) - closing, ⇧C, or dimming focus clears it
-    const at = !show || !showAnchor ? null : (draft?.frame === frameId ? draft.anchor
+    const at = !show || !showAnchor ? null : (draft?.frame === frameId && !isNoteAnchor(draft.anchor) ? draft.anchor
       : (active ? (threads.find((t) => t.id === active && (t.anchor as any)?.el)?.anchor ?? null) : null))
     win.postMessage({ type: 'sh:highlight-anchor', frame: frameId, anchor: at ?? null }, location.origin)
   }, [active, draft, show, showAnchor, frameId, iframe, rects, ready])
@@ -261,7 +264,7 @@ function PlayComments({ iframe, frameId, vp, dw, dh, ready }: {
     return { x: (p?.fx ?? .94) * dw, y: (p?.fy ?? .06) * dh, orphan: false }
   }
   const activeThread = threads.find((t) => t.id === active)
-  const draftAt = draft?.frame === frameId ? (() => {
+  const draftAt = draft?.frame === frameId && !isNoteAnchor(draft.anchor) ? (() => {
     const a = draft.anchor as any
     return { x: ((a?.rect?.x ?? 0) + (a?.pos?.fx ?? .5) * (a?.rect?.w ?? 0)) * sx, y: ((a?.rect?.y ?? 0) + (a?.pos?.fy ?? .5) * (a?.rect?.h ?? 0)) * sy }
   })() : null

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

@@ -4,6 +4,7 @@ import { CONFIG, useStore } from '../store.ts'
 import { bootHash } from '../hash.ts'
 import { startPerf } from '../perf.ts'
 import { FrameNode, HEADER } from './FrameNode.tsx'
+import { NOTE_GAP } from '../notes.ts'
 import { startCameraBroadcast, setCameraScale } from './camera-broadcast.ts'
 
 /**
@@ -177,7 +178,15 @@ export function Canvas() {
           y0 -= Math.max(64, 36 / s1)    // caption line above the group
         }
       }
-      fitRect(x0, y0, x1 - x0, y1 - y0, focus)
+      // sticky notes (spec 18): a visible column hangs left of its frame, and may run below it
+      let y1n = y1
+      for (const n of ns) {
+        const col = document.querySelector(`[data-node-notes="${CSS.escape(n.key)}"]:not(.off)`) as HTMLElement | null
+        if (!col) continue
+        x0 = Math.min(x0, n.x - col.offsetWidth - NOTE_GAP)
+        y1n = Math.max(y1n, n.y + col.offsetTop + col.offsetHeight)
+      }
+      fitRect(x0, y0, x1 - x0, y1n - y0, focus)
     }
     canvasCtl.fitNode = (key: string) => fitKeys([key], true)
     canvasCtl.fitNodes = (keys: string[]) => fitKeys(keys, true)
@@ -246,8 +255,8 @@ export function Canvas() {
     if (!app || !canvas) return
     let settle = 0
     const beginGesture = (panning: boolean) => {
-      // sh-camera = a CANVAS pan/zoom (drives the snapshot cover); sh-gesturing also drops iframe
-      // pointer-events. A frame click/drag sets only sh-gesturing, so it never flashes a snapshot.
+      // sh-camera = a CANVAS pan/zoom (the image-LOD freeze signal); sh-gesturing also drops iframe
+      // pointer-events. A frame click/drag sets only sh-gesturing.
       document.getElementById('sh-world')?.classList.add('sh-gesturing', 'sh-camera')
       document.body.classList.toggle('sh-panning', panning)
       clearTimeout(settle)