@idle-screens/schema 3.16.0 → 3.16.1

package/FORMAT.md

@@ -394,7 +394,8 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
     `"evenodd"` are SVG's own rules — use them for pasted SVG, for overlap
     patterns (a rosette of overlapping circles wants `evenodd`), and when a
     same-colour shape sits inside another on purpose (`auto` would cut it).
-  - **`gradient`** replaces the flat colour of the fill:
+  - **`gradient`** replaces the flat colour of the fill (the sprite still
+    needs a `color` or `colors`; a gradient does not stand in for it):
     `{ "type": "linear", "from": [0, -1], "to": [0, 1], "stops": [{ "at": 0, "color": "#2c6a3a" }, { "at": 1, "color": "#7ab070", "opacity": 0.6 }] }`
     or `{ "type": "radial", "center": [0, 0], "radius": 1, "focus": [-0.3, -0.4], "stops": [...] }`
     (2..8 stops, `at` 0..1 non-decreasing, optional per-stop `opacity`).
@@ -424,7 +425,9 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
     (1..256), drawn back to front, each with its own `path`, `color`
     (default: the entity's colour, so `colors` palettes still pick per
     entity), `fillRule`, `fill`, `gradient`, `stroke` and `opacity`. With
-    `parts`, put that paint on the parts, never on the sprite. One layer
+    `parts`, put that paint on the parts, never on the sprite. The sprite
+    still needs its own `color` (or a `colors` palette): parts without a
+    colour inherit it, and it is required even when every part sets one. One layer
     holds a whole illustration, and a counted layer reuses it: a balloon with
     gores, shading, ropes and basket × 7 drifting entities, all parts moving
     as one.
@@ -1143,7 +1146,13 @@ moves and scales its positions and sizes (sprite rotation is not modelled).
   `loop-seam` fires when a scene declares a looping timeline and the rest
   of the scene repeats too, but on a period the lap does not divide — so
   one lap can never come round to its own first frame (it names the period
-  to make the lap a multiple of). A scene whose other motion never repeats
+  to make the lap a multiple of). `spin`, `rock`, `pulse` and `grow` are left
+  out of that period: they run on scene time and change smoothly, so nothing
+  jumps at the wrap, and a lap off their period still loops seamlessly on
+  screen (only an exact one-lap export would differ). Keyed paths are
+  continuous at the wrap by construction — each lap enters from the last
+  key's value — unless a key cuts there on purpose (`t: 0, dur: 0`) or a
+  glide overruns the lap (`timeline-glide-overruns-lap` warns). A scene whose other motion never repeats
   (drifting stars, wandering motes) is not judged: that is ambient by
   design. `scenePeriod(spec)` is the analysis behind it — the least common
   multiple of every periodic part (pulse, grow, rock, spin, cycle, orbit,

package/dist/index.d.ts

@@ -2757,17 +2757,31 @@ interface ScenePeriod {
     period: number | null;
     /** One line per part that sets or breaks the period, e.g. `layers[2] pulse: 4000 ms`. */
     parts: string[];
+    /** What drives each of `parts`, index for index: `pulse`, `grow`, `rock`, `spin`, `path`, `orbit`, `emit`, `cycle`, `caret`, `background`, `timeline`. */
+    kinds: PeriodKind[];
     /** Why it is null (empty otherwise). */
     reasons: string[];
 }
-/** The repeat period of `spec` — see the module comment. */
-declare function scenePeriod(spec: SaverSpec): ScenePeriod;
+type PeriodKind = 'timeline' | 'background' | 'pulse' | 'grow' | 'rock' | 'emit' | 'spin' | 'cycle' | 'caret' | 'path' | 'orbit';
+/**
+ * Periodic parts that run on scene time and change smoothly, so a looping
+ * timeline's wrap never makes them jump: they carry on through it. A lap
+ * that does not divide their period still loops seamlessly on screen — only
+ * an exact export of one lap would differ (F145, X725, X823).
+ */
+declare const SEAMLESS_PERIOD_KINDS: ReadonlySet<PeriodKind>;
+/**
+ * The repeat period of `spec` — see the module comment. `skip` leaves out the
+ * periodic parts of those kinds, as if they were static (the loop-seam
+ * advisory passes `SEAMLESS_PERIOD_KINDS`).
+ */
+declare function scenePeriod(spec: SaverSpec, skip?: ReadonlySet<PeriodKind>): ScenePeriod;
 /**
  * The period of everything in the scene except its timeline — what a
  * looping timeline's lap has to be a multiple of for one lap to loop
  * seamlessly.
  */
-declare function periodWithoutTimeline(spec: SaverSpec): ScenePeriod;
+declare function periodWithoutTimeline(spec: SaverSpec, skip?: ReadonlySet<PeriodKind>): ScenePeriod;
 /**
  * How many-fold rotationally symmetric a sprite's drawing is about the point
  * `spin` turns it on: a spinning layer looks the same again after 360°/n,
@@ -3300,5 +3314,5 @@ declare function pathFrame(s: PolygonSprite, r: number, w: number, h: number): {
     uniform: boolean;
 };
 
-export { AQUARIUM_SPEC, AURORA_SPEC, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, DASHBOARD_SPEC, DEFAULT_KEY_DUR, DITHER_ALPHA, DITHER_TILE, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, GRAIN_ALPHA, GRAIN_TILE, HAIKU_SPEC, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, MATRIX_RAIN_SPEC, MAX_PATH_POINTS, MAX_SCENE_PERIOD, MOTION_FIELDS, MURMUR_SPEC, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, RAIN_SPEC, RELAY_BOARD_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, STEER_EASES, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, adviseSequence, adviseSpec, alphaAt, applyDeltasShared, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, buriedAreaOf, canMorph, canWrapMorph, canonicalSpecPath, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, drawSpan, easeGlide, easeSmooth, emitEnvelope, emitWindow, entityScales, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, flashSamplingForecast, flattenPath, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, isCombiningKana, isFullWidth, isPathPolygon, latticeHash, layerCellFootprints, layerCohesion, lerpPathD, lerpSpec, lerpValue, lifeAlphaAt, lifeStaggerAt, linkEdges, linkMaxDistPx, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, pathFrame, pathParts, perceiveScene, perceiveSequenceFrame, periodWithoutTimeline, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, sceneColour, scenePeriod, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spinSymmetry, spriteIndexAt, spriteVariants, steerablePaths, strokeDrawnSamples, strokeLines, structuralSignature, textBlockAnchorOffset, textBlockText, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineFlashReport, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, trimLines, trimPolyline, validateSequence, validateSpec, validateSpecPaths, wipeMask, withoutTimeline };
-export type { BackgroundDrift, BackgroundSpec, BandSpec, CapabilityTier, CohesionRead, CycleSpec, DominanceEntry, Entity, FieldBackground, FieldDrift, FinishPass, FinishSpec, FlashSamplingForecast, FlattenedPath, GlideEase, GradientStop, IdleSequence, LayerCohesion, LayerGroup, LayerMotionStats, LayerSnapshot, LayerSpec, LayerTransform, LinkEdge, LuminanceGrid, LuminanceGridOptions, MotionEase, MotionSpec, PathGradient, PathGradientStop, PathPart, PathStroke, PerceiveOptions, PerceiveSequenceOptions, Placed, ResolveOptions, ResolvedPart, ResolvedSegment, RevealState, SaverSpec, SceneColour, SceneDescription, SceneDiff, ScenePerception, ScenePeriod, SceneSnapshot, SchemaExample, ScreenOp, SequenceExample, SequenceFramePerception, SequenceMountContext, SequenceSaverInstance, SequenceSaverPlugin, SequenceSegment, SequenceTransition, SpecError, SpecMountContext, SpecWarning, SpriteSpec, SteerDelta, StrokeDraw, TextBlockAnchor, TextBlockLine, TextMetricsClass, TextNumber, TextRevealInput, TextRevealSpec, TextRole, TextSpriteInfo, Timeline, TimelineFlashReport, TimelineKey, ValidationResult, WanderOsc, WarningBox, WipeTransition };
+export { AQUARIUM_SPEC, AURORA_SPEC, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, DASHBOARD_SPEC, DEFAULT_KEY_DUR, DITHER_ALPHA, DITHER_TILE, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, GRAIN_ALPHA, GRAIN_TILE, HAIKU_SPEC, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, MATRIX_RAIN_SPEC, MAX_PATH_POINTS, MAX_SCENE_PERIOD, MOTION_FIELDS, MURMUR_SPEC, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, RAIN_SPEC, RELAY_BOARD_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SEAMLESS_PERIOD_KINDS, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, STEER_EASES, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, adviseSequence, adviseSpec, alphaAt, applyDeltasShared, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, buriedAreaOf, canMorph, canWrapMorph, canonicalSpecPath, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, drawSpan, easeGlide, easeSmooth, emitEnvelope, emitWindow, entityScales, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, flashSamplingForecast, flattenPath, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, isCombiningKana, isFullWidth, isPathPolygon, latticeHash, layerCellFootprints, layerCohesion, lerpPathD, lerpSpec, lerpValue, lifeAlphaAt, lifeStaggerAt, linkEdges, linkMaxDistPx, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, pathFrame, pathParts, perceiveScene, perceiveSequenceFrame, periodWithoutTimeline, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, sceneColour, scenePeriod, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spinSymmetry, spriteIndexAt, spriteVariants, steerablePaths, strokeDrawnSamples, strokeLines, structuralSignature, textBlockAnchorOffset, textBlockText, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineFlashReport, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, trimLines, trimPolyline, validateSequence, validateSpec, validateSpecPaths, wipeMask, withoutTimeline };
+export type { BackgroundDrift, BackgroundSpec, BandSpec, CapabilityTier, CohesionRead, CycleSpec, DominanceEntry, Entity, FieldBackground, FieldDrift, FinishPass, FinishSpec, FlashSamplingForecast, FlattenedPath, GlideEase, GradientStop, IdleSequence, LayerCohesion, LayerGroup, LayerMotionStats, LayerSnapshot, LayerSpec, LayerTransform, LinkEdge, LuminanceGrid, LuminanceGridOptions, MotionEase, MotionSpec, PathGradient, PathGradientStop, PathPart, PathStroke, PerceiveOptions, PerceiveSequenceOptions, PeriodKind, Placed, ResolveOptions, ResolvedPart, ResolvedSegment, RevealState, SaverSpec, SceneColour, SceneDescription, SceneDiff, ScenePerception, ScenePeriod, SceneSnapshot, SchemaExample, ScreenOp, SequenceExample, SequenceFramePerception, SequenceMountContext, SequenceSaverInstance, SequenceSaverPlugin, SequenceSegment, SequenceTransition, SpecError, SpecMountContext, SpecWarning, SpriteSpec, SteerDelta, StrokeDraw, TextBlockAnchor, TextBlockLine, TextMetricsClass, TextNumber, TextRevealInput, TextRevealSpec, TextRole, TextSpriteInfo, Timeline, TimelineFlashReport, TimelineKey, ValidationResult, WanderOsc, WarningBox, WipeTransition };

package/dist/index.js

@@ -1602,6 +1602,11 @@ function pathDrawCost(s) {
   return c;
 }
 
+// src/validate-hints.ts
+var SCALAR_ONLY = /not a \[min,max\] range/;
+var SCALAR_BOUND = /^must be (?:>|an? (?:positive |single |finite |whole )?(?:number|integer)\b|between -?\d|-?\d+(?:\.\d+)?\.\.-?\d+(?:\.\d+)?(?: \(|$))/;
+var scalarWanted = (m) => SCALAR_ONLY.test(m) || !m.includes("[") && SCALAR_BOUND.test(m);
+
 // src/validate.ts
 var HEX2 = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -1734,6 +1739,15 @@ var KNOWN_BG_SOLID = /* @__PURE__ */ new Set(["type", "color"]);
 var KNOWN_BG_GRADIENT = /* @__PURE__ */ new Set(["type", "stops", "band", "drift"]);
 var KNOWN_BG_FIELD = /* @__PURE__ */ new Set(["type", "scale", "octaves", "warp", "quantize", "bands", "drift", "seed"]);
 var KNOWN_FIELD_DRIFT = /* @__PURE__ */ new Set(["period", "amount"]);
+var KNOWN_BG_STOP = /* @__PURE__ */ new Set(["at", "color"]);
+var KNOWN_BAND = /* @__PURE__ */ new Set(["color", "height"]);
+var KNOWN_BG_DRIFT = /* @__PURE__ */ new Set(["period", "amount"]);
+var KNOWN_PATH_STROKE = /* @__PURE__ */ new Set(["color", "width", "opacity", "join", "cap", "draw"]);
+var KNOWN_PATH_GRADIENT = {
+  linear: /* @__PURE__ */ new Set(["type", "from", "to", "stops", "units"]),
+  radial: /* @__PURE__ */ new Set(["type", "center", "radius", "focus", "stops", "units"])
+};
+var KNOWN_PATH_STOP = /* @__PURE__ */ new Set(["at", "color", "opacity"]);
 var LAYER_PROPS_ON_SPRITE = /* @__PURE__ */ new Set(["blend", "trail", "alpha", "pulse", "spin", "grow", "region", "links", "flip", "wrap", "key", "emit", "clock", "life", "layout", "rotate", "rock"]);
 function unknownKeys(obj, known) {
   return Object.keys(obj).filter((k) => !known.has(k));
@@ -1751,6 +1765,50 @@ 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 valueAtPath(root, path) {
+  let v = root;
+  for (const seg of path.match(/[^.[\]]+/g) ?? []) {
+    if (Array.isArray(v) && /^\d+$/.test(seg)) v = v[Number(seg)];
+    else if (isObj(v)) v = v[seg];
+    else return void 0;
+  }
+  return v;
+}
+function echo(v) {
+  if (isNum(v)) return String(v);
+  if (Array.isArray(v) && v.length <= 4 && v.every(isNum)) return `[${v.join(", ")}]`;
+  const s = JSON.stringify(v) ?? String(v);
+  return s.length > 48 ? `${s.slice(0, 45)}\u2026` : s;
+}
+var RANGE_WANTED = /^must be a \[min,max\] range/;
+function shapeHint(spec, path, message) {
+  if (message.includes(" \u2014 got ")) return "";
+  const v = valueAtPath(spec, path);
+  if (v === void 0) return "";
+  if (RANGE_WANTED.test(message)) {
+    if (isNum(v)) {
+      const fits = message.includes("within 0..1") ? v >= 0 && v <= 1 : message.includes(">= 0") ? v >= 0 : !message.includes("positive") || v > 0;
+      return fits ? ` \u2014 got ${v}; write [${v}, ${v}]` : ` \u2014 got ${v}; a range is two numbers, [min, max]`;
+    }
+    if (isObj(v) && ("min" in v || "max" in v)) {
+      return ` \u2014 got {min, max}; write [${isNum(v.min) ? v.min : "min"}, ${isNum(v.max) ? v.max : "max"}]`;
+    }
+    if (Array.isArray(v) && v.length === 2 && isNum(v[0]) && isNum(v[1]) && v[0] > v[1]) {
+      return ` \u2014 got ${echo(v)}; the smaller number comes first: write [${v[1]}, ${v[0]}]`;
+    }
+    return ` \u2014 got ${echo(v)}`;
+  }
+  if (Array.isArray(v) && scalarWanted(message)) {
+    const segs = path.match(/[^.[\]]+/g) ?? [];
+    const key = segs[segs.length - 1] ?? path;
+    const parentKey = segs[segs.length - 2];
+    const parent = valueAtPath(spec, path.slice(0, path.lastIndexOf(".")));
+    const kind = isObj(parent) && isStr(parent.kind) ? parent.kind : void 0;
+    const noun = kind ? `${/^[aeiou]/i.test(kind) ? "an" : "a"} ${kind}'s \`${key}\`` : parentKey && !/^\d+$/.test(parentKey) && parentKey !== "sprite" ? `\`${parentKey}.${key}\`` : `\`${key}\``;
+    return ` \u2014 got ${echo(v)}; ${noun} is one number`;
+  }
+  return "";
+}
 function normalizeColors(spec) {
   if (!isObj(spec) || !Array.isArray(spec.layers)) return;
   for (const layer of spec.layers) {
@@ -1819,7 +1877,7 @@ function specPathsValid(spec, paths) {
 function validateSpecCore(spec, checkApplied = true) {
   const errors = [];
   const warnings = [];
-  const err = (path, message) => void errors.push({ path, message });
+  const err = (path, message) => void errors.push({ path, message: message + shapeHint(spec, path, message) });
   const warn = (path, code, message) => void warnings.push({ path, code, message });
   if (!isObj(spec)) return { valid: false, errors: [{ path: "", message: "spec must be an object" }], warnings: [] };
   if (spec.schemaVersion !== SCHEMA_VERSION) err("schemaVersion", `must be ${SCHEMA_VERSION}`);
@@ -2048,9 +2106,12 @@ function validateTimelineKeys(spec, errOuter, warn, checkApplied) {
     return;
   }
 }
-function color(v, path, err) {
-  if (!isStr(v) || !HEX2.test(v)) err(path, "must be a hex colour like #0a3a52");
+function color(v, path, err, missing = "is required (a hex colour like #0a3a52)") {
+  if (v === void 0) err(path, missing);
+  else if (!isStr(v) || !HEX2.test(v)) err(path, "must be a hex colour like #0a3a52");
 }
+var SPRITE_COLOR_MISSING = "`color` is required (or a `colors` palette)";
+var POLYGON_COLOR_MISSING = `${SPRITE_COLOR_MISSING}; parts without their own colour inherit it, and a gradient or stroke does not stand in for it`;
 function validateFinish(f, path, err, warn) {
   if (!isObj(f)) return err(path, "must be an object");
   for (const k of ["grain", "dither"]) {
@@ -2075,6 +2136,7 @@ function validateBackground(bg, err, warn) {
       bg.stops.forEach((s, i) => {
         if (!isObj(s) || !isNum(s.at) || s.at < 0 || s.at > 1) err(`background.stops[${i}].at`, "must be 0..1");
         color(isObj(s) ? s.color : void 0, `background.stops[${i}].color`, err);
+        if (isObj(s)) for (const k of unknownKeys(s, KNOWN_BG_STOP)) warn(`background.stops[${i}].${k}`, "unknown-property", `unknown stop property '${k}' \u2014 will be ignored`);
       });
     }
     if (bg.drift !== void 0) {
@@ -2086,6 +2148,7 @@ function validateBackground(bg, err, warn) {
         if (bg.drift.amount !== void 0 && (!isNum(bg.drift.amount) || bg.drift.amount <= 0 || bg.drift.amount > LIMITS.maxDriftAmount)) {
           err("background.drift.amount", `must be > 0 and <= ${LIMITS.maxDriftAmount}`);
         }
+        for (const k of unknownKeys(bg.drift, KNOWN_BG_DRIFT)) warn(`background.drift.${k}`, "unknown-property", `unknown drift property '${k}' \u2014 will be ignored`);
       }
     }
     if (bg.band !== void 0) {
@@ -2093,6 +2156,7 @@ function validateBackground(bg, err, warn) {
       else {
         color(bg.band.color, "background.band.color", err);
         positiveScalar(bg.band.height, "background.band.height", err);
+        for (const k of unknownKeys(bg.band, KNOWN_BAND)) warn(`background.band.${k}`, "unknown-property", `unknown band property '${k}' \u2014 will be ignored`);
       }
     }
     for (const k of unknownKeys(bg, KNOWN_BG_GRADIENT)) {
@@ -2500,19 +2564,19 @@ function validateSprite(sprite, path, err, warn, spec) {
   } else if (sprite.kind === "circle") {
     knownSet = KNOWN_CIRCLE;
     if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, rangeMsg(spec));
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, SPRITE_COLOR_MISSING);
     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`, rangeMsg(spec));
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, SPRITE_COLOR_MISSING);
     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`, rangeMsg(spec));
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, SPRITE_COLOR_MISSING);
     if (sprite.width !== void 0) positiveScalar(sprite.width, `${path}.width`, err);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "rect") {
@@ -2524,7 +2588,7 @@ function validateSprite(sprite, path, err, warn, spec) {
     if (sprite.feather !== void 0 && (!isNum(sprite.feather) || sprite.feather < 0 || sprite.feather > 1)) {
       err(`${path}.feather`, "must be 0..1 (fraction of the half-size that fades out)");
     }
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, SPRITE_COLOR_MISSING);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "bar") {
     knownSet = KNOWN_BAR;
@@ -2537,7 +2601,7 @@ function validateSprite(sprite, path, err, warn, spec) {
     if (sprite.direction !== void 0 && !["right", "left", "up", "down"].includes(sprite.direction)) {
       err(`${path}.direction`, "must be 'right' | 'left' | 'up' | 'down'");
     }
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, SPRITE_COLOR_MISSING);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "polygon") {
     knownSet = KNOWN_POLYGON;
@@ -2581,7 +2645,7 @@ function validateSprite(sprite, path, err, warn, spec) {
       if (sprite.origin !== void 0 && !(Array.isArray(sprite.origin) && sprite.origin.length === 2 && sprite.origin.every((v) => isNum(v) && Math.abs(v) <= 1))) err(`${path}.origin`, "must be [x, y] in the unit box (-1..1): the point placed at the position");
     }
     if (sprite.soft !== void 0 && typeof sprite.soft !== "boolean") err(`${path}.soft`, "must be a boolean");
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, POLYGON_COLOR_MISSING);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "stroke") {
     knownSet = KNOWN_STROKE;
@@ -2592,7 +2656,7 @@ function validateSprite(sprite, path, err, warn, spec) {
     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");
     if (sprite.draw !== void 0) validateDraw(sprite.draw, `${path}.draw`, err, warn);
-    color(sprite.color, `${path}.color`, err);
+    color(sprite.color, `${path}.color`, err, SPRITE_COLOR_MISSING);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "textBlock") {
     knownSet = KNOWN_TEXT_BLOCK;
@@ -2903,10 +2967,10 @@ function validatePathPiece(piece, path, err, warn) {
 function validatePiecePaint(piece, path, err, warn) {
   if (piece.fill !== void 0 && typeof piece.fill !== "boolean") err(`${path}.fill`, "must be a boolean");
   if (piece.fill === false && piece.stroke === void 0) err(`${path}.fill`, "fill: false draws nothing without a stroke");
-  if (piece.gradient !== void 0) validatePathGradient(piece.gradient, `${path}.gradient`, err);
+  if (piece.gradient !== void 0) validatePathGradient(piece.gradient, `${path}.gradient`, err, warn);
   if (piece.stroke !== void 0) validatePathStroke(piece.stroke, `${path}.stroke`, err, warn);
 }
-function validatePathGradient(g, path, err) {
+function validatePathGradient(g, path, err, warn) {
   if (!isObj(g)) return err(path, "must be { type: 'linear', from, to, stops } or { type: 'radial', center, radius, stops }");
   if (g.type === "linear") {
     if (!isPair(g.from)) err(`${path}.from`, "must be [x, y] in unit-box coordinates (-2..2)");
@@ -2918,6 +2982,7 @@ function validatePathGradient(g, path, err) {
   } else {
     return err(`${path}.type`, "must be 'linear' | 'radial'");
   }
+  for (const k of unknownKeys(g, KNOWN_PATH_GRADIENT[g.type])) warn(`${path}.${k}`, "unknown-property", `unknown ${g.type} gradient property '${k}' \u2014 will be ignored`);
   if (g.units !== void 0 && g.units !== "box" && g.units !== "part") err(`${path}.units`, "must be 'box' (the drawing's unit box, default) | 'part' (the part's own box, -1..1)");
   if (!Array.isArray(g.stops) || g.stops.length < 2 || g.stops.length > 8) return err(`${path}.stops`, "must be 2..8 stops");
   let last = -Infinity;
@@ -2927,16 +2992,18 @@ function validatePathGradient(g, path, err) {
     else last = st.at;
     color(st.color, `${path}.stops[${i}].color`, err);
     if (st.opacity !== void 0 && (!isNum(st.opacity) || st.opacity < 0 || st.opacity > 1)) err(`${path}.stops[${i}].opacity`, "must be 0..1");
+    for (const k of unknownKeys(st, KNOWN_PATH_STOP)) warn(`${path}.stops[${i}].${k}`, "unknown-property", `unknown stop property '${k}' \u2014 will be ignored`);
   });
 }
 function validatePathStroke(st, path, err, warn) {
   if (!isObj(st)) return err(path, "must be { color, width, opacity?, join?, cap?, draw? }");
-  color(st.color, `${path}.color`, err);
+  color(st.color, `${path}.color`, err, "`color` is required on a stroke (a hex colour like #0a3a52); a stroke does not inherit the entity colour");
   if (!isNum(st.width) || st.width <= 0 || st.width > 0.5) err(`${path}.width`, "must be > 0 and <= 0.5 (unit-box units: 0.01 is 1% of the drawing's half-size)");
   if (st.opacity !== void 0 && (!isNum(st.opacity) || st.opacity < 0 || st.opacity > 1)) err(`${path}.opacity`, "must be 0..1");
   if (st.join !== void 0 && !["round", "miter", "bevel"].includes(st.join)) err(`${path}.join`, "must be 'round' | 'miter' | 'bevel'");
   if (st.cap !== void 0 && !["round", "butt", "square"].includes(st.cap)) err(`${path}.cap`, "must be 'round' | 'butt' | 'square'");
   if (st.draw !== void 0) validateDraw(st.draw, `${path}.draw`, err, warn);
+  for (const k of unknownKeys(st, KNOWN_PATH_STROKE)) warn(`${path}.${k}`, "unknown-property", `unknown stroke property '${k}' \u2014 will be ignored`);
 }
 function validateWipe(tr, path, err, warn) {
   if (tr.shape !== void 0 && tr.shape !== "circle" && tr.shape !== "line") err(`${path}.shape`, "must be 'circle' | 'line'");
@@ -3566,6 +3633,7 @@ function lifeStaggerAt(life, t, i) {
 }
 function wrap(v, min, max) {
   const range2 = max - min;
+  if (range2 <= 0) return min;
   return ((v - min) % range2 + range2) % range2 + min;
 }
 function reflect(v, min, max) {
@@ -5430,14 +5498,14 @@ var SpecInstance = class {
    * entity as it was at `t` (rotation, heading, values), but at the echo's
    * position, size and alpha.
    */
-  drawEntity(built, e, t, lifeA, parentE, paint, echo) {
+  drawEntity(built, e, t, lifeA, parentE, paint, echo2) {
     const { ctx } = this;
-    const p = echo ? { x: echo.x, y: echo.y, flip: false } : this.entityPos(e, t, parentE);
+    const p = echo2 ? { x: echo2.x, y: echo2.y, flip: false } : this.entityPos(e, t, parentE);
     const sprite = paint?.sprite ?? built.layer.sprite;
-    const sz = echo ? echo.size : sizeAt(e, t);
+    const sz = echo2 ? echo2.size : sizeAt(e, t);
     const rot = rotationAt(e, t);
     const unitScale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
-    ctx.globalAlpha = echo ? echo.alpha : alphaAt(e, t) * lifeA * (paint?.alpha ?? 1);
+    ctx.globalAlpha = echo2 ? echo2.alpha : alphaAt(e, t) * lifeA * (paint?.alpha ?? 1);
     if (sprite.kind === "ring") {
       const r = sz / 2;
       const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
@@ -8841,6 +8909,7 @@ function flashSamplingForecast(spec) {
 
 // src/period.ts
 var MAX_SCENE_PERIOD = 36e5;
+var SEAMLESS_PERIOD_KINDS = /* @__PURE__ */ new Set(["spin", "rock", "pulse", "grow"]);
 var PERIOD_LEAF = /(^|\.)(period|rate|every|duration|spin|speed|blink|drift)$/;
 var gcd = (a, b) => {
   while (b) [a, b] = [b, a % b];
@@ -8858,27 +8927,27 @@ function toRatio(ms) {
   return null;
 }
 var range = (r) => r === void 0 ? null : typeof r === "number" ? r : r[0] === r[1] ? r[0] : NaN;
-function scenePeriod(spec) {
+function scenePeriod(spec, skip) {
   const parts = [];
   const reasons = [];
-  const add = (label, ms) => {
-    if (!(ms > 0) || !Number.isFinite(ms)) return;
+  const add = (label, ms, kind) => {
+    if (!(ms > 0) || !Number.isFinite(ms) || skip?.has(kind)) return;
     const ratio = toRatio(ms);
     if (!ratio) reasons.push(`${label} repeats every ${Number(ms.toFixed(3))} ms, which has no exact ratio to combine`);
-    else parts.push([label, ratio[0], ratio[1]]);
+    else parts.push([label, ratio[0], ratio[1], kind]);
   };
   const tl = spec.timeline;
   if (tl && tl.keys.length > 0) {
     const keyed = tl.keys.filter((k) => PERIOD_LEAF.test(String(k.path)));
     if (keyed.length > 0) reasons.push(`timeline keys animate ${[...new Set(keyed.map((k) => String(k.path)))].join(", ")}, which sets the scene's own period`);
-    if (tl.loop && (tl.duration ?? 0) > 0) add("timeline", tl.duration);
+    if (tl.loop && (tl.duration ?? 0) > 0) add("timeline", tl.duration, "timeline");
     else reasons.push("timeline does not loop (it plays once, then holds)");
   }
   const bg = spec.background;
   if (bg && bg.type !== "solid" && bg.drift && !(bg.type === "field" && bg.drift.amount === 0)) {
     const { period } = bg.drift;
     const r = bg.type === "field" ? toRatio(period) : null;
-    add("background drift", r ? r[0] / gcd(r[0], FIELD_BUCKET_MS) * FIELD_BUCKET_MS : period);
+    add("background drift", r ? r[0] / gcd(r[0], FIELD_BUCKET_MS) * FIELD_BUCKET_MS : period, "background");
   }
   if (spec.finish?.animate && ((spec.finish.grain ?? 0) > 0 || (spec.finish.dither ?? 0) > 0)) reasons.push("finish.animate steps the grain without repeating");
   spec.layers.forEach((layer, i) => {
@@ -8887,53 +8956,58 @@ function scenePeriod(spec) {
     const life = layer.life;
     const staggered = (life?.stagger ?? 0) > 0;
     if (life && (life.exit !== void 0 || life.enter !== void 0 && ((life.enter ?? 0) > 0 || (life.fade ?? 1e3) > 0 || staggered))) reasons.push(`${at} life builds in or out once`);
-    if (layer.pulse && layer.pulse.amp !== 0) add(`${at} pulse`, layer.pulse.period / rate);
-    if (layer.grow) add(`${at} grow`, layer.grow.period / rate);
-    if (layer.rock) add(`${at} rock`, layer.rock.period / rate);
-    if (layer.emit) add(`${at} emit`, layer.emit.every);
+    if (layer.pulse && layer.pulse.amp !== 0) add(`${at} pulse`, layer.pulse.period / rate, "pulse");
+    if (layer.grow) add(`${at} grow`, layer.grow.period / rate, "grow");
+    if (layer.rock) add(`${at} rock`, layer.rock.period / rate, "rock");
+    if (layer.emit) add(`${at} emit`, layer.emit.every, "emit");
     const spin = range(layer.spin);
     const fold = spin !== null && spin !== 0 ? spinSymmetry(layer.sprite) : 1;
     if (spin !== null && fold !== Infinity) {
       if (Number.isNaN(spin)) reasons.push(`${at} spin range gives each entity its own speed`);
-      else if (spin !== 0) add(`${at} spin${fold > 1 ? ` (${fold}-fold)` : ""}`, 36e4 / Math.abs(spin) / fold);
+      else if (spin !== 0) add(`${at} spin${fold > 1 ? ` (${fold}-fold)` : ""}`, 36e4 / Math.abs(spin) / fold, "spin");
     }
     const sp = layer.sprite;
-    if ((sp.kind === "emoji" || sp.kind === "text") && sp.cycle && spriteVariants(sp) > 1) add(`${at} cycle`, sp.cycle.period * spriteVariants(sp) / rate);
+    if ((sp.kind === "emoji" || sp.kind === "text") && sp.cycle && spriteVariants(sp) > 1) add(`${at} cycle`, sp.cycle.period * spriteVariants(sp) / rate, "cycle");
     if (sp.kind === "textBlock" && sp.reveal) {
       if ((sp.reveal.speed ?? 0) > 0) reasons.push(`${at} reveal types itself once`);
       if (sp.reveal.caret) {
         const hz = Math.min(3, sp.reveal.caret === true ? 1.2 : sp.reveal.caret.blink ?? 1.2);
-        if (hz > 0) add(`${at} caret`, 1e3 / hz);
+        if (hz > 0) add(`${at} caret`, 1e3 / hz, "caret");
       }
     }
     const m = layer.motion;
-    if (m.type === "path") add(`${at} path`, m.duration);
+    if (m.type === "path") add(`${at} path`, m.duration, "path");
     else if (m.type === "orbit") {
       const s = range(m.speed);
       if (s === null || Number.isNaN(s)) reasons.push(`${at} orbit speed range gives each entity its own lap`);
-      else if (s !== 0) add(`${at} orbit`, 36e4 / Math.abs(s));
+      else if (s !== 0) add(`${at} orbit`, 36e4 / Math.abs(s), "orbit");
     } else if (m.type !== "static") {
       if (m.type === "drift" && m.ease?.type === "settle" && !layer.emit) reasons.push(`${at} drift settles once`);
       else reasons.push(`${at} ${m.type} motion travels at seeded per-entity speeds`);
     }
   });
   const labelled = parts.map(([l, n, d]) => `${l}: ${Number((n / d).toFixed(3))} ms`);
-  if (reasons.length > 0) return { period: null, parts: labelled, reasons };
-  if (parts.length === 0) return { period: 0, parts: labelled, reasons };
+  const kinds = parts.map(([, , , k]) => k);
+  if (reasons.length > 0) return { period: null, parts: labelled, kinds, reasons };
+  const combined = combinePeriods(parts);
+  return { ...combined, parts: labelled, kinds };
+}
+function combinePeriods(parts) {
+  if (parts.length === 0) return { period: 0, reasons: [] };
   let num = 1;
   let den = 0;
   for (const [, n, d] of parts) {
     num = num / gcd(num, n) * n;
     den = gcd(den, d);
     if (num / den > MAX_SCENE_PERIOD) {
-      return { period: null, parts: labelled, reasons: [`its parts share no cycle shorter than ${MAX_SCENE_PERIOD / 6e4} min`] };
+      return { period: null, reasons: [`its parts share no cycle shorter than ${MAX_SCENE_PERIOD / 6e4} min`] };
     }
   }
-  if (num % den !== 0) return { period: null, parts: labelled, reasons: [`its parts repeat together every ${Number((num / den).toFixed(3))} ms, not a whole number of milliseconds`] };
-  return { period: num / den, parts: labelled, reasons };
+  if (num % den !== 0) return { period: null, reasons: [`its parts repeat together every ${Number((num / den).toFixed(3))} ms, not a whole number of milliseconds`] };
+  return { period: num / den, reasons: [] };
 }
-function periodWithoutTimeline(spec) {
-  return scenePeriod(withoutTimeline(spec));
+function periodWithoutTimeline(spec, skip) {
+  return scenePeriod(withoutTimeline(spec), skip);
 }
 var MAX_SYMMETRY = 64;
 var MAX_SYMMETRY_POINTS = 8192;
@@ -9270,14 +9344,15 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   if (authored.timeline?.loop && (authored.timeline.duration ?? 0) > 0) {
     const lap = Math.round(authored.timeline.duration);
     const rest = periodWithoutTimeline(authored);
-    if (rest.period !== null && rest.period > 0 && lap % rest.period !== 0) {
+    const seam = rest.period !== null && rest.period > 0 && lap % rest.period !== 0 ? periodWithoutTimeline(authored, SEAMLESS_PERIOD_KINDS) : null;
+    if (seam && seam.period !== null && seam.period > 0 && lap % seam.period !== 0) {
       let a = lap;
-      let b = rest.period;
+      let b = seam.period;
       while (b) [a, b] = [b, a % b];
       warnings.push({
         path: "timeline.duration",
         code: "loop-seam",
-        message: `the timeline loops every ${lap} ms but the rest of the scene repeats every ${rest.period} ms (${rest.parts.join(", ")}), so the whole scene only repeats every ${lap / a * rest.period} ms \u2014 make the lap a multiple of ${rest.period} ms for one lap to loop`
+        message: `the timeline loops every ${lap} ms but ${seam.parts.join(", ")} repeat${seam.parts.length === 1 ? "s" : ""} every ${seam.period} ms, so the scene only comes round to its first frame every ${lap / a * seam.period} ms \u2014 make the lap a multiple of ${seam.period} ms for one lap to loop`
       });
     }
   }
@@ -12385,6 +12460,7 @@ export {
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
+  SEAMLESS_PERIOD_KINDS,
   SHARD_FALL_SPEC,
   SIGNAL_BOARD_SPEC,
   SNOWFALL_SPEC,