@idle-screens/schema 1.0.0 → 2.0.0

package/dist/index.js

@@ -292,6 +292,99 @@ 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);
@@ -310,12 +403,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 +449,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 +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;
@@ -385,7 +486,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);
@@ -440,8 +541,47 @@ var SpecInstance = class {
     }
     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";
@@ -483,7 +623,7 @@ function compileSaver(spec) {
   };
 }
 
-// src/examples.ts
+// src/examples/aquarium.ts
 var AQUARIUM_SPEC = {
   schemaVersion: 1,
   id: "aquarium",
@@ -514,185 +654,8 @@ 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 = {
-  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 }
-    }
-  ]
-};
-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/dev-dashboard.ts
 var DASHBOARD_SPEC = {
   schemaVersion: 1,
   id: "dev-dashboard",
@@ -1154,7 +1117,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 +1143,231 @@ 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/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 }
 ];
+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