@idle-screens/schema 3.5.0 → 3.6.1

package/dist/index.d.ts

@@ -22,6 +22,16 @@ interface SaverSpec {
     background?: BackgroundSpec;
     layers: LayerSpec[];
     motionIntensity?: 'calm' | 'moderate' | 'energetic';
+    /**
+     * Declared density intent. `sparse` says the emptiness is the point (one
+     * mark on a dark ground, long silences): `adviseSpec` withholds
+     * `sparse-scene`, and scorers that gate on coverage should read this before
+     * calling a faithful scene broken. `dense` withholds `dense-scene` the same
+     * way. Either declaration is checked against the measured coverage and a
+     * `density-mismatch` advisory fires when the scene contradicts it. Omitted
+     * means `normal`. A hint only — it changes no pixel.
+     */
+    density?: 'sparse' | 'normal' | 'dense';
     /**
      * 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
@@ -137,7 +147,8 @@ interface LayerSpec {
     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.
+     * Only valid when `count` is 1 — or, with a `list` / `table` layout, as the
+     * top-left anchor of the whole block. Overrides `region` scatter placement.
      */
     position?: {
         x: number;
@@ -185,6 +196,26 @@ interface LayerSpec {
             x?: number;
             y?: number;
         };
+    }
+    /**
+     * Data layouts — entities in READING ORDER, no scatter. `list` stacks them
+     * in one column `gap` apart (viewport units of min(w,h), default 0.06);
+     * `table` fills `columns` row-major with `gap` `{x, y}` (one number = both).
+     * Text and emoji sprites take `strings[i]` / `glyphs[i]` in order instead of
+     * a seeded pick, and palette `colors[i]` likewise, so N labels or N bars are
+     * ONE layer. `position` (with any count) is the block's top-left anchor;
+     * without it the block is centred in `region`.
+     */
+     | {
+        type: 'list';
+        gap?: number;
+    } | {
+        type: 'table';
+        columns: number;
+        gap?: number | {
+            x?: number;
+            y?: number;
+        };
     };
     /**
      * Layer lifecycle for act structure — a pure function of t, no state. Alpha is 0
@@ -196,6 +227,56 @@ interface LayerSpec {
         exit?: number;
         fade?: number;
     };
+    /**
+     * Sparse events — marks that appear, expand and fade in place, one at a time,
+     * with long silences between (the "one ping" primitive). Each entity is dark
+     * except for a window of `life` ms that recurs every `every` ms at a
+     * per-entity offset: `jitter` 1 (default) scatters the offsets (a fixed
+     * low-discrepancy sequence — not seeded, so declaring `emit` disturbs no
+     * other draw and the same spec times its events identically under every
+     * seed), 0 spreads the entities evenly across the period — a metronome, one
+     * event at a time as long as `life ≤ every / count`.
+     * Inside a window the entity fades in over the first quarter and out over
+     * the rest; `grow` scales its size from `grow[0]` to `grow[1]` across the
+     * window — expansion rather than travel. A pure function of t. Flash safety:
+     * `every` ≥ 1000 ms and `life` ≥ 500 ms, so no entity fires more than once a
+     * second and never as a hard cut. Composes with `pulse`, `life`, `trail` and
+     * every motion; with `motion.ease` the eased travel restarts on every event.
+     */
+    emit?: {
+        every: number;
+        life: number;
+        jitter?: number;
+        grow?: [number, number];
+    };
+    /**
+     * Phase-lock. Replaces the seeded per-entity phases of `pulse`, `grow` and
+     * `cycle` with one shared phase (`phase` in turns, 0..1, default 0) and runs
+     * those three at `rate` × scene time (default 1). Two layers declaring the
+     * same clock breathe in step; different phases give a fixed offset (call and
+     * response). `pulse.wave` still adds its position-derived phase on top, so a
+     * clocked wave stays a wave. Because a clocked layer moves in unison, its
+     * `pulse`/`grow` periods must satisfy `period / rate ≥ 1000 ms` (1 Hz).
+     */
+    clock?: {
+        phase?: number;
+        rate?: number;
+    };
+}
+/**
+ * Closed-form velocity easing for `drift`, `rise` and `wander`. `settle`
+ * starts at the entity's speed and decelerates to rest with time constant
+ * `tau` ms — it travels `speed × tau` and stops, a mark flung and coming to
+ * rest. `buoyant` starts at rest and approaches the speed over `tau` — a
+ * bubble reaching terminal velocity. Position stays an analytic function of
+ * t (no integration state). With `emit`, the eased travel restarts from the
+ * spawn point on every event. For `wander` only the base velocity eases —
+ * the harmonic meander keeps breathing, so a settled wanderer hovers rather
+ * than freezes.
+ */
+interface MotionEase {
+    type: 'settle' | 'buoyant';
+    tau: number;
 }
 type SpriteSpec = {
     kind: 'emoji';
@@ -248,6 +329,8 @@ type SpriteSpec = {
 /**
  * Axis-aligned rectangle (rotates with `spin`). `width` is the horizontal size
  * range; `aspect` the height/width ratio range (default [1,1] = squares).
+ * `feather` (0..1) softens the edges: that fraction of the half-size fades
+ * out toward the border — Rothko's soft-edged block at 0.5–0.8.
  * Mondrian blocks, confetti, city lights.
  */
  | {
@@ -255,6 +338,63 @@ type SpriteSpec = {
     width: [number, number];
     aspect?: [number, number];
     color: string;
+    feather?: number;
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * A data bar. Entity i draws a bar `length × values[i] / max` long (viewport
+ * units of min(w,h)), `thickness` thick, growing from its position toward
+ * `direction` (default 'right'). `values` are PAINT — steer
+ * `layers.N.sprite.values` and the bars glide; `max` defaults to the largest
+ * value. Pair with a `list` layout: a chart is one layer, labels another.
+ */
+ | {
+    kind: 'bar';
+    values: number[];
+    length: number;
+    thickness: number;
+    color: string;
+    max?: number;
+    direction?: 'right' | 'left' | 'up' | 'down';
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * Regular or custom polygon. `sides` (3..12, default 6) draws a regular
+ * n-gon of the seeded `radius` (circumradius), point up; `points` (3..24
+ * unit coordinates in −1..1, scaled by the radius) draws any facet — a
+ * Picasso shard, a Kandinsky triangle, a Mondrian plane. `soft` feathers
+ * the fill from the centre like a soft circle. Rotates with `spin`.
+ */
+ | {
+    kind: 'polygon';
+    radius: [number, number];
+    color: string;
+    sides?: number;
+    points?: Array<[number, number]>;
+    soft?: boolean;
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * A freehand mark: a path through `points` (2..24 unit coordinates in
+ * −1..1, scaled by the seeded `length`) stroked `width` wide with round
+ * joins. `curve: 'smooth'` (default) runs a Catmull-Rom spline through the
+ * points, `'linear'` a polyline. `taper` thins the mark to almost nothing at
+ * both ends — a brush stroke rather than a line. `orient` turns the path's
+ * +x along the entity's heading (like `streak`). Rotates with `spin`. Van
+ * Gogh's stroke, Hokusai's contour, O'Keeffe's petal, Basquiat's scrawl.
+ */
+ | {
+    kind: 'stroke';
+    length: [number, number];
+    points: Array<[number, number]>;
+    color: string;
+    width?: number;
+    curve?: 'smooth' | 'linear';
+    taper?: boolean;
+    orient?: boolean;
     colors?: string[];
     colorWeights?: number[];
 }
@@ -338,12 +478,14 @@ type MotionSpec =
     angle?: number;
     bidirectional?: boolean;
     bob?: number;
+    ease?: MotionEase;
 }
 /** Rise upward (px/sec) with an optional horizontal sway amplitude (px) — bubbles. */
  | {
     type: 'rise';
     speed: [number, number];
     sway?: number;
+    ease?: MotionEase;
 }
 /** Bounce diagonally at a per-entity speed, reflecting off the edges (px/sec). */
  | {
@@ -388,6 +530,7 @@ type MotionSpec =
     angle?: number;
     meander?: number;
     coherence?: number;
+    ease?: MotionEase;
 }
 /**
  * Perspective starfield: entities live on a depth axis and stream toward the
@@ -477,6 +620,20 @@ declare const LIMITS: {
     readonly minSegmentDuration: 1000;
     readonly maxTransitionDur: 5000;
     readonly minTransitionDur: 200;
+    readonly minEmitEvery: 1000;
+    readonly maxEmitEvery: 600000;
+    readonly minEmitLife: 500;
+    readonly maxEmitGrow: 8;
+    readonly minClockedPeriod: 1000;
+    readonly minClockRate: 0.1;
+    readonly maxClockRate: 4;
+    readonly defaultListGap: 0.06;
+    readonly defaultListGapPx: 40;
+    readonly minPolygonSides: 3;
+    readonly maxPolygonSides: 12;
+    readonly maxShapePoints: 24;
+    readonly minEaseTau: 100;
+    readonly maxEaseTau: 120000;
 };
 type SequenceTransition = {
     type: 'cut';
@@ -554,10 +711,16 @@ interface Entity {
     orbitCy: number;
     colorIndex: number;
     cyclePeriod: number;
-    /** Rect sprite second dimension (height px). Only set for rect sprites. */
+    /** Rect sprite second dimension (height px), or bar thickness. Only set for rect / bar sprites. */
     size2?: number;
+    /** Reading-order index into `bar.values`. Only set for bar sprites. */
+    barIndex?: number;
+    /** Placed by a list/table layout: variants cycle from the ordered base index, in step. Only set for data layouts. */
+    ordered?: true;
     /** Orbit parent layer key (motion.center = { layer }). Center resolved at render time. */
     orbitParent?: string;
+    /** Present only when the layer explicitly disables edge wrapping. */
+    wrapDisabled?: true;
     /** Harmonic drift params. Only set for wander motion. */
     wander?: {
         own: WanderOsc;
@@ -574,6 +737,23 @@ interface Entity {
         cx: number;
         cy: number;
     };
+    /** Sparse-event window. Only set when `layer.emit` is declared. `phase` ms offset. */
+    emit?: {
+        every: number;
+        life: number;
+        phase: number;
+        growFrom: number;
+        growTo: number;
+    };
+    /** Shared-clock time multiplier for pulse/grow/cycle. Only set when `layer.clock` is declared. */
+    clockRate?: number;
+    /** Shared cycle phase (radians). Only set when `layer.clock` is declared. */
+    cyclePhase?: number;
+    /** Velocity easing. Only set when the motion declares `ease`. */
+    ease?: {
+        type: 'settle' | 'buoyant';
+        tau: number;
+    };
     /** Spline params (pts in px, shared per layer). Only set for path motion. */
     path?: {
         pts: Array<{
@@ -598,6 +778,14 @@ declare function spriteVariants(sprite: SpriteSpec): number;
  *  `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[];
+/**
+ * Where entity `e` sits in its current emit window at time `t`: 0..1 across
+ * the visible `life` ms, or null while dark (or when the layer has no `emit`).
+ * Pure — the window index is `floor((t - phase) / every)`, no state.
+ */
+declare function emitWindow(e: Entity, t: number): number | null;
+/** Alpha envelope across an emit window: fast smooth attack, slow smooth decay. */
+declare function emitEnvelope(u: number): number;
 /** 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. */
@@ -762,6 +950,16 @@ declare function structuralSignature(spec: SaverSpec): string;
 declare function adviseSpec(spec: SaverSpec, viewport?: {
     width: number;
     height: number;
+}, 
+/**
+ * Sample point. `perceiveScene` forwards its own `t`/`seed` so the advisories
+ * describe the same scene its other channels do — without them a caller
+ * perceiving at t = 30 s would get `form` for that instant beside an
+ * `overlap-seams` advisory computed for a different one.
+ */
+opts?: {
+    t?: number;
+    seed?: number;
 }): SpecWarning[];
 /**
  * Non-blocking advisory warnings for a validated sequence envelope.
@@ -772,6 +970,82 @@ declare function adviseSequence(seq: IdleSequence, viewport?: {
     height: number;
 }): SpecWarning[];
 
+/**
+ * Layer cohesion — does a layer read as ONE form, or as N separate marks?
+ *
+ * The gap this closes: every other perception channel reports a heavily
+ * overlapping layer identically whether its sprites merge into a silhouette or
+ * stay legible as individual discs. Luminance, coverage, dominance and the
+ * braille map are all blind to it, because they measure ink, not edges. An
+ * agent drawing a *shape* out of sprites therefore cannot tell success from
+ * failure without publishing and looking at real pixels.
+ *
+ * Two independent facts decide it, so both are reported:
+ *
+ * - `overlap` — geometry. What fraction of a typical entity's outline is buried
+ *   inside a sibling. Scattered fields sit near 0; a deliberate mass sits high.
+ * - `seamless` — paint. Whether an overlap between two of this layer's entities
+ *   paints as an invisible join. Only a hard-edged, fully opaque, single-colour,
+ *   un-blended layer merges; anything else shows every internal edge.
+ *
+ * Both are analytic, deterministic and renderer-free, like the rest of
+ * `perceive.ts`.
+ */
+
+/**
+ * Sample time for a spec-level cohesion read, matching `perceiveScene`'s own
+ * default so the advisory and the reported numbers agree on the usual call.
+ * Past all typical `life.enter` staging; `grow` has had time to breathe.
+ */
+declare const COHESION_T = 5000;
+/** What a layer will read as on the wall. */
+type CohesionRead = 
+/** Entities merge into a single silhouette — the layer draws a shape. */
+'mass'
+/** Entities overlap heavily but every overlap paints a visible edge. */
+ | 'seamed'
+/** Entities stand alone — a field of marks, which most layers are. */
+ | 'marks';
+interface LayerCohesion {
+    layerIndex: number;
+    key: string | undefined;
+    /**
+     * Mean fraction of an entity's outline covered by a same-layer sibling, 0..1.
+     * `null` for sprite kinds where a merged silhouette is not a meaningful idea
+     * (lines, glyphs and text: ring, streak, stroke, bar, emoji, text, textBlock).
+     */
+    overlap: number | null;
+    /** Do this layer's overlaps paint as invisible joins? */
+    seamless: boolean;
+    /** Why not, when not — the field to act on. `null` when seamless. */
+    seamCause: string | null;
+    /** The verdict. `null` when `overlap` is null. */
+    reads: CohesionRead | null;
+}
+/**
+ * Why this layer's overlaps paint a visible edge, or null when they vanish.
+ *
+ * Opacity is judged over the whole timeline, not this instant: a layer that
+ * breathes with `pulse` is translucent at some point in every cycle, so its
+ * seams appear even if the sampled frame happens to catch it at full alpha.
+ */
+declare function seamCauseOf(layer: LayerSpec): string | null;
+/**
+ * Per-layer cohesion for an already-built scene. Takes entities rather than a
+ * spec so `perceiveScene` and `adviseSpec` can each pass the scene they already
+ * built instead of building a third one.
+ */
+declare function cohesionOf(layers: Array<{
+    layer: LayerSpec;
+    entities: Entity[];
+}>, t: number, w: number, h: number): LayerCohesion[];
+/**
+ * True when a `seamed` layer is worth warning about: dense enough to be
+ * deliberate, and opaque enough that it cannot be an atmospheric wash. Keeps
+ * the advisory off the soft low-alpha glow fields the playbook recommends.
+ */
+declare function seamsWorthWarning(layer: LayerSpec, c: LayerCohesion, entityCount: number): boolean;
+
 interface LayerSnapshot {
     key: string | undefined;
     count: number;
@@ -918,6 +1192,13 @@ interface DominanceEntry {
  * ribbons, so a comet layer is ranked by its comet, not just its head.
  */
 declare function dominanceRanking(spec: SaverSpec, opts?: PerceiveOptions): DominanceEntry[];
+/**
+ * Does each layer read as one merged form or as separate marks? The one thing
+ * the luminance maps cannot answer — they measure ink, not edges, so a layer
+ * that merged into a silhouette and one that stayed a pile of discs look
+ * identical in every other channel. See `cohesion.ts`.
+ */
+declare function layerCohesion(spec: SaverSpec, opts?: PerceiveOptions): LayerCohesion[];
 interface LayerMotionStats {
     layerIndex: number;
     key: string | undefined;
@@ -995,6 +1276,8 @@ interface ScenePerception {
     colProfile: number[];
     dominance: DominanceEntry[];
     motion: LayerMotionStats[];
+    /** Per layer: merged silhouette, seamed overlap, or separate marks. */
+    form: LayerCohesion[];
     /** Literal strings + sizes of any text layers (glyphs don't show in the maps). */
     text: TextSpriteInfo[];
     advisories: ReturnType<typeof adviseSpec>;
@@ -1157,6 +1440,38 @@ declare const MATRIX_RAIN_SPEC: SaverSpec;
  */
 declare const NOSTALGHIA_CANDLE_SPEC: SaverSpec;
 
+/**
+ * Pings — almost nothing, almost never.
+ * A near-black ground and one teal hue. Three rings take turns: each one
+ * appears, grows sixteenfold (0.15× → 2.4× its radius) and fades over four
+ * seconds, then the frame is empty until the next — `emit` with `jitter: 0`
+ * spaces them evenly, one event every four seconds, and `life` is kept at
+ * the stagger so no two rings are ever lit together. Underneath, a few motes rise,
+ * `settle` to rest and fade on their own, longer, seeded schedule. Nothing
+ * travels; everything grows and goes. The house style Fathom describes this
+ * exactly and, before `emit`, could not be authored.
+ */
+declare const PINGS_SPEC: SaverSpec;
+
+/**
+ * Facets — a composition in the manner of the early abstractionists: three
+ * soft-edged colour planes (feathered `rect`) breathing slowly behind a field
+ * of tumbling triangular facets (custom `polygon`), tapered brush arcs
+ * (`stroke`) drifting across, and a few glowing hexagons (soft regular
+ * `polygon`). Every glyph here is a path, not a disc — the shape family nine
+ * of the fifteen style profiles asked for.
+ */
+declare const FACETS_SPEC: SaverSpec;
+
+/**
+ * Relay Board — a six-row status chart in five layers instead of twenty-five.
+ * One `list` of labels, one `list` of `bar`s whose lengths are the numbers,
+ * one `list` of readouts, a title block, and a slow dust field behind so the
+ * board reads as a live wall, not a document. Steer `bars.values` and the
+ * bars glide to the new figures; the labels never move.
+ */
+declare const RELAY_BOARD_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
@@ -1193,4 +1508,4 @@ declare const EXAMPLE_SPECS: SaverSpec[];
 /** Lookup by saver id. */
 declare const EXAMPLE_BY_ID: Readonly<Record<string, SaverSpec>>;
 
-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, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextRevealInput, type TextRevealSpec, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, graphemeClusters, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rotationAt, segmentStart, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, textWidthEm, validateSequence, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, FACETS_SPEC, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerCohesion, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextRevealInput, type TextRevealSpec, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, cohesionOf, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, graphemeClusters, headingAt, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rotationAt, seamCauseOf, seamsWorthWarning, segmentStart, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, textWidthEm, validateSequence, validateSpec };