@marver-design/marver 0.17.0 → 0.18.0

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/store.ts

@@ -18,8 +18,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
@@ -54,6 +59,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
@@ -302,6 +312,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
@@ -985,6 +997,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

package/src/client/shell/styles.css

@@ -150,21 +150,17 @@ button svg { pointer-events: none }   /* event targets stay on the button - pan
   opacity: var(--grid-alpha, 1) }
 .sh-content { will-change: auto }
 #sh-world { position: relative; width: 1px; height: 1px }
-#sh-world.sh-gesturing .sh-live { pointer-events: none }          /* law G-4 (live iframe only; lean is always pe:none) */
-.sh-gesturing .sh-content { will-change: transform }              /* law G-3: gesture-scoped only */
+#sh-world.sh-gesturing .sh-live { pointer-events: none }          /* law G-4 */
+/* no gesture promotion (a will-change layer on the world was measured harmful: 18-29 dropped frames
+   per pan on a 32-frame board against 0-3 without, spec 16) */
 /* preset transitions: armed by animateLayout() around device/tidy mutations - nodes ease
    to their new frame on the same 320ms ease-out the camera fit animates with */
 #sh-world.sh-preset .sh-node { transition: transform .32s cubic-bezier(.25,.46,.45,.94),
   width .32s cubic-bezier(.25,.46,.45,.94), height .32s cubic-bezier(.25,.46,.45,.94) }
-#sh-world.sh-preset .sh-node-body,
-#sh-world.sh-preset .sh-node .sh-live { transition: width .32s cubic-bezier(.25,.46,.45,.94),
+#sh-world.sh-preset .sh-node-body { transition: width .32s cubic-bezier(.25,.46,.45,.94),
   height .32s cubic-bezier(.25,.46,.45,.94) }
-/* Device-sweep: a frame WITH a ready lean cover jumps its LIVE iframe straight to the final
-   width (ONE reflow, hidden under the cover) while the lean cover - being width:100% of the animating
-   body - reflows smoothly every frame (real CSS, the device-sweep fix). A frame WITHOUT a usable
-   cover keeps the live width animation above. */
-body:not(.sh-laser):not(.sh-commenting) #sh-world.sh-preset .sh-node:has(.sh-lean[data-ready]):not(.interact) .sh-live { transition: none }
-
+/* the live iframe takes its new size at once (ONE reflow per sweep) while the body's box eases to it;
+   the frame sleeps again under the new size once it settles */
 /* cursor conventions (Figma): arrow everywhere; grab only while space is held */
 body.sh-space .sh-canvas { cursor: grab }
 body.sh-space.sh-panning .sh-canvas { cursor: grabbing }
@@ -199,8 +195,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
   font-size: 11px; color: var(--head-dim);
   border-bottom: 1px solid var(--node-brd); user-select: none;
   border-radius: var(--r-node) var(--r-node) 0 0;
-  background-color: var(--head-bg); background-image: var(--head-sheen);
-  backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur) }
+  background-color: var(--head-bg); background-image: var(--head-sheen) }   /* no backdrop-filter: one render surface less per frame */
 .sh-node-head .id { font-weight: 600; color: var(--head-ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
 /* frame icons: every sidebar row leads with one */
 .sh-node-head .iicon { flex: none; color: var(--head-dim) }
@@ -210,20 +205,9 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-panel .sub.vrow { padding-left: 51px }
 .sh-node-head .dim { margin-left: auto; color: var(--head-dim); flex: none; font-variant-numeric: tabular-nums }
 .sh-node-body { position: relative; background: var(--node-bg); border-radius: 0 0 var(--r-node) var(--r-node); overflow: hidden }
+/* no content-visibility on the body: it flips frames between skipped and rendered as they cross the
+   viewport during a zoom, and the raster storm that follows left the page unfinished 2.5 s later */
 .sh-node iframe { border: 0; display: block }
-/* LEAN-PRIMARY: the lean DOM-snapshot <iframe> (static html, 0 JS) is what you SEE for a
-   passive frame - at rest AND during pan/zoom/resize. There is NO per-gesture swap between the lean
-   and the live iframe (the swap shifted text ~1-2px = "jiggle", and flashed mermaid/theme colors,
-   because two documents never render pixel-identically). The live app (.sh-live) sits underneath and
-   shows ONLY when: the frame is interacted (.interact), laser/comment mode is on, or the lean is not
-   yet built (no data-ready = live-fallback). Hard cut, never a crossfade - two ~1px-offset text docs
-   would ghost into double text. */
-.sh-lean { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; z-index: 1;
-  opacity: 0; pointer-events: none; transition: none; background: var(--node-bg) }
-.sh-lean[data-ready] { opacity: 1 }
-.sh-node.interact .sh-lean,
-body.sh-laser .sh-lean,
-body.sh-commenting .sh-lean { opacity: 0 }
 .sh-overlay { position: absolute; inset: 0; z-index: 2 }   /* above the lean (z1) so drag-by-body works; inherits the app arrow cursor */
 .sh-node.interact { border-color: var(--interact);
   outline: calc(2px * var(--sh-inv, 1)) solid var(--interact);

package/src/shared/sleep-rule.ts

@@ -0,0 +1,41 @@
+/**
+ * The paint override a sleeping backdrop-filter element wears (spec 16) - ONE definition, used by
+ * the compiler inside the frame it certifies (src/server/bake.ts embeds these functions' source in
+ * a page script) and by the shell inside the frame it puts to sleep (src/client/shell/canvas/sleep.ts).
+ * Plain ES2020 with no imports or closures, so `Function.prototype.toString` carries it whole.
+ *
+ * The composition, bottom to top: the certified texture (the element's filtered backdrop, clipped to
+ * its border box the way the effect is), the element's own colour under the clip the author gave it,
+ * the element's own images, then its content.
+ *
+ * `backdrop-filter: none`: the element must stop being an effect layer. An effect layer is its own
+ * compositor layer with its own tiles, and thirty of them per frame are what a headed Chrome cannot
+ * re-raster fast enough under a pan or a zoom - the presented frames show the frame body missing
+ * while the pills draw (research/hifi/glitch.ts). `blur(0px)` measured better only in headless
+ * Chrome, whose forced screenshots never show a missing tile. A static `filter` keeps what the
+ * backdrop-filter gave layout - the containing block of fixed descendants (a hidden checkbox input
+ * is one) and the stacking context - without a direct compositing reason (a video, a canvas or a
+ * will-change inside still promotes that one element): `opacity(1)` when the author set none, the
+ * author's own filter otherwise.
+ */
+export interface OwnBackground { img: string; color: string; size: string; pos: string; rep: string; org: string; clip: string; filter: string }
+
+/** The element's own background and filter, read once BEFORE any override touches it. */
+export function readOwn(cs: CSSStyleDeclaration): OwnBackground {
+  return { img: cs.backgroundImage, color: cs.backgroundColor, size: cs.backgroundSize, pos: cs.backgroundPosition, rep: cs.backgroundRepeat, org: cs.backgroundOrigin, clip: cs.backgroundClip, filter: cs.filter }
+}
+
+export function sleepRule(selector: string, o: OwnBackground, texture: string): string {
+  const img = o.img === 'none' ? '' : o.img + ','
+  // the authored colour paints under the LAST layer's clip (CSS Backgrounds 3)
+  const colorClip = o.clip.split(',').pop()!.trim() || 'border-box'
+  return selector + '{backdrop-filter:none!important;-webkit-backdrop-filter:none!important;' +
+    (o.filter === 'none' ? 'filter:opacity(1)!important;' : '') +
+    'background-color:transparent!important;' +
+    'background-image:' + img + 'linear-gradient(' + o.color + ',' + o.color + '),url("' + texture + '")!important;' +
+    'background-size:' + (img ? o.size + ',' : '') + 'auto,100% 100%!important;' +
+    'background-position:' + (img ? o.pos + ',' : '') + '0 0,0 0!important;' +
+    'background-repeat:' + (img ? o.rep + ',' : '') + 'no-repeat,no-repeat!important;' +
+    'background-origin:' + (img ? o.org + ',' : '') + 'border-box,border-box!important;' +
+    'background-clip:' + (img ? o.clip + ',' : '') + colorClip + ',border-box!important}'
+}

package/templates/instructions/craft.md

@@ -158,3 +158,12 @@ app, and the human attributes the fault to your frame, not to a library.
   WILL sweep devices with keys 1-5.
 - Live fully inside the settled visual world. A direction executed at full commitment
   can be judged and improved; a hedged one can only be redone.
+
+## Glass on the canvas
+
+While a frame rests on the canvas, marver compiles every `backdrop-filter` element into a still
+texture of its own filtered backdrop, certified pixel by pixel, so a board of hi-fi glass pans
+like a board of statics; the frame wakes the moment it is interacted with. Three things cannot
+be compiled and stay live: glass inside glass, a glass element with a `mix-blend-mode`, and a
+frame whose paint at rest is not a function of its URL (random data at boot, a clock, a
+count-up). Use them on the one frame that needs them, not as a house style.

package/templates/instructions/publish.md

@@ -77,9 +77,39 @@ The host does two things, and the deploy config names both. **`design/.dist` is
 gitignored - it is built ON THE HOST at deploy time, never committed.**
 
 - **build command**: `<install> && npx marver build` (respects `publish.json`,
-  seeds comment logs into the bundle)
+  seeds comment logs into the bundle, compiles the glass textures - see below)
 - **start command**: `npx marver serve` (reads `PORT` + the env vars above)
 - a **persistent volume** mounted at some path, named by `MARVER_DATA_DIR`
+- **Chrome or Chromium on the build machine**, for the glass textures. Without one
+  the build still succeeds and says `textures: none - no Chrome on this machine`;
+  the canvas ships and every feature works, but hi-fi frames with `backdrop-filter`
+  rest with their glass live and pan the way they did before 0.18.0.
+
+## Glass textures at build (0.18.0)
+
+A hi-fi frame at rest sleeps under certified textures of its blurred backdrops
+(the dev canvas compiles them on the fly). A published canvas has no compiler,
+so `marver build` compiles them once, against the exact site it just built -
+every published node, at its size on its board, in every theme - and ships them
+under `design/.dist/__mv/bakes/`. The build log tells you what happened:
+
+```
+textures: 8 frame views asleep under certified glass, 0 with live glass, 34 without effects (42 asked: every published node x 2 themes; 806 KB, 35 s)
+```
+
+- `asleep under certified glass` is the number you want to see for hi-fi boards.
+  `with live glass` counts views the compiler refused (glass inside glass, blend
+  modes, paint that is not a function of the URL): they show exactly as before.
+- Budget: about 1-3 s per hi-fi frame and theme, under a second per frame without
+  glass; a 4-frame hi-fi board plus a 128-frame lo-fi board took 35 s.
+- **Bundle your fonts** (`@fontsource-*`, or files under `public/`). The textures
+  are certified as the build machine renders the frame; a font that only exists on
+  the designer's laptop renders differently in the build container and the
+  visitor's browser then refuses those textures (the frame rests live, nothing
+  breaks).
+- Skip it on purpose with `npx marver build --no-textures`, or `MARVER_NO_TEXTURES=1`
+  in a CI that has no Chrome and should stay quiet about it.
+- `MARVER_CHROME=/path/to/chrome` names a browser marver does not find on its own.
 
 The `@marver-design/marver` dependency must resolve from the registry (a local
 `link:`/`file:` dep cannot ride to a remote host) - a normal registry version (`npm i -D @marver-design/marver@latest`) in
@@ -87,15 +117,36 @@ The `@marver-design/marver` dependency must resolve from the registry (a local
 
 ## Railway quickstart
 
-Commit a `railway.json` so `railway up` knows how to build and serve:
+Commit a `Dockerfile` at the upload root - Railway detects it, and it is the one
+path that gives the build a browser for the glass textures:
+
+```dockerfile
+FROM node:22-slim
+# Chromium for `marver build` (the glass textures); fonts-liberation so system-ui text
+# has a face in the container. marver finds /usr/bin/chromium on its own and runs it
+# with the container flags a root build needs.
+RUN apt-get update && apt-get install -y --no-install-recommends chromium fonts-liberation \
+  && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY package.json ./
+RUN npm install
+COPY . .
+RUN npx marver build
+ENV PORT=8080
+CMD ["npx", "marver", "serve"]
+```
 
-```json
-{
-  "$schema": "https://railway.com/railway.schema.json",
-  "build": { "builder": "NIXPACKS", "buildCommand": "pnpm install && npx marver build" },
-  "deploy": { "startCommand": "npx marver serve" }
-}
 ```
+# .dockerignore
+node_modules
+design/.dist
+design/.local
+```
+
+(A `railway.json` with the NIXPACKS builder - `"buildCommand": "pnpm install && npx marver build"`,
+`"startCommand": "npx marver serve"` - works too, but a Nixpacks image has no browser: the build
+prints `textures: none` and ships the hi-fi frames with live glass. Add chromium to it, or use the
+Dockerfile.)
 
 Then, once per service:
 
@@ -117,7 +168,9 @@ railway logs                      # with a PASSWORD gate, the owner claim link p
 
 Republishing is just `railway up` again: the server unions the seeded logs on
 boot, so collected feedback is NEVER clobbered by a new build. Run ONE instance -
-the event log is single-writer by design.
+the event log is single-writer by design. A republish mints new glass textures;
+a tab that was already open keeps asking for the old ones and rests its glass
+live until it reloads - by design, so an old shell never dresses new frames.
 
 ## What the deployed gate offers (so you know what you're wiring)
 

package/src/client/frame-host/serialize.ts

@@ -1,195 +0,0 @@
-// The DOM-snapshot serializer. Turns a live, same-origin frame Document into a
-// self-contained STATIC html string: post-render DOM + full inlined CSS (styleSheets +
-// adoptedStyleSheets), JS stripped. Rendered in a `sandbox="allow-same-origin"` (NO allow-scripts)
-// iframe srcdoc, it reflows / theme-flips / device-sweeps with the browser's own layout engine and
-// the app's own stylesheet - so color is identical (same tokens, no raster) and layout is real CSS.
-//
-// Runs in the SHELL (same origin as every frame), reading the live iframe's contentDocument directly
-// - no bridge round-trip. Fail soft: any throw returns a `degraded` result the coordinator refuses to
-// show. Correctness beats the flash-guard: a frame we cannot serialise faithfully stays live.
-
-export interface ScrollEntry { sel: string; top: number; left: number }
-export interface SerializeResult {
-  html: string
-  scrollMap: ScrollEntry[]          // native scrollers to restore shell-side after load
-  degraded: string[]                // 'canvas' | 'video' | 'shadow-dom' | 'cross-origin-css' | 'js-layout'
-  notes: string[]
-  cssBytes: number
-}
-
-const STRIP_TAGS = new Set(['SCRIPT', 'NOSCRIPT'])
-
-/** Absolutize relative url() in a sheet's cssText against that sheet's href (consolidating
- *  rules into one <style> moves the url() base from each sheet to the srcdoc base). */
-function absolutizeUrls(css: string, sheetHref: string | null): string {
-  if (!sheetHref) return css
-  return css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (m, q, ref: string) => {
-    if (/^(data:|https?:|blob:|#|\/)/i.test(ref) || !ref.trim()) return m
-    try { return `url(${q}${new URL(ref, sheetHref).href}${q})` } catch { return m }
-  })
-}
-
-/** Serialise one sheet's rules, recursing into same-origin @import (so imported CSS is inlined, not
- *  left as an invalid mid-list @import pointing at an un-inlined sheet). Bumps `xo` on any unreadable
- *  (cross-origin) sheet or import so the caller can degrade. */
-function rulesText(rules: CSSRuleList, href: string | null, xo: { n: number }): string {
-  let text = ''
-  for (const r of Array.from(rules)) {
-    if (r.type === 3 /* CSSRule.IMPORT_RULE */) {
-      const imp = r as CSSImportRule & { supportsText?: string; layerName?: string | null }
-      const sheet = imp.styleSheet
-      if (!sheet) { xo.n++; continue }
-      let inner: string
-      try { inner = rulesText(sheet.cssRules, sheet.href ?? href, xo) } catch { xo.n++; continue }
-      // preserve the import's conditions - flattening them makes a conditional (e.g. desktop-only,
-      // layered, feature-gated) sheet globally active and mis-render the lean.
-      if (imp.layerName != null) inner = `@layer${imp.layerName ? ' ' + imp.layerName : ''}{\n${inner}\n}`
-      if (imp.supportsText) inner = `@supports (${imp.supportsText}){\n${inner}\n}`
-      const m = imp.media?.mediaText
-      if (m && m !== 'all') inner = `@media ${m}{\n${inner}\n}`
-      text += inner
-      continue
-    }
-    text += r.cssText + '\n'
-  }
-  return absolutizeUrls(text, href)
-}
-
-/** Collect every CSS rule the document renders with: <style>/<link> sheets (recursing @import) AND
- *  constructable adoptedStyleSheets. Cross-origin sheets throw on .cssRules - record + degrade (never
- *  claim fidelity). Honours per-sheet media (`<link media=print>`) and skips disabled sheets. */
-function collectCss(doc: Document, degraded: string[], notes: string[]): string {
-  const chunks: string[] = []
-  const xo = { n: 0 }
-  const dump = (sheet: CSSStyleSheet, href: string | null, label: string) => {
-    if (sheet.disabled) return
-    let rules: CSSRuleList | null = null
-    try { rules = sheet.cssRules } catch { xo.n++; return }
-    if (!rules) return
-    const text = rulesText(rules, href, xo)
-    if (!text) return
-    const media = sheet.media?.mediaText
-    chunks.push(`/* ${label} */\n${media && media !== 'all' ? `@media ${media}{\n${text}\n}` : text}`)
-  }
-  for (const s of Array.from(doc.styleSheets)) dump(s as CSSStyleSheet, s.href, s.href ?? 'inline')
-  const adopted = (doc as Document & { adoptedStyleSheets?: CSSStyleSheet[] }).adoptedStyleSheets ?? []
-  adopted.forEach((s, i) => dump(s, null, `adopted[${i}]`))
-  if (xo.n) { degraded.push('cross-origin-css'); notes.push(`${xo.n} cross-origin stylesheet(s)/import(s) unreadable`) }
-  if (adopted.length) notes.push(`${adopted.length} adoptedStyleSheet(s) inlined`)
-  return chunks.join('\n')
-}
-
-/** A stable-ish selector for restoring scroll in the identical-structure lean doc. */
-function selectorFor(el: Element): string {
-  const seg: string[] = []
-  for (let cur: Element | null = el; cur && cur !== el.ownerDocument.documentElement; cur = cur.parentElement) {
-    if (cur.id) { seg.unshift(`#${CSS.escape(cur.id)}`); break }
-    const tag = cur.tagName.toLowerCase()
-    let n = 1
-    for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling) if (sib.tagName === cur.tagName) n++
-    seg.unshift(`${tag}:nth-of-type(${n})`)
-  }
-  return seg.join('>')
-}
-
-/** Strip execution + inline handlers from the clone; flag content that cannot reflow as DOM. */
-function scrub(root: Element, doc: Document, degraded: string[]): void {
-  root.querySelectorAll('script, noscript, link[rel~="modulepreload"], link[rel~="preload"], link[rel~="stylesheet"]').forEach((n) => n.remove())
-  const walk = doc.createTreeWalker(root, NodeFilter.SHOW_ELEMENT)
-  const flag = { canvas: false, video: false, nested: false }
-  for (let el = walk.currentNode as Element | null; el; el = walk.nextNode() as Element | null) {
-    for (const attr of Array.from(el.attributes)) {
-      if (/^on/i.test(attr.name)) el.removeAttribute(attr.name)
-      else if (/^\s*javascript:/i.test(attr.value)) el.removeAttribute(attr.name)
-    }
-    const tag = el.tagName
-    if (tag === 'CANVAS') flag.canvas = true
-    if (tag === 'VIDEO') flag.video = true
-    // a nested iframe/object/embed can't reflow in a scriptless clone (blank/stale, and would
-    // re-fetch third-party content) - degrade to live rather than ship a broken lean.
-    if (tag === 'IFRAME' || tag === 'OBJECT' || tag === 'EMBED') flag.nested = true
-    if (STRIP_TAGS.has(tag)) el.remove()
-  }
-  if (flag.canvas) degraded.push('canvas')
-  if (flag.video) degraded.push('video')
-  if (flag.nested) degraded.push('nested-frame')
-}
-
-/** Open shadow roots must be detected on the ORIGINAL tree - cloneNode(true) drops them, so the clone
- *  can never reveal them. A frame with any shadow DOM (open here, or closed via the boot-time flag)
- *  degrades to live rather than shipping a lean copy missing its shadow content. */
-function hasOpenShadow(doc: Document): boolean {
-  const walk = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_ELEMENT)
-  for (let el = walk.currentNode as Element | null; el; el = walk.nextNode() as Element | null)
-    if ((el as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot) return true
-  return false
-}
-
-/** Copy live form PROPERTIES (value/checked/selected) into the clone. They are runtime state, not
- *  attributes, so cloneNode never carries them - without this a re-captured frame shows empty inputs
- *  and unchecked boxes. Original and clone share structure, so we pair them in document order.
- *  tagName/type checks (not instanceof) because the clone nodes are owned by the frame's realm. */
-function syncFormState(doc: Document, clone: HTMLElement): void {
-  const live = doc.querySelectorAll('input, textarea, option')
-  const dst = clone.querySelectorAll('input, textarea, option')
-  live.forEach((src, i) => {
-    const d = dst[i]
-    if (!d || d.tagName !== src.tagName) return
-    if (src.tagName === 'INPUT') {
-      const s = src as HTMLInputElement
-      // never bake a password into the retained snapshot html; a file input can't be reconstructed
-      if (s.type === 'password' || s.type === 'file') { d.removeAttribute('value'); return }
-      if (s.type === 'checkbox' || s.type === 'radio') s.checked ? d.setAttribute('checked', '') : d.removeAttribute('checked')
-      else d.setAttribute('value', s.value)
-    } else if (src.tagName === 'TEXTAREA') { d.textContent = (src as HTMLTextAreaElement).value }
-    else if (src.tagName === 'OPTION') { (src as HTMLOptionElement).selected ? d.setAttribute('selected', '') : d.removeAttribute('selected') }
-  })
-}
-
-/**
- * Serialize a live same-origin Document into a static, self-contained html string.
- * @param doc       the live frame document (same origin - we read its cssRules directly)
- * @param baseHref  the frame's real URL, injected as <base> so relative url()/img/font resolve
- */
-export function serializeDoc(doc: Document, baseHref: string): SerializeResult {
-  const notes: string[] = []
-  const degraded: string[] = []
-
-  // shadow DOM (open detected on the original tree, closed via the boot-time attachShadow flag):
-  // either kind degrades the frame to live - cloneNode cannot carry a shadow root.
-  const win = doc.defaultView as (Window & { __mvClosedShadow?: boolean }) | null
-  if (win?.__mvClosedShadow || hasOpenShadow(doc)) { degraded.push('shadow-dom'); notes.push('shadow root(s) present') }
-
-  const css = collectCss(doc, degraded, notes)
-  const cssBytes = new Blob([css]).size
-
-  // scroll offsets to restore shell-side (native scrollers; a virtualised one that fails to resolve
-  // OR whose offset does not stick re-degrades the frame in the coordinator). != 0 catches RTL/negative.
-  const scrollMap: ScrollEntry[] = []
-  for (const el of Array.from(doc.querySelectorAll<HTMLElement>('*'))) {
-    if (el.scrollTop !== 0 || el.scrollLeft !== 0) scrollMap.push({ sel: selectorFor(el), top: el.scrollTop, left: el.scrollLeft })
-  }
-  const de = doc.documentElement
-  if (de.scrollTop !== 0 || de.scrollLeft !== 0) scrollMap.push({ sel: ':root', top: de.scrollTop, left: de.scrollLeft })
-
-  // clone the RENDERED dom (React's committed output = authored markup that reflows under CSS)
-  const html = doc.documentElement.cloneNode(true) as HTMLElement
-  scrub(html, doc, degraded)
-  syncFormState(doc, html)
-
-  // head: <meta charset> + <base> (relative url()/img/font resolve against the real frame URL) +
-  // ONE inlined stylesheet (both themes, all media queries). Drop the clone's own style nodes.
-  const head = html.querySelector('head') ?? html.insertBefore(doc.createElement('head'), html.firstChild)
-  head.querySelectorAll('style').forEach((n) => n.remove())
-  // sentinel first rule: the coordinator checks --mv-lean-ok resolves before showing the lean. If a
-  // hardened host's CSP (style-src 'self') blocked this inline <style>, the sentinel is absent and the
-  // frame stays live rather than showing an unstyled cover.
-  const style = doc.createElement('style'); style.textContent = ':root{--mv-lean-ok:1}\n' + css
-  const base = doc.createElement('base'); base.setAttribute('href', baseHref)
-  const meta = doc.createElement('meta'); meta.setAttribute('charset', 'utf-8')
-  head.insertBefore(style, head.firstChild)
-  head.insertBefore(base, head.firstChild)
-  head.insertBefore(meta, head.firstChild)
-
-  return { html: '<!doctype html>\n' + html.outerHTML, scrollMap, degraded: Array.from(new Set(degraded)), notes, cssBytes }
-}