@idle-screens/schema 2.0.0 → 2.1.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';
@@ -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;
@@ -242,6 +326,15 @@ 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[];
+
 /**
  * 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 +342,13 @@ declare function structuralSignature(spec: SaverSpec): string;
  */
 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;
 
@@ -287,6 +387,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 +408,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 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 };