@idle-screens/schema 2.1.0 → 2.2.0

package/dist/index.js

@@ -20,8 +20,16 @@ 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
 };
 
 // src/validate.ts
@@ -30,10 +38,45 @@ 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", "background", "layers"]);
+var KNOWN_LAYER = /* @__PURE__ */ new Set([
+  "count",
+  "sprite",
+  "motion",
+  "size",
+  "wrap",
+  "flip",
+  "alpha",
+  "blend",
+  "region",
+  "pulse",
+  "spin",
+  "grow",
+  "key",
+  "position",
+  "trail",
+  "links"
+]);
+var KNOWN_CIRCLE = /* @__PURE__ */ new Set(["kind", "radius", "color", "soft", "colors"]);
+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_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 +87,10 @@ 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);
+  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 +98,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 +123,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 +141,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 yet supported \u2014 fake parallax with size/speed/alpha across layers instead`);
+    } 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) {
@@ -171,17 +243,31 @@ function validateLayer(layer, path, err, spec) {
       }
     }
   }
-  validateSprite(layer.sprite, `${path}.sprite`, err);
-  validateMotion(layer.motion, `${path}.motion`, err, spec);
+  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,6 +283,7 @@ 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");
@@ -209,6 +296,14 @@ function validateSprite(sprite, path, err) {
     }
   } else {
     err(`${path}.kind`, "must be emoji | text | circle");
+    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 validateCycle(sprite, path, err) {
@@ -218,7 +313,7 @@ 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;
@@ -226,20 +321,40 @@ function validateMotion(motion, path, err, spec) {
     if (!isRange(v)) err(p, "must be a [min,max] range");
     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) || !isNum(motion.center.x) || !isNum(motion.center.y)) {
@@ -251,6 +366,10 @@ function validateMotion(motion, path, err, spec) {
     }
   } else {
     err(`${path}.type`, "must be drift | rise | bounce | static | orbit");
+    return;
+  }
+  for (const k of unknownKeys(motion, knownSet)) {
+    warn(`${path}.${k}`, "unknown-property", `unknown motion property '${k}' \u2014 will be ignored`);
   }
 }
 function assertValidSpec(spec) {
@@ -268,13 +387,17 @@ function spriteVariants(sprite) {
   if (sprite.kind === "text") return sprite.strings.length;
   return 1;
 }
-function buildEntities(layer, rng, w, h, scale = 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 out = [];
-  for (let i = 0; i < layer.count; i++) {
+  for (let i = 0; i < effectiveCount; i++) {
     const size = layer.sprite.kind === "circle" ? rng.range(layer.sprite.radius[0], layer.sprite.radius[1]) * 2 * scale : rng.range(smin, smax) * scale;
     let vx = 0;
     let vy = 0;
@@ -513,6 +636,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"]);
+  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);
@@ -617,11 +766,16 @@ var SpecInstance = class {
     this.canvas.height = Math.max(1, Math.round(this.h * dpr));
     this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
   }
-  /** (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) }));
+    let countScale = scale > 1 ? Math.min(this.w, this.h) / LIMITS.referenceViewport : 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 +796,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,7 +805,17 @@ 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) {
@@ -660,6 +824,52 @@ var SpecInstance = class {
       ctx.fillRect(0, h - bh, w, bh);
     }
   }
+  drawTrail(built, e, t) {
+    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);
+    const headSize = sizeAt(e, t);
+    const sprite = built.layer.sprite;
+    const resolvedColor = sprite.kind === "circle" ? 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 = positionAt(e, t, w, h);
+    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 = positionAt(e, pastT, w, h);
+      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) {
     const { ctx } = this;
     const p = positionAt(e, t, this.w, this.h);
@@ -791,11 +1001,14 @@ var SpecInstance = class {
     const { ctx } = this;
     ctx.globalAlpha = 1;
     ctx.globalCompositeOperation = "source-over";
-    this.drawBackground();
+    this.drawBackground(t);
     for (const built of this.layers) {
       ctx.globalCompositeOperation = built.layer.blend ?? "source-over";
       this.drawLinks(built, t);
-      for (const e of built.entities) this.drawEntity(built, e, t);
+      for (const e of built.entities) {
+        this.drawTrail(built, e, t);
+        this.drawEntity(built, e, t);
+      }
     }
     ctx.globalAlpha = 1;
     ctx.globalCompositeOperation = "source-over";
@@ -837,8 +1050,9 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
   const w = viewport.width;
   const h = viewport.height;
   const scale = spec.units === "viewport" ? Math.min(w, h) : 1;
+  const countScale = scale > 1 ? Math.min(w, h) / LIMITS.referenceViewport : 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 +1061,16 @@ 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 === "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);
@@ -897,9 +1117,148 @@ 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) 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"
+      });
+    }
+  }
+  if (totalEntities >= 8) {
+    const positions = allEntities.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/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 countScale = scale > 1 ? Math.min(w, h) / LIMITS.referenceViewport : 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/examples/aquarium.ts
 var AQUARIUM_SPEC = {
   schemaVersion: 1,
@@ -932,6 +1291,53 @@ var AQUARIUM_SPEC = {
   ]
 };
 
+// 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: [0.5, 2], 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: [3, 8], color: "#88ccff", soft: true },
+      motion: { type: "drift", speed: [80, 200], angle: 225 },
+      alpha: [0.7, 1],
+      blend: "lighter",
+      trail: { length: 1500, fade: 1 }
+    },
+    {
+      key: "fireflies",
+      count: 20,
+      sprite: { kind: "circle", radius: [2, 5], color: "#ffdd44", soft: true },
+      motion: { type: "drift", speed: [10, 30], bidirectional: true, bob: 20 },
+      alpha: [0.4, 0.8],
+      pulse: { amp: 0.3, period: 2e3 },
+      blend: "lighter",
+      trail: { length: 800 }
+    }
+  ]
+};
+
 // src/examples/constellation.ts
 var CONSTELLATION_SPEC = {
   schemaVersion: 1,
@@ -1746,7 +2152,8 @@ var SCHEMA_EXAMPLES = [
   { id: "sakura", label: "Sakura Drift", spec: SAKURA_SPEC },
   { id: "dev-dashboard", label: "Dev Dashboard", 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 }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -1754,6 +2161,7 @@ var EXAMPLE_BY_ID = Object.fromEntries(
 );
 export {
   AQUARIUM_SPEC,
+  COMETS_SPEC,
   CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
@@ -1772,6 +2180,7 @@ export {
   assertValidSpec,
   buildEntities,
   compileSaver,
+  describeScene,
   easeSmooth,
   lerpSpec,
   linkPairs,
@@ -1782,6 +2191,7 @@ export {
   sizeAt,
   spriteIndexAt,
   spriteVariants,
+  steerablePaths,
   structuralSignature,
   validateSpec
 };