@idle-screens/schema 3.8.0 → 3.9.1

package/dist/index.js

@@ -246,7 +246,9 @@ function steerablePaths(spec) {
     if (prefix) out.push(prefix);
   };
   walk(spec, "", "");
-  return out;
+  const ignored = ignoredPropertyPaths(spec);
+  if (ignored.length === 0) return out;
+  return out.filter((p) => !ignored.some((ig) => p === ig || p.startsWith(`${ig}.`)));
 }
 function sequenceSteerablePaths(seq) {
   const out = /* @__PURE__ */ new Set(["sequence.segment"]);
@@ -361,6 +363,16 @@ var LAYER_PROPS_ON_SPRITE = /* @__PURE__ */ new Set(["blend", "trail", "alpha",
 function unknownKeys(obj, known) {
   return Object.keys(obj).filter((k) => !known.has(k));
 }
+function dimUnit(spec) {
+  return isObj(spec) && spec.units === "px" ? "px" : "fractions of min(width, height)";
+}
+function rangeMsg(spec, note) {
+  return `must be a [min,max] range of positive ${dimUnit(spec)}${note ? ` (${note})` : ""}`;
+}
+function positiveScalar(v, path, err, msg = "must be > 0") {
+  if (Array.isArray(v)) err(path, "must be a single number > 0, not a [min,max] range");
+  else if (!isNum(v) || v <= 0) err(path, msg);
+}
 function normalizeColors(spec) {
   if (!isObj(spec) || !Array.isArray(spec.layers)) return;
   for (const layer of spec.layers) {
@@ -375,6 +387,13 @@ function normalizeColors(spec) {
 }
 function validateSpec(spec) {
   normalizeColors(spec);
+  return validateSpecCore(spec);
+}
+function ignoredPropertyPaths(spec) {
+  if (!isObj(spec)) return [];
+  return (validateSpecCore(spec).warnings ?? []).filter((w) => w.code === "unknown-property" || w.code === "misplaced-property").map((w) => w.path.replace(/\[(\d+)\]/g, ".$1"));
+}
+function validateSpecCore(spec) {
   const errors = [];
   const warnings = [];
   const err = (path, message) => void errors.push({ path, message });
@@ -471,7 +490,7 @@ function validateBackground(bg, err, warn) {
       if (!isObj(bg.band)) err("background.band", "must be an object");
       else {
         color(bg.band.color, "background.band.color", err);
-        if (!isNum(bg.band.height) || bg.band.height <= 0) err("background.band.height", "must be > 0");
+        positiveScalar(bg.band.height, "background.band.height", err);
       }
     }
     for (const k of unknownKeys(bg, KNOWN_BG_GRADIENT)) {
@@ -537,7 +556,7 @@ function validateLayer(layer, path, err, warn, spec) {
     err(`${path}.count`, `at most ${LIMITS.maxPerLayer} per layer`);
   }
   if (layer.size !== void 0 && (!isRange(layer.size) || layer.size[0] <= 0)) {
-    err(`${path}.size`, "must be a [min,max] range of positive px");
+    err(`${path}.size`, rangeMsg(spec));
   }
   if (layer.wrap !== void 0 && typeof layer.wrap !== "boolean") err(`${path}.wrap`, "must be a boolean");
   if (layer.flip !== void 0 && typeof layer.flip !== "boolean") err(`${path}.flip`, "must be a boolean");
@@ -634,16 +653,12 @@ function validateLayer(layer, path, err, warn, spec) {
       if (!isNum(layer.links.k) || !Number.isInteger(layer.links.k) || layer.links.k < 1 || layer.links.k > LIMITS.maxLinksK) {
         err(`${path}.links.k`, `must be an integer 1..${LIMITS.maxLinksK}`);
       }
-      if (!isNum(layer.links.maxDist) || layer.links.maxDist <= 0) {
-        err(`${path}.links.maxDist`, "must be > 0");
-      }
+      positiveScalar(layer.links.maxDist, `${path}.links.maxDist`, err);
       if (layer.links.color !== void 0) color(layer.links.color, `${path}.links.color`, err);
       if (layer.links.alpha !== void 0 && (!isNum(layer.links.alpha) || layer.links.alpha < 0 || layer.links.alpha > 1)) {
         err(`${path}.links.alpha`, "must be 0..1");
       }
-      if (layer.links.width !== void 0 && (!isNum(layer.links.width) || layer.links.width <= 0)) {
-        err(`${path}.links.width`, "must be > 0");
-      }
+      if (layer.links.width !== void 0) positiveScalar(layer.links.width, `${path}.links.width`, err);
       if (layer.links.mode !== void 0 && !["nearest", "chain", "random"].includes(layer.links.mode)) {
         err(`${path}.links.mode`, "must be 'nearest' | 'chain' | 'random'");
       }
@@ -797,10 +812,10 @@ function validateLayer(layer, path, err, warn, spec) {
       }
     }
   }
-  validateSprite(layer.sprite, `${path}.sprite`, err, warn);
+  validateSprite(layer.sprite, `${path}.sprite`, err, warn, spec);
   validateMotion(layer.motion, `${path}.motion`, err, warn, spec);
 }
-function validateSprite(sprite, path, err, warn) {
+function validateSprite(sprite, path, err, warn, spec) {
   if (!isObj(sprite)) return err(path, "must be an object");
   let knownSet;
   if (sprite.kind === "emoji") {
@@ -824,32 +839,30 @@ function validateSprite(sprite, path, err, warn) {
     if (sprite.baseline !== void 0 && !["top", "middle", "bottom"].includes(sprite.baseline)) {
       err(`${path}.baseline`, "must be top | middle | bottom");
     }
-    if (sprite.maxWidth !== void 0 && (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0)) {
-      err(`${path}.maxWidth`, "must be a positive number");
-    }
+    if (sprite.maxWidth !== void 0) positiveScalar(sprite.maxWidth, `${path}.maxWidth`, err, "must be a positive number");
     validateTextRole(sprite, path, err);
     validateCycle(sprite, path, err);
   } else if (sprite.kind === "circle") {
     knownSet = KNOWN_CIRCLE;
-    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
+    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, rangeMsg(spec));
     color(sprite.color, `${path}.color`, err);
     if (sprite.soft !== void 0 && typeof sprite.soft !== "boolean") err(`${path}.soft`, "must be a boolean");
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "ring") {
     knownSet = KNOWN_RING;
-    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
+    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, rangeMsg(spec));
     color(sprite.color, `${path}.color`, err);
-    if (sprite.width !== void 0 && (!isNum(sprite.width) || sprite.width <= 0)) err(`${path}.width`, "must be > 0");
+    if (sprite.width !== void 0) positiveScalar(sprite.width, `${path}.width`, err);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "streak") {
     knownSet = KNOWN_STREAK;
-    if (!isRange(sprite.length) || sprite.length[0] <= 0) err(`${path}.length`, "must be a [min,max] range of positive px");
+    if (!isRange(sprite.length) || sprite.length[0] <= 0) err(`${path}.length`, rangeMsg(spec));
     color(sprite.color, `${path}.color`, err);
-    if (sprite.width !== void 0 && (!isNum(sprite.width) || sprite.width <= 0)) err(`${path}.width`, "must be > 0");
+    if (sprite.width !== void 0) positiveScalar(sprite.width, `${path}.width`, err);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "rect") {
     knownSet = KNOWN_RECT;
-    if (!isRange(sprite.width) || sprite.width[0] <= 0) err(`${path}.width`, "must be a [min,max] range of positive px");
+    if (!isRange(sprite.width) || sprite.width[0] <= 0) err(`${path}.width`, rangeMsg(spec));
     if (sprite.aspect !== void 0 && (!isRange(sprite.aspect) || sprite.aspect[0] <= 0)) {
       err(`${path}.aspect`, "must be a [min,max] range of positive height/width ratios");
     }
@@ -863,9 +876,9 @@ function validateSprite(sprite, path, err, warn) {
     if (!Array.isArray(sprite.values) || sprite.values.length === 0 || sprite.values.length > LIMITS.maxPerLayer || !sprite.values.every((v) => isNum(v) && v >= 0)) {
       err(`${path}.values`, `must be 1..${LIMITS.maxPerLayer} numbers >= 0`);
     }
-    if (!isNum(sprite.length) || sprite.length <= 0) err(`${path}.length`, "must be > 0 (full-scale bar length)");
-    if (!isNum(sprite.thickness) || sprite.thickness <= 0) err(`${path}.thickness`, "must be > 0");
-    if (sprite.max !== void 0 && (!isNum(sprite.max) || sprite.max <= 0)) err(`${path}.max`, "must be > 0");
+    positiveScalar(sprite.length, `${path}.length`, err, "must be > 0 (full-scale bar length)");
+    positiveScalar(sprite.thickness, `${path}.thickness`, err);
+    if (sprite.max !== void 0) positiveScalar(sprite.max, `${path}.max`, err);
     if (sprite.direction !== void 0 && !["right", "left", "up", "down"].includes(sprite.direction)) {
       err(`${path}.direction`, "must be 'right' | 'left' | 'up' | 'down'");
     }
@@ -873,7 +886,7 @@ function validateSprite(sprite, path, err, warn) {
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "polygon") {
     knownSet = KNOWN_POLYGON;
-    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px (circumradius)");
+    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, rangeMsg(spec, "circumradius"));
     if (sprite.sides !== void 0 && sprite.points !== void 0) {
       err(`${path}.sides`, "use sides (a regular polygon) or points (a custom one), not both");
     }
@@ -886,9 +899,9 @@ function validateSprite(sprite, path, err, warn) {
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "stroke") {
     knownSet = KNOWN_STROKE;
-    if (!isRange(sprite.length) || sprite.length[0] <= 0) err(`${path}.length`, "must be a [min,max] range of positive px (the mark's bounding size)");
+    if (!isRange(sprite.length) || sprite.length[0] <= 0) err(`${path}.length`, rangeMsg(spec, "the mark's bounding size"));
     validateShapePoints(sprite.points, `${path}.points`, 2, err);
-    if (sprite.width !== void 0 && (!isNum(sprite.width) || sprite.width <= 0)) err(`${path}.width`, "must be > 0");
+    if (sprite.width !== void 0) positiveScalar(sprite.width, `${path}.width`, err);
     if (sprite.curve !== void 0 && sprite.curve !== "smooth" && sprite.curve !== "linear") err(`${path}.curve`, "must be 'smooth' | 'linear'");
     if (sprite.taper !== void 0 && typeof sprite.taper !== "boolean") err(`${path}.taper`, "must be a boolean");
     if (sprite.orient !== void 0 && typeof sprite.orient !== "boolean") err(`${path}.orient`, "must be a boolean");
@@ -901,10 +914,14 @@ function validateSprite(sprite, path, err, warn) {
     } 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) {
+    if (Array.isArray(sprite.maxWidth)) {
+      err(`${path}.maxWidth`, "must be a single number (viewport fraction), not a [min,max] range");
+    } else 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) {
+    if (Array.isArray(sprite.fontSize)) {
+      err(`${path}.fontSize`, "must be a single number (viewport fraction), not a [min,max] range");
+    } else 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)) {
@@ -1052,7 +1069,7 @@ function validateMotion(motion, path, err, warn, spec) {
         warn(`${path}.speed`, "near-zero-speed", `orbit speed is near zero \u2014 entities will appear frozen. Typical range: 5\u201360 deg/sec`);
       }
     }
-    if (!isRange(motion.radius) || motion.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
+    if (!isRange(motion.radius) || motion.radius[0] <= 0) err(`${path}.radius`, rangeMsg(spec));
     if (motion.center !== void 0) {
       if (!isObj(motion.center)) {
         err(`${path}.center`, "must be {x, y} (0..1) or { layer: key }");
@@ -2233,7 +2250,7 @@ function fieldAt(u, v, t, cfg, seed) {
 }
 function hexToRgb255(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);
+  const n = /^#[0-9a-f]{6}$/i.test(h) ? parseInt(h.slice(1), 16) : NaN;
   if (Number.isNaN(n)) return [128, 128, 128];
   return [n >> 16 & 255, n >> 8 & 255, n & 255];
 }
@@ -2475,8 +2492,16 @@ function bedRenderSeed(seq) {
   const raw = seq.bed.seed ?? (seq.seed !== void 0 ? seq.seed + LIMITS.maxSegments : void 0);
   return raw === void 0 ? void 0 : normalizeSeed(raw);
 }
+function sequenceWantsFinish(seq) {
+  return seq.finish !== void 0 || seq.segments.some((s) => s.scene.finish !== void 0);
+}
 function sequenceSwapCompatible(prev, next) {
   if (prev.segments.length !== next.segments.length) return false;
+  if (prev.finish !== void 0 || next.finish !== void 0) {
+    if (prev.seed === void 0 !== (next.seed === void 0)) return false;
+    if (prev.seed !== void 0 && next.seed !== void 0 && normalizeSeed(prev.seed) !== normalizeSeed(next.seed)) return false;
+  }
+  if (sequenceWantsFinish(prev) !== sequenceWantsFinish(next)) return false;
   if (prev.loop !== next.loop) return false;
   if ((prev.sync ?? "mount") !== (next.sync ?? "mount")) return false;
   if (!!prev.bed !== !!next.bed) return false;
@@ -2851,7 +2876,7 @@ var SpecInstance = class {
     }
     if (sprite.kind === "streak") {
       const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
-      const heading = headingAt(e, t, this.w, this.h) ?? 0;
+      const heading = (headingAt(e, t, this.w, this.h) ?? 0) + rot;
       const tailX = p.x - Math.cos(heading) * sz;
       const tailY = p.y - Math.sin(heading) * sz;
       const g = ctx.createLinearGradient(tailX, tailY, p.x, p.y);
@@ -3425,8 +3450,7 @@ var SequenceInstance = class {
     this.canvas = canvas;
     this.seed = (seq.seed ?? ctx.seed ?? 0) >>> 0 || 1;
     this.animateFinish = capabilityTier !== "basic" && capabilityTier !== "minimal";
-    const wantsFinish = seq.finish !== void 0 || seq.segments.some((s) => s.scene.finish !== void 0);
-    if (wantsFinish && surface) {
+    if (sequenceWantsFinish(seq) && surface) {
       const pass = createFinishPass(surface, this.seed);
       if (pass) {
         this.finishPass = pass;
@@ -3950,13 +3974,14 @@ function legibilityRatio(a, b) {
   const lo = Math.min(la, lb);
   return (hi + 0.05) / (lo + 0.05);
 }
-function backgroundRgbAt(spec, yPx, h, unit, xPx, w, seed) {
+function backgroundRgbAt(spec, yPx, h, unit, xPx, w, seed, t = 0) {
   const bg = spec.background;
   if (!bg || bg.type === "solid") return hexRgb(bg?.color ?? "#05050a");
   if (bg.type === "field") {
     if (xPx === void 0 || w === void 0) return backgroundRgb(spec);
     const short = Math.max(1, Math.min(w, h));
-    const c = fieldRgbAt(xPx / short, yPx / short, 0, bg, seed ?? spec.seed ?? 42);
+    const ft = fieldSampleTime(bg, t);
+    const c = fieldRgbAt(xPx / short, yPx / short, ft, bg, seed ?? spec.seed ?? 42);
     return { r: c[0] / 255, g: c[1] / 255, b: c[2] / 255 };
   }
   if (bg.band) {
@@ -4512,7 +4537,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     for (const box of boxes) {
       const cy = (box.y0 + box.y1) / 2;
       const cx = (box.x0 + box.x1) / 2;
-      const groundRgb = backgroundRgbAt(spec, cy, h, scale, cx, w, opts.backgroundSeed ?? opts.seed);
+      const groundRgb = backgroundRgbAt(spec, cy, h, scale, cx, w, opts.backgroundSeed ?? opts.seed, opts.t ?? COHESION_T);
       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;
@@ -4762,7 +4787,7 @@ var LINE_SALIENCE = 3.5;
 var GHOST_TAPS = 12;
 function buildScene(spec, opts) {
   const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
-  const seed = opts.seed ?? spec.seed ?? 42;
+  const seed = normalizeSeed(opts.seed ?? spec.seed ?? 42);
   const scale = spec.units === "px" ? 1 : Math.min(w, h);
   const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
   let countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
@@ -4774,7 +4799,7 @@ function buildScene(spec, opts) {
   const layers = spec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, w, h, scale, countScale) }));
   const byKey = /* @__PURE__ */ new Map();
   for (const { layer, entities } of layers) if (layer.key) byKey.set(layer.key, entities);
-  return { w, h, scale, layers, byKey };
+  return { w, h, scale, seed, layers, byKey };
 }
 function posOf(scene, e, t) {
   const p = positionAt(e, t, scene.w, scene.h);
@@ -4854,7 +4879,7 @@ function luminanceGrid(spec, opts = {}) {
   } else if (bg.type === "field") {
     bgCells = new Array(cols * rows);
     const short = Math.max(1, Math.min(w, h));
-    const seed = opts.seed ?? spec.seed ?? 42;
+    const seed = scene.seed;
     const ft = fieldSampleTime(bg, t);
     for (let r = 0; r < rows; r++) {
       let rowSum = 0;
@@ -4980,7 +5005,7 @@ function luminanceGrid(spec, opts = {}) {
           continue;
         }
         if (s.kind === "streak") {
-          const heading = headingAt(e, tPass, w, h) ?? 0;
+          const heading = (headingAt(e, tPass, w, h) ?? 0) + rotationAt(e, tPass);
           const steps = Math.max(2, Math.ceil(sz / Math.min(cellW, cellH)));
           const wgt = Math.min(1, (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale / cellH);
           for (let i = 0; i <= steps; i++) {
@@ -6186,6 +6211,616 @@ var DASHBOARD_SPEC = {
   ]
 };
 
+// src/examples/sparse-night.ts
+var SPARSE_NIGHT_SPEC = {
+  schemaVersion: 1,
+  id: "sparse-night",
+  label: "Sparse Night",
+  seed: 101,
+  motionIntensity: "calm",
+  density: "sparse",
+  background: { type: "solid", color: "#02030a" },
+  layers: [
+    {
+      key: "grain",
+      count: 110,
+      sprite: {
+        kind: "circle",
+        radius: [3e-4, 9e-4],
+        color: "#c9d4e6"
+      },
+      motion: { type: "static" },
+      alpha: [0.05, 0.3],
+      pulse: { amp: 0.08, period: 7e3 }
+    },
+    {
+      key: "figure",
+      count: 5,
+      sprite: {
+        kind: "circle",
+        radius: [16e-4, 22e-4],
+        color: "#dfe8f2"
+      },
+      motion: { type: "drift", speed: [4e-4, 9e-4] },
+      alpha: [0.4, 0.7],
+      region: { x: [0.36, 0.64], y: [0.32, 0.62] },
+      links: {
+        k: 2,
+        maxDist: 0.09,
+        color: "#7f97b8",
+        alpha: 0.16,
+        width: 4e-4,
+        mode: "chain",
+        closed: true
+      }
+    },
+    {
+      key: "satellite",
+      count: 1,
+      sprite: {
+        kind: "circle",
+        radius: [24e-4, 24e-4],
+        color: "#e8b04a",
+        soft: true
+      },
+      motion: { type: "orbit", speed: [3, 3], radius: [0.34, 0.4] },
+      alpha: [0.85, 0.85],
+      blend: "lighter",
+      emit: { every: 18e3, life: 3e3, jitter: 0, grow: [0.5, 1.6] }
+    }
+  ]
+};
+
+// src/examples/signal-board.ts
+var SIGNAL_BOARD_SPEC = {
+  schemaVersion: 1,
+  id: "signal-board",
+  label: "Signal Board",
+  seed: 707,
+  motionIntensity: "calm",
+  background: { type: "solid", color: "#0d0b08" },
+  layers: [
+    {
+      key: "readout",
+      count: 9,
+      sprite: {
+        kind: "bar",
+        values: [62, 38, 84, 21, 55, 91, 44, 70, 29],
+        max: 100,
+        // Cell pitch is the table's authored `gap` (0.07), so a full-value
+        // bar must stay under that or neighboring cells' bars overlap.
+        // 0.06 leaves a hairline margin.
+        length: 0.06,
+        thickness: 0.013,
+        color: "#ffb000",
+        direction: "right"
+      },
+      motion: { type: "static" },
+      layout: { type: "table", columns: 3, gap: 0.07 },
+      region: { x: [0.1, 0.9], y: [0.34, 0.78] },
+      alpha: [0.5, 0.62]
+    },
+    {
+      key: "labels",
+      count: 9,
+      sprite: {
+        kind: "text",
+        strings: [
+          "A-01",
+          "A-02",
+          "A-03",
+          "B-01",
+          "B-02",
+          "B-03",
+          "C-01",
+          "C-02",
+          "C-03"
+        ],
+        color: "#b08a3a",
+        font: "monospace",
+        align: "left"
+      },
+      motion: { type: "static" },
+      size: [0.011, 0.011],
+      layout: { type: "table", columns: 3, gap: 0.07 },
+      region: { x: [0.1, 0.9], y: [0.28, 0.72] },
+      alpha: [0.55, 0.55]
+    },
+    {
+      key: "caption",
+      count: 1,
+      sprite: {
+        kind: "textBlock",
+        text: "STATION 7 \u2014 QUIET HOURS",
+        maxWidth: 0.6,
+        fontSize: 0.022,
+        lineHeight: 1.4,
+        align: "left",
+        anchor: "top-left",
+        font: "bold monospace",
+        color: "#c8862a"
+      },
+      motion: { type: "static" },
+      position: { x: 0.1, y: 0.14 },
+      alpha: [0.8, 0.8]
+    },
+    {
+      key: "sweep",
+      count: 1,
+      sprite: {
+        kind: "stroke",
+        length: [1.4, 1.4],
+        points: [
+          [-1, 0],
+          [1, 0]
+        ],
+        width: 16e-4,
+        color: "#33ff66"
+      },
+      motion: { type: "drift", speed: [0.012, 0.012], angle: 90 },
+      alpha: [0.22, 0.22],
+      blend: "screen"
+    }
+  ]
+};
+
+// src/examples/phase-duet.ts
+var PHASE_DUET_SPEC = {
+  schemaVersion: 1,
+  id: "phase-duet",
+  label: "Phase Duet",
+  seed: 88,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#0a0f1c" },
+      { at: 0.6, color: "#101b2e" },
+      { at: 1, color: "#07141a" }
+    ]
+  },
+  layers: [
+    {
+      key: "ripple",
+      count: 60,
+      sprite: {
+        kind: "circle",
+        radius: [18e-4, 3e-3],
+        color: "#6fd3c7",
+        colors: ["#6fd3c7", "#9fb8d8"],
+        colorWeights: [2, 1]
+      },
+      motion: { type: "static" },
+      layout: { type: "grid", columns: 10, jitter: 0 },
+      alpha: [0.3, 0.55],
+      pulse: { amp: 0.35, period: 6e3, wave: { wavelength: 0.7, angle: 25 } },
+      clock: { phase: 0, rate: 1 }
+    },
+    {
+      key: "rings",
+      count: 3,
+      sprite: {
+        kind: "ring",
+        radius: [0.05, 0.09],
+        width: 12e-4,
+        color: "#6fd3c7"
+      },
+      motion: { type: "static" },
+      alpha: [0.25, 0.35],
+      blend: "lighter",
+      grow: { amp: 0.5, period: 6e3 },
+      clock: { phase: 0, rate: 1 }
+    },
+    {
+      key: "heart",
+      count: 1,
+      sprite: {
+        kind: "circle",
+        radius: [0.11, 0.11],
+        color: "#9fb8d8",
+        soft: true
+      },
+      motion: { type: "static" },
+      position: { x: 0.5, y: 0.5 },
+      alpha: [0.22, 0.22],
+      blend: "lighter",
+      grow: { amp: 0.25, period: 6e3 },
+      clock: { phase: 0, rate: 1 }
+    }
+  ]
+};
+
+// src/examples/web-work.ts
+var WEB_WORK_SPEC = {
+  schemaVersion: 1,
+  id: "web-work",
+  label: "Web Work",
+  seed: 31,
+  motionIntensity: "calm",
+  background: { type: "solid", color: "#04070c" },
+  layers: [
+    {
+      key: "nodes",
+      count: 44,
+      sprite: {
+        kind: "circle",
+        radius: [18e-4, 34e-4],
+        color: "#8fb4d8",
+        colors: ["#8fb4d8", "#c9d8e6"],
+        colorWeights: [2, 1]
+      },
+      motion: {
+        type: "drift",
+        speed: [2e-3, 6e-3],
+        angle: 0,
+        bidirectional: true
+      },
+      alpha: [0.45, 0.8],
+      links: {
+        k: 3,
+        maxDist: 0.3,
+        color: "#5f7f9f",
+        alpha: 0.16,
+        width: 5e-4,
+        mode: "random",
+        falloff: true
+      }
+    },
+    {
+      key: "flags",
+      count: 22,
+      sprite: {
+        kind: "stroke",
+        length: [0.02, 0.045],
+        points: [
+          [-1, 0.2],
+          [-0.2, -0.5],
+          [0.6, -0.3],
+          [1, 0.1]
+        ],
+        width: 16e-4,
+        taper: true,
+        orient: true,
+        color: "#6f93b8",
+        colors: ["#6f93b8", "#9fb8d8"]
+      },
+      motion: {
+        type: "drift",
+        speed: [0.01, 0.03],
+        angle: 0,
+        bidirectional: true
+      },
+      alpha: [0.3, 0.6]
+    }
+  ]
+};
+
+// src/examples/shard-fall.ts
+var SHARD_FALL_SPEC = {
+  schemaVersion: 1,
+  id: "shard-fall",
+  label: "Shard Fall",
+  seed: 214,
+  motionIntensity: "moderate",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#efe6d6" },
+      { at: 0.55, color: "#e6d6bd" },
+      { at: 1, color: "#d9c39f" }
+    ]
+  },
+  layers: [
+    {
+      key: "shards",
+      count: 26,
+      sprite: {
+        kind: "polygon",
+        points: [
+          [-1, 0.35],
+          [-0.25, -1],
+          [0.85, -0.4],
+          [0.4, 0.9]
+        ],
+        radius: [0.012, 0.03],
+        color: "#b4593a",
+        colors: ["#b4593a", "#7f8a5e", "#5a6b7d", "#8a5a3c"],
+        colorWeights: [2, 2, 1, 2]
+      },
+      motion: { type: "drift", speed: [0.012, 0.032], angle: 90 },
+      alpha: [0.85, 0.95],
+      rotate: [-180, 180],
+      spin: [-35, 35]
+    },
+    {
+      key: "shadows",
+      count: 2,
+      sprite: {
+        kind: "circle",
+        radius: [0.18, 0.22],
+        color: "#5a4a34",
+        soft: true
+      },
+      motion: {
+        type: "wander",
+        speed: [3e-3, 5e-3],
+        meander: 0.04,
+        coherence: 0.6
+      },
+      alpha: [0.2, 0.28],
+      blend: "multiply"
+    }
+  ]
+};
+
+// src/examples/murmur.ts
+var MURMUR_SPEC = {
+  schemaVersion: 1,
+  id: "murmur",
+  label: "Murmur",
+  seed: 512,
+  motionIntensity: "moderate",
+  density: "dense",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#151a26" },
+      { at: 0.5, color: "#232c3d" },
+      { at: 1, color: "#3a3f52" }
+    ]
+  },
+  layers: [
+    {
+      key: "flock-a",
+      count: 260,
+      sprite: {
+        kind: "streak",
+        length: [4e-3, 0.012],
+        width: 12e-4,
+        color: "#c9d4e6",
+        colors: ["#c9d4e6", "#8fa6c4"],
+        colorWeights: [2, 1]
+      },
+      motion: {
+        type: "wander",
+        speed: [0.015, 0.06],
+        meander: 0.05,
+        coherence: 0.95
+      },
+      alpha: [0.25, 0.6],
+      blend: "screen"
+    },
+    {
+      // The cap is 400 per layer, so a flock above it is two registers of the
+      // same body — slightly different speed and length ranges read as depth.
+      key: "flock-b",
+      count: 260,
+      sprite: {
+        kind: "streak",
+        length: [6e-3, 0.014],
+        width: 12e-4,
+        color: "#8fa6c4",
+        colors: ["#8fa6c4", "#c9d4e6"],
+        colorWeights: [2, 1]
+      },
+      motion: {
+        type: "wander",
+        speed: [0.02, 0.05],
+        meander: 0.045,
+        coherence: 0.93
+      },
+      alpha: [0.2, 0.5],
+      blend: "screen"
+    },
+    {
+      key: "grain",
+      count: 100,
+      sprite: { kind: "circle", radius: [5e-4, 12e-4], color: "#c9d4e6" },
+      motion: { type: "static" },
+      alpha: [0.06, 0.2]
+    }
+  ]
+};
+
+// src/examples/three-movements.ts
+var THREE_MOVEMENTS_SEQUENCE = {
+  format: "idle-sequence",
+  schemaVersion: 1,
+  id: "three-movements",
+  label: "Three Movements",
+  seed: 404,
+  loop: false,
+  sync: "mount",
+  finish: { grain: 0.3, dither: 0.12 },
+  bed: {
+    schemaVersion: 1,
+    id: "three-movements-bed",
+    label: "Three Movements \u2014 bed",
+    background: {
+      type: "field",
+      scale: 2,
+      octaves: 3,
+      warp: 0.4,
+      quantize: 0,
+      bands: ["#0a0d18", "#141c2e", "#233046"],
+      drift: { period: 6e4, amount: 0.25 }
+    },
+    layers: [
+      {
+        key: "motes",
+        count: 12,
+        sprite: {
+          kind: "circle",
+          radius: [12e-4, 3e-3],
+          color: "#9fb8d8",
+          soft: true
+        },
+        motion: { type: "drift", speed: [2e-3, 6e-3], angle: 90 },
+        alpha: [0.1, 0.25]
+      }
+    ]
+  },
+  segments: [
+    {
+      key: "cold-open",
+      duration: 8e3,
+      transition: { type: "morph", dur: 2500, text: "crossfade" },
+      scene: {
+        schemaVersion: 1,
+        id: "three-movements-cold-open",
+        label: "Cold Open",
+        seed: 11,
+        layers: [
+          {
+            key: "caption",
+            count: 1,
+            sprite: {
+              kind: "textBlock",
+              text: "COLD OPEN.\nThe room before anyone arrives.",
+              maxWidth: 0.6,
+              fontSize: 0.028,
+              lineHeight: 1.5,
+              align: "left",
+              anchor: "top-left",
+              font: "monospace",
+              color: "#9fb8d8",
+              opacity: 0.9,
+              reveal: {
+                progress: 1,
+                mode: "typewriter",
+                speed: 12,
+                caret: { blink: 1.1 }
+              }
+            },
+            motion: { type: "static" },
+            position: { x: 0.1, y: 0.4 },
+            alpha: [0.9, 0.9]
+          },
+          {
+            key: "sparks",
+            count: 30,
+            sprite: {
+              kind: "circle",
+              radius: [12e-4, 26e-4],
+              color: "#c9d8e6"
+            },
+            motion: { type: "static" },
+            alpha: [0.15, 0.45],
+            pulse: { amp: 0.12, period: 6e3 }
+          }
+        ]
+      }
+    },
+    {
+      key: "kindle",
+      duration: 9e3,
+      transition: { type: "fade", dur: 3e3 },
+      scene: {
+        schemaVersion: 1,
+        id: "three-movements-kindle",
+        label: "Kindle",
+        seed: 12,
+        layers: [
+          {
+            key: "caption",
+            count: 1,
+            sprite: {
+              kind: "textBlock",
+              text: "KINDLE.\nOne lamp, and then another.",
+              maxWidth: 0.6,
+              fontSize: 0.028,
+              lineHeight: 1.5,
+              align: "left",
+              anchor: "top-left",
+              font: "monospace",
+              color: "#e8b878",
+              opacity: 0.9,
+              reveal: {
+                progress: 1,
+                mode: "typewriter",
+                speed: 12,
+                caret: { blink: 1.1 }
+              }
+            },
+            motion: { type: "static" },
+            position: { x: 0.1, y: 0.4 },
+            alpha: [0.9, 0.9]
+          },
+          {
+            key: "sparks",
+            count: 30,
+            sprite: {
+              kind: "circle",
+              radius: [12e-4, 26e-4],
+              color: "#e8b878"
+            },
+            motion: { type: "static" },
+            alpha: [0.15, 0.45],
+            pulse: { amp: 0.12, period: 6e3 }
+          }
+        ]
+      }
+    },
+    {
+      key: "dusk",
+      scene: {
+        schemaVersion: 1,
+        id: "three-movements-dusk",
+        label: "Dusk",
+        seed: 13,
+        layers: [
+          {
+            key: "bloom",
+            count: 3,
+            sprite: {
+              kind: "circle",
+              radius: [0.09, 0.14],
+              color: "#7a4a5e",
+              colors: ["#7a4a5e", "#b06a4a"],
+              soft: true
+            },
+            motion: {
+              type: "wander",
+              speed: [1e-3, 2e-3],
+              meander: 0.04,
+              coherence: 0.7
+            },
+            alpha: [0.25, 0.4],
+            blend: "lighter",
+            grow: { amp: 0.3, period: 14e3 }
+          },
+          {
+            key: "strokes",
+            count: 8,
+            sprite: {
+              kind: "stroke",
+              length: [0.1, 0.2],
+              points: [
+                [-1, 0.2],
+                [-0.3, -0.6],
+                [0.5, -0.4],
+                [1, 0.2]
+              ],
+              width: 4e-3,
+              taper: true,
+              color: "#c2447a",
+              colors: ["#c2447a", "#8f2c58"]
+            },
+            motion: {
+              type: "drift",
+              speed: [3e-3, 8e-3],
+              angle: 20,
+              bidirectional: true
+            },
+            alpha: [0.3, 0.5],
+            rotate: [-30, 30]
+          }
+        ]
+      }
+    }
+  ]
+};
+
 // src/examples/facets.ts
 var FACETS_SPEC = {
   schemaVersion: 1,
@@ -7177,6 +7812,71 @@ var WARP_TUNNEL_SPEC = {
   ]
 };
 
+// src/examples/typed-cue.ts
+var TYPED_CUE_SPEC = {
+  schemaVersion: 1,
+  id: "typed-cue",
+  label: "Typed Cue",
+  seed: 19,
+  motionIntensity: "calm",
+  background: { type: "solid", color: "#050608" },
+  layers: [
+    {
+      key: "scan",
+      count: 1,
+      sprite: { kind: "rect", width: [1, 1], aspect: [0.02, 0.02], color: "#16241f", feather: 0.9 },
+      motion: { type: "drift", speed: [0.014, 0.014], angle: 90 },
+      alpha: [0.5, 0.5],
+      blend: "screen"
+    },
+    {
+      key: "headline",
+      count: 1,
+      sprite: {
+        kind: "textBlock",
+        text: "THE SCREEN IS AWAKE.\nWORDS ARRIVE ON THEIR OWN CLOCK.",
+        maxWidth: 0.84,
+        fontSize: 0.03,
+        lineHeight: 1.5,
+        align: "left",
+        anchor: "top-left",
+        font: "bold monospace",
+        color: "#e6e8ef",
+        opacity: 0.94,
+        reveal: {
+          progress: 1,
+          mode: "typewriter",
+          speed: 10,
+          caret: { blink: 1.1, color: "#e6e8ef" }
+        }
+      },
+      motion: { type: "static" },
+      position: { x: 0.08, y: 0.16 },
+      alpha: [0.95, 0.95]
+    },
+    {
+      key: "aside",
+      count: 1,
+      sprite: {
+        kind: "textBlock",
+        text: "and leaves the same way \u2014\na dissolve, not a delete.",
+        maxWidth: 0.5,
+        fontSize: 0.022,
+        lineHeight: 1.5,
+        align: "left",
+        anchor: "bottom-right",
+        font: "monospace",
+        color: "#8f96a3",
+        opacity: 0.85,
+        reveal: { progress: 1, mode: "glyphFade", speed: 6, fade: 0.4 }
+      },
+      motion: { type: "static" },
+      position: { x: 0.92, y: 0.86 },
+      alpha: [0.9, 0.9]
+    }
+  ]
+};
+
 // src/examples/index.ts
 var SCHEMA_EXAMPLES = [
   { id: "aquarium", label: "Aquarium", spec: AQUARIUM_SPEC },
@@ -7199,7 +7899,17 @@ var SCHEMA_EXAMPLES = [
   { id: "facets", label: "Facets", spec: FACETS_SPEC },
   { id: "relay-board", label: "Relay Board", spec: RELAY_BOARD_SPEC },
   { id: "lobby-talk", label: "Lobby Talk", spec: LOBBY_TALK_SPEC },
-  { id: "thermal-field", label: "Thermal Field", spec: THERMAL_FIELD_SPEC }
+  { id: "thermal-field", label: "Thermal Field", spec: THERMAL_FIELD_SPEC },
+  { id: "sparse-night", label: "Sparse Night", spec: SPARSE_NIGHT_SPEC },
+  { id: "typed-cue", label: "Typed Cue", spec: TYPED_CUE_SPEC },
+  { id: "signal-board", label: "Signal Board", spec: SIGNAL_BOARD_SPEC },
+  { id: "phase-duet", label: "Phase Duet", spec: PHASE_DUET_SPEC },
+  { id: "web-work", label: "Web Work", spec: WEB_WORK_SPEC },
+  { id: "shard-fall", label: "Shard Fall", spec: SHARD_FALL_SPEC },
+  { id: "murmur", label: "Murmur", spec: MURMUR_SPEC }
+];
+var EXAMPLE_SEQUENCES = [
+  { id: "three-movements", label: "Three Movements", sequence: THREE_MOVEMENTS_SEQUENCE }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -7215,6 +7925,7 @@ export {
   DITHER_ALPHA,
   DITHER_TILE,
   EXAMPLE_BY_ID,
+  EXAMPLE_SEQUENCES,
   EXAMPLE_SPECS,
   FACETS_SPEC,
   FIELD_BUCKET_MS,
@@ -7229,8 +7940,10 @@ export {
   LIMITS,
   LOBBY_TALK_SPEC,
   MATRIX_RAIN_SPEC,
+  MURMUR_SPEC,
   NOSTALGHIA_CANDLE_SPEC,
   ORRERY_SPEC,
+  PHASE_DUET_SPEC,
   PINGS_SPEC,
   POLYGONS_SPEC,
   PROCESSION_SPEC,
@@ -7239,11 +7952,17 @@ export {
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
+  SHARD_FALL_SPEC,
+  SIGNAL_BOARD_SPEC,
   SNOWFALL_SPEC,
+  SPARSE_NIGHT_SPEC,
   THERMAL_FIELD_SPEC,
+  THREE_MOVEMENTS_SEQUENCE,
+  TYPED_CUE_SPEC,
   WARP_MAX_SCALE,
   WARP_NEAR,
   WARP_TUNNEL_SPEC,
+  WEB_WORK_SPEC,
   adviseSequence,
   adviseSpec,
   alphaAt,
@@ -7279,6 +7998,7 @@ export {
   hasHotSwapSequence,
   headingAt,
   hexToRgb255,
+  ignoredPropertyPaths,
   latticeHash,
   layerCohesion,
   lerpSpec,
@@ -7309,6 +8029,7 @@ export {
   segmentStart,
   sequenceSteerablePaths,
   sequenceSwapCompatible,
+  sequenceWantsFinish,
   sizeAt,
   spriteIndexAt,
   spriteVariants,