@idle-screens/schema 1.0.0 → 2.1.0

package/dist/index.js

@@ -8,8 +8,20 @@ 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
 };
 
 // src/validate.ts
@@ -29,6 +41,9 @@ function validateSpec(spec) {
   if (spec.motionIntensity !== void 0 && !["calm", "moderate", "energetic"].includes(spec.motionIntensity)) {
     err("motionIntensity", "must be calm | moderate | energetic");
   }
+  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 (!Array.isArray(spec.layers) || spec.layers.length === 0) {
     err("layers", "must be a non-empty array");
@@ -37,7 +52,7 @@ 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, spec);
     });
     if (total > LIMITS.maxTotal) err("layers", `total entities ${total} exceeds cap ${LIMITS.maxTotal}`);
   }
@@ -70,7 +85,7 @@ function validateBackground(bg, err) {
     err("background.type", "must be solid | gradient");
   }
 }
-function validateLayer(layer, path, err) {
+function validateLayer(layer, path, err, spec) {
   if (!isObj(layer)) return err(path, "must be an object");
   if (!isNum(layer.count) || !Number.isInteger(layer.count) || layer.count < 1) {
     err(`${path}.count`, "must be a positive integer");
@@ -120,8 +135,44 @@ function validateLayer(layer, path, 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`);
+      }
+    }
+  }
   validateSprite(layer.sprite, `${path}.sprite`, err);
-  validateMotion(layer.motion, `${path}.motion`, err);
+  validateMotion(layer.motion, `${path}.motion`, err, spec);
 }
 function validateSprite(sprite, path, err) {
   if (!isObj(sprite)) return err(path, "must be an object");
@@ -129,6 +180,7 @@ function validateSprite(sprite, path, err) {
     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") {
     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,19 +195,36 @@ 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") {
     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");
   }
 }
-function validateMotion(motion, path, err) {
+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, 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"}`);
   };
   if (motion.type === "drift") {
     speedOk(motion.speed, `${path}.speed`);
@@ -168,8 +237,20 @@ function validateMotion(motion, path, err) {
   } else if (motion.type === "bounce") {
     speedOk(motion.speed, `${path}.speed`);
   } else if (motion.type === "static") {
+  } else if (motion.type === "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 (!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");
   }
 }
 function assertValidSpec(spec) {
@@ -187,12 +268,14 @@ 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) {
   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);
+    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 +284,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 +329,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 +352,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 +374,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,11 +403,145 @@ 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 {
   createRng
 } from "@idle-screens/core";
+
+// src/steer.ts
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function resolveSpecPath(spec, path) {
+  if (!spec || typeof spec !== "object" || !path) return null;
+  const parts = path.split(".");
+  if (parts.some((p) => UNSAFE_KEYS.has(p))) return null;
+  const s = spec;
+  if (parts[0] !== "layers" && parts[0] !== "background" && Array.isArray(s.layers)) {
+    const idx = s.layers.findIndex((l) => l && l.key === parts[0]);
+    if (idx === -1) return null;
+    parts.splice(0, 1, "layers", String(idx));
+  }
+  let node = spec;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (node === null || typeof node !== "object") return null;
+    node = node[parts[i]];
+  }
+  if (node === null || typeof node !== "object") return null;
+  const last = parts[parts.length - 1];
+  const key = Array.isArray(node) ? Number(last) : last;
+  const exists = Array.isArray(node) ? Number.isInteger(key) && key >= 0 && key < node.length : last in node;
+  return exists ? { parent: node, key } : null;
+}
+function applyDeltasToSpec(spec, deltas) {
+  const copy = JSON.parse(JSON.stringify(spec));
+  for (const d of deltas) {
+    const loc = resolveSpecPath(copy, d.path);
+    if (loc) loc.parent[loc.key] = d.value;
+  }
+  return copy;
+}
+var HEX2 = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function hexToRgb(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);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function lerpHex(a, b, k) {
+  const ca = hexToRgb(a);
+  const cb = hexToRgb(b);
+  const mix = ca.map((v, i) => Math.round(v + (cb[i] - v) * k));
+  return `#${mix.map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+function lerpSpec(from, to, k) {
+  const kk = Math.max(0, Math.min(1, k));
+  const walk = (a, b, key) => {
+    if (typeof a === "number" && typeof b === "number") {
+      const v = a + (b - a) * kk;
+      return key === "count" ? Math.max(1, Math.round(v)) : v;
+    }
+    if (typeof a === "string" && typeof b === "string" && HEX2.test(a) && HEX2.test(b)) {
+      return lerpHex(a, b, kk);
+    }
+    if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+      return b.map((bv, i) => walk(a[i], bv, i));
+    }
+    if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+      const out = {};
+      for (const kName of Object.keys(b)) {
+        out[kName] = walk(a[kName], b[kName], kName);
+      }
+      return out;
+    }
+    return kk > 0 ? b : a;
+  };
+  return walk(from, to);
+}
+function easeSmooth(k) {
+  const c = Math.max(0, Math.min(1, k));
+  return c * c * (3 - 2 * c);
+}
+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
+    ])
+  ]);
+}
+
+// src/compile.ts
+var DEFAULT_STEER_DUR = 1e3;
 function hexToRgba(hex, alpha) {
   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);
@@ -310,12 +560,14 @@ function manifestFor(spec) {
     reducedMotionFallback: "static",
     // Flash-safe by construction: static background + bounded sprites, no strobe
     // primitive. Proven by sampling a compiled spec through @idle-screens/validator.
-    a11y: { flashSafe: true }
+    a11y: { flashSafe: true },
+    workerReady: true
   };
 }
 var SpecInstance = class {
   constructor(spec, ctx) {
     this.spec = spec;
+    this.effSpec = spec;
     this.saverCtx = ctx;
     this.seed = (spec.seed ?? ctx.seed) >>> 0 || 1;
     let canvas;
@@ -354,6 +606,11 @@ var SpecInstance = class {
   baseT = 0;
   // elapsed logical time carried across pause/resume
   lastT = 0;
+  /** The spec currently being rendered (base spec + any applied steering). */
+  effSpec;
+  /** Active glide between two resolved specs (live setParam/applyTrack). */
+  transition = null;
+  lastStructural = "";
   sizeCanvas() {
     const dpr = Math.min(this.saverCtx.dpr, 2);
     this.canvas.width = Math.max(1, Math.round(this.w * dpr));
@@ -363,7 +620,9 @@ var SpecInstance = class {
   /** (Re)seed and place all entities — deterministic for the seed + size. */
   rebuild() {
     const rng = createRng(this.seed);
-    this.layers = this.spec.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;
+    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h, scale) }));
+    this.lastStructural = structuralSignature(this.effSpec);
   }
   start() {
     if (this.frameId !== null || typeof requestAnimationFrame === "undefined") return;
@@ -385,7 +644,7 @@ var SpecInstance = class {
   }
   drawBackground() {
     const { ctx, w, h } = this;
-    const bg = this.spec.background;
+    const bg = this.effSpec.background;
     if (!bg || bg.type === "solid") {
       ctx.fillStyle = bg?.color ?? "#05050a";
       ctx.fillRect(0, 0, w, h);
@@ -397,57 +656,145 @@ var SpecInstance = class {
     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);
     }
   }
   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();
   }
+  /** Advance any live steering glide; rebuild entities on structural change. */
+  stepTransition(t) {
+    const tr = this.transition;
+    if (!tr) return;
+    const k = tr.dur <= 0 ? 1 : (t - tr.startT) / tr.dur;
+    this.effSpec = k >= 1 ? tr.to : lerpSpec(tr.from, tr.to, easeSmooth(k));
+    if (k >= 1) this.transition = null;
+    const sig = structuralSignature(this.effSpec);
+    if (sig !== this.lastStructural) this.rebuild();
+    else this.layers.forEach((b, i) => {
+      b.layer = this.effSpec.layers[i] ?? b.layer;
+    });
+  }
+  /**
+   * Live steering: glide from what's currently rendered to the track's target
+   * state (deltas applied last-wins). Duration = the longest delta `dur`.
+   */
+  applyTrack(track) {
+    const deltas = track?.deltas ?? [];
+    const target = applyDeltasToSpec(this.effSpec, deltas);
+    if (!validateSpec(target).valid) return;
+    const dur = deltas.length ? deltas.reduce((m, d) => Math.max(m, d.dur ?? DEFAULT_STEER_DUR), 0) : DEFAULT_STEER_DUR;
+    this.transition = {
+      from: JSON.parse(JSON.stringify(this.effSpec)),
+      to: target,
+      startT: this.lastT,
+      dur
+    };
+    if (this.paused) {
+      this.transition = null;
+      this.effSpec = target;
+      if (structuralSignature(this.effSpec) !== this.lastStructural) this.rebuild();
+      else this.layers.forEach((b, i) => {
+        b.layer = this.effSpec.layers[i] ?? b.layer;
+      });
+      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();
     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);
     }
     ctx.globalAlpha = 1;
@@ -483,7 +830,77 @@ function compileSaver(spec) {
   };
 }
 
-// src/examples.ts
+// 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 rng = createRng2(spec.seed ?? 42);
+  const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale));
+  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 isEmoji = layer.sprite.kind === "emoji";
+    const isStaticText = isText && layer.motion.type === "static";
+    if (isStaticText) textLayerCount++;
+    if (layer.motion.type !== "static") motionLayerCount++;
+    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"
+      });
+    }
+  }
+  return warnings;
+}
+
+// src/examples/aquarium.ts
 var AQUARIUM_SPEC = {
   schemaVersion: 1,
   id: "aquarium",
@@ -514,185 +931,53 @@ var AQUARIUM_SPEC = {
     }
   ]
 };
-var RAIN_SPEC = {
-  schemaVersion: 1,
-  id: "rain",
-  label: "Rain",
-  seed: 7,
-  motionIntensity: "moderate",
-  background: { type: "solid", color: "#05070a" },
-  layers: [
-    {
-      count: 140,
-      sprite: { kind: "text", strings: ["\u2502"], color: "#9fd0ff" },
-      size: [12, 26],
-      motion: { type: "drift", angle: 90, speed: [520, 900] }
-    }
-  ]
-};
-var SNOWFALL_SPEC = {
-  schemaVersion: 1,
-  id: "snowfall",
-  label: "Snowfall",
-  seed: 12,
-  motionIntensity: "calm",
-  background: {
-    type: "gradient",
-    stops: [
-      { at: 0, color: "#0a1628" },
-      { at: 0.7, color: "#0d1f3c" },
-      { at: 1, color: "#121212" }
-    ]
-  },
-  layers: [
-    {
-      count: 50,
-      sprite: { kind: "circle", radius: [1, 2.5], color: "#8899aa" },
-      motion: { type: "drift", angle: 90, speed: [15, 40], bob: 3 }
-    },
-    {
-      count: 35,
-      sprite: { kind: "circle", radius: [2, 4.5], color: "#c0cdd8" },
-      motion: { type: "drift", angle: 85, speed: [35, 80], bob: 6 }
-    },
-    {
-      count: 15,
-      sprite: { kind: "circle", radius: [3.5, 7], color: "#e8eff5" },
-      motion: { type: "drift", angle: 82, speed: [55, 120], bob: 10 }
-    }
-  ]
-};
-var LANTERNS_SPEC = {
+
+// src/examples/constellation.ts
+var CONSTELLATION_SPEC = {
   schemaVersion: 1,
-  id: "lanterns",
-  label: "Night Lanterns",
-  seed: 88,
+  id: "constellation",
+  label: "Constellation",
+  seed: 73,
   motionIntensity: "calm",
   background: {
     type: "gradient",
     stops: [
-      { at: 0, color: "#04060f" },
-      { at: 0.55, color: "#0b1026" },
-      { at: 0.85, color: "#251731" },
-      { at: 1, color: "#472518" }
+      { at: 0, color: "#020212" },
+      { at: 0.5, color: "#050520" },
+      { at: 1, color: "#0a0830" }
     ]
   },
   layers: [
+    // Distant static stars (no links, just atmosphere)
     {
-      count: 60,
-      sprite: { kind: "circle", radius: [0.5, 1.4], color: "#8fa0c8" },
-      alpha: [0.35, 1],
-      region: { y: [0, 0.62] },
-      motion: { type: "drift", speed: [0.5, 2], bob: 1 }
+      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
     {
-      count: 36,
-      sprite: {
-        kind: "circle",
-        radius: [1.5, 3],
-        color: "#b06a2a",
-        soft: true
-      },
+      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",
-      pulse: { amp: 0.18, period: 2800 },
-      motion: { type: "rise", speed: [6, 14], sway: 4 }
-    },
-    {
-      count: 14,
-      sprite: {
-        kind: "circle",
-        radius: [3.5, 6.5],
-        color: "#e08a34",
-        soft: true
-      },
-      alpha: [0.6, 1],
-      blend: "lighter",
-      pulse: { amp: 0.22, period: 3400 },
-      motion: { type: "rise", speed: [16, 28], sway: 7 }
-    },
-    {
-      count: 8,
-      sprite: { kind: "emoji", glyphs: ["\u{1F3EE}"] },
-      size: [26, 44],
-      alpha: [0.85, 1],
-      motion: { type: "rise", speed: [30, 48], sway: 10 }
+      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: 4,
-      sprite: { kind: "emoji", glyphs: ["\u{1F3EE}"] },
-      size: [58, 84],
-      motion: { type: "rise", speed: [52, 74], sway: 14 }
-    },
-    {
-      count: 12,
-      sprite: { kind: "circle", radius: [2, 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 }
-    }
-  ]
-};
-var SAKURA_SPEC = {
-  schemaVersion: 1,
-  id: "sakura",
-  label: "Sakura Drift",
-  seed: 314,
-  motionIntensity: "calm",
-  background: {
-    type: "gradient",
-    stops: [
-      { at: 0, color: "#1b1d38" },
-      { at: 0.45, color: "#3a2645" },
-      { at: 0.8, color: "#7d3d4e" },
-      { at: 1, color: "#0f140d" }
-    ],
-    band: { color: "#0c140d", height: 44 }
-  },
-  layers: [
-    {
-      count: 60,
-      sprite: { kind: "circle", radius: [0.6, 1.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 }
-    },
-    {
-      count: 28,
-      sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
-      size: [13, 20],
-      alpha: [0.5, 0.8],
-      motion: { type: "drift", speed: [12, 26], angle: 100, bob: 3 }
-    },
-    {
-      count: 18,
-      sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
-      size: [20, 32],
-      alpha: [0.7, 0.95],
-      motion: { type: "drift", speed: [24, 44], angle: 100, bob: 6 }
-    },
-    {
-      count: 10,
-      sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
-      size: [34, 54],
-      alpha: [0.85, 1],
-      motion: { type: "drift", speed: [42, 68], angle: 100, bob: 11 }
-    },
-    {
-      count: 16,
-      sprite: { kind: "circle", radius: [1.5, 4], 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 }
+      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,
   id: "dev-dashboard",
@@ -1154,7 +1439,7 @@ var DASHBOARD_SPEC = {
       position: { x: 0.06, y: 0.92 },
       sprite: {
         kind: "text",
-        strings: ["14:03  Edit examples.ts +84 -1"],
+        strings: ["14:03  Edit examples/dev-dashboard.ts +84 -1"],
         color: "#445544",
         font: "10px monospace",
         align: "left",
@@ -1180,31 +1465,324 @@ var DASHBOARD_SPEC = {
     }
   ]
 };
-var EXAMPLE_SPECS = [
-  AQUARIUM_SPEC,
-  RAIN_SPEC,
-  SNOWFALL_SPEC,
-  LANTERNS_SPEC,
-  SAKURA_SPEC,
-  DASHBOARD_SPEC
+
+// src/examples/lanterns.ts
+var LANTERNS_SPEC = {
+  schemaVersion: 1,
+  id: "lanterns",
+  label: "Night Lanterns",
+  seed: 88,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#04060f" },
+      { at: 0.55, color: "#0b1026" },
+      { at: 0.85, color: "#251731" },
+      { at: 1, color: "#472518" }
+    ]
+  },
+  layers: [
+    {
+      count: 60,
+      sprite: { kind: "circle", radius: [0.5, 1.4], color: "#8fa0c8" },
+      alpha: [0.35, 1],
+      region: { y: [0, 0.62] },
+      motion: { type: "drift", speed: [0.5, 2], bob: 1 }
+    },
+    {
+      count: 36,
+      sprite: {
+        kind: "circle",
+        radius: [1.5, 3],
+        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 }
+    },
+    {
+      count: 14,
+      sprite: {
+        kind: "circle",
+        radius: [3.5, 6.5],
+        color: "#e08a34",
+        soft: true
+      },
+      alpha: [0.6, 1],
+      blend: "lighter",
+      pulse: { amp: 0.22, period: 3400 },
+      motion: { type: "rise", speed: [16, 28], sway: 7 }
+    },
+    {
+      count: 8,
+      sprite: { kind: "emoji", glyphs: ["\u{1F3EE}"] },
+      size: [26, 44],
+      alpha: [0.85, 1],
+      motion: { type: "rise", speed: [30, 48], sway: 10 }
+    },
+    {
+      count: 4,
+      sprite: { kind: "emoji", glyphs: ["\u{1F3EE}"] },
+      size: [58, 84],
+      motion: { type: "rise", speed: [52, 74], sway: 14 }
+    },
+    {
+      count: 12,
+      sprite: { kind: "circle", radius: [2, 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 }
+    }
+  ]
+};
+
+// 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,
+  id: "rain",
+  label: "Rain",
+  seed: 7,
+  motionIntensity: "moderate",
+  background: { type: "solid", color: "#05070a" },
+  layers: [
+    {
+      count: 140,
+      sprite: { kind: "text", strings: ["\u2502"], color: "#9fd0ff" },
+      size: [12, 26],
+      motion: { type: "drift", angle: 90, speed: [520, 900] }
+    }
+  ]
+};
+
+// src/examples/sakura.ts
+var SAKURA_SPEC = {
+  schemaVersion: 1,
+  id: "sakura",
+  label: "Sakura Drift",
+  seed: 314,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#1b1d38" },
+      { at: 0.45, color: "#3a2645" },
+      { at: 0.8, color: "#7d3d4e" },
+      { at: 1, color: "#0f140d" }
+    ],
+    band: { color: "#0c140d", height: 44 }
+  },
+  layers: [
+    {
+      count: 60,
+      sprite: { kind: "circle", radius: [0.6, 1.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 }
+    },
+    {
+      count: 28,
+      sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
+      size: [13, 20],
+      alpha: [0.5, 0.8],
+      motion: { type: "drift", speed: [12, 26], angle: 100, bob: 3 }
+    },
+    {
+      count: 18,
+      sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
+      size: [20, 32],
+      alpha: [0.7, 0.95],
+      motion: { type: "drift", speed: [24, 44], angle: 100, bob: 6 }
+    },
+    {
+      count: 10,
+      sprite: { kind: "emoji", glyphs: ["\u{1F338}"] },
+      size: [34, 54],
+      alpha: [0.85, 1],
+      motion: { type: "drift", speed: [42, 68], angle: 100, bob: 11 }
+    },
+    {
+      count: 16,
+      sprite: { kind: "circle", radius: [1.5, 4], 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 }
+    }
+  ]
+};
+
+// src/examples/snowfall.ts
+var SNOWFALL_SPEC = {
+  schemaVersion: 1,
+  id: "snowfall",
+  label: "Snowfall",
+  seed: 12,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#0a1628" },
+      { at: 0.7, color: "#0d1f3c" },
+      { at: 1, color: "#121212" }
+    ]
+  },
+  layers: [
+    {
+      count: 50,
+      sprite: { kind: "circle", radius: [1, 2.5], color: "#8899aa" },
+      motion: { type: "drift", angle: 90, speed: [15, 40], bob: 3 }
+    },
+    {
+      count: 35,
+      sprite: { kind: "circle", radius: [2, 4.5], color: "#c0cdd8" },
+      motion: { type: "drift", angle: 85, speed: [35, 80], bob: 6 }
+    },
+    {
+      count: 15,
+      sprite: { kind: "circle", radius: [3.5, 7], color: "#e8eff5" },
+      motion: { type: "drift", angle: 82, speed: [55, 120], bob: 10 }
+    }
+  ]
+};
+
+// src/examples/index.ts
+var SCHEMA_EXAMPLES = [
+  { id: "aquarium", label: "Aquarium", spec: AQUARIUM_SPEC },
+  { id: "rain", label: "Rain", spec: RAIN_SPEC },
+  { 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: "orrery", label: "Orrery", spec: ORRERY_SPEC },
+  { id: "constellation", label: "Constellation", spec: CONSTELLATION_SPEC }
 ];
+var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
+var EXAMPLE_BY_ID = Object.fromEntries(
+  SCHEMA_EXAMPLES.map((e) => [e.id, e.spec])
+);
 export {
   AQUARIUM_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,
+  easeSmooth,
+  lerpSpec,
+  linkPairs,
   manifestFor,
   positionAt,
+  resolveSpecPath,
+  rotationAt,
+  sizeAt,
+  spriteIndexAt,
   spriteVariants,
+  structuralSignature,
   validateSpec
 };
 //# sourceMappingURL=index.js.map