@idle-screens/schema 1.0.0 → 2.0.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

@@ -204,16 +204,57 @@ 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;
+
 /**
  * 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;
+
 /** 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 +265,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 +278,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 +286,18 @@ declare const SAKURA_SPEC: SaverSpec;
  * file list, and scrolling event log.
  */
 declare const DASHBOARD_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, DASHBOARD_SPEC, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerSpec, type MotionSpec, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SchemaExample, type SpecError, type SpriteSpec, type SteerDelta, type ValidationResult, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, easeSmooth, lerpSpec, manifestFor, positionAt, resolveSpecPath, spriteVariants, structuralSignature, validateSpec };