@idle-screens/schema 3.16.1 → 3.17.1

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
@@ -1821,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 [];
@@ -2224,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)) {
@@ -2395,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`);
         }
       }
@@ -2760,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 {
@@ -3191,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({
@@ -3210,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` });
@@ -4892,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;
@@ -4917,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
@@ -7619,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;
@@ -7654,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;
@@ -7673,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;
       }
@@ -9119,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;
@@ -9132,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;
@@ -9168,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);
@@ -9287,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) {
@@ -9333,12 +9460,12 @@ 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) {
@@ -9356,6 +9483,21 @@ 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);
+    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`
+      });
+    }
+  }
   for (let li = 0; li < spec.layers.length; li++) {
     if (hidden?.[li]) continue;
     const layer = spec.layers[li];
@@ -9379,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)));
@@ -9413,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),
@@ -9460,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];
@@ -9495,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;
@@ -9601,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);
@@ -9682,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;
@@ -9691,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") {
@@ -9711,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++) {
@@ -9792,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 });
@@ -9829,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({
@@ -9934,6 +10224,468 @@ 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 LATTICE_SLACK = 1;
+var LATTICE_JITTER = 0.15;
+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);
+}
+var latticeTolerance = (p) => LATTICE_SLACK + LATTICE_JITTER * p;
+function latticeFit(xs, s, e) {
+  const n = e - s + 1;
+  let sk = 0, sx = 0, skk = 0, skx = 0;
+  for (let j = s; j <= e; j++) {
+    const k = j - s, x = xs[j];
+    sk += k;
+    sx += x;
+    skk += k * k;
+    skx += k * x;
+  }
+  const p = (n * skx - sk * sx) / (n * skk - sk * sk), a = (sx - p * sk) / n;
+  let worst = 0, at = s;
+  for (let j = s; j <= e; j++) {
+    const off = Math.abs(xs[j] - a - p * (j - s));
+    if (off > worst) {
+      worst = off;
+      at = j;
+    }
+    if (j > s) {
+      const gap = Math.abs(xs[j] - xs[j - 1] - p);
+      if (gap > worst) {
+        worst = gap;
+        at = j - s <= e - j ? j - 1 : j;
+      }
+    }
+  }
+  return { p, worst, trimStart: at - s < e - at };
+}
+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);
+    });
+    const xs = idx.map((i) => ext[i].x);
+    const close = (s, e) => {
+      while (e - s + 1 >= PATTERN_MIN_PAIRS) {
+        const fit = latticeFit(xs, s, e);
+        if (fit.worst <= latticeTolerance(fit.p)) break;
+        if (fit.trimStart) s++;
+        else e--;
+      }
+      const count = e - s + 1;
+      if (count < PATTERN_MIN_PAIRS) return;
+      const periods = xs.slice(s + 1, e + 1).map((x, k) => x - xs[s + k]).sort((a, b) => a - b);
+      const first = idx[s], last = idx[e];
+      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[s], to: xs[e], period: periods[periods.length >> 1], count, light, contrast: pairs ? swing / pairs : 0 });
+    };
+    let start = 0, n = 0, sk = 0, sx = 0, skk = 0, skx = 0;
+    const add = (j) => {
+      const k = j - start, x = xs[j];
+      n++;
+      sk += k;
+      sx += x;
+      skk += k * k;
+      skx += k * x;
+    };
+    for (let j = 0; j < xs.length; j++) {
+      if (n >= 2) {
+        const p = (n * skx - sk * sx) / (n * skk - sk * sk), a = (sx - p * sk) / n;
+        const tol = latticeTolerance(p);
+        if (Math.abs(xs[j] - a - p * (j - start)) > tol || Math.abs(xs[j] - xs[j - 1] - p) > tol) {
+          close(start, j - 1);
+          start = j - 1;
+          n = sk = sx = skk = skx = 0;
+          add(j - 1);
+        }
+      }
+      add(j);
+    }
+    if (xs.length) close(start, xs.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;
+    const medians = /* @__PURE__ */ new Map();
+    for (const run of flat) {
+      const root = find(at.get(run));
+      const sp = span.get(root);
+      if (sp.hi - sp.lo + 1 < PATTERN_MIN_EXTENT * sp.across) continue;
+      let med = medians.get(root);
+      if (!med) medians.set(root, med = { period: median(sp.periods), slant: median(sp.slants) });
+      const [along, step] = run.axis === "x" ? [r.cellX, r.cellY] : [r.cellY, r.cellX];
+      const slant = med.slant * along;
+      run.pitch = med.period * 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,
@@ -12451,6 +13203,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,
@@ -12495,6 +13255,7 @@ export {
   createFinishPass,
   createSceneCanvas,
   describeScene,
+  describeStructuralDifferences,
   diffScenes,
   dominanceRanking,
   drawSpan,
@@ -12524,6 +13285,7 @@ export {
   latticeHash,
   layerCellFootprints,
   layerCohesion,
+  layerPatternMotion,
   lerpPathD,
   lerpSpec,
   lerpValue,
@@ -12541,6 +13303,8 @@ export {
   normalizeSeed,
   pathFrame,
   pathParts,
+  patternHazardReport,
+  patternSampleTimes,
   perceiveScene,
   perceiveSequenceFrame,
   periodWithoutTimeline,
@@ -12572,6 +13336,7 @@ export {
   steerablePaths,
   strokeDrawnSamples,
   strokeLines,
+  structuralDifferences,
   structuralSignature,
   textBlockAnchorOffset,
   textBlockText,