@idle-screens/schema 3.13.0 → 3.15.0

package/FORMAT.md

@@ -48,7 +48,11 @@ scene's own clock), paint-level layer `opacity` and `transform`,
 `text: 'dip'` on `morph` (2026-09-25 — timed scenes); layer `groups` and
 `transform.origin` (2026-09-26 — groups and origin); path drawings on
 `polygon` — `path`, `fillRule`, `fill`, `gradient`, `stroke`, `parts`,
-`span`, `origin` (2026-10-17 — vector drawings).
+`span`, `origin` (2026-10-17 — vector drawings); `draw` on `stroke` sprites
+and path strokes, the `in` / `out` / `spring` glide eases (timeline keys and
+live steers), `rock`, `life.stagger`, `reveal.rise`, `textBlock.number`, the
+`wipe` transition, `scenePeriod` and the `loop-seam` advisory
+(2026-10-25 — motion vocabulary).
 
 ## Safety invariants
 
@@ -90,6 +94,12 @@ Two validators exist with deliberately different strictness:
 
 Author against the JSON Schema; ship through the runtime validator.
 
+An unknown field that is another motion tool's vocabulary gets a pointer in
+its `unknown-property` warning: `delay` on a layer names `life.enter`,
+`duration` on a timeline key names `dur`, `fps` or `bpm` at the top level
+says a scene is a pure function of time in ms. The code and path are the
+same as any unknown field's; only the message says what to write instead.
+
 Rules the JSON Schema cannot fully express (the runtime enforces them):
 total entities across all layers ≤ 800; every `[min, max]` range must satisfy
 `min ≤ max`; `colorWeights` length must match `colors`; `emit.life ≤
@@ -287,16 +297,17 @@ own `finish` is not steerable; steer a segment's, or republish.
 | `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) |
+| `rock` | `{amp ≤ 45, period ≥ 1000}` (degrees, ms) | none | a **swing** about each entity's resting angle (`rotate` plus any `spin`): `amp` degrees either side, once per `period` there and back, on a seeded per-entity phase — a boat on a swell, a hanging sign, a lantern. A `clock` replaces the seeded phase (the layer swings in step) and then needs `period / rate ≥ 1000`. Structural, like `pulse`; its phases are drawn in a pass after the layer's entities, only when declared, so declaring it re-seats nothing else in the layer. Rotation is not in the luminance grid, so perception does not see it. **Native:** ignored ⇒ no swing |
 | `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; 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` |
+| `layout` | `{type: "grid", columns?, jitter?}` \| `{type: "list", gap?}` \| `{type: "table", columns, gap?}` (`gap`: a number or `{x?, y?}`) | 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?}` — a list is one column, so only its `y`, the row pitch, applies). **`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?, stagger?}` ms | always on | act structure: fade the layer in at `enter`, out at `exit`. `stagger` shifts entity *i*'s whole envelope (enter and exit) by *i* × `stagger` in entity order (reading order for `list` / `table` / `grid`), so a row of labels builds one after another; paint, no RNG draws. Density scaling changes the count, so the build takes (count − 1) × `stagger`. **Native:** ignored ⇒ all together |
 | `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, 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 |
+| `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). **Order:** `scale`/`scaleX` (along the layer's own horizontal) and `rotate` apply about the origin first, then `x`/`y` translate in **screen space** — an offset is never turned or stretched by the layer's own `rotate`/`scale`, so `{ "rotate": 90, "x": 0.2 }` moves the layer right, not down. A group's transform wraps the result (*group(layer(p))*), so a group's `scale` and `rotate` do act on its members' offsets. 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? }`.
@@ -364,7 +375,9 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   `parts`).
   - **Holes and pieces.** Several subpaths in one `path` are one drawing.
     `fillRule: "auto"` (default) decides by containment: a subpath lying
-    entirely inside another is a hole; one inside a hole is solid again (a
+    entirely inside another is a hole — touching its container's edge counts
+    as inside, so a notch cut from the rim or a mouth meeting the face's
+    outline is a hole too (a vertex within 0.001 of the edge is on it); one inside a hole is solid again (a
     pupil in an eye-spot ring); pieces that merely overlap merge (branches,
     veins, leaflets on a stem), and a hole cuts through every overlapping
     piece of the layer (a window across two walls). `"nonzero"` /
@@ -383,6 +396,12 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
     — an outline along every subpath **as drawn** (holes included; open
     subpaths too). `width` is in unit-box units (0.01 = 1% of the drawing's
     half-size). Overlapping pieces show their inner edges, as in SVG.
+    `draw: {start?, end?}` on a stroke paints only that stretch of it, the
+    part's subpaths counted as one pen run in the order the path draws them
+    (a closed ring includes its closing edge, and comes back open when cut) —
+    `fill: false` line art plus a glide of `stroke.draw.end` is a drawing
+    that draws itself. Paint; `…stroke.draw.end` is a key target like the
+    stroke's width. **Native:** ignored ⇒ the whole outline.
   - **`fill: false`** draws the stroke only — line art. Then open paths
     (no `Z`) are fine: veins, hatching, antennae, rigging.
   - **`parts`** — a multi-colour drawing in one layer:
@@ -411,18 +430,26 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   - **Steering and morphs.** Part colours, gradient stops, stroke widths
     and opacities glide like any paint. Two paths with the **same commands**
     (same letters, same count of numbers — draw both from one template)
-    morph number by number; any other path change steps.
+    morph number by number; any other path change steps. The full list of
+    what a `setParam` or `timeline` key can address is under **Timeline**
+    ("Path drawings: what a key can address").
   - Drawings are rendered once and reused while they look the same (moving
     copies are resampled), so a detailed still drawing costs about what a
     flat one does per frame.
 - `{ "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;
+  `curve: "smooth"` (default) is a Catmull-Rom spline, `"linear"` a polyline
+  through every point (its corners stay sharp);
   `taper` thins the mark to almost nothing at both ends (a brush stroke rather
   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,
+  like `streak`. Rotates with `spin`. **`draw: {start?, end?}`** paints only
+  the stretch of the mark between those fractions of its length (defaults 0
+  and 1) — glide `end` 0 → 1 and the mark draws itself on; glide `start` after
+  it and it erases from the tail. Paint (it glides, it is outside the
+  structural signature), and perception scales the ink with it.
+  **Native:** ignored ⇒ the whole mark. 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 }` —
   multi-line text block with deterministic line-breaking. All dimensions are
@@ -437,6 +464,9 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   wrapping is identical across platforms; note that the table is approximate
   — a painted line may slightly exceed `maxWidth` when the real font is wider
   than the table estimates, so `maxWidth` is a layout target, not a hard clip.
+  Full-width glyphs (CJK ideographs, kana, Hangul, fullwidth forms) count a
+  whole em in every table; lines break only at whitespace, so an unspaced CJK
+  run stays on one line — break it with spaces or `\n`.
   Use with `count: 1`, `motion: { type: "static" }`, and `position`.
 
   `anchor` (one of nine compass points: `top-left`, `top`, `top-right`,
@@ -461,7 +491,7 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   rejected** (`fontSize` owns size, so the block keeps scaling with the
   viewport). A monospace family (`monospace`, `ui-monospace`, Menlo, Courier,
   SF Mono, Fira Code, …) switches the line-breaker to a uniform 0.6 em
-  advance so mono wraps land where the real face puts them; every other
+  advance (1 em for a full-width glyph) 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
@@ -490,7 +520,9 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   across the room, and opts that layer into two advisories:
   `text-legibility` fires when the text colour's WCAG ratio falls below
   **4.5:1** against the background sampled at the box centre (gradient stops
-  interpolated at rest, `band` honoured) **or** against the brightest
+  interpolated at rest, `band` honoured) — or, where an earlier static,
+  hard-edged, unblended layer covers the whole box (a backing chip), against
+  that layer composited over the page — **or** against the brightest
   additive layer (`blend: lighter` / `screen`) whose entities can reach the
   box and are at least a glyph tall, taken at its peak alpha (base + pulse)
   composited over that background — a glow parked under a caption is
@@ -520,7 +552,11 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   progress — small reads as a soft typewriter, large as a wave of
   overlapping fades. Still a pure function of `progress`, so it glides and
   deletes exactly like the other modes. Native clients render `glyphFade`
-  as `typewriter` until they gain per-glyph alpha. `caret` draws a
+  as `typewriter` until they gain per-glyph alpha. With `glyphFade`, `rise`
+  (0..1 em, default 0) lifts each glyph into its line as it fades in, from
+  `rise` em below — still a pure function of progress, and layout never
+  moves (it warns and is ignored on the other modes; native ignores it).
+  `caret` draws a
   blinking caret at the frontier (`true`, or `{ "blink": 1.2, "color": "#fff" }`;
   blink is in full cycles/sec, capped at 3 for flash safety, and is a square
   wave of `t` like every other animation). With `align: "center"`/`"right"`
@@ -533,6 +569,20 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   sequence, a morph declared `text: 'crossfade'` cross-fades the old words
   under the new ones instead (see **Transitions** below).
 
+  textBlock also accepts **`number`** — a counter:
+  `{ "number": { "value": 1200, "decimals": 0, "prefix": "", "suffix": " visitors", "grouping": true } }`.
+  The block paints `prefix + value + suffix` instead of `text`, `value`
+  rounded to `decimals` (0..6, default 0) with its thousands grouped by
+  commas unless `grouping: false` — formatted by the engine, never by the
+  viewer's locale, so every screen shows the same digits. `value` is
+  **paint**: `setParam("stats.sprite.number.value", 48210, { dur: 4000 })`
+  rolls the digits up over the glide, and a timeline key does the same.
+  Line-breaking runs on the formatted string, so a counter that gains a
+  digit can re-wrap: give it width to spare and an `anchor` on the edge that
+  should stay put. Perception and the text advisories read the formatted
+  number. `text` is what clients that do not read `number` show — author it
+  as the counter's rest value. **Native:** ignored ⇒ `text`.
+
 `circle`, `ring`, `streak`, `rect`, `bar`, `polygon` and `stroke` all accept
 `colors: [...]` (seeded per-entity palette pick) and `colorWeights: [...]`
 (relative weights, same length — "mostly cool tones, occasional ember").
@@ -550,10 +600,29 @@ and configured the second.
 
 ### `motion` (one of)
 
+Every field each motion type takes — **bold** is required; anything else
+on a motion is an unknown property, ignored with a warning. Lengths are
+fractions of `min(w, h)` like every size (px under `units: "px"`).
+
+| `type` | fields | units and ranges |
+| --- | --- | --- |
+| `drift` | **`speed`**, `angle`, `bidirectional`, `bob`, `ease` | `speed` [min,max] per second; `angle` degrees (0 = right, 90 = down); `bob` vertical wobble amplitude (typ. 0.002–0.02) |
+| `rise` | **`speed`**, `sway`, `ease` | `speed` [min,max] per second, upward; `sway` horizontal amplitude (typ. 0.002–0.02) |
+| `bounce` | **`speed`** | `speed` [min,max] per second, diagonal |
+| `static` | — | none |
+| `orbit` | **`speed`**, **`radius`**, `center` | `speed` [min,max] **degrees** per second (negative turns the other way, ≤ 180); `radius` [min,max]; `center` `{x, y}` 0..1 or `{layer}` |
+| `wander` | **`speed`**, `angle`, `meander`, `coherence`, `ease` | `speed` [min,max] per second; `angle` degrees (omit for a seeded heading); `meander` amplitude ≤ 0.463; `coherence` 0..1 |
+| `warp` | **`speed`**, `center` | `speed` [min,max] **depth-units** per second (≤ 1.5); `center` `{x, y}` 0..1 |
+| `path` | **`points`**, **`duration`**, `curve`, `closed`, `scatter` | `points` 2..24 `{x, y}` 0..1; `duration` ms per lap (≥ 2000); `curve` `"smooth"` \| `"linear"`; `closed` boolean; `scatter` > 0 |
+
+`ease` is `{ "type": "settle" | "buoyant", "tau": ms }` (below). `bob` and
+`sway` warn `motion-amplitude` above 0.25: `bob: 4` swings the layer four
+screen-heights each way, a px value written into a viewport-unit spec.
+
 - `{ "type": "drift", "speed": [0.02, 0.06], "angle": 0, "bidirectional": true, "bob": 0.004 }`
   — heading in degrees (0 = right, 90 = down); `bidirectional` flips horizontal
-  direction per entity (fish); `bob` adds vertical wobble
-- `{ "type": "rise", "speed": [0.01, 0.03], "sway": 0.006 }` — upward, with horizontal sway (bubbles)
+  direction per entity (fish); `bob` adds vertical wobble (0.004 ≈ 4 px at 1080p)
+- `{ "type": "rise", "speed": [0.01, 0.03], "sway": 0.006 }` — upward, with horizontal sway (bubbles; 0.006 ≈ 6 px at 1080p)
 - `{ "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 } }`
@@ -773,6 +842,12 @@ Paths that are **paint** (colours, `alpha` inside a sprite's paint, layer
 pop. Prefer `opacity` over `alpha` and `transform` over `position` for
 anything that should move smoothly.
 
+A live steer glides `smooth` unless a delta names `ease: "in"`, `"out"` or
+`"spring"` (the longest delta's ease shapes the glide). `step`, `linear` and
+`smooth` on a steer still mean smooth: tracks carried those names before
+steers read an ease at all, and honouring them now would change how every
+stored track replays.
+
 ## Timeline — keyframes on the scene's clock
 
 A SaverSpec can carry authored change on its **own** clock — the same clock
@@ -794,7 +869,12 @@ its drift, orbit and pulse run on (from mount; a sequence segment's `localT`):
   (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).
+  (default), `linear`, `step` (holds, then switches at the glide's end),
+  `in` (accelerates from rest — a departure), `out` (leaves at speed and
+  decelerates into place — an arrival) or `spring` (a critically damped
+  spring: a quick start that settles with no overshoot). Every ease is
+  monotone, so a glide never leaves the range its two values bound.
+  **Native:** an ease it does not know reads as `smooth`.
   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.
@@ -809,7 +889,38 @@ its drift, orbit and pulse run on (from mount; a sequence segment's `localT`):
   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.
+  quarter-points and rejects it there. Paint keys on different paths can
+  also combine into a faster flicker than any one path allows: a top
+  layer's `opacity` switching between its own colour and the colour
+  beneath, each keyed at the floor and out of step, flickers the whole
+  frame 5 times a second. So where any one second holds 7 or more key
+  boundaries on paint paths (opacity, alpha, colours, stops, gradients,
+  strokes), publishing resolves the frame there and refuses more than 3
+  flashes a second over a quarter of the screen (WCAG 2.3.1,
+  `timelineFlashReport`). Keep big brightness changes at least ~170 ms
+  apart across the whole frame, not just per path. The count is also taken
+  per cell of the check's 16 × 9 grid, from the keys on the layers that can
+  paint that cell: a staggered wave of small static dots is busy across the
+  frame but sparse in every cell, so it passes without a frame resolved. A
+  layer that moves, emits, links or has its geometry keyed counts as
+  reaching every cell. Past 512 frames to resolve, publishing refuses and
+  says the timeline is too dense to verify: put fewer paint keys in that
+  second, or align them to shared times.
+- **Path drawings: what a key can address.** Every field of a path
+  polygon is paint, so all of these glide (`N` is a part's index):
+  `sprite.path` and `sprite.parts.N.path` (a morph number by number when the
+  commands match, else a step); `sprite.color` / `sprite.parts.N.color`;
+  `sprite.parts.N.opacity`; `…stroke.width`, `…stroke.color`,
+  `…stroke.opacity`; `…gradient.stops.M.color` / `.opacity` / `.at`; and a
+  gradient's `from` / `to` / `center` / `radius` / `focus`. A key can only
+  address a field the spec **declares** — key `parts.N.opacity` or a
+  stroke's `opacity` only after writing it on the part (`"opacity": 1`).
+  A **gradient paints over the flat colour**: a `color` key on a part (or
+  path sprite) that has a `gradient` changes nothing, and the validator
+  warns `timeline-key-no-effect` — key its stops instead. A keyed path may
+  **collapse to nothing** (an eye blinking shut, a mouth closing to a line):
+  at those moments that part draws nothing, rather than the scene being
+  refused. The base spec's own paths must still draw something.
 - 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
@@ -840,9 +951,15 @@ 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.
+after the mount, while screens that saw it live have already moved on. Inside
+a `sync: 'epoch'` sequence every viewer shares the channel's clock (the
+idlescreens.com viewer passes `sequenceBaseT` from idle-server PR 247 on), so
+playback lines up. That aligns playback, not steers: a steer is still armed at
+the receiving screen's current time rather than the server stamp, so a stored
+track replayed at a later mount can still hold a path until a different key
+than a screen that saw it live. A timed scene on its own, or a `mount`
+sequence, runs on each screen's own clock, so 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
@@ -962,14 +1079,40 @@ moves and scales its positions and sizes (sprite rotation is not modelled).
   will look wrong on the wall; one that passes may still sit a few px off.
   Two more are **opt-in** through the text sprite's `role: "read"` (see the
   `textBlock` sprite): `text-legibility` (WCAG ratio below 4.5:1 against the
-  background at the box centre or under the brightest additive layer that can
-  sit beneath the line) and `text-safe-area` (the box within 5 % of an edge,
+  background at the box centre, or the solid chip painted under the whole box,
+  or under the brightest additive layer that can sit beneath the line) and `text-safe-area` (the box within 5 % of an edge,
   with its box in `boxes`). Undeclared text is never measured for either.
   `overlap-seams` catches the trap the other channels are blind to: a layer
   whose entities bury each other (so it was drawn as one shape) but whose paint
   settings make every overlap visible. It is gated to stay off deliberate
   washes — it needs at least 6 entities and a mean base alpha of 0.45, and
-  never fires under `blend: lighter` / `screen`. No shipped example trips it.
+  never fires under `blend: lighter` / `screen`. Nor does it fire when the
+  only seam is a multi-colour palette and the shapes bury their neighbours'
+  outlines but under 15 % of their area — rows or tiles butted edge to edge
+  (overlapping by a hairline to hide the gap) are banding, not a pile. No
+  shipped example trips it.
+  `motion-intensity-mismatch` fires when a scene declares
+  `motionIntensity: "calm"` but a layer of shapes, glyphs or text spins
+  faster than 90°/s on average (shipped calm spins stay at or under 32°/s).
+  `flash-near-limit` fires when a timeline's luminance keys, resolved over
+  their densest one-second window, flicker at least 2 times a second over a
+  quarter of the frame — a full-frame step at the 200 ms key floor is 2.5, which
+  the publish-time WCAG gate (more than 3) lets through.
+  `loop-seam` fires when a scene declares a looping timeline and the rest
+  of the scene repeats too, but on a period the lap does not divide — so
+  one lap can never come round to its own first frame (it names the period
+  to make the lap a multiple of). A scene whose other motion never repeats
+  (drifting stars, wandering motes) is not judged: that is ambient by
+  design. `scenePeriod(spec)` is the analysis behind it — the least common
+  multiple of every periodic part (pulse, grow, rock, spin, cycle, orbit,
+  path laps, emit, caret, background drift, a looping timeline), `0` for a
+  static scene, or `null` with the reasons when something never repeats
+  (seeded speed ranges, wrapping travel, a `life` build, a non-looping
+  timeline, a self-typing reveal, animated grain) — and likewise when a part
+  repeats between whole milliseconds (`spin: 7` laps every 51428.57 ms, which
+  no whole-ms period reproduces) or a timeline key moves a period, rate or
+  speed (the cycle itself then varies). An exporter reads it to cut an exact
+  loop.
   The two density advisories read the spec's declared `density` first:
   `sparse-scene` is withheld under `density: "sparse"` and `dense-scene`
   under `"dense"`, and `density-mismatch` fires instead when the measured
@@ -1107,6 +1250,20 @@ 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.
 
+`{ type: 'wipe', dur, shape?, origin?, angle?, feather? }` reveals the
+incoming segment through a moving edge instead of a dissolve: `shape:
+'circle'` (default) is an iris opening from `origin` (`{x, y}` 0..1,
+default the centre) until it clears the farthest corner; `'line'` sweeps a
+straight edge along `angle` degrees (0 = left to right, 90 = top to
+bottom). `feather` (0..1, default 0.08) is the edge's softness, as a
+fraction of the distance it travels. It runs on `fade`'s machinery — both
+segments live on canvases of their own for `dur`, each composited through
+the edge's mask — with the same `dur` bounds, the same tier gate (`basic` /
+`minimal` hosts cut, and `fade-degrades-on-low-tier` counts wipes), and the
+same answer to `boundary-luminance-jump`: every pixel changes once, a
+spatial ramp, never a flash. `text` is a morph option and is rejected on a
+wipe. **Native:** tvOS cross-fades over `dur`.
+
 **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
@@ -1287,5 +1444,9 @@ layers); and `lobby-talk` (one screen of a quarter-in-review, every text
 layer `role: "read"`, zero advisories — readable copy over additive
 atmosphere); and `thermal-field` (a `field` background in six riso inks,
 `quantize: 6`, warped and drifting, under a handful of screened motes, with
-a grain-and-dither `finish` — the ground is the piece and the paper shows). See [`src/examples/`](./src/examples/). The dashboard exercises the
+a grain-and-dither `finish` — the ground is the piece and the paper shows); and
+`ink-tide` (the motion vocabulary in one scene: a pen line that draws itself
+on with `stroke.draw` eased `out` and erases eased `in`, a boat that `rock`s on
+a clock, and a caption that lifts in with `reveal.rise` — its rock period
+divides the 30 s lap, so `loop-seam` stays quiet). See [`src/examples/`](./src/examples/). The dashboard exercises the
 static/HUD subset at scale (34 layers of keyed, positioned text).