@idle-screens/schema 3.1.1 → 3.3.0

package/FORMAT.md

@@ -7,7 +7,8 @@ deterministic, flash-safe `SaverPlugin`. There is no code in a spec: no
 scripting, no network access, no DOM access.
 
 - **Machine-readable schema:** [`saver-spec.schema.json`](./saver-spec.schema.json)
-  (JSON Schema draft-07), importable as
+  (JSON Schema draft-07), covering SaverSpec scenes and `idle-sequence`
+  envelopes (`oneOf`, discriminated by `format: "idle-sequence"`). Importable as
   `@idle-screens/schema/saver-spec.schema.json`.
 - **Runtime validator:** `validateSpec(spec)` / `assertValidSpec(spec)` — used by
   `compileSaver()`, which refuses to run an invalid spec.
@@ -29,7 +30,8 @@ Additions to version 1 so far, all optional and backward compatible:
 `ghosting`, `wander` / `warp` / `path` motions, `ring` / `streak` / `rect`
 sprites, `colorWeights`, `pulse.wave`, `layout` (grid), `life`,
 `links.mode/falloff/closed`, `blend: screen|multiply`, orbit layer-parents
-(2026-07-21 — "the v1 ceiling").
+(2026-07-21 — "the v1 ceiling");
+`textBlock` sprite — deterministic multi-line text with viewport-unit sizing.
 
 ## Safety invariants
 
@@ -154,6 +156,18 @@ with distance, removing pop-in at the cutoff.
   (rain that reads as rain, shooting stars, warp stars)
 - `{ "kind": "rect", "width": [0.012, 0.02], "aspect": [1.3, 1.7], "color": "#ffb347" }` —
   rectangle; `aspect` is the height/width ratio range (rotates with `spin`)
+- `{ "kind": "textBlock", "text": "Multi-line text with wrapping.", "maxWidth": 0.8, "fontSize": 0.04, "lineHeight": 1.4, "align": "left", "color": "#e6e8ef" }` —
+  multi-line text block with deterministic line-breaking. All dimensions are
+  viewport fractions (of `min(w,h)`), not px — `units: "px"` specs reject
+  textBlock sprites at validation time. `position` is always the block's
+  **top-left corner** regardless of `align` (align moves text within the box,
+  not the box itself — different from the `text` sprite where `align`/`baseline`
+  shift the meaning of `position`). Line breaks are computed from a fixed
+  character-class metrics table so wrapping is identical across platforms; note
+  that the table is approximate — a painted line may slightly exceed `maxWidth`
+  when the real font is wider than the table estimates, so `maxWidth` is a
+  layout target, not a hard clip.
+  Use with `count: 1`, `motion: { type: "static" }`, and `position`.
 
 `circle`, `ring`, `streak`, and `rect` all accept `colors: [...]` (seeded
 per-entity palette pick) and `colorWeights: [...]` (relative weights, same
@@ -271,6 +285,61 @@ is estimated from font size × string length. Good enough to perceive
 composition, focus, balance, and motion — not a substitute for a human (or VLM)
 judgement of beauty.
 
+## Sequence envelope (`idle-sequence`)
+
+A second top-level format that composes multiple SaverSpecs into a sequenced
+timeline. Discriminated from SaverSpec by `format: 'idle-sequence'`.
+
+```jsonc
+{
+  "format": "idle-sequence",
+  "schemaVersion": 1,
+  "id": "my-sequence",
+  "label": "My Sequence",
+  "seed": 42,           // optional; forwarded to children without their own seed
+  "loop": false,
+  "segments": [
+    { "key": "intro",  "scene": { /* SaverSpec */ }, "duration": 5000 },
+    { "key": "main",   "scene": { /* SaverSpec */ }, "duration": 10000, "advance": "auto" },
+    { "key": "outro",  "scene": { /* SaverSpec */ } }  // durationless: holds forever
+  ]
+}
+```
+
+**Segments:** 1–24 segments, each carrying an unmodified SaverSpec. Keys must
+be unique. Duration is in milliseconds (minimum 1000 ms for flash safety). Only
+the final segment may omit duration (holds indefinitely).
+
+**Advance mode:** `auto` (default), `input`, or `either`. Validated but not
+wired to runtime behavior — timer/input drivers are planned for a follow-up.
+
+**Transitions:** `{ type: 'cut' }` (default) performs a hard switch.
+`{ type: 'morph', dur: number }` smoothly interpolates paint properties
+(colors, opacity values) over `dur` ms when crossing into the next segment.
+Morph requires structurally identical adjacent segments (same
+`structuralSignature`); if they differ, the engine falls back to cut and the
+validator emits a `morph-structural-mismatch` warning. During a morph, entity
+placement inherits the outgoing segment's seed — the incoming segment's own
+seed is unused. `dur` must be between 200 and 5000 ms.
+
+**Time mapping:** global clock `T` maps to `(segmentIndex, localT)` via prefix
+sums of durations. Half-open segments: `[start, start+duration)`. With
+`loop: true`, `T` wraps at the sum of all durations (loop is incompatible with
+a durationless final segment).
+
+**Compilation:** `compileSequence()` returns an ordinary `SaverPlugin` — the
+viewer needs zero changes. All children share a single canvas; only the active
+segment's `SpecInstance` is alive at any time. `workerReady` is `false` (the
+worker compile-hook does not dispatch sequences).
+
+**Steering:** segment switching uses the `sequence.segment` delta path via
+`applyTrack`. The `SequenceInstance` intercepts this path before delegation.
+Remaining deltas are forwarded to the active child's `applyTrack`.
+
+**Seed:** `seq.seed` is forwarded to children that lack a scene-level seed
+(offset by segment index for independence). Children with their own seed are
+unaffected.
+
 ## Examples
 
 Shipped working specs (also exposed as `EXAMPLE_SPECS` /

package/dist/index.d.ts

@@ -257,6 +257,23 @@ type SpriteSpec = {
     color: string;
     colors?: string[];
     colorWeights?: number[];
+}
+/**
+ * Multi-line text block with deterministic line-breaking. Unlike `text` (one
+ * string drawn as a single fillText call), `textBlock` wraps `text` within
+ * `maxWidth` using a fixed metrics table so line breaks are identical across
+ * platforms (same seed → same frames). All dimensions are viewport-fraction
+ * (of `min(w,h)`), not px — addresses the absolute-font-size inconsistency.
+ * Use with `count: 1`, `motion: { type: 'static' }`, and `position`.
+ */
+ | {
+    kind: 'textBlock';
+    text: string;
+    maxWidth: number;
+    fontSize: number;
+    lineHeight?: number;
+    align?: 'left' | 'center' | 'right';
+    color?: string;
 };
 /** Rotate through sprite variants over time. Each entity offsets by its seeded phase. */
 interface CycleSpec {
@@ -405,7 +422,39 @@ declare const LIMITS: {
     readonly maxPathPoints: 24;
     readonly minPathDuration: 2000;
     readonly maxGridColumns: 100;
+    readonly maxTextBlockLength: 2000;
+    readonly minTextBlockFontSize: 0.01;
+    readonly maxTextBlockFontSize: 0.2;
+    readonly maxTextBlockMaxWidth: 1;
+    readonly maxSegments: 24;
+    readonly minSegmentDuration: 1000;
+    readonly maxTransitionDur: 5000;
+    readonly minTransitionDur: 200;
+};
+type SequenceTransition = {
+    type: 'cut';
+} | {
+    type: 'morph';
+    dur: number;
 };
+interface SequenceSegment {
+    key: string;
+    scene: SaverSpec;
+    /** Segment duration in ms. Only the final segment may omit this (holds until input). */
+    duration?: number;
+    /** How the segment advances: 'auto' (timer), 'input' (external event), 'either'. */
+    advance?: 'auto' | 'input' | 'either';
+    transition?: SequenceTransition;
+}
+interface IdleSequence {
+    format: 'idle-sequence';
+    schemaVersion: 1;
+    id: string;
+    label: string;
+    seed?: number;
+    loop: boolean;
+    segments: SequenceSegment[];
+}
 
 /**
  * Validate an untrusted (agent- or JSON-authored) spec structurally + semantically.
@@ -417,6 +466,13 @@ declare const LIMITS: {
 declare function validateSpec(spec: unknown): ValidationResult;
 /** Narrowing helper: validate + cast. Throws with a joined message when invalid. */
 declare function assertValidSpec(spec: unknown): SaverSpec;
+/**
+ * Validate a sequence envelope. Each segment's `scene` goes through `validateSpec`;
+ * sequence-level rules (segment count, duration floors, key uniqueness, transition
+ * bounds) are checked here.
+ */
+declare function validateSequence(seq: unknown): ValidationResult;
+declare function assertValidSequence(seq: unknown): IdleSequence;
 
 /** Near plane for warp motion. z lives in [WARP_NEAR, 1]; screen scale is 1/z. */
 declare const WARP_NEAR = 0.08;
@@ -551,6 +607,16 @@ declare function linkPairs(positions: Array<{
     x: number;
     y: number;
 }>, k: number, maxDist: number, doWrap: boolean, w: number, h: number): Array<[number, number]>;
+interface TextBlockLine {
+    text: string;
+    widthEm: number;
+}
+/**
+ * Break `text` into lines that fit within `maxWidthEm` em-widths. Splits on
+ * whitespace; a single word wider than the limit gets its own line unbroken.
+ * Explicit `\n` always forces a break. Pure, deterministic, no canvas needed.
+ */
+declare function breakTextBlock(text: string, maxWidthEm: number): TextBlockLine[];
 
 /** Derive a manifest so a compiled spec composes with @idle-screens/capabilities. */
 declare function manifestFor(spec: SaverSpec): SaverManifest;
@@ -560,6 +626,7 @@ declare function manifestFor(spec: SaverSpec): SaverManifest;
  * deterministic, `renderFrame(t,seed)`-addressable, and flash-safe by construction.
  */
 declare function compileSaver(spec: unknown): SaverPlugin;
+declare function compileSequence(spec: unknown): SaverPlugin;
 
 /**
  * Pure helpers for LIVE steering of compiled specs (setParam / applyTrack).
@@ -617,6 +684,14 @@ declare function adviseSpec(spec: SaverSpec, viewport?: {
     width: number;
     height: number;
 }): SpecWarning[];
+/**
+ * Non-blocking advisory warnings for a validated sequence envelope.
+ * Checks cross-segment luminance jumps at boundaries and per-segment advisories.
+ */
+declare function adviseSequence(seq: IdleSequence, viewport?: {
+    width: number;
+    height: number;
+}): SpecWarning[];
 
 interface LayerSnapshot {
     key: string | undefined;
@@ -851,6 +926,24 @@ interface ScenePerception {
  */
 declare function perceiveScene(spec: SaverSpec, opts?: LuminanceGridOptions): ScenePerception;
 
+interface ResolvedSegment {
+    index: number;
+    localT: number;
+    /** Cumulative start time of this segment in the global timeline. */
+    startT: number;
+}
+/**
+ * Map global time T to (segmentIndex, localT) via prefix sums of durations.
+ * Segments are half-open: [start, start+duration). The final segment may omit
+ * duration, in which case it holds indefinitely (T past the last timed segment
+ * always resolves to the final one).
+ *
+ * With `loop: true`, T wraps modulo the total duration of all segments. If the
+ * final segment has no duration, looping is over the timed prefix only — the
+ * durationless tail is unreachable in loop mode (validated elsewhere).
+ */
+declare function resolveSegment(seq: IdleSequence, T: number): ResolvedSegment;
+
 /**
  * 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
@@ -919,6 +1012,9 @@ declare const SAKURA_SPEC: SaverSpec;
  */
 declare const DASHBOARD_SPEC: SaverSpec;
 
+/** Haiku: a centered text block with a slowly drifting haiku over deep indigo. */
+declare const HAIKU_SPEC: SaverSpec;
+
 /**
  * Orrery: a mechanical solar system. Exercises orbit motion (concentric rings
  * at different speeds), spin (planets rotate on their axes), and grow (the sun
@@ -990,4 +1086,4 @@ 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, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSpec, buildEntities, compileSaver, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, type ResolvedSegment, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, validateSequence, validateSpec };