@idle-screens/schema 3.14.0 → 3.15.0

package/dist/index.d.ts

@@ -194,11 +194,22 @@ interface TimelineKey {
     path: string;
     /** The target value; the key must still validate when applied. */
     value: unknown;
-    /** Default `smooth`. */
-    ease?: 'step' | 'linear' | 'smooth';
+    /** Default `smooth`. See `GlideEase`. */
+    ease?: GlideEase;
     /** Glide length in ms, starting at `t`. Default 1000 (as live steering); 0 = a cut. */
     dur?: number;
 }
+/**
+ * How a glide moves between its two values. `smooth` (default) starts and
+ * ends at rest; `linear` is constant speed; `step` holds, then switches at
+ * the glide's end. `in` accelerates from rest and arrives at speed (a
+ * departure); `out` leaves at speed and decelerates into place (an
+ * arrival); `spring` is a critically damped spring — a fast start that
+ * settles with no overshoot, so every value stays between its two ends.
+ * Every ease is monotone, so a glide never leaves the range its endpoints
+ * bound. **Native:** an ease it does not know reads as `smooth`.
+ */
+type GlideEase = 'step' | 'linear' | 'smooth' | 'in' | 'out' | 'spring';
 /**
  * Authored change on the scene's own clock — keyframes. A scene without a
  * timeline is unchanged (ambient, today's behaviour); with one, each key
@@ -373,7 +384,8 @@ interface LayerSpec {
     }
     /**
      * Data layouts — entities in READING ORDER, no scatter. `list` stacks them
-     * in one column `gap` apart (viewport units of min(w,h), default 0.06);
+     * in one column `gap` apart (viewport units of min(w,h), default 0.06;
+     * `{y}` alone also works — a list has no columns, so `x` does nothing);
      * `table` fills `columns` row-major with `gap` `{x, y}` (one number = both).
      * Text and emoji sprites take `strings[i]` / `glyphs[i]` in order instead of
      * a seeded pick, and palette `colors[i]` likewise, so N labels or N bars are
@@ -382,7 +394,10 @@ interface LayerSpec {
      */
      | {
         type: 'list';
-        gap?: number;
+        gap?: number | {
+            x?: number;
+            y?: number;
+        };
     } | {
         type: 'table';
         columns: number;
@@ -395,11 +410,33 @@ interface LayerSpec {
      * Layer lifecycle for act structure — a pure function of t, no state. Alpha is 0
      * before `enter` (ms), ramps up over `fade` ms (default 1000), holds at 1, then
      * ramps down starting at `exit`. Entities are skipped entirely while at alpha 0.
+     * `stagger` (ms, default 0) shifts entity i's whole envelope — its enter and
+     * its exit — by i × stagger, in the layer's entity order (reading order for
+     * `list` / `table` / `grid`), so a row of labels builds one after another
+     * instead of together. Paint, like the rest of `life`: it glides, draws
+     * nothing from the RNG, and on screens where density scaling changes the
+     * count the whole build takes (count − 1) × stagger. **Native:** ignored ⇒
+     * every entity enters together.
      */
     life?: {
         enter?: number;
         exit?: number;
         fade?: number;
+        stagger?: number;
+    };
+    /**
+     * A swing back and forth: each entity rotates `amp` degrees either side of
+     * its resting angle (`rotate` plus any `spin`), once per `period` ms, on a
+     * seeded per-entity phase — a boat on a swell, a hanging sign, a lantern,
+     * a jellyfish's lean. A `clock` replaces the seeded phase like `pulse`'s,
+     * so a clocked layer swings in step. Structural (baked per entity like
+     * `pulse`). Its phase is one seeded draw per entity, made last and only
+     * when declared, so existing specs keep identical streams. **Native:**
+     * ignored ⇒ no swing.
+     */
+    rock?: {
+        amp: number;
+        period: number;
     };
     /**
      * Sparse events — marks that appear, expand and fade in place, one at a time,
@@ -579,6 +616,8 @@ type SpriteSpec = {
     curve?: 'smooth' | 'linear';
     taper?: boolean;
     orient?: boolean;
+    /** Draw-on: the stretch of the mark that is painted — see `StrokeDraw`. Absent ⇒ the whole mark. */
+    draw?: StrokeDraw;
     colors?: string[];
     colorWeights?: number[];
 }
@@ -624,7 +663,28 @@ type SpriteSpec = {
     opacity?: number;
     /** See `TextRole`. Absent ⇒ no legibility advisories, no pixel change. */
     role?: TextRole;
+    /** A number the block shows instead of `text` — see `TextNumber`. */
+    number?: TextNumber;
 };
+/**
+ * A counter: the block paints `prefix + value + suffix` instead of `text`,
+ * with `value` rounded to `decimals` places (default 0) and, unless
+ * `grouping: false`, its thousands separated by commas — formatted the same
+ * way on every device (never by locale). `value` is **paint**: steer
+ * `sprite.number.value` (or key it on the timeline) and the digits roll
+ * there over the glide. Line-breaking runs on the formatted string, so a
+ * counter that gains a digit can re-wrap — give it room (`maxWidth`) or an
+ * `anchor` that pins the edge you want still. `text` stays what clients
+ * that do not read `number` show — author it as the counter's rest value.
+ * **Native:** ignored ⇒ `text`.
+ */
+interface TextNumber {
+    value: number;
+    decimals?: number;
+    prefix?: string;
+    suffix?: string;
+    grouping?: boolean;
+}
 /**
  * What a text layer is *for* — a declaration, not a pixel. `read` says the
  * words must be readable from across the room and opts the layer into
@@ -679,6 +739,14 @@ interface TextRevealSpec {
      * wave of overlapping fades. Ignored by the other modes.
      */
     fade?: number;
+    /**
+     * `glyphFade` only: each glyph rises into place as it fades in, from
+     * `rise` em below its line (0..1, default 0) — the caption that lifts as
+     * it appears. A pure function of the glyph's fade, so it glides, deletes
+     * and seeks like the rest of reveal; layout never moves. **Native:**
+     * ignored ⇒ no rise.
+     */
+    rise?: number;
 }
 /** Rotate through sprite variants over time. Each entity offsets by its seeded phase. */
 interface CycleSpec {
@@ -686,11 +754,12 @@ interface CycleSpec {
 }
 type MotionSpec = 
 /**
- * Drift at a per-entity speed picked from `speed` (px/sec) along `angle` degrees
+ * Drift at a per-entity speed picked from `speed` (min(w,h) per second; px/sec under `units: 'px'`) along `angle` degrees
  * (0 = right, 90 = down; default 0). `bidirectional` randomly flips horizontal
  * direction per entity (e.g. fish swimming both ways); `bob` adds a small vertical
- * wobble amplitude (px). Covers horizontal fields, diagonals (toasters) and rain
- * (angle 90).
+ * wobble amplitude, in the spec's dimensional unit like `speed` — a fraction of
+ * min(w,h) (0.004 ≈ 4 px at 1080p), px only under `units: 'px'`. Covers
+ * horizontal fields, diagonals (toasters) and rain (angle 90).
  */
 {
     type: 'drift';
@@ -700,14 +769,18 @@ type MotionSpec =
     bob?: number;
     ease?: MotionEase;
 }
-/** Rise upward (px/sec) with an optional horizontal sway amplitude (px) — bubbles. */
+/**
+ * Rise upward with an optional horizontal `sway` amplitude — bubbles. Speed
+ * is min(w,h) per second and `sway` a fraction of min(w,h) (px/sec and px
+ * only under `units: 'px'`).
+ */
  | {
     type: 'rise';
     speed: [number, number];
     sway?: number;
     ease?: MotionEase;
 }
-/** Bounce diagonally at a per-entity speed, reflecting off the edges (px/sec). */
+/** Bounce diagonally at a per-entity speed, reflecting off the edges (min(w,h) per second; px/sec under `units: 'px'`). */
  | {
     type: 'bounce';
     speed: [number, number];
@@ -878,11 +951,18 @@ declare const LIMITS: {
     readonly minClockedPeriod: 1000;
     readonly minClockRate: 0.1;
     readonly maxClockRate: 4;
+    readonly maxWobble: 0.25;
     readonly defaultListGap: 0.06;
     readonly defaultListGapPx: 40;
     readonly minPolygonSides: 3;
     readonly maxPolygonSides: 12;
     readonly maxShapePoints: 24;
+    readonly maxTextNumberDecimals: 6;
+    readonly maxTextAffix: 64;
+    readonly maxRevealRise: 1;
+    readonly maxRockAmp: 45;
+    readonly minRockPeriod: 1000;
+    readonly maxLifeStagger: 60000;
     readonly minEaseTau: 100;
     readonly maxEaseTau: 120000;
 };
@@ -915,7 +995,32 @@ type SequenceTransition = {
  | {
     type: 'fade';
     dur: number;
-};
+}
+/**
+ * Wipe into the next segment over `dur` ms: the incoming segment is
+ * revealed 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 across the frame along `angle` degrees (0 = left to right, 90 = top
+ * to bottom). `feather` (0..1, default 0.08) softens the edge, as a
+ * fraction of the distance it travels. Works between unlike segments,
+ * like `fade`, on the same two-live-segment machinery and the same tier
+ * gate (`basic` / `minimal` hosts cut). Every pixel changes once, so it is
+ * a spatial ramp, never a flash. **Native:** cross-fades over `dur`.
+ */
+ | WipeTransition;
+/** See the `wipe` member of `SequenceTransition`. */
+interface WipeTransition {
+    type: 'wipe';
+    dur: number;
+    shape?: 'circle' | 'line';
+    origin?: {
+        x: number;
+        y: number;
+    };
+    angle?: number;
+    feather?: number;
+}
 interface SequenceSegment {
     key: string;
     scene: SaverSpec;
@@ -995,13 +1100,31 @@ interface PathGradientStop {
     color: string;
     opacity?: number;
 }
-/** An outline drawn along every subpath of a path polygon (open ones too). `width` is in unit-box units. */
+/**
+ * An outline drawn along every subpath of a path polygon (open ones too).
+ * `width` is in unit-box units. `draw` paints only a stretch of it — see
+ * `StrokeDraw`: every subpath of the part counts as one pen line, in the
+ * order the path draws them.
+ */
 interface PathStroke {
     color: string;
     width: number;
     opacity?: number;
     join?: 'round' | 'miter' | 'bevel';
     cap?: 'round' | 'butt' | 'square';
+    draw?: StrokeDraw;
+}
+/**
+ * Draw-on for a line: only the stretch from `start` to `end` (fractions of
+ * the line's arc length, 0..1, defaults 0 and 1) is painted, so gliding
+ * `end` from 0 to 1 draws the line on as if by a pen, and gliding `start`
+ * after it erases it from the tail. Paint: both glide under a steer, a
+ * `timeline` key or a `morph` without a rebuild. `start ≥ end` paints
+ * nothing. **Native:** ignored ⇒ the whole line.
+ */
+interface StrokeDraw {
+    start?: number;
+    end?: number;
 }
 /**
  * One piece of a multi-colour path drawing (`polygon.parts`), drawn back to
@@ -1020,6 +1143,21 @@ interface PathPart {
     opacity?: number;
 }
 
+/**
+ * Every motion type's fields besides `type` — the validator's allowlist, and
+ * the source FORMAT.md's motion table is checked against (F74), so the table
+ * cannot drift from what the validator accepts.
+ */
+declare const MOTION_FIELDS: {
+    readonly drift: readonly ["speed", "angle", "bidirectional", "bob", "ease"];
+    readonly rise: readonly ["speed", "sway", "ease"];
+    readonly bounce: readonly ["speed"];
+    readonly static: readonly [];
+    readonly orbit: readonly ["speed", "radius", "center"];
+    readonly wander: readonly ["speed", "angle", "meander", "coherence", "ease"];
+    readonly warp: readonly ["speed", "center"];
+    readonly path: readonly ["points", "duration", "curve", "closed", "scatter"];
+};
 declare function validateSpec(spec: unknown): ValidationResult;
 /**
  * Dot-paths (numeric layer indices, as `steerablePaths` spells them) of every
@@ -1038,8 +1176,11 @@ declare function ignoredPropertyPaths(spec: unknown): string[];
  * `validateSpec`. For the timeline's composed-state checks, which run at every
  * key boundary and on every live steer: the whole-spec check costs a
  * full validation per sample, this one a layer or two.
+ *
+ * `keyed`: the spec is a timeline state (a key's value, or mid-glide), where a
+ * path that collapses to nothing draws nothing instead of failing (X583).
  */
-declare function validateSpecPaths(spec: SaverSpec, paths: Iterable<string>): boolean;
+declare function validateSpecPaths(spec: SaverSpec, paths: Iterable<string>, keyed?: boolean): boolean;
 /** Narrowing helper: validate + cast. Throws with a joined message when invalid. */
 declare function assertValidSpec(spec: unknown): SaverSpec;
 /**
@@ -1156,6 +1297,12 @@ interface Entity {
     };
     /** Static rotation (radians), added to any spin. Only set when `layer.rotate` is declared. */
     rotate?: number;
+    /** `rock`: amplitude (radians), period (ms) and phase (radians; a clock's shared phase when clocked). */
+    rock?: {
+        amp: number;
+        period: number;
+        phase: number;
+    };
     /** Spline params (pts in px, shared per layer). Only set for path motion. */
     path?: {
         pts: Array<{
@@ -1180,6 +1327,16 @@ declare function spriteVariants(sprite: SpriteSpec): number;
  *  `scale` multiplies every dimensional draw (default 1). Used for viewport units.
  *  `countScale` multiplies entity count for density-aware scaling (default 1). */
 declare function buildEntities(layer: LayerSpec, rng: Rng, w: number, h: number, scale?: number, countScale?: number): Entity[];
+/**
+ * The string a `textBlock` paints: its `text`, or with `number` the
+ * counter's `prefix + value + suffix` — rounded to `decimals`, thousands
+ * grouped with commas unless `grouping: false`. Locale-free, so every
+ * device draws the same digits.
+ */
+declare function textBlockText(s: {
+    text: string;
+    number?: TextNumber;
+}): string;
 /**
  * Where entity `e` sits in its current emit window at time `t`: 0..1 across
  * the visible `life` ms, or null while dark (or when the layer has no `emit`).
@@ -1200,12 +1357,29 @@ declare function sizeAt(e: Entity, t: number): number;
  * `rotate` is for).
  */
 declare function rotationAt(e: Entity, t: number): number;
-/** Layer lifecycle alpha multiplier at time `t` (ms). Pure. 1 when `life` is unset. */
+/**
+ * Layer lifecycle alpha multiplier at time `t` (ms). Pure. 1 when `life` is
+ * unset. With `stagger` this is the layer's GATE only — 0 before the first
+ * entity enters, else 1 — and each entity's own envelope is
+ * `lifeStaggerAt(life, t, i)`.
+ */
 declare function lifeAlphaAt(life: {
     enter?: number;
     exit?: number;
     fade?: number;
+    stagger?: number;
 } | undefined, t: number): number;
+/**
+ * Entity i's share of a staggered `life`: its whole envelope shifted by
+ * i × stagger. 1 without a stagger (the layer's `lifeAlphaAt` already
+ * carries the envelope), so callers multiply it in unconditionally.
+ */
+declare function lifeStaggerAt(life: {
+    enter?: number;
+    exit?: number;
+    fade?: number;
+    stagger?: number;
+} | undefined, t: number, i: number): number;
 /** Analytic position of an entity at logical time `t` (ms). Pure & deterministic. */
 declare function positionAt(e: Entity, t: number, w: number, h: number): Placed;
 /**
@@ -1266,11 +1440,23 @@ type TextMetricsClass = 'proportional' | 'mono';
  * family), else `proportional`. Absent font ⇒ proportional, as before.
  */
 declare function textMetricsClassFor(font?: string): TextMetricsClass;
+/** Combining (semi-)voiced sound marks: they ride on the preceding kana and advance nothing. */
+declare function isCombiningKana(cp: number): boolean;
+/**
+ * Whether a code point is set full-width — a CJK ideograph, kana, Hangul
+ * syllable, CJK punctuation or a fullwidth form — so it advances ~1 em, not
+ * the 0.55 of a Latin letter (X614: a centred katakana line measured at half
+ * its real width and spilled off the frame). Halfwidth kana and Hangul
+ * (U+FF61–FFDC) stay narrow. A fixed table, for the same determinism reason
+ * as the buckets below.
+ */
+declare function isFullWidth(cp: number): boolean;
 /**
  * Em-width of a string under the same character-class table `breakTextBlock`
  * uses. `mono` counts grapheme clusters, not UTF-16 code units — an emoji or
  * combining/ZWJ sequence is one advance-width cell, matching what's painted,
- * not one cell per surrogate half or combining mark.
+ * not one cell per surrogate half or combining mark. Under either table a
+ * full-width (CJK) glyph advances a full em.
  */
 declare function textWidthEm(str: string, metrics?: TextMetricsClass): number;
 interface TextBlockLine {
@@ -1356,6 +1542,14 @@ type CapabilityTier = 'minimal' | 'basic' | 'standard' | 'high';
 interface SpecMountContext extends SaverContext {
     capabilityTier?: CapabilityTier;
 }
+/**
+ * A wipe's revealed region at progress `k` as a fill: opaque where the
+ * incoming segment shows, clear where the outgoing still does, ramping over
+ * the feathered edge — in the canvas's own pixels (`cw` × `ch`). The edge
+ * starts just outside the frame and ends past its far side (feather
+ * included), so k = 0 reveals nothing and k = 1 everything.
+ */
+declare function wipeMask(g: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, w: WipeTransition, k: number, cw: number, ch: number): CanvasGradient;
 /**
  * Compile a declarative spec into a runnable SaverPlugin. Throws if the spec is invalid
  * (so an agent-authored spec is validated before it can run). The result is seeded,
@@ -1516,6 +1710,16 @@ declare function steerablePaths(spec: unknown): string[];
 declare function sequenceSteerablePaths(seq: IdleSequence): string[];
 /** Smooth (ease-in-out) progress curve used for glides. */
 declare function easeSmooth(k: number): number;
+/**
+ * A glide's progress curve, by name (`GlideEase`), for progress `k` (0..1).
+ * Every curve is monotone and runs 0 → 1, so an eased value never leaves the
+ * range its two endpoints bound. `spring` is the critically damped step
+ * response 1 − (1 + ωk)e^(−ωk), normalised to land exactly on 1 at k = 1.
+ * Anything unknown is `smooth` (today's default).
+ */
+declare function easeGlide(ease: string | undefined, k: number): number;
+/** The named eases a live steer honours (the ones that did not exist before steers carried an ease). */
+declare const STEER_EASES: ReadonlySet<string>;
 /**
  * Fields that require re-seeding entities when they change (placement/motion
  * are baked at build time). Colour/alpha/pulse-only changes redraw in place.
@@ -1746,6 +1950,15 @@ interface LuminanceGridOptions extends PerceiveOptions {
  * balance — and now smear.
  */
 declare function luminanceGrid(spec: SaverSpec, opts?: LuminanceGridOptions): LuminanceGrid;
+/**
+ * The luminance-grid cells each layer can paint (same viewport, seed and
+ * grid as `luminanceGrid` with these options), for the timeline flash gate's
+ * shortcut: per layer its cell indices, or null when its footprint is not
+ * fixed — it moves, emits, links, trails, orbits or cycles its text — and so may reach
+ * any cell. Each entity is a disc about its position that holds its whole
+ * outline at its largest size under any rotation: generous, never short.
+ */
+declare function layerCellFootprints(spec: SaverSpec, opts?: LuminanceGridOptions): Array<number[] | null>;
 /**
  * Encode a luminance grid as a braille "image": each output character is a 2×4
  * pixel cell, ordered-dithered so mid-tones render as dot density. A grid of
@@ -2059,8 +2272,16 @@ interface TimelineFlashReport {
     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. */
+    /**
+     * Set (with `fails`) when dense sections remained beyond the
+     * {@link MAX_TOTAL_SAMPLES} budget: unchecked is never reported as safe.
+     * `flashesPerSecond` and `flashingArea` then describe only what was checked
+     * (often nothing), so a message must say the timeline was too dense to
+     * verify, not quote them as a strobe.
+     */
     incomplete?: true;
+    /** With `incomplete`: the paint-key boundaries in the busiest second of the window left unchecked. */
+    boundariesPerSecond?: number;
 }
 declare function timelineFlashReport(spec: SaverSpec): TimelineFlashReport;
 
@@ -2363,7 +2584,7 @@ declare function sequenceSwapCompatible(prev: IdleSequence, next: IdleSequence):
  *   exist on the spec (a key cannot create a field).
  * - A key glides from wherever its path is at `t` to `value` over `dur` ms
  *   (default 1000, the live-steering default; 0 is a cut), eased `smooth`
- *   unless it says otherwise. Overlapping glides are fine: the later one
+ *   unless it names another `GlideEase`. Overlapping glides are fine: the later one
  *   starts from the earlier one's in-flight value.
  * - Without `loop`, a path holds the base spec's value before its first key.
  * - With `loop`, time wraps every `duration` ms and a path's value before its
@@ -2416,6 +2637,42 @@ declare function timelineSampleTimes(spec: SaverSpec, dense?: boolean, cap?: num
 /** The absolute scene times at or after `now` where `timelineSampleTimes` fall — the next lap's occurrences under `loop`. */
 declare function timelineSampleTimesAfter(spec: SaverSpec, now: number, dense?: boolean, only?: (path: string) => boolean): number[];
 
+/**
+ * The scene's own repeat period — how long until every frame comes round
+ * again — read analytically from the spec, never by rendering.
+ *
+ * A scene is a pure function of time, so it repeats exactly when every
+ * time-varying part does: each periodic part contributes its period, and the
+ * scene's is their least common multiple (in whole ms). Anything that never
+ * repeats — a seeded speed range, a drift that wraps at a per-entity speed,
+ * a `life` build, a non-looping timeline, a self-typing reveal, animated
+ * grain — makes the scene aperiodic, and the reason says which part. A scene
+ * with nothing time-varying is static: every frame is the same (period 0).
+ *
+ * Who reads it: an export that wants an exact loop (#84), and the
+ * `loop-seam` advisory, which fires only when a scene declares a looping
+ * timeline whose lap the rest of the scene does not divide.
+ */
+
+/** Periods that share no cycle shorter than this are reported as aperiodic. */
+declare const MAX_SCENE_PERIOD = 3600000;
+interface ScenePeriod {
+    /** ms until the scene repeats exactly; 0 for a static scene; null when it never does (within an hour). */
+    period: number | null;
+    /** One line per part that sets or breaks the period, e.g. `layers[2] pulse: 4000 ms`. */
+    parts: string[];
+    /** Why it is null (empty otherwise). */
+    reasons: string[];
+}
+/** The repeat period of `spec` — see the module comment. */
+declare function scenePeriod(spec: SaverSpec): ScenePeriod;
+/**
+ * The period of everything in the scene except its timeline — what a
+ * looping timeline's lap has to be a multiple of for one lap to loop
+ * seamlessly.
+ */
+declare function periodWithoutTimeline(spec: SaverSpec): ScenePeriod;
+
 /**
  * Reproduces the hand-coded Fish Aquarium saver as pure DATA — the discriminating test
  * that the schema is actually expressive: two layers (fish drifting both ways at varied
@@ -2806,6 +3063,54 @@ declare const EXAMPLE_BY_ID: Readonly<Record<string, SaverSpec>>;
 type PolygonSprite = Extract<SpriteSpec, {
     kind: 'polygon';
 }>;
+type StrokeSprite = Extract<SpriteSpec, {
+    kind: 'stroke';
+}>;
+/** A stroke sprite's sampled path as painted: `strokeSamples`, cut to its `draw` span when it has one. */
+declare function strokeDrawnSamples(s: StrokeSprite, halfSize: number): Array<{
+    x: number;
+    y: number;
+}>;
+/**
+ * The [start, end] arc-length fractions a `draw` paints, clamped to 0..1 — or
+ * null when it paints the whole line (absent, or 0..1), so the caller keeps
+ * its untrimmed (cached) geometry.
+ */
+declare function drawSpan(d: StrokeDraw | undefined): [number, number] | null;
+/** The stretch of a polyline between arc-length fractions `a` and `b` (a ≥ b ⇒ empty). Endpoints are interpolated. */
+declare function trimPolyline(pts: Array<{
+    x: number;
+    y: number;
+}>, a: number, b: number): Array<{
+    x: number;
+    y: number;
+}>;
+/**
+ * A part's subpaths cut to a `draw` span: the lines are one pen run in draw
+ * order (a closed ring counts its closing edge), so `end` sweeps through the
+ * first subpath, then the next. A trimmed ring comes back open; untouched
+ * lines are returned as they were. Memoised per (lines, span).
+ */
+declare function trimLines(lines: Array<{
+    points: Array<[number, number]>;
+    closed: boolean;
+}>, a: number, b: number): Array<{
+    points: Array<[number, number]>;
+    closed: boolean;
+}>;
+/** A part's stroke lines as drawn: its subpaths, cut to its stroke's `draw` span when it has one. */
+declare function strokeLines(part: {
+    flat: {
+        lines: Array<{
+            points: Array<[number, number]>;
+            closed: boolean;
+        }>;
+    };
+    stroke?: PathStroke;
+}): Array<{
+    points: Array<[number, number]>;
+    closed: boolean;
+}>;
 /** Most outline points one flattened path may produce. */
 declare const MAX_PATH_POINTS = 4096;
 interface FlattenedPath {
@@ -2876,5 +3181,5 @@ declare function pathFrame(s: PolygonSprite, r: number, w: number, h: 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 };
+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, MAX_SCENE_PERIOD, MOTION_FIELDS, 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, STEER_EASES, 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, drawSpan, easeGlide, easeSmooth, emitEnvelope, emitWindow, entityScales, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, flattenPath, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, isCombiningKana, isFullWidth, isPathPolygon, latticeHash, layerCellFootprints, layerCohesion, lerpPathD, lerpSpec, lerpValue, lifeAlphaAt, lifeStaggerAt, linkEdges, linkMaxDistPx, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, pathFrame, pathParts, perceiveScene, perceiveSequenceFrame, periodWithoutTimeline, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, sceneColour, scenePeriod, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, strokeDrawnSamples, strokeLines, structuralSignature, textBlockAnchorOffset, textBlockText, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineFlashReport, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, trimLines, trimPolyline, validateSequence, validateSpec, validateSpecPaths, wipeMask, withoutTimeline };
+export type { BackgroundDrift, BackgroundSpec, BandSpec, CapabilityTier, CohesionRead, CycleSpec, DominanceEntry, Entity, FieldBackground, FieldDrift, FinishPass, FinishSpec, FlattenedPath, GlideEase, 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, ScenePeriod, SceneSnapshot, SchemaExample, ScreenOp, SequenceExample, SequenceFramePerception, SequenceMountContext, SequenceSaverInstance, SequenceSaverPlugin, SequenceSegment, SequenceTransition, SpecError, SpecMountContext, SpecWarning, SpriteSpec, SteerDelta, StrokeDraw, TextBlockAnchor, TextBlockLine, TextMetricsClass, TextNumber, TextRevealInput, TextRevealSpec, TextRole, TextSpriteInfo, Timeline, TimelineFlashReport, TimelineKey, ValidationResult, WanderOsc, WarningBox, WipeTransition };