@idle-screens/schema 3.2.0 → 3.4.0

package/FORMAT.md

@@ -31,7 +31,8 @@ Additions to version 1 so far, all optional and backward compatible:
 sprites, `colorWeights`, `pulse.wave`, `layout` (grid), `life`,
 `links.mode/falloff/closed`, `blend: screen|multiply`, orbit layer-parents
 (2026-07-21 — "the v1 ceiling");
-`textBlock` sprite — deterministic multi-line text with viewport-unit sizing.
+`textBlock` sprite — deterministic multi-line text with viewport-unit sizing;
+`textBlock.reveal` — animated typing/deleting via one steerable paint param.
 
 ## Safety invariants
 
@@ -169,6 +170,25 @@ with distance, removing pop-in at the cutoff.
   layout target, not a hard clip.
   Use with `count: 1`, `motion: { type: "static" }`, and `position`.
 
+  textBlock also accepts `reveal` — animated typing/deleting:
+  `{ "reveal": { "progress": 1, "mode": "typewriter", "speed": 0, "caret": true } }`.
+  Layout always runs on the **full** text; reveal only masks which glyphs are
+  painted, so lines never reflow and the block never resizes while typing.
+  `progress` (0–1, default 1) is the frontier — it is a numeric **paint**
+  param, so steering it with `dur`/`ease` animates typing in a single
+  `setParam` call, and gliding it back toward 0 deletes. `mode` quantizes the
+  frontier per grapheme (`typewriter`, default), per `word`, or per `line`.
+  `speed` (graphemes/sec, max 120) makes the block type itself from scene
+  start: effective progress is `min(progress, speed·t/total)`, so a steered
+  `progress` can still hold or delete a self-typing block. `caret` draws a
+  blinking caret at the frontier (`true`, or `{ "blink": 1.2, "color": "#fff" }`;
+  blink is in full cycles/sec, capped at 3 for flash safety, and is a square
+  wave of `t` like every other animation). With `align: "center"`/`"right"`
+  the revealing line stays anchored to its alignment as it types — only
+  left-aligned text reads as a classic typewriter. To "edit" text live:
+  glide `reveal.progress` to 0, swap `text` while nothing is visible, glide
+  back to 1.
+
 `circle`, `ring`, `streak`, and `rect` all accept `colors: [...]` (seeded
 per-entity palette pick) and `colorWeights: [...]` (relative weights, same
 length — "mostly cool tones, occasional ember").
@@ -313,8 +333,14 @@ 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' }` is the only supported transition. `fade` is
-defined as a type but rejected at validation.
+**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

package/dist/index.d.ts

@@ -274,7 +274,42 @@ type SpriteSpec = {
     lineHeight?: number;
     align?: 'left' | 'center' | 'right';
     color?: string;
+    reveal?: TextRevealSpec;
 };
+/**
+ * Animated typing/deleting for `textBlock`. Layout always runs on the FULL
+ * text — reveal only masks which glyphs are painted, so lines never reflow
+ * and the block's box never changes size. `progress` is a numeric paint
+ * param (excluded from the structural signature), so steering it with
+ * `dur`/`ease` animates typing client-side in one call; gliding it back to 0
+ * deletes. With center/right `align`, the revealing line stays anchored to
+ * its alignment as it types (only left-aligned text reads as a classic
+ * typewriter).
+ */
+interface TextRevealSpec {
+    /**
+     * 0..1 fraction of the text revealed (default 1 = fully shown). Quantized
+     * by `mode`. Steerable paint — glide it to animate typing or deleting.
+     */
+    progress?: number;
+    /** Reveal granularity: per-grapheme (default), per-word, or per-line. */
+    mode?: 'typewriter' | 'word' | 'line';
+    /**
+     * Self-typing rate in graphemes/second from scene start (media time). The
+     * effective progress is `min(progress, speed·t/total)` — so a steered
+     * `progress` can hold or delete even while `speed` is set. 0 = off.
+     */
+    speed?: number;
+    /**
+     * Caret at the reveal frontier. `true` for defaults, or configure blink
+     * rate (Hz, full cycles/sec, capped at 3 for flash safety) and color.
+     * Blink is a square wave of `t` — deterministic like everything else.
+     */
+    caret?: boolean | {
+        blink?: number;
+        color?: string;
+    };
+}
 /** Rotate through sprite variants over time. Each entity offsets by its seeded phase. */
 interface CycleSpec {
     period: number;
@@ -426,14 +461,19 @@ declare const LIMITS: {
     readonly minTextBlockFontSize: 0.01;
     readonly maxTextBlockFontSize: 0.2;
     readonly maxTextBlockMaxWidth: 1;
+    readonly maxRevealSpeed: 120;
+    readonly maxCaretBlinkHz: 3;
     readonly maxSegments: 24;
     readonly minSegmentDuration: 1000;
     readonly maxTransitionDur: 5000;
     readonly minTransitionDur: 200;
 };
-interface SequenceTransition {
+type SequenceTransition = {
     type: 'cut';
-}
+} | {
+    type: 'morph';
+    dur: number;
+};
 interface SequenceSegment {
     key: string;
     scene: SaverSpec;
@@ -614,6 +654,36 @@ interface TextBlockLine {
  * Explicit `\n` always forces a break. Pure, deterministic, no canvas needed.
  */
 declare function breakTextBlock(text: string, maxWidthEm: number): TextBlockLine[];
+/**
+ * Split a string into paint-safe grapheme clusters: surrogate pairs stay
+ * whole, combining marks / variation selectors / skin tones attach to their
+ * base, ZWJ joins sequences (emoji families), regional indicators pair up
+ * (flags). Deterministic across engines by construction.
+ */
+declare function graphemeClusters(text: string): string[];
+interface TextRevealInput {
+    progress?: number;
+    mode?: 'typewriter' | 'word' | 'line';
+    speed?: number;
+}
+interface RevealState {
+    /** Effective 0..1 progress after combining authored progress and speed at t. */
+    progress: number;
+    /** Number of fully visible lines. */
+    fullLines: number;
+    /** Grapheme-safe visible prefix of the next line ('' when none). */
+    partialText: string;
+    /** Caret anchor: line index and the visible prefix on that line. */
+    caretLine: number;
+    caretPrefix: string;
+}
+/**
+ * Resolve which glyphs of a broken textBlock are visible at time `tMs`.
+ * Pure function of (lines, reveal, tMs) — the renderer paints exactly this,
+ * and perceive models exactly this, so agents and pixels agree. `speed` is
+ * graphemes/sec regardless of mode; mode only quantizes the frontier.
+ */
+declare function revealState(lines: TextBlockLine[], reveal: TextRevealInput, tMs: number): RevealState;
 
 /** Derive a manifest so a compiled spec composes with @idle-screens/capabilities. */
 declare function manifestFor(spec: SaverSpec): SaverManifest;
@@ -681,6 +751,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;
@@ -795,6 +873,8 @@ interface TextSpriteInfo {
     count: number;
     /** Representative rendered glyph height in px at the sample viewport. */
     sizePx: number;
+    /** For a revealing textBlock: effective 0..1 fraction shown at sample t. */
+    revealed?: number;
 }
 /**
  * List every text layer's actual strings and rendered size. No grid resolution
@@ -1075,4 +1155,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, 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, 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 };
+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, type RevealState, 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 TextRevealInput, type TextRevealSpec, 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, graphemeClusters, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rotationAt, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, validateSequence, validateSpec };