@idle-screens/schema 0.1.0 → 1.0.0

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;
 
@@ -159,6 +212,37 @@ declare function compileSaver(spec: unknown): SaverPlugin;
 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;
 declare const EXAMPLE_SPECS: 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_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 };