@idle-screens/schema 2.1.0 → 2.3.0

package/dist/index.d.ts

@@ -22,8 +22,22 @@ 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';
+    /**
+     * Frame persistence (0..1, capped at LIMITS.maxGhosting). Instead of fully clearing,
+     * each frame the background is painted at reduced alpha so moving entities leave
+     * decaying after-images (Mystify smears, long-exposure light). Inherently
+     * flash-safe: ghosting can only smooth luminance changes, never sharpen them.
+     * `renderFrame(t)` stays deterministic for seeks via a fixed-step warm-up replay.
+     */
+    ghosting?: number;
+    /** Dimensional unit system. 'viewport' (default) = all sizes/speeds/distances are fractions of min(w,h). */
+    units?: 'viewport' | 'px';
+    /**
+     * Resolution at which this spec was designed. Density scaling kicks in above this
+     * threshold: entity counts scale by min(w,h) / referenceViewport. Default: 1080.
+     * Set to your design resolution so a spec authored at 4K doesn't over-densify.
+     */
+    referenceViewport?: number;
 }
 type BackgroundSpec = {
     type: 'solid';
@@ -32,6 +46,7 @@ type BackgroundSpec = {
     type: 'gradient';
     stops: GradientStop[];
     band?: BandSpec;
+    drift?: BackgroundDrift;
 };
 /** A vertical gradient stop (`at` 0 = top, 1 = bottom). */
 interface GradientStop {
@@ -41,9 +56,16 @@ interface GradientStop {
 /** An optional solid band at the bottom (e.g. an aquarium seafloor). */
 interface BandSpec {
     color: string;
-    /** Band height in px. */
+    /** Band height — px or a viewport fraction, per the spec's `units`. */
     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;
@@ -56,8 +78,12 @@ interface LayerSpec {
     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';
+    /**
+     * Compositing for this layer. 'lighter' = additive (glow stacking); 'screen' =
+     * gentler additive for pale backgrounds; 'multiply' = darkening (shadows,
+     * silhouettes). Default source-over. None of these can strobe.
+     */
+    blend?: 'lighter' | 'screen' | 'multiply';
     /**
      * Fractional spawn window (0 = left/top, 1 = right/bottom). Constrains where
      * entities are PLACED, not where they may travel. Default full viewport.
@@ -71,10 +97,20 @@ interface LayerSpec {
      * 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.
+     *
+     * `wave` derives each entity's phase from its spawn position instead of a seeded
+     * draw, turning independent breathing into a traveling wave across the field
+     * (ripples, wind through grass). `wavelength` is dimensional (px or viewport
+     * units); `angle` is the propagation direction in degrees (0 = rightward,
+     * default 0). Still flash-safe: neighbors are out of phase by construction.
      */
     pulse?: {
         amp: number;
         period: number;
+        wave?: {
+            wavelength: number;
+            angle?: number;
+        };
     };
     /**
      * Per-entity rotation speed in degrees/sec (positive = clockwise).
@@ -104,7 +140,13 @@ interface LayerSpec {
         y: number;
     };
     /**
-     * Inter-entity links: draw lines to each entity's k nearest neighbors within maxDist.
+     * Inter-entity links. `mode` picks the wiring:
+     * - 'nearest' (default): each entity's k nearest neighbors within maxDist.
+     * - 'chain': entities connected in order (0-1-2-…) — Mystify polygons, string
+     *   art. Ignores k/maxDist; `closed` joins the last entity back to the first.
+     * - 'random': a fixed golden-ratio-stride wiring (k partners per entity,
+     *   deterministic, no RNG draws) — breaks the crystalline k-nearest look.
+     * `falloff` fades link alpha with distance/maxDist, killing pop-in at the cutoff.
      * Capped at LIMITS.maxLinksK. Layer count must be <= LIMITS.maxLinkLayerCount when set.
      */
     links?: {
@@ -113,6 +155,42 @@ interface LayerSpec {
         color?: string;
         alpha?: number;
         width?: number;
+        mode?: 'nearest' | 'chain' | 'random';
+        falloff?: boolean;
+        closed?: boolean;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * Grid placement instead of random scatter: entities fill cells row-major within
+     * `region`. `columns` defaults to an aspect-fit square-ish grid; `jitter` (0..1,
+     * scalar or per-axis) offsets each entity within its cell by a seeded fraction of
+     * the cell size — `{ y: 1 }` keeps columns crisp while scattering vertically
+     * (Matrix rain). Unlocks column effects, LED walls, mosaics, uniform dot fields.
+     */
+    layout?: {
+        type: 'grid';
+        columns?: number;
+        jitter?: number | {
+            x?: number;
+            y?: number;
+        };
+    };
+    /**
+     * Layer lifecycle for act structure — a pure function of t, no state. Alpha is 0
+     * before `enter` (ms), ramps up over `fade` ms (default 1000), holds at 1, then
+     * ramps down starting at `exit`. Entities are skipped entirely while at alpha 0.
+     */
+    life?: {
+        enter?: number;
+        exit?: number;
+        fade?: number;
     };
 }
 type SpriteSpec = {
@@ -129,13 +207,52 @@ type SpriteSpec = {
     maxWidth?: number;
     cycle?: CycleSpec;
 }
-/** `soft` renders a radial falloff (glow orb) instead of a hard disc. */
+/** `soft` renders a radial falloff (glow orb) instead of a hard disc.
+ *  `colorWeights` (same length as `colors`) biases the seeded per-entity pick —
+ *  "mostly cool tones, occasional ember" without duplicating entries. */
  | {
     kind: 'circle';
     radius: [number, number];
     color: string;
     soft?: boolean;
     colors?: string[];
+    colorWeights?: number[];
+}
+/** Unfilled circle (bubbles, portals, sonar pings). `width` = stroke width. */
+ | {
+    kind: 'ring';
+    radius: [number, number];
+    color: string;
+    width?: number;
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * A line segment oriented along the entity's instantaneous heading (derived
+ * analytically from its motion) with a faded tail — rain that reads as rain,
+ * shooting stars, warp stars. `length` is the segment length range; `width` the
+ * stroke width.
+ */
+ | {
+    kind: 'streak';
+    length: [number, number];
+    color: string;
+    width?: number;
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * Axis-aligned rectangle (rotates with `spin`). `width` is the horizontal size
+ * range; `aspect` the height/width ratio range (default [1,1] = squares).
+ * Mondrian blocks, confetti, city lights.
+ */
+ | {
+    kind: 'rect';
+    width: [number, number];
+    aspect?: [number, number];
+    color: string;
+    colors?: string[];
+    colorWeights?: number[];
 };
 /** Rotate through sprite variants over time. Each entity offsets by its seeded phase. */
 interface CycleSpec {
@@ -174,7 +291,10 @@ type MotionSpec =
 /**
  * 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).
+ * fractional {x, y} (default {0.5, 0.5} = viewport center) — or
+ * `{ layer: key }` to orbit a single-entity parent layer (moons around a
+ * wandering planet). Strictly one level deep: the parent may not itself
+ * orbit a layer, and must have `count: 1`.
  */
  | {
     type: 'orbit';
@@ -183,7 +303,59 @@ type MotionSpec =
     center?: {
         x: number;
         y: number;
+    } | {
+        layer: string;
     };
+}
+/**
+ * Organic harmonic drift — the analytic flow field. Each entity moves at a base
+ * velocity from `speed` plus 3 seeded sine octaves per axis, producing flowing
+ * curved paths (Flurry streams, aurora, jellyfish) with zero simulation state.
+ * `angle` fixes the base heading in degrees (omit for a seeded heading per
+ * entity); `meander` scales the harmonic amplitude (dimensional, default 0.05
+ * viewport units); `coherence` (0..1) blends every entity's harmonics toward a
+ * shared layer-level set — at 1 the field undulates in unison (fake flocking).
+ */
+ | {
+    type: 'wander';
+    speed: [number, number];
+    angle?: number;
+    meander?: number;
+    coherence?: number;
+}
+/**
+ * Perspective starfield: entities live on a depth axis and stream toward the
+ * viewer, projected as `screen = center + offset / z`. Size and alpha scale
+ * with 1/z (small and faint at the far plane, large and fast up close), and z
+ * wraps — the honest warp tunnel. `speed` is in depth-units/sec
+ * (1 = full near-to-far span per second, capped at LIMITS.maxWarpSpeed).
+ */
+ | {
+    type: 'warp';
+    speed: [number, number];
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Choreographed spline motion: entities traverse `points` (fractional {x,y})
+ * over `duration` ms. `curve: 'smooth'` (default) uses Catmull-Rom through the
+ * points; 'linear' uses straight segments. `closed` (default true) loops the
+ * path; open paths ping-pong. Each entity gets a seeded phase offset along the
+ * path, and `scatter` (dimensional) adds a seeded per-entity offset so shared
+ * paths don't stack. Figure-eights, sweeping arcs, patrol routes.
+ */
+ | {
+    type: 'path';
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    duration: number;
+    curve?: 'linear' | 'smooth';
+    closed?: boolean;
+    scatter?: number;
 };
 /** A validation problem, pointing at a JSON path within the spec. */
 interface SpecError {
@@ -193,6 +365,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,18 +389,46 @@ 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;
+    readonly maxGhosting: 0.95;
+    readonly maxGhostReplayFrames: 120;
+    readonly maxMeander: 500;
+    readonly maxWarpSpeed: 1.5;
+    readonly minPathPoints: 2;
+    readonly maxPathPoints: 24;
+    readonly minPathDuration: 2000;
+    readonly maxGridColumns: 100;
 };
 
 /**
  * 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. */
 declare function assertValidSpec(spec: unknown): SaverSpec;
 
+/** Near plane for warp motion. z lives in [WARP_NEAR, 1]; screen scale is 1/z. */
+declare const WARP_NEAR = 0.08;
+/** One axis-pair of seeded harmonic octaves for wander motion (amps px, freqs rad/ms). */
+interface WanderOsc {
+    ax: number[];
+    fx: number[];
+    phx: number[];
+    ay: number[];
+    fy: number[];
+    phy: number[];
+}
 /** A seeded entity: initial state + resolved velocity. `positionAt` is a pure function
- *  of this + time, so the rAF loop and renderFrame(t) produce identical results. */
+ *  of this + time, so the rAF loop and renderFrame(t) produce identical results.
+ *  IMPORTANT (determinism/compat): fields for newer features are OPTIONAL and only
+ *  set when the feature is declared, so older specs snapshot byte-identically. */
 interface Entity {
     x0: number;
     y0: number;
@@ -236,7 +438,7 @@ interface Entity {
     vx: number;
     vy: number;
     bob: number;
-    motion: 'drift' | 'rise' | 'bounce' | 'static' | 'orbit';
+    motion: 'drift' | 'rise' | 'bounce' | 'static' | 'orbit' | 'wander' | 'warp' | 'path';
     headingLeft: boolean;
     alpha: number;
     pulseAmp: number;
@@ -252,6 +454,39 @@ interface Entity {
     orbitCy: number;
     colorIndex: number;
     cyclePeriod: number;
+    /** Rect sprite second dimension (height px). Only set for rect sprites. */
+    size2?: number;
+    /** Orbit parent layer key (motion.center = { layer }). Center resolved at render time. */
+    orbitParent?: string;
+    /** Harmonic drift params. Only set for wander motion. */
+    wander?: {
+        own: WanderOsc;
+        shared: WanderOsc;
+        coherence: number;
+        margin: number;
+    };
+    /** Depth-axis params. Only set for warp motion. */
+    warp?: {
+        ux: number;
+        uy: number;
+        z0: number;
+        vz: number;
+        cx: number;
+        cy: number;
+    };
+    /** Spline params (pts in px, shared per layer). Only set for path motion. */
+    path?: {
+        pts: Array<{
+            x: number;
+            y: number;
+        }>;
+        duration: number;
+        closed: boolean;
+        smooth: boolean;
+        phase: number;
+        offX: number;
+        offY: number;
+    };
 }
 interface Placed {
     x: number;
@@ -260,18 +495,52 @@ 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. */
 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;
+/** Layer lifecycle alpha multiplier at time `t` (ms). Pure. 1 when `life` is unset. */
+declare function lifeAlphaAt(life: {
+    enter?: number;
+    exit?: number;
+    fade?: number;
+} | undefined, 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;
+/**
+ * Analytic heading (radians) at time `t`, from a finite difference of positionAt.
+ * Used to orient streak sprites. Returns null across a wrap seam (position jump
+ * larger than half the viewport) — callers should skip orientation that frame.
+ */
+declare function headingAt(e: Entity, t: number, w: number, h: number): number | null;
 /** 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;
+/** An inter-entity link edge with its (wrap-aware) distance, for falloff alpha. */
+interface LinkEdge {
+    i: number;
+    j: number;
+    dist: number;
+}
+/**
+ * Edge list for a layer's `links`, dispatching on mode:
+ * 'nearest' (default) k-nearest within maxDist; 'chain' sequential order
+ * (Mystify — ignores k/maxDist, `closed` joins last to first); 'random' a fixed
+ * golden-ratio-stride wiring filtered by maxDist (deterministic, no RNG draws).
+ */
+declare function linkEdges(links: {
+    k: number;
+    maxDist: number;
+    mode?: 'nearest' | 'chain' | 'random';
+    closed?: boolean;
+}, positions: Array<{
+    x: number;
+    y: number;
+}>, maxDistPx: number, doWrap: boolean, w: number, h: number): LinkEdge[];
 /** 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<{
@@ -318,6 +587,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 +614,202 @@ 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;
+
+interface PerceiveOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    seed?: number;
+    /** Sample time in ms. Default 5000 (past all typical life.enter staging). */
+    t?: number;
+}
+interface LuminanceGrid {
+    cols: number;
+    rows: number;
+    /** Row-major luminance 0..1 including the background. */
+    cells: number[];
+    /** Per-row background luminance (what an empty scene would be). */
+    background: number[];
+    meanLuminance: number;
+    /** Fraction of cells deviating perceptibly (> 0.03) from the background. */
+    coverage: number;
+    /** Deviation-weighted centre of visual mass as viewport fractions, or null for a flat scene. */
+    centroid: {
+        x: number;
+        y: number;
+    } | null;
+    /** Mean deviation-from-background per row/column — 1D transects of the composition. */
+    rowProfile: number[];
+    colProfile: number[];
+}
+interface LuminanceGridOptions extends PerceiveOptions {
+    /** Grid resolution. Defaults 80×48 (→ a 40×12 braille map). */
+    cols?: number;
+    rows?: number;
+}
+/**
+ * Sample the spec into a coarse luminance image — analytically, no renderer.
+ * Approximations (documented, deliberate): trails and ghosting are ignored,
+ * soft circles use a linear falloff, background drift is sampled at its rest
+ * position. Good enough to perceive composition, focus, and balance.
+ */
+declare function luminanceGrid(spec: SaverSpec, opts?: LuminanceGridOptions): LuminanceGrid;
+/**
+ * Encode a luminance grid as a braille "image": each output character is a 2×4
+ * pixel cell, ordered-dithered so mid-tones render as dot density. A grid of
+ * 80×48 becomes 12 lines of 40 chars — a picture a text model can read whole.
+ *
+ * Auto-exposure: most savers live in the bottom of the luminance range, so the
+ * cells are normalized (min → 98th percentile) before dithering — like a
+ * camera exposing for the scene. Stats on the grid itself stay raw.
+ */
+declare function renderBrailleMap(grid: LuminanceGrid): string;
+interface DominanceEntry {
+    rank: number;
+    layerIndex: number;
+    key: string | undefined;
+    /** Normalized share of total visual weight, 0..1 (all entries sum to 1). */
+    share: number;
+    entityCount: number;
+    meanLuma: number;
+    factors: {
+        area: number;
+        contrast: number;
+        blendBoost: number;
+        motionBoost: number;
+    };
+}
+/**
+ * Rank layers by estimated visual weight — where the eye goes. Weight is
+ * on-screen area × alpha, scaled by contrast against the background, an
+ * additive-glow boost, and a motion boost. Link lines count as area.
+ */
+declare function dominanceRanking(spec: SaverSpec, opts?: PerceiveOptions): DominanceEntry[];
+interface LayerMotionStats {
+    layerIndex: number;
+    key: string | undefined;
+    /** Mean / max on-screen speed in px per second (wrap jumps excluded). */
+    meanSpeed: number;
+    maxSpeed: number;
+    moving: boolean;
+}
+/** Per-layer displacement between t and t+dt — choreography as numbers. */
+declare function motionStats(spec: SaverSpec, opts?: PerceiveOptions & {
+    dt?: number;
+}): LayerMotionStats[];
+declare const REGION_NAMES: readonly ["top-left", "top-center", "top-right", "mid-left", "center", "mid-right", "bottom-left", "bottom-center", "bottom-right"];
+interface SceneDiff {
+    t: number;
+    coverage: {
+        a: number;
+        b: number;
+        delta: number;
+    };
+    meanLuminance: {
+        a: number;
+        b: number;
+        delta: number;
+    };
+    /** Shift of the visual-mass centroid from A to B, in viewport fractions. */
+    balanceShift: {
+        dx: number;
+        dy: number;
+    } | null;
+    /** Mean deviation-from-background per third-by-third region, with deltas. */
+    regions: Array<{
+        region: (typeof REGION_NAMES)[number];
+        a: number;
+        b: number;
+        delta: number;
+    }>;
+    /** Dominance changes, matched by layer key (falls back to index). Sorted by |share delta|. */
+    dominance: Array<{
+        key: string;
+        rankA: number | null;
+        rankB: number | null;
+        shareA: number;
+        shareB: number;
+    }>;
+    advisories: {
+        added: string[];
+        removed: string[];
+    };
+}
+/**
+ * Compare two specs at the same time/viewport — relative perception. A text
+ * model is far better at "is B better than A" than "is A good"; this returns
+ * the deltas that question needs: coverage, balance, per-region visual mass,
+ * dominance-rank movement, and advisory changes.
+ */
+declare function diffScenes(a: SaverSpec, b: SaverSpec, opts?: LuminanceGridOptions): SceneDiff;
+interface ScenePerception {
+    t: number;
+    /** The picture: a braille luminance map (each char = 2×4 pixels). */
+    braille: string;
+    coverage: number;
+    meanLuminance: number;
+    centroid: {
+        x: number;
+        y: number;
+    } | null;
+    rowProfile: number[];
+    colProfile: number[];
+    dominance: DominanceEntry[];
+    motion: LayerMotionStats[];
+    advisories: ReturnType<typeof adviseSpec>;
+}
+/**
+ * Everything a non-vision agent needs to "see" a spec in one deterministic
+ * call: the braille picture, composition transects, dominance ranking, motion
+ * stats, and advisories. Intended as the payload behind an MCP previewScene.
+ */
+declare function perceiveScene(spec: SaverSpec, opts?: LuminanceGridOptions): ScenePerception;
+
 /**
  * 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,10 +817,17 @@ 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
- * (emoji asterisms rotate glyphs). Stars are soft circles in pixel units.
+ * (emoji asterisms rotate glyphs). Stars are soft circles in viewport units.
  */
 declare const CONSTELLATION_SPEC: SaverSpec;
 
@@ -367,23 +849,24 @@ declare const SNOWFALL_SPEC: SaverSpec;
 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.
+ * Sakura Drift: cherry-blossom petals carried on a spring twilight breeze.
+ * Glow-up pass (v1-ceiling features): petals ride `wander` harmonics with shared
+ * `coherence` so gusts move the whole fall together, `spin` tumbles the glyphs,
+ * faint `streak` wind-lines cross the frame, the blossom-glow backdrop shimmers
+ * as a traveling `pulse.wave`, and dusk fireflies wander the lower field. The
+ * ground is a warm plum earth blended out of the sunset (no more abrupt dark
+ * band), with slow background `drift` keeping the sky alive.
  */
 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.
+ * Control Center: a general-purpose ambient status HUD (home / ops / anything —
+ * not dev-specific). Exercises the static/HUD subset at scale plus the
+ * v1-ceiling features: `life` staggers the panels in like a boot sequence, a
+ * grid-`layout` LED wall breathes behind everything via a traveling
+ * `pulse.wave`, `ring` sprites form the central gauge, and a rect "equalizer"
+ * animates with a wave-phased pulse. Every panel is keyed so an agent can
+ * steer any reading live (`power-value`, `gauge-value`, `feed-1`, ...).
  */
 declare const DASHBOARD_SPEC: SaverSpec;
 
@@ -395,6 +878,44 @@ declare const DASHBOARD_SPEC: SaverSpec;
  */
 declare const ORRERY_SPEC: SaverSpec;
 
+/**
+ * Aurora Borealis: the "fake fluid" recipe — showcases `wander` motion (harmonic
+ * drift) with high `coherence` so the curtain undulates as one body, `pulse.wave`
+ * (a traveling shimmer across the star field), weighted palettes, additive blend,
+ * and `ghosting` smearing the soft glows into continuous curtains of light.
+ */
+declare const AURORA_SPEC: SaverSpec;
+
+/**
+ * Matrix Rain: showcases `layout: grid` with per-axis jitter ({ y: 1 } keeps the
+ * columns crisp while de-syncing them vertically), glyph `cycle`, and `ghosting`
+ * doing the classic fading-trail work. Two depths of rain plus rare bright heads.
+ */
+declare const MATRIX_RAIN_SPEC: SaverSpec;
+
+/**
+ * Polygons: the classic Mystify-style bouncing-polygon saver, expressed as chain links + heavy
+ * ghosting. Showcases `links.mode: 'chain'` with `closed` (vertices wired in order
+ * into a polygon), `bounce` motion, and high `ghosting` (the decaying after-images
+ * ARE the effect — no per-entity trail sampling involved).
+ */
+declare const POLYGONS_SPEC: SaverSpec;
+
+/**
+ * Night Procession: a choreographed scene. Showcases `path` motion (a smooth
+ * figure-eight lantern route with scatter), layer-parented `orbit` (moths circling
+ * a wandering lantern-bearer), `life` staging (stars first, the procession enters
+ * at 4 s, moths at 7 s), plus `ring` and `rect` sprites.
+ */
+declare const PROCESSION_SPEC: SaverSpec;
+
+/**
+ * Warp Tunnel: showcases `warp` motion (perspective depth — size/alpha/speed scale
+ * with 1/z), `streak` sprites oriented along the analytic heading, `colorWeights`
+ * (mostly white stars, occasional blue/amber), and light `ghosting` for smear.
+ */
+declare const WARP_TUNNEL_SPEC: SaverSpec;
+
 /** Catalog entry for a bundled schema example. */
 interface SchemaExample {
     id: string;
@@ -408,4 +929,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, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, validateSpec };