@idle-screens/schema 3.7.0 → 3.9.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Rng, SaverContext, SaverPlugin, SaverManifest } from '@idle-screens/core';
+import { Rng, SaverContext, SaverInstance, ControlTrack, SaverPlugin, SaverManifest } from '@idle-screens/core';
 
 /**
  * Declarative, agent-authorable saver format. A `SaverSpec` describes a saver as DATA
@@ -40,6 +40,12 @@ interface SaverSpec {
      * `renderFrame(t)` stays deterministic for seeks via a fixed-step warm-up replay.
      */
     ghosting?: number;
+    /**
+     * The print finish — grain and a dither screen composited over the
+     * finished frame as the last step of every render. See `FinishSpec`.
+     * Absent ⇒ the frame is presented exactly as drawn.
+     */
+    finish?: FinishSpec;
     /** Dimensional unit system. 'viewport' (default) = all sizes/speeds/distances are fractions of min(w,h). */
     units?: 'viewport' | 'px';
     /**
@@ -49,6 +55,25 @@ interface SaverSpec {
      */
     referenceViewport?: number;
 }
+/**
+ * A print finish over the finished frame: `grain` (0..1) screens a seeded
+ * zero-mean noise tile at up to 35 % alpha; `dither` (0..1) screens an 8×8
+ * ordered Bayer tile at up to 25 % — a stylistic screen, not per-pixel
+ * dithering of the image. Both composite with a symmetric blend (`overlay`)
+ * so the frame's mean luminance is unchanged: flash-safe by construction,
+ * and invisible to `luminanceGrid`. The grain tile is generated once per
+ * mount from the spec seed and sits still; `animate: true` steps its offset
+ * deterministically from the frame's time bucket (12 Hz), never randomly —
+ * ignored on the `basic` / `minimal` capability tiers (static tile). The
+ * finish is applied on a presentation canvas, never fed back into
+ * `ghosting`'s persistence. `grain` and `dither` are numeric paint paths
+ * (`finish.grain`) and glide.
+ */
+interface FinishSpec {
+    grain?: number;
+    dither?: number;
+    animate?: boolean;
+}
 type BackgroundSpec = {
     type: 'solid';
     color: string;
@@ -57,7 +82,45 @@ type BackgroundSpec = {
     stops: GradientStop[];
     band?: BandSpec;
     drift?: BackgroundDrift;
-};
+} | FieldBackground;
+/**
+ * A scalar-field background: seeded, warped value noise quantised into
+ * `bands` — thermal maps, contour terrain, sonar landmasses, riso washes.
+ * Pure in `(x, y, t, seed)`: the renderer paints it as a low-res raster
+ * (short side 96 px; 48 on the `basic` / `minimal` tiers) scaled to the
+ * canvas, recomputed once per 100 ms bucket while drifting and once ever
+ * otherwise, and the perception grid samples the same function directly.
+ * The sampler uses its own hash, never the entity RNG, so adding a field to
+ * a spec leaves every entity where it was.
+ */
+interface FieldBackground {
+    type: 'field';
+    /** Noise features across the short side, 0.5..8 (LIMITS.minFieldScale / maxFieldScale). */
+    scale: number;
+    /** Octaves of detail, integer 1..4 (default 2). */
+    octaves?: number;
+    /** Domain-warp amount 0..1 (default 0) — folds round blobs into smeared contours. */
+    warp?: number;
+    /**
+     * Levels to posterise the field into, integer 2..8, or 0 for smooth
+     * interpolation between bands (Aura, Mist). Default `bands.length`: one
+     * hard band per level.
+     */
+    quantize?: number;
+    /** 2..8 hex colours, darkest-to-lightest or whatever ramp the look wants. */
+    bands: string[];
+    /** Slow domain travel — the field's "animate". Period floored at 10 s (flash guard). */
+    drift?: FieldDrift;
+    /** Field seed; defaults to the spec seed. Independent of the entity stream. */
+    seed?: number;
+}
+/** Slow travel of a field's sample domain: a circle of radius `amount` feature units per `period`. */
+interface FieldDrift {
+    /** Full loop period in ms. Floor: LIMITS.minDriftPeriod (10 s) — the flash guard. */
+    period: number;
+    /** Radius of the domain travel in feature units, 0..1. Default 0.3. */
+    amount?: number;
+}
 /** A vertical gradient stop (`at` 0 = top, 1 = bottom). */
 interface GradientStop {
     at: number;
@@ -131,6 +194,17 @@ interface LayerSpec {
      * form draws one extra seeded value, only when present).
      */
     spin?: number | [number, number];
+    /**
+     * Static per-entity rotation in degrees (positive = clockwise), ±360. A
+     * scalar turns every entity the same way; a `[min, max]` range gives each
+     * entity a seeded angle — thrown blades, scattered glyphs, a tilted grid.
+     * Composes with `spin` (added to its seeded start angle). Note that `spin:
+     * [0, 0]` does NOT do this: a zero spin speed renders at angle 0, its
+     * seeded phase unused. Structural (baked into entities). The range form
+     * draws one seeded value per entity, only when declared, so existing
+     * specs keep identical streams.
+     */
+    rotate?: number | [number, 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
@@ -644,6 +718,7 @@ declare const LIMITS: {
     readonly maxPulseAmp: 0.5;
     readonly minPulsePeriod: 500;
     readonly maxSpin: 360;
+    readonly maxRotate: 360;
     readonly maxGrowAmp: 0.8;
     readonly maxOrbitSpeed: 180;
     readonly maxLinksK: 8;
@@ -654,6 +729,13 @@ declare const LIMITS: {
     readonly maxTrailSamples: 24;
     readonly minDriftPeriod: 10000;
     readonly maxDriftAmount: 0.3;
+    readonly minFieldScale: 0.5;
+    readonly maxFieldScale: 8;
+    readonly maxFieldOctaves: 4;
+    readonly minFieldBands: 2;
+    readonly maxFieldBands: 8;
+    readonly maxFieldQuantize: 8;
+    readonly maxFieldDriftAmount: 1;
     readonly maxGhosting: 0.95;
     readonly maxGhostReplayFrames: 120;
     readonly maxMeander: 500;
@@ -749,6 +831,14 @@ interface IdleSequence {
      * paints its own ground, exactly as before the field existed.
      */
     bed?: SaverSpec;
+    /**
+     * A print finish applied once per composed frame — over bed, segment and
+     * any fade together, on the sequence's presentation canvas. Overrides
+     * every segment's own `finish` while set; absent, the active segment's
+     * `finish` applies when it declares one (a bed's is ignored — the bed is
+     * ground, finish the sequence). Children never apply their own.
+     */
+    finish?: FinishSpec;
     segments: SequenceSegment[];
 }
 
@@ -848,6 +938,8 @@ interface Entity {
         type: 'settle' | 'buoyant';
         tau: number;
     };
+    /** Static rotation (radians), added to any spin. Only set when `layer.rotate` is declared. */
+    rotate?: number;
     /** Spline params (pts in px, shared per layer). Only set for path motion. */
     path?: {
         pts: Array<{
@@ -884,7 +976,13 @@ declare function emitEnvelope(u: number): number;
 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. */
+/**
+ * Analytic rotation angle at time `t` (ms) in radians. Pure. A static
+ * `rotate` is the base; a spinning entity adds its seeded start angle and
+ * speed × t on top. With neither, 0 — and with `spin: [0, 0]` also 0: a zero
+ * spin speed never rotates, so its seeded phase is not applied (that is what
+ * `rotate` is for).
+ */
 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: {
@@ -1016,6 +1114,22 @@ declare function revealState(lines: TextBlockLine[], reveal: TextRevealInput, tM
 
 /** Derive a manifest so a compiled spec composes with @idle-screens/capabilities. */
 declare function manifestFor(spec: SaverSpec): SaverManifest;
+/**
+ * The device's compute tier (`computeTier` from `@idle-screens/capabilities`;
+ * the string union is repeated here so schema does not depend on that
+ * package). Hosts pass it on the mount context; a compiled scene reads it to
+ * step down work that a `basic` / `minimal` device cannot afford.
+ */
+type CapabilityTier = 'minimal' | 'basic' | 'standard' | 'high';
+/**
+ * Mount context for a compiled spec. A plain `SaverContext` works — every
+ * field here is optional. `capabilityTier` `basic` / `minimal` halves a
+ * `field` background's raster resolution (48 px short side instead of 96).
+ * Absent ⇒ full resolution.
+ */
+interface SpecMountContext extends SaverContext {
+    capabilityTier?: CapabilityTier;
+}
 /**
  * Compile a declarative spec into a runnable SaverPlugin. Throws if the spec is invalid
  * (so an agent-authored spec is validated before it can run). The result is seeded,
@@ -1029,19 +1143,47 @@ declare function compileSaver(spec: unknown): SaverPlugin;
  * clock's elapsed ms (idlescreens.com: `Date.now() − scene.epoch`) so every
  * viewer of that sequence resolves the same segment.
  */
-interface SequenceMountContext extends SaverContext {
+interface SequenceMountContext extends SpecMountContext {
     /** ms already elapsed on the shared sequence clock. Ignored unless `sync: 'epoch'`. */
     sequenceBaseT?: number;
     /**
-     * The device's compute tier (`computeTier` from `@idle-screens/capabilities`;
-     * the string union is repeated here so schema does not depend on that
-     * package). A `fade` transition keeps two segments live for `dur`, which
-     * `basic` (canvas2d only) and `minimal` cannot afford: on those tiers fade
-     * renders as `cut`. Absent ⇒ fade enabled.
+     * See `SpecMountContext.capabilityTier`. A `fade` transition keeps two
+     * segments live for `dur`, which `basic` (canvas2d only) and `minimal`
+     * cannot afford: on those tiers fade renders as `cut`. The tier is also
+     * handed to every child and the bed (a `field` background's raster steps
+     * down with it). Absent ⇒ fade enabled, full resolution.
+     */
+    capabilityTier?: CapabilityTier;
+}
+/**
+ * What `compileSequence().mount()` returns: a `SaverInstance` that can also
+ * take a republished sequence in place. Hosts feature-detect it with
+ * `hasHotSwapSequence` (an older engine's instance simply lacks the method)
+ * and fall through to a remount when it returns `false`.
+ */
+interface SequenceSaverInstance extends SaverInstance {
+    renderFrame(t: number, seed: number): void;
+    applyTrack(track: ControlTrack): void;
+    /**
+     * Swap `next` in for the running sequence without remounting, when the
+     * two are `sequenceSwapCompatible`: every live segment child (and the bed)
+     * hot-swaps to its new scene, the clock, the active segment, every
+     * released hold and the retained track stay exactly where they were, and
+     * the next frame resolves to the same `(segment, localT)` as if nothing
+     * had happened — a mid-show caption fix that does not send the room back
+     * to segment 0. Returns `false` and changes nothing when the sequences are
+     * not compatible (a structural or timing edit); the host remounts then.
      */
-    capabilityTier?: 'minimal' | 'basic' | 'standard' | 'high';
+    hotSwapSequence(next: IdleSequence): boolean;
 }
-declare function compileSequence(spec: unknown): SaverPlugin;
+/** `compileSequence`'s plugin: `mount` is typed to the sequence instance and `spec` to the validated sequence. */
+interface SequenceSaverPlugin extends SaverPlugin {
+    mount(ctx: SequenceMountContext): SequenceSaverInstance;
+    spec: IdleSequence;
+}
+/** Feature-detect `hotSwapSequence` on any mounted instance (false for a plain scene, or a sequence from an older engine). */
+declare function hasHotSwapSequence(inst: SaverInstance): inst is SequenceSaverInstance;
+declare function compileSequence(spec: unknown): SequenceSaverPlugin;
 
 /**
  * Pure helpers for LIVE steering of compiled specs (setParam / applyTrack).
@@ -1089,7 +1231,7 @@ declare function morphNothingMorphable(a: SaverSpec, b: SaverSpec, opts?: {
 }): boolean;
 /**
  * Enumerate all steerable leaf paths in a (resolved) spec. Returns dot-paths
- * like "layers.0.count", "background.stops.1.color", etc. Metadata fields
+ * like "layers.0.count", "background.stops.1.color", "background.bands.2", etc. Metadata fields
  * (id, label, schemaVersion, seed, units, kind, type, key) are excluded —
  * they describe structure, not tuneable values.
  *
@@ -1126,10 +1268,18 @@ declare function adviseSpec(spec: SaverSpec, viewport?: {
  * 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.
+ *
+ * `backgroundSeed` is separate from `seed` because a sequence's
+ * `inkOverBed` (the segment's ink layers judged against the bed's
+ * background — see `perceiveSequenceFrame`) mixes two scenes with
+ * potentially different seeds: `seed` drives the ink layers' own entity
+ * stream, `backgroundSeed` samples the bed's field. Defaults to `seed` —
+ * every other caller has one scene and one seed for both.
  */
 opts?: {
     t?: number;
     seed?: number;
+    backgroundSeed?: number;
 }): SpecWarning[];
 /**
  * Non-blocking advisory warnings for a validated sequence envelope.
@@ -1240,10 +1390,12 @@ interface SceneSnapshot {
     warnings: string[];
 }
 interface SceneDescription {
+    /** `finish` is present only when the spec declares one — a print screen the luminance numbers do not include. */
     spec: {
         id: string;
         label: string;
         units: string;
+        finish?: FinishSpec;
     };
     snapshots: SceneSnapshot[];
 }
@@ -1275,8 +1427,15 @@ interface LuminanceGrid {
     rows: number;
     /** Row-major luminance 0..1 including the background. */
     cells: number[];
-    /** Per-row background luminance (what an empty scene would be). */
+    /** Per-row background luminance (what an empty scene would be). For a `field` background: each row's mean. */
     background: number[];
+    /**
+     * Per-cell background luminance, present only for a `field` background
+     * (a solid or gradient varies by row alone, and `background` says it all).
+     * Coverage, centroid and the profiles deviate from THIS, so the field's own
+     * contours never count as content — a bright field is ground, not ink.
+     */
+    backgroundCells?: number[];
     meanLuminance: number;
     /** Fraction of cells deviating perceptibly (> 0.03) from the background. */
     coverage: number;
@@ -1512,6 +1671,159 @@ interface PerceiveSequenceOptions extends Omit<LuminanceGridOptions, 't'> {
  */
 declare function perceiveSequenceFrame(seq: IdleSequence, T: number, opts?: PerceiveSequenceOptions): SequenceFramePerception;
 
+/**
+ * The `field` background sampler — seeded, dependency-free value noise that
+ * is a PURE function of `(u, v, t, config, seed)`.
+ *
+ * Why it is its own module, and why it never touches the entity RNG: a
+ * background must be able to change without re-seating a single entity. The
+ * sampler hashes an integer lattice with its own mixing function, so a spec
+ * that adds (or steers) a field keeps the exact `buildEntities` stream it
+ * had before — `field.test.ts` asserts it. Because the value at any point is
+ * closed-form, the renderer (a low-res raster, upscaled) and the perception
+ * grid (`luminanceGrid`) sample the SAME function and agree by construction;
+ * that is the analytic guarantee FORMAT.md states for the field.
+ *
+ * Coordinates: `u`, `v` are in short-side units — `xPx / min(w, h)`,
+ * `yPx / min(w, h)` — so `scale` reads as "features across the short side"
+ * on every aspect ratio, and a 16:9 frame simply shows more of the same field
+ * than a square one does. Callers on both sides normalise the same way.
+ */
+
+/** Cache bucket for a drifting field: the raster is recomputed at most this often. */
+declare const FIELD_BUCKET_MS = 100;
+/** Raster short side (px) the renderer paints the field at, then upscales. */
+declare const FIELD_RASTER_SHORT_SIDE = 96;
+/** Raster short side on the `basic` / `minimal` capability tiers. */
+declare const FIELD_RASTER_SHORT_SIDE_LOW = 48;
+/** Default `drift.amount`. */
+declare const FIELD_DRIFT_DEFAULT_AMOUNT = 0.3;
+/**
+ * Integer-lattice hash → 0..1. Every product goes through `Math.imul` so the
+ * arithmetic stays in int32 and the result is identical on every platform
+ * (a float multiply of large ints would drift by ULPs across engines).
+ */
+declare function latticeHash(ix: number, iy: number, seed: number): number;
+/** The clamped, rounded octave count a config resolves to (steering may glide it through fractions). */
+declare function fieldOctaves(cfg: Pick<FieldBackground, 'octaves'>): number;
+/**
+ * The time the field is sampled at for scene time `t`: with `drift` at a
+ * nonzero `amount`, the start of the 100 ms bucket `t` falls in (the renderer
+ * recomputes its raster once per bucket and holds it, so the perception grid
+ * samples the same instant); without `drift`, or with `drift.amount: 0` (the
+ * domain never moves), the field is static and the answer is always 0 — so a
+ * legally-static drift config isn't rebucketed, and re-rastered, ten times a
+ * second for nothing.
+ */
+declare function fieldSampleTime(cfg: Pick<FieldBackground, 'drift'>, t: number): number;
+/**
+ * The scalar field at short-side coordinates `(u, v)` and time `t` (ms),
+ * 0..1. `seed` is the spec's seed; `cfg.seed` overrides it. Pure — no state,
+ * no RNG stream, so the same inputs give the same value in every call on
+ * every platform.
+ */
+declare function fieldAt(u: number, v: number, t: number, cfg: FieldBackground, seed: number): number;
+/** `#rgb` / `#rrggbb` → integer channels 0..255. Malformed input reads as mid grey. */
+declare function hexToRgb255(hex: string): [number, number, number];
+/** Perceptual luma (0..1) of integer RGB — the same weights `hexLuma` uses, so a band's luma matches its hex's. */
+declare function rgb255Luma(rgb: readonly [number, number, number]): number;
+/**
+ * The colour a field value paints: `quantize ≥ 2` posterises the value into
+ * that many levels and reads each level off the `bands` ramp (`quantize ===
+ * bands.length`, the default, is exactly one band per level — hard, crisp
+ * contours); `quantize: 0` interpolates the ramp smoothly (Aura, Mist). A
+ * steered `quantize` gliding through fractions rounds to the nearest level
+ * count. Integer channels, so a quantised band is byte-exact its hex.
+ */
+declare function fieldRgb(value: number, bands: readonly string[], quantize: number | undefined): [number, number, number];
+/** The painted colour at short-side coordinates `(u, v)`: `fieldRgb(fieldAt(...))`. */
+declare function fieldRgbAt(u: number, v: number, t: number, cfg: FieldBackground, seed: number): [number, number, number];
+
+/** Grain tile side (px). Repeats across the frame. */
+declare const GRAIN_TILE = 256;
+/** Ordered-dither tile side (px): an 8×8 Bayer matrix. */
+declare const DITHER_TILE = 8;
+/** Composite alpha at `grain: 1`. */
+declare const GRAIN_ALPHA = 0.35;
+/** Composite alpha at `dither: 1`. */
+declare const DITHER_ALPHA = 0.25;
+/** Offset step rate under `animate: true`. */
+declare const FINISH_ANIMATE_HZ = 12;
+/** The clamped strengths a spec's finish resolves to (0 when absent). */
+declare function finishStrength(f: FinishSpec | undefined): {
+    grain: number;
+    dither: number;
+};
+/**
+ * RGBA pixels of the grain tile for `seed`: zero-mean grey noise (the sum of
+ * two lattice hashes — a triangular distribution, softer than uniform —
+ * centred on 128), alpha 255. Pure; the same seed gives the same tile on
+ * every platform.
+ */
+declare function grainTilePixels(seed: number): Uint8ClampedArray;
+/** The 8×8 Bayer ordered-dither matrix (values 0..63, recursively built). */
+declare function bayerMatrix(): number[][];
+/**
+ * RGBA pixels of the dither tile: the Bayer matrix as grey levels
+ * `(v + 0.5) / 64 × 255`, so the tile's mean is mid grey (zero-mean under a
+ * symmetric blend). A stylistic screen — it is composited at low alpha, not
+ * used to threshold the image per pixel.
+ */
+declare function bayerTilePixels(): Uint8ClampedArray;
+/**
+ * Where the grain tile sits for scene time `t`: fixed at the origin unless
+ * `animate`, in which case it steps to a seeded offset (0..255 per axis)
+ * once per 1/12 s bucket — a pure function of `(t, seed)`.
+ */
+declare function grainOffset(t: number, seed: number, animate: boolean): {
+    x: number;
+    y: number;
+};
+type ScreenOp = 'overlay' | 'soft-light' | 'multiply';
+/**
+ * The symmetric blend the finish composites with. `overlay` is what every
+ * shipping canvas2d implements; the readback detect exists for the odd
+ * context that rejects it (an assignment the context does not support leaves
+ * the previous value in place).
+ */
+declare function pickScreenOp(ctx: {
+    globalCompositeOperation: string;
+}): ScreenOp;
+type Canvas2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+type AnyCanvas = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * A presentation pass: the visible canvas and the tiles (as repeat
+ * patterns, created lazily and cached — patterns are bound to the context
+ * that made them). Owned by the instance that presents; the scene itself is
+ * drawn on a separate canvas that this pass copies from.
+ */
+interface FinishPass {
+    canvas: AnyCanvas;
+    ctx: Canvas2D;
+    op: ScreenOp;
+    grain: CanvasPattern | null;
+    dither: CanvasPattern | null;
+    /** Seed the grain tile was generated for. */
+    seed: number;
+}
+/** Open a presentation pass on `visible`; null if it has no 2d context. */
+declare function createFinishPass(visible: AnyCanvas, seed: number): FinishPass | null;
+/** A fresh scene canvas for the instance to draw into (never attached to the DOM). */
+declare function createSceneCanvas(width: number, height: number): AnyCanvas;
+/**
+ * Copy `scene` onto the pass's canvas and screen the finish over it:
+ * grain at `grain × 0.35` (tile offset per `grainOffset`), then dither at
+ * `dither × 0.25`, both with the pass's blend op and no image smoothing (a
+ * crisp screen). With nothing to apply it is a plain copy. `w`/`h` are the
+ * logical size the context transform maps to the canvas. `seed` is the
+ * effective seed the *current* finish resolves to — a sequence with a
+ * segment-level finish can present a different seed per frame (one segment
+ * to the next); it defaults to the pass's own seed, so a single-scene
+ * caller (whose seed never changes) can omit it. The cached grain pattern
+ * is rebuilt whenever the seed changes.
+ */
+declare function presentWithFinish(fp: FinishPass, scene: AnyCanvas, w: number, h: number, t: number, finish: FinishSpec | undefined, animateAllowed: boolean, seed?: number): void;
+
 interface ResolvedSegment {
     index: number;
     localT: number;
@@ -1582,6 +1894,53 @@ declare function segmentRenderSeed(seq: IdleSequence, index: number): number | u
  * `SpecInstance`. `undefined` when there's no bed or no derivable seed.
  */
 declare function bedRenderSeed(seq: IdleSequence): number | undefined;
+/**
+ * Whether any scene in the sequence — the sequence itself or any segment —
+ * declares a `finish`. Mirrors `SequenceInstance`'s construction-time check:
+ * a finish anywhere allocates the presentation pass for the instance's whole
+ * lifetime, so this is also what `sequenceSwapCompatible` must agree on
+ * before and after a swap.
+ */
+declare function sequenceWantsFinish(seq: IdleSequence): boolean;
+/**
+ * Whether a republished sequence can be swapped into a live
+ * `SequenceInstance` in place of `prev` without a remount
+ * (`SequenceInstance.hotSwapSequence`). True only when every part of the
+ * running instance that is fixed at mount — or that a running clock is
+ * measured against — is unchanged:
+ *
+ * - the same number of segments;
+ * - every segment's scene is a structural twin (`structuralSignature`) of
+ *   its counterpart, so the live child's entities survive a `hotSwapSpec`;
+ * - the same render seed per segment (`segmentRenderSeed`) — a child's seed
+ *   is fixed at construction, so a changed seed could only take effect at
+ *   the next boundary, leaving the room half-swapped;
+ * - a `bed` on both sides or neither, structural twins with the same seed
+ *   when present;
+ * - the same top-level `seq.seed`, compared normalized (like the mount-time
+ *   seed itself) so a change of an exact multiple of 2^32 isn't flagged —
+ *   even when every segment and the bed resolve their own seed (so
+ *   `segmentRenderSeed`/`bedRenderSeed` are unaffected), a sequence-level
+ *   `finish` grain resolves against the instance's mount-time seed
+ *   (`frameFinishSeed`), which a swap cannot update;
+ * - the same finish presence (`sequenceWantsFinish`) — the presentation
+ *   pass is allocated once at construction, so a swap that adds or removes
+ *   every `finish` in the sequence cannot (de)allocate it;
+ * - the same `loop` and `sync` (absent `sync` is `'mount'`);
+ * - the same `duration`, `advance` (absent is `'auto'`) and `transition`
+ *   (absent is `cut`; `text` on a morph defaults to `'step'`) on every
+ *   segment. Durations move segment boundaries under a clock that keeps
+ *   running, and `clockOffset`/`releasedBelow` on the instance are measured
+ *   in that timeline — so a timing edit is a remount for now.
+ *
+ * Paint stays free: colours, words, `background`, `ghosting`, ids and
+ * labels, segment keys. Layer `alpha` is a per-entity range baked at build
+ * time (like `size`), so it is already covered by the structural twin check
+ * above and is not free — an alpha-only edit correctly falls back to a
+ * remount. Mirrors idle-server's `sequenceSignaturesEqual` precondition and
+ * adds the timing terms.
+ */
+declare function sequenceSwapCompatible(prev: IdleSequence, next: IdleSequence): boolean;
 
 /**
  * Reproduces the hand-coded Fish Aquarium saver as pure DATA — the discriminating test
@@ -1761,6 +2120,171 @@ declare const PROCESSION_SPEC: SaverSpec;
  */
 declare const WARP_TUNNEL_SPEC: SaverSpec;
 
+/**
+ * Thermal Field: the `field` background — seeded, domain-warped value noise
+ * posterised into six riso inks (`quantize: 6`, one hard band per level) and
+ * drifting once every forty seconds, so the contours crawl like a weather
+ * chart. The foreground is deliberately almost nothing: a handful of pale
+ * motes screened over the bands, so the ground IS the piece. A house
+ * `thermal` look; the same field with `quantize: 0` is a smooth aura. A
+ * `finish` of grain and dither screens the whole frame like a riso print.
+ */
+declare const THERMAL_FIELD_SPEC: SaverSpec;
+
+/**
+ * Sparse Night — emptiness, declared as intent.
+ * A star-grain field (radius under 0.001 — the rung FORMAT.md's ladder calls
+ * texture, never the subject) over near-black, one faint linked pentagon as
+ * the only figure, and a single satellite that flares for three seconds out of
+ * every eighteen. Measured coverage sits around one percent, which `adviseSpec`
+ * would flag as `sparse-scene` at every legal count — the spec's
+ * `density: 'sparse'` declaration is the point of this example: it withholds
+ * that advisory AND opts the scene into `density-mismatch` instead, so the
+ * emptiness is a claim the perception API checks rather than a gap it nags
+ * about. Before `density` shipped, restraint like this could not pass advise
+ * clean; the one-mark house style sat at the suite floor for exactly this
+ * reason.
+ */
+declare const SPARSE_NIGHT_SPEC: SaverSpec;
+
+/**
+ * Typed Cue — textBlock.reveal, both moods.
+ * Two self-typing captions over near-black. The upper one types at ten
+ * graphemes a second with a blinking caret (`mode: 'typewriter'` — the classic
+ * terminal reveal; `speed` makes progress a pure function of scene time, so
+ * every viewer types the same line on the same clock from its own mount). The
+ * lower one arrives as a wave of overlapping fades (`mode: 'glyphFade'`,
+ * `fade: 0.4` — each glyph ramps in over 40% of the progress window, which
+ * reads as a soft dissolve rather than typing) and carries no caret. Both
+ * blocks declare `opacity` so the path is steerable, and layout always runs on
+ * the FULL text — reveal only masks glyphs, so lines never reflow mid-type.
+ *
+ * Trap, documented in the playbook and true here too: at t = 0 a self-typing
+ * block has typed nothing, so `previewScene` at the default instant looks
+ * empty — preview at t ≥ 10 s to see the words. To swap the line live, glide
+ * `reveal.progress` to 0, step the `text`, glide back (one `setTrack` call).
+ *
+ * The scan band is the one non-text layer, and it is load-bearing twice over:
+ * a screensaver of two static text blocks is a document, not a screensaver
+ * (`text-heavy`), and the band gives the words something to sit on — a slow
+ * refresh sweep passing under the type. Note the units: `perceiveScene` takes
+ * `t` in MILLISECONDS while the MCP `previewScene` tool takes seconds (the
+ * worker converts); passing seconds to the library reads as a block that
+ * never finishes typing.
+ */
+declare const TYPED_CUE_SPEC: SaverSpec;
+
+/**
+ * Signal Board — the instrument panel, laid out by the format.
+ * A 3×3 table of data bars with their labels in a matching table, one
+ * monospace caption, and a phosphor sweep crossing the frame every ~90
+ * seconds. The teaching layer is `layout: { type: 'table', columns: 3 }`:
+ * nine bars and nine labels are TWO layers, not eighteen positioned blocks —
+ * entity i reads `values[i]` / `strings[i]` in reading order, and each bar
+ * draws `length × values[i] / max` from its cell. `values` are paint, so
+ * `setParam("readout.sprite.values", [...])` glides every bar at once, which
+ * is the whole point of the shape: a live readout that never re-publishes.
+ */
+declare const SIGNAL_BOARD_SPEC: SaverSpec;
+
+/**
+ * Phase Duet — three layers on one clock.
+ * A grid of sixty dots ripples as a traveling wave (`pulse.wave`), three rings
+ * swell, and one soft heart breathes — and none of them drift apart, because
+ * all three declare the same `clock`. `clock` is the format's answer to
+ * coincidence: without it, `pulse`, `grow` and `cycle` run on per-entity
+ * seeded phases, so two layers with the same period never line up (they are
+ * a room full of people, not a duet). With one shared `clock: { phase: 0,
+ * rate: 1 }` they breathe in step and stay there — period ÷ rate must stay
+ * ≥ 1000 ms, which is why every layer here runs a 6000 ms cycle.
+ */
+declare const PHASE_DUET_SPEC: SaverSpec;
+
+/**
+ * Web Work — a randomised graph that fades with distance.
+ * Forty-four drifting nodes wired `mode: 'random'` (a fixed deterministic
+ * wiring, not k-nearest — the difference is topology: nearest gives
+ * crystalline clusters, random gives a web that crosses itself) with
+ * `falloff: true`, so an edge's alpha fades toward `maxDist` instead of
+ * popping in at the cutoff. The second layer is a row of `orient: true`
+ * strokes: the mark's +x axis turns to follow the entity's heading, so each
+ * one reads as a wind tick rather than a stamp. Both are the difference
+ * between "lines between dots" and a drawing.
+ */
+declare const WEB_WORK_SPEC: SaverSpec;
+
+/**
+ * Shard Fall — tumbling shapes and a passing shadow.
+ * Two features nothing else here uses. `rotate` is STATIC per-entity rotation
+ * (a range seeded per entity), which is not the same as `spin: [0, 0]` — a
+ * zero spin speed renders the seeded start angle as 0, so "tilted but not
+ * turning" was previously inexpressible; here the shards are thrown at
+ * `rotate: [-180, 180]` AND tumbling on their own `spin` range, so no two
+ * facets agree on an angle. The shadow layer demonstrates `blend:
+ * 'multiply'`: two large soft discs darkening a pale plate as they wander,
+ * which is how the format does shadow and silhouette — `lighter` adds light,
+ * `multiply` removes it, and neither needs a sprite that looks like darkness.
+ * The polygons use `points` (unit coordinates scaled by `radius`), which are
+ * paint, so two shards with the same point count will morph into each other.
+ */
+declare const SHARD_FALL_SPEC: SaverSpec;
+
+/**
+ * Murmur — a flock with no birds in it.
+ * Six hundred and twenty entities: two registers of streaks (260 each) on
+ * harmonic `wander` with `coherence` near 1, so each layer folds and wheels as
+ * one body, and a static grain layer behind them. Nothing here
+ * interacts — no entity reads another's position — which is the trick the
+ * format is built on: a shared harmonic set plus a wide speed range reads as
+ * a murmuration while staying a pure function of (seed, t), so it replays
+ * identically and seeks instantly. `density: 'dense'` is doing real work:
+ * past 500 entities `adviseSpec` raises `dense-scene`, and the declaration
+ * says the crowding is the subject rather than a mistake — while still opting
+ * into `density-mismatch` if the scene ever measures as empty instead.
+ */
+declare const MURMUR_SPEC: SaverSpec;
+
+/**
+ * Three Movements — one ground, three scenes, two kinds of transition.
+ *
+ * The sequence envelope, exercised end to end:
+ *
+ * - **bed.** A drifting field with a few motes, drawn under every segment on
+ *   the SEQUENCE clock — it does not reset at a boundary and a
+ *   `sequence.segment` steer cannot rewind it. That is the fix for the
+ *   boundary rewind every ambient sequence suffers: put the motion that must
+ *   be continuous in the bed, the slide content in the segments. (Segments
+ *   deliberately declare no `background`: over a bed it is never painted on
+ *   the web, and the validator warns `bed-hides-segment-background` — the
+ *   native tvOS player, which ignores the bed, will show them over black
+ *   until it learns the field. Prefer a bed the piece can survive without.)
+ * - **morph + text crossfade.** Segments 1 → 2 are structural twins differing
+ *   only in colour and words, so the transition can MORPH: every numeric and
+ *   hex value glides over 2500 ms, and because the words differ and the
+ *   transition declares `text: 'crossfade'`, the outgoing caption fades under
+ *   the incoming one instead of switching whole-frame. Without the crossfade
+ *   declaration a morph steps strings on its first frame — it reads as a cut
+ *   and the validator says `morph-nothing-morphable`.
+ * - **fade.** Segments 2 → 3 have nothing structurally in common, so a morph
+ *   is impossible and a `fade` is the honest transition: the outgoing scene
+ *   keeps animating on its own canvas for 3000 ms while the incoming one
+ *   fades up. The cost is two live segments during the window, which is why
+ *   the lowest capability tier degrades a fade to a cut
+ *   (`fade-degrades-on-low-tier` — informational, and this sequence keeps the
+ *   fade because the web and native players both honour it).
+ * - **finish.** One grain-and-dither pass over the composed frame — bed,
+ *   segment and any fade together — the sequence-level screen no segment can
+ *   override.
+ *
+ * The final segment carries no duration, so it holds indefinitely; `loop` is
+ * therefore false (`loop: true` is incompatible with a durationless segment).
+ * `sync: 'mount'` is the default and the reason a joiner always sees movement
+ * one: pre-roll semantics. An `epoch` sequence would instead start every
+ * viewer at the room's shared clock — right for a wall of screens, wrong for
+ * a piece that should start when you look at it.
+ */
+declare const THREE_MOVEMENTS_SEQUENCE: IdleSequence;
+
 /** Catalog entry for a bundled schema example. */
 interface SchemaExample {
     id: string;
@@ -1769,9 +2293,24 @@ interface SchemaExample {
 }
 /** Ordered catalog of bundled schema examples. Add new specs as standalone files, then register here. */
 declare const SCHEMA_EXAMPLES: readonly SchemaExample[];
+/** Catalog entry for a bundled idle-sequence example. */
+interface SequenceExample {
+    id: string;
+    label: string;
+    sequence: IdleSequence;
+}
+/**
+ * Ordered catalog of bundled idle-sequence examples.
+ *
+ * Deliberately separate from SCHEMA_EXAMPLES: that catalog is typed
+ * `SaverSpec[]` and its consumers (manifests, batch compile, the MCP examples
+ * resource) rely on that. A sequence is a different top-level format, so it
+ * gets its own list rather than widening theirs.
+ */
+declare const EXAMPLE_SEQUENCES: readonly SequenceExample[];
 /** All example specs in catalog order (tests, batch compile). */
 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, 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, LOBBY_TALK_SPEC, 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 PerceiveSequenceOptions, 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 SequenceFramePerception, type SequenceMountContext, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockAnchor, type TextBlockLine, type TextMetricsClass, type TextRevealInput, type TextRevealSpec, type TextRole, type TextSpriteInfo, type ValidationResult, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, type WarningBox, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, bedRenderSeed, breakTextBlock, buildEntities, canMorph, cohesionOf, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, graphemeClusters, headingAt, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, normalizeSeed, perceiveScene, perceiveSequenceFrame, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CapabilityTier, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, DITHER_ALPHA, DITHER_TILE, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, type Entity, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, type FieldBackground, type FieldDrift, type FinishPass, type FinishSpec, GRAIN_ALPHA, GRAIN_TILE, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, type LayerCohesion, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, MURMUR_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type PerceiveSequenceOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type ScreenOp, type SequenceExample, type SequenceFramePerception, type SequenceMountContext, type SequenceSaverInstance, type SequenceSaverPlugin, type SequenceSegment, type SequenceTransition, type SpecError, type SpecMountContext, type SpecWarning, type SpriteSpec, type SteerDelta, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, type TextBlockAnchor, type TextBlockLine, type TextMetricsClass, type TextRevealInput, type TextRevealSpec, type TextRole, type TextSpriteInfo, type ValidationResult, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, type WanderOsc, type WarningBox, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, canMorph, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, latticeHash, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rgb255Luma, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };