@idle-screens/schema 3.1.1 → 3.3.0

package/dist/index.js

@@ -42,11 +42,149 @@ var LIMITS = {
   maxPathPoints: 24,
   minPathDuration: 2e3,
   // ms — a path lap can't be faster than this
-  maxGridColumns: 100
+  maxGridColumns: 100,
+  maxTextBlockLength: 2e3,
+  minTextBlockFontSize: 0.01,
+  maxTextBlockFontSize: 0.2,
+  maxTextBlockMaxWidth: 1,
+  maxSegments: 24,
+  minSegmentDuration: 1e3,
+  // ms — flash-safety floor: segment cuts are luminance transitions
+  maxTransitionDur: 5e3,
+  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);
@@ -78,6 +216,7 @@ 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_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"]);
@@ -108,6 +247,14 @@ function validateSpec(spec) {
   if (spec.units !== void 0 && spec.units !== "px" && spec.units !== "viewport") {
     err("units", "must be 'px' | 'viewport'");
   }
+  if (spec.units === "px" && Array.isArray(spec.layers)) {
+    for (const l of spec.layers) {
+      if (isObj(l) && isObj(l.sprite) && l.sprite.kind === "textBlock") {
+        err("units", "textBlock dimensions are viewport fractions \u2014 units: 'px' is not supported with textBlock sprites");
+        break;
+      }
+    }
+  }
   if (spec.referenceViewport !== void 0) {
     if (!isNum(spec.referenceViewport) || spec.referenceViewport < 100 || spec.referenceViewport > 8640) {
       err("referenceViewport", "must be a number between 100 and 8640");
@@ -134,7 +281,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");
@@ -407,8 +554,28 @@ function validateSprite(sprite, path, err, warn) {
     }
     color(sprite.color, `${path}.color`, err);
     validatePalette(sprite, path, err);
+  } else if (sprite.kind === "textBlock") {
+    knownSet = KNOWN_TEXT_BLOCK;
+    if (typeof sprite.text !== "string" || sprite.text.length === 0) {
+      err(`${path}.text`, "must be a non-empty string");
+    } else if (sprite.text.length > LIMITS.maxTextBlockLength) {
+      err(`${path}.text`, `must be at most ${LIMITS.maxTextBlockLength} characters`);
+    }
+    if (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0 || sprite.maxWidth > LIMITS.maxTextBlockMaxWidth) {
+      err(`${path}.maxWidth`, `must be a positive number up to ${LIMITS.maxTextBlockMaxWidth} (viewport fraction)`);
+    }
+    if (!isNum(sprite.fontSize) || sprite.fontSize < LIMITS.minTextBlockFontSize || sprite.fontSize > LIMITS.maxTextBlockFontSize) {
+      err(`${path}.fontSize`, `must be between ${LIMITS.minTextBlockFontSize} and ${LIMITS.maxTextBlockFontSize} (viewport fraction)`);
+    }
+    if (sprite.lineHeight !== void 0 && (!isNum(sprite.lineHeight) || sprite.lineHeight < 0.5 || sprite.lineHeight > 4)) {
+      err(`${path}.lineHeight`, "must be between 0.5 and 4 (multiplier)");
+    }
+    if (sprite.align !== void 0 && !["left", "center", "right"].includes(sprite.align)) {
+      err(`${path}.align`, "must be 'left' | 'center' | 'right'");
+    }
+    if (sprite.color !== void 0) color(sprite.color, `${path}.color`, err);
   } else {
-    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect");
+    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect | textBlock");
     return;
   }
   for (const k of unknownKeys(sprite, knownSet)) {
@@ -576,6 +743,107 @@ ${r.errors.map((e) => `  ${e.path || "<root>"}: ${e.message}`).join("\n")}`);
   }
   return spec;
 }
+function validateSequence(seq) {
+  const errors = [];
+  const warnings = [];
+  const err = (path, message) => void errors.push({ path, message });
+  if (!isObj(seq)) return { valid: false, errors: [{ path: "", message: "sequence must be an object" }], warnings: [] };
+  if (seq.format !== "idle-sequence") err("format", "must be 'idle-sequence'");
+  if (seq.schemaVersion !== SCHEMA_VERSION) err("schemaVersion", `must be ${SCHEMA_VERSION}`);
+  if (!isStr(seq.id) || seq.id.trim() === "") err("id", "must be a non-empty string");
+  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 (!Array.isArray(seq.segments) || seq.segments.length === 0) {
+    err("segments", "must be a non-empty array");
+    return { valid: false, errors, warnings };
+  }
+  if (seq.segments.length > LIMITS.maxSegments) {
+    err("segments", `at most ${LIMITS.maxSegments} segments`);
+  }
+  const keys = /* @__PURE__ */ new Set();
+  let hasDurationless = false;
+  for (let i = 0; i < seq.segments.length; i++) {
+    const s = seq.segments[i];
+    const p = `segments[${i}]`;
+    if (!isObj(s)) {
+      err(p, "must be an object");
+      continue;
+    }
+    if (!isStr(s.key) || s.key.trim() === "") {
+      err(`${p}.key`, "must be a non-empty string");
+    } else if (keys.has(s.key)) {
+      err(`${p}.key`, `duplicate key '${s.key}'`);
+    } else {
+      keys.add(s.key);
+    }
+    if (s.duration !== void 0) {
+      if (hasDurationless) {
+        err(`${p}.duration`, "a segment after a durationless segment may not have a duration");
+      }
+      if (!isNum(s.duration) || s.duration < LIMITS.minSegmentDuration) {
+        err(`${p}.duration`, `must be >= ${LIMITS.minSegmentDuration} ms`);
+      }
+    } else {
+      if (i < seq.segments.length - 1) {
+        err(`${p}.duration`, "only the final segment may omit duration");
+      }
+      hasDurationless = true;
+    }
+    if (s.advance !== void 0 && !["auto", "input", "either"].includes(s.advance)) {
+      err(`${p}.advance`, "must be 'auto' | 'input' | 'either'");
+    }
+    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' or 'morph'");
+      }
+    }
+    if (isObj(s.scene)) {
+      const sceneResult = validateSpec(s.scene);
+      for (const e of sceneResult.errors) errors.push({ path: `${p}.scene.${e.path}`, message: e.message });
+      if (sceneResult.warnings) {
+        for (const w of sceneResult.warnings) warnings.push({ path: `${p}.scene.${w.path}`, code: w.code, message: w.message });
+      }
+    } else {
+      err(`${p}.scene`, "must be a valid SaverSpec object");
+    }
+  }
+  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) {
+  const r = validateSequence(seq);
+  if (!r.valid) {
+    throw new Error(`invalid sequence:
+${r.errors.map((e) => `  ${e.path || "<root>"}: ${e.message}`).join("\n")}`);
+  }
+  return seq;
+}
 
 // src/simulate.ts
 var WARP_NEAR = 0.08;
@@ -660,7 +928,7 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
   }
   const out = [];
   for (let i = 0; i < effectiveCount; i++) {
-    const size = sprite.kind === "circle" || sprite.kind === "ring" ? rng.range(sprite.radius[0], sprite.radius[1]) * 2 * scale : sprite.kind === "streak" ? rng.range(sprite.length[0], sprite.length[1]) * scale : sprite.kind === "rect" ? rng.range(sprite.width[0], sprite.width[1]) * scale : rng.range(smin, smax) * scale;
+    const size = sprite.kind === "textBlock" ? sprite.fontSize * scale : sprite.kind === "circle" || sprite.kind === "ring" ? rng.range(sprite.radius[0], sprite.radius[1]) * 2 * scale : sprite.kind === "streak" ? rng.range(sprite.length[0], sprite.length[1]) * scale : sprite.kind === "rect" ? rng.range(sprite.width[0], sprite.width[1]) * scale : rng.range(smin, smax) * scale;
     const size2 = sprite.kind === "rect" ? size * (sprite.aspect ? rng.range(sprite.aspect[0], sprite.aspect[1]) : 1) : void 0;
     let vx = 0;
     let vy = 0;
@@ -1044,139 +1312,84 @@ function linkPairs(positions, k, maxDist, doWrap, w, h) {
   }
   return out;
 }
+var CHAR_NARROW = new Set(`iIljtf1!|.,;:'"()[]{}`);
+var CHAR_WIDE = new Set("mwMWGOQD@%");
+function charWidthEm(ch) {
+  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) {
+  let w = 0;
+  for (let i = 0; i < str.length; i++) w += charWidthEm(str[i]);
+  return w;
+}
+function breakTextBlock(text, maxWidthEm) {
+  const paragraphs = text.split("\n");
+  const lines = [];
+  for (const para of paragraphs) {
+    if (para.length === 0) {
+      lines.push({ text: "", widthEm: 0 });
+      continue;
+    }
+    const words = para.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0) {
+      lines.push({ text: "", widthEm: 0 });
+      continue;
+    }
+    let lineText = words[0];
+    let lineW = textWidthEm(lineText);
+    const spaceW = charWidthEm(" ");
+    for (let i = 1; i < words.length; i++) {
+      const word = words[i];
+      const wordW = textWidthEm(word);
+      if (lineW + spaceW + wordW <= maxWidthEm) {
+        lineText += " " + word;
+        lineW += spaceW + wordW;
+      } else {
+        lines.push({ text: lineText, widthEm: lineW });
+        lineText = word;
+        lineW = wordW;
+      }
+    }
+    lines.push({ text: lineText, widthEm: lineW });
+  }
+  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));
+// src/sequence.ts
+function resolveSegment(seq, T) {
+  const { segments, loop } = seq;
+  if (segments.length === 0) return { index: 0, localT: 0, startT: 0 };
+  let totalTimed = 0;
+  for (const seg of segments) {
+    if (seg.duration != null) totalTimed += seg.duration;
+    else break;
   }
-  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;
+  let t = Math.max(0, T);
+  if (loop && totalTimed > 0) {
+    t = t % totalTimed;
   }
-  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 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" && 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));
+  let cumulative = 0;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg.duration == null) {
+      return { index: i, localT: t - cumulative, startT: cumulative };
     }
-    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;
+    if (t < cumulative + seg.duration) {
+      return { index: i, localT: t - cumulative, startT: cumulative };
     }
-    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] : void 0
-      ];
-    })
-  ]);
+    cumulative += seg.duration;
+  }
+  const last = segments.length - 1;
+  const lastStart = cumulative - (segments[last].duration ?? 0);
+  return { index: last, localT: t - lastStart, startT: lastStart };
 }
 
 // src/compile.ts
@@ -1226,12 +1439,14 @@ var SpecInstance = class {
     let canvas;
     if (ctx.surface) {
       canvas = ctx.surface;
+      this.ownsCanvas = false;
     } else {
       const el = document.createElement("canvas");
       el.style.cssText = "display:block;width:100%;height:100%";
       el.setAttribute("aria-hidden", "true");
       ctx.host.appendChild(el);
       canvas = el;
+      this.ownsCanvas = true;
     }
     this.canvas = canvas;
     const c2d = canvas.getContext("2d", { alpha: false });
@@ -1247,6 +1462,7 @@ var SpecInstance = class {
   }
   spec;
   canvas;
+  ownsCanvas;
   ctx;
   saverCtx;
   seed;
@@ -1365,7 +1581,7 @@ var SpecInstance = class {
     const headAlpha = alphaAt(e, t) * lifeA;
     const headSize = sizeAt(e, t);
     const sprite = built.layer.sprite;
-    const resolvedColor = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" ? sprite.color ?? "#e6e8ef" : "#e6e8ef";
+    const resolvedColor = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" || sprite.kind === "textBlock" ? sprite.color ?? "#e6e8ef" : "#e6e8ef";
     const isSoft = sprite.kind === "circle" && sprite.soft;
     const wrap2 = built.layer.wrap !== false;
     const head = this.entityPos(e, t, parentE);
@@ -1472,6 +1688,28 @@ var SpecInstance = class {
       ctx.restore();
       return;
     }
+    if (sprite.kind === "textBlock") {
+      const unitScale2 = Math.min(this.w, this.h);
+      const fsPx = sprite.fontSize * unitScale2;
+      const lh = (sprite.lineHeight ?? 1.4) * fsPx;
+      const maxWPx = sprite.maxWidth * unitScale2;
+      const maxWEm = maxWPx / fsPx;
+      const lines = breakTextBlock(sprite.text, maxWEm);
+      const align = sprite.align ?? "left";
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      if (rot) ctx.rotate(rot);
+      ctx.font = `${fsPx}px system-ui, sans-serif`;
+      ctx.fillStyle = sprite.color ?? "#e6e8ef";
+      ctx.textBaseline = "top";
+      ctx.textAlign = align;
+      const xOff = align === "center" ? maxWPx / 2 : align === "right" ? maxWPx : 0;
+      for (let li = 0; li < lines.length; li++) {
+        ctx.fillText(lines[li].text, xOff, li * lh);
+      }
+      ctx.restore();
+      return;
+    }
     ctx.save();
     ctx.translate(p.x, p.y);
     if (rot) ctx.rotate(rot);
@@ -1639,9 +1877,29 @@ 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 (typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
+    if (this.ownsCanvas && typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
   }
 };
 function compileSaver(spec) {
@@ -1652,6 +1910,192 @@ function compileSaver(spec) {
     spec: valid
   };
 }
+var SequenceInstance = class {
+  seq;
+  childCtx;
+  canvas;
+  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;
+  constructor(seq, ctx) {
+    this.seq = seq;
+    let surface = ctx.surface ?? null;
+    let canvas = null;
+    if (!surface && typeof document !== "undefined") {
+      canvas = document.createElement("canvas");
+      canvas.style.cssText = "display:block;width:100%;height:100%";
+      canvas.setAttribute("aria-hidden", "true");
+      ctx.host.appendChild(canvas);
+      surface = canvas;
+    }
+    this.canvas = canvas;
+    this.childCtx = { ...ctx, surface, reducedMotion: true };
+    this.children = new Array(seq.segments.length).fill(null);
+  }
+  childSeed(index, fallback) {
+    return this.seq.segments[index].scene.seed ?? this.seq.seed ?? fallback;
+  }
+  childScene(index) {
+    const seg = this.seq.segments[index];
+    if (seg.scene.seed != null) return seg.scene;
+    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);
+    }
+    return child;
+  }
+  releaseChild(index) {
+    const child = this.children[index];
+    if (child) {
+      child.dispose();
+      this.children[index] = null;
+    }
+  }
+  renderFrame(T, seed) {
+    const resolved = resolveSegment(this.seq, T);
+    const { index, localT } = resolved;
+    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 !== chainRoot) this.releaseChild(i);
+      }
+      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;
+        if (this.paused) child.setPaused(true);
+        child.hotSwapSpec(this.childScene(index));
+      } else {
+        child = this.ensureChild(index);
+        if (useMorphSeed) child.hotSwapSpec(this.childScene(index));
+      }
+      child.renderFrame(localT, effSeed);
+    }
+  }
+  setPaused(paused) {
+    this.paused = paused;
+    for (const child of this.children) {
+      child?.setPaused(paused);
+    }
+  }
+  resize(width, height, dpr) {
+    for (const child of this.children) {
+      child?.resize(width, height, dpr);
+    }
+  }
+  applyTrack(track) {
+    const deltas = track?.deltas ?? [];
+    const segDelta = deltas.find((d) => d.path === "sequence.segment");
+    if (segDelta !== void 0 && typeof segDelta.value === "number") {
+      const idx = Math.max(0, Math.min(this.seq.segments.length - 1, Math.round(segDelta.value)));
+      if (idx !== this.activeIndex) {
+        for (let i = 0; i < this.children.length; i++) {
+          if (i !== idx) this.releaseChild(i);
+        }
+        this.activeIndex = idx;
+        const child = this.ensureChild(idx);
+        child.renderFrame(0, this.seq.segments[idx].scene.seed ?? this.seq.seed ?? 0);
+      }
+    }
+    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 });
+    }
+  }
+  dispose() {
+    for (let i = 0; i < this.children.length; i++) {
+      this.releaseChild(i);
+    }
+    if (this.canvas) this.canvas.remove();
+  }
+};
+function sequenceManifest(seq) {
+  const maxTotal = seq.segments.reduce((max, s) => {
+    const t = s.scene.layers.reduce((n, l) => n + l.count, 0);
+    return Math.max(max, t);
+  }, 0);
+  const costTier = maxTotal < 30 ? "idle" : maxTotal < 150 ? "low" : maxTotal < 400 ? "medium" : "high";
+  return {
+    id: seq.id,
+    label: seq.label,
+    timeModel: "closed-form",
+    passthrough: false,
+    minBackend: "canvas2d",
+    costTier,
+    motionIntensity: "moderate",
+    reducedMotionFallback: "static",
+    a11y: { flashSafe: true },
+    workerReady: false
+  };
+}
+function compileSequence(spec) {
+  const valid = assertValidSequence(spec);
+  return {
+    manifest: sequenceManifest(valid),
+    mount: (ctx) => new SequenceInstance(valid, ctx),
+    spec: valid
+  };
+}
 
 // src/advise.ts
 import { createRng as createRng2 } from "@idle-screens/core";
@@ -1671,7 +2115,7 @@ function spriteLuma(layer, e) {
   if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
     return hexLuma(s.colors?.[e.colorIndex] ?? s.color);
   }
-  if (s.kind === "text") return hexLuma(s.color ?? "#e6e8ef");
+  if (s.kind === "text" || s.kind === "textBlock") return hexLuma(s.color ?? "#e6e8ef");
   return 0.75;
 }
 function spriteHex(layer, e) {
@@ -1679,7 +2123,7 @@ function spriteHex(layer, e) {
   if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
     return s.colors?.[e.colorIndex] ?? s.color;
   }
-  if (s.kind === "text") return s.color ?? "#e6e8ef";
+  if (s.kind === "text" || s.kind === "textBlock") return s.color ?? "#e6e8ef";
   return null;
 }
 function backgroundLuma(spec) {
@@ -1734,7 +2178,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
     const layer = spec.layers[li];
     const entities = allEntities[li];
     totalEntities += entities.length;
-    const isText = layer.sprite.kind === "text";
+    const isText = layer.sprite.kind === "text" || layer.sprite.kind === "textBlock";
     const isStaticText = isText && layer.motion.type === "static";
     if (isStaticText) textLayerCount++;
     if (layer.motion.type !== "static") motionLayerCount++;
@@ -1793,7 +2237,18 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
     const entities = allEntities[li];
     for (const e of entities) {
       const r = e.size / 2;
-      const pixArea = layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
+      let pixArea;
+      if (layer.sprite.kind === "circle") {
+        pixArea = Math.PI * r * r;
+      } else if (layer.sprite.kind === "textBlock") {
+        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;
+      } else {
+        pixArea = e.size * e.size;
+      }
       totalCoverage += pixArea * e.alpha / (w * h);
     }
     if (layer.links) {
@@ -1880,6 +2335,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";
@@ -2021,6 +2510,24 @@ function textBox(s, e, p) {
     halfY: fh * 0.6
   };
 }
+function textBlockBox(s, _e, p, w, h) {
+  const unitScale = Math.min(w, h);
+  const fsPx = s.fontSize * unitScale;
+  const lh = (s.lineHeight ?? 1.4) * fsPx;
+  const maxWPx = s.maxWidth * unitScale;
+  const maxWEm = maxWPx / fsPx;
+  const lines = breakTextBlock(s.text, maxWEm);
+  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;
+  return {
+    cx,
+    cy: p.y + totalH / 2,
+    halfX: maxLineW / 2,
+    halfY: totalH / 2
+  };
+}
 function luminanceGrid(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
@@ -2142,6 +2649,12 @@ function luminanceGrid(spec, opts = {}) {
           centerY = box.cy;
           halfX = box.halfX;
           halfY = box.halfY;
+        } else if (s.kind === "textBlock") {
+          const box = textBlockBox(s, e, p, w, h);
+          centerX = box.cx;
+          centerY = box.cy;
+          halfX = box.halfX;
+          halfY = box.halfY;
         }
         const circular = s.kind === "circle" || s.kind === "ring";
         const soft = s.kind === "circle" && !!s.soft;
@@ -2153,7 +2666,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" ? 0.55 : 1;
+        const inkWeight = s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1;
         for (let r = r0; r <= r1; r++) {
           for (let c = c0; c <= c1; c++) {
             const dx = (c + 0.5) * cellW - centerX;
@@ -2312,6 +2825,13 @@ function textSprites(spec, opts = {}) {
   const t = opts.t ?? 5e3;
   const out = [];
   scene.layers.forEach(({ layer, entities }, layerIndex) => {
+    if (layer.sprite.kind === "textBlock") {
+      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) });
+      return;
+    }
     if (layer.sprite.kind !== "text") return;
     const s = layer.sprite;
     const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
@@ -2362,6 +2882,9 @@ function dominanceRanking(spec, opts = {}) {
       } else if (s.kind === "text") {
         const box = textBox(s, e, { x: 0, y: 0 });
         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;
       } else entArea = sz * sz * 0.55;
       area += entArea * a;
       if (layer.trail) {
@@ -3213,6 +3736,36 @@ var DASHBOARD_SPEC = {
   ]
 };
 
+// src/examples/haiku.ts
+var HAIKU_SPEC = {
+  schemaVersion: 1,
+  id: "haiku",
+  label: "Haiku",
+  seed: 42,
+  background: { type: "solid", color: "#080812" },
+  layers: [
+    {
+      count: 1,
+      sprite: {
+        kind: "textBlock",
+        text: "An old silent pond\nA frog jumps into the pond \u2014\nSplash! Silence again.",
+        maxWidth: 0.8,
+        fontSize: 0.05,
+        lineHeight: 1.8,
+        align: "center",
+        color: "#c8cad4"
+      },
+      motion: { type: "static" },
+      position: { x: 0.1, y: 0.35 }
+    },
+    {
+      count: 30,
+      sprite: { kind: "circle", radius: [5e-4, 15e-4], color: "#3a3a5c" },
+      motion: { type: "drift", speed: [2e-3, 6e-3], angle: 270 }
+    }
+  ]
+};
+
 // src/examples/lanterns.ts
 var LANTERNS_SPEC = {
   schemaVersion: 1,
@@ -3906,7 +4459,8 @@ var SCHEMA_EXAMPLES = [
   { id: "polygons", label: "Polygons", spec: POLYGONS_SPEC },
   { id: "matrix-rain", label: "Matrix Rain", spec: MATRIX_RAIN_SPEC },
   { id: "procession", label: "Night Procession", spec: PROCESSION_SPEC },
-  { id: "nostalghia-candle", label: "Nostalghia's Candle", spec: NOSTALGHIA_CANDLE_SPEC }
+  { id: "nostalghia-candle", label: "Nostalghia's Candle", spec: NOSTALGHIA_CANDLE_SPEC },
+  { id: "haiku", label: "Haiku", spec: HAIKU_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -3920,6 +4474,7 @@ export {
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
+  HAIKU_SPEC,
   LANTERNS_SPEC,
   LIMITS,
   MATRIX_RAIN_SPEC,
@@ -3934,12 +4489,16 @@ export {
   SNOWFALL_SPEC,
   WARP_NEAR,
   WARP_TUNNEL_SPEC,
+  adviseSequence,
   adviseSpec,
   alphaAt,
   applyDeltasToSpec,
+  assertValidSequence,
   assertValidSpec,
+  breakTextBlock,
   buildEntities,
   compileSaver,
+  compileSequence,
   describeScene,
   diffScenes,
   dominanceRanking,
@@ -3956,6 +4515,7 @@ export {
   positionAt,
   renderBrailleMap,
   renderDensityMap,
+  resolveSegment,
   resolveSpecPath,
   rotationAt,
   sizeAt,
@@ -3964,6 +4524,7 @@ export {
   steerablePaths,
   structuralSignature,
   textSprites,
+  validateSequence,
   validateSpec
 };
 //# sourceMappingURL=index.js.map