@idle-screens/schema 0.1.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

@@ -52,6 +52,41 @@ interface LayerSpec {
     wrap?: boolean;
     /** Flip the sprite horizontally to face its heading. Default false. */
     flip?: boolean;
+    /** Per-entity opacity range, both 0..1. Default [1,1]. */
+    alpha?: [number, number];
+    /** Compositing for this layer. 'lighter' = additive (glow stacking). Default source-over. */
+    blend?: 'lighter';
+    /**
+     * Fractional spawn window (0 = left/top, 1 = right/bottom). Constrains where
+     * entities are PLACED, not where they may travel. Default full viewport.
+     */
+    region?: {
+        x?: [number, number];
+        y?: [number, number];
+    };
+    /**
+     * Sinusoidal opacity breathing. SAFETY: amp is capped (LIMITS.maxPulseAmp),
+     * period has a floor (LIMITS.minPulsePeriod — max 2 Hz), and every entity gets
+     * its own seeded phase, so a layer can never strobe in unison. Effective alpha
+     * is clamped to 0..1.
+     */
+    pulse?: {
+        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.
+     */
+    key?: string;
+    /**
+     * Exact fractional position {x, y} for a single entity (0 = left/top, 1 = right/bottom).
+     * Only valid when `count` is 1. Overrides `region` scatter placement.
+     */
+    position?: {
+        x: number;
+        y: number;
+    };
 }
 type SpriteSpec = {
     kind: 'emoji';
@@ -61,10 +96,16 @@ type SpriteSpec = {
     strings: string[];
     color?: string;
     font?: string;
-} | {
+    align?: 'left' | 'center' | 'right';
+    baseline?: 'top' | 'middle' | 'bottom';
+    maxWidth?: number;
+}
+/** `soft` renders a radial falloff (glow orb) instead of a hard disc. */
+ | {
     kind: 'circle';
     radius: [number, number];
     color: string;
+    soft?: boolean;
 };
 type MotionSpec = 
 /**
@@ -91,6 +132,10 @@ type MotionSpec =
  | {
     type: 'bounce';
     speed: [number, number];
+}
+/** Entity stays exactly where placed. No movement. Use with `position` for pinned elements. */
+ | {
+    type: 'static';
 };
 /** A validation problem, pointing at a JSON path within the spec. */
 interface SpecError {
@@ -105,8 +150,10 @@ interface ValidationResult {
 declare const LIMITS: {
     readonly maxPerLayer: 400;
     readonly maxTotal: 800;
-    readonly maxLayers: 8;
+    readonly maxLayers: 36;
     readonly maxSpeed: 4000;
+    readonly maxPulseAmp: 0.5;
+    readonly minPulsePeriod: 500;
 };
 
 /**
@@ -128,8 +175,12 @@ interface Entity {
     vx: number;
     vy: number;
     bob: number;
-    motion: 'drift' | 'rise' | 'bounce';
+    motion: 'drift' | 'rise' | 'bounce' | 'static';
     headingLeft: boolean;
+    alpha: number;
+    pulseAmp: number;
+    pulsePeriod: number;
+    pulsePhase: number;
 }
 interface Placed {
     x: number;
@@ -139,6 +190,8 @@ interface Placed {
 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[];
+/** Analytic opacity of an entity at logical time `t` (ms). Pure, clamped to 0..1. */
+declare function alphaAt(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;
 
@@ -151,14 +204,100 @@ 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
+ * composition exercises the expressive additions the first draft exposed as missing:
+ * soft glow orbs + additive blend (lantern light that sums where it overlaps), bounded
+ * alpha pulse with per-entity phases (breathing flames, strobe-proof by construction),
+ * and spawn regions (stars only above the horizon; dim ember shimmer kept low near
+ * 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
+ * field of soft blossom-glow orbs (additive, breathing out of phase), then three
+ * petal layers grow LARGER, FASTER, BRIGHTER and FLUTTER WIDER as they approach
+ * (the near gust), over a blue-hour gradient with a warm rose horizon and a dark
+ * grass band. A final low layer of dim pink glow settles at the grass line — fallen
+ * petals catching the last light. Wind direction is consistent (down-left) across
+ * every moving layer; petals differ from snowfall by glyph, colour, palette and the
+ * 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
+ * pinned text elements arranged in a three-column layout with header, metrics,
+ * 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, EXAMPLE_SPECS, type Entity, type GradientStop, LIMITS, type LayerSpec, type MotionSpec, type Placed, RAIN_SPEC, SCHEMA_VERSION, type SaverSpec, type SpecError, type SpriteSpec, type ValidationResult, 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 };