@idle-screens/schema 3.2.0 → 3.3.0

package/FORMAT.md

@@ -313,8 +313,14 @@ the final segment may omit duration (holds indefinitely).
 **Advance mode:** `auto` (default), `input`, or `either`. Validated but not
 wired to runtime behavior — timer/input drivers are planned for a follow-up.
 
-**Transitions:** `{ type: 'cut' }` is the only supported transition. `fade` is
-defined as a type but rejected at validation.
+**Transitions:** `{ type: 'cut' }` (default) performs a hard switch.
+`{ type: 'morph', dur: number }` smoothly interpolates paint properties
+(colors, opacity values) over `dur` ms when crossing into the next segment.
+Morph requires structurally identical adjacent segments (same
+`structuralSignature`); if they differ, the engine falls back to cut and the
+validator emits a `morph-structural-mismatch` warning. During a morph, entity
+placement inherits the outgoing segment's seed — the incoming segment's own
+seed is unused. `dur` must be between 200 and 5000 ms.
 
 **Time mapping:** global clock `T` maps to `(segmentIndex, localT)` via prefix
 sums of durations. Half-open segments: `[start, start+duration)`. With

package/dist/index.d.ts

@@ -431,9 +431,12 @@ declare const LIMITS: {
     readonly maxTransitionDur: 5000;
     readonly minTransitionDur: 200;
 };
-interface SequenceTransition {
+type SequenceTransition = {
     type: 'cut';
-}
+} | {
+    type: 'morph';
+    dur: number;
+};
 interface SequenceSegment {
     key: string;
     scene: SaverSpec;
@@ -681,6 +684,14 @@ declare function adviseSpec(spec: SaverSpec, viewport?: {
     width: number;
     height: number;
 }): SpecWarning[];
+/**
+ * Non-blocking advisory warnings for a validated sequence envelope.
+ * Checks cross-segment luminance jumps at boundaries and per-segment advisories.
+ */
+declare function adviseSequence(seq: IdleSequence, viewport?: {
+    width: number;
+    height: number;
+}): SpecWarning[];
 
 interface LayerSnapshot {
     key: string | undefined;
@@ -1075,4 +1086,4 @@ declare const EXAMPLE_SPECS: SaverSpec[];
 /** Lookup by saver id. */
 declare const EXAMPLE_BY_ID: Readonly<Record<string, SaverSpec>>;
 
-export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, type ResolvedSegment, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, validateSequence, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, type ResolvedSegment, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, validateSequence, validateSpec };

package/dist/index.js

@@ -54,8 +54,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);
@@ -152,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");
@@ -667,8 +796,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 +817,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) {
@@ -1213,135 +1363,6 @@ 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 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));
-    }
-    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/sequence.ts
 function resolveSegment(seq, T) {
   const { segments, loop } = seq;
@@ -1856,6 +1877,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 +1917,12 @@ 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;
   constructor(seq, ctx) {
     this.seq = seq;
     let surface = ctx.surface ?? null;
@@ -1891,12 +1938,33 @@ var SequenceInstance = class {
     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];
@@ -1917,15 +1985,51 @@ var SequenceInstance = class {
   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;
+        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);
     }
-    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;
@@ -2231,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";
@@ -4351,6 +4489,7 @@ export {
   SNOWFALL_SPEC,
   WARP_NEAR,
   WARP_TUNNEL_SPEC,
+  adviseSequence,
   adviseSpec,
   alphaAt,
   applyDeltasToSpec,