@marver-design/marver 0.17.0 → 0.19.0

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

@@ -1,13 +1,16 @@
-import { memo, useCallback, useEffect, useRef } from 'react'
+import { memo, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
+import { admit, release } from './admission.ts'
 import { CopyIcon, IntentGlyph, ParallelogramFillIcon, ReloadIcon, SlideFrameIcon, XIcon } from '../icons.tsx'
 import { CommentLayer } from '../Comments.tsx'
 import { useComments } from '../comments-store.ts'
 import { threadHostKey } from '../keys.ts'
 import { registerFrame, unregisterFrame } from './frame-registry.ts'
 import { primeCameraFor } from './camera-broadcast.ts'
-import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
+import { sleep, wake } from './sleep.ts'
 import { canAutoReload, shouldArmReadyWatch } from './ready-watch.ts'
+import { Stickies, type NoteSpec } from './Sticky.tsx'
+import { noteId, sceneNoteHost } from '../notes.ts'
 
 export const HEADER = 28
 const SNAP = 12
@@ -34,6 +37,12 @@ function WorkShimmer({ belowBadge }: { belowBadge: boolean }) {
  * One frame on the canvas. Iframe laws: the iframe element is created once per node key
  * and never remounted - theme changes go through sh:set-theme, size changes are CSS only.
  *
+ * At rest the frame SLEEPS in place (sleep.ts, spec 16): the same live document, its animations
+ * paused and its backdrop-filters replaced by certified textures. Interact mode wakes it; laser,
+ * comment pins and selection act on the sleeping document as it is. A frame the human has
+ * interacted with is a state the compiler cannot reproduce from its URL: it stays awake until
+ * it is reloaded. Any change of theme, size or source wakes first and sleeps again once settled.
+ *
  * Every interactive element carries `sh-no-pan` (rzpp's panning.excluded checks the event
  * TARGET's classList, nothing else), and drags additionally raise the store gesture flag,
  * which hard-disables canvas panning for the duration. Both are needed: the class stops the
@@ -44,6 +53,18 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const selected = useStore((s) => s.selection.includes(node.key))
   const interact = useStore((s) => s.interact === node.key)
   const working = useStore((s) => s.working.includes(node.frame))   // Live Jam: Marver is editing this frame
+  // sticky notes (spec 18): the scene's note when this node is the scene's first on the board
+  // (reading order), then the frame's own. Text is compared by value - a note edit re-renders
+  // only its column; a pan never re-renders any node (no position subscription here).
+  const sceneNote = useStore((s) => {
+    const scene = frame?.scene
+    const text = scene ? s.manifest?.scenes.find((sc) => sc.name === scene)?.note : undefined
+    if (!text) return undefined
+    return sceneNoteHost(s.nodes, (id) => s.manifest?.frames.find((f) => f.id === id)?.scene, scene!) === node.key ? text : undefined
+  })
+  const notes: NoteSpec[] = []
+  if (frame && sceneNote) notes.push({ kind: 'scene', id: noteId('scene', frame.scene), text: sceneNote })
+  if (frame?.note) notes.push({ kind: 'frame', id: noteId('frame', frame.id), text: frame.note })
   const workingSince = useStore((s) => s.workingSince[node.frame])
   // B0.1: no reactive scale subscription - it re-rendered every FrameNode on every
   // pan/zoom tick. gestureScale below measures the world rect (the canonical source,
@@ -51,21 +72,46 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, reloadFrame, setGesture, toast } = useStore.getState()
   const iframeRef = useRef<HTMLIFrameElement>(null)
   const themeRef = useRef(node.theme)
-  // src is frozen at mount: theme changes ride sh:set-theme (never navigation), so
-  // frame state (forms, scroll, dialogs) survives a theme flip. Real file changes below.
-  const initialSrc = useRef<string | null>(null)
-  if (frame && initialSrc.current === null) initialSrc.current = frameUrl(frame, node.theme)
+  // The JSX src is set ONCE, at ADMISSION, with the theme and revision of that moment, and never
+  // changes again (React would write it back after any later navigation and load the frame twice):
+  // theme changes ride sh:set-theme (never navigation), so frame state (forms, scroll, dialogs)
+  // survives a theme flip; file changes and reloads navigate imperatively below, only once
+  // admitted - a queued frame takes the fresh revision when its turn comes.
+  const [src, setSrc] = useState<string>()
+  const admitted = src !== undefined
+  const admittedRef = useRef(false)
   const fileRef = useRef(frame ? `${frame.kind}:${frame.file}` : null)
 
-  // theme switch without remount: the live iframe flips via message (no navigation). The lean is
-  // INVALIDATED (not mutated) - a baked mermaid SVG can't be re-themed in place, so we drop it, show
-  // live while it re-renders in the new theme, and the capture effect (theme is a dep) rebuilds a
-  // fresh lean that is only shown once ready. No light-on-dark flash.
+  // admission (admission.ts): the iframe gets its src when a boot slot is free, nearest the centre
+  // of the view first; the slot goes back when the frame is ready, errored, gone, or its watchdog acts
+  const navigate = (url: string) => { if (admittedRef.current && iframeRef.current) iframeRef.current.src = url }
+  useEffect(() => {
+    if (!frame || node.missing) { admittedRef.current = false; setSrc(undefined); return }   // gone: the card replaces the iframe; a return is a new document, admitted anew
+    if (admittedRef.current) return   // the document exists (the frame's id changed under it): no slot
+    const rank = () => {   // visible first, then by distance to the centre of the canvas (the panel offsets the window's)
+      const r = iframeRef.current?.getBoundingClientRect(), c = document.querySelector('.sh-canvas')?.getBoundingClientRect()
+      if (!r || !c) return Infinity
+      const visible = r.right > c.left && r.left < c.right && r.bottom > c.top && r.top < c.bottom
+      return (visible ? 0 : 1e7) + Math.hypot(r.x + r.width / 2 - c.x - c.width / 2, r.y + r.height / 2 - c.y - c.height / 2)
+    }
+    const start = () => {
+      const s = useStore.getState(), n = s.nodes.find((x) => x.key === node.key), f = n && s.frameFor(n)
+      if (!n || !f) { release(node.key); return }
+      if (n.status !== 'loading') setStatus(node.key, 'loading')   // a returning frame boots under the watchdog like any other
+      admittedRef.current = true
+      setSrc(frameUrl(f, n.theme))
+    }
+    admit({ key: node.key, rank, start })
+    return () => release(node.key)
+  }, [frame?.id, node.key, node.missing])
+  useEffect(() => { if (node.status !== 'loading') release(node.key) }, [node.status, node.key])
+
+  // theme switch without remount: the live iframe flips via message (no navigation); the frame
+  // reports sh:theme-applied and only then sleeps again under the new theme (node.themeOn)
   useEffect(() => {
     if (themeRef.current !== node.theme) {
       themeRef.current = node.theme
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:set-theme', theme: node.theme }, '*')
-      invalidateLean(node.key)
     }
   }, [node.theme, node.key])
 
@@ -90,53 +136,6 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     registerWin()
   }, [node.key])
 
-  // Register the facade <iframe> so the lean coordinator can drive its srcdoc imperatively.
-  const bindLean = useCallback((el: HTMLIFrameElement | null) => { registerLeanFrame(node.key, el) }, [node.key])
-  // capture a fresh lean snapshot once the frame is ready and quiet, and whenever its CONTENT changes
-  // (nav). Resize needs no re-capture (the lean doc reflows) and theme needs none (attribute flip),
-  // so neither is a dep - keeping captures rare. Never during a gesture; the coordinator serialises.
-  useEffect(() => {
-    // capture reads the live iframe's same-origin document - true in dev AND publish (published frames
-    // are bundled same-origin and served by `marver serve`), so the lean tier works in both via this
-    // client-side capture. Fail-soft: a frame that can't serialise stays live (publish == today's
-    // behaviour in the worst case). No headless build step / heavy dependency needed.
-    if (node.status !== 'ready' || node.missing) return
-    const iframe = iframeRef.current
-    if (!iframe) return
-    const t = setTimeout(() => {
-      // never re-admit a cover while this frame hosts an open thread / draft: the live app
-      // must stay visible (its highlight updates in real time). A status/theme change would
-      // otherwise capture the live DOM WITH the highlight baked in and re-cover it. The
-      // hostsCard rail recaptures a clean lean once the card closes.
-      const c = useComments.getState()
-      // hosting goes through the resolver (keys.ts): an adopted thread's card renders
-      // here even though its stored nodeKey names a node that no longer exists
-      const hosting = (!!c.active && c.threads.some((th) =>
-        th.id === c.active && !th.resolved && threadHostKey(th, useStore.getState().nodes) === node.key)) || c.draft?.nodeKey === node.key
-      if (hosting) return
-      scheduleCapture(node.key, iframe, { sourceRevision: String(node.nav ?? 0), theme: node.theme })
-    }, 450)
-    return () => clearTimeout(t)
-    // node.theme IS a dep: baked content (mermaid SVG) can't be re-themed by the cover's attribute
-    // flip, so a theme change re-captures after the live frame re-renders (key includes theme).
-  }, [node.status, node.nav, node.key, node.missing, node.theme])
-  useEffect(() => () => dropSnapshot(node.key), [node.key])   // drop the snapshot on unmount
-  // a reload / file-swap / error takes the frame out of 'ready': drop its cover so a stale picture
-  // never lingers (nav may not bump on a same-file reload). The next 'ready' re-captures.
-  useEffect(() => { if (node.status !== 'ready') dropSnapshot(node.key) }, [node.status, node.key])
-  // LEAN-PRIMARY focus handoff: entering interact shows the live app (drop the now-stale lean at
-  // once); leaving it recaptures the live frame's CURRENT state (the user may have typed/toggled)
-  // and only swaps back to lean once that fresh capture is admitted. force=true: same nav/theme.
-  const prevInteract = useRef(interact)
-  useEffect(() => {
-    if (prevInteract.current === interact) return
-    const wasInteract = prevInteract.current
-    prevInteract.current = interact
-    if (interact) invalidateLean(node.key)
-    else if (wasInteract && node.status === 'ready' && iframeRef.current)
-      scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
-  }, [interact, node.key, node.nav, node.theme, node.status])
-
   // laser mode rides the same rail; re-sent when a frame becomes ready
   // so late loaders join an already-lasered board
   const laser = useStore((s) => s.laser)
@@ -147,21 +146,6 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const hostsCard = useComments((s) =>
     (!!s.active && s.threads.some((t) =>
       t.id === s.active && !t.resolved && threadHostKey(t, useStore.getState().nodes) === node.key)) || s.draft?.nodeKey === node.key)
-  // a frame hosting an OPEN thread or a draft must show its LIVE app, not the frozen lean
-  // cover: the active-element highlight lives in the live DOM and updates in real time
-  // (open -> lit, close -> cleared). Without this the cover re-freezes the moment comment
-  // mode ends and either bakes a stale highlight or hides the live one. Mirror the interact
-  // rail: drop the cover while hosting, rebuild a fresh lean once the card closes (the
-  // highlight is cleared by then, so the recapture is clean).
-  const prevHostsCard = useRef(hostsCard)
-  useEffect(() => {
-    if (prevHostsCard.current === hostsCard) return
-    const wasHosting = prevHostsCard.current
-    prevHostsCard.current = hostsCard
-    if (hostsCard) invalidateLean(node.key)
-    else if (wasHosting && node.status === 'ready' && iframeRef.current)
-      scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
-  }, [hostsCard, node.key, node.nav, node.theme, node.status])
   useEffect(() => {
     if (node.status === 'ready' || !laser)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:laser', on: laser }, location.origin)
@@ -179,6 +163,32 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (node.status === 'ready' || !interact)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:interactive', on: interact }, location.origin)
   }, [interact, node.status])
+  // SLEEP lifecycle. Interact = awake and DIRTY (the app's state is now its own); a resize drag =
+  // awake for the whole drag; any other change of the key (theme once applied, size, source revision,
+  // navigation) wakes first - the old override describes another state - and sleeps again once the
+  // new one has settled. Laser and comment mode need nothing: the sleeping document IS the live one.
+  const dirty = useRef(false)
+  const lastDoc = useRef<Document | null>(null)   // a new document (reload, self-reload) is pristine again
+  const resizing = useRef(false)
+  const [resizeTick, setResizeTick] = useState(0)
+  useEffect(() => { dirty.current = false }, [node.nav])   // a fresh document is pristine again
+  const w = Math.round(node.w), h = Math.round(node.h)
+  // a layout effect: the wake lands BEFORE the first paint of the new state (a stretched texture
+  // must never be painted at a new size)
+  useLayoutEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe || !frame || node.missing) { wake(node.key, null); return }   // nothing to keep (a deleted frame's card must not retain its old document)
+    const doc = iframe.contentDocument
+    if (doc && doc !== lastDoc.current) { lastDoc.current = doc; dirty.current = false }
+    if (interact) dirty.current = true
+    wake(node.key, iframe)
+    if (interact || dirty.current || resizing.current || node.status !== 'ready') return
+    if (node.themeOn !== undefined && node.themeOn !== node.theme) return   // the frame has not painted the new theme yet
+    const t = setTimeout(() => { void sleep(node.key, iframe, { frame: frame.id, theme: node.theme, w, h }) }, 250)
+    return () => clearTimeout(t)
+  }, [interact, node.status, node.theme, node.themeOn, node.rev, node.nav, w, h, node.missing, frame?.id, node.key, resizeTick])
+  useEffect(() => () => wake(node.key, iframeRef.current), [node.key])
+
   // image-LOD: once the frame is ready its content listener is live, so send the settled zoom - a static
   // board that never gets a gesture then still sharpens its images from the cheap low-res first paint.
   useEffect(() => {
@@ -191,7 +201,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     const sig = `${frame.kind}:${frame.file}`
     if (fileRef.current !== null && fileRef.current !== sig && iframeRef.current) {
       setStatus(node.key, 'loading')
-      iframeRef.current.src = frameUrl(frame, node.theme)
+      navigate(frameUrl(frame, node.theme))
     }
     fileRef.current = sig
   }, [frame?.kind, frame?.file])
@@ -202,7 +212,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   useEffect(() => {
     if ((node.nav ?? 0) === navRef.current) return
     navRef.current = node.nav ?? 0
-    if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
+    if (frame) navigate(frameUrl(frame, node.theme))
   }, [node.nav])
 
   // Reload the frame, assigning the fresh URL SYNCHRONOUSLY so the live iframe's src is current the
@@ -215,8 +225,8 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     reloadFrame(node.key, automatic)
     const after = useStore.getState().nodes.find((x) => x.key === node.key)
     const f = useStore.getState().frameFor(node)
-    if (after && f && iframeRef.current) {
-      iframeRef.current.src = frameUrl(f, node.theme)
+    if (after && f) {
+      navigate(frameUrl(f, node.theme))
       navRef.current = after.nav ?? 0
     }
   }
@@ -231,14 +241,16 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   // auto-renavigates ONCE on a fresh rev; a second silence stays 'loading' (never a red error card).
   // node.nav is a dep so a fresh navigation restarts the full budget; readyRetried flips true on the
   // retry and bounds it to exactly one.
+  // The budget counts from ADMISSION (a queued frame is not silent). The retried document keeps its
+  // boot slot - its boot is still running - and gives it back after a second silence.
   useEffect(() => {
-    if (!shouldArmReadyWatch(node, !!frame)) return
-    const t = setTimeout(() => reloadRef.current(true), 10_000)
+    if (!admitted || node.status !== 'loading' || !frame || node.missing) return
+    const t = setTimeout(() => { if (shouldArmReadyWatch(node, true)) reloadRef.current(true); else release(node.key) }, 10_000)
     return () => clearTimeout(t)
     // depend on the frame's stable SIGNATURE, not the manifest object - that object is replaced on
     // every manifest reconcile, so depending on it would reset the budget on unrelated frames during
     // heavy Live Jam churn and starve the retry. kind/file still re-arm on a real file swap.
-  }, [node.status, node.readyRetried, node.nav, node.key, node.missing, frame?.kind, frame?.file])
+  }, [admitted, node.status, node.readyRetried, node.nav, node.key, node.missing, frame?.kind, frame?.file])
 
   const drag = (e: React.PointerEvent, mode: 'move' | 'e' | 's' | 'se') => {
     e.stopPropagation()
@@ -268,8 +280,9 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     const begin = () => {
       if (gesturing) return
       gesturing = true
-      world.classList.add('sh-gesturing')   // drops iframe pointer-events (sh-camera is NOT set, so no cover)
+      world.classList.add('sh-gesturing')   // drops iframe pointer-events
       setGesture(true)
+      if (mode !== 'move') { resizing.current = true; wake(node.key, iframeRef.current); setResizeTick((t) => t + 1) }   // awake before the first resized paint, for the whole resize
     }
     const MOVE_THRESHOLD = 3   // px in screen space before a press counts as a drag
 
@@ -297,6 +310,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       try { el.releasePointerCapture(e.pointerId) } catch { /* already released */ }
       world.classList.remove('sh-gesturing')
       setGesture(false)
+      if (resizing.current) { resizing.current = false; setResizeTick((t) => t + 1) }   // settle, then sleep again
       el.removeEventListener('pointermove', onMove)
       el.removeEventListener('pointerup', done)
       el.removeEventListener('pointercancel', done)
@@ -346,12 +360,15 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       className={`sh-node${selected ? ' sel' : ''}${interact ? ' interact' : ''}${working ? ' working' : ''}`}
       data-theme={node.theme}
       style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER, zIndex: hostsCard ? 30 : undefined,
+        // the sticky column's width (spec 18): the docked comment card clears it on the left
+        ...(notes.length ? { ['--sh-note-w' as string]: `${Math.max(...notes.map((n) => (n.kind === 'scene' ? 380 : 260)))}px` } : {}),
         // phase every working animation by when THIS frame's job started - parallel
         // frames pulsing in sync would read as one fake choreography
         ...(working ? { ['--mv-w0' as string]: `${-(Date.now() - (workingSince ?? Date.now()))}ms` } : {}) }}
       data-node={node.key}
     >
       {working && <WorkShimmer belowBadge={!!frame.variantGroup} />}
+      <Stickies nodeKey={node.key} frameId={frame.id} notes={notes} underBadge={!!frame.variantGroup} />
       {frame.variantGroup && (
         <div className="sh-vbadge sh-no-pan" title={`${frame.variantGroup} · variant ${frame.variant?.toUpperCase()} - click to select`}
           onPointerDown={(e) => e.stopPropagation()}
@@ -398,18 +415,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         <iframe
           ref={bindIframe}
           className="sh-live"
-          src={initialSrc.current ?? frameUrl(frame, node.theme)}
+          src={src}
           title={frame.id}
           onLoad={registerWin}
           style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
         />
-        {/* Lean facade: a DOM-snapshot (static html, 0 JS) covering the live iframe only while
-            the canvas is gesturing (CSS), so a heavy frame never flashes white mid-transform and the
-            device sweep reflows correctly. sandbox WITHOUT allow-scripts = no JS runs; allow-same-origin
-            so fonts/assets resolve and the shell can flip its theme + restore scroll. Never registered,
-            never messaged, pointer-events:none - it is NOT the live iframe (role: .sh-lean).
-            Rendered in dev AND publish (runtime client-side capture; frames are same-origin in both). */}
-        <iframe ref={bindLean} className="sh-lean" sandbox="allow-same-origin" title="" aria-hidden tabIndex={-1} />
         {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
             need the mouse INSIDE the frame for hover highlights, so it steps aside
             (drag still works via the header) */}

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

@@ -0,0 +1,284 @@
+/**
+ * Sticky notes (spec 18): the yellow column left of a frame - the scene's note (when this node
+ * hosts it) above the frame's own. Shell DOM, never inside the iframe: sleep, bakes and the frame
+ * document are untouched. Markdown through the content package's renderer (the Md block's link
+ * and image policy, raw HTML inert); a ```mermaid fence renders hand-drawn on demand.
+ *
+ * Fold: the dog-ear at the column's top-right corner folds the whole column down to that corner
+ * (scale + fade toward it); the corner stays as the tab that unfolds it. Per viewer, in
+ * localStorage - never in the board file.
+ *
+ * Comments: in comment mode a click on a note element stages a draft on the node, anchored like
+ * a frame element (notes.ts builds the bundle; the CommentLayer resolves it here in the shell).
+ * Links: `goto:` navigates through the one goto path; in comment mode a click picks, never
+ * navigates (the bridge rule).
+ */
+import { memo, useEffect, useMemo, useRef } from 'react'
+import { renderMarkdown, sanitizeMarkdownHtml } from '../../content/md.ts'
+import { cleanSource, guardDiagramSource, sanitizeSvg } from '../../content/diagram.tsx'
+import { useComments } from '../comments-store.ts'
+import { goTo } from '../goto.ts'
+import { NOTE_W, SCENE_NOTE_W, noteAnchor, noteVisible, useNotes, type NoteKind } from '../notes.ts'
+
+export interface NoteSpec { kind: NoteKind; id: string; text: string }
+
+/** Diagram text only: the sketched look is the diagram's, prose stays in the shell font. */
+const HAND_FONT = `"Segoe Print", "Bradley Hand", "Chalkboard SE", "Comic Sans MS", "Comic Neue", cursive`
+/** Yellow paper for the hand-drawn look - the same values the sheet paints the sticky with. */
+const PAPER = { bg: '#fff3a3', ink: '#2b2500', line: '#6b5a00', soft: '#ffe680', pale: '#fffbdc', hatch: '#f0cc4e' }
+const THEME_VARS = {
+  background: PAPER.bg, fontFamily: HAND_FONT, fontSize: '17px',
+  primaryColor: PAPER.soft, primaryTextColor: PAPER.ink, primaryBorderColor: PAPER.line,
+  secondaryColor: PAPER.pale, secondaryTextColor: PAPER.ink, secondaryBorderColor: PAPER.line,
+  tertiaryColor: PAPER.pale, tertiaryTextColor: PAPER.ink, tertiaryBorderColor: PAPER.line,
+  lineColor: PAPER.line, textColor: PAPER.ink, mainBkg: PAPER.soft, nodeBorder: PAPER.line,
+  clusterBkg: PAPER.pale, clusterBorder: PAPER.line, titleColor: PAPER.ink,
+  edgeLabelBackground: PAPER.bg, noteBkgColor: PAPER.soft, noteTextColor: PAPER.ink, noteBorderColor: PAPER.line,
+  actorBkg: PAPER.soft, actorBorder: PAPER.line, actorTextColor: PAPER.ink, signalColor: PAPER.line, signalTextColor: PAPER.ink,
+  labelBoxBkgColor: PAPER.pale, labelBoxBorderColor: PAPER.line, labelTextColor: PAPER.ink, loopTextColor: PAPER.ink,
+  activationBkgColor: PAPER.pale, activationBorderColor: PAPER.line, sequenceNumberColor: PAPER.ink,
+  pie1: PAPER.soft, pie2: PAPER.pale, pie3: '#f3d96a', pie4: '#e9c94f', pie5: '#fff0b8', pie6: '#e0c04a', pieTitleTextColor: PAPER.ink, pieSectionTextColor: PAPER.ink, pieLegendTextColor: PAPER.ink, pieStrokeColor: PAPER.line, pieOuterStrokeColor: PAPER.line,
+  // every family that would otherwise bring its own rainbow: gantt sections, journey fills,
+  // git branches, the cScale mindmap and timeline use - all the paper's yellows, ink for text
+  sectionBkgColor: PAPER.pale, altSectionBkgColor: PAPER.bg, sectionBkgColor2: PAPER.soft,
+  taskBkgColor: PAPER.soft, taskBorderColor: PAPER.line, taskTextColor: PAPER.ink, taskTextLightColor: PAPER.ink, taskTextOutsideColor: PAPER.ink, taskTextDarkColor: PAPER.ink,
+  activeTaskBkgColor: '#f3d96a', activeTaskBorderColor: PAPER.line, doneTaskBkgColor: PAPER.pale, doneTaskBorderColor: PAPER.line,
+  critBkgColor: '#e9c94f', critBorderColor: PAPER.ink, gridColor: PAPER.line, todayLineColor: PAPER.ink,
+  fillType0: PAPER.soft, fillType1: PAPER.pale, fillType2: '#f3d96a', fillType3: PAPER.soft, fillType4: PAPER.pale, fillType5: '#f3d96a', fillType6: PAPER.soft, fillType7: PAPER.pale,
+  git0: '#e9c94f', git1: '#f3d96a', git2: PAPER.soft, git3: '#e0c04a', git4: PAPER.pale, git5: '#e9c94f', git6: '#f3d96a', git7: PAPER.soft,
+  gitBranchLabel0: PAPER.ink, gitBranchLabel1: PAPER.ink, gitBranchLabel2: PAPER.ink, gitBranchLabel3: PAPER.ink, gitBranchLabel4: PAPER.ink, gitBranchLabel5: PAPER.ink, gitBranchLabel6: PAPER.ink, gitBranchLabel7: PAPER.ink,
+  gitInv0: PAPER.ink, gitInv1: PAPER.ink, gitInv2: PAPER.ink, gitInv3: PAPER.ink, gitInv4: PAPER.ink, gitInv5: PAPER.ink, gitInv6: PAPER.ink, gitInv7: PAPER.ink,
+  commitLabelColor: PAPER.ink, commitLabelBackground: PAPER.bg, tagLabelColor: PAPER.ink, tagLabelBackground: PAPER.soft, tagLabelBorder: PAPER.line,
+  ...Object.fromEntries([...Array(12)].flatMap((_, i) => [[`cScale${i}`, [PAPER.soft, '#f3d96a', PAPER.pale, '#e9c94f'][i % 4]], [`cScaleLabel${i}`, PAPER.ink], [`cScalePeer${i}`, PAPER.line]])),
+  quadrant1Fill: PAPER.soft, quadrant2Fill: PAPER.pale, quadrant3Fill: PAPER.pale, quadrant4Fill: PAPER.soft,
+  quadrant1TextFill: PAPER.ink, quadrant2TextFill: PAPER.ink, quadrant3TextFill: PAPER.ink, quadrant4TextFill: PAPER.ink,
+  quadrantPointFill: PAPER.ink, quadrantPointTextFill: PAPER.ink, quadrantXAxisTextFill: PAPER.ink, quadrantYAxisTextFill: PAPER.ink,
+  quadrantInternalBorderStrokeFill: PAPER.line, quadrantExternalBorderStrokeFill: PAPER.line, quadrantTitleFill: PAPER.ink,
+  attributeBackgroundColorOdd: PAPER.pale, attributeBackgroundColorEven: PAPER.bg,
+}
+let diagramSeq = 0
+
+/** A sticky is one colour of paper. Whatever a diagram family brings that the theme variables
+ *  did not reach (journey actor dots, ER marker circles, a white attribute row, block fills) is
+ *  mapped onto the palette AFTER render, by computed colour: white and light fills become paper,
+ *  dark fills become ink, strokes likewise. Text is never touched (its fill is set above). */
+const PALETTE = new Set([PAPER.bg, PAPER.ink, PAPER.line, PAPER.soft, PAPER.pale, PAPER.hatch, '#f3d96a', '#e9c94f', '#e0c04a', '#fff0b8', '#a88f2a'].map((c) => c.toLowerCase()))
+const hex = (rgb: string): string | null => {
+  const m = /^rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)$/.exec(rgb)
+  if (!m || (m[4] !== undefined && Number(m[4]) === 0)) return null
+  return '#' + [m[1], m[2], m[3]].map((n) => Number(n).toString(16).padStart(2, '0')).join('')
+}
+const luminance = (h: string) => { const n = parseInt(h.slice(1), 16); return (0.2126 * (n >> 16) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255 }
+function inkPalette(svg: SVGSVGElement) {
+  for (const el of svg.querySelectorAll('path, rect, circle, ellipse, polygon, polyline, line') as NodeListOf<SVGElement>) {
+    const cs = getComputedStyle(el)
+    const fill = hex(cs.fill), stroke = hex(cs.stroke)
+    if (fill && !PALETTE.has(fill)) el.style.setProperty('fill', luminance(fill) > 0.55 ? (fill === '#ffffff' ? PAPER.pale : PAPER.soft) : PAPER.line, 'important')
+    // a LIGHT stroke is a hachure line or a faint grid (rough draws a white fill as white
+    // hatching): it becomes the hatch yellow; a mid stroke the line brown; a dark one the ink
+    if (stroke && !PALETTE.has(stroke)) el.style.setProperty('stroke', luminance(stroke) > 0.7 ? PAPER.hatch : luminance(stroke) > 0.35 ? PAPER.line : PAPER.ink, 'important')
+  }
+}
+
+/** One look for every diagram type. mermaid's hand-drawn look (rough.js) reaches flowchart,
+ *  state, class, ER and block natively; sequence actors, journey and timeline boxes, mindmap
+ *  nodes, quadrants, git commits, pie slices and legends come out as plain rects, circles and
+ *  paths. Every visible one of those that mermaid did not already sketch is redrawn here with the
+ *  same rough.js recipe the flowchart nodes got - hachured fill, sketched border - in the paper's
+ *  colours, the plain shape kept underneath as a flat backing. Seeded per shape, so a re-render
+ *  of the same note draws the same lines. */
+const FILLS = ['hachure', 'cross-hatch', 'dots', 'zigzag-line', 'dashed'] as const
+function sketchShapes(svg: SVGSVGElement, rough: any) {
+  const rc = rough.svg(svg)
+  let seed = 7, slice = 0
+  const visible = (el: Element) => { const f = getComputedStyle(el).fill; return f !== 'none' && !/rgba\(\d+, \d+, \d+, 0\)/.test(f) }
+  const skip = (el: Element) =>
+    (el as any).__sketched
+    || !!el.closest('.label, foreignObject, marker, defs, .face, .legend-text')
+    || sketchedByMermaid(el)
+    || (el.nextElementSibling?.tagName === 'g' && !!el.nextElementSibling.querySelector('path'))   // mermaid's own rough
+    || !visible(el)
+  // the unified renderer's nodes carry `g.node` / `g.rough-node`, but the class is a promise, not
+  // a fact: a mindmap node wears `rough-node` around a plain path. Trust the evidence - rough
+  // output is classless paths, direct or inside the label container
+  const sketchedByMermaid = (el: Element) => {
+    const node = el.parentElement?.closest('g.node, g.rough-node, g.cluster')
+    if (!node) return false
+    const plain = (e: Element) => !(e.getAttribute('class') ?? '').trim()   // an EMPTY class attribute is no class
+    for (const c of node.children) {
+      if (c.tagName === 'path' && plain(c)) return true
+      if (c.tagName === 'g' && (plain(c) || /\b(basic|label-container)\b/.test(c.getAttribute('class') ?? '')) && [...c.children].some((cc) => cc.tagName === 'path' && plain(cc))) return true
+    }
+    return false
+  }
+  const place = (el: Element, g: SVGGElement, backing: string) => {
+    // rough draws with presentation attributes; inside a mermaid node group the diagram's own
+    // stylesheet (`.node path { fill; stroke }`) would beat them - pin them as inline styles
+    for (const path of g.querySelectorAll('path')) {
+      path.style.fill = path.getAttribute('fill') ?? 'none'
+      path.style.stroke = path.getAttribute('stroke') ?? 'none'
+      path.style.strokeWidth = path.getAttribute('stroke-width') ?? '1'
+    }
+    el.setAttribute('style', `fill: ${backing}; stroke: none;`)
+    ;(el as any).__sketched = true
+    el.after(g)
+  }
+  const recipe = (extra: Record<string, unknown> = {}) => ({
+    seed: seed++, roughness: 0.7, bowing: 0.6, stroke: PAPER.line, strokeWidth: 1.6,
+    fill: PAPER.hatch, fillStyle: 'hachure', hachureAngle: 120, hachureGap: 4, fillWeight: 1.2, ...extra,
+  })
+  for (const r of [...svg.querySelectorAll('rect')]) {
+    if (skip(r)) continue
+    const w = Number(r.getAttribute('width') ?? 0), h = Number(r.getAttribute('height') ?? 0)
+    if (!(w > 6 && h > 6)) continue
+    const x = Number(r.getAttribute('x') ?? 0), y = Number(r.getAttribute('y') ?? 0)
+    // a quadrant is a field, not a box: the sketched border only, a flat pale backing
+    const field = !!r.closest('.quadrants') || w * h > 40_000
+    place(r, rc.rectangle(x, y, w, h, recipe(field ? { fill: undefined, fillStyle: 'solid' } : {})), field ? PAPER.pale : PAPER.soft)
+  }
+  for (const c of [...svg.querySelectorAll('circle')]) {
+    if (skip(c)) continue
+    const d = 2 * Number(c.getAttribute('r') ?? 0)
+    if (d < 6) continue
+    place(c, rc.circle(Number(c.getAttribute('cx') ?? 0), Number(c.getAttribute('cy') ?? 0), d, recipe(d < 30 ? { fillStyle: 'solid', fill: PAPER.hatch } : {})), PAPER.soft)
+  }
+  for (const e of [...svg.querySelectorAll('ellipse')]) {
+    if (skip(e)) continue
+    place(e, rc.ellipse(Number(e.getAttribute('cx') ?? 0), Number(e.getAttribute('cy') ?? 0), 2 * Number(e.getAttribute('rx') ?? 0), 2 * Number(e.getAttribute('ry') ?? 0), recipe()), PAPER.soft)
+  }
+  // pie slices: one fill style per slice, so the wedges read apart in one colour of ink;
+  // mindmap and timeline draw their boxes as paths (node-bkg) - the same box recipe
+  for (const p of [...svg.querySelectorAll('path.pieCircle, path.node-bkg')]) {
+    if (skip(p)) continue
+    const d = p.getAttribute('d')
+    if (!d) continue
+    const pie = p.classList.contains('pieCircle')
+    place(p, rc.path(d, recipe(pie ? { fillStyle: FILLS[slice++ % FILLS.length], hachureGap: 5, fillWeight: 1 } : {})), PAPER.soft)
+  }
+}
+
+/** Render every ```mermaid fence in a sticky body: hand-drawn, strict, sanitized. The pre stays
+ *  mounted through an error (the message replaces the code), so a healed edit heals in place. */
+async function renderDiagrams(body: HTMLElement, alive: () => boolean) {
+  const fences = [...body.querySelectorAll('pre > code.language-mermaid')] as HTMLElement[]
+  if (!fences.length) return
+  const [{ default: mermaid }, { default: rough }] = await Promise.all([import('mermaid'), import('roughjs')])
+  if (!alive()) return
+  mermaid.initialize({
+    startOnLoad: false, securityLevel: 'strict', theme: 'base', look: 'handDrawn', themeVariables: THEME_VARS, fontFamily: HAND_FONT,
+    // legible at sticky size. Flowcharts get rough.js boxes and HTML labels; every other type
+    // draws plain SVG text in a handwriting face that has no bold - so SVG text is inked with a
+    // thin stroke (paint-order keeps the fill on top), lines and boxes are darker and thicker.
+    themeCSS: [
+      `.nodeLabel, .edgeLabel, .label { font-weight: 700 !important; letter-spacing: .01em }`,
+      `text, tspan { font-weight: 700 !important; fill: ${PAPER.ink}; stroke: ${PAPER.ink}; stroke-width: .45px; paint-order: stroke fill; letter-spacing: .01em }`,
+      `.edgePath path, .flowchart-link { stroke-width: 2px } .node path, .node rect { stroke-width: 1.6px }`,
+      // sequence: actor boxes, lifelines, messages and arrowheads in the paper's ink
+      `.actor-line { stroke: ${PAPER.line} !important; stroke-width: 1.4px !important }`,
+      `.messageLine0, .messageLine1 { stroke: ${PAPER.ink} !important; stroke-width: 1.8px !important } #arrowhead path, .arrowheadPath { fill: ${PAPER.ink} !important; stroke: ${PAPER.ink} !important }`,
+      `.messageText, .actor > tspan, text.actor { fill: ${PAPER.ink} !important }`,
+      `.loopLine { stroke: ${PAPER.line} !important } .labelBox, .loopText, .note { stroke: ${PAPER.line} }`,
+      `.er.attributeBoxOdd { fill: ${PAPER.pale} !important; stroke: ${PAPER.line} } .er.attributeBoxEven { fill: ${PAPER.bg} !important; stroke: ${PAPER.line} } .er.relationshipLine { stroke: ${PAPER.ink} !important }`,
+      `.section0, .section2, .section4 { fill: ${PAPER.pale} } .section1, .section3 { fill: ${PAPER.bg} } .grid .tick line { stroke: ${PAPER.line} } .today { stroke: ${PAPER.ink} }`,
+      `.commit-label, .branchLabel text { fill: ${PAPER.ink} !important } .commit-label-bkg { fill: ${PAPER.bg} !important } .commit-arrow, .arrow { stroke: ${PAPER.ink} !important }`,
+      `.mindmap-node > path, .mindmap-node rect { stroke: ${PAPER.line}; stroke-width: 1.4px } .edge { stroke: ${PAPER.line}; stroke-width: 2px }`,
+      // state / class / er: the same ink
+      `.statediagram-state rect, .classGroup rect, .er.entityBox { stroke: ${PAPER.line}; stroke-width: 1.6px; fill: ${PAPER.soft} } .transition, .relation, .er.relationshipLine { stroke: ${PAPER.ink} !important; stroke-width: 1.8px !important }`,
+    ].join(' '),
+    flowchart: { padding: 10, nodeSpacing: 32, rankSpacing: 36 },
+    // one actor row (the mirrored bottom row is noise at note size), roomier boxes, bigger text
+    sequence: { mirrorActors: false, actorFontSize: 18, actorFontWeight: 700, messageFontSize: 17, messageFontWeight: 700, noteFontSize: 16, width: 96, height: 50, actorMargin: 26, boxMargin: 8, messageMargin: 30, diagramMarginX: 6, diagramMarginY: 6, wrap: true, bottomMarginAdj: 4 },
+    // the wide-by-nature types drawn AT the note's width instead of shrunk into it
+    gantt: { useWidth: 380, fontSize: 13, sectionFontSize: 13, barHeight: 22, barGap: 6, topPadding: 44, leftPadding: 64, rightPadding: 12, gridLineStartPadding: 20, numberSectionStyles: 2 },
+    journey: { width: 118, height: 40, leftMargin: 56, taskMargin: 12, taskFontSize: 13, diagramMarginX: 8, diagramMarginY: 8, boxMargin: 6, actorColours: [PAPER.line, PAPER.ink, '#a88f2a', '#e9c94f'] },
+    timeline: { disableMulticolor: true, padding: 10, width: 84, height: 40, leftMargin: 40, taskMargin: 8, diagramMarginX: 8, diagramMarginY: 8 },
+    quadrantChart: { chartWidth: 360, chartHeight: 360, titleFontSize: 16, quadrantLabelFontSize: 14, pointLabelFontSize: 13, xAxisLabelFontSize: 13, yAxisLabelFontSize: 13, pointRadius: 5 },
+    mindmap: { padding: 10, maxNodeWidth: 150 },
+    er: { minEntityWidth: 90, minEntityHeight: 50, entityPadding: 12, fontSize: 14, diagramPadding: 10 },
+    gitGraph: { showBranches: true, rotateCommitLabel: false, nodeLabel: { width: 60 } } as any,
+  })
+  for (const code of fences) {
+    const pre = code.parentElement!
+    const src = cleanSource(code.textContent ?? '')   // front matter and %%{init}%% directives never reach mermaid (the Diagram rule)
+    const host = document.createElement('div')
+    host.className = 'sh-sticky-diagram'
+    try {
+      guardDiagramSource(src)   // the zero-external-request boundary (the Diagram block's)
+      const { svg } = await mermaid.render(`sh-note-d${++diagramSeq}`, src)
+      if (!alive()) return
+      host.innerHTML = sanitizeSvg(svg)
+      const el = host.querySelector('svg')
+      // never larger than drawn: a family without mermaid's max-width (block) would upscale to
+      // the note's width and its hatching with it - the viewBox width is the ceiling
+      const vb = el?.viewBox?.baseVal
+      if (el && vb && vb.width > 0 && !el.style.maxWidth) el.style.maxWidth = `${Math.ceil(vb.width)}px`
+      pre.replaceWith(host)
+      if (el) { sketchShapes(el, rough); inkPalette(el) }   // computed colours need the svg in the document
+    } catch (e) {
+      if (!alive()) return
+      pre.classList.add('err')
+      code.textContent = `diagram: ${String((e as Error)?.message ?? e).split('\n')[0]}`
+    }
+  }
+}
+
+function StickyBody({ text, kind, nodeKey, frameId }: { text: string; kind: NoteKind; nodeKey: string; frameId: string }) {
+  const ref = useRef<HTMLDivElement>(null)
+  const html = useMemo(() => sanitizeMarkdownHtml(renderMarkdown(text)), [text])
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    let live = true
+    el.innerHTML = html
+    void renderDiagrams(el, () => live && ref.current === el)
+    return () => { live = false }
+  }, [html])
+
+  const onClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    const root = ref.current
+    const target = e.target instanceof Element ? e.target : null
+    if (!root || !target) return
+    const c = useComments.getState()
+    if (c.commentMode) {
+      // comment mode owns every click: pick the element, exactly like a frame pick
+      e.preventDefault(); e.stopPropagation()
+      // the picked element is the innermost element under the pointer; a click in the body's
+      // own padding picks the first block instead of the whole note
+      const pick = target === root ? root.firstElementChild : target
+      if (!pick) return
+      const nodeEl = root.closest('.sh-node') as HTMLElement | null
+      const bodyEl = nodeEl?.querySelector('.cm-layer') as HTMLElement | null
+      if (!nodeEl || !bodyEl) return
+      const origin = bodyEl.getBoundingClientRect()
+      const s = origin.width ? origin.width / nodeEl.offsetWidth : 1     // on-screen px per world px
+      const toBody = (r: DOMRect) => ({ x: (r.left - origin.left) / s, y: (r.top - origin.top) / s, w: r.width / s, h: r.height / s })
+      if (c.active) c.setActive(null)
+      c.setDraft({ nodeKey, frame: frameId, anchor: noteAnchor(pick, root, kind, e, toBody) })
+      return
+    }
+    const link = target.closest('a[data-goto]')
+    if (link) { e.preventDefault(); e.stopPropagation(); goTo(link.getAttribute('data-goto') ?? '') }
+  }
+  return <div ref={ref} className="sh-sticky-body" onClick={onClick} />
+}
+
+/** The column for one node. `underBadge`: a variant badge owns the top of the gutter. */
+export const Stickies = memo(function Stickies({ nodeKey, frameId, notes, underBadge }: { nodeKey: string; frameId: string; notes: NoteSpec[]; underBadge: boolean }) {
+  const ids = notes.map((n) => n.id)
+  const on = useNotes((s) => noteVisible(s, ids))
+  if (!notes.length) return null
+  const width = Math.max(...notes.map((n) => (n.kind === 'scene' ? SCENE_NOTE_W : NOTE_W)))
+  return (
+    <div className={`sh-notes${on ? '' : ' off'}${underBadge ? ' below-vbadge' : ''}`} data-node-notes={nodeKey} style={{ width }}>
+      <button className="sh-notes-fold sh-no-pan" type="button" aria-label={on ? 'hide notes' : 'show notes'} title={on ? 'hide notes (N: all)' : 'show notes (N: all)'}
+        onPointerDown={(e) => e.stopPropagation()}
+        onClick={(e) => { e.stopPropagation(); useNotes.getState().toggle(ids) }} />
+      {notes.map((n) => (
+        <div key={n.id} className="sh-sticky sh-no-pan" data-sticky={n.kind} data-note={n.id} style={{ width: n.kind === 'scene' ? SCENE_NOTE_W : NOTE_W }}
+          onPointerDown={(e) => e.stopPropagation()} onDoubleClick={(e) => e.stopPropagation()}>
+          <StickyBody text={n.text} kind={n.kind} nodeKey={nodeKey} frameId={frameId} />
+        </div>
+      ))}
+    </div>
+  )
+})