@idle-screens/schema 2.0.0 → 2.1.0

package/dist/index.js

@@ -8,8 +8,20 @@ var LIMITS = {
   // px/sec — bounds motion so nothing teleports
   maxPulseAmp: 0.5,
   // opacity breathing amplitude cap
-  minPulsePeriod: 500
+  minPulsePeriod: 500,
   // ms — caps pulse at 2 Hz (WCAG flash threshold is 3 Hz)
+  maxSpin: 360,
+  // degrees/sec — one full revolution per second
+  maxGrowAmp: 0.8,
+  // size breathing amplitude cap (fraction of base size)
+  maxOrbitSpeed: 180,
+  // degrees/sec — half a revolution per second
+  maxLinksK: 8,
+  maxLinkLayerCount: 200,
+  minCyclePeriod: 500,
+  // ms — same flash-safety floor as pulse
+  referenceViewport: 1080
+  // for validating viewport-unit dimensional caps
 };
 
 // src/validate.ts
@@ -29,6 +41,9 @@ function validateSpec(spec) {
   if (spec.motionIntensity !== void 0 && !["calm", "moderate", "energetic"].includes(spec.motionIntensity)) {
     err("motionIntensity", "must be calm | moderate | energetic");
   }
+  if (spec.units !== void 0 && spec.units !== "px" && spec.units !== "viewport") {
+    err("units", "must be 'px' | 'viewport'");
+  }
   if (spec.background !== void 0) validateBackground(spec.background, err);
   if (!Array.isArray(spec.layers) || spec.layers.length === 0) {
     err("layers", "must be a non-empty array");
@@ -37,7 +52,7 @@ function validateSpec(spec) {
     let total = 0;
     spec.layers.forEach((layer, i) => {
       total += isObj(layer) && isNum(layer.count) ? layer.count : 0;
-      validateLayer(layer, `layers[${i}]`, err);
+      validateLayer(layer, `layers[${i}]`, err, spec);
     });
     if (total > LIMITS.maxTotal) err("layers", `total entities ${total} exceeds cap ${LIMITS.maxTotal}`);
   }
@@ -70,7 +85,7 @@ function validateBackground(bg, err) {
     err("background.type", "must be solid | gradient");
   }
 }
-function validateLayer(layer, path, err) {
+function validateLayer(layer, path, err, spec) {
   if (!isObj(layer)) return err(path, "must be an object");
   if (!isNum(layer.count) || !Number.isInteger(layer.count) || layer.count < 1) {
     err(`${path}.count`, "must be a positive integer");
@@ -120,8 +135,44 @@ function validateLayer(layer, path, err) {
       }
     }
   }
+  if (layer.spin !== void 0) {
+    if (!isNum(layer.spin)) err(`${path}.spin`, "must be a number (degrees/sec)");
+    else if (Math.abs(layer.spin) > LIMITS.maxSpin) err(`${path}.spin`, `must be within \xB1${LIMITS.maxSpin} deg/sec`);
+  }
+  if (layer.grow !== void 0) {
+    if (!isObj(layer.grow)) err(`${path}.grow`, "must be an object");
+    else {
+      if (!isNum(layer.grow.amp) || layer.grow.amp <= 0 || layer.grow.amp > LIMITS.maxGrowAmp) {
+        err(`${path}.grow.amp`, `must be within 0..${LIMITS.maxGrowAmp}`);
+      }
+      if (!isNum(layer.grow.period) || layer.grow.period < LIMITS.minPulsePeriod) {
+        err(`${path}.grow.period`, `must be >= ${LIMITS.minPulsePeriod} ms (flash-safety floor)`);
+      }
+    }
+  }
+  if (layer.links !== void 0) {
+    if (!isObj(layer.links)) err(`${path}.links`, "must be an object");
+    else {
+      if (!isNum(layer.links.k) || !Number.isInteger(layer.links.k) || layer.links.k < 1 || layer.links.k > LIMITS.maxLinksK) {
+        err(`${path}.links.k`, `must be an integer 1..${LIMITS.maxLinksK}`);
+      }
+      if (!isNum(layer.links.maxDist) || layer.links.maxDist <= 0) {
+        err(`${path}.links.maxDist`, "must be > 0");
+      }
+      if (layer.links.color !== void 0) color(layer.links.color, `${path}.links.color`, err);
+      if (layer.links.alpha !== void 0 && (!isNum(layer.links.alpha) || layer.links.alpha < 0 || layer.links.alpha > 1)) {
+        err(`${path}.links.alpha`, "must be 0..1");
+      }
+      if (layer.links.width !== void 0 && (!isNum(layer.links.width) || layer.links.width <= 0)) {
+        err(`${path}.links.width`, "must be > 0");
+      }
+      if (isNum(layer.count) && layer.count > LIMITS.maxLinkLayerCount) {
+        err(`${path}.links`, `layer count must be <= ${LIMITS.maxLinkLayerCount} when links is set`);
+      }
+    }
+  }
   validateSprite(layer.sprite, `${path}.sprite`, err);
-  validateMotion(layer.motion, `${path}.motion`, err);
+  validateMotion(layer.motion, `${path}.motion`, err, spec);
 }
 function validateSprite(sprite, path, err) {
   if (!isObj(sprite)) return err(path, "must be an object");
@@ -129,6 +180,7 @@ function validateSprite(sprite, path, err) {
     if (!Array.isArray(sprite.glyphs) || sprite.glyphs.length === 0 || !sprite.glyphs.every(isStr)) {
       err(`${path}.glyphs`, "must be a non-empty array of strings");
     }
+    validateCycle(sprite, path, err);
   } else if (sprite.kind === "text") {
     if (!Array.isArray(sprite.strings) || sprite.strings.length === 0 || !sprite.strings.every(isStr)) {
       err(`${path}.strings`, "must be a non-empty array of strings");
@@ -143,19 +195,36 @@ function validateSprite(sprite, path, err) {
     if (sprite.maxWidth !== void 0 && (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0)) {
       err(`${path}.maxWidth`, "must be a positive number");
     }
+    validateCycle(sprite, path, err);
   } else if (sprite.kind === "circle") {
     if (!isRange(sprite.radius) || sprite.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
     color(sprite.color, `${path}.color`, err);
     if (sprite.soft !== void 0 && typeof sprite.soft !== "boolean") err(`${path}.soft`, "must be a boolean");
+    if (sprite.colors !== void 0) {
+      if (!Array.isArray(sprite.colors) || sprite.colors.length === 0) {
+        err(`${path}.colors`, "must be a non-empty array of hex colours");
+      } else {
+        sprite.colors.forEach((c, ci) => color(c, `${path}.colors[${ci}]`, err));
+      }
+    }
   } else {
     err(`${path}.kind`, "must be emoji | text | circle");
   }
 }
-function validateMotion(motion, path, err) {
+function validateCycle(sprite, path, err) {
+  if (sprite.cycle === void 0) return;
+  if (!isObj(sprite.cycle)) return err(`${path}.cycle`, "must be an object");
+  if (!isNum(sprite.cycle.period) || sprite.cycle.period < LIMITS.minCyclePeriod) {
+    err(`${path}.cycle.period`, `must be >= ${LIMITS.minCyclePeriod} ms (flash-safety floor)`);
+  }
+}
+function validateMotion(motion, path, err, spec) {
   if (!isObj(motion)) return err(path, "must be an object");
+  const isViewport = isObj(spec) && spec.units === "viewport";
+  const speedCap = isViewport ? LIMITS.maxSpeed / LIMITS.referenceViewport : LIMITS.maxSpeed;
   const speedOk = (v, p) => {
     if (!isRange(v)) err(p, "must be a [min,max] range");
-    else if (v[1] > LIMITS.maxSpeed) err(p, `speed exceeds cap ${LIMITS.maxSpeed} px/sec`);
+    else if (v[1] > speedCap) err(p, `speed exceeds cap ${isViewport ? speedCap.toFixed(2) + " viewport-units/sec" : LIMITS.maxSpeed + " px/sec"}`);
   };
   if (motion.type === "drift") {
     speedOk(motion.speed, `${path}.speed`);
@@ -168,8 +237,20 @@ function validateMotion(motion, path, err) {
   } else if (motion.type === "bounce") {
     speedOk(motion.speed, `${path}.speed`);
   } else if (motion.type === "static") {
+  } else if (motion.type === "orbit") {
+    if (!isRange(motion.speed)) err(`${path}.speed`, "must be a [min,max] range");
+    else if (Math.abs(motion.speed[0]) > LIMITS.maxOrbitSpeed || Math.abs(motion.speed[1]) > LIMITS.maxOrbitSpeed) err(`${path}.speed`, `orbit speed exceeds cap ${LIMITS.maxOrbitSpeed} deg/sec`);
+    if (!isRange(motion.radius) || motion.radius[0] <= 0) err(`${path}.radius`, "must be a [min,max] range of positive px");
+    if (motion.center !== void 0) {
+      if (!isObj(motion.center) || !isNum(motion.center.x) || !isNum(motion.center.y)) {
+        err(`${path}.center`, "must be {x, y} with numbers 0..1");
+      } else {
+        if (motion.center.x < 0 || motion.center.x > 1) err(`${path}.center.x`, "must be 0..1");
+        if (motion.center.y < 0 || motion.center.y > 1) err(`${path}.center.y`, "must be 0..1");
+      }
+    }
   } else {
-    err(`${path}.type`, "must be drift | rise | bounce | static");
+    err(`${path}.type`, "must be drift | rise | bounce | static | orbit");
   }
 }
 function assertValidSpec(spec) {
@@ -187,12 +268,14 @@ function spriteVariants(sprite) {
   if (sprite.kind === "text") return sprite.strings.length;
   return 1;
 }
-function buildEntities(layer, rng, w, h) {
+function buildEntities(layer, rng, w, h, scale = 1) {
   const [smin, smax] = layer.size ?? [20, 40];
   const variants = spriteVariants(layer.sprite);
+  const colorsLen = layer.sprite.kind === "circle" && layer.sprite.colors ? layer.sprite.colors.length : 0;
+  const cycle = layer.sprite.kind === "emoji" || layer.sprite.kind === "text" ? layer.sprite.cycle : void 0;
   const out = [];
   for (let i = 0; i < layer.count; i++) {
-    const size = layer.sprite.kind === "circle" ? rng.range(layer.sprite.radius[0], layer.sprite.radius[1]) * 2 : rng.range(smin, smax);
+    const size = layer.sprite.kind === "circle" ? rng.range(layer.sprite.radius[0], layer.sprite.radius[1]) * 2 * scale : rng.range(smin, smax) * scale;
     let vx = 0;
     let vy = 0;
     let bob = 0;
@@ -201,22 +284,25 @@ function buildEntities(layer, rng, w, h) {
     if (m.type === "static") {
       motion = "static";
     } else if (m.type === "drift") {
-      const s = rng.range(m.speed[0], m.speed[1]);
+      const s = rng.range(m.speed[0], m.speed[1]) * scale;
       let angle = (m.angle ?? 0) * Math.PI / 180;
       if (m.bidirectional && rng.next() < 0.5) angle = Math.PI - angle;
       vx = s * Math.cos(angle);
       vy = s * Math.sin(angle);
-      bob = m.bob ?? 0;
+      bob = (m.bob ?? 0) * scale;
     } else if (m.type === "rise") {
       motion = "rise";
-      vy = -rng.range(m.speed[0], m.speed[1]);
-      bob = m.sway ?? 0;
-    } else {
+      vy = -rng.range(m.speed[0], m.speed[1]) * scale;
+      bob = (m.sway ?? 0) * scale;
+    } else if (m.type === "bounce") {
       motion = "bounce";
-      const s = rng.range(m.speed[0], m.speed[1]);
+      const s = rng.range(m.speed[0], m.speed[1]) * scale;
       const a = rng.range(0, Math.PI * 2);
       vx = s * Math.cos(a);
       vy = s * Math.sin(a);
+    } else if (m.type === "orbit") {
+      motion = "orbit";
+      vx = rng.range(m.speed[0], m.speed[1]);
     }
     let x0;
     let y0;
@@ -243,7 +329,20 @@ function buildEntities(layer, rng, w, h) {
       alpha: layer.alpha ? rng.range(layer.alpha[0], layer.alpha[1]) : 1,
       pulseAmp: layer.pulse?.amp ?? 0,
       pulsePeriod: layer.pulse?.period ?? 1e3,
-      pulsePhase: layer.pulse ? rng.range(0, Math.PI * 2) : 0
+      pulsePhase: layer.pulse ? rng.range(0, Math.PI * 2) : 0,
+      // New draws AFTER pulsePhase — guarded so existing specs keep identical streams.
+      spinSpeed: layer.spin ? layer.spin * Math.PI / 180 : 0,
+      // deg/sec → rad/sec
+      spinPhase: layer.spin ? rng.range(0, Math.PI * 2) : 0,
+      growAmp: layer.grow?.amp ?? 0,
+      growPeriod: layer.grow?.period ?? 1e3,
+      growPhase: layer.grow ? rng.range(0, Math.PI * 2) : 0,
+      orbitR: m.type === "orbit" ? rng.range(m.radius[0], m.radius[1]) * scale : 0,
+      orbitCx: m.type === "orbit" ? (m.center?.x ?? 0.5) * w : 0,
+      orbitCy: m.type === "orbit" ? (m.center?.y ?? 0.5) * h : 0,
+      // New draws AFTER orbit — guarded so existing specs keep identical streams.
+      colorIndex: colorsLen > 0 ? rng.int(0, colorsLen - 1) : -1,
+      cyclePeriod: cycle ? cycle.period : 0
     });
   }
   return out;
@@ -253,6 +352,15 @@ function alphaAt(e, t) {
   const a = e.alpha + e.pulseAmp * Math.sin(t * 2 * Math.PI / e.pulsePeriod + e.pulsePhase);
   return a < 0 ? 0 : a > 1 ? 1 : a;
 }
+function sizeAt(e, t) {
+  if (!e.growAmp) return e.size;
+  const s = e.size * (1 + e.growAmp * Math.sin(t * 2 * Math.PI / e.growPeriod + e.growPhase));
+  return s > 0 ? s : 0.1;
+}
+function rotationAt(e, t) {
+  if (!e.spinSpeed) return 0;
+  return e.spinPhase + e.spinSpeed * (t / 1e3);
+}
 function wrap(v, min, max) {
   const range = max - min;
   return ((v - min) % range + range) % range + min;
@@ -266,6 +374,14 @@ function reflect(v, min, max) {
 }
 function positionAt(e, t, w, h) {
   if (e.motion === "static") return { x: e.x0, y: e.y0, flip: false };
+  if (e.motion === "orbit") {
+    const angle = e.phase + e.vx * Math.PI / 180 * (t / 1e3);
+    return {
+      x: e.orbitCx + e.orbitR * Math.cos(angle),
+      y: e.orbitCy + e.orbitR * Math.sin(angle),
+      flip: false
+    };
+  }
   const dt = t / 1e3;
   const m = e.size;
   if (e.motion === "bounce") {
@@ -287,6 +403,43 @@ function positionAt(e, t, w, h) {
   if (e.bob) y += e.bob * Math.sin(t / 500 + e.phase);
   return { x, y, flip: e.headingLeft };
 }
+function spriteIndexAt(e, t, variants) {
+  if (!e.cyclePeriod || variants <= 1) return e.spriteIndex;
+  return Math.floor(t / e.cyclePeriod + e.phase / (2 * Math.PI)) % variants;
+}
+function linkPairs(positions, k, maxDist, doWrap, w, h) {
+  const n = positions.length;
+  const edges = /* @__PURE__ */ new Set();
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const pi = positions[i];
+    const neighbors = [];
+    for (let j = 0; j < n; j++) {
+      if (i === j) continue;
+      const pj = positions[j];
+      let dx = pj.x - pi.x;
+      let dy = pj.y - pi.y;
+      if (doWrap) {
+        if (Math.abs(dx) > w / 2) dx = dx > 0 ? dx - w : dx + w;
+        if (Math.abs(dy) > h / 2) dy = dy > 0 ? dy - h : dy + h;
+      }
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      if (dist <= maxDist) neighbors.push({ dist, j });
+    }
+    neighbors.sort((a, b) => a.dist - b.dist || a.j - b.j);
+    for (let ni = 0; ni < Math.min(k, neighbors.length); ni++) {
+      const j = neighbors[ni].j;
+      const lo = Math.min(i, j);
+      const hi = Math.max(i, j);
+      const key = `${lo}:${hi}`;
+      if (!edges.has(key)) {
+        edges.add(key);
+        out.push([lo, hi]);
+      }
+    }
+  }
+  return out;
+}
 
 // src/compile.ts
 import {
@@ -365,7 +518,8 @@ function easeSmooth(k) {
   return c * c * (3 - 2 * c);
 }
 function structuralSignature(spec) {
-  return JSON.stringify(
+  return JSON.stringify([
+    spec.units,
     spec.layers.map((l) => [
       l.count,
       l.size,
@@ -376,11 +530,14 @@ function structuralSignature(spec) {
       l.flip,
       l.alpha,
       l.pulse,
+      l.spin,
+      l.grow,
       l.sprite.kind,
       l.sprite.kind === "circle" ? l.sprite.radius : void 0,
-      l.sprite.kind === "emoji" ? l.sprite.glyphs.length : l.sprite.kind === "text" ? l.sprite.strings.length : void 0
+      l.sprite.kind === "circle" ? l.sprite.colors?.length : void 0,
+      l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : void 0
     ])
-  );
+  ]);
 }
 
 // src/compile.ts
@@ -463,7 +620,8 @@ var SpecInstance = class {
   /** (Re)seed and place all entities — deterministic for the seed + size. */
   rebuild() {
     const rng = createRng(this.seed);
-    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h) }));
+    const scale = this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1;
+    this.layers = this.effSpec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, this.w, this.h, scale) }));
     this.lastStructural = structuralSignature(this.effSpec);
   }
   start() {
@@ -498,45 +656,60 @@ var SpecInstance = class {
     ctx.fillRect(0, 0, w, h);
     if (bg.band) {
       ctx.fillStyle = bg.band.color;
-      ctx.fillRect(0, h - bg.band.height, w, bg.band.height);
+      const bh = bg.band.height * (this.effSpec.units === "viewport" ? Math.min(w, h) : 1);
+      ctx.fillRect(0, h - bh, w, bh);
     }
   }
   drawEntity(built, e, t) {
     const { ctx } = this;
     const p = positionAt(e, t, this.w, this.h);
     const sprite = built.layer.sprite;
+    const sz = sizeAt(e, t);
+    const rot = rotationAt(e, t);
     ctx.globalAlpha = alphaAt(e, t);
     if (sprite.kind === "circle") {
-      const r = e.size / 2;
+      const r = sz / 2;
+      const resolvedColor = sprite.colors?.[e.colorIndex] ?? sprite.color;
+      ctx.save();
+      if (rot) {
+        ctx.translate(p.x, p.y);
+        ctx.rotate(rot);
+        ctx.translate(-p.x, -p.y);
+      }
       if (sprite.soft) {
         const g = ctx.createRadialGradient(p.x, p.y, 0, p.x, p.y, r);
-        g.addColorStop(0, sprite.color);
-        g.addColorStop(0.35, hexToRgba(sprite.color, 0.75));
-        g.addColorStop(1, hexToRgba(sprite.color, 0));
+        g.addColorStop(0, resolvedColor);
+        g.addColorStop(0.35, hexToRgba(resolvedColor, 0.75));
+        g.addColorStop(1, hexToRgba(resolvedColor, 0));
         ctx.fillStyle = g;
       } else {
-        ctx.fillStyle = sprite.color;
+        ctx.fillStyle = resolvedColor;
       }
       ctx.beginPath();
       ctx.arc(p.x, p.y, r, 0, Math.PI * 2);
       ctx.fill();
+      ctx.restore();
       return;
     }
     ctx.save();
     ctx.translate(p.x, p.y);
+    if (rot) ctx.rotate(rot);
     if (p.flip && built.layer.flip) ctx.scale(-1, 1);
     ctx.textAlign = "center";
     ctx.textBaseline = "middle";
     if (sprite.kind === "emoji") {
-      ctx.font = `${e.size}px serif`;
-      ctx.fillText(sprite.glyphs[e.spriteIndex] ?? sprite.glyphs[0], 0, 0);
+      const idx = spriteIndexAt(e, t, sprite.glyphs.length);
+      ctx.font = `${sz}px serif`;
+      ctx.fillText(sprite.glyphs[idx] ?? sprite.glyphs[0], 0, 0);
     } else {
       ctx.textAlign = sprite.align ?? "center";
       ctx.textBaseline = sprite.baseline ?? "middle";
-      ctx.font = sprite.font ?? `${e.size}px system-ui, sans-serif`;
+      ctx.font = sprite.font ?? `${sz}px system-ui, sans-serif`;
       ctx.fillStyle = sprite.color ?? "#e6e8ef";
-      const text = sprite.strings[e.spriteIndex] ?? sprite.strings[0];
-      if (sprite.maxWidth) ctx.fillText(text, 0, 0, sprite.maxWidth);
+      const idx = spriteIndexAt(e, t, sprite.strings.length);
+      const text = sprite.strings[idx] ?? sprite.strings[0];
+      const mw = sprite.maxWidth ? sprite.maxWidth * (this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1) : void 0;
+      if (mw) ctx.fillText(text, 0, 0, mw);
       else ctx.fillText(text, 0, 0);
     }
     ctx.restore();
@@ -579,6 +752,39 @@ var SpecInstance = class {
       this.renderFrame(this.lastT, this.seed);
     }
   }
+  drawLinks(built, t) {
+    const { links } = built.layer;
+    if (!links) return;
+    const { ctx } = this;
+    const wrap2 = built.layer.wrap !== false;
+    const positions = built.entities.map((e) => positionAt(e, t, this.w, this.h));
+    const pairs = linkPairs(positions, links.k, links.maxDist * (this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1), wrap2, this.w, this.h);
+    const lw = (links.width ?? 1) * (this.effSpec.units === "viewport" ? Math.min(this.w, this.h) : 1);
+    ctx.lineWidth = lw;
+    for (const [i, j] of pairs) {
+      const pi = positions[i];
+      const pj = positions[j];
+      const ei = built.entities[i];
+      let resolvedColor = links.color;
+      if (!resolvedColor) {
+        const sprite = built.layer.sprite;
+        if (sprite.kind === "circle") resolvedColor = sprite.colors?.[ei.colorIndex] ?? sprite.color;
+        else resolvedColor = "#e6e8ef";
+      }
+      ctx.globalAlpha = links.alpha ?? alphaAt(ei, t);
+      ctx.strokeStyle = resolvedColor;
+      let dx = pj.x - pi.x;
+      let dy = pj.y - pi.y;
+      if (wrap2) {
+        if (Math.abs(dx) > this.w / 2) dx = dx > 0 ? dx - this.w : dx + this.w;
+        if (Math.abs(dy) > this.h / 2) dy = dy > 0 ? dy - this.h : dy + this.h;
+      }
+      ctx.beginPath();
+      ctx.moveTo(pi.x, pi.y);
+      ctx.lineTo(pi.x + dx, pi.y + dy);
+      ctx.stroke();
+    }
+  }
   /** Deterministic, frame-addressable render (shared by the rAF loop). */
   renderFrame(t, _seed) {
     this.stepTransition(t);
@@ -588,6 +794,7 @@ var SpecInstance = class {
     this.drawBackground();
     for (const built of this.layers) {
       ctx.globalCompositeOperation = built.layer.blend ?? "source-over";
+      this.drawLinks(built, t);
       for (const e of built.entities) this.drawEntity(built, e, t);
     }
     ctx.globalAlpha = 1;
@@ -623,6 +830,76 @@ function compileSaver(spec) {
   };
 }
 
+// src/advise.ts
+import { createRng as createRng2 } from "@idle-screens/core";
+function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
+  const warnings = [];
+  const w = viewport.width;
+  const h = viewport.height;
+  const scale = spec.units === "viewport" ? Math.min(w, h) : 1;
+  const rng = createRng2(spec.seed ?? 42);
+  const allEntities = spec.layers.map((l) => buildEntities(l, rng, w, h, scale));
+  let totalEntities = 0;
+  let textLayerCount = 0;
+  let motionLayerCount = 0;
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    const entities = allEntities[li];
+    totalEntities += entities.length;
+    const isText = layer.sprite.kind === "text";
+    const isEmoji = layer.sprite.kind === "emoji";
+    const isStaticText = isText && layer.motion.type === "static";
+    if (isStaticText) textLayerCount++;
+    if (layer.motion.type !== "static") motionLayerCount++;
+    if (layer.sprite.kind === "circle") {
+      const maxR = entities.reduce((m, e) => Math.max(m, e.size / 2), 0);
+      const maxAlpha = entities.reduce((m, e) => Math.max(m, e.alpha), 0);
+      if (maxR * maxAlpha < 0.05) {
+        warnings.push({
+          path: `layers[${li}]`,
+          code: "invisible-layer",
+          message: `layer's max visible radius (${maxR.toFixed(1)}px \xD7 ${maxAlpha.toFixed(2)} alpha) is below perceptual floor`
+        });
+      }
+    }
+  }
+  let totalCoverage = 0;
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    const entities = allEntities[li];
+    for (const e of entities) {
+      const r = e.size / 2;
+      const pixArea = layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
+      totalCoverage += pixArea * e.alpha / (w * h);
+    }
+  }
+  if (totalCoverage < 5e-4 && spec.layers.length > 0) {
+    warnings.push({
+      path: "layers",
+      code: "sparse-scene",
+      message: `alpha-weighted coverage is ${(totalCoverage * 100).toFixed(4)}% \u2014 scene will look empty on most displays`
+    });
+  }
+  if (totalEntities > 500) {
+    warnings.push({
+      path: "layers",
+      code: "dense-scene",
+      message: `${totalEntities} entities \u2014 scene may feel crowded and hurt performance on low-end devices`
+    });
+  }
+  if (spec.layers.length > 0 && textLayerCount > 0 && motionLayerCount === 0) {
+    const textRatio = textLayerCount / spec.layers.length;
+    if (textRatio >= 0.8) {
+      warnings.push({
+        path: "layers",
+        code: "text-heavy",
+        message: "most layers are static text \u2014 reads as a document, not a screensaver"
+      });
+    }
+  }
+  return warnings;
+}
+
 // src/examples/aquarium.ts
 var AQUARIUM_SPEC = {
   schemaVersion: 1,
@@ -655,6 +932,51 @@ var AQUARIUM_SPEC = {
   ]
 };
 
+// src/examples/constellation.ts
+var CONSTELLATION_SPEC = {
+  schemaVersion: 1,
+  id: "constellation",
+  label: "Constellation",
+  seed: 73,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#020212" },
+      { at: 0.5, color: "#050520" },
+      { at: 1, color: "#0a0830" }
+    ]
+  },
+  layers: [
+    // Distant static stars (no links, just atmosphere)
+    {
+      count: 100,
+      sprite: { kind: "circle", radius: [1, 3], color: "#667799", colors: ["#8899cc", "#99aadd", "#aabbee", "#7788aa"] },
+      alpha: [0.2, 0.7],
+      pulse: { amp: 0.2, period: 3e3 },
+      motion: { type: "static" }
+    },
+    // Connected constellation nodes — slow drift, linked
+    {
+      key: "nodes",
+      count: 40,
+      sprite: { kind: "circle", radius: [2, 5], color: "#88aaff", colors: ["#88aaff", "#aaccff", "#ffcc88", "#ff8866"], soft: true },
+      alpha: [0.5, 0.9],
+      blend: "lighter",
+      motion: { type: "drift", speed: [2, 8], bidirectional: true, bob: 3 },
+      links: { k: 3, maxDist: 200, alpha: 0.15, width: 0.5 }
+    },
+    // Cycling asterism markers
+    {
+      count: 6,
+      sprite: { kind: "emoji", glyphs: ["\u2726", "\u2727", "\u22C6", "\u2217"], cycle: { period: 2e3 } },
+      size: [14, 22],
+      alpha: [0.4, 0.7],
+      motion: { type: "drift", speed: [1, 4], bidirectional: true }
+    }
+  ]
+};
+
 // src/examples/dev-dashboard.ts
 var DASHBOARD_SPEC = {
   schemaVersion: 1,
@@ -1219,6 +1541,90 @@ var LANTERNS_SPEC = {
   ]
 };
 
+// src/examples/orrery.ts
+var ORRERY_SPEC = {
+  schemaVersion: 1,
+  id: "orrery",
+  label: "Orrery",
+  seed: 7,
+  motionIntensity: "calm",
+  background: {
+    type: "gradient",
+    stops: [
+      { at: 0, color: "#020210" },
+      { at: 0.5, color: "#06051a" },
+      { at: 1, color: "#0a0820" }
+    ]
+  },
+  layers: [
+    // Distant stars
+    {
+      count: 80,
+      sprite: { kind: "circle", radius: [0.3, 1.2], color: "#8899cc" },
+      alpha: [0.2, 0.8],
+      pulse: { amp: 0.3, period: 3e3 },
+      motion: { type: "static" }
+    },
+    // Sun corona (soft glow)
+    {
+      key: "corona",
+      count: 1,
+      sprite: { kind: "circle", radius: [60, 60], color: "#ffaa22", soft: true },
+      blend: "lighter",
+      alpha: [0.6, 0.6],
+      grow: { amp: 0.15, period: 4e3 },
+      motion: { type: "static" },
+      position: { x: 0.5, y: 0.5 }
+    },
+    // Sun body
+    {
+      key: "sun",
+      count: 1,
+      sprite: { kind: "emoji", glyphs: ["\u2600\uFE0F"] },
+      size: [48, 48],
+      grow: { amp: 0.08, period: 4e3 },
+      motion: { type: "static" },
+      position: { x: 0.5, y: 0.5 }
+    },
+    // Inner ring — small fast planets
+    {
+      key: "inner",
+      count: 3,
+      sprite: { kind: "emoji", glyphs: ["\u{1FAA8}", "\u{1F534}", "\u{1F7E0}"] },
+      size: [16, 22],
+      spin: 30,
+      motion: { type: "orbit", speed: [28, 42], radius: [80, 120] }
+    },
+    // Middle ring — gas giants
+    {
+      key: "middle",
+      count: 2,
+      sprite: { kind: "emoji", glyphs: ["\u{1F7E4}", "\u{1FA90}"] },
+      size: [28, 38],
+      spin: -15,
+      motion: { type: "orbit", speed: [12, 20], radius: [160, 200] }
+    },
+    // Outer ring — ice giants
+    {
+      key: "outer",
+      count: 2,
+      sprite: { kind: "emoji", glyphs: ["\u{1F535}", "\u{1F48E}"] },
+      size: [22, 30],
+      spin: 10,
+      motion: { type: "orbit", speed: [5, 10], radius: [240, 300] }
+    },
+    // Orbital dust ring (soft glow particles orbiting slowly)
+    {
+      count: 24,
+      sprite: { kind: "circle", radius: [1, 3], color: "#ccaa66", soft: true },
+      alpha: [0.15, 0.4],
+      blend: "lighter",
+      pulse: { amp: 0.2, period: 2500 },
+      motion: { type: "orbit", speed: [2, 8], radius: [100, 320] }
+    }
+  ]
+};
+
 // src/examples/rain.ts
 var RAIN_SPEC = {
   schemaVersion: 1,
@@ -1338,7 +1744,9 @@ var SCHEMA_EXAMPLES = [
   { id: "snowfall", label: "Snowfall", spec: SNOWFALL_SPEC },
   { id: "lanterns", label: "Night Lanterns", spec: LANTERNS_SPEC },
   { id: "sakura", label: "Sakura Drift", spec: SAKURA_SPEC },
-  { id: "dev-dashboard", label: "Dev Dashboard", spec: DASHBOARD_SPEC }
+  { id: "dev-dashboard", label: "Dev Dashboard", spec: DASHBOARD_SPEC },
+  { id: "orrery", label: "Orrery", spec: ORRERY_SPEC },
+  { id: "constellation", label: "Constellation", spec: CONSTELLATION_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -1346,16 +1754,19 @@ var EXAMPLE_BY_ID = Object.fromEntries(
 );
 export {
   AQUARIUM_SPEC,
+  CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
   LANTERNS_SPEC,
   LIMITS,
+  ORRERY_SPEC,
   RAIN_SPEC,
   SAKURA_SPEC,
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
   SNOWFALL_SPEC,
+  adviseSpec,
   alphaAt,
   applyDeltasToSpec,
   assertValidSpec,
@@ -1363,9 +1774,13 @@ export {
   compileSaver,
   easeSmooth,
   lerpSpec,
+  linkPairs,
   manifestFor,
   positionAt,
   resolveSpecPath,
+  rotationAt,
+  sizeAt,
+  spriteIndexAt,
   spriteVariants,
   structuralSignature,
   validateSpec