@idle-screens/schema 3.3.0 → 3.4.1

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").

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,6 +461,8 @@ 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;
@@ -617,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;
@@ -806,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
@@ -1086,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, 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 };
+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 };

package/dist/index.js

@@ -47,6 +47,10 @@ var LIMITS = {
   minTextBlockFontSize: 0.01,
   maxTextBlockFontSize: 0.2,
   maxTextBlockMaxWidth: 1,
+  maxRevealSpeed: 120,
+  // graphemes/sec — faster than any readable typing
+  maxCaretBlinkHz: 3,
+  // full blink cycles/sec — WCAG 2.3.1 flash-safety cap
   maxSegments: 24,
   minSegmentDuration: 1e3,
   // ms — flash-safety floor: segment cuts are luminance transitions
@@ -216,7 +220,9 @@ var KNOWN_STREAK = /* @__PURE__ */ new Set(["kind", "length", "color", "width",
 var KNOWN_RECT = /* @__PURE__ */ new Set(["kind", "width", "aspect", "color", "colors", "colorWeights"]);
 var KNOWN_EMOJI = /* @__PURE__ */ new Set(["kind", "glyphs", "cycle"]);
 var KNOWN_TEXT = /* @__PURE__ */ new Set(["kind", "strings", "color", "font", "align", "baseline", "maxWidth", "cycle"]);
-var KNOWN_TEXT_BLOCK = /* @__PURE__ */ new Set(["kind", "text", "maxWidth", "fontSize", "lineHeight", "align", "color"]);
+var KNOWN_TEXT_BLOCK = /* @__PURE__ */ new Set(["kind", "text", "maxWidth", "fontSize", "lineHeight", "align", "color", "reveal"]);
+var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret"]);
+var KNOWN_REVEAL_CARET = /* @__PURE__ */ new Set(["blink", "color"]);
 var KNOWN_DRIFT = /* @__PURE__ */ new Set(["type", "speed", "angle", "bidirectional", "bob"]);
 var KNOWN_RISE = /* @__PURE__ */ new Set(["type", "speed", "sway"]);
 var KNOWN_BOUNCE = /* @__PURE__ */ new Set(["type", "speed"]);
@@ -574,6 +580,39 @@ function validateSprite(sprite, path, err, warn) {
       err(`${path}.align`, "must be 'left' | 'center' | 'right'");
     }
     if (sprite.color !== void 0) color(sprite.color, `${path}.color`, err);
+    if (sprite.reveal !== void 0) {
+      const rv = sprite.reveal;
+      if (typeof rv !== "object" || rv === null || Array.isArray(rv)) {
+        err(`${path}.reveal`, "must be an object");
+      } else {
+        for (const k of Object.keys(rv)) {
+          if (!KNOWN_REVEAL.has(k)) err(`${path}.reveal.${k}`, "unknown reveal field");
+        }
+        if (rv.progress !== void 0 && (!isNum(rv.progress) || rv.progress < 0 || rv.progress > 1)) {
+          err(`${path}.reveal.progress`, "must be a number between 0 and 1");
+        }
+        if (rv.mode !== void 0 && !["typewriter", "word", "line"].includes(rv.mode)) {
+          err(`${path}.reveal.mode`, "must be 'typewriter' | 'word' | 'line'");
+        }
+        if (rv.speed !== void 0 && (!isNum(rv.speed) || rv.speed < 0 || rv.speed > LIMITS.maxRevealSpeed)) {
+          err(`${path}.reveal.speed`, `must be between 0 and ${LIMITS.maxRevealSpeed} (graphemes/sec)`);
+        }
+        if (rv.caret !== void 0 && typeof rv.caret !== "boolean") {
+          const caret = rv.caret;
+          if (typeof caret !== "object" || caret === null || Array.isArray(caret)) {
+            err(`${path}.reveal.caret`, "must be a boolean or an object");
+          } else {
+            for (const k of Object.keys(caret)) {
+              if (!KNOWN_REVEAL_CARET.has(k)) err(`${path}.reveal.caret.${k}`, "unknown caret field");
+            }
+            if (caret.blink !== void 0 && (!isNum(caret.blink) || caret.blink <= 0 || caret.blink > LIMITS.maxCaretBlinkHz)) {
+              err(`${path}.reveal.caret.blink`, `must be between 0 (exclusive) and ${LIMITS.maxCaretBlinkHz} Hz (flash safety)`);
+            }
+            if (caret.color !== void 0) color(caret.color, `${path}.reveal.caret.color`, err);
+          }
+        }
+      }
+    }
   } else {
     err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect | textBlock");
     return;
@@ -1357,6 +1396,93 @@ function breakTextBlock(text, maxWidthEm) {
   }
   return lines;
 }
+function isClusterExtend(cp) {
+  return cp >= 768 && cp <= 879 || // combining diacritics
+  cp >= 6832 && cp <= 6911 || cp >= 8400 && cp <= 8447 || cp >= 65024 && cp <= 65039 || // variation selectors
+  cp >= 127995 && cp <= 127999 || // skin tones
+  cp === 8419;
+}
+function isRegionalIndicator(cp) {
+  return cp >= 127462 && cp <= 127487;
+}
+var ZWJ = 8205;
+function graphemeClusters(text) {
+  const out = [];
+  let i = 0;
+  while (i < text.length) {
+    const cp = text.codePointAt(i);
+    let end = i + (cp > 65535 ? 2 : 1);
+    if (isRegionalIndicator(cp) && end < text.length) {
+      const next = text.codePointAt(end);
+      if (isRegionalIndicator(next)) end += next > 65535 ? 2 : 1;
+    }
+    while (end < text.length) {
+      const next = text.codePointAt(end);
+      if (isClusterExtend(next)) {
+        end += next > 65535 ? 2 : 1;
+      } else if (next === ZWJ && end + 1 < text.length) {
+        const after = text.codePointAt(end + 1);
+        end += 1 + (after > 65535 ? 2 : 1);
+      } else {
+        break;
+      }
+    }
+    out.push(text.slice(i, end));
+    i = end;
+  }
+  return out;
+}
+function revealState(lines, reveal, tMs) {
+  const lineClusters = lines.map((l) => graphemeClusters(l.text));
+  const totalGraphemes = lineClusters.reduce((n, c) => n + c.length, 0);
+  const authored = Math.max(0, Math.min(1, reveal.progress ?? 1));
+  const speed = reveal.speed ?? 0;
+  const timed = speed > 0 && totalGraphemes > 0 ? Math.min(1, speed * tMs / 1e3 / totalGraphemes) : 1;
+  const progress = Math.min(authored, timed);
+  const mode = reveal.mode ?? "typewriter";
+  let fullLines = 0;
+  let partialText = "";
+  if (mode === "line") {
+    fullLines = Math.round(progress * lines.length);
+  } else if (mode === "word") {
+    const lineWords = lines.map((l) => l.text.length === 0 ? [] : l.text.split(" "));
+    const totalWords = lineWords.reduce((n, ws) => n + ws.length, 0);
+    let remaining = Math.round(progress * totalWords);
+    for (const ws of lineWords) {
+      if (remaining >= ws.length) {
+        remaining -= ws.length;
+        fullLines++;
+        continue;
+      }
+      if (remaining > 0) partialText = ws.slice(0, remaining).join(" ");
+      break;
+    }
+  } else {
+    let remaining = Math.round(progress * totalGraphemes);
+    for (const clusters of lineClusters) {
+      if (remaining >= clusters.length) {
+        remaining -= clusters.length;
+        fullLines++;
+        continue;
+      }
+      if (remaining > 0) partialText = clusters.slice(0, remaining).join("");
+      break;
+    }
+  }
+  let caretLine;
+  let caretPrefix;
+  if (partialText.length > 0) {
+    caretLine = fullLines;
+    caretPrefix = partialText;
+  } else if (fullLines > 0) {
+    caretLine = fullLines - 1;
+    caretPrefix = lines[fullLines - 1].text;
+  } else {
+    caretLine = 0;
+    caretPrefix = "";
+  }
+  return { progress, fullLines, partialText, caretLine, caretPrefix };
+}
 
 // src/compile.ts
 import {
@@ -1696,6 +1822,9 @@ var SpecInstance = class {
       const maxWEm = maxWPx / fsPx;
       const lines = breakTextBlock(sprite.text, maxWEm);
       const align = sprite.align ?? "left";
+      const reveal = sprite.reveal;
+      const rs = reveal ? revealState(lines, reveal, t) : null;
+      const fullLines = rs ? rs.fullLines : lines.length;
       ctx.save();
       ctx.translate(p.x, p.y);
       if (rot) ctx.rotate(rot);
@@ -1704,9 +1833,23 @@ var SpecInstance = class {
       ctx.textBaseline = "top";
       ctx.textAlign = align;
       const xOff = align === "center" ? maxWPx / 2 : align === "right" ? maxWPx : 0;
-      for (let li = 0; li < lines.length; li++) {
+      for (let li = 0; li < fullLines; li++) {
         ctx.fillText(lines[li].text, xOff, li * lh);
       }
+      if (rs && rs.partialText.length > 0) {
+        ctx.fillText(rs.partialText, xOff, fullLines * lh);
+      }
+      if (rs && reveal.caret) {
+        const cfg = reveal.caret === true ? {} : reveal.caret;
+        const hz = Math.min(3, cfg.blink ?? 1.2);
+        const on = hz <= 0 || Math.floor(t / 1e3 * hz * 2) % 2 === 0;
+        if (on) {
+          const pw = ctx.measureText(rs.caretPrefix).width;
+          const cx = align === "center" ? xOff + pw / 2 : align === "right" ? xOff : pw;
+          ctx.fillStyle = cfg.color ?? sprite.color ?? "#e6e8ef";
+          ctx.fillRect(cx + fsPx * 0.06, rs.caretLine * lh, Math.max(1, fsPx * 0.08), fsPx);
+        }
+      }
       ctx.restore();
       return;
     }
@@ -1923,6 +2066,11 @@ var SequenceInstance = class {
    * its seed (and entity placement) is continuous.
    */
   morphFromIndex = -1;
+  seed;
+  frameId = null;
+  startT = 0;
+  baseT = 0;
+  lastT = 0;
   constructor(seq, ctx) {
     this.seq = seq;
     let surface = ctx.surface ?? null;
@@ -1935,8 +2083,12 @@ var SequenceInstance = class {
       surface = canvas;
     }
     this.canvas = canvas;
+    this.seed = (seq.seed ?? ctx.seed ?? 0) >>> 0 || 1;
     this.childCtx = { ...ctx, surface, reducedMotion: true };
     this.children = new Array(seq.segments.length).fill(null);
+    this.paused = ctx.reducedMotion;
+    if (this.paused) this.renderFrame(0, this.seed);
+    else this.start();
   }
   childSeed(index, fallback) {
     return this.seq.segments[index].scene.seed ?? this.seq.seed ?? fallback;
@@ -1971,7 +2123,7 @@ var SequenceInstance = class {
     if (!child) {
       child = new SpecInstance(this.childScene(index), this.childCtx);
       this.children[index] = child;
-      if (this.paused) child.setPaused(true);
+      child.setPaused(true);
     }
     return child;
   }
@@ -1982,6 +2134,24 @@ var SequenceInstance = class {
       this.children[index] = null;
     }
   }
+  start() {
+    if (this.frameId !== null || typeof requestAnimationFrame === "undefined") return;
+    this.startT = 0;
+    this.frameId = requestAnimationFrame((now) => this.loop(now));
+  }
+  stop() {
+    if (this.frameId !== null) {
+      cancelAnimationFrame(this.frameId);
+      this.frameId = null;
+    }
+    this.baseT = this.lastT;
+  }
+  loop(now) {
+    this.frameId = requestAnimationFrame((n) => this.loop(n));
+    if (this.startT === 0) this.startT = now;
+    this.lastT = now - this.startT + this.baseT;
+    this.renderFrame(this.lastT, this.seed);
+  }
   renderFrame(T, seed) {
     const resolved = resolveSegment(this.seq, T);
     const { index, localT } = resolved;
@@ -2022,7 +2192,7 @@ var SequenceInstance = class {
         const rootScene = this.childScene(chainRoot);
         child = new SpecInstance(rootScene, this.childCtx);
         this.children[index] = child;
-        if (this.paused) child.setPaused(true);
+        child.setPaused(true);
         child.hotSwapSpec(this.childScene(index));
       } else {
         child = this.ensureChild(index);
@@ -2033,8 +2203,10 @@ var SequenceInstance = class {
   }
   setPaused(paused) {
     this.paused = paused;
+    if (paused) this.stop();
+    else this.start();
     for (const child of this.children) {
-      child?.setPaused(paused);
+      child?.setPaused(true);
     }
   }
   resize(width, height, dpr) {
@@ -2063,6 +2235,7 @@ var SequenceInstance = class {
     }
   }
   dispose() {
+    this.stop();
     for (let i = 0; i < this.children.length; i++) {
       this.releaseChild(i);
     }
@@ -2528,6 +2701,13 @@ function textBlockBox(s, _e, p, w, h) {
     halfY: totalH / 2
   };
 }
+function textBlockRevealFraction(s, w, h, t) {
+  if (!s.reveal) return 1;
+  const unitScale = Math.min(w, h);
+  const maxWEm = s.maxWidth * unitScale / (s.fontSize * unitScale);
+  const lines = breakTextBlock(s.text, maxWEm);
+  return revealState(lines, s.reveal, t).progress;
+}
 function luminanceGrid(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
@@ -2666,7 +2846,7 @@ function luminanceGrid(spec, opts = {}) {
         const c1 = Math.min(cols - 1, Math.floor((centerX + reachX) / cellW));
         const r0 = Math.max(0, Math.floor((centerY - reachY) / cellH));
         const r1 = Math.min(rows - 1, Math.floor((centerY + reachY) / cellH));
-        const inkWeight = s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1;
+        const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) : 1);
         for (let r = r0; r <= r1; r++) {
           for (let c = c0; c <= c1; c++) {
             const dx = (c + 0.5) * cellW - centerX;
@@ -2829,7 +3009,9 @@ function textSprites(spec, opts = {}) {
       const s2 = layer.sprite;
       const unitScale = Math.min(scene.w, scene.h);
       const sizePx2 = s2.fontSize * unitScale;
-      out.push({ layerIndex, key: layer.key, strings: [s2.text], count: entities.length, sizePx: Math.round(sizePx2) });
+      const info = { layerIndex, key: layer.key, strings: [s2.text], count: entities.length, sizePx: Math.round(sizePx2) };
+      if (s2.reveal) info.revealed = Math.round(textBlockRevealFraction(s2, scene.w, scene.h, t) * 100) / 100;
+      out.push(info);
       return;
     }
     if (layer.sprite.kind !== "text") return;
@@ -2884,7 +3066,7 @@ function dominanceRanking(spec, opts = {}) {
         entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
       } else if (s.kind === "textBlock") {
         const box = textBlockBox(s, e, { x: 0, y: 0 }, w, h);
-        entArea = box.halfX * 2 * box.halfY * 2 * 0.55;
+        entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t);
       } else entArea = sz * sz * 0.55;
       area += entArea * a;
       if (layer.trail) {
@@ -4503,6 +4685,7 @@ export {
   diffScenes,
   dominanceRanking,
   easeSmooth,
+  graphemeClusters,
   headingAt,
   lerpSpec,
   lifeAlphaAt,
@@ -4517,6 +4700,7 @@ export {
   renderDensityMap,
   resolveSegment,
   resolveSpecPath,
+  revealState,
   rotationAt,
   sizeAt,
   spriteIndexAt,