@marver-design/marver 0.16.1 → 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/AGENTS-embedded.md

@@ -81,7 +81,10 @@ planning. The human should see the request land on the canvas within the first m
    lit frame, never before one.
 3. Build. Independent frames can go in parallel - one subagent per frame, each marking
    its own; frames that depend on one another go in order.
-4. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
+4. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
+   `--all`) renders the frames headless in one go - one PNG path per line - and you READ
+   the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
+5. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
    self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
    and never lean on expiry instead of `done`.
 

package/templates/AGENTS-studio.md

@@ -81,7 +81,10 @@ planning. The human should see the request land on the canvas within the first m
    lit frame, never before one.
 3. Build. Independent frames can go in parallel - one subagent per frame, each marking
    its own; frames that depend on one another go in order.
-4. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
+4. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
+   `--all`) renders the frames headless in one go - one PNG path per line - and you READ
+   the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
+5. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
    self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
    and never lean on expiry instead of `done`.
 

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/jam.md

@@ -98,6 +98,15 @@ file - the dev server renders it and writes the PNG back:
 3. **Read the PNG** at that `path` and check it with your own eyes: content present, both
    themes if you touched theming, nothing clipped. Fix and re-shoot; files overwrite in place.
 
+**Several frames? Ask for them in ONE request** - a whole scene renders in one browser,
+several frames at a time, for about the cost of one shot. Write any `<name>.request.json`
+with `{"scene":"checkout"}`, or `{"frames":["checkout/cart","checkout/summary"]}`, or
+`{"all":true}` (plus `"theme"`, `"scale"` as you like). The result is
+`{"ok":true,"results":[{"frame":"checkout/cart","ok":true,"path":"..."},...]}`, one entry
+per frame in the order asked; a frame that failed carries its own `"ok":false,"error"` and
+the others still ship. A frame that ran out of time to settle (a slow image, a heavy chart)
+comes back with `"unsettled":true` and a `note` - shoot that one alone before you judge it.
+
 The `result.json` is the universal signal - it works even when you cannot see images.
 `"ok":false` means the frame did not render: the `error` carries the reason (a runtime
 throw shows the frame's own exception, "the frame rendered an error - ..."; an unreachable
@@ -108,9 +117,12 @@ shot at its natural width and its FULL height, so a wide layout or a long spec r
 full, not cropped. A frame tall enough to hit the capture cap comes back with
 `"truncated":true` and a `note` - split it or shorten it and re-shoot.
 
-(If you DO have a shell - `npx marver shot <scene/frame> [--theme dark] [--scale 4]` is the
-same thing in one line, printing the PNG path. `--scale 4` is for a print-quality still - the
-human's "copy as image" on the canvas uses this same renderer, so you both see one picture.)
+(If you DO have a shell - `npx marver shot <scene/frame ...>`, `npx marver shot --scene
+<name>` or `--all` (`[--theme dark] [--scale 4] [--json]`) is the same thing in one line,
+printing one PNG path per line; a failed frame goes to stderr and the exit code is 1. After
+writing a scene, shoot the scene, not the frames. `--scale 4` is for a print-quality still -
+the human's "copy as image" on the canvas uses this same renderer, so you both see one
+picture.)
 
 Verification is best-effort, not a gate. If your model cannot read images, or the result
 reports no Chrome on the machine, still act on `ok`/`error` - and say plainly in your reply

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/templates/instructions/shape.md

@@ -183,7 +183,8 @@ of described imagery every time (the full asset rules: instructions/craft.md,
   never set a frame height - the frame auto-heights to fit everything the canvas
   measures. Marver renders images crisp and zooms fast, so fine detail is one zoom away.
 - Judge on the RENDER, not the props: after composing, look at the actual frame
-  (screenshot it if you can) and adjust the per-row count until it reads well. "The code
+  (`npx marver shot --scene <scene>` shoots the whole scene in one go; instructions/jam.md
+  has the shell-less way) and adjust the per-row count until it reads well. "The code
   says they're the same width" proves nothing.
 
 ## When Shape ends

package/dist/shot-By1AItpD.mjs

@@ -1,30 +0,0 @@
-import { n as NAME } from "./cli.mjs";
-import { readDevInfo } from "./work-CLrmY-vQ.mjs";
-//#region src/cli/shot.ts
-/**
-* `marver shot <scene/frame>` - render one frame headless and print the PNG path.
-*
-* The shell-ful agents' door into the same verify loop jam teaches: build, shoot, LOOK.
-* Thin wrapper over the dev server's /api/shot (shot.ts has the capture story).
-*/
-async function shotCommand(root, frame, opts) {
-	if (!frame) throw new Error(`name the frame: ${NAME} shot <scene/frame> [--theme <name>] [--scale 1-4]`);
-	const info = readDevInfo(root);
-	if (!info) throw new Error(`\`${NAME} dev\` is not running in this repo (design/.local/dev.json not found) - start it first.`);
-	const qs = new URLSearchParams({
-		frame,
-		...opts.theme ? { theme: opts.theme } : {},
-		...opts.scale != null ? { scale: String(opts.scale) } : {}
-	});
-	let res;
-	try {
-		res = await fetch(`http://localhost:${info.port}/__mv/api/shot?${qs}`, { headers: { "x-mv-work": info.token } });
-	} catch {
-		throw new Error(`could not reach \`${NAME} dev\` on port ${info.port} - is it still running?`);
-	}
-	const data = await res.json().catch(() => ({}));
-	if (!res.ok || !data.path) throw new Error(data.error ?? `shot failed (${res.status})`);
-	console.log(data.path);
-}
-//#endregion
-export { shotCommand };