@idle-screens/schema 3.4.5 → 3.6.0

package/dist/index.js

@@ -55,7 +55,30 @@ var LIMITS = {
   minSegmentDuration: 1e3,
   // ms — flash-safety floor: segment cuts are luminance transitions
   maxTransitionDur: 5e3,
-  minTransitionDur: 200
+  minTransitionDur: 200,
+  minEmitEvery: 1e3,
+  // ms — at most one event per second per entity (flash safety)
+  maxEmitEvery: 6e5,
+  // ms — ten minutes; longer silences than that are `life.enter`
+  minEmitLife: 500,
+  // ms — an event is a smooth envelope, never a cut
+  maxEmitGrow: 8,
+  // × base size across an event window
+  minClockedPeriod: 1e3,
+  // ms — a `clock`ed layer breathes in unison, so 1 Hz not 2
+  minClockRate: 0.1,
+  maxClockRate: 4,
+  defaultListGap: 0.06,
+  // viewport units between list/table cells (40 px in px specs)
+  defaultListGapPx: 40,
+  minPolygonSides: 3,
+  maxPolygonSides: 12,
+  maxShapePoints: 24,
+  // polygon.points / stroke.points
+  minEaseTau: 100,
+  // ms
+  maxEaseTau: 12e4
+  // ms
 };
 
 // src/steer.ts
@@ -173,12 +196,14 @@ function structuralSignature(spec) {
         l.spin,
         l.grow,
         l.layout,
+        l.emit,
+        l.clock,
         l.sprite.kind,
         // Dimensional draws baked into entities: radius (circle/ring), length
         // (streak), width+aspect (rect), palette pick (all shaped sprites).
         s.radius,
         s.length,
-        l.sprite.kind === "rect" ? [s.width, s.aspect] : void 0,
+        l.sprite.kind === "rect" ? [s.width, s.aspect] : l.sprite.kind === "bar" ? [s.length, s.thickness] : void 0,
         Array.isArray(s.colors) ? s.colors.length : void 0,
         s.colorWeights,
         l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : l.sprite.kind === "textBlock" ? [l.sprite.fontSize] : void 0
@@ -193,7 +218,7 @@ var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isStr = (v) => typeof v === "string";
 var isNum = (v) => typeof v === "number" && Number.isFinite(v);
 var isRange = (v) => Array.isArray(v) && v.length === 2 && isNum(v[0]) && isNum(v[1]) && v[0] <= v[1];
-var KNOWN_TOP = /* @__PURE__ */ new Set(["schemaVersion", "id", "label", "seed", "motionIntensity", "units", "referenceViewport", "background", "layers", "ghosting"]);
+var KNOWN_TOP = /* @__PURE__ */ new Set(["schemaVersion", "id", "label", "seed", "motionIntensity", "density", "units", "referenceViewport", "background", "layers", "ghosting"]);
 var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "count",
   "sprite",
@@ -212,28 +237,33 @@ var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "trail",
   "links",
   "layout",
-  "life"
+  "life",
+  "emit",
+  "clock"
 ]);
 var KNOWN_CIRCLE = /* @__PURE__ */ new Set(["kind", "radius", "color", "soft", "colors", "colorWeights"]);
 var KNOWN_RING = /* @__PURE__ */ new Set(["kind", "radius", "color", "width", "colors", "colorWeights"]);
 var KNOWN_STREAK = /* @__PURE__ */ new Set(["kind", "length", "color", "width", "colors", "colorWeights"]);
-var KNOWN_RECT = /* @__PURE__ */ new Set(["kind", "width", "aspect", "color", "colors", "colorWeights"]);
+var KNOWN_RECT = /* @__PURE__ */ new Set(["kind", "width", "aspect", "color", "feather", "colors", "colorWeights"]);
+var KNOWN_BAR = /* @__PURE__ */ new Set(["kind", "values", "length", "thickness", "color", "max", "direction", "colors", "colorWeights"]);
+var KNOWN_POLYGON = /* @__PURE__ */ new Set(["kind", "radius", "color", "sides", "points", "soft", "colors", "colorWeights"]);
+var KNOWN_STROKE = /* @__PURE__ */ new Set(["kind", "length", "points", "color", "width", "curve", "taper", "orient", "colors", "colorWeights"]);
 var KNOWN_EMOJI = /* @__PURE__ */ new Set(["kind", "glyphs", "cycle"]);
 var KNOWN_TEXT = /* @__PURE__ */ new Set(["kind", "strings", "color", "font", "align", "baseline", "maxWidth", "cycle"]);
 var KNOWN_TEXT_BLOCK = /* @__PURE__ */ new Set(["kind", "text", "maxWidth", "fontSize", "lineHeight", "align", "color", "reveal"]);
-var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret"]);
+var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret", "fade"]);
 var KNOWN_REVEAL_CARET = /* @__PURE__ */ new Set(["blink", "color"]);
-var KNOWN_DRIFT = /* @__PURE__ */ new Set(["type", "speed", "angle", "bidirectional", "bob"]);
-var KNOWN_RISE = /* @__PURE__ */ new Set(["type", "speed", "sway"]);
+var KNOWN_DRIFT = /* @__PURE__ */ new Set(["type", "speed", "angle", "bidirectional", "bob", "ease"]);
+var KNOWN_RISE = /* @__PURE__ */ new Set(["type", "speed", "sway", "ease"]);
 var KNOWN_BOUNCE = /* @__PURE__ */ new Set(["type", "speed"]);
 var KNOWN_STATIC = /* @__PURE__ */ new Set(["type"]);
 var KNOWN_ORBIT = /* @__PURE__ */ new Set(["type", "speed", "radius", "center"]);
-var KNOWN_WANDER = /* @__PURE__ */ new Set(["type", "speed", "angle", "meander", "coherence"]);
+var KNOWN_WANDER = /* @__PURE__ */ new Set(["type", "speed", "angle", "meander", "coherence", "ease"]);
 var KNOWN_WARP = /* @__PURE__ */ new Set(["type", "speed", "center"]);
 var KNOWN_PATH = /* @__PURE__ */ new Set(["type", "points", "duration", "curve", "closed", "scatter"]);
 var KNOWN_BG_SOLID = /* @__PURE__ */ new Set(["type", "color"]);
 var KNOWN_BG_GRADIENT = /* @__PURE__ */ new Set(["type", "stops", "band", "drift"]);
-var LAYER_PROPS_ON_SPRITE = /* @__PURE__ */ new Set(["blend", "trail", "alpha", "pulse", "spin", "grow", "region", "links", "flip", "wrap", "key"]);
+var LAYER_PROPS_ON_SPRITE = /* @__PURE__ */ new Set(["blend", "trail", "alpha", "pulse", "spin", "grow", "region", "links", "flip", "wrap", "key", "emit", "clock", "life", "layout"]);
 function unknownKeys(obj, known) {
   return Object.keys(obj).filter((k) => !known.has(k));
 }
@@ -263,6 +293,9 @@ function validateSpec(spec) {
   if (spec.motionIntensity !== void 0 && !["calm", "moderate", "energetic"].includes(spec.motionIntensity)) {
     err("motionIntensity", "must be calm | moderate | energetic");
   }
+  if (spec.density !== void 0 && !["sparse", "normal", "dense"].includes(spec.density)) {
+    err("density", "must be sparse | normal | dense");
+  }
   if (spec.units !== void 0 && spec.units !== "px" && spec.units !== "viewport") {
     err("units", "must be 'px' | 'viewport'");
   }
@@ -379,7 +412,10 @@ function validateLayer(layer, path, err, warn, spec) {
     } else {
       if (layer.position.x < 0 || layer.position.x > 1) err(`${path}.position.x`, "must be 0..1");
       if (layer.position.y < 0 || layer.position.y > 1) err(`${path}.position.y`, "must be 0..1");
-      if (isNum(layer.count) && layer.count !== 1) err(`${path}.position`, "position requires count: 1");
+      const dataLayout = isObj(layer.layout) && (layer.layout.type === "list" || layer.layout.type === "table");
+      if (isNum(layer.count) && layer.count !== 1 && !dataLayout) {
+        err(`${path}.position`, "position requires count: 1 \u2014 or a layout of type 'list' / 'table', where it anchors the whole block");
+      }
     }
   }
   if (layer.region !== void 0) {
@@ -468,8 +504,37 @@ function validateLayer(layer, path, err, warn, spec) {
     }
   }
   if (layer.layout !== void 0) {
-    if (!isObj(layer.layout) || layer.layout.type !== "grid") {
-      err(`${path}.layout`, "must be an object with type: 'grid'");
+    if (isObj(layer.layout) && (layer.layout.type === "list" || layer.layout.type === "table")) {
+      const lay = layer.layout;
+      if (lay.type === "table" && (!isNum(lay.columns) || !Number.isInteger(lay.columns) || lay.columns < 1 || lay.columns > LIMITS.maxGridColumns)) {
+        err(`${path}.layout.columns`, `must be an integer 1..${LIMITS.maxGridColumns}`);
+      }
+      const gapOk = (v) => isNum(v) && v > 0;
+      if (lay.gap !== void 0) {
+        if (isNum(lay.gap)) {
+          if (!gapOk(lay.gap)) err(`${path}.layout.gap`, "must be > 0 (viewport units of min(w,h), or px)");
+        } else if (lay.type === "table" && isObj(lay.gap)) {
+          if (lay.gap.x !== void 0 && !gapOk(lay.gap.x)) err(`${path}.layout.gap.x`, "must be > 0");
+          if (lay.gap.y !== void 0 && !gapOk(lay.gap.y)) err(`${path}.layout.gap.y`, "must be > 0");
+          for (const k of unknownKeys(lay.gap, /* @__PURE__ */ new Set(["x", "y"]))) {
+            warn(`${path}.layout.gap.${k}`, "unknown-property", `unknown gap property '${k}' \u2014 will be ignored`);
+          }
+        } else {
+          err(`${path}.layout.gap`, lay.type === "table" ? "must be a number > 0 or { x?, y? }" : "must be a number > 0");
+        }
+      }
+      for (const k of unknownKeys(lay, new Set(lay.type === "list" ? ["type", "gap"] : ["type", "columns", "gap"]))) {
+        warn(`${path}.layout.${k}`, "unknown-property", `unknown layout property '${k}' \u2014 will be ignored`);
+      }
+      const sp = layer.sprite;
+      if (isObj(sp) && isNum(layer.count)) {
+        const variants = sp.kind === "text" && Array.isArray(sp.strings) ? sp.strings.length : sp.kind === "emoji" && Array.isArray(sp.glyphs) ? sp.glyphs.length : sp.kind === "bar" && Array.isArray(sp.values) ? sp.values.length : null;
+        if (variants !== null && variants !== layer.count) {
+          warn(`${path}.count`, "list-length-mismatch", `count is ${layer.count} but the sprite carries ${variants} ${sp.kind === "bar" ? "values" : "variants"} \u2014 a ${lay.type} layout reads them in order, so they cycle or go unused`);
+        }
+      }
+    } else if (!isObj(layer.layout) || layer.layout.type !== "grid") {
+      err(`${path}.layout`, "must be an object with type: 'grid' | 'list' | 'table'");
     } else {
       if (layer.layout.columns !== void 0 && (!isNum(layer.layout.columns) || !Number.isInteger(layer.layout.columns) || layer.layout.columns < 1 || layer.layout.columns > LIMITS.maxGridColumns)) {
         err(`${path}.layout.columns`, `must be an integer 1..${LIMITS.maxGridColumns}`);
@@ -519,6 +584,64 @@ function validateLayer(layer, path, err, warn, spec) {
       }
     }
   }
+  if (layer.emit !== void 0) {
+    if (!isObj(layer.emit)) err(`${path}.emit`, "must be an object { every, life, jitter?, grow? }");
+    else {
+      const em = layer.emit;
+      if (!isNum(em.every) || em.every < LIMITS.minEmitEvery || em.every > LIMITS.maxEmitEvery) {
+        err(`${path}.emit.every`, `must be ${LIMITS.minEmitEvery}..${LIMITS.maxEmitEvery} ms (at most one event per second per entity)`);
+      }
+      if (!isNum(em.life) || em.life < LIMITS.minEmitLife) {
+        err(`${path}.emit.life`, `must be >= ${LIMITS.minEmitLife} ms (an event is a smooth envelope, never a cut)`);
+      } else if (isNum(em.every) && em.life > em.every) {
+        err(`${path}.emit.life`, "must be <= emit.every (the visible window cannot outlast its period)");
+      }
+      if (em.jitter !== void 0 && (!isNum(em.jitter) || em.jitter < 0 || em.jitter > 1)) {
+        err(`${path}.emit.jitter`, "must be 0..1 (0 = evenly staggered, 1 = scattered by a fixed sequence)");
+      }
+      if (em.grow !== void 0) {
+        if (!Array.isArray(em.grow) || em.grow.length !== 2 || !isNum(em.grow[0]) || !isNum(em.grow[1])) {
+          err(`${path}.emit.grow`, "must be [from, to] size multipliers");
+        } else if (em.grow[0] < 0 || em.grow[1] < 0 || em.grow[0] > LIMITS.maxEmitGrow || em.grow[1] > LIMITS.maxEmitGrow) {
+          err(`${path}.emit.grow`, `each multiplier must be 0..${LIMITS.maxEmitGrow}`);
+        }
+      }
+      if (em.jitter === 0 && isNum(em.every) && isNum(em.life) && isNum(layer.count) && layer.count > 1 && em.life > em.every / layer.count) {
+        warn(`${path}.emit.life`, "emit-overlap", `jitter 0 staggers ${layer.count} entities ${(em.every / layer.count).toFixed(0)} ms apart but each stays lit ${em.life} ms \u2014 windows overlap, so more than one event is visible at a time. Shorten life or lengthen every`);
+      }
+      for (const k of unknownKeys(em, /* @__PURE__ */ new Set(["every", "life", "jitter", "grow"]))) {
+        warn(`${path}.emit.${k}`, "unknown-property", `unknown emit property '${k}' \u2014 will be ignored`);
+      }
+    }
+  }
+  if (layer.clock !== void 0) {
+    if (!isObj(layer.clock)) err(`${path}.clock`, "must be an object { phase?, rate? }");
+    else {
+      const ck = layer.clock;
+      if (ck.phase !== void 0 && (!isNum(ck.phase) || ck.phase < 0 || ck.phase > 1)) {
+        err(`${path}.clock.phase`, "must be 0..1 (turns)");
+      }
+      const rate = ck.rate === void 0 ? 1 : ck.rate;
+      if (!isNum(rate) || rate < LIMITS.minClockRate || rate > LIMITS.maxClockRate) {
+        err(`${path}.clock.rate`, `must be ${LIMITS.minClockRate}..${LIMITS.maxClockRate}`);
+      } else {
+        const floor = LIMITS.minClockedPeriod * rate;
+        if (isObj(layer.pulse) && isNum(layer.pulse.period) && layer.pulse.period < floor) {
+          err(`${path}.pulse.period`, `must be >= ${floor} ms when the layer has a clock (period / rate >= ${LIMITS.minClockedPeriod} \u2014 the whole layer breathes in unison)`);
+        }
+        if (isObj(layer.grow) && isNum(layer.grow.period) && layer.grow.period < floor) {
+          err(`${path}.grow.period`, `must be >= ${floor} ms when the layer has a clock (period / rate >= ${LIMITS.minClockedPeriod})`);
+        }
+        const sp = layer.sprite;
+        if (isObj(sp) && isObj(sp.cycle) && isNum(sp.cycle.period) && sp.cycle.period < floor) {
+          err(`${path}.sprite.cycle.period`, `must be >= ${floor} ms when the layer has a clock (period / rate >= ${LIMITS.minClockedPeriod})`);
+        }
+      }
+      for (const k of unknownKeys(ck, /* @__PURE__ */ new Set(["phase", "rate"]))) {
+        warn(`${path}.clock.${k}`, "unknown-property", `unknown clock property '${k}' \u2014 will be ignored`);
+      }
+    }
+  }
   validateSprite(layer.sprite, `${path}.sprite`, err, warn);
   validateMotion(layer.motion, `${path}.motion`, err, warn, spec);
 }
@@ -571,6 +694,45 @@ function validateSprite(sprite, path, err, warn) {
     if (sprite.aspect !== void 0 && (!isRange(sprite.aspect) || sprite.aspect[0] <= 0)) {
       err(`${path}.aspect`, "must be a [min,max] range of positive height/width ratios");
     }
+    if (sprite.feather !== void 0 && (!isNum(sprite.feather) || sprite.feather < 0 || sprite.feather > 1)) {
+      err(`${path}.feather`, "must be 0..1 (fraction of the half-size that fades out)");
+    }
+    color(sprite.color, `${path}.color`, err);
+    validatePalette(sprite, path, err);
+  } else if (sprite.kind === "bar") {
+    knownSet = KNOWN_BAR;
+    if (!Array.isArray(sprite.values) || sprite.values.length === 0 || sprite.values.length > LIMITS.maxPerLayer || !sprite.values.every((v) => isNum(v) && v >= 0)) {
+      err(`${path}.values`, `must be 1..${LIMITS.maxPerLayer} numbers >= 0`);
+    }
+    if (!isNum(sprite.length) || sprite.length <= 0) err(`${path}.length`, "must be > 0 (full-scale bar length)");
+    if (!isNum(sprite.thickness) || sprite.thickness <= 0) err(`${path}.thickness`, "must be > 0");
+    if (sprite.max !== void 0 && (!isNum(sprite.max) || sprite.max <= 0)) err(`${path}.max`, "must be > 0");
+    if (sprite.direction !== void 0 && !["right", "left", "up", "down"].includes(sprite.direction)) {
+      err(`${path}.direction`, "must be 'right' | 'left' | 'up' | 'down'");
+    }
+    color(sprite.color, `${path}.color`, err);
+    validatePalette(sprite, path, err);
+  } else if (sprite.kind === "polygon") {
+    knownSet = KNOWN_POLYGON;
+    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px (circumradius)");
+    if (sprite.sides !== void 0 && sprite.points !== void 0) {
+      err(`${path}.sides`, "use sides (a regular polygon) or points (a custom one), not both");
+    }
+    if (sprite.sides !== void 0 && (!isNum(sprite.sides) || !Number.isInteger(sprite.sides) || sprite.sides < LIMITS.minPolygonSides || sprite.sides > LIMITS.maxPolygonSides)) {
+      err(`${path}.sides`, `must be an integer ${LIMITS.minPolygonSides}..${LIMITS.maxPolygonSides}`);
+    }
+    if (sprite.points !== void 0) validateShapePoints(sprite.points, `${path}.points`, 3, err);
+    if (sprite.soft !== void 0 && typeof sprite.soft !== "boolean") err(`${path}.soft`, "must be a boolean");
+    color(sprite.color, `${path}.color`, err);
+    validatePalette(sprite, path, err);
+  } else if (sprite.kind === "stroke") {
+    knownSet = KNOWN_STROKE;
+    if (!isRange(sprite.length) || sprite.length[0] <= 0) err(`${path}.length`, "must be a [min,max] range of positive px (the mark's bounding size)");
+    validateShapePoints(sprite.points, `${path}.points`, 2, err);
+    if (sprite.width !== void 0 && (!isNum(sprite.width) || sprite.width <= 0)) err(`${path}.width`, "must be > 0");
+    if (sprite.curve !== void 0 && sprite.curve !== "smooth" && sprite.curve !== "linear") err(`${path}.curve`, "must be 'smooth' | 'linear'");
+    if (sprite.taper !== void 0 && typeof sprite.taper !== "boolean") err(`${path}.taper`, "must be a boolean");
+    if (sprite.orient !== void 0 && typeof sprite.orient !== "boolean") err(`${path}.orient`, "must be a boolean");
     color(sprite.color, `${path}.color`, err);
     validatePalette(sprite, path, err);
   } else if (sprite.kind === "textBlock") {
@@ -604,8 +766,11 @@ function validateSprite(sprite, path, err, warn) {
         if (rv.progress !== void 0 && (!isNum(rv.progress) || rv.progress < 0 || rv.progress > 1)) {
           err(`${path}.reveal.progress`, "must be a number between 0 and 1");
         }
-        if (rv.mode !== void 0 && !["typewriter", "word", "line"].includes(rv.mode)) {
-          err(`${path}.reveal.mode`, "must be 'typewriter' | 'word' | 'line'");
+        if (rv.mode !== void 0 && !["typewriter", "word", "line", "glyphFade"].includes(rv.mode)) {
+          err(`${path}.reveal.mode`, "must be 'typewriter' | 'word' | 'line' | 'glyphFade'");
+        }
+        if (rv.fade !== void 0 && (!isNum(rv.fade) || rv.fade <= 0 || rv.fade > 1)) {
+          err(`${path}.reveal.fade`, "must be between 0 (exclusive) and 1 (fraction of progress)");
         }
         if (rv.speed !== void 0 && (!isNum(rv.speed) || rv.speed < 0 || rv.speed > LIMITS.maxRevealSpeed)) {
           err(`${path}.reveal.speed`, `must be between 0 and ${LIMITS.maxRevealSpeed} (graphemes/sec)`);
@@ -627,7 +792,7 @@ function validateSprite(sprite, path, err, warn) {
       }
     }
   } else {
-    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect | textBlock");
+    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect | bar | polygon | stroke | textBlock");
     return;
   }
   for (const k of unknownKeys(sprite, knownSet)) {
@@ -680,6 +845,7 @@ function validateMotion(motion, path, err, warn, spec) {
     if (motion.angle !== void 0 && !isNum(motion.angle)) err(`${path}.angle`, "must be a number (degrees)");
     if (motion.bidirectional !== void 0 && typeof motion.bidirectional !== "boolean") err(`${path}.bidirectional`, "must be a boolean");
     if (motion.bob !== void 0 && !isNum(motion.bob)) err(`${path}.bob`, "must be a number");
+    validateEase(motion.ease, `${path}.ease`, err, warn);
     if (isRange(motion.speed) && motion.speed[1] < 1 && !isViewport) {
       warn(`${path}.speed`, "near-zero-speed", `max speed is ${motion.speed[1]} px/sec \u2014 entities will appear frozen. Typical range: 10\u2013200 px/sec`);
     }
@@ -687,6 +853,7 @@ function validateMotion(motion, path, err, warn, spec) {
     knownSet = KNOWN_RISE;
     speedOk(motion.speed, `${path}.speed`);
     if (motion.sway !== void 0 && !isNum(motion.sway)) err(`${path}.sway`, "must be a number");
+    validateEase(motion.ease, `${path}.ease`, err, warn);
     if (isRange(motion.speed) && motion.speed[1] < 1 && !isViewport) {
       warn(`${path}.speed`, "near-zero-speed", `max speed is ${motion.speed[1]} px/sec \u2014 entities will appear frozen. Typical range: 5\u201380 px/sec`);
     }
@@ -736,6 +903,7 @@ function validateMotion(motion, path, err, warn, spec) {
     }
   } else if (motion.type === "wander") {
     knownSet = KNOWN_WANDER;
+    validateEase(motion.ease, `${path}.ease`, err, warn);
     speedOk(motion.speed, `${path}.speed`);
     if (motion.angle !== void 0 && !isNum(motion.angle)) err(`${path}.angle`, "must be a number (degrees)");
     const meanderCap = isViewport ? LIMITS.maxMeander / refVp : LIMITS.maxMeander;
@@ -787,6 +955,28 @@ function validateMotion(motion, path, err, warn, spec) {
     warn(`${path}.${k}`, "unknown-property", `unknown motion property '${k}' \u2014 will be ignored`);
   }
 }
+function validateShapePoints(points, path, min, err) {
+  if (!Array.isArray(points) || points.length < min || points.length > LIMITS.maxShapePoints) {
+    return err(path, `must be ${min}..${LIMITS.maxShapePoints} [x, y] pairs in unit coordinates (-1..1)`);
+  }
+  for (let i = 0; i < points.length; i++) {
+    const pt = points[i];
+    if (!Array.isArray(pt) || pt.length !== 2 || !isNum(pt[0]) || !isNum(pt[1]) || Math.abs(pt[0]) > 1 || Math.abs(pt[1]) > 1) {
+      err(`${path}[${i}]`, "must be an [x, y] pair with each coordinate in -1..1");
+    }
+  }
+}
+function validateEase(ease, path, err, warn) {
+  if (ease === void 0) return;
+  if (!isObj(ease)) return err(path, "must be an object { type: 'settle' | 'buoyant', tau }");
+  if (ease.type !== "settle" && ease.type !== "buoyant") err(`${path}.type`, "must be 'settle' | 'buoyant'");
+  if (!isNum(ease.tau) || ease.tau < LIMITS.minEaseTau || ease.tau > LIMITS.maxEaseTau) {
+    err(`${path}.tau`, `must be ${LIMITS.minEaseTau}..${LIMITS.maxEaseTau} ms`);
+  }
+  for (const k of unknownKeys(ease, /* @__PURE__ */ new Set(["type", "tau"]))) {
+    warn(`${path}.${k}`, "unknown-property", `unknown ease property '${k}' \u2014 will be ignored`);
+  }
+}
 function assertValidSpec(spec) {
   const r = validateSpec(spec);
   if (!r.valid) {
@@ -904,6 +1094,110 @@ ${r.errors.map((e) => `  ${e.path || "<root>"}: ${e.message}`).join("\n")}`);
   return seq;
 }
 
+// src/shapes.ts
+function isShapedSprite(s) {
+  return s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect" || s.kind === "polygon" || s.kind === "stroke" || s.kind === "bar";
+}
+function barFraction(s, index) {
+  const n = s.values.length;
+  if (n === 0) return 0;
+  const v = s.values[(index % n + n) % n] ?? 0;
+  const max = s.max ?? s.values.reduce((m, x) => Math.max(m, x), 0);
+  if (!(max > 0)) return 0;
+  return Math.max(0, Math.min(1, v / max));
+}
+function barBox(direction, len, thick) {
+  switch (direction) {
+    case "left":
+      return { cx: -len / 2, cy: 0, halfX: len / 2, halfY: thick / 2 };
+    case "up":
+      return { cx: 0, cy: -len / 2, halfX: thick / 2, halfY: len / 2 };
+    case "down":
+      return { cx: 0, cy: len / 2, halfX: thick / 2, halfY: len / 2 };
+    default:
+      return { cx: len / 2, cy: 0, halfX: len / 2, halfY: thick / 2 };
+  }
+}
+var DEFAULT_POLYGON_SIDES = 6;
+var STROKE_SAMPLES = 24;
+function polygonPoints(s, radius) {
+  if (s.points && s.points.length >= 3) {
+    return s.points.map(([x, y]) => ({ x: x * radius, y: y * radius }));
+  }
+  const n = Math.max(3, Math.round(s.sides ?? DEFAULT_POLYGON_SIDES));
+  const out = [];
+  for (let k = 0; k < n; k++) {
+    const a = -Math.PI / 2 + 2 * Math.PI * k / n;
+    out.push({ x: Math.cos(a) * radius, y: Math.sin(a) * radius });
+  }
+  return out;
+}
+function polygonArea(pts) {
+  let a = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i];
+    const q = pts[(i + 1) % pts.length];
+    a += p.x * q.y - q.x * p.y;
+  }
+  return Math.abs(a) / 2;
+}
+function polygonFill(s, radius) {
+  if (radius <= 0) return 0;
+  const disc = Math.PI * radius * radius;
+  return Math.min(1, polygonArea(polygonPoints(s, radius)) / disc);
+}
+function catmullRom(p0, p1, p2, p3, u) {
+  const u2 = u * u;
+  const u3 = u2 * u;
+  return 0.5 * (2 * p1 + (-p0 + p2) * u + (2 * p0 - 5 * p1 + 4 * p2 - p3) * u2 + (-p0 + 3 * p1 - 3 * p2 + p3) * u3);
+}
+function strokeSamples(s, halfSize, n) {
+  const pts = s.points.map(([x, y]) => ({ x: x * halfSize, y: y * halfSize }));
+  const m = pts.length;
+  if (m < 2) return pts;
+  const smooth = s.curve !== "linear" && m >= 3;
+  const segs = m - 1;
+  n = n ?? Math.max(STROKE_SAMPLES, segs * 6 + 1);
+  const at = (k) => pts[Math.max(0, Math.min(m - 1, k))];
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const u = i / (n - 1) * segs;
+    const seg = Math.min(segs - 1, Math.floor(u));
+    const local = u - seg;
+    const p1 = at(seg);
+    const p2 = at(seg + 1);
+    if (!smooth) {
+      out.push({ x: p1.x + (p2.x - p1.x) * local, y: p1.y + (p2.y - p1.y) * local });
+    } else {
+      const p0 = at(seg - 1);
+      const p3 = at(seg + 2);
+      out.push({ x: catmullRom(p0.x, p1.x, p2.x, p3.x, local), y: catmullRom(p0.y, p1.y, p2.y, p3.y, local) });
+    }
+  }
+  return out;
+}
+function pathLength(pts) {
+  let l = 0;
+  for (let i = 1; i < pts.length; i++) {
+    const dx = pts[i].x - pts[i - 1].x;
+    const dy = pts[i].y - pts[i - 1].y;
+    l += Math.sqrt(dx * dx + dy * dy);
+  }
+  return l;
+}
+function strokeTaper(u) {
+  return Math.max(0.15, Math.sin(Math.PI * Math.max(0, Math.min(1, 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;
+}
+var FEATHER_STEPS = 6;
+
 // src/simulate.ts
 var WARP_NEAR = 0.08;
 var WARP_MAX_SCALE = 8;
@@ -932,6 +1226,21 @@ function drawOsc(rng, amp) {
   }
   return osc;
 }
+var GOLDEN = 0.6180339887498949;
+function emitParams(emit, i, n) {
+  const every = emit.every;
+  const jitter = Math.max(0, Math.min(1, emit.jitter ?? 1));
+  const scattered = (i + 0.5) * GOLDEN % 1 * every;
+  const even = i / Math.max(1, n) * every;
+  const phase = ((even * (1 - jitter) + scattered * jitter) % every + every) % every;
+  return {
+    every,
+    life: Math.min(emit.life, every),
+    phase,
+    growFrom: emit.grow?.[0] ?? 1,
+    growTo: emit.grow?.[1] ?? 1
+  };
+}
 function weightedIndex(u, weights) {
   const total = weights.reduce((a, b) => a + b, 0);
   let acc = 0;
@@ -942,15 +1251,15 @@ function weightedIndex(u, weights) {
   return weights.length - 1;
 }
 function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
-  const effectiveCount = countScale === 1 || layer.layout?.type === "grid" ? layer.count : Math.max(1, Math.min(
+  const effectiveCount = countScale === 1 || layer.layout !== void 0 ? layer.count : Math.max(1, Math.min(
     Math.round(layer.count * countScale),
     layer.links ? LIMITS.maxLinkLayerCount : LIMITS.maxPerLayer
   ));
   const [smin, smax] = layer.size ?? [20, 40];
   const variants = spriteVariants(layer.sprite);
   const sprite = layer.sprite;
-  const spriteColors = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors : void 0;
-  const colorWeights = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colorWeights : void 0;
+  const spriteColors = isShapedSprite(sprite) ? sprite.colors : void 0;
+  const colorWeights = isShapedSprite(sprite) ? sprite.colorWeights : void 0;
   const colorsLen = spriteColors?.length ?? 0;
   const cycle = sprite.kind === "emoji" || sprite.kind === "text" ? sprite.cycle : void 0;
   const mSpec = layer.motion;
@@ -964,7 +1273,32 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
   if (mSpec.type === "path") {
     pathPts = mSpec.points.map((p) => ({ x: p.x * w, y: p.y * h }));
   }
+  const ease = mSpec.type === "drift" || mSpec.type === "rise" || mSpec.type === "wander" ? mSpec.ease : void 0;
+  const clockPhase = layer.clock ? (layer.clock.phase ?? 0) % 1 * Math.PI * 2 : 0;
   const layout = layer.layout;
+  const ordered = layout?.type === "list" || layout?.type === "table";
+  let gapX = 0;
+  let gapY = 0;
+  let listX0 = 0;
+  let listY0 = 0;
+  let listCols = 1;
+  if (layout?.type === "list" || layout?.type === "table") {
+    const dflt = scale === 1 ? LIMITS.defaultListGapPx : LIMITS.defaultListGap;
+    const g = layout.gap ?? dflt;
+    gapX = (typeof g === "number" ? g : g.x ?? dflt) * scale;
+    gapY = (typeof g === "number" ? g : g.y ?? dflt) * scale;
+    listCols = layout.type === "list" ? 1 : Math.max(1, Math.round(layout.columns));
+    const rows = Math.max(1, Math.ceil(effectiveCount / listCols));
+    if (layer.position) {
+      listX0 = layer.position.x * w;
+      listY0 = layer.position.y * h;
+    } else {
+      const [rx0, rx1] = layer.region?.x ?? [0, 1];
+      const [ry0, ry1] = layer.region?.y ?? [0, 1];
+      listX0 = (rx0 + rx1) / 2 * w - (listCols - 1) * gapX / 2;
+      listY0 = (ry0 + ry1) / 2 * h - (rows - 1) * gapY / 2;
+    }
+  }
   let gridCols = 0;
   let cellW = 0;
   let cellH = 0;
@@ -987,8 +1321,8 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
   }
   const out = [];
   for (let i = 0; i < effectiveCount; i++) {
-    const size = sprite.kind === "textBlock" ? sprite.fontSize * scale : sprite.kind === "circle" || sprite.kind === "ring" ? rng.range(sprite.radius[0], sprite.radius[1]) * 2 * scale : sprite.kind === "streak" ? rng.range(sprite.length[0], sprite.length[1]) * scale : sprite.kind === "rect" ? rng.range(sprite.width[0], sprite.width[1]) * scale : rng.range(smin, smax) * scale;
-    const size2 = sprite.kind === "rect" ? size * (sprite.aspect ? rng.range(sprite.aspect[0], sprite.aspect[1]) : 1) : void 0;
+    const size = sprite.kind === "textBlock" ? sprite.fontSize * scale : sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "polygon" ? rng.range(sprite.radius[0], sprite.radius[1]) * 2 * scale : sprite.kind === "streak" || sprite.kind === "stroke" ? rng.range(sprite.length[0], sprite.length[1]) * scale : sprite.kind === "rect" ? rng.range(sprite.width[0], sprite.width[1]) * scale : sprite.kind === "bar" ? sprite.length * scale : rng.range(smin, smax) * scale;
+    const size2 = sprite.kind === "rect" ? size * (sprite.aspect ? rng.range(sprite.aspect[0], sprite.aspect[1]) : 1) : sprite.kind === "bar" ? sprite.thickness * scale : void 0;
     let vx = 0;
     let vy = 0;
     let bob = 0;
@@ -1052,6 +1386,11 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
     if (layer.position && layer.count === 1) {
       x0 = layer.position.x * w;
       y0 = layer.position.y * h;
+    } else if (layout?.type === "list" || layout?.type === "table") {
+      rng.next();
+      rng.next();
+      x0 = listX0 + i % listCols * gapX;
+      y0 = listY0 + Math.floor(i / listCols) * gapY;
     } else if (layout?.type === "grid") {
       const col = i % gridCols;
       const row = Math.floor(i / gridCols);
@@ -1071,7 +1410,10 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
       x0,
       y0,
       size,
-      spriteIndex: variants > 1 ? rng.int(0, variants - 1) : 0,
+      // Data layouts read variants in order — strings[i] beside bar i. The
+      // seeded draw is still consumed so a layout is placement only: toggling
+      // list/table never disturbs the layer's alpha, pulse or spin stream.
+      spriteIndex: variants > 1 ? ordered ? (rng.int(0, variants - 1), i % variants) : rng.int(0, variants - 1) : 0,
       phase: rng.range(0, Math.PI * 2),
       vx,
       vy,
@@ -1095,10 +1437,12 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
       orbitCx: m.type === "orbit" && !orbitParent ? (m.center?.x ?? 0.5) * w : 0,
       orbitCy: m.type === "orbit" && !orbitParent ? (m.center?.y ?? 0.5) * h : 0,
       // New draws AFTER orbit — guarded so existing specs keep identical streams.
-      colorIndex: colorsLen > 0 ? colorWeights && colorWeights.length === colorsLen ? weightedIndex(rng.next(), colorWeights) : rng.int(0, colorsLen - 1) : -1,
+      colorIndex: colorsLen > 0 ? colorWeights && colorWeights.length === colorsLen ? weightedIndex(rng.next(), colorWeights) : ordered ? (rng.int(0, colorsLen - 1), i % colorsLen) : rng.int(0, colorsLen - 1) : -1,
       cyclePeriod: cycle ? cycle.period : 0,
       // Optional feature fields last (guarded draws inside — wander draws 18 here).
       ...size2 !== void 0 ? { size2 } : {},
+      ...sprite.kind === "bar" ? { barIndex: i } : {},
+      ...ordered ? { ordered: true } : {},
       ...orbitParent ? { orbitParent } : {},
       ...m.type === "wander" ? {
         wander: {
@@ -1119,33 +1463,80 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
           offX: pathOffX,
           offY: pathOffY
         }
-      } : {}
+      } : {},
+      // Time-structure fields (2026-09): ease draws nothing; emit's one draw
+      // per entity happens in a pass AFTER this loop (see below).
+      ...ease ? { ease: { type: ease.type, tau: ease.tau } } : {}
     });
+    if (layer.clock) {
+      const ent = out[out.length - 1];
+      ent.pulsePhase = clockPhase;
+      ent.growPhase = clockPhase;
+      ent.cyclePhase = clockPhase;
+      ent.clockRate = layer.clock.rate ?? 1;
+    }
     if (layer.pulse?.wave) {
       const wl = Math.max(1e-6, layer.pulse.wave.wavelength * scale);
       const ang = (layer.pulse.wave.angle ?? 0) * Math.PI / 180;
-      out[out.length - 1].pulsePhase = -((x0 * Math.cos(ang) + y0 * Math.sin(ang)) / wl) * Math.PI * 2;
+      out[out.length - 1].pulsePhase = clockPhase - (x0 * Math.cos(ang) + y0 * Math.sin(ang)) / wl * Math.PI * 2;
     }
   }
+  if (layer.emit) {
+    for (let i = 0; i < out.length; i++) out[i].emit = emitParams(layer.emit, i, out.length);
+  }
   return out;
 }
 function warpZ(e, t) {
   const wp = e.warp;
   return wrap(wp.z0 - wp.vz * (t / 1e3), WARP_NEAR, 1);
 }
+function smoothstep(x) {
+  const c = x < 0 ? 0 : x > 1 ? 1 : x;
+  return c * c * (3 - 2 * c);
+}
+var EMIT_ATTACK = 0.25;
+function emitWindow(e, t) {
+  const em = e.emit;
+  if (!em) return null;
+  const local = ((t - em.phase) % em.every + em.every) % em.every;
+  return local < em.life ? local / em.life : null;
+}
+function emitEnvelope(u) {
+  if (u < 0 || u >= 1) return 0;
+  return u < EMIT_ATTACK ? smoothstep(u / EMIT_ATTACK) : 1 - smoothstep((u - EMIT_ATTACK) / (1 - EMIT_ATTACK));
+}
+function clockTime(e, t) {
+  return e.clockRate ? t * e.clockRate : t;
+}
+function motionSeconds(e, t) {
+  if (!e.ease) return t / 1e3;
+  let tl = t;
+  if (e.emit) tl = ((t - e.emit.phase) % e.emit.every + e.emit.every) % e.emit.every;
+  const tau = e.ease.tau;
+  const k = 1 - Math.exp(-tl / tau);
+  return (e.ease.type === "settle" ? tau * k : tl - tau * k) / 1e3;
+}
 function alphaAt(e, t) {
   let a = e.alpha;
-  if (e.pulseAmp) a = e.alpha + e.pulseAmp * Math.sin(t * 2 * Math.PI / e.pulsePeriod + e.pulsePhase);
+  if (e.pulseAmp) a = e.alpha + e.pulseAmp * Math.sin(clockTime(e, t) * 2 * Math.PI / e.pulsePeriod + e.pulsePhase);
   if (e.motion === "warp") {
     const z = warpZ(e, t);
     a *= Math.max(0, Math.min(1, (1 - z) / 0.2));
   }
+  if (e.emit) {
+    const u = emitWindow(e, t);
+    a = u === null ? 0 : a * emitEnvelope(u);
+  }
   return a < 0 ? 0 : a > 1 ? 1 : a;
 }
 function sizeAt(e, t) {
   let s = e.size;
-  if (e.growAmp) s = e.size * (1 + e.growAmp * Math.sin(t * 2 * Math.PI / e.growPeriod + e.growPhase));
+  if (e.growAmp) s = e.size * (1 + e.growAmp * Math.sin(clockTime(e, t) * 2 * Math.PI / e.growPeriod + e.growPhase));
   if (e.motion === "warp") s *= Math.min(1 / warpZ(e, t), WARP_MAX_SCALE);
+  if (e.emit && (e.emit.growFrom !== 1 || e.emit.growTo !== 1)) {
+    const u = emitWindow(e, t);
+    if (u !== null) s *= e.emit.growFrom + (e.emit.growTo - e.emit.growFrom) * u;
+  }
   return s > 0 ? s : 0.1;
 }
 function rotationAt(e, t) {
@@ -1176,7 +1567,7 @@ function reflect(v, min, max) {
   const p = ((v - min) % period + period) % period;
   return min + (p < range ? p : period - p);
 }
-function catmullRom(p0, p1, p2, p3, u) {
+function catmullRom2(p0, p1, p2, p3, u) {
   const u2 = u * u;
   const u3 = u2 * u;
   return 0.5 * (2 * p1 + (-p0 + p2) * u + (2 * p0 - 5 * p1 + 4 * p2 - p3) * u2 + (-p0 + 3 * p1 - 3 * p2 + p3) * u3);
@@ -1206,8 +1597,8 @@ function pathPosition(e, t) {
   const p0 = at(i - 1);
   const p3 = at(i + 2);
   return {
-    x: catmullRom(p0.x, p1.x, p2.x, p3.x, local) + p.offX,
-    y: catmullRom(p0.y, p1.y, p2.y, p3.y, local) + p.offY
+    x: catmullRom2(p0.x, p1.x, p2.x, p3.x, local) + p.offX,
+    y: catmullRom2(p0.y, p1.y, p2.y, p3.y, local) + p.offY
   };
 }
 function positionAt(e, t, w, h) {
@@ -1234,7 +1625,7 @@ function positionAt(e, t, w, h) {
     const pos = pathPosition(e, t);
     return { x: pos.x, y: pos.y, flip: false };
   }
-  const dt = t / 1e3;
+  const dt = motionSeconds(e, t);
   const m = e.size;
   if (e.motion === "bounce") {
     return {
@@ -1291,7 +1682,8 @@ function headingAt(e, t, w, h) {
 }
 function spriteIndexAt(e, t, variants) {
   if (!e.cyclePeriod || variants <= 1) return e.spriteIndex;
-  return Math.floor(t / e.cyclePeriod + e.phase / (2 * Math.PI)) % variants;
+  if (e.ordered) return (e.spriteIndex + Math.floor(clockTime(e, t) / e.cyclePeriod)) % variants;
+  return Math.floor(clockTime(e, t) / e.cyclePeriod + (e.cyclePhase ?? e.phase) / (2 * Math.PI)) % variants;
 }
 function wrapDist(pi, pj, doWrap, w, h) {
   let dx = pj.x - pi.x;
@@ -1462,6 +1854,17 @@ function revealState(lines, reveal, tMs) {
   const mode = reveal.mode ?? "typewriter";
   let fullLines = 0;
   let partialText = "";
+  let glyphAlphas;
+  if (mode === "glyphFade") {
+    const f = Math.min(1, Math.max(0.01, reveal.fade ?? 0.15));
+    let g = 0;
+    glyphAlphas = lineClusters.map(
+      (clusters) => clusters.map(() => {
+        const start = totalGraphemes > 0 ? g++ / totalGraphemes * (1 - f) : 0;
+        return Math.max(0, Math.min(1, (progress - start) / f));
+      })
+    );
+  }
   if (mode === "line") {
     fullLines = Math.round(progress * lines.length);
   } else if (mode === "word") {
@@ -1501,7 +1904,7 @@ function revealState(lines, reveal, tMs) {
     caretLine = 0;
     caretPrefix = "";
   }
-  return { progress, fullLines, partialText, caretLine, caretPrefix };
+  return { progress, fullLines, partialText, caretLine, caretPrefix, glyphAlphas };
 }
 
 // src/compile.ts
@@ -1510,7 +1913,13 @@ import {
 } from "@idle-screens/core";
 
 // src/sequence.ts
-function resolveSegment(seq, T) {
+function segmentStart(seq, index) {
+  let t = 0;
+  const n = Math.max(0, Math.min(index, seq.segments.length - 1));
+  for (let i = 0; i < n; i++) t += seq.segments[i].duration ?? 0;
+  return t;
+}
+function resolveSegment(seq, T, opts = {}) {
   const { segments, loop } = seq;
   if (segments.length === 0) return { index: 0, localT: 0, startT: 0 };
   let totalTimed = 0;
@@ -1518,24 +1927,33 @@ function resolveSegment(seq, T) {
     if (seg.duration != null) totalTimed += seg.duration;
     else break;
   }
-  let t = Math.max(0, T);
-  if (loop && totalTimed > 0) {
-    t = t % totalTimed;
-  }
-  let cumulative = 0;
-  for (let i = 0; i < segments.length; i++) {
-    const seg = segments[i];
-    if (seg.duration == null) {
-      return { index: i, localT: t - cumulative, startT: cumulative };
-    }
-    if (t < cumulative + seg.duration) {
-      return { index: i, localT: t - cumulative, startT: cumulative };
+  const t0 = Math.max(0, T);
+  const walk = (t, releasedBelow) => {
+    let cumulative = 0;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      if (seg.duration == null) {
+        return loop ? null : { index: i, localT: t - cumulative, startT: cumulative };
+      }
+      if (t < cumulative + seg.duration) {
+        return { index: i, localT: t - cumulative, startT: cumulative };
+      }
+      if (seg.advance === "input" && i >= releasedBelow) {
+        return { index: i, localT: t - cumulative, startT: cumulative, held: true };
+      }
+      cumulative += seg.duration;
     }
-    cumulative += seg.duration;
+    return null;
+  };
+  const first = walk(t0, opts.releasedBelow ?? 0);
+  if (first) return first;
+  if (loop && totalTimed > 0) {
+    const wrapped = walk(t0 % totalTimed, 0);
+    if (wrapped) return wrapped;
   }
   const last = segments.length - 1;
-  const lastStart = cumulative - (segments[last].duration ?? 0);
-  return { index: last, localT: t - lastStart, startT: lastStart };
+  const lastStart = totalTimed - (segments[last].duration ?? 0);
+  return { index: last, localT: t0 - lastStart, startT: lastStart };
 }
 
 // src/compile.ts
@@ -1727,7 +2145,7 @@ var SpecInstance = class {
     const headAlpha = alphaAt(e, t) * lifeA;
     const headSize = sizeAt(e, t);
     const sprite = built.layer.sprite;
-    const resolvedColor = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" || sprite.kind === "textBlock" ? sprite.color ?? "#e6e8ef" : "#e6e8ef";
+    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);
@@ -1806,7 +2224,90 @@ var SpecInstance = class {
       ctx.translate(p.x, p.y);
       if (rot) ctx.rotate(rot);
       ctx.fillStyle = resolvedColor;
-      ctx.fillRect(-sz / 2, -rh / 2, sz, rh);
+      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;
+      } else {
+        ctx.fillRect(-sz / 2, -rh / 2, sz, rh);
+      }
+      ctx.restore();
+      return;
+    }
+    if (sprite.kind === "bar") {
+      const len = sz * barFraction(sprite, e.barIndex ?? 0);
+      if (len <= 0) return;
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      const th = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz * 0.2;
+      const box = barBox(sprite.direction ?? "right", len, th);
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      if (rot) ctx.rotate(rot);
+      ctx.fillStyle = resolvedColor;
+      ctx.fillRect(box.cx - box.halfX, box.cy - box.halfY, box.halfX * 2, box.halfY * 2);
+      ctx.restore();
+      return;
+    }
+    if (sprite.kind === "polygon") {
+      const r = sz / 2;
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      const pts = polygonPoints(sprite, r);
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      if (rot) ctx.rotate(rot);
+      if (sprite.soft) {
+        const g = ctx.createRadialGradient(0, 0, 0, 0, 0, r);
+        g.addColorStop(0, resolvedColor);
+        g.addColorStop(0.35, hexToRgba(resolvedColor, 0.75));
+        g.addColorStop(1, hexToRgba(resolvedColor, 0));
+        ctx.fillStyle = g;
+      } else {
+        ctx.fillStyle = resolvedColor;
+      }
+      ctx.beginPath();
+      ctx.moveTo(pts[0].x, pts[0].y);
+      for (let i = 1; i < pts.length; i++) ctx.lineTo(pts[i].x, pts[i].y);
+      ctx.closePath();
+      ctx.fill();
+      ctx.restore();
+      return;
+    }
+    if (sprite.kind === "stroke") {
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      const pts = strokeSamples(sprite, sz / 2);
+      const lw = strokeWidthPx(sprite, unitScale);
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      let angle = rot;
+      if (sprite.orient) angle += headingAt(e, t, this.w, this.h) ?? 0;
+      if (angle) ctx.rotate(angle);
+      ctx.strokeStyle = resolvedColor;
+      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();
+        }
+      } else {
+        ctx.lineWidth = lw;
+        ctx.beginPath();
+        ctx.moveTo(pts[0].x, pts[0].y);
+        for (let i = 1; i < pts.length; i++) ctx.lineTo(pts[i].x, pts[i].y);
+        ctx.stroke();
+      }
       ctx.restore();
       return;
     }
@@ -1853,11 +2354,39 @@ var SpecInstance = class {
       ctx.textBaseline = "top";
       ctx.textAlign = align;
       const xOff = align === "center" ? maxWPx / 2 : align === "right" ? maxWPx : 0;
-      for (let li = 0; li < fullLines; li++) {
-        ctx.fillText(lines[li].text, xOff, li * lh);
-      }
-      if (rs && rs.partialText.length > 0) {
-        ctx.fillText(rs.partialText, xOff, fullLines * lh);
+      if (rs?.glyphAlphas) {
+        ctx.textAlign = "left";
+        const baseAlpha = ctx.globalAlpha;
+        for (let li = 0; li < lines.length; li++) {
+          const alphas = rs.glyphAlphas[li] ?? [];
+          if (alphas.length > 0 && alphas[0] <= 0) break;
+          const clusters = graphemeClusters(lines[li].text);
+          const lw = ctx.measureText(lines[li].text).width;
+          const x0 = align === "center" ? (maxWPx - lw) / 2 : align === "right" ? maxWPx - lw : 0;
+          let opaque = 0;
+          while (opaque < clusters.length && (alphas[opaque] ?? 0) >= 1) opaque++;
+          let prefix = "";
+          if (opaque > 0) {
+            prefix = clusters.slice(0, opaque).join("");
+            ctx.globalAlpha = baseAlpha;
+            ctx.fillText(prefix, x0, li * lh);
+          }
+          for (let gi = opaque; gi < clusters.length; gi++) {
+            const a = alphas[gi] ?? 0;
+            if (a <= 0) break;
+            ctx.globalAlpha = baseAlpha * a;
+            ctx.fillText(clusters[gi], x0 + ctx.measureText(prefix).width, li * lh);
+            prefix += clusters[gi];
+          }
+        }
+        ctx.globalAlpha = baseAlpha;
+      } else {
+        for (let li = 0; li < fullLines; li++) {
+          ctx.fillText(lines[li].text, xOff, li * lh);
+        }
+        if (rs && rs.partialText.length > 0) {
+          ctx.fillText(rs.partialText, xOff, fullLines * lh);
+        }
       }
       if (rs && reveal.caret) {
         const cfg = reveal.caret === true ? {} : reveal.caret;
@@ -1953,7 +2482,7 @@ var SpecInstance = class {
       let resolvedColor = links.color;
       if (!resolvedColor) {
         const sprite = built.layer.sprite;
-        if (sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect") {
+        if (isShapedSprite(sprite)) {
           resolvedColor = sprite.colors?.[ei.colorIndex] ?? sprite.color;
         } else resolvedColor = "#e6e8ef";
       }
@@ -2091,6 +2620,18 @@ var SequenceInstance = class {
   startT = 0;
   baseT = 0;
   lastT = 0;
+  /** The T most recently passed to renderFrame — the clock a steer displaces. */
+  renderedT = 0;
+  /**
+   * The clicker's two pieces of state. `clockOffset` is added to every T so
+   * a `sequence.segment` steer lands the timeline at the target segment's
+   * start and STAYS there as the wall clock keeps ticking — the steer moves
+   * the clock instead of fighting it. `releasedBelow` records that the steer
+   * counts as the presenter clicking past every `advance: 'input'` hold
+   * before the target (see `resolveSegment`).
+   */
+  clockOffset = 0;
+  releasedBelow = 0;
   constructor(seq, ctx) {
     this.seq = seq;
     let surface = ctx.surface ?? null;
@@ -2173,7 +2714,8 @@ var SequenceInstance = class {
     this.renderFrame(this.lastT, this.seed);
   }
   renderFrame(T, seed) {
-    const resolved = resolveSegment(this.seq, T);
+    this.renderedT = T;
+    const resolved = resolveSegment(this.seq, T + this.clockOffset, { releasedBelow: this.releasedBelow });
     const { index, localT } = resolved;
     const prevIdx = index > 0 ? index - 1 : -1;
     const morphActive = prevIdx >= 0 && this.canMorph(prevIdx) && localT < this.morphDur(prevIdx);
@@ -2242,14 +2784,9 @@ var SequenceInstance = class {
     const segDelta = deltas.find((d) => d.path === "sequence.segment");
     if (segDelta !== void 0 && typeof segDelta.value === "number") {
       const idx = Math.max(0, Math.min(this.seq.segments.length - 1, Math.round(segDelta.value)));
-      if (idx !== this.activeIndex) {
-        for (let i = 0; i < this.children.length; i++) {
-          if (i !== idx) this.releaseChild(i);
-        }
-        this.activeIndex = idx;
-        const child = this.ensureChild(idx);
-        child.renderFrame(0, this.seq.segments[idx].scene.seed ?? this.seq.seed ?? 0);
-      }
+      this.clockOffset = segmentStart(this.seq, idx) - this.renderedT;
+      this.releasedBelow = idx;
+      this.renderFrame(this.renderedT, this.seed);
     }
     const childDeltas = deltas.filter((d) => d.path !== "sequence.segment");
     if (childDeltas.length > 0 && this.activeIndex >= 0) {
@@ -2308,7 +2845,7 @@ function hexLuma(hex) {
 }
 function spriteLuma(layer, e) {
   const s = layer.sprite;
-  if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
+  if (isShapedSprite(s)) {
     return hexLuma(s.colors?.[e.colorIndex] ?? s.color);
   }
   if (s.kind === "text" || s.kind === "textBlock") return hexLuma(s.color ?? "#e6e8ef");
@@ -2316,7 +2853,7 @@ function spriteLuma(layer, e) {
 }
 function spriteHex(layer, e) {
   const s = layer.sprite;
-  if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
+  if (isShapedSprite(s)) {
     return s.colors?.[e.colorIndex] ?? s.color;
   }
   if (s.kind === "text" || s.kind === "textBlock") return s.color ?? "#e6e8ef";
@@ -2354,19 +2891,237 @@ function colourSeparation(layer, sprite, bg) {
   return Math.sqrt((dr * dr + dg * dg + db * db) / 3);
 }
 
+// src/cohesion.ts
+var MERGE_FLOOR = 0.35;
+var WASH_ALPHA_MAX = 0.45;
+var COHESION_T = 5e3;
+var OUTLINE_SAMPLES = 24;
+var MAX_TRACED = 240;
+var EDGE_INSET = 1e-4;
+function circleShape(cx, cy, r) {
+  return {
+    cx,
+    cy,
+    br: r,
+    area: Math.PI * r * r,
+    contains: (x, y) => (x - cx) * (x - cx) + (y - cy) * (y - cy) < r * r,
+    outline: (n) => Array.from({ length: n }, (_, i) => {
+      const a = i / n * Math.PI * 2;
+      const inner = r * (1 - EDGE_INSET);
+      return { x: cx + inner * Math.cos(a), y: cy + inner * Math.sin(a) };
+    })
+  };
+}
+function polyShape(cx, cy, raw) {
+  const abs = raw.filter((p, i) => {
+    const q = raw[(i + 1) % raw.length];
+    return Math.hypot(q.x - p.x, q.y - p.y) > 0;
+  });
+  if (abs.length < 3) return null;
+  let br = 0;
+  for (const p of abs) br = Math.max(br, Math.hypot(p.x - cx, p.y - cy));
+  const inside = (x, y) => {
+    let hit = false;
+    for (let i = 0, j = abs.length - 1; i < abs.length; j = i++) {
+      const a = abs[i];
+      const b = abs[j];
+      if (a.y > y !== b.y > y && x < (b.x - a.x) * (y - a.y) / (b.y - a.y) + a.x) hit = !hit;
+    }
+    return hit;
+  };
+  const seg = abs.map((p, i) => {
+    const q = abs[(i + 1) % abs.length];
+    return Math.hypot(q.x - p.x, q.y - p.y);
+  });
+  const perimeter = seg.reduce((a, b) => a + b, 0);
+  const shortest = Math.min(...seg);
+  const step = Math.min(br * EDGE_INSET, shortest * 0.25);
+  const area = polygonArea(abs);
+  if (!(area > 0)) return null;
+  return {
+    cx,
+    cy,
+    br,
+    area,
+    contains: inside,
+    /**
+     * `n` points spread along the perimeter by ARC LENGTH, not one share per
+     * edge — a long skinny rectangle has two edges carrying almost all of its
+     * perimeter, and an equal-per-edge split would report a fully buried long
+     * side as only a quarter covered. Each point is then stepped along its
+     * edge's inward normal, whichever of the two candidates lands inside.
+     */
+    outline: (n) => {
+      if (!(perimeter > 0)) return [];
+      const out = [];
+      for (let i = 0; i < n; i++) {
+        let d = i / n * perimeter;
+        let k = 0;
+        while (k < seg.length - 1 && d > seg[k]) {
+          d -= seg[k];
+          k++;
+        }
+        const a = abs[k];
+        const b = abs[(k + 1) % abs.length];
+        const len = seg[k];
+        const f = d / len;
+        const px = a.x + (b.x - a.x) * f;
+        const py = a.y + (b.y - a.y) * f;
+        const ux = (b.x - a.x) / len;
+        const uy = (b.y - a.y) / len;
+        for (let t = step; t > 0; t /= 8) {
+          const qx1 = px - uy * t;
+          const qy1 = py + ux * t;
+          if (inside(qx1, qy1)) {
+            out.push({ x: qx1, y: qy1 });
+            break;
+          }
+          const qx2 = px + uy * t;
+          const qy2 = py - ux * t;
+          if (inside(qx2, qy2)) {
+            out.push({ x: qx2, y: qy2 });
+            break;
+          }
+          if (t < step * 1e-3) break;
+        }
+      }
+      return out;
+    }
+  };
+}
+function rectShape(cx, cy, halfW, halfH, rot) {
+  const cos = Math.cos(rot);
+  const sin = Math.sin(rot);
+  const corner = (lx, ly) => ({ x: cx + lx * cos - ly * sin, y: cy + lx * sin + ly * cos });
+  return polyShape(cx, cy, [
+    corner(-halfW, -halfH),
+    corner(halfW, -halfH),
+    corner(halfW, halfH),
+    corner(-halfW, halfH)
+  ]);
+}
+function polygonShape(cx, cy, pts, rot) {
+  const cos = Math.cos(rot);
+  const sin = Math.sin(rot);
+  return polyShape(cx, cy, pts.map((p) => ({ x: cx + p.x * cos - p.y * sin, y: cy + p.x * sin + p.y * cos })));
+}
+function shapeOf(layer, e, t, w, h) {
+  const s = layer.sprite;
+  if (s.kind !== "circle" && s.kind !== "rect" && s.kind !== "polygon") return null;
+  const p = positionAt(e, t, w, h);
+  const sz = sizeAt(e, t);
+  if (!(sz > 0)) return null;
+  if (s.kind === "circle") return circleShape(p.x, p.y, sz / 2);
+  const rot = rotationAt(e, t);
+  if (s.kind === "rect") {
+    const h2 = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz;
+    return rectShape(p.x, p.y, sz / 2, h2 / 2, rot);
+  }
+  return polygonShape(p.x, p.y, polygonPoints(s, sz / 2), rot);
+}
+function seamCauseOf(layer) {
+  const s = layer.sprite;
+  if ((s.kind === "circle" || s.kind === "polygon") && s.soft) {
+    return "sprite.soft \u2014 radial falloff never forms a hard union";
+  }
+  if (s.kind === "rect" && s.feather) {
+    return "rect.feather \u2014 a feathered edge never forms a hard union";
+  }
+  if (layer.blend) {
+    return `blend: ${layer.blend} \u2014 overlaps composite instead of covering`;
+  }
+  const [lo, hi] = layer.alpha ?? [1, 1];
+  if (lo < 1 || hi < 1) {
+    return `alpha ${lo === hi ? lo : `${lo}..${hi}`} \u2014 every overlap paints a darker patch`;
+  }
+  if (layer.pulse && layer.pulse.amp > 0) {
+    return "pulse \u2014 the layer is translucent for part of every cycle";
+  }
+  const palette = "colors" in s && Array.isArray(s.colors) ? s.colors : null;
+  const weights = "colorWeights" in s && Array.isArray(s.colorWeights) ? s.colorWeights : null;
+  if (palette) {
+    const aligned = weights !== null && weights.length === palette.length;
+    const reachable = new Set(palette.filter((_, i) => !aligned || (weights[i] ?? 0) > 0));
+    if (reachable.size > 1) {
+      return `sprite.colors has ${reachable.size} reachable colours \u2014 neighbours of unlike colour show their join`;
+    }
+  }
+  return null;
+}
+function cohesionOf(layers, t, w, h) {
+  return layers.map(({ layer, entities }, layerIndex) => {
+    const seamCause = seamCauseOf(layer);
+    const base = {
+      layerIndex,
+      key: layer.key,
+      seamless: seamCause === null,
+      seamCause
+    };
+    if (lifeAlphaAt(layer.life, t) <= 0) return { ...base, overlap: null, reads: null };
+    const shapes = entities.map((e) => shapeOf(layer, e, t, w, h));
+    const solid = shapes.filter((x) => x !== null && x.area > 0);
+    if (solid.length < 2) return { ...base, overlap: null, reads: null };
+    const stride = Math.max(1, Math.ceil(solid.length / MAX_TRACED));
+    let covered = 0;
+    let traced = 0;
+    for (let i = 0; i < solid.length; i += stride) {
+      const self = solid[i];
+      const pts = self.outline(OUTLINE_SAMPLES);
+      if (pts.length === 0) continue;
+      let hit = 0;
+      for (const p of pts) {
+        for (let j = 0; j < solid.length; j++) {
+          if (j === i) continue;
+          const other = solid[j];
+          const dx = p.x - other.cx;
+          const dy = p.y - other.cy;
+          if (dx * dx + dy * dy > other.br * other.br) continue;
+          if (other.contains(p.x, p.y)) {
+            hit++;
+            break;
+          }
+        }
+      }
+      covered += hit / pts.length;
+      traced++;
+    }
+    if (traced === 0) return { ...base, overlap: null, reads: null };
+    const overlap = Number((covered / traced).toFixed(4));
+    const reads = overlap < MERGE_FLOOR ? "marks" : seamCause === null ? "mass" : "seamed";
+    return { ...base, overlap, reads };
+  });
+}
+function seamsWorthWarning(layer, c, entityCount) {
+  if (c.reads !== "seamed" || entityCount < 6) return false;
+  const [lo, hi] = layer.alpha ?? [1, 1];
+  if ((lo + hi) / 2 < WASH_ALPHA_MAX) return false;
+  return layer.blend !== "lighter" && layer.blend !== "screen";
+}
+
 // src/advise.ts
 var LOW_CONTRAST_FLOOR = 0.05;
-function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
+var SPARSE_DECLARED_MAX_COVERAGE = 0.02;
+function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   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;
-  const countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
-  const rng = createRng2(spec.seed ?? 42);
+  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;
+  }
+  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;
@@ -2378,6 +3133,14 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
     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`,
@@ -2385,11 +3148,11 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
         message: "trail has no effect on static entities \u2014 they have no past positions to draw"
       });
     }
-    if (layer.sprite.kind === "streak" && layer.motion.type === "static") {
+    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: "streak sprites orient along the motion heading \u2014 static entities have none and will render at angle 0"
+        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) {
@@ -2436,6 +3199,8 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       let pixArea;
       if (layer.sprite.kind === "circle") {
         pixArea = Math.PI * r * 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;
@@ -2445,7 +3210,13 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       } else {
         pixArea = e.size * e.size;
       }
-      totalCoverage += pixArea * e.alpha / (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;
+      }
+      totalCoverage += pixArea * e.alpha * duty / (w * h);
     }
     if (layer.links) {
       const positions = entities.map((e) => positionAt(e, 0, w, h));
@@ -2456,20 +3227,35 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       for (const edge of edges) totalCoverage += edge.dist * lwPx * la / (w * h);
     }
   }
-  if (totalCoverage < 5e-4 && spec.layers.length > 0) {
+  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) {
+  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) {
@@ -2529,8 +3315,88 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       });
     }
   }
+  const textBoxes = [];
+  for (let li = 0; li < spec.layers.length; li++) {
+    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 box = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
+      textBoxes.push({ li, label, ...box });
+    }
+  }
+  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`
+      });
+    }
+  }
   return warnings;
 }
+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 };
+}
+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);
+  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;
+  return { x0, y0: p.y, x1: x0 + maxLineW, y1: p.y + totalH };
+}
 function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
   const warnings = [];
   for (let i = 0; i < seq.segments.length; i++) {
@@ -2729,7 +3595,17 @@ function textBlockRevealFraction(s, w, h, t) {
   const unitScale = Math.min(w, h);
   const maxWEm = s.maxWidth * unitScale / (s.fontSize * unitScale);
   const lines = breakTextBlock(s.text, maxWEm);
-  return revealState(lines, s.reveal, t).progress;
+  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;
+  }
+  return rs.progress;
 }
 function luminanceGrid(spec, opts = {}) {
   const scene = buildScene(spec, opts);
@@ -2827,6 +3703,36 @@ function luminanceGrid(spec, opts = {}) {
         const p = posOf(scene, e, tPass);
         const sz = sizeAt(e, tPass);
         const s = layer.sprite;
+        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;
           const steps = Math.max(2, Math.ceil(sz / Math.min(cellW, cellH)));
@@ -2858,9 +3764,22 @@ function luminanceGrid(spec, opts = {}) {
           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";
-        const soft = s.kind === "circle" && !!s.soft;
+        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;
@@ -2893,9 +3812,9 @@ function luminanceGrid(spec, opts = {}) {
               } else {
                 wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
               }
-              compose(r * cols + c, lum, a * wgt, layer.blend);
+              compose(r * cols + c, lum, a * wgt * shapeWeight, layer.blend);
             } else {
-              compose(r * cols + c, lum, a * inkWeight, layer.blend);
+              compose(r * cols + c, lum, a * inkWeight * shapeWeight, layer.blend);
             }
           }
         }
@@ -3083,7 +4002,15 @@ function dominanceRanking(spec, opts = {}) {
       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;
-        entArea = sz * h2;
+        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;
@@ -3128,6 +4055,10 @@ function dominanceRanking(spec, opts = {}) {
     factors: r.factors
   }));
 }
+function layerCohesion(spec, opts = {}) {
+  const scene = buildScene(spec, opts);
+  return cohesionOf(scene.layers, opts.t ?? 5e3, scene.w, scene.h);
+}
 function motionStats(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
@@ -3224,8 +4155,9 @@ function perceiveScene(spec, opts = {}) {
     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 })
+    advisories: adviseSpec(spec, opts.viewport ?? { width: 1920, height: 1080 }, { t: opts.t, seed: opts.seed })
   };
 }
 
@@ -3941,6 +4873,77 @@ var DASHBOARD_SPEC = {
   ]
 };
 
+// src/examples/facets.ts
+var FACETS_SPEC = {
+  schemaVersion: 1,
+  id: "facets",
+  label: "Facets",
+  seed: 1911,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#101626" },
+      { at: 1, color: "#1c1a2e" }
+    ]
+  },
+  layers: [
+    {
+      key: "planes",
+      count: 3,
+      sprite: {
+        kind: "rect",
+        width: [0.28, 0.42],
+        aspect: [0.6, 1.4],
+        color: "#b3402f",
+        colors: ["#b3402f", "#c9862b", "#2d4f8a"],
+        feather: 0.6
+      },
+      alpha: [0.35, 0.5],
+      region: { x: [0.2, 0.8], y: [0.2, 0.8] },
+      motion: { type: "wander", speed: [1e-3, 3e-3], meander: 0.02 },
+      spin: [-2, 2]
+    },
+    {
+      key: "facets",
+      count: 14,
+      sprite: {
+        kind: "polygon",
+        radius: [0.02, 0.06],
+        points: [[-1, 0.9], [0.2, -1], [1, 0.4]],
+        color: "#f2e8c9",
+        colors: ["#f2e8c9", "#e0b53a", "#6fa8dc", "#d94f3d"]
+      },
+      alpha: [0.6, 0.9],
+      motion: { type: "wander", speed: [3e-3, 8e-3], meander: 0.03 },
+      spin: [-8, 8]
+    },
+    {
+      key: "arcs",
+      count: 12,
+      sprite: {
+        kind: "stroke",
+        length: [0.08, 0.18],
+        points: [[-1, 0.3], [-0.5, -0.6], [0.3, -0.7], [1, 0.1]],
+        width: 4e-3,
+        taper: true,
+        color: "#f2e8c9"
+      },
+      alpha: [0.5, 0.8],
+      motion: { type: "drift", speed: [4e-3, 0.01], angle: 20, bidirectional: true },
+      spin: [-4, 4]
+    },
+    {
+      key: "hexes",
+      count: 8,
+      sprite: { kind: "polygon", radius: [8e-3, 0.016], sides: 6, color: "#e0b53a", soft: true },
+      alpha: [0.5, 0.8],
+      blend: "lighter",
+      motion: { type: "wander", speed: [2e-3, 5e-3] }
+    }
+  ]
+};
+
 // src/examples/haiku.ts
 var HAIKU_SPEC = {
   schemaVersion: 1,
@@ -4333,6 +5336,40 @@ var ORRERY_SPEC = {
   ]
 };
 
+// src/examples/pings.ts
+var PINGS_SPEC = {
+  schemaVersion: 1,
+  id: "pings",
+  label: "Pings",
+  seed: 7,
+  motionIntensity: "calm",
+  ghosting: 0.9,
+  background: { type: "solid", color: "#03060a" },
+  layers: [
+    {
+      key: "ping",
+      count: 3,
+      sprite: { kind: "ring", radius: [0.05, 0.05], color: "#4fb3a8", width: 15e-4 },
+      alpha: [0.35, 0.35],
+      blend: "lighter",
+      region: { x: [0.2, 0.8], y: [0.25, 0.75] },
+      motion: { type: "static" },
+      // One ring at a time: three entities evenly staggered across 12 s.
+      emit: { every: 12e3, life: 4e3, jitter: 0, grow: [0.15, 2.4] }
+    },
+    {
+      key: "motes",
+      count: 14,
+      sprite: { kind: "circle", radius: [12e-4, 2e-3], color: "#4fb3a8", soft: true },
+      alpha: [0.1, 0.22],
+      blend: "lighter",
+      // Each mote is flung upward and comes to rest within ~2.5 s of its event.
+      motion: { type: "rise", speed: [0.01, 0.02], sway: 4e-3, ease: { type: "settle", tau: 2500 } },
+      emit: { every: 16e3, life: 7e3, grow: [0.6, 1.4] }
+    }
+  ]
+};
+
 // src/examples/procession.ts
 var PROCESSION_SPEC = {
   schemaVersion: 1,
@@ -4429,6 +5466,74 @@ var RAIN_SPEC = {
   ]
 };
 
+// src/examples/relay-board.ts
+var RELAY_BOARD_SPEC = {
+  schemaVersion: 1,
+  id: "relay-board",
+  label: "Relay Board",
+  seed: 9,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#05070d" },
+      { at: 1, color: "#0a0d18" }
+    ]
+  },
+  layers: [
+    {
+      key: "dust",
+      count: 40,
+      sprite: { kind: "circle", radius: [8e-4, 16e-4], color: "#22344a", soft: true },
+      alpha: [0.2, 0.45],
+      blend: "lighter",
+      motion: { type: "wander", speed: [1e-3, 3e-3] }
+    },
+    {
+      key: "title",
+      count: 1,
+      sprite: { kind: "textBlock", text: "RELAY LINKS \u2014 UPLINK MARGIN", maxWidth: 0.6, fontSize: 0.028, color: "#9fb4c9" },
+      motion: { type: "static" },
+      position: { x: 0.12, y: 0.16 }
+    },
+    {
+      key: "labels",
+      count: 6,
+      sprite: { kind: "text", strings: ["VIREO-9", "TIDE", "ORRERY", "COMET", "LANTERN", "SAKURA"], font: "bold monospace", align: "left", color: "#e6e8ef" },
+      size: [0.024, 0.024],
+      motion: { type: "static" },
+      position: { x: 0.12, y: 0.3 },
+      layout: { type: "list", gap: 0.075 }
+    },
+    {
+      key: "bars",
+      count: 6,
+      sprite: {
+        kind: "bar",
+        values: [82, 64, 91, 37, 58, 73],
+        max: 100,
+        length: 0.5,
+        thickness: 0.02,
+        color: "#17e8c8",
+        colors: ["#17e8c8", "#35d0ff", "#ffd93b", "#ff6ad5", "#ad8cff", "#17e8c8"]
+      },
+      alpha: [0.85, 0.85],
+      motion: { type: "static" },
+      position: { x: 0.3, y: 0.3 },
+      layout: { type: "list", gap: 0.075 }
+    },
+    {
+      key: "readouts",
+      count: 6,
+      sprite: { kind: "text", strings: ["82%", "64%", "91%", "37%", "58%", "73%"], font: "monospace", align: "left", color: "#9fb4c9" },
+      size: [0.02, 0.02],
+      motion: { type: "static" },
+      position: { x: 0.86, y: 0.3 },
+      layout: { type: "list", gap: 0.075 }
+    }
+  ]
+};
+
 // src/examples/sakura.ts
 var SAKURA_SPEC = {
   schemaVersion: 1,
@@ -4665,7 +5770,10 @@ var SCHEMA_EXAMPLES = [
   { id: "matrix-rain", label: "Matrix Rain", spec: MATRIX_RAIN_SPEC },
   { id: "procession", label: "Night Procession", spec: PROCESSION_SPEC },
   { id: "nostalghia-candle", label: "Nostalghia's Candle", spec: NOSTALGHIA_CANDLE_SPEC },
-  { id: "haiku", label: "Haiku", spec: HAIKU_SPEC }
+  { id: "haiku", label: "Haiku", spec: HAIKU_SPEC },
+  { id: "pings", label: "Pings", spec: PINGS_SPEC },
+  { id: "facets", label: "Facets", spec: FACETS_SPEC },
+  { id: "relay-board", label: "Relay Board", spec: RELAY_BOARD_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -4674,20 +5782,24 @@ var EXAMPLE_BY_ID = Object.fromEntries(
 export {
   AQUARIUM_SPEC,
   AURORA_SPEC,
+  COHESION_T,
   COMETS_SPEC,
   CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
+  FACETS_SPEC,
   HAIKU_SPEC,
   LANTERNS_SPEC,
   LIMITS,
   MATRIX_RAIN_SPEC,
   NOSTALGHIA_CANDLE_SPEC,
   ORRERY_SPEC,
+  PINGS_SPEC,
   POLYGONS_SPEC,
   PROCESSION_SPEC,
   RAIN_SPEC,
+  RELAY_BOARD_SPEC,
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
@@ -4702,14 +5814,18 @@ export {
   assertValidSpec,
   breakTextBlock,
   buildEntities,
+  cohesionOf,
   compileSaver,
   compileSequence,
   describeScene,
   diffScenes,
   dominanceRanking,
   easeSmooth,
+  emitEnvelope,
+  emitWindow,
   graphemeClusters,
   headingAt,
+  layerCohesion,
   lerpSpec,
   lifeAlphaAt,
   linkEdges,
@@ -4725,12 +5841,16 @@ export {
   resolveSpecPath,
   revealState,
   rotationAt,
+  seamCauseOf,
+  seamsWorthWarning,
+  segmentStart,
   sizeAt,
   spriteIndexAt,
   spriteVariants,
   steerablePaths,
   structuralSignature,
   textSprites,
+  textWidthEm,
   validateSequence,
   validateSpec
 };