@idle-screens/schema 2.0.0 → 2.2.0

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';
@@ -30,6 +32,7 @@ type BackgroundSpec = {
     type: 'gradient';
     stops: GradientStop[];
     band?: BandSpec;
+    drift?: BackgroundDrift;
 };
 /** A vertical gradient stop (`at` 0 = top, 1 = bottom). */
 interface GradientStop {
@@ -42,6 +45,13 @@ interface BandSpec {
     /** Band height in px. */
     height: number;
 }
+/** Slow oscillation of gradient stop positions — makes the background feel alive. */
+interface BackgroundDrift {
+    /** Full cycle period in ms. Floor: LIMITS.minDriftPeriod (10 s). */
+    period: number;
+    /** How far stops shift (fraction of the 0..1 range). Default 0.15, max 0.3. */
+    amount?: number;
+}
 interface LayerSpec {
     count: number;
     sprite: SpriteSpec;
@@ -74,6 +84,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 +111,30 @@ 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;
+    };
+    /**
+     * Afterglow trail behind moving entities. Samples past positions analytically
+     * (no state, fully deterministic). `length` in ms, `fade` 0..1 (default 1 = full fade).
+     */
+    trail?: {
+        length: number;
+        fade?: number;
+    };
 }
 type SpriteSpec = {
     kind: 'emoji';
     glyphs: string[];
+    cycle?: CycleSpec;
 } | {
     kind: 'text';
     strings: string[];
@@ -99,6 +143,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 +151,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 +186,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 {
@@ -145,6 +209,14 @@ interface SpecError {
 interface ValidationResult {
     valid: boolean;
     errors: SpecError[];
+    /** Non-blocking warnings about unknown/misplaced properties or likely authoring mistakes. */
+    warnings?: SpecWarning[];
+}
+/** 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: {
@@ -154,11 +226,25 @@ 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;
+    readonly maxTrailLength: 5000;
+    readonly maxTrailSamples: 24;
+    readonly minDriftPeriod: 10000;
+    readonly maxDriftAmount: 0.3;
 };
 
 /**
  * Validate an untrusted (agent- or JSON-authored) spec structurally + semantically.
- * Returns typed errors; never throws. `compileSaver` refuses to run an invalid spec.
+ * Returns typed errors and warnings; never throws. `compileSaver` refuses to run an invalid spec.
+ *
+ * Warnings are non-blocking advisories about unknown/misplaced properties and
+ * near-zero speeds. They don't prevent compilation but indicate likely authoring mistakes.
  */
 declare function validateSpec(spec: unknown): ValidationResult;
 /** Narrowing helper: validate + cast. Throws with a joined message when invalid. */
@@ -175,12 +261,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 +284,26 @@ 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.
+ *  `countScale` multiplies entity count for density-aware scaling (default 1). */
+declare function buildEntities(layer: LayerSpec, rng: Rng, w: number, h: number, scale?: number, countScale?: 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;
@@ -234,6 +344,16 @@ declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): Saver
  * target immediately (k > 0). Layer counts round to integers.
  */
 declare function lerpSpec(from: SaverSpec, to: SaverSpec, k: number): SaverSpec;
+/**
+ * Enumerate all steerable leaf paths in a (resolved) spec. Returns dot-paths
+ * like "layers.0.count", "background.stops.1.color", etc. Metadata fields
+ * (id, label, schemaVersion, seed, units, kind, type, key) are excluded —
+ * they describe structure, not tuneable values.
+ *
+ * Layer keys are NOT substituted: paths always use numeric indices.
+ * Consumers can map to key-based paths via resolveSpecPath if needed.
+ */
+declare function steerablePaths(spec: unknown): string[];
 /** Smooth (ease-in-out) progress curve used for glides. */
 declare function easeSmooth(k: number): number;
 /**
@@ -242,6 +362,60 @@ declare function easeSmooth(k: number): number;
  */
 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[];
+
+interface LayerSnapshot {
+    key: string | undefined;
+    count: number;
+    centroid: {
+        x: number;
+        y: number;
+    };
+    coverage: number;
+    meanAlpha: number;
+    linksDrawn: number | null;
+    linksExpected: number | null;
+    connectedComponents: number | null;
+    isolatedNodes: number | null;
+}
+interface SceneSnapshot {
+    t: number;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    layers: LayerSnapshot[];
+    warnings: string[];
+}
+interface SceneDescription {
+    spec: {
+        id: string;
+        label: string;
+        units: string;
+    };
+    snapshots: SceneSnapshot[];
+}
+/**
+ * Deterministic scene analysis at one or more time values. Reuses `buildEntities`
+ * and `linkPairs` — no render needed. Returns structured data a non-vision model
+ * can use to understand what a spec looks like when rendered.
+ */
+declare function describeScene(spec: SaverSpec, options?: {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    seed?: number;
+    times?: number[];
+}): SceneDescription;
+
 /**
  * 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
@@ -249,6 +423,20 @@ declare function structuralSignature(spec: SaverSpec): string;
  */
 declare const AQUARIUM_SPEC: SaverSpec;
 
+/**
+ * Comet Shower: showcases trails (afterglow behind moving entities) and background
+ * drift (gradient stops breathing slowly). Three layers: a static star field, fast
+ * comets with long trails, and slow fireflies with short trails and pulse.
+ */
+declare const COMETS_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;
 
@@ -287,6 +475,14 @@ declare const SAKURA_SPEC: SaverSpec;
  */
 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;
@@ -300,4 +496,4 @@ 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_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 };
+export { AQUARIUM_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerSnapshot, type LayerSpec, type MotionSpec, ORRERY_SPEC, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneSnapshot, type SchemaExample, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type ValidationResult, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, describeScene, easeSmooth, lerpSpec, linkPairs, manifestFor, positionAt, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, validateSpec };