@idle-screens/schema 2.0.0 → 2.2.0

package/dist/index.js

@@ -8,8 +8,28 @@ var LIMITS = {
   // px/sec — bounds motion so nothing teleports
   maxPulseAmp: 0.5,
   // opacity breathing amplitude cap
-  minPulsePeriod: 500
+  minPulsePeriod: 500,
   // ms — caps pulse at 2 Hz (WCAG flash threshold is 3 Hz)
+  maxSpin: 360,
+  // degrees/sec — one full revolution per second
+  maxGrowAmp: 0.8,
+  // size breathing amplitude cap (fraction of base size)
+  maxOrbitSpeed: 180,
+  // degrees/sec — half a revolution per second
+  maxLinksK: 8,
+  maxLinkLayerCount: 200,
+  minCyclePeriod: 500,
+  // ms — same flash-safety floor as pulse
+  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
@@ -18,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");
@@ -29,7 +84,13 @@ function validateSpec(spec) {
   if (spec.motionIntensity !== void 0 && !["calm", "moderate", "energetic"].includes(spec.motionIntensity)) {
     err("motionIntensity", "must be calm | moderate | energetic");
   }
-  if (spec.background !== void 0) validateBackground(spec.background, err);
+  if (spec.units !== void 0 && spec.units !== "px" && spec.units !== "viewport") {
+    err("units", "must be 'px' | 'viewport'");
+  }
+  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 {
@@ -37,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);
+      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");
@@ -59,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 {
@@ -66,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) {
+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) {
@@ -120,16 +207,67 @@ function validateLayer(layer, path, err) {
       }
     }
   }
-  validateSprite(layer.sprite, `${path}.sprite`, err);
-  validateMotion(layer.motion, `${path}.motion`, err);
+  if (layer.spin !== void 0) {
+    if (!isNum(layer.spin)) err(`${path}.spin`, "must be a number (degrees/sec)");
+    else if (Math.abs(layer.spin) > LIMITS.maxSpin) err(`${path}.spin`, `must be within \xB1${LIMITS.maxSpin} deg/sec`);
+  }
+  if (layer.grow !== void 0) {
+    if (!isObj(layer.grow)) err(`${path}.grow`, "must be an object");
+    else {
+      if (!isNum(layer.grow.amp) || layer.grow.amp <= 0 || layer.grow.amp > LIMITS.maxGrowAmp) {
+        err(`${path}.grow.amp`, `must be within 0..${LIMITS.maxGrowAmp}`);
+      }
+      if (!isNum(layer.grow.period) || layer.grow.period < LIMITS.minPulsePeriod) {
+        err(`${path}.grow.period`, `must be >= ${LIMITS.minPulsePeriod} ms (flash-safety floor)`);
+      }
+    }
+  }
+  if (layer.links !== void 0) {
+    if (!isObj(layer.links)) err(`${path}.links`, "must be an object");
+    else {
+      if (!isNum(layer.links.k) || !Number.isInteger(layer.links.k) || layer.links.k < 1 || layer.links.k > LIMITS.maxLinksK) {
+        err(`${path}.links.k`, `must be an integer 1..${LIMITS.maxLinksK}`);
+      }
+      if (!isNum(layer.links.maxDist) || layer.links.maxDist <= 0) {
+        err(`${path}.links.maxDist`, "must be > 0");
+      }
+      if (layer.links.color !== void 0) color(layer.links.color, `${path}.links.color`, err);
+      if (layer.links.alpha !== void 0 && (!isNum(layer.links.alpha) || layer.links.alpha < 0 || layer.links.alpha > 1)) {
+        err(`${path}.links.alpha`, "must be 0..1");
+      }
+      if (layer.links.width !== void 0 && (!isNum(layer.links.width) || layer.links.width <= 0)) {
+        err(`${path}.links.width`, "must be > 0");
+      }
+      if (isNum(layer.count) && layer.count > LIMITS.maxLinkLayerCount) {
+        err(`${path}.links`, `layer count must be <= ${LIMITS.maxLinkLayerCount} when links is set`);
+      }
+    }
+  }
+  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");
     }
@@ -143,33 +281,95 @@ function validateSprite(sprite, path, err) {
     if (sprite.maxWidth !== void 0 && (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0)) {
       err(`${path}.maxWidth`, "must be a positive number");
     }
+    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));
+      }
+    }
   } 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) {
+  if (sprite.cycle === void 0) return;
+  if (!isObj(sprite.cycle)) return err(`${path}.cycle`, "must be an object");
+  if (!isNum(sprite.cycle.period) || sprite.cycle.period < LIMITS.minCyclePeriod) {
+    err(`${path}.cycle.period`, `must be >= ${LIMITS.minCyclePeriod} ms (flash-safety floor)`);
   }
 }
-function validateMotion(motion, path, err) {
+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 speedOk = (v, p) => {
     if (!isRange(v)) err(p, "must be a [min,max] range");
-    else if (v[1] > LIMITS.maxSpeed) err(p, `speed exceeds cap ${LIMITS.maxSpeed} px/sec`);
+    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`);
+      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)) {
+        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 {
-    err(`${path}.type`, "must be drift | rise | bounce | static");
+    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) {
@@ -187,12 +387,18 @@ function spriteVariants(sprite) {
   if (sprite.kind === "text") return sprite.strings.length;
   return 1;
 }
-function buildEntities(layer, rng, w, h) {
+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++) {
-    const size = layer.sprite.kind === "circle" ? rng.range(layer.sprite.radius[0], layer.sprite.radius[1]) * 2 : rng.range(smin, smax);
+  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;
     let bob = 0;
@@ -201,22 +407,25 @@ function buildEntities(layer, rng, w, h) {
     if (m.type === "static") {
       motion = "static";
     } else if (m.type === "drift") {
-      const s = rng.range(m.speed[0], m.speed[1]);
+      const s = rng.range(m.speed[0], m.speed[1]) * scale;
       let angle = (m.angle ?? 0) * Math.PI / 180;
       if (m.bidirectional && rng.next() < 0.5) angle = Math.PI - angle;
       vx = s * Math.cos(angle);
       vy = s * Math.sin(angle);
-      bob = m.bob ?? 0;
+      bob = (m.bob ?? 0) * scale;
     } else if (m.type === "rise") {
       motion = "rise";
-      vy = -rng.range(m.speed[0], m.speed[1]);
-      bob = m.sway ?? 0;
-    } else {
+      vy = -rng.range(m.speed[0], m.speed[1]) * scale;
+      bob = (m.sway ?? 0) * scale;
+    } else if (m.type === "bounce") {
       motion = "bounce";
-      const s = rng.range(m.speed[0], m.speed[1]);
+      const s = rng.range(m.speed[0], m.speed[1]) * scale;
       const a = rng.range(0, Math.PI * 2);
       vx = s * Math.cos(a);
       vy = s * Math.sin(a);
+    } else if (m.type === "orbit") {
+      motion = "orbit";
+      vx = rng.range(m.speed[0], m.speed[1]);
     }
     let x0;
     let y0;
@@ -243,7 +452,20 @@ function buildEntities(layer, rng, w, h) {
       alpha: layer.alpha ? rng.range(layer.alpha[0], layer.alpha[1]) : 1,
       pulseAmp: layer.pulse?.amp ?? 0,
       pulsePeriod: layer.pulse?.period ?? 1e3,
-      pulsePhase: layer.pulse ? rng.range(0, Math.PI * 2) : 0
+      pulsePhase: layer.pulse ? rng.range(0, Math.PI * 2) : 0,
+      // New draws AFTER pulsePhase — guarded so existing specs keep identical streams.
+      spinSpeed: layer.spin ? layer.spin * Math.PI / 180 : 0,
+      // deg/sec → rad/sec
+      spinPhase: layer.spin ? rng.range(0, Math.PI * 2) : 0,
+      growAmp: layer.grow?.amp ?? 0,
+      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,
+      // 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
     });
   }
   return out;
@@ -253,6 +475,15 @@ function alphaAt(e, t) {
   const a = e.alpha + e.pulseAmp * Math.sin(t * 2 * Math.PI / e.pulsePeriod + e.pulsePhase);
   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));
+  return s > 0 ? s : 0.1;
+}
+function rotationAt(e, t) {
+  if (!e.spinSpeed) return 0;
+  return e.spinPhase + e.spinSpeed * (t / 1e3);
+}
 function wrap(v, min, max) {
   const range = max - min;
   return ((v - min) % range + range) % range + min;
@@ -266,6 +497,14 @@ function reflect(v, min, max) {
 }
 function positionAt(e, t, w, h) {
   if (e.motion === "static") return { x: e.x0, y: e.y0, flip: false };
+  if (e.motion === "orbit") {
+    const angle = e.phase + e.vx * Math.PI / 180 * (t / 1e3);
+    return {
+      x: e.orbitCx + e.orbitR * Math.cos(angle),
+      y: e.orbitCy + e.orbitR * Math.sin(angle),
+      flip: false
+    };
+  }
   const dt = t / 1e3;
   const m = e.size;
   if (e.motion === "bounce") {
@@ -287,6 +526,43 @@ function positionAt(e, t, w, h) {
   if (e.bob) y += e.bob * Math.sin(t / 500 + e.phase);
   return { x, y, flip: e.headingLeft };
 }
+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 linkPairs(positions, k, maxDist, doWrap, w, h) {
+  const n = positions.length;
+  const edges = /* @__PURE__ */ new Set();
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const pi = positions[i];
+    const neighbors = [];
+    for (let j = 0; j < n; j++) {
+      if (i === j) continue;
+      const pj = positions[j];
+      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;
+      }
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      if (dist <= maxDist) neighbors.push({ dist, j });
+    }
+    neighbors.sort((a, b) => a.dist - b.dist || a.j - b.j);
+    for (let ni = 0; ni < Math.min(k, neighbors.length); ni++) {
+      const j = neighbors[ni].j;
+      const lo = Math.min(i, j);
+      const hi = Math.max(i, j);
+      const key = `${lo}:${hi}`;
+      if (!edges.has(key)) {
+        edges.add(key);
+        out.push([lo, hi]);
+      }
+    }
+  }
+  return out;
+}
 
 // src/compile.ts
 import {
@@ -360,12 +636,39 @@ 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);
 }
 function structuralSignature(spec) {
-  return JSON.stringify(
+  return JSON.stringify([
+    spec.units,
     spec.layers.map((l) => [
       l.count,
       l.size,
@@ -376,11 +679,14 @@ function structuralSignature(spec) {
       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 === "emoji" ? l.sprite.glyphs.length : l.sprite.kind === "text" ? l.sprite.strings.length : 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
     ])
-  );
+  ]);
 }
 
 // src/compile.ts
@@ -460,10 +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);
-    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h) }));
+    const scale = this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1;
+    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() {
@@ -484,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") {
@@ -493,50 +805,121 @@ 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;
-      ctx.fillRect(0, h - bg.band.height, w, bg.band.height);
+      const bh = bg.band.height * (this.effSpec.units === "viewport" ? Math.min(w, h) : 1);
+      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);
     const sprite = built.layer.sprite;
+    const sz = sizeAt(e, t);
+    const rot = rotationAt(e, t);
     ctx.globalAlpha = alphaAt(e, t);
     if (sprite.kind === "circle") {
-      const r = e.size / 2;
+      const r = sz / 2;
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      ctx.save();
+      if (rot) {
+        ctx.translate(p.x, p.y);
+        ctx.rotate(rot);
+        ctx.translate(-p.x, -p.y);
+      }
       if (sprite.soft) {
         const g = ctx.createRadialGradient(p.x, p.y, 0, p.x, p.y, r);
-        g.addColorStop(0, sprite.color);
-        g.addColorStop(0.35, hexToRgba(sprite.color, 0.75));
-        g.addColorStop(1, hexToRgba(sprite.color, 0));
+        g.addColorStop(0, resolvedColor);
+        g.addColorStop(0.35, hexToRgba(resolvedColor, 0.75));
+        g.addColorStop(1, hexToRgba(resolvedColor, 0));
         ctx.fillStyle = g;
       } else {
-        ctx.fillStyle = sprite.color;
+        ctx.fillStyle = resolvedColor;
       }
       ctx.beginPath();
       ctx.arc(p.x, p.y, r, 0, Math.PI * 2);
       ctx.fill();
+      ctx.restore();
       return;
     }
     ctx.save();
     ctx.translate(p.x, p.y);
+    if (rot) ctx.rotate(rot);
     if (p.flip && built.layer.flip) ctx.scale(-1, 1);
     ctx.textAlign = "center";
     ctx.textBaseline = "middle";
     if (sprite.kind === "emoji") {
-      ctx.font = `${e.size}px serif`;
-      ctx.fillText(sprite.glyphs[e.spriteIndex] ?? sprite.glyphs[0], 0, 0);
+      const idx = spriteIndexAt(e, t, sprite.glyphs.length);
+      ctx.font = `${sz}px serif`;
+      ctx.fillText(sprite.glyphs[idx] ?? sprite.glyphs[0], 0, 0);
     } else {
       ctx.textAlign = sprite.align ?? "center";
       ctx.textBaseline = sprite.baseline ?? "middle";
-      ctx.font = sprite.font ?? `${e.size}px system-ui, sans-serif`;
+      ctx.font = sprite.font ?? `${sz}px system-ui, sans-serif`;
       ctx.fillStyle = sprite.color ?? "#e6e8ef";
-      const text = sprite.strings[e.spriteIndex] ?? sprite.strings[0];
-      if (sprite.maxWidth) ctx.fillText(text, 0, 0, sprite.maxWidth);
+      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;
+      if (mw) ctx.fillText(text, 0, 0, mw);
       else ctx.fillText(text, 0, 0);
     }
     ctx.restore();
@@ -579,16 +962,53 @@ var SpecInstance = class {
       this.renderFrame(this.lastT, this.seed);
     }
   }
+  drawLinks(built, t) {
+    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);
+    ctx.lineWidth = lw;
+    for (const [i, j] of pairs) {
+      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";
+      }
+      ctx.globalAlpha = links.alpha ?? alphaAt(ei, t);
+      ctx.strokeStyle = resolvedColor;
+      let dx = pj.x - pi.x;
+      let dy = pj.y - pi.y;
+      if (wrap2) {
+        if (Math.abs(dx) > this.w / 2) dx = dx > 0 ? dx - this.w : dx + this.w;
+        if (Math.abs(dy) > this.h / 2) dy = dy > 0 ? dy - this.h : dy + this.h;
+      }
+      ctx.beginPath();
+      ctx.moveTo(pi.x, pi.y);
+      ctx.lineTo(pi.x + dx, pi.y + dy);
+      ctx.stroke();
+    }
+  }
   /** Deterministic, frame-addressable render (shared by the rAF loop). */
   renderFrame(t, _seed) {
     this.stepTransition(t);
     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";
-      for (const e of built.entities) this.drawEntity(built, e, t);
+      this.drawLinks(built, t);
+      for (const e of built.entities) {
+        this.drawTrail(built, e, t);
+        this.drawEntity(built, e, t);
+      }
     }
     ctx.globalAlpha = 1;
     ctx.globalCompositeOperation = "source-over";
@@ -623,6 +1043,222 @@ function compileSaver(spec) {
   };
 }
 
+// src/advise.ts
+import { createRng as createRng2 } from "@idle-screens/core";
+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 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, countScale));
+  let totalEntities = 0;
+  let textLayerCount = 0;
+  let motionLayerCount = 0;
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    const entities = allEntities[li];
+    totalEntities += entities.length;
+    const isText = layer.sprite.kind === "text";
+    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);
+      if (maxR * maxAlpha < 0.05) {
+        warnings.push({
+          path: `layers[${li}]`,
+          code: "invisible-layer",
+          message: `layer's max visible radius (${maxR.toFixed(1)}px \xD7 ${maxAlpha.toFixed(2)} alpha) is below perceptual floor`
+        });
+      }
+    }
+  }
+  let totalCoverage = 0;
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    const entities = allEntities[li];
+    for (const e of entities) {
+      const r = e.size / 2;
+      const pixArea = layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
+      totalCoverage += pixArea * e.alpha / (w * h);
+    }
+  }
+  if (totalCoverage < 5e-4 && spec.layers.length > 0) {
+    warnings.push({
+      path: "layers",
+      code: "sparse-scene",
+      message: `alpha-weighted coverage is ${(totalCoverage * 100).toFixed(4)}% \u2014 scene will look empty on most displays`
+    });
+  }
+  if (totalEntities > 500) {
+    warnings.push({
+      path: "layers",
+      code: "dense-scene",
+      message: `${totalEntities} entities \u2014 scene may feel crowded and hurt performance on low-end devices`
+    });
+  }
+  if (spec.layers.length > 0 && textLayerCount > 0 && motionLayerCount === 0) {
+    const textRatio = textLayerCount / spec.layers.length;
+    if (textRatio >= 0.8) {
+      warnings.push({
+        path: "layers",
+        code: "text-heavy",
+        message: "most layers are static text \u2014 reads as a document, not a screensaver"
+      });
+    }
+  }
+  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,
@@ -655,6 +1291,98 @@ 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,
+  id: "constellation",
+  label: "Constellation",
+  seed: 73,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#020212" },
+      { at: 0.5, color: "#050520" },
+      { at: 1, color: "#0a0830" }
+    ]
+  },
+  layers: [
+    // Distant static stars (no links, just atmosphere)
+    {
+      count: 100,
+      sprite: { kind: "circle", radius: [1, 3], color: "#667799", colors: ["#8899cc", "#99aadd", "#aabbee", "#7788aa"] },
+      alpha: [0.2, 0.7],
+      pulse: { amp: 0.2, period: 3e3 },
+      motion: { type: "static" }
+    },
+    // Connected constellation nodes — slow drift, linked
+    {
+      key: "nodes",
+      count: 40,
+      sprite: { kind: "circle", radius: [2, 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 }
+    },
+    // Cycling asterism markers
+    {
+      count: 6,
+      sprite: { kind: "emoji", glyphs: ["\u2726", "\u2727", "\u22C6", "\u2217"], cycle: { period: 2e3 } },
+      size: [14, 22],
+      alpha: [0.4, 0.7],
+      motion: { type: "drift", speed: [1, 4], bidirectional: true }
+    }
+  ]
+};
+
 // src/examples/dev-dashboard.ts
 var DASHBOARD_SPEC = {
   schemaVersion: 1,
@@ -1219,6 +1947,90 @@ var LANTERNS_SPEC = {
   ]
 };
 
+// src/examples/orrery.ts
+var ORRERY_SPEC = {
+  schemaVersion: 1,
+  id: "orrery",
+  label: "Orrery",
+  seed: 7,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#020210" },
+      { at: 0.5, color: "#06051a" },
+      { at: 1, color: "#0a0820" }
+    ]
+  },
+  layers: [
+    // Distant stars
+    {
+      count: 80,
+      sprite: { kind: "circle", radius: [0.3, 1.2], color: "#8899cc" },
+      alpha: [0.2, 0.8],
+      pulse: { amp: 0.3, period: 3e3 },
+      motion: { type: "static" }
+    },
+    // Sun corona (soft glow)
+    {
+      key: "corona",
+      count: 1,
+      sprite: { kind: "circle", radius: [60, 60], color: "#ffaa22", soft: true },
+      blend: "lighter",
+      alpha: [0.6, 0.6],
+      grow: { amp: 0.15, period: 4e3 },
+      motion: { type: "static" },
+      position: { x: 0.5, y: 0.5 }
+    },
+    // Sun body
+    {
+      key: "sun",
+      count: 1,
+      sprite: { kind: "emoji", glyphs: ["\u2600\uFE0F"] },
+      size: [48, 48],
+      grow: { amp: 0.08, period: 4e3 },
+      motion: { type: "static" },
+      position: { x: 0.5, y: 0.5 }
+    },
+    // Inner ring — small fast planets
+    {
+      key: "inner",
+      count: 3,
+      sprite: { kind: "emoji", glyphs: ["\u{1FAA8}", "\u{1F534}", "\u{1F7E0}"] },
+      size: [16, 22],
+      spin: 30,
+      motion: { type: "orbit", speed: [28, 42], radius: [80, 120] }
+    },
+    // Middle ring — gas giants
+    {
+      key: "middle",
+      count: 2,
+      sprite: { kind: "emoji", glyphs: ["\u{1F7E4}", "\u{1FA90}"] },
+      size: [28, 38],
+      spin: -15,
+      motion: { type: "orbit", speed: [12, 20], radius: [160, 200] }
+    },
+    // Outer ring — ice giants
+    {
+      key: "outer",
+      count: 2,
+      sprite: { kind: "emoji", glyphs: ["\u{1F535}", "\u{1F48E}"] },
+      size: [22, 30],
+      spin: 10,
+      motion: { type: "orbit", speed: [5, 10], radius: [240, 300] }
+    },
+    // Orbital dust ring (soft glow particles orbiting slowly)
+    {
+      count: 24,
+      sprite: { kind: "circle", radius: [1, 3], 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] }
+    }
+  ]
+};
+
 // src/examples/rain.ts
 var RAIN_SPEC = {
   schemaVersion: 1,
@@ -1338,7 +2150,10 @@ 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: "Dev Dashboard", spec: DASHBOARD_SPEC },
+  { id: "orrery", label: "Orrery", spec: ORRERY_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(
@@ -1346,27 +2161,37 @@ var EXAMPLE_BY_ID = Object.fromEntries(
 );
 export {
   AQUARIUM_SPEC,
+  COMETS_SPEC,
+  CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
   LANTERNS_SPEC,
   LIMITS,
+  ORRERY_SPEC,
   RAIN_SPEC,
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
   SNOWFALL_SPEC,
+  adviseSpec,
   alphaAt,
   applyDeltasToSpec,
   assertValidSpec,
   buildEntities,
   compileSaver,
+  describeScene,
   easeSmooth,
   lerpSpec,
+  linkPairs,
   manifestFor,
   positionAt,
   resolveSpecPath,
+  rotationAt,
+  sizeAt,
+  spriteIndexAt,
   spriteVariants,
+  steerablePaths,
   structuralSignature,
   validateSpec
 };