@idle-screens/schema 0.1.0 → 2.0.0

package/dist/index.js

@@ -3,9 +3,13 @@ var SCHEMA_VERSION = 1;
 var LIMITS = {
   maxPerLayer: 400,
   maxTotal: 800,
-  maxLayers: 8,
-  maxSpeed: 4e3
+  maxLayers: 36,
+  maxSpeed: 4e3,
   // px/sec — bounds motion so nothing teleports
+  maxPulseAmp: 0.5,
+  // opacity breathing amplitude cap
+  minPulsePeriod: 500
+  // ms — caps pulse at 2 Hz (WCAG flash threshold is 3 Hz)
 };
 
 // src/validate.ts
@@ -78,6 +82,44 @@ function validateLayer(layer, path, err) {
   }
   if (layer.wrap !== void 0 && typeof layer.wrap !== "boolean") err(`${path}.wrap`, "must be a boolean");
   if (layer.flip !== void 0 && typeof layer.flip !== "boolean") err(`${path}.flip`, "must be a boolean");
+  if (layer.alpha !== void 0 && (!isRange(layer.alpha) || layer.alpha[0] < 0 || layer.alpha[1] > 1)) {
+    err(`${path}.alpha`, "must be a [min,max] range within 0..1");
+  }
+  if (layer.blend !== void 0 && layer.blend !== "lighter") err(`${path}.blend`, "must be 'lighter' when set");
+  if (layer.key !== void 0 && (!isStr(layer.key) || layer.key.trim() === "")) {
+    err(`${path}.key`, "must be a non-empty string");
+  }
+  if (layer.position !== void 0) {
+    if (!isObj(layer.position) || !isNum(layer.position.x) || !isNum(layer.position.y)) {
+      err(`${path}.position`, "must be {x, y} with numbers 0..1");
+    } else {
+      if (layer.position.x < 0 || layer.position.x > 1) err(`${path}.position.x`, "must be 0..1");
+      if (layer.position.y < 0 || layer.position.y > 1) err(`${path}.position.y`, "must be 0..1");
+      if (isNum(layer.count) && layer.count !== 1) err(`${path}.position`, "position requires count: 1");
+    }
+  }
+  if (layer.region !== void 0) {
+    if (!isObj(layer.region)) err(`${path}.region`, "must be an object");
+    else {
+      for (const axis of ["x", "y"]) {
+        const r = layer.region[axis];
+        if (r !== void 0 && (!isRange(r) || r[0] < 0 || r[1] > 1)) {
+          err(`${path}.region.${axis}`, "must be a [min,max] range within 0..1");
+        }
+      }
+    }
+  }
+  if (layer.pulse !== void 0) {
+    if (!isObj(layer.pulse)) err(`${path}.pulse`, "must be an object");
+    else {
+      if (!isNum(layer.pulse.amp) || layer.pulse.amp <= 0 || layer.pulse.amp > LIMITS.maxPulseAmp) {
+        err(`${path}.pulse.amp`, `must be within 0..${LIMITS.maxPulseAmp}`);
+      }
+      if (!isNum(layer.pulse.period) || layer.pulse.period < LIMITS.minPulsePeriod) {
+        err(`${path}.pulse.period`, `must be >= ${LIMITS.minPulsePeriod} ms (flash-safety floor)`);
+      }
+    }
+  }
   validateSprite(layer.sprite, `${path}.sprite`, err);
   validateMotion(layer.motion, `${path}.motion`, err);
 }
@@ -92,9 +134,19 @@ function validateSprite(sprite, path, err) {
       err(`${path}.strings`, "must be a non-empty array of strings");
     }
     if (sprite.color !== void 0) color(sprite.color, `${path}.color`, err);
+    if (sprite.align !== void 0 && !["left", "center", "right"].includes(sprite.align)) {
+      err(`${path}.align`, "must be left | center | right");
+    }
+    if (sprite.baseline !== void 0 && !["top", "middle", "bottom"].includes(sprite.baseline)) {
+      err(`${path}.baseline`, "must be top | middle | bottom");
+    }
+    if (sprite.maxWidth !== void 0 && (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0)) {
+      err(`${path}.maxWidth`, "must be a positive number");
+    }
   } 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");
   } else {
     err(`${path}.kind`, "must be emoji | text | circle");
   }
@@ -115,8 +167,9 @@ function validateMotion(motion, path, err) {
     if (motion.sway !== void 0 && !isNum(motion.sway)) err(`${path}.sway`, "must be a number");
   } else if (motion.type === "bounce") {
     speedOk(motion.speed, `${path}.speed`);
+  } else if (motion.type === "static") {
   } else {
-    err(`${path}.type`, "must be drift | rise | bounce");
+    err(`${path}.type`, "must be drift | rise | bounce | static");
   }
 }
 function assertValidSpec(spec) {
@@ -145,7 +198,9 @@ function buildEntities(layer, rng, w, h) {
     let bob = 0;
     let motion = "drift";
     const m = layer.motion;
-    if (m.type === "drift") {
+    if (m.type === "static") {
+      motion = "static";
+    } else if (m.type === "drift") {
       const s = rng.range(m.speed[0], m.speed[1]);
       let angle = (m.angle ?? 0) * Math.PI / 180;
       if (m.bidirectional && rng.next() < 0.5) angle = Math.PI - angle;
@@ -163,9 +218,20 @@ function buildEntities(layer, rng, w, h) {
       vx = s * Math.cos(a);
       vy = s * Math.sin(a);
     }
+    let x0;
+    let y0;
+    if (layer.position && layer.count === 1) {
+      x0 = layer.position.x * w;
+      y0 = layer.position.y * h;
+    } else {
+      const [rx0, rx1] = layer.region?.x ?? [0, 1];
+      const [ry0, ry1] = layer.region?.y ?? [0, 1];
+      x0 = rng.range(rx0 * w, rx1 * w);
+      y0 = rng.range(ry0 * h, ry1 * h);
+    }
     out.push({
-      x0: rng.range(0, w),
-      y0: rng.range(0, h),
+      x0,
+      y0,
       size,
       spriteIndex: variants > 1 ? rng.int(0, variants - 1) : 0,
       phase: rng.range(0, Math.PI * 2),
@@ -173,11 +239,20 @@ function buildEntities(layer, rng, w, h) {
       vy,
       bob,
       motion,
-      headingLeft: vx < 0
+      headingLeft: vx < 0,
+      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
     });
   }
   return out;
 }
+function alphaAt(e, t) {
+  if (!e.pulseAmp) return e.alpha;
+  const a = e.alpha + e.pulseAmp * Math.sin(t * 2 * Math.PI / e.pulsePeriod + e.pulsePhase);
+  return a < 0 ? 0 : a > 1 ? 1 : a;
+}
 function wrap(v, min, max) {
   const range = max - min;
   return ((v - min) % range + range) % range + min;
@@ -190,6 +265,7 @@ function reflect(v, min, max) {
   return min + (p < range ? p : period - p);
 }
 function positionAt(e, t, w, h) {
+  if (e.motion === "static") return { x: e.x0, y: e.y0, flip: false };
   const dt = t / 1e3;
   const m = e.size;
   if (e.motion === "bounce") {
@@ -216,6 +292,104 @@ function positionAt(e, t, w, h) {
 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.layers.map((l) => [
+      l.count,
+      l.size,
+      l.region,
+      l.position,
+      l.motion,
+      l.wrap,
+      l.flip,
+      l.alpha,
+      l.pulse,
+      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
+    ])
+  );
+}
+
+// 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);
+  return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${alpha})`;
+}
 function manifestFor(spec) {
   const total = spec.layers.reduce((n, l) => n + l.count, 0);
   const costTier = total < 30 ? "idle" : total < 150 ? "low" : total < 400 ? "medium" : "high";
@@ -229,17 +403,26 @@ 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;
-    const canvas = document.createElement("canvas");
-    canvas.style.cssText = "display:block;width:100%;height:100%";
-    canvas.setAttribute("aria-hidden", "true");
-    ctx.host.appendChild(canvas);
+    let canvas;
+    if (ctx.surface) {
+      canvas = ctx.surface;
+    } else {
+      const el = document.createElement("canvas");
+      el.style.cssText = "display:block;width:100%;height:100%";
+      el.setAttribute("aria-hidden", "true");
+      ctx.host.appendChild(el);
+      canvas = el;
+    }
     this.canvas = canvas;
     const c2d = canvas.getContext("2d", { alpha: false });
     if (!c2d) throw new Error("schema saver: no 2d context");
@@ -255,6 +438,7 @@ var SpecInstance = class {
   spec;
   canvas;
   ctx;
+  saverCtx;
   seed;
   w;
   h;
@@ -262,8 +446,16 @@ var SpecInstance = class {
   frameId = null;
   paused = false;
   startT = 0;
+  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(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, 2);
+    const dpr = Math.min(this.saverCtx.dpr, 2);
     this.canvas.width = Math.max(1, Math.round(this.w * dpr));
     this.canvas.height = Math.max(1, Math.round(this.h * dpr));
     this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
@@ -271,7 +463,8 @@ 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) }));
+    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h) }));
+    this.lastStructural = structuralSignature(this.effSpec);
   }
   start() {
     if (this.frameId !== null || typeof requestAnimationFrame === "undefined") return;
@@ -283,15 +476,17 @@ var SpecInstance = class {
       cancelAnimationFrame(this.frameId);
       this.frameId = null;
     }
+    this.baseT = this.lastT;
   }
   loop(now) {
     this.frameId = requestAnimationFrame((n) => this.loop(n));
     if (this.startT === 0) this.startT = now;
-    this.renderFrame(now - this.startT, this.seed);
+    this.lastT = now - this.startT + this.baseT;
+    this.renderFrame(this.lastT, this.seed);
   }
   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);
@@ -310,10 +505,20 @@ var SpecInstance = class {
     const { ctx } = this;
     const p = positionAt(e, t, this.w, this.h);
     const sprite = built.layer.sprite;
+    ctx.globalAlpha = alphaAt(e, t);
     if (sprite.kind === "circle") {
-      ctx.fillStyle = sprite.color;
+      const r = e.size / 2;
+      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));
+        ctx.fillStyle = g;
+      } else {
+        ctx.fillStyle = sprite.color;
+      }
       ctx.beginPath();
-      ctx.arc(p.x, p.y, e.size / 2, 0, Math.PI * 2);
+      ctx.arc(p.x, p.y, r, 0, Math.PI * 2);
       ctx.fill();
       return;
     }
@@ -326,18 +531,67 @@ var SpecInstance = class {
       ctx.font = `${e.size}px serif`;
       ctx.fillText(sprite.glyphs[e.spriteIndex] ?? 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.fillStyle = sprite.color ?? "#e6e8ef";
-      ctx.fillText(sprite.strings[e.spriteIndex] ?? sprite.strings[0], 0, 0);
+      const text = sprite.strings[e.spriteIndex] ?? sprite.strings[0];
+      if (sprite.maxWidth) ctx.fillText(text, 0, 0, sprite.maxWidth);
+      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);
+    }
+  }
   /** 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";
       for (const e of built.entities) this.drawEntity(built, e, t);
     }
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = "source-over";
   }
   setPaused(paused) {
     this.paused = paused;
@@ -347,31 +601,33 @@ var SpecInstance = class {
       this.start();
     }
   }
-  resize(width, height) {
+  resize(width, height, dpr) {
     this.w = width;
     this.h = height;
+    if (dpr !== void 0) this.saverCtx.dpr = dpr;
     this.sizeCanvas();
     this.rebuild();
     if (this.paused) this.renderFrame(0, this.seed);
   }
   dispose() {
     this.stop();
-    this.canvas.remove();
+    if (typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
   }
 };
 function compileSaver(spec) {
   const valid = assertValidSpec(spec);
   return {
     manifest: manifestFor(valid),
-    mount: (ctx) => new SpecInstance(valid, ctx)
+    mount: (ctx) => new SpecInstance(valid, ctx),
+    spec: valid
   };
 }
 
-// src/examples.ts
+// src/examples/aquarium.ts
 var AQUARIUM_SPEC = {
   schemaVersion: 1,
   id: "aquarium",
-  label: "Aquarium (declarative)",
+  label: "Aquarium",
   seed: 42,
   motionIntensity: "calm",
   background: {
@@ -398,10 +654,576 @@ var AQUARIUM_SPEC = {
     }
   ]
 };
+
+// src/examples/dev-dashboard.ts
+var DASHBOARD_SPEC = {
+  schemaVersion: 1,
+  id: "dev-dashboard",
+  label: "Dev Dashboard",
+  seed: 256,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#06060c" },
+      { at: 0.5, color: "#0a0a14" },
+      { at: 1, color: "#0c0c18" }
+    ]
+  },
+  layers: [
+    // --- ambient depth ---
+    {
+      count: 50,
+      sprite: { kind: "circle", radius: [0.2, 0.8], color: "#1a2538" },
+      alpha: [0.1, 0.25],
+      motion: { type: "drift", speed: [0.3, 1.2], bob: 0.3 }
+    },
+    {
+      count: 12,
+      sprite: { kind: "circle", radius: [1, 2.5], color: "#1a3050", soft: true },
+      alpha: [0.08, 0.18],
+      blend: "lighter",
+      pulse: { amp: 0.08, period: 4e3 },
+      motion: { type: "drift", speed: [0.5, 1.5], bob: 0.5 }
+    },
+    // --- header ---
+    {
+      key: "title",
+      count: 1,
+      position: { x: 0.5, y: 0.04 },
+      sprite: {
+        kind: "text",
+        strings: ["DEV PULSE"],
+        color: "#556677",
+        font: "600 13px 'SF Mono', monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "status",
+      count: 1,
+      position: { x: 0.92, y: 0.04 },
+      sprite: {
+        kind: "text",
+        strings: ["\u25CF ACTIVE"],
+        color: "#44cc66",
+        font: "bold 10px monospace",
+        align: "right"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "uptime",
+      count: 1,
+      position: { x: 0.08, y: 0.04 },
+      sprite: {
+        kind: "text",
+        strings: ["up 2h 14m"],
+        color: "#445566",
+        font: "10px monospace",
+        align: "left"
+      },
+      motion: { type: "static" }
+    },
+    // --- left column: metrics ---
+    {
+      key: "tools-label",
+      count: 1,
+      position: { x: 0.06, y: 0.12 },
+      sprite: {
+        kind: "text",
+        strings: ["TOOL CALLS"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "tools-value",
+      count: 1,
+      position: { x: 0.06, y: 0.16 },
+      sprite: {
+        kind: "text",
+        strings: ["147"],
+        color: "#44aaff",
+        font: "bold 28px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "reads-label",
+      count: 1,
+      position: { x: 0.06, y: 0.26 },
+      sprite: {
+        kind: "text",
+        strings: ["READS"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "reads-value",
+      count: 1,
+      position: { x: 0.06, y: 0.3 },
+      sprite: {
+        kind: "text",
+        strings: ["89"],
+        color: "#44ddcc",
+        font: "bold 28px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "edits-label",
+      count: 1,
+      position: { x: 0.06, y: 0.4 },
+      sprite: {
+        kind: "text",
+        strings: ["EDITS"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "edits-value",
+      count: 1,
+      position: { x: 0.06, y: 0.44 },
+      sprite: {
+        kind: "text",
+        strings: ["34"],
+        color: "#ff8844",
+        font: "bold 28px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "errors-label",
+      count: 1,
+      position: { x: 0.06, y: 0.54 },
+      sprite: {
+        kind: "text",
+        strings: ["ERRORS"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "errors-value",
+      count: 1,
+      position: { x: 0.06, y: 0.58 },
+      sprite: {
+        kind: "text",
+        strings: ["2"],
+        color: "#ff4455",
+        font: "bold 28px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    // --- center column: system gauges ---
+    {
+      key: "cpu-label",
+      count: 1,
+      position: { x: 0.38, y: 0.12 },
+      sprite: {
+        kind: "text",
+        strings: ["CPU"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "cpu-value",
+      count: 1,
+      position: { x: 0.38, y: 0.22 },
+      sprite: {
+        kind: "text",
+        strings: ["73%"],
+        color: "#44ff88",
+        font: "bold 36px monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "mem-label",
+      count: 1,
+      position: { x: 0.38, y: 0.36 },
+      sprite: {
+        kind: "text",
+        strings: ["MEMORY"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "mem-value",
+      count: 1,
+      position: { x: 0.38, y: 0.46 },
+      sprite: {
+        kind: "text",
+        strings: ["4.2 GB"],
+        color: "#ddcc44",
+        font: "bold 36px monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "tokens-label",
+      count: 1,
+      position: { x: 0.38, y: 0.58 },
+      sprite: {
+        kind: "text",
+        strings: ["TOKENS"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "tokens-value",
+      count: 1,
+      position: { x: 0.38, y: 0.66 },
+      sprite: {
+        kind: "text",
+        strings: ["128k"],
+        color: "#aa88ff",
+        font: "bold 28px monospace",
+        align: "center"
+      },
+      motion: { type: "static" }
+    },
+    // --- right column: recent files ---
+    {
+      key: "files-label",
+      count: 1,
+      position: { x: 0.62, y: 0.12 },
+      sprite: {
+        kind: "text",
+        strings: ["RECENT FILES"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "file-1",
+      count: 1,
+      position: { x: 0.62, y: 0.17 },
+      sprite: {
+        kind: "text",
+        strings: ["src/worker.ts"],
+        color: "#8899aa",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 280
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "file-2",
+      count: 1,
+      position: { x: 0.62, y: 0.21 },
+      sprite: {
+        kind: "text",
+        strings: ["site/src/App.tsx"],
+        color: "#778899",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 280
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "file-3",
+      count: 1,
+      position: { x: 0.62, y: 0.25 },
+      sprite: {
+        kind: "text",
+        strings: ["packages/schema/compile.ts"],
+        color: "#667788",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 280
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "file-4",
+      count: 1,
+      position: { x: 0.62, y: 0.29 },
+      sprite: {
+        kind: "text",
+        strings: ["docs/dashboard-spec.md"],
+        color: "#556677",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 280
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "file-5",
+      count: 1,
+      position: { x: 0.62, y: 0.33 },
+      sprite: {
+        kind: "text",
+        strings: ["packages/core/types.ts"],
+        color: "#445566",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 280
+      },
+      motion: { type: "static" }
+    },
+    // --- right column: session info ---
+    {
+      key: "session-label",
+      count: 1,
+      position: { x: 0.62, y: 0.42 },
+      sprite: {
+        kind: "text",
+        strings: ["SESSION"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "session-model",
+      count: 1,
+      position: { x: 0.62, y: 0.47 },
+      sprite: {
+        kind: "text",
+        strings: ["claude-opus-4-6"],
+        color: "#8888aa",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "session-cost",
+      count: 1,
+      position: { x: 0.62, y: 0.51 },
+      sprite: {
+        kind: "text",
+        strings: ["$2.47 this session"],
+        color: "#667788",
+        font: "11px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    // --- bottom: event log ---
+    {
+      key: "log-label",
+      count: 1,
+      position: { x: 0.06, y: 0.76 },
+      sprite: {
+        kind: "text",
+        strings: ["EVENT LOG"],
+        color: "#445566",
+        font: "9px monospace",
+        align: "left",
+        baseline: "top"
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "log-1",
+      count: 1,
+      position: { x: 0.06, y: 0.8 },
+      sprite: {
+        kind: "text",
+        strings: ["14:07  Edit compile.ts +18 -3"],
+        color: "#667766",
+        font: "10px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 600
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "log-2",
+      count: 1,
+      position: { x: 0.06, y: 0.84 },
+      sprite: {
+        kind: "text",
+        strings: ["14:06  Bash pnpm test  \u2713 125 passed"],
+        color: "#556655",
+        font: "10px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 600
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "log-3",
+      count: 1,
+      position: { x: 0.06, y: 0.88 },
+      sprite: {
+        kind: "text",
+        strings: ["14:05  Read types.ts  (121 lines)"],
+        color: "#4d5e4d",
+        font: "10px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 600
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "log-4",
+      count: 1,
+      position: { x: 0.06, y: 0.92 },
+      sprite: {
+        kind: "text",
+        strings: ["14:03  Edit examples/dev-dashboard.ts +84 -1"],
+        color: "#445544",
+        font: "10px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 600
+      },
+      motion: { type: "static" }
+    },
+    {
+      key: "log-5",
+      count: 1,
+      position: { x: 0.06, y: 0.96 },
+      sprite: {
+        kind: "text",
+        strings: ["14:01  Bash pnpm build  \u2713 6 packages"],
+        color: "#3d4e3d",
+        font: "10px monospace",
+        align: "left",
+        baseline: "top",
+        maxWidth: 600
+      },
+      motion: { type: "static" }
+    }
+  ]
+};
+
+// 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/rain.ts
 var RAIN_SPEC = {
   schemaVersion: 1,
   id: "rain",
-  label: "Rain (declarative)",
+  label: "Rain",
   seed: 7,
   motionIntensity: "moderate",
   background: { type: "solid", color: "#05070a" },
@@ -414,19 +1236,138 @@ var RAIN_SPEC = {
     }
   ]
 };
-var EXAMPLE_SPECS = [AQUARIUM_SPEC, RAIN_SPEC];
+
+// 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 }
+];
+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,
+  DASHBOARD_SPEC,
+  EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
+  LANTERNS_SPEC,
   LIMITS,
   RAIN_SPEC,
+  SAKURA_SPEC,
+  SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
+  SNOWFALL_SPEC,
+  alphaAt,
+  applyDeltasToSpec,
   assertValidSpec,
   buildEntities,
   compileSaver,
+  easeSmooth,
+  lerpSpec,
   manifestFor,
   positionAt,
+  resolveSpecPath,
   spriteVariants,
+  structuralSignature,
   validateSpec
 };
 //# sourceMappingURL=index.js.map