@marver-design/marver 0.17.0 → 0.19.0

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);
@@ -1038,6 +1022,8 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
   margin-left: calc(-1 * clamp(8px, calc(12px * var(--sh-inv, 1)), 36px)) }
 .cm-card.parked.dock-l.flank-shim { margin-left: calc(-1 * clamp(18px, calc(28px * var(--sh-inv, 1)), 68px)) }
 .cm-card.parked.dock-l.flank-badge { margin-left: calc(-1 * clamp(26px, calc(44px * var(--sh-inv, 1)), 108px)) }
+/* a sticky column (spec 18) is world-sized: the card clears it and its gutter */
+.cm-card.parked.dock-l.flank-note { margin-left: calc(-1 * (var(--sh-note-w, 260px) + 36px)) }
 /* PLAY: fixed beside the static device, viewport-clamped (position comes inline). Near-solid
    ground - the stage floats the card over arbitrary artwork on a dark room, glass is unreadable
    there. No transform: play has no zoom, and a leaked --sh-inv must never scale it. */
@@ -1281,3 +1267,84 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 .sh-slides-strip .bar { width: 140px; height: 3px; border-radius: 999px; background: var(--glass-hover); overflow: hidden }
 .sh-slides-strip .bar i { display: block; height: 100%; border-radius: inherit; background: var(--accent); transition: width .25s ease }
 @media (max-width: 480px) { .sh-slides-strip .bar { width: 80px } }
+
+
+/* ---- sticky notes (spec 18): the yellow column left of a frame ------------------------------
+   World-sized (it scales with the canvas, like the artwork); the fold's hit target keeps a screen
+   minimum through --sh-inv. Yellow in both shell themes - a sticky is yellow. */
+.sh-node { --note-bg: #fff3a3; --note-bg-2: #ffeb85; --note-ink: #2b2500; --note-dim: rgba(43, 37, 0, .62);
+  --note-line: rgba(107, 90, 0, .28); --note-link: #7a4d00; --note-fold: #e9cf5e; --note-fold-2: #c9ae3c }
+/* dark canvas: a deeper mustard so the paper reads as paper, not as a highlight; ink darker for contrast */
+.sh-node[data-theme="dark"] { --note-bg: #e6c94f; --note-bg-2: #d6b73c; --note-ink: #1f1a00; --note-dim: rgba(31, 26, 0, .68);
+  --note-line: rgba(70, 56, 0, .35); --note-link: #5c3a00; --note-fold: #c9aa33; --note-fold-2: #8f7518 }
+.sh-notes { position: absolute; right: 100%; top: 0; margin-right: 24px;
+  display: flex; flex-direction: column; align-items: flex-end; gap: 12px; pointer-events: none }
+.sh-notes.below-vbadge { top: 72px }
+.sh-notes > * { pointer-events: auto }
+.sh-sticky { position: relative; box-sizing: border-box; background: var(--note-bg); color: var(--note-ink);
+  border-radius: 2px 10px 2px 2px; padding: 14px 16px 12px;
+  box-shadow: 0 1px 2px rgba(60, 45, 0, .18), 0 6px 18px -6px rgba(60, 45, 0, .35);
+  font: 400 13px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  transform-origin: top right; opacity: 1; visibility: visible;
+  transition: transform .18s cubic-bezier(.2, .7, .3, 1), opacity .16s ease, visibility 0s linear 0s;
+  user-select: text; -webkit-user-select: text; cursor: default }
+.sh-sticky[data-sticky="scene"] { padding: 18px 20px 16px; font-size: 14px }
+.sh-notes.off .sh-sticky { transform: scale(.04); opacity: 0; visibility: hidden;
+  transition: transform .18s cubic-bezier(.4, 0, .8, .4), opacity .14s ease .04s, visibility 0s linear .18s; pointer-events: none }
+/* the dog-ear: on the column it is the top sticky's folded corner; folded, it is the tab that stays */
+.sh-notes-fold { position: absolute; top: 0; right: 0; z-index: 2; padding: 0; border: 0; cursor: pointer;
+  width: clamp(22px, calc(14px * var(--sh-inv, 1)), 72px); height: clamp(22px, calc(14px * var(--sh-inv, 1)), 72px);
+  border-radius: 0 10px 0 4px;
+  background: linear-gradient(225deg, transparent 50%, var(--note-fold) 50%, var(--note-fold-2) 100%);
+  transition: background .18s ease, border-radius .18s ease, box-shadow .18s ease, transform .18s ease }
+.sh-notes-fold:hover { filter: brightness(.96) }
+.sh-notes-fold:focus-visible { outline: 2px solid var(--accent, #2f6df6); outline-offset: 2px }
+.sh-notes.off .sh-notes-fold { border-radius: 3px 3px 3px 8px; background: linear-gradient(160deg, var(--note-bg) 0%, var(--note-bg-2) 100%);
+  box-shadow: 0 1px 2px rgba(60, 45, 0, .25), 0 3px 8px -2px rgba(60, 45, 0, .35) }
+.sh-notes.off .sh-notes-fold::after { content: ""; position: absolute; right: 0; top: 0; width: 38%; height: 38%;
+  border-radius: 0 3px 0 3px; background: linear-gradient(225deg, transparent 50%, var(--note-fold-2) 50%) }
+@media (prefers-reduced-motion: reduce) { .sh-sticky, .sh-notes-fold { transition: none } }
+/* comment mode: hover names the element the click would pick; the lock is the shell's own outline */
+body.sh-commenting .sh-sticky-body :is(p, li, h1, h2, h3, h4, blockquote, pre, img, table, .sh-sticky-diagram):hover { outline: 1.5px solid var(--accent, #2f6df6); outline-offset: 2px; border-radius: 3px }
+body.sh-commenting .sh-sticky-body { cursor: crosshair }
+.sh-sticky-body [data-sh-lock] { outline: 2px solid hsl(var(--cm-h, 48) 80% 42%); outline-offset: 3px; border-radius: 3px;
+  box-shadow: 0 0 0 5px hsl(var(--cm-h, 48) 90% 60% / .28) }
+/* prose: the Md block's vocabulary, sized for an aside */
+.sh-sticky-body > :first-child { margin-top: 0 }
+.sh-sticky-body > :last-child { margin-bottom: 0 }
+.sh-sticky-body h1, .sh-sticky-body h2, .sh-sticky-body h3, .sh-sticky-body h4 { margin: 0 0 6px; line-height: 1.25; letter-spacing: -0.01em; text-wrap: balance }
+.sh-sticky-body h1 { font-size: 1.28em; font-weight: 700 }
+.sh-sticky-body h2 { font-size: 1.14em; font-weight: 650 }
+.sh-sticky-body h3, .sh-sticky-body h4 { font-size: 1em; font-weight: 650 }
+.sh-sticky-body p, .sh-sticky-body ul, .sh-sticky-body ol, .sh-sticky-body blockquote, .sh-sticky-body pre, .sh-sticky-body table { margin: 0 0 8px }
+.sh-sticky-body ul, .sh-sticky-body ol { padding-left: 18px }
+.sh-sticky-body li { margin: 2px 0 }
+.sh-sticky-body li > ul, .sh-sticky-body li > ol { margin-bottom: 0 }
+.sh-sticky-body blockquote { padding: 2px 0 2px 10px; border-left: 3px solid var(--note-line); color: var(--note-dim) }
+.sh-sticky-body a { color: var(--note-link); text-decoration: underline; text-underline-offset: 2px; text-decoration-color: rgba(122, 77, 0, .45) }
+.sh-sticky-body a:hover { text-decoration-color: currentColor }
+.sh-sticky-body a[data-goto]::after { content: "\2197"; font-size: .8em; margin-left: 2px; text-decoration: none; display: inline-block }
+.sh-sticky-body code { font: 500 .9em/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: rgba(43, 37, 0, .07); padding: 1px 4px; border-radius: 3px }
+.sh-sticky-body pre { padding: 8px 10px; border-radius: 6px; background: rgba(43, 37, 0, .07); overflow-x: auto; white-space: pre }
+.sh-sticky-body pre code { background: none; padding: 0; font-weight: 400 }
+.sh-sticky-body pre.err { background: rgba(190, 40, 20, .1); color: #7a1f0f }
+.sh-sticky-body hr { border: 0; border-top: 1px solid var(--note-line); margin: 10px 0 }
+.sh-sticky-body img { max-width: 100%; border-radius: 4px; display: block }
+.sh-sticky-body strong { font-weight: 650 }
+.sh-sticky-body table { border-collapse: collapse; font-size: .92em; width: 100%; table-layout: auto }
+.sh-sticky-body td, .sh-sticky-body th { overflow-wrap: anywhere }
+.sh-sticky-body th, .sh-sticky-body td { border: 1px solid var(--note-line); padding: 3px 6px; text-align: left; vertical-align: top }
+.sh-sticky-body th { font-weight: 650; background: rgba(43, 37, 0, .05) }
+.sh-sticky-body input[type="checkbox"] { margin: 0 6px 0 0; vertical-align: -1px }
+.sh-sticky-body .mv-md-noimg { color: var(--note-dim); font-style: italic }
+.sh-sticky-body .mv-c-blue { color: #0070d6 } .sh-sticky-body .mv-c-orange { color: #c9640a } .sh-sticky-body .mv-c-purple { color: #9a23ad }
+.sh-sticky-body .mv-c-green { color: #1a8a3f } .sh-sticky-body .mv-c-red { color: #c72a22 } .sh-sticky-body .mv-c-gray { color: #6b7480 }
+/* the hand-drawn diagram: the fence's place, the paper's colors, scaled to the column */
+.sh-sticky-diagram { margin: 4px 0 10px; overflow: visible; display: flex; justify-content: center }
+.sh-sticky-diagram svg { display: block; max-width: 100%; height: auto; margin: 0 auto;
+  /* the canvas scales the world with a CSS transform, and Chrome lays SVG text out ONCE for the
+     scale it was inserted at (a diagram born at 13 % zoom keeps 13 %-zoom glyph positions at
+     140 %: labels drift, some vanish). geometricPrecision lays glyphs out scale-free - measured,
+     research/notes/diagprobe5.ts */
+  text-rendering: geometricPrecision }
+.sh-sticky-diagram svg text, .sh-sticky-diagram svg tspan { text-rendering: geometricPrecision }

package/src/client/shell/tidy.ts

@@ -1,4 +1,10 @@
-export interface TidyNode { key: string; frame: string; scene: string; group?: string; variant?: string; w: number; h: number }
+export interface TidyNode {
+  key: string; frame: string; scene: string; group?: string; variant?: string; w: number; h: number
+  /** Sticky notes (spec 18), world px INCLUDING the gutter: reserved in front of this node
+   *  (its own note), and in front of the scene's first placed node (the scene note - carried on
+   *  every member, applied once). A column holds both, so the wider wins, never the sum. */
+  noteW?: number; sceneNoteW?: number
+}
 export interface Placed { key: string; x: number; y: number }
 
 // Lane-flow grammar: one shape at both scopes. A scope is rows XOR columns
@@ -43,7 +49,7 @@ const box = (id: string, parts: Array<{ key: string; dx: number; dy: number; w:
 const runBox = (id: string, run: TidyNode[]): Box => {
   const parts: Array<{ key: string; dx: number; dy: number; w: number; h: number }> = []
   let dx = 0
-  for (const n of run) { parts.push({ key: n.key, dx, dy: 0, w: n.w, h: n.h }); dx += n.w + frameGapX(n.w) }
+  for (const n of run) { dx += n.noteW ?? 0; parts.push({ key: n.key, dx, dy: 0, w: n.w, h: n.h }); dx += n.w + frameGapX(n.w) }
   return box(id, parts)
 }
 
@@ -264,6 +270,18 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
   for (const scene of scenes) {
     const members = nodes.filter((n) => n.scene === scene)
     const m = layoutScene(scene, members, layout?.scenes?.[scene], warn)
+    // the scene note sits in front of the scene's first node in reading order (the host the
+    // shell picks): widen the scene box on the left by what that node's own note does not cover
+    const sceneNoteW = Math.max(0, ...members.map((n) => n.sceneNoteW ?? 0))
+    if (sceneNoteW) {
+      const placed = members.filter((n) => m.has(n.key))
+      const first = placed.reduce<TidyNode | null>((best, n) => {
+        const p = m.get(n.key)!, b = best && m.get(best.key)!
+        return !b || p.y < b.y || (p.y === b.y && p.x < b.x) ? n : best
+      }, null)
+      const extra = sceneNoteW - (first?.noteW ?? 0)
+      if (extra > 0) for (const [k, p] of m) m.set(k, { x: p.x + extra, y: p.y })
+    }
     sceneMaps.set(scene, m)
     const parts = members
       .filter((n) => m.has(n.key))

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

@@ -118,6 +118,21 @@ Report where the request came from: chat requests get chat replies; only comment
 - CONTENT frames (specs, mermaid diagrams, mood boards) are ordinary tsx frames built
   from the block primitives in '@marver-design/marver/content' - import them directly
   in the frame file and declare meta.intent. Full guide: instructions/shape.md.
+- STICKY NOTES: the aside beside a frame. One markdown file, nothing to declare:
+  `design/scenes/<scene>/<frame>.note.md` beside the frame file (tsx, jsx or html),
+  `design/scenes/<scene>/_note.md` for the scene (it shows beside the scene's first frame),
+  `design/components/<name>.note.md` for a component. It renders as a yellow note left of the
+  frame on every canvas, dev and published. Write one when a reader needs what the screen
+  cannot say: what the frame is for, how two variations differ, how a mechanism works, an
+  open question. Markdown (headings, lists, tables, emphasis, code), `[text](goto:scene/frame)`
+  links that jump to a frame, images from design/assets/, and ```mermaid fences drawn
+  hand-sketched in the note's own yellow - plain mermaid, any family, no init/theme/style
+  lines, no URLs (flowchart, sequence, state, class, ER, pie, mindmap read well at note
+  width; gantt, journey and timeline are wide by nature - few items, or a content frame) -
+  raw HTML is inert. Readers comment on a note's text like on a frame element,
+  fold it to its corner, hide all with N. An edit lands live without reloading the frame.
+  Keep it an aside, a screen's worth at most: specs, flows and mood boards stay content frames.
+  Full guide: instructions/shape.md.
 
 ## Structure ladder (embedded mode: screens live in src/)
 1. First pass: write the whole page inline in the frame file. Diverge fast.

package/templates/AGENTS-studio.md

@@ -118,6 +118,21 @@ Report where the request came from: chat requests get chat replies; only comment
 - CONTENT frames (specs, mermaid diagrams, mood boards) are ordinary tsx frames built
   from the block primitives in '@marver-design/marver/content' - import them directly
   in the frame file and declare meta.intent. Full guide: instructions/shape.md.
+- STICKY NOTES: the aside beside a frame. One markdown file, nothing to declare:
+  `design/scenes/<scene>/<frame>.note.md` beside the frame file (tsx, jsx or html),
+  `design/scenes/<scene>/_note.md` for the scene (it shows beside the scene's first frame),
+  `design/components/<name>.note.md` for a component. It renders as a yellow note left of the
+  frame on every canvas, dev and published. Write one when a reader needs what the screen
+  cannot say: what the frame is for, how two variations differ, how a mechanism works, an
+  open question. Markdown (headings, lists, tables, emphasis, code), `[text](goto:scene/frame)`
+  links that jump to a frame, images from design/assets/, and ```mermaid fences drawn
+  hand-sketched in the note's own yellow - plain mermaid, any family, no init/theme/style
+  lines, no URLs (flowchart, sequence, state, class, ER, pie, mindmap read well at note
+  width; gantt, journey and timeline are wide by nature - few items, or a content frame) -
+  raw HTML is inert. Readers comment on a note's text like on a frame element,
+  fold it to its corner, hide all with N. An edit lands live without reloading the frame.
+  Keep it an aside, a screen's worth at most: specs, flows and mood boards stay content frames.
+  Full guide: instructions/shape.md.
 
 ## Structure ladder
 1. First pass: write the whole page inline in the frame file. Diverge fast.

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

@@ -187,6 +187,68 @@ of described imagery every time (the full asset rules: instructions/craft.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.
 
+## Sticky notes - the aside beside a frame
+
+A sticky note is one markdown file beside the thing it explains. It renders as a yellow note
+left of the frame on the canvas, in dev and in every published or shared canvas. Nothing to
+declare, no board node, no imports, no iframe:
+
+| For | Write | Shows |
+|---|---|---|
+| a frame `checkout/cart` (`cart.tsx`, `cart.jsx` or `cart.html`) | `design/scenes/checkout/cart.note.md` | left of that frame, 260 wide |
+| a scene `checkout` | `design/scenes/checkout/_note.md` | left of the scene's first frame on the board, 380 wide |
+| a component frame | `design/components/<name>.note.md` | as a frame note |
+
+Write one when a reader needs something the screen cannot say: what the frame is for, what
+differs between two variations, how a mechanism works, an open question. Markdown, the Md
+block's rules: `[text](goto:scene/frame)` links jump to a frame on the canvas, `http(s)`
+links open a new tab, images are `design/assets/` paths, raw HTML is inert, and a
+` ```mermaid ` fence renders hand-drawn, in the note's own yellow. Readers can comment on any
+element of a note exactly as on a frame element.
+
+````md
+## Why the jobs list leads
+
+Drivers ask "where am I going first" - the list beats the map here.
+Compare with the [empty day](goto:app-home/today-empty): same header, one call to action.
+
+| Reason | Effect |
+|---|---|
+| Too far | lane weight down |
+
+```mermaid
+flowchart LR
+  Login --> Today --> Jobs
+```
+````
+
+### Diagrams in a note
+
+A ```mermaid fence in a note renders hand-sketched on the yellow paper: rough boxes, hatched
+fills, handwriting labels, one ink. You write plain mermaid and nothing else - no `%%{init}%%`,
+no theme, no colours, no `style` lines (the note has one look and applies it to every family),
+no URLs or images in the source (refused). Every family works: flowchart, sequence, state,
+class, ER, pie, mindmap, timeline, gantt, journey, quadrant, git graph, block.
+
+Fit the note: flowchart (`TD` for a tall note, `LR` for three or four steps), sequence, state,
+class, ER, pie and mindmap read well at 260 or 380 wide. Gantt, journey, timeline, quadrant and
+git graphs are drawn at the note's width too but are wide by nature - keep them to a handful of
+items, or give them a content frame. Five to eight nodes is the sweet spot; short labels
+(two or three words); one diagram per note, above or below the prose it explains.
+
+```mermaid
+sequenceDiagram
+  participant D as Driver
+  participant G as Gate
+  D->>G: scan gate code
+  G-->>D: bay + lot map
+```
+
+Keep it an aside: a screen's worth of reading at most. The spec, the flow, the mood board stay
+content frames - a note explains, it does not document. Every viewer can fold a note to its
+corner tab (the choice is theirs, never saved to the board) and hide all of them with `N`.
+Edits to a note file land on the canvas as you save, without reloading the frame.
+
 ## When Shape ends
 
 The board holds the agreed flow, spec, and direction. Wireframe picks up from