@idle-screens/schema 3.0.0 → 3.1.0

package/FORMAT.md

@@ -195,6 +195,14 @@ the format never changes the entity stream of an existing spec — a spec author
 against an older runtime renders bit-identically on a newer one
 (`determinism-baseline.test.ts` guards this with snapshot streams).
 
+The same discipline applies to **meaning**, not just RNG draws: a new field may
+introduce a default, but a default must never *reinterpret* values that already
+exist in published specs. Ship the field opt-in first, flip the default only in
+a major, and write the stored-spec migration in the same change. (Learned the
+hard way when 2.3.0's `units: "viewport"` default invalidated live channels —
+see idle-server's G5 spec stamping, which now heals reads but can't excuse a
+repeat.)
+
 Positions are **analytic**: `positionAt(entity, t)` is a pure function, so
 `renderFrame(t, seed)` can seek anywhere instantly, trails sample the past for
 free, and streak headings derive from a finite difference. `ghosting` is the
@@ -214,11 +222,15 @@ for `ControlTrack` and the idlescreens.com MCP `setParam` tool.
 
 `src/perceive.ts` translates a spec into modalities a **non-vision agent** can
 reason about, computed analytically from the entity model (no canvas, no
-renderer, deterministic, Node-safe). Note: the analytical model approximates
-but does not perfectly match canvas rendering — blend modes are simplified
-(`screen` ≈ `lighter`), wrapped link segments use straight interpolation, and
-background drift is sampled at rest. These are documented trade-offs for a
-zero-dependency, renderer-free analysis tool.
+renderer, deterministic, Node-safe). Persistence is part of the picture:
+`ghosting` is modeled as a decayed sum of past-frame splats (ink from m frames
+ago survives at weight gᵐ, mirroring the renderer's warm-up replay) and `trail`
+mirrors the renderer's past-position sampling — so the smear an audience sees
+is measurable, not invisible, in every output below. Note: the analytical model
+approximates but does not perfectly match canvas rendering — blend modes are
+simplified (`screen` ≈ `lighter`), wrapped link segments use straight
+interpolation, and background drift is sampled at rest. These are documented
+trade-offs for a zero-dependency, renderer-free analysis tool.
 
 - `perceiveScene(spec, {t?, viewport?, seed?})` — one-call bundle: everything below.
 - `luminanceGrid(spec, opts)` — an 80×48 luminance image of the composed frame
@@ -234,9 +246,10 @@ zero-dependency, renderer-free analysis tool.
   braille map smears — concentric rings, grids, text blocks. This is the sharper
   read when composition detail matters.
 - `dominanceRanking(spec, opts)` — layers ranked by estimated visual weight
-  (area × alpha × contrast × glow/motion boosts; links count) — *where the eye
-  goes*, normalized to shares. Thin-but-bright structures (rings, streaks, link
-  lines) get a line-salience boost so they aren't crushed by filled discs.
+  (area × alpha × contrast × glow/motion boosts; links and persistence ink —
+  trail ribbons, ghosting smear — count) — *where the eye goes*, normalized to
+  shares. Thin-but-bright structures (rings, streaks, link lines) get a
+  line-salience boost so they aren't crushed by filled discs.
 - `motionStats(spec, opts)` — per-layer mean/max on-screen speed from analytic
   displacement — choreography as numbers.
 - `textSprites(spec, opts)` — the literal strings and rendered sizes of every

package/dist/index.d.ts

@@ -698,9 +698,14 @@ interface LuminanceGridOptions extends PerceiveOptions {
 }
 /**
  * Sample the spec into a coarse luminance image — analytically, no renderer.
- * Approximations (documented, deliberate): trails and ghosting are ignored,
- * soft circles use a linear falloff, background drift is sampled at its rest
- * position. Good enough to perceive composition, focus, and balance.
+ * Persistence is modeled, not simulated: because positions are pure functions
+ * of (seed, t), `ghosting` is a decayed sum of past-frame splats (weight g^m
+ * for ink m frames old, mirroring the renderer's warm-up replay) and `trail`
+ * re-uses drawTrail's sampling — past positions with decaying alpha and
+ * shrinking radius. Remaining approximations (documented, deliberate): soft
+ * circles use a linear falloff, background drift is sampled at its rest
+ * position. Good enough to perceive composition, focus, balance — and now
+ * smear.
  */
 declare function luminanceGrid(spec: SaverSpec, opts?: LuminanceGridOptions): LuminanceGrid;
 /**
@@ -752,7 +757,9 @@ interface DominanceEntry {
 /**
  * Rank layers by estimated visual weight — where the eye goes. Weight is
  * on-screen area × alpha, scaled by contrast against the background, an
- * additive-glow boost, and a motion boost. Link lines count as area.
+ * additive-glow boost, and a motion boost. Link lines count as area, and so
+ * does persistence ink: trail ribbons and ghosting smear are modeled as swept
+ * ribbons, so a comet layer is ranked by its comet, not just its head.
  */
 declare function dominanceRanking(spec: SaverSpec, opts?: PerceiveOptions): DominanceEntry[];
 interface LayerMotionStats {

package/dist/index.js

@@ -1187,7 +1187,7 @@ function hexToRgba(hex, alpha) {
   return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${alpha})`;
 }
 var FONT_PREFIX_RE = /^((?:(?:italic|oblique|bold|bolder|lighter|normal|\d{3})\s+)+)/;
-var FONT_PX_RE = /(\d*\.?\d+)px/;
+var FONT_PX_RE = /(\d{1,5}(?:\.\d{1,4})?|\.\d{1,4})px/;
 function scaleFontPx(font, factor) {
   if (factor === 1) return font;
   return font.replace(FONT_PX_RE, (_m, n) => `${(Number(n) * factor).toFixed(2)}px`);
@@ -1203,6 +1203,9 @@ function manifestFor(spec) {
   return {
     id: spec.id,
     label: spec.label,
+    // Declarative specs are closed-form by construction: every entity is a
+    // pure function of (seed, t), which is the whole point of the format.
+    timeModel: "closed-form",
     passthrough: false,
     minBackend: "canvas2d",
     costTier,
@@ -1652,6 +1655,67 @@ function compileSaver(spec) {
 
 // src/advise.ts
 import { createRng as createRng2 } from "@idle-screens/core";
+
+// src/luma.ts
+function hexLuma(hex) {
+  const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
+  const n = parseInt(h.slice(1), 16);
+  if (Number.isNaN(n)) return 0.7;
+  const r = (n >> 16 & 255) / 255;
+  const g = (n >> 8 & 255) / 255;
+  const b = (n & 255) / 255;
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function spriteLuma(layer, e) {
+  const s = layer.sprite;
+  if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
+    return hexLuma(s.colors?.[e.colorIndex] ?? s.color);
+  }
+  if (s.kind === "text") return hexLuma(s.color ?? "#e6e8ef");
+  return 0.75;
+}
+function spriteHex(layer, e) {
+  const s = layer.sprite;
+  if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
+    return s.colors?.[e.colorIndex] ?? s.color;
+  }
+  if (s.kind === "text") return s.color ?? "#e6e8ef";
+  return null;
+}
+function backgroundLuma(spec) {
+  const bg = spec.background;
+  if (!bg || bg.type === "solid") return hexLuma(bg?.color ?? "#05050a");
+  return bg.stops.reduce((s, st) => s + hexLuma(st.color), 0) / bg.stops.length;
+}
+function hexRgb(hex) {
+  const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
+  const n = parseInt(h.slice(1), 16);
+  if (Number.isNaN(n)) return { r: 0.7, g: 0.7, b: 0.7 };
+  return { r: (n >> 16 & 255) / 255, g: (n >> 8 & 255) / 255, b: (n & 255) / 255 };
+}
+function backgroundRgb(spec) {
+  const bg = spec.background;
+  if (!bg || bg.type === "solid") return hexRgb(bg?.color ?? "#05050a");
+  const acc = bg.stops.reduce(
+    (s, st) => {
+      const c = hexRgb(st.color);
+      return { r: s.r + c.r, g: s.g + c.g, b: s.b + c.b };
+    },
+    { r: 0, g: 0, b: 0 }
+  );
+  const n = bg.stops.length || 1;
+  return { r: acc.r / n, g: acc.g / n, b: acc.b / n };
+}
+function colourSeparation(layer, sprite, bg) {
+  if (layer.blend === "lighter" || layer.blend === "screen") return sprite.luma;
+  const dr = sprite.rgb.r - bg.rgb.r;
+  const dg = sprite.rgb.g - bg.rgb.g;
+  const db = sprite.rgb.b - bg.rgb.b;
+  return Math.sqrt((dr * dr + dg * dg + db * db) / 3);
+}
+
+// src/advise.ts
+var LOW_CONTRAST_FLOOR = 0.05;
 function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
   const warnings = [];
   const w = viewport.width;
@@ -1661,6 +1725,8 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
   const countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
   const rng = createRng2(spec.seed ?? 42);
   const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale, countScale));
+  const bgLuma = backgroundLuma(spec);
+  const bgRgb = backgroundRgb(spec);
   let totalEntities = 0;
   let textLayerCount = 0;
   let motionLayerCount = 0;
@@ -1704,6 +1770,22 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
         });
       }
     }
+    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`
+        });
+      }
+    }
   }
   let totalCoverage = 0;
   for (let li = 0; li < spec.layers.length; li++) {
@@ -1896,6 +1978,7 @@ function describeScene(spec, options = {}) {
 import { createRng as createRng4 } from "@idle-screens/core";
 var GLOW_SPREAD = 2.4;
 var LINE_SALIENCE = 3.5;
+var GHOST_TAPS = 12;
 function buildScene(spec, opts) {
   const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
   const seed = opts.seed ?? spec.seed ?? 42;
@@ -1924,23 +2007,6 @@ function posOf(scene, e, t) {
   }
   return p;
 }
-function hexLuma(hex) {
-  const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
-  const n = parseInt(h.slice(1), 16);
-  if (Number.isNaN(n)) return 0.7;
-  const r = (n >> 16 & 255) / 255;
-  const g = (n >> 8 & 255) / 255;
-  const b = (n & 255) / 255;
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-function spriteLuma(layer, e) {
-  const s = layer.sprite;
-  if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
-    return hexLuma(s.colors?.[e.colorIndex] ?? s.color);
-  }
-  if (s.kind === "text") return hexLuma(s.color ?? "#e6e8ef");
-  return 0.75;
-}
 function textBox(s, e, p) {
   const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
   const fh = m ? Number(m[1]) : e.size;
@@ -1998,105 +2064,163 @@ function luminanceGrid(spec, opts = {}) {
     else if (blend === "multiply") cells[idx] = cur * (1 - a * (1 - lum));
     else cells[idx] = cur * (1 - a) + lum * a;
   };
-  for (const { layer, entities } of scene.layers) {
-    const lifeA = lifeAlphaAt(layer.life, t);
-    if (lifeA <= 0) continue;
-    for (const e of entities) {
-      const a = Math.min(1, alphaAt(e, t) * lifeA);
-      if (a <= 4e-3) continue;
-      const lum = spriteLuma(layer, e);
-      const p = posOf(scene, e, t);
-      const sz = sizeAt(e, t);
-      const s = layer.sprite;
-      if (s.kind === "streak") {
-        const heading = headingAt(e, t, w, h) ?? 0;
-        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;
-      if (s.kind === "text") {
-        const box = textBox(s, e, p);
-        centerX = box.cx;
-        centerY = box.cy;
-        halfX = box.halfX;
-        halfY = box.halfY;
-      }
-      const circular = s.kind === "circle" || s.kind === "ring";
-      const soft = s.kind === "circle" && !!s.soft;
-      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" ? 0.55 : 1;
+  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 - 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;
+          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 splatPass = (tPass, alphaScale) => {
+    for (const { layer, entities } of scene.layers) {
+      const lifeA = lifeAlphaAt(layer.life, tPass);
+      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 = sizeAt(e, tPass);
+        const s = layer.sprite;
+        if (s.kind === "streak") {
+          const heading = headingAt(e, tPass, w, h) ?? 0;
+          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;
+        if (s.kind === "text") {
+          const box = textBox(s, e, p);
+          centerX = box.cx;
+          centerY = box.cy;
+          halfX = box.halfX;
+          halfY = box.halfY;
+        }
+        const circular = s.kind === "circle" || s.kind === "ring";
+        const soft = s.kind === "circle" && !!s.soft;
+        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" ? 0.55 : 1;
+        for (let r = r0; r <= r1; r++) {
+          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, layer.blend);
             } else {
-              wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
+              compose(r * cols + c, lum, a * inkWeight, layer.blend);
             }
-            compose(r * cols + c, lum, a * wgt, layer.blend);
-          } else {
-            compose(r * cols + c, lum, a * inkWeight, layer.blend);
           }
         }
       }
-    }
-    if (layer.links) {
-      const positions = entities.map((e) => posOf(scene, e, t));
-      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 wgt = Math.min(1, (layer.links.width ?? 1) * scale / cellH) * la;
-      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);
+      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 wgt = Math.min(1, (layer.links.width ?? 1) * 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);
+          }
         }
       }
     }
-  }
+  };
+  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));
+    }
+  }
+  splatPass(t, 1);
   let sum = 0;
   let covered = 0;
   let devSum = 0;
@@ -2200,11 +2324,26 @@ function dominanceRanking(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
   const { w, h, scale } = scene;
-  const bgMean = (() => {
-    const bg = spec.background;
-    if (!bg || bg.type === "solid") return hexLuma(bg?.color ?? "#05050a");
-    return bg.stops.reduce((s, st) => s + hexLuma(st.color), 0) / bg.stops.length;
-  })();
+  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 = lifeAlphaAt(layer.life, t);
     let area = 0;
@@ -2225,6 +2364,14 @@ function dominanceRanking(spec, opts = {}) {
         entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
       } else entArea = sz * sz * 0.55;
       area += 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) {