@idle-screens/schema 3.6.0 → 3.7.0

package/dist/index.js

@@ -46,7 +46,8 @@ var LIMITS = {
   maxTextBlockLength: 2e3,
   minTextBlockFontSize: 0.01,
   maxTextBlockFontSize: 0.2,
-  maxTextBlockMaxWidth: 1,
+  maxTextBlockMaxWidth: 2,
+  // of min(w,h) — wider than the frame is legal; text-off-screen reports the overflow
   maxRevealSpeed: 120,
   // graphemes/sec — faster than any readable typing
   maxCaretBlinkHz: 3,
@@ -83,12 +84,13 @@ var LIMITS = {
 
 // src/steer.ts
 var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var STEERABLE_ROOT_KEYS = /* @__PURE__ */ new Set(["ghosting", "referenceViewport"]);
 function resolveSpecPath(spec, path) {
   if (!spec || typeof spec !== "object" || !path) return null;
   const parts = path.split(".");
   if (parts.some((p) => UNSAFE_KEYS.has(p))) return null;
   const s = spec;
-  if (parts[0] !== "layers" && parts[0] !== "background" && Array.isArray(s.layers)) {
+  if (parts[0] !== "layers" && parts[0] !== "background" && !STEERABLE_ROOT_KEYS.has(parts[0]) && Array.isArray(s.layers)) {
     const idx = s.layers.findIndex((l) => l && l.key === parts[0]);
     if (idx === -1) return null;
     parts.splice(0, 1, "layers", String(idx));
@@ -148,9 +150,61 @@ function lerpSpec(from, to, k) {
   };
   return walk(from, to);
 }
+function textStringsOf(sprite) {
+  if (sprite.kind === "text") return sprite.strings;
+  if (sprite.kind === "textBlock") return [sprite.text];
+  return null;
+}
+function textStringsDiffer(a, b, i) {
+  const sa = a.layers[i]?.sprite;
+  const sb = b.layers[i]?.sprite;
+  if (!sa || !sb) return false;
+  const ta = textStringsOf(sa);
+  const tb = textStringsOf(sb);
+  if (!ta || !tb) return false;
+  return ta.length !== tb.length || ta.some((s, j) => s !== tb[j]);
+}
+var NON_RENDERED_KEYS = /* @__PURE__ */ new Set(["id", "label", "schemaVersion", "key"]);
+function morphNothingMorphable(a, b, opts = {}) {
+  if (opts.textCrossfade && a.layers.some((_, i) => textStringsDiffer(a, b, i))) return false;
+  let hasDiff = false;
+  let hasGlide = false;
+  const walk = (x, y, key) => {
+    if (key !== void 0 && NON_RENDERED_KEYS.has(key)) return;
+    if (x === y) return;
+    if (typeof x === "number" && typeof y === "number") {
+      hasDiff = true;
+      hasGlide = true;
+      return;
+    }
+    if (typeof x === "string" && typeof y === "string" && HEX.test(x) && HEX.test(y)) {
+      const ca = hexToRgb(x);
+      const cb = hexToRgb(y);
+      if (ca.some((v, i) => v !== cb[i])) {
+        hasDiff = true;
+        hasGlide = true;
+      }
+      return;
+    }
+    if (Array.isArray(x) && Array.isArray(y) && x.length === y.length) {
+      for (let i = 0; i < y.length; i++) walk(x[i], y[i]);
+      return;
+    }
+    if (x && y && typeof x === "object" && typeof y === "object" && !Array.isArray(x) && !Array.isArray(y)) {
+      const keys = /* @__PURE__ */ new Set([...Object.keys(x), ...Object.keys(y)]);
+      for (const k of keys) {
+        walk(x[k], y[k], k);
+      }
+      return;
+    }
+    hasDiff = true;
+  };
+  walk(a, b);
+  return hasDiff && !hasGlide;
+}
 function steerablePaths(spec) {
   if (!spec || typeof spec !== "object") return [];
-  const SKIP = /* @__PURE__ */ new Set(["kind", "type", "key", "schemaVersion", "id", "label", "seed", "units", "mode", "curve", "layer"]);
+  const SKIP = /* @__PURE__ */ new Set(["kind", "type", "key", "schemaVersion", "id", "label", "seed", "units", "motionIntensity", "mode", "curve", "layer"]);
   const INDEXED = /* @__PURE__ */ new Set(["layers", "stops"]);
   const out = [];
   const walk = (node, prefix, key) => {
@@ -174,6 +228,12 @@ function steerablePaths(spec) {
   walk(spec, "", "");
   return out;
 }
+function sequenceSteerablePaths(seq) {
+  const out = /* @__PURE__ */ new Set(["sequence.segment"]);
+  if (seq.bed) for (const p of steerablePaths(seq.bed)) out.add(`bed.${p}`);
+  for (const seg of seq.segments) for (const p of steerablePaths(seg.scene)) out.add(p);
+  return [...out];
+}
 function easeSmooth(k) {
   const c = Math.max(0, Math.min(1, k));
   return c * c * (3 - 2 * c);
@@ -181,6 +241,7 @@ function easeSmooth(k) {
 function structuralSignature(spec) {
   return JSON.stringify([
     spec.units,
+    spec.referenceViewport,
     spec.layers.map((l) => {
       const s = l.sprite;
       return [
@@ -206,7 +267,7 @@ function structuralSignature(spec) {
         l.sprite.kind === "rect" ? [s.width, s.aspect] : l.sprite.kind === "bar" ? [s.length, s.thickness] : void 0,
         Array.isArray(s.colors) ? s.colors.length : void 0,
         s.colorWeights,
-        l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : l.sprite.kind === "textBlock" ? [l.sprite.fontSize] : void 0
+        l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : l.sprite.kind === "textBlock" ? l.sprite.anchor ? [l.sprite.fontSize, l.sprite.anchor] : [l.sprite.fontSize] : void 0
       ];
     })
   ]);
@@ -249,8 +310,11 @@ var KNOWN_BAR = /* @__PURE__ */ new Set(["kind", "values", "length", "thickness"
 var KNOWN_POLYGON = /* @__PURE__ */ new Set(["kind", "radius", "color", "sides", "points", "soft", "colors", "colorWeights"]);
 var KNOWN_STROKE = /* @__PURE__ */ new Set(["kind", "length", "points", "color", "width", "curve", "taper", "orient", "colors", "colorWeights"]);
 var KNOWN_EMOJI = /* @__PURE__ */ new Set(["kind", "glyphs", "cycle"]);
-var KNOWN_TEXT = /* @__PURE__ */ new Set(["kind", "strings", "color", "font", "align", "baseline", "maxWidth", "cycle"]);
-var KNOWN_TEXT_BLOCK = /* @__PURE__ */ new Set(["kind", "text", "maxWidth", "fontSize", "lineHeight", "align", "color", "reveal"]);
+var KNOWN_TEXT = /* @__PURE__ */ new Set(["kind", "strings", "color", "font", "align", "baseline", "maxWidth", "cycle", "role"]);
+var KNOWN_TEXT_BLOCK = /* @__PURE__ */ new Set(["kind", "text", "maxWidth", "fontSize", "lineHeight", "align", "color", "reveal", "anchor", "font", "opacity", "role"]);
+var TEXT_ROLES = /* @__PURE__ */ new Set(["read", "atmosphere"]);
+var TEXT_BLOCK_ANCHORS = /* @__PURE__ */ new Set(["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"]);
+var FONT_SIZE_RE = /\d(?:px|pt|pc|em|rem|ex|ch|vw|vh|vmin|vmax|%)/i;
 var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret", "fade"]);
 var KNOWN_REVEAL_CARET = /* @__PURE__ */ new Set(["blink", "color"]);
 var KNOWN_DRIFT = /* @__PURE__ */ new Set(["type", "speed", "angle", "bidirectional", "bob", "ease"]);
@@ -660,6 +724,9 @@ function validateSprite(sprite, path, err, warn) {
       err(`${path}.strings`, "must be a non-empty array of strings");
     }
     if (sprite.color !== void 0) color(sprite.color, `${path}.color`, err);
+    if (sprite.font !== void 0 && !isStr(sprite.font)) {
+      err(`${path}.font`, "must be a string");
+    }
     if (sprite.align !== void 0 && !["left", "center", "right"].includes(sprite.align)) {
       err(`${path}.align`, "must be left | center | right");
     }
@@ -669,6 +736,7 @@ function validateSprite(sprite, path, err, warn) {
     if (sprite.maxWidth !== void 0 && (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0)) {
       err(`${path}.maxWidth`, "must be a positive number");
     }
+    validateTextRole(sprite, path, err);
     validateCycle(sprite, path, err);
   } else if (sprite.kind === "circle") {
     knownSet = KNOWN_CIRCLE;
@@ -755,6 +823,20 @@ function validateSprite(sprite, path, err, warn) {
       err(`${path}.align`, "must be 'left' | 'center' | 'right'");
     }
     if (sprite.color !== void 0) color(sprite.color, `${path}.color`, err);
+    if (sprite.anchor !== void 0 && !TEXT_BLOCK_ANCHORS.has(sprite.anchor)) {
+      err(`${path}.anchor`, "must be 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right'");
+    }
+    if (sprite.font !== void 0) {
+      if (!isStr(sprite.font) || sprite.font.trim() === "") {
+        err(`${path}.font`, "must be a non-empty string (family and/or weight)");
+      } else if (FONT_SIZE_RE.test(sprite.font)) {
+        err(`${path}.font`, "must name a family and/or weight only \u2014 fontSize owns the size");
+      }
+    }
+    if (sprite.opacity !== void 0 && (!isNum(sprite.opacity) || sprite.opacity < 0 || sprite.opacity > 1)) {
+      err(`${path}.opacity`, "must be a number between 0 and 1");
+    }
+    validateTextRole(sprite, path, err);
     if (sprite.reveal !== void 0) {
       const rv = sprite.reveal;
       if (typeof rv !== "object" || rv === null || Array.isArray(rv)) {
@@ -821,6 +903,11 @@ function validatePalette(sprite, path, err) {
     }
   }
 }
+function validateTextRole(sprite, path, err) {
+  if (sprite.role !== void 0 && !TEXT_ROLES.has(sprite.role)) {
+    err(`${path}.role`, "must be 'read' | 'atmosphere'");
+  }
+}
 function validateCycle(sprite, path, err) {
   if (sprite.cycle === void 0) return;
   if (!isObj(sprite.cycle)) return err(`${path}.cycle`, "must be an object");
@@ -993,6 +1080,7 @@ function validateSequence(seq) {
       }
     }
   }
+  if (isObj(seq) && isObj(seq.bed)) normalizeColors(seq.bed);
   const errors = [];
   const warnings = [];
   const err = (path, message) => void errors.push({ path, message });
@@ -1003,6 +1091,7 @@ function validateSequence(seq) {
   if (!isStr(seq.label) || seq.label.trim() === "") err("label", "must be a non-empty string");
   if (seq.seed !== void 0 && !isNum(seq.seed)) err("seed", "must be a number");
   if (typeof seq.loop !== "boolean") err("loop", "must be a boolean");
+  if (seq.sync !== void 0 && seq.sync !== "mount" && seq.sync !== "epoch") err("sync", "must be 'mount' | 'epoch'");
   if (!Array.isArray(seq.segments) || seq.segments.length === 0) {
     err("segments", "must be a non-empty array");
     return { valid: false, errors, warnings };
@@ -1045,12 +1134,19 @@ function validateSequence(seq) {
     if (s.transition !== void 0) {
       if (!isObj(s.transition)) {
         err(`${p}.transition`, "must be an object");
-      } else if (s.transition.type === "morph") {
+      } else if (s.transition.type === "morph" || s.transition.type === "fade") {
         if (!isNum(s.transition.dur) || s.transition.dur < LIMITS.minTransitionDur || s.transition.dur > LIMITS.maxTransitionDur) {
           err(`${p}.transition.dur`, `must be a number between ${LIMITS.minTransitionDur} and ${LIMITS.maxTransitionDur}`);
         }
       } else if (s.transition.type !== "cut") {
-        err(`${p}.transition.type`, "must be 'cut' or 'morph'");
+        err(`${p}.transition.type`, "must be 'cut', 'morph' or 'fade'");
+      }
+      if (isObj(s.transition) && s.transition.text !== void 0) {
+        if (s.transition.type !== "morph") {
+          err(`${p}.transition.text`, "is a morph option (fade already cross-fades whole frames; cut has no window)");
+        } else if (s.transition.text !== "step" && s.transition.text !== "crossfade") {
+          err(`${p}.transition.text`, "must be 'step' | 'crossfade'");
+        }
       }
     }
     if (isObj(s.scene)) {
@@ -1066,6 +1162,32 @@ function validateSequence(seq) {
   if (seq.loop === true && hasDurationless) {
     err("loop", "loop: true requires all segments to have a duration");
   }
+  if (seq.bed !== void 0) {
+    if (!isObj(seq.bed)) {
+      err("bed", "must be a SaverSpec object");
+    } else {
+      const bedResult = validateSpec(seq.bed);
+      for (const e of bedResult.errors) errors.push({ path: `bed.${e.path}`, message: e.message });
+      for (const w of bedResult.warnings ?? []) warnings.push({ path: `bed.${w.path}`, code: w.code, message: w.message });
+      if (bedResult.valid) {
+        const entityTotal = (spec) => isObj(spec) && Array.isArray(spec.layers) ? spec.layers.reduce((n, l) => n + (isObj(l) && isNum(l.count) ? l.count : 0), 0) : 0;
+        const bedTotal = entityTotal(seq.bed);
+        const largest = seq.segments.reduce((m, s) => Math.max(m, isObj(s) ? entityTotal(s.scene) : 0), 0);
+        if (bedTotal + largest > LIMITS.maxTotal) {
+          err("bed", `bed entities ${bedTotal} + largest segment ${largest} = ${bedTotal + largest} exceeds cap ${LIMITS.maxTotal} (the two are live at once)`);
+        }
+        seq.segments.forEach((s, i) => {
+          if (isObj(s) && isObj(s.scene) && s.scene.background !== void 0) {
+            warnings.push({
+              path: `segments[${i}].scene.background`,
+              code: "bed-hides-segment-background",
+              message: `segment ${i} declares a background but the sequence has a bed \u2014 segments render transparently over the bed, so this background is never painted`
+            });
+          }
+        });
+      }
+    }
+  }
   if (errors.length === 0 && Array.isArray(seq.segments)) {
     for (let i = 0; i < seq.segments.length; i++) {
       const s = seq.segments[i];
@@ -1080,6 +1202,12 @@ function validateSequence(seq) {
           code: "morph-structural-mismatch",
           message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
         });
+      } else if (morphNothingMorphable(s.scene, next.scene, { textCrossfade: s.transition.text === "crossfade" })) {
+        warnings.push({
+          path: `segments[${i}].transition`,
+          code: "morph-nothing-morphable",
+          message: `segments ${i}\u2192${i + 1} differ only in values morph cannot interpolate (strings such as textBlock.text step on the first frame): the morph will look like a cut \u2014 fade text via colour or reveal.progress`
+        });
       }
     }
   }
@@ -1255,7 +1383,8 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
     Math.round(layer.count * countScale),
     layer.links ? LIMITS.maxLinkLayerCount : LIMITS.maxPerLayer
   ));
-  const [smin, smax] = layer.size ?? [20, 40];
+  const defaultSize = scale === 1 ? [20, 40] : [20 / LIMITS.referenceViewport, 40 / LIMITS.referenceViewport];
+  const [smin, smax] = layer.size ?? defaultSize;
   const variants = spriteVariants(layer.sprite);
   const sprite = layer.sprite;
   const spriteColors = isShapedSprite(sprite) ? sprite.colors : void 0;
@@ -1444,6 +1573,7 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
       ...sprite.kind === "bar" ? { barIndex: i } : {},
       ...ordered ? { ordered: true } : {},
       ...orbitParent ? { orbitParent } : {},
+      ...layer.wrap === false ? { wrapDisabled: true } : {},
       ...m.type === "wander" ? {
         wander: {
           own: drawOsc(rng, meanderPx),
@@ -1635,9 +1765,10 @@ function positionAt(e, t, w, h) {
     };
   }
   if (e.motion === "rise") {
+    const y2 = e.y0 + e.vy * dt;
     return {
       x: e.x0 + (e.bob ? e.bob * Math.sin(t / 700 + e.phase) : 0),
-      y: wrap(e.y0 + e.vy * dt, -m, h + m),
+      y: e.wrapDisabled ? y2 : wrap(y2, -m, h + m),
       flip: false
     };
   }
@@ -1657,14 +1788,18 @@ function positionAt(e, t, w, h) {
       }
     }
     const margin = m + wp.margin;
+    const x2 = e.x0 + e.vx * dt + hx;
+    const y2 = e.y0 + e.vy * dt + hy;
     return {
-      x: wrap(e.x0 + e.vx * dt + hx, -margin, w + margin),
-      y: wrap(e.y0 + e.vy * dt + hy, -margin, h + margin),
+      x: e.wrapDisabled ? x2 : wrap(x2, -margin, w + margin),
+      y: e.wrapDisabled ? y2 : wrap(y2, -margin, h + margin),
       flip: e.headingLeft
     };
   }
-  const x = wrap(e.x0 + e.vx * dt, -m, w + m);
-  let y = e.vy !== 0 ? wrap(e.y0 + e.vy * dt, -m, h + m) : e.y0;
+  const rawX = e.x0 + e.vx * dt;
+  const x = e.wrapDisabled ? rawX : wrap(rawX, -m, w + m);
+  const rawY = e.y0 + e.vy * dt;
+  let y = e.vy !== 0 && !e.wrapDisabled ? wrap(rawY, -m, h + m) : rawY;
   if (e.bob) y += e.bob * Math.sin(t / 500 + e.phase);
   return { x, y, flip: e.headingLeft };
 }
@@ -1765,18 +1900,25 @@ function linkPairs(positions, k, maxDist, doWrap, w, h) {
 }
 var CHAR_NARROW = new Set(`iIljtf1!|.,;:'"()[]{}`);
 var CHAR_WIDE = new Set("mwMWGOQD@%");
-function charWidthEm(ch) {
+var MONO_FAMILY_RE = /\b(?:ui-)?mono(?:space)?\b|courier|menlo|monaco|sfmono|consolas|inconsolata|fira\s*code|source\s*code|jetbrains|ibm\s*plex\s*mono|roboto\s*mono/i;
+function textMetricsClassFor(font) {
+  return font && MONO_FAMILY_RE.test(font) ? "mono" : "proportional";
+}
+var MONO_ADVANCE_EM = 0.6;
+function charWidthEm(ch, metrics = "proportional") {
+  if (metrics === "mono") return MONO_ADVANCE_EM;
   if (ch === " " || ch === "	") return 0.3;
   if (CHAR_NARROW.has(ch)) return 0.35;
   if (CHAR_WIDE.has(ch)) return 0.72;
   return 0.55;
 }
-function textWidthEm(str) {
+function textWidthEm(str, metrics = "proportional") {
+  if (metrics === "mono") return graphemeClusters(str).length * MONO_ADVANCE_EM;
   let w = 0;
-  for (let i = 0; i < str.length; i++) w += charWidthEm(str[i]);
+  for (let i = 0; i < str.length; i++) w += charWidthEm(str[i], metrics);
   return w;
 }
-function breakTextBlock(text, maxWidthEm) {
+function breakTextBlock(text, maxWidthEm, metrics = "proportional") {
   const paragraphs = text.split("\n");
   const lines = [];
   for (const para of paragraphs) {
@@ -1790,11 +1932,11 @@ function breakTextBlock(text, maxWidthEm) {
       continue;
     }
     let lineText = words[0];
-    let lineW = textWidthEm(lineText);
-    const spaceW = charWidthEm(" ");
+    let lineW = textWidthEm(lineText, metrics);
+    const spaceW = charWidthEm(" ", metrics);
     for (let i = 1; i < words.length; i++) {
       const word = words[i];
-      const wordW = textWidthEm(word);
+      const wordW = textWidthEm(word, metrics);
       if (lineW + spaceW + wordW <= maxWidthEm) {
         lineText += " " + word;
         lineW += spaceW + wordW;
@@ -1808,6 +1950,13 @@ function breakTextBlock(text, maxWidthEm) {
   }
   return lines;
 }
+function textBlockAnchorOffset(s, maxWPx, maxLineW, totalH) {
+  if (!s.anchor) return { dx: 0, dy: 0 };
+  const ax = s.anchor.endsWith("left") ? 0 : s.anchor.endsWith("right") ? 1 : 0.5;
+  const ay = s.anchor.startsWith("top") ? 0 : s.anchor.startsWith("bottom") ? 1 : 0.5;
+  const inkX0 = s.align === "center" ? (maxWPx - maxLineW) / 2 : s.align === "right" ? maxWPx - maxLineW : 0;
+  return { dx: -(inkX0 + ax * maxLineW), dy: -(ay * totalH) };
+}
 function isClusterExtend(cp) {
   return cp >= 768 && cp <= 879 || // combining diacritics
   cp >= 6832 && cp <= 6911 || cp >= 8400 && cp <= 8447 || cp >= 65024 && cp <= 65039 || // variation selectors
@@ -1955,9 +2104,45 @@ function resolveSegment(seq, T, opts = {}) {
   const lastStart = totalTimed - (segments[last].duration ?? 0);
   return { index: last, localT: t0 - lastStart, startT: lastStart };
 }
+function canMorph(seq, from) {
+  const seg = seq.segments[from];
+  if (!seg || seg.transition?.type !== "morph") return false;
+  const next = seq.segments[from + 1];
+  if (!next) return false;
+  return structuralSignature(seg.scene) === structuralSignature(next.scene);
+}
+function morphChainRoot(seq, index) {
+  let i = index;
+  while (i > 0 && canMorph(seq, i - 1)) i--;
+  return i;
+}
+function normalizeSeed(seed) {
+  return seed >>> 0 || 1;
+}
+function segmentRenderSeed(seq, index) {
+  const root = morphChainRoot(seq, index);
+  const scene = seq.segments[root]?.scene;
+  if (!scene) return void 0;
+  const raw = scene.seed ?? (seq.seed !== void 0 ? seq.seed + root : void 0);
+  return raw === void 0 ? void 0 : normalizeSeed(raw);
+}
+function bedRenderSeed(seq) {
+  if (!seq.bed) return void 0;
+  const raw = seq.bed.seed ?? (seq.seed !== void 0 ? seq.seed + LIMITS.maxSegments : void 0);
+  return raw === void 0 ? void 0 : normalizeSeed(raw);
+}
 
 // src/compile.ts
 var DEFAULT_STEER_DUR = 1e3;
+function applyRetainedDeltas(spec, deltas) {
+  let out = spec;
+  for (const d of deltas) {
+    if (!resolveSpecPath(out, d.path)) continue;
+    const next = applyDeltasToSpec(out, [d]);
+    if (validateSpec(next).valid) out = next;
+  }
+  return out;
+}
 function hexToRgba(hex, alpha) {
   const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
   const n = parseInt(h.slice(1), 16);
@@ -1995,11 +2180,12 @@ function manifestFor(spec) {
   };
 }
 var SpecInstance = class {
-  constructor(spec, ctx) {
+  constructor(spec, ctx, opts = {}) {
     this.spec = spec;
     this.effSpec = spec;
     this.saverCtx = ctx;
-    this.seed = (spec.seed ?? ctx.seed) >>> 0 || 1;
+    this.transparent = opts.transparent === true;
+    this.seed = normalizeSeed(spec.seed ?? ctx.seed);
     let canvas;
     if (ctx.surface) {
       canvas = ctx.surface;
@@ -2013,7 +2199,7 @@ var SpecInstance = class {
       this.ownsCanvas = true;
     }
     this.canvas = canvas;
-    const c2d = canvas.getContext("2d", { alpha: false });
+    const c2d = canvas.getContext("2d", { alpha: this.transparent });
     if (!c2d) throw new Error("schema saver: no 2d context");
     this.ctx = c2d;
     this.w = ctx.width;
@@ -2021,12 +2207,16 @@ var SpecInstance = class {
     this.sizeCanvas();
     this.rebuild();
     this.paused = ctx.reducedMotion;
-    if (this.paused) this.renderFrame(0, this.seed);
-    else this.start();
+    if (this.paused) {
+      if (!opts.skipInitialPaint) this.renderFrame(0, this.seed);
+    } else {
+      this.start();
+    }
   }
   spec;
   canvas;
   ownsCanvas;
+  transparent;
   ctx;
   saverCtx;
   seed;
@@ -2046,6 +2236,8 @@ var SpecInstance = class {
   /** Active glide between two resolved specs (live setParam/applyTrack). */
   transition = null;
   lastStructural = "";
+  /** See `LayerPaintOverride`; null (the default, and every plain mount) draws every layer once. */
+  paintOverrides = null;
   /** Viewport factor for absolute px sizes — 1 for `units: 'px'` specs. */
   fontScale() {
     if (this.effSpec.units === "px") return 1;
@@ -2182,14 +2374,14 @@ var SpecInstance = class {
       ctx.fill();
     }
   }
-  drawEntity(built, e, t, lifeA, parentE) {
+  drawEntity(built, e, t, lifeA, parentE, paint) {
     const { ctx } = this;
     const p = this.entityPos(e, t, parentE);
-    const sprite = built.layer.sprite;
+    const sprite = paint?.sprite ?? built.layer.sprite;
     const sz = sizeAt(e, t);
     const rot = rotationAt(e, t);
     const unitScale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
-    ctx.globalAlpha = alphaAt(e, t) * lifeA;
+    ctx.globalAlpha = alphaAt(e, t) * lifeA * (paint?.alpha ?? 1);
     if (sprite.kind === "ring") {
       const r = sz / 2;
       const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
@@ -2341,7 +2533,7 @@ var SpecInstance = class {
       const lh = (sprite.lineHeight ?? 1.4) * fsPx;
       const maxWPx = sprite.maxWidth * unitScale2;
       const maxWEm = maxWPx / fsPx;
-      const lines = breakTextBlock(sprite.text, maxWEm);
+      const lines = breakTextBlock(sprite.text, maxWEm, textMetricsClassFor(sprite.font));
       const align = sprite.align ?? "left";
       const reveal = sprite.reveal;
       const rs = reveal ? revealState(lines, reveal, t) : null;
@@ -2349,7 +2541,13 @@ var SpecInstance = class {
       ctx.save();
       ctx.translate(p.x, p.y);
       if (rot) ctx.rotate(rot);
-      ctx.font = `${fsPx}px system-ui, sans-serif`;
+      if (sprite.anchor) {
+        const maxLineW = lines.reduce((m, l) => Math.max(m, l.widthEm), 0) * fsPx;
+        const { dx, dy } = textBlockAnchorOffset(sprite, maxWPx, maxLineW, lines.length * lh);
+        if (dx !== 0 || dy !== 0) ctx.translate(dx, dy);
+      }
+      if (sprite.opacity !== void 0) ctx.globalAlpha *= sprite.opacity;
+      ctx.font = sprite.font ? composeFontShorthand(fsPx, sprite.font) : `${fsPx}px system-ui, sans-serif`;
       ctx.fillStyle = sprite.color ?? "#e6e8ef";
       ctx.textBaseline = "top";
       ctx.textAlign = align;
@@ -2463,6 +2661,33 @@ var SpecInstance = class {
       this.renderFrame(this.lastT, this.seed);
     }
   }
+  /**
+   * Apply steering deltas immediately: no glide, no frame painted. Each delta
+   * is routed by `applyRetainedDeltas` (unresolvable or invalid ones are
+   * skipped on this spec alone). `SequenceInstance` uses this to hand a
+   * freshly created child the track the sequence has retained, so a steer
+   * made while another segment was active lands on the segment that owns the
+   * path. Not painting matters: a child is created inside the parent's
+   * renderFrame, and a stray t=0 paint here would make the real frame that
+   * follows look "contiguous" to the ghosting warm-up — but the constructor
+   * already painted ONE stray t=0 frame of the pre-steer spec (SpecInstance's
+   * own mount does an immediate render when paused, which every sequence
+   * child is), so `lastRenderT` must be reset too: otherwise, with `ghosting`
+   * on, the real frame that follows still finds itself "contiguous" with
+   * that stray paint and composites over it at partial alpha, briefly
+   * showing a ghost of the un-steered scene.
+   */
+  applyDeltasNow(deltas) {
+    const next = applyRetainedDeltas(this.effSpec, deltas);
+    if (next === this.effSpec) return;
+    this.transition = null;
+    this.lastRenderT = Number.NEGATIVE_INFINITY;
+    this.effSpec = next;
+    if (structuralSignature(this.effSpec) !== this.lastStructural) this.rebuild();
+    else this.layers.forEach((b, i) => {
+      b.layer = this.effSpec.layers[i] ?? b.layer;
+    });
+  }
   drawLinks(built, t, lifeA, parentE) {
     const { links } = built.layer;
     if (!links) return;
@@ -2472,7 +2697,9 @@ var SpecInstance = class {
     const positions = built.entities.map((e) => this.entityPos(e, t, parentE));
     const maxDistPx = links.maxDist * (this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h));
     const edges = linkEdges(links, positions, maxDistPx, wrap2, this.w, this.h);
-    const lw = (links.width ?? 1) * (this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h));
+    const unitScale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
+    const defaultWidth = unitScale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+    const lw = (links.width ?? defaultWidth) * unitScale;
     ctx.lineWidth = lw;
     ctx.lineCap = "butt";
     for (const { i, j, dist } of edges) {
@@ -2506,19 +2733,28 @@ var SpecInstance = class {
    *  showing through — the ghosting smear. */
   paintFrame(t, bgAlpha) {
     const { ctx } = this;
-    ctx.globalAlpha = bgAlpha;
-    ctx.globalCompositeOperation = "source-over";
-    this.drawBackground(t);
+    if (!this.transparent) {
+      ctx.globalAlpha = bgAlpha;
+      ctx.globalCompositeOperation = "source-over";
+      this.drawBackground(t);
+    }
     ctx.globalAlpha = 1;
-    for (const built of this.layers) {
+    for (let li = 0; li < this.layers.length; li++) {
+      const built = this.layers[li];
       const lifeA = lifeAlphaAt(built.layer.life, t);
       if (lifeA <= 0) continue;
       const parentE = this.parentEntityFor(built);
       ctx.globalCompositeOperation = built.layer.blend ?? "source-over";
       this.drawLinks(built, t, lifeA, parentE);
+      const override = this.paintOverrides?.get(li) ?? null;
       for (const e of built.entities) {
         this.drawTrail(built, e, t, lifeA, parentE);
-        this.drawEntity(built, e, t, lifeA, parentE);
+        if (override === null) {
+          this.drawEntity(built, e, t, lifeA, parentE);
+          continue;
+        }
+        if (override.k < 1) this.drawEntity(built, e, t, lifeA, parentE, { sprite: override.outgoing, alpha: 1 - override.k });
+        if (override.k > 0) this.drawEntity(built, e, t, lifeA, parentE, { alpha: override.k });
       }
     }
     ctx.globalAlpha = 1;
@@ -2535,7 +2771,7 @@ var SpecInstance = class {
    */
   renderFrame(t, _seed) {
     this.stepTransition(t);
-    const g = this.effSpec.ghosting ?? 0;
+    const g = this.transparent ? 0 : this.effSpec.ghosting ?? 0;
     if (g > 0) {
       const dt = 1e3 / 60;
       const contiguous = this.lastRenderT !== Number.NEGATIVE_INFINITY && t > this.lastRenderT && t - this.lastRenderT <= 250;
@@ -2571,8 +2807,8 @@ var SpecInstance = class {
   }
   /**
    * Replace the rendered spec without triggering a transition glide.
-   * Checks structural signature — use `hotSwapPaint` when the caller
-   * already knows the signature is unchanged (e.g. mid-morph lerp).
+   * Checks structural signature — use `hotSwapPaint` only when the caller
+   * already knows the signature is unchanged.
    */
   hotSwapSpec(spec) {
     this.effSpec = spec;
@@ -2589,6 +2825,15 @@ var SpecInstance = class {
       b.layer = this.effSpec.layers[i] ?? b.layer;
     });
   }
+  /**
+   * Internal (see `LayerPaintOverride`): draw the listed layers twice —
+   * outgoing sprite at `1 − k`, own sprite at `k` — until cleared with
+   * `null`. Keyed by layer index. A `SequenceInstance` sets it per morph
+   * frame under `text: 'crossfade'`; nothing else does.
+   */
+  setLayerPaintOverrides(overrides) {
+    this.paintOverrides = overrides && overrides.size > 0 ? overrides : null;
+  }
   dispose() {
     this.stop();
     if (this.ownsCanvas && typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
@@ -2602,6 +2847,7 @@ function compileSaver(spec) {
     spec: valid
   };
 }
+var BED_PREFIX = "bed.";
 var SequenceInstance = class {
   seq;
   childCtx;
@@ -2632,8 +2878,55 @@ var SequenceInstance = class {
    */
   clockOffset = 0;
   releasedBelow = 0;
+  /**
+   * Set by a `sequence.segment` steer that targets segment 0 under `loop:
+   * true`: the steer resets the clock to segment 0's own start (localT 0),
+   * so `renderFrame`'s wrap check (which compares the raw, ever-increasing
+   * clock against `timedTotal()`) can no longer recognize the jump as a
+   * wrap. This flag lets the clicker's jump to 0 still count as one, so the
+   * last segment's fade plays instead of a hard cut. Cleared once the wrap
+   * window (if any) has passed.
+   */
+  pendingWrapFade = false;
+  /**
+   * Every non-`sequence.segment` delta this instance has been handed, last
+   * wins per path, merged across `applyTrack` calls. Children are created
+   * lazily and disposed on every segment switch, so a steer forwarded only
+   * to the active child would evaporate at the next boundary — and a steer
+   * to a path only a *later* segment owns (`bars.sprite.values` while the title
+   * slide is up) would land nowhere. Re-applied to every child on creation
+   * and folded into the morph endpoints; each child keeps the deltas that
+   * resolve on it (see `applyRetainedDeltas`).
+   */
+  retainedDeltas = /* @__PURE__ */ new Map();
+  /** The outgoing segment while a `fade` runs; null otherwise. */
+  fading = null;
+  /**
+   * The incoming segment while a `fade` runs over a `bed`. Children over a
+   * bed are transparent, so a cross-fade needs both of them on canvases of
+   * their own — the incoming composited at k, the outgoing at 1 − k. Without
+   * a bed the incoming paints its own opaque ground on the shared surface and
+   * this stays null.
+   */
+  fadingIn = null;
+  /** False on the `basic`/`minimal` capability tiers — fade renders as cut. */
+  fadeEnabled;
+  /**
+   * The sequence's `bed`: one scene on the shared surface, drawn first every
+   * frame at the sequence clock — WITHOUT `clockOffset`, so a
+   * `sequence.segment` steer rewinds the segment and never the bed — and never
+   * re-created. Segments render over it transparently. Null when absent.
+   */
+  bed;
   constructor(seq, ctx) {
     this.seq = seq;
+    const { sequenceBaseT, capabilityTier, ...plainCtx } = ctx;
+    this.fadeEnabled = capabilityTier !== "basic" && capabilityTier !== "minimal";
+    if (seq.sync === "epoch" && typeof sequenceBaseT === "number" && Number.isFinite(sequenceBaseT)) {
+      this.baseT = Math.max(0, sequenceBaseT);
+      this.lastT = this.baseT;
+      this.renderedT = this.baseT;
+    }
     let surface = ctx.surface ?? null;
     let canvas = null;
     if (!surface && typeof document !== "undefined") {
@@ -2645,15 +2938,32 @@ var SequenceInstance = class {
     }
     this.canvas = canvas;
     this.seed = (seq.seed ?? ctx.seed ?? 0) >>> 0 || 1;
-    this.childCtx = { ...ctx, surface, reducedMotion: true };
+    this.childCtx = { ...plainCtx, surface, reducedMotion: true };
     this.children = new Array(seq.segments.length).fill(null);
+    if (seq.bed) {
+      this.bed = new SpecInstance(this.bedScene(seq.bed), this.childCtx);
+      this.bed.setPaused(true);
+    } else {
+      this.bed = null;
+    }
     this.paused = ctx.reducedMotion;
-    if (this.paused) this.renderFrame(0, this.seed);
+    if (this.paused) this.renderFrame(this.baseT, this.seed);
     else this.start();
   }
   childSeed(index, fallback) {
     return this.seq.segments[index].scene.seed ?? this.seq.seed ?? fallback;
   }
+  /**
+   * The bed's seed follows the segment rule (own seed, else the sequence seed)
+   * but offset by `maxSegments`, past every segment's `seed + index`, so a bed
+   * and segment 0 never share an entity stream and adding a segment does not
+   * re-seat the bed.
+   */
+  bedScene(bed) {
+    if (bed.seed != null) return bed;
+    if (this.seq.seed != null) return { ...bed, seed: this.seq.seed + LIMITS.maxSegments };
+    return bed;
+  }
   childScene(index) {
     const seg = this.seq.segments[index];
     if (seg.scene.seed != null) return seg.scene;
@@ -2662,29 +2972,132 @@ var SequenceInstance = class {
   }
   /** Whether the boundary from `from` to `from+1` should morph. */
   canMorph(from) {
-    const seg = this.seq.segments[from];
-    if (!seg || seg.transition?.type !== "morph") return false;
-    const next = this.seq.segments[from + 1];
-    if (!next) return false;
-    return structuralSignature(seg.scene) === structuralSignature(next.scene);
+    return canMorph(this.seq, from);
   }
   /** Walk back through consecutive morph boundaries to find the chain origin. */
   morphChainRoot(index) {
-    let i = index;
-    while (i > 0 && this.canMorph(i - 1)) i--;
-    return i;
+    return morphChainRoot(this.seq, index);
   }
   morphDur(from) {
     const tr = this.seq.segments[from]?.transition;
     return tr?.type === "morph" ? tr.dur : 0;
   }
-  ensureChild(index) {
+  /** Whether the morph out of `from` cross-fades its text (default `step`: strings switch at k > 0). */
+  morphTextCrossfades(from) {
+    const tr = this.seq.segments[from]?.transition;
+    return tr?.type === "morph" && tr.text === "crossfade";
+  }
+  /**
+   * The paint overrides for one crossfade frame: every text layer whose
+   * words differ between the outgoing and incoming specs, painting the
+   * outgoing words (in the lerped frame's paint — colour and alpha glide as
+   * usual) at `1 − k` under the incoming at `k`. Null when nothing differs,
+   * so a crossfade between same-worded twins is a plain morph frame.
+   */
+  crossfadeOverrides(specA, specB, lerped, k) {
+    let map = null;
+    for (let i = 0; i < lerped.layers.length; i++) {
+      if (!textStringsDiffer(specA, specB, i)) continue;
+      const from = specA.layers[i].sprite;
+      const now = lerped.layers[i].sprite;
+      const outgoing = from.kind === "text" && now.kind === "text" ? { ...now, strings: from.strings } : from.kind === "textBlock" && now.kind === "textBlock" ? { ...now, text: from.text } : now;
+      if (outgoing === now) continue;
+      (map ??= /* @__PURE__ */ new Map()).set(i, { outgoing, k });
+    }
+    return map;
+  }
+  /** Length of the fade out of segment `from`, or 0 (no fade, or a tier that plays it as cut). */
+  fadeDur(from) {
+    const tr = this.seq.segments[from]?.transition;
+    return this.fadeEnabled && tr?.type === "fade" ? tr.dur : 0;
+  }
+  /** Sum of every timed segment — the lap length under `loop: true`. */
+  timedTotal() {
+    const last = this.seq.segments.length - 1;
+    return segmentStart(this.seq, last) + (this.seq.segments[last].duration ?? 0);
+  }
+  releaseFading() {
+    if (this.fading) {
+      this.fading.child.dispose();
+      this.fading = null;
+    }
+    if (this.fadingIn) {
+      this.fadingIn.child.dispose();
+      this.fadingIn = null;
+    }
+  }
+  /**
+   * A segment child on a canvas of its own. Like a morph it mounts on its
+   * chain root's scene and seed (so its entities are the ones the viewer was
+   * watching) and hot-swaps to the segment's spec; the retained track is
+   * applied last. Transparent over a bed, opaque otherwise.
+   */
+  offscreenChild(index, root) {
+    const canvas = typeof document !== "undefined" ? document.createElement("canvas") : new OffscreenCanvas(Math.max(1, this.childCtx.width), Math.max(1, this.childCtx.height));
+    const child = new SpecInstance(this.childScene(root), { ...this.childCtx, surface: canvas }, { transparent: this.bed !== null });
+    child.setPaused(true);
+    if (root !== index) child.hotSwapSpec(this.childScene(index));
+    if (this.retainedDeltas.size > 0) child.applyDeltasNow(this.retainedDeltas.values());
+    return { index, child, canvas };
+  }
+  /** Render an offscreen child; a transparent one never clears, so its owner does here. */
+  renderOffscreen(oc, t, seed) {
+    if (this.bed) {
+      const c = oc.canvas.getContext("2d");
+      c?.clearRect(0, 0, this.childCtx.width, this.childCtx.height);
+    }
+    oc.child.renderFrame(t, seed);
+  }
+  /** Draw an offscreen canvas onto the shared surface at `alpha`. */
+  composite(canvas, alpha) {
+    const main = this.childCtx.surface?.getContext("2d");
+    if (!main) return;
+    main.save();
+    main.globalAlpha = alpha;
+    main.globalCompositeOperation = "source-over";
+    main.drawImage(canvas, 0, 0, this.childCtx.width, this.childCtx.height);
+    main.restore();
+  }
+  /**
+   * Render the outgoing segment `from` of a live fade onto its own canvas. It
+   * keeps animating at `duration(from) + localT` (it does not freeze — and if
+   * it was an `advance: 'input'` hold it resumes from its duration, not from
+   * wherever the hold had reached). Two live segments for `dur` only; the
+   * outgoing one is disposed when the fade ends.
+   */
+  renderOutgoing(from, localT, seed) {
+    if (this.fading && this.fading.index !== from) {
+      this.fading.child.dispose();
+      this.fading = null;
+    }
+    if (!this.fading) this.fading = this.offscreenChild(from, this.morphChainRoot(from));
+    const outDur = this.seq.segments[from].duration ?? 0;
+    this.renderOffscreen(this.fading, outDur + localT, this.childSeed(this.morphChainRoot(from), seed));
+    return this.fading;
+  }
+  /** A segment's scene with the retained track applied — `scene` itself when nothing resolves on it. */
+  steeredScene(scene) {
+    return this.retainedDeltas.size === 0 ? scene : applyRetainedDeltas(scene, this.retainedDeltas.values());
+  }
+  /**
+   * The child for segment `index`, created paused on the shared surface if
+   * the slot is empty. `rootScene` (a morph chain's root) mounts the child
+   * with the root's scene so its seed and entity placement are continuous
+   * with the chain, then hot-swaps to the segment's own spec. Either way the
+   * retained track is applied last, so a steer made while another segment
+   * was up is already in effect on this child's first frame. `skipInitialPaint`
+   * is for a caller (the morph branch) that is about to render a real frame,
+   * paint overrides included, in this same call — see `SpecInstanceOptions`.
+   */
+  ensureChild(index, rootScene, skipInitialPaint) {
     if (index < 0 || index >= this.seq.segments.length) index = 0;
     let child = this.children[index];
     if (!child) {
-      child = new SpecInstance(this.childScene(index), this.childCtx);
+      child = new SpecInstance(rootScene ?? this.childScene(index), this.childCtx, { transparent: this.bed !== null, skipInitialPaint });
       this.children[index] = child;
       child.setPaused(true);
+      if (rootScene) child.hotSwapSpec(this.childScene(index));
+      if (this.retainedDeltas.size > 0) child.applyDeltasNow(this.retainedDeltas.values());
     }
     return child;
   }
@@ -2717,8 +3130,15 @@ var SequenceInstance = class {
     this.renderedT = T;
     const resolved = resolveSegment(this.seq, T + this.clockOffset, { releasedBelow: this.releasedBelow });
     const { index, localT } = resolved;
+    this.bed?.renderFrame(T, this.seq.bed?.seed ?? this.seq.seed ?? seed);
     const prevIdx = index > 0 ? index - 1 : -1;
     const morphActive = prevIdx >= 0 && this.canMorph(prevIdx) && localT < this.morphDur(prevIdx);
+    const lastIdx = this.seq.segments.length - 1;
+    const wrapped = this.seq.loop && index === 0 && lastIdx > 0 && (T + this.clockOffset >= this.timedTotal() || this.pendingWrapFade);
+    const fadeFrom = prevIdx >= 0 ? prevIdx : wrapped ? lastIdx : -1;
+    const fadeActive = fadeFrom >= 0 && localT < this.fadeDur(fadeFrom);
+    if (!fadeActive && this.fading) this.releaseFading();
+    if (this.pendingWrapFade && (index !== 0 || !fadeActive)) this.pendingWrapFade = false;
     if (morphActive) {
       const chainRoot = this.morphChainRoot(index);
       this.morphFromIndex = prevIdx;
@@ -2726,12 +3146,14 @@ var SequenceInstance = class {
       for (let i = 0; i < this.children.length; i++) {
         if (i !== chainRoot) this.releaseChild(i);
       }
-      const child = this.ensureChild(chainRoot);
+      const child = this.ensureChild(chainRoot, void 0, this.morphTextCrossfades(prevIdx));
       const dur = this.morphDur(prevIdx);
       const k = easeSmooth(localT / dur);
-      const specA = this.childScene(prevIdx);
-      const specB = this.childScene(index);
-      child.hotSwapPaint(lerpSpec(specA, specB, k));
+      const specA = this.steeredScene(this.childScene(prevIdx));
+      const specB = this.steeredScene(this.childScene(index));
+      const lerped = lerpSpec(specA, specB, k);
+      child.hotSwapSpec(lerped);
+      child.setLayerPaintOverrides(this.morphTextCrossfades(prevIdx) ? this.crossfadeOverrides(specA, specB, lerped, k) : null);
       child.renderFrame(localT, this.childSeed(chainRoot, seed));
     } else {
       if (this.morphFromIndex >= 0) {
@@ -2749,18 +3171,25 @@ var SequenceInstance = class {
       const chainRoot = this.morphChainRoot(index);
       const useMorphSeed = chainRoot < index;
       const effSeed = useMorphSeed ? this.childSeed(chainRoot, seed) : this.childSeed(index, seed);
-      let child;
-      if (useMorphSeed && !this.children[index]) {
-        const rootScene = this.childScene(chainRoot);
-        child = new SpecInstance(rootScene, this.childCtx);
-        this.children[index] = child;
-        child.setPaused(true);
-        child.hotSwapSpec(this.childScene(index));
-      } else {
-        child = this.ensureChild(index);
-        if (useMorphSeed) child.hotSwapSpec(this.childScene(index));
+      if (fadeActive && this.bed) {
+        const k = easeSmooth(localT / this.fadeDur(fadeFrom));
+        if (this.fadingIn && this.fadingIn.index !== index) {
+          this.fadingIn.child.dispose();
+          this.fadingIn = null;
+        }
+        if (!this.fadingIn) this.fadingIn = this.offscreenChild(index, useMorphSeed ? chainRoot : index);
+        this.renderOffscreen(this.fadingIn, localT, effSeed);
+        const out = this.renderOutgoing(fadeFrom, localT, seed);
+        this.composite(this.fadingIn.canvas, k);
+        this.composite(out.canvas, 1 - k);
+        return;
       }
+      const child = useMorphSeed ? this.ensureChild(index, this.childScene(chainRoot)) : this.ensureChild(index);
       child.renderFrame(localT, effSeed);
+      if (fadeActive) {
+        const out = this.renderOutgoing(fadeFrom, localT, seed);
+        this.composite(out.canvas, 1 - easeSmooth(localT / this.fadeDur(fadeFrom)));
+      }
     }
   }
   setPaused(paused) {
@@ -2770,6 +3199,9 @@ var SequenceInstance = class {
     for (const child of this.children) {
       child?.setPaused(true);
     }
+    this.fading?.child.setPaused(true);
+    this.fadingIn?.child.setPaused(true);
+    this.bed?.setPaused(true);
   }
   resize(width, height, dpr) {
     this.childCtx.width = width;
@@ -2778,35 +3210,58 @@ var SequenceInstance = class {
     for (const child of this.children) {
       child?.resize(width, height, dpr);
     }
+    this.fading?.child.resize(width, height, dpr);
+    this.fadingIn?.child.resize(width, height, dpr);
+    this.bed?.resize(width, height, dpr);
   }
   applyTrack(track) {
-    const deltas = track?.deltas ?? [];
+    const all = track?.deltas ?? [];
+    const isBedPath = (d) => this.bed !== null && typeof d.path === "string" && d.path.startsWith(BED_PREFIX);
+    const bedDeltas = all.filter(isBedPath).map((d) => ({ ...d, path: d.path.slice(BED_PREFIX.length) }));
+    if (bedDeltas.length > 0) this.bed.applyTrack({ ...track, deltas: bedDeltas });
+    const deltas = all.filter((d) => !isBedPath(d));
+    for (const d of deltas) {
+      if (d.path !== "sequence.segment" && typeof d.path === "string") this.retainedDeltas.set(d.path, d);
+    }
     const segDelta = deltas.find((d) => d.path === "sequence.segment");
+    let switchedSegment = false;
     if (segDelta !== void 0 && typeof segDelta.value === "number") {
       const idx = Math.max(0, Math.min(this.seq.segments.length - 1, Math.round(segDelta.value)));
+      this.pendingWrapFade = this.seq.loop && idx === 0 && this.seq.segments.length > 1;
       this.clockOffset = segmentStart(this.seq, idx) - this.renderedT;
       this.releasedBelow = idx;
       this.renderFrame(this.renderedT, this.seed);
+      switchedSegment = true;
     }
     const childDeltas = deltas.filter((d) => d.path !== "sequence.segment");
-    if (childDeltas.length > 0 && this.activeIndex >= 0) {
-      const child = this.children[this.activeIndex];
-      child?.applyTrack({ ...track, deltas: childDeltas });
+    if (childDeltas.length > 0) {
+      if (this.morphFromIndex >= 0) {
+        if (!switchedSegment) this.renderFrame(this.renderedT, this.seed);
+      } else if (this.activeIndex >= 0) {
+        const child = this.children[this.activeIndex];
+        child?.applyTrack({ ...track, deltas: childDeltas });
+      }
+      this.fading?.child.applyTrack({ ...track, deltas: childDeltas });
+      this.fadingIn?.child.applyTrack({ ...track, deltas: childDeltas });
     }
   }
   dispose() {
     this.stop();
+    this.releaseFading();
     for (let i = 0; i < this.children.length; i++) {
       this.releaseChild(i);
     }
+    this.bed?.dispose();
     if (this.canvas) this.canvas.remove();
   }
 };
 function sequenceManifest(seq) {
-  const maxTotal = seq.segments.reduce((max, s) => {
+  const maxSegment = seq.segments.reduce((max, s) => {
     const t = s.scene.layers.reduce((n, l) => n + l.count, 0);
     return Math.max(max, t);
   }, 0);
+  const bedTotal = seq.bed ? seq.bed.layers.reduce((n, l) => n + l.count, 0) : 0;
+  const maxTotal = bedTotal + maxSegment;
   const costTier = maxTotal < 30 ? "idle" : maxTotal < 150 ? "low" : maxTotal < 400 ? "medium" : "high";
   return {
     id: seq.id,
@@ -2890,6 +3345,58 @@ function colourSeparation(layer, sprite, bg) {
   const db = sprite.rgb.b - bg.rgb.b;
   return Math.sqrt((dr * dr + dg * dg + db * db) / 3);
 }
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+function relativeLuminance(rgb) {
+  return 0.2126 * srgbToLinear(rgb.r) + 0.7152 * srgbToLinear(rgb.g) + 0.0722 * srgbToLinear(rgb.b);
+}
+function legibilityRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const hi = Math.max(la, lb);
+  const lo = Math.min(la, lb);
+  return (hi + 0.05) / (lo + 0.05);
+}
+function backgroundRgbAt(spec, yPx, h, unit) {
+  const bg = spec.background;
+  if (!bg || bg.type === "solid") return hexRgb(bg?.color ?? "#05050a");
+  if (bg.band) {
+    const bh = bg.band.height * unit;
+    if (yPx >= h - bh) return hexRgb(bg.band.color);
+  }
+  const stops = [...bg.stops].sort((a, b) => a.at - b.at);
+  const y = h > 0 ? Math.max(0, Math.min(1, yPx / h)) : 0;
+  const first = stops[0];
+  const last = stops[stops.length - 1];
+  if (y <= first.at) return hexRgb(first.color);
+  if (y >= last.at) return hexRgb(last.color);
+  for (let i = 1; i < stops.length; i++) {
+    const a = stops[i - 1];
+    const b = stops[i];
+    if (y > b.at) continue;
+    const span = b.at - a.at;
+    const k = span > 0 ? (y - a.at) / span : 1;
+    const ca = hexRgb(a.color);
+    const cb = hexRgb(b.color);
+    return { r: ca.r + (cb.r - ca.r) * k, g: ca.g + (cb.g - ca.g) * k, b: ca.b + (cb.b - ca.b) * k };
+  }
+  return hexRgb(last.color);
+}
+function sourceOverPlate(ground, colour, alpha) {
+  return {
+    r: ground.r + (colour.r - ground.r) * alpha,
+    g: ground.g + (colour.g - ground.g) * alpha,
+    b: ground.b + (colour.b - ground.b) * alpha
+  };
+}
+function additivePlate(ground, colour, alpha, blend) {
+  const mix = (g, c) => {
+    const v = c * alpha;
+    return blend === "lighter" ? Math.min(1, g + v) : 1 - (1 - g) * (1 - v);
+  };
+  return { r: mix(ground.r, colour.r), g: mix(ground.g, colour.g), b: mix(ground.b, colour.b) };
+}
 
 // src/cohesion.ts
 var MERGE_FLOOR = 0.35;
@@ -3101,6 +3608,8 @@ function seamsWorthWarning(layer, c, entityCount) {
 // src/advise.ts
 var LOW_CONTRAST_FLOOR = 0.05;
 var SPARSE_DECLARED_MAX_COVERAGE = 0.02;
+var READ_LEGIBILITY_FLOOR = 4.5;
+var READ_SAFE_AREA = 0.05;
 function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   const warnings = [];
   const w = viewport.width;
@@ -3205,8 +3714,8 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
         const fsPx = layer.sprite.fontSize * scale;
         const lh = (layer.sprite.lineHeight ?? 1.4) * fsPx;
         const maxWPx = layer.sprite.maxWidth * scale;
-        const lines = breakTextBlock(layer.sprite.text, maxWPx / fsPx);
-        pixArea = maxWPx * lines.length * lh * 0.55;
+        const lines = breakTextBlock(layer.sprite.text, maxWPx / fsPx, textMetricsClassFor(layer.sprite.font));
+        pixArea = maxWPx * lines.length * lh * 0.55 * (layer.sprite.opacity ?? 1);
       } else {
         pixArea = e.size * e.size;
       }
@@ -3222,7 +3731,8 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       const positions = entities.map((e) => positionAt(e, 0, w, h));
       const maxDistPx = layer.links.maxDist * scale;
       const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false, w, h);
-      const lwPx = (layer.links.width ?? 1) * scale;
+      const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+      const lwPx = (layer.links.width ?? defaultWidth) * scale;
       const la = layer.links.alpha ?? 1;
       for (const edge of edges) totalCoverage += edge.dist * lwPx * la / (w * h);
     }
@@ -3325,9 +3835,16 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     for (const e of allEntities[li]) {
       const p = positionAt(e, 0, w, h);
       const box = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
-      textBoxes.push({ li, label, ...box });
+      const alpha = Math.max(0, Math.min(1, e.alpha - e.pulseAmp)) * (s.kind === "textBlock" ? s.opacity ?? 1 : 1);
+      textBoxes.push({ li, label, alpha, ...box });
     }
   }
+  const asFraction = (b) => ({
+    x: +(b.x0 / w).toFixed(4),
+    y: +(b.y0 / h).toFixed(4),
+    w: +((b.x1 - b.x0) / w).toFixed(4),
+    h: +((b.y1 - b.y0) / h).toFixed(4)
+  });
   const tolX = w * 0.01;
   const tolY = h * 0.01;
   const offFlagged = /* @__PURE__ */ new Set();
@@ -3366,12 +3883,109 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       warnings.push({
         path: `layers[${first.li}]`,
         code: "text-overlap",
-        message: `${first.label} and ${second.label} text boxes overlap (~${Math.round(share * 100)}% of the smaller one) \u2014 they will paint over each other; move one or shrink it`
+        message: `${first.label} and ${second.label} text boxes overlap (~${Math.round(share * 100)}% of the smaller one) \u2014 they will paint over each other; move one or shrink it`,
+        // The two boxes, so an agent can move one without re-deriving the
+        // layout. Additive: the message is unchanged.
+        boxes: [asFraction(first), asFraction(second)]
+      });
+    }
+  }
+  const readFlagged = /* @__PURE__ */ new Set();
+  for (const b of textBoxes) {
+    if (readFlagged.has(b.li)) continue;
+    const layer = spec.layers[b.li];
+    const s = layer.sprite;
+    if (s.kind !== "text" && s.kind !== "textBlock" || s.role !== "read") continue;
+    const boxes = textBoxes.filter((x) => x.li === b.li);
+    readFlagged.add(b.li);
+    const ink = hexRgb(s.color ?? "#e6e8ef");
+    const textPlate = (base, alpha) => {
+      if (layer.blend === "lighter" || layer.blend === "screen") return additivePlate(base, ink, alpha, layer.blend);
+      if (layer.blend === "multiply") {
+        return {
+          r: base.r * (1 - alpha + ink.r * alpha),
+          g: base.g * (1 - alpha + ink.g * alpha),
+          b: base.b * (1 - alpha + ink.b * alpha)
+        };
+      }
+      return sourceOverPlate(base, ink, alpha);
+    };
+    let worst = null;
+    for (const box of boxes) {
+      const cy = (box.y0 + box.y1) / 2;
+      const groundRgb = backgroundRgbAt(spec, cy, h, scale);
+      const ground = legibilityRatio(textPlate(groundRgb, box.alpha), groundRgb);
+      const lit = brightestAdditivePlate(spec, allEntities, groundRgb, box, w, h);
+      const plate = lit ? legibilityRatio(textPlate(lit.rgb, box.alpha), lit.rgb) : Infinity;
+      if (!worst || Math.min(ground, plate) < Math.min(worst.ground, worst.plate)) {
+        worst = { ground, plate, plateLabel: lit?.label ?? null };
+      }
+    }
+    if (worst && Math.min(worst.ground, worst.plate) < READ_LEGIBILITY_FLOOR) {
+      const under = worst.plateLabel ? ` and ${worst.plate.toFixed(1)}:1 under ${worst.plateLabel} at its brightest` : "";
+      warnings.push({
+        path: `layers[${b.li}].sprite`,
+        code: "text-legibility",
+        message: `${b.label} is declared role: 'read' but its colour reads at ${worst.ground.toFixed(1)}:1 against the background at the box centre${under} \u2014 below ${READ_LEGIBILITY_FLOOR}:1; brighten the text, darken the ground under it, or declare role: 'atmosphere' if it is texture`
+      });
+    }
+    const edges = [];
+    const x0 = Math.min(...boxes.map((x) => x.x0));
+    const x1 = Math.max(...boxes.map((x) => x.x1));
+    const y0 = Math.min(...boxes.map((x) => x.y0));
+    const y1 = Math.max(...boxes.map((x) => x.y1));
+    if (x0 < w * READ_SAFE_AREA) edges.push("left");
+    if (x1 > w * (1 - READ_SAFE_AREA)) edges.push("right");
+    if (y0 < h * READ_SAFE_AREA) edges.push("top");
+    if (y1 > h * (1 - READ_SAFE_AREA)) edges.push("bottom");
+    if (edges.length > 0) {
+      warnings.push({
+        path: `layers[${b.li}]`,
+        code: "text-safe-area",
+        message: `${b.label} is declared role: 'read' but its box is within ${READ_SAFE_AREA * 100}% of the ${edges.join(" and ")} edge${edges.length === 1 ? "" : "s"} at ${w}\xD7${h} \u2014 displays crop and bezels hide that zone; move it inward`,
+        boxes: [asFraction({ x0, y0, x1, y1 })]
       });
     }
   }
   return warnings;
 }
+function brightestAdditivePlate(spec, allEntities, ground, box, w, h) {
+  let best = null;
+  for (let lj = 0; lj < spec.layers.length; lj++) {
+    const layer = spec.layers[lj];
+    const blend = layer.blend;
+    if (blend !== "lighter" && blend !== "screen") continue;
+    if (lj === box.li) continue;
+    const entities = allEntities[lj];
+    for (const e of entities) {
+      const hex = spriteHex(layer, e);
+      if (hex === null) continue;
+      const growScale = (e.motion === "warp" ? WARP_MAX_SCALE : 1) * (e.emit ? Math.max(e.emit.growFrom, e.emit.growTo) : 1);
+      const maxDim = Math.max(e.size, e.size2 ?? 0) * (1 + e.growAmp) * growScale;
+      if (maxDim < box.fs) continue;
+      if (!entityReachesBox(e, maxDim / 2, box, w, h)) continue;
+      const a = Math.min(1, e.alpha + e.pulseAmp);
+      if (a <= 0) continue;
+      const plate = additivePlate(ground, hexRgb(hex), a, blend);
+      const lum = relativeLuminance(plate);
+      if (!best || lum > best.lum) {
+        best = { rgb: plate, label: layer.key ? `\`${layer.key}\`` : `layers[${lj}]`, lum };
+      }
+    }
+  }
+  return best ? { rgb: best.rgb, label: best.label } : null;
+}
+function entityReachesBox(e, r, box, w, h) {
+  if (e.motion === "static") {
+    const p = positionAt(e, 0, w, h);
+    return p.x + r > box.x0 && p.x - r < box.x1 && p.y + r > box.y0 && p.y - r < box.y1;
+  }
+  if (e.motion === "orbit" && !e.orbitParent) {
+    const span = e.orbitR + r;
+    return e.orbitCx + span > box.x0 && e.orbitCx - span < box.x1 && e.orbitCy + span > box.y0 && e.orbitCy - span < box.y1;
+  }
+  return true;
+}
 function textBoxAt(s, e, p, spec, w, h) {
   const m = s.font ? /(\d{1,5}(?:\.\d{1,4})?|\.\d{1,4})px/.exec(s.font) : null;
   const fontScale = spec.units === "px" ? 1 : Math.min(w, h) / (spec.referenceViewport ?? LIMITS.referenceViewport);
@@ -3383,28 +3997,39 @@ function textBoxAt(s, e, p, spec, w, h) {
   const baseline = s.baseline ?? "middle";
   const x0 = align === "left" ? p.x : align === "right" ? p.x - fw : p.x - fw / 2;
   const y0 = baseline === "top" ? p.y : baseline === "bottom" ? p.y - fh : p.y - fh / 2;
-  return { x0, y0, x1: x0 + fw, y1: y0 + fh };
+  return { x0, y0, x1: x0 + fw, y1: y0 + fh, fs: fh };
 }
 function textBlockBoxAt(s, p, w, h) {
   const unit = Math.min(w, h);
   const fsPx = s.fontSize * unit;
   const lh = (s.lineHeight ?? 1.4) * fsPx;
   const maxWPx = s.maxWidth * unit;
-  const lines = breakTextBlock(s.text, maxWPx / fsPx);
+  const lines = breakTextBlock(s.text, maxWPx / fsPx, textMetricsClassFor(s.font));
   const maxLineW = lines.reduce((mx, l) => Math.max(mx, l.widthEm), 0) * fsPx;
   const totalH = lines.length * lh;
   const align = s.align ?? "left";
   const x0 = align === "center" ? p.x + (maxWPx - maxLineW) / 2 : align === "right" ? p.x + maxWPx - maxLineW : p.x;
-  return { x0, y0: p.y, x1: x0 + maxLineW, y1: p.y + totalH };
+  const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
+  return { x0: x0 + dx, y0: p.y + dy, x1: x0 + dx + maxLineW, y1: p.y + dy + totalH, fs: fsPx };
 }
 function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
   const warnings = [];
   for (let i = 0; i < seq.segments.length; i++) {
     const segWarnings = adviseSpec(seq.segments[i].scene, viewport);
     for (const w of segWarnings) {
-      warnings.push({ path: `segments[${i}].scene.${w.path}`, code: w.code, message: w.message });
+      warnings.push({ path: `segments[${i}].scene.${w.path}`, code: w.code, message: w.message, boxes: w.boxes });
     }
   }
+  const fadeBound = seq.loop ? seq.segments.length : seq.segments.length - 1;
+  const fades = seq.segments.slice(0, fadeBound).filter((s) => s.transition?.type === "fade").length;
+  if (fades > 0) {
+    const first = seq.segments.slice(0, fadeBound).findIndex((s) => s.transition?.type === "fade");
+    warnings.push({
+      path: `segments[${first}].transition`,
+      code: "fade-degrades-on-low-tier",
+      message: `informational: ${fades} fade transition${fades === 1 ? "" : "s"} declared \u2014 viewers on the 'basic' or 'minimal' capability tier render fade as cut (two live segments for dur is over that budget); the show still plays`
+    });
+  }
   for (let i = 0; i < seq.segments.length - 1; i++) {
     const lumaA = backgroundLuma(seq.segments[i].scene);
     const lumaB = backgroundLuma(seq.segments[i + 1].scene);
@@ -3426,6 +4051,12 @@ function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
           code: "morph-structural-mismatch",
           message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
         });
+      } else if (morphNothingMorphable(seq.segments[i].scene, seq.segments[i + 1].scene, { textCrossfade: tr.text === "crossfade" })) {
+        warnings.push({
+          path: `segments[${i}].transition`,
+          code: "morph-nothing-morphable",
+          message: `segments ${i}\u2192${i + 1} differ only in values morph cannot interpolate (strings such as textBlock.text step on the first frame): the morph will look like a cut \u2014 fade text via colour or reveal.progress`
+        });
       }
     }
   }
@@ -3578,14 +4209,15 @@ function textBlockBox(s, _e, p, w, h) {
   const lh = (s.lineHeight ?? 1.4) * fsPx;
   const maxWPx = s.maxWidth * unitScale;
   const maxWEm = maxWPx / fsPx;
-  const lines = breakTextBlock(s.text, maxWEm);
+  const lines = breakTextBlock(s.text, maxWEm, textMetricsClassFor(s.font));
   const totalH = lines.length * lh;
   const maxLineW = lines.reduce((m, l) => Math.max(m, l.widthEm), 0) * fsPx;
   const align = s.align ?? "left";
   const cx = align === "center" ? p.x + maxWPx / 2 : align === "right" ? p.x + maxWPx - maxLineW / 2 : p.x + maxLineW / 2;
+  const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
   return {
-    cx,
-    cy: p.y + totalH / 2,
+    cx: cx + dx,
+    cy: p.y + totalH / 2 + dy,
     halfX: maxLineW / 2,
     halfY: totalH / 2
   };
@@ -3594,7 +4226,7 @@ function textBlockRevealFraction(s, w, h, t) {
   if (!s.reveal) return 1;
   const unitScale = Math.min(w, h);
   const maxWEm = s.maxWidth * unitScale / (s.fontSize * unitScale);
-  const lines = breakTextBlock(s.text, maxWEm);
+  const lines = breakTextBlock(s.text, maxWEm, textMetricsClassFor(s.font));
   const rs = revealState(lines, s.reveal, t);
   if (rs.glyphAlphas) {
     let sum = 0;
@@ -3788,7 +4420,7 @@ function luminanceGrid(spec, opts = {}) {
         const c1 = Math.min(cols - 1, Math.floor((centerX + reachX) / cellW));
         const r0 = Math.max(0, Math.floor((centerY - reachY) / cellH));
         const r1 = Math.min(rows - 1, Math.floor((centerY + reachY) / cellH));
-        const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) : 1);
+        const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1) : 1);
         for (let r = r0; r <= r1; r++) {
           for (let c = c0; c <= c1; c++) {
             const dx = (c + 0.5) * cellW - centerX;
@@ -3826,7 +4458,8 @@ function luminanceGrid(spec, opts = {}) {
         const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false && motionWraps, w, h);
         const la = Math.min(1, (layer.links.alpha ?? 0.6) * lifeA);
         const lum = layer.links.color ? hexLuma(layer.links.color) : 0.7;
-        const wgt = Math.min(1, (layer.links.width ?? 1) * scale / cellH) * la * alphaScale;
+        const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+        const wgt = Math.min(1, (layer.links.width ?? defaultWidth) * scale / cellH) * la * alphaScale;
         for (const edge of edges) {
           const pi = positions[edge.i];
           const pj = positions[edge.j];
@@ -3856,6 +4489,9 @@ function luminanceGrid(spec, opts = {}) {
     }
   }
   splatPass(t, 1);
+  return finishGrid(cols, rows, cells, bgRow);
+}
+function finishGrid(cols, rows, cells, bgRow) {
   let sum = 0;
   let covered = 0;
   let devSum = 0;
@@ -3965,6 +4601,21 @@ function textSprites(spec, opts = {}) {
   return out;
 }
 function dominanceRanking(spec, opts = {}) {
+  return rankDominance(rawDominance(spec, opts));
+}
+function rankDominance(raw) {
+  const total = raw.reduce((s, r) => s + r.weight, 0) || 1;
+  return raw.slice().sort((a, b) => b.weight - a.weight).map((r, i) => ({
+    rank: i + 1,
+    layerIndex: r.layerIndex,
+    key: r.key,
+    share: r.weight / total,
+    entityCount: r.entityCount,
+    meanLuma: r.meanLuma,
+    factors: r.factors
+  }));
+}
+function rawDominance(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
   const { w, h, scale } = scene;
@@ -4016,7 +4667,7 @@ function dominanceRanking(spec, opts = {}) {
         entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
       } else if (s.kind === "textBlock") {
         const box = textBlockBox(s, e, { x: 0, y: 0 }, w, h);
-        entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t);
+        entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1);
       } else entArea = sz * sz * 0.55;
       area += entArea * a;
       if (layer.trail) {
@@ -4034,7 +4685,8 @@ function dominanceRanking(spec, opts = {}) {
       const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
       const edges = linkEdges(layer.links, positions, layer.links.maxDist * scale, layer.wrap !== false && motionWraps, w, h);
       const la = (layer.links.alpha ?? 0.6) * lifeA;
-      const lw = (layer.links.width ?? 1) * scale;
+      const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+      const lw = (layer.links.width ?? defaultWidth) * scale;
       for (const edge of edges) area += edge.dist * lw * la * LINE_SALIENCE;
     }
     const meanLuma = entities.length ? lumAcc / entities.length : 0;
@@ -4044,16 +4696,7 @@ function dominanceRanking(spec, opts = {}) {
     const weight = area / (w * h) * contrast * blendBoost * motionBoost;
     return { layerIndex, key: layer.key, weight, entityCount: entities.length, meanLuma, factors: { area: area / (w * h), contrast, blendBoost, motionBoost } };
   });
-  const total = raw.reduce((s, r) => s + r.weight, 0) || 1;
-  return raw.slice().sort((a, b) => b.weight - a.weight).map((r, i) => ({
-    rank: i + 1,
-    layerIndex: r.layerIndex,
-    key: r.key,
-    share: r.weight / total,
-    entityCount: r.entityCount,
-    meanLuma: r.meanLuma,
-    factors: r.factors
-  }));
+  return raw;
 }
 function layerCohesion(spec, opts = {}) {
   const scene = buildScene(spec, opts);
@@ -4160,6 +4803,51 @@ function perceiveScene(spec, opts = {}) {
     advisories: adviseSpec(spec, opts.viewport ?? { width: 1920, height: 1080 }, { t: opts.t, seed: opts.seed })
   };
 }
+var bedKey = (key, layerIndex) => `bed:${key ?? layerIndex}`;
+function perceiveSequenceFrame(seq, T, opts = {}) {
+  const { releasedBelow, ...gridOpts } = opts;
+  const r = resolveSegment(seq, T, { releasedBelow });
+  const seg = seq.segments[r.index];
+  const segment = { index: r.index, key: seg.key, localT: r.localT, ...r.held ? { held: true } : {} };
+  const segOpts = { ...gridOpts, t: r.localT, seed: gridOpts.seed ?? segmentRenderSeed(seq, r.index) };
+  if (!seq.bed) return { ...perceiveScene(seg.scene, segOpts), segment, bed: false };
+  const bedOpts = { ...gridOpts, t: T, seed: gridOpts.seed ?? bedRenderSeed(seq) };
+  const viewport = gridOpts.viewport ?? { width: 1920, height: 1080 };
+  const ink = { ...seg.scene, background: { type: "solid", color: "#000000" } };
+  delete ink.ghosting;
+  const inkOverBed = { ...ink, background: seq.bed.background ?? { type: "solid", color: "#05050a" } };
+  const bedGrid = luminanceGrid(seq.bed, bedOpts);
+  const inkGrid = luminanceGrid(ink, segOpts);
+  const cells = bedGrid.cells.map((v, i) => Math.min(1, v + inkGrid.cells[i]));
+  const grid = finishGrid(bedGrid.cols, bedGrid.rows, cells, bedGrid.background);
+  const bedLayers = seq.bed.layers.length;
+  const dominance = rankDominance([
+    ...rawDominance(seq.bed, bedOpts).map((d) => ({ ...d, key: bedKey(d.key, d.layerIndex) })),
+    ...rawDominance(inkOverBed, segOpts).map((d) => ({ ...d, layerIndex: d.layerIndex + bedLayers }))
+  ]);
+  const shift = (x) => ({ ...x, layerIndex: x.layerIndex + bedLayers });
+  const prefix = (x) => ({ ...x, key: bedKey(x.key, x.layerIndex) });
+  return {
+    t: r.localT,
+    braille: renderBrailleMap(grid),
+    density: renderDensityMap(grid),
+    coverage: grid.coverage,
+    meanLuminance: grid.meanLuminance,
+    centroid: grid.centroid,
+    rowProfile: grid.rowProfile,
+    colProfile: grid.colProfile,
+    dominance,
+    motion: [...motionStats(seq.bed, bedOpts).map(prefix), ...motionStats(ink, segOpts).map(shift)],
+    form: [...layerCohesion(seq.bed, bedOpts).map(prefix), ...layerCohesion(ink, segOpts).map(shift)],
+    text: [...textSprites(seq.bed, bedOpts).map(prefix), ...textSprites(ink, segOpts).map(shift)],
+    advisories: [
+      ...adviseSpec(seq.bed, viewport, { t: T, seed: bedOpts.seed }).map((w) => ({ ...w, path: `bed.${w.path}` })),
+      ...adviseSpec(inkOverBed, viewport, { t: r.localT, seed: segOpts.seed })
+    ],
+    segment,
+    bed: true
+  };
+}
 
 // src/examples/aquarium.ts
 var AQUARIUM_SPEC = {
@@ -5049,6 +5737,85 @@ var LANTERNS_SPEC = {
   ]
 };
 
+// src/examples/lobby-talk.ts
+var LOBBY_TALK_SPEC = {
+  schemaVersion: 1,
+  id: "lobby-talk",
+  label: "Lobby Talk",
+  seed: 1207,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#060912" },
+      { at: 1, color: "#0b1224" }
+    ],
+    drift: { period: 4e4, amount: 0.1 }
+  },
+  layers: [
+    {
+      key: "haze",
+      count: 3,
+      sprite: { kind: "circle", radius: [0.22, 0.3], soft: true, color: "#123a4a", colors: ["#123a4a", "#2a1e4a", "#0e2a3a"] },
+      alpha: [0.35, 0.5],
+      blend: "lighter",
+      region: { x: [0.2, 0.8], y: [0.3, 0.7] },
+      motion: { type: "wander", speed: [2e-3, 4e-3], meander: 0.05 },
+      pulse: { amp: 0.15, period: 9e3 }
+    },
+    {
+      key: "dust",
+      count: 50,
+      sprite: { kind: "circle", radius: [8e-4, 18e-4], soft: true, color: "#7fb8c9" },
+      alpha: [0.2, 0.5],
+      blend: "lighter",
+      motion: { type: "wander", speed: [1e-3, 3e-3] }
+    },
+    {
+      key: "title",
+      count: 1,
+      sprite: { kind: "textBlock", text: "Adoption by feature, % of accounts", maxWidth: 1, fontSize: 0.034, color: "#f2f4f8", role: "read" },
+      motion: { type: "static" },
+      position: { x: 0.12, y: 0.16 }
+    },
+    {
+      key: "labels",
+      count: 5,
+      sprite: { kind: "text", strings: ["Onboarding", "Search", "Billing", "Exports", "Mobile"], font: "system-ui", align: "left", baseline: "middle", color: "#a9b7cc", role: "read" },
+      size: [0.03, 0.03],
+      motion: { type: "static" },
+      position: { x: 0.12, y: 0.32 },
+      layout: { type: "list", gap: 0.085 }
+    },
+    {
+      key: "bars",
+      count: 5,
+      sprite: {
+        kind: "bar",
+        values: [82, 64, 91, 37, 58],
+        max: 100,
+        length: 0.42,
+        thickness: 0.026,
+        color: "#7fe0d2",
+        colors: ["#7fe0d2", "#7fe0d2", "#ffcf7a", "#7fe0d2", "#7fe0d2"]
+      },
+      alpha: [0.9, 0.9],
+      motion: { type: "static" },
+      position: { x: 0.33, y: 0.32 },
+      layout: { type: "list", gap: 0.085 }
+    },
+    {
+      key: "readouts",
+      count: 5,
+      sprite: { kind: "text", strings: ["82%", "64%", "91%", "37%", "58%"], font: "bold system-ui", align: "left", baseline: "middle", color: "#f2f4f8", role: "read" },
+      size: [0.03, 0.03],
+      motion: { type: "static" },
+      position: { x: 0.78, y: 0.32 },
+      layout: { type: "list", gap: 0.085 }
+    }
+  ]
+};
+
 // src/examples/matrix-rain.ts
 var MATRIX_RAIN_SPEC = {
   schemaVersion: 1,
@@ -5773,7 +6540,8 @@ var SCHEMA_EXAMPLES = [
   { id: "haiku", label: "Haiku", spec: HAIKU_SPEC },
   { id: "pings", label: "Pings", spec: PINGS_SPEC },
   { id: "facets", label: "Facets", spec: FACETS_SPEC },
-  { id: "relay-board", label: "Relay Board", spec: RELAY_BOARD_SPEC }
+  { id: "relay-board", label: "Relay Board", spec: RELAY_BOARD_SPEC },
+  { id: "lobby-talk", label: "Lobby Talk", spec: LOBBY_TALK_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -5792,6 +6560,7 @@ export {
   HAIKU_SPEC,
   LANTERNS_SPEC,
   LIMITS,
+  LOBBY_TALK_SPEC,
   MATRIX_RAIN_SPEC,
   NOSTALGHIA_CANDLE_SPEC,
   ORRERY_SPEC,
@@ -5804,6 +6573,7 @@ export {
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
   SNOWFALL_SPEC,
+  WARP_MAX_SCALE,
   WARP_NEAR,
   WARP_TUNNEL_SPEC,
   adviseSequence,
@@ -5812,8 +6582,10 @@ export {
   applyDeltasToSpec,
   assertValidSequence,
   assertValidSpec,
+  bedRenderSeed,
   breakTextBlock,
   buildEntities,
+  canMorph,
   cohesionOf,
   compileSaver,
   compileSequence,
@@ -5832,8 +6604,12 @@ export {
   linkPairs,
   luminanceGrid,
   manifestFor,
+  morphChainRoot,
+  morphNothingMorphable,
   motionStats,
+  normalizeSeed,
   perceiveScene,
+  perceiveSequenceFrame,
   positionAt,
   renderBrailleMap,
   renderDensityMap,
@@ -5843,13 +6619,19 @@ export {
   rotationAt,
   seamCauseOf,
   seamsWorthWarning,
+  segmentRenderSeed,
   segmentStart,
+  sequenceSteerablePaths,
   sizeAt,
   spriteIndexAt,
   spriteVariants,
   steerablePaths,
   structuralSignature,
+  textBlockAnchorOffset,
+  textMetricsClassFor,
   textSprites,
+  textStringsDiffer,
+  textStringsOf,
   textWidthEm,
   validateSequence,
   validateSpec