@idle-screens/schema 3.12.1 → 3.14.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
 
@@ -302,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)
 
@@ -349,7 +353,68 @@ with distance, removing pop-in at the cutoff.
   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
+  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.
@@ -425,7 +490,9 @@ with distance, removing pop-in at the cutoff.
   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
@@ -744,7 +811,16 @@ 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.
 - 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
@@ -897,14 +973,25 @@ 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.
   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

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<{
@@ -1376,6 +1444,16 @@ interface SteerDelta {
 }
 /** Apply deltas to a deep copy of the spec (last-wins, target values). */
 declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): SaverSpec;
+/**
+ * `applyDeltasToSpec` for read-only callers: the same result, but every
+ * subtree a delta does not touch is shared with `spec` — only the containers
+ * on each delta's path are copied. The validator checks a timeline by applying
+ * each key, and the composed keys at every sample time, to the whole spec; a
+ * full deep copy per check was most of the cost of validating a long timeline
+ * (a 132 KB scene spent ~60% of its CPU in JSON round-trips). The result
+ * aliases `spec`, so it must never be mutated.
+ */
+declare function applyDeltasShared(spec: SaverSpec, deltas: SteerDelta[]): SaverSpec;
 /**
  * Interpolate between two structurally-similar specs at progress k (0..1).
  * Numbers lerp, hex colours lerp per channel, everything else steps to the
@@ -1391,6 +1469,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.
@@ -1541,12 +1626,25 @@ declare function cohesionOf(layers: Array<{
     layer: LayerSpec;
     entities: Entity[];
 }>, t: number, w: number, h: number): LayerCohesion[];
+/**
+ * Mean fraction of an entity's filled AREA covered by a same-layer sibling,
+ * 0..1 — the counterpart of `overlap`, which measures outline. Edge contact
+ * buries outline and no area; a real pile buries both. `null` where
+ * `cohesionOf` reports no overlap.
+ */
+declare function buriedAreaOf(layer: LayerSpec, entities: Entity[], t: number, w: number, h: number): number | null;
 /**
  * True when a `seamed` layer is worth warning about: dense enough to be
  * deliberate, and opaque enough that it cannot be an atmospheric wash. Keeps
  * the advisory off the soft low-alpha glow fields the playbook recommends.
+ *
+ * `buriedArea` (lazy, from {@link buriedAreaOf}) lets it also stay off a
+ * TILING whose only seam is its palette: opaque hard tiles of unlike colour
+ * that butt edge to edge show one clean colour boundary per join, which is
+ * the banding the author drew (X574). A translucent tiling is still warned
+ * about — each hairline overlap paints a darker line.
  */
-declare function seamsWorthWarning(layer: LayerSpec, c: LayerCohesion, entityCount: number): boolean;
+declare function seamsWorthWarning(layer: LayerSpec, c: LayerCohesion, entityCount: number, buriedArea?: () => number | null): boolean;
 
 interface LayerSnapshot {
     key: string | undefined;
@@ -1643,9 +1741,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;
 /**
@@ -1952,6 +2050,20 @@ interface PerceiveSequenceOptions extends Omit<LuminanceGridOptions, 't'> {
  */
 declare function perceiveSequenceFrame(seq: IdleSequence, T: number, opts?: PerceiveSequenceOptions): SequenceFramePerception;
 
+interface TimelineFlashReport {
+    /** More than 3 flashes in some one-second window over at least a quarter of the frame (WCAG 2.3.1). */
+    fails: boolean;
+    /** Worst flashes per second any part of the frame reaches (0 when nothing was dense enough to check). */
+    flashesPerSecond: number;
+    /** Fraction of the frame flashing more than 3 times a second. */
+    flashingArea: number;
+    /** Start (scene ms, within the lap) of the worst window checked, or null when none was checked. */
+    at: number | null;
+    /** Set (with `fails`) when dense sections remained beyond the {@link MAX_TOTAL_SAMPLES} budget: unchecked is never reported as safe. */
+    incomplete?: true;
+}
+declare function timelineFlashReport(spec: SaverSpec): TimelineFlashReport;
+
 /**
  * The `field` background sampler — seeded, dependency-free value noise that
  * is a PURE function of `(u, v, t, config, seed)`.
@@ -2277,8 +2389,9 @@ 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.
+ * `shared` (read-only callers): untouched subtrees alias `spec` — never mutate the result.
  */
-declare function resolveTimelineAt(spec: SaverSpec, t: number): SaverSpec;
+declare function resolveTimelineAt(spec: SaverSpec, t: number, shared?: boolean): 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
@@ -2678,4 +2791,90 @@ 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, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, DASHBOARD_SPEC, DEFAULT_KEY_DUR, DITHER_ALPHA, DITHER_TILE, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, GRAIN_ALPHA, GRAIN_TILE, HAIKU_SPEC, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, MATRIX_RAIN_SPEC, MAX_PATH_POINTS, MURMUR_SPEC, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, RAIN_SPEC, RELAY_BOARD_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, adviseSequence, adviseSpec, alphaAt, applyDeltasShared, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, buriedAreaOf, 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, timelineFlashReport, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, validateSequence, validateSpec, validateSpecPaths, withoutTimeline };
+export type { BackgroundDrift, BackgroundSpec, BandSpec, CapabilityTier, CohesionRead, CycleSpec, DominanceEntry, Entity, FieldBackground, FieldDrift, FinishPass, FinishSpec, FlattenedPath, GradientStop, IdleSequence, LayerCohesion, LayerGroup, LayerMotionStats, LayerSnapshot, LayerSpec, LayerTransform, LinkEdge, LuminanceGrid, LuminanceGridOptions, MotionEase, MotionSpec, PathGradient, PathGradientStop, PathPart, PathStroke, PerceiveOptions, PerceiveSequenceOptions, Placed, ResolveOptions, ResolvedPart, ResolvedSegment, RevealState, SaverSpec, SceneColour, SceneDescription, SceneDiff, ScenePerception, SceneSnapshot, SchemaExample, ScreenOp, SequenceExample, SequenceFramePerception, SequenceMountContext, SequenceSaverInstance, SequenceSaverPlugin, SequenceSegment, SequenceTransition, SpecError, SpecMountContext, SpecWarning, SpriteSpec, SteerDelta, TextBlockAnchor, TextBlockLine, TextMetricsClass, TextRevealInput, TextRevealSpec, TextRole, TextSpriteInfo, Timeline, TimelineFlashReport, TimelineKey, ValidationResult, WanderOsc, WarningBox };