@idle-screens/schema 3.16.0 → 3.17.0

package/dist/index.js

@@ -500,46 +500,105 @@ function easeGlide(ease2, k) {
 }
 var STEER_EASES = /* @__PURE__ */ new Set(["in", "out", "spring"]);
 function structuralSignature(spec) {
-  return JSON.stringify([
-    spec.units,
-    // Normalized against the same default every renderer uses — an omitted
-    // referenceViewport and an explicit 1080 render identically, so they must
-    // hash identically or a same-sizing morph gets rejected as structural.
-    spec.referenceViewport ?? LIMITS.referenceViewport,
-    spec.layers.map((l) => {
+  const f = structuralFields(spec);
+  return JSON.stringify([...f.root.map(([, v]) => v), f.layers.map((l) => l.map(([, v]) => v))]);
+}
+function structuralFields(spec) {
+  return {
+    root: [
+      ["units", spec.units],
+      // Normalized against the same default every renderer uses — an omitted
+      // referenceViewport and an explicit 1080 render identically, so they must
+      // hash identically or a same-sizing morph gets rejected as structural.
+      ["referenceViewport", spec.referenceViewport ?? LIMITS.referenceViewport]
+    ],
+    layers: 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.emit,
-        l.clock,
-        l.sprite.kind,
+        ["count", l.count],
+        ["size", l.size],
+        ["region", l.region],
+        ["position", l.position],
+        ["motion", l.motion],
+        ["wrap", l.wrap],
+        ["flip", l.flip],
+        ["alpha", l.alpha],
+        ["pulse", l.pulse],
+        ["spin", l.spin],
+        ["grow", l.grow],
+        ["layout", l.layout],
+        ["emit", l.emit],
+        ["clock", l.clock],
+        ["sprite.kind", 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] : l.sprite.kind === "bar" ? [s.length, s.thickness] : 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.anchor ? [l.sprite.fontSize, l.sprite.anchor] : [l.sprite.fontSize] : void 0,
+        ["sprite.radius", s.radius],
+        ["sprite.length", s.length],
+        l.sprite.kind === "rect" ? [["sprite.width", "sprite.aspect"], [s.width, s.aspect]] : l.sprite.kind === "bar" ? [["sprite.length", "sprite.thickness"], [s.length, s.thickness]] : ["sprite.dimensions", void 0],
+        ["sprite.colors.length", Array.isArray(s.colors) ? s.colors.length : void 0],
+        ["sprite.colorWeights", s.colorWeights],
+        l.sprite.kind === "emoji" ? [["sprite.glyphs.length", "sprite.cycle.period"], [l.sprite.glyphs.length, l.sprite.cycle?.period]] : l.sprite.kind === "text" ? [["sprite.strings.length", "sprite.cycle.period"], [l.sprite.strings.length, l.sprite.cycle?.period]] : l.sprite.kind === "textBlock" ? [["sprite.fontSize", "sprite.anchor"], l.sprite.anchor ? [l.sprite.fontSize, l.sprite.anchor] : [l.sprite.fontSize]] : ["sprite.variants", void 0],
         // Static rotation is baked into entities (a range draws a seeded
         // angle). Appended only when set — same rule as `anchor` above.
-        ...l.rotate !== void 0 ? [l.rotate] : [],
+        ...l.rotate !== void 0 ? [["rotate", l.rotate]] : [],
         // `rock` is baked per entity like `pulse` (and draws a seeded phase).
-        ...l.rock !== void 0 ? [{ rock: l.rock }] : []
+        ...l.rock !== void 0 ? [["rock", { rock: l.rock }]] : []
       ];
     })
-  ]);
+  };
+}
+function showValue(v) {
+  if (v === void 0) return "(unset)";
+  if (typeof v === "string") return v;
+  const j = JSON.stringify(v);
+  return j.length > 40 ? `${j.slice(0, 37)}\u2026` : j;
+}
+function leafDifferences(path, a, b, out) {
+  if (JSON.stringify(a) === JSON.stringify(b)) return;
+  const isRec = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+  if (isRec(a) && isRec(b)) {
+    const before = out.length;
+    for (const k of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])) leafDifferences(`${path}.${k}`, a[k], b[k], out);
+    if (out.length === before) out.push(`${path}: the same fields in a different key order`);
+    return;
+  }
+  out.push(`${path}: ${showValue(a)} \u2192 ${showValue(b)}`);
+}
+function namedFields(fields) {
+  const m = /* @__PURE__ */ new Map();
+  for (const [name, value] of fields) {
+    if (typeof name === "string") {
+      m.set(name, value);
+      continue;
+    }
+    const vs = Array.isArray(value) ? value : [];
+    name.forEach((n, i) => m.set(n, vs[i]));
+  }
+  return m;
+}
+function structuralDifferences(a, b) {
+  const fa = structuralFields(a);
+  const fb = structuralFields(b);
+  const out = [];
+  const ra = namedFields(fa.root);
+  const rb = namedFields(fb.root);
+  for (const k of /* @__PURE__ */ new Set([...ra.keys(), ...rb.keys()])) leafDifferences(k, ra.get(k), rb.get(k), out);
+  if (fa.layers.length !== fb.layers.length) out.push(`layers.length: ${fa.layers.length} \u2192 ${fb.layers.length}`);
+  for (let i = 0; i < Math.min(fa.layers.length, fb.layers.length); i++) {
+    const la = namedFields(fa.layers[i]);
+    const lb = namedFields(fb.layers[i]);
+    const kindChanged = la.get("sprite.kind") !== lb.get("sprite.kind");
+    for (const k of /* @__PURE__ */ new Set([...la.keys(), ...lb.keys()])) {
+      if (kindChanged && k.startsWith("sprite.") && k !== "sprite.kind") continue;
+      leafDifferences(`layers[${i}].${k}`, la.get(k), lb.get(k), out);
+    }
+  }
+  return out;
+}
+function describeStructuralDifferences(a, b, max = 3) {
+  const d = structuralDifferences(a, b);
+  if (d.length === 0) return "";
+  return d.length <= max ? d.join("; ") : `${d.slice(0, max).join("; ")}; +${d.length - max} more`;
 }
 
 // src/sequence.ts
@@ -1602,6 +1661,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 +1798,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 +1824,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) {
@@ -1763,9 +1880,37 @@ function normalizeColors(spec) {
     }
   }
 }
+var LAYER_SIZED_SPRITES = /* @__PURE__ */ new Set(["emoji", "text"]);
+var SPRITE_SIZE_FIELD = {
+  circle: "radius",
+  ring: "radius",
+  polygon: "radius",
+  streak: "length",
+  stroke: "length",
+  rect: "width",
+  bar: "length and thickness",
+  textBlock: "fontSize"
+};
+var SPRITE_SIZE_MISPLACED = "'size' belongs on the layer, not inside sprite \u2014 move it up one level";
+function aliasSpriteSize(spec) {
+  const out = [];
+  if (!isObj(spec) || !Array.isArray(spec.layers)) return out;
+  spec.layers.forEach((layer, i) => {
+    if (!isObj(layer) || !isObj(layer.sprite)) return;
+    const sp = layer.sprite;
+    if (sp.size === void 0 || !LAYER_SIZED_SPRITES.has(sp.kind) || layer.size !== void 0) return;
+    layer.size = sp.size;
+    delete sp.size;
+    out.push({ path: `layers[${i}].sprite.size`, code: "misplaced-property", message: `${SPRITE_SIZE_MISPLACED} (applied as layers[${i}].size this time)` });
+  });
+  return out;
+}
 function validateSpec(spec) {
   normalizeColors(spec);
-  return validateSpecCore(spec);
+  const repaired = aliasSpriteSize(spec);
+  const result = validateSpecCore(spec);
+  if (repaired.length > 0) result.warnings = [...repaired, ...result.warnings ?? []];
+  return result;
 }
 function ignoredPropertyPaths(spec) {
   if (!isObj(spec)) return [];
@@ -1819,7 +1964,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 +2193,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 +2223,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 +2235,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 +2243,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)) {
@@ -2160,6 +2311,15 @@ function validateLayer(layer, path, err, warn, spec) {
   if (layer.size !== void 0 && (!isRange(layer.size) || layer.size[0] <= 0)) {
     err(`${path}.size`, rangeMsg(spec));
   }
+  if (isObj(layer.sprite) && layer.sprite.size !== void 0) {
+    const kind = layer.sprite.kind;
+    if (LAYER_SIZED_SPRITES.has(kind)) {
+      warn(`${path}.sprite.size`, "misplaced-property", layer.size !== void 0 ? `${SPRITE_SIZE_MISPLACED} \u2014 layer.size is also set, so the layer's value wins and sprite.size is ignored` : SPRITE_SIZE_MISPLACED);
+    } else {
+      const field = SPRITE_SIZE_FIELD[kind];
+      warn(`${path}.sprite.size`, "unknown-property", field ? `unknown sprite property 'size' \u2014 will be ignored; a ${kind} sprite is sized by its ${field}` : `unknown sprite property 'size' \u2014 will be ignored`);
+    }
+  }
   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");
   if (layer.alpha !== void 0 && (!isRange(layer.alpha) || layer.alpha[0] < 0 || layer.alpha[1] > 1)) {
@@ -2331,7 +2491,8 @@ function validateLayer(layer, path, err, warn, spec) {
       const sp = layer.sprite;
       if (isObj(sp) && isNum(layer.count)) {
         const variants = sp.kind === "text" && Array.isArray(sp.strings) ? sp.strings.length : sp.kind === "emoji" && Array.isArray(sp.glyphs) ? sp.glyphs.length : sp.kind === "bar" && Array.isArray(sp.values) ? sp.values.length : null;
-        if (variants !== null && variants !== layer.count) {
+        const atmosphere = sp.kind === "text" && sp.role === "atmosphere";
+        if (variants !== null && variants !== layer.count && !atmosphere) {
           warn(`${path}.count`, "list-length-mismatch", `count is ${layer.count} but the sprite carries ${variants} ${sp.kind === "bar" ? "values" : "variants"} \u2014 a ${lay.type} layout reads them in order, so they cycle or go unused`);
         }
       }
@@ -2500,19 +2661,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 +2685,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 +2698,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 +2742,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 +2753,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;
@@ -2696,6 +2857,7 @@ function validateSprite(sprite, path, err, warn, spec) {
     return;
   }
   for (const k of unknownKeys(sprite, knownSet)) {
+    if (k === "size") continue;
     if (LAYER_PROPS_ON_SPRITE.has(k)) {
       warn(`${path}.${k}`, "misplaced-property", `'${k}' belongs on the layer, not inside sprite \u2014 move it up one level`);
     } else {
@@ -2903,10 +3065,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 +3080,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 +3090,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'");
@@ -3124,7 +3289,7 @@ function validateSequence(seq) {
         warnings.push({
           path: `segments[${i}].transition`,
           code: "morph-structural-mismatch",
-          message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
+          message: `segments ${i}\u2192${i + 1} differ structurally (${describeStructuralDifferences(s.scene, next.scene)}): morph will fall back to cut`
         });
       } else if (s.scene.timeline === void 0 && next.scene.timeline === void 0 && morphNothingMorphable(s.scene, next.scene, { textCrossfade: s.transition.text === "crossfade" || s.transition.text === "dip" })) {
         warnings.push({
@@ -3143,7 +3308,7 @@ function validateSequence(seq) {
     if (sq.loop !== true) why = "the sequence does not loop";
     else if (last < 1) why = "there is only one segment";
     else if (lastTr?.type !== "morph") why = "the last segment declares no morph transition";
-    else if (structuralSignature(sq.segments[last].scene) !== structuralSignature(sq.segments[0].scene)) why = `segment ${last} and segment 0 differ structurally`;
+    else if (structuralSignature(sq.segments[last].scene) !== structuralSignature(sq.segments[0].scene)) why = `segment ${last} and segment 0 differ structurally (${describeStructuralDifferences(sq.segments[last].scene, sq.segments[0].scene)})`;
     else if (morphChainRoot(sq, last) !== 0) why = `the lap is not one morph chain (segment ${morphChainRoot(sq, last)} starts a new chain), so the wrap would jump seeds`;
     if (why || !canWrapMorph(sq)) {
       warnings.push({ path: "wrapMorph", code: "wrap-morph-inactive", message: `wrapMorph has no effect: ${why ?? "the wrap cannot morph"} \u2014 the wrap stays a cut` });
@@ -3566,6 +3731,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) {
@@ -4824,17 +4990,17 @@ var SpecInstance = class {
     const rows = Math.max(1, Math.round(this.fieldShortSide * h / short));
     const ft = fieldSampleTime(bg, t);
     const key = `${JSON.stringify(bg)}|${w}x${h}|${cols}x${rows}|${ft}`;
-    let raster = this.field;
-    if (!raster || raster.key !== key) {
-      if (!raster || raster.cols !== cols || raster.rows !== rows) {
+    let raster2 = this.field;
+    if (!raster2 || raster2.key !== key) {
+      if (!raster2 || raster2.cols !== cols || raster2.rows !== rows) {
         const canvas = typeof document !== "undefined" ? document.createElement("canvas") : new OffscreenCanvas(cols, rows);
         canvas.width = cols;
         canvas.height = rows;
         const rctx = canvas.getContext("2d");
         if (!rctx) return;
-        raster = { canvas, ctx: rctx, cols, rows, key: "" };
+        raster2 = { canvas, ctx: rctx, cols, rows, key: "" };
       }
-      const img = raster.ctx.createImageData(cols, rows);
+      const img = raster2.ctx.createImageData(cols, rows);
       const data = img.data;
       const seed = this.seed;
       let i = 0;
@@ -4849,14 +5015,14 @@ var SpecInstance = class {
           data[i++] = 255;
         }
       }
-      raster.ctx.putImageData(img, 0, 0);
-      raster.key = key;
-      this.field = raster;
+      raster2.ctx.putImageData(img, 0, 0);
+      raster2.key = key;
+      this.field = raster2;
     }
     const smooth = Math.round(bg.quantize ?? bg.bands.length) < 2;
     const prev = ctx.imageSmoothingEnabled;
     ctx.imageSmoothingEnabled = smooth;
-    ctx.drawImage(raster.canvas, 0, 0, w, h);
+    ctx.drawImage(raster2.canvas, 0, 0, w, h);
     ctx.imageSmoothingEnabled = prev;
   }
   /** Position with parent-orbit resolution: a layer-parented orbit entity's
@@ -5430,14 +5596,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;
@@ -7551,6 +7717,7 @@ function polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1, evenodd = false)
   }
   return cov;
 }
+var MAX_GRID_SIDE = 400;
 function softProfile(u) {
   if (u <= 0) return 1;
   if (u >= 1) return 0;
@@ -7586,12 +7753,13 @@ function discCellInk(cx, cy, rOuter, rInner, soft, x0, y0, cw, ch) {
   }
   return ink / (ni * nj) * sx * sy / (cw * ch);
 }
-function luminanceGrid(spec, opts = {}) {
+function luminanceGrid(spec, opts = {}, maxSide = 200) {
   spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
-  const cols = Math.max(8, Math.min(200, opts.cols ?? 80));
-  const rows = Math.max(8, Math.min(200, opts.rows ?? 48));
+  const cap = Math.max(8, Math.min(MAX_GRID_SIDE, maxSide));
+  const cols = Math.max(8, Math.min(cap, opts.cols ?? 80));
+  const rows = Math.max(8, Math.min(cap, opts.rows ?? 48));
   const { w, h, scale } = scene;
   const cellW = w / cols;
   const cellH = h / rows;
@@ -7605,10 +7773,22 @@ function luminanceGrid(spec, opts = {}) {
     const short = Math.max(1, Math.min(w, h));
     const seed = scene.seed;
     const ft = fieldSampleTime(bg, t);
+    const fCols = Math.max(1, Math.round(FIELD_RASTER_SHORT_SIDE * w / short));
+    const fRows = Math.max(1, Math.round(FIELD_RASTER_SHORT_SIDE * h / short));
+    const viaRaster = cols > fCols || rows > fRows;
+    const rasterLum = viaRaster ? new Float64Array(fCols * fRows).fill(-1) : null;
+    const fieldLum = (c, r) => {
+      if (!rasterLum) return rgb255Luma(fieldRgbAt((c + 0.5) * cellW / short, (r + 0.5) * cellH / short, ft, bg, seed));
+      const fc = Math.min(fCols - 1, Math.floor((c + 0.5) / cols * fCols));
+      const fr = Math.min(fRows - 1, Math.floor((r + 0.5) / rows * fRows));
+      const k = fr * fCols + fc;
+      if (rasterLum[k] < 0) rasterLum[k] = rgb255Luma(fieldRgbAt((fc + 0.5) * w / fCols / short, (fr + 0.5) * h / fRows / short, ft, bg, seed));
+      return rasterLum[k];
+    };
     for (let r = 0; r < rows; r++) {
       let rowSum = 0;
       for (let c = 0; c < cols; c++) {
-        const lum = rgb255Luma(fieldRgbAt((c + 0.5) * cellW / short, (r + 0.5) * cellH / short, ft, bg, seed));
+        const lum = fieldLum(c, r);
         bgCells[r * cols + c] = lum;
         rowSum += lum;
       }
@@ -8841,6 +9021,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 +9039,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 +9068,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;
@@ -9045,6 +9231,7 @@ function edgeAnchored(range2) {
 function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   const hidden = hiddenLayers(spec);
   const authored = spec;
+  const keyed = keyedLayers(authored);
   spec = resolveTimelineAt(spec, opts.t ?? COHESION_T);
   const warnings = [];
   const w = viewport.width;
@@ -9058,18 +9245,19 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     w,
     h
   );
-  let totalEntities = 0;
+  let declaredEntities = 0;
   let textLayerCount = 0;
   let motionLayerCount = 0;
   for (let li = 0; li < spec.layers.length; li++) {
     if (hidden?.[li]) continue;
     const layer = spec.layers[li];
     const entities = allEntities[li];
-    totalEntities += entities.length;
-    const isText = layer.sprite.kind === "text" || layer.sprite.kind === "textBlock";
-    const isStaticText = isText && layer.motion.type === "static";
+    declaredEntities += layer.count;
+    const isText2 = layer.sprite.kind === "text" || layer.sprite.kind === "textBlock";
+    const isKeyed = !!keyed?.[li];
+    const isStaticText = isText2 && layer.motion.type === "static" && !isKeyed;
     if (isStaticText) textLayerCount++;
-    if (layer.motion.type !== "static") motionLayerCount++;
+    if (layer.motion.type !== "static" || isKeyed) motionLayerCount++;
     const coh = cohesion[li];
     if (seamsWorthWarning(layer, coh, entities.length, () => buriedAreaOf(layer, entities, opts.t ?? COHESION_T, w, h))) {
       const s = layer.sprite;
@@ -9094,13 +9282,26 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
         message: `${layer.sprite.kind === "streak" ? "streak sprites orient" : "an oriented stroke turns"} along the motion heading \u2014 static entities have none, so the heading contributes nothing and it renders at angle 0`
       });
     }
-    if (layer.motion.type === "wander" && layer.motion.coherence === 1 && entities.length >= 20) {
+    if (layer.motion.type === "wander" && layer.motion.coherence === 1 && layer.count >= 20) {
       warnings.push({
         path: `layers[${li}].motion.coherence`,
         code: "full-coherence",
         message: "coherence 1 makes every entity share identical harmonics \u2014 the layer moves as a rigid sheet. 0.5\u20130.8 reads as schooling"
       });
     }
+    if (layer.sprite.kind === "emoji" || layer.sprite.kind === "text") {
+      const vpMin = Math.min(w, h);
+      const fontPx = layer.sprite.kind === "text" && layer.sprite.font ? /(\d{1,5}(?:\.\d{1,4})?|\.\d{1,4})px/.exec(layer.sprite.font) : null;
+      const maxGlyph = fontPx ? Number(fontPx[1]) * (spec.units === "px" ? 1 : vpMin / (spec.referenceViewport ?? LIMITS.referenceViewport)) : entities.reduce((m, e) => Math.max(m, e.size), 0);
+      if (maxGlyph > vpMin) {
+        const unitHint = spec.units === "px" ? 'sizes are px under units: "px"' : `sizes are fractions of min(width, height) \u2014 ${fontPx ? "the font's px size is rescaled from the reference viewport" : "write e.g. [0.03, 0.06], not px"}`;
+        warnings.push({
+          path: `layers[${li}]`,
+          code: "giant-entity",
+          message: `layer ${layer.key ? `'${layer.key}'` : li} renders ${layer.sprite.kind} glyphs up to ${Math.round(maxGlyph)}px \u2014 taller than the ${vpMin}px viewport (its min dimension), so they blanket the frame as blurred blobs; ${unitHint}`
+        });
+      }
+    }
     if (layer.sprite.kind === "circle") {
       const maxR = entities.reduce((m, e) => Math.max(m, e.size / 2), 0);
       const maxAlpha = entities.reduce((m, e) => Math.max(m, e.alpha), 0);
@@ -9213,11 +9414,11 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       message: `"lighter"/"screen" layers stack ${additiveInk.toFixed(1)}\xD7 the frame's area in alpha-weighted light \u2014 overlapping additive sprites clip to white on a real canvas, and the analytic perception model sums them without a ceiling so its coverage/luminance/dominance numbers cannot see it. Thin the count, lower alpha (summed additive alpha at any point \u2272 0.5), or drop blend on the densest layer`
     });
   }
-  if (totalEntities > 500 && density !== "dense") {
+  if (declaredEntities > 500 && density !== "dense") {
     warnings.push({
       path: "layers",
       code: "dense-scene",
-      message: `${totalEntities} entities \u2014 scene may feel crowded and hurt performance on low-end devices`
+      message: `${declaredEntities} entities \u2014 scene may feel crowded and hurt performance on low-end devices`
     });
   }
   if (density === "sparse" && totalCoverage > SPARSE_DECLARED_MAX_COVERAGE) {
@@ -9259,25 +9460,41 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       });
     }
   }
-  const flicker = nearLimitFlash(authored);
-  if (flicker) {
+  const flicker2 = nearLimitFlash(authored);
+  if (flicker2) {
     warnings.push({
       path: "timeline",
       code: "flash-near-limit",
-      message: `the timeline flickers ${flicker.flashesPerSecond} times a second over ${Math.round(flicker.area * 100)}% of the frame around ${Math.round(flicker.at)} ms \u2014 at or near WCAG 2.3.1's limit of 3; space opposing luminance changes \u2265 500 ms apart, or lower the contrast between the two states`
+      message: `the timeline flickers ${flicker2.flashesPerSecond} times a second over ${Math.round(flicker2.area * 100)}% of the frame around ${Math.round(flicker2.at)} ms \u2014 at or near WCAG 2.3.1's limit of 3; space opposing luminance changes \u2265 500 ms apart, or lower the contrast between the two states`
     });
   }
   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`
+      });
+    }
+  }
+  if (authored.timeline?.loop && (authored.timeline.duration ?? 0) > 0) {
+    const lap = Math.round(authored.timeline.duration);
+    for (let li = 0; li < authored.layers.length; li++) {
+      if (hidden?.[li]) continue;
+      const layer = authored.layers[li];
+      const life = layer.life;
+      if (!life || life.enter === void 0 && life.exit === void 0 && !life.stagger) continue;
+      const label = layer.key ? `\`${layer.key}\`` : `layers[${li}]`;
+      warnings.push({
+        path: `layers[${li}].life`,
+        code: "life-runs-once",
+        message: `informational: ${label}'s \`life\` runs once on scene time, from when the scene (or its sequence segment) starts \u2014 it does not replay when the timeline loops every ${lap} ms${life.exit !== void 0 ? ", so after its exit the layer stays gone for every later lap" : ""}; to build it on every lap, key its \`opacity\` in the timeline instead`
       });
     }
   }
@@ -9304,7 +9521,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     if (layer.motion.type === "static") continue;
     const entities = allEntities[li];
     if (entities.length < 3) continue;
-    const speeds = entities.map((e) => Math.sqrt(e.vx * e.vx + e.vy * e.vy));
+    const speeds = layer.motion.type === "orbit" ? entities.map((e) => Math.abs(e.vx) * (Math.PI / 180) * e.orbitR) : entities.map((e) => Math.sqrt(e.vx * e.vx + e.vy * e.vy));
     const mean = speeds.reduce((a, b) => a + b, 0) / speeds.length;
     if (mean === 0) continue;
     const maxDev = Math.max(...speeds.map((s) => Math.abs(s - mean)));
@@ -9338,29 +9555,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       }
     }
   }
-  const textBoxes = [];
-  for (let li = 0; li < spec.layers.length; li++) {
-    if (hidden?.[li]) continue;
-    const layer = spec.layers[li];
-    const s = layer.sprite;
-    if (layer.motion.type !== "static") continue;
-    if (s.kind !== "text" && s.kind !== "textBlock") continue;
-    const label = layer.key ? `\`${layer.key}\`` : `layers[${li}]`;
-    for (const e of allEntities[li]) {
-      const p = positionAt(e, 0, w, h);
-      const unturned = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
-      const rot = rotationAt(e, 0);
-      const turn = (q) => ({ x: p.x + (q.x - p.x) * Math.cos(rot) - (q.y - p.y) * Math.sin(rot), y: p.y + (q.x - p.x) * Math.sin(rot) + (q.y - p.y) * Math.cos(rot) });
-      const map = paintMap(spec, layer, w, h, scale);
-      const both = rot && map ? (q) => map(turn(q)) : rot ? turn : map;
-      const box = both ? { ...unturned, ...mapBox(both, unturned) } : unturned;
-      const raw = rot ? { ...unturned, ...mapBox(turn, unturned) } : unturned;
-      const baseAlpha = Math.max(0, Math.min(1, e.alpha - e.pulseAmp)) * (s.kind === "textBlock" ? s.opacity ?? 1 : 1);
-      const alpha = layer.opacity === void 0 && layer.group === void 0 ? baseAlpha : baseAlpha * paintOpacity(spec, layer);
-      const str = s.kind === "textBlock" ? textBlockText(s) : s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
-      textBoxes.push({ li, label, alpha, str, ...box, rawW: raw.x1 - raw.x0, rawH: raw.y1 - raw.y0 });
-    }
-  }
+  const textBoxes = staticTextBoxes(spec, allEntities, hidden, w, h, scale);
   const asFraction = (b) => ({
     x: +(b.x0 / w).toFixed(4),
     y: +(b.y0 / h).toFixed(4),
@@ -9385,34 +9580,46 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       message: `${b.label} text runs off the ${edges.join(" and the ")} at ${w}\xD7${h} \u2014 move position, or shrink fontSize / maxWidth`
     });
   }
-  const pairFlagged = /* @__PURE__ */ new Set();
-  for (let i = 0; i < textBoxes.length; i++) {
-    for (let j = i + 1; j < textBoxes.length; j++) {
-      const a = textBoxes[i];
-      const b = textBoxes[j];
-      if (a.li === b.li) continue;
-      const pair = `${Math.min(a.li, b.li)}:${Math.max(a.li, b.li)}`;
-      if (pairFlagged.has(pair)) continue;
-      const ix = Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0);
-      const iy = Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0);
-      if (ix <= 0 || iy <= 0) continue;
-      const smaller = Math.min((a.x1 - a.x0) * (a.y1 - a.y0), (b.x1 - b.x0) * (b.y1 - b.y0));
-      if (smaller <= 0) continue;
-      const share = ix * iy / smaller;
-      if (share <= 0.1) continue;
-      if (isOutlineStack(a, b)) continue;
-      pairFlagged.add(pair);
-      const [first, second] = a.li < b.li ? [a, b] : [b, a];
-      warnings.push({
-        path: `layers[${first.li}]`,
-        code: "text-overlap",
-        message: `${first.label} and ${second.label} text boxes overlap (~${Math.round(share * 100)}% of the smaller one) \u2014 they will paint over each other; move one or shrink it`,
-        // The two boxes, so an agent can move one without re-deriving the
-        // layout. Additive: the message is unchanged.
-        boxes: [asFraction(first), asFraction(second)]
+  const overlapSamples = textOverlapSamples(authored, spec, allEntities, keyed, hidden, opts.t ?? COHESION_T, opts.until, opts.seed ?? spec.seed ?? 42, w, h);
+  const overlapAt = /* @__PURE__ */ new Map();
+  if (overlapSamples) {
+    const pairsIn = (boxes, each) => {
+      for (let i = 0; i < boxes.length; i++) {
+        for (let j = i + 1; j < boxes.length; j++) {
+          const a = boxes[i];
+          const b = boxes[j];
+          if (a.li === b.li) continue;
+          const share = overlapShare(a, b);
+          if (share <= 0.1 || isOutlineStack(a, b)) continue;
+          each(`${Math.min(a.li, b.li)}:${Math.max(a.li, b.li)}`, a, b, share);
+        }
+      }
+    };
+    const raised = /* @__PURE__ */ new Set();
+    pairsIn(overlapSamples.now, (pair) => raised.add(pair));
+    for (const sample of overlapSamples.visible) {
+      pairsIn(sample.boxes, (pair, a, b, share) => {
+        if (!raised.has(pair) || overlapAt.has(pair)) return;
+        overlapAt.set(pair, { share, a, b, t: sample.t });
       });
     }
   }
+  for (const pair of [...overlapAt.keys()].sort((x, y) => {
+    const [x0, x1] = x.split(":").map(Number);
+    const [y0, y1] = y.split(":").map(Number);
+    return x0 - y0 || x1 - y1;
+  })) {
+    const { share, a, b, t } = overlapAt.get(pair);
+    const [first, second] = a.li < b.li ? [a, b] : [b, a];
+    warnings.push({
+      path: `layers[${first.li}]`,
+      code: "text-overlap",
+      message: `${first.label} and ${second.label} text boxes overlap (~${Math.round(share * 100)}% of the smaller one)${t === null ? "" : `, both visible at ${Math.round(t)} ms`} \u2014 they will paint over each other; move one or shrink it`,
+      // The two boxes, so an agent can move one without re-deriving the
+      // layout. Additive: the message is unchanged.
+      boxes: [asFraction(first), asFraction(second)]
+    });
+  }
   const cellFlagged = /* @__PURE__ */ new Set();
   for (let i = 0; i < textBoxes.length; i++) {
     const a = textBoxes[i];
@@ -9420,6 +9627,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     const layer = spec.layers[a.li];
     const layout = layer.layout;
     if (layout?.type !== "list" && layout?.type !== "table") continue;
+    if (isAtmosphere(layer)) continue;
     for (let j = i + 1; j < textBoxes.length; j++) {
       const b = textBoxes[j];
       if (b.li !== a.li) continue;
@@ -9526,6 +9734,120 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   }
   return warnings;
 }
+function isAtmosphere(layer) {
+  const s = layer.sprite;
+  return (s.kind === "text" || s.kind === "textBlock") && s.role === "atmosphere";
+}
+function staticTextBoxes(spec, allEntities, hidden, w, h, scale, only) {
+  const textBoxes = [];
+  for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
+    if (only && !only.has(li)) continue;
+    const layer = spec.layers[li];
+    const s = layer.sprite;
+    if (layer.motion.type !== "static") continue;
+    if (s.kind !== "text" && s.kind !== "textBlock") continue;
+    const label = layer.key ? `\`${layer.key}\`` : `layers[${li}]`;
+    for (const e of allEntities[li]) {
+      const p = positionAt(e, 0, w, h);
+      const unturned = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
+      const rot = rotationAt(e, 0);
+      const turn = (q) => ({ x: p.x + (q.x - p.x) * Math.cos(rot) - (q.y - p.y) * Math.sin(rot), y: p.y + (q.x - p.x) * Math.sin(rot) + (q.y - p.y) * Math.cos(rot) });
+      const map = paintMap(spec, layer, w, h, scale);
+      const both = rot && map ? (q) => map(turn(q)) : rot ? turn : map;
+      const box = both ? { ...unturned, ...mapBox(both, unturned) } : unturned;
+      const raw = rot ? { ...unturned, ...mapBox(turn, unturned) } : unturned;
+      const baseAlpha = Math.max(0, Math.min(1, e.alpha - e.pulseAmp)) * (s.kind === "textBlock" ? s.opacity ?? 1 : 1);
+      const alpha = layer.opacity === void 0 && layer.group === void 0 ? baseAlpha : baseAlpha * paintOpacity(spec, layer);
+      const str = s.kind === "textBlock" ? textBlockText(s) : s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
+      textBoxes.push({ li, label, alpha, peak: Math.min(1, e.alpha + e.pulseAmp), str, ...box, rawW: raw.x1 - raw.x0, rawH: raw.y1 - raw.y0 });
+    }
+  }
+  return textBoxes;
+}
+function keyedLayers(spec) {
+  if (!spec.timeline) return null;
+  const paths = [...timelineTracks(spec).keys()];
+  if (paths.length === 0) return null;
+  return spec.layers.map((l, i) => paths.some((p) => keyTouchesLayer(p, i, l)));
+}
+function keyTouchesLayer(path, i, layer) {
+  const lp = `layers.${i}`;
+  if (path === "layers" || path === lp || path.startsWith(`${lp}.`)) return true;
+  if (path === "referenceViewport" || path === "units") return true;
+  if (layer.group === void 0) return false;
+  const gp = `groups.${layer.group}`;
+  return path === "groups" || path === gp || path.startsWith(`${gp}.`);
+}
+var TEXT_VISIBLE_FLOOR = 0.02;
+function paintAxisScale(spec, layer) {
+  const axes = (tf) => {
+    const s = Math.abs(tf?.scale ?? 1);
+    return [s * Math.abs(tf?.scaleX ?? 1), s * Math.abs(tf?.scaleY ?? 1)];
+  };
+  const [lx, ly] = axes(layer.transform);
+  const [gx, gy] = axes(groupOf(spec, layer)?.transform);
+  return Math.min(lx * gx, ly * gy);
+}
+var TEXT_OVERLAP_MAX_SAMPLES = 48;
+function textOverlapSamples(authored, spec, allEntities, keyed, hidden, tNow, until, seed, w, h) {
+  const candidates = /* @__PURE__ */ new Set();
+  spec.layers.forEach((l, li) => {
+    const k = l.sprite.kind;
+    if (!hidden?.[li] && (k === "text" || k === "textBlock") && !isAtmosphere(l)) candidates.add(li);
+  });
+  if (candidates.size < 2) return null;
+  const visibleAt = (t, at, entities, boxes) => {
+    const { scale } = entityScales(at, w, h);
+    return (boxes ?? staticTextBoxes(at, entities, hidden, w, h, scale, candidates)).filter((b) => textBoxVisible(at, at.layers[b.li], b, t, w, h, scale));
+  };
+  const now = staticTextBoxes(spec, allEntities, hidden, w, h, entityScales(spec, w, h).scale, candidates);
+  const visible = [{ t: null, boxes: visibleAt(tNow, spec, allEntities, now) }];
+  if (keyed && [...candidates].some((li) => keyed[li])) {
+    const touches = (path) => [...candidates].some((li) => keyTouchesLayer(path, li, authored.layers[li]));
+    let times = timelineSampleTimes(authored, false, 120, touches).filter((t) => t !== tNow && (until === void 0 || t <= until));
+    if (times.length > TEXT_OVERLAP_MAX_SAMPLES) {
+      const step = times.length / TEXT_OVERLAP_MAX_SAMPLES;
+      times = Array.from({ length: TEXT_OVERLAP_MAX_SAMPLES }, (_, i) => times[Math.floor(i * step)]);
+    }
+    const built = /* @__PURE__ */ new Map([[structuralSignature(spec), allEntities]]);
+    for (const t of times) {
+      const at = resolveTimelineAt(authored, t, true);
+      const sig = structuralSignature(at);
+      let entities = built.get(sig);
+      if (!entities) {
+        const sc = entityScales(at, w, h);
+        const rng = createRng3(seed);
+        entities = at.layers.map((l) => buildEntities(l, rng, w, h, sc.scale, sc.countScale));
+        built.set(sig, entities);
+      }
+      visible.push({ t, boxes: visibleAt(t, at, entities) });
+    }
+  }
+  return { now, visible };
+}
+function textBoxVisible(spec, layer, b, t, w, h, scale) {
+  if (b.x1 <= 0 || b.x0 >= w || b.y1 <= 0 || b.y0 >= h) return false;
+  if (paintAxisScale(spec, layer) <= TEXT_VISIBLE_FLOOR) return false;
+  const s = layer.sprite;
+  let a = paintOpacity(spec, layer) * b.peak;
+  if (s.kind === "textBlock") {
+    a *= s.opacity ?? 1;
+    if (s.reveal) {
+      const fsPx = s.fontSize * scale;
+      const lines = breakTextBlock(textBlockText(s), s.maxWidth * scale / fsPx, textMetricsClassFor(s.font));
+      if (revealState(lines, s.reveal, t).progress <= 0) return false;
+    }
+  }
+  return a > TEXT_VISIBLE_FLOOR;
+}
+function overlapShare(a, b) {
+  const ix = Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0);
+  const iy = Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0);
+  if (ix <= 0 || iy <= 0) return 0;
+  const smaller = Math.min((a.x1 - a.x0) * (a.y1 - a.y0), (b.x1 - b.x0) * (b.y1 - b.y0));
+  return smaller > 0 ? ix * iy / smaller : 0;
+}
 function nearLimitFlash(spec) {
   if (!spec.timeline) return null;
   const { times, lap } = lumaKeyTimes(spec);
@@ -9607,7 +9929,7 @@ function groundUnder(spec, allEntities, li, hidden, pt, w, h, base = backgroundR
     if (layer.life !== void 0 || layer.emit !== void 0) continue;
     if ((sp.kind === "circle" || sp.kind === "polygon") && sp.soft) continue;
     if (sp.kind !== "circle" && sp.kind !== "rect" && sp.kind !== "polygon") continue;
-    if (sp.kind === "polygon" && isPathPolygon(sp)) continue;
+    const drawing = sp.kind === "polygon" && isPathPolygon(sp);
     const a = layer.opacity === void 0 && layer.group === void 0 ? 1 : paintOpacity(spec, layer);
     for (const e of allEntities[lj]) {
       if (e.spinSpeed !== 0 || e.pulseAmp > 0 || e.growAmp > 0 || e.alpha * a <= 0) continue;
@@ -9616,6 +9938,14 @@ function groundUnder(spec, allEntities, li, hidden, pt, w, h, base = backgroundR
       const c = positionAt(e, 0, w, h);
       const dx = pt.x - c.x;
       const dy = pt.y - c.y;
+      if (drawing) {
+        if (e.rotate) continue;
+        const ink = pathGroundAt(sp, e, dx, dy, w, h);
+        if (!ink) continue;
+        plate = sourceOverPlate(plate, ink.rgb, Math.min(1, e.alpha * a * ink.opacity));
+        covered = true;
+        continue;
+      }
       let inside2 = false;
       if (sp.kind === "circle") inside2 = Math.hypot(dx, dy) <= e.size / 2;
       else if (sp.kind === "rect") {
@@ -9636,6 +9966,41 @@ function groundUnder(spec, allEntities, li, hidden, pt, w, h, base = backgroundR
   }
   return covered ? { rgb: plate, luma: 0.2126 * plate.r + 0.7152 * plate.g + 0.0722 * plate.b } : null;
 }
+function pathGroundAt(sp, e, dx, dy, w, h) {
+  const base = sp.colors?.[e.colorIndex] ?? sp.color;
+  const fr = pathFrame(sp, e.size / 2, w, h);
+  const u = dx / fr.sx + fr.ox;
+  const v = dy / fr.sy + fr.oy;
+  let r = 0, g = 0, b = 0, wsum = 0, area = 0;
+  for (const part of pathParts(sp)) {
+    if (!part.fill || part.opacity <= 0 || part.flat.points.length < 3) continue;
+    const box = part.box;
+    if (Math.abs(u - box.cx) > box.hw || Math.abs(v - box.cy) > box.hh) continue;
+    const ring = part.flat.points.map(([x, y]) => ({ x, y }));
+    if (!pointInPolygon(u, v, ring)) continue;
+    const pc = hexRgb(part.color ?? base);
+    let rgb = pc;
+    if (part.gradient) {
+      const weights = gradientStopWeights(part.gradient.stops);
+      rgb = { r: 0, g: 0, b: 0 };
+      part.gradient.stops.forEach((st, i) => {
+        const o = st.opacity ?? 1;
+        const c = hexRgb(st.color);
+        const k = weights[i];
+        rgb = { r: rgb.r + (c.r * o + pc.r * (1 - o)) * k, g: rgb.g + (c.g * o + pc.g * (1 - o)) * k, b: rgb.b + (c.b * o + pc.b * (1 - o)) * k };
+      });
+    }
+    const pa = Math.max(1e-6, polygonArea(ring));
+    const wt = pa * part.opacity;
+    r += rgb.r * wt;
+    g += rgb.g * wt;
+    b += rgb.b * wt;
+    wsum += wt;
+    area += pa;
+  }
+  if (wsum <= 0 || area <= 0) return null;
+  return { rgb: { r: r / wsum, g: g / wsum, b: b / wsum }, opacity: Math.min(1, wsum / area) };
+}
 function pointInPolygon(x, y, pts) {
   let inside2 = false;
   for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
@@ -9717,7 +10082,7 @@ function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
     const seg = seq.segments[i];
     const timed = !!seg.scene.timeline && seg.duration !== void 0;
     const tSample = timed ? Math.min(COHESION_T, seg.duration) : void 0;
-    const segWarnings = adviseSpec(seg.scene, viewport, tSample === void 0 ? {} : { t: tSample });
+    const segWarnings = adviseSpec(seg.scene, viewport, tSample === void 0 ? {} : { t: tSample, until: seg.duration });
     const at = tSample === void 0 ? "" : ` (judged ${(tSample / 1e3).toFixed(1)} s into this ${(seg.duration / 1e3).toFixed(1)} s segment)`;
     for (const w of segWarnings) {
       warnings.push({ path: `segments[${i}].scene.${w.path}`, code: w.code, message: w.message + at, boxes: w.boxes });
@@ -9754,7 +10119,7 @@ function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
         warnings.push({
           path: `segments[${i}].transition`,
           code: "morph-structural-mismatch",
-          message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
+          message: `segments ${i}\u2192${i + 1} differ structurally (${describeStructuralDifferences(seq.segments[i].scene, seq.segments[i + 1].scene)}): morph will fall back to cut`
         });
       } else if (!seq.segments[i].scene.timeline && !seq.segments[i + 1].scene.timeline && morphNothingMorphable(seq.segments[i].scene, seq.segments[i + 1].scene, { textCrossfade: tr.text === "crossfade" || tr.text === "dip" })) {
         warnings.push({
@@ -9859,6 +10224,418 @@ function describeScene(spec, options = {}) {
   };
 }
 
+// src/pattern-hazard.ts
+import { FLASH_DARK_MAX, FLASH_MAX_PER_SECOND, FLASH_SWING_THRESHOLD, srgbToLinear as srgbToLinear4 } from "@idle-screens/validator";
+var PATTERN_GRID_SHORT_SIDE = 216;
+var PATTERN_GRID_MAX_SIDE = 400;
+var PATTERN_MIN_PAIRS = 6;
+var PATTERN_STATIONARY_AREA = 0.4;
+var PATTERN_MOVING_AREA = 0.25;
+var PATTERN_FLICKER_AREA = 0.25;
+var PATTERN_MAX_SAMPLE_TIMES = 6;
+var PERIOD_RATIO = 4 / 3;
+var PATTERN_MAX_PITCH = 0.15;
+var PATTERN_MIN_EXTENT = 2;
+var NEIGHBOUR_PITCH = 0.25;
+var BLOCK = 4;
+var DELTA_MS = 1e3 / 60;
+var FLICKER_PERIODS = 4;
+var BASE_T = 5e3;
+var isText = (l) => l.sprite.kind === "text" || l.sprite.kind === "textBlock";
+function prepared(spec, t, keep, flat) {
+  const resolved = resolveTimelineAt(spec, t);
+  const out = { ...resolved, layers: resolved.layers.map((l, i) => keep(l, i) && !isText(l) ? l : { ...l, opacity: 0 }) };
+  delete out.ghosting;
+  if (flat !== void 0) {
+    const v = Math.round(Math.max(0, Math.min(1, flat)) * 255).toString(16).padStart(2, "0");
+    out.background = { type: "solid", color: `#${v}${v}${v}` };
+  }
+  return out;
+}
+function gridSize(viewport) {
+  const { width: w, height: h } = viewport;
+  const short = Math.max(1, Math.min(w, h));
+  const fit = (side) => Math.max(8, Math.min(PATTERN_GRID_MAX_SIDE, Math.round(side / short * PATTERN_GRID_SHORT_SIDE)));
+  return { cols: fit(w), rows: fit(h) };
+}
+function raster(spec, t, opts) {
+  const { cols, rows } = gridSize(opts.viewport);
+  const g = luminanceGrid(spec, { viewport: opts.viewport, seed: opts.seed, t, cols, rows }, PATTERN_GRID_MAX_SIDE);
+  const lum = new Float64Array(g.cells.length);
+  for (let i = 0; i < lum.length; i++) lum[i] = srgbToLinear4(g.cells[i] * 255);
+  const short = Math.min(opts.viewport.width, opts.viewport.height);
+  const bg = g.backgroundCells ?? g.background;
+  return {
+    cols: g.cols,
+    rows: g.rows,
+    cellX: opts.viewport.width / g.cols / short,
+    cellY: opts.viewport.height / g.rows / short,
+    lum,
+    meanGround: bg.reduce((a, b) => a + b, 0) / Math.max(1, bg.length)
+  };
+}
+function stripeExtrema(line) {
+  const n = line.length;
+  const out = [];
+  if (n < 3) return out;
+  let lo = line[0], loAt = 0, hi = line[0], hiAt = 0;
+  let dir = 0;
+  let cand = 0, candFrom = 0, candTo = 0;
+  for (let i = 1; i < n; i++) {
+    const v = line[i];
+    if (dir === 0) {
+      if (v > hi) {
+        hi = v;
+        hiAt = i;
+      }
+      if (v < lo) {
+        lo = v;
+        loAt = i;
+      }
+      if (hi - lo >= FLASH_SWING_THRESHOLD && lo < FLASH_DARK_MAX) {
+        if (loAt < hiAt) {
+          out.push({ x: loAt, v: lo, light: false });
+          dir = 1;
+          cand = hi;
+          candFrom = candTo = hiAt;
+        } else {
+          out.push({ x: hiAt, v: hi, light: true });
+          dir = -1;
+          cand = lo;
+          candFrom = candTo = loAt;
+        }
+      }
+      continue;
+    }
+    if (dir === 1 ? v > cand : v < cand) {
+      cand = v;
+      candFrom = candTo = i;
+      continue;
+    }
+    if (v === cand) {
+      if (candTo === i - 1) candTo = i;
+      continue;
+    }
+    const swing = dir === 1 ? cand - v : v - cand;
+    if (swing >= FLASH_SWING_THRESHOLD && Math.min(cand, v) < FLASH_DARK_MAX) {
+      out.push({ x: (candFrom + candTo) / 2, v: cand, light: dir === 1 });
+      dir = -dir;
+      cand = v;
+      candFrom = candTo = i;
+    }
+  }
+  return out;
+}
+function similarSpacing(a, b, frac) {
+  return Math.abs(a - b) <= 1 + frac * Math.min(a, b);
+}
+function stripeRuns(ext, line, axis) {
+  const runs = [];
+  for (const light of [true, false]) {
+    const idx = [];
+    ext.forEach((e, i) => {
+      if (e.light === light) idx.push(i);
+    });
+    let start = 0;
+    const close = (end) => {
+      const count = end - start + 1;
+      if (count >= PATTERN_MIN_PAIRS) {
+        const xs = idx.slice(start, end + 1).map((i) => ext[i].x);
+        const periods = xs.slice(1).map((x, k) => x - xs[k]).sort((a, b) => a - b);
+        const first = idx[start], last = idx[end];
+        let swing = 0, pairs = 0;
+        for (let k = Math.max(0, first - 1); k < Math.min(ext.length - 1, last + 1); k++) {
+          swing += Math.abs(ext[k + 1].v - ext[k].v);
+          pairs++;
+        }
+        runs.push({ line, axis, from: xs[0], to: xs[xs.length - 1], period: periods[periods.length >> 1], count, light, contrast: pairs ? swing / pairs : 0 });
+      }
+    };
+    for (let k = 1; k < idx.length; k++) {
+      if (k >= 2) {
+        const p0 = ext[idx[k - 1]].x - ext[idx[k - 2]].x;
+        const p1 = ext[idx[k]].x - ext[idx[k - 1]].x;
+        if (!similarSpacing(p0, p1, PERIOD_RATIO - 1)) {
+          close(k - 1);
+          start = k - 1;
+        }
+      }
+    }
+    if (idx.length) close(idx.length - 1);
+  }
+  return runs;
+}
+function scanRaster(r) {
+  const rowLine = new Float64Array(r.cols);
+  const colLine = new Float64Array(r.rows);
+  const perLine = (axis, n) => {
+    const lines = [];
+    for (let k = 0; k < n; k++) {
+      if (axis === "x") {
+        for (let c = 0; c < r.cols; c++) rowLine[c] = r.lum[k * r.cols + c];
+      } else {
+        for (let q = 0; q < r.rows; q++) colLine[q] = r.lum[q * r.cols + k];
+      }
+      const line = axis === "x" ? rowLine : colLine;
+      lines.push(stripeRuns(stripeExtrema(line), k, axis));
+    }
+    return lines;
+  };
+  const all = [perLine("x", r.rows), perLine("y", r.cols)];
+  const kept = [];
+  for (const lines of all) {
+    const flat = lines.flat();
+    const at = /* @__PURE__ */ new Map();
+    flat.forEach((run, i) => at.set(run, i));
+    const parent = flat.map((_, i) => i);
+    const find = (i) => {
+      while (parent[i] !== i) i = parent[i] = parent[parent[i]];
+      return i;
+    };
+    const across = (run) => run.period * (run.axis === "x" ? r.cellX / r.cellY : r.cellY / r.cellX);
+    for (const run of flat) {
+      const reach = Math.max(1, Math.ceil(across(run)));
+      for (let k = run.line + 1; k <= run.line + reach && k < lines.length; k++) {
+        for (const q of lines[k]) {
+          const overlap = Math.min(run.to, q.to) - Math.max(run.from, q.from);
+          if (overlap >= 0.5 * Math.min(run.to - run.from, q.to - q.from) && similarSpacing(run.period, q.period, NEIGHBOUR_PITCH)) {
+            parent[find(at.get(q))] = find(at.get(run));
+          }
+        }
+      }
+    }
+    const span = /* @__PURE__ */ new Map();
+    for (const run of flat) {
+      const root = find(at.get(run));
+      const s0 = span.get(root);
+      const a = across(run);
+      if (!s0) span.set(root, { lo: run.line, hi: run.line, across: a, periods: [run.period], slants: [] });
+      else {
+        s0.lo = Math.min(s0.lo, run.line);
+        s0.hi = Math.max(s0.hi, run.line);
+        s0.across = Math.max(s0.across, a);
+        s0.periods.push(run.period);
+      }
+    }
+    for (const run of flat) {
+      for (const q of lines[run.line + 1] ?? []) {
+        if (q.light !== run.light || find(at.get(q)) !== find(at.get(run))) continue;
+        const d = q.from - run.from;
+        span.get(find(at.get(run))).slants.push(Math.abs(d - run.period * Math.round(d / run.period)));
+      }
+    }
+    const median = (xs) => xs.length ? [...xs].sort((a, b) => a - b)[xs.length >> 1] : 0;
+    for (const run of flat) {
+      const sp = span.get(find(at.get(run)));
+      if (sp.hi - sp.lo + 1 < PATTERN_MIN_EXTENT * sp.across) continue;
+      const [along, step] = run.axis === "x" ? [r.cellX, r.cellY] : [r.cellY, r.cellX];
+      const slant = median(sp.slants) * along;
+      run.pitch = median(sp.periods) * along * (step / Math.hypot(slant, step));
+      if (run.pitch <= PATTERN_MAX_PITCH) kept.push(run);
+    }
+  }
+  return kept;
+}
+function runBlocks(r, run, from = run.from, to = run.to) {
+  const half = run.period / 2;
+  const across = run.axis === "x" ? half * (r.cellX / r.cellY) : half * (r.cellY / r.cellX);
+  const [x0, x1, y0, y1] = run.axis === "x" ? [from - half, to + half, run.line - across, run.line + across] : [run.line - across, run.line + across, from - half, to + half];
+  const bw = Math.ceil(r.cols / BLOCK), bh = Math.ceil(r.rows / BLOCK);
+  const clampB = (v, blocks) => Math.max(0, Math.min(blocks - 1, Math.floor(v / BLOCK)));
+  return { bx0: clampB(x0, bw), bx1: clampB(x1, bw), by0: clampB(y0, bh), by1: clampB(y1, bh) };
+}
+function markedArea(r, marked) {
+  const bw = Math.ceil(r.cols / BLOCK);
+  let cells = 0;
+  marked.forEach((m, i) => {
+    if (!m) return;
+    const bx = i % bw, by = Math.floor(i / bw);
+    cells += (Math.min(r.cols, (bx + 1) * BLOCK) - bx * BLOCK) * (Math.min(r.rows, (by + 1) * BLOCK) - by * BLOCK);
+  });
+  return cells / (r.cols * r.rows);
+}
+function patternArea(r, runs) {
+  const bw = Math.ceil(r.cols / BLOCK), bh = Math.ceil(r.rows / BLOCK);
+  const marked = new Uint8Array(bw * bh);
+  for (const run of runs) {
+    const b = runBlocks(r, run);
+    for (let y = b.by0; y <= b.by1; y++) for (let x = b.bx0; x <= b.bx1; x++) marked[y * bw + x] = 1;
+  }
+  return markedArea(r, marked);
+}
+function flicker(a, b, runs, dt) {
+  const bw = Math.ceil(a.cols / BLOCK), bh = Math.ceil(a.rows / BLOCK);
+  const marked = new Uint8Array(bw * bh);
+  let worst = 0;
+  for (const run of runs) {
+    if (run.contrast <= 0) continue;
+    const span = Math.max(8, FLICKER_PERIODS * run.period);
+    for (let s = run.from; s < run.to; s += span) {
+      const e = Math.min(run.to, s + span);
+      const c0 = Math.max(0, Math.floor(s)), c1 = Math.min((run.axis === "x" ? a.cols : a.rows) - 1, Math.ceil(e));
+      let sum = 0;
+      for (let c = c0; c <= c1; c++) {
+        const i = run.axis === "x" ? run.line * a.cols + c : c * a.cols + run.line;
+        sum += Math.abs(b.lum[i] - a.lum[i]);
+      }
+      const hz = sum / (c1 - c0 + 1) / (dt / 1e3) / (2 * run.contrast);
+      worst = Math.max(worst, hz);
+      if (hz > FLASH_MAX_PER_SECOND) {
+        const bl = runBlocks(a, run, s, e);
+        for (let y = bl.by0; y <= bl.by1; y++) for (let x = bl.bx0; x <= bl.bx1; x++) marked[y * bw + x] = 1;
+      }
+    }
+  }
+  return { area: markedArea(a, marked), hz: worst };
+}
+var nonZero = (v) => v !== void 0 && (Array.isArray(v) ? v[0] !== 0 || v[1] !== 0 : v !== 0);
+function layerPatternMotion(spec, index) {
+  const l = spec.layers[index];
+  if (!l) return "static";
+  const keyed = keyedLayers2(spec);
+  if (keyed.has(index)) return "moving";
+  const sprite = l.sprite;
+  if (nonZero(l.spin) || l.rock || l.pulse || l.grow || l.emit || sprite.cycle) return "moving";
+  const m = l.motion;
+  const moves = !!m.speed && nonZero(m.speed);
+  switch (m.type) {
+    case "static":
+      return "static";
+    case "drift":
+      if (!moves) return (m.bob ?? 0) !== 0 ? "moving" : "static";
+      return (m.bob ?? 0) !== 0 || m.bidirectional ? "moving" : "flow";
+    case "rise":
+      if (!moves) return (m.sway ?? 0) !== 0 ? "moving" : "static";
+      return (m.sway ?? 0) !== 0 ? "moving" : "flow";
+    case "warp":
+      return moves ? "flow" : "static";
+    default:
+      return "moving";
+  }
+}
+function keyedLayers2(spec) {
+  const out = /* @__PURE__ */ new Set();
+  if (!spec.timeline) return out;
+  for (const path of timelineTracks(spec).keys()) {
+    const [root, id] = path.split(".");
+    if (root === "layers" && /^\d+$/.test(id ?? "")) out.add(Number(id));
+    else if (root === "groups" && id !== void 0) spec.layers.forEach((l, i) => {
+      if (l.group === id) out.add(i);
+    });
+    else out.add(-1);
+  }
+  return out;
+}
+function backgroundMotion(spec) {
+  if (keyedLayers2(spec).has(-1)) return "moving";
+  const bg = spec.background;
+  if (!bg) return "static";
+  const drift = bg.drift;
+  if (bg.type === "field") return drift && drift.amount !== 0 ? "flow" : "static";
+  return drift ? "flow" : "static";
+}
+function patternSampleTimes(spec) {
+  const tl = spec.timeline;
+  if (!tl) return [BASE_T];
+  const lap = tl.loop && tl.duration ? tl.duration : 0;
+  const settle = /* @__PURE__ */ new Set();
+  for (const keys of timelineTracks(spec).values()) {
+    for (const k of keys) {
+      const end = k.t + Math.max(0, k.dur ?? DEFAULT_KEY_DUR);
+      settle.add(lap ? end % lap : end);
+    }
+  }
+  settle.delete(BASE_T);
+  const ts = [...settle].sort((a, b) => a - b);
+  const room = PATTERN_MAX_SAMPLE_TIMES - 1;
+  const picked = ts.length <= room ? ts : Array.from({ length: room }, (_, i) => ts[Math.round((i + 1) * (ts.length - 1) / room)]);
+  return [BASE_T, ...new Set(picked)];
+}
+var pct = (f) => `${Math.round(f * 100)}%`;
+function describeRun(run) {
+  const p = run.pitch ?? 0;
+  return `${run.count} light-dark pairs of stripes at a pitch of ${p.toFixed(3)} of the short side (about ${Math.round(p * 1080)} px at 1080p), luminance swing ${run.contrast.toFixed(2)}`;
+}
+var REMEDY = "To pass: lower the stripes' contrast (keep light and dark within 0.1 relative luminance of each other), use five or fewer stripes, break the regular spacing, or confine the pattern to a smaller part of the frame.";
+function patternHazardReport(spec, opts = {}) {
+  const viewport = opts.viewport ?? { width: 1920, height: 1080 };
+  const ro = { viewport, seed: opts.seed };
+  const motion = spec.layers.map((_, i) => layerPatternMotion(spec, i));
+  const bgMotion = backgroundMotion(spec);
+  const anyMotion = bgMotion !== "static" || motion.some((m, i) => m !== "static" && !isText(spec.layers[i]));
+  const best = { fails: false, kind: null, at: null, area: 0, movingArea: 0, flickerArea: 0, flickerHz: 0, pairs: 0, pitch: null, contrast: 0, rasters: 0 };
+  let rasters = 0;
+  for (const t of opts.times ?? patternSampleTimes(spec)) {
+    const full = raster(prepared(spec, t, () => true), t, ro);
+    rasters++;
+    const runs = scanRaster(full);
+    const area = patternArea(full, runs);
+    const top = runs.reduce((a, b) => !a || b.count > a.count ? b : a, null);
+    const found = {
+      fails: false,
+      kind: null,
+      at: runs.length ? t : null,
+      area,
+      movingArea: 0,
+      flickerArea: 0,
+      flickerHz: 0,
+      pairs: top?.count ?? 0,
+      pitch: top?.pitch ?? null,
+      contrast: top?.contrast ?? 0,
+      rasters: 0
+    };
+    const where = `at t = ${Math.round(t)} ms`;
+    if (top && area > PATTERN_STATIONARY_AREA) {
+      return {
+        ...found,
+        fails: true,
+        kind: "pattern",
+        rasters,
+        message: `pattern hazard (photosensitivity): ${where} the frame shows a regular stripe pattern (${describeRun(top)}) over ${pct(area)} of the frame. ITU-R BT.1702 treats more than five light-dark pairs of such stripes as harmful above 40% of the screen when still, and above 25% when they move, turn or oscillate. ${REMEDY}`
+      };
+    }
+    if (top && area > PATTERN_MOVING_AREA) {
+      const movers = motion.map((m) => m === "moving");
+      if (movers.some((m, i) => m && !isText(spec.layers[i])) || bgMotion === "moving") {
+        const flat = bgMotion === "moving" ? void 0 : full.meanGround;
+        const own = raster(prepared(spec, t, (_, i) => movers[i], flat), t, ro);
+        rasters++;
+        const ownRuns = scanRaster(own);
+        found.movingArea = patternArea(own, ownRuns);
+        if (found.movingArea > PATTERN_MOVING_AREA) {
+          const ownTop = ownRuns.reduce((a, b) => !a || b.count > a.count ? b : a, null) ?? top;
+          return {
+            ...found,
+            fails: true,
+            kind: "moving-pattern",
+            rasters,
+            message: `pattern hazard (photosensitivity): ${where} a regular stripe pattern (${describeRun(ownTop)}) that moves, turns or oscillates covers ${pct(found.movingArea)} of the frame. ITU-R BT.1702 limits a moving pattern of more than five light-dark pairs to 25% of the screen (40% when still). ${REMEDY} Or hold it still.`
+          };
+        }
+      }
+      if (anyMotion) {
+        const later = raster(prepared(spec, t + DELTA_MS, () => true), t + DELTA_MS, ro);
+        rasters++;
+        const f = flicker(full, later, runs, DELTA_MS);
+        found.flickerArea = f.area;
+        found.flickerHz = f.hz;
+        if (f.area > PATTERN_FLICKER_AREA) {
+          return {
+            ...found,
+            fails: true,
+            kind: "flicker",
+            rasters,
+            message: `pattern hazard (photosensitivity): ${where} a regular stripe pattern (${describeRun(top)}) moves across its stripes fast enough that ${pct(f.area)} of the frame flickers more than ${FLASH_MAX_PER_SECOND} times a second (up to ${Math.round(f.hz)}): each point turns light and dark as the stripes pass, at speed \xF7 pitch. More than 3 a second over 25% of the frame is a flash hazard. Slow it (under 3 stripe pitches a second), widen the pitch, lower the contrast, or shrink the patterned area.`
+          };
+        }
+      }
+    }
+    if (area > best.area || best.at === null && found.at !== null) Object.assign(best, found);
+  }
+  best.rasters = rasters;
+  return best;
+}
+
 // src/examples/aquarium.ts
 var AQUARIUM_SPEC = {
   schemaVersion: 1,
@@ -12376,6 +13153,14 @@ export {
   MURMUR_SPEC,
   NOSTALGHIA_CANDLE_SPEC,
   ORRERY_SPEC,
+  PATTERN_FLICKER_AREA,
+  PATTERN_GRID_SHORT_SIDE,
+  PATTERN_MAX_PITCH,
+  PATTERN_MAX_SAMPLE_TIMES,
+  PATTERN_MIN_EXTENT,
+  PATTERN_MIN_PAIRS,
+  PATTERN_MOVING_AREA,
+  PATTERN_STATIONARY_AREA,
   PHASE_DUET_SPEC,
   PINGS_SPEC,
   POLYGONS_SPEC,
@@ -12385,6 +13170,7 @@ export {
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
+  SEAMLESS_PERIOD_KINDS,
   SHARD_FALL_SPEC,
   SIGNAL_BOARD_SPEC,
   SNOWFALL_SPEC,
@@ -12419,6 +13205,7 @@ export {
   createFinishPass,
   createSceneCanvas,
   describeScene,
+  describeStructuralDifferences,
   diffScenes,
   dominanceRanking,
   drawSpan,
@@ -12448,6 +13235,7 @@ export {
   latticeHash,
   layerCellFootprints,
   layerCohesion,
+  layerPatternMotion,
   lerpPathD,
   lerpSpec,
   lerpValue,
@@ -12465,6 +13253,8 @@ export {
   normalizeSeed,
   pathFrame,
   pathParts,
+  patternHazardReport,
+  patternSampleTimes,
   perceiveScene,
   perceiveSequenceFrame,
   periodWithoutTimeline,
@@ -12496,6 +13286,7 @@ export {
   steerablePaths,
   strokeDrawnSamples,
   strokeLines,
+  structuralDifferences,
   structuralSignature,
   textBlockAnchorOffset,
   textBlockText,