@idle-screens/schema 1.0.0 → 2.1.0

package/FORMAT.md

@@ -0,0 +1,135 @@
+# SaverSpec — Format Specification (version 1)
+
+The declarative, agent-authorable screensaver format compiled by
+`@idle-screens/schema`. A spec describes a saver as **data** — a static
+background plus layers of moving sprites — which `compileSaver()` turns into a
+seeded, deterministic, flash-safe `SaverPlugin`. There is no code in a spec: no
+scripting, no network access, no DOM access.
+
+- **Machine-readable schema:** [`saver-spec.schema.json`](./saver-spec.schema.json)
+  (JSON Schema draft-07), importable as
+  `@idle-screens/schema/saver-spec.schema.json`.
+- **Runtime validator:** `validateSpec(spec)` / `assertValidSpec(spec)` — used by
+  `compileSaver()`, which refuses to run an invalid spec.
+
+## Versioning
+
+The **format version** (`schemaVersion`, currently `1`) is independent of the
+npm package version. The package may ship breaking API changes without bumping
+the format; the format only bumps when existing specs would parse or render
+differently. New *optional* fields may be added within a format version —
+older runtimes ignore unknown fields (see Validation semantics).
+
+Additions to version 1 so far, all optional and backward compatible:
+`alpha`, `blend`, `pulse`, `region` (layer appearance/placement);
+`static` motion, `position`, `key` (dashboard/HUD support);
+`align`, `baseline`, `maxWidth` (text sprites).
+
+## Safety invariants
+
+These hold **by construction** — no spec can violate them:
+
+1. **No flash primitive.** The background is static and entities are bounded
+   sprites, so a compiled spec cannot strobe the full field. Provable by
+   sampling any compiled spec through `@idle-screens/validator`.
+2. **Pulse is bounded.** Opacity breathing amplitude is capped at 0.5 and its
+   period floored at 500 ms (2 Hz — under the WCAG 3 Hz flash threshold), and
+   every entity gets its own seeded phase, so a layer can never pulse in unison.
+3. **Motion is bounded.** Speeds are capped at 4000 px/sec.
+4. **Work is bounded.** ≤ 36 layers, ≤ 400 entities per layer, ≤ 800 total.
+5. **Determinism.** All randomness comes from a seeded PRNG. Same spec + same
+   seed ⇒ identical entity streams and identical frames at any time `t`
+   (compiled savers expose `renderFrame(t, seed)`).
+
+## Validation semantics
+
+Two validators exist with deliberately different strictness:
+
+| | unknown fields | everything else |
+|---|---|---|
+| `saver-spec.schema.json` | **rejected** (catches authoring typos) | identical |
+| `validateSpec()` (runtime) | **ignored** (forward compatibility) | identical |
+
+Author against the JSON Schema; ship through the runtime validator.
+
+Two rules the JSON Schema cannot fully express (the runtime enforces them):
+total entities across all layers ≤ 800, and every `[min, max]` range must
+satisfy `min ≤ max`.
+
+## Structure
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "id": "snowfall",              // unique kebab-case id
+  "label": "Snowfall",
+  "seed": 42,                    // optional; falls back to the host's seed
+  "motionIntensity": "calm",     // optional: calm | moderate | energetic
+  "background": { ... },         // optional; defaults to black
+  "layers": [ { ... }, ... ]     // 1..36, rendered back-to-front
+}
+```
+
+### `background`
+
+- `{ "type": "solid", "color": "#06060c" }`
+- `{ "type": "gradient", "stops": [{ "at": 0, "color": "#06121e" }, { "at": 1, "color": "#0d2436" }], "band": { "color": "#3a2d18", "height": 90 } }`
+  — vertical gradient (`at` 0 = top → 1 = bottom); optional solid `band` at the
+  bottom (e.g. an aquarium seafloor). All colours are hex (`#rgb` / `#rrggbb`).
+
+### `layers[]`
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `count` | int 1..400 | — | entities in this layer |
+| `sprite` | SpriteSpec | — | what each entity looks like |
+| `motion` | MotionSpec | — | how entities move |
+| `size` | `[min,max]` px > 0 | sprite-dependent | font size for emoji/text; ignored for circle |
+| `wrap` | boolean | `true` | wrap to the opposite edge when leaving the viewport |
+| `flip` | boolean | `false` | mirror the sprite to face its heading |
+| `alpha` | `[min,max]` 0..1 | `[1,1]` | per-entity opacity range |
+| `blend` | `"lighter"` | source-over | additive compositing (glow stacking) |
+| `region` | `{x?, y?}` ranges 0..1 | full viewport | fractional spawn window (placement only, not travel) |
+| `pulse` | `{amp ≤ 0.5, period ≥ 500}` | none | seeded-phase opacity breathing |
+| `key` | string | none | addressable name → `setParam("key.field", …)` |
+| `position` | `{x, y}` 0..1 | none | exact placement; **requires `count: 1`**; overrides `region` |
+
+### `sprite` (one of)
+
+- `{ "kind": "emoji", "glyphs": ["🐟", "🐠"] }` — glyph picked per entity (seeded)
+- `{ "kind": "text", "strings": ["HELLO"], "color": "#e6e8ef", "font": "bold 24px monospace", "align": "center", "baseline": "middle", "maxWidth": 300 }`
+- `{ "kind": "circle", "radius": [1, 3], "color": "#ffffff", "soft": true }` —
+  `soft` renders a radial-falloff glow orb instead of a hard disc
+
+### `motion` (one of)
+
+- `{ "type": "drift", "speed": [20, 60], "angle": 0, "bidirectional": true, "bob": 4 }`
+  — heading in degrees (0 = right, 90 = down); `bidirectional` flips horizontal
+  direction per entity (fish); `bob` adds vertical wobble (px)
+- `{ "type": "rise", "speed": [10, 30], "sway": 6 }` — upward, with horizontal sway (bubbles)
+- `{ "type": "bounce", "speed": [120, 240] }` — diagonal, reflecting off edges
+- `{ "type": "static" }` — stays exactly where placed (use with `position` for HUD text)
+
+All speeds are px/sec ranges; each entity draws its own value (seeded).
+
+## Determinism contract
+
+Entity construction consumes the seeded RNG in a **fixed draw order** per layer.
+New optional fields only consume RNG draws when present, so adding features to
+the format never changes the entity stream of an existing spec — a spec authored
+against an older runtime renders bit-identically on a newer one.
+
+## Steering
+
+Compiled specs accept live parameter changes via dot-paths —
+`layers.0.count`, `background.stops.0.color`, or `key`-based paths like
+`cpu-gauge.color` when layers declare `key`. Changes interpolate over a
+control-track (`step` | `linear` | `smooth`). See `@idle-screens/core` for
+`ControlTrack` and the idlescreens.com MCP `setParam` tool.
+
+## Examples
+
+Shipped working specs (also exposed as `EXAMPLE_SPECS`): `aquarium`, `rain`,
+`snowfall`, `lanterns`, `sakura`, `dev-dashboard` — see
+[`src/examples.ts`](./src/examples.ts). The dashboard exercises the static/HUD
+subset at scale (34 layers of keyed, positioned text).

package/dist/index.d.ts

@@ -22,6 +22,8 @@ interface SaverSpec {
     background?: BackgroundSpec;
     layers: LayerSpec[];
     motionIntensity?: 'calm' | 'moderate' | 'energetic';
+    /** Dimensional unit system. 'viewport' = all sizes/speeds/distances are fractions of min(w,h). */
+    units?: 'px' | 'viewport';
 }
 type BackgroundSpec = {
     type: 'solid';
@@ -74,6 +76,20 @@ interface LayerSpec {
         amp: number;
         period: number;
     };
+    /**
+     * Per-entity rotation speed in degrees/sec (positive = clockwise).
+     * Each entity gets a seeded starting angle. Composes with any motion type.
+     */
+    spin?: 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
+     * flash-safety floor as pulse. Per-entity seeded phase.
+     */
+    grow?: {
+        amp: number;
+        period: number;
+    };
     /**
      * Addressable name for this layer. Enables `setParam` to use `key.field` paths
      * instead of `layers.N.field` indices. Also makes specs self-documenting.
@@ -87,10 +103,22 @@ interface LayerSpec {
         x: number;
         y: number;
     };
+    /**
+     * Inter-entity links: draw lines to each entity's k nearest neighbors within maxDist.
+     * Capped at LIMITS.maxLinksK. Layer count must be <= LIMITS.maxLinkLayerCount when set.
+     */
+    links?: {
+        k: number;
+        maxDist: number;
+        color?: string;
+        alpha?: number;
+        width?: number;
+    };
 }
 type SpriteSpec = {
     kind: 'emoji';
     glyphs: string[];
+    cycle?: CycleSpec;
 } | {
     kind: 'text';
     strings: string[];
@@ -99,6 +127,7 @@ type SpriteSpec = {
     align?: 'left' | 'center' | 'right';
     baseline?: 'top' | 'middle' | 'bottom';
     maxWidth?: number;
+    cycle?: CycleSpec;
 }
 /** `soft` renders a radial falloff (glow orb) instead of a hard disc. */
  | {
@@ -106,7 +135,12 @@ type SpriteSpec = {
     radius: [number, number];
     color: string;
     soft?: boolean;
+    colors?: string[];
 };
+/** Rotate through sprite variants over time. Each entity offsets by its seeded phase. */
+interface CycleSpec {
+    period: number;
+}
 type MotionSpec = 
 /**
  * Drift at a per-entity speed picked from `speed` (px/sec) along `angle` degrees
@@ -136,6 +170,20 @@ type MotionSpec =
 /** Entity stays exactly where placed. No movement. Use with `position` for pinned elements. */
  | {
     type: 'static';
+}
+/**
+ * Orbit around a center point. Each entity gets a seeded radius from `radius`
+ * and a seeded phase. `speed` is angular velocity in degrees/sec. `center` is
+ * fractional {x, y} (default {0.5, 0.5} = viewport center).
+ */
+ | {
+    type: 'orbit';
+    speed: [number, number];
+    radius: [number, number];
+    center?: {
+        x: number;
+        y: number;
+    };
 };
 /** A validation problem, pointing at a JSON path within the spec. */
 interface SpecError {
@@ -146,6 +194,12 @@ interface ValidationResult {
     valid: boolean;
     errors: SpecError[];
 }
+/** An advisory warning (non-blocking). Returned by `adviseSpec`. */
+interface SpecWarning {
+    path: string;
+    code: string;
+    message: string;
+}
 /** Perf/safety caps enforced by `validateSpec`. */
 declare const LIMITS: {
     readonly maxPerLayer: 400;
@@ -154,6 +208,13 @@ declare const LIMITS: {
     readonly maxSpeed: 4000;
     readonly maxPulseAmp: 0.5;
     readonly minPulsePeriod: 500;
+    readonly maxSpin: 360;
+    readonly maxGrowAmp: 0.8;
+    readonly maxOrbitSpeed: 180;
+    readonly maxLinksK: 8;
+    readonly maxLinkLayerCount: 200;
+    readonly minCyclePeriod: 500;
+    readonly referenceViewport: 1080;
 };
 
 /**
@@ -175,12 +236,22 @@ interface Entity {
     vx: number;
     vy: number;
     bob: number;
-    motion: 'drift' | 'rise' | 'bounce' | 'static';
+    motion: 'drift' | 'rise' | 'bounce' | 'static' | 'orbit';
     headingLeft: boolean;
     alpha: number;
     pulseAmp: number;
     pulsePeriod: number;
     pulsePhase: number;
+    spinSpeed: number;
+    spinPhase: number;
+    growAmp: number;
+    growPeriod: number;
+    growPhase: number;
+    orbitR: number;
+    orbitCx: number;
+    orbitCy: number;
+    colorIndex: number;
+    cyclePeriod: number;
 }
 interface Placed {
     x: number;
@@ -188,12 +259,25 @@ interface Placed {
     flip: boolean;
 }
 declare function spriteVariants(sprite: SpriteSpec): number;
-/** Deterministically place a layer's entities using the seeded RNG (never Math.random). */
-declare function buildEntities(layer: LayerSpec, rng: Rng, w: number, h: number): Entity[];
+/** Deterministically place a layer's entities using the seeded RNG (never Math.random).
+ *  `scale` multiplies every dimensional draw (default 1). Used for viewport units. */
+declare function buildEntities(layer: LayerSpec, rng: Rng, w: number, h: number, scale?: number): Entity[];
 /** Analytic opacity of an entity at logical time `t` (ms). Pure, clamped to 0..1. */
 declare function alphaAt(e: Entity, t: number): number;
+/** Analytic size multiplier at time `t` (ms). Pure, clamped to > 0. */
+declare function sizeAt(e: Entity, t: number): number;
+/** Analytic rotation angle at time `t` (ms) in radians. Pure. */
+declare function rotationAt(e: Entity, t: number): number;
 /** Analytic position of an entity at logical time `t` (ms). Pure & deterministic. */
 declare function positionAt(e: Entity, t: number, w: number, h: number): Placed;
+/** Time-varying sprite index for text/emoji cycling. Returns static index when cyclePeriod is 0. */
+declare function spriteIndexAt(e: Entity, t: number, variants: number): number;
+/** K-nearest-neighbor edge list. Deterministic tie-break: (dist, index).
+ *  When `doWrap` is true, uses toroidal distance so links don't streak across wrap seams. */
+declare function linkPairs(positions: Array<{
+    x: number;
+    y: number;
+}>, k: number, maxDist: number, doWrap: boolean, w: number, h: number): Array<[number, number]>;
 
 /** Derive a manifest so a compiled spec composes with @idle-screens/capabilities. */
 declare function manifestFor(spec: SaverSpec): SaverManifest;
@@ -204,16 +288,73 @@ declare function manifestFor(spec: SaverSpec): SaverManifest;
  */
 declare function compileSaver(spec: unknown): SaverPlugin;
 
+/**
+ * Pure helpers for LIVE steering of compiled specs (setParam / applyTrack).
+ * A track's deltas address spec fields by dot-path ("layers.0.count",
+ * "background.stops.1.color") or layer key ("fireflies.count"). Steering
+ * changes existing values only — unknown paths are ignored (the server
+ * validates and rejects them; the runtime stays lenient).
+ */
+
+interface PathTarget {
+    parent: Record<string, unknown> | unknown[];
+    key: string | number;
+}
+/** Resolve a dot-path (key-aware) to its parent + final key; null if absent. */
+declare function resolveSpecPath(spec: unknown, path: string): PathTarget | null;
+/** A steering delta as carried on a channel control-track. */
+interface SteerDelta {
+    t: number;
+    path: string;
+    value: unknown;
+    ease?: string;
+    dur?: number;
+}
+/** Apply deltas to a deep copy of the spec (last-wins, target values). */
+declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): SaverSpec;
+/**
+ * Interpolate between two structurally-similar specs at progress k (0..1).
+ * Numbers lerp, hex colours lerp per channel, everything else steps to the
+ * target immediately (k > 0). Layer counts round to integers.
+ */
+declare function lerpSpec(from: SaverSpec, to: SaverSpec, k: number): SaverSpec;
+/** Smooth (ease-in-out) progress curve used for glides. */
+declare function easeSmooth(k: number): number;
+/**
+ * Fields that require re-seeding entities when they change (placement/motion
+ * are baked at build time). Colour/alpha/pulse-only changes redraw in place.
+ */
+declare function structuralSignature(spec: SaverSpec): string;
+
+/**
+ * Non-blocking advisory warnings for a valid spec. Does NOT replace validateSpec —
+ * call advise only on specs that have already passed validation.
+ */
+declare function adviseSpec(spec: SaverSpec, viewport?: {
+    width: number;
+    height: number;
+}): SpecWarning[];
+
 /**
  * Reproduces the hand-coded Fish Aquarium saver as pure DATA — the discriminating test
  * that the schema is actually expressive: two layers (fish drifting both ways at varied
  * speeds with a bob + flip, over a gradient with a seafloor band; bubbles rising with sway).
  */
 declare const AQUARIUM_SPEC: SaverSpec;
+
+/**
+ * Constellation: drifting stars connected by faint k-nearest links. Exercises
+ * colors[] (multi-hued stars), links (k-nearest neighbor lines), and cycle
+ * (emoji asterisms rotate glyphs). Stars are soft circles in pixel units.
+ */
+declare const CONSTELLATION_SPEC: SaverSpec;
+
 /** Rain: dense text streaks falling straight down over a near-black sky. */
 declare const RAIN_SPEC: SaverSpec;
+
 /** Snowfall: three depth layers of white circles drifting down with horizontal bob. */
 declare const SNOWFALL_SPEC: SaverSpec;
+
 /**
  * Night Lanterns (Yi Peng festival sky): depth from four correlated parallax cues —
  * closer layers are LARGER, FASTER, SWAY WIDER, and glow WARMER/BRIGHTER. v2 of this
@@ -224,6 +365,7 @@ declare const SNOWFALL_SPEC: SaverSpec;
  * the water line).
  */
 declare const LANTERNS_SPEC: SaverSpec;
+
 /**
  * Sakura Drift: cherry-blossom petals carried on a spring twilight breeze. Five
  * correlated-parallax layers build the depth — the far backdrop is a barely-moving
@@ -236,6 +378,7 @@ declare const LANTERNS_SPEC: SaverSpec;
  * diagonal breeze, and from lanterns by falling rather than rising.
  */
 declare const SAKURA_SPEC: SaverSpec;
+
 /**
  * Dev Dashboard: a dense ops-style HUD exercising static positioning, keyed layers,
  * and text alignment at scale. Two ambient particle layers provide depth behind 28
@@ -243,6 +386,26 @@ declare const SAKURA_SPEC: SaverSpec;
  * file list, and scrolling event log.
  */
 declare const DASHBOARD_SPEC: SaverSpec;
+
+/**
+ * Orrery: a mechanical solar system. Exercises orbit motion (concentric rings
+ * at different speeds), spin (planets rotate on their axes), and grow (the sun
+ * pulses). Soft glow circles with additive blending create the corona and
+ * planetary halos.
+ */
+declare const ORRERY_SPEC: SaverSpec;
+
+/** Catalog entry for a bundled schema example. */
+interface SchemaExample {
+    id: string;
+    label: string;
+    spec: SaverSpec;
+}
+/** Ordered catalog of bundled schema examples. Add new specs as standalone files, then register here. */
+declare const SCHEMA_EXAMPLES: readonly SchemaExample[];
+/** All example specs in catalog order (tests, batch compile). */
 declare const EXAMPLE_SPECS: SaverSpec[];
+/** Lookup by saver id. */
+declare const EXAMPLE_BY_ID: Readonly<Record<string, SaverSpec>>;
 
-export { AQUARIUM_SPEC, type BackgroundSpec, type BandSpec, DASHBOARD_SPEC, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerSpec, type MotionSpec, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SpecError, type SpriteSpec, type ValidationResult, alphaAt, assertValidSpec, buildEntities, compileSaver, manifestFor, positionAt, spriteVariants, validateSpec };
+export { AQUARIUM_SPEC, type BackgroundSpec, type BandSpec, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerSpec, type MotionSpec, ORRERY_SPEC, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SchemaExample, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type ValidationResult, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, easeSmooth, lerpSpec, linkPairs, manifestFor, positionAt, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, structuralSignature, validateSpec };