@idle-screens/schema 3.11.1 → 3.12.0

package/dist/index.js

@@ -2027,6 +2027,16 @@ function featherAlphas(steps, additive) {
 var FEATHER_STEPS = 6;
 
 // src/simulate.ts
+function entityScales(spec, w, h) {
+  const scale = spec.units === "px" ? 1 : Math.min(w, h);
+  const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
+  let countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
+  if (countScale > 1) {
+    const rawTotal = spec.layers.reduce((s, l) => s + Math.round(l.count * countScale), 0);
+    if (rawTotal > LIMITS.maxTotal) countScale *= LIMITS.maxTotal / rawTotal;
+  }
+  return { scale, countScale };
+}
 var WARP_NEAR = 0.08;
 var WARP_MAX_SCALE = 8;
 function spriteVariants(sprite) {
@@ -3310,13 +3320,7 @@ var SpecInstance = class {
   /** (Re)seed and place all entities — deterministic for the seed + viewport. */
   rebuild() {
     const rng = createRng(this.seed);
-    const scale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
-    const refVp = this.effSpec.referenceViewport ?? LIMITS.referenceViewport;
-    let countScale = scale > 1 ? Math.min(this.w, this.h) / refVp : 1;
-    if (countScale > 1) {
-      const rawTotal = this.effSpec.layers.reduce((s, l) => s + Math.round(l.count * countScale), 0);
-      if (rawTotal > LIMITS.maxTotal) countScale *= LIMITS.maxTotal / rawTotal;
-    }
+    const { scale, countScale } = entityScales(this.effSpec, this.w, this.h);
     this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h, scale, countScale) }));
     this.lastStructural = structuralSignature(this.effSpec);
   }
@@ -4748,7 +4752,7 @@ function compileSequence(spec) {
 }
 
 // src/advise.ts
-import { createRng as createRng2 } from "@idle-screens/core";
+import { createRng as createRng3 } from "@idle-screens/core";
 
 // src/luma.ts
 function fieldRenderedRgbs(bg) {
@@ -5092,1504 +5096,1662 @@ function seamsWorthWarning(layer, c, entityCount) {
   return layer.blend !== "lighter" && layer.blend !== "screen";
 }
 
-// src/advise.ts
-var LOW_CONTRAST_FLOOR = 0.05;
-var SPARSE_DECLARED_MAX_COVERAGE = 0.02;
-var READ_LEGIBILITY_FLOOR = 4.5;
-var READ_SAFE_AREA = 0.05;
-function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
-  const hidden = hiddenLayers(spec);
-  spec = resolveTimelineAt(spec, opts.t ?? COHESION_T);
-  const warnings = [];
-  const w = viewport.width;
-  const h = viewport.height;
-  const scale = spec.units === "px" ? 1 : Math.min(w, h);
-  const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
-  let countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
-  if (countScale > 1) {
-    const rawTotal = spec.layers.reduce((sum, l) => sum + Math.round(l.count * countScale), 0);
-    if (rawTotal > LIMITS.maxTotal) countScale *= LIMITS.maxTotal / rawTotal;
+// src/perceive.ts
+import { createRng as createRng2 } from "@idle-screens/core";
+var GLOW_SPREAD = 2.4;
+var LINE_SALIENCE = 3.5;
+var GHOST_TAPS = 12;
+var POLYGON_OUTLINE_CELLS = 3;
+var POLYGON_SCANLINES = 4;
+function buildScene(spec, opts) {
+  const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
+  const seed = normalizeSeed(opts.seed ?? spec.seed ?? 42);
+  const { scale, countScale } = entityScales(spec, w, h);
+  const rng = createRng2(seed);
+  const layers = spec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, w, h, scale, countScale) }));
+  const byKey = /* @__PURE__ */ new Map();
+  for (const { layer, entities } of layers) if (layer.key) byKey.set(layer.key, entities);
+  let transforms = null;
+  for (const { layer, entities } of layers) {
+    const map = paintMap(spec, layer, w, h, scale);
+    if (!map) continue;
+    transforms ??= /* @__PURE__ */ new Map();
+    for (const e of entities) transforms.set(e, map);
   }
-  const rng = createRng2(opts.seed ?? spec.seed ?? 42);
-  const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale, countScale));
-  const bgLuma = backgroundLuma(spec);
-  const bgRgb = backgroundRgb(spec);
-  const cohesion = cohesionOf(
-    spec.layers.map((layer, i) => ({ layer, entities: allEntities[i] })),
-    opts.t ?? COHESION_T,
-    w,
-    h
-  );
-  let totalEntities = 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";
-    if (isStaticText) textLayerCount++;
-    if (layer.motion.type !== "static") motionLayerCount++;
-    const coh = cohesion[li];
-    if (seamsWorthWarning(layer, coh, entities.length)) {
-      warnings.push({
-        path: `layers[${li}]`,
-        code: "overlap-seams",
-        message: `entities bury ${Math.round((coh.overlap ?? 0) * 100)}% of each other's outlines, so this layer is drawn as one shape \u2014 but ${coh.seamCause}, so every overlap paints a visible edge and it will read as a pile of sprites instead. A layer merges into a single silhouette only when it is one flat colour at alpha 1, hard-edged, with no blend and no pulse.`
-      });
-    }
-    if (layer.trail && layer.motion.type === "static") {
-      warnings.push({
-        path: `layers[${li}].trail`,
-        code: "trail-on-static",
-        message: "trail has no effect on static entities \u2014 they have no past positions to draw"
-      });
-    }
-    if ((layer.sprite.kind === "streak" || layer.sprite.kind === "stroke" && layer.sprite.orient) && layer.motion.type === "static") {
-      warnings.push({
-        path: `layers[${li}].sprite`,
-        code: "streak-on-static",
-        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${layer.spin ? " (spin still rotates the mark)" : " and it renders at angle 0"}`
-      });
-    }
-    if (layer.motion.type === "wander" && layer.motion.coherence === 1 && entities.length >= 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 === "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);
-      if (maxR * maxAlpha < 0.05) {
-        warnings.push({
-          path: `layers[${li}]`,
-          code: "invisible-layer",
-          message: `layer's max visible radius (${maxR.toFixed(1)}px \xD7 ${maxAlpha.toFixed(2)} alpha) is below perceptual floor`
-        });
-      }
+  return { w, h, scale, seed, layers, byKey, transforms };
+}
+function posOf(scene, e, t) {
+  const p = positionAt(e, t, scene.w, scene.h);
+  if (e.orbitParent) {
+    const parent = scene.byKey.get(e.orbitParent)?.[0];
+    if (parent) {
+      const pp = positionAt(parent, t, scene.w, scene.h);
+      p.x += pp.x;
+      p.y += pp.y;
     }
-    if (entities.length > 0 && layer.sprite.kind !== "emoji") {
-      const seps = entities.map((e) => {
-        const hex = spriteHex(layer, e);
-        if (hex === null) return Infinity;
-        return colourSeparation(layer, { rgb: hexRgb(hex), luma: hexLuma(hex) }, { rgb: bgRgb, luma: bgLuma });
-      });
-      const best = Math.max(...seps);
-      if (best < LOW_CONTRAST_FLOOR) {
-        const additive = layer.blend === "lighter" || layer.blend === "screen";
-        warnings.push({
-          path: `layers[${li}].sprite`,
-          code: "low-contrast-layer",
-          message: additive ? `additive layer adds almost no light (luma ${best.toFixed(3)}) \u2014 a "lighter"/"screen" layer is only as visible as it is bright` : `layer colour is within ${best.toFixed(3)} of the background (floor ${LOW_CONTRAST_FLOOR}) \u2014 it will read as background, not as content`
-        });
-      }
+  }
+  const map = scene.transforms?.get(e);
+  return map ? map(p) : p;
+}
+function textBox(s, e, p) {
+  const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
+  const fh = m ? Number(m[1]) : e.size;
+  const str = s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
+  const fw = Math.max(fh, 0.62 * fh * Math.min(str.length, 48));
+  const align = s.align ?? "center";
+  const baseline = s.baseline ?? "middle";
+  return {
+    cx: align === "left" ? p.x + fw / 2 : align === "right" ? p.x - fw / 2 : p.x,
+    cy: baseline === "top" ? p.y + fh * 0.6 : baseline === "bottom" ? p.y - fh * 0.6 : p.y,
+    halfX: fw / 2,
+    halfY: fh * 0.6
+  };
+}
+function textBlockBox(s, _e, p, w, h) {
+  const unitScale = Math.min(w, h);
+  const fsPx = s.fontSize * unitScale;
+  const lh = (s.lineHeight ?? 1.4) * fsPx;
+  const maxWPx = s.maxWidth * unitScale;
+  const maxWEm = maxWPx / fsPx;
+  const lines = breakTextBlock(s.text, maxWEm, textMetricsClassFor(s.font));
+  const totalH = lines.length * lh;
+  const maxLineW = lines.reduce((m, l) => Math.max(m, l.widthEm), 0) * fsPx;
+  const align = s.align ?? "left";
+  const cx = align === "center" ? p.x + maxWPx / 2 : align === "right" ? p.x + maxWPx - maxLineW / 2 : p.x + maxLineW / 2;
+  const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
+  return {
+    cx: cx + dx,
+    cy: p.y + totalH / 2 + dy,
+    halfX: maxLineW / 2,
+    halfY: totalH / 2
+  };
+}
+function textBlockRevealFraction(s, w, h, t) {
+  if (!s.reveal) return 1;
+  const unitScale = Math.min(w, h);
+  const maxWEm = s.maxWidth * unitScale / (s.fontSize * unitScale);
+  const lines = breakTextBlock(s.text, maxWEm, textMetricsClassFor(s.font));
+  const rs = revealState(lines, s.reveal, t);
+  if (rs.glyphAlphas) {
+    let sum = 0;
+    let n = 0;
+    for (const line of rs.glyphAlphas) for (const a of line) {
+      sum += a;
+      n++;
     }
+    return n > 0 ? sum / n : 1;
   }
-  let totalCoverage = 0;
-  for (let li = 0; li < spec.layers.length; li++) {
-    if (hidden?.[li]) continue;
-    const layer = spec.layers[li];
-    const entities = allEntities[li];
-    const paintA = layer.opacity === void 0 && layer.group === void 0 ? 1 : paintOpacity(spec, layer);
-    for (const e of entities) {
-      const r = e.size / 2;
-      let pixArea;
-      if (layer.sprite.kind === "circle") {
-        pixArea = Math.PI * r * r;
-      } else if (layer.sprite.kind === "polygon") {
-        pixArea = polygonArea(polygonPoints(layer.sprite, r));
-      } else if (layer.sprite.kind === "bar") {
-        pixArea = e.size * barFraction(layer.sprite, e.barIndex ?? 0) * (e.size2 ?? e.size * 0.2);
-      } else if (layer.sprite.kind === "textBlock") {
-        const fsPx = layer.sprite.fontSize * scale;
-        const lh = (layer.sprite.lineHeight ?? 1.4) * fsPx;
-        const maxWPx = layer.sprite.maxWidth * scale;
-        const lines = breakTextBlock(layer.sprite.text, maxWPx / fsPx, textMetricsClassFor(layer.sprite.font));
-        pixArea = maxWPx * lines.length * lh * 0.55 * (layer.sprite.opacity ?? 1);
-      } else {
-        pixArea = e.size * e.size;
+  return rs.progress;
+}
+function polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1) {
+  const nc = c1 - c0 + 1;
+  const cov = new Float64Array(nc * (r1 - r0 + 1));
+  const xMin = c0 * cellW;
+  const xMax = (c1 + 1) * cellW;
+  const share = 1 / POLYGON_SCANLINES;
+  const hits = [];
+  const addSpan = (row, xa, xb) => {
+    const a = Math.max(xMin, xa);
+    const b = Math.min(xMax, xb);
+    if (!(b > a)) return;
+    const first = Math.max(c0, Math.floor(a / cellW));
+    const last = Math.min(c1, Math.floor(b / cellW));
+    for (let c = first; c <= last; c++) {
+      const len = Math.min(b, (c + 1) * cellW) - Math.max(a, c * cellW);
+      if (len > 0) cov[row * nc + (c - c0)] += len / cellW * share;
+    }
+  };
+  for (let r = r0; r <= r1; r++) {
+    for (let k = 0; k < POLYGON_SCANLINES; k++) {
+      const y = (r + (k + 0.5) / POLYGON_SCANLINES) * cellH;
+      hits.length = 0;
+      for (let i = 0; i < pts.length; i++) {
+        const p = pts[i];
+        const q = pts[(i + 1) % pts.length];
+        const down = p.y <= y && q.y > y;
+        if (!down && !(q.y <= y && p.y > y)) continue;
+        hits.push({ x: p.x + (y - p.y) / (q.y - p.y) * (q.x - p.x), dir: down ? 1 : -1 });
       }
-      let duty = 1;
-      if (layer.emit) {
-        const [ga, gb] = layer.emit.grow ?? [1, 1];
-        const g2 = (ga * ga + ga * gb + gb * gb) / 3;
-        duty = Math.min(layer.emit.life, layer.emit.every) / layer.emit.every * 0.5 * g2;
+      if (hits.length < 2) continue;
+      hits.sort((m, n) => m.x - n.x);
+      let wind = 0;
+      let start = 0;
+      for (const hit of hits) {
+        const before = wind;
+        wind += hit.dir;
+        if (before === 0 && wind !== 0) start = hit.x;
+        else if (before !== 0 && wind === 0) addSpan(r - r0, start, hit.x);
       }
-      totalCoverage += paintA === 1 ? pixArea * e.alpha * duty / (w * h) : pixArea * e.alpha * duty * paintA / (w * h);
-    }
-    if (layer.links) {
-      const positions = entities.map((e) => positionAt(e, 0, w, h));
-      const maxDistPx = layer.links.maxDist * scale;
-      const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false, w, h);
-      const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
-      const lwPx = (layer.links.width ?? defaultWidth) * scale;
-      const la = layer.links.alpha ?? 1;
-      for (const edge of edges) totalCoverage += paintA === 1 ? edge.dist * lwPx * la / (w * h) : edge.dist * lwPx * la * paintA / (w * h);
     }
   }
-  const density = spec.density ?? "normal";
-  const wouldBeSparse = totalCoverage < 5e-4 && spec.layers.length > 0;
-  if (wouldBeSparse && density !== "sparse") {
-    warnings.push({
-      path: "layers",
-      code: "sparse-scene",
-      message: `alpha-weighted coverage is ${(totalCoverage * 100).toFixed(4)}% \u2014 scene will look empty on most displays`
-    });
-  }
-  if (totalEntities > 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`
-    });
-  }
-  if (density === "sparse" && totalCoverage > SPARSE_DECLARED_MAX_COVERAGE) {
-    warnings.push({
-      path: "density",
-      code: "density-mismatch",
-      message: `declared sparse but alpha-weighted coverage is ${(totalCoverage * 100).toFixed(2)}% \u2014 either the declaration or the scene is wrong`
-    });
-  } else if (density === "dense" && wouldBeSparse) {
-    warnings.push({
-      path: "density",
-      code: "density-mismatch",
-      message: `declared dense but alpha-weighted coverage is ${(totalCoverage * 100).toFixed(4)}% \u2014 the scene will look empty`
-    });
+  return cov;
+}
+function distanceToOutline(pts, x, y) {
+  let best = Infinity;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i];
+    const q = pts[(i + 1) % pts.length];
+    const ex = q.x - p.x;
+    const ey = q.y - p.y;
+    const len2 = ex * ex + ey * ey;
+    const u = len2 > 0 ? Math.max(0, Math.min(1, ((x - p.x) * ex + (y - p.y) * ey) / len2)) : 0;
+    const dx = x - (p.x + ex * u);
+    const dy = y - (p.y + ey * u);
+    best = Math.min(best, dx * dx + dy * dy);
   }
-  if (spec.layers.length > 0 && textLayerCount > 0 && motionLayerCount === 0) {
-    const textRatio = textLayerCount / spec.layers.length;
-    if (textRatio >= 0.8) {
-      warnings.push({
-        path: "layers",
-        code: "text-heavy",
-        message: "most layers are static text \u2014 reads as a document, not a screensaver"
-      });
+  return Math.sqrt(best);
+}
+function luminanceGrid(spec, opts = {}) {
+  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 { w, h, scale } = scene;
+  const cellW = w / cols;
+  const cellH = h / rows;
+  const bg = spec.background;
+  const bgRow = new Array(rows).fill(0);
+  let bgCells;
+  if (!bg || bg.type === "solid") {
+    bgRow.fill(hexLuma(bg?.color ?? "#05050a"));
+  } else if (bg.type === "field") {
+    bgCells = new Array(cols * rows);
+    const short = Math.max(1, Math.min(w, h));
+    const seed = scene.seed;
+    const ft = fieldSampleTime(bg, t);
+    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));
+        bgCells[r * cols + c] = lum;
+        rowSum += lum;
+      }
+      bgRow[r] = rowSum / cols;
     }
-  }
-  for (let li = 0; li < spec.layers.length; li++) {
-    if (hidden?.[li]) continue;
-    const layer = spec.layers[li];
-    if (!layer.links || layer.links.mode === "chain") continue;
-    const entities = allEntities[li];
-    const positions = entities.map((e) => positionAt(e, 0, w, h));
-    const maxDist = layer.links.maxDist * scale;
-    const pairs = linkPairs(positions, layer.links.k, maxDist, layer.wrap !== false, w, h);
-    const maxPossible = Math.min(entities.length * layer.links.k, entities.length * (entities.length - 1) / 2);
-    if (maxPossible > 0 && pairs.length / maxPossible < 0.1) {
-      warnings.push({
-        path: `layers[${li}].links`,
-        code: "link-starvation",
-        message: `only ${pairs.length}/${maxPossible} possible edges formed \u2014 raise count or widen links.maxDist`
-      });
+  } else {
+    const stops = [...bg.stops].sort((a, b) => a.at - b.at);
+    for (let r = 0; r < rows; r++) {
+      const y = (r + 0.5) / rows;
+      let lum;
+      if (y <= stops[0].at) lum = hexLuma(stops[0].color);
+      else if (y >= stops[stops.length - 1].at) lum = hexLuma(stops[stops.length - 1].color);
+      else {
+        let i = 0;
+        while (i < stops.length - 1 && stops[i + 1].at < y) i++;
+        const a = stops[i];
+        const b = stops[i + 1];
+        const k = b.at === a.at ? 0 : (y - a.at) / (b.at - a.at);
+        lum = hexLuma(a.color) + (hexLuma(b.color) - hexLuma(a.color)) * k;
+      }
+      bgRow[r] = lum;
     }
-  }
-  for (let li = 0; li < spec.layers.length; li++) {
-    if (hidden?.[li]) continue;
-    const layer = spec.layers[li];
-    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 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)));
-    if (maxDev / mean < 0.05) {
-      warnings.push({
-        path: `layers[${li}].motion`,
-        code: "uniform-motion",
-        message: "all entities move at nearly identical speed \u2014 widen the speed range for visual variety"
-      });
+    if (bg.band) {
+      const bandPx = bg.band.height * (spec.units === "px" ? 1 : Math.min(w, h));
+      const fromRow = Math.max(0, Math.floor((h - bandPx) / cellH));
+      for (let r = fromRow; r < rows; r++) bgRow[r] = hexLuma(bg.band.color);
     }
   }
-  const composed = spec.layers.map((l, li) => ({ l, li, ents: allEntities[li] })).filter(({ li }) => !hidden?.[li]).filter(({ l }) => !["bounce", "warp", "path"].includes(l.motion.type)).filter(({ l }) => !(l.motion.type === "orbit" && l.motion.center && "layer" in l.motion.center));
-  const composedCount = composed.reduce((s, c) => s + c.ents.length, 0);
-  if (composedCount >= 8) {
-    const positions = composed.flatMap(({ ents }) => ents.map((e) => positionAt(e, 0, w, h)));
-    const cx = positions.reduce((s, p) => s + p.x, 0) / positions.length;
-    const cy = positions.reduce((s, p) => s + p.y, 0) / positions.length;
-    const offX = Math.abs(cx / w - 0.5);
-    const offY = Math.abs(cy / h - 0.5);
-    if (offX > 0.2 || offY > 0.2) {
-      warnings.push({
-        path: "layers",
-        code: "off-center",
-        message: `centroid at (${(cx / w).toFixed(2)}, ${(cy / h).toFixed(2)}) \u2014 composition is heavily offset from center`
-      });
+  const cells = new Array(cols * rows);
+  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells[r * cols + c] = bgCells ? bgCells[r * cols + c] : bgRow[r];
+  const compose = (idx, lum, a, blend) => {
+    const cur = cells[idx];
+    if (blend === "lighter" || blend === "screen") cells[idx] = Math.min(1, cur + lum * a);
+    else if (blend === "multiply") cells[idx] = cur * (1 - a * (1 - lum));
+    else cells[idx] = cur * (1 - a) + lum * a;
+  };
+  const splatTrail = (layer, e, tPass, lifeA, alphaScale) => {
+    const trail = layer.trail;
+    if (!trail) return;
+    const fade = trail.fade ?? 1;
+    const n = Math.min(Math.ceil(trail.length / 50), LIMITS.maxTrailSamples);
+    const headAlpha = alphaAt(e, tPass) * lifeA;
+    const headSize = sizeAt(e, tPass);
+    const lum = spriteLuma(layer, e);
+    const soft = layer.sprite.kind === "circle" && !!layer.sprite.soft;
+    const wrapOn = layer.wrap !== false;
+    const head = posOf(scene, e, tPass);
+    let prevX = head.x;
+    let prevY = head.y;
+    for (let s = 1; s <= n; s++) {
+      const k = s / n;
+      const pastT = tPass - k * trail.length;
+      if (pastT < 0) break;
+      const pos = posOf(scene, e, pastT);
+      if (wrapOn && (Math.abs(pos.x - prevX) > w / 2 || Math.abs(pos.y - prevY) > h / 2)) break;
+      prevX = pos.x;
+      prevY = pos.y;
+      const a = headAlpha * (1 - k * fade) * alphaScale;
+      if (a <= 4e-3) break;
+      const rad = headSize / 2 * (1 - k * 0.7);
+      if (rad < 0.2) break;
+      const c0 = Math.max(0, Math.floor((pos.x - rad) / cellW));
+      const c1 = Math.min(cols - 1, Math.floor((pos.x + rad) / cellW));
+      const r0 = Math.max(0, Math.floor((pos.y - rad) / cellH));
+      const r1 = Math.min(rows - 1, Math.floor((pos.y + rad) / cellH));
+      for (let r = r0; r <= r1; r++) {
+        for (let c = c0; c <= c1; c++) {
+          const dx = (c + 0.5) * cellW - pos.x;
+          const dy = (r + 0.5) * cellH - pos.y;
+          const d = Math.sqrt(dx * dx + dy * dy);
+          if (d > rad + Math.min(cellW, cellH) / 2) continue;
+          const wgt = soft ? Math.max(0.1, 1 - d / Math.max(rad, 1e-6)) : 1;
+          compose(r * cols + c, lum, Math.min(1, a * wgt), layer.blend);
+        }
+      }
     }
-  }
-  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 raw = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
-      const map = paintMap(spec, layer, w, h, scale);
-      const box = map ? { ...raw, ...mapBox(map, raw) } : raw;
-      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);
-      textBoxes.push({ li, label, alpha, ...box });
+  };
+  const splatPolygonOutline = (layer, s, e, p, sz, a, lum, tPass) => {
+    const radius = sz / 2;
+    const rot = rotationAt(e, tPass);
+    const cr = Math.cos(rot);
+    const sr = Math.sin(rot);
+    const pts = polygonPoints(s, radius).map((q) => ({ x: p.x + q.x * cr - q.y * sr, y: p.y + q.x * sr + q.y * cr }));
+    const additive = layer.blend === "lighter" || layer.blend === "screen";
+    const glow = !!s.soft && additive;
+    let band = 0;
+    if (glow) {
+      const perimeter = pts.reduce((acc, q, i) => {
+        const n = pts[(i + 1) % pts.length];
+        return acc + Math.hypot(n.x - q.x, n.y - q.y);
+      }, 0);
+      band = perimeter > 0 ? (GLOW_SPREAD - 1) * (2 * polygonArea(pts) / perimeter) : 0;
     }
-  }
-  const asFraction = (b) => ({
-    x: +(b.x0 / w).toFixed(4),
-    y: +(b.y0 / h).toFixed(4),
-    w: +((b.x1 - b.x0) / w).toFixed(4),
-    h: +((b.y1 - b.y0) / h).toFixed(4)
-  });
-  const tolX = w * 0.01;
-  const tolY = h * 0.01;
-  const offFlagged = /* @__PURE__ */ new Set();
-  for (const b of textBoxes) {
-    if (offFlagged.has(b.li)) continue;
-    const edges = [];
-    if (b.x0 < -tolX) edges.push(`left edge by ~${Math.round(-b.x0)}px`);
-    if (b.x1 > w + tolX) edges.push(`right edge by ~${Math.round(b.x1 - w)}px`);
-    if (b.y0 < -tolY) edges.push(`top edge by ~${Math.round(-b.y0)}px`);
-    if (b.y1 > h + tolY) edges.push(`bottom edge by ~${Math.round(b.y1 - h)}px`);
-    if (edges.length === 0) continue;
-    offFlagged.add(b.li);
-    warnings.push({
-      path: `layers[${b.li}]`,
-      code: "text-off-screen",
-      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;
-      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 readFlagged = /* @__PURE__ */ new Set();
-  for (const b of textBoxes) {
-    if (readFlagged.has(b.li)) continue;
-    const layer = spec.layers[b.li];
-    const s = layer.sprite;
-    if (s.kind !== "text" && s.kind !== "textBlock" || s.role !== "read") continue;
-    const boxes = textBoxes.filter((x) => x.li === b.li);
-    readFlagged.add(b.li);
-    const ink = hexRgb(s.color ?? "#e6e8ef");
-    const textPlate = (base, alpha) => {
-      if (layer.blend === "lighter" || layer.blend === "screen") return additivePlate(base, ink, alpha, layer.blend);
-      if (layer.blend === "multiply") {
-        return {
-          r: base.r * (1 - alpha + ink.r * alpha),
-          g: base.g * (1 - alpha + ink.g * alpha),
-          b: base.b * (1 - alpha + ink.b * alpha)
-        };
-      }
-      return sourceOverPlate(base, ink, alpha);
-    };
-    let worst = null;
-    for (const box of boxes) {
-      const cy = (box.y0 + box.y1) / 2;
-      const cx = (box.x0 + box.x1) / 2;
-      const groundRgb = backgroundRgbAt(spec, cy, h, scale, cx, w, opts.backgroundSeed ?? opts.seed, opts.t ?? COHESION_T);
-      const ground = legibilityRatio(textPlate(groundRgb, box.alpha), groundRgb);
-      const lit = brightestAdditivePlate(spec, allEntities, groundRgb, box, w, h);
-      const plate = lit ? legibilityRatio(textPlate(lit.rgb, box.alpha), lit.rgb) : Infinity;
-      if (!worst || Math.min(ground, plate) < Math.min(worst.ground, worst.plate)) {
-        worst = { ground, plate, plateLabel: lit?.label ?? null };
-      }
-    }
-    if (worst && Math.min(worst.ground, worst.plate) < READ_LEGIBILITY_FLOOR) {
-      const under = worst.plateLabel ? ` and ${worst.plate.toFixed(1)}:1 under ${worst.plateLabel} at its brightest` : "";
-      warnings.push({
-        path: `layers[${b.li}].sprite`,
-        code: "text-legibility",
-        message: `${b.label} is declared role: 'read' but its colour reads at ${worst.ground.toFixed(1)}:1 against the background at the box centre${under} \u2014 below ${READ_LEGIBILITY_FLOOR}:1; brighten the text, darken the ground under it, or declare role: 'atmosphere' if it is texture`
-      });
-    }
-    const edges = [];
-    const x0 = Math.min(...boxes.map((x) => x.x0));
-    const x1 = Math.max(...boxes.map((x) => x.x1));
-    const y0 = Math.min(...boxes.map((x) => x.y0));
-    const y1 = Math.max(...boxes.map((x) => x.y1));
-    if (x0 < w * READ_SAFE_AREA) edges.push("left");
-    if (x1 > w * (1 - READ_SAFE_AREA)) edges.push("right");
-    if (y0 < h * READ_SAFE_AREA) edges.push("top");
-    if (y1 > h * (1 - READ_SAFE_AREA)) edges.push("bottom");
-    if (edges.length > 0) {
-      warnings.push({
-        path: `layers[${b.li}]`,
-        code: "text-safe-area",
-        message: `${b.label} is declared role: 'read' but its box is within ${READ_SAFE_AREA * 100}% of the ${edges.join(" and ")} edge${edges.length === 1 ? "" : "s"} at ${w}\xD7${h} \u2014 displays crop and bezels hide that zone; move it inward`,
-        boxes: [asFraction({ x0, y0, x1, y1 })]
-      });
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const q of pts) {
+      minX = Math.min(minX, q.x);
+      maxX = Math.max(maxX, q.x);
+      minY = Math.min(minY, q.y);
+      maxY = Math.max(maxY, q.y);
     }
-  }
-  return warnings;
-}
-function brightestAdditivePlate(spec, allEntities, ground, box, w, h) {
-  let best = null;
-  for (let lj = 0; lj < spec.layers.length; lj++) {
-    const layer = spec.layers[lj];
-    const blend = layer.blend;
-    if (blend !== "lighter" && blend !== "screen") continue;
-    if (lj === box.li) continue;
-    const entities = allEntities[lj];
-    const moved = layer.transform !== void 0 || groupOf(spec, layer)?.transform !== void 0;
-    for (const e of entities) {
-      const hex = spriteHex(layer, e);
-      if (hex === null) continue;
-      const growScale = (e.motion === "warp" ? WARP_MAX_SCALE : 1) * (e.emit ? Math.max(e.emit.growFrom, e.emit.growTo) : 1);
-      const maxDim = Math.max(e.size, e.size2 ?? 0) * (1 + e.growAmp) * growScale;
-      if (maxDim < box.fs) continue;
-      if (!moved && !entityReachesBox(e, maxDim / 2, box, w, h)) continue;
-      const a = layer.opacity === void 0 && layer.group === void 0 ? Math.min(1, e.alpha + e.pulseAmp) : Math.min(1, e.alpha + e.pulseAmp) * paintOpacity(spec, layer);
-      if (a <= 0) continue;
-      const plate = additivePlate(ground, hexRgb(hex), a, blend);
-      const lum = relativeLuminance(plate);
-      if (!best || lum > best.lum) {
-        best = { rgb: plate, label: layer.key ? `\`${layer.key}\`` : `layers[${lj}]`, lum };
+    const c0 = Math.max(0, Math.floor((minX - band) / cellW));
+    const c1 = Math.min(cols - 1, Math.floor((maxX + band) / cellW));
+    const r0 = Math.max(0, Math.floor((minY - band) / cellH));
+    const r1 = Math.min(rows - 1, Math.floor((maxY + band) / cellH));
+    if (c0 > c1 || r0 > r1) return;
+    const cov = polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1);
+    const nc = c1 - c0 + 1;
+    for (let r = r0; r <= r1; r++) {
+      for (let c = c0; c <= c1; c++) {
+        const f = cov[(r - r0) * nc + (c - c0)];
+        const x = (c + 0.5) * cellW;
+        const y = (r + 0.5) * cellH;
+        let wgt;
+        if (glow) {
+          const outX = Math.max(0, minX - x, x - maxX);
+          const outY = Math.max(0, minY - y, y - maxY);
+          if (f >= 1) wgt = 1;
+          else if (outX * outX + outY * outY >= band * band) wgt = f;
+          else {
+            const k = band > 0 ? Math.max(0, 1 - distanceToOutline(pts, x, y) / band) : 0;
+            wgt = f + (1 - f) * k * k;
+          }
+        } else if (s.soft) {
+          wgt = f * Math.max(0.1, 1 - Math.hypot(x - p.x, y - p.y) / Math.max(radius, 1e-6));
+        } else {
+          wgt = f;
+        }
+        if (wgt > 0) compose(r * cols + c, lum, a * Math.min(1, wgt), layer.blend);
       }
     }
-  }
-  return best ? { rgb: best.rgb, label: best.label } : null;
-}
-function entityReachesBox(e, r, box, w, h) {
-  if (e.motion === "static") {
-    const p = positionAt(e, 0, w, h);
-    return p.x + r > box.x0 && p.x - r < box.x1 && p.y + r > box.y0 && p.y - r < box.y1;
-  }
-  if (e.motion === "orbit" && !e.orbitParent) {
-    const span = e.orbitR + r;
-    return e.orbitCx + span > box.x0 && e.orbitCx - span < box.x1 && e.orbitCy + span > box.y0 && e.orbitCy - span < box.y1;
-  }
-  return true;
-}
-function textBoxAt(s, e, p, spec, w, h) {
-  const m = s.font ? /(\d{1,5}(?:\.\d{1,4})?|\.\d{1,4})px/.exec(s.font) : null;
-  const fontScale = spec.units === "px" ? 1 : Math.min(w, h) / (spec.referenceViewport ?? LIMITS.referenceViewport);
-  const fh = m ? Number(m[1]) * fontScale : e.size;
-  const str = s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
-  let fw = textWidthEm(str) * fh;
-  if (s.maxWidth) fw = Math.min(fw, s.maxWidth * (spec.units === "px" ? 1 : Math.min(w, h)));
-  const align = s.align ?? "center";
-  const baseline = s.baseline ?? "middle";
-  const x0 = align === "left" ? p.x : align === "right" ? p.x - fw : p.x - fw / 2;
-  const y0 = baseline === "top" ? p.y : baseline === "bottom" ? p.y - fh : p.y - fh / 2;
-  return { x0, y0, x1: x0 + fw, y1: y0 + fh, fs: fh };
-}
-function textBlockBoxAt(s, p, w, h) {
-  const unit = Math.min(w, h);
-  const fsPx = s.fontSize * unit;
-  const lh = (s.lineHeight ?? 1.4) * fsPx;
-  const maxWPx = s.maxWidth * unit;
-  const lines = breakTextBlock(s.text, maxWPx / fsPx, textMetricsClassFor(s.font));
-  const maxLineW = lines.reduce((mx, l) => Math.max(mx, l.widthEm), 0) * fsPx;
-  const totalH = lines.length * lh;
-  const align = s.align ?? "left";
-  const x0 = align === "center" ? p.x + (maxWPx - maxLineW) / 2 : align === "right" ? p.x + maxWPx - maxLineW : p.x;
-  const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
-  return { x0: x0 + dx, y0: p.y + dy, x1: x0 + dx + maxLineW, y1: p.y + dy + totalH, fs: fsPx };
-}
-function hiddenLayers(spec) {
-  if (!spec.groups && !spec.layers.some((l) => l.opacity !== void 0)) return null;
-  const tracks = spec.timeline ? timelineTracks(spec) : null;
-  const pinnedZero = (path, base, ancestors) => {
-    if (base !== 0) return false;
-    if (!tracks) return true;
-    for (const [p, keys] of tracks) {
-      if (p === path && keys.some((k) => k.value !== 0)) return false;
-      if (ancestors.includes(p)) return false;
-    }
-    return true;
   };
-  const out = spec.layers.map((l, i) => {
-    const lp = `layers.${i}`;
-    if (pinnedZero(`${lp}.opacity`, l.opacity, ["layers", lp])) return true;
-    const g = l.group !== void 0 && spec.groups && Object.prototype.hasOwnProperty.call(spec.groups, l.group) ? spec.groups[l.group] : void 0;
-    return !!g && pinnedZero(`groups.${l.group}.opacity`, g.opacity, ["groups", `groups.${l.group}`]);
-  });
-  return out.some(Boolean) ? out : null;
-}
-function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
-  const warnings = [];
-  for (let i = 0; i < seq.segments.length; i++) {
-    const segWarnings = adviseSpec(seq.segments[i].scene, viewport);
-    for (const w of segWarnings) {
-      warnings.push({ path: `segments[${i}].scene.${w.path}`, code: w.code, message: w.message, boxes: w.boxes });
-    }
-  }
-  const fadeBound = seq.loop ? seq.segments.length : seq.segments.length - 1;
-  const fades = seq.segments.slice(0, fadeBound).filter((s) => s.transition?.type === "fade").length;
-  if (fades > 0) {
-    const first = seq.segments.slice(0, fadeBound).findIndex((s) => s.transition?.type === "fade");
-    warnings.push({
-      path: `segments[${first}].transition`,
-      code: "fade-degrades-on-low-tier",
-      message: `informational: ${fades} fade transition${fades === 1 ? "" : "s"} declared \u2014 viewers on the 'basic' or 'minimal' capability tier render fade as cut (two live segments for dur is over that budget); the show still plays`
-    });
-  }
-  for (let i = 0; i < seq.segments.length - 1; i++) {
-    const tr = seq.segments[i].transition;
-    const lumaA = backgroundLuma(resolveTimelineAt(seq.segments[i].scene, seq.segments[i].duration ?? 0));
-    const lumaB = backgroundLuma(resolveTimelineAt(seq.segments[i + 1].scene, 0));
-    const delta = Math.abs(lumaA - lumaB);
-    if (delta > 0.5 && tr?.type !== "fade") {
-      warnings.push({
-        path: `segments[${i}]`,
-        code: "boundary-luminance-jump",
-        message: `background luminance jumps ${delta.toFixed(2)} at boundary ${i}\u2192${i + 1} \u2014 may flash on cut${tr === void 0 || tr.type === "cut" ? `; declare transition: { type: 'fade', dur } on segments[${i}] to ramp it` : ""}`
-      });
-    }
-    if (tr?.type === "morph") {
-      const sigA = structuralSignature(seq.segments[i].scene);
-      const sigB = structuralSignature(seq.segments[i + 1].scene);
-      if (sigA !== sigB) {
-        warnings.push({
-          path: `segments[${i}].transition`,
-          code: "morph-structural-mismatch",
-          message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
-        });
-      } 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({
-          path: `segments[${i}].transition`,
-          code: "morph-nothing-morphable",
-          message: `segments ${i}\u2192${i + 1} differ only in values morph cannot interpolate (strings such as textBlock.text step on the first frame): the morph will look like a cut \u2014 fade text via colour or reveal.progress`
-        });
-      }
-    }
-  }
-  return warnings;
-}
-
-// src/describe.ts
-import { createRng as createRng3 } from "@idle-screens/core";
-function describeScene(spec, options = {}) {
-  const { width: w, height: h } = options.viewport ?? { width: 1920, height: 1080 };
-  const seed = options.seed ?? spec.seed ?? 42;
-  const times = options.times ?? [0, 5e3, 15e3];
-  const scale = spec.units === "viewport" ? Math.min(w, h) : 1;
-  const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
-  const countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
-  const rng = createRng3(seed);
-  const builtLayers = spec.layers.map((layer) => ({
-    layer,
-    entities: buildEntities(layer, rng, w, h, scale, countScale)
-  }));
-  const snapshots = times.map((t) => {
-    const layerSnapshots = builtLayers.map(({ layer, entities }) => {
-      const positions = entities.map((e) => positionAt(e, t, w, h));
-      const cx = positions.length > 0 ? positions.reduce((s, p) => s + p.x, 0) / positions.length : 0;
-      const cy = positions.length > 0 ? positions.reduce((s, p) => s + p.y, 0) / positions.length : 0;
-      let pixArea = 0;
+  const splatPass = (tPass, alphaScale) => {
+    for (const { layer, entities } of scene.layers) {
+      const lifeA = layer.opacity === void 0 && layer.group === void 0 ? lifeAlphaAt(layer.life, tPass) : lifeAlphaAt(layer.life, tPass) * paintOpacity(spec, layer);
+      if (lifeA <= 0) continue;
       for (const e of entities) {
-        const r = e.size / 2;
-        pixArea += layer.sprite.kind === "circle" ? Math.PI * r * r : layer.sprite.kind === "polygon" ? polygonArea(polygonPoints(layer.sprite, r)) : e.size * e.size;
-      }
-      const coverage = pixArea / (w * h);
-      const meanAlpha = entities.length > 0 ? entities.reduce((s, e) => s + e.alpha, 0) / entities.length : 0;
-      let linksDrawn = null;
-      let linksExpected = null;
-      let connectedComponents = null;
-      let isolatedNodes = null;
-      if (layer.links) {
-        const maxDist = layer.links.maxDist * scale;
-        const pairs = linkPairs(positions, layer.links.k, maxDist, layer.wrap !== false, w, h);
-        linksDrawn = pairs.length;
-        linksExpected = Math.min(entities.length * layer.links.k, entities.length * (entities.length - 1) / 2);
-        const parent = Array.from({ length: entities.length }, (_, i) => i);
-        const find = (x) => {
-          while (parent[x] !== x) {
-            parent[x] = parent[parent[x]];
-            x = parent[x];
+        splatTrail(layer, e, tPass, lifeA, alphaScale);
+        const a = Math.min(1, alphaAt(e, tPass) * lifeA) * alphaScale;
+        if (a <= 4e-3) continue;
+        const lum = spriteLuma(layer, e);
+        const p = posOf(scene, e, tPass);
+        const sz = layer.transform || layer.group !== void 0 ? sizeAt(e, tPass) * paintSize(spec, layer) : sizeAt(e, tPass);
+        const s = layer.sprite;
+        if (s.kind === "polygon" && sz >= POLYGON_OUTLINE_CELLS * Math.min(cellW, cellH)) {
+          splatPolygonOutline(layer, s, e, p, sz, a, lum, tPass);
+          continue;
+        }
+        if (s.kind === "stroke") {
+          const pts = strokeSamples(s, sz / 2);
+          let angle = rotationAt(e, tPass);
+          if (s.orient) angle += headingAt(e, tPass, w, h) ?? 0;
+          const ca = Math.cos(angle);
+          const sa = Math.sin(angle);
+          const lw = strokeWidthPx(s, scale);
+          const stampAt = (q, u) => {
+            const x = p.x + q.x * ca - q.y * sa;
+            const y = p.y + q.x * sa + q.y * ca;
+            const c = Math.floor(x / cellW);
+            const r = Math.floor(y / cellH);
+            if (c < 0 || c >= cols || r < 0 || r >= rows) return;
+            const taper = s.taper ? strokeTaper(u) : 1;
+            compose(r * cols + c, lum, a * Math.min(1, lw * taper / cellH), layer.blend);
+          };
+          const step = Math.min(cellW, cellH) / 2;
+          stampAt(pts[0], 0);
+          for (let i = 1; i < pts.length; i++) {
+            const q0 = pts[i - 1];
+            const q1 = pts[i];
+            const segLen = Math.hypot(q1.x - q0.x, q1.y - q0.y);
+            const sub = Math.max(1, Math.ceil(segLen / step));
+            for (let k = 1; k <= sub; k++) {
+              const f = k / sub;
+              stampAt({ x: q0.x + (q1.x - q0.x) * f, y: q0.y + (q1.y - q0.y) * f }, (i - 1 + f) / (pts.length - 1));
+            }
           }
-          return x;
-        };
-        for (const [a, b] of pairs) {
-          const ra = find(a);
-          const rb = find(b);
-          if (ra !== rb) parent[ra] = rb;
+          continue;
         }
-        const roots = new Set(entities.map((_, i) => find(i)));
-        connectedComponents = roots.size;
-        const degree = new Uint16Array(entities.length);
-        for (const [a, b] of pairs) {
-          degree[a]++;
-          degree[b]++;
+        if (s.kind === "streak") {
+          const heading = (headingAt(e, tPass, w, h) ?? 0) + rotationAt(e, tPass);
+          const steps = Math.max(2, Math.ceil(sz / Math.min(cellW, cellH)));
+          const wgt = Math.min(1, (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale / cellH);
+          for (let i = 0; i <= steps; i++) {
+            const k = i / steps;
+            const x = p.x - Math.cos(heading) * sz * (1 - k);
+            const y = p.y - Math.sin(heading) * sz * (1 - k);
+            const c = Math.floor(x / cellW);
+            const r = Math.floor(y / cellH);
+            if (c < 0 || c >= cols || r < 0 || r >= rows) continue;
+            compose(r * cols + c, lum, a * k * wgt, layer.blend);
+          }
+          continue;
         }
-        isolatedNodes = degree.filter((d) => d === 0).length;
-      }
-      return {
-        key: layer.key,
-        count: entities.length,
-        centroid: { x: +(cx / w).toFixed(3), y: +(cy / h).toFixed(3) },
-        coverage: +coverage.toFixed(4),
-        meanAlpha: +meanAlpha.toFixed(3),
-        linksDrawn,
-        linksExpected,
-        connectedComponents,
-        isolatedNodes
-      };
-    });
-    const warnings = [];
-    for (const ls of layerSnapshots) {
-      const label = ls.key ?? `layer`;
-      if (ls.coverage * ls.meanAlpha < 5e-4) {
-        warnings.push(`${label}: effectively invisible (coverage\xD7alpha=${(ls.coverage * ls.meanAlpha).toFixed(5)})`);
-      }
-      if (ls.linksDrawn !== null && ls.linksExpected !== null && ls.linksExpected > 0) {
-        const ratio = ls.linksDrawn / ls.linksExpected;
-        if (ratio < 0.1) {
-          warnings.push(`${label}: link starvation \u2014 ${ls.linksDrawn}/${ls.linksExpected} edges formed`);
+        let centerX = p.x;
+        let centerY = p.y;
+        let halfX = sz / 2;
+        let halfY = s.kind === "rect" ? (e.size2 ?? sz) * (e.size > 0 ? sz / e.size : 1) / 2 : sz / 2;
+        if (s.kind === "text") {
+          const box = textBox(s, e, p);
+          centerX = box.cx;
+          centerY = box.cy;
+          halfX = box.halfX;
+          halfY = box.halfY;
+        } else if (s.kind === "textBlock") {
+          const box = textBlockBox(s, e, p, w, h);
+          centerX = box.cx;
+          centerY = box.cy;
+          halfX = box.halfX;
+          halfY = box.halfY;
+        } else if (s.kind === "bar") {
+          const len = sz * barFraction(s, e.barIndex ?? 0);
+          if (len <= 0) continue;
+          const th = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz * 0.2;
+          const box = barBox(s.direction ?? "right", len, th);
+          const rot = rotationAt(e, tPass);
+          const cr = Math.cos(rot);
+          const sr = Math.sin(rot);
+          centerX = p.x + box.cx * cr - box.cy * sr;
+          centerY = p.y + box.cx * sr + box.cy * cr;
+          halfX = Math.abs(box.halfX * cr) + Math.abs(box.halfY * sr);
+          halfY = Math.abs(box.halfX * sr) + Math.abs(box.halfY * cr);
+        }
+        const circular = s.kind === "circle" || s.kind === "ring" || s.kind === "polygon";
+        const soft = (s.kind === "circle" || s.kind === "polygon") && !!s.soft;
+        const shapeWeight = s.kind === "polygon" ? polygonFill(s, sz / 2) : s.kind === "rect" && s.feather ? (1 - s.feather / 2) * (1 - s.feather / 2) : 1;
+        const additive = layer.blend === "lighter" || layer.blend === "screen";
+        const glow = soft && additive;
+        const reachX = glow ? halfX * GLOW_SPREAD : halfX;
+        const reachY = glow ? halfY * GLOW_SPREAD : halfY;
+        const c0 = Math.max(0, Math.floor((centerX - reachX) / cellW));
+        const c1 = Math.min(cols - 1, Math.floor((centerX + reachX) / cellW));
+        const r0 = Math.max(0, Math.floor((centerY - reachY) / cellH));
+        const r1 = Math.min(rows - 1, Math.floor((centerY + reachY) / cellH));
+        const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1) : 1);
+        const byArea = s.kind === "rect" || s.kind === "bar";
+        for (let r = r0; r <= r1; r++) {
+          const fy = byArea ? Math.max(0, Math.min((r + 1) * cellH, centerY + halfY) - Math.max(r * cellH, centerY - halfY)) / cellH : 1;
+          if (fy <= 0) continue;
+          for (let c = c0; c <= c1; c++) {
+            const dx = (c + 0.5) * cellW - centerX;
+            const dy = (r + 0.5) * cellH - centerY;
+            if (circular) {
+              const d = Math.sqrt(dx * dx + dy * dy);
+              const reach = glow ? reachX : halfX;
+              if (d > reach + Math.min(cellW, cellH) / 2) continue;
+              if (s.kind === "ring") {
+                const strokeW = (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale;
+                if (d < halfX - strokeW) continue;
+              }
+              let wgt;
+              if (glow) {
+                const core = halfX;
+                if (d <= core) wgt = 1;
+                else {
+                  const f = Math.max(0, 1 - (d - core) / Math.max(reachX - core, 1e-6));
+                  wgt = f * f;
+                }
+              } else {
+                wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
+              }
+              compose(r * cols + c, lum, a * wgt * shapeWeight, layer.blend);
+            } else if (byArea) {
+              const fx = Math.max(0, Math.min((c + 1) * cellW, centerX + halfX) - Math.max(c * cellW, centerX - halfX)) / cellW;
+              if (fx > 0) compose(r * cols + c, lum, a * shapeWeight * fx * fy, layer.blend);
+            } else {
+              compose(r * cols + c, lum, a * inkWeight * shapeWeight, layer.blend);
+            }
+          }
         }
       }
-      if (ls.isolatedNodes !== null && ls.count > 0 && ls.isolatedNodes / ls.count > 0.5) {
-        warnings.push(`${label}: ${ls.isolatedNodes}/${ls.count} nodes isolated \u2014 graph is disconnected`);
+      if (layer.links) {
+        const positions = entities.map((e) => posOf(scene, e, tPass));
+        const maxDistPx = layer.links.maxDist * scale;
+        const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
+        const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false && motionWraps, w, h);
+        const la = Math.min(1, (layer.links.alpha ?? 0.6) * lifeA);
+        const lum = layer.links.color ? hexLuma(layer.links.color) : 0.7;
+        const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+        const wgt = Math.min(1, (layer.links.width ?? defaultWidth) * scale / cellH) * la * alphaScale;
+        for (const edge of edges) {
+          const pi = positions[edge.i];
+          const pj = positions[edge.j];
+          const steps = Math.max(1, Math.ceil(edge.dist / Math.min(cellW, cellH)));
+          for (let i = 0; i <= steps; i++) {
+            const k = i / steps;
+            const c = Math.floor((pi.x + (pj.x - pi.x) * k) / cellW);
+            const r = Math.floor((pi.y + (pj.y - pi.y) * k) / cellH);
+            if (c < 0 || c >= cols || r < 0 || r >= rows) continue;
+            compose(r * cols + c, lum, wgt, layer.blend);
+          }
+        }
       }
     }
-    return { t, viewport: { w, h }, layers: layerSnapshots, warnings };
-  });
-  return {
-    spec: { id: spec.id, label: spec.label, units: spec.units ?? "px", ...spec.finish ? { finish: spec.finish } : {} },
-    snapshots
   };
-}
-
-// src/perceive.ts
-import { createRng as createRng4 } from "@idle-screens/core";
-var GLOW_SPREAD = 2.4;
-var LINE_SALIENCE = 3.5;
-var GHOST_TAPS = 12;
-var POLYGON_OUTLINE_CELLS = 3;
-var POLYGON_SCANLINES = 4;
-function buildScene(spec, opts) {
-  const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
-  const seed = normalizeSeed(opts.seed ?? spec.seed ?? 42);
-  const scale = spec.units === "px" ? 1 : Math.min(w, h);
-  const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
-  let countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
-  if (countScale > 1) {
-    const rawTotal = spec.layers.reduce((s, l) => s + Math.round(l.count * countScale), 0);
-    if (rawTotal > LIMITS.maxTotal) countScale *= LIMITS.maxTotal / rawTotal;
-  }
-  const rng = createRng4(seed);
-  const layers = spec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, w, h, scale, countScale) }));
-  const byKey = /* @__PURE__ */ new Map();
-  for (const { layer, entities } of layers) if (layer.key) byKey.set(layer.key, entities);
-  let transforms = null;
-  for (const { layer, entities } of layers) {
-    const map = paintMap(spec, layer, w, h, scale);
-    if (!map) continue;
-    transforms ??= /* @__PURE__ */ new Map();
-    for (const e of entities) transforms.set(e, map);
+  const ghost = spec.ghosting ?? 0;
+  if (ghost > 0) {
+    const dt = 1e3 / 60;
+    const windowFrames = Math.min(Math.ceil(Math.log(1 / 255) / Math.log(ghost)), LIMITS.maxGhostReplayFrames);
+    const taps = Math.min(GHOST_TAPS, windowFrames);
+    const spacing = windowFrames / taps;
+    for (let i = taps; i >= 1; i--) {
+      const tPass = t - i * spacing * dt;
+      if (tPass < 0) continue;
+      const bracketWeight = Math.pow(ghost, (i - 1) * spacing + 1) * (1 - Math.pow(ghost, spacing)) / (1 - ghost);
+      splatPass(tPass, Math.min(1, bracketWeight));
+    }
   }
-  return { w, h, scale, seed, layers, byKey, transforms };
+  splatPass(t, 1);
+  return finishGrid(cols, rows, cells, bgRow, bgCells);
 }
-function posOf(scene, e, t) {
-  const p = positionAt(e, t, scene.w, scene.h);
-  if (e.orbitParent) {
-    const parent = scene.byKey.get(e.orbitParent)?.[0];
-    if (parent) {
-      const pp = positionAt(parent, t, scene.w, scene.h);
-      p.x += pp.x;
-      p.y += pp.y;
+function finishGrid(cols, rows, cells, bgRow, bgCells) {
+  let sum = 0;
+  let covered = 0;
+  let devSum = 0;
+  let cxAcc = 0;
+  let cyAcc = 0;
+  const rowProfile = new Array(rows).fill(0);
+  const colProfile = new Array(cols).fill(0);
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const v = cells[r * cols + c];
+      sum += v;
+      const dev = Math.abs(v - (bgCells ? bgCells[r * cols + c] : bgRow[r]));
+      if (dev > 0.03) covered++;
+      devSum += dev;
+      cxAcc += dev * (c + 0.5);
+      cyAcc += dev * (r + 0.5);
+      rowProfile[r] += dev;
+      colProfile[c] += dev;
     }
   }
-  const map = scene.transforms?.get(e);
-  return map ? map(p) : p;
-}
-function textBox(s, e, p) {
-  const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
-  const fh = m ? Number(m[1]) : e.size;
-  const str = s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
-  const fw = Math.max(fh, 0.62 * fh * Math.min(str.length, 48));
-  const align = s.align ?? "center";
-  const baseline = s.baseline ?? "middle";
+  for (let r = 0; r < rows; r++) rowProfile[r] = rowProfile[r] / cols;
+  for (let c = 0; c < cols; c++) colProfile[c] = colProfile[c] / rows;
   return {
-    cx: align === "left" ? p.x + fw / 2 : align === "right" ? p.x - fw / 2 : p.x,
-    cy: baseline === "top" ? p.y + fh * 0.6 : baseline === "bottom" ? p.y - fh * 0.6 : p.y,
-    halfX: fw / 2,
-    halfY: fh * 0.6
+    cols,
+    rows,
+    cells,
+    background: bgRow,
+    ...bgCells ? { backgroundCells: bgCells } : {},
+    meanLuminance: sum / (cols * rows),
+    coverage: covered / (cols * rows),
+    centroid: devSum > 1e-6 ? { x: cxAcc / devSum / cols, y: cyAcc / devSum / rows } : null,
+    rowProfile,
+    colProfile
   };
 }
-function textBlockBox(s, _e, p, w, h) {
-  const unitScale = Math.min(w, h);
-  const fsPx = s.fontSize * unitScale;
-  const lh = (s.lineHeight ?? 1.4) * fsPx;
-  const maxWPx = s.maxWidth * unitScale;
-  const maxWEm = maxWPx / fsPx;
-  const lines = breakTextBlock(s.text, maxWEm, textMetricsClassFor(s.font));
-  const totalH = lines.length * lh;
-  const maxLineW = lines.reduce((m, l) => Math.max(m, l.widthEm), 0) * fsPx;
-  const align = s.align ?? "left";
-  const cx = align === "center" ? p.x + maxWPx / 2 : align === "right" ? p.x + maxWPx - maxLineW / 2 : p.x + maxLineW / 2;
-  const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
-  return {
-    cx: cx + dx,
-    cy: p.y + totalH / 2 + dy,
-    halfX: maxLineW / 2,
-    halfY: totalH / 2
-  };
+var DITHER = [
+  [0.5 / 8, 4.5 / 8],
+  [2.5 / 8, 6.5 / 8],
+  [1.5 / 8, 5.5 / 8],
+  [3.5 / 8, 7.5 / 8]
+];
+var DOT_BIT = [
+  [1, 8],
+  [2, 16],
+  [4, 32],
+  [64, 128]
+];
+function autoExpose(grid) {
+  const sorted = [...grid.cells].sort((a, b) => a - b);
+  const lo = sorted[0];
+  const hi = Math.max(sorted[Math.floor(sorted.length * 0.98)], lo + 0.08);
+  return (v) => Math.pow(Math.max(0, Math.min(1, (v - lo) / (hi - lo))), 0.8);
 }
-function textBlockRevealFraction(s, w, h, t) {
-  if (!s.reveal) return 1;
-  const unitScale = Math.min(w, h);
-  const maxWEm = s.maxWidth * unitScale / (s.fontSize * unitScale);
-  const lines = breakTextBlock(s.text, maxWEm, textMetricsClassFor(s.font));
-  const rs = revealState(lines, s.reveal, t);
-  if (rs.glyphAlphas) {
-    let sum = 0;
-    let n = 0;
-    for (const line of rs.glyphAlphas) for (const a of line) {
-      sum += a;
-      n++;
+function renderBrailleMap(grid) {
+  const expose = autoExpose(grid);
+  const outRows = [];
+  for (let br = 0; br < Math.floor(grid.rows / 4); br++) {
+    let line = "";
+    for (let bc = 0; bc < Math.floor(grid.cols / 2); bc++) {
+      let bits = 0;
+      for (let dr = 0; dr < 4; dr++) {
+        for (let dc = 0; dc < 2; dc++) {
+          const v = expose(grid.cells[(br * 4 + dr) * grid.cols + (bc * 2 + dc)]);
+          if (v > DITHER[dr][dc]) bits |= DOT_BIT[dr][dc];
+        }
+      }
+      line += String.fromCharCode(10240 + bits);
     }
-    return n > 0 ? sum / n : 1;
+    outRows.push(line);
   }
-  return rs.progress;
+  return outRows.join("\n");
 }
-function polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1) {
-  const nc = c1 - c0 + 1;
-  const cov = new Float64Array(nc * (r1 - r0 + 1));
-  const xMin = c0 * cellW;
-  const xMax = (c1 + 1) * cellW;
-  const share = 1 / POLYGON_SCANLINES;
-  const hits = [];
-  const addSpan = (row, xa, xb) => {
-    const a = Math.max(xMin, xa);
-    const b = Math.min(xMax, xb);
-    if (!(b > a)) return;
-    const first = Math.max(c0, Math.floor(a / cellW));
-    const last = Math.min(c1, Math.floor(b / cellW));
-    for (let c = first; c <= last; c++) {
-      const len = Math.min(b, (c + 1) * cellW) - Math.max(a, c * cellW);
-      if (len > 0) cov[row * nc + (c - c0)] += len / cellW * share;
-    }
-  };
-  for (let r = r0; r <= r1; r++) {
-    for (let k = 0; k < POLYGON_SCANLINES; k++) {
-      const y = (r + (k + 0.5) / POLYGON_SCANLINES) * cellH;
-      hits.length = 0;
-      for (let i = 0; i < pts.length; i++) {
-        const p = pts[i];
-        const q = pts[(i + 1) % pts.length];
-        const down = p.y <= y && q.y > y;
-        if (!down && !(q.y <= y && p.y > y)) continue;
-        hits.push({ x: p.x + (y - p.y) / (q.y - p.y) * (q.x - p.x), dir: down ? 1 : -1 });
-      }
-      if (hits.length < 2) continue;
-      hits.sort((m, n) => m.x - n.x);
-      let wind = 0;
-      let start = 0;
-      for (const hit of hits) {
-        const before = wind;
-        wind += hit.dir;
-        if (before === 0 && wind !== 0) start = hit.x;
-        else if (before !== 0 && wind === 0) addSpan(r - r0, start, hit.x);
-      }
+var DENSITY_RAMP = " .:-=+*#%@";
+function renderDensityMap(grid) {
+  const expose = autoExpose(grid);
+  const ramp = DENSITY_RAMP;
+  const lines = [];
+  for (let r = 0; r < grid.rows; r++) {
+    let line = "";
+    for (let c = 0; c < grid.cols; c++) {
+      const v = expose(grid.cells[r * grid.cols + c]);
+      line += ramp[Math.min(ramp.length - 1, Math.floor(v * ramp.length))];
     }
+    lines.push(line);
   }
-  return cov;
+  return lines.join("\n");
 }
-function distanceToOutline(pts, x, y) {
-  let best = Infinity;
-  for (let i = 0; i < pts.length; i++) {
-    const p = pts[i];
-    const q = pts[(i + 1) % pts.length];
-    const ex = q.x - p.x;
-    const ey = q.y - p.y;
-    const len2 = ex * ex + ey * ey;
-    const u = len2 > 0 ? Math.max(0, Math.min(1, ((x - p.x) * ex + (y - p.y) * ey) / len2)) : 0;
-    const dx = x - (p.x + ex * u);
-    const dy = y - (p.y + ey * u);
-    best = Math.min(best, dx * dx + dy * dy);
-  }
-  return Math.sqrt(best);
+function textSprites(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
+  const scene = buildScene(spec, opts);
+  const t = opts.t ?? 5e3;
+  const out = [];
+  scene.layers.forEach(({ layer, entities }, layerIndex) => {
+    if (layer.sprite.kind === "textBlock") {
+      const s2 = layer.sprite;
+      const unitScale = Math.min(scene.w, scene.h);
+      const sizePx2 = s2.fontSize * unitScale;
+      const info = { layerIndex, key: layer.key, strings: [s2.text], count: entities.length, sizePx: Math.round(sizePx2) };
+      if (s2.reveal) info.revealed = Math.round(textBlockRevealFraction(s2, scene.w, scene.h, t) * 100) / 100;
+      out.push(info);
+      return;
+    }
+    if (layer.sprite.kind !== "text") return;
+    const s = layer.sprite;
+    const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
+    const sizePx = m ? Number(m[1]) : entities[0] ? sizeAt(entities[0], t) : 0;
+    out.push({ layerIndex, key: layer.key, strings: [...s.strings], count: entities.length, sizePx: Math.round(sizePx) });
+  });
+  return out;
 }
-function rotatedBoxCoverage(cx, cy, hx, hy, rot, x0, y0, x1, y1) {
-  const cr = Math.cos(rot), sr = Math.sin(rot);
-  let poly = [[-hx, -hy], [hx, -hy], [hx, hy], [-hx, hy]].map(([x, y]) => [cx + x * cr - y * sr, cy + x * sr + y * cr]);
-  const clip = (inside, cut) => {
-    const out = [];
-    for (let i = 0; i < poly.length; i++) {
-      const a = poly[i], b = poly[(i + 1) % poly.length];
-      if (inside(a)) {
-        out.push(a);
-        if (!inside(b)) out.push(cut(a, b));
-      } else if (inside(b)) out.push(cut(a, b));
-    }
-    poly = out;
-  };
-  const atX = (x) => (a, b) => [x, a[1] + (x - a[0]) / (b[0] - a[0]) * (b[1] - a[1])];
-  const atY = (y) => (a, b) => [a[0] + (y - a[1]) / (b[1] - a[1]) * (b[0] - a[0]), y];
-  clip((p) => p[0] >= x0, atX(x0));
-  if (!poly.length) return 0;
-  clip((p) => p[0] <= x1, atX(x1));
-  if (!poly.length) return 0;
-  clip((p) => p[1] >= y0, atY(y0));
-  if (!poly.length) return 0;
-  clip((p) => p[1] <= y1, atY(y1));
-  if (!poly.length) return 0;
-  let area = 0;
-  for (let i = 0; i < poly.length; i++) {
-    const a = poly[i], b = poly[(i + 1) % poly.length];
-    area += a[0] * b[1] - b[0] * a[1];
-  }
-  return Math.abs(area) / 2 / ((x1 - x0) * (y1 - y0));
+function dominanceRanking(spec, opts = {}) {
+  return rankDominance(rawDominance(spec, opts));
 }
-function luminanceGrid(spec, opts = {}) {
+function rankDominance(raw) {
+  const total = raw.reduce((s, r) => s + r.weight, 0) || 1;
+  return raw.slice().sort((a, b) => b.weight - a.weight).map((r, i) => ({
+    rank: i + 1,
+    layerIndex: r.layerIndex,
+    key: r.key,
+    share: r.weight / total,
+    entityCount: r.entityCount,
+    meanLuma: r.meanLuma,
+    factors: r.factors
+  }));
+}
+function rawDominance(spec, opts = {}) {
   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 { w, h, scale } = scene;
-  const cellW = w / cols;
-  const cellH = h / rows;
-  const bg = spec.background;
-  const bgRow = new Array(rows).fill(0);
-  let bgCells;
-  if (!bg || bg.type === "solid") {
-    bgRow.fill(hexLuma(bg?.color ?? "#05050a"));
-  } else if (bg.type === "field") {
-    bgCells = new Array(cols * rows);
-    const short = Math.max(1, Math.min(w, h));
-    const seed = scene.seed;
-    const ft = fieldSampleTime(bg, t);
-    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));
-        bgCells[r * cols + c] = lum;
-        rowSum += lum;
-      }
-      bgRow[r] = rowSum / cols;
-    }
-  } else {
-    const stops = [...bg.stops].sort((a, b) => a.at - b.at);
-    for (let r = 0; r < rows; r++) {
-      const y = (r + 0.5) / rows;
-      let lum;
-      if (y <= stops[0].at) lum = hexLuma(stops[0].color);
-      else if (y >= stops[stops.length - 1].at) lum = hexLuma(stops[stops.length - 1].color);
-      else {
-        let i = 0;
-        while (i < stops.length - 1 && stops[i + 1].at < y) i++;
-        const a = stops[i];
-        const b = stops[i + 1];
-        const k = b.at === a.at ? 0 : (y - a.at) / (b.at - a.at);
-        lum = hexLuma(a.color) + (hexLuma(b.color) - hexLuma(a.color)) * k;
-      }
-      bgRow[r] = lum;
-    }
-    if (bg.band) {
-      const bandPx = bg.band.height * (spec.units === "px" ? 1 : Math.min(w, h));
-      const fromRow = Math.max(0, Math.floor((h - bandPx) / cellH));
-      for (let r = fromRow; r < rows; r++) bgRow[r] = hexLuma(bg.band.color);
-    }
+  const bgMean = backgroundLuma(spec);
+  const ghost = spec.ghosting ?? 0;
+  let ghostWindowMs = 0;
+  let ghostMeanW = 0;
+  if (ghost > 0) {
+    const dt = 1e3 / 60;
+    const frames = Math.min(Math.ceil(Math.log(1 / 255) / Math.log(ghost)), LIMITS.maxGhostReplayFrames);
+    ghostWindowMs = frames * dt;
+    ghostMeanW = ghost * (1 - Math.pow(ghost, frames)) / (1 - ghost) / frames;
   }
-  const cells = new Array(cols * rows);
-  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells[r * cols + c] = bgCells ? bgCells[r * cols + c] : bgRow[r];
-  const compose = (idx, lum, a, blend) => {
-    const cur = cells[idx];
-    if (blend === "lighter" || blend === "screen") cells[idx] = Math.min(1, cur + lum * a);
-    else if (blend === "multiply") cells[idx] = cur * (1 - a * (1 - lum));
-    else cells[idx] = cur * (1 - a) + lum * a;
+  const sweptDistance = (e, spanMs) => {
+    const span = Math.min(spanMs, t);
+    if (span <= 0) return 0;
+    const p0 = posOf(scene, e, t - span);
+    const p1 = posOf(scene, e, t);
+    const dx = p1.x - p0.x;
+    const dy = p1.y - p0.y;
+    if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) return 0;
+    return Math.sqrt(dx * dx + dy * dy);
   };
-  const splatTrail = (layer, e, tPass, lifeA, alphaScale) => {
-    const trail = layer.trail;
-    if (!trail) return;
-    const fade = trail.fade ?? 1;
-    const n = Math.min(Math.ceil(trail.length / 50), LIMITS.maxTrailSamples);
-    const headAlpha = alphaAt(e, tPass) * lifeA;
-    const headSize = sizeAt(e, tPass);
-    const lum = spriteLuma(layer, e);
-    const soft = layer.sprite.kind === "circle" && !!layer.sprite.soft;
-    const wrapOn = layer.wrap !== false;
-    const head = posOf(scene, e, tPass);
-    let prevX = head.x;
-    let prevY = head.y;
-    for (let s = 1; s <= n; s++) {
-      const k = s / n;
-      const pastT = tPass - k * trail.length;
-      if (pastT < 0) break;
-      const pos = posOf(scene, e, pastT);
-      if (wrapOn && (Math.abs(pos.x - prevX) > w / 2 || Math.abs(pos.y - prevY) > h / 2)) break;
-      prevX = pos.x;
-      prevY = pos.y;
-      const a = headAlpha * (1 - k * fade) * alphaScale;
-      if (a <= 4e-3) break;
-      const rad = headSize / 2 * (1 - k * 0.7);
-      if (rad < 0.2) break;
-      const c0 = Math.max(0, Math.floor((pos.x - rad) / cellW));
-      const c1 = Math.min(cols - 1, Math.floor((pos.x + rad) / cellW));
-      const r0 = Math.max(0, Math.floor((pos.y - rad) / cellH));
-      const r1 = Math.min(rows - 1, Math.floor((pos.y + rad) / cellH));
-      for (let r = r0; r <= r1; r++) {
-        for (let c = c0; c <= c1; c++) {
-          const dx = (c + 0.5) * cellW - pos.x;
-          const dy = (r + 0.5) * cellH - pos.y;
-          const d = Math.sqrt(dx * dx + dy * dy);
-          if (d > rad + Math.min(cellW, cellH) / 2) continue;
-          const wgt = soft ? Math.max(0.1, 1 - d / Math.max(rad, 1e-6)) : 1;
-          compose(r * cols + c, lum, Math.min(1, a * wgt), layer.blend);
-        }
+  const raw = scene.layers.map(({ layer, entities }, layerIndex) => {
+    const lifeA = layer.opacity === void 0 && layer.group === void 0 ? lifeAlphaAt(layer.life, t) : lifeAlphaAt(layer.life, t) * paintOpacity(spec, layer);
+    const painted = layer.transform !== void 0 || layer.group !== void 0;
+    const areaScale = painted ? paintSize(spec, layer) ** 2 : 1;
+    let area = 0;
+    let lumAcc = 0;
+    for (const e of entities) {
+      const a = alphaAt(e, t) * lifeA;
+      const sz = sizeAt(e, t);
+      const s = layer.sprite;
+      let entArea;
+      if (s.kind === "circle") entArea = Math.PI * (sz / 2) * (sz / 2);
+      else if (s.kind === "ring") entArea = Math.PI * sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale) * LINE_SALIENCE;
+      else if (s.kind === "streak") entArea = sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale) * LINE_SALIENCE;
+      else if (s.kind === "rect") {
+        const h2 = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz;
+        const f = s.feather ? (1 - s.feather / 2) * (1 - s.feather / 2) : 1;
+        entArea = sz * h2 * f;
+      } else if (s.kind === "polygon") entArea = polygonArea(polygonPoints(s, sz / 2));
+      else if (s.kind === "bar") {
+        const th = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz * 0.2;
+        entArea = sz * barFraction(s, e.barIndex ?? 0) * th;
+      } else if (s.kind === "stroke") {
+        const meanTaper = s.taper ? 0.64 : 1;
+        entArea = pathLength(strokeSamples(s, sz / 2)) * strokeWidthPx(s, scale) * meanTaper * LINE_SALIENCE;
+      } else if (s.kind === "text") {
+        const box = textBox(s, e, { x: 0, y: 0 });
+        entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
+      } else if (s.kind === "textBlock") {
+        const box = textBlockBox(s, e, { x: 0, y: 0 }, w, h);
+        entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1);
+      } else entArea = sz * sz * 0.55;
+      area += painted ? entArea * areaScale * a : entArea * a;
+      if (layer.trail) {
+        const fade = layer.trail.fade ?? 1;
+        const span = sweptDistance(e, layer.trail.length);
+        area += span * sz * 0.65 * Math.max(0, 1 - fade / 2) * a;
       }
+      if (ghost > 0) {
+        area += sweptDistance(e, ghostWindowMs) * sz * ghostMeanW * a;
+      }
+      lumAcc += spriteLuma(layer, e);
     }
-  };
-  const splatPolygonOutline = (layer, s, e, p, sz, a, lum, tPass) => {
-    const radius = sz / 2;
-    const rot = rotationAt(e, tPass);
-    const cr = Math.cos(rot);
-    const sr = Math.sin(rot);
-    const pts = polygonPoints(s, radius).map((q) => ({ x: p.x + q.x * cr - q.y * sr, y: p.y + q.x * sr + q.y * cr }));
-    const additive = layer.blend === "lighter" || layer.blend === "screen";
-    const glow = !!s.soft && additive;
-    let band = 0;
-    if (glow) {
-      const perimeter = pts.reduce((acc, q, i) => {
-        const n = pts[(i + 1) % pts.length];
-        return acc + Math.hypot(n.x - q.x, n.y - q.y);
-      }, 0);
-      band = perimeter > 0 ? (GLOW_SPREAD - 1) * (2 * polygonArea(pts) / perimeter) : 0;
-    }
-    let minX = Infinity;
-    let maxX = -Infinity;
-    let minY = Infinity;
-    let maxY = -Infinity;
-    for (const q of pts) {
-      minX = Math.min(minX, q.x);
-      maxX = Math.max(maxX, q.x);
-      minY = Math.min(minY, q.y);
-      maxY = Math.max(maxY, q.y);
+    if (layer.links && entities.length > 1) {
+      const positions = entities.map((e) => posOf(scene, e, t));
+      const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
+      const edges = linkEdges(layer.links, positions, layer.links.maxDist * scale, layer.wrap !== false && motionWraps, w, h);
+      const la = (layer.links.alpha ?? 0.6) * lifeA;
+      const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+      const lw = (layer.links.width ?? defaultWidth) * scale;
+      for (const edge of edges) area += edge.dist * lw * la * LINE_SALIENCE;
     }
-    const c0 = Math.max(0, Math.floor((minX - band) / cellW));
-    const c1 = Math.min(cols - 1, Math.floor((maxX + band) / cellW));
-    const r0 = Math.max(0, Math.floor((minY - band) / cellH));
-    const r1 = Math.min(rows - 1, Math.floor((maxY + band) / cellH));
-    if (c0 > c1 || r0 > r1) return;
-    const cov = polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1);
-    const nc = c1 - c0 + 1;
-    for (let r = r0; r <= r1; r++) {
-      for (let c = c0; c <= c1; c++) {
-        const f = cov[(r - r0) * nc + (c - c0)];
-        const x = (c + 0.5) * cellW;
-        const y = (r + 0.5) * cellH;
-        let wgt;
-        if (glow) {
-          const outX = Math.max(0, minX - x, x - maxX);
-          const outY = Math.max(0, minY - y, y - maxY);
-          if (f >= 1) wgt = 1;
-          else if (outX * outX + outY * outY >= band * band) wgt = f;
-          else {
-            const k = band > 0 ? Math.max(0, 1 - distanceToOutline(pts, x, y) / band) : 0;
-            wgt = f + (1 - f) * k * k;
-          }
-        } else if (s.soft) {
-          wgt = f * Math.max(0.1, 1 - Math.hypot(x - p.x, y - p.y) / Math.max(radius, 1e-6));
-        } else {
-          wgt = f;
-        }
-        if (wgt > 0) compose(r * cols + c, lum, a * Math.min(1, wgt), layer.blend);
+    const meanLuma = entities.length ? lumAcc / entities.length : 0;
+    const contrast = Math.abs(meanLuma - bgMean) + 0.1;
+    const blendBoost = layer.blend === "lighter" || layer.blend === "screen" ? 1.3 : layer.blend === "multiply" ? 1.1 : 1;
+    const motionBoost = layer.motion.type === "static" ? 1 : 1.2;
+    const weight = area / (w * h) * contrast * blendBoost * motionBoost;
+    return { layerIndex, key: layer.key, weight, entityCount: entities.length, meanLuma, factors: { area: area / (w * h), contrast, blendBoost, motionBoost } };
+  });
+  return raw;
+}
+function layerCohesion(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
+  const scene = buildScene(spec, opts);
+  return cohesionOf(scene.layers, opts.t ?? 5e3, scene.w, scene.h);
+}
+var MOVING_FLOOR = 5e-4;
+function motionStats(spec, opts = {}) {
+  const t = opts.t ?? 5e3;
+  const dt = opts.dt ?? 500;
+  const scene0 = buildScene(resolveTimelineAt(spec, t), opts);
+  const scene1 = spec.timeline ? buildScene(resolveTimelineAt(spec, t + dt), opts) : scene0;
+  const { w, h } = scene0;
+  const unit = Math.min(w, h);
+  return scene0.layers.map(({ layer, entities }, layerIndex) => {
+    const entities1 = scene1.layers[layerIndex]?.entities ?? entities;
+    let acc = 0;
+    let max = 0;
+    let n = 0;
+    let ux = 0;
+    let uy = 0;
+    let moversN = 0;
+    entities.forEach((e, i) => {
+      const p0 = posOf(scene0, e, t);
+      const p1 = posOf(scene1, entities1[i] ?? e, t + dt);
+      const dx = p1.x - p0.x;
+      const dy = p1.y - p0.y;
+      if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) return;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      const speed = dist / dt * 1e3;
+      acc += speed;
+      max = Math.max(max, speed);
+      n++;
+      if (dist > 0) {
+        ux += dx / dist;
+        uy += dy / dist;
+        moversN++;
       }
+    });
+    const meanSpeed = n ? acc / n : 0;
+    const meanSpeedVp = meanSpeed / unit;
+    const maxSpeedVp = max / unit;
+    const moving = meanSpeedVp > MOVING_FLOOR;
+    let heading = null;
+    let headingSpread = null;
+    if (moving && moversN > 0) {
+      const mx = ux / moversN;
+      const my = uy / moversN;
+      const mag = Math.sqrt(mx * mx + my * my);
+      headingSpread = 1 - mag;
+      heading = mag > 0.05 ? (Math.atan2(my, mx) * 180 / Math.PI + 360) % 360 : null;
+    }
+    return { layerIndex, key: layer.key, meanSpeed, maxSpeed: max, meanSpeedVp, maxSpeedVp, moving, heading, headingSpread };
+  });
+}
+function rgbToHsl(c) {
+  const max = Math.max(c.r, c.g, c.b);
+  const min = Math.min(c.r, c.g, c.b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d < 1e-6) return { h: null, s: 0, l };
+  const sat = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === c.r) h = ((c.g - c.b) / d + (c.g < c.b ? 6 : 0)) * 60;
+  else if (max === c.g) h = ((c.b - c.r) / d + 2) * 60;
+  else h = ((c.r - c.g) / d + 4) * 60;
+  return { h: sat < 0.05 ? null : h, s: sat, l };
+}
+function toHex(c) {
+  const q = (v) => Math.round(Math.max(0, Math.min(1, v)) * 255).toString(16).padStart(2, "0");
+  return `#${q(c.r)}${q(c.g)}${q(c.b)}`;
+}
+function describeColour(c) {
+  const hsl = rgbToHsl(c);
+  return { hue: hsl.h === null ? null : Math.round(hsl.h), saturation: +hsl.s.toFixed(3), warmth: +(c.r - c.b).toFixed(3), hex: toHex(c) };
+}
+function sceneColour(spec, opts = {}) {
+  const t = opts.t ?? 5e3;
+  spec = resolveTimelineAt(spec, t);
+  const scene = buildScene(spec, opts);
+  let wr = 0;
+  let wg = 0;
+  let wb = 0;
+  let wsum = 0;
+  for (const { layer, entities } of scene.layers) {
+    const lifeA = lifeAlphaAt(layer.life, t) * (layer.opacity === void 0 && layer.group === void 0 ? 1 : paintOpacity(spec, layer));
+    for (const e of entities) {
+      const hex = spriteHex(layer, e);
+      if (hex === null) continue;
+      const sz = sizeAt(e, t);
+      const weight = alphaAt(e, t) * lifeA * (layer.sprite.kind === "circle" ? Math.PI * (sz / 2) * (sz / 2) : sz * sz);
+      if (weight <= 0) continue;
+      const c = hexRgb(hex);
+      wr += c.r * weight;
+      wg += c.g * weight;
+      wb += c.b * weight;
+      wsum += weight;
     }
-  };
-  const splatPass = (tPass, alphaScale) => {
-    for (const { layer, entities } of scene.layers) {
-      const lifeA = layer.opacity === void 0 && layer.group === void 0 ? lifeAlphaAt(layer.life, tPass) : lifeAlphaAt(layer.life, tPass) * paintOpacity(spec, layer);
-      if (lifeA <= 0) continue;
-      for (const e of entities) {
-        splatTrail(layer, e, tPass, lifeA, alphaScale);
-        const a = Math.min(1, alphaAt(e, tPass) * lifeA) * alphaScale;
-        if (a <= 4e-3) continue;
-        const lum = spriteLuma(layer, e);
-        const p = posOf(scene, e, tPass);
-        const sz = layer.transform || layer.group !== void 0 ? sizeAt(e, tPass) * paintSize(spec, layer) : sizeAt(e, tPass);
-        const s = layer.sprite;
-        if (s.kind === "polygon" && sz >= POLYGON_OUTLINE_CELLS * Math.min(cellW, cellH)) {
-          splatPolygonOutline(layer, s, e, p, sz, a, lum, tPass);
-          continue;
-        }
-        if (s.kind === "stroke") {
-          const pts = strokeSamples(s, sz / 2);
-          let angle = rotationAt(e, tPass);
-          if (s.orient) angle += headingAt(e, tPass, w, h) ?? 0;
-          const ca = Math.cos(angle);
-          const sa = Math.sin(angle);
-          const lw = strokeWidthPx(s, scale);
-          const stampAt = (q, u) => {
-            const x = p.x + q.x * ca - q.y * sa;
-            const y = p.y + q.x * sa + q.y * ca;
-            const c = Math.floor(x / cellW);
-            const r = Math.floor(y / cellH);
-            if (c < 0 || c >= cols || r < 0 || r >= rows) return;
-            const taper = s.taper ? strokeTaper(u) : 1;
-            compose(r * cols + c, lum, a * Math.min(1, lw * taper / cellH), layer.blend);
-          };
-          const step = Math.min(cellW, cellH) / 2;
-          stampAt(pts[0], 0);
-          for (let i = 1; i < pts.length; i++) {
-            const q0 = pts[i - 1];
-            const q1 = pts[i];
-            const segLen = Math.hypot(q1.x - q0.x, q1.y - q0.y);
-            const sub = Math.max(1, Math.ceil(segLen / step));
-            for (let k = 1; k <= sub; k++) {
-              const f = k / sub;
-              stampAt({ x: q0.x + (q1.x - q0.x) * f, y: q0.y + (q1.y - q0.y) * f }, (i - 1 + f) / (pts.length - 1));
-            }
-          }
-          continue;
-        }
-        if (s.kind === "streak") {
-          const heading = (headingAt(e, tPass, w, h) ?? 0) + rotationAt(e, tPass);
-          const steps = Math.max(2, Math.ceil(sz / Math.min(cellW, cellH)));
-          const wgt = Math.min(1, (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale / cellH);
-          for (let i = 0; i <= steps; i++) {
-            const k = i / steps;
-            const x = p.x - Math.cos(heading) * sz * (1 - k);
-            const y = p.y - Math.sin(heading) * sz * (1 - k);
-            const c = Math.floor(x / cellW);
-            const r = Math.floor(y / cellH);
-            if (c < 0 || c >= cols || r < 0 || r >= rows) continue;
-            compose(r * cols + c, lum, a * k * wgt, layer.blend);
-          }
-          continue;
-        }
-        let centerX = p.x;
-        let centerY = p.y;
-        let halfX = sz / 2;
-        let halfY = s.kind === "rect" ? (e.size2 ?? sz) * (e.size > 0 ? sz / e.size : 1) / 2 : sz / 2;
-        let boxRot = 0, boxHx = 0, boxHy = 0;
-        if (s.kind === "text") {
-          const box = textBox(s, e, p);
-          centerX = box.cx;
-          centerY = box.cy;
-          halfX = box.halfX;
-          halfY = box.halfY;
-        } else if (s.kind === "textBlock") {
-          const box = textBlockBox(s, e, p, w, h);
-          centerX = box.cx;
-          centerY = box.cy;
-          halfX = box.halfX;
-          halfY = box.halfY;
-        } else if (s.kind === "bar") {
-          const len = sz * barFraction(s, e.barIndex ?? 0);
-          if (len <= 0) continue;
-          const th = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz * 0.2;
-          const box = barBox(s.direction ?? "right", len, th);
-          const rot = rotationAt(e, tPass);
-          const cr = Math.cos(rot);
-          const sr = Math.sin(rot);
-          centerX = p.x + box.cx * cr - box.cy * sr;
-          centerY = p.y + box.cx * sr + box.cy * cr;
-          boxRot = rot;
-          boxHx = box.halfX;
-          boxHy = box.halfY;
-          halfX = Math.abs(box.halfX * cr) + Math.abs(box.halfY * sr);
-          halfY = Math.abs(box.halfX * sr) + Math.abs(box.halfY * cr);
-        } else if (s.kind === "rect") {
-          const rot = rotationAt(e, tPass);
-          if (rot) {
-            boxRot = rot;
-            boxHx = halfX;
-            boxHy = halfY;
-            const cr = Math.abs(Math.cos(rot));
-            const sr = Math.abs(Math.sin(rot));
-            const hx = halfX * cr + halfY * sr;
-            halfY = halfX * sr + halfY * cr;
-            halfX = hx;
-          }
-        }
-        const circular = s.kind === "circle" || s.kind === "ring" || s.kind === "polygon";
-        const soft = (s.kind === "circle" || s.kind === "polygon") && !!s.soft;
-        const shapeWeight = s.kind === "polygon" ? polygonFill(s, sz / 2) : s.kind === "rect" && s.feather ? (1 - s.feather / 2) * (1 - s.feather / 2) : 1;
+  }
+  const bg = backgroundRgb(spec);
+  const sprites = wsum > 0 ? { r: wr / wsum, g: wg / wsum, b: wb / wsum } : bg;
+  return { ...describeColour(sprites), background: describeColour(bg) };
+}
+function hueShift(a, b) {
+  if (a === null || b === null) return null;
+  let d = b - a;
+  while (d > 180) d -= 360;
+  while (d < -180) d += 360;
+  return Math.round(d);
+}
+var REGION_NAMES = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "mid-left",
+  "center",
+  "mid-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right"
+];
+function regionMeans(grid) {
+  const out = new Array(9).fill(0);
+  const cnt = new Array(9).fill(0);
+  for (let r = 0; r < grid.rows; r++) {
+    for (let c = 0; c < grid.cols; c++) {
+      const idx = r * grid.cols + c;
+      const region = Math.min(2, Math.floor(r / grid.rows * 3)) * 3 + Math.min(2, Math.floor(c / grid.cols * 3));
+      out[region] += Math.abs(grid.cells[idx] - (grid.backgroundCells ? grid.backgroundCells[idx] : grid.background[r]));
+      cnt[region]++;
+    }
+  }
+  return out.map((v, i) => cnt[i] ? v / cnt[i] : 0);
+}
+function diffScenes(a, b, opts = {}) {
+  const t = opts.t ?? 5e3;
+  const gridA = luminanceGrid(a, opts);
+  const gridB = luminanceGrid(b, opts);
+  const regsA = regionMeans(gridA);
+  const regsB = regionMeans(gridB);
+  const domA = dominanceRanking(a, opts);
+  const domB = dominanceRanking(b, opts);
+  const nameOf = (d) => d.key ?? `layer-${d.layerIndex}`;
+  const names = /* @__PURE__ */ new Set([...domA.map(nameOf), ...domB.map(nameOf)]);
+  const dominance = [...names].map((key) => {
+    const inA = domA.find((d) => nameOf(d) === key);
+    const inB = domB.find((d) => nameOf(d) === key);
+    return {
+      key,
+      rankA: inA?.rank ?? null,
+      rankB: inB?.rank ?? null,
+      shareA: inA?.share ?? 0,
+      shareB: inB?.share ?? 0
+    };
+  }).sort((x, y) => Math.abs(y.shareB - y.shareA) - Math.abs(x.shareB - x.shareA));
+  const vp = opts.viewport ?? { width: 1920, height: 1080 };
+  const codesA = new Set(adviseSpec(a, vp).map((w) => w.code));
+  const codesB = new Set(adviseSpec(b, vp).map((w) => w.code));
+  const colA = sceneColour(a, opts);
+  const colB = sceneColour(b, opts);
+  const motA = motionStats(a, opts);
+  const motB = motionStats(b, opts);
+  const weighted = (stats, dom) => {
+    let acc = 0;
+    let n = 0;
+    for (const m of stats) {
+      const c = dom.find((d) => d.layerIndex === m.layerIndex)?.entityCount ?? 1;
+      acc += m.meanSpeedVp * c;
+      n += c;
+    }
+    return n ? acc / n : 0;
+  };
+  const motNameOf = (m) => m.key ?? `layer-${m.layerIndex}`;
+  const motionLayers = [.../* @__PURE__ */ new Set([...motA.map(motNameOf), ...motB.map(motNameOf)])].map((key) => {
+    const ma = motA.find((m) => motNameOf(m) === key);
+    const mb = motB.find((m) => motNameOf(m) === key);
+    const va = ma?.meanSpeedVp ?? 0;
+    const vb = mb?.meanSpeedVp ?? 0;
+    return { key, a: va, b: vb, delta: vb - va, headingA: ma?.heading ?? null, headingB: mb?.heading ?? null };
+  }).filter((m) => Math.abs(m.delta) > 1e-9 || m.headingA !== m.headingB).sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+  const overallA = weighted(motA, domA);
+  const overallB = weighted(motB, domB);
+  return {
+    t,
+    coverage: { a: gridA.coverage, b: gridB.coverage, delta: gridB.coverage - gridA.coverage },
+    meanLuminance: { a: gridA.meanLuminance, b: gridB.meanLuminance, delta: gridB.meanLuminance - gridA.meanLuminance },
+    balanceShift: gridA.centroid && gridB.centroid ? { dx: gridB.centroid.x - gridA.centroid.x, dy: gridB.centroid.y - gridA.centroid.y } : null,
+    regions: REGION_NAMES.map((region, i) => ({ region, a: regsA[i], b: regsB[i], delta: regsB[i] - regsA[i] })),
+    dominance,
+    colour: {
+      a: colA,
+      b: colB,
+      hueShift: hueShift(colA.hue, colB.hue),
+      saturationDelta: +(colB.saturation - colA.saturation).toFixed(3),
+      warmthDelta: +(colB.warmth - colA.warmth).toFixed(3),
+      background: {
+        hueShift: hueShift(colA.background.hue, colB.background.hue),
+        warmthDelta: +(colB.background.warmth - colA.background.warmth).toFixed(3)
+      }
+    },
+    motion: {
+      overall: { a: overallA, b: overallB, delta: overallB - overallA },
+      layers: motionLayers
+    },
+    advisories: {
+      added: [...codesB].filter((c) => !codesA.has(c)),
+      removed: [...codesA].filter((c) => !codesB.has(c))
+    }
+  };
+}
+function perceiveScene(spec, opts = {}) {
+  const timed = spec;
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
+  const grid = luminanceGrid(spec, opts);
+  return {
+    t: opts.t ?? 5e3,
+    braille: renderBrailleMap(grid),
+    density: renderDensityMap(grid),
+    coverage: grid.coverage,
+    meanLuminance: grid.meanLuminance,
+    centroid: grid.centroid,
+    rowProfile: grid.rowProfile,
+    colProfile: grid.colProfile,
+    dominance: dominanceRanking(spec, opts),
+    motion: motionStats(timed, opts),
+    form: layerCohesion(spec, opts),
+    colour: sceneColour(spec, opts),
+    text: textSprites(spec, opts),
+    advisories: adviseSpec(spec, opts.viewport ?? { width: 1920, height: 1080 }, { t: opts.t, seed: opts.seed })
+  };
+}
+var bedKey = (key, layerIndex) => `bed:${key ?? layerIndex}`;
+function perceiveSequenceFrame(seq, T, opts = {}) {
+  const { releasedBelow, ...gridOpts } = opts;
+  const r = resolveSegment(seq, T, { releasedBelow });
+  const seg = seq.segments[r.index];
+  const segment = { index: r.index, key: seg.key, localT: r.localT, ...r.held ? { held: true } : {} };
+  const segOpts = { ...gridOpts, t: r.localT, seed: gridOpts.seed ?? segmentRenderSeed(seq, r.index) };
+  if (!seq.bed) return { ...perceiveScene(seg.scene, segOpts), segment, bed: false };
+  const bedOpts = { ...gridOpts, t: T, seed: gridOpts.seed ?? bedRenderSeed(seq) };
+  const viewport = gridOpts.viewport ?? { width: 1920, height: 1080 };
+  const ink = { ...seg.scene, background: { type: "solid", color: "#000000" } };
+  delete ink.ghosting;
+  const inkOverBed = { ...ink, background: seq.bed.background ?? { type: "solid", color: "#05050a" } };
+  const bedGrid = luminanceGrid(seq.bed, bedOpts);
+  const inkGrid = luminanceGrid(ink, segOpts);
+  const cells = bedGrid.cells.map((v, i) => Math.min(1, v + inkGrid.cells[i]));
+  const grid = finishGrid(bedGrid.cols, bedGrid.rows, cells, bedGrid.background, bedGrid.backgroundCells);
+  const bedLayers = seq.bed.layers.length;
+  const dominance = rankDominance([
+    ...rawDominance(seq.bed, bedOpts).map((d) => ({ ...d, key: bedKey(d.key, d.layerIndex) })),
+    ...rawDominance(inkOverBed, segOpts).map((d) => ({ ...d, layerIndex: d.layerIndex + bedLayers }))
+  ]);
+  const shift = (x) => ({ ...x, layerIndex: x.layerIndex + bedLayers });
+  const prefix = (x) => ({ ...x, key: bedKey(x.key, x.layerIndex) });
+  return {
+    t: r.localT,
+    braille: renderBrailleMap(grid),
+    density: renderDensityMap(grid),
+    coverage: grid.coverage,
+    meanLuminance: grid.meanLuminance,
+    centroid: grid.centroid,
+    rowProfile: grid.rowProfile,
+    colProfile: grid.colProfile,
+    dominance,
+    motion: [...motionStats(seq.bed, bedOpts).map(prefix), ...motionStats(ink, segOpts).map(shift)],
+    form: [...layerCohesion(seq.bed, bedOpts).map(prefix), ...layerCohesion(ink, segOpts).map(shift)],
+    text: [...textSprites(seq.bed, bedOpts).map(prefix), ...textSprites(ink, segOpts).map(shift)],
+    // The segment's sprite mass over the bed's plate — what the screen shows
+    // in front of the bed. The bed's own sprites are a slow constant beneath.
+    colour: sceneColour(inkOverBed, segOpts),
+    advisories: [
+      ...adviseSpec(seq.bed, viewport, { t: T, seed: bedOpts.seed }).map((w) => ({ ...w, path: `bed.${w.path}` })),
+      // inkOverBed's layers are the segment's (seed: segOpts.seed) but its
+      // background is the bed's (seq.bed.background) — a field there must be
+      // sampled with the bed's own seed, or a `role: 'read'` legibility
+      // advisory checks terrain that isn't what's actually behind the ink.
+      // `?? 42`: inkOverBed.seed is the SEGMENT's raw seed field (it's `ink`
+      // spread first), so adviseSpec's own `backgroundSeed ?? seed` fallback
+      // would substitute the segment's seed, not the bed's, if bedOpts.seed
+      // were left undefined — 42 is the same default `luminanceGrid` (and
+      // every other field seed fallback) converges on.
+      ...adviseSpec(inkOverBed, viewport, { t: r.localT, seed: segOpts.seed, backgroundSeed: bedOpts.seed ?? 42 })
+    ],
+    segment,
+    bed: true
+  };
+}
+
+// src/advise.ts
+var LOW_CONTRAST_FLOOR = 0.05;
+var SPARSE_DECLARED_MAX_COVERAGE = 0.02;
+var READ_LEGIBILITY_FLOOR = 4.5;
+var READ_SAFE_AREA = 0.05;
+var ADDITIVE_INK_CEILING = 1;
+function edgeAnchored(range) {
+  if (!range) return false;
+  const [a, b] = range;
+  return (a <= 0.02 || b >= 0.98) && b - a <= 0.6;
+}
+function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
+  const hidden = hiddenLayers(spec);
+  spec = resolveTimelineAt(spec, opts.t ?? COHESION_T);
+  const warnings = [];
+  const w = viewport.width;
+  const h = viewport.height;
+  const { scale, countScale } = entityScales(spec, w, h);
+  const rng = createRng3(opts.seed ?? spec.seed ?? 42);
+  const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale, countScale));
+  const cohesion = cohesionOf(
+    spec.layers.map((layer, i) => ({ layer, entities: allEntities[i] })),
+    opts.t ?? COHESION_T,
+    w,
+    h
+  );
+  let totalEntities = 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";
+    if (isStaticText) textLayerCount++;
+    if (layer.motion.type !== "static") motionLayerCount++;
+    const coh = cohesion[li];
+    if (seamsWorthWarning(layer, coh, entities.length)) {
+      const s = layer.sprite;
+      const softEdged = (s.kind === "circle" || s.kind === "polygon") && s.soft || s.kind === "rect" && !!s.feather;
+      warnings.push({
+        path: `layers[${li}]`,
+        code: "overlap-seams",
+        message: softEdged ? `entities bury ${Math.round((coh.overlap ?? 0) * 100)}% of each other's outlines, but ${coh.seamCause}: overlaps pool into soft lumps rather than one solid silhouette (no hard edges \u2014 a cloud, smoke or haze reads well this way). If this layer is meant to be ONE solid shape, make it one flat colour at alpha 1, hard-edged, with no blend and no pulse.` : `entities bury ${Math.round((coh.overlap ?? 0) * 100)}% of each other's outlines, so this layer is drawn as one shape \u2014 but ${coh.seamCause}, so every overlap paints a visible edge and it will read as a pile of sprites instead. A layer merges into a single silhouette only when it is one flat colour at alpha 1, hard-edged, with no blend and no pulse.`
+      });
+    }
+    if (layer.trail && layer.motion.type === "static") {
+      warnings.push({
+        path: `layers[${li}].trail`,
+        code: "trail-on-static",
+        message: "trail has no effect on static entities \u2014 they have no past positions to draw"
+      });
+    }
+    if ((layer.sprite.kind === "streak" || layer.sprite.kind === "stroke" && layer.sprite.orient) && layer.motion.type === "static" && !layer.spin) {
+      warnings.push({
+        path: `layers[${li}].sprite`,
+        code: "streak-on-static",
+        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) {
+      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 === "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);
+      if (maxR * maxAlpha < 0.05) {
+        warnings.push({
+          path: `layers[${li}]`,
+          code: "invisible-layer",
+          message: `layer's max visible radius (${maxR.toFixed(1)}px \xD7 ${maxAlpha.toFixed(2)} alpha) is below perceptual floor`
+        });
+      }
+    }
+    if (entities.length > 0 && layer.sprite.kind !== "emoji") {
+      const [y0, y1] = layer.position ? [layer.position.y, layer.position.y] : layer.region?.y ?? [0, 1];
+      const plates = [y0, (y0 + y1) / 2, y1].map((y) => {
+        const rgb = backgroundRgbAt(spec, y * h, h, scale, void 0, void 0, opts.backgroundSeed ?? opts.seed, opts.t ?? COHESION_T);
+        return { rgb, luma: 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b };
+      });
+      const seps = entities.map((e) => {
+        const hex = spriteHex(layer, e);
+        if (hex === null) return Infinity;
+        const ink = { rgb: hexRgb(hex), luma: hexLuma(hex) };
+        const sep = Math.max(...plates.map((bg) => colourSeparation(layer, ink, bg)));
+        if (sep >= LOW_CONTRAST_FLOOR || layer.blend === "lighter" || layer.blend === "screen") return sep;
+        const under = groundUnder(spec, allEntities, li, hidden, positionAt(e, 0, w, h), w, h);
+        return under ? colourSeparation(layer, ink, under) : sep;
+      });
+      const best = Math.max(...seps);
+      if (best < LOW_CONTRAST_FLOOR) {
         const additive = layer.blend === "lighter" || layer.blend === "screen";
-        const glow = soft && additive;
-        const reachX = glow ? halfX * GLOW_SPREAD : halfX;
-        const reachY = glow ? halfY * GLOW_SPREAD : halfY;
-        const c0 = Math.max(0, Math.floor((centerX - reachX) / cellW));
-        const c1 = Math.min(cols - 1, Math.floor((centerX + reachX) / cellW));
-        const r0 = Math.max(0, Math.floor((centerY - reachY) / cellH));
-        const r1 = Math.min(rows - 1, Math.floor((centerY + reachY) / cellH));
-        const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1) : 1);
-        const byArea = s.kind === "rect" || s.kind === "bar";
-        for (let r = r0; r <= r1; r++) {
-          const fy = byArea ? Math.max(0, Math.min((r + 1) * cellH, centerY + halfY) - Math.max(r * cellH, centerY - halfY)) / cellH : 1;
-          if (fy <= 0) continue;
-          for (let c = c0; c <= c1; c++) {
-            const dx = (c + 0.5) * cellW - centerX;
-            const dy = (r + 0.5) * cellH - centerY;
-            if (circular) {
-              const d = Math.sqrt(dx * dx + dy * dy);
-              const reach = glow ? reachX : halfX;
-              if (d > reach + Math.min(cellW, cellH) / 2) continue;
-              if (s.kind === "ring") {
-                const strokeW = (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale;
-                if (d < halfX - strokeW) continue;
-              }
-              let wgt;
-              if (glow) {
-                const core = halfX;
-                if (d <= core) wgt = 1;
-                else {
-                  const f = Math.max(0, 1 - (d - core) / Math.max(reachX - core, 1e-6));
-                  wgt = f * f;
-                }
-              } else {
-                wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
-              }
-              compose(r * cols + c, lum, a * wgt * shapeWeight, layer.blend);
-            } else if (byArea) {
-              if (boxRot) {
-                const cov = rotatedBoxCoverage(centerX, centerY, boxHx, boxHy, boxRot, c * cellW, r * cellH, (c + 1) * cellW, (r + 1) * cellH);
-                if (cov > 0) compose(r * cols + c, lum, a * shapeWeight * cov, layer.blend);
-              } else {
-                const fx = Math.max(0, Math.min((c + 1) * cellW, centerX + halfX) - Math.max(c * cellW, centerX - halfX)) / cellW;
-                if (fx > 0) compose(r * cols + c, lum, a * shapeWeight * fx * fy, layer.blend);
-              }
-            } else {
-              compose(r * cols + c, lum, a * inkWeight * shapeWeight, layer.blend);
-            }
-          }
-        }
+        warnings.push({
+          path: `layers[${li}].sprite`,
+          code: "low-contrast-layer",
+          message: additive ? `additive layer adds almost no light (luma ${best.toFixed(3)}) \u2014 a "lighter"/"screen" layer is only as visible as it is bright` : `layer colour is within ${best.toFixed(3)} of the background, or of the solid layer under it (floor ${LOW_CONTRAST_FLOOR}) \u2014 it will read as background, not as content`
+        });
       }
-      if (layer.links) {
-        const positions = entities.map((e) => posOf(scene, e, tPass));
-        const maxDistPx = layer.links.maxDist * scale;
-        const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
-        const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false && motionWraps, w, h);
-        const la = Math.min(1, (layer.links.alpha ?? 0.6) * lifeA);
-        const lum = layer.links.color ? hexLuma(layer.links.color) : 0.7;
-        const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
-        const wgt = Math.min(1, (layer.links.width ?? defaultWidth) * scale / cellH) * la * alphaScale;
-        for (const edge of edges) {
-          const pi = positions[edge.i];
-          const pj = positions[edge.j];
-          const steps = Math.max(1, Math.ceil(edge.dist / Math.min(cellW, cellH)));
-          for (let i = 0; i <= steps; i++) {
-            const k = i / steps;
-            const c = Math.floor((pi.x + (pj.x - pi.x) * k) / cellW);
-            const r = Math.floor((pi.y + (pj.y - pi.y) * k) / cellH);
-            if (c < 0 || c >= cols || r < 0 || r >= rows) continue;
-            compose(r * cols + c, lum, wgt, layer.blend);
-          }
-        }
+    }
+  }
+  let totalCoverage = 0;
+  let additiveInk = 0;
+  for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
+    const layer = spec.layers[li];
+    const entities = allEntities[li];
+    const paintA = layer.opacity === void 0 && layer.group === void 0 ? 1 : paintOpacity(spec, layer);
+    const map = paintMap(spec, layer, w, h, scale);
+    const areaScale = map ? paintSize(spec, layer) ** 2 : 1;
+    const additive = layer.blend === "lighter" || layer.blend === "screen";
+    for (const e of entities) {
+      const r = e.size / 2;
+      let pixArea;
+      if (layer.sprite.kind === "circle") {
+        pixArea = Math.PI * r * r;
+      } else if (layer.sprite.kind === "polygon") {
+        pixArea = polygonArea(polygonPoints(layer.sprite, r));
+      } else if (layer.sprite.kind === "bar") {
+        pixArea = e.size * barFraction(layer.sprite, e.barIndex ?? 0) * (e.size2 ?? e.size * 0.2);
+      } else if (layer.sprite.kind === "textBlock") {
+        const fsPx = layer.sprite.fontSize * scale;
+        const lh = (layer.sprite.lineHeight ?? 1.4) * fsPx;
+        const maxWPx = layer.sprite.maxWidth * scale;
+        const lines = breakTextBlock(layer.sprite.text, maxWPx / fsPx, textMetricsClassFor(layer.sprite.font));
+        pixArea = maxWPx * lines.length * lh * 0.55 * (layer.sprite.opacity ?? 1);
+      } else if (layer.sprite.kind === "text") {
+        const b = textBoxAt(layer.sprite, e, positionAt(e, 0, w, h), spec, w, h);
+        pixArea = (b.x1 - b.x0) * (b.y1 - b.y0) * 0.55;
+      } else {
+        pixArea = e.size * e.size;
+      }
+      if (areaScale !== 1) pixArea *= areaScale;
+      if (pixArea > w * h) pixArea = w * h;
+      let duty = 1;
+      if (layer.emit) {
+        const [ga, gb] = layer.emit.grow ?? [1, 1];
+        const g2 = (ga * ga + ga * gb + gb * gb) / 3;
+        duty = Math.min(layer.emit.life, layer.emit.every) / layer.emit.every * 0.5 * g2;
+      }
+      const ink = paintA === 1 ? pixArea * e.alpha * duty / (w * h) : pixArea * e.alpha * duty * paintA / (w * h);
+      totalCoverage += ink;
+      if (additive) additiveInk += ink;
+    }
+    if (layer.links) {
+      const positions = entities.map((e) => positionAt(e, 0, w, h));
+      const maxDistPx = layer.links.maxDist * scale;
+      const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false, w, h);
+      const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
+      const lwPx = (layer.links.width ?? defaultWidth) * scale;
+      const la = layer.links.alpha ?? 1;
+      for (const edge of edges) totalCoverage += paintA === 1 ? edge.dist * lwPx * la / (w * h) : edge.dist * lwPx * la * paintA / (w * h);
+    }
+  }
+  const density = spec.density ?? "normal";
+  const wouldBeSparse = totalCoverage < 5e-4 && spec.layers.length > 0;
+  if (wouldBeSparse && density !== "sparse") {
+    warnings.push({
+      path: "layers",
+      code: "sparse-scene",
+      message: `alpha-weighted coverage is ${(totalCoverage * 100).toFixed(4)}% \u2014 scene will look empty on most displays`
+    });
+  }
+  if (additiveInk > ADDITIVE_INK_CEILING) {
+    warnings.push({
+      path: "layers",
+      code: "additive-saturation",
+      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") {
+    warnings.push({
+      path: "layers",
+      code: "dense-scene",
+      message: `${totalEntities} entities \u2014 scene may feel crowded and hurt performance on low-end devices`
+    });
+  }
+  if (density === "sparse" && totalCoverage > SPARSE_DECLARED_MAX_COVERAGE) {
+    warnings.push({
+      path: "density",
+      code: "density-mismatch",
+      message: `declared sparse but alpha-weighted coverage is ${(totalCoverage * 100).toFixed(2)}% \u2014 either the declaration or the scene is wrong`
+    });
+  } else if (density === "dense" && wouldBeSparse) {
+    warnings.push({
+      path: "density",
+      code: "density-mismatch",
+      message: `declared dense but alpha-weighted coverage is ${(totalCoverage * 100).toFixed(4)}% \u2014 the scene will look empty`
+    });
+  }
+  if (spec.layers.length > 0 && textLayerCount > 0 && motionLayerCount === 0) {
+    const textRatio = textLayerCount / spec.layers.length;
+    if (textRatio >= 0.8) {
+      warnings.push({
+        path: "layers",
+        code: "text-heavy",
+        message: "most layers are static text \u2014 reads as a document, not a screensaver"
+      });
+    }
+  }
+  for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
+    const layer = spec.layers[li];
+    if (!layer.links || layer.links.mode === "chain") continue;
+    const entities = allEntities[li];
+    const positions = entities.map((e) => positionAt(e, 0, w, h));
+    const maxDist = layer.links.maxDist * scale;
+    const pairs = linkPairs(positions, layer.links.k, maxDist, layer.wrap !== false, w, h);
+    const maxPossible = Math.min(entities.length * layer.links.k, entities.length * (entities.length - 1) / 2);
+    if (maxPossible > 0 && pairs.length / maxPossible < 0.1) {
+      warnings.push({
+        path: `layers[${li}].links`,
+        code: "link-starvation",
+        message: `only ${pairs.length}/${maxPossible} possible edges formed \u2014 raise count or widen links.maxDist`
+      });
+    }
+  }
+  for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
+    const layer = spec.layers[li];
+    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 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)));
+    if (maxDev / mean < 0.05) {
+      warnings.push({
+        path: `layers[${li}].motion`,
+        code: "uniform-motion",
+        message: "all entities move at nearly identical speed \u2014 widen the speed range for visual variety"
+      });
+    }
+  }
+  const composed = spec.layers.map((l, li) => ({ l, li, ents: allEntities[li] })).filter(({ li }) => !hidden?.[li]).filter(({ l }) => !["bounce", "warp", "path"].includes(l.motion.type)).filter(({ l }) => !(l.motion.type === "orbit" && l.motion.center && "layer" in l.motion.center));
+  const composedCount = composed.reduce((s, c) => s + c.ents.length, 0);
+  if (composedCount >= 8) {
+    const positions = composed.flatMap(({ ents }) => ents.map((e) => positionAt(e, 0, w, h)));
+    const px = positions.reduce((s, p) => s + p.x, 0) / positions.length / w;
+    const py = positions.reduce((s, p) => s + p.y, 0) / positions.length / h;
+    const offX = Math.abs(px - 0.5);
+    const offY = Math.abs(py - 0.5);
+    const anchoredOn = (axis) => composed.reduce((n, { l, ents }) => n + (edgeAnchored(l.region?.[axis]) ? ents.length : 0), 0) / composedCount;
+    const intentional = offY > 0.2 && offX <= 0.2 && anchoredOn("y") >= 0.5 || offX > 0.2 && offY <= 0.2 && anchoredOn("x") >= 0.5;
+    if ((offX > 0.2 || offY > 0.2) && !intentional) {
+      const grid = luminanceGrid({ ...spec, layers: composed.map(({ l }) => l) }, { viewport: { width: w, height: h }, t: opts.t ?? COHESION_T, seed: opts.seed });
+      const c = grid.centroid;
+      if (c && (Math.abs(c.x - 0.5) > 0.2 || Math.abs(c.y - 0.5) > 0.2)) {
+        warnings.push({
+          path: "layers",
+          code: "off-center",
+          message: `centroid at (${c.x.toFixed(2)}, ${c.y.toFixed(2)}) \u2014 composition is heavily offset from center`
+        });
       }
     }
-  };
-  const ghost = spec.ghosting ?? 0;
-  if (ghost > 0) {
-    const dt = 1e3 / 60;
-    const windowFrames = Math.min(Math.ceil(Math.log(1 / 255) / Math.log(ghost)), LIMITS.maxGhostReplayFrames);
-    const taps = Math.min(GHOST_TAPS, windowFrames);
-    const spacing = windowFrames / taps;
-    for (let i = taps; i >= 1; i--) {
-      const tPass = t - i * spacing * dt;
-      if (tPass < 0) continue;
-      const bracketWeight = Math.pow(ghost, (i - 1) * spacing + 1) * (1 - Math.pow(ghost, spacing)) / (1 - ghost);
-      splatPass(tPass, Math.min(1, bracketWeight));
+  }
+  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 raw = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
+      const map = paintMap(spec, layer, w, h, scale);
+      const box = map ? { ...raw, ...mapBox(map, raw) } : raw;
+      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" ? s.text : s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
+      textBoxes.push({ li, label, alpha, str, ...box });
     }
   }
-  splatPass(t, 1);
-  return finishGrid(cols, rows, cells, bgRow, bgCells);
-}
-function finishGrid(cols, rows, cells, bgRow, bgCells) {
-  let sum = 0;
-  let covered = 0;
-  let devSum = 0;
-  let cxAcc = 0;
-  let cyAcc = 0;
-  const rowProfile = new Array(rows).fill(0);
-  const colProfile = new Array(cols).fill(0);
-  for (let r = 0; r < rows; r++) {
-    for (let c = 0; c < cols; c++) {
-      const v = cells[r * cols + c];
-      sum += v;
-      const dev = Math.abs(v - (bgCells ? bgCells[r * cols + c] : bgRow[r]));
-      if (dev > 0.03) covered++;
-      devSum += dev;
-      cxAcc += dev * (c + 0.5);
-      cyAcc += dev * (r + 0.5);
-      rowProfile[r] += dev;
-      colProfile[c] += dev;
+  const asFraction = (b) => ({
+    x: +(b.x0 / w).toFixed(4),
+    y: +(b.y0 / h).toFixed(4),
+    w: +((b.x1 - b.x0) / w).toFixed(4),
+    h: +((b.y1 - b.y0) / h).toFixed(4)
+  });
+  const tolX = w * 0.01;
+  const tolY = h * 0.01;
+  const offFlagged = /* @__PURE__ */ new Set();
+  for (const b of textBoxes) {
+    if (offFlagged.has(b.li)) continue;
+    const edges = [];
+    if (b.x0 < -tolX) edges.push(`left edge by ~${Math.round(-b.x0)}px`);
+    if (b.x1 > w + tolX) edges.push(`right edge by ~${Math.round(b.x1 - w)}px`);
+    if (b.y0 < -tolY) edges.push(`top edge by ~${Math.round(-b.y0)}px`);
+    if (b.y1 > h + tolY) edges.push(`bottom edge by ~${Math.round(b.y1 - h)}px`);
+    if (edges.length === 0) continue;
+    offFlagged.add(b.li);
+    warnings.push({
+      path: `layers[${b.li}]`,
+      code: "text-off-screen",
+      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)]
+      });
     }
   }
-  for (let r = 0; r < rows; r++) rowProfile[r] = rowProfile[r] / cols;
-  for (let c = 0; c < cols; c++) colProfile[c] = colProfile[c] / rows;
-  return {
-    cols,
-    rows,
-    cells,
-    background: bgRow,
-    ...bgCells ? { backgroundCells: bgCells } : {},
-    meanLuminance: sum / (cols * rows),
-    coverage: covered / (cols * rows),
-    centroid: devSum > 1e-6 ? { x: cxAcc / devSum / cols, y: cyAcc / devSum / rows } : null,
-    rowProfile,
-    colProfile
-  };
-}
-var DITHER = [
-  [0.5 / 8, 4.5 / 8],
-  [2.5 / 8, 6.5 / 8],
-  [1.5 / 8, 5.5 / 8],
-  [3.5 / 8, 7.5 / 8]
-];
-var DOT_BIT = [
-  [1, 8],
-  [2, 16],
-  [4, 32],
-  [64, 128]
-];
-function autoExpose(grid) {
-  const sorted = [...grid.cells].sort((a, b) => a - b);
-  const lo = sorted[0];
-  const hi = Math.max(sorted[Math.floor(sorted.length * 0.98)], lo + 0.08);
-  return (v) => Math.pow(Math.max(0, Math.min(1, (v - lo) / (hi - lo))), 0.8);
+  const readFlagged = /* @__PURE__ */ new Set();
+  for (const b of textBoxes) {
+    if (readFlagged.has(b.li)) continue;
+    const layer = spec.layers[b.li];
+    const s = layer.sprite;
+    if (s.kind !== "text" && s.kind !== "textBlock" || s.role !== "read") continue;
+    const boxes = textBoxes.filter((x) => x.li === b.li);
+    readFlagged.add(b.li);
+    const ink = hexRgb(s.color ?? "#e6e8ef");
+    const textPlate = (base, alpha) => {
+      if (layer.blend === "lighter" || layer.blend === "screen") return additivePlate(base, ink, alpha, layer.blend);
+      if (layer.blend === "multiply") {
+        return {
+          r: base.r * (1 - alpha + ink.r * alpha),
+          g: base.g * (1 - alpha + ink.g * alpha),
+          b: base.b * (1 - alpha + ink.b * alpha)
+        };
+      }
+      return sourceOverPlate(base, ink, alpha);
+    };
+    let worst = null;
+    for (const box of boxes) {
+      const cy = (box.y0 + box.y1) / 2;
+      const cx = (box.x0 + box.x1) / 2;
+      const groundRgb = backgroundRgbAt(spec, cy, h, scale, cx, w, opts.backgroundSeed ?? opts.seed, opts.t ?? COHESION_T);
+      const ground = legibilityRatio(textPlate(groundRgb, box.alpha), groundRgb);
+      const lit = brightestAdditivePlate(spec, allEntities, groundRgb, box, w, h);
+      const plate = lit ? legibilityRatio(textPlate(lit.rgb, box.alpha), lit.rgb) : Infinity;
+      if (!worst || Math.min(ground, plate) < Math.min(worst.ground, worst.plate)) {
+        worst = { ground, plate, plateLabel: lit?.label ?? null };
+      }
+    }
+    if (worst && Math.min(worst.ground, worst.plate) < READ_LEGIBILITY_FLOOR) {
+      const under = worst.plateLabel ? ` and ${worst.plate.toFixed(1)}:1 under ${worst.plateLabel} at its brightest` : "";
+      warnings.push({
+        path: `layers[${b.li}].sprite`,
+        code: "text-legibility",
+        message: `${b.label} is declared role: 'read' but its colour reads at ${worst.ground.toFixed(1)}:1 against the background at the box centre${under} \u2014 below ${READ_LEGIBILITY_FLOOR}:1; brighten the text, darken the ground under it, or declare role: 'atmosphere' if it is texture`
+      });
+    }
+    const edges = [];
+    const x0 = Math.min(...boxes.map((x) => x.x0));
+    const x1 = Math.max(...boxes.map((x) => x.x1));
+    const y0 = Math.min(...boxes.map((x) => x.y0));
+    const y1 = Math.max(...boxes.map((x) => x.y1));
+    if (x0 < w * READ_SAFE_AREA) edges.push("left");
+    if (x1 > w * (1 - READ_SAFE_AREA)) edges.push("right");
+    if (y0 < h * READ_SAFE_AREA) edges.push("top");
+    if (y1 > h * (1 - READ_SAFE_AREA)) edges.push("bottom");
+    if (edges.length > 0) {
+      warnings.push({
+        path: `layers[${b.li}]`,
+        code: "text-safe-area",
+        message: `${b.label} is declared role: 'read' but its box is within ${READ_SAFE_AREA * 100}% of the ${edges.join(" and ")} edge${edges.length === 1 ? "" : "s"} at ${w}\xD7${h} \u2014 displays crop and bezels hide that zone; move it inward`,
+        boxes: [asFraction({ x0, y0, x1, y1 })]
+      });
+    }
+  }
+  return warnings;
 }
-function renderBrailleMap(grid) {
-  const expose = autoExpose(grid);
-  const outRows = [];
-  for (let br = 0; br < Math.floor(grid.rows / 4); br++) {
-    let line = "";
-    for (let bc = 0; bc < Math.floor(grid.cols / 2); bc++) {
-      let bits = 0;
-      for (let dr = 0; dr < 4; dr++) {
-        for (let dc = 0; dc < 2; dc++) {
-          const v = expose(grid.cells[(br * 4 + dr) * grid.cols + (bc * 2 + dc)]);
-          if (v > DITHER[dr][dc]) bits |= DOT_BIT[dr][dc];
-        }
+function brightestAdditivePlate(spec, allEntities, ground, box, w, h) {
+  let best = null;
+  for (let lj = 0; lj < spec.layers.length; lj++) {
+    const layer = spec.layers[lj];
+    const blend = layer.blend;
+    if (blend !== "lighter" && blend !== "screen") continue;
+    if (lj === box.li) continue;
+    const entities = allEntities[lj];
+    const moved = layer.transform !== void 0 || groupOf(spec, layer)?.transform !== void 0;
+    for (const e of entities) {
+      const hex = spriteHex(layer, e);
+      if (hex === null) continue;
+      const growScale = (e.motion === "warp" ? WARP_MAX_SCALE : 1) * (e.emit ? Math.max(e.emit.growFrom, e.emit.growTo) : 1);
+      const maxDim = Math.max(e.size, e.size2 ?? 0) * (1 + e.growAmp) * growScale;
+      if (maxDim < box.fs) continue;
+      if (!moved && !entityReachesBox(e, maxDim / 2, box, w, h)) continue;
+      const a = layer.opacity === void 0 && layer.group === void 0 ? Math.min(1, e.alpha + e.pulseAmp) : Math.min(1, e.alpha + e.pulseAmp) * paintOpacity(spec, layer);
+      if (a <= 0) continue;
+      const plate = additivePlate(ground, hexRgb(hex), a, blend);
+      const lum = relativeLuminance(plate);
+      if (!best || lum > best.lum) {
+        best = { rgb: plate, label: layer.key ? `\`${layer.key}\`` : `layers[${lj}]`, lum };
       }
-      line += String.fromCharCode(10240 + bits);
     }
-    outRows.push(line);
   }
-  return outRows.join("\n");
+  return best ? { rgb: best.rgb, label: best.label } : null;
 }
-var DENSITY_RAMP = " .:-=+*#%@";
-function renderDensityMap(grid) {
-  const expose = autoExpose(grid);
-  const ramp = DENSITY_RAMP;
-  const lines = [];
-  for (let r = 0; r < grid.rows; r++) {
-    let line = "";
-    for (let c = 0; c < grid.cols; c++) {
-      const v = expose(grid.cells[r * grid.cols + c]);
-      line += ramp[Math.min(ramp.length - 1, Math.floor(v * ramp.length))];
+function groundUnder(spec, allEntities, li, hidden, pt, w, h) {
+  let plate = backgroundRgb(spec);
+  let covered = false;
+  for (let lj = 0; lj < li; lj++) {
+    if (hidden?.[lj]) continue;
+    const layer = spec.layers[lj];
+    const sp = layer.sprite;
+    if (layer.motion.type !== "static" || layer.blend !== void 0 || layer.transform !== void 0 || groupOf(spec, layer)?.transform !== void 0) continue;
+    if ((sp.kind === "circle" || sp.kind === "polygon") && sp.soft) continue;
+    if (sp.kind !== "circle" && sp.kind !== "rect" && sp.kind !== "polygon") continue;
+    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.alpha * a <= 0) continue;
+      const hex = spriteHex(layer, e);
+      if (hex === null) continue;
+      const c = positionAt(e, 0, w, h);
+      const dx = pt.x - c.x;
+      const dy = pt.y - c.y;
+      let inside = false;
+      if (sp.kind === "circle") inside = Math.hypot(dx, dy) <= e.size / 2;
+      else if (sp.kind === "rect") {
+        const rot = ((e.rotate ?? 0) % Math.PI + Math.PI) % Math.PI;
+        const quarter = Math.abs(rot - Math.PI / 2) < 0.01;
+        if (rot > 0.01 && rot < Math.PI - 0.01 && !quarter) continue;
+        const hx = (quarter ? e.size2 ?? e.size : e.size) / 2;
+        const hy = (quarter ? e.size : e.size2 ?? e.size) / 2;
+        inside = Math.abs(dx) <= hx && Math.abs(dy) <= hy;
+      } else {
+        if (e.rotate) continue;
+        inside = pointInPolygon(dx, dy, polygonPoints(sp, e.size / 2));
+      }
+      if (!inside) continue;
+      plate = sourceOverPlate(plate, hexRgb(hex), Math.min(1, e.alpha * a));
+      covered = true;
     }
-    lines.push(line);
   }
-  return lines.join("\n");
+  return covered ? { rgb: plate, luma: 0.2126 * plate.r + 0.7152 * plate.g + 0.0722 * plate.b } : null;
 }
-function textSprites(spec, opts = {}) {
-  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
-  const scene = buildScene(spec, opts);
-  const t = opts.t ?? 5e3;
-  const out = [];
-  scene.layers.forEach(({ layer, entities }, layerIndex) => {
-    if (layer.sprite.kind === "textBlock") {
-      const s2 = layer.sprite;
-      const unitScale = Math.min(scene.w, scene.h);
-      const sizePx2 = s2.fontSize * unitScale;
-      const info = { layerIndex, key: layer.key, strings: [s2.text], count: entities.length, sizePx: Math.round(sizePx2) };
-      if (s2.reveal) info.revealed = Math.round(textBlockRevealFraction(s2, scene.w, scene.h, t) * 100) / 100;
-      out.push(info);
-      return;
-    }
-    if (layer.sprite.kind !== "text") return;
-    const s = layer.sprite;
-    const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
-    const sizePx = m ? Number(m[1]) : entities[0] ? sizeAt(entities[0], t) : 0;
-    out.push({ layerIndex, key: layer.key, strings: [...s.strings], count: entities.length, sizePx: Math.round(sizePx) });
-  });
-  return out;
+function pointInPolygon(x, y, pts) {
+  let inside = false;
+  for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+    const a = pts[i];
+    const b = pts[j];
+    if (a.y > y !== b.y > y && x < (b.x - a.x) * (y - a.y) / (b.y - a.y) + a.x) inside = !inside;
+  }
+  return inside;
 }
-function dominanceRanking(spec, opts = {}) {
-  return rankDominance(rawDominance(spec, opts));
+function entityReachesBox(e, r, box, w, h) {
+  if (e.motion === "static") {
+    const p = positionAt(e, 0, w, h);
+    return p.x + r > box.x0 && p.x - r < box.x1 && p.y + r > box.y0 && p.y - r < box.y1;
+  }
+  if (e.motion === "orbit" && !e.orbitParent) {
+    const span = e.orbitR + r;
+    return e.orbitCx + span > box.x0 && e.orbitCx - span < box.x1 && e.orbitCy + span > box.y0 && e.orbitCy - span < box.y1;
+  }
+  return true;
 }
-function rankDominance(raw) {
-  const total = raw.reduce((s, r) => s + r.weight, 0) || 1;
-  return raw.slice().sort((a, b) => b.weight - a.weight).map((r, i) => ({
-    rank: i + 1,
-    layerIndex: r.layerIndex,
-    key: r.key,
-    share: r.weight / total,
-    entityCount: r.entityCount,
-    meanLuma: r.meanLuma,
-    factors: r.factors
-  }));
+var OUTLINE_STACK_OFFSET = 0.15;
+function isOutlineStack(a, b) {
+  if (a.str !== b.str || a.str.trim() === "") return false;
+  const fs = Math.min(a.fs, b.fs);
+  if (fs <= 0 || Math.abs(a.fs - b.fs) > 0.1 * Math.max(a.fs, b.fs)) return false;
+  const dx = (a.x0 + a.x1) / 2 - (b.x0 + b.x1) / 2;
+  const dy = (a.y0 + a.y1) / 2 - (b.y0 + b.y1) / 2;
+  return Math.hypot(dx, dy) <= OUTLINE_STACK_OFFSET * fs;
 }
-function rawDominance(spec, opts = {}) {
-  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
-  const scene = buildScene(spec, opts);
-  const t = opts.t ?? 5e3;
-  const { w, h, scale } = scene;
-  const bgMean = backgroundLuma(spec);
-  const ghost = spec.ghosting ?? 0;
-  let ghostWindowMs = 0;
-  let ghostMeanW = 0;
-  if (ghost > 0) {
-    const dt = 1e3 / 60;
-    const frames = Math.min(Math.ceil(Math.log(1 / 255) / Math.log(ghost)), LIMITS.maxGhostReplayFrames);
-    ghostWindowMs = frames * dt;
-    ghostMeanW = ghost * (1 - Math.pow(ghost, frames)) / (1 - ghost) / frames;
-  }
-  const sweptDistance = (e, spanMs) => {
-    const span = Math.min(spanMs, t);
-    if (span <= 0) return 0;
-    const p0 = posOf(scene, e, t - span);
-    const p1 = posOf(scene, e, t);
-    const dx = p1.x - p0.x;
-    const dy = p1.y - p0.y;
-    if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) return 0;
-    return Math.sqrt(dx * dx + dy * dy);
-  };
-  const raw = scene.layers.map(({ layer, entities }, layerIndex) => {
-    const lifeA = layer.opacity === void 0 && layer.group === void 0 ? lifeAlphaAt(layer.life, t) : lifeAlphaAt(layer.life, t) * paintOpacity(spec, layer);
-    const painted = layer.transform !== void 0 || layer.group !== void 0;
-    const areaScale = painted ? paintSize(spec, layer) ** 2 : 1;
-    let area = 0;
-    let lumAcc = 0;
-    for (const e of entities) {
-      const a = alphaAt(e, t) * lifeA;
-      const sz = sizeAt(e, t);
-      const s = layer.sprite;
-      let entArea;
-      if (s.kind === "circle") entArea = Math.PI * (sz / 2) * (sz / 2);
-      else if (s.kind === "ring") entArea = Math.PI * sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale) * LINE_SALIENCE;
-      else if (s.kind === "streak") entArea = sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale) * LINE_SALIENCE;
-      else if (s.kind === "rect") {
-        const h2 = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz;
-        const f = s.feather ? (1 - s.feather / 2) * (1 - s.feather / 2) : 1;
-        entArea = sz * h2 * f;
-      } else if (s.kind === "polygon") entArea = polygonArea(polygonPoints(s, sz / 2));
-      else if (s.kind === "bar") {
-        const th = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz * 0.2;
-        entArea = sz * barFraction(s, e.barIndex ?? 0) * th;
-      } else if (s.kind === "stroke") {
-        const meanTaper = s.taper ? 0.64 : 1;
-        entArea = pathLength(strokeSamples(s, sz / 2)) * strokeWidthPx(s, scale) * meanTaper * LINE_SALIENCE;
-      } else if (s.kind === "text") {
-        const box = textBox(s, e, { x: 0, y: 0 });
-        entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
-      } else if (s.kind === "textBlock") {
-        const box = textBlockBox(s, e, { x: 0, y: 0 }, w, h);
-        entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1);
-      } else entArea = sz * sz * 0.55;
-      area += painted ? entArea * areaScale * a : entArea * a;
-      if (layer.trail) {
-        const fade = layer.trail.fade ?? 1;
-        const span = sweptDistance(e, layer.trail.length);
-        area += span * sz * 0.65 * Math.max(0, 1 - fade / 2) * a;
-      }
-      if (ghost > 0) {
-        area += sweptDistance(e, ghostWindowMs) * sz * ghostMeanW * a;
-      }
-      lumAcc += spriteLuma(layer, e);
-    }
-    if (layer.links && entities.length > 1) {
-      const positions = entities.map((e) => posOf(scene, e, t));
-      const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
-      const edges = linkEdges(layer.links, positions, layer.links.maxDist * scale, layer.wrap !== false && motionWraps, w, h);
-      const la = (layer.links.alpha ?? 0.6) * lifeA;
-      const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
-      const lw = (layer.links.width ?? defaultWidth) * scale;
-      for (const edge of edges) area += edge.dist * lw * la * LINE_SALIENCE;
-    }
-    const meanLuma = entities.length ? lumAcc / entities.length : 0;
-    const contrast = Math.abs(meanLuma - bgMean) + 0.1;
-    const blendBoost = layer.blend === "lighter" || layer.blend === "screen" ? 1.3 : layer.blend === "multiply" ? 1.1 : 1;
-    const motionBoost = layer.motion.type === "static" ? 1 : 1.2;
-    const weight = area / (w * h) * contrast * blendBoost * motionBoost;
-    return { layerIndex, key: layer.key, weight, entityCount: entities.length, meanLuma, factors: { area: area / (w * h), contrast, blendBoost, motionBoost } };
-  });
-  return raw;
+function textBoxAt(s, e, p, spec, w, h) {
+  const m = s.font ? /(\d{1,5}(?:\.\d{1,4})?|\.\d{1,4})px/.exec(s.font) : null;
+  const fontScale = spec.units === "px" ? 1 : Math.min(w, h) / (spec.referenceViewport ?? LIMITS.referenceViewport);
+  const fh = m ? Number(m[1]) * fontScale : e.size;
+  const str = s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
+  let fw = textWidthEm(str) * fh;
+  if (s.maxWidth) fw = Math.min(fw, s.maxWidth * (spec.units === "px" ? 1 : Math.min(w, h)));
+  const align = s.align ?? "center";
+  const baseline = s.baseline ?? "middle";
+  const x0 = align === "left" ? p.x : align === "right" ? p.x - fw : p.x - fw / 2;
+  const y0 = baseline === "top" ? p.y : baseline === "bottom" ? p.y - fh : p.y - fh / 2;
+  return { x0, y0, x1: x0 + fw, y1: y0 + fh, fs: fh };
 }
-function layerCohesion(spec, opts = {}) {
-  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
-  const scene = buildScene(spec, opts);
-  return cohesionOf(scene.layers, opts.t ?? 5e3, scene.w, scene.h);
+function textBlockBoxAt(s, p, w, h) {
+  const unit = Math.min(w, h);
+  const fsPx = s.fontSize * unit;
+  const lh = (s.lineHeight ?? 1.4) * fsPx;
+  const maxWPx = s.maxWidth * unit;
+  const lines = breakTextBlock(s.text, maxWPx / fsPx, textMetricsClassFor(s.font));
+  const maxLineW = lines.reduce((mx, l) => Math.max(mx, l.widthEm), 0) * fsPx;
+  const totalH = lines.length * lh;
+  const align = s.align ?? "left";
+  const x0 = align === "center" ? p.x + (maxWPx - maxLineW) / 2 : align === "right" ? p.x + maxWPx - maxLineW : p.x;
+  const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
+  return { x0: x0 + dx, y0: p.y + dy, x1: x0 + dx + maxLineW, y1: p.y + dy + totalH, fs: fsPx };
 }
-function motionStats(spec, opts = {}) {
-  const t = opts.t ?? 5e3;
-  const dt = opts.dt ?? 500;
-  const scene0 = buildScene(resolveTimelineAt(spec, t), opts);
-  const scene1 = spec.timeline ? buildScene(resolveTimelineAt(spec, t + dt), opts) : scene0;
-  const { w, h } = scene0;
-  return scene0.layers.map(({ layer, entities }, layerIndex) => {
-    const entities1 = scene1.layers[layerIndex]?.entities ?? entities;
-    let acc = 0;
-    let max = 0;
-    let n = 0;
-    entities.forEach((e, i) => {
-      const p0 = posOf(scene0, e, t);
-      const p1 = posOf(scene1, entities1[i] ?? e, t + dt);
-      const dx = p1.x - p0.x;
-      const dy = p1.y - p0.y;
-      if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) return;
-      const speed = Math.sqrt(dx * dx + dy * dy) / dt * 1e3;
-      acc += speed;
-      max = Math.max(max, speed);
-      n++;
-    });
-    const meanSpeed = n ? acc / n : 0;
-    return { layerIndex, key: layer.key, meanSpeed, maxSpeed: max, moving: meanSpeed > 0.5 };
+function hiddenLayers(spec) {
+  if (!spec.groups && !spec.layers.some((l) => l.opacity !== void 0)) return null;
+  const tracks = spec.timeline ? timelineTracks(spec) : null;
+  const pinnedZero = (path, base, ancestors) => {
+    if (base !== 0) return false;
+    if (!tracks) return true;
+    for (const [p, keys] of tracks) {
+      if (p === path && keys.some((k) => k.value !== 0)) return false;
+      if (ancestors.includes(p)) return false;
+    }
+    return true;
+  };
+  const out = spec.layers.map((l, i) => {
+    const lp = `layers.${i}`;
+    if (pinnedZero(`${lp}.opacity`, l.opacity, ["layers", lp])) return true;
+    const g = l.group !== void 0 && spec.groups && Object.prototype.hasOwnProperty.call(spec.groups, l.group) ? spec.groups[l.group] : void 0;
+    return !!g && pinnedZero(`groups.${l.group}.opacity`, g.opacity, ["groups", `groups.${l.group}`]);
   });
+  return out.some(Boolean) ? out : null;
 }
-var REGION_NAMES = [
-  "top-left",
-  "top-center",
-  "top-right",
-  "mid-left",
-  "center",
-  "mid-right",
-  "bottom-left",
-  "bottom-center",
-  "bottom-right"
-];
-function regionMeans(grid) {
-  const out = new Array(9).fill(0);
-  const cnt = new Array(9).fill(0);
-  for (let r = 0; r < grid.rows; r++) {
-    for (let c = 0; c < grid.cols; c++) {
-      const idx = r * grid.cols + c;
-      const region = Math.min(2, Math.floor(r / grid.rows * 3)) * 3 + Math.min(2, Math.floor(c / grid.cols * 3));
-      out[region] += Math.abs(grid.cells[idx] - (grid.backgroundCells ? grid.backgroundCells[idx] : grid.background[r]));
-      cnt[region]++;
+function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
+  const warnings = [];
+  for (let i = 0; i < seq.segments.length; i++) {
+    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 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 });
     }
   }
-  return out.map((v, i) => cnt[i] ? v / cnt[i] : 0);
-}
-function diffScenes(a, b, opts = {}) {
-  const t = opts.t ?? 5e3;
-  const gridA = luminanceGrid(a, opts);
-  const gridB = luminanceGrid(b, opts);
-  const regsA = regionMeans(gridA);
-  const regsB = regionMeans(gridB);
-  const domA = dominanceRanking(a, opts);
-  const domB = dominanceRanking(b, opts);
-  const nameOf = (d) => d.key ?? `layer-${d.layerIndex}`;
-  const names = /* @__PURE__ */ new Set([...domA.map(nameOf), ...domB.map(nameOf)]);
-  const dominance = [...names].map((key) => {
-    const inA = domA.find((d) => nameOf(d) === key);
-    const inB = domB.find((d) => nameOf(d) === key);
-    return {
-      key,
-      rankA: inA?.rank ?? null,
-      rankB: inB?.rank ?? null,
-      shareA: inA?.share ?? 0,
-      shareB: inB?.share ?? 0
-    };
-  }).sort((x, y) => Math.abs(y.shareB - y.shareA) - Math.abs(x.shareB - x.shareA));
-  const codesA = new Set(adviseSpec(a).map((w) => w.code));
-  const codesB = new Set(adviseSpec(b).map((w) => w.code));
-  return {
-    t,
-    coverage: { a: gridA.coverage, b: gridB.coverage, delta: gridB.coverage - gridA.coverage },
-    meanLuminance: { a: gridA.meanLuminance, b: gridB.meanLuminance, delta: gridB.meanLuminance - gridA.meanLuminance },
-    balanceShift: gridA.centroid && gridB.centroid ? { dx: gridB.centroid.x - gridA.centroid.x, dy: gridB.centroid.y - gridA.centroid.y } : null,
-    regions: REGION_NAMES.map((region, i) => ({ region, a: regsA[i], b: regsB[i], delta: regsB[i] - regsA[i] })),
-    dominance,
-    advisories: {
-      added: [...codesB].filter((c) => !codesA.has(c)),
-      removed: [...codesA].filter((c) => !codesB.has(c))
+  const fadeBound = seq.loop ? seq.segments.length : seq.segments.length - 1;
+  const fades = seq.segments.slice(0, fadeBound).filter((s) => s.transition?.type === "fade").length;
+  if (fades > 0) {
+    const first = seq.segments.slice(0, fadeBound).findIndex((s) => s.transition?.type === "fade");
+    warnings.push({
+      path: `segments[${first}].transition`,
+      code: "fade-degrades-on-low-tier",
+      message: `informational: ${fades} fade transition${fades === 1 ? "" : "s"} declared \u2014 viewers on the 'basic' or 'minimal' capability tier render fade as cut (two live segments for dur is over that budget); the show still plays`
+    });
+  }
+  for (let i = 0; i < seq.segments.length - 1; i++) {
+    const tr = seq.segments[i].transition;
+    const lumaA = backgroundLuma(resolveTimelineAt(seq.segments[i].scene, seq.segments[i].duration ?? 0));
+    const lumaB = backgroundLuma(resolveTimelineAt(seq.segments[i + 1].scene, 0));
+    const delta = Math.abs(lumaA - lumaB);
+    if (delta > 0.5 && tr?.type !== "fade") {
+      warnings.push({
+        path: `segments[${i}]`,
+        code: "boundary-luminance-jump",
+        message: `background luminance jumps ${delta.toFixed(2)} at boundary ${i}\u2192${i + 1} \u2014 may flash on cut; declare transition: { type: 'fade', dur } on segments[${i}] to ramp it`
+      });
     }
-  };
-}
-function perceiveScene(spec, opts = {}) {
-  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
-  const grid = luminanceGrid(spec, opts);
-  return {
-    t: opts.t ?? 5e3,
-    braille: renderBrailleMap(grid),
-    density: renderDensityMap(grid),
-    coverage: grid.coverage,
-    meanLuminance: grid.meanLuminance,
-    centroid: grid.centroid,
-    rowProfile: grid.rowProfile,
-    colProfile: grid.colProfile,
-    dominance: dominanceRanking(spec, opts),
-    motion: motionStats(spec, opts),
-    form: layerCohesion(spec, opts),
-    text: textSprites(spec, opts),
-    advisories: adviseSpec(spec, opts.viewport ?? { width: 1920, height: 1080 }, { t: opts.t, seed: opts.seed })
-  };
+    if (tr?.type === "morph") {
+      const sigA = structuralSignature(seq.segments[i].scene);
+      const sigB = structuralSignature(seq.segments[i + 1].scene);
+      if (sigA !== sigB) {
+        warnings.push({
+          path: `segments[${i}].transition`,
+          code: "morph-structural-mismatch",
+          message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
+        });
+      } 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({
+          path: `segments[${i}].transition`,
+          code: "morph-nothing-morphable",
+          message: `segments ${i}\u2192${i + 1} differ only in values morph cannot interpolate (strings such as textBlock.text step on the first frame): the morph will look like a cut \u2014 fade text via colour or reveal.progress`
+        });
+      }
+    }
+  }
+  return warnings;
 }
-var bedKey = (key, layerIndex) => `bed:${key ?? layerIndex}`;
-function perceiveSequenceFrame(seq, T, opts = {}) {
-  const { releasedBelow, ...gridOpts } = opts;
-  const r = resolveSegment(seq, T, { releasedBelow });
-  const seg = seq.segments[r.index];
-  const segment = { index: r.index, key: seg.key, localT: r.localT, ...r.held ? { held: true } : {} };
-  const segOpts = { ...gridOpts, t: r.localT, seed: gridOpts.seed ?? segmentRenderSeed(seq, r.index) };
-  if (!seq.bed) return { ...perceiveScene(seg.scene, segOpts), segment, bed: false };
-  const bedOpts = { ...gridOpts, t: T, seed: gridOpts.seed ?? bedRenderSeed(seq) };
-  const viewport = gridOpts.viewport ?? { width: 1920, height: 1080 };
-  const ink = { ...seg.scene, background: { type: "solid", color: "#000000" } };
-  delete ink.ghosting;
-  const inkOverBed = { ...ink, background: seq.bed.background ?? { type: "solid", color: "#05050a" } };
-  const bedGrid = luminanceGrid(seq.bed, bedOpts);
-  const inkGrid = luminanceGrid(ink, segOpts);
-  const cells = bedGrid.cells.map((v, i) => Math.min(1, v + inkGrid.cells[i]));
-  const grid = finishGrid(bedGrid.cols, bedGrid.rows, cells, bedGrid.background, bedGrid.backgroundCells);
-  const bedLayers = seq.bed.layers.length;
-  const dominance = rankDominance([
-    ...rawDominance(seq.bed, bedOpts).map((d) => ({ ...d, key: bedKey(d.key, d.layerIndex) })),
-    ...rawDominance(inkOverBed, segOpts).map((d) => ({ ...d, layerIndex: d.layerIndex + bedLayers }))
-  ]);
-  const shift = (x) => ({ ...x, layerIndex: x.layerIndex + bedLayers });
-  const prefix = (x) => ({ ...x, key: bedKey(x.key, x.layerIndex) });
+
+// src/describe.ts
+import { createRng as createRng4 } from "@idle-screens/core";
+function describeScene(spec, options = {}) {
+  const { width: w, height: h } = options.viewport ?? { width: 1920, height: 1080 };
+  const seed = options.seed ?? spec.seed ?? 42;
+  const times = options.times ?? [0, 5e3, 15e3];
+  const { scale, countScale } = entityScales(spec, w, h);
+  const rng = createRng4(seed);
+  const builtLayers = spec.layers.map((layer) => ({
+    layer,
+    entities: buildEntities(layer, rng, w, h, scale, countScale)
+  }));
+  const snapshots = times.map((t) => {
+    const layerSnapshots = builtLayers.map(({ layer, entities }) => {
+      const positions = entities.map((e) => positionAt(e, t, w, h));
+      const cx = positions.length > 0 ? positions.reduce((s, p) => s + p.x, 0) / positions.length : 0;
+      const cy = positions.length > 0 ? positions.reduce((s, p) => s + p.y, 0) / positions.length : 0;
+      let pixArea = 0;
+      for (const e of entities) {
+        const r = e.size / 2;
+        pixArea += layer.sprite.kind === "circle" ? Math.PI * r * r : layer.sprite.kind === "polygon" ? polygonArea(polygonPoints(layer.sprite, r)) : e.size * e.size;
+      }
+      const coverage = pixArea / (w * h);
+      const meanAlpha = entities.length > 0 ? entities.reduce((s, e) => s + e.alpha, 0) / entities.length : 0;
+      let linksDrawn = null;
+      let linksExpected = null;
+      let connectedComponents = null;
+      let isolatedNodes = null;
+      if (layer.links) {
+        const maxDist = layer.links.maxDist * scale;
+        const pairs = linkPairs(positions, layer.links.k, maxDist, layer.wrap !== false, w, h);
+        linksDrawn = pairs.length;
+        linksExpected = Math.min(entities.length * layer.links.k, entities.length * (entities.length - 1) / 2);
+        const parent = Array.from({ length: entities.length }, (_, i) => i);
+        const find = (x) => {
+          while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+          }
+          return x;
+        };
+        for (const [a, b] of pairs) {
+          const ra = find(a);
+          const rb = find(b);
+          if (ra !== rb) parent[ra] = rb;
+        }
+        const roots = new Set(entities.map((_, i) => find(i)));
+        connectedComponents = roots.size;
+        const degree = new Uint16Array(entities.length);
+        for (const [a, b] of pairs) {
+          degree[a]++;
+          degree[b]++;
+        }
+        isolatedNodes = degree.filter((d) => d === 0).length;
+      }
+      return {
+        key: layer.key,
+        count: entities.length,
+        centroid: { x: +(cx / w).toFixed(3), y: +(cy / h).toFixed(3) },
+        coverage: +coverage.toFixed(4),
+        meanAlpha: +meanAlpha.toFixed(3),
+        linksDrawn,
+        linksExpected,
+        connectedComponents,
+        isolatedNodes
+      };
+    });
+    const warnings = [];
+    for (const ls of layerSnapshots) {
+      const label = ls.key ?? `layer`;
+      if (ls.coverage * ls.meanAlpha < 5e-4) {
+        warnings.push(`${label}: effectively invisible (coverage\xD7alpha=${(ls.coverage * ls.meanAlpha).toFixed(5)})`);
+      }
+      if (ls.linksDrawn !== null && ls.linksExpected !== null && ls.linksExpected > 0) {
+        const ratio = ls.linksDrawn / ls.linksExpected;
+        if (ratio < 0.1) {
+          warnings.push(`${label}: link starvation \u2014 ${ls.linksDrawn}/${ls.linksExpected} edges formed`);
+        }
+      }
+      if (ls.isolatedNodes !== null && ls.count > 0 && ls.isolatedNodes / ls.count > 0.5) {
+        warnings.push(`${label}: ${ls.isolatedNodes}/${ls.count} nodes isolated \u2014 graph is disconnected`);
+      }
+    }
+    return { t, viewport: { w, h }, layers: layerSnapshots, warnings };
+  });
   return {
-    t: r.localT,
-    braille: renderBrailleMap(grid),
-    density: renderDensityMap(grid),
-    coverage: grid.coverage,
-    meanLuminance: grid.meanLuminance,
-    centroid: grid.centroid,
-    rowProfile: grid.rowProfile,
-    colProfile: grid.colProfile,
-    dominance,
-    motion: [...motionStats(seq.bed, bedOpts).map(prefix), ...motionStats(ink, segOpts).map(shift)],
-    form: [...layerCohesion(seq.bed, bedOpts).map(prefix), ...layerCohesion(ink, segOpts).map(shift)],
-    text: [...textSprites(seq.bed, bedOpts).map(prefix), ...textSprites(ink, segOpts).map(shift)],
-    advisories: [
-      ...adviseSpec(seq.bed, viewport, { t: T, seed: bedOpts.seed }).map((w) => ({ ...w, path: `bed.${w.path}` })),
-      // inkOverBed's layers are the segment's (seed: segOpts.seed) but its
-      // background is the bed's (seq.bed.background) — a field there must be
-      // sampled with the bed's own seed, or a `role: 'read'` legibility
-      // advisory checks terrain that isn't what's actually behind the ink.
-      // `?? 42`: inkOverBed.seed is the SEGMENT's raw seed field (it's `ink`
-      // spread first), so adviseSpec's own `backgroundSeed ?? seed` fallback
-      // would substitute the segment's seed, not the bed's, if bedOpts.seed
-      // were left undefined — 42 is the same default `luminanceGrid` (and
-      // every other field seed fallback) converges on.
-      ...adviseSpec(inkOverBed, viewport, { t: r.localT, seed: segOpts.seed, backgroundSeed: bedOpts.seed ?? 42 })
-    ],
-    segment,
-    bed: true
+    spec: { id: spec.id, label: spec.label, units: spec.units ?? "viewport", ...spec.finish ? { finish: spec.finish } : {} },
+    snapshots
   };
 }
 
@@ -9083,6 +9245,7 @@ export {
   easeSmooth,
   emitEnvelope,
   emitWindow,
+  entityScales,
   fieldAt,
   fieldOctaves,
   fieldRgb,
@@ -9124,6 +9287,7 @@ export {
   revealState,
   rgb255Luma,
   rotationAt,
+  sceneColour,
   seamCauseOf,
   seamsWorthWarning,
   segmentRenderSeed,