@idle-screens/schema 2.3.0 → 2.4.0

package/FORMAT.md

@@ -122,7 +122,7 @@ trails, long-exposure light). 0.85–0.95 is the useful range; 0 (default) is of
 | `blend` | `lighter` \| `screen` \| `multiply` | source-over | additive glow / gentle additive / darkening |
 | `region` | `{x?, y?}` ranges 0..1 | full viewport | fractional spawn window (placement only, not travel) |
 | `pulse` | `{amp ≤ 0.5, period ≥ 500, wave?}` | none | opacity breathing; `wave: {wavelength, angle?}` turns it into a traveling wave across the field |
-| `spin` | number ±360 deg/sec | none | per-entity rotation (seeded start angle) |
+| `spin` | number \| `[min,max]` ±360 deg/sec | none | per-entity rotation (seeded start angle); a range gives each entity a seeded speed (confetti, tumbling debris) |
 | `grow` | `{amp ≤ 0.8, period ≥ 500}` | none | size breathing (seeded phase) |
 | `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail (ms of history) |
 | `links` | see below | none | inter-entity lines |
@@ -225,23 +225,38 @@ zero-dependency, renderer-free analysis tool.
   (background gradient + entities + link lines, blend-aware), with coverage,
   visual-mass centroid, and **row/column deviation profiles** (1D transects of
   the composition).
-- `renderBrailleMap(grid)` — the picture: 12 lines × 40 braille chars, each
-  char a 2×4 dot cell, ordered-dithered with auto-exposure. An agent reads the
-  whole frame at once instead of reconstructing it entity by entity.
+- `renderBrailleMap(grid)` — the compact picture: 12 lines × 40 braille chars,
+  each char a 2×4 dot cell, ordered-dithered with auto-exposure. An agent reads
+  the whole frame at once instead of reconstructing it entity by entity.
+- `renderDensityMap(grid)` — a **higher-fidelity** picture: one ASCII density
+  char (`  .:-=+*#%@`) per grid cell, so it's 1:1 with the grid. Pair with a
+  larger `cols`/`rows` (e.g. `{cols: 120, rows: 48}`) to resolve structure the
+  braille map smears — concentric rings, grids, text blocks. This is the sharper
+  read when composition detail matters.
 - `dominanceRanking(spec, opts)` — layers ranked by estimated visual weight
   (area × alpha × contrast × glow/motion boosts; links count) — *where the eye
-  goes*, normalized to shares.
+  goes*, normalized to shares. Thin-but-bright structures (rings, streaks, link
+  lines) get a line-salience boost so they aren't crushed by filled discs.
 - `motionStats(spec, opts)` — per-layer mean/max on-screen speed from analytic
   displacement — choreography as numbers.
+- `textSprites(spec, opts)` — the literal strings and rendered sizes of every
+  text layer. Glyphs are invisible in the luminance maps, so this is the only
+  way to confirm *what words* are on screen and how big. (Also on
+  `perceiveScene().text`.)
 - `diffScenes(a, b, opts)` — **relative sight**: coverage/luminance deltas,
   visual-balance shift, 3×3 region deltas, dominance-rank movement, and
   advisory codes added/removed. Agents judge "is B better than A" far more
   reliably than "is A good"; this is the edit loop's primary instrument.
 
-Known approximations (deliberate): trails and ghosting are not sampled, soft
-circles use a linear falloff, text ink is estimated from font size × string
-length. Good enough to perceive composition, focus, balance, and motion —
-not a substitute for a human (or VLM) judgement of beauty.
+Coverage is **additive-glow-calibrated**: soft circles drawn with
+`blend: lighter`/`screen` bloom past their radius (as they do on the real
+canvas), so `coverage` tracks what the audience sees instead of under-reporting
+glow-heavy scenes by an order of magnitude.
+
+Known approximations (deliberate): trails and ghosting are not sampled, text ink
+is estimated from font size × string length. Good enough to perceive
+composition, focus, balance, and motion — not a substitute for a human (or VLM)
+judgement of beauty.
 
 ## Examples
 

package/dist/index.d.ts

@@ -115,8 +115,12 @@ interface LayerSpec {
     /**
      * Per-entity rotation speed in degrees/sec (positive = clockwise).
      * Each entity gets a seeded starting angle. Composes with any motion type.
+     * A scalar applies one speed to every entity; a `[min, max]` range gives each
+     * entity a seeded speed within the range (like `speed`/`alpha`) — confetti,
+     * tumbling debris, foliage. Existing scalar specs are unaffected (the range
+     * form draws one extra seeded value, only when present).
      */
-    spin?: number;
+    spin?: number | [number, number];
     /**
      * Sinusoidal size breathing, parallel to `pulse` for opacity. `amp` is a
      * fraction of base size (0.3 = ±30 %). `period` in ms with the same
@@ -703,12 +707,33 @@ declare function luminanceGrid(spec: SaverSpec, opts?: LuminanceGridOptions): Lu
  * Encode a luminance grid as a braille "image": each output character is a 2×4
  * pixel cell, ordered-dithered so mid-tones render as dot density. A grid of
  * 80×48 becomes 12 lines of 40 chars — a picture a text model can read whole.
- *
- * Auto-exposure: most savers live in the bottom of the luminance range, so the
- * cells are normalized (min → 98th percentile) before dithering — like a
- * camera exposing for the scene. Stats on the grid itself stay raw.
  */
 declare function renderBrailleMap(grid: LuminanceGrid): string;
+/**
+ * Encode a luminance grid as a one-char-per-cell ASCII density map. Unlike the
+ * braille map (compact, 2×4 dots/char) this is 1:1 with the grid, so pairing it
+ * with a larger `cols`/`rows` gives a non-vision agent a genuinely higher-detail
+ * read: 120×48 resolves concentric rings and text blocks braille smears into a
+ * blob. Shares the braille map's auto-exposure so both views agree.
+ */
+declare function renderDensityMap(grid: LuminanceGrid): string;
+interface TextSpriteInfo {
+    layerIndex: number;
+    key: string | undefined;
+    /** The literal strings this layer draws (glyphs are invisible in the maps). */
+    strings: string[];
+    /** How many entities carry text. */
+    count: number;
+    /** Representative rendered glyph height in px at the sample viewport. */
+    sizePx: number;
+}
+/**
+ * List every text layer's actual strings and rendered size. No grid resolution
+ * renders glyphs legibly, so a non-vision agent otherwise can't tell whether the
+ * words it wrote are on screen, how big, or whether they'll overlap. This closes
+ * that blind spot analytically.
+ */
+declare function textSprites(spec: SaverSpec, opts?: PerceiveOptions): TextSpriteInfo[];
 interface DominanceEntry {
     rank: number;
     layerIndex: number;
@@ -789,8 +814,14 @@ interface SceneDiff {
 declare function diffScenes(a: SaverSpec, b: SaverSpec, opts?: LuminanceGridOptions): SceneDiff;
 interface ScenePerception {
     t: number;
-    /** The picture: a braille luminance map (each char = 2×4 pixels). */
+    /** The picture: a braille luminance map (each char = 2×4 pixels), compact. */
     braille: string;
+    /**
+     * A one-char-per-cell ASCII density map at the grid resolution — higher
+     * fidelity than braille for structure (rings, grids, text blocks). Pair with
+     * a larger `cols`/`rows` for a sharper read.
+     */
+    density: string;
     coverage: number;
     meanLuminance: number;
     centroid: {
@@ -801,12 +832,15 @@ interface ScenePerception {
     colProfile: number[];
     dominance: DominanceEntry[];
     motion: LayerMotionStats[];
+    /** Literal strings + sizes of any text layers (glyphs don't show in the maps). */
+    text: TextSpriteInfo[];
     advisories: ReturnType<typeof adviseSpec>;
 }
 /**
  * Everything a non-vision agent needs to "see" a spec in one deterministic
- * call: the braille picture, composition transects, dominance ranking, motion
- * stats, and advisories. Intended as the payload behind an MCP previewScene.
+ * call: the braille picture, a higher-res density map, composition transects,
+ * dominance ranking, motion stats, the literal text on screen, and advisories.
+ * Intended as the payload behind an MCP previewScene.
  */
 declare function perceiveScene(spec: SaverSpec, opts?: LuminanceGridOptions): ScenePerception;
 
@@ -929,4 +963,4 @@ declare const EXAMPLE_SPECS: SaverSpec[];
 /** Lookup by saver id. */
 declare const EXAMPLE_BY_ID: Readonly<Record<string, SaverSpec>>;
 
-export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, validateSpec };

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,
@@ -1875,6 +1884,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 +2024,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 +2041,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 +2133,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 +2158,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 +2205,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 +2223,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 +2331,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 +2339,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 })
   };
 }
@@ -3616,6 +3675,7 @@ export {
   perceiveScene,
   positionAt,
   renderBrailleMap,
+  renderDensityMap,
   resolveSpecPath,
   rotationAt,
   sizeAt,
@@ -3623,6 +3683,7 @@ export {
   spriteVariants,
   steerablePaths,
   structuralSignature,
+  textSprites,
   validateSpec
 };
 //# sourceMappingURL=index.js.map