@idle-screens/schema 2.1.0 → 2.3.0

package/dist/index.js

@@ -20,8 +20,29 @@ var LIMITS = {
   maxLinkLayerCount: 200,
   minCyclePeriod: 500,
   // ms — same flash-safety floor as pulse
-  referenceViewport: 1080
+  referenceViewport: 1080,
   // for validating viewport-unit dimensional caps
+  maxTrailLength: 5e3,
+  // ms — cap trail duration
+  maxTrailSamples: 24,
+  // dots per trail
+  minDriftPeriod: 1e4,
+  // ms — background drift floor (10 s)
+  maxDriftAmount: 0.3,
+  // fraction of gradient stop shift
+  maxGhosting: 0.95,
+  // frame persistence cap — bounds the seek warm-up replay
+  maxGhostReplayFrames: 120,
+  // fixed-step frames replayed on a non-contiguous seek
+  maxMeander: 500,
+  // px — wander harmonic amplitude cap (viewport cap: /referenceViewport)
+  maxWarpSpeed: 1.5,
+  // depth-units/sec — full near-to-far span in ~0.7 s at max
+  minPathPoints: 2,
+  maxPathPoints: 24,
+  minPathDuration: 2e3,
+  // ms — a path lap can't be faster than this
+  maxGridColumns: 100
 };
 
 // src/validate.ts
@@ -30,10 +51,53 @@ 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_LAYER = /* @__PURE__ */ new Set([
+  "count",
+  "sprite",
+  "motion",
+  "size",
+  "wrap",
+  "flip",
+  "alpha",
+  "blend",
+  "region",
+  "pulse",
+  "spin",
+  "grow",
+  "key",
+  "position",
+  "trail",
+  "links",
+  "layout",
+  "life"
+]);
+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_EMOJI = /* @__PURE__ */ new Set(["kind", "glyphs", "cycle"]);
+var KNOWN_TEXT = /* @__PURE__ */ new Set(["kind", "strings", "color", "font", "align", "baseline", "maxWidth", "cycle"]);
+var KNOWN_DRIFT = /* @__PURE__ */ new Set(["type", "speed", "angle", "bidirectional", "bob"]);
+var KNOWN_RISE = /* @__PURE__ */ new Set(["type", "speed", "sway"]);
+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_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"]);
+function unknownKeys(obj, known) {
+  return Object.keys(obj).filter((k) => !known.has(k));
+}
 function validateSpec(spec) {
   const errors = [];
+  const warnings = [];
   const err = (path, message) => void errors.push({ path, message });
-  if (!isObj(spec)) return { valid: false, errors: [{ path: "", message: "spec must be an object" }] };
+  const warn = (path, code, message) => void warnings.push({ path, code, message });
+  if (!isObj(spec)) return { valid: false, errors: [{ path: "", message: "spec must be an object" }], warnings: [] };
   if (spec.schemaVersion !== SCHEMA_VERSION) err("schemaVersion", `must be ${SCHEMA_VERSION}`);
   if (!isStr(spec.id) || spec.id.trim() === "") err("id", "must be a non-empty string");
   if (!isStr(spec.label) || spec.label.trim() === "") err("label", "must be a non-empty string");
@@ -44,7 +108,18 @@ function validateSpec(spec) {
   if (spec.units !== void 0 && spec.units !== "px" && spec.units !== "viewport") {
     err("units", "must be 'px' | 'viewport'");
   }
-  if (spec.background !== void 0) validateBackground(spec.background, err);
+  if (spec.referenceViewport !== void 0) {
+    if (!isNum(spec.referenceViewport) || spec.referenceViewport < 100 || spec.referenceViewport > 8640) {
+      err("referenceViewport", "must be a number between 100 and 8640");
+    }
+  }
+  if (spec.ghosting !== void 0 && (!isNum(spec.ghosting) || spec.ghosting < 0 || spec.ghosting > LIMITS.maxGhosting)) {
+    err("ghosting", `must be a number 0..${LIMITS.maxGhosting}`);
+  }
+  for (const k of unknownKeys(spec, KNOWN_TOP)) {
+    warn(k, "unknown-property", `unknown top-level property '${k}' \u2014 will be ignored`);
+  }
+  if (spec.background !== void 0) validateBackground(spec.background, err, warn);
   if (!Array.isArray(spec.layers) || spec.layers.length === 0) {
     err("layers", "must be a non-empty array");
   } else {
@@ -52,19 +127,22 @@ function validateSpec(spec) {
     let total = 0;
     spec.layers.forEach((layer, i) => {
       total += isObj(layer) && isNum(layer.count) ? layer.count : 0;
-      validateLayer(layer, `layers[${i}]`, err, spec);
+      validateLayer(layer, `layers[${i}]`, err, warn, spec);
     });
     if (total > LIMITS.maxTotal) err("layers", `total entities ${total} exceeds cap ${LIMITS.maxTotal}`);
   }
-  return { valid: errors.length === 0, errors };
+  return { valid: errors.length === 0, errors, warnings };
 }
 function color(v, path, err) {
   if (!isStr(v) || !HEX.test(v)) err(path, "must be a hex colour like #0a3a52");
 }
-function validateBackground(bg, err) {
+function validateBackground(bg, err, warn) {
   if (!isObj(bg)) return err("background", "must be an object");
   if (bg.type === "solid") {
     color(bg.color, "background.color", err);
+    for (const k of unknownKeys(bg, KNOWN_BG_SOLID)) {
+      warn(`background.${k}`, "unknown-property", `unknown background property '${k}' \u2014 will be ignored`);
+    }
   } else if (bg.type === "gradient") {
     if (!Array.isArray(bg.stops) || bg.stops.length < 2) {
       err("background.stops", "gradient needs at least 2 stops");
@@ -74,6 +152,17 @@ function validateBackground(bg, err) {
         color(isObj(s) ? s.color : void 0, `background.stops[${i}].color`, err);
       });
     }
+    if (bg.drift !== void 0) {
+      if (!isObj(bg.drift)) err("background.drift", "must be an object");
+      else {
+        if (!isNum(bg.drift.period) || bg.drift.period < LIMITS.minDriftPeriod) {
+          err("background.drift.period", `must be >= ${LIMITS.minDriftPeriod} ms`);
+        }
+        if (bg.drift.amount !== void 0 && (!isNum(bg.drift.amount) || bg.drift.amount <= 0 || bg.drift.amount > LIMITS.maxDriftAmount)) {
+          err("background.drift.amount", `must be > 0 and <= ${LIMITS.maxDriftAmount}`);
+        }
+      }
+    }
     if (bg.band !== void 0) {
       if (!isObj(bg.band)) err("background.band", "must be an object");
       else {
@@ -81,12 +170,24 @@ function validateBackground(bg, err) {
         if (!isNum(bg.band.height) || bg.band.height <= 0) err("background.band.height", "must be > 0");
       }
     }
+    for (const k of unknownKeys(bg, KNOWN_BG_GRADIENT)) {
+      warn(`background.${k}`, "unknown-property", `unknown background property '${k}' \u2014 will be ignored`);
+    }
   } else {
     err("background.type", "must be solid | gradient");
   }
 }
-function validateLayer(layer, path, err, spec) {
+function validateLayer(layer, path, err, warn, spec) {
   if (!isObj(layer)) return err(path, "must be an object");
+  for (const k of unknownKeys(layer, KNOWN_LAYER)) {
+    if (k === "id") {
+      warn(`${path}.id`, "misplaced-property", `'id' is not a layer property \u2014 did you mean 'key'? Use 'key' to name a layer`);
+    } else if (k === "depth") {
+      warn(`${path}.depth`, "unknown-property", `'depth' is not a layer property \u2014 use motion type 'warp' for true perspective depth, or fake parallax with size/speed/alpha across layers`);
+    } else {
+      warn(`${path}.${k}`, "unknown-property", `unknown layer property '${k}' \u2014 will be ignored`);
+    }
+  }
   if (!isNum(layer.count) || !Number.isInteger(layer.count) || layer.count < 1) {
     err(`${path}.count`, "must be a positive integer");
   } else if (layer.count > LIMITS.maxPerLayer) {
@@ -100,7 +201,9 @@ function validateLayer(layer, path, err, spec) {
   if (layer.alpha !== void 0 && (!isRange(layer.alpha) || layer.alpha[0] < 0 || layer.alpha[1] > 1)) {
     err(`${path}.alpha`, "must be a [min,max] range within 0..1");
   }
-  if (layer.blend !== void 0 && layer.blend !== "lighter") err(`${path}.blend`, "must be 'lighter' when set");
+  if (layer.blend !== void 0 && !["lighter", "screen", "multiply"].includes(layer.blend)) {
+    err(`${path}.blend`, "must be 'lighter' | 'screen' | 'multiply' when set");
+  }
   if (layer.key !== void 0 && (!isStr(layer.key) || layer.key.trim() === "")) {
     err(`${path}.key`, "must be a non-empty string");
   }
@@ -133,6 +236,17 @@ function validateLayer(layer, path, err, spec) {
       if (!isNum(layer.pulse.period) || layer.pulse.period < LIMITS.minPulsePeriod) {
         err(`${path}.pulse.period`, `must be >= ${LIMITS.minPulsePeriod} ms (flash-safety floor)`);
       }
+      if (layer.pulse.wave !== void 0) {
+        if (!isObj(layer.pulse.wave)) err(`${path}.pulse.wave`, "must be an object");
+        else {
+          if (!isNum(layer.pulse.wave.wavelength) || layer.pulse.wave.wavelength <= 0) {
+            err(`${path}.pulse.wave.wavelength`, "must be > 0 (px or viewport-units)");
+          }
+          if (layer.pulse.wave.angle !== void 0 && !isNum(layer.pulse.wave.angle)) {
+            err(`${path}.pulse.wave.angle`, "must be a number (degrees)");
+          }
+        }
+      }
     }
   }
   if (layer.spin !== void 0) {
@@ -166,22 +280,86 @@ function validateLayer(layer, path, err, spec) {
       if (layer.links.width !== void 0 && (!isNum(layer.links.width) || layer.links.width <= 0)) {
         err(`${path}.links.width`, "must be > 0");
       }
+      if (layer.links.mode !== void 0 && !["nearest", "chain", "random"].includes(layer.links.mode)) {
+        err(`${path}.links.mode`, "must be 'nearest' | 'chain' | 'random'");
+      }
+      if (layer.links.falloff !== void 0 && typeof layer.links.falloff !== "boolean") {
+        err(`${path}.links.falloff`, "must be a boolean");
+      }
+      if (layer.links.closed !== void 0 && typeof layer.links.closed !== "boolean") {
+        err(`${path}.links.closed`, "must be a boolean");
+      }
       if (isNum(layer.count) && layer.count > LIMITS.maxLinkLayerCount) {
         err(`${path}.links`, `layer count must be <= ${LIMITS.maxLinkLayerCount} when links is set`);
       }
     }
   }
-  validateSprite(layer.sprite, `${path}.sprite`, err);
-  validateMotion(layer.motion, `${path}.motion`, err, spec);
+  if (layer.layout !== void 0) {
+    if (!isObj(layer.layout) || layer.layout.type !== "grid") {
+      err(`${path}.layout`, "must be an object with type: 'grid'");
+    } 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}`);
+      }
+      const jit = layer.layout.jitter;
+      if (jit !== void 0) {
+        const jitterOk = (v) => isNum(v) && v >= 0 && v <= 1;
+        if (isNum(jit)) {
+          if (!jitterOk(jit)) err(`${path}.layout.jitter`, "must be 0..1");
+        } else if (isObj(jit)) {
+          if (jit.x !== void 0 && !jitterOk(jit.x)) err(`${path}.layout.jitter.x`, "must be 0..1");
+          if (jit.y !== void 0 && !jitterOk(jit.y)) err(`${path}.layout.jitter.y`, "must be 0..1");
+        } else {
+          err(`${path}.layout.jitter`, "must be a number 0..1 or { x?, y? }");
+        }
+      }
+      if (layer.position !== void 0) {
+        warn(`${path}.layout`, "layout-with-position", "position overrides layout for the single entity \u2014 layout has no effect");
+      }
+    }
+  }
+  if (layer.life !== void 0) {
+    if (!isObj(layer.life)) err(`${path}.life`, "must be an object");
+    else {
+      if (layer.life.enter !== void 0 && (!isNum(layer.life.enter) || layer.life.enter < 0)) {
+        err(`${path}.life.enter`, "must be >= 0 (ms)");
+      }
+      if (layer.life.exit !== void 0 && (!isNum(layer.life.exit) || layer.life.exit < 0)) {
+        err(`${path}.life.exit`, "must be >= 0 (ms)");
+      }
+      if (isNum(layer.life.enter) && isNum(layer.life.exit) && layer.life.exit <= layer.life.enter) {
+        err(`${path}.life.exit`, "must be greater than life.enter");
+      }
+      if (layer.life.fade !== void 0 && (!isNum(layer.life.fade) || layer.life.fade < 0)) {
+        err(`${path}.life.fade`, "must be >= 0 (ms)");
+      }
+    }
+  }
+  if (layer.trail !== void 0) {
+    if (!isObj(layer.trail)) err(`${path}.trail`, "must be an object");
+    else {
+      if (!isNum(layer.trail.length) || layer.trail.length <= 0 || layer.trail.length > LIMITS.maxTrailLength) {
+        err(`${path}.trail.length`, `must be > 0 and <= ${LIMITS.maxTrailLength} ms`);
+      }
+      if (layer.trail.fade !== void 0 && (!isNum(layer.trail.fade) || layer.trail.fade < 0 || layer.trail.fade > 1)) {
+        err(`${path}.trail.fade`, "must be 0..1");
+      }
+    }
+  }
+  validateSprite(layer.sprite, `${path}.sprite`, err, warn);
+  validateMotion(layer.motion, `${path}.motion`, err, warn, spec);
 }
-function validateSprite(sprite, path, err) {
+function validateSprite(sprite, path, err, warn) {
   if (!isObj(sprite)) return err(path, "must be an object");
+  let knownSet;
   if (sprite.kind === "emoji") {
+    knownSet = KNOWN_EMOJI;
     if (!Array.isArray(sprite.glyphs) || sprite.glyphs.length === 0 || !sprite.glyphs.every(isStr)) {
       err(`${path}.glyphs`, "must be a non-empty array of strings");
     }
     validateCycle(sprite, path, err);
   } else if (sprite.kind === "text") {
+    knownSet = KNOWN_TEXT;
     if (!Array.isArray(sprite.strings) || sprite.strings.length === 0 || !sprite.strings.every(isStr)) {
       err(`${path}.strings`, "must be a non-empty array of strings");
     }
@@ -197,18 +375,59 @@ function validateSprite(sprite, path, err) {
     }
     validateCycle(sprite, path, err);
   } else if (sprite.kind === "circle") {
+    knownSet = KNOWN_CIRCLE;
     if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
     color(sprite.color, `${path}.color`, err);
     if (sprite.soft !== void 0 && typeof sprite.soft !== "boolean") err(`${path}.soft`, "must be a boolean");
-    if (sprite.colors !== void 0) {
-      if (!Array.isArray(sprite.colors) || sprite.colors.length === 0) {
-        err(`${path}.colors`, "must be a non-empty array of hex colours");
-      } else {
-        sprite.colors.forEach((c, ci) => color(c, `${path}.colors[${ci}]`, err));
-      }
+    validatePalette(sprite, path, err);
+  } else if (sprite.kind === "ring") {
+    knownSet = KNOWN_RING;
+    if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
+    color(sprite.color, `${path}.color`, err);
+    if (sprite.width !== void 0 && (!isNum(sprite.width) || sprite.width <= 0)) err(`${path}.width`, "must be > 0");
+    validatePalette(sprite, path, err);
+  } else if (sprite.kind === "streak") {
+    knownSet = KNOWN_STREAK;
+    if (!isRange(sprite.length) || sprite.length[0] <= 0) err(`${path}.length`, "must be a [min,max] range of positive px");
+    color(sprite.color, `${path}.color`, err);
+    if (sprite.width !== void 0 && (!isNum(sprite.width) || sprite.width <= 0)) err(`${path}.width`, "must be > 0");
+    validatePalette(sprite, path, err);
+  } else if (sprite.kind === "rect") {
+    knownSet = KNOWN_RECT;
+    if (!isRange(sprite.width) || sprite.width[0] <= 0) err(`${path}.width`, "must be a [min,max] range of positive px");
+    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");
     }
+    color(sprite.color, `${path}.color`, err);
+    validatePalette(sprite, path, err);
   } else {
-    err(`${path}.kind`, "must be emoji | text | circle");
+    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect");
+    return;
+  }
+  for (const k of unknownKeys(sprite, knownSet)) {
+    if (LAYER_PROPS_ON_SPRITE.has(k)) {
+      warn(`${path}.${k}`, "misplaced-property", `'${k}' belongs on the layer, not inside sprite \u2014 move it up one level`);
+    } else {
+      warn(`${path}.${k}`, "unknown-property", `unknown sprite property '${k}' \u2014 will be ignored`);
+    }
+  }
+}
+function validatePalette(sprite, path, err) {
+  if (sprite.colors !== void 0) {
+    if (!Array.isArray(sprite.colors) || sprite.colors.length === 0) {
+      err(`${path}.colors`, "must be a non-empty array of hex colours");
+    } else {
+      sprite.colors.forEach((c, ci) => color(c, `${path}.colors[${ci}]`, err));
+    }
+  }
+  if (sprite.colorWeights !== void 0) {
+    if (!Array.isArray(sprite.colors)) {
+      err(`${path}.colorWeights`, "requires colors to be set");
+    } else if (!Array.isArray(sprite.colorWeights) || sprite.colorWeights.length !== sprite.colors.length) {
+      err(`${path}.colorWeights`, "must be an array the same length as colors");
+    } else if (!sprite.colorWeights.every((v) => isNum(v) && v >= 0) || !sprite.colorWeights.some((v) => isNum(v) && v > 0)) {
+      err(`${path}.colorWeights`, "weights must be >= 0 with at least one > 0");
+    }
   }
 }
 function validateCycle(sprite, path, err) {
@@ -218,29 +437,92 @@ function validateCycle(sprite, path, err) {
     err(`${path}.cycle.period`, `must be >= ${LIMITS.minCyclePeriod} ms (flash-safety floor)`);
   }
 }
-function validateMotion(motion, path, err, spec) {
+function validateMotion(motion, path, err, warn, spec) {
   if (!isObj(motion)) return err(path, "must be an object");
-  const isViewport = isObj(spec) && spec.units === "viewport";
-  const speedCap = isViewport ? LIMITS.maxSpeed / LIMITS.referenceViewport : LIMITS.maxSpeed;
+  const isViewport = !isObj(spec) || spec.units !== "px";
+  const refVp = isObj(spec) && isNum(spec.referenceViewport) ? spec.referenceViewport : LIMITS.referenceViewport;
+  const speedCap = isViewport ? LIMITS.maxSpeed / refVp : LIMITS.maxSpeed;
   const speedOk = (v, p) => {
     if (!isRange(v)) err(p, "must be a [min,max] range");
+    else if (v[0] < 0) err(p, "speed lower bound must be >= 0");
     else if (v[1] > speedCap) err(p, `speed exceeds cap ${isViewport ? speedCap.toFixed(2) + " viewport-units/sec" : LIMITS.maxSpeed + " px/sec"}`);
   };
+  let knownSet;
   if (motion.type === "drift") {
+    knownSet = KNOWN_DRIFT;
     speedOk(motion.speed, `${path}.speed`);
     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");
+    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`);
+    }
   } else if (motion.type === "rise") {
+    knownSet = KNOWN_RISE;
     speedOk(motion.speed, `${path}.speed`);
     if (motion.sway !== void 0 && !isNum(motion.sway)) err(`${path}.sway`, "must be a number");
+    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`);
+    }
   } else if (motion.type === "bounce") {
+    knownSet = KNOWN_BOUNCE;
     speedOk(motion.speed, `${path}.speed`);
+    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: 20\u2013150 px/sec`);
+    }
   } else if (motion.type === "static") {
+    knownSet = KNOWN_STATIC;
   } else if (motion.type === "orbit") {
+    knownSet = KNOWN_ORBIT;
     if (!isRange(motion.speed)) err(`${path}.speed`, "must be a [min,max] range");
-    else if (Math.abs(motion.speed[0]) > LIMITS.maxOrbitSpeed || Math.abs(motion.speed[1]) > LIMITS.maxOrbitSpeed) err(`${path}.speed`, `orbit speed exceeds cap ${LIMITS.maxOrbitSpeed} deg/sec`);
+    else {
+      if (Math.abs(motion.speed[0]) > LIMITS.maxOrbitSpeed || Math.abs(motion.speed[1]) > LIMITS.maxOrbitSpeed) err(`${path}.speed`, `orbit speed exceeds cap ${LIMITS.maxOrbitSpeed} deg/sec`);
+      if (Math.max(Math.abs(motion.speed[0]), Math.abs(motion.speed[1])) < 1) {
+        warn(`${path}.speed`, "near-zero-speed", `orbit speed is near zero \u2014 entities will appear frozen. Typical range: 5\u201360 deg/sec`);
+      }
+    }
     if (!isRange(motion.radius) || motion.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
+    if (motion.center !== void 0) {
+      if (!isObj(motion.center)) {
+        err(`${path}.center`, "must be {x, y} (0..1) or { layer: key }");
+      } else if ("layer" in motion.center) {
+        if (!isStr(motion.center.layer) || motion.center.layer.trim() === "") {
+          err(`${path}.center.layer`, "must be a non-empty layer key");
+        } else if (isObj(spec) && Array.isArray(spec.layers)) {
+          const layers = spec.layers;
+          const parent = layers.find((l) => isObj(l) && l.key === motion.center.layer);
+          if (!parent) {
+            err(`${path}.center.layer`, `no layer with key '${motion.center.layer}'`);
+          } else {
+            if (parent.count !== 1) err(`${path}.center.layer`, "parent layer must have count: 1");
+            const pm = parent.motion;
+            if (isObj(pm) && pm.type === "orbit" && isObj(pm.center) && "layer" in pm.center) {
+              err(`${path}.center.layer`, "parent may not itself orbit a layer (one level deep only)");
+            }
+          }
+        }
+      } else if (!isNum(motion.center.x) || !isNum(motion.center.y)) {
+        err(`${path}.center`, "must be {x, y} with numbers 0..1");
+      } else {
+        if (motion.center.x < 0 || motion.center.x > 1) err(`${path}.center.x`, "must be 0..1");
+        if (motion.center.y < 0 || motion.center.y > 1) err(`${path}.center.y`, "must be 0..1");
+      }
+    }
+  } else if (motion.type === "wander") {
+    knownSet = KNOWN_WANDER;
+    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;
+    if (motion.meander !== void 0 && (!isNum(motion.meander) || motion.meander <= 0 || motion.meander > meanderCap)) {
+      err(`${path}.meander`, `must be > 0 and <= ${isViewport ? meanderCap.toFixed(3) + " viewport-units" : LIMITS.maxMeander + " px"}`);
+    }
+    if (motion.coherence !== void 0 && (!isNum(motion.coherence) || motion.coherence < 0 || motion.coherence > 1)) {
+      err(`${path}.coherence`, "must be 0..1");
+    }
+  } else if (motion.type === "warp") {
+    knownSet = KNOWN_WARP;
+    if (!isRange(motion.speed) || motion.speed[0] < 0) err(`${path}.speed`, "must be a [min,max] range >= 0 (depth-units/sec)");
+    else if (motion.speed[1] > LIMITS.maxWarpSpeed) err(`${path}.speed`, `warp speed exceeds cap ${LIMITS.maxWarpSpeed} depth-units/sec`);
     if (motion.center !== void 0) {
       if (!isObj(motion.center) || !isNum(motion.center.x) || !isNum(motion.center.y)) {
         err(`${path}.center`, "must be {x, y} with numbers 0..1");
@@ -249,8 +531,34 @@ function validateMotion(motion, path, err, spec) {
         if (motion.center.y < 0 || motion.center.y > 1) err(`${path}.center.y`, "must be 0..1");
       }
     }
+  } else if (motion.type === "path") {
+    knownSet = KNOWN_PATH;
+    if (!Array.isArray(motion.points) || motion.points.length < LIMITS.minPathPoints || motion.points.length > LIMITS.maxPathPoints) {
+      err(`${path}.points`, `must be an array of ${LIMITS.minPathPoints}..${LIMITS.maxPathPoints} points`);
+    } else {
+      motion.points.forEach((p, pi) => {
+        if (!isObj(p) || !isNum(p.x) || !isNum(p.y) || p.x < 0 || p.x > 1 || p.y < 0 || p.y > 1) {
+          err(`${path}.points[${pi}]`, "must be {x, y} with numbers 0..1");
+        }
+      });
+    }
+    if (!isNum(motion.duration) || motion.duration < LIMITS.minPathDuration) {
+      err(`${path}.duration`, `must be >= ${LIMITS.minPathDuration} ms`);
+    }
+    if (motion.curve !== void 0 && motion.curve !== "linear" && motion.curve !== "smooth") {
+      err(`${path}.curve`, "must be 'linear' | 'smooth'");
+    }
+    if (motion.closed !== void 0 && typeof motion.closed !== "boolean") err(`${path}.closed`, "must be a boolean");
+    const scatterCap = isViewport ? LIMITS.maxMeander / refVp : LIMITS.maxMeander;
+    if (motion.scatter !== void 0 && (!isNum(motion.scatter) || motion.scatter <= 0 || motion.scatter > scatterCap)) {
+      err(`${path}.scatter`, `must be > 0 and <= ${isViewport ? scatterCap.toFixed(3) + " viewport-units" : LIMITS.maxMeander + " px"}`);
+    }
   } else {
-    err(`${path}.type`, "must be drift | rise | bounce | static | orbit");
+    err(`${path}.type`, "must be drift | rise | bounce | static | orbit | wander | warp | path");
+    return;
+  }
+  for (const k of unknownKeys(motion, knownSet)) {
+    warn(`${path}.${k}`, "unknown-property", `unknown motion property '${k}' \u2014 will be ignored`);
   }
 }
 function assertValidSpec(spec) {
@@ -263,23 +571,98 @@ ${r.errors.map((e) => `  ${e.path || "<root>"}: ${e.message}`).join("\n")}`);
 }
 
 // src/simulate.ts
+var WARP_NEAR = 0.08;
+var WARP_MAX_SCALE = 8;
 function spriteVariants(sprite) {
   if (sprite.kind === "emoji") return sprite.glyphs.length;
   if (sprite.kind === "text") return sprite.strings.length;
   return 1;
 }
-function buildEntities(layer, rng, w, h, scale = 1) {
+var OCT_AMP = [1, 0.5, 0.25];
+var OCT_PERIOD = [
+  [6e3, 14e3],
+  [3e3, 7e3],
+  [1500, 4e3]
+];
+function drawOsc(rng, amp) {
+  const osc = { ax: [], fx: [], phx: [], ay: [], fy: [], phy: [] };
+  for (let i = 0; i < 3; i++) {
+    osc.ax.push(amp * OCT_AMP[i] * rng.range(0.6, 1.4));
+    osc.fx.push(2 * Math.PI / rng.range(OCT_PERIOD[i][0], OCT_PERIOD[i][1]));
+    osc.phx.push(rng.range(0, Math.PI * 2));
+  }
+  for (let i = 0; i < 3; i++) {
+    osc.ay.push(amp * OCT_AMP[i] * rng.range(0.6, 1.4));
+    osc.fy.push(2 * Math.PI / rng.range(OCT_PERIOD[i][0], OCT_PERIOD[i][1]));
+    osc.phy.push(rng.range(0, Math.PI * 2));
+  }
+  return osc;
+}
+function weightedIndex(u, weights) {
+  const total = weights.reduce((a, b) => a + b, 0);
+  let acc = 0;
+  for (let i = 0; i < weights.length; i++) {
+    acc += weights[i] / total;
+    if (u < acc) return i;
+  }
+  return weights.length - 1;
+}
+function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
+  const effectiveCount = countScale === 1 ? 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 colorsLen = layer.sprite.kind === "circle" && layer.sprite.colors ? layer.sprite.colors.length : 0;
-  const cycle = layer.sprite.kind === "emoji" || layer.sprite.kind === "text" ? layer.sprite.cycle : void 0;
+  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 colorsLen = spriteColors?.length ?? 0;
+  const cycle = sprite.kind === "emoji" || sprite.kind === "text" ? sprite.cycle : void 0;
+  const mSpec = layer.motion;
+  let sharedOsc = null;
+  let meanderPx = 0;
+  if (mSpec.type === "wander") {
+    meanderPx = (mSpec.meander ?? (scale === 1 ? 60 : 0.05)) * scale;
+    sharedOsc = drawOsc(rng, meanderPx);
+  }
+  let pathPts = null;
+  if (mSpec.type === "path") {
+    pathPts = mSpec.points.map((p) => ({ x: p.x * w, y: p.y * h }));
+  }
+  const layout = layer.layout;
+  let gridCols = 0;
+  let cellW = 0;
+  let cellH = 0;
+  let gridX0 = 0;
+  let gridY0 = 0;
+  if (layout?.type === "grid") {
+    const [rx0, rx1] = layer.region?.x ?? [0, 1];
+    const [ry0, ry1] = layer.region?.y ?? [0, 1];
+    const gw = Math.max(1, (rx1 - rx0) * w);
+    const gh = Math.max(1, (ry1 - ry0) * h);
+    gridCols = Math.min(
+      layout.columns ?? Math.max(1, Math.round(Math.sqrt(effectiveCount * (gw / gh)))),
+      LIMITS.maxGridColumns
+    );
+    const gridRows = Math.max(1, Math.ceil(effectiveCount / gridCols));
+    cellW = gw / gridCols;
+    cellH = gh / gridRows;
+    gridX0 = rx0 * w;
+    gridY0 = ry0 * h;
+  }
   const out = [];
-  for (let i = 0; i < layer.count; i++) {
-    const size = layer.sprite.kind === "circle" ? rng.range(layer.sprite.radius[0], layer.sprite.radius[1]) * 2 * scale : rng.range(smin, smax) * scale;
+  for (let i = 0; i < effectiveCount; i++) {
+    const size = 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;
     let vx = 0;
     let vy = 0;
     let bob = 0;
     let motion = "drift";
+    let warpParams;
+    let pathPhase = 0;
+    let pathOffX = 0;
+    let pathOffY = 0;
     const m = layer.motion;
     if (m.type === "static") {
       motion = "static";
@@ -303,18 +686,53 @@ function buildEntities(layer, rng, w, h, scale = 1) {
     } else if (m.type === "orbit") {
       motion = "orbit";
       vx = rng.range(m.speed[0], m.speed[1]);
+    } else if (m.type === "wander") {
+      motion = "wander";
+      const s = rng.range(m.speed[0], m.speed[1]) * scale;
+      const heading = m.angle !== void 0 ? m.angle * Math.PI / 180 : rng.range(0, Math.PI * 2);
+      vx = s * Math.cos(heading);
+      vy = s * Math.sin(heading);
+    } else if (m.type === "warp") {
+      motion = "warp";
+      const vz = rng.range(m.speed[0], m.speed[1]);
+      const theta = rng.range(0, Math.PI * 2);
+      const r = rng.range(0.15, 1);
+      warpParams = {
+        ux: Math.cos(theta) * r,
+        uy: Math.sin(theta) * r,
+        z0: rng.range(WARP_NEAR, 1),
+        vz,
+        cx: (m.center?.x ?? 0.5) * w,
+        cy: (m.center?.y ?? 0.5) * h
+      };
+    } else if (m.type === "path") {
+      motion = "path";
+      pathPhase = rng.next();
+      if (m.scatter) {
+        pathOffX = rng.range(-1, 1) * m.scatter * scale;
+        pathOffY = rng.range(-1, 1) * m.scatter * scale;
+      }
     }
     let x0;
     let y0;
     if (layer.position && layer.count === 1) {
       x0 = layer.position.x * w;
       y0 = layer.position.y * h;
+    } else if (layout?.type === "grid") {
+      const col = i % gridCols;
+      const row = Math.floor(i / gridCols);
+      const j = layout.jitter ?? 0;
+      const jx = typeof j === "number" ? j : j.x ?? 0;
+      const jy = typeof j === "number" ? j : j.y ?? 0;
+      x0 = gridX0 + (col + 0.5) * cellW + rng.range(-0.5, 0.5) * jx * cellW;
+      y0 = gridY0 + (row + 0.5) * cellH + rng.range(-0.5, 0.5) * jy * cellH;
     } else {
       const [rx0, rx1] = layer.region?.x ?? [0, 1];
       const [ry0, ry1] = layer.region?.y ?? [0, 1];
       x0 = rng.range(rx0 * w, rx1 * w);
       y0 = rng.range(ry0 * h, ry1 * h);
     }
+    const orbitParent = m.type === "orbit" && m.center && "layer" in m.center ? m.center.layer : void 0;
     out.push({
       x0,
       y0,
@@ -338,29 +756,79 @@ function buildEntities(layer, rng, w, h, scale = 1) {
       growPeriod: layer.grow?.period ?? 1e3,
       growPhase: layer.grow ? rng.range(0, Math.PI * 2) : 0,
       orbitR: m.type === "orbit" ? rng.range(m.radius[0], m.radius[1]) * scale : 0,
-      orbitCx: m.type === "orbit" ? (m.center?.x ?? 0.5) * w : 0,
-      orbitCy: m.type === "orbit" ? (m.center?.y ?? 0.5) * h : 0,
+      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 ? rng.int(0, colorsLen - 1) : -1,
-      cyclePeriod: cycle ? cycle.period : 0
+      colorIndex: colorsLen > 0 ? colorWeights && colorWeights.length === colorsLen ? weightedIndex(rng.next(), colorWeights) : 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 } : {},
+      ...orbitParent ? { orbitParent } : {},
+      ...m.type === "wander" ? {
+        wander: {
+          own: drawOsc(rng, meanderPx),
+          shared: sharedOsc,
+          coherence: Math.max(0, Math.min(1, m.coherence ?? 0)),
+          margin: meanderPx * (OCT_AMP[0] + OCT_AMP[1] + OCT_AMP[2]) * 1.4
+        }
+      } : {},
+      ...warpParams ? { warp: warpParams } : {},
+      ...m.type === "path" && pathPts ? {
+        path: {
+          pts: pathPts,
+          duration: m.duration,
+          closed: m.closed !== false,
+          smooth: m.curve !== "linear",
+          phase: pathPhase,
+          offX: pathOffX,
+          offY: pathOffY
+        }
+      } : {}
     });
+    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;
+    }
   }
   return out;
 }
+function warpZ(e, t) {
+  const wp = e.warp;
+  return wrap(wp.z0 - wp.vz * (t / 1e3), WARP_NEAR, 1);
+}
 function alphaAt(e, t) {
-  if (!e.pulseAmp) return e.alpha;
-  const a = e.alpha + e.pulseAmp * Math.sin(t * 2 * Math.PI / e.pulsePeriod + e.pulsePhase);
+  let a = e.alpha;
+  if (e.pulseAmp) a = e.alpha + e.pulseAmp * Math.sin(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));
+  }
   return a < 0 ? 0 : a > 1 ? 1 : a;
 }
 function sizeAt(e, t) {
-  if (!e.growAmp) return e.size;
-  const s = e.size * (1 + e.growAmp * Math.sin(t * 2 * Math.PI / e.growPeriod + e.growPhase));
+  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.motion === "warp") s *= Math.min(1 / warpZ(e, t), WARP_MAX_SCALE);
   return s > 0 ? s : 0.1;
 }
 function rotationAt(e, t) {
   if (!e.spinSpeed) return 0;
   return e.spinPhase + e.spinSpeed * (t / 1e3);
 }
+function lifeAlphaAt(life, t) {
+  if (!life) return 1;
+  const fade = life.fade ?? 1e3;
+  let a = 1;
+  if (life.enter !== void 0) {
+    if (t < life.enter) return 0;
+    a = fade > 0 ? Math.min(1, (t - life.enter) / fade) : 1;
+  }
+  if (life.exit !== void 0 && t >= life.exit) {
+    a *= fade > 0 ? Math.max(0, 1 - (t - life.exit) / fade) : 0;
+  }
+  return a;
+}
 function wrap(v, min, max) {
   const range = max - min;
   return ((v - min) % range + range) % range + min;
@@ -372,6 +840,40 @@ 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) {
+  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 pathPosition(e, t) {
+  const p = e.path;
+  const n = p.pts.length;
+  let s = (t / p.duration + p.phase) % 1;
+  if (s < 0) s += 1;
+  if (!p.closed) {
+    const pp = s * 2;
+    s = pp < 1 ? pp : 2 - pp;
+  }
+  const segs = p.closed ? n : n - 1;
+  const u = Math.min(s * segs, segs - 1e-9);
+  const i = Math.floor(u);
+  const local = u - i;
+  const at = (k) => p.closed ? p.pts[(k % n + n) % n] : p.pts[Math.max(0, Math.min(n - 1, k))];
+  const p1 = at(i);
+  const p2 = at(i + 1);
+  if (!p.smooth) {
+    return {
+      x: p1.x + (p2.x - p1.x) * local + p.offX,
+      y: p1.y + (p2.y - p1.y) * local + p.offY
+    };
+  }
+  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
+  };
+}
 function positionAt(e, t, w, h) {
   if (e.motion === "static") return { x: e.x0, y: e.y0, flip: false };
   if (e.motion === "orbit") {
@@ -382,6 +884,20 @@ function positionAt(e, t, w, h) {
       flip: false
     };
   }
+  if (e.motion === "warp") {
+    const wp = e.warp;
+    const persp = 1 / warpZ(e, t);
+    const halfMin = Math.min(w, h) / 2;
+    return {
+      x: wp.cx + wp.ux * halfMin * persp,
+      y: wp.cy + wp.uy * halfMin * persp,
+      flip: false
+    };
+  }
+  if (e.motion === "path") {
+    const pos = pathPosition(e, t);
+    return { x: pos.x, y: pos.y, flip: false };
+  }
   const dt = t / 1e3;
   const m = e.size;
   if (e.motion === "bounce") {
@@ -398,15 +914,94 @@ function positionAt(e, t, w, h) {
       flip: false
     };
   }
+  if (e.motion === "wander") {
+    const wp = e.wander;
+    const c = wp.coherence;
+    let hx = 0;
+    let hy = 0;
+    for (let i = 0; i < 3; i++) {
+      if (c < 1) {
+        hx += (1 - c) * wp.own.ax[i] * Math.sin(wp.own.fx[i] * t + wp.own.phx[i]);
+        hy += (1 - c) * wp.own.ay[i] * Math.sin(wp.own.fy[i] * t + wp.own.phy[i]);
+      }
+      if (c > 0) {
+        hx += c * wp.shared.ax[i] * Math.sin(wp.shared.fx[i] * t + wp.shared.phx[i]);
+        hy += c * wp.shared.ay[i] * Math.sin(wp.shared.fy[i] * t + wp.shared.phy[i]);
+      }
+    }
+    const margin = m + wp.margin;
+    return {
+      x: wrap(e.x0 + e.vx * dt + hx, -margin, w + margin),
+      y: wrap(e.y0 + e.vy * dt + hy, -margin, h + margin),
+      flip: e.headingLeft
+    };
+  }
   const x = wrap(e.x0 + e.vx * dt, -m, w + m);
   let y = e.vy !== 0 ? wrap(e.y0 + e.vy * dt, -m, h + m) : e.y0;
   if (e.bob) y += e.bob * Math.sin(t / 500 + e.phase);
   return { x, y, flip: e.headingLeft };
 }
+function headingAt(e, t, w, h) {
+  const dtMs = 32;
+  const t1 = t < dtMs ? t + dtMs : t;
+  const t0 = t1 - dtMs;
+  const a = positionAt(e, t0, w, h);
+  const b = positionAt(e, t1, w, h);
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) return null;
+  if (dx === 0 && dy === 0) return null;
+  return Math.atan2(dy, dx);
+}
 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;
 }
+function wrapDist(pi, pj, doWrap, w, h) {
+  let dx = pj.x - pi.x;
+  let dy = pj.y - pi.y;
+  if (doWrap) {
+    if (Math.abs(dx) > w / 2) dx = dx > 0 ? dx - w : dx + w;
+    if (Math.abs(dy) > h / 2) dy = dy > 0 ? dy - h : dy + h;
+  }
+  return Math.sqrt(dx * dx + dy * dy);
+}
+function linkEdges(links, positions, maxDistPx, doWrap, w, h) {
+  const n = positions.length;
+  const mode = links.mode ?? "nearest";
+  if (mode === "chain") {
+    const out = [];
+    for (let i = 0; i < n - 1; i++) {
+      out.push({ i, j: i + 1, dist: wrapDist(positions[i], positions[i + 1], doWrap, w, h) });
+    }
+    if (links.closed && n > 2) out.push({ i: n - 1, j: 0, dist: wrapDist(positions[n - 1], positions[0], doWrap, w, h) });
+    return out;
+  }
+  if (mode === "random") {
+    const stride = Math.max(1, Math.round(n * 0.381966));
+    const edges = /* @__PURE__ */ new Set();
+    const out = [];
+    for (let i = 0; i < n; i++) {
+      for (let mIdx = 1; mIdx <= links.k; mIdx++) {
+        const j = (i + mIdx * stride) % n;
+        if (j === i) continue;
+        const dist = wrapDist(positions[i], positions[j], doWrap, w, h);
+        if (dist > maxDistPx) continue;
+        const key = `${Math.min(i, j)}:${Math.max(i, j)}`;
+        if (!edges.has(key)) {
+          edges.add(key);
+          out.push({ i: Math.min(i, j), j: Math.max(i, j), dist });
+        }
+      }
+    }
+    return out;
+  }
+  return linkPairs(positions, links.k, maxDistPx, doWrap, w, h).map(([i, j]) => ({
+    i,
+    j,
+    dist: wrapDist(positions[i], positions[j], doWrap, w, h)
+  }));
+}
 function linkPairs(positions, k, maxDist, doWrap, w, h) {
   const n = positions.length;
   const edges = /* @__PURE__ */ new Set();
@@ -513,6 +1108,32 @@ function lerpSpec(from, to, k) {
   };
   return walk(from, to);
 }
+function steerablePaths(spec) {
+  if (!spec || typeof spec !== "object") return [];
+  const SKIP = /* @__PURE__ */ new Set(["kind", "type", "key", "schemaVersion", "id", "label", "seed", "units", "mode", "curve", "layer"]);
+  const INDEXED = /* @__PURE__ */ new Set(["layers", "stops"]);
+  const out = [];
+  const walk = (node, prefix, key) => {
+    if (Array.isArray(node) && INDEXED.has(key)) {
+      node.forEach((child, i) => walk(child, `${prefix}.${i}`, ""));
+      return;
+    }
+    if (Array.isArray(node)) {
+      if (prefix) out.push(prefix);
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const [k, v] of Object.entries(node)) {
+        if (SKIP.has(k)) continue;
+        walk(v, prefix ? `${prefix}.${k}` : k, k);
+      }
+      return;
+    }
+    if (prefix) out.push(prefix);
+  };
+  walk(spec, "", "");
+  return out;
+}
 function easeSmooth(k) {
   const c = Math.max(0, Math.min(1, k));
   return c * c * (3 - 2 * c);
@@ -520,23 +1141,32 @@ function easeSmooth(k) {
 function structuralSignature(spec) {
   return JSON.stringify([
     spec.units,
-    spec.layers.map((l) => [
-      l.count,
-      l.size,
-      l.region,
-      l.position,
-      l.motion,
-      l.wrap,
-      l.flip,
-      l.alpha,
-      l.pulse,
-      l.spin,
-      l.grow,
-      l.sprite.kind,
-      l.sprite.kind === "circle" ? l.sprite.radius : void 0,
-      l.sprite.kind === "circle" ? l.sprite.colors?.length : void 0,
-      l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : void 0
-    ])
+    spec.layers.map((l) => {
+      const s = l.sprite;
+      return [
+        l.count,
+        l.size,
+        l.region,
+        l.position,
+        l.motion,
+        l.wrap,
+        l.flip,
+        l.alpha,
+        l.pulse,
+        l.spin,
+        l.grow,
+        l.layout,
+        l.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,
+        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] : void 0
+      ];
+    })
   ]);
 }
 
@@ -547,6 +1177,12 @@ function hexToRgba(hex, alpha) {
   const n = parseInt(h.slice(1), 16);
   return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${alpha})`;
 }
+var FONT_PREFIX_RE = /^((?:(?:italic|oblique|bold|bolder|lighter|normal|\d{3})\s+)+)/;
+function composeFontShorthand(sz, font) {
+  const m = FONT_PREFIX_RE.exec(font);
+  if (m) return `${m[1].trim()} ${sz}px ${font.slice(m[0].length)}`;
+  return `${sz}px ${font}`;
+}
 function manifestFor(spec) {
   const total = spec.layers.reduce((n, l) => n + l.count, 0);
   const costTier = total < 30 ? "idle" : total < 150 ? "low" : total < 400 ? "medium" : "high";
@@ -606,6 +1242,8 @@ var SpecInstance = class {
   baseT = 0;
   // elapsed logical time carried across pause/resume
   lastT = 0;
+  /** Last time painted — detects non-contiguous seeks for the ghosting warm-up replay. */
+  lastRenderT = Number.NEGATIVE_INFINITY;
   /** The spec currently being rendered (base spec + any applied steering). */
   effSpec;
   /** Active glide between two resolved specs (live setParam/applyTrack). */
@@ -616,12 +1254,19 @@ var SpecInstance = class {
     this.canvas.width = Math.max(1, Math.round(this.w * dpr));
     this.canvas.height = Math.max(1, Math.round(this.h * dpr));
     this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    this.lastRenderT = Number.NEGATIVE_INFINITY;
   }
-  /** (Re)seed and place all entities — deterministic for the seed + size. */
+  /** (Re)seed and place all entities — deterministic for the seed + viewport. */
   rebuild() {
     const rng = createRng(this.seed);
-    const scale = this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1;
-    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h, scale) }));
+    const scale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
+    const refVp = this.effSpec.referenceViewport ?? LIMITS.referenceViewport;
+    let countScale = scale > 1 ? Math.min(this.w, this.h) / refVp : 1;
+    if (countScale > 1) {
+      const rawTotal = this.effSpec.layers.reduce((s, l) => s + Math.round(l.count * countScale), 0);
+      if (rawTotal > LIMITS.maxTotal) countScale *= LIMITS.maxTotal / rawTotal;
+    }
+    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h, scale, countScale) }));
     this.lastStructural = structuralSignature(this.effSpec);
   }
   start() {
@@ -642,7 +1287,7 @@ var SpecInstance = class {
     this.lastT = now - this.startT + this.baseT;
     this.renderFrame(this.lastT, this.seed);
   }
-  drawBackground() {
+  drawBackground(t) {
     const { ctx, w, h } = this;
     const bg = this.effSpec.background;
     if (!bg || bg.type === "solid") {
@@ -651,22 +1296,136 @@ var SpecInstance = class {
       return;
     }
     const g = ctx.createLinearGradient(0, 0, 0, h);
-    for (const s of bg.stops) g.addColorStop(Math.max(0, Math.min(1, s.at)), s.color);
+    const drift = bg.drift;
+    for (let i = 0; i < bg.stops.length; i++) {
+      const s = bg.stops[i];
+      let at = s.at;
+      if (drift) {
+        const amount = drift.amount ?? 0.15;
+        const phase = i / bg.stops.length * Math.PI * 2;
+        at = Math.max(0, Math.min(1, at + amount * Math.sin(t * 2 * Math.PI / drift.period + phase)));
+      }
+      g.addColorStop(at, s.color);
+    }
     ctx.fillStyle = g;
     ctx.fillRect(0, 0, w, h);
     if (bg.band) {
       ctx.fillStyle = bg.band.color;
-      const bh = bg.band.height * (this.effSpec.units === "viewport" ? Math.min(w, h) : 1);
+      const bh = bg.band.height * (this.effSpec.units === "px" ? 1 : Math.min(w, h));
       ctx.fillRect(0, h - bh, w, bh);
     }
   }
-  drawEntity(built, e, t) {
-    const { ctx } = this;
+  /** Position with parent-orbit resolution: a layer-parented orbit entity's
+   *  positionAt is an offset around (0,0); add the parent's own analytic position. */
+  entityPos(e, t, parentE) {
     const p = positionAt(e, t, this.w, this.h);
+    if (parentE && e.orbitParent) {
+      const pp = positionAt(parentE, t, this.w, this.h);
+      p.x += pp.x;
+      p.y += pp.y;
+    }
+    return p;
+  }
+  /** Resolve the single parent entity for a layer-parented orbit layer (or null). */
+  parentEntityFor(built) {
+    const m = built.layer.motion;
+    if (m.type !== "orbit" || !m.center || !("layer" in m.center)) return null;
+    const key = m.center.layer;
+    const parent = this.layers.find((b) => b.layer.key === key);
+    return parent?.entities[0] ?? null;
+  }
+  drawTrail(built, e, t, lifeA, parentE) {
+    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 resolvedColor = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" ? 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 (isSoft) {
+        const g = ctx.createRadialGradient(pos.x, pos.y, 0, pos.x, pos.y, 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.arc(pos.x, pos.y, r, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+  drawEntity(built, e, t, lifeA, parentE) {
+    const { ctx } = this;
+    const p = this.entityPos(e, t, parentE);
     const sprite = built.layer.sprite;
     const sz = sizeAt(e, t);
     const rot = rotationAt(e, t);
-    ctx.globalAlpha = alphaAt(e, t);
+    const unitScale = this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h);
+    ctx.globalAlpha = alphaAt(e, t) * lifeA;
+    if (sprite.kind === "ring") {
+      const r = sz / 2;
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      ctx.strokeStyle = resolvedColor;
+      ctx.lineWidth = Math.max(0.5, (sprite.width ?? (unitScale === 1 ? 2 : 2e-3)) * unitScale);
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, r, 0, Math.PI * 2);
+      ctx.stroke();
+      return;
+    }
+    if (sprite.kind === "streak") {
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      const heading = headingAt(e, t, this.w, this.h) ?? 0;
+      const tailX = p.x - Math.cos(heading) * sz;
+      const tailY = p.y - Math.sin(heading) * sz;
+      const g = ctx.createLinearGradient(tailX, tailY, p.x, p.y);
+      g.addColorStop(0, hexToRgba(resolvedColor, 0));
+      g.addColorStop(1, resolvedColor);
+      ctx.strokeStyle = g;
+      ctx.lineWidth = Math.max(0.5, (sprite.width ?? (unitScale === 1 ? 2 : 2e-3)) * unitScale);
+      ctx.lineCap = "round";
+      ctx.beginPath();
+      ctx.moveTo(tailX, tailY);
+      ctx.lineTo(p.x, p.y);
+      ctx.stroke();
+      return;
+    }
+    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;
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      if (rot) ctx.rotate(rot);
+      ctx.fillStyle = resolvedColor;
+      ctx.fillRect(-sz / 2, -rh / 2, sz, rh);
+      ctx.restore();
+      return;
+    }
     if (sprite.kind === "circle") {
       const r = sz / 2;
       const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
@@ -704,11 +1463,11 @@ var SpecInstance = class {
     } else {
       ctx.textAlign = sprite.align ?? "center";
       ctx.textBaseline = sprite.baseline ?? "middle";
-      ctx.font = sprite.font ?? `${sz}px system-ui, sans-serif`;
+      ctx.font = sprite.font ? /\dpx/.test(sprite.font) ? sprite.font : composeFontShorthand(sz, sprite.font) : `${sz}px system-ui, sans-serif`;
       ctx.fillStyle = sprite.color ?? "#e6e8ef";
       const idx = spriteIndexAt(e, t, sprite.strings.length);
       const text = sprite.strings[idx] ?? sprite.strings[0];
-      const mw = sprite.maxWidth ? sprite.maxWidth * (this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1) : void 0;
+      const mw = sprite.maxWidth ? sprite.maxWidth * (this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h)) : void 0;
       if (mw) ctx.fillText(text, 0, 0, mw);
       else ctx.fillText(text, 0, 0);
     }
@@ -752,26 +1511,32 @@ var SpecInstance = class {
       this.renderFrame(this.lastT, this.seed);
     }
   }
-  drawLinks(built, t) {
+  drawLinks(built, t, lifeA, parentE) {
     const { links } = built.layer;
     if (!links) return;
     const { ctx } = this;
-    const wrap2 = built.layer.wrap !== false;
-    const positions = built.entities.map((e) => positionAt(e, t, this.w, this.h));
-    const pairs = linkPairs(positions, links.k, links.maxDist * (this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1), wrap2, this.w, this.h);
-    const lw = (links.width ?? 1) * (this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1);
+    const motionWraps = ["drift", "rise", "wander"].includes(built.layer.motion.type);
+    const wrap2 = built.layer.wrap !== false && motionWraps;
+    const positions = built.entities.map((e) => this.entityPos(e, t, parentE));
+    const maxDistPx = links.maxDist * (this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h));
+    const edges = linkEdges(links, positions, maxDistPx, wrap2, this.w, this.h);
+    const lw = (links.width ?? 1) * (this.effSpec.units === "px" ? 1 : Math.min(this.w, this.h));
     ctx.lineWidth = lw;
-    for (const [i, j] of pairs) {
+    ctx.lineCap = "butt";
+    for (const { i, j, dist } of edges) {
       const pi = positions[i];
       const pj = positions[j];
       const ei = built.entities[i];
       let resolvedColor = links.color;
       if (!resolvedColor) {
         const sprite = built.layer.sprite;
-        if (sprite.kind === "circle") resolvedColor = sprite.colors?.[ei.colorIndex] ?? sprite.color;
-        else resolvedColor = "#e6e8ef";
+        if (sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect") {
+          resolvedColor = sprite.colors?.[ei.colorIndex] ?? sprite.color;
+        } else resolvedColor = "#e6e8ef";
       }
-      ctx.globalAlpha = links.alpha ?? alphaAt(ei, t);
+      let a = links.alpha ?? alphaAt(ei, t);
+      if (links.falloff) a *= Math.max(0, 1 - dist / maxDistPx);
+      ctx.globalAlpha = a * lifeA;
       ctx.strokeStyle = resolvedColor;
       let dx = pj.x - pi.x;
       let dy = pj.y - pi.y;
@@ -785,21 +1550,57 @@ var SpecInstance = class {
       ctx.stroke();
     }
   }
-  /** Deterministic, frame-addressable render (shared by the rAF loop). */
-  renderFrame(t, _seed) {
-    this.stepTransition(t);
+  /** Paint one composite pass at time t. `bgAlpha` < 1 leaves the previous frame
+   *  showing through — the ghosting smear. */
+  paintFrame(t, bgAlpha) {
     const { ctx } = this;
-    ctx.globalAlpha = 1;
+    ctx.globalAlpha = bgAlpha;
     ctx.globalCompositeOperation = "source-over";
-    this.drawBackground();
+    this.drawBackground(t);
+    ctx.globalAlpha = 1;
     for (const built of this.layers) {
+      const lifeA = lifeAlphaAt(built.layer.life, t);
+      if (lifeA <= 0) continue;
+      const parentE = this.parentEntityFor(built);
       ctx.globalCompositeOperation = built.layer.blend ?? "source-over";
-      this.drawLinks(built, t);
-      for (const e of built.entities) this.drawEntity(built, e, t);
+      this.drawLinks(built, t, lifeA, parentE);
+      for (const e of built.entities) {
+        this.drawTrail(built, e, t, lifeA, parentE);
+        this.drawEntity(built, e, t, lifeA, parentE);
+      }
     }
     ctx.globalAlpha = 1;
     ctx.globalCompositeOperation = "source-over";
   }
+  /**
+   * Deterministic, frame-addressable render (shared by the rAF loop).
+   *
+   * With `ghosting` set, contiguous frames composite over the previous frame with a
+   * refresh-rate-normalized fade. A non-contiguous seek (pause render, e2e frame
+   * addressing) replays a bounded fixed-step warm-up from a full clear, so the
+   * accumulated smear at time t is identical on every run — the determinism proof
+   * survives statefulness because the "state" is reconstructed from pure history.
+   */
+  renderFrame(t, _seed) {
+    this.stepTransition(t);
+    const g = this.effSpec.ghosting ?? 0;
+    if (g > 0) {
+      const dt = 1e3 / 60;
+      const contiguous = this.lastRenderT !== Number.NEGATIVE_INFINITY && t > this.lastRenderT && t - this.lastRenderT <= 250;
+      if (contiguous) {
+        this.paintFrame(t, 1 - Math.pow(g, (t - this.lastRenderT) / dt));
+      } else {
+        const k = Math.min(Math.ceil(Math.log(1 / 255) / Math.log(g)), LIMITS.maxGhostReplayFrames);
+        const t0 = Math.max(0, t - k * dt);
+        this.paintFrame(t0, 1);
+        for (let ft = t0 + dt; ft < t - dt / 2; ft += dt) this.paintFrame(ft, 1 - g);
+        if (t > t0) this.paintFrame(t, 1 - g);
+      }
+    } else {
+      this.paintFrame(t, 1);
+    }
+    this.lastRenderT = t;
+  }
   setPaused(paused) {
     this.paused = paused;
     if (paused) {
@@ -836,9 +1637,11 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
   const warnings = [];
   const w = viewport.width;
   const h = viewport.height;
-  const scale = spec.units === "viewport" ? Math.min(w, h) : 1;
+  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);
-  const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale));
+  const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale, countScale));
   let totalEntities = 0;
   let textLayerCount = 0;
   let motionLayerCount = 0;
@@ -847,10 +1650,30 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
     const entities = allEntities[li];
     totalEntities += entities.length;
     const isText = layer.sprite.kind === "text";
-    const isEmoji = layer.sprite.kind === "emoji";
     const isStaticText = isText && layer.motion.type === "static";
     if (isStaticText) textLayerCount++;
     if (layer.motion.type !== "static") motionLayerCount++;
+    if (layer.trail && layer.motion.type === "static") {
+      warnings.push({
+        path: `layers[${li}].trail`,
+        code: "trail-on-static",
+        message: "trail has no effect on static entities \u2014 they have no past positions to draw"
+      });
+    }
+    if (layer.sprite.kind === "streak" && layer.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"
+      });
+    }
+    if (layer.motion.type === "wander" && layer.motion.coherence === 1 && entities.length >= 20) {
+      warnings.push({
+        path: `layers[${li}].motion.coherence`,
+        code: "full-coherence",
+        message: "coherence 1 makes every entity share identical harmonics \u2014 the layer moves as a rigid sheet. 0.5\u20130.8 reads as schooling"
+      });
+    }
     if (layer.sprite.kind === "circle") {
       const maxR = entities.reduce((m, e) => Math.max(m, e.size / 2), 0);
       const maxAlpha = entities.reduce((m, e) => Math.max(m, e.alpha), 0);
@@ -872,6 +1695,14 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       const pixArea = layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
       totalCoverage += pixArea * e.alpha / (w * h);
     }
+    if (layer.links) {
+      const positions = entities.map((e) => positionAt(e, 0, w, h));
+      const maxDistPx = layer.links.maxDist * scale;
+      const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false, w, h);
+      const lwPx = (layer.links.width ?? 1) * scale;
+      const la = layer.links.alpha ?? 1;
+      for (const edge of edges) totalCoverage += edge.dist * lwPx * la / (w * h);
+    }
   }
   if (totalCoverage < 5e-4 && spec.layers.length > 0) {
     warnings.push({
@@ -897,40 +1728,716 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       });
     }
   }
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    if (!layer.links || layer.links.mode === "chain") continue;
+    const entities = allEntities[li];
+    const positions = entities.map((e) => positionAt(e, 0, w, h));
+    const maxDist = layer.links.maxDist * scale;
+    const pairs = linkPairs(positions, layer.links.k, maxDist, layer.wrap !== false, w, h);
+    const maxPossible = Math.min(entities.length * layer.links.k, entities.length * (entities.length - 1) / 2);
+    if (maxPossible > 0 && pairs.length / maxPossible < 0.1) {
+      warnings.push({
+        path: `layers[${li}].links`,
+        code: "link-starvation",
+        message: `only ${pairs.length}/${maxPossible} possible edges formed \u2014 raise count or widen links.maxDist`
+      });
+    }
+  }
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    if (layer.motion.type === "static") continue;
+    const entities = allEntities[li];
+    if (entities.length < 3) continue;
+    const speeds = entities.map((e) => Math.sqrt(e.vx * e.vx + e.vy * e.vy));
+    const mean = speeds.reduce((a, b) => a + b, 0) / speeds.length;
+    if (mean === 0) continue;
+    const maxDev = Math.max(...speeds.map((s) => Math.abs(s - mean)));
+    if (maxDev / mean < 0.05) {
+      warnings.push({
+        path: `layers[${li}].motion`,
+        code: "uniform-motion",
+        message: "all entities move at nearly identical speed \u2014 widen the speed range for visual variety"
+      });
+    }
+  }
+  const composed = spec.layers.map((l, li) => ({ l, ents: allEntities[li] })).filter(({ l }) => !["bounce", "warp", "path"].includes(l.motion.type)).filter(({ l }) => !(l.motion.type === "orbit" && l.motion.center && "layer" in l.motion.center));
+  const composedCount = composed.reduce((s, c) => s + c.ents.length, 0);
+  if (composedCount >= 8) {
+    const positions = composed.flatMap(({ ents }) => ents.map((e) => positionAt(e, 0, w, h)));
+    const cx = positions.reduce((s, p) => s + p.x, 0) / positions.length;
+    const cy = positions.reduce((s, p) => s + p.y, 0) / positions.length;
+    const offX = Math.abs(cx / w - 0.5);
+    const offY = Math.abs(cy / h - 0.5);
+    if (offX > 0.2 || offY > 0.2) {
+      warnings.push({
+        path: "layers",
+        code: "off-center",
+        message: `centroid at (${(cx / w).toFixed(2)}, ${(cy / h).toFixed(2)}) \u2014 composition is heavily offset from center`
+      });
+    }
+  }
   return warnings;
 }
 
-// src/examples/aquarium.ts
-var AQUARIUM_SPEC = {
-  schemaVersion: 1,
-  id: "aquarium",
-  label: "Aquarium",
-  seed: 42,
-  motionIntensity: "calm",
-  background: {
-    type: "gradient",
-    stops: [
-      { at: 0, color: "#0a3a52" },
-      { at: 0.6, color: "#062534" },
-      { at: 1, color: "#02141d" }
-    ],
-    band: { color: "#0b1a12", height: 24 }
-  },
-  layers: [
-    {
-      count: 14,
-      sprite: { kind: "emoji", glyphs: ["\u{1F41F}", "\u{1F420}", "\u{1F421}", "\u{1F988}", "\u{1F419}"] },
-      size: [34, 72],
-      motion: { type: "drift", speed: [30, 110], bidirectional: true, bob: 6 },
-      flip: true
-    },
-    {
-      count: 22,
-      sprite: { kind: "circle", radius: [2, 7], color: "#c8ebff" },
-      motion: { type: "rise", speed: [24, 78], sway: 8 }
-    }
-  ]
-};
+// src/describe.ts
+import { createRng as createRng3 } from "@idle-screens/core";
+function describeScene(spec, options = {}) {
+  const { width: w, height: h } = options.viewport ?? { width: 1920, height: 1080 };
+  const seed = options.seed ?? spec.seed ?? 42;
+  const times = options.times ?? [0, 5e3, 15e3];
+  const scale = spec.units === "viewport" ? Math.min(w, h) : 1;
+  const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
+  const countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
+  const rng = createRng3(seed);
+  const builtLayers = spec.layers.map((layer) => ({
+    layer,
+    entities: buildEntities(layer, rng, w, h, scale, countScale)
+  }));
+  const snapshots = times.map((t) => {
+    const layerSnapshots = builtLayers.map(({ layer, entities }) => {
+      const positions = entities.map((e) => positionAt(e, t, w, h));
+      const cx = positions.length > 0 ? positions.reduce((s, p) => s + p.x, 0) / positions.length : 0;
+      const cy = positions.length > 0 ? positions.reduce((s, p) => s + p.y, 0) / positions.length : 0;
+      let pixArea = 0;
+      for (const e of entities) {
+        const r = e.size / 2;
+        pixArea += layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
+      }
+      const coverage = pixArea / (w * h);
+      const meanAlpha = entities.length > 0 ? entities.reduce((s, e) => s + e.alpha, 0) / entities.length : 0;
+      let linksDrawn = null;
+      let linksExpected = null;
+      let connectedComponents = null;
+      let isolatedNodes = null;
+      if (layer.links) {
+        const maxDist = layer.links.maxDist * scale;
+        const pairs = linkPairs(positions, layer.links.k, maxDist, layer.wrap !== false, w, h);
+        linksDrawn = pairs.length;
+        linksExpected = Math.min(entities.length * layer.links.k, entities.length * (entities.length - 1) / 2);
+        const parent = Array.from({ length: entities.length }, (_, i) => i);
+        const find = (x) => {
+          while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+          }
+          return x;
+        };
+        for (const [a, b] of pairs) {
+          const ra = find(a);
+          const rb = find(b);
+          if (ra !== rb) parent[ra] = rb;
+        }
+        const roots = new Set(entities.map((_, i) => find(i)));
+        connectedComponents = roots.size;
+        const degree = new Uint16Array(entities.length);
+        for (const [a, b] of pairs) {
+          degree[a]++;
+          degree[b]++;
+        }
+        isolatedNodes = degree.filter((d) => d === 0).length;
+      }
+      return {
+        key: layer.key,
+        count: entities.length,
+        centroid: { x: +(cx / w).toFixed(3), y: +(cy / h).toFixed(3) },
+        coverage: +coverage.toFixed(4),
+        meanAlpha: +meanAlpha.toFixed(3),
+        linksDrawn,
+        linksExpected,
+        connectedComponents,
+        isolatedNodes
+      };
+    });
+    const warnings = [];
+    for (const ls of layerSnapshots) {
+      const label = ls.key ?? `layer`;
+      if (ls.coverage * ls.meanAlpha < 5e-4) {
+        warnings.push(`${label}: effectively invisible (coverage\xD7alpha=${(ls.coverage * ls.meanAlpha).toFixed(5)})`);
+      }
+      if (ls.linksDrawn !== null && ls.linksExpected !== null && ls.linksExpected > 0) {
+        const ratio = ls.linksDrawn / ls.linksExpected;
+        if (ratio < 0.1) {
+          warnings.push(`${label}: link starvation \u2014 ${ls.linksDrawn}/${ls.linksExpected} edges formed`);
+        }
+      }
+      if (ls.isolatedNodes !== null && ls.count > 0 && ls.isolatedNodes / ls.count > 0.5) {
+        warnings.push(`${label}: ${ls.isolatedNodes}/${ls.count} nodes isolated \u2014 graph is disconnected`);
+      }
+    }
+    return { t, viewport: { w, h }, layers: layerSnapshots, warnings };
+  });
+  return {
+    spec: { id: spec.id, label: spec.label, units: spec.units ?? "px" },
+    snapshots
+  };
+}
+
+// src/perceive.ts
+import { createRng as createRng4 } from "@idle-screens/core";
+function buildScene(spec, opts) {
+  const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
+  const seed = opts.seed ?? spec.seed ?? 42;
+  const scale = spec.units === "px" ? 1 : Math.min(w, h);
+  const refVp = spec.referenceViewport ?? LIMITS.referenceViewport;
+  let countScale = scale > 1 ? Math.min(w, h) / refVp : 1;
+  if (countScale > 1) {
+    const rawTotal = spec.layers.reduce((s, l) => s + Math.round(l.count * countScale), 0);
+    if (rawTotal > LIMITS.maxTotal) countScale *= LIMITS.maxTotal / rawTotal;
+  }
+  const rng = createRng4(seed);
+  const layers = spec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, w, h, scale, countScale) }));
+  const byKey = /* @__PURE__ */ new Map();
+  for (const { layer, entities } of layers) if (layer.key) byKey.set(layer.key, entities);
+  return { w, h, scale, layers, byKey };
+}
+function posOf(scene, e, t) {
+  const p = positionAt(e, t, scene.w, scene.h);
+  if (e.orbitParent) {
+    const parent = scene.byKey.get(e.orbitParent)?.[0];
+    if (parent) {
+      const pp = positionAt(parent, t, scene.w, scene.h);
+      p.x += pp.x;
+      p.y += pp.y;
+    }
+  }
+  return p;
+}
+function hexLuma(hex) {
+  const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
+  const n = parseInt(h.slice(1), 16);
+  if (Number.isNaN(n)) return 0.7;
+  const r = (n >> 16 & 255) / 255;
+  const g = (n >> 8 & 255) / 255;
+  const b = (n & 255) / 255;
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function spriteLuma(layer, e) {
+  const s = layer.sprite;
+  if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
+    return hexLuma(s.colors?.[e.colorIndex] ?? s.color);
+  }
+  if (s.kind === "text") return hexLuma(s.color ?? "#e6e8ef");
+  return 0.75;
+}
+function textBox(s, e, p) {
+  const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
+  const fh = m ? Number(m[1]) : e.size;
+  const str = s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
+  const fw = Math.max(fh, 0.62 * fh * Math.min(str.length, 48));
+  const align = s.align ?? "center";
+  const baseline = s.baseline ?? "middle";
+  return {
+    cx: align === "left" ? p.x + fw / 2 : align === "right" ? p.x - fw / 2 : p.x,
+    cy: baseline === "top" ? p.y + fh * 0.6 : baseline === "bottom" ? p.y - fh * 0.6 : p.y,
+    halfX: fw / 2,
+    halfY: fh * 0.6
+  };
+}
+function luminanceGrid(spec, opts = {}) {
+  const scene = buildScene(spec, opts);
+  const t = opts.t ?? 5e3;
+  const cols = Math.max(8, Math.min(200, opts.cols ?? 80));
+  const rows = Math.max(8, Math.min(200, opts.rows ?? 48));
+  const { w, h, scale } = scene;
+  const cellW = w / cols;
+  const cellH = h / rows;
+  const bg = spec.background;
+  const bgRow = new Array(rows).fill(0);
+  if (!bg || bg.type === "solid") {
+    bgRow.fill(hexLuma(bg?.color ?? "#05050a"));
+  } else {
+    const stops = [...bg.stops].sort((a, b) => a.at - b.at);
+    for (let r = 0; r < rows; r++) {
+      const y = (r + 0.5) / rows;
+      let lum;
+      if (y <= stops[0].at) lum = hexLuma(stops[0].color);
+      else if (y >= stops[stops.length - 1].at) lum = hexLuma(stops[stops.length - 1].color);
+      else {
+        let i = 0;
+        while (i < stops.length - 1 && stops[i + 1].at < y) i++;
+        const a = stops[i];
+        const b = stops[i + 1];
+        const k = b.at === a.at ? 0 : (y - a.at) / (b.at - a.at);
+        lum = hexLuma(a.color) + (hexLuma(b.color) - hexLuma(a.color)) * k;
+      }
+      bgRow[r] = lum;
+    }
+    if (bg.band) {
+      const bandPx = bg.band.height * (spec.units === "px" ? 1 : Math.min(w, h));
+      const fromRow = Math.max(0, Math.floor((h - bandPx) / cellH));
+      for (let r = fromRow; r < rows; r++) bgRow[r] = hexLuma(bg.band.color);
+    }
+  }
+  const cells = new Array(cols * rows);
+  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells[r * cols + c] = bgRow[r];
+  const compose = (idx, lum, a, blend) => {
+    const cur = cells[idx];
+    if (blend === "lighter" || blend === "screen") cells[idx] = Math.min(1, cur + lum * a);
+    else if (blend === "multiply") cells[idx] = cur * (1 - a * (1 - lum));
+    else cells[idx] = cur * (1 - a) + lum * a;
+  };
+  for (const { layer, entities } of scene.layers) {
+    const lifeA = lifeAlphaAt(layer.life, t);
+    if (lifeA <= 0) continue;
+    for (const e of entities) {
+      const a = Math.min(1, alphaAt(e, t) * lifeA);
+      if (a <= 4e-3) continue;
+      const lum = spriteLuma(layer, e);
+      const p = posOf(scene, e, t);
+      const sz = sizeAt(e, t);
+      const s = layer.sprite;
+      if (s.kind === "streak") {
+        const heading = headingAt(e, t, w, h) ?? 0;
+        const steps = Math.max(2, Math.ceil(sz / Math.min(cellW, cellH)));
+        const wgt = Math.min(1, (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale / cellH);
+        for (let i = 0; i <= steps; i++) {
+          const k = i / steps;
+          const x = p.x - Math.cos(heading) * sz * (1 - k);
+          const y = p.y - Math.sin(heading) * sz * (1 - k);
+          const c = Math.floor(x / cellW);
+          const r = Math.floor(y / cellH);
+          if (c < 0 || c >= cols || r < 0 || r >= rows) continue;
+          compose(r * cols + c, lum, a * k * wgt, layer.blend);
+        }
+        continue;
+      }
+      let centerX = p.x;
+      let centerY = p.y;
+      let halfX = sz / 2;
+      let halfY = s.kind === "rect" ? (e.size2 ?? sz) * (e.size > 0 ? sz / e.size : 1) / 2 : sz / 2;
+      if (s.kind === "text") {
+        const box = textBox(s, e, p);
+        centerX = box.cx;
+        centerY = box.cy;
+        halfX = box.halfX;
+        halfY = box.halfY;
+      }
+      const c0 = Math.max(0, Math.floor((centerX - halfX) / cellW));
+      const c1 = Math.min(cols - 1, Math.floor((centerX + halfX) / cellW));
+      const r0 = Math.max(0, Math.floor((centerY - halfY) / cellH));
+      const r1 = Math.min(rows - 1, Math.floor((centerY + halfY) / cellH));
+      const circular = s.kind === "circle" || s.kind === "ring";
+      const soft = s.kind === "circle" && s.soft;
+      const inkWeight = s.kind === "text" || s.kind === "emoji" ? 0.55 : 1;
+      for (let r = r0; r <= r1; r++) {
+        for (let c = c0; c <= c1; c++) {
+          const dx = (c + 0.5) * cellW - centerX;
+          const dy = (r + 0.5) * cellH - centerY;
+          if (circular) {
+            const d = Math.sqrt(dx * dx + dy * dy);
+            if (d > halfX + Math.min(cellW, cellH) / 2) continue;
+            if (s.kind === "ring") {
+              const strokeW = (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale;
+              if (d < halfX - strokeW) continue;
+            }
+            const wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
+            compose(r * cols + c, lum, a * wgt, layer.blend);
+          } else {
+            compose(r * cols + c, lum, a * inkWeight, layer.blend);
+          }
+        }
+      }
+    }
+    if (layer.links) {
+      const positions = entities.map((e) => posOf(scene, e, t));
+      const maxDistPx = layer.links.maxDist * scale;
+      const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
+      const edges = linkEdges(layer.links, positions, maxDistPx, layer.wrap !== false && motionWraps, w, h);
+      const la = Math.min(1, (layer.links.alpha ?? 0.6) * lifeA);
+      const lum = layer.links.color ? hexLuma(layer.links.color) : 0.7;
+      const wgt = Math.min(1, (layer.links.width ?? 1) * scale / cellH) * la;
+      for (const edge of edges) {
+        const pi = positions[edge.i];
+        const pj = positions[edge.j];
+        const steps = Math.max(1, Math.ceil(edge.dist / Math.min(cellW, cellH)));
+        for (let i = 0; i <= steps; i++) {
+          const k = i / steps;
+          const c = Math.floor((pi.x + (pj.x - pi.x) * k) / cellW);
+          const r = Math.floor((pi.y + (pj.y - pi.y) * k) / cellH);
+          if (c < 0 || c >= cols || r < 0 || r >= rows) continue;
+          compose(r * cols + c, lum, wgt, layer.blend);
+        }
+      }
+    }
+  }
+  let sum = 0;
+  let covered = 0;
+  let devSum = 0;
+  let cxAcc = 0;
+  let cyAcc = 0;
+  const rowProfile = new Array(rows).fill(0);
+  const colProfile = new Array(cols).fill(0);
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const v = cells[r * cols + c];
+      sum += v;
+      const dev = Math.abs(v - bgRow[r]);
+      if (dev > 0.03) covered++;
+      devSum += dev;
+      cxAcc += dev * (c + 0.5);
+      cyAcc += dev * (r + 0.5);
+      rowProfile[r] += dev;
+      colProfile[c] += dev;
+    }
+  }
+  for (let r = 0; r < rows; r++) rowProfile[r] = rowProfile[r] / cols;
+  for (let c = 0; c < cols; c++) colProfile[c] = colProfile[c] / rows;
+  return {
+    cols,
+    rows,
+    cells,
+    background: bgRow,
+    meanLuminance: sum / (cols * rows),
+    coverage: covered / (cols * rows),
+    centroid: devSum > 1e-6 ? { x: cxAcc / devSum / cols, y: cyAcc / devSum / rows } : null,
+    rowProfile,
+    colProfile
+  };
+}
+var DITHER = [
+  [0.5 / 8, 4.5 / 8],
+  [2.5 / 8, 6.5 / 8],
+  [1.5 / 8, 5.5 / 8],
+  [3.5 / 8, 7.5 / 8]
+];
+var DOT_BIT = [
+  [1, 8],
+  [2, 16],
+  [4, 32],
+  [64, 128]
+];
+function renderBrailleMap(grid) {
+  const sorted = [...grid.cells].sort((a, b) => a - b);
+  const lo = sorted[0];
+  const hi = Math.max(sorted[Math.floor(sorted.length * 0.98)], lo + 0.08);
+  const expose = (v) => Math.pow(Math.max(0, Math.min(1, (v - lo) / (hi - lo))), 0.8);
+  const outRows = [];
+  for (let br = 0; br < Math.floor(grid.rows / 4); br++) {
+    let line = "";
+    for (let bc = 0; bc < Math.floor(grid.cols / 2); bc++) {
+      let bits = 0;
+      for (let dr = 0; dr < 4; dr++) {
+        for (let dc = 0; dc < 2; dc++) {
+          const v = expose(grid.cells[(br * 4 + dr) * grid.cols + (bc * 2 + dc)]);
+          if (v > DITHER[dr][dc]) bits |= DOT_BIT[dr][dc];
+        }
+      }
+      line += String.fromCharCode(10240 + bits);
+    }
+    outRows.push(line);
+  }
+  return outRows.join("\n");
+}
+function dominanceRanking(spec, opts = {}) {
+  const scene = buildScene(spec, opts);
+  const t = opts.t ?? 5e3;
+  const { w, h, scale } = scene;
+  const bgMean = (() => {
+    const bg = spec.background;
+    if (!bg || bg.type === "solid") return hexLuma(bg?.color ?? "#05050a");
+    return bg.stops.reduce((s, st) => s + hexLuma(st.color), 0) / bg.stops.length;
+  })();
+  const raw = scene.layers.map(({ layer, entities }, layerIndex) => {
+    const lifeA = lifeAlphaAt(layer.life, t);
+    let area = 0;
+    let lumAcc = 0;
+    for (const e of entities) {
+      const a = alphaAt(e, t) * lifeA;
+      const sz = sizeAt(e, t);
+      const s = layer.sprite;
+      let entArea;
+      if (s.kind === "circle") entArea = Math.PI * (sz / 2) * (sz / 2);
+      else if (s.kind === "ring") entArea = Math.PI * sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale);
+      else if (s.kind === "streak") entArea = sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale);
+      else if (s.kind === "rect") {
+        const h2 = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz;
+        entArea = sz * h2;
+      } else if (s.kind === "text") {
+        const box = textBox(s, e, { x: 0, y: 0 });
+        entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
+      } else entArea = sz * sz * 0.55;
+      area += entArea * a;
+      lumAcc += spriteLuma(layer, e);
+    }
+    if (layer.links && entities.length > 1) {
+      const positions = entities.map((e) => posOf(scene, e, t));
+      const motionWraps = ["drift", "rise", "wander"].includes(layer.motion.type);
+      const edges = linkEdges(layer.links, positions, layer.links.maxDist * scale, layer.wrap !== false && motionWraps, w, h);
+      const la = (layer.links.alpha ?? 0.6) * lifeA;
+      const lw = (layer.links.width ?? 1) * scale;
+      for (const edge of edges) area += edge.dist * lw * la;
+    }
+    const meanLuma = entities.length ? lumAcc / entities.length : 0;
+    const contrast = Math.abs(meanLuma - bgMean) + 0.1;
+    const blendBoost = layer.blend === "lighter" || layer.blend === "screen" ? 1.3 : layer.blend === "multiply" ? 1.1 : 1;
+    const motionBoost = layer.motion.type === "static" ? 1 : 1.2;
+    const weight = area / (w * h) * contrast * blendBoost * motionBoost;
+    return { layerIndex, key: layer.key, weight, entityCount: entities.length, meanLuma, factors: { area: area / (w * h), contrast, blendBoost, motionBoost } };
+  });
+  const total = raw.reduce((s, r) => s + r.weight, 0) || 1;
+  return raw.slice().sort((a, b) => b.weight - a.weight).map((r, i) => ({
+    rank: i + 1,
+    layerIndex: r.layerIndex,
+    key: r.key,
+    share: r.weight / total,
+    entityCount: r.entityCount,
+    meanLuma: r.meanLuma,
+    factors: r.factors
+  }));
+}
+function motionStats(spec, opts = {}) {
+  const scene = buildScene(spec, opts);
+  const t = opts.t ?? 5e3;
+  const dt = opts.dt ?? 500;
+  const { w, h } = scene;
+  return scene.layers.map(({ layer, entities }, layerIndex) => {
+    let acc = 0;
+    let max = 0;
+    let n = 0;
+    for (const e of entities) {
+      const p0 = posOf(scene, e, t);
+      const p1 = posOf(scene, e, t + dt);
+      const dx = p1.x - p0.x;
+      const dy = p1.y - p0.y;
+      if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) continue;
+      const speed = Math.sqrt(dx * dx + dy * dy) / dt * 1e3;
+      acc += speed;
+      max = Math.max(max, speed);
+      n++;
+    }
+    const meanSpeed = n ? acc / n : 0;
+    return { layerIndex, key: layer.key, meanSpeed, maxSpeed: max, moving: meanSpeed > 0.5 };
+  });
+}
+var REGION_NAMES = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "mid-left",
+  "center",
+  "mid-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right"
+];
+function regionMeans(grid) {
+  const out = new Array(9).fill(0);
+  const cnt = new Array(9).fill(0);
+  for (let r = 0; r < grid.rows; r++) {
+    for (let c = 0; c < grid.cols; c++) {
+      const region = Math.min(2, Math.floor(r / grid.rows * 3)) * 3 + Math.min(2, Math.floor(c / grid.cols * 3));
+      out[region] += Math.abs(grid.cells[r * grid.cols + c] - grid.background[r]);
+      cnt[region]++;
+    }
+  }
+  return out.map((v, i) => cnt[i] ? v / cnt[i] : 0);
+}
+function diffScenes(a, b, opts = {}) {
+  const t = opts.t ?? 5e3;
+  const gridA = luminanceGrid(a, opts);
+  const gridB = luminanceGrid(b, opts);
+  const regsA = regionMeans(gridA);
+  const regsB = regionMeans(gridB);
+  const domA = dominanceRanking(a, opts);
+  const domB = dominanceRanking(b, opts);
+  const nameOf = (d) => d.key ?? `layer-${d.layerIndex}`;
+  const names = /* @__PURE__ */ new Set([...domA.map(nameOf), ...domB.map(nameOf)]);
+  const dominance = [...names].map((key) => {
+    const inA = domA.find((d) => nameOf(d) === key);
+    const inB = domB.find((d) => nameOf(d) === key);
+    return {
+      key,
+      rankA: inA?.rank ?? null,
+      rankB: inB?.rank ?? null,
+      shareA: inA?.share ?? 0,
+      shareB: inB?.share ?? 0
+    };
+  }).sort((x, y) => Math.abs(y.shareB - y.shareA) - Math.abs(x.shareB - x.shareA));
+  const codesA = new Set(adviseSpec(a).map((w) => w.code));
+  const codesB = new Set(adviseSpec(b).map((w) => w.code));
+  return {
+    t,
+    coverage: { a: gridA.coverage, b: gridB.coverage, delta: gridB.coverage - gridA.coverage },
+    meanLuminance: { a: gridA.meanLuminance, b: gridB.meanLuminance, delta: gridB.meanLuminance - gridA.meanLuminance },
+    balanceShift: gridA.centroid && gridB.centroid ? { dx: gridB.centroid.x - gridA.centroid.x, dy: gridB.centroid.y - gridA.centroid.y } : null,
+    regions: REGION_NAMES.map((region, i) => ({ region, a: regsA[i], b: regsB[i], delta: regsB[i] - regsA[i] })),
+    dominance,
+    advisories: {
+      added: [...codesB].filter((c) => !codesA.has(c)),
+      removed: [...codesA].filter((c) => !codesB.has(c))
+    }
+  };
+}
+function perceiveScene(spec, opts = {}) {
+  const grid = luminanceGrid(spec, opts);
+  return {
+    t: opts.t ?? 5e3,
+    braille: renderBrailleMap(grid),
+    coverage: grid.coverage,
+    meanLuminance: grid.meanLuminance,
+    centroid: grid.centroid,
+    rowProfile: grid.rowProfile,
+    colProfile: grid.colProfile,
+    dominance: dominanceRanking(spec, opts),
+    motion: motionStats(spec, opts),
+    advisories: adviseSpec(spec, opts.viewport ?? { width: 1920, height: 1080 })
+  };
+}
+
+// src/examples/aquarium.ts
+var AQUARIUM_SPEC = {
+  schemaVersion: 1,
+  id: "aquarium",
+  label: "Aquarium",
+  seed: 42,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#0a3a52" },
+      { at: 0.6, color: "#062534" },
+      { at: 1, color: "#02141d" }
+    ],
+    band: { color: "#0b1a12", height: 0.02222 }
+  },
+  layers: [
+    {
+      count: 14,
+      sprite: { kind: "emoji", glyphs: ["\u{1F41F}", "\u{1F420}", "\u{1F421}", "\u{1F988}", "\u{1F419}"] },
+      size: [0.03148, 0.06667],
+      motion: { type: "drift", speed: [0.02778, 0.1019], bidirectional: true, bob: 5556e-6 },
+      flip: true
+    },
+    {
+      count: 22,
+      sprite: { kind: "circle", radius: [1852e-6, 6481e-6], color: "#c8ebff" },
+      motion: { type: "rise", speed: [0.02222, 0.07222], sway: 7407e-6 }
+    }
+  ]
+};
+
+// src/examples/aurora.ts
+var AURORA_SPEC = {
+  schemaVersion: 1,
+  id: "aurora",
+  label: "Aurora",
+  seed: 66,
+  motionIntensity: "calm",
+  ghosting: 0.85,
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#02030d" },
+      { at: 0.65, color: "#050a18" },
+      { at: 1, color: "#0a1220" }
+    ],
+    drift: { period: 4e4, amount: 0.1 }
+  },
+  layers: [
+    {
+      key: "stars",
+      count: 110,
+      sprite: { kind: "circle", radius: [5e-4, 15e-4], color: "#e8ecff", soft: true },
+      motion: { type: "static" },
+      region: { y: [0, 0.75] },
+      alpha: [0.2, 0.6],
+      // A slow shimmer travels across the sky instead of stars twinkling independently.
+      pulse: { amp: 0.25, period: 6e3, wave: { wavelength: 0.5, angle: 15 } }
+    },
+    {
+      key: "curtain-green",
+      count: 100,
+      sprite: {
+        kind: "circle",
+        radius: [0.055, 0.11],
+        color: "#1fd68a",
+        soft: true,
+        colors: ["#1fd68a", "#2ee6c8", "#4bd1ff"],
+        colorWeights: [5, 2, 1]
+      },
+      motion: { type: "wander", speed: [4e-3, 0.012], angle: 0, meander: 0.13, coherence: 0.7 },
+      region: { y: [0.1, 0.42] },
+      alpha: [0.04, 0.1],
+      blend: "lighter",
+      grow: { amp: 0.25, period: 9e3 }
+    },
+    {
+      key: "curtain-violet",
+      count: 60,
+      sprite: {
+        kind: "circle",
+        radius: [0.045, 0.09],
+        color: "#8d5bff",
+        soft: true,
+        colors: ["#8d5bff", "#d14bff", "#ff4bd8"],
+        colorWeights: [4, 1.5, 0.5]
+      },
+      motion: { type: "wander", speed: [3e-3, 0.01], angle: 180, meander: 0.1, coherence: 0.55 },
+      region: { y: [0.04, 0.28] },
+      alpha: [0.03, 0.08],
+      blend: "lighter",
+      grow: { amp: 0.3, period: 12e3 }
+    },
+    {
+      key: "fireflies",
+      count: 14,
+      sprite: { kind: "circle", radius: [1e-3, 3e-3], color: "#b8ffe1", soft: true },
+      motion: { type: "wander", speed: [6e-3, 0.02], meander: 0.06 },
+      region: { y: [0.55, 0.95] },
+      alpha: [0.2, 0.55],
+      pulse: { amp: 0.3, period: 3500 },
+      blend: "lighter"
+    }
+  ]
+};
+
+// src/examples/comets.ts
+var COMETS_SPEC = {
+  schemaVersion: 1,
+  id: "comets",
+  label: "Comet Shower",
+  seed: 42,
+  motionIntensity: "moderate",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#0a0015" },
+      { at: 0.5, color: "#0d1b2a" },
+      { at: 1, color: "#1b0a2e" }
+    ],
+    drift: { period: 25e3, amount: 0.12 }
+  },
+  layers: [
+    {
+      key: "stars",
+      count: 120,
+      sprite: { kind: "circle", radius: [463e-6, 1852e-6], color: "#ffffff", soft: true },
+      motion: { type: "static" },
+      alpha: [0.3, 0.7],
+      pulse: { amp: 0.15, period: 3e3 }
+    },
+    {
+      key: "comets",
+      count: 8,
+      sprite: { kind: "circle", radius: [2778e-6, 7407e-6], color: "#88ccff", soft: true },
+      motion: { type: "drift", speed: [0.07407, 0.1852], angle: 225 },
+      alpha: [0.7, 1],
+      blend: "lighter",
+      trail: { length: 1500, fade: 1 }
+    },
+    {
+      key: "fireflies",
+      count: 20,
+      sprite: { kind: "circle", radius: [1852e-6, 463e-5], color: "#ffdd44", soft: true },
+      motion: { type: "drift", speed: [9259e-6, 0.02778], bidirectional: true, bob: 0.01852 },
+      alpha: [0.4, 0.8],
+      pulse: { amp: 0.3, period: 2e3 },
+      blend: "lighter",
+      trail: { length: 800 }
+    }
+  ]
+};
 
 // src/examples/constellation.ts
 var CONSTELLATION_SPEC = {
@@ -951,7 +2458,7 @@ var CONSTELLATION_SPEC = {
     // Distant static stars (no links, just atmosphere)
     {
       count: 100,
-      sprite: { kind: "circle", radius: [1, 3], color: "#667799", colors: ["#8899cc", "#99aadd", "#aabbee", "#7788aa"] },
+      sprite: { kind: "circle", radius: [9259e-7, 2778e-6], color: "#667799", colors: ["#8899cc", "#99aadd", "#aabbee", "#7788aa"] },
       alpha: [0.2, 0.7],
       pulse: { amp: 0.2, period: 3e3 },
       motion: { type: "static" }
@@ -960,19 +2467,19 @@ var CONSTELLATION_SPEC = {
     {
       key: "nodes",
       count: 40,
-      sprite: { kind: "circle", radius: [2, 5], color: "#88aaff", colors: ["#88aaff", "#aaccff", "#ffcc88", "#ff8866"], soft: true },
+      sprite: { kind: "circle", radius: [1852e-6, 463e-5], color: "#88aaff", colors: ["#88aaff", "#aaccff", "#ffcc88", "#ff8866"], soft: true },
       alpha: [0.5, 0.9],
       blend: "lighter",
-      motion: { type: "drift", speed: [2, 8], bidirectional: true, bob: 3 },
-      links: { k: 3, maxDist: 200, alpha: 0.15, width: 0.5 }
+      motion: { type: "drift", speed: [1852e-6, 7407e-6], bidirectional: true, bob: 2778e-6 },
+      links: { k: 3, maxDist: 0.1852, alpha: 0.15, width: 463e-6 }
     },
     // Cycling asterism markers
     {
       count: 6,
       sprite: { kind: "emoji", glyphs: ["\u2726", "\u2727", "\u22C6", "\u2217"], cycle: { period: 2e3 } },
-      size: [14, 22],
+      size: [0.01296, 0.02037],
       alpha: [0.4, 0.7],
-      motion: { type: "drift", speed: [1, 4], bidirectional: true }
+      motion: { type: "drift", speed: [9259e-7, 3704e-6], bidirectional: true }
     }
   ]
 };
@@ -981,7 +2488,7 @@ var CONSTELLATION_SPEC = {
 var DASHBOARD_SPEC = {
   schemaVersion: 1,
   id: "dev-dashboard",
-  label: "Dev Dashboard",
+  label: "Control Center",
   seed: 256,
   motionIntensity: "calm",
   background: {
@@ -995,473 +2502,490 @@ var DASHBOARD_SPEC = {
   layers: [
     // --- ambient depth ---
     {
-      count: 50,
-      sprite: { kind: "circle", radius: [0.2, 0.8], color: "#1a2538" },
+      key: "dust",
+      count: 40,
+      sprite: { kind: "circle", radius: [1852e-7, 7407e-7], color: "#1a2538" },
       alpha: [0.1, 0.25],
-      motion: { type: "drift", speed: [0.3, 1.2], bob: 0.3 }
+      motion: { type: "drift", speed: [2778e-7, 1111e-6], bob: 2778e-7 }
     },
     {
-      count: 12,
-      sprite: { kind: "circle", radius: [1, 2.5], color: "#1a3050", soft: true },
-      alpha: [0.08, 0.18],
-      blend: "lighter",
-      pulse: { amp: 0.08, period: 4e3 },
-      motion: { type: "drift", speed: [0.5, 1.5], bob: 0.5 }
+      key: "led-wall",
+      count: 140,
+      sprite: { kind: "circle", radius: [8e-4, 12e-4], color: "#274058" },
+      alpha: [0.05, 0.11],
+      layout: { type: "grid", columns: 20, jitter: 0.15 },
+      // A slow breath travels diagonally across the wall of dots.
+      pulse: { amp: 0.3, period: 5e3, wave: { wavelength: 0.35, angle: 20 } },
+      motion: { type: "static" }
     },
-    // --- header ---
+    // --- header (boots first) ---
     {
       key: "title",
       count: 1,
-      position: { x: 0.5, y: 0.04 },
+      position: { x: 0.5, y: 0.045 },
       sprite: {
         kind: "text",
-        strings: ["DEV PULSE"],
+        strings: ["CONTROL CENTER"],
         color: "#556677",
         font: "600 13px 'SF Mono', monospace",
         align: "center"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 200, fade: 600 }
     },
     {
       key: "status",
       count: 1,
-      position: { x: 0.92, y: 0.04 },
+      position: { x: 0.94, y: 0.045 },
       sprite: {
         kind: "text",
-        strings: ["\u25CF ACTIVE"],
+        strings: ["\u25CF ALL SYSTEMS GO"],
         color: "#44cc66",
         font: "bold 10px monospace",
         align: "right"
       },
-      motion: { type: "static" }
+      pulse: { amp: 0.2, period: 2400 },
+      motion: { type: "static" },
+      life: { enter: 200, fade: 600 }
     },
     {
-      key: "uptime",
+      key: "clock",
       count: 1,
-      position: { x: 0.08, y: 0.04 },
+      position: { x: 0.06, y: 0.045 },
       sprite: {
         kind: "text",
-        strings: ["up 2h 14m"],
-        color: "#445566",
-        font: "10px monospace",
+        strings: ["21:47"],
+        color: "#8899aa",
+        font: "bold 12px monospace",
         align: "left"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 200, fade: 600 }
     },
-    // --- left column: metrics ---
+    // --- left column: readings (boots second) ---
     {
-      key: "tools-label",
+      key: "power-label",
       count: 1,
-      position: { x: 0.06, y: 0.12 },
+      position: { x: 0.06, y: 0.14 },
       sprite: {
         kind: "text",
-        strings: ["TOOL CALLS"],
+        strings: ["POWER"],
         color: "#445566",
         font: "9px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "tools-value",
+      key: "power-value",
       count: 1,
-      position: { x: 0.06, y: 0.16 },
+      position: { x: 0.06, y: 0.18 },
       sprite: {
         kind: "text",
-        strings: ["147"],
-        color: "#44aaff",
-        font: "bold 28px monospace",
+        strings: ["3.2 kW"],
+        color: "#ffd166",
+        font: "bold 26px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "reads-label",
+      key: "network-label",
       count: 1,
-      position: { x: 0.06, y: 0.26 },
+      position: { x: 0.06, y: 0.28 },
       sprite: {
         kind: "text",
-        strings: ["READS"],
+        strings: ["NETWORK"],
         color: "#445566",
         font: "9px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "reads-value",
+      key: "network-value",
       count: 1,
-      position: { x: 0.06, y: 0.3 },
+      position: { x: 0.06, y: 0.32 },
       sprite: {
         kind: "text",
-        strings: ["89"],
-        color: "#44ddcc",
-        font: "bold 28px monospace",
+        strings: ["940 Mb/s"],
+        color: "#44aaff",
+        font: "bold 26px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "edits-label",
+      key: "climate-label",
       count: 1,
-      position: { x: 0.06, y: 0.4 },
+      position: { x: 0.06, y: 0.42 },
       sprite: {
         kind: "text",
-        strings: ["EDITS"],
+        strings: ["CLIMATE"],
         color: "#445566",
         font: "9px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "edits-value",
+      key: "climate-value",
       count: 1,
-      position: { x: 0.06, y: 0.44 },
+      position: { x: 0.06, y: 0.46 },
       sprite: {
         kind: "text",
-        strings: ["34"],
-        color: "#ff8844",
-        font: "bold 28px monospace",
+        strings: ["21.5\xB0"],
+        color: "#44ddcc",
+        font: "bold 26px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "errors-label",
+      key: "alerts-label",
       count: 1,
-      position: { x: 0.06, y: 0.54 },
+      position: { x: 0.06, y: 0.56 },
       sprite: {
         kind: "text",
-        strings: ["ERRORS"],
+        strings: ["ALERTS"],
         color: "#445566",
         font: "9px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
     {
-      key: "errors-value",
+      key: "alerts-value",
       count: 1,
-      position: { x: 0.06, y: 0.58 },
+      position: { x: 0.06, y: 0.6 },
       sprite: {
         kind: "text",
-        strings: ["2"],
-        color: "#ff4455",
-        font: "bold 28px monospace",
+        strings: ["0"],
+        color: "#44cc66",
+        font: "bold 26px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 700, fade: 600 }
     },
-    // --- center column: system gauges ---
+    // --- center: energy gauge (boots third) ---
     {
-      key: "cpu-label",
+      key: "gauge-ring",
       count: 1,
-      position: { x: 0.38, y: 0.12 },
-      sprite: {
-        kind: "text",
-        strings: ["CPU"],
-        color: "#445566",
-        font: "9px monospace",
-        align: "center"
-      },
-      motion: { type: "static" }
+      position: { x: 0.4, y: 0.36 },
+      sprite: { kind: "ring", radius: [0.105, 0.105], color: "#1e3a52", width: 28e-4 },
+      alpha: [0.85, 0.85],
+      motion: { type: "static" },
+      life: { enter: 1200, fade: 700 }
     },
     {
-      key: "cpu-value",
+      key: "gauge-glow",
       count: 1,
-      position: { x: 0.38, y: 0.22 },
-      sprite: {
-        kind: "text",
-        strings: ["73%"],
-        color: "#44ff88",
-        font: "bold 36px monospace",
-        align: "center"
-      },
-      motion: { type: "static" }
+      position: { x: 0.4, y: 0.36 },
+      sprite: { kind: "ring", radius: [0.088, 0.088], color: "#2ee6c8", width: 16e-4 },
+      alpha: [0.55, 0.55],
+      blend: "lighter",
+      pulse: { amp: 0.25, period: 4e3 },
+      grow: { amp: 0.05, period: 4e3 },
+      motion: { type: "static" },
+      life: { enter: 1200, fade: 700 }
     },
     {
-      key: "mem-label",
+      key: "gauge-label",
       count: 1,
-      position: { x: 0.38, y: 0.36 },
+      position: { x: 0.4, y: 0.29 },
       sprite: {
         kind: "text",
-        strings: ["MEMORY"],
+        strings: ["ENERGY"],
         color: "#445566",
         font: "9px monospace",
         align: "center"
       },
-      motion: { type: "static" }
-    },
-    {
-      key: "mem-value",
-      count: 1,
-      position: { x: 0.38, y: 0.46 },
-      sprite: {
-        kind: "text",
-        strings: ["4.2 GB"],
-        color: "#ddcc44",
-        font: "bold 36px monospace",
-        align: "center"
-      },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1200, fade: 700 }
     },
     {
-      key: "tokens-label",
+      key: "gauge-value",
       count: 1,
-      position: { x: 0.38, y: 0.58 },
+      position: { x: 0.4, y: 0.375 },
       sprite: {
         kind: "text",
-        strings: ["TOKENS"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["73%"],
+        color: "#2ee6c8",
+        font: "bold 34px monospace",
         align: "center"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1200, fade: 700 }
     },
     {
-      key: "tokens-value",
-      count: 1,
-      position: { x: 0.38, y: 0.66 },
+      key: "equalizer",
+      count: 22,
       sprite: {
-        kind: "text",
-        strings: ["128k"],
-        color: "#aa88ff",
-        font: "bold 28px monospace",
-        align: "center"
+        kind: "rect",
+        width: [5e-3, 5e-3],
+        aspect: [0.6, 3.4],
+        color: "#2ee6c8",
+        colors: ["#2ee6c8", "#44aaff", "#aa88ff"],
+        colorWeights: [3, 2, 1]
       },
-      motion: { type: "static" }
+      alpha: [0.35, 0.7],
+      layout: { type: "grid", columns: 22 },
+      region: { x: [0.28, 0.52], y: [0.585, 0.615] },
+      // Wave-phased pulse sweeps along the bars — reads as a live meter.
+      pulse: { amp: 0.4, period: 1600, wave: { wavelength: 0.1, angle: 0 } },
+      motion: { type: "static" },
+      life: { enter: 1200, fade: 700 }
     },
-    // --- right column: recent files ---
+    // --- right column: agenda + devices (boots fourth) ---
     {
-      key: "files-label",
+      key: "agenda-label",
       count: 1,
-      position: { x: 0.62, y: 0.12 },
+      position: { x: 0.64, y: 0.14 },
       sprite: {
         kind: "text",
-        strings: ["RECENT FILES"],
+        strings: ["AGENDA"],
         color: "#445566",
         font: "9px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "file-1",
+      key: "agenda-1",
       count: 1,
-      position: { x: 0.62, y: 0.17 },
+      position: { x: 0.64, y: 0.19 },
       sprite: {
         kind: "text",
-        strings: ["src/worker.ts"],
+        strings: ["09:00  Standup"],
         color: "#8899aa",
         font: "11px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 280
+        maxWidth: 0.2593
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "file-2",
+      key: "agenda-2",
       count: 1,
-      position: { x: 0.62, y: 0.21 },
+      position: { x: 0.64, y: 0.23 },
       sprite: {
         kind: "text",
-        strings: ["site/src/App.tsx"],
+        strings: ["12:30  Lunch w/ Kai"],
         color: "#778899",
         font: "11px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 280
+        maxWidth: 0.2593
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "file-3",
+      key: "agenda-3",
       count: 1,
-      position: { x: 0.62, y: 0.25 },
+      position: { x: 0.64, y: 0.27 },
       sprite: {
         kind: "text",
-        strings: ["packages/schema/compile.ts"],
+        strings: ["18:00  Gym"],
         color: "#667788",
         font: "11px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 280
+        maxWidth: 0.2593
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "file-4",
+      key: "devices-label",
       count: 1,
-      position: { x: 0.62, y: 0.29 },
+      position: { x: 0.64, y: 0.36 },
       sprite: {
         kind: "text",
-        strings: ["docs/dashboard-spec.md"],
-        color: "#556677",
-        font: "11px monospace",
+        strings: ["DEVICES"],
+        color: "#445566",
+        font: "9px monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 280
+        baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "file-5",
+      key: "devices-1",
       count: 1,
-      position: { x: 0.62, y: 0.33 },
+      position: { x: 0.64, y: 0.41 },
       sprite: {
         kind: "text",
-        strings: ["packages/core/types.ts"],
-        color: "#445566",
+        strings: ["Lights      6 on"],
+        color: "#8899aa",
         font: "11px monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 280
+        baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
-    // --- right column: session info ---
     {
-      key: "session-label",
+      key: "devices-2",
       count: 1,
-      position: { x: 0.62, y: 0.42 },
+      position: { x: 0.64, y: 0.45 },
       sprite: {
         kind: "text",
-        strings: ["SESSION"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["Thermostat  eco"],
+        color: "#778899",
+        font: "11px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "session-model",
+      key: "devices-3",
       count: 1,
-      position: { x: 0.62, y: 0.47 },
+      position: { x: 0.64, y: 0.49 },
       sprite: {
         kind: "text",
-        strings: ["claude-opus-4-6"],
-        color: "#8888aa",
+        strings: ["Locks       secured"],
+        color: "#667788",
         font: "11px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
     {
-      key: "session-cost",
+      key: "devices-4",
       count: 1,
-      position: { x: 0.62, y: 0.51 },
+      position: { x: 0.64, y: 0.53 },
       sprite: {
         kind: "text",
-        strings: ["$2.47 this session"],
-        color: "#667788",
+        strings: ["Media       paused"],
+        color: "#556677",
         font: "11px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 1700, fade: 600 }
     },
-    // --- bottom: event log ---
+    // --- bottom: activity feed (boots last) ---
     {
-      key: "log-label",
+      key: "feed-label",
       count: 1,
-      position: { x: 0.06, y: 0.76 },
+      position: { x: 0.06, y: 0.74 },
       sprite: {
         kind: "text",
-        strings: ["EVENT LOG"],
+        strings: ["ACTIVITY"],
         color: "#445566",
         font: "9px monospace",
         align: "left",
         baseline: "top"
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 2200, fade: 600 }
     },
     {
-      key: "log-1",
+      key: "feed-1",
       count: 1,
-      position: { x: 0.06, y: 0.8 },
+      position: { x: 0.06, y: 0.78 },
       sprite: {
         kind: "text",
-        strings: ["14:07  Edit compile.ts +18 -3"],
-        color: "#667766",
+        strings: ["21:42  Front door locked"],
+        color: "#7a8a7a",
         font: "10px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 600
+        maxWidth: 0.5556
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 2200, fade: 600 }
     },
     {
-      key: "log-2",
+      key: "feed-2",
       count: 1,
-      position: { x: 0.06, y: 0.84 },
+      position: { x: 0.06, y: 0.82 },
       sprite: {
         kind: "text",
-        strings: ["14:06  Bash pnpm test  \u2713 125 passed"],
-        color: "#556655",
+        strings: ["21:36  Thermostat \u2192 eco"],
+        color: "#6a7a6a",
         font: "10px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 600
+        maxWidth: 0.5556
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 2200, fade: 600 }
     },
     {
-      key: "log-3",
+      key: "feed-3",
       count: 1,
-      position: { x: 0.06, y: 0.88 },
+      position: { x: 0.06, y: 0.86 },
       sprite: {
         kind: "text",
-        strings: ["14:05  Read types.ts  (121 lines)"],
-        color: "#4d5e4d",
+        strings: ["21:14  Backup completed"],
+        color: "#5a6a5a",
         font: "10px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 600
+        maxWidth: 0.5556
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 2200, fade: 600 }
     },
     {
-      key: "log-4",
+      key: "feed-4",
       count: 1,
-      position: { x: 0.06, y: 0.92 },
+      position: { x: 0.06, y: 0.9 },
       sprite: {
         kind: "text",
-        strings: ["14:03  Edit examples/dev-dashboard.ts +84 -1"],
-        color: "#445544",
+        strings: ["20:58  Motion \xB7 driveway"],
+        color: "#4d5e4d",
         font: "10px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 600
+        maxWidth: 0.5556
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 2200, fade: 600 }
     },
     {
-      key: "log-5",
+      key: "feed-5",
       count: 1,
-      position: { x: 0.06, y: 0.96 },
+      position: { x: 0.06, y: 0.94 },
       sprite: {
         kind: "text",
-        strings: ["14:01  Bash pnpm build  \u2713 6 packages"],
+        strings: ["20:41  Sunset scene on"],
         color: "#3d4e3d",
         font: "10px monospace",
         align: "left",
         baseline: "top",
-        maxWidth: 600
+        maxWidth: 0.5556
       },
-      motion: { type: "static" }
+      motion: { type: "static" },
+      life: { enter: 2200, fade: 600 }
     }
   ]
 };
@@ -1485,58 +3009,147 @@ var LANTERNS_SPEC = {
   layers: [
     {
       count: 60,
-      sprite: { kind: "circle", radius: [0.5, 1.4], color: "#8fa0c8" },
+      sprite: { kind: "circle", radius: [463e-6, 1296e-6], color: "#8fa0c8" },
       alpha: [0.35, 1],
       region: { y: [0, 0.62] },
-      motion: { type: "drift", speed: [0.5, 2], bob: 1 }
+      motion: { type: "drift", speed: [463e-6, 1852e-6], bob: 9259e-7 }
     },
     {
       count: 36,
       sprite: {
         kind: "circle",
-        radius: [1.5, 3],
+        radius: [1389e-6, 2778e-6],
         color: "#b06a2a",
         soft: true
       },
       alpha: [0.5, 0.9],
       blend: "lighter",
       pulse: { amp: 0.18, period: 2800 },
-      motion: { type: "rise", speed: [6, 14], sway: 4 }
+      motion: { type: "rise", speed: [5556e-6, 0.01296], sway: 3704e-6 }
     },
     {
       count: 14,
       sprite: {
         kind: "circle",
-        radius: [3.5, 6.5],
+        radius: [3241e-6, 6019e-6],
         color: "#e08a34",
         soft: true
       },
       alpha: [0.6, 1],
       blend: "lighter",
       pulse: { amp: 0.22, period: 3400 },
-      motion: { type: "rise", speed: [16, 28], sway: 7 }
+      motion: { type: "rise", speed: [0.01481, 0.02593], sway: 6481e-6 }
     },
     {
       count: 8,
       sprite: { kind: "emoji", glyphs: ["\u{1F3EE}"] },
-      size: [26, 44],
+      size: [0.02407, 0.04074],
       alpha: [0.85, 1],
-      motion: { type: "rise", speed: [30, 48], sway: 10 }
+      motion: { type: "rise", speed: [0.02778, 0.04444], sway: 9259e-6 }
     },
     {
       count: 4,
       sprite: { kind: "emoji", glyphs: ["\u{1F3EE}"] },
-      size: [58, 84],
-      motion: { type: "rise", speed: [52, 74], sway: 14 }
+      size: [0.0537, 0.07778],
+      motion: { type: "rise", speed: [0.04815, 0.06852], sway: 0.01296 }
     },
     {
       count: 12,
-      sprite: { kind: "circle", radius: [2, 5], color: "#e08a34", soft: true },
+      sprite: { kind: "circle", radius: [1852e-6, 463e-5], color: "#e08a34", soft: true },
       alpha: [0.12, 0.35],
       blend: "lighter",
       region: { y: [0.93, 1] },
       pulse: { amp: 0.1, period: 2200 },
-      motion: { type: "drift", speed: [2, 6], bob: 2 }
+      motion: { type: "drift", speed: [1852e-6, 5556e-6], bob: 1852e-6 }
+    }
+  ]
+};
+
+// src/examples/matrix-rain.ts
+var MATRIX_RAIN_SPEC = {
+  schemaVersion: 1,
+  id: "matrix-rain",
+  label: "Matrix Rain",
+  seed: 1999,
+  motionIntensity: "moderate",
+  ghosting: 0.88,
+  background: { type: "solid", color: "#010401" },
+  layers: [
+    {
+      key: "rain-far",
+      count: 64,
+      sprite: {
+        kind: "text",
+        strings: ["\u30A2", "\u30AB", "\u30B5", "\u30BF", "\u30CA", "\u30CF", "\u30DE", "\u30E4", "\u30E9", "\u30EF", "0", "1", "7", "Z", "X", "K"],
+        color: "#1c7a2e",
+        font: "bold monospace",
+        cycle: { period: 900 }
+      },
+      size: [0.014, 0.02],
+      layout: { type: "grid", columns: 32, jitter: { y: 1 } },
+      motion: { type: "drift", speed: [0.06, 0.14], angle: 90 },
+      alpha: [0.35, 0.6]
+    },
+    {
+      key: "rain-near",
+      count: 40,
+      sprite: {
+        kind: "text",
+        strings: ["\u30DF", "\u30CD", "\u30EA", "\u30BD", "\u30C4", "\u30CC", "\u30DB", "\u30E6", "3", "8", "9", "V", "N"],
+        color: "#2ecc40",
+        font: "bold monospace",
+        cycle: { period: 700 }
+      },
+      size: [0.022, 0.03],
+      layout: { type: "grid", columns: 20, jitter: { y: 1 } },
+      motion: { type: "drift", speed: [0.16, 0.3], angle: 90 },
+      alpha: [0.6, 0.9]
+    },
+    {
+      key: "heads",
+      count: 12,
+      sprite: {
+        kind: "text",
+        strings: ["\u30B1", "\u30E1", "\u30A8", "\u30E0", "\u30F2", "5", "2"],
+        color: "#c8ffd4",
+        font: "bold monospace",
+        cycle: { period: 500 }
+      },
+      size: [0.024, 0.032],
+      layout: { type: "grid", columns: 12, jitter: { y: 1 } },
+      motion: { type: "drift", speed: [0.2, 0.34], angle: 90 },
+      alpha: [0.9, 1]
+    }
+  ]
+};
+
+// src/examples/polygons.ts
+var POLYGONS_SPEC = {
+  schemaVersion: 1,
+  id: "polygons",
+  label: "Polygons",
+  seed: 1995,
+  motionIntensity: "moderate",
+  ghosting: 0.95,
+  background: { type: "solid", color: "#04040a" },
+  layers: [
+    {
+      key: "poly-cyan",
+      count: 4,
+      sprite: { kind: "circle", radius: [25e-4, 25e-4], color: "#37e5d7" },
+      motion: { type: "bounce", speed: [0.14, 0.24] },
+      wrap: false,
+      alpha: [0.9, 0.9],
+      links: { k: 1, maxDist: 3, mode: "chain", closed: true, color: "#37e5d7", alpha: 0.85, width: 18e-4 }
+    },
+    {
+      key: "poly-magenta",
+      count: 4,
+      sprite: { kind: "circle", radius: [25e-4, 25e-4], color: "#e83e9c" },
+      motion: { type: "bounce", speed: [0.1, 0.2] },
+      wrap: false,
+      alpha: [0.9, 0.9],
+      links: { k: 1, maxDist: 3, mode: "chain", closed: true, color: "#e83e9c", alpha: 0.85, width: 18e-4 }
     }
   ]
 };
@@ -1560,7 +3173,7 @@ var ORRERY_SPEC = {
     // Distant stars
     {
       count: 80,
-      sprite: { kind: "circle", radius: [0.3, 1.2], color: "#8899cc" },
+      sprite: { kind: "circle", radius: [2778e-7, 1111e-6], color: "#8899cc" },
       alpha: [0.2, 0.8],
       pulse: { amp: 0.3, period: 3e3 },
       motion: { type: "static" }
@@ -1569,7 +3182,7 @@ var ORRERY_SPEC = {
     {
       key: "corona",
       count: 1,
-      sprite: { kind: "circle", radius: [60, 60], color: "#ffaa22", soft: true },
+      sprite: { kind: "circle", radius: [0.05556, 0.05556], color: "#ffaa22", soft: true },
       blend: "lighter",
       alpha: [0.6, 0.6],
       grow: { amp: 0.15, period: 4e3 },
@@ -1581,7 +3194,7 @@ var ORRERY_SPEC = {
       key: "sun",
       count: 1,
       sprite: { kind: "emoji", glyphs: ["\u2600\uFE0F"] },
-      size: [48, 48],
+      size: [0.04444, 0.04444],
       grow: { amp: 0.08, period: 4e3 },
       motion: { type: "static" },
       position: { x: 0.5, y: 0.5 }
@@ -1591,36 +3204,114 @@ var ORRERY_SPEC = {
       key: "inner",
       count: 3,
       sprite: { kind: "emoji", glyphs: ["\u{1FAA8}", "\u{1F534}", "\u{1F7E0}"] },
-      size: [16, 22],
+      size: [0.01481, 0.02037],
       spin: 30,
-      motion: { type: "orbit", speed: [28, 42], radius: [80, 120] }
+      motion: { type: "orbit", speed: [28, 42], radius: [0.07407, 0.1111] }
     },
     // Middle ring — gas giants
     {
       key: "middle",
       count: 2,
       sprite: { kind: "emoji", glyphs: ["\u{1F7E4}", "\u{1FA90}"] },
-      size: [28, 38],
+      size: [0.02593, 0.03519],
       spin: -15,
-      motion: { type: "orbit", speed: [12, 20], radius: [160, 200] }
+      motion: { type: "orbit", speed: [12, 20], radius: [0.1481, 0.1852] }
     },
     // Outer ring — ice giants
     {
       key: "outer",
       count: 2,
       sprite: { kind: "emoji", glyphs: ["\u{1F535}", "\u{1F48E}"] },
-      size: [22, 30],
+      size: [0.02037, 0.02778],
       spin: 10,
-      motion: { type: "orbit", speed: [5, 10], radius: [240, 300] }
+      motion: { type: "orbit", speed: [5, 10], radius: [0.2222, 0.2778] }
     },
     // Orbital dust ring (soft glow particles orbiting slowly)
     {
       count: 24,
-      sprite: { kind: "circle", radius: [1, 3], color: "#ccaa66", soft: true },
+      sprite: { kind: "circle", radius: [9259e-7, 2778e-6], color: "#ccaa66", soft: true },
       alpha: [0.15, 0.4],
       blend: "lighter",
       pulse: { amp: 0.2, period: 2500 },
-      motion: { type: "orbit", speed: [2, 8], radius: [100, 320] }
+      motion: { type: "orbit", speed: [2, 8], radius: [0.09259, 0.2963] }
+    }
+  ]
+};
+
+// src/examples/procession.ts
+var PROCESSION_SPEC = {
+  schemaVersion: 1,
+  id: "procession",
+  label: "Night Procession",
+  seed: 8,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#060612" },
+      { at: 0.8, color: "#101024" },
+      { at: 1, color: "#1a1428" }
+    ],
+    drift: { period: 3e4, amount: 0.08 }
+  },
+  layers: [
+    {
+      key: "stars",
+      count: 90,
+      sprite: { kind: "circle", radius: [6e-4, 16e-4], color: "#f0ead8", soft: true },
+      motion: { type: "static" },
+      region: { y: [0, 0.6] },
+      alpha: [0.25, 0.6],
+      pulse: { amp: 0.15, period: 5e3 }
+    },
+    {
+      key: "lanterns",
+      count: 9,
+      sprite: {
+        kind: "rect",
+        width: [0.012, 0.02],
+        aspect: [1.3, 1.7],
+        color: "#ffb347",
+        colors: ["#ffb347", "#ff8c69", "#ffd97a"],
+        colorWeights: [3, 1, 2]
+      },
+      motion: {
+        type: "path",
+        points: [
+          { x: 0.12, y: 0.72 },
+          { x: 0.38, y: 0.58 },
+          { x: 0.62, y: 0.78 },
+          { x: 0.88, y: 0.62 },
+          { x: 0.62, y: 0.5 },
+          { x: 0.38, y: 0.72 }
+        ],
+        duration: 36e3,
+        curve: "smooth",
+        closed: true,
+        scatter: 0.02
+      },
+      alpha: [0.65, 0.9],
+      pulse: { amp: 0.15, period: 2600 },
+      life: { enter: 4e3, fade: 2500 },
+      trail: { length: 1200, fade: 1 }
+    },
+    {
+      key: "bearer",
+      count: 1,
+      sprite: { kind: "circle", radius: [0.014, 0.014], color: "#ffe9b0", soft: true },
+      motion: { type: "wander", speed: [8e-3, 0.012], meander: 0.08 },
+      alpha: [0.8, 0.8],
+      blend: "lighter",
+      life: { enter: 4e3, fade: 2500 }
+    },
+    {
+      key: "moths",
+      count: 7,
+      sprite: { kind: "ring", radius: [2e-3, 5e-3], color: "#d8f6ff", width: 1e-3 },
+      motion: { type: "orbit", speed: [20, 55], radius: [0.03, 0.09], center: { layer: "bearer" } },
+      alpha: [0.3, 0.7],
+      life: { enter: 7e3, fade: 2e3 },
+      trail: { length: 600 }
     }
   ]
 };
@@ -1637,8 +3328,8 @@ var RAIN_SPEC = {
     {
       count: 140,
       sprite: { kind: "text", strings: ["\u2502"], color: "#9fd0ff" },
-      size: [12, 26],
-      motion: { type: "drift", angle: 90, speed: [520, 900] }
+      size: [0.01111, 0.02407],
+      motion: { type: "drift", angle: 90, speed: [0.4815, 0.8333] }
     }
   ]
 };
@@ -1655,50 +3346,122 @@ var SAKURA_SPEC = {
     stops: [
       { at: 0, color: "#1b1d38" },
       { at: 0.45, color: "#3a2645" },
-      { at: 0.8, color: "#7d3d4e" },
-      { at: 1, color: "#0f140d" }
+      { at: 0.78, color: "#7d3d4e" },
+      { at: 0.92, color: "#4a2438" },
+      { at: 1, color: "#1c1018" }
     ],
-    band: { color: "#0c140d", height: 44 }
+    drift: { period: 35e3, amount: 0.08 }
   },
   layers: [
     {
+      key: "blossom-glow",
       count: 60,
-      sprite: { kind: "circle", radius: [0.6, 1.6], color: "#ffe3ec", soft: true },
+      sprite: {
+        kind: "circle",
+        radius: [5556e-7, 1481e-6],
+        color: "#ffe3ec",
+        soft: true
+      },
       alpha: [0.3, 0.9],
       blend: "lighter",
       region: { y: [0, 0.72] },
-      pulse: { amp: 0.22, period: 3e3 },
-      motion: { type: "drift", speed: [0.3, 1.2], bob: 1 }
+      // Shimmer travels across the sky instead of orbs twinkling independently.
+      pulse: { amp: 0.22, period: 4e3, wave: { wavelength: 0.45, angle: 10 } },
+      motion: { type: "drift", speed: [2778e-7, 1111e-6], bob: 9259e-7 }
     },
     {
+      key: "petals-far",
       count: 28,
       sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
-      size: [13, 20],
+      size: [0.01204, 0.01852],
       alpha: [0.5, 0.8],
-      motion: { type: "drift", speed: [12, 26], angle: 100, bob: 3 }
+      spin: 16,
+      motion: {
+        type: "wander",
+        speed: [0.011, 0.024],
+        angle: 100,
+        meander: 0.025,
+        coherence: 0.35
+      }
     },
     {
+      key: "petals-mid",
       count: 18,
       sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
-      size: [20, 32],
+      size: [0.01852, 0.02963],
       alpha: [0.7, 0.95],
-      motion: { type: "drift", speed: [24, 44], angle: 100, bob: 6 }
+      spin: 24,
+      motion: {
+        type: "wander",
+        speed: [0.022, 0.041],
+        angle: 100,
+        meander: 0.045,
+        coherence: 0.35
+      }
     },
     {
+      key: "petals-near",
       count: 10,
       sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
-      size: [34, 54],
+      size: [0.03148, 0.05],
       alpha: [0.85, 1],
-      motion: { type: "drift", speed: [42, 68], angle: 100, bob: 11 }
+      spin: 32,
+      motion: {
+        type: "wander",
+        speed: [0.039, 0.063],
+        angle: 100,
+        meander: 0.07,
+        coherence: 0.35
+      }
+    },
+    {
+      key: "gusts",
+      count: 7,
+      sprite: {
+        kind: "streak",
+        length: [0.02, 0.045],
+        width: 12e-4,
+        color: "#ffd9e6"
+      },
+      alpha: [0.1, 0.22],
+      blend: "lighter",
+      motion: { type: "drift", speed: [0.09, 0.14], angle: 100 }
+    },
+    {
+      key: "fireflies",
+      count: 6,
+      sprite: {
+        kind: "circle",
+        radius: [9e-4, 2e-3],
+        color: "#ffe9a8",
+        soft: true
+      },
+      alpha: [0.15, 0.5],
+      blend: "lighter",
+      region: { y: [0.6, 0.9] },
+      pulse: { amp: 0.3, period: 2800 },
+      motion: { type: "wander", speed: [4e-3, 0.01], meander: 0.05 }
     },
     {
+      key: "fallen-petals",
       count: 16,
-      sprite: { kind: "circle", radius: [1.5, 4], color: "#ff9bb5", soft: true },
+      sprite: {
+        kind: "circle",
+        radius: [1389e-6, 3704e-6],
+        color: "#ff9bb5",
+        soft: true
+      },
       alpha: [0.1, 0.3],
       blend: "lighter",
       region: { y: [0.9, 1] },
-      pulse: { amp: 0.15, period: 2600 },
-      motion: { type: "drift", speed: [0.3, 1.5], angle: 180, bob: 1 }
+      // Settled petals catch the last light in a slow wave along the ground.
+      pulse: { amp: 0.15, period: 3200, wave: { wavelength: 0.3, angle: 0 } },
+      motion: {
+        type: "drift",
+        speed: [2778e-7, 1389e-6],
+        angle: 180,
+        bob: 9259e-7
+      }
     }
   ]
 };
@@ -1721,18 +3484,71 @@ var SNOWFALL_SPEC = {
   layers: [
     {
       count: 50,
-      sprite: { kind: "circle", radius: [1, 2.5], color: "#8899aa" },
-      motion: { type: "drift", angle: 90, speed: [15, 40], bob: 3 }
+      sprite: { kind: "circle", radius: [9259e-7, 2315e-6], color: "#8899aa" },
+      motion: { type: "drift", angle: 90, speed: [0.01389, 0.03704], bob: 2778e-6 }
     },
     {
       count: 35,
-      sprite: { kind: "circle", radius: [2, 4.5], color: "#c0cdd8" },
-      motion: { type: "drift", angle: 85, speed: [35, 80], bob: 6 }
+      sprite: { kind: "circle", radius: [1852e-6, 4167e-6], color: "#c0cdd8" },
+      motion: { type: "drift", angle: 85, speed: [0.03241, 0.07407], bob: 5556e-6 }
     },
     {
       count: 15,
-      sprite: { kind: "circle", radius: [3.5, 7], color: "#e8eff5" },
-      motion: { type: "drift", angle: 82, speed: [55, 120], bob: 10 }
+      sprite: { kind: "circle", radius: [3241e-6, 6481e-6], color: "#e8eff5" },
+      motion: { type: "drift", angle: 82, speed: [0.05093, 0.1111], bob: 9259e-6 }
+    }
+  ]
+};
+
+// src/examples/warp-tunnel.ts
+var WARP_TUNNEL_SPEC = {
+  schemaVersion: 1,
+  id: "warp-tunnel",
+  label: "Warp Tunnel",
+  seed: 1701,
+  motionIntensity: "energetic",
+  ghosting: 0.55,
+  background: { type: "solid", color: "#020208" },
+  layers: [
+    {
+      key: "far-stars",
+      count: 150,
+      sprite: {
+        kind: "streak",
+        length: [8e-3, 0.02],
+        width: 15e-4,
+        color: "#cfd8ff",
+        colors: ["#cfd8ff", "#ffffff", "#8ab4ff", "#ffd9a0"],
+        colorWeights: [5, 3, 1.5, 0.5]
+      },
+      motion: { type: "warp", speed: [0.06, 0.16] },
+      alpha: [0.5, 0.9],
+      blend: "lighter"
+    },
+    {
+      key: "near-stars",
+      count: 50,
+      sprite: {
+        kind: "streak",
+        length: [0.025, 0.06],
+        width: 25e-4,
+        color: "#ffffff",
+        colors: ["#ffffff", "#a8c8ff"],
+        colorWeights: [3, 1]
+      },
+      motion: { type: "warp", speed: [0.3, 0.55] },
+      alpha: [0.7, 1],
+      blend: "lighter"
+    },
+    {
+      key: "core-glow",
+      count: 1,
+      sprite: { kind: "circle", radius: [0.06, 0.06], color: "#3a4a8f", soft: true },
+      motion: { type: "static" },
+      position: { x: 0.5, y: 0.5 },
+      alpha: [0.35, 0.35],
+      pulse: { amp: 0.15, period: 5e3 },
+      blend: "lighter"
     }
   ]
 };
@@ -1744,9 +3560,15 @@ var SCHEMA_EXAMPLES = [
   { id: "snowfall", label: "Snowfall", spec: SNOWFALL_SPEC },
   { id: "lanterns", label: "Night Lanterns", spec: LANTERNS_SPEC },
   { id: "sakura", label: "Sakura Drift", spec: SAKURA_SPEC },
-  { id: "dev-dashboard", label: "Dev Dashboard", spec: DASHBOARD_SPEC },
+  { id: "dev-dashboard", label: "Control Center", spec: DASHBOARD_SPEC },
   { id: "orrery", label: "Orrery", spec: ORRERY_SPEC },
-  { id: "constellation", label: "Constellation", spec: CONSTELLATION_SPEC }
+  { id: "constellation", label: "Constellation", spec: CONSTELLATION_SPEC },
+  { id: "comets", label: "Comet Shower", spec: COMETS_SPEC },
+  { id: "aurora", label: "Aurora", spec: AURORA_SPEC },
+  { id: "warp-tunnel", label: "Warp Tunnel", spec: WARP_TUNNEL_SPEC },
+  { id: "polygons", label: "Polygons", spec: POLYGONS_SPEC },
+  { id: "matrix-rain", label: "Matrix Rain", spec: MATRIX_RAIN_SPEC },
+  { id: "procession", label: "Night Procession", spec: PROCESSION_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -1754,34 +3576,52 @@ var EXAMPLE_BY_ID = Object.fromEntries(
 );
 export {
   AQUARIUM_SPEC,
+  AURORA_SPEC,
+  COMETS_SPEC,
   CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
   LANTERNS_SPEC,
   LIMITS,
+  MATRIX_RAIN_SPEC,
   ORRERY_SPEC,
+  POLYGONS_SPEC,
+  PROCESSION_SPEC,
   RAIN_SPEC,
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
   SNOWFALL_SPEC,
+  WARP_NEAR,
+  WARP_TUNNEL_SPEC,
   adviseSpec,
   alphaAt,
   applyDeltasToSpec,
   assertValidSpec,
   buildEntities,
   compileSaver,
+  describeScene,
+  diffScenes,
+  dominanceRanking,
   easeSmooth,
+  headingAt,
   lerpSpec,
+  lifeAlphaAt,
+  linkEdges,
   linkPairs,
+  luminanceGrid,
   manifestFor,
+  motionStats,
+  perceiveScene,
   positionAt,
+  renderBrailleMap,
   resolveSpecPath,
   rotationAt,
   sizeAt,
   spriteIndexAt,
   spriteVariants,
+  steerablePaths,
   structuralSignature,
   validateSpec
 };