@idle-screens/schema 3.7.0 → 3.8.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,36 @@ 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 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 `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 +2103,17 @@ 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;
+
 /** Catalog entry for a bundled schema example. */
 interface SchemaExample {
     id: string;
@@ -1774,4 +2127,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, 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_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, 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 ScreenOp, 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, 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, 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, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };