@idle-screens/schema 2.3.0 → 3.0.0

package/dist/index.js

@@ -250,8 +250,15 @@ function validateLayer(layer, path, err, warn, spec) {
     }
   }
   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 (isRange(layer.spin)) {
+      if (Math.abs(layer.spin[0]) > LIMITS.maxSpin || Math.abs(layer.spin[1]) > LIMITS.maxSpin) {
+        err(`${path}.spin`, `each end of the range must be within \xB1${LIMITS.maxSpin} deg/sec`);
+      }
+    } else if (!isNum(layer.spin)) {
+      err(`${path}.spin`, "must be a number or a [min,max] range (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");
@@ -749,8 +756,10 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
       pulsePeriod: layer.pulse?.period ?? 1e3,
       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
+      // Scalar spin: no draw here, one phase draw below (unchanged). Range spin
+      // (new): one seeded speed draw here, then the phase draw — array form is new
+      // so the extra draw can't perturb any existing spec's entity stream.
+      spinSpeed: typeof layer.spin === "number" ? layer.spin * Math.PI / 180 : Array.isArray(layer.spin) ? rng.range(layer.spin[0], layer.spin[1]) * Math.PI / 180 : 0,
       spinPhase: layer.spin ? rng.range(0, Math.PI * 2) : 0,
       growAmp: layer.grow?.amp ?? 0,
       growPeriod: layer.grow?.period ?? 1e3,
@@ -1178,6 +1187,11 @@ function hexToRgba(hex, alpha) {
   return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${alpha})`;
 }
 var FONT_PREFIX_RE = /^((?:(?:italic|oblique|bold|bolder|lighter|normal|\d{3})\s+)+)/;
+var FONT_PX_RE = /(\d*\.?\d+)px/;
+function scaleFontPx(font, factor) {
+  if (factor === 1) return font;
+  return font.replace(FONT_PX_RE, (_m, n) => `${(Number(n) * factor).toFixed(2)}px`);
+}
 function composeFontShorthand(sz, font) {
   const m = FONT_PREFIX_RE.exec(font);
   if (m) return `${m[1].trim()} ${sz}px ${font.slice(m[0].length)}`;
@@ -1249,6 +1263,11 @@ var SpecInstance = class {
   /** Active glide between two resolved specs (live setParam/applyTrack). */
   transition = null;
   lastStructural = "";
+  /** Viewport factor for absolute px sizes — 1 for `units: 'px'` specs. */
+  fontScale() {
+    if (this.effSpec.units === "px") return 1;
+    return Math.min(this.w, this.h) / (this.effSpec.referenceViewport ?? LIMITS.referenceViewport);
+  }
   sizeCanvas() {
     const dpr = Math.min(this.saverCtx.dpr, 2);
     this.canvas.width = Math.max(1, Math.round(this.w * dpr));
@@ -1463,7 +1482,7 @@ var SpecInstance = class {
     } else {
       ctx.textAlign = sprite.align ?? "center";
       ctx.textBaseline = sprite.baseline ?? "middle";
-      ctx.font = sprite.font ? /\dpx/.test(sprite.font) ? sprite.font : composeFontShorthand(sz, sprite.font) : `${sz}px system-ui, sans-serif`;
+      ctx.font = sprite.font ? FONT_PX_RE.test(sprite.font) ? scaleFontPx(sprite.font, this.fontScale()) : composeFontShorthand(sz, sprite.font) : `${sz}px system-ui, sans-serif`;
       ctx.fillStyle = sprite.color ?? "#e6e8ef";
       const idx = spriteIndexAt(e, t, sprite.strings.length);
       const text = sprite.strings[idx] ?? sprite.strings[0];
@@ -1875,6 +1894,8 @@ function describeScene(spec, options = {}) {
 
 // src/perceive.ts
 import { createRng as createRng4 } from "@idle-screens/core";
+var GLOW_SPREAD = 2.4;
+var LINE_SALIENCE = 3.5;
 function buildScene(spec, opts) {
   const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
   const seed = opts.seed ?? spec.seed ?? 42;
@@ -2013,12 +2034,16 @@ function luminanceGrid(spec, opts = {}) {
         halfX = box.halfX;
         halfY = box.halfY;
       }
-      const c0 = Math.max(0, Math.floor((centerX - halfX) / cellW));
-      const c1 = Math.min(cols - 1, Math.floor((centerX + halfX) / cellW));
-      const r0 = Math.max(0, Math.floor((centerY - halfY) / cellH));
-      const r1 = Math.min(rows - 1, Math.floor((centerY + halfY) / cellH));
       const circular = s.kind === "circle" || s.kind === "ring";
-      const soft = s.kind === "circle" && s.soft;
+      const soft = s.kind === "circle" && !!s.soft;
+      const additive = layer.blend === "lighter" || layer.blend === "screen";
+      const glow = soft && additive;
+      const reachX = glow ? halfX * GLOW_SPREAD : halfX;
+      const reachY = glow ? halfY * GLOW_SPREAD : halfY;
+      const c0 = Math.max(0, Math.floor((centerX - reachX) / cellW));
+      const c1 = Math.min(cols - 1, Math.floor((centerX + reachX) / cellW));
+      const r0 = Math.max(0, Math.floor((centerY - reachY) / cellH));
+      const r1 = Math.min(rows - 1, Math.floor((centerY + reachY) / cellH));
       const inkWeight = s.kind === "text" || s.kind === "emoji" ? 0.55 : 1;
       for (let r = r0; r <= r1; r++) {
         for (let c = c0; c <= c1; c++) {
@@ -2026,12 +2051,23 @@ function luminanceGrid(spec, opts = {}) {
           const dy = (r + 0.5) * cellH - centerY;
           if (circular) {
             const d = Math.sqrt(dx * dx + dy * dy);
-            if (d > halfX + Math.min(cellW, cellH) / 2) continue;
+            const reach = glow ? reachX : halfX;
+            if (d > reach + Math.min(cellW, cellH) / 2) continue;
             if (s.kind === "ring") {
               const strokeW = (s.width ?? (scale === 1 ? 2 : 2e-3)) * scale;
               if (d < halfX - strokeW) continue;
             }
-            const wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
+            let wgt;
+            if (glow) {
+              const core = halfX;
+              if (d <= core) wgt = 1;
+              else {
+                const f = Math.max(0, 1 - (d - core) / Math.max(reachX - core, 1e-6));
+                wgt = f * f;
+              }
+            } else {
+              wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
+            }
             compose(r * cols + c, lum, a * wgt, layer.blend);
           } else {
             compose(r * cols + c, lum, a * inkWeight, layer.blend);
@@ -2107,11 +2143,14 @@ var DOT_BIT = [
   [4, 32],
   [64, 128]
 ];
-function renderBrailleMap(grid) {
+function autoExpose(grid) {
   const sorted = [...grid.cells].sort((a, b) => a - b);
   const lo = sorted[0];
   const hi = Math.max(sorted[Math.floor(sorted.length * 0.98)], lo + 0.08);
-  const expose = (v) => Math.pow(Math.max(0, Math.min(1, (v - lo) / (hi - lo))), 0.8);
+  return (v) => Math.pow(Math.max(0, Math.min(1, (v - lo) / (hi - lo))), 0.8);
+}
+function renderBrailleMap(grid) {
+  const expose = autoExpose(grid);
   const outRows = [];
   for (let br = 0; br < Math.floor(grid.rows / 4); br++) {
     let line = "";
@@ -2129,6 +2168,34 @@ function renderBrailleMap(grid) {
   }
   return outRows.join("\n");
 }
+var DENSITY_RAMP = " .:-=+*#%@";
+function renderDensityMap(grid) {
+  const expose = autoExpose(grid);
+  const ramp = DENSITY_RAMP;
+  const lines = [];
+  for (let r = 0; r < grid.rows; r++) {
+    let line = "";
+    for (let c = 0; c < grid.cols; c++) {
+      const v = expose(grid.cells[r * grid.cols + c]);
+      line += ramp[Math.min(ramp.length - 1, Math.floor(v * ramp.length))];
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function textSprites(spec, opts = {}) {
+  const scene = buildScene(spec, opts);
+  const t = opts.t ?? 5e3;
+  const out = [];
+  scene.layers.forEach(({ layer, entities }, layerIndex) => {
+    if (layer.sprite.kind !== "text") return;
+    const s = layer.sprite;
+    const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
+    const sizePx = m ? Number(m[1]) : entities[0] ? sizeAt(entities[0], t) : 0;
+    out.push({ layerIndex, key: layer.key, strings: [...s.strings], count: entities.length, sizePx: Math.round(sizePx) });
+  });
+  return out;
+}
 function dominanceRanking(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
@@ -2148,8 +2215,8 @@ function dominanceRanking(spec, opts = {}) {
       const s = layer.sprite;
       let entArea;
       if (s.kind === "circle") entArea = Math.PI * (sz / 2) * (sz / 2);
-      else if (s.kind === "ring") entArea = Math.PI * sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale);
-      else if (s.kind === "streak") entArea = sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale);
+      else if (s.kind === "ring") entArea = Math.PI * sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale) * LINE_SALIENCE;
+      else if (s.kind === "streak") entArea = sz * ((s.width ?? (scale === 1 ? 2 : 2e-3)) * scale) * LINE_SALIENCE;
       else if (s.kind === "rect") {
         const h2 = e.size2 !== void 0 ? e.size2 * (e.size > 0 ? sz / e.size : 1) : sz;
         entArea = sz * h2;
@@ -2166,7 +2233,7 @@ function dominanceRanking(spec, opts = {}) {
       const edges = linkEdges(layer.links, positions, layer.links.maxDist * scale, layer.wrap !== false && motionWraps, w, h);
       const la = (layer.links.alpha ?? 0.6) * lifeA;
       const lw = (layer.links.width ?? 1) * scale;
-      for (const edge of edges) area += edge.dist * lw * la;
+      for (const edge of edges) area += edge.dist * lw * la * LINE_SALIENCE;
     }
     const meanLuma = entities.length ? lumAcc / entities.length : 0;
     const contrast = Math.abs(meanLuma - bgMean) + 0.1;
@@ -2274,6 +2341,7 @@ function perceiveScene(spec, opts = {}) {
   return {
     t: opts.t ?? 5e3,
     braille: renderBrailleMap(grid),
+    density: renderDensityMap(grid),
     coverage: grid.coverage,
     meanLuminance: grid.meanLuminance,
     centroid: grid.centroid,
@@ -2281,6 +2349,7 @@ function perceiveScene(spec, opts = {}) {
     colProfile: grid.colProfile,
     dominance: dominanceRanking(spec, opts),
     motion: motionStats(spec, opts),
+    text: textSprites(spec, opts),
     advisories: adviseSpec(spec, opts.viewport ?? { width: 1920, height: 1080 })
   };
 }
@@ -2494,84 +2563,113 @@ var DASHBOARD_SPEC = {
   background: {
     type: "gradient",
     stops: [
-      { at: 0, color: "#06060c" },
-      { at: 0.5, color: "#0a0a14" },
-      { at: 1, color: "#0c0c18" }
+      { at: 0, color: "#05070d" },
+      { at: 0.55, color: "#080b14" },
+      { at: 1, color: "#0a0d18" }
     ]
   },
   layers: [
-    // --- ambient depth ---
-    {
-      key: "dust",
-      count: 40,
-      sprite: { kind: "circle", radius: [1852e-7, 7407e-7], color: "#1a2538" },
-      alpha: [0.1, 0.25],
-      motion: { type: "drift", speed: [2778e-7, 1111e-6], bob: 2778e-7 }
-    },
+    // ---- ambient: the LED wall behind everything ----
     {
       key: "led-wall",
-      count: 140,
-      sprite: { kind: "circle", radius: [8e-4, 12e-4], color: "#274058" },
-      alpha: [0.05, 0.11],
-      layout: { type: "grid", columns: 20, jitter: 0.15 },
-      // A slow breath travels diagonally across the wall of dots.
-      pulse: { amp: 0.3, period: 5e3, wave: { wavelength: 0.35, angle: 20 } },
+      count: 240,
+      sprite: { kind: "circle", radius: [7e-4, 11e-4], color: "#22344c" },
+      alpha: [0.04, 0.1],
+      layout: { type: "grid", columns: 24, jitter: 0.1 },
+      pulse: { amp: 0.3, period: 6200, wave: { wavelength: 0.4, angle: 24 } },
       motion: { type: "static" }
     },
-    // --- header (boots first) ---
+    // ---- frame chrome (boots first) ----
+    {
+      key: "rule-header",
+      count: 1,
+      position: { x: 0.5, y: 0.085 },
+      sprite: { kind: "rect", width: [0.93, 0.93], aspect: [12e-4, 12e-4], color: "#24384f" },
+      alpha: [0.8, 0.8],
+      motion: { type: "static" },
+      life: { enter: 100, fade: 400 }
+    },
+    {
+      key: "rule-footer",
+      count: 1,
+      position: { x: 0.5, y: 0.915 },
+      sprite: { kind: "rect", width: [0.93, 0.93], aspect: [12e-4, 12e-4], color: "#24384f" },
+      alpha: [0.8, 0.8],
+      motion: { type: "static" },
+      life: { enter: 100, fade: 400 }
+    },
+    {
+      key: "rule-col-left",
+      count: 1,
+      position: { x: 0.265, y: 0.5 },
+      sprite: { kind: "rect", width: [9e-4, 9e-4], aspect: [620, 620], color: "#1c2c40" },
+      alpha: [0.7, 0.7],
+      motion: { type: "static" },
+      life: { enter: 100, fade: 400 }
+    },
+    {
+      key: "rule-col-right",
+      count: 1,
+      position: { x: 0.645, y: 0.5 },
+      sprite: { kind: "rect", width: [9e-4, 9e-4], aspect: [620, 620], color: "#1c2c40" },
+      alpha: [0.7, 0.7],
+      motion: { type: "static" },
+      life: { enter: 100, fade: 400 }
+    },
+    // ---- header band ----
     {
       key: "title",
       count: 1,
-      position: { x: 0.5, y: 0.045 },
+      position: { x: 0.035, y: 0.052 },
       sprite: {
         kind: "text",
-        strings: ["CONTROL CENTER"],
-        color: "#556677",
+        strings: ["VIREO-9 \xB7 TRANS-LUNAR RELAY \xB7 OPS WALL 03"],
+        color: "#7f93ab",
         font: "600 13px 'SF Mono', monospace",
-        align: "center"
+        align: "left"
       },
       motion: { type: "static" },
       life: { enter: 200, fade: 600 }
     },
     {
-      key: "status",
+      key: "clock",
       count: 1,
-      position: { x: 0.94, y: 0.045 },
+      position: { x: 0.5, y: 0.058 },
       sprite: {
         kind: "text",
-        strings: ["\u25CF ALL SYSTEMS GO"],
-        color: "#44cc66",
-        font: "bold 10px monospace",
-        align: "right"
+        strings: ["04:17:26 UTC"],
+        color: "#c8d4e4",
+        font: "600 20px 'SF Mono', monospace",
+        align: "center"
       },
-      pulse: { amp: 0.2, period: 2400 },
       motion: { type: "static" },
       life: { enter: 200, fade: 600 }
     },
     {
-      key: "clock",
+      key: "status",
       count: 1,
-      position: { x: 0.06, y: 0.045 },
+      position: { x: 0.965, y: 0.052 },
       sprite: {
         kind: "text",
-        strings: ["21:47"],
-        color: "#8899aa",
-        font: "bold 12px monospace",
-        align: "left"
+        strings: ["\u25CF UPLINK LOCKED \xB7 WATCH C"],
+        color: "#46d17a",
+        font: "bold 11px 'SF Mono', monospace",
+        align: "right"
       },
+      pulse: { amp: 0.18, period: 2600 },
       motion: { type: "static" },
       life: { enter: 200, fade: 600 }
     },
-    // --- left column: readings (boots second) ---
+    // ---- left column: arrays (boots second) ----
     {
-      key: "power-label",
+      key: "dish1",
       count: 1,
-      position: { x: 0.06, y: 0.14 },
+      position: { x: 0.035, y: 0.148 },
       sprite: {
         kind: "text",
-        strings: ["POWER"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["DSA-1 EAST    AZ 214.6\xB0  EL 38.2\xB0"],
+        color: "#9fb2c8",
+        font: "11px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
@@ -2579,267 +2677,245 @@ var DASHBOARD_SPEC = {
       life: { enter: 700, fade: 600 }
     },
     {
-      key: "power-value",
-      count: 1,
-      position: { x: 0.06, y: 0.18 },
-      sprite: {
-        kind: "text",
-        strings: ["3.2 kW"],
-        color: "#ffd166",
-        font: "bold 26px monospace",
-        align: "left",
-        baseline: "top"
-      },
+      key: "dish1-bars",
+      count: 14,
+      sprite: { kind: "rect", width: [38e-4, 38e-4], aspect: [0.5, 2.6], color: "#2ee6c8" },
+      alpha: [0.3, 0.65],
+      layout: { type: "grid", columns: 14 },
+      region: { x: [0.035, 0.15], y: [0.183, 0.203] },
+      pulse: { amp: 0.42, period: 1500, wave: { wavelength: 0.09, angle: 0 } },
       motion: { type: "static" },
       life: { enter: 700, fade: 600 }
     },
     {
-      key: "network-label",
+      key: "dish2",
       count: 1,
-      position: { x: 0.06, y: 0.28 },
+      position: { x: 0.035, y: 0.243 },
       sprite: {
         kind: "text",
-        strings: ["NETWORK"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["DSA-2 WEST    AZ 097.1\xB0  EL 61.7\xB0"],
+        color: "#9fb2c8",
+        font: "11px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 700, fade: 600 }
+      life: { enter: 850, fade: 600 }
     },
     {
-      key: "network-value",
-      count: 1,
-      position: { x: 0.06, y: 0.32 },
-      sprite: {
-        kind: "text",
-        strings: ["940 Mb/s"],
-        color: "#44aaff",
-        font: "bold 26px monospace",
-        align: "left",
-        baseline: "top"
-      },
+      key: "dish2-bars",
+      count: 14,
+      sprite: { kind: "rect", width: [38e-4, 38e-4], aspect: [0.5, 2.2], color: "#44aaff" },
+      alpha: [0.3, 0.6],
+      layout: { type: "grid", columns: 14 },
+      region: { x: [0.035, 0.15], y: [0.278, 0.298] },
+      pulse: { amp: 0.4, period: 1900, wave: { wavelength: 0.11, angle: 0 } },
       motion: { type: "static" },
-      life: { enter: 700, fade: 600 }
+      life: { enter: 850, fade: 600 }
     },
     {
-      key: "climate-label",
+      key: "dish3",
       count: 1,
-      position: { x: 0.06, y: 0.42 },
+      position: { x: 0.035, y: 0.338 },
       sprite: {
         kind: "text",
-        strings: ["CLIMATE"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["DSA-3 POLAR   AZ 002.4\xB0  EL 12.9\xB0  \u25B3 WIND"],
+        color: "#5d7089",
+        font: "11px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 700, fade: 600 }
+      life: { enter: 1e3, fade: 600 }
     },
     {
-      key: "climate-value",
-      count: 1,
-      position: { x: 0.06, y: 0.46 },
-      sprite: {
-        kind: "text",
-        strings: ["21.5\xB0"],
-        color: "#44ddcc",
-        font: "bold 26px monospace",
-        align: "left",
-        baseline: "top"
-      },
+      key: "dish3-bars",
+      count: 14,
+      sprite: { kind: "rect", width: [38e-4, 38e-4], aspect: [0.4, 1.1], color: "#5d7089" },
+      alpha: [0.2, 0.4],
+      layout: { type: "grid", columns: 14 },
+      region: { x: [0.035, 0.15], y: [0.373, 0.393] },
+      pulse: { amp: 0.3, period: 2600, wave: { wavelength: 0.14, angle: 0 } },
       motion: { type: "static" },
-      life: { enter: 700, fade: 600 }
+      life: { enter: 1e3, fade: 600 }
     },
     {
-      key: "alerts-label",
+      key: "dish-leds",
+      count: 3,
+      sprite: { kind: "circle", radius: [4e-3, 4e-3], color: "#46d17a" },
+      alpha: [0.9, 0.9],
+      layout: { type: "grid", columns: 1 },
+      region: { x: [0.238, 0.246], y: [0.15, 0.35] },
+      pulse: { amp: 0.25, period: 2100 },
+      motion: { type: "static" },
+      life: { enter: 1e3, fade: 600 }
+    },
+    // carrier + doppler + station env
+    {
+      key: "carrier-wave",
+      count: 30,
+      sprite: { kind: "rect", width: [32e-4, 32e-4], aspect: [0.4, 3.6], color: "#2ee6c8" },
+      alpha: [0.25, 0.6],
+      layout: { type: "grid", columns: 30 },
+      region: { x: [0.035, 0.245], y: [0.47, 0.5] },
+      pulse: { amp: 0.5, period: 2100, wave: { wavelength: 0.16, angle: 0 } },
+      motion: { type: "static" },
+      life: { enter: 1150, fade: 600 }
+    },
+    {
+      key: "doppler",
       count: 1,
-      position: { x: 0.06, y: 0.56 },
+      position: { x: 0.035, y: 0.535 },
       sprite: {
         kind: "text",
-        strings: ["ALERTS"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["CARRIER X-BAND \xB7 DOPPLER +2.114 kHz \xB7 DRIFT 0.03"],
+        color: "#9fb2c8",
+        font: "10px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 700, fade: 600 }
+      life: { enter: 1150, fade: 600 }
     },
     {
-      key: "alerts-value",
+      key: "env-line",
       count: 1,
-      position: { x: 0.06, y: 0.6 },
+      position: { x: 0.035, y: 0.6 },
       sprite: {
         kind: "text",
-        strings: ["0"],
-        color: "#44cc66",
-        font: "bold 26px monospace",
+        strings: ["STATION \xB7 PWR 28.1 V \xB7 THERM 312 K \xB7 GYRO NOM \xB7 PROP 81%"],
+        color: "#5d7089",
+        font: "10px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 700, fade: 600 }
+      life: { enter: 1300, fade: 600 }
     },
-    // --- center: energy gauge (boots third) ---
+    // ---- center: the orbital plot (boots third) ----
     {
-      key: "gauge-ring",
+      key: "moon",
       count: 1,
-      position: { x: 0.4, y: 0.36 },
-      sprite: { kind: "ring", radius: [0.105, 0.105], color: "#1e3a52", width: 28e-4 },
-      alpha: [0.85, 0.85],
+      position: { x: 0.455, y: 0.4 },
+      sprite: { kind: "circle", radius: [0.028, 0.028], color: "#8fa3bd", soft: true },
+      alpha: [0.9, 0.9],
       motion: { type: "static" },
       life: { enter: 1200, fade: 700 }
     },
     {
-      key: "gauge-glow",
-      count: 1,
-      position: { x: 0.4, y: 0.36 },
-      sprite: { kind: "ring", radius: [0.088, 0.088], color: "#2ee6c8", width: 16e-4 },
+      key: "orbit-guides",
+      count: 3,
+      // All three guides pin to the plot centre; the seeded radius range
+      // spreads them into concentric orbits (`position` is count:1-only).
+      region: { x: [0.455, 0.455], y: [0.4, 0.4] },
+      sprite: { kind: "ring", radius: [0.075, 0.185], color: "#1e3a52", width: 11e-4 },
       alpha: [0.55, 0.55],
-      blend: "lighter",
-      pulse: { amp: 0.25, period: 4e3 },
-      grow: { amp: 0.05, period: 4e3 },
       motion: { type: "static" },
       life: { enter: 1200, fade: 700 }
     },
     {
-      key: "gauge-label",
-      count: 1,
-      position: { x: 0.4, y: 0.29 },
+      key: "fleet",
+      count: 5,
       sprite: {
-        kind: "text",
-        strings: ["ENERGY"],
-        color: "#445566",
-        font: "9px monospace",
-        align: "center"
-      },
-      motion: { type: "static" },
-      life: { enter: 1200, fade: 700 }
-    },
-    {
-      key: "gauge-value",
-      count: 1,
-      position: { x: 0.4, y: 0.375 },
-      sprite: {
-        kind: "text",
-        strings: ["73%"],
-        color: "#2ee6c8",
-        font: "bold 34px monospace",
-        align: "center"
-      },
-      motion: { type: "static" },
-      life: { enter: 1200, fade: 700 }
-    },
-    {
-      key: "equalizer",
-      count: 22,
-      sprite: {
-        kind: "rect",
-        width: [5e-3, 5e-3],
-        aspect: [0.6, 3.4],
+        kind: "circle",
+        radius: [45e-4, 65e-4],
         color: "#2ee6c8",
-        colors: ["#2ee6c8", "#44aaff", "#aa88ff"],
-        colorWeights: [3, 2, 1]
+        colors: ["#2ee6c8", "#44aaff", "#ffd166", "#aa88ff", "#ff9f43"]
       },
-      alpha: [0.35, 0.7],
-      layout: { type: "grid", columns: 22 },
-      region: { x: [0.28, 0.52], y: [0.585, 0.615] },
-      // Wave-phased pulse sweeps along the bars — reads as a live meter.
-      pulse: { amp: 0.4, period: 1600, wave: { wavelength: 0.1, angle: 0 } },
-      motion: { type: "static" },
-      life: { enter: 1200, fade: 700 }
+      alpha: [0.85, 0.95],
+      blend: "lighter",
+      motion: { type: "orbit", speed: [4, 11], radius: [0.075, 0.185], center: { x: 0.455, y: 0.4 } },
+      trail: { length: 9, fade: 0.75 },
+      // The relay web: each craft holds a comm chain to its neighbours.
+      links: { k: 2, maxDist: 0.5, color: "#2ee6c8", alpha: 0.2, width: 12e-4, mode: "chain" },
+      life: { enter: 1350, fade: 700 }
     },
-    // --- right column: agenda + devices (boots fourth) ---
     {
-      key: "agenda-label",
+      key: "fleet-legend",
       count: 1,
-      position: { x: 0.64, y: 0.14 },
+      position: { x: 0.455, y: 0.63 },
       sprite: {
         kind: "text",
-        strings: ["AGENDA"],
-        color: "#445566",
-        font: "9px monospace",
-        align: "left",
+        strings: ["TRACKING 5 \xB7 KESTREL  TIDE-2  LIMELIGHT  CATWALK-1  SLIPSTREAM"],
+        color: "#5d7089",
+        font: "9px 'SF Mono', monospace",
+        align: "center",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1500, fade: 700 }
     },
+    // pass schedule under the plot
     {
-      key: "agenda-1",
+      key: "pass-label",
       count: 1,
-      position: { x: 0.64, y: 0.19 },
+      position: { x: 0.3, y: 0.69 },
       sprite: {
         kind: "text",
-        strings: ["09:00  Standup"],
-        color: "#8899aa",
-        font: "11px monospace",
+        strings: ["PASS SCHEDULE"],
+        color: "#41536b",
+        font: "9px 'SF Mono', monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 0.2593
+        baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1650, fade: 600 }
     },
     {
-      key: "agenda-2",
+      key: "pass-1",
       count: 1,
-      position: { x: 0.64, y: 0.23 },
+      position: { x: 0.3, y: 0.72 },
       sprite: {
         kind: "text",
-        strings: ["12:30  Lunch w/ Kai"],
-        color: "#778899",
-        font: "11px monospace",
+        strings: ["04:41  CATWALK-1   ACQUIRE \xB7 DSA-1     \u25B2 12 MIN"],
+        color: "#c8d4e4",
+        font: "11px 'SF Mono', monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 0.2593
+        baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1650, fade: 600 }
     },
     {
-      key: "agenda-3",
+      key: "pass-2",
       count: 1,
-      position: { x: 0.64, y: 0.27 },
+      position: { x: 0.3, y: 0.757 },
       sprite: {
         kind: "text",
-        strings: ["18:00  Gym"],
-        color: "#667788",
-        font: "11px monospace",
+        strings: ["05:03  TIDE-2      OCCULT EXIT \xB7 DSA-2"],
+        color: "#7f93ab",
+        font: "11px 'SF Mono', monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 0.2593
+        baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1750, fade: 600 }
     },
     {
-      key: "devices-label",
+      key: "pass-3",
       count: 1,
-      position: { x: 0.64, y: 0.36 },
+      position: { x: 0.3, y: 0.794 },
       sprite: {
         kind: "text",
-        strings: ["DEVICES"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["05:47  KESTREL     RANGING \xB7 DSA-1+2"],
+        color: "#7f93ab",
+        font: "11px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1850, fade: 600 }
     },
+    // ---- right column: telemetry (boots fourth) ----
     {
-      key: "devices-1",
+      key: "signal-label",
       count: 1,
-      position: { x: 0.64, y: 0.41 },
+      position: { x: 0.665, y: 0.115 },
       sprite: {
         kind: "text",
-        strings: ["Lights      6 on"],
-        color: "#8899aa",
-        font: "11px monospace",
+        strings: ["PRIMARY CARRIER \xB7 CATWALK-1"],
+        color: "#41536b",
+        font: "9px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
@@ -2847,14 +2923,14 @@ var DASHBOARD_SPEC = {
       life: { enter: 1700, fade: 600 }
     },
     {
-      key: "devices-2",
+      key: "signal-value",
       count: 1,
-      position: { x: 0.64, y: 0.45 },
+      position: { x: 0.665, y: 0.14 },
       sprite: {
         kind: "text",
-        strings: ["Thermostat  eco"],
-        color: "#778899",
-        font: "11px monospace",
+        strings: ["-112.4 dBm"],
+        color: "#ffd166",
+        font: "bold 30px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
@@ -2862,130 +2938,130 @@ var DASHBOARD_SPEC = {
       life: { enter: 1700, fade: 600 }
     },
     {
-      key: "devices-3",
+      key: "telemetry-row",
       count: 1,
-      position: { x: 0.64, y: 0.49 },
+      position: { x: 0.665, y: 0.215 },
       sprite: {
         kind: "text",
-        strings: ["Locks       secured"],
-        color: "#667788",
-        font: "11px monospace",
+        strings: ["RANGE 1.28 LS   DOWNLINK 2.048 Mb/s   BUFFER 38%"],
+        color: "#9fb2c8",
+        font: "11px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1800, fade: 600 }
     },
+    // event log
     {
-      key: "devices-4",
+      key: "feed-1",
       count: 1,
-      position: { x: 0.64, y: 0.53 },
+      position: { x: 0.665, y: 0.3 },
       sprite: {
         kind: "text",
-        strings: ["Media       paused"],
-        color: "#556677",
-        font: "11px monospace",
+        strings: ["04:15:02  DSA-1 LOCK RE-ACQUIRED"],
+        color: "#9fb2c8",
+        font: "10px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 1700, fade: 600 }
+      life: { enter: 1950, fade: 600 }
     },
-    // --- bottom: activity feed (boots last) ---
     {
-      key: "feed-label",
+      key: "feed-2",
       count: 1,
-      position: { x: 0.06, y: 0.74 },
+      position: { x: 0.665, y: 0.334 },
       sprite: {
         kind: "text",
-        strings: ["ACTIVITY"],
-        color: "#445566",
-        font: "9px monospace",
+        strings: ["04:12:47  CATWALK-1 WHEEL DESAT OK"],
+        color: "#7f93ab",
+        font: "10px 'SF Mono', monospace",
         align: "left",
         baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 2200, fade: 600 }
+      life: { enter: 2050, fade: 600 }
     },
     {
-      key: "feed-1",
+      key: "feed-3",
       count: 1,
-      position: { x: 0.06, y: 0.78 },
+      position: { x: 0.665, y: 0.368 },
       sprite: {
         kind: "text",
-        strings: ["21:42  Front door locked"],
-        color: "#7a8a7a",
-        font: "10px monospace",
+        strings: ["04:09:31  RANGING RESIDUAL 0.4 m"],
+        color: "#5d7089",
+        font: "10px 'SF Mono', monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 0.5556
+        baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 2200, fade: 600 }
+      life: { enter: 2150, fade: 600 }
     },
+    // alert + relay load
     {
-      key: "feed-2",
+      key: "alert",
       count: 1,
-      position: { x: 0.06, y: 0.82 },
+      position: { x: 0.665, y: 0.49 },
       sprite: {
         kind: "text",
-        strings: ["21:36  Thermostat \u2192 eco"],
-        color: "#6a7a6a",
-        font: "10px monospace",
+        strings: ["\u25B3 SOLAR FLUX ELEVATED \u2014 MONITORING"],
+        color: "#ff9f43",
+        font: "bold 11px 'SF Mono', monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 0.5556
+        baseline: "top"
       },
+      pulse: { amp: 0.22, period: 3400 },
       motion: { type: "static" },
-      life: { enter: 2200, fade: 600 }
+      life: { enter: 2450, fade: 600 }
     },
     {
-      key: "feed-3",
-      count: 1,
-      position: { x: 0.06, y: 0.86 },
+      key: "load-bars",
+      count: 24,
       sprite: {
-        kind: "text",
-        strings: ["21:14  Backup completed"],
-        color: "#5a6a5a",
-        font: "10px monospace",
-        align: "left",
-        baseline: "top",
-        maxWidth: 0.5556
+        kind: "rect",
+        width: [42e-4, 42e-4],
+        aspect: [0.5, 3.2],
+        color: "#aa88ff",
+        colors: ["#aa88ff", "#44aaff", "#2ee6c8"],
+        colorWeights: [2, 2, 3]
       },
+      alpha: [0.3, 0.65],
+      layout: { type: "grid", columns: 24 },
+      region: { x: [0.665, 0.965], y: [0.58, 0.615] },
+      pulse: { amp: 0.45, period: 1800, wave: { wavelength: 0.12, angle: 0 } },
       motion: { type: "static" },
-      life: { enter: 2200, fade: 600 }
+      life: { enter: 2550, fade: 600 }
     },
     {
-      key: "feed-4",
+      key: "load-note",
       count: 1,
-      position: { x: 0.06, y: 0.9 },
+      position: { x: 0.665, y: 0.65 },
       sprite: {
         kind: "text",
-        strings: ["20:58  Motion \xB7 driveway"],
-        color: "#4d5e4d",
-        font: "10px monospace",
+        strings: ["RELAY LOAD \xB7 QUEUE 14 FRAMES \xB7 NOMINAL"],
+        color: "#5d7089",
+        font: "10px 'SF Mono', monospace",
         align: "left",
-        baseline: "top",
-        maxWidth: 0.5556
+        baseline: "top"
       },
       motion: { type: "static" },
-      life: { enter: 2200, fade: 600 }
+      life: { enter: 2550, fade: 600 }
     },
+    // ---- footer band ----
     {
-      key: "feed-5",
+      key: "footer",
       count: 1,
-      position: { x: 0.06, y: 0.94 },
+      position: { x: 0.035, y: 0.95 },
       sprite: {
         kind: "text",
-        strings: ["20:41  Sunset scene on"],
-        color: "#3d4e3d",
-        font: "10px monospace",
-        align: "left",
-        baseline: "top",
-        maxWidth: 0.5556
+        strings: ["NET STATE GREEN \xB7 3 ARRAYS \xB7 5 CARRIERS \xB7 DSN HANDOVER 23:34 \xB7 NEXT WINDOW 04:41:00"],
+        color: "#41536b",
+        font: "9px 'SF Mono', monospace",
+        align: "left"
       },
       motion: { type: "static" },
-      life: { enter: 2200, fade: 600 }
+      life: { enter: 2750, fade: 600 }
     }
   ]
 };
@@ -3123,6 +3199,120 @@ var MATRIX_RAIN_SPEC = {
   ]
 };
 
+// src/examples/nostalghia-candle.ts
+var NOSTALGHIA_CANDLE_SPEC = {
+  schemaVersion: 1,
+  id: "nostalghia-candle",
+  label: "Nostalghia's Candle",
+  seed: 1983,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#050302" },
+      { at: 0.55, color: "#0a0704" },
+      { at: 1, color: "#120c08" }
+    ]
+  },
+  layers: [
+    {
+      key: "halo",
+      count: 1,
+      position: { x: 0.5, y: 0.52 },
+      sprite: {
+        kind: "circle",
+        radius: [0.11, 0.11],
+        color: "#c4782a",
+        soft: true
+      },
+      // Base 0.04 + amp 0.02 → breathes ~0.02..0.06; never clamps to 0.
+      // (pulse.amp is ADDED to alpha, not multiplied.) Kept subordinate to the flame.
+      alpha: [0.04, 0.04],
+      blend: "lighter",
+      pulse: { amp: 0.02, period: 1e4 },
+      grow: { amp: 0.08, period: 1e4 },
+      motion: { type: "static" }
+    },
+    {
+      key: "smoke",
+      count: 3,
+      sprite: {
+        kind: "circle",
+        radius: [0.01, 0.022],
+        color: "#6a6258",
+        soft: true
+      },
+      alpha: [0.02, 0.04],
+      blend: "lighter",
+      region: { x: [0.46, 0.54], y: [0.36, 0.48] },
+      pulse: { amp: 0.015, period: 4500 },
+      motion: { type: "rise", speed: [2e-3, 4e-3], sway: 8e-3 }
+    },
+    {
+      key: "flame-glow",
+      count: 1,
+      sprite: {
+        kind: "circle",
+        radius: [0.028, 0.028],
+        color: "#ffb040",
+        soft: true
+      },
+      alpha: [0.32, 0.32],
+      blend: "lighter",
+      pulse: { amp: 0.12, period: 1400 },
+      grow: { amp: 0.4, period: 1600 },
+      // Tiny orbit = positional lean without drifting off-center (wander has vx).
+      motion: {
+        type: "orbit",
+        speed: [18, 18],
+        radius: [3e-3, 3e-3],
+        center: { x: 0.5, y: 0.52 }
+      }
+    },
+    {
+      key: "flame-core",
+      count: 1,
+      sprite: {
+        kind: "circle",
+        radius: [0.014, 0.014],
+        color: "#fff6e0",
+        soft: true
+      },
+      alpha: [0.95, 0.95],
+      blend: "lighter",
+      pulse: { amp: 0.25, period: 900 },
+      grow: { amp: 0.55, period: 1100 },
+      motion: {
+        type: "orbit",
+        speed: [22, 22],
+        radius: [25e-4, 25e-4],
+        center: { x: 0.5, y: 0.52 }
+      }
+    },
+    {
+      key: "embers",
+      count: 7,
+      sprite: {
+        kind: "circle",
+        radius: [18e-4, 4e-3],
+        color: "#e08a34",
+        soft: true
+      },
+      alpha: [0.4, 0.8],
+      blend: "lighter",
+      region: { x: [0.35, 0.65], y: [0.4, 0.7] },
+      pulse: { amp: 0.2, period: 2200 },
+      trail: { length: 2200, fade: 1 },
+      motion: {
+        type: "drift",
+        speed: [4e-3, 0.012],
+        angle: 270,
+        bob: 8e-3
+      }
+    }
+  ]
+};
+
 // src/examples/polygons.ts
 var POLYGONS_SPEC = {
   schemaVersion: 1,
@@ -3568,7 +3758,8 @@ var SCHEMA_EXAMPLES = [
   { id: "warp-tunnel", label: "Warp Tunnel", spec: WARP_TUNNEL_SPEC },
   { id: "polygons", label: "Polygons", spec: POLYGONS_SPEC },
   { id: "matrix-rain", label: "Matrix Rain", spec: MATRIX_RAIN_SPEC },
-  { id: "procession", label: "Night Procession", spec: PROCESSION_SPEC }
+  { id: "procession", label: "Night Procession", spec: PROCESSION_SPEC },
+  { id: "nostalghia-candle", label: "Nostalghia's Candle", spec: NOSTALGHIA_CANDLE_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -3585,6 +3776,7 @@ export {
   LANTERNS_SPEC,
   LIMITS,
   MATRIX_RAIN_SPEC,
+  NOSTALGHIA_CANDLE_SPEC,
   ORRERY_SPEC,
   POLYGONS_SPEC,
   PROCESSION_SPEC,
@@ -3616,6 +3808,7 @@ export {
   perceiveScene,
   positionAt,
   renderBrailleMap,
+  renderDensityMap,
   resolveSpecPath,
   rotationAt,
   sizeAt,
@@ -3623,6 +3816,7 @@ export {
   spriteVariants,
   steerablePaths,
   structuralSignature,
+  textSprites,
   validateSpec
 };
 //# sourceMappingURL=index.js.map