@idle-screens/schema 2.3.0 → 3.0.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;
 
@@ -860,13 +894,21 @@ declare const LANTERNS_SPEC: SaverSpec;
 declare const SAKURA_SPEC: SaverSpec;
 
 /**
- * Control Center: a general-purpose ambient status HUD (home / ops / anything —
- * not dev-specific). Exercises the static/HUD subset at scale plus the
- * v1-ceiling features: `life` staggers the panels in like a boot sequence, a
- * grid-`layout` LED wall breathes behind everything via a traveling
- * `pulse.wave`, `ring` sprites form the central gauge, and a rect "equalizer"
- * animates with a wave-phased pulse. Every panel is keyed so an agent can
- * steer any reading live (`power-value`, `gauge-value`, `feed-1`, ...).
+ * Control Center — VIREO-9, Trans-Lunar Relay Operations.
+ *
+ * A mission-control WALL BOARD, laid out the way real ops rooms lay them out:
+ * framed zones with a clear reading order, one hero display (the orbital
+ * plot), dense-but-calm peripheral telemetry, and a boot sequence when the
+ * board comes up. The fiction: a small relay station somewhere past GEO,
+ * mid-shift, tracking a five-craft fleet (named for this library's own
+ * savers — the station runs our little universe).
+ *
+ * Composed against the validator's 36-layer ceiling deliberately — every
+ * layer earns its slot. Schema exercises: grid `layout` LED wall with a
+ * traveling `pulse.wave`, `orbit` motion with `trail`s and chain `links`
+ * (the relay web between the fleet), `ring` orbit guides, wave-phased rect
+ * meters, staged `life` boots per zone. Every reading is keyed so an agent
+ * can steer the fiction live (`signal-value`, `feed-1`, `alert`, ...).
  */
 declare const DASHBOARD_SPEC: SaverSpec;
 
@@ -893,6 +935,18 @@ declare const AURORA_SPEC: SaverSpec;
  */
 declare const MATRIX_RAIN_SPEC: SaverSpec;
 
+/**
+ * Tarkovsky — Nostalghia's candle: a single point of devotion.
+ * Near-black warm ground; one small warm-white flame at center with grow/pulse
+ * wobble; faint smoke rising; sparse amber embers with long fading trails;
+ * a wide near-invisible halo breathing on a 10s cycle. Minimalism as tension —
+ * most of the screen is darkness.
+ *
+ * Note: `pulse.amp` is ADDED to base alpha (not multiplied), so the halo's amp
+ * must stay below its base alpha or the trough clamps to fully invisible.
+ */
+declare const NOSTALGHIA_CANDLE_SPEC: SaverSpec;
+
 /**
  * Polygons: the classic Mystify-style bouncing-polygon saver, expressed as chain links + heavy
  * ghosting. Showcases `links.mode: 'chain'` with `closed` (vertices wired in order
@@ -929,4 +983,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, NOSTALGHIA_CANDLE_SPEC, 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 };