@idle-screens/schema 3.11.1 → 3.12.0

package/FORMAT.md

@@ -471,9 +471,11 @@ 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
@@ -486,7 +488,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 +702,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
@@ -891,6 +898,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. */
@@ -1694,10 +1713,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 +1752,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 +1813,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 +1885,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 +2677,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 };