@marver-design/marver 0.17.0 → 0.19.0

package/src/client/shell/canvas/admission.ts

@@ -0,0 +1,70 @@
+/**
+ * Frame admission: how many iframes boot at once.
+ *
+ * Every frame on a board is a document booting on the ONE renderer main thread (~400 ms each for a
+ * lo-fi React frame), and a batch that starts together finishes together: 64 started at once, the
+ * first is ready at 25.6 s and the last at 26.0 s - the board is blank until the end. Admitted a few
+ * at a time, the first is ready at 1.8 s and the board fills in view order for the same total
+ * (research/hifi/bootscale.ts). The ready watchdog counts from admission, not from mount, so a
+ * queued frame is never mistaken for a stalled one.
+ *
+ * A new batch admits ONE frame first (the quickest first content: one boot alone is ~550 ms, four
+ * together ~1.8 s), then up to SLOTS at a time. Pure, apart from its timing: a board that mounts
+ * registers every node, the shell fits the camera (App.tsx, a few tens of ms later), then the first
+ * pump ranks them (visible first, nearest the centre of the canvas first); a freed slot pumps on
+ * the next microtask, ranking again by the view of that moment.
+ */
+export const SLOTS = 4
+/** A new batch's head start: one frame alone until it is done, or until this long - one stalled
+ *  first frame must not hold the whole board. */
+export const HEAD_MS = 2000
+let primed = false   // the batch may use every slot
+let gen = 0          // the batch: a pump scheduled for an earlier one is void
+let timer: ReturnType<typeof setTimeout> | undefined
+
+export interface Admission { key: string; rank: () => number; start: () => void }
+
+const waiting = new Map<string, Admission>()
+const active = new Set<string>()
+let scheduled = false
+
+/** Ask for a slot. Starts once the view has settled (SETTLE ms) when one is free; else queued by rank. */
+export function admit(a: Admission): void {
+  if (active.has(a.key)) return
+  if (!waiting.size && !active.size) {   // a new batch
+    primed = false; gen++; scheduled = false; clearTimeout(timer)
+    timer = setTimeout(() => { primed = true; schedule(0) }, HEAD_MS)
+  }
+  waiting.set(a.key, a)
+  schedule(SETTLE)
+}
+const SETTLE = 350   // the board fit animates ~250 ms from 60 ms after mount: rank the first pick on the settled view
+
+/** The frame is done booting (ready, error, gone, or its watchdog took over): free the slot, or
+ *  leave the queue if it never started. */
+export function release(key: string): void {
+  waiting.delete(key)
+  if (active.delete(key)) { primed = true; schedule(0) }
+}
+
+function schedule(ms: number): void {
+  if (scheduled) return
+  scheduled = true
+  const g = gen, run = () => { if (g === gen) pump() }
+  if (ms) setTimeout(run, ms); else queueMicrotask(run)
+}
+
+function pump(): void {
+  scheduled = false
+  while (active.size < (primed ? SLOTS : 1) && waiting.size) {
+    let best: Admission | undefined, bestRank = Infinity
+    for (const a of waiting.values()) { const r = a.rank(); if (r < bestRank || !best) { best = a; bestRank = r } }
+    waiting.delete(best!.key)
+    active.add(best!.key)
+    ;(globalThis as { __mvAdmitted?: string[] }).__mvAdmitted?.push(best!.key)   // diagnostic: the order, when a probe asks for it
+    best!.start()
+  }
+}
+
+/** For tests: nothing queued, nothing active. */
+export function resetAdmission(): void { waiting.clear(); active.clear(); primed = false; scheduled = false; gen++; clearTimeout(timer) }

package/src/client/shell/canvas/sleep.ts

@@ -0,0 +1,194 @@
+/**
+ * Sleep - a frame at rest, in place (spec 16).
+ *
+ * A resting frame is its own LIVE document. Nothing is copied, pictured or swapped, so the moment
+ * the human interacts, comments or lasers, they are already looking at the thing itself: no line
+ * break, no spacing, no pixel can move. Sleep changes PAINT only:
+ *
+ *   - CSS animations pause (`animation-play-state: paused`);
+ *   - every `backdrop-filter` element - the one effect that reads back what is behind it on every
+ *     composited frame, and the reason a glass design checkerboards at scale - gets the compositor's
+ *     own filtered backdrop as a static texture under its own background layers, computed and
+ *     certified by the dev server in headless Chrome (src/server/bake.ts); the rule itself is
+ *     src/shared/sleep-rule.ts, the same one the compiler certified.
+ *
+ * A frame with no such element - markdown, images, slides, lo-fi - never talks to the server:
+ * its sleep is the animation pause. Frames are asked in one batch per tick; the server answers from
+ * its disk cache (keyed by frame, theme, size and source generation) or compiles. Textures are
+ * decoded BEFORE the override is installed, so sleep is one paint. Without textures - no compiler
+ * (a published canvas), a compile that failed, a texture that does not decode - the frame sleeps
+ * with the pause alone and its glass stays live: never an effect layer without its texture.
+ *
+ * Safety: the override is all or nothing - every target's selector must resolve to an element whose
+ * border box is the one the server measured (half a pixel) and whose filter is still the one baked, or
+ * the frame stays live. Wake restores the live effects under `transition: none` (an authored
+ * transition on backdrop-filter, filter or background must not animate out of the sleep, nor into
+ * it), then removes the <style> and the attributes.
+ */
+import { ROUTE } from '../../const.ts'
+import { BAKES, PUBLISHED } from '../store.ts'
+import { readOwn, sleepRule } from '../../../shared/sleep-rule.ts'
+
+export interface SleepKey { frame: string; theme: string; w: number; h: number }
+interface Target { sel: string; rect: { x: number; y: number; w: number; h: number }; filter: string; level: number; texture: string; verified: boolean }
+type Answer = { ok: true; targets: Target[] } | { ok: false; error: string }
+
+const STYLE_ID = 'mv-sleep'
+/** How far (CSS px) any EDGE of an element's border box may sit from the one the compiler measured.
+ *  Headless and headed Chrome shape text a few hundredths of a pixel apart (a 784 px pill measures
+ *  784.09 in a window, 784.125 in the compiler), which is invisible under a texture stretched to
+ *  the box; a different wrap, size or place is a whole line or more and still refuses the frame. */
+const TOL = 0.5
+/** `?awake=1` keeps every frame live - the diagnostic switch the identity probes compare against. */
+const AWAKE = new URLSearchParams(location.search).get('awake') === '1'
+const PAUSE = `*,*::before,*::after{animation-play-state:paused!important}`
+const csrf = () => document.cookie.match(/(?:^|; )mv_c=([^;]+)/)?.[1] ?? ''
+const keyOf = (k: SleepKey) => `${k.frame}|${k.theme}|${Math.round(k.w)}|${Math.round(k.h)}`
+
+/** What a node's DOCUMENT is asleep under, published only once its override is INSTALLED. */
+const asleep = new Map<string, { key: string; doc: Document }>()
+/** The node's current request, so a stale answer (a newer sleep, a wake in between) is dropped. */
+const pending = new Map<string, number>()
+let seq = 0
+/** Nodes with one retry of a failed compile in flight. */
+const retried = new Set<string>()
+const RETRY_MS = 4000
+
+/** Does this document have anything to compile? Cheap: one computed style per element. */
+export function hasEffects(doc: Document): boolean {
+  for (const el of doc.querySelectorAll('*')) {
+    const cs = doc.defaultView!.getComputedStyle(el)
+    const bf = cs.backdropFilter || (cs as unknown as { webkitBackdropFilter?: string }).webkitBackdropFilter
+    if (bf && bf !== 'none') return true
+  }
+  return false
+}
+
+/** A published canvas has no compiler: its textures were compiled at build time against the very
+ *  document it serves, and ship as one static index (publish-bakes.ts), read once. */
+let published: Promise<Record<string, Answer>> | undefined
+const staticAnswers = () => (published ??= (BAKES ? fetch(`${ROUTE}/bakes/${BAKES}/index.json`).then((r) => (r.ok ? r.json() : {})) : Promise.resolve({}))
+  .then((j: { gen?: number; answers?: Record<string, Answer> }) => (j.gen === BAKES && j.answers) || {}).catch((): Record<string, Answer> => ({})))
+
+// ---- one batch per tick: every frame that decides to sleep in the same moment shares a browser
+const queue: { key: SleepKey; resolve: (a: Answer) => void }[] = []
+let flush: ReturnType<typeof setTimeout> | undefined
+function ask(key: SleepKey): Promise<Answer> {
+  return new Promise((resolve) => {
+    queue.push({ key, resolve })
+    clearTimeout(flush)
+    flush = setTimeout(async () => {
+      const batch = queue.splice(0)
+      // one ask per key; every waiter for that key gets the same answer
+      const byKey = new Map<string, { key: SleepKey; waiters: ((a: Answer) => void)[] }>()
+      for (const q of batch) { const kk = keyOf(q.key); const e = byKey.get(kk); if (e) e.waiters.push(q.resolve); else byKey.set(kk, { key: q.key, waiters: [q.resolve] }) }
+      const asks = [...byKey.values()].map((e) => ({ frame: e.key.frame, theme: e.key.theme, w: Math.round(e.key.w), h: Math.round(e.key.h) }))
+      let data: { answers?: (Answer & SleepKey)[] } | null = null
+      const index = PUBLISHED ? await staticAnswers() : null
+      if (!index) {
+        try {
+          const r = await fetch(`${ROUTE}/api/bakes`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify({ asks }) })
+          data = r.ok ? await r.json() : null
+        } catch { data = null }
+      }
+      for (const e of byKey.values()) {
+        const a = index ? index[keyOf(e.key)] : data?.answers?.find((x) => keyOf(x) === keyOf(e.key))
+        const answer: Answer = a ? (a.ok ? { ok: true, targets: a.targets } : { ok: false, error: a.error }) : { ok: false, error: 'no answer' }
+        for (const w of e.waiters) w(answer)
+      }
+    }, 40)
+  })
+}
+
+/** Put a node's live document to sleep under `key`. Resolves once the override is installed (or
+ *  the document was found to have no effects, or the compile failed and the frame stays live).
+ *  A wake or a newer sleep in the meantime supersedes it. */
+export async function sleep(nodeKey: string, iframe: HTMLIFrameElement, key: SleepKey): Promise<'asleep' | 'live'> {
+  if (AWAKE) return 'live'
+  const k = keyOf(key)
+  const doc = iframe.contentDocument
+  if (!doc?.body) return 'live'
+  const have = asleep.get(nodeKey)
+  if (have && have.key === k && have.doc === doc && doc.getElementById(STYLE_ID)) return 'asleep'
+  const mine = ++seq
+  pending.set(nodeKey, mine)
+  const current = () => pending.get(nodeKey) === mine && iframe.contentDocument === doc
+  // the compiler measured after the frame's fonts; so does the gate below
+  if (doc.fonts) { await doc.fonts.ready; if (!current()) return 'live' }
+  if (!hasEffects(doc)) {
+    // nothing to compile: the pause alone is this frame's sleep
+    if (!current()) return 'live'
+    install(doc, [])
+    asleep.set(nodeKey, { key: k, doc })
+    return 'asleep'
+  }
+  const answer = await ask(key)
+  if (!current()) return 'live'
+  // no compiler (a published canvas, a compile that failed): the pause alone, the glass live -
+  // never an effect layer without its texture
+  let targets = answer.ok ? answer.targets.filter((t) => t.verified && t.texture) : []
+  // decode every texture BEFORE the paint that installs them - one commit, no pop-in; one that
+  // fails to decode (pruned, missing, corrupt) leaves the glass live
+  const decoded = await Promise.all(targets.map((t) => { const im = new Image(); im.src = t.texture; return im.decode().then(() => true, () => false) }))
+  if (!current()) return 'live'
+  if (decoded.some((ok) => !ok)) targets = []
+  // a published document names the generation it was built with: textures dress that build only
+  if (PUBLISHED && targets.length && doc.querySelector('meta[name="mv-bakes"]')?.getAttribute('content') !== String(BAKES)) targets = []
+  if (!install(doc, targets)) return 'live'
+  // a certified sleep is remembered; the pause-only fallback is not, so the next lifecycle event
+  // asks again (a compile the source outran, a server hiccup), and one retry is scheduled now
+  if (targets.length) asleep.set(nodeKey, { key: k, doc })
+  else if (!PUBLISHED && !retried.has(nodeKey)) { retried.add(nodeKey); setTimeout(() => { retried.delete(nodeKey); if (current()) void sleep(nodeKey, iframe, key) }, RETRY_MS) }   // a static miss is final
+  return 'asleep'
+}
+
+/** Wake: paint goes back to the live effects. The document is otherwise untouched. */
+export function wake(nodeKey: string, iframe: HTMLIFrameElement | null): void {
+  pending.delete(nodeKey)
+  asleep.delete(nodeKey)
+  const doc = iframe?.contentDocument
+  const st = doc?.getElementById(STYLE_ID)
+  if (!doc || !st) return
+  const els = [...doc.querySelectorAll<HTMLElement>('[data-mv-sleep]')]
+  still(doc, els, () => st.remove())
+  for (const el of els) el.removeAttribute('data-mv-sleep')
+}
+
+/** Run `change` with no transition able to start on `els`: an INLINE important
+ *  `transition-property: none` (it outranks an authored important transition), the change, one
+ *  forced style recalc - a style change event with nothing to animate - then the authored longhand
+ *  back. Only the longhand is touched: an inline `transition-duration` alone does not serialize
+ *  through the shorthand, and a shorthand round trip would have deleted it. */
+function still(doc: Document, els: HTMLElement[], change: () => void): void {
+  const authored = els.map((el) => [el.style.getPropertyValue('transition-property'), el.style.getPropertyPriority('transition-property')] as const)
+  for (const el of els) el.style.setProperty('transition-property', 'none', 'important')
+  change()
+  void doc.documentElement.offsetWidth
+  els.forEach((el, i) => { const [v, p] = authored[i]; if (v) el.style.setProperty('transition-property', v, p); else el.style.removeProperty('transition-property') })
+}
+
+/** Install the override for the targets. All or nothing: a target whose element is not exactly the
+ *  one the server measured leaves the whole document live. Returns whether it was installed. */
+function install(doc: Document, targets: Target[]): boolean {
+  doc.querySelectorAll('[data-mv-sleep]').forEach((el) => el.removeAttribute('data-mv-sleep'))
+  const rules: string[] = [PAUSE]
+  const els: HTMLElement[] = []
+  for (const [i, t] of targets.entries()) {
+    let el: HTMLElement | null = null
+    try { el = doc.querySelector<HTMLElement>(t.sel) } catch { /* a selector from another document shape */ }
+    if (!el) return false
+    const r = el.getBoundingClientRect()
+    if (Math.abs(r.x - t.rect.x) > TOL || Math.abs(r.y - t.rect.y) > TOL || Math.abs(r.right - t.rect.x - t.rect.w) > TOL || Math.abs(r.bottom - t.rect.y - t.rect.h) > TOL) return false
+    const cs = doc.defaultView!.getComputedStyle(el)
+    if ((cs.backdropFilter || (cs as unknown as { webkitBackdropFilter?: string }).webkitBackdropFilter || 'none') !== t.filter) return false
+    rules.push(sleepRule(`[data-mv-sleep="${i}"]`, readOwn(cs), t.texture))
+    els.push(el)
+  }
+  let st = doc.getElementById(STYLE_ID)
+  if (!st) { st = doc.createElement('style'); st.id = STYLE_ID; (doc.head ?? doc.documentElement).appendChild(st) }
+  const style = st
+  // one paint, and no authored transition (`transition: all` is common on a pill) may animate the
+  // effect out or the texture in
+  still(doc, els, () => { els.forEach((el, i) => el.setAttribute('data-mv-sleep', String(i))); style.textContent = rules.join('\n') })
+  return true
+}

package/src/client/shell/goto.ts

@@ -0,0 +1,72 @@
+/**
+ * `goto:` navigation, one path for every caller: a frame's data-goto (sh:go from the bridge)
+ * and a sticky note's link (shell DOM, spec 18). On this board: select and fit. Elsewhere: follow
+ * the frame home (below). Never edits a board unless no board pins the target.
+ */
+import { boardFrames, fetchBoardNames, useStore } from './store.ts'
+import { canvasCtl } from './canvas/ctl.ts'
+
+/** Navigate to a frame id. `carry` keeps interact mode across the hop (a link inside an
+ *  interacting frame walks a flow - it must not eject you to design mode). */
+export function goTo(target: string, carry = false): void {
+  const s = useStore.getState()
+  const existing = s.nodes.find((n) => n.frame === target && !n.missing)
+  if (existing) {
+    gotoSeq++                                  // a local goto supersedes any cross-board one in flight
+    s.select(existing.key)
+    if (carry) s.setInteract(existing.key)
+    setTimeout(() => canvasCtl.fitNode(existing.key), 50)
+  } else void gotoAcrossBoards(target, carry)
+}
+
+/** 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))
+  }
+}

package/src/client/shell/notes.ts

@@ -0,0 +1,151 @@
+/**
+ * Sticky notes (spec 18): the pure half. Widths the layout reserves, which node hosts a
+ * scene's note, the per-viewer hide state, and the comment anchor a note builds and resolves
+ * in the shell (a note is shell DOM - inspect.js never sees it, so the shell plays its part).
+ * No React, no store import: unit tests read this straight.
+ */
+import { create } from 'zustand'
+
+/** World px. A frame note is a column beside one frame; a scene note is wider, an intro. */
+export const NOTE_W = 260
+export const SCENE_NOTE_W = 380
+/** The gutter between a note and its frame (the variant badge lives in the same gutter). */
+export const NOTE_GAP = 24
+/** Pin and card tint for anchors on a note - the paper's own hue. */
+export const NOTE_HUE = 48
+
+export type NoteKind = 'frame' | 'scene'
+export const noteId = (kind: NoteKind, name: string): string => `${kind}:${name}`
+
+/** The width tidy reserves in front of a node: its own note, and the scene note when this node
+ *  hosts it - one column, so the wider of the two, never the sum. */
+export function noteReserve(frameNote: boolean, sceneNote: boolean): number {
+  const w = Math.max(frameNote ? NOTE_W : 0, sceneNote ? SCENE_NOTE_W : 0)
+  return w ? w + NOTE_GAP : 0
+}
+
+/** The node that shows a scene's note: the scene's first node on the board in reading order -
+ *  smallest y, then x, then original index (the deck rule), missing nodes skipped. Null when the
+ *  scene has no node here. */
+export function sceneNoteHost(
+  nodes: readonly { key: string; frame: string; x: number; y: number; missing?: boolean }[],
+  sceneOf: (frame: string) => string | undefined,
+  scene: string,
+): string | null {
+  let best: { key: string; x: number; y: number; i: number } | null = null
+  nodes.forEach((n, i) => {
+    if (n.missing || sceneOf(n.frame) !== scene) return
+    if (!best || n.y < best.y || (n.y === best.y && (n.x < best.x || (n.x === best.x && i < best.i)))) best = { key: n.key, x: n.x, y: n.y, i }
+  })
+  return best ? (best as { key: string }).key : null
+}
+
+// ---- per-viewer visibility -------------------------------------------------------------
+
+const STORAGE = 'mv-notes'
+interface NotesState {
+  /** the N toggle: false hides every note on the canvas */
+  all: boolean
+  /** note ids folded by their own corner */
+  hidden: string[]
+  /** fold or unfold one column (its ids together) */
+  toggle(ids: string[]): void
+  /** N: any note visible -> hide all; none -> show all (and unfold every column) */
+  toggleAll(anyVisible: boolean): void
+}
+const load = (): { all: boolean; hidden: string[] } => {
+  try {
+    const raw = JSON.parse(localStorage.getItem(STORAGE) ?? 'null')
+    if (raw && typeof raw === 'object') return { all: raw.all !== false, hidden: Array.isArray(raw.hidden) ? raw.hidden.filter((x: unknown) => typeof x === 'string') : [] }
+  } catch { /* storage unavailable or junk: shown by default */ }
+  return { all: true, hidden: [] }
+}
+const save = (s: { all: boolean; hidden: string[] }) => { try { localStorage.setItem(STORAGE, JSON.stringify(s)) } catch { /* private mode */ } }
+
+export const useNotes = create<NotesState>((set, get) => ({
+  ...load(),
+  toggle(ids) {
+    const { all, hidden } = get()
+    const off = !all || ids.some((id) => hidden.includes(id))
+    // unfolding a column while N hid everything shows that column alone: N flips back on and
+    // every OTHER column is folded, so the one asked for is the one that appears
+    const next = off
+      ? { all: true, hidden: all ? hidden.filter((id) => !ids.includes(id)) : [...new Set([...allIds(), ...hidden].filter((id) => !ids.includes(id)))] }
+      : { all, hidden: [...new Set([...hidden, ...ids])] }
+    set(next); save(next)
+  },
+  toggleAll(anyVisible) {
+    const next = anyVisible ? { all: false, hidden: get().hidden } : { all: true, hidden: [] }
+    set(next); save(next)
+  },
+}))
+/** Every note id currently on the canvas - read from the DOM, the one place that knows. */
+const allIds = (): string[] => (typeof document === 'undefined' ? [] : [...document.querySelectorAll('[data-note]')].map((el) => el.getAttribute('data-note')!))
+
+export const noteVisible = (s: { all: boolean; hidden: string[] }, ids: string[]): boolean => s.all && !ids.some((id) => s.hidden.includes(id))
+
+// ---- comment anchors on a note ------------------------------------------------------------
+
+/** The same bundle inspect.js posts for a frame element, plus `note` so the shell resolves it
+ *  itself. `rect` and `pos` are in node-body coordinates (the CommentLayer's), so a pin on a note
+ *  sits at a negative x - left of the frame. */
+export interface NoteAnchor {
+  el: { semantics: { tag: string; quote?: string }; cssPath: string; note: NoteKind; hue: number }
+  pos: { fx: number; fy: number }
+  rect: { x: number; y: number; w: number; h: number }
+}
+
+/** An nth-of-type chain from the sticky body to the element - stable across re-renders of the
+ *  same markdown, honest when it changes (the quote fallback then decides). */
+export function cssPathWithin(el: Element, root: Element): string {
+  const parts: string[] = []
+  let cur: Element | null = el
+  while (cur && cur !== root) {
+    const tag = cur.tagName.toLowerCase()
+    const parent: Element | null = cur.parentElement
+    if (!parent) break
+    const same = [...parent.children].filter((c) => c.tagName === cur!.tagName)
+    parts.unshift(same.length > 1 ? `${tag}:nth-of-type(${same.indexOf(cur) + 1})` : tag)
+    cur = parent
+  }
+  return parts.join(' > ')
+}
+
+const quoteOf = (el: Element) => (el.textContent ?? '').trim().replace(/\s+/g, ' ')
+
+/** Build the anchor for a click at (clientX, clientY) on `el` inside a sticky whose body is
+ *  `root`; `toBody` maps a screen rect to node-body coordinates. */
+export function noteAnchor(el: Element, root: Element, kind: NoteKind, at: { clientX: number; clientY: number }, toBody: (r: DOMRect) => { x: number; y: number; w: number; h: number }): NoteAnchor {
+  const r = el.getBoundingClientRect()
+  const quote = quoteOf(el).slice(0, 200)
+  return {
+    el: { semantics: { tag: el.tagName.toLowerCase(), ...(quote ? { quote } : {}) }, cssPath: cssPathWithin(el, root), note: kind, hue: NOTE_HUE },
+    pos: {
+      fx: r.width ? Math.min(1, Math.max(0, (at.clientX - r.left) / r.width)) : .5,
+      fy: r.height ? Math.min(1, Math.max(0, (at.clientY - r.top) / r.height)) : .5,
+    },
+    rect: toBody(r),
+  }
+}
+
+/** inspect.js's resolve, for a note: the path when it still matches, else tag + quote. */
+export function resolveNoteAnchor(anchor: unknown, root: Element): Element | null {
+  const a = anchor as Partial<NoteAnchor> | null
+  const want = a?.el?.semantics ?? { tag: '' }
+  const match = (el: Element) => {
+    if (want.tag && el.tagName.toLowerCase() !== want.tag) return false
+    if (want.quote) { const t = quoteOf(el); if (!(t.startsWith(want.quote.slice(0, 60)) || t.includes(want.quote.slice(0, 40)))) return false }
+    return true
+  }
+  try {
+    const byPath = a?.el?.cssPath ? root.querySelector(a.el.cssPath) : null
+    if (byPath && match(byPath)) return byPath
+  } catch { /* stale selector */ }
+  if (want.quote && /^[a-z][a-z0-9-]*$/.test(want.tag)) for (const el of root.querySelectorAll(want.tag)) if (match(el)) return el
+  return null
+}
+
+export const isNoteAnchor = (anchor: unknown): anchor is NoteAnchor => {
+  const n = (anchor as any)?.el?.note
+  return n === 'frame' || n === 'scene'
+}

package/src/client/shell/store.ts

@@ -1,6 +1,7 @@
 import { create } from 'zustand'
 import { ROUTE, slideSize } from '../const.ts'
-import { tidy, parseLayout, type BoardLayout } from './tidy.ts'
+import { tidy, parseLayout, type BoardLayout, type TidyNode } from './tidy.ts'
+import { noteReserve } from './notes.ts'
 import { stableNodeKey } from './keys.ts'
 // @ts-expect-error virtual module provided by the plugin
 import shConfig from 'virtual:sh-config'
@@ -18,8 +19,13 @@ const DATA: {
   titles?: Record<string, string>
   /** publish.json v2: per-board artifact type + open/lock, and the reveal flags. */
   policy?: { boards: Record<string, { type?: string; open?: string; lock?: boolean }>; reveal?: { structure?: boolean; source?: boolean }; lockedShell?: boolean }
+  /** the generation of the glass textures this build shipped (publish-bakes.ts); absent = none */
+  bakes?: number
 } | null = shData
 
+/** The published textures' generation, or 0: the static index this build shipped is at /__mv/bakes/<gen>/index.json. */
+export const BAKES = DATA?.bakes ?? 0
+
 /** Every published board is locked to a stage mode - the canvas shell is never
  *  offered on this bundle (01-sharing §5.1's all-boards rule). */
 export const LOCKED_SHELL = DATA?.policy?.lockedShell === true
@@ -45,8 +51,8 @@ export function hydrateBoardPolicy(boards: Record<string, { type?: string; open?
   for (const [k, v] of Object.entries(boards)) if (!BOARD_POLICY[k]) BOARD_POLICY[k] = v
 }
 
-export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number; slide?: boolean }
-export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number; title?: string; description?: string }[] }
+export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number; slide?: boolean; note?: string }
+export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number; title?: string; description?: string; note?: string }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
   /** RESOLVED theme (what renders): themeUser ?? frame meta.theme ?? viewTheme. */
@@ -54,6 +60,11 @@ export interface Node {
   /** Renavigation nonce: bumped when the shell wants this iframe on a FRESH URL
    *  (errored frame whose file is back in the manifest). Never persisted. */
   nav?: number
+  /** Source revision: bumped when the frame reports an HMR update (its modules changed without a
+   *  navigation). Never persisted. */
+  rev?: number
+  /** The theme the frame reports as APPLIED (sh:theme-applied) - sleep waits for it to match. */
+  themeOn?: string
   /** Explicit per-frame override, set by scoped theme actions; cleared by a global set.
    *  The only theme value that persists into the board file. */
   themeUser?: string
@@ -197,6 +208,21 @@ export async function boardFrames(name: string): Promise<string[]> {
 }
 
 const HEADER = 28
+/** What tidy sees: nodes with their scene, variant run, header-inclusive height, and the sticky
+ *  note width to reserve in front (spec 18: the frame's note, and the scene's on every member -
+ *  tidy keeps the scene reserve on the first node it places). */
+export function tidyInput(nodes: readonly Node[], manifest: Manifest | null): TidyNode[] {
+  const entryOf = (id: string) => manifest?.frames.find((f) => f.id === id)
+  const sceneNote = (scene: string) => !!manifest?.scenes.find((s) => s.name === scene)?.note
+  return nodes.map((n) => {
+    const f = entryOf(n.frame)
+    const scene = f?.scene ?? ''
+    return {
+      key: n.key, frame: n.frame, scene, group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER,
+      noteW: noteReserve(!!f?.note, false), sceneNoteW: noteReserve(false, sceneNote(scene)),
+    }
+  })
+}
 let toastSeq = 0
 const nodeKey = () => 'n_' + Math.random().toString(36).slice(2, 8)
 
@@ -302,6 +328,8 @@ interface State {
   resizeNode(key: string, w: number, h: number): void
   measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number): void
   setStatus(key: string, status: Node['status'], error?: string): void
+  bumpRev(key: string): void
+  setThemeOn(key: string, theme: string): void
   reloadFrame(key: string, automatic?: boolean): void
   removeNode(key: string): void
   select(key: string | null, additive?: boolean): void
@@ -601,11 +629,7 @@ export const useStore = create<State>((set, get) => {
         }
       }
       if ((!boardHash || needTidy) && nodes.length) {
-        const entryOf = (id: string) => manifest.frames.find((f) => f.id === id)
-        const placedAll = tidy(nodes.map((n) => {
-          const f = entryOf(n.frame)
-          return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
-        }), effectiveLayout(layout, sceneRows), layoutWarn)
+        const placedAll = tidy(tidyInput(nodes, manifest), effectiveLayout(layout, sceneRows), layoutWarn)
         for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
       }
       // dirty matches disk by construction - except when load-time pruning changed the
@@ -613,11 +637,7 @@ export const useStore = create<State>((set, get) => {
       // surface recipe problems at load (dry-run): materialized boards otherwise
       // never run tidy, so a broken agent-authored layout would fail silently
       if (layout && boardHash && !needTidy && nodes.length) {
-        const entryOf2 = (id: string) => manifest.frames.find((f) => f.id === id)
-        tidy(nodes.map((n) => {
-          const f = entryOf2(n.frame)
-          return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
-        }), layout, layoutWarn)
+        tidy(tidyInput(nodes, manifest), layout, layoutWarn)
       }
       return { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, selection: [], dirty: prunedAtLoad }
     } catch { return null }
@@ -985,6 +1005,8 @@ export const useStore = create<State>((set, get) => {
       if (name) get().runTidy()                      // restore must NOT tidy - it would destroy positions
       else scheduleSave()
     },
+    bumpRev(key) { set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, rev: (n.rev ?? 0) + 1 } : n)) })) },
+    setThemeOn(key, theme) { set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, themeOn: theme } : n)) })) },
     setStatus(key, status, error) {
       // any real ready/error resets the one-shot retry allowance, so a later manual reload or a
       // fresh manifest earns its own auto-retry again
@@ -1189,11 +1211,7 @@ export const useStore = create<State>((set, get) => {
     },
     runTidy() {
       const { nodes, manifest, sceneRows, layout } = get()
-      const entryOf = (id: string) => manifest?.frames.find((f) => f.id === id)
-      const placed = tidy(nodes.map((n) => {
-        const f = entryOf(n.frame)
-        return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
-      }), effectiveLayout(layout, sceneRows), layoutWarn)
+      const placed = tidy(tidyInput(nodes, manifest), effectiveLayout(layout, sceneRows), layoutWarn)
       set((s) => ({
         nodes: s.nodes.map((n) => {
           const p = placed.find((x) => x.key === n.key)