@idle-screens/schema 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -32,6 +32,7 @@ type BackgroundSpec = {
     type: 'gradient';
     stops: GradientStop[];
     band?: BandSpec;
+    drift?: BackgroundDrift;
 };
 /** A vertical gradient stop (`at` 0 = top, 1 = bottom). */
 interface GradientStop {
@@ -44,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;
@@ -114,6 +122,14 @@ interface LayerSpec {
         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';
@@ -193,6 +209,8 @@ 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 {
@@ -215,11 +233,18 @@ declare const LIMITS: {
     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. */
@@ -260,8 +285,9 @@ interface Placed {
 }
 declare function spriteVariants(sprite: SpriteSpec): number;
 /** 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[];
+ *  `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. */
@@ -318,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;
 /**
@@ -335,6 +371,51 @@ declare function adviseSpec(spec: SaverSpec, viewport?: {
     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
@@ -342,6 +423,13 @@ declare function adviseSpec(spec: SaverSpec, viewport?: {
  */
 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
@@ -408,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, 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 };
+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 };