@idle-screens/schema 3.12.0 → 3.12.1

package/dist/index.js

@@ -279,7 +279,13 @@ function lerpValue(from, to, k, specRoot = false, rootKey) {
   const walk = (a, b, key, root = false) => {
     if (typeof a === "number" && typeof b === "number") {
       const v = a + (b - a) * kk;
-      return key === "count" ? Math.max(1, Math.round(v)) : v;
+      if (key === "count") return Math.max(1, Math.round(v));
+      if (key === "octaves") return Math.round(v);
+      if (key === "quantize") {
+        const q = Math.round(v);
+        return q < 2 ? 0 : q;
+      }
+      return v;
     }
     if (typeof a === "string" && typeof b === "string" && HEX.test(a) && HEX.test(b)) {
       return lerpHex(a, b, kk);
@@ -2019,12 +2025,75 @@ function strokeTaper(u) {
 function strokeWidthPx(s, scale) {
   return Math.max(0.5, (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale);
 }
-function featherAlphas(steps, additive) {
-  const out = [];
-  for (let k = 1; k <= steps; k++) out.push(additive ? 1 / steps : 1 / (steps - k + 1));
-  return out;
+function featherRamp(u, feather) {
+  const band = Math.max(0, Math.min(1, feather)) / 2;
+  const d = Math.min(u, 1 - u);
+  if (band <= 0) return d >= 0 ? 1 : 0;
+  return Math.max(0, Math.min(1, d / band));
+}
+var FEATHER_MASK_SIZE = 128;
+function ribbonSides(pts, half) {
+  const n = pts.length;
+  const left = [];
+  const right = [];
+  if (n < 2) return { left, right };
+  const dir = (a, b) => {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const l = Math.hypot(dx, dy);
+    return l > 1e-9 ? { x: dx / l, y: dy / l } : { x: 1, y: 0 };
+  };
+  for (let i = 0; i < n; i++) {
+    const tIn = i > 0 ? dir(pts[i - 1], pts[i]) : dir(pts[0], pts[1]);
+    const tOut = i < n - 1 ? dir(pts[i], pts[i + 1]) : tIn;
+    let tx = tIn.x + tOut.x;
+    let ty = tIn.y + tOut.y;
+    const tl = Math.hypot(tx, ty);
+    if (tl < 1e-9) {
+      tx = tOut.x;
+      ty = tOut.y;
+    } else {
+      tx /= tl;
+      ty /= tl;
+    }
+    const hw = half[i] / Math.max(0.5, tx * tOut.x + ty * tOut.y);
+    const p = pts[i];
+    left.push({ x: p.x - ty * hw, y: p.y + tx * hw });
+    right.push({ x: p.x + ty * hw, y: p.y - tx * hw });
+  }
+  return { left, right };
+}
+function strokeOutline(pts, lw, taper = true) {
+  const n = pts.length;
+  if (n < 2) return [];
+  const half = (i) => Math.max(0.5, taper ? lw * strokeTaper(i / (n - 1)) : lw) / 2;
+  const dir = (a, b) => {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const l = Math.hypot(dx, dy);
+    return l > 1e-9 ? { x: dx / l, y: dy / l } : { x: 1, y: 0 };
+  };
+  const { left, right } = ribbonSides(pts, Array.from({ length: n }, (_, i) => half(i)));
+  const cap = (c, r, from) => {
+    const out = [];
+    const steps = 6;
+    for (let k = 1; k < steps; k++) {
+      const a = from - Math.PI * k / steps;
+      out.push({ x: c.x + Math.cos(a) * r, y: c.y + Math.sin(a) * r });
+    }
+    return out;
+  };
+  const endT = dir(pts[n - 2], pts[n - 1]);
+  const startT = dir(pts[0], pts[1]);
+  const endA = Math.atan2(endT.y, endT.x) + Math.PI / 2;
+  const startA = Math.atan2(startT.y, startT.x) - Math.PI / 2;
+  return [
+    ...left,
+    ...cap(pts[n - 1], half(n - 1), endA),
+    ...right.reverse(),
+    ...cap(pts[0], half(0), startA)
+  ];
 }
-var FEATHER_STEPS = 6;
 
 // src/simulate.ts
 function entityScales(spec, w, h) {
@@ -3088,6 +3157,79 @@ function screen(fp, pat, alpha, off, w, h) {
   p.restore();
 }
 
+// src/trail.ts
+function trailFillBudget(layerCount) {
+  return Math.max(4, Math.min(48, Math.floor(240 / Math.max(1, layerCount))));
+}
+function trailEchoes(trail, t, headAlpha, headSize, posAt, w, h, wrap2, fillBudget, minAlpha = 0, additive = false) {
+  const fade = trail.fade ?? 1;
+  const n = Math.min(Math.ceil(trail.length / 50), LIMITS.maxTrailSamples);
+  const alphaAtK = (k) => headAlpha * (1 - k * fade);
+  const radiusAtK = (k) => headSize / 2 * (1 - k * 0.7);
+  const jumps = (a, b) => wrap2 && (Math.abs(b.x - a.x) > w / 2 || Math.abs(b.y - a.y) > h / 2);
+  const head = posAt(t);
+  const base = [];
+  let prev = head;
+  for (let s = 1; s <= n; s++) {
+    const k = s / n;
+    const pastT = t - k * trail.length;
+    if (pastT < 0) break;
+    const pos = posAt(pastT);
+    if (jumps(prev, pos)) break;
+    prev = pos;
+    const a = alphaAtK(k);
+    if (a <= minAlpha) break;
+    const r = radiusAtK(k);
+    if (r < 0.2) break;
+    base.push({ t: pastT, x: pos.x, y: pos.y, k, alpha: a, r });
+  }
+  if (base.length === 0) return base;
+  const need = [];
+  let total = 0;
+  for (let i = 0; i < base.length; i++) {
+    const a = i === 0 ? head : base[i - 1];
+    const b = base[i];
+    const d = Math.hypot(b.x - a.x, b.y - a.y);
+    const m = d > b.r ? Math.ceil(d / b.r) - 1 : 0;
+    need.push(m);
+    total += m;
+  }
+  if (total === 0) return base;
+  const scale = total > fillBudget ? fillBudget / total : 1;
+  const out = [];
+  let last = head;
+  for (let i = 0; i < base.length; i++) {
+    const b = base[i];
+    const m = Math.floor(need[i] * scale);
+    if (m === 0) {
+      out.push(b);
+      last = b;
+      continue;
+    }
+    const a = i === 0 ? head : base[i - 1];
+    const spacing = Math.hypot(b.x - a.x, b.y - a.y) / (m + 1);
+    const share = (alpha, r) => {
+      const k = Math.min(1, spacing / (2 * r));
+      return additive ? alpha * k : 1 - Math.pow(1 - Math.min(1, alpha), k);
+    };
+    const t0 = i === 0 ? t : base[i - 1].t;
+    const k0 = i === 0 ? 0 : base[i - 1].k;
+    for (let j = 1; j <= m; j++) {
+      const f = j / (m + 1);
+      const tt = t0 + (b.t - t0) * f;
+      const k = k0 + (b.k - k0) * f;
+      const pos = posAt(tt);
+      if (jumps(last, pos)) continue;
+      last = pos;
+      const r = radiusAtK(k);
+      out.push({ t: tt, x: pos.x, y: pos.y, k, alpha: share(alphaAtK(k), r), r });
+    }
+    out.push({ ...b, alpha: share(b.alpha, b.r) });
+    last = b;
+  }
+  return out;
+}
+
 // src/compile.ts
 var DEFAULT_STEER_DUR = 1e3;
 function applyRetainedDeltas(spec, deltas) {
@@ -3285,6 +3427,15 @@ var SpecInstance = class {
   fieldShortSide;
   /** The `field` background's cached raster; null until a field is first painted. */
   field = null;
+  featherWhite = /* @__PURE__ */ new Map();
+  /** Per-entity pre-rendered feathered rects (see `blitFeather`), and the device pixels they hold. */
+  featherBlits = /* @__PURE__ */ new WeakMap();
+  featherBlitPx = 0;
+  featherBlitN = 0;
+  paintSeq = 0;
+  /** Per layer: ribbon area painted this frame (px²), and whether its trails ribbon (see ribbonAllowed). */
+  ribbonBudget = /* @__PURE__ */ new WeakMap();
+  featherTints = /* @__PURE__ */ new Map();
   /**
    * The presentation pass when this instance applies a `finish`: the
    * visible canvas plus the cached screen tiles. When set, `this.canvas` is
@@ -3449,36 +3600,81 @@ var SpecInstance = class {
     const trail = built.layer.trail;
     if (!trail) return;
     const { ctx, w, h } = this;
-    const fade = trail.fade ?? 1;
-    const n = Math.min(Math.ceil(trail.length / 50), LIMITS.maxTrailSamples);
     const headAlpha = alphaAt(e, t) * lifeA;
     const headSize = sizeAt(e, t);
     const sprite = built.layer.sprite;
+    const shaped = isShapedSprite(sprite) && sprite.kind !== "circle";
+    const isSoft = sprite.kind === "circle" && !!sprite.soft;
+    const hardCircle = sprite.kind === "circle" && !sprite.soft;
+    const ribbon = hardCircle && this.ribbonAllowed(built);
+    const posAt = (pt) => this.entityPos(e, pt, parentE);
+    const fill = shaped || hardCircle ? 0 : trailFillBudget(built.entities.length);
+    const echoes = trailEchoes(trail, t, headAlpha, headSize, posAt, w, h, built.layer.wrap !== false, fill, 0, built.layer.blend === "lighter");
+    if (echoes.length === 0) return;
+    const head = posAt(t);
+    if (hardCircle) {
+      const rb = this.ribbonBudget.get(built);
+      let prev = head;
+      let r0 = headSize / 2;
+      for (const ec of echoes) {
+        rb.area += Math.hypot(ec.x - prev.x, ec.y - prev.y) * (r0 + ec.r);
+        prev = ec;
+        r0 = ec.r;
+      }
+    }
+    if (shaped) {
+      for (const ec of echoes) this.drawEntity(built, e, ec.t, 1, parentE, void 0, { x: ec.x, y: ec.y, size: ec.r * 2, alpha: ec.alpha });
+      return;
+    }
     const resolvedColor = isShapedSprite(sprite) ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" || sprite.kind === "textBlock" ? sprite.color ?? "#e6e8ef" : "#e6e8ef";
-    const isSoft = sprite.kind === "circle" && sprite.soft;
-    const wrap2 = built.layer.wrap !== false;
-    const head = this.entityPos(e, t, parentE);
-    let prevX = head.x;
-    let prevY = head.y;
-    for (let s = 1; s <= n; s++) {
-      const k = s / n;
-      const pastT = t - k * trail.length;
-      if (pastT < 0) break;
-      const pos = this.entityPos(e, pastT, parentE);
-      if (wrap2) {
-        const dx = pos.x - prevX;
-        const dy = pos.y - prevY;
-        if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) break;
-      }
-      prevX = pos.x;
-      prevY = pos.y;
-      const a = headAlpha * (1 - k * fade);
-      if (a <= 0) break;
-      const r = headSize / 2 * (1 - k * 0.7);
-      if (r < 0.2) break;
-      ctx.globalAlpha = a;
+    if (ribbon) {
+      const pts = [head];
+      const radii = [headSize / 2];
+      const alphas = [headAlpha];
+      let prevT = t;
+      for (const ec of echoes) {
+        const p0 = pts[pts.length - 1];
+        const r0 = radii[radii.length - 1];
+        const a0 = alphas[alphas.length - 1];
+        const sub = Math.max(1, Math.min(8, Math.ceil(Math.hypot(ec.x - p0.x, ec.y - p0.y) / 12)));
+        for (let j = 1; j < sub; j++) {
+          const f = j / sub;
+          pts.push(posAt(prevT + (ec.t - prevT) * f));
+          radii.push(r0 + (ec.r - r0) * f);
+          alphas.push(a0 + (ec.alpha - a0) * f);
+        }
+        pts.push(ec);
+        radii.push(ec.r);
+        alphas.push(ec.alpha);
+        prevT = ec.t;
+      }
+      const { left, right } = ribbonSides(pts, radii);
+      ctx.fillStyle = resolvedColor;
+      const tol = Math.max(4e-3, headAlpha * 0.04);
+      let from = 0;
+      while (from < pts.length - 1) {
+        const a0 = alphas[from + 1];
+        let to = from + 1;
+        let sum = a0;
+        while (to < pts.length - 1 && Math.abs(alphas[to + 1] - a0) <= tol) {
+          sum += alphas[to + 1];
+          to++;
+        }
+        ctx.globalAlpha = sum / (to - from);
+        ctx.beginPath();
+        ctx.moveTo(left[from].x, left[from].y);
+        for (let i = from + 1; i <= to; i++) ctx.lineTo(left[i].x, left[i].y);
+        for (let i = to; i >= from; i--) ctx.lineTo(right[i].x, right[i].y);
+        ctx.closePath();
+        ctx.fill();
+        from = to;
+      }
+      return;
+    }
+    for (const ec of echoes) {
+      ctx.globalAlpha = ec.alpha;
       if (isSoft) {
-        const g = ctx.createRadialGradient(pos.x, pos.y, 0, pos.x, pos.y, r);
+        const g = ctx.createRadialGradient(ec.x, ec.y, 0, ec.x, ec.y, ec.r);
         g.addColorStop(0, resolvedColor);
         g.addColorStop(0.35, hexToRgba(resolvedColor, 0.75));
         g.addColorStop(1, hexToRgba(resolvedColor, 0));
@@ -3487,18 +3683,202 @@ var SpecInstance = class {
         ctx.fillStyle = resolvedColor;
       }
       ctx.beginPath();
-      ctx.arc(pos.x, pos.y, r, 0, Math.PI * 2);
+      ctx.arc(ec.x, ec.y, ec.r, 0, Math.PI * 2);
       ctx.fill();
     }
   }
-  drawEntity(built, e, t, lifeA, parentE, paint) {
+  /**
+   * Whether this layer's hard-circle trails draw as ribbons this frame. A
+   * ribbon paints its trail's whole length, so a layer of many fast, long
+   * trails can paint far more pixels than its dots did — under `lighter` on
+   * a CPU rasteriser that was 2.4× the frame time (60 trails, 3 s, 0.4/s).
+   * Past a tenth of the viewport's area in ribbon (measured on the
+   * previous frame) the layer falls back to the time-sample discs it always
+   * drew; it returns to ribbons below 70 % of that, so a layer near the line
+   * does not flicker between the two.
+   */
+  ribbonAllowed(built) {
+    let rb = this.ribbonBudget.get(built);
+    if (!rb) {
+      rb = { seq: this.paintSeq, area: 0, ribbon: true };
+      this.ribbonBudget.set(built, rb);
+    }
+    if (rb.seq !== this.paintSeq) {
+      const budget = 0.1 * this.w * this.h;
+      if (rb.ribbon && rb.area > budget) rb.ribbon = false;
+      else if (!rb.ribbon && rb.area < 0.7 * budget) rb.ribbon = true;
+      rb.seq = this.paintSeq;
+      rb.area = 0;
+    }
+    return rb.ribbon;
+  }
+  /** A fresh 2D canvas (DOM or Offscreen), or null where none can be made. */
+  makeCanvas(n) {
+    try {
+      const canvas = typeof document !== "undefined" ? document.createElement("canvas") : new OffscreenCanvas(n, n);
+      canvas.width = n;
+      canvas.height = n;
+      const c = canvas.getContext("2d");
+      return c ? { canvas, ctx: c } : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * A feathered rect from a per-entity bitmap of it, pre-rendered at device
+   * resolution with its rotation baked in, copied 1:1 at a whole-pixel
+   * offset. A smooth falloff is a sampled image draw — on a CPU rasteriser
+   * (a Raspberry Pi wall) ~3× the six flat fills it replaced, ~10× when
+   * rotated and stretched — while a 1:1 integer copy costs about one flat
+   * fill. The bitmap is rebuilt only when the rect's size, rotation or
+   * feather changes (in device pixels, to a quarter pixel / 0.06°), and
+   * re-tinted (one copy + one flat fill) only when its colour changes, so a
+   * drifting block or a colour glide stays cheap. A rect whose shape
+   * changes every frame (`grow`, `spin`), a canvas under a rotating or
+   * mirroring transform, or a scene past the 8 Mpx cache budget draws the
+   * stretched mask directly instead. Returns false when it did not draw.
+   */
+  blitFeather(e, p, sz, rh, rot, color2, feather) {
+    const ctx = this.ctx;
+    const m = typeof ctx.getTransform === "function" ? ctx.getTransform() : null;
+    if (!m || m.b !== 0 || m.c !== 0 || m.a <= 0 || m.d <= 0) return false;
+    const cos = Math.abs(Math.cos(rot));
+    const sin = Math.abs(Math.sin(rot));
+    const bw = Math.ceil((cos * sz + sin * rh) * m.a) + 2;
+    const bh = Math.ceil((sin * sz + cos * rh) * m.d) + 2;
+    const shapeKey = `${feather}|${Math.round(sz * m.a * 4)}|${Math.round(rh * m.d * 4)}|${Math.round(rot * 1e3)}|${bw}x${bh}`;
+    let b = this.featherBlits.get(e);
+    if (!b || b.shapeKey !== shapeKey) {
+      if (b) {
+        if (b.seenKey !== shapeKey) {
+          b.seenKey = shapeKey;
+          b.seenAt = this.paintSeq;
+        }
+        if (b.seenAt === this.paintSeq) return false;
+      }
+      const px = bw * bh;
+      const reuse = b && b.w === bw && b.h === bh;
+      if (!reuse && this.featherBlitPx + px - (b ? b.w * b.h : 0) > 8e6) return false;
+      const white = this.featherWhite.get(feather);
+      if (!white) return false;
+      const wc = reuse ? b.white : this.makeCanvas(1);
+      const tc = reuse ? b.tint : this.makeCanvas(1);
+      if (!wc || !tc) return false;
+      if (!reuse) {
+        wc.canvas.width = bw;
+        wc.canvas.height = bh;
+        tc.canvas.width = bw;
+        tc.canvas.height = bh;
+        this.featherBlitPx += px - (b ? b.w * b.h : 0);
+      }
+      const w2 = wc.ctx;
+      w2.setTransform(1, 0, 0, 1, 0, 0);
+      w2.clearRect(0, 0, bw, bh);
+      w2.translate(bw / 2, bh / 2);
+      w2.scale(m.a, m.d);
+      if (rot) w2.rotate(rot);
+      w2.imageSmoothingEnabled = true;
+      w2.drawImage(white, -sz / 2, -rh / 2, sz, rh);
+      w2.setTransform(1, 0, 0, 1, 0, 0);
+      b = { shapeKey, w: bw, h: bh, white: wc, tint: tc, tintKey: "", tintAt: 0, stagger: this.featherBlitN++ % 8, seenKey: shapeKey, seenAt: this.paintSeq };
+      this.featherBlits.set(e, b);
+    }
+    if (b.tintKey !== color2 && (b.tintKey === "" || this.paintSeq - b.tintAt >= 8)) {
+      const t2 = b.tint.ctx;
+      t2.setTransform(1, 0, 0, 1, 0, 0);
+      t2.globalCompositeOperation = "copy";
+      t2.drawImage(b.white.canvas, 0, 0);
+      t2.globalCompositeOperation = "source-in";
+      t2.fillStyle = color2;
+      t2.fillRect(0, 0, b.w, b.h);
+      t2.globalCompositeOperation = "source-over";
+      b.tintKey = color2;
+      b.tintAt = this.paintSeq - (b.stagger ?? 0);
+      b.stagger = 0;
+    }
+    const cx = m.a * p.x + m.e;
+    const cy = m.d * p.y + m.f;
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.drawImage(b.tint.canvas, Math.round(cx - b.w / 2), Math.round(cy - b.h / 2));
+    ctx.restore();
+    return true;
+  }
+  /**
+   * A feathered rect's mask in `color`: FEATHER_MASK_SIZE² texels of
+   * `featherRamp(u) × featherRamp(v)`, drawn stretched to the rect with
+   * smoothing on, so the falloff is continuous at any size (X383).
+   *
+   * The ramp itself is built ONCE per feather (a white alpha mask, the only
+   * per-pixel work). A colour is a cheap tint of it — clear, draw the mask,
+   * `source-in` fill — into a pooled canvas, cached per colour × feather.
+   * A colour glide or a palette larger than the pool re-tints a pooled
+   * canvas (three GPU draws) rather than rebuilding pixels in JS.
+   */
+  featherMask(color2, feather) {
+    const key = `${color2}|${feather}`;
+    const hit = this.featherTints.get(key);
+    if (hit) {
+      this.featherTints.delete(key);
+      this.featherTints.set(key, hit);
+      return hit.canvas;
+    }
+    const N = FEATHER_MASK_SIZE;
+    let white = this.featherWhite.get(feather);
+    if (!white) {
+      const made = this.makeCanvas(N);
+      if (!made) return null;
+      const img = made.ctx.createImageData(N, N);
+      const data = img.data;
+      const ramp = [];
+      for (let i = 0; i < N; i++) ramp.push(featherRamp((i + 0.5) / N, feather));
+      let o = 0;
+      for (let y = 0; y < N; y++) {
+        const ry = ramp[y];
+        for (let x = 0; x < N; x++) {
+          data[o++] = 255;
+          data[o++] = 255;
+          data[o++] = 255;
+          data[o++] = Math.round(255 * ry * ramp[x]);
+        }
+      }
+      made.ctx.putImageData(img, 0, 0);
+      if (this.featherWhite.size >= 8) this.featherWhite.delete(this.featherWhite.keys().next().value);
+      white = made.canvas;
+      this.featherWhite.set(feather, white);
+    }
+    let slot = null;
+    if (this.featherTints.size >= 48) {
+      const oldest = this.featherTints.keys().next().value;
+      slot = this.featherTints.get(oldest);
+      this.featherTints.delete(oldest);
+    } else {
+      slot = this.makeCanvas(N);
+      if (!slot) return null;
+    }
+    const tctx = slot.ctx;
+    tctx.globalCompositeOperation = "copy";
+    tctx.drawImage(white, 0, 0);
+    tctx.globalCompositeOperation = "source-in";
+    tctx.fillStyle = color2;
+    tctx.fillRect(0, 0, N, N);
+    tctx.globalCompositeOperation = "source-over";
+    this.featherTints.set(key, slot);
+    return slot.canvas;
+  }
+  /**
+   * Paint one entity at time `t`. `echo` paints a trail echo instead: the
+   * entity as it was at `t` (rotation, heading, values), but at the echo's
+   * position, size and alpha.
+   */
+  drawEntity(built, e, t, lifeA, parentE, paint, echo) {
     const { ctx } = this;
-    const p = this.entityPos(e, t, parentE);
+    const p = echo ? { x: echo.x, y: echo.y, flip: false } : this.entityPos(e, t, parentE);
     const sprite = paint?.sprite ?? built.layer.sprite;
-    const sz = sizeAt(e, t);
+    const sz = echo ? echo.size : sizeAt(e, t);
     const rot = rotationAt(e, t);
     const unitScale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
-    ctx.globalAlpha = alphaAt(e, t) * lifeA * (paint?.alpha ?? 1);
+    ctx.globalAlpha = echo ? echo.alpha : alphaAt(e, t) * lifeA * (paint?.alpha ?? 1);
     if (sprite.kind === "ring") {
       const r = sz / 2;
       const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
@@ -3529,23 +3909,18 @@ var SpecInstance = class {
     if (sprite.kind === "rect") {
       const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
       const rh = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz;
+      const feather = sprite.feather ?? 0;
+      const mask = feather > 0 ? this.featherMask(resolvedColor, feather) : null;
+      if (mask && this.blitFeather(e, p, sz, rh, rot, resolvedColor, feather)) return;
       ctx.save();
       ctx.translate(p.x, p.y);
       if (rot) ctx.rotate(rot);
       ctx.fillStyle = resolvedColor;
-      const feather = sprite.feather ?? 0;
-      if (feather > 0) {
-        const base = ctx.globalAlpha;
-        const additive = built.layer.blend === "lighter";
-        const alphas = featherAlphas(FEATHER_STEPS, additive);
-        for (let j = 1; j <= FEATHER_STEPS; j++) {
-          const f = 1 - feather * (j - 1) / FEATHER_STEPS;
-          const fw = sz * f;
-          const fh = rh * f;
-          ctx.globalAlpha = base * alphas[j - 1];
-          ctx.fillRect(-fw / 2, -fh / 2, fw, fh);
-        }
-        ctx.globalAlpha = base;
+      if (mask) {
+        const prevSmooth = ctx.imageSmoothingEnabled;
+        ctx.imageSmoothingEnabled = true;
+        ctx.drawImage(mask, -sz / 2, -rh / 2, sz, rh);
+        ctx.imageSmoothingEnabled = prevSmooth;
       } else {
         ctx.fillRect(-sz / 2, -rh / 2, sz, rh);
       }
@@ -3603,13 +3978,13 @@ var SpecInstance = class {
       ctx.lineCap = "round";
       ctx.lineJoin = "round";
       if (sprite.taper) {
-        for (let i = 1; i < pts.length; i++) {
-          ctx.lineWidth = Math.max(0.5, lw * strokeTaper((i - 0.5) / (pts.length - 1)));
-          ctx.beginPath();
-          ctx.moveTo(pts[i - 1].x, pts[i - 1].y);
-          ctx.lineTo(pts[i].x, pts[i].y);
-          ctx.stroke();
-        }
+        const outline = strokeOutline(pts, lw);
+        ctx.fillStyle = resolvedColor;
+        ctx.beginPath();
+        ctx.moveTo(outline[0].x, outline[0].y);
+        for (let i = 1; i < outline.length; i++) ctx.lineTo(outline[i].x, outline[i].y);
+        ctx.closePath();
+        ctx.fill();
       } else {
         ctx.lineWidth = lw;
         ctx.beginPath();
@@ -3863,6 +4238,7 @@ var SpecInstance = class {
    *  showing through — the ghosting smear. */
   paintFrame(t, bgAlpha) {
     const { ctx } = this;
+    this.paintSeq++;
     if (this.authored) this.resolveAuthored(t);
     if (!this.transparent) {
       ctx.globalAlpha = bgAlpha;
@@ -5300,31 +5676,36 @@ function luminanceGrid(spec, opts = {}) {
     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 splatTrail = (layer, e, tPass, lifeA, alphaScale, layerCount) => {
     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 headAlpha = alphaAt(e, tPass) * lifeA * alphaScale;
     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 echoes = trailEchoes(
+      trail,
+      tPass,
+      headAlpha,
+      headSize,
+      (pt) => posOf(scene, e, pt),
+      w,
+      h,
+      layer.wrap !== false,
+      // As the renderer: a shape echoes at its time samples only; circles fill
+      // (a hard circle's ribbon reads, on the coarse grid, as filled discs).
+      isShapedSprite(layer.sprite) && layer.sprite.kind !== "circle" ? 0 : trailFillBudget(layerCount),
+      4e-3,
+      layer.blend === "lighter"
+    );
+    for (const ec of echoes) {
+      const a = ec.alpha;
+      const rad = ec.r;
+      if (layer.sprite.kind === "polygon" && rad * 2 >= POLYGON_OUTLINE_CELLS * Math.min(cellW, cellH)) {
+        splatPolygonOutline(layer, layer.sprite, e, ec, rad * 2, Math.min(1, a), lum, ec.t);
+        continue;
+      }
+      const pos = ec;
       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));
@@ -5403,7 +5784,7 @@ function luminanceGrid(spec, opts = {}) {
       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);
+        splatTrail(layer, e, tPass, lifeA, alphaScale, entities.length);
         const a = Math.min(1, alphaAt(e, tPass) * lifeA) * alphaScale;
         if (a <= 4e-3) continue;
         const lum = spriteLuma(layer, e);
@@ -6354,7 +6735,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       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 });
+      textBoxes.push({ li, label, alpha, str, ...box, rawW: raw.x1 - raw.x0, rawH: raw.y1 - raw.y0 });
     }
   }
   const asFraction = (b) => ({
@@ -6409,6 +6790,45 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       });
     }
   }
+  const cellFlagged = /* @__PURE__ */ new Set();
+  for (let i = 0; i < textBoxes.length; i++) {
+    const a = textBoxes[i];
+    if (cellFlagged.has(a.li)) continue;
+    const layer = spec.layers[a.li];
+    const layout = layer.layout;
+    if (layout?.type !== "list" && layout?.type !== "table") continue;
+    for (let j = i + 1; j < textBoxes.length; j++) {
+      const b = textBoxes[j];
+      if (b.li !== a.li) 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 || ix * iy / smaller <= 0.1) continue;
+      cellFlagged.add(a.li);
+      const cells = textBoxes.filter((x) => x.li === a.li);
+      const dflt = scale === 1 ? LIMITS.defaultListGapPx : LIMITS.defaultListGap;
+      const g = layout.gap ?? dflt;
+      const gx = typeof g === "number" ? g : g.x ?? dflt;
+      const gy = typeof g === "number" ? g : g.y ?? dflt;
+      const cols = layout.type === "list" ? 1 : Math.max(1, Math.round(layout.columns));
+      const unitPx = (v) => scale === 1 ? v : v * scale;
+      const fromPx = (px) => scale === 1 ? Math.ceil(px) : Math.ceil(px / scale * 100) / 100;
+      const maxW = cells.reduce((m, c) => Math.max(m, c.rawW), 0);
+      const maxH = cells.reduce((m, c) => Math.max(m, c.rawH), 0);
+      const fixes = [];
+      const across = cols > 1 && maxW > unitPx(gx);
+      if (across) fixes.push(`its labels are up to ~${Math.round(maxW)}px wide against a ${Math.round(unitPx(gx))}px column pitch (gap${typeof g === "number" ? "" : ".x"} ${gx}) \u2014 raise gap${typeof g === "number" ? "" : ".x"} to \u2265 ${fromPx(maxW * 1.1)}`);
+      if (!across || maxH > unitPx(gy)) fixes.push(`rows are ~${Math.round(maxH)}px tall against a ${Math.round(unitPx(gy))}px row pitch (gap${typeof g === "number" ? "" : ".y"} ${gy}) \u2014 raise gap${typeof g === "number" ? "" : ".y"} to \u2265 ${fromPx(maxH * 1.1)}`);
+      warnings.push({
+        path: `layers[${a.li}].layout.gap`,
+        code: "layout-text-overlap",
+        message: `${a.label} cells overlap at ${w}\xD7${h}: a ${layout.type}'s \`gap\` is the pitch between cell anchors, not the space between cells; ${fixes.join("; and ")}, or shrink the text`,
+        boxes: [asFraction(a), asFraction(b)]
+      });
+      break;
+    }
+  }
   const readFlagged = /* @__PURE__ */ new Set();
   for (const b of textBoxes) {
     if (readFlagged.has(b.li)) continue;