@idle-screens/schema 3.2.0 → 3.4.0

package/dist/index.js

@@ -47,6 +47,10 @@ var LIMITS = {
   minTextBlockFontSize: 0.01,
   maxTextBlockFontSize: 0.2,
   maxTextBlockMaxWidth: 1,
+  maxRevealSpeed: 120,
+  // graphemes/sec — faster than any readable typing
+  maxCaretBlinkHz: 3,
+  // full blink cycles/sec — WCAG 2.3.1 flash-safety cap
   maxSegments: 24,
   minSegmentDuration: 1e3,
   // ms — flash-safety floor: segment cuts are luminance transitions
@@ -54,8 +58,137 @@ var LIMITS = {
   minTransitionDur: 200
 };
 
+// src/steer.ts
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+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)) {
+    const idx = s.layers.findIndex((l) => l && l.key === parts[0]);
+    if (idx === -1) return null;
+    parts.splice(0, 1, "layers", String(idx));
+  }
+  let node = spec;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (node === null || typeof node !== "object") return null;
+    node = node[parts[i]];
+  }
+  if (node === null || typeof node !== "object") return null;
+  const last = parts[parts.length - 1];
+  const key = Array.isArray(node) ? Number(last) : last;
+  const exists = Array.isArray(node) ? Number.isInteger(key) && key >= 0 && key < node.length : last in node;
+  return exists ? { parent: node, key } : null;
+}
+function applyDeltasToSpec(spec, deltas) {
+  const copy = JSON.parse(JSON.stringify(spec));
+  for (const d of deltas) {
+    const loc = resolveSpecPath(copy, d.path);
+    if (loc) loc.parent[loc.key] = d.value;
+  }
+  return copy;
+}
+var HEX = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function hexToRgb(hex) {
+  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);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function lerpHex(a, b, k) {
+  const ca = hexToRgb(a);
+  const cb = hexToRgb(b);
+  const mix = ca.map((v, i) => Math.round(v + (cb[i] - v) * k));
+  return `#${mix.map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+function lerpSpec(from, to, k) {
+  const kk = Math.max(0, Math.min(1, k));
+  const walk = (a, b, key) => {
+    if (typeof a === "number" && typeof b === "number") {
+      const v = a + (b - a) * kk;
+      return key === "count" ? Math.max(1, Math.round(v)) : v;
+    }
+    if (typeof a === "string" && typeof b === "string" && HEX.test(a) && HEX.test(b)) {
+      return lerpHex(a, b, kk);
+    }
+    if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+      return b.map((bv, i) => walk(a[i], bv, i));
+    }
+    if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+      const out = {};
+      for (const kName of Object.keys(b)) {
+        out[kName] = walk(a[kName], b[kName], kName);
+      }
+      return out;
+    }
+    return kk > 0 ? b : a;
+  };
+  return walk(from, to);
+}
+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 INDEXED = /* @__PURE__ */ new Set(["layers", "stops"]);
+  const out = [];
+  const walk = (node, prefix, key) => {
+    if (Array.isArray(node) && INDEXED.has(key)) {
+      node.forEach((child, i) => walk(child, `${prefix}.${i}`, ""));
+      return;
+    }
+    if (Array.isArray(node)) {
+      if (prefix) out.push(prefix);
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const [k, v] of Object.entries(node)) {
+        if (SKIP.has(k)) continue;
+        walk(v, prefix ? `${prefix}.${k}` : k, k);
+      }
+      return;
+    }
+    if (prefix) out.push(prefix);
+  };
+  walk(spec, "", "");
+  return out;
+}
+function easeSmooth(k) {
+  const c = Math.max(0, Math.min(1, k));
+  return c * c * (3 - 2 * c);
+}
+function structuralSignature(spec) {
+  return JSON.stringify([
+    spec.units,
+    spec.layers.map((l) => {
+      const s = l.sprite;
+      return [
+        l.count,
+        l.size,
+        l.region,
+        l.position,
+        l.motion,
+        l.wrap,
+        l.flip,
+        l.alpha,
+        l.pulse,
+        l.spin,
+        l.grow,
+        l.layout,
+        l.sprite.kind,
+        // Dimensional draws baked into entities: radius (circle/ring), length
+        // (streak), width+aspect (rect), palette pick (all shaped sprites).
+        s.radius,
+        s.length,
+        l.sprite.kind === "rect" ? [s.width, s.aspect] : 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
+      ];
+    })
+  ]);
+}
+
 // src/validate.ts
-var HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+var HEX2 = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isStr = (v) => typeof v === "string";
 var isNum = (v) => typeof v === "number" && Number.isFinite(v);
@@ -87,7 +220,9 @@ var KNOWN_STREAK = /* @__PURE__ */ new Set(["kind", "length", "color", "width",
 var KNOWN_RECT = /* @__PURE__ */ new Set(["kind", "width", "aspect", "color", "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"]);
+var KNOWN_TEXT_BLOCK = /* @__PURE__ */ new Set(["kind", "text", "maxWidth", "fontSize", "lineHeight", "align", "color", "reveal"]);
+var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret"]);
+var KNOWN_REVEAL_CARET = /* @__PURE__ */ new Set(["blink", "color"]);
 var KNOWN_DRIFT = /* @__PURE__ */ new Set(["type", "speed", "angle", "bidirectional", "bob"]);
 var KNOWN_RISE = /* @__PURE__ */ new Set(["type", "speed", "sway"]);
 var KNOWN_BOUNCE = /* @__PURE__ */ new Set(["type", "speed"]);
@@ -152,7 +287,7 @@ function validateSpec(spec) {
   return { valid: errors.length === 0, errors, warnings };
 }
 function color(v, path, err) {
-  if (!isStr(v) || !HEX.test(v)) err(path, "must be a hex colour like #0a3a52");
+  if (!isStr(v) || !HEX2.test(v)) err(path, "must be a hex colour like #0a3a52");
 }
 function validateBackground(bg, err, warn) {
   if (!isObj(bg)) return err("background", "must be an object");
@@ -445,6 +580,39 @@ 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.reveal !== void 0) {
+      const rv = sprite.reveal;
+      if (typeof rv !== "object" || rv === null || Array.isArray(rv)) {
+        err(`${path}.reveal`, "must be an object");
+      } else {
+        for (const k of Object.keys(rv)) {
+          if (!KNOWN_REVEAL.has(k)) err(`${path}.reveal.${k}`, "unknown reveal field");
+        }
+        if (rv.progress !== void 0 && (!isNum(rv.progress) || rv.progress < 0 || rv.progress > 1)) {
+          err(`${path}.reveal.progress`, "must be a number between 0 and 1");
+        }
+        if (rv.mode !== void 0 && !["typewriter", "word", "line"].includes(rv.mode)) {
+          err(`${path}.reveal.mode`, "must be 'typewriter' | 'word' | 'line'");
+        }
+        if (rv.speed !== void 0 && (!isNum(rv.speed) || rv.speed < 0 || rv.speed > LIMITS.maxRevealSpeed)) {
+          err(`${path}.reveal.speed`, `must be between 0 and ${LIMITS.maxRevealSpeed} (graphemes/sec)`);
+        }
+        if (rv.caret !== void 0 && typeof rv.caret !== "boolean") {
+          const caret = rv.caret;
+          if (typeof caret !== "object" || caret === null || Array.isArray(caret)) {
+            err(`${path}.reveal.caret`, "must be a boolean or an object");
+          } else {
+            for (const k of Object.keys(caret)) {
+              if (!KNOWN_REVEAL_CARET.has(k)) err(`${path}.reveal.caret.${k}`, "unknown caret field");
+            }
+            if (caret.blink !== void 0 && (!isNum(caret.blink) || caret.blink <= 0 || caret.blink > LIMITS.maxCaretBlinkHz)) {
+              err(`${path}.reveal.caret.blink`, `must be between 0 (exclusive) and ${LIMITS.maxCaretBlinkHz} Hz (flash safety)`);
+            }
+            if (caret.color !== void 0) color(caret.color, `${path}.reveal.caret.color`, err);
+          }
+        }
+      }
+    }
   } else {
     err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect | textBlock");
     return;
@@ -667,8 +835,12 @@ 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") {
+        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' (fade not yet supported)");
+        err(`${p}.transition.type`, "must be 'cut' or 'morph'");
       }
     }
     if (isObj(s.scene)) {
@@ -684,6 +856,23 @@ function validateSequence(seq) {
   if (seq.loop === true && hasDurationless) {
     err("loop", "loop: true requires all segments to have a duration");
   }
+  if (errors.length === 0 && Array.isArray(seq.segments)) {
+    for (let i = 0; i < seq.segments.length; i++) {
+      const s = seq.segments[i];
+      if (!isObj(s) || !isObj(s.transition) || s.transition.type !== "morph") continue;
+      const next = seq.segments[i + 1];
+      if (!next || !isObj(next) || !isObj(s.scene) || !isObj(next.scene)) continue;
+      const sigA = structuralSignature(s.scene);
+      const sigB = structuralSignature(next.scene);
+      if (sigA !== sigB) {
+        warnings.push({
+          path: `segments[${i}].transition`,
+          code: "morph-structural-mismatch",
+          message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
+        });
+      }
+    }
+  }
   return { valid: errors.length === 0, errors, warnings };
 }
 function assertValidSequence(seq) {
@@ -1207,141 +1396,99 @@ function breakTextBlock(text, maxWidthEm) {
   }
   return lines;
 }
-
-// src/compile.ts
-import {
-  createRng
-} from "@idle-screens/core";
-
-// src/steer.ts
-var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-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)) {
-    const idx = s.layers.findIndex((l) => l && l.key === parts[0]);
-    if (idx === -1) return null;
-    parts.splice(0, 1, "layers", String(idx));
-  }
-  let node = spec;
-  for (let i = 0; i < parts.length - 1; i++) {
-    if (node === null || typeof node !== "object") return null;
-    node = node[parts[i]];
-  }
-  if (node === null || typeof node !== "object") return null;
-  const last = parts[parts.length - 1];
-  const key = Array.isArray(node) ? Number(last) : last;
-  const exists = Array.isArray(node) ? Number.isInteger(key) && key >= 0 && key < node.length : last in node;
-  return exists ? { parent: node, key } : null;
-}
-function applyDeltasToSpec(spec, deltas) {
-  const copy = JSON.parse(JSON.stringify(spec));
-  for (const d of deltas) {
-    const loc = resolveSpecPath(copy, d.path);
-    if (loc) loc.parent[loc.key] = d.value;
-  }
-  return copy;
-}
-var HEX2 = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
-function hexToRgb(hex) {
-  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);
-  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+function isClusterExtend(cp) {
+  return cp >= 768 && cp <= 879 || // combining diacritics
+  cp >= 6832 && cp <= 6911 || cp >= 8400 && cp <= 8447 || cp >= 65024 && cp <= 65039 || // variation selectors
+  cp >= 127995 && cp <= 127999 || // skin tones
+  cp === 8419;
 }
-function lerpHex(a, b, k) {
-  const ca = hexToRgb(a);
-  const cb = hexToRgb(b);
-  const mix = ca.map((v, i) => Math.round(v + (cb[i] - v) * k));
-  return `#${mix.map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+function isRegionalIndicator(cp) {
+  return cp >= 127462 && cp <= 127487;
 }
-function lerpSpec(from, to, k) {
-  const kk = Math.max(0, Math.min(1, k));
-  const walk = (a, b, key) => {
-    if (typeof a === "number" && typeof b === "number") {
-      const v = a + (b - a) * kk;
-      return key === "count" ? Math.max(1, Math.round(v)) : v;
-    }
-    if (typeof a === "string" && typeof b === "string" && HEX2.test(a) && HEX2.test(b)) {
-      return lerpHex(a, b, kk);
-    }
-    if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
-      return b.map((bv, i) => walk(a[i], bv, i));
-    }
-    if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
-      const out = {};
-      for (const kName of Object.keys(b)) {
-        out[kName] = walk(a[kName], b[kName], kName);
+var ZWJ = 8205;
+function graphemeClusters(text) {
+  const out = [];
+  let i = 0;
+  while (i < text.length) {
+    const cp = text.codePointAt(i);
+    let end = i + (cp > 65535 ? 2 : 1);
+    if (isRegionalIndicator(cp) && end < text.length) {
+      const next = text.codePointAt(end);
+      if (isRegionalIndicator(next)) end += next > 65535 ? 2 : 1;
+    }
+    while (end < text.length) {
+      const next = text.codePointAt(end);
+      if (isClusterExtend(next)) {
+        end += next > 65535 ? 2 : 1;
+      } else if (next === ZWJ && end + 1 < text.length) {
+        const after = text.codePointAt(end + 1);
+        end += 1 + (after > 65535 ? 2 : 1);
+      } else {
+        break;
       }
-      return out;
     }
-    return kk > 0 ? b : a;
-  };
-  return walk(from, to);
+    out.push(text.slice(i, end));
+    i = end;
+  }
+  return out;
 }
-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 INDEXED = /* @__PURE__ */ new Set(["layers", "stops"]);
-  const out = [];
-  const walk = (node, prefix, key) => {
-    if (Array.isArray(node) && INDEXED.has(key)) {
-      node.forEach((child, i) => walk(child, `${prefix}.${i}`, ""));
-      return;
-    }
-    if (Array.isArray(node)) {
-      if (prefix) out.push(prefix);
-      return;
+function revealState(lines, reveal, tMs) {
+  const lineClusters = lines.map((l) => graphemeClusters(l.text));
+  const totalGraphemes = lineClusters.reduce((n, c) => n + c.length, 0);
+  const authored = Math.max(0, Math.min(1, reveal.progress ?? 1));
+  const speed = reveal.speed ?? 0;
+  const timed = speed > 0 && totalGraphemes > 0 ? Math.min(1, speed * tMs / 1e3 / totalGraphemes) : 1;
+  const progress = Math.min(authored, timed);
+  const mode = reveal.mode ?? "typewriter";
+  let fullLines = 0;
+  let partialText = "";
+  if (mode === "line") {
+    fullLines = Math.round(progress * lines.length);
+  } else if (mode === "word") {
+    const lineWords = lines.map((l) => l.text.length === 0 ? [] : l.text.split(" "));
+    const totalWords = lineWords.reduce((n, ws) => n + ws.length, 0);
+    let remaining = Math.round(progress * totalWords);
+    for (const ws of lineWords) {
+      if (remaining >= ws.length) {
+        remaining -= ws.length;
+        fullLines++;
+        continue;
+      }
+      if (remaining > 0) partialText = ws.slice(0, remaining).join(" ");
+      break;
     }
-    if (node && typeof node === "object") {
-      for (const [k, v] of Object.entries(node)) {
-        if (SKIP.has(k)) continue;
-        walk(v, prefix ? `${prefix}.${k}` : k, k);
+  } else {
+    let remaining = Math.round(progress * totalGraphemes);
+    for (const clusters of lineClusters) {
+      if (remaining >= clusters.length) {
+        remaining -= clusters.length;
+        fullLines++;
+        continue;
       }
-      return;
+      if (remaining > 0) partialText = clusters.slice(0, remaining).join("");
+      break;
     }
-    if (prefix) out.push(prefix);
-  };
-  walk(spec, "", "");
-  return out;
-}
-function easeSmooth(k) {
-  const c = Math.max(0, Math.min(1, k));
-  return c * c * (3 - 2 * c);
-}
-function structuralSignature(spec) {
-  return JSON.stringify([
-    spec.units,
-    spec.layers.map((l) => {
-      const s = l.sprite;
-      return [
-        l.count,
-        l.size,
-        l.region,
-        l.position,
-        l.motion,
-        l.wrap,
-        l.flip,
-        l.alpha,
-        l.pulse,
-        l.spin,
-        l.grow,
-        l.layout,
-        l.sprite.kind,
-        // Dimensional draws baked into entities: radius (circle/ring), length
-        // (streak), width+aspect (rect), palette pick (all shaped sprites).
-        s.radius,
-        s.length,
-        l.sprite.kind === "rect" ? [s.width, s.aspect] : 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
-      ];
-    })
-  ]);
+  }
+  let caretLine;
+  let caretPrefix;
+  if (partialText.length > 0) {
+    caretLine = fullLines;
+    caretPrefix = partialText;
+  } else if (fullLines > 0) {
+    caretLine = fullLines - 1;
+    caretPrefix = lines[fullLines - 1].text;
+  } else {
+    caretLine = 0;
+    caretPrefix = "";
+  }
+  return { progress, fullLines, partialText, caretLine, caretPrefix };
 }
 
+// src/compile.ts
+import {
+  createRng
+} from "@idle-screens/core";
+
 // src/sequence.ts
 function resolveSegment(seq, T) {
   const { segments, loop } = seq;
@@ -1675,6 +1822,9 @@ var SpecInstance = class {
       const maxWEm = maxWPx / fsPx;
       const lines = breakTextBlock(sprite.text, maxWEm);
       const align = sprite.align ?? "left";
+      const reveal = sprite.reveal;
+      const rs = reveal ? revealState(lines, reveal, t) : null;
+      const fullLines = rs ? rs.fullLines : lines.length;
       ctx.save();
       ctx.translate(p.x, p.y);
       if (rot) ctx.rotate(rot);
@@ -1683,9 +1833,23 @@ var SpecInstance = class {
       ctx.textBaseline = "top";
       ctx.textAlign = align;
       const xOff = align === "center" ? maxWPx / 2 : align === "right" ? maxWPx : 0;
-      for (let li = 0; li < lines.length; li++) {
+      for (let li = 0; li < fullLines; li++) {
         ctx.fillText(lines[li].text, xOff, li * lh);
       }
+      if (rs && rs.partialText.length > 0) {
+        ctx.fillText(rs.partialText, xOff, fullLines * lh);
+      }
+      if (rs && reveal.caret) {
+        const cfg = reveal.caret === true ? {} : reveal.caret;
+        const hz = Math.min(3, cfg.blink ?? 1.2);
+        const on = hz <= 0 || Math.floor(t / 1e3 * hz * 2) % 2 === 0;
+        if (on) {
+          const pw = ctx.measureText(rs.caretPrefix).width;
+          const cx = align === "center" ? xOff + pw / 2 : align === "right" ? xOff : pw;
+          ctx.fillStyle = cfg.color ?? sprite.color ?? "#e6e8ef";
+          ctx.fillRect(cx + fsPx * 0.06, rs.caretLine * lh, Math.max(1, fsPx * 0.08), fsPx);
+        }
+      }
       ctx.restore();
       return;
     }
@@ -1856,6 +2020,26 @@ var SpecInstance = class {
     this.rebuild();
     if (this.paused) this.renderFrame(0, this.seed);
   }
+  /**
+   * 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).
+   */
+  hotSwapSpec(spec) {
+    this.effSpec = spec;
+    const sig = structuralSignature(this.effSpec);
+    if (sig !== this.lastStructural) this.rebuild();
+    else this.layers.forEach((b, i) => {
+      b.layer = this.effSpec.layers[i] ?? b.layer;
+    });
+  }
+  /** Paint-only hot-swap: skips structuralSignature (caller guarantees match). */
+  hotSwapPaint(spec) {
+    this.effSpec = spec;
+    this.layers.forEach((b, i) => {
+      b.layer = this.effSpec.layers[i] ?? b.layer;
+    });
+  }
   dispose() {
     this.stop();
     if (this.ownsCanvas && typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
@@ -1876,6 +2060,17 @@ var SequenceInstance = class {
   children;
   activeIndex = -1;
   paused = false;
+  /**
+   * When a morph is active, the child at `morphFromIndex` renders with a
+   * lerped spec. The child stays keyed to the *outgoing* segment's slot so
+   * its seed (and entity placement) is continuous.
+   */
+  morphFromIndex = -1;
+  seed;
+  frameId = null;
+  startT = 0;
+  baseT = 0;
+  lastT = 0;
   constructor(seq, ctx) {
     this.seq = seq;
     let surface = ctx.surface ?? null;
@@ -1888,8 +2083,15 @@ var SequenceInstance = class {
       surface = canvas;
     }
     this.canvas = canvas;
+    this.seed = (seq.seed ?? ctx.seed ?? 0) >>> 0 || 1;
     this.childCtx = { ...ctx, surface, reducedMotion: true };
     this.children = new Array(seq.segments.length).fill(null);
+    this.paused = ctx.reducedMotion;
+    if (this.paused) this.renderFrame(0, this.seed);
+    else this.start();
+  }
+  childSeed(index, fallback) {
+    return this.seq.segments[index].scene.seed ?? this.seq.seed ?? fallback;
   }
   childScene(index) {
     const seg = this.seq.segments[index];
@@ -1897,13 +2099,31 @@ var SequenceInstance = class {
     if (this.seq.seed != null) return { ...seg.scene, seed: this.seq.seed + index };
     return seg.scene;
   }
+  /** 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);
+  }
+  /** 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;
+  }
+  morphDur(from) {
+    const tr = this.seq.segments[from]?.transition;
+    return tr?.type === "morph" ? tr.dur : 0;
+  }
   ensureChild(index) {
     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);
       this.children[index] = child;
-      if (this.paused) child.setPaused(true);
+      child.setPaused(true);
     }
     return child;
   }
@@ -1914,23 +2134,79 @@ var SequenceInstance = class {
       this.children[index] = null;
     }
   }
+  start() {
+    if (this.frameId !== null || typeof requestAnimationFrame === "undefined") return;
+    this.startT = 0;
+    this.frameId = requestAnimationFrame((now) => this.loop(now));
+  }
+  stop() {
+    if (this.frameId !== null) {
+      cancelAnimationFrame(this.frameId);
+      this.frameId = null;
+    }
+    this.baseT = this.lastT;
+  }
+  loop(now) {
+    this.frameId = requestAnimationFrame((n) => this.loop(n));
+    if (this.startT === 0) this.startT = now;
+    this.lastT = now - this.startT + this.baseT;
+    this.renderFrame(this.lastT, this.seed);
+  }
   renderFrame(T, seed) {
     const resolved = resolveSegment(this.seq, T);
     const { index, localT } = resolved;
-    if (index !== this.activeIndex) {
+    const prevIdx = index > 0 ? index - 1 : -1;
+    const morphActive = prevIdx >= 0 && this.canMorph(prevIdx) && localT < this.morphDur(prevIdx);
+    if (morphActive) {
+      const chainRoot = this.morphChainRoot(index);
+      this.morphFromIndex = prevIdx;
+      this.activeIndex = index;
       for (let i = 0; i < this.children.length; i++) {
-        if (i !== index) this.releaseChild(i);
+        if (i !== chainRoot) this.releaseChild(i);
       }
-      this.activeIndex = index;
+      const child = this.ensureChild(chainRoot);
+      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));
+      child.renderFrame(localT, this.childSeed(chainRoot, seed));
+    } else {
+      if (this.morphFromIndex >= 0) {
+        const oldRoot = this.morphChainRoot(this.morphFromIndex);
+        this.releaseChild(oldRoot);
+        if (oldRoot !== this.morphFromIndex) this.releaseChild(this.morphFromIndex);
+        this.morphFromIndex = -1;
+      }
+      if (index !== this.activeIndex) {
+        for (let i = 0; i < this.children.length; i++) {
+          if (i !== index) this.releaseChild(i);
+        }
+        this.activeIndex = index;
+      }
+      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));
+      }
+      child.renderFrame(localT, effSeed);
     }
-    const child = this.ensureChild(index);
-    const childSeed = this.seq.segments[index].scene.seed ?? this.seq.seed ?? seed;
-    child.renderFrame(localT, childSeed);
   }
   setPaused(paused) {
     this.paused = paused;
+    if (paused) this.stop();
+    else this.start();
     for (const child of this.children) {
-      child?.setPaused(paused);
+      child?.setPaused(true);
     }
   }
   resize(width, height, dpr) {
@@ -1959,6 +2235,7 @@ var SequenceInstance = class {
     }
   }
   dispose() {
+    this.stop();
     for (let i = 0; i < this.children.length; i++) {
       this.releaseChild(i);
     }
@@ -2231,6 +2508,40 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
   }
   return warnings;
 }
+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 });
+    }
+  }
+  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);
+    const delta = Math.abs(lumaA - lumaB);
+    if (delta > 0.5) {
+      warnings.push({
+        path: `segments[${i}]`,
+        code: "boundary-luminance-jump",
+        message: `background luminance jumps ${delta.toFixed(2)} at boundary ${i}\u2192${i + 1} \u2014 may flash on cut`
+      });
+    }
+    const tr = seq.segments[i].transition;
+    if (tr?.type === "morph") {
+      const sigA = structuralSignature(seq.segments[i].scene);
+      const sigB = structuralSignature(seq.segments[i + 1].scene);
+      if (sigA !== sigB) {
+        warnings.push({
+          path: `segments[${i}].transition`,
+          code: "morph-structural-mismatch",
+          message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
+        });
+      }
+    }
+  }
+  return warnings;
+}
 
 // src/describe.ts
 import { createRng as createRng3 } from "@idle-screens/core";
@@ -2390,6 +2701,13 @@ function textBlockBox(s, _e, p, w, h) {
     halfY: totalH / 2
   };
 }
+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);
+  return revealState(lines, s.reveal, t).progress;
+}
 function luminanceGrid(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
@@ -2528,7 +2846,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;
+        const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) : 1);
         for (let r = r0; r <= r1; r++) {
           for (let c = c0; c <= c1; c++) {
             const dx = (c + 0.5) * cellW - centerX;
@@ -2691,7 +3009,9 @@ function textSprites(spec, opts = {}) {
       const s2 = layer.sprite;
       const unitScale = Math.min(scene.w, scene.h);
       const sizePx2 = s2.fontSize * unitScale;
-      out.push({ layerIndex, key: layer.key, strings: [s2.text], count: entities.length, sizePx: Math.round(sizePx2) });
+      const info = { layerIndex, key: layer.key, strings: [s2.text], count: entities.length, sizePx: Math.round(sizePx2) };
+      if (s2.reveal) info.revealed = Math.round(textBlockRevealFraction(s2, scene.w, scene.h, t) * 100) / 100;
+      out.push(info);
       return;
     }
     if (layer.sprite.kind !== "text") return;
@@ -2746,7 +3066,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;
+        entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t);
       } else entArea = sz * sz * 0.55;
       area += entArea * a;
       if (layer.trail) {
@@ -4351,6 +4671,7 @@ export {
   SNOWFALL_SPEC,
   WARP_NEAR,
   WARP_TUNNEL_SPEC,
+  adviseSequence,
   adviseSpec,
   alphaAt,
   applyDeltasToSpec,
@@ -4364,6 +4685,7 @@ export {
   diffScenes,
   dominanceRanking,
   easeSmooth,
+  graphemeClusters,
   headingAt,
   lerpSpec,
   lifeAlphaAt,
@@ -4378,6 +4700,7 @@ export {
   renderDensityMap,
   resolveSegment,
   resolveSpecPath,
+  revealState,
   rotationAt,
   sizeAt,
   spriteIndexAt,