@idle-screens/schema 3.11.1 → 3.12.1

package/FORMAT.md

@@ -192,8 +192,11 @@ exceeds 2 %, or a `dense` one that would have tripped `sparse-scene`, gets a
 
   **Steering.** Every numeric knob and every band is a paint path —
   `background.scale`, `background.warp`, `background.quantize`,
-  `background.bands.2`, `background.drift.amount` — and glides (a fractional
-  `quantize` or `octaves` mid-glide rounds). `background.seed` is not
+  `background.bands.2`, `background.drift.amount` — and glides. `quantize`
+  and `octaves` are level counts, so a glide (`setParam`, a `timeline` key, a
+  `morph`) steps through **whole** levels: the in-between value rounds, and a
+  `quantize` under 1.5 reads `0` (smooth) — so `quantize` 0 → 6 eases smooth,
+  then 2, 3 … 6 bands. Authored values must still be whole. `background.seed` is not
   steerable. The background is paint, not structure, so a `morph` between
   two field segments glides the field; a gradient → field morph steps
   (different shape).
@@ -269,7 +272,7 @@ own `finish` is not steerable; steer a segment's, or republish.
 
 | Field | Type | Default | Meaning |
 |---|---|---|---|
-| `count` | int 1..400 | — | entities in this layer |
+| `count` | int 1..400 | — | entities in this layer. **At most 800 entities across all layers** (and ≤ 36 layers): the validator rejects a spec whose counts sum past 800, and density scaling never takes a screen past it |
 | `sprite` | SpriteSpec | — | what each entity looks like |
 | `motion` | MotionSpec | — | how entities move |
 | `size` | `[min,max]` > 0 | sprite-dependent | font size for emoji/text; ignored for shaped sprites |
@@ -278,13 +281,13 @@ own `finish` is not steerable; steer a segment's, or republish.
 | `alpha` | `[min,max]` 0..1 | `[1,1]` | per-entity opacity range |
 | `blend` | `lighter` \| `screen` \| `multiply` | source-over | additive glow / gentle additive / darkening |
 | `region` | `{x?, y?}` ranges 0..1 | full viewport | fractional spawn window (placement only, not travel) |
-| `pulse` | `{amp ≤ 0.5, period ≥ 500, wave?}` | none | opacity breathing; `wave: {wavelength, angle?}` turns it into a traveling wave across the field |
-| `spin` | number \| `[min,max]` ±360 deg/sec | none | per-entity rotation (seeded start angle); a range gives each entity a seeded speed (confetti, tumbling debris). `[0, 0]` does **not** hold the seeded angle — a zero speed renders at 0; use `rotate` |
+| `pulse` | `{amp ≤ 0.5, period ≥ 500, wave?}` | none | opacity breathing: `amp` is **added** to the entity's `alpha` (alpha ± amp, clamped to 0..1), not a fraction of it — a dim layer (`alpha` 0.2, `amp` 0.3) swings through 0 and sits fully dark for part of every period; keep `amp` ≤ the alpha floor for a breath that never blacks out. `wave: {wavelength, angle?}` turns it into a traveling wave across the field |
+| `spin` | number \| `[min,max]` ±360 deg/sec | none | per-entity rotation (seeded start angle — drawn from the scene's one shared seeded stream, so it is reproducible for a given spec, seed **and viewport** but not a fixed per-entity value: density scaling changes how many entities draw before it, and declaring a `rotate` range adds a draw per entity, so either one changes the angles; use `rotate` for an angle you need to pin); a range gives each entity a seeded speed (confetti, tumbling debris). `[0, 0]` does **not** hold the seeded angle — a zero speed renders at 0; use `rotate` |
 | `rotate` | number \| `[min,max]` ±360 deg | none | **static** per-entity rotation: a scalar turns the whole layer, a range gives each entity a seeded angle (thrown blades, scattered glyphs, a tilted grid). Adds to `spin`'s start angle. Structural. **Native:** tvOS reads `spin` only ⇒ 0 |
 | `grow` | `{amp ≤ 0.8, period ≥ 500}` | none | size breathing (seeded phase) |
-| `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail; `length` is **milliseconds** of history (max 5000), `fade` a number 0..1 (not a boolean — `links.falloff` in the next row is the boolean) |
+| `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail; `length` is **milliseconds** of history (max 5000), `fade` a number 0..1 (not a boolean — `links.falloff` in the next row is the boolean). Echoes of a shaped sprite (`polygon`, `stroke`, `rect`, `ring`, `streak`, `bar`) are the sprite's own shape as it was then, shrinking toward the tail; `circle`, `emoji` and text trail discs. A hard `circle`'s trail is one continuous ribbon tapering behind it, so a quick path draws a line rather than a string of dots (a layer whose ribbons would cover more than a tenth of the screen draws its echo discs instead, to bound the cost); a `soft` circle's echoes are filled in where they would part, within a small per-layer budget |
 | `links` | see below | none | inter-entity lines |
-| `layout` | `{type: "grid", columns?, jitter?}` \| `{type: "list", gap?}` \| `{type: "table", columns, gap?}` | scatter | `grid`: cells fill `region`, `jitter` scalar or `{x?, y?}` 0..1 per axis. **`list` / `table`: data layouts** — entities in reading order from `position` (any count) or centred in `region`, `gap` apart (viewport units of `min(w,h)`, default 0.06); text/emoji take `strings[i]` / `glyphs[i]` and palettes `colors[i]` **in order**, so N labels are one layer |
+| `layout` | `{type: "grid", columns?, jitter?}` \| `{type: "list", gap?}` \| `{type: "table", columns, gap?}` | scatter | `grid`: cells fill `region`, `jitter` scalar or `{x?, y?}` 0..1 per axis. **`list` / `table`: data layouts** — entities in reading order from `position` (any count) or centred in `region`, `gap` apart (viewport units of `min(w,h)`, default 0.06; a number or `{x?, y?}`). **`gap` is the pitch between cell anchors, not the space between cells** — a label wider than the column pitch runs into its neighbour (the `layout-text-overlap` advisory names the gap that clears it), so size `gap.x` to the widest label. Text/emoji take `strings[i]` / `glyphs[i]` **in order**, so N labels are one layer; a shaped sprite's palette (`colors[i]` on `bar`, `rect`, `circle`…) is read in order too. **Text and emoji have no `colors`**: a `text` layer paints every label in its one `color` (a `colors` on it is an unknown property, ignored with a warning) — use one layer per label colour |
 | `life` | `{enter?, exit?, fade?}` ms | always on | act structure: fade the layer in at `enter`, out at `exit` |
 | `emit` | `{every ≥ 1000, life ≥ 500, jitter?, grow?}` (`life ≤ every`) | always lit | **sparse events**: each entity is dark except a `life`-ms window every `every` ms, fading in fast and out slow; `jitter` 0 staggers entities evenly (one event at a time while `life ≤ every / count`), 1 scatters the offsets (a fixed sequence, not seeded — declaring `emit` disturbs no other draw); `grow: [from, to]` scales size across the window — expansion rather than travel |
 | `clock` | `{phase?, rate?}` | seeded phases | **phase-lock**: `pulse`, `grow` and `cycle` share one phase (turns, 0..1) and run at `rate` × time; two layers with the same clock breathe in step. Clocked periods must satisfy `period / rate ≥ 1000` |
@@ -308,20 +311,24 @@ with distance, removing pop-in at the cutoff.
 - `{ "kind": "text", "strings": ["HELLO"], "color": "#e6e8ef", "font": "bold monospace", "align": "center", "baseline": "middle", "maxWidth": 300, "cycle": ..., "role": "read" }`
   — a `font` **with** a px size keeps that shorthand, its number rescaled to the
   viewport (verbatim only under `units: "px"`); a family/weight only
-  (`"bold monospace"`) composes with the seeded per-entity `size`; `role` is
+  (`"bold monospace"`) composes with the seeded per-entity `size` (faces
+  installed on the viewer only — see `font` under `textBlock`); `role` is
   the legibility opt-in described under `textBlock` below (same field, same
   meaning on both text sprites)
 - `{ "kind": "circle", "radius": [0.001, 0.003], "color": "#ffffff", "soft": true }` —
   `soft` renders a radial-falloff glow orb instead of a hard disc
 - `{ "kind": "ring", "radius": [0.002, 0.005], "color": "#d8f6ff", "width": 0.001 }` —
-  unfilled circle (bubbles, portals, sonar)
+  unfilled circle (bubbles, portals, sonar). The line is **centred on the
+  radius**: half of `width` falls inside, half outside, so the outer edge is
+  `radius + width / 2`
 - `{ "kind": "streak", "length": [0.01, 0.03], "color": "#cfd8ff", "width": 0.002 }` —
   a line oriented along the entity's analytic heading with a faded tail
   (rain that reads as rain, shooting stars, warp stars)
 - `{ "kind": "rect", "width": [0.012, 0.02], "aspect": [1.3, 1.7], "color": "#ffb347", "feather": 0.6 }` —
   rectangle; `aspect` is the height/width ratio range (rotates with `spin`);
   `feather` 0..1 softens the edges — that fraction of the half-size fades out
-  toward the border (Rothko's block at 0.5–0.8)
+  toward the border in one smooth linear falloff on each axis (Rothko's block
+  at 0.5–0.8)
 - `{ "kind": "bar", "values": [82, 64, 91], "max": 100, "length": 0.5, "thickness": 0.02, "color": "#17e8c8", "direction": "right" }` —
   a data bar: entity *i* draws `length × values[i] / max` (viewport units),
   `thickness` thick, growing from its position toward `direction` (`right`
@@ -334,14 +341,22 @@ with distance, removing pop-in at the cutoff.
   6); or `"points": [[-1, 0.9], [0.2, -1], [1, 0.4]]` — 3..24 unit
   coordinates in −1..1 scaled by the radius — for any facet (a Picasso shard,
   a Kandinsky triangle, a Mondrian plane). `soft` feathers the fill from the
-  centre. Rotates with `spin`. `points` are paint, so two polygons with the
-  same point count `morph` into each other
+  centre. Rotates with `spin`. The outline fills with the **nonzero** winding
+  rule: a self-crossing outline paints both lobes, and a hole needs its inner
+  loop traced in the **opposite** direction (a keyhole: outer ring clockwise,
+  then back round the hole counter-clockwise, joined by a zero-width slit). `points` are paint, so two polygons with the
+  same point count `morph` into each other — and a `setParam`, `timeline` key
+  or `morph` target for `sprite.points` is in the **same unit coordinates**,
+  scaled by each entity's seeded radius (not by the keyed shape's own extent):
+  keep every keyed point inside −1..1 (the validator rejects one outside), and
+  shrink a target shape by scaling its points, not by exceeding the box
 - `{ "kind": "stroke", "length": [0.08, 0.18], "points": [[-1, 0.3], [-0.5, -0.6], [0.3, -0.7], [1, 0.1]], "width": 0.004, "taper": true, "color": "#f2e8c9" }` —
   a freehand mark: a path through 2..24 unit-coordinate points, scaled so the
   unit box spans the seeded `length`, stroked `width` wide with round joins.
   `curve: "smooth"` (default) is a Catmull-Rom spline, `"linear"` a polyline;
   `taper` thins the mark to almost nothing at both ends (a brush stroke rather
-  than a line); `orient: true` turns the path's +x along the entity's heading,
+  than a line; it paints as one filled mark, so a translucent stroke has no
+  overlap beads); `orient: true` 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": "textBlock", "text": "Multi-line text with wrapping.", "maxWidth": 0.8, "fontSize": 0.04, "lineHeight": 1.4, "align": "left", "color": "#e6e8ef", "anchor": "top-left", "font": "system-ui, sans-serif", "opacity": 1 }` —
@@ -384,6 +399,12 @@ with distance, removing pop-in at the cutoff.
   advance so mono wraps land where the real face puts them; every other
   family uses the proportional table. Default `system-ui, sans-serif`.
   **Native clients fall back to the system face** until a face table exists.
+  `font` names faces **installed on the viewing device** — nothing is
+  bundled and no web font is fetched, so `'Inter'` only appears where Inter
+  is installed and every other screen falls through the stack. End every
+  stack in a generic `sans-serif`, `serif` or `monospace`; avoid ending on
+  `cursive` or `fantasy`, which resolve to a different (sometimes absurd)
+  face on every platform.
 
   `opacity` (0–1, default 1) multiplies the block's paint alpha — the whole
   block, on top of the layer's per-entity `alpha`. It is **paint**, not
@@ -471,13 +492,18 @@ and configured the second.
 - `{ "type": "bounce", "speed": [0.12, 0.24] }` — diagonal, reflecting off edges
 - `{ "type": "static" }` — stays exactly where placed (use with `position` for HUD text)
 - `{ "type": "orbit", "speed": [10, 40], "radius": [0.05, 0.2], "center": { "x": 0.5, "y": 0.5 } }`
-  — angular speed in deg/sec; `center` may instead be `{ "layer": "planet" }`
-  to orbit a single-entity parent layer (moons around a wandering planet;
-  strictly one level deep)
+  — angular speed in deg/sec; a **negative** speed orbits the other way
+  (counter-rotating rings, meshing gears); `center` may instead be
+  `{ "layer": "planet" }` to orbit a single-entity parent layer (moons around a
+  wandering planet; strictly one level deep — and the parent must have
+  `count: 1`)
 - `{ "type": "wander", "speed": [0.004, 0.012], "angle": 0, "meander": 0.1, "coherence": 0.7 }`
   — organic harmonic drift: base velocity plus 3 seeded sine octaves per axis.
   Flowing curved paths with zero simulation state. `meander` scales the
-  curvature; `coherence` 0..1 blends every entity toward a shared harmonic set
+  curvature (it is the harmonics' amplitude, so it also sets how fast an
+  entity sways — keep it ≤ ~0.015 for a slow drift); it is capped at
+  **0.463** (500 px ÷ `referenceViewport`, 1080 by default — 500 under
+  `units: "px"`), and the validator rejects anything above; `coherence` 0..1 blends every entity toward a shared harmonic set
   (1 = the layer undulates as one body — fake flocking)
 - `{ "type": "warp", "speed": [0.1, 0.5], "center": { "x": 0.5, "y": 0.5 } }`
   — perspective starfield: entities stream toward the viewer on a depth axis,
@@ -486,7 +512,10 @@ and configured the second.
 - `{ "type": "path", "points": [{"x":0.1,"y":0.7}, ...], "duration": 30000, "curve": "smooth", "closed": true, "scatter": 0.02 }`
   — choreographed spline (Catmull-Rom, or `linear`); 2..24 waypoints, lap time
   ≥ 2 s; `closed` loops (default), open paths ping-pong; `scatter` offsets
-  entities sharing the path; each entity gets a seeded phase along it
+  entities sharing the path (**must be > 0** — omit it for an exact path
+  rather than writing `0`); each entity gets a seeded phase along it. A single
+  entity cannot show a curve — use `count` ≥ 12 (plus `trail`/`ghosting`) to
+  make the whole path read
 
 All speeds are ranges; each entity draws its own value (seeded).
 
@@ -697,7 +726,9 @@ its drift, orbit and pulse run on (from mount; a sequence segment's `localT`):
 ```
 
 - A key glides `path` from wherever it is at `t` to `value` over `dur` ms
-  (default 1000, the live-steer default; `0` is a cut), eased `smooth`
+  (default 1000, the live-steer default; `0` is a cut; at most 30000 — a
+  longer `dur` fails validation for the whole spec, so split a slower glide
+  into consecutive keys of ≤ 30 s each), eased `smooth`
   (default), `linear` or `step` (holds, then switches at the glide's end).
   Keys address the same dot-paths as `setParam` — index or `key` form — and a
   path must already exist on the spec (a key cannot add a field). The spec must
@@ -853,11 +884,14 @@ moves and scales its positions and sizes (sprite rotation is not modelled).
   its own × its group's — is 0 in the base scene and at every key boundary of
   its `timeline` never shows, so it is not judged and its entities do not count
   toward `dense-scene`; coverage is weighed by paint opacity) (also on
-  `perceiveScene().advisories`). Two of them are **spatial**, for static text:
+  `perceiveScene().advisories`). Three of them are **spatial**, for static text:
   `text-off-screen` (a text/textBlock box crosses the viewport edge by more
-  than 1%) and `text-overlap` (two static text layers share more than 10% of
+  than 1%), `text-overlap` (two static text layers share more than 10% of
   the smaller box; it carries both boxes as `boxes: [{x, y, w, h}]` in
-  viewport fractions so the fix needs no re-derivation). Boxes come from the
+  viewport fractions so the fix needs no re-derivation) and
+  `layout-text-overlap` (two cells of one `list`/`table` layer do — its
+  `gap` pitch is narrower than its labels; the message names the `gap` that
+  clears them, and it carries the two boxes too). Boxes come from the
   same character-class width table the textBlock line-breaker uses, so they
   are estimates of the renderer's own layout — a caption that fails these
   will look wrong on the wall; one that passes may still sit a few px off.
@@ -891,6 +925,27 @@ is estimated from font size × string length. Good enough to perceive
 composition, focus, balance, and motion — not a substitute for a human (or VLM)
 judgement of beauty.
 
+**Motion comes in both units.** `motion[].meanSpeed` / `maxSpeed` are px per
+second at the perceived size; `meanSpeedVp` / `maxSpeedVp` are the same speeds
+in viewport units per second (fractions of `min(w,h)` — the unit specs are
+authored in), which do not change with the preview size; `1.0` crosses the
+short side of the screen every second. `moving` is judged in viewport units,
+so it gives the same answer at every size. Each layer also carries `heading` (screen degrees: 0 right, 90 down) and
+`headingSpread` (0 = a conveyor, everything moving the same way — the
+"screen-wipe" to avoid; 1 = scattered). Sampling a centroid over time gives the
+WRONG sign for a wrapping full-viewport scatter, which is why heading is
+reported directly.
+
+**Colour is its own channel.** `perceiveScene(...).colour` and
+`diffScenes(...).colour` carry the hue / saturation / warmth (red minus blue,
+−1 cold … 1 warm) of the alpha × area weighted sprite mass and of the
+background plate. Judge "warmer / cooler" on `colour.warmthDelta`, not on
+`meanLuminance` — plausible cool tones weigh MORE under luma than the reds they
+replace, so a calming edit pushes luminance up. `diffScenes` also reports a
+`motion` channel (overall and per-layer speed deltas with headings) and
+advises at the diff's own viewport, so its `advisories.added/removed` agree
+with `adviseSpec` at that size.
+
 ## Sequence envelope (`idle-sequence`)
 
 A second top-level format that composes multiple SaverSpecs into a sequenced

package/dist/index.d.ts

@@ -992,6 +992,25 @@ declare function assertValidSpec(spec: unknown): SaverSpec;
 declare function validateSequence(seq: unknown): ValidationResult;
 declare function assertValidSequence(seq: unknown): IdleSequence;
 
+/**
+ * The two scale factors every entity builder must agree on, computed in ONE
+ * place. `scale` turns viewport-unit dimensions into px (1 for `units: "px"`,
+ * min(w,h) otherwise — the default is viewport, so an omitted `units` scales);
+ * `countScale` thins or thickens scatter density against `referenceViewport`
+ * and is clamped so the projected total never exceeds LIMITS.maxTotal.
+ *
+ * Four callers (compile, perceive, advise, describe) each carried their own
+ * copy of this arithmetic and they drifted twice: describeScene inverted the
+ * units default and built every shipped example at scale 1 (F48), and
+ * advise/describe skipped the maxTotal clamp so above ~4.6K they measured a
+ * scene the renderer never draws — and because the RNG stream is shared across
+ * layers, one early layer's different count shifts every later layer's
+ * positions too (F49).
+ */
+declare function entityScales(spec: SaverSpec, w: number, h: number): {
+    scale: number;
+    countScale: number;
+};
 /** Near plane for warp motion. z lives in [WARP_NEAR, 1]; screen scale is 1/z. */
 declare const WARP_NEAR = 0.08;
 /** Cap on the 1/z size multiplier so near stars don't blow out. */
@@ -1360,7 +1379,8 @@ declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): Saver
 /**
  * Interpolate between two structurally-similar specs at progress k (0..1).
  * Numbers lerp, hex colours lerp per channel, everything else steps to the
- * target immediately (k > 0). Layer counts round to integers.
+ * target immediately (k > 0). Layer counts, and a field background's
+ * `octaves` / `quantize`, round to whole values.
  */
 declare function lerpSpec(from: SaverSpec, to: SaverSpec, k: number): SaverSpec;
 /**
@@ -1694,10 +1714,32 @@ declare function layerCohesion(spec: SaverSpec, opts?: PerceiveOptions): LayerCo
 interface LayerMotionStats {
     layerIndex: number;
     key: string | undefined;
-    /** Mean / max on-screen speed in px per second (wrap jumps excluded). */
+    /** Mean / max on-screen speed in px per second at the perceived size (wrap jumps excluded). */
     meanSpeed: number;
     maxSpeed: number;
+    /**
+     * The same speeds in **viewport units per second** — fractions of
+     * min(w, h), the unit a spec's `speed` is authored in — so they do not
+     * change with the size the scene is perceived at. 1.0 crosses the short side
+     * of the screen every second.
+     */
+    meanSpeedVp: number;
+    maxSpeedVp: number;
+    /** meanSpeedVp above MOVING_FLOOR — the same answer at every preview size. */
     moving: boolean;
+    /**
+     * Direction the layer's mass is going, in screen degrees (0 = right,
+     * 90 = down, 180 = left, 270 = up), or null when nothing moves. Sampling a
+     * centroid over time gives the WRONG sign for a wrapping full-viewport
+     * scatter, which is why this is reported directly.
+     */
+    heading: number | null;
+    /**
+     * 0 = every entity moves the same way (a conveyor — the "screen-wipe" the
+     * schema warns about), 1 = headings cancel out (a scatter, an orbit, a
+     * bounce field). |mean unit vector| inverted.
+     */
+    headingSpread: number | null;
 }
 /**
  * Per-layer displacement between t and t+dt — choreography as numbers.
@@ -1711,6 +1753,34 @@ interface LayerMotionStats {
 declare function motionStats(spec: SaverSpec, opts?: PerceiveOptions & {
     dt?: number;
 }): LayerMotionStats[];
+interface SceneColour {
+    /** Hue of the visible sprite mass in degrees (0 red, 120 green, 240 blue), null when unsaturated. */
+    hue: number | null;
+    /** HSL saturation 0..1 of the sprite mass. */
+    saturation: number;
+    /** red minus blue of the mean sprite colour, -1 (cold) .. 1 (warm). The "cooler/warmer" axis. */
+    warmth: number;
+    /** Mean sprite colour as hex, for a model that reads hex better than angles. */
+    hex: string;
+    /** The same three numbers for the background plate. */
+    background: {
+        hue: number | null;
+        saturation: number;
+        warmth: number;
+        hex: string;
+    };
+}
+/**
+ * What colour the scene IS — the alpha × area weighted mean of every hex a
+ * sprite paints with, beside the background plate. A luminance map cannot
+ * carry this: a luma-matched red→cyan swap moves every other channel by
+ * ~0.001 (comprehension eval 2026-07-28, P2 F3), and `meanLuminance` reads
+ * plausible cool tones as *brighter* than the reds they replace, so "make it
+ * cooler" pushed the only number an agent had in the wrong direction. Emoji
+ * carry their own palette and are excluded; a scene of only emoji reports the
+ * background.
+ */
+declare function sceneColour(spec: SaverSpec, opts?: PerceiveOptions): SceneColour;
 declare const REGION_NAMES: readonly ["top-left", "top-center", "top-right", "mid-left", "center", "mid-right", "bottom-left", "bottom-center", "bottom-right"];
 interface SceneDiff {
     t: number;
@@ -1744,6 +1814,44 @@ interface SceneDiff {
         shareA: number;
         shareB: number;
     }>;
+    /**
+     * The hue channel. `hueShift` is the signed shortest rotation A→B in
+     * degrees; `warmthDelta` is the cooler/warmer axis (negative = B is cooler)
+     * — read THIS for "cooler", not `meanLuminance`, which weights cool tones
+     * brighter than the reds they replace.
+     */
+    colour: {
+        a: SceneColour;
+        b: SceneColour;
+        hueShift: number | null;
+        saturationDelta: number;
+        warmthDelta: number;
+        background: {
+            hueShift: number | null;
+            warmthDelta: number;
+        };
+    };
+    /**
+     * The motion channel, in viewport units per second. `overall` is the
+     * entity-weighted mean across layers; `layers` lists every layer whose speed
+     * changed, largest change first. Halving every speed used to leave the diff
+     * bit-identical (comprehension eval 2026-07-28, P2 F4).
+     */
+    motion: {
+        overall: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        layers: Array<{
+            key: string;
+            a: number;
+            b: number;
+            delta: number;
+            headingA: number | null;
+            headingB: number | null;
+        }>;
+    };
     advisories: {
         added: string[];
         removed: string[];
@@ -1778,6 +1886,8 @@ interface ScenePerception {
     motion: LayerMotionStats[];
     /** Per layer: merged silhouette, seamed overlap, or separate marks. */
     form: LayerCohesion[];
+    /** What colour the scene is — hue/saturation/warmth of the sprite mass and the plate. */
+    colour: SceneColour;
     /** Literal strings + sizes of any text layers (glyphs don't show in the maps). */
     text: TextSpriteInfo[];
     advisories: ReturnType<typeof adviseSpec>;
@@ -2568,4 +2678,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 CapabilityTier, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, DEFAULT_KEY_DUR, 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 LayerGroup, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LayerTransform, 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 Timeline, type TimelineKey, 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, canWrapMorph, canonicalSpecPath, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, latticeHash, layerCohesion, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, validateSequence, validateSpec, validateSpecPaths, withoutTimeline };
+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, DEFAULT_KEY_DUR, 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 LayerGroup, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LayerTransform, 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 SceneColour, 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 Timeline, type TimelineKey, 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, canWrapMorph, canonicalSpecPath, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, entityScales, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, latticeHash, layerCohesion, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, sceneColour, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, validateSequence, validateSpec, validateSpecPaths, withoutTimeline };