@idle-screens/schema 3.12.0 → 3.13.0

package/FORMAT.md

@@ -46,7 +46,9 @@ 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).
+`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).
 
 ## Safety invariants
 
@@ -192,8 +194,11 @@ exceeds 2 %, or a `dense` one that would have tripped `sparse-scene`, gets a
 
   **Steering.** Every numeric knob and every band is a paint path —
   `background.scale`, `background.warp`, `background.quantize`,
-  `background.bands.2`, `background.drift.amount` — and glides (a fractional
-  `quantize` or `octaves` mid-glide rounds). `background.seed` is not
+  `background.bands.2`, `background.drift.amount` — and glides. `quantize`
+  and `octaves` are level counts, so a glide (`setParam`, a `timeline` key, a
+  `morph`) steps through **whole** levels: the in-between value rounds, and a
+  `quantize` under 1.5 reads `0` (smooth) — so `quantize` 0 → 6 eases smooth,
+  then 2, 3 … 6 bands. Authored values must still be whole. `background.seed` is not
   steerable. The background is paint, not structure, so a `morph` between
   two field segments glides the field; a gradient → field morph steps
   (different shape).
@@ -269,7 +274,7 @@ own `finish` is not steerable; steer a segment's, or republish.
 
 | Field | Type | Default | Meaning |
 |---|---|---|---|
-| `count` | int 1..400 | — | entities in this layer |
+| `count` | int 1..400 | — | entities in this layer. **At most 800 entities across all layers** (and ≤ 36 layers): the validator rejects a spec whose counts sum past 800, and density scaling never takes a screen past it |
 | `sprite` | SpriteSpec | — | what each entity looks like |
 | `motion` | MotionSpec | — | how entities move |
 | `size` | `[min,max]` > 0 | sprite-dependent | font size for emoji/text; ignored for shaped sprites |
@@ -278,13 +283,13 @@ own `finish` is not steerable; steer a segment's, or republish.
 | `alpha` | `[min,max]` 0..1 | `[1,1]` | per-entity opacity range |
 | `blend` | `lighter` \| `screen` \| `multiply` | source-over | additive glow / gentle additive / darkening |
 | `region` | `{x?, y?}` ranges 0..1 | full viewport | fractional spawn window (placement only, not travel) |
-| `pulse` | `{amp ≤ 0.5, period ≥ 500, wave?}` | none | opacity breathing; `wave: {wavelength, angle?}` turns it into a traveling wave across the field |
-| `spin` | number \| `[min,max]` ±360 deg/sec | none | per-entity rotation (seeded start angle); a range gives each entity a seeded speed (confetti, tumbling debris). `[0, 0]` does **not** hold the seeded angle — a zero speed renders at 0; use `rotate` |
+| `pulse` | `{amp ≤ 0.5, period ≥ 500, wave?}` | none | opacity breathing: `amp` is **added** to the entity's `alpha` (alpha ± amp, clamped to 0..1), not a fraction of it — a dim layer (`alpha` 0.2, `amp` 0.3) swings through 0 and sits fully dark for part of every period; keep `amp` ≤ the alpha floor for a breath that never blacks out. `wave: {wavelength, angle?}` turns it into a traveling wave across the field |
+| `spin` | number \| `[min,max]` ±360 deg/sec | none | per-entity rotation (seeded start angle — drawn from the scene's one shared seeded stream, so it is reproducible for a given spec, seed **and viewport** but not a fixed per-entity value: density scaling changes how many entities draw before it, and declaring a `rotate` range adds a draw per entity, so either one changes the angles; use `rotate` for an angle you need to pin); a range gives each entity a seeded speed (confetti, tumbling debris). `[0, 0]` does **not** hold the seeded angle — a zero speed renders at 0; use `rotate` |
 | `rotate` | number \| `[min,max]` ±360 deg | none | **static** per-entity rotation: a scalar turns the whole layer, a range gives each entity a seeded angle (thrown blades, scattered glyphs, a tilted grid). Adds to `spin`'s start angle. Structural. **Native:** tvOS reads `spin` only ⇒ 0 |
 | `grow` | `{amp ≤ 0.8, period ≥ 500}` | none | size breathing (seeded phase) |
-| `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail; `length` is **milliseconds** of history (max 5000), `fade` a number 0..1 (not a boolean — `links.falloff` in the next row is the boolean) |
+| `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail; `length` is **milliseconds** of history (max 5000), `fade` a number 0..1 (not a boolean — `links.falloff` in the next row is the boolean). Echoes of a shaped sprite (`polygon`, `stroke`, `rect`, `ring`, `streak`, `bar`) are the sprite's own shape as it was then, shrinking toward the tail; `circle`, `emoji` and text trail discs. A hard `circle`'s trail is one continuous ribbon tapering behind it, so a quick path draws a line rather than a string of dots (a layer whose ribbons would cover more than a tenth of the screen draws its echo discs instead, to bound the cost); a `soft` circle's echoes are filled in where they would part, within a small per-layer budget |
 | `links` | see below | none | inter-entity lines |
-| `layout` | `{type: "grid", columns?, jitter?}` \| `{type: "list", gap?}` \| `{type: "table", columns, gap?}` | scatter | `grid`: cells fill `region`, `jitter` scalar or `{x?, y?}` 0..1 per axis. **`list` / `table`: data layouts** — entities in reading order from `position` (any count) or centred in `region`, `gap` apart (viewport units of `min(w,h)`, default 0.06); text/emoji take `strings[i]` / `glyphs[i]` and palettes `colors[i]` **in order**, so N labels are one layer |
+| `layout` | `{type: "grid", columns?, jitter?}` \| `{type: "list", gap?}` \| `{type: "table", columns, gap?}` | scatter | `grid`: cells fill `region`, `jitter` scalar or `{x?, y?}` 0..1 per axis. **`list` / `table`: data layouts** — entities in reading order from `position` (any count) or centred in `region`, `gap` apart (viewport units of `min(w,h)`, default 0.06; a number or `{x?, y?}`). **`gap` is the pitch between cell anchors, not the space between cells** — a label wider than the column pitch runs into its neighbour (the `layout-text-overlap` advisory names the gap that clears it), so size `gap.x` to the widest label. Text/emoji take `strings[i]` / `glyphs[i]` **in order**, so N labels are one layer; a shaped sprite's palette (`colors[i]` on `bar`, `rect`, `circle`…) is read in order too. **Text and emoji have no `colors`**: a `text` layer paints every label in its one `color` (a `colors` on it is an unknown property, ignored with a warning) — use one layer per label colour |
 | `life` | `{enter?, exit?, fade?}` ms | always on | act structure: fade the layer in at `enter`, out at `exit` |
 | `emit` | `{every ≥ 1000, life ≥ 500, jitter?, grow?}` (`life ≤ every`) | always lit | **sparse events**: each entity is dark except a `life`-ms window every `every` ms, fading in fast and out slow; `jitter` 0 staggers entities evenly (one event at a time while `life ≤ every / count`), 1 scatters the offsets (a fixed sequence, not seeded — declaring `emit` disturbs no other draw); `grow: [from, to]` scales size across the window — expansion rather than travel |
 | `clock` | `{phase?, rate?}` | seeded phases | **phase-lock**: `pulse`, `grow` and `cycle` share one phase (turns, 0..1) and run at `rate` × time; two layers with the same clock breathe in step. Clocked periods must satisfy `period / rate ≥ 1000` |
@@ -299,7 +304,9 @@ own `finish` is not steerable; steer a segment's, or republish.
 `maxDist`; `"chain"` wires entities in order (Mystify polygons — ignores
 `k`/`maxDist`, `closed: true` closes the loop); `"random"` uses a fixed
 deterministic wiring filtered by `maxDist`. `falloff: true` fades link alpha
-with distance, removing pop-in at the cutoff.
+with distance, removing pop-in at the cutoff. `k` and `maxDist` are required
+for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
+`falloff: true` needs `maxDist` (the distance at which a link has faded out).
 
 ### `sprite` (one of)
 
@@ -308,20 +315,24 @@ with distance, removing pop-in at the cutoff.
 - `{ "kind": "text", "strings": ["HELLO"], "color": "#e6e8ef", "font": "bold monospace", "align": "center", "baseline": "middle", "maxWidth": 300, "cycle": ..., "role": "read" }`
   — a `font` **with** a px size keeps that shorthand, its number rescaled to the
   viewport (verbatim only under `units: "px"`); a family/weight only
-  (`"bold monospace"`) composes with the seeded per-entity `size`; `role` is
+  (`"bold monospace"`) composes with the seeded per-entity `size` (faces
+  installed on the viewer only — see `font` under `textBlock`); `role` is
   the legibility opt-in described under `textBlock` below (same field, same
   meaning on both text sprites)
 - `{ "kind": "circle", "radius": [0.001, 0.003], "color": "#ffffff", "soft": true }` —
   `soft` renders a radial-falloff glow orb instead of a hard disc
 - `{ "kind": "ring", "radius": [0.002, 0.005], "color": "#d8f6ff", "width": 0.001 }` —
-  unfilled circle (bubbles, portals, sonar)
+  unfilled circle (bubbles, portals, sonar). The line is **centred on the
+  radius**: half of `width` falls inside, half outside, so the outer edge is
+  `radius + width / 2`
 - `{ "kind": "streak", "length": [0.01, 0.03], "color": "#cfd8ff", "width": 0.002 }` —
   a line oriented along the entity's analytic heading with a faded tail
   (rain that reads as rain, shooting stars, warp stars)
 - `{ "kind": "rect", "width": [0.012, 0.02], "aspect": [1.3, 1.7], "color": "#ffb347", "feather": 0.6 }` —
   rectangle; `aspect` is the height/width ratio range (rotates with `spin`);
   `feather` 0..1 softens the edges — that fraction of the half-size fades out
-  toward the border (Rothko's block at 0.5–0.8)
+  toward the border in one smooth linear falloff on each axis (Rothko's block
+  at 0.5–0.8)
 - `{ "kind": "bar", "values": [82, 64, 91], "max": 100, "length": 0.5, "thickness": 0.02, "color": "#17e8c8", "direction": "right" }` —
   a data bar: entity *i* draws `length × values[i] / max` (viewport units),
   `thickness` thick, growing from its position toward `direction` (`right`
@@ -334,14 +345,83 @@ with distance, removing pop-in at the cutoff.
   6); or `"points": [[-1, 0.9], [0.2, -1], [1, 0.4]]` — 3..24 unit
   coordinates in −1..1 scaled by the radius — for any facet (a Picasso shard,
   a Kandinsky triangle, a Mondrian plane). `soft` feathers the fill from the
-  centre. Rotates with `spin`. `points` are paint, so two polygons with the
-  same point count `morph` into each other
+  centre. Rotates with `spin`. The outline fills with the **nonzero** winding
+  rule: a self-crossing outline paints both lobes, and a hole needs its inner
+  loop traced in the **opposite** direction (a keyhole: outer ring clockwise,
+  then back round the hole counter-clockwise, joined by a zero-width slit). `points` are paint, so two polygons with the
+  same point count `morph` into each other — and a `setParam`, `timeline` key
+  or `morph` target for `sprite.points` is in the **same unit coordinates**,
+  scaled by each entity's seeded radius (not by the keyed shape's own extent):
+  keep every keyed point inside −1..1 (the validator rejects one outside), and
+  shrink a target shape by scaling its points, not by exceeding the box.
+  For anything more detailed than a 24-point facet, give the polygon a
+  **path** instead (next entry)
+- **Path drawings** — `{ "kind": "polygon", "radius": [0.3, 0.3], "color": "#2f6a3e", "path": "M 0 -0.9 C 0.5 -0.9 0.7 -0.3 0.5 0.1 … Z" }`:
+  an SVG path `d` string in the same −1..1 unit box (`M L H V C S Q T A Z`,
+  absolute or relative, curves and arcs included), flattened once to a smooth
+  outline. Use it for illustration: leaves, creatures, lettering-like marks,
+  architecture. Everything below is **only** for polygons with a `path` (or
+  `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
+    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"` /
+    `"evenodd"` are SVG's own rules — use them for pasted SVG, for overlap
+    patterns (a rosette of overlapping circles wants `evenodd`), and when a
+    same-colour shape sits inside another on purpose (`auto` would cut it).
+  - **`gradient`** replaces the flat colour of the fill:
+    `{ "type": "linear", "from": [0, -1], "to": [0, 1], "stops": [{ "at": 0, "color": "#2c6a3a" }, { "at": 1, "color": "#7ab070", "opacity": 0.6 }] }`
+    or `{ "type": "radial", "center": [0, 0], "radius": 1, "focus": [-0.3, -0.4], "stops": [...] }`
+    (2..8 stops, `at` 0..1 non-decreasing, optional per-stop `opacity`).
+    Coordinates are in the drawing's unit box, so the shading scales and
+    rotates with it; `"units": "part"` reads them in the part's own bounding
+    box (−1..1), so one gradient lights every piece on its own (a radial
+    there is the piece's ellipse). A `focus` off-centre gives a lit sphere.
+  - **`stroke`** — `{ "color": "#1f2a1c", "width": 0.006, "opacity": 0.8, "join": "round", "cap": "round" }`
+    — 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.
+  - **`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:
+    `"parts": [{ "path": "…", "color": "#c8501e" }, { "path": "…", "gradient": {…}, "stroke": {…}, "opacity": 0.85 }, …]`
+    (1..256), drawn back to front, each with its own `path`, `color`
+    (default: the entity's colour, so `colors` palettes still pick per
+    entity), `fillRule`, `fill`, `gradient`, `stroke` and `opacity`. With
+    `parts`, put that paint on the parts, never on the sprite. One layer
+    holds a whole illustration, and a counted layer reuses it: a balloon with
+    gores, shading, ropes and basket × 7 drifting entities, all parts moving
+    as one.
+  - **`span`** — how the unit box lands on screen: `"box"` (default, the
+    square sized by `radius`), `"width"` (x spans the full screen width; y
+    keeps `radius`), `"height"`, `"screen"` (both). **`origin`** `[x, y]` is
+    the unit-box point placed at `position`: hills and ground bands are
+    `span: "width", origin: [0, 1]` at `position: { x: 0.5, y: 1 }` — their
+    base sits on the bottom edge, edge to edge, on 16:9, 9:16 and 1:1 alike.
+    Strokes keep one width when a drawing stretches. Anything meant to sit
+    at a screen position (a moon beside its glow) is its own layer, not a
+    part of a big centred drawing — positions are screen fractions, a
+    drawing's interior is not.
+  - **Budget.** A path flattens to at most 4096 points; a scene's path
+    outlines total at most 16384 (flattened points, strokes included, ×
+    `count`). Curves cost points; straight segments and gentle curves are
+    nearly free (flattening drops points within 0.0005 of the line).
+  - **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.
+  - 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;
   `taper` thins the mark to almost nothing at both ends (a brush stroke rather
-  than a line); `orient: true` turns the path's +x along the entity's heading,
+  than a line; it paints as one filled mark, so a translucent stroke has no
+  overlap beads); `orient: true` turns the path's +x along the entity's heading,
   like `streak`. Rotates with `spin`. Van Gogh's stroke, Hokusai's contour,
   O'Keeffe's petal, Basquiat's scrawl
 - `{ "kind": "textBlock", "text": "Multi-line text with wrapping.", "maxWidth": 0.8, "fontSize": 0.04, "lineHeight": 1.4, "align": "left", "color": "#e6e8ef", "anchor": "top-left", "font": "system-ui, sans-serif", "opacity": 1 }` —
@@ -384,6 +464,12 @@ with distance, removing pop-in at the cutoff.
   advance so mono wraps land where the real face puts them; every other
   family uses the proportional table. Default `system-ui, sans-serif`.
   **Native clients fall back to the system face** until a face table exists.
+  `font` names faces **installed on the viewing device** — nothing is
+  bundled and no web font is fetched, so `'Inter'` only appears where Inter
+  is installed and every other screen falls through the stack. End every
+  stack in a generic `sans-serif`, `serif` or `monospace`; avoid ending on
+  `cursive` or `fantasy`, which resolve to a different (sometimes absurd)
+  face on every platform.
 
   `opacity` (0–1, default 1) multiplies the block's paint alpha — the whole
   block, on top of the layer's per-entity `alpha`. It is **paint**, not
@@ -479,7 +565,10 @@ and configured the second.
 - `{ "type": "wander", "speed": [0.004, 0.012], "angle": 0, "meander": 0.1, "coherence": 0.7 }`
   — organic harmonic drift: base velocity plus 3 seeded sine octaves per axis.
   Flowing curved paths with zero simulation state. `meander` scales the
-  curvature; `coherence` 0..1 blends every entity toward a shared harmonic set
+  curvature (it is the harmonics' amplitude, so it also sets how fast an
+  entity sways — keep it ≤ ~0.015 for a slow drift); it is capped at
+  **0.463** (500 px ÷ `referenceViewport`, 1080 by default — 500 under
+  `units: "px"`), and the validator rejects anything above; `coherence` 0..1 blends every entity toward a shared harmonic set
   (1 = the layer undulates as one body — fake flocking)
 - `{ "type": "warp", "speed": [0.1, 0.5], "center": { "x": 0.5, "y": 0.5 } }`
   — perspective starfield: entities stream toward the viewer on a depth axis,
@@ -860,11 +949,14 @@ moves and scales its positions and sizes (sprite rotation is not modelled).
   its own × its group's — is 0 in the base scene and at every key boundary of
   its `timeline` never shows, so it is not judged and its entities do not count
   toward `dense-scene`; coverage is weighed by paint opacity) (also on
-  `perceiveScene().advisories`). Two of them are **spatial**, for static text:
+  `perceiveScene().advisories`). Three of them are **spatial**, for static text:
   `text-off-screen` (a text/textBlock box crosses the viewport edge by more
-  than 1%) and `text-overlap` (two static text layers share more than 10% of
+  than 1%), `text-overlap` (two static text layers share more than 10% of
   the smaller box; it carries both boxes as `boxes: [{x, y, w, h}]` in
-  viewport fractions so the fix needs no re-derivation). Boxes come from the
+  viewport fractions so the fix needs no re-derivation) and
+  `layout-text-overlap` (two cells of one `list`/`table` layer do — its
+  `gap` pitch is narrower than its labels; the message names the `gap` that
+  clears them, and it carries the two boxes too). Boxes come from the
   same character-class width table the textBlock line-breaker uses, so they
   are estimates of the renderer's own layout — a caption that fails these
   will look wrong on the wall; one that passes may still sit a few px off.

package/dist/index.d.ts

@@ -334,11 +334,13 @@ interface LayerSpec {
      * - 'random': a fixed golden-ratio-stride wiring (k partners per entity,
      *   deterministic, no RNG draws) — breaks the crystalline k-nearest look.
      * `falloff` fades link alpha with distance/maxDist, killing pop-in at the cutoff.
+     * `k` and `maxDist` are required for 'nearest' and 'random'; 'chain' needs
+     * neither, except `maxDist` when `falloff` is set (it is the fade distance).
      * Capped at LIMITS.maxLinksK. Layer count must be <= LIMITS.maxLinkLayerCount when set.
      */
     links?: {
-        k: number;
-        maxDist: number;
+        k?: number;
+        maxDist?: number;
         color?: string;
         alpha?: number;
         width?: number;
@@ -547,6 +549,14 @@ type SpriteSpec = {
     color: string;
     sides?: number;
     points?: Array<[number, number]>;
+    path?: string;
+    fillRule?: 'auto' | 'nonzero' | 'evenodd';
+    fill?: boolean;
+    gradient?: PathGradient;
+    stroke?: PathStroke;
+    parts?: PathPart[];
+    span?: 'box' | 'width' | 'height' | 'screen';
+    origin?: [number, number];
     soft?: boolean;
     colors?: string[];
     colorWeights?: number[];
@@ -961,6 +971,54 @@ interface IdleSequence {
     finish?: FinishSpec;
     segments: SequenceSegment[];
 }
+/**
+ * A gradient fill for a path polygon, in the path's own −1..1 unit box (so it
+ * scales and rotates with the drawing). Overrides `color` for the fill;
+ * `color` stays what perception and palettes read when no gradient is known.
+ */
+type PathGradient = {
+    type: 'linear';
+    from: [number, number];
+    to: [number, number];
+    stops: PathGradientStop[];
+    units?: 'box' | 'part';
+} | {
+    type: 'radial';
+    center: [number, number];
+    radius: number;
+    focus?: [number, number];
+    stops: PathGradientStop[];
+    units?: 'box' | 'part';
+};
+interface PathGradientStop {
+    at: number;
+    color: string;
+    opacity?: number;
+}
+/** An outline drawn along every subpath of a path polygon (open ones too). `width` is in unit-box units. */
+interface PathStroke {
+    color: string;
+    width: number;
+    opacity?: number;
+    join?: 'round' | 'miter' | 'bevel';
+    cap?: 'round' | 'butt' | 'square';
+}
+/**
+ * One piece of a multi-colour path drawing (`polygon.parts`), drawn back to
+ * front in the drawing's unit box: its own outline, colour (default: the
+ * sprite's), gradient, stroke and opacity. A gradient with `units: 'part'`
+ * reads its coordinates in this part's own bounding box mapped to −1..1, so
+ * one gradient spec shades each piece on its own.
+ */
+interface PathPart {
+    path: string;
+    color?: string;
+    fillRule?: 'auto' | 'nonzero' | 'evenodd';
+    fill?: boolean;
+    gradient?: PathGradient;
+    stroke?: PathStroke;
+    opacity?: number;
+}
 
 declare function validateSpec(spec: unknown): ValidationResult;
 /**
@@ -1164,15 +1222,25 @@ interface LinkEdge {
     j: number;
     dist: number;
 }
+/**
+ * `links.maxDist` in px at `scale` (px per spec unit), or `Infinity` when it is
+ * absent — a chain needs no cutoff. Callers apply `falloff` only to a finite
+ * value, so an absent `maxDist` can never put NaN into an alpha.
+ */
+declare function linkMaxDistPx(links: {
+    maxDist?: number;
+}, scale: number): number;
 /**
  * Edge list for a layer's `links`, dispatching on mode:
  * 'nearest' (default) k-nearest within maxDist; 'chain' sequential order
  * (Mystify — ignores k/maxDist, `closed` joins last to first); 'random' a fixed
  * golden-ratio-stride wiring filtered by maxDist (deterministic, no RNG draws).
+ * An absent `k` reads as 1 and an absent `maxDist` (`Infinity` from
+ * `linkMaxDistPx`) as no cutoff; the validator requires both outside chain mode.
  */
 declare function linkEdges(links: {
-    k: number;
-    maxDist: number;
+    k?: number;
+    maxDist?: number;
     mode?: 'nearest' | 'chain' | 'random';
     closed?: boolean;
 }, positions: Array<{
@@ -1379,7 +1447,8 @@ declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): Saver
 /**
  * Interpolate between two structurally-similar specs at progress k (0..1).
  * Numbers lerp, hex colours lerp per channel, everything else steps to the
- * target immediately (k > 0). Layer counts round to integers.
+ * target immediately (k > 0). Layer counts, and a field background's
+ * `octaves` / `quantize`, round to whole values.
  */
 declare function lerpSpec(from: SaverSpec, to: SaverSpec, k: number): SaverSpec;
 /**
@@ -1390,6 +1459,13 @@ declare function lerpSpec(from: SaverSpec, to: SaverSpec, k: number): SaverSpec;
  * timeline, so every stored morph and glide is unchanged.
  */
 declare function lerpValue(from: unknown, to: unknown, k: number, specRoot?: boolean, rootKey?: string): unknown;
+/**
+ * Interpolate two SVG path d strings that share their structure — the same
+ * command letters in the same order and the same count of numbers — by
+ * lerping every number; null when they differ in structure (the morph then
+ * steps). Arc flags (0/1) round, so a half-way arc stays a valid arc.
+ */
+declare function lerpPathD(a: string, b: string, k: number): string | null;
 /**
  * The string(s) a text layer paints — `strings` of a `text` sprite, `text`
  * of a `textBlock` — or null for every other sprite.
@@ -1642,9 +1718,9 @@ interface LuminanceGridOptions extends PerceiveOptions {
  * re-uses drawTrail's sampling — past positions with decaying alpha and
  * 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.
+ * Remaining approximations (documented, deliberate): 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;
 /**
@@ -2677,4 +2753,89 @@ 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 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 };
+/**
+ * Shape glyph geometry — pure, renderer-free, shared by the compiler (what to
+ * stroke/fill), perception (how much ink that is) and advise. Everything is
+ * computed from the sprite spec + the entity's seeded size, so the canvas and
+ * the analytic model agree by construction.
+ *
+ * Unit coordinates: `polygon.points` and `stroke.points` live in a −1..1 box
+ * that is scaled by the entity's half-size (circumradius for polygons, half of
+ * `length` for strokes), so the seeded size range is the glyph's bounding
+ * diameter — the same rule `circle.radius` / `streak.length` already follow.
+ */
+
+type PolygonSprite = Extract<SpriteSpec, {
+    kind: 'polygon';
+}>;
+/** Most outline points one flattened path may produce. */
+declare const MAX_PATH_POINTS = 4096;
+interface FlattenedPath {
+    /** One closed ring: subpaths joined by zero-width bridges, inner ones wound as holes. */
+    points: Array<[number, number]>;
+    subpaths: number;
+    /** Every subpath as drawn (simplified, no bridges), for strokes: open unless it ended in Z. */
+    lines: Array<{
+        points: Array<[number, number]>;
+        closed: boolean;
+    }>;
+    /** Parse error, if the string is not a usable path. */
+    error?: string;
+}
+/**
+ * How a path's subpaths combine. `auto` (default): containment decides which
+ * subpaths are holes (see joinRings) — for authors who never think about
+ * winding. `nonzero` / `evenodd`: SVG's own fill rules, honouring the winding
+ * as drawn — for pasted SVG, and for a deliberate same-colour shape that sits
+ * inside another (auto would read it as a hole).
+ */
+type PathFillRule = 'auto' | 'nonzero' | 'evenodd';
+declare function flattenPath(d: string, rule?: PathFillRule): FlattenedPath;
+/** A polygon drawn from SVG paths: one `path`, or a multi-colour drawing of `parts`. */
+declare function isPathPolygon(s: SpriteSpec): boolean;
+/** One drawable piece of a path polygon, resolved: its outline, paint and part-space box. */
+interface ResolvedPart {
+    flat: FlattenedPath;
+    /** Its own colour, or null to use the entity's (sprite colour / palette pick). */
+    color: string | null;
+    fill: boolean;
+    rule: 'nonzero' | 'evenodd';
+    gradient?: PathGradient;
+    stroke?: PathStroke;
+    opacity: number;
+    /** The fill's bounding box in the unit box (centre + half extents) — the space of `gradient.units: 'part'`. */
+    box: {
+        cx: number;
+        cy: number;
+        hw: number;
+        hh: number;
+    };
+}
+/**
+ * A path polygon as an ordered list of parts, back to front. A single
+ * `path` is a drawing of one part (its colour the entity's), so the renderer,
+ * perception and the budget treat both forms one way. Memoised per sprite.
+ */
+declare function pathParts(s: PolygonSprite): ResolvedPart[];
+/**
+ * How a path drawing's −1..1 unit box lands on screen, in px: scale per axis
+ * (sx, sy) and the unit-box point (ox, oy) that sits at the entity position.
+ *   span 'box' (default): uniform, the entity radius r on both axes — the
+ *     classic square box sized by the short side;
+ *   'width': x spans the full screen width (sx = w/2), y keeps r — skylines,
+ *     hills and ground bands that must reach both side edges on any aspect;
+ *   'height': y spans the full height, x keeps r;
+ *   'screen': both — a frame or wash that hugs every edge.
+ * `origin` [ox, oy] picks the anchored point: [0, 1] with position y = 1 sets
+ * the drawing's bottom on the screen's bottom edge. Strokes keep the uniform
+ * r for their width, so stretching never fattens an outline sideways.
+ */
+declare function pathFrame(s: PolygonSprite, r: number, w: number, h: number): {
+    sx: number;
+    sy: number;
+    ox: number;
+    oy: number;
+    uniform: boolean;
+};
+
+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, type FlattenedPath, 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, MAX_PATH_POINTS, MURMUR_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PathGradient, type PathGradientStop, type PathPart, type PathStroke, type PerceiveOptions, type PerceiveSequenceOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedPart, 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, flattenPath, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, isPathPolygon, latticeHash, layerCohesion, lerpPathD, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkMaxDistPx, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, pathFrame, pathParts, 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 };