@idle-screens/schema 3.13.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,
@@ -1444,6 +1638,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
@@ -1506,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.
@@ -1616,12 +1830,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;
@@ -1723,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
@@ -2027,6 +2263,28 @@ 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.
+     * `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;
+
 /**
  * The `field` background sampler — seeded, dependency-free value noise that
  * is a PURE function of `(u, v, t, config, seed)`.
@@ -2326,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
@@ -2352,8 +2610,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
@@ -2378,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
@@ -2768,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 {
@@ -2838,4 +3181,5 @@ declare function pathFrame(s: PolygonSprite, r: number, w: number, h: 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 };
+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 };