@idle-screens/schema 3.9.0 → 3.9.1

package/dist/index.d.ts

@@ -843,6 +843,13 @@ interface IdleSequence {
 }
 
 declare function validateSpec(spec: unknown): ValidationResult;
+/**
+ * Dot-paths (numeric layer indices, as `steerablePaths` spells them) of every
+ * property the validator flags as unknown or misplaced — i.e. fields the
+ * renderer never reads, so steering them does nothing. Pure: unlike
+ * `validateSpec` it never normalises colours into the caller's spec.
+ */
+declare function ignoredPropertyPaths(spec: unknown): string[];
 /** Narrowing helper: validate + cast. Throws with a joined message when invalid. */
 declare function assertValidSpec(spec: unknown): SaverSpec;
 /**
@@ -1235,6 +1242,12 @@ declare function morphNothingMorphable(a: SaverSpec, b: SaverSpec, opts?: {
  * (id, label, schemaVersion, seed, units, kind, type, key) are excluded —
  * they describe structure, not tuneable values.
  *
+ * Properties the validator flags as unknown or misplaced (e.g. `angle` on a
+ * gradient background, `blend` inside a sprite) are excluded too: the
+ * renderer never reads them, so advertising them invites a steer that
+ * silently does nothing. Same source of truth as validateSpec's
+ * "will be ignored" warnings (`ignoredPropertyPaths`).
+ *
  * Layer keys are NOT substituted: paths always use numeric indices.
  * Consumers can map to key-based paths via resolveSpecPath if needed.
  */
@@ -1919,10 +1932,14 @@ declare function sequenceWantsFinish(seq: IdleSequence): boolean;
  *   when present;
  * - the same top-level `seq.seed`, compared normalized (like the mount-time
  *   seed itself) so a change of an exact multiple of 2^32 isn't flagged —
- *   even when every segment and the bed resolve their own seed (so
- *   `segmentRenderSeed`/`bedRenderSeed` are unaffected), a sequence-level
- *   `finish` grain resolves against the instance's mount-time seed
- *   (`frameFinishSeed`), which a swap cannot update;
+ *   but ONLY when either side has a sequence-level `finish`: that's the one
+ *   place `seq.seed` reaches rendering on its own (`frameFinishSeed` uses the
+ *   instance's mount-time seed for a sequence-level finish's grain, which a
+ *   swap cannot update). Without a sequence-level `finish`, every consumer of
+ *   `seq.seed` is a `segmentRenderSeed`/`bedRenderSeed` fallback, and those
+ *   are already compared per segment and for the bed below — so when every
+ *   segment and the bed carry their own seed, `seq.seed` is dead weight and
+ *   changing it is free;
  * - the same finish presence (`sequenceWantsFinish`) — the presentation
  *   pass is allocated once at construction, so a swap that adds or removes
  *   every `finish` in the sequence cannot (de)allocate it;
@@ -2263,8 +2280,12 @@ declare const MURMUR_SPEC: SaverSpec;
  *   hex value glides over 2500 ms, and because the words differ and the
  *   transition declares `text: 'crossfade'`, the outgoing caption fades under
  *   the incoming one instead of switching whole-frame. Without the crossfade
- *   declaration a morph steps strings on its first frame — it reads as a cut
- *   and the validator says `morph-nothing-morphable`.
+ *   declaration the morph would still glide — colour alone gives it a
+ *   `hasGlide` — just with the caption stepping on the first frame instead of
+ *   fading; the validator only says `morph-nothing-morphable` for a pair
+ *   whose differences are all values morph cannot glide — strings
+ *   (`textBlock.text` above all), booleans, mismatched arrays — which this
+ *   one isn't.
  * - **fade.** Segments 2 → 3 have nothing structurally in common, so a morph
  *   is impossible and a `fade` is the honest transition: the outgoing scene
  *   keeps animating on its own canvas for 3000 ms while the incoming one
@@ -2313,4 +2334,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, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CapabilityTier, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, DITHER_ALPHA, DITHER_TILE, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, type Entity, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, type FieldBackground, type FieldDrift, type FinishPass, type FinishSpec, GRAIN_ALPHA, GRAIN_TILE, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, type LayerCohesion, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, MURMUR_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type PerceiveSequenceOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type ScreenOp, type SequenceExample, type SequenceFramePerception, type SequenceMountContext, type SequenceSaverInstance, type SequenceSaverPlugin, type SequenceSegment, type SequenceTransition, type SpecError, type SpecMountContext, type SpecWarning, type SpriteSpec, type SteerDelta, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, type TextBlockAnchor, type TextBlockLine, type TextMetricsClass, type TextRevealInput, type TextRevealSpec, type TextRole, type TextSpriteInfo, type ValidationResult, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, type WanderOsc, type WarningBox, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, canMorph, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, latticeHash, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rgb255Luma, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CapabilityTier, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, DITHER_ALPHA, DITHER_TILE, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, type Entity, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, type FieldBackground, type FieldDrift, type FinishPass, type FinishSpec, GRAIN_ALPHA, GRAIN_TILE, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, type LayerCohesion, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, MURMUR_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type PerceiveSequenceOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type ScreenOp, type SequenceExample, type SequenceFramePerception, type SequenceMountContext, type SequenceSaverInstance, type SequenceSaverPlugin, type SequenceSegment, type SequenceTransition, type SpecError, type SpecMountContext, type SpecWarning, type SpriteSpec, type SteerDelta, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, type TextBlockAnchor, type TextBlockLine, type TextMetricsClass, type TextRevealInput, type TextRevealSpec, type TextRole, type TextSpriteInfo, type ValidationResult, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, type WanderOsc, type WarningBox, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, canMorph, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, latticeHash, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rgb255Luma, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };

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 }");
@@ -2480,8 +2497,10 @@ function sequenceWantsFinish(seq) {
 }
 function sequenceSwapCompatible(prev, next) {
   if (prev.segments.length !== next.segments.length) return false;
-  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 (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;
@@ -4768,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;
@@ -4780,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);
@@ -4860,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 = normalizeSeed(opts.seed ?? spec.seed ?? 42);
+    const seed = scene.seed;
     const ft = fieldSampleTime(bg, t);
     for (let r = 0; r < rows; r++) {
       let rowSum = 0;
@@ -6268,7 +6287,10 @@ var SIGNAL_BOARD_SPEC = {
         kind: "bar",
         values: [62, 38, 84, 21, 55, 91, 44, 70, 29],
         max: 100,
-        length: 0.24,
+        // 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"
@@ -7976,6 +7998,7 @@ export {
   hasHotSwapSequence,
   headingAt,
   hexToRgb255,
+  ignoredPropertyPaths,
   latticeHash,
   layerCohesion,
   lerpSpec,