@idle-screens/schema 3.9.1 → 3.11.0

package/FORMAT.md

@@ -42,7 +42,11 @@ the `fade` transition, `role` on text sprites, and `text: 'crossfade'` on
 `morph` (2026-09-08 — ambient presentations); `background: { type: 'field' }`
 (seeded, warped noise quantised into bands), the static per-entity
 `rotate`, and the print `finish` (grain + dither screen, spec- and
-sequence-level) (2026-09-10 — the print look).
+sequence-level) (2026-09-10 — the print look); `timeline` (keyframes on the
+scene's own clock), paint-level layer `opacity` and `transform`,
+`position.dx` / `dy`, `wrapMorph` on the sequence envelope and
+`text: 'dip'` on `morph` (2026-09-25 — timed scenes); layer `groups` and
+`transform.origin` (2026-09-26 — groups and origin).
 
 ## Safety invariants
 
@@ -107,7 +111,9 @@ must exist, have `count: 1`, and not themselves orbit a layer.
   "ghosting": 0.9,               // optional 0..0.95; frame-persistence smear
   "finish": { "grain": 0.5, "dither": 0.3 },  // optional; print screen over the finished frame
   "background": { ... },         // optional; defaults to black
-  "layers": [ { ... }, ... ]     // 1..36, rendered back-to-front
+  "layers": [ { ... }, ... ],    // 1..36, rendered back-to-front
+  "timeline": { ... },           // optional; authored keyframes — see **Timeline**
+  "groups": { "moon": { ... } }  // optional; named paint groups — see **Groups**
 }
 ```
 
@@ -283,7 +289,10 @@ own `finish` is not steerable; steer a segment's, or republish.
 | `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` |
 | `key` | string | none | addressable name → `setParam("key.count", …)` for a layer field, `setParam("key.sprite.color", …)` for a sprite field (the path mirrors the JSON: sprite fields sit under `sprite`) |
-| `position` | `{x, y}` 0..1 | none | exact placement; **requires `count: 1`** — except with a `list`/`table` layout, where it anchors the block's top-left; overrides `region` |
+| `position` | `{x, y, dx?, dy?}` — `x`/`y` 0..1, `dx`/`dy` ±2 (±17280 px under `units: "px"`) | none | exact placement; **requires `count: 1`** — except with a `list`/`table` layout, where it anchors the block's top-left; overrides `region`. `dx`/`dy` offset the point in **`min(w, h)` units** (px under `units: "px"`): `x`/`y` are fractions of width and height while every size is a fraction of `min(w, h)`, so parts placed at computed fractions only register at the aspect they were computed for — anchor a compound form's parts on one shared fraction (the centre is the only aspect-safe one) and offset each with `dx`/`dy`. Placement (structural). **Native:** tvOS ignores the offset |
+| `opacity` | number 0..1 | `1` | **paint-level** layer opacity: multiplies every entity's `alpha` and the `life` envelope at draw time. Unlike `alpha` (a range baked into each entity), it is outside the structural signature, so `setParam`, a `timeline` key or a `morph` **glides** it instead of re-seeding the layer. `0` skips the layer. **Native:** ignored ⇒ 1 |
+| `transform` | `{x?, y?, scale?, scaleX?, rotate?, origin?}` | identity | **paint-level** transform of the whole layer, about the viewport centre — or, with `origin: "anchor"`, about the layer's own anchor (its `position` point with `dx`/`dy`; a `list`/`table` block's anchor; without `position`, the centre of its `region`), so a word scales **in place** on every aspect (`origin` is an enum: not a steer or key target, and it steps across a morph — keep one origin per layer): translate `x`/`y` (±2 in `min(w, h)` units; px under `units: "px"`, ±17280), `rotate` (degrees, ±3600), `scale` (0..8) and `scaleX` (±8, × `scale` horizontally — toward 0 reads as a turn about the vertical axis, negative mirrors). Outside the structural signature: a camera for a timed piece, a slow drift for an ambient one, and it glides under steering. Sprites are not re-rasterised, so a large `scale` enlarges pixels of soft sprites, not detail. **Native:** ignored ⇒ identity |
+| `group` | string | none | the name of a `groups` entry this layer paints through — see **Groups**. **Native:** ignored |
 
 `links`: `{ k: 1..8, maxDist, color?, alpha?, width?, mode?, falloff?, closed? }`.
 `mode: "nearest"` (default) wires each entity to its k nearest neighbors within
@@ -663,6 +672,119 @@ control-track (`step` | `linear` | `smooth`). Placement/motion changes trigger
 a deterministic rebuild (same seed → same stream). See `@idle-screens/core`
 for `ControlTrack` and the idlescreens.com MCP `setParam` tool.
 
+Paths that are **paint** (colours, `alpha` inside a sprite's paint, layer
+`opacity` / `transform`, `textBlock.opacity`, `reveal.progress`, polygon
+`points`) glide; paths that are **structure** (`count`, `position`, `motion`,
+`size`, `layer.alpha`, …) rebuild — a deterministic re-seed, which reads as a
+pop. Prefer `opacity` over `alpha` and `transform` over `position` for
+anything that should move smoothly.
+
+## Timeline — keyframes on the scene's clock
+
+A SaverSpec can carry authored change on its **own** clock — the same clock
+its drift, orbit and pulse run on (from mount; a sequence segment's `localT`):
+
+```jsonc
+"timeline": {
+  "loop": true,             // optional; repeat every `duration` ms
+  "duration": 16000,        // required with loop; > the latest key's t
+  "keys": [                 // 1..256
+    { "t": 400,  "path": "sun.transform.y", "value": 0, "dur": 5200 },
+    { "t": 6000, "path": "title.opacity",   "value": 1, "dur": 1400, "ease": "linear" },
+    { "t": 11000, "path": "title.opacity",  "value": 0, "dur": 1200 }
+  ]
+}
+```
+
+- 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), `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
+  still validate with each key's value applied.
+- Overlapping keys on one path chain: the later glide starts from the earlier
+  one's in-flight value.
+- Without `loop`, a path holds the base spec's value before its first key and
+  its last key's value after it. With `loop`, the value depends only on
+  `t mod duration`, and **before a path's first key it has its last key's
+  value** — each lap is one closed cycle, lap 7 looks exactly like lap 1.
+- **Flash safety:** distinct key times on one path sit ≥ 200 ms apart
+  (across the loop wrap too). Keys on different paths may share a beat.
+  Keys are also checked **together**: two keys that are each valid can
+  combine past a floor (a `clock.rate` and a `pulse.period` share one), so
+  the validator resolves the scene at every key's start, end and glide
+  quarter-points and rejects it there.
+- A key on a **structural** path rebuilds the scene at that key — a pop, and
+  the validator warns `timeline-structural-key`. Animate paint: colours,
+  `opacity`, `transform`, polygon `points` (a whole equal-length array
+  lerps point by point), `reveal.progress`. A glide that runs past a loop's
+  lap warns `timeline-glide-overruns-lap`.
+- A timeline is **frame-addressable**: the scene at `t` is a pure function of
+  `(spec, t)`, so seeks, ghosting warm-ups and perception all resolve it at
+  their own time. `resolveTimelineAt(spec, t)` returns the plain spec at `t`
+  (the same object when there is no timeline).
+
+**Steering a scene with a timeline** — live steering layers on top, and the
+rule falls out of the scene itself, no mode flag:
+
+- a steer on a path **no key touches** is a sticky override — exactly today's
+  behaviour on an ambient scene;
+- a steer on a path the **timeline animates** holds until that path's next
+  key, then glides back to the timeline over that key's `dur` — from
+  wherever the steer's own glide had reached, if the key arrives mid-glide.
+
+A steer is rejected, as on any scene, when the scene it makes is invalid —
+judged with every live steer applied, now and at each key still ahead (a
+sticky steer outlives the keys).
+
+A channel's control track is not a timeline: its `t` is a wall-clock stamp the
+server writes, so it is never read as a schedule. Authored time lives here.
+
+Each steer is applied once per server stamp, so a host re-sending the whole
+track (idle-server does, on every steer) never re-arms a hold the timeline has
+taken back. A viewer that mounts later replays the stored track at its own
+mount: a steer on an animated path shows there until that path's next key
+after the mount, while screens that saw it live have already moved on. Until
+viewers share a clock (`sync: 'epoch'`, still unwired on the site), screens
+mounted at different times can briefly disagree on such a path.
+
+**One format for both use cases.** An ambient scene is a SaverSpec without a
+timeline — nothing about it changes. A timed piece (an ident, a film, a
+pre-roll) is a scene whose evolution is a timeline, and a sequence only where
+it genuinely cuts to a different set of layers.
+
+**Native:** tvOS ignores `timeline` and shows the base spec — so **author the
+base as the piece's rest state** (its end card), and a timed piece degrades
+to a valid ambient scene.
+
+## Groups — one handle for a multi-layer subject
+
+A subject drawn from several layers (a character's body, eyes and mouth; a
+record's grooves and label) can be moved, scaled and faded as one thing:
+
+```jsonc
+"groups": { "moon": { "transform": { "scale": 1, "y": 0 }, "opacity": 1 } },
+"layers": [ { "key": "face", "group": "moon", ... }, { "key": "eyes", "group": "moon", ... } ]
+```
+
+- A member paints through its group: the group's `transform` wraps the
+  layer's own (a point lands at *group(layer(p))*), and the group's `opacity`
+  multiplies the layer's. A group's transform always turns about the viewport
+  centre — it is a camera; `origin: "anchor"` is for a layer's own transform.
+- Up to 16 groups; names are 1–32 letters, digits, `-` or `_`, starting with a
+  letter. A layer's `group` must name one of them.
+- **Paint**, outside the structural signature: `setParam("groups.moon.opacity", 0)`,
+  a `timeline` key on `groups.moon.transform.scale`, or a sequence `morph`
+  glides the whole subject — one path instead of one per layer. A group present
+  on only one end of a morph glides from the identity (no transform, opacity 1).
+- Membership is fixed per scene: `layers.N.group` is not a steer or `timeline`
+  target. A sequence `morph` where a layer joins or leaves a group glides (the
+  end without the group paints it at the identity); moving a layer from one
+  group to another steps on the morph's first frame.
+
+**Native:** ignored ⇒ identity transform, opacity 1 — author the base so the
+subject reads without the group's paint.
+
 ## Seeing without eyes — the perception API
 
 `src/perceive.ts` translates a spec into modalities a **non-vision agent** can
@@ -677,6 +799,11 @@ simplified (`screen` ≈ `lighter`), wrapped link segments use straight
 interpolation, and background drift is sampled at rest. These are documented
 trade-offs for a zero-dependency, renderer-free analysis tool.
 
+A `timeline` is resolved at the sample time `t` before anything is measured,
+so every output below describes the scene as it is at that moment of the
+piece. Layer `opacity` scales a layer's ink and weight; a layer `transform`
+moves and scales its positions and sizes (sprite rotation is not modelled).
+
 - `perceiveScene(spec, {t?, viewport?, seed?})` — one-call bundle: everything below.
   **`t` is in milliseconds** (the MCP `previewScene` tool takes seconds and
   converts; passing seconds here reads a self-typing block as one that never
@@ -722,7 +849,10 @@ trade-offs for a zero-dependency, renderer-free analysis tool.
   text layer. Glyphs are invisible in the luminance maps, so this is the only
   way to confirm *what words* are on screen and how big. (Also on
   `perceiveScene().text`.)
-- `adviseSpec(spec)` — non-blocking advisories (also on
+- `adviseSpec(spec)` — non-blocking advisories (a layer whose paint opacity —
+  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:
   `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
@@ -797,7 +927,7 @@ the presenter never freezes. A durationless final segment holds regardless of
 `advance`.
 
 **Transitions:** `{ type: 'cut' }` (default) performs a hard switch.
-`{ type: 'morph', dur: number, text?: 'step' | 'crossfade' }` interpolates
+`{ type: 'morph', dur: number, text?: 'step' | 'crossfade' | 'dip' }` interpolates
 **numbers and hex colours** (colour, alpha, pulse, `reveal.progress`, …) over
 `dur` ms when crossing into the next segment; **every other value — strings,
 and `textBlock.text` above all — switches on the first morph frame** under
@@ -811,7 +941,11 @@ lerped frame's paint (colour, `opacity` and layer alpha glide as usual). Only
 the differing text layers cost a second draw, and only for `dur`; layers
 whose words match, and every non-text layer, are untouched. It is an
 internal paint pass, not a spec field — no `opacity` appears on the `text`
-sprite. `text` is a morph option only (a `fade` already cross-fades whole
+sprite. **`text: 'dip'`** draws the same two passes one after the other
+instead: the outgoing words fade out over the first half of the morph
+(alpha `1 − 2k`) and the incoming fade in over the second (`2k − 1`), so two
+captions never overlap — the right choice when the words sit in the same
+place. `text` is a morph option only (a `fade` already cross-fades whole
 frames; a `cut` has no window) and the validator rejects it elsewhere.
 **Default `step` is today's behaviour byte for byte** — the sequence
 baseline pins it — and a flip to `crossfade` by default would be a major
@@ -825,7 +959,7 @@ warning. When the segments are structural twins whose only differences are
 values morph steps (a text-only change), the morph runs but every frame of it
 shows the incoming segment — it reads as a cut — and the validator emits a
 `morph-nothing-morphable` warning (never an error; stored sequences stay
-valid) — unless the transition declared `text: 'crossfade'` and the words
+valid) — unless the transition declared `text: 'crossfade'` or `'dip'` and the words
 differ, in which case the words are the thing that morphs and the warning is
 withheld. During a morph, entity placement inherits the outgoing segment's
 seed — the incoming segment's own seed is unused. `dur` must be between 200
@@ -853,6 +987,28 @@ cross-fades on every segment change using the transition's `dur`, so `fade`
 matches the native player rather than diverging from it; native reads
 `fade.dur` where it reads the morph `dur` today.
 
+**Wrap morph:** under `loop: true` a morph declared on the **last** segment
+is ignored at the wrap — the lap cuts back to segment 0, and every stored
+sequence expects that. `wrapMorph: true` on the envelope honours it: the lap
+morphs back into segment 0 (from the second lap on; the first mount at
+`T = 0` is not a wrap). It takes effect only when the whole lap is **one
+morph chain** — every segment morphs into the next and the last is a
+structural twin of the first — so every lap keeps the chain root's seed and
+entity placement; otherwise it is still a cut and the validator warns
+`wrap-morph-inactive` with the reason. With it, a looping ident is a closed
+cycle of poses. A clicker jump to segment 0 (a `sequence.segment` steer)
+still cuts — it arrives from wherever the presenter was, not from the last
+segment. **Native:** tvOS cross-fades the wrap like any segment change.
+
+**Timelines in segments:** a segment's scene may carry a `timeline`; it runs
+on the segment's `localT`. A morph resolves each side on its own clock — the
+outgoing segment at `duration + localT`, the incoming at `localT` — and lerps
+the results, so a looping timeline keeps cycling through the morph. The
+retained steers follow the steering rule on both ends (a steer the outgoing
+timeline has already taken back stays taken back), and a layer `opacity` or
+`transform` present on only one end glides from its identity (opacity 1,
+no transform) instead of stepping.
+
 **Time mapping:** global clock `T` maps to `(segmentIndex, localT)` via prefix
 sums of durations. Half-open segments: `[start, start+duration)`. With
 `loop: true`, `T` wraps at the sum of all durations (loop is incompatible with

package/dist/index.d.ts

@@ -46,6 +46,14 @@ interface SaverSpec {
      * Absent ⇒ the frame is presented exactly as drawn.
      */
     finish?: FinishSpec;
+    /**
+     * Authored keyframes on the scene's own clock — see `Timeline`. Absent ⇒
+     * the scene is exactly what it was before the field existed. **Native:**
+     * ignored ⇒ the base spec (author it as the piece's rest state).
+     */
+    timeline?: Timeline;
+    /** Named layer groups — see `LayerGroup`. Absent ⇒ no layer is grouped (today's behaviour). */
+    groups?: Record<string, LayerGroup>;
     /** Dimensional unit system. 'viewport' (default) = all sizes/speeds/distances are fractions of min(w,h). */
     units?: 'viewport' | 'px';
     /**
@@ -139,6 +147,73 @@ interface BackgroundDrift {
     /** How far stops shift (fraction of the 0..1 range). Default 0.15, max 0.3. */
     amount?: number;
 }
+/**
+ * A paint-level transform applied to a whole layer at draw time, about the
+ * viewport centre: translate by (`x`, `y`) in `min(w, h)` units, rotate by
+ * `rotate` degrees, scale by `scale` (× `scaleX` horizontally — `scaleX`
+ * toward 0 reads as a turn about the vertical axis). Kept out of the
+ * structural signature, so it glides under steering, a `timeline` key or a
+ * `morph` — a camera for timed pieces, a slow drift for ambient ones. Every
+ * field optional; an empty transform is the identity. **Native:** ignored ⇒
+ * identity.
+ */
+interface LayerTransform {
+    x?: number;
+    y?: number;
+    scale?: number;
+    scaleX?: number;
+    rotate?: number;
+    /**
+     * What `scale` / `scaleX` / `rotate` turn about. `'viewport'` (default) is
+     * the viewport centre — a camera move. `'anchor'` is the layer's own
+     * `position` point (with `dx`/`dy`; for a `list`/`table` layout, the block's
+     * anchor; without `position`, the centre of its `region`) — a slam word
+     * punches in place, on every aspect. Group transforms always turn about the
+     * viewport centre. **Native:** ignored with the rest of `transform`.
+     */
+    origin?: 'viewport' | 'anchor';
+}
+/**
+ * A named set of layers painted through one shared `transform` and
+ * `opacity` (`SaverSpec.groups`, joined by `LayerSpec.group`): the group's
+ * transform wraps each member's own (it turns about the viewport centre, a
+ * camera), and its opacity multiplies theirs. Paint — outside the structural
+ * signature — so a steer (`groups.<name>.transform.scale`), a `timeline` key
+ * or a `morph` glides a whole multi-layer subject as one thing. **Native:**
+ * ignored ⇒ identity, opacity 1.
+ */
+interface LayerGroup {
+    transform?: LayerTransform;
+    opacity?: number;
+}
+/** One authored key of a `Timeline`: at scene time `t` (ms), glide `path` to `value` over `dur` ms. */
+interface TimelineKey {
+    /** Scene time in ms (the instance's own clock — a sequence segment's `localT`). */
+    t: number;
+    /** A steering path (`layers.0.sprite.color`, `key.sprite.color`, `background.stops.1.color`, …). It must already exist on the spec, as for `setParam`. */
+    path: string;
+    /** The target value; the key must still validate when applied. */
+    value: unknown;
+    /** Default `smooth`. */
+    ease?: 'step' | 'linear' | 'smooth';
+    /** Glide length in ms, starting at `t`. Default 1000 (as live steering); 0 = a cut. */
+    dur?: number;
+}
+/**
+ * Authored change on the scene's own clock — keyframes. A scene without a
+ * timeline is unchanged (ambient, today's behaviour); with one, each key
+ * glides its path at its time, and the scene can loop. Distinct from the
+ * channel's live `track`, whose `t` is a wall-clock stamp: live steering still
+ * layers on top, and a steer on a path the timeline animates holds until that
+ * path's next key.
+ */
+interface Timeline {
+    /** Repeat every `duration` ms. A looping path's value before its first key is its last key's value (the loop wraps). */
+    loop?: boolean;
+    /** Loop length in ms; required with `loop`, and at least the latest key's `t`. */
+    duration?: number;
+    keys: TimelineKey[];
+}
 interface LayerSpec {
     count: number;
     sprite: SpriteSpec;
@@ -227,7 +302,30 @@ interface LayerSpec {
     position?: {
         x: number;
         y: number;
+        /**
+         * An offset from `x`/`y` in `min(w, h)` units (px under `units: 'px'`).
+         * `x`/`y` are fractions of width and height while every size is a fraction
+         * of `min(w, h)`, so parts placed at computed fractions only register at
+         * the aspect they were computed for; anchor on a shared fraction (the
+         * centre is the only aspect-safe one) and offset in size units instead.
+         * Placement, like `x`/`y` (structural). Absent ⇒ 0. **Native:** tvOS
+         * ignores the offset until it reads the field.
+         */
+        dx?: number;
+        dy?: number;
     };
+    /**
+     * Paint-level layer opacity, 0..1 (default 1): multiplies the per-entity
+     * `alpha` and the `life` envelope at draw time. Unlike `alpha` (a range baked
+     * into every entity at build), it is **paint** — kept out of the structural
+     * signature — so `setParam`, a `timeline` key or a sequence `morph` glides it
+     * instead of re-seeding the layer. **Native:** ignored ⇒ 1.
+     */
+    opacity?: number;
+    /** Paint-level transform of the whole layer — see `LayerTransform`. */
+    transform?: LayerTransform;
+    /** The name of a `SaverSpec.groups` entry this layer is painted through (see `LayerGroup`). */
+    group?: string;
     /**
      * Inter-entity links. `mode` picks the wiring:
      * - 'nearest' (default): each entity's k nearest neighbors within maxDist.
@@ -755,6 +853,15 @@ declare const LIMITS: {
     readonly maxTransitionDur: 5000;
     readonly minTransitionDur: 200;
     readonly minEmitEvery: 1000;
+    readonly maxTimelineKeys: 256;
+    readonly minTimelineKeyInterval: 200;
+    readonly maxTimelineKeyDur: 30000;
+    readonly maxTimelineDuration: 86400000;
+    readonly maxLayerTransformOffset: 2;
+    readonly maxLayerTransformOffsetPx: 17280;
+    readonly maxLayerTransformScale: 8;
+    readonly maxLayerTransformRotate: 3600;
+    readonly maxGroups: 16;
     readonly maxEmitEvery: 600000;
     readonly minEmitLife: 500;
     readonly maxEmitGrow: 8;
@@ -777,13 +884,16 @@ type SequenceTransition = {
  * identical) segment over `dur` ms. Strings step on the first frame —
  * unless `text: 'crossfade'`, which draws each `text` / `textBlock` layer
  * whose string(s) differ twice for the window: the outgoing string at
- * `1 − k`, the incoming at `k` (k = the morph's eased progress). Default
- * `'step'`, today's behaviour, byte for byte.
+ * `1 − k`, the incoming at `k` (k = the morph's eased progress). `'dip'`
+ * draws the same two passes one after the other instead — the outgoing
+ * words fade out over the first half, the incoming fade in over the second —
+ * so the two strings never overlap. Default `'step'`, today's behaviour,
+ * byte for byte.
  */
  | {
     type: 'morph';
     dur: number;
-    text?: 'step' | 'crossfade';
+    text?: 'step' | 'crossfade' | 'dip';
 }
 /**
  * Cross-fade into the next segment over `dur` ms: the outgoing segment
@@ -821,6 +931,16 @@ interface IdleSequence {
      * lands mid-loop. `advance: 'input'` holds stay armed under either mode.
      */
     sync?: 'mount' | 'epoch';
+    /**
+     * Honour a `morph` declared on the last segment at the loop wrap (the lap
+     * morphs back into segment 0 instead of cutting). Opt-in: without it a
+     * last-segment morph stays a cut at the wrap, as every stored sequence
+     * expects. Takes effect only when the whole loop is one morph chain (every
+     * segment morphs into the next, and the last is a structural twin of the
+     * first) — so every lap reuses the same child and seed; otherwise it is a
+     * cut and the validator says why. Needs `loop: true`.
+     */
+    wrapMorph?: boolean;
     /**
      * A scene drawn under every segment on the sequence's **global** clock —
      * the ground that does not reset at a boundary or under a `sequence.segment`
@@ -850,6 +970,18 @@ declare function validateSpec(spec: unknown): ValidationResult;
  * `validateSpec` it never normalises colours into the caller's spec.
  */
 declare function ignoredPropertyPaths(spec: unknown): string[];
+/**
+ * Validity of only the parts of a spec that `paths` (index-form dot-paths,
+ * as `canonicalSpecPath` spells them) live in: each touched layer, the
+ * background, the finish — plus the cross-layer entity cap. A layer's rules
+ * (the `clock`/`pulse`/`grow` flash floors, `emit`, orbit parents) are all
+ * judged inside that layer, so a change confined to layer N can only break
+ * layer N or the total. Any other top-level path falls back to the full
+ * `validateSpec`. For the timeline's composed-state checks, which run at every
+ * key boundary and on every live steer: the whole-spec check costs a
+ * full validation per sample, this one a layer or two.
+ */
+declare function validateSpecPaths(spec: SaverSpec, paths: Iterable<string>): boolean;
 /** Narrowing helper: validate + cast. Throws with a joined message when invalid. */
 declare function assertValidSpec(spec: unknown): SaverSpec;
 /**
@@ -1206,6 +1338,15 @@ interface PathTarget {
 }
 /** Resolve a dot-path (key-aware) to its parent + final key; null if absent. */
 declare function resolveSpecPath(spec: unknown, path: string): PathTarget | null;
+/**
+ * The index form of a key-aware dot-path (`fireflies.sprite.color` →
+ * `layers.3.sprite.color`), or null when it does not resolve. Two paths that
+ * address the same field compare equal after this — how a live steer finds
+ * out whether a `timeline` key animates the field it touches.
+ */
+declare function canonicalSpecPath(spec: unknown, path: string): string | null;
+/** Read the value at a dot-path, or undefined when it does not resolve. */
+declare function readSpecPath(spec: unknown, path: string): unknown;
 /** A steering delta as carried on a channel control-track. */
 interface SteerDelta {
     t: number;
@@ -1222,6 +1363,14 @@ declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): Saver
  * target immediately (k > 0). Layer counts round to integers.
  */
 declare function lerpSpec(from: SaverSpec, to: SaverSpec, k: number): SaverSpec;
+/**
+ * The walk behind `lerpSpec`, for any value: numbers lerp, hex colours lerp
+ * per channel, equal-length arrays and objects recurse, everything else steps
+ * to the target at k > 0 (`count` rounds). At a spec's root a `timeline` steps
+ * too — two timelines' key times must never blend. No existing spec carries a
+ * timeline, so every stored morph and glide is unchanged.
+ */
+declare function lerpValue(from: unknown, to: unknown, k: number, specRoot?: boolean, rootKey?: string): unknown;
 /**
  * The string(s) a text layer paints — `strings` of a `text` sprite, `text`
  * of a `textBlock` — or null for every other sprite.
@@ -1472,10 +1621,11 @@ interface LuminanceGridOptions extends PerceiveOptions {
  * of (seed, t), `ghosting` is a decayed sum of past-frame splats (weight g^m
  * for ink m frames old, mirroring the renderer's warm-up replay) and `trail`
  * re-uses drawTrail's sampling — past positions with decaying alpha and
- * shrinking radius. Remaining approximations (documented, deliberate): soft
- * circles use a linear falloff, background drift is sampled at its rest
- * position. Good enough to perceive composition, focus, balance — and now
- * smear.
+ * shrinking radius. Polygons larger than POLYGON_OUTLINE_CELLS are scanned by
+ * their real (rotated) outline; smaller ones splat as a fill-weighted disc.
+ * Remaining approximations (documented, deliberate): soft circles use a linear
+ * falloff, background drift is sampled at its rest position. Good enough to
+ * perceive composition, focus, balance — and now smear.
  */
 declare function luminanceGrid(spec: SaverSpec, opts?: LuminanceGridOptions): LuminanceGrid;
 /**
@@ -1549,7 +1699,15 @@ interface LayerMotionStats {
     maxSpeed: number;
     moving: boolean;
 }
-/** Per-layer displacement between t and t+dt — choreography as numbers. */
+/**
+ * Per-layer displacement between t and t+dt — choreography as numbers.
+ *
+ * Samples the scene at both ends of the window separately (not just each
+ * entity's own position within one scene) so a `timeline`-driven layer
+ * `transform` — a camera pan or zoom with every entity otherwise static —
+ * registers as motion instead of vanishing between two reads of the same
+ * frozen transform.
+ */
 declare function motionStats(spec: SaverSpec, opts?: PerceiveOptions & {
     dt?: number;
 }): LayerMotionStats[];
@@ -1890,6 +2048,15 @@ declare function canMorph(seq: IdleSequence, from: number): boolean;
  * never its own index's.
  */
 declare function morphChainRoot(seq: IdleSequence, index: number): number;
+/**
+ * Whether a looping sequence's wrap (last segment → segment 0) plays the last
+ * segment's `morph`. Opt-in via `wrapMorph: true`, and only when the whole lap
+ * is one morph chain — every boundary morphs and the last segment is a
+ * structural twin of segment 0 — so the wrap keeps the chain root's seed and
+ * entity placement and nothing pops. Otherwise the wrap is the hard cut it has
+ * always been (the validator warns when `wrapMorph` asks for one it can't do).
+ */
+declare function canWrapMorph(seq: IdleSequence): boolean;
 /** `SpecInstance`'s seed normalization: 0 is falsy, so a valid `seed: 0` lands on 1. */
 declare function normalizeSeed(seed: number): number;
 /**
@@ -1959,6 +2126,73 @@ declare function sequenceWantsFinish(seq: IdleSequence): boolean;
  */
 declare function sequenceSwapCompatible(prev: IdleSequence, next: IdleSequence): boolean;
 
+/**
+ * `timeline` — authored keyframes on a scene's own clock.
+ *
+ * Everything here is a pure function of `(spec, t)`: resolving a scene at a
+ * time never depends on what was rendered before, so a timeline scene is as
+ * seekable and frame-addressable as any other (ghosting warm-up replays call
+ * `resolveTimelineAt` at each replay frame's own time). A spec without a
+ * `timeline` is returned untouched, which is what keeps every existing scene
+ * byte-identical.
+ *
+ * Semantics:
+ * - Keys address the same dot-paths as live steering; a path must already
+ *   exist on the spec (a key cannot create a field).
+ * - A key glides from wherever its path is at `t` to `value` over `dur` ms
+ *   (default 1000, the live-steering default; 0 is a cut), eased `smooth`
+ *   unless it says otherwise. Overlapping glides are fine: the later one
+ *   starts from the earlier one's in-flight value.
+ * - Without `loop`, a path holds the base spec's value before its first key.
+ * - With `loop`, time wraps every `duration` ms and a path's value before its
+ *   first key is its LAST key's value — the lap is one closed cycle, and lap 1
+ *   looks exactly like lap 7 (the value depends only on `t mod duration`).
+ */
+
+/** Default glide length for a key without `dur` — the same as a live steer's. */
+declare const DEFAULT_KEY_DUR = 1000;
+type Tracks = Map<string, TimelineKey[]>;
+/** The spec without its `timeline` (a shallow copy — the layers are shared, never mutated). */
+declare function withoutTimeline(spec: SaverSpec): SaverSpec;
+/**
+ * The spec's keys grouped by the field they animate (index-form path), each
+ * group sorted by time (stable, so equal times keep authored order and the
+ * later one wins). Keys whose path does not resolve are dropped — the
+ * validator rejects them, and the runtime stays lenient like steering.
+ */
+declare function timelineTracks(spec: SaverSpec): Tracks;
+/** Scene time folded into the timeline's own clock: `t mod duration` under `loop`, else `t`. */
+declare function timelineLocalTime(tl: Timeline, t: number): number;
+/**
+ * The scene at time `t` with every key applied — and without its `timeline`,
+ * so the result can be rendered, perceived, lerped or steered like any plain
+ * spec. A spec without a timeline comes back as the same object.
+ */
+declare function resolveTimelineAt(spec: SaverSpec, t: number): SaverSpec;
+/**
+ * When the timeline next takes a path back: the scene time of that path's
+ * next key after `t`, and that key's glide length — or null when no key will
+ * ever touch it again (no key on the path, or a non-looping timeline past its
+ * last key). A live steer on the path holds until `at`, then glides back to
+ * the timeline over `dur`.
+ */
+declare function nextKeyAfter(spec: SaverSpec, path: string, t: number): {
+    at: number;
+    dur: number;
+} | null;
+/**
+ * Scene times (timeline-local; within one lap under `loop`) where the keys'
+ * combined state is worth checking: time 0, and every key's start, end and
+ * glide quarter-points. Two keys can each be valid alone and invalid together
+ * (a `clock.rate` and a `pulse.period` the flash floor bounds as a ratio), so
+ * validation samples the composed scene here. `dense: false` keeps only the
+ * starts and ends, for the per-steer check a live viewer runs. Capped (evenly
+ * subsampled) so a 256-key timeline stays cheap to check.
+ */
+declare function timelineSampleTimes(spec: SaverSpec, dense?: boolean, cap?: number, only?: (path: string) => boolean): number[];
+/** The absolute scene times at or after `now` where `timelineSampleTimes` fall — the next lap's occurrences under `loop`. */
+declare function timelineSampleTimesAfter(spec: SaverSpec, now: number, dense?: boolean, only?: (path: string) => boolean): number[];
+
 /**
  * Reproduces the hand-coded Fish Aquarium saver as pure DATA — the discriminating test
  * that the schema is actually expressive: two layers (fish drifting both ways at varied
@@ -2334,4 +2568,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, 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, ignoredPropertyPaths, 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 };
+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 };