@idle-screens/schema 3.4.4 → 3.5.0

package/FORMAT.md

@@ -127,7 +127,7 @@ trails, long-exposure light). 0.85–0.95 is the useful range; 0 (default) is of
 | `pulse` | `{amp ≤ 0.5, period ≥ 500, wave?}` | none | opacity breathing; `wave: {wavelength, angle?}` turns it into a traveling wave across the field |
 | `spin` | number \| `[min,max]` ±360 deg/sec | none | per-entity rotation (seeded start angle); a range gives each entity a seeded speed (confetti, tumbling debris) |
 | `grow` | `{amp ≤ 0.8, period ≥ 500}` | none | size breathing (seeded phase) |
-| `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail (ms of history) |
+| `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail; `length` is **milliseconds** of history (max 5000), `fade` a number 0..1 (not a boolean — `links.falloff` in the next row is the boolean) |
 | `links` | see below | none | inter-entity lines |
 | `layout` | `{type: "grid", columns?, jitter?}` | scatter | grid placement; `jitter` scalar or `{x?, y?}` 0..1 per axis |
 | `life` | `{enter?, exit?, fade?}` ms | always on | act structure: fade the layer in at `enter`, out at `exit` |
@@ -180,7 +180,14 @@ with distance, removing pop-in at the cutoff.
   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
+  `progress` can still hold or delete a self-typing block. A fourth mode,
+  `glyphFade`, fades each glyph in over a staggered alpha ramp instead of
+  popping it whole (the caption look); `fade` (0–1 exclusive of 0, default
+  0.15, `glyphFade` only) is each glyph's fade window as a fraction of
+  progress — small reads as a soft typewriter, large as a wave of
+  overlapping fades. Still a pure function of `progress`, so it glides and
+  deletes exactly like the other modes. Native clients render `glyphFade`
+  as `typewriter` until they gain per-glyph alpha. `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"`
@@ -290,6 +297,14 @@ trade-offs for a zero-dependency, renderer-free analysis tool.
   text layer. Glyphs are invisible in the luminance maps, so this is the only
   way to confirm *what words* are on screen and how big. (Also on
   `perceiveScene().text`.)
+- `adviseSpec(spec)` — non-blocking advisories (also on
+  `perceiveScene().advisories`). Two of them are **spatial**, for static text:
+  `text-off-screen` (a text/textBlock box crosses the viewport edge by more
+  than 1%) and `text-overlap` (two static text layers share more than 10% of
+  the smaller box). Boxes come from the same character-class width table the
+  textBlock line-breaker uses, so they are estimates of the renderer's own
+  layout — a caption that fails these will look wrong on the wall; one that
+  passes may still sit a few px off.
 - `diffScenes(a, b, opts)` — **relative sight**: coverage/luminance deltas,
   visual-balance shift, 3×3 region deltas, dominance-rank movement, and
   advisory codes added/removed. Agents judge "is B better than A" far more
@@ -330,8 +345,12 @@ timeline. Discriminated from SaverSpec by `format: 'idle-sequence'`.
 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.
+**Advance mode:** `auto` (default) and `either` advance on the timer. `input`
+makes a timed segment **hold** at the end of its `duration` until a
+`sequence.segment` steer releases it — the clicker (see Steering below). The
+held scene keeps animating (its `localT` keeps growing), so a slide waiting for
+the presenter never freezes. A durationless final segment holds regardless of
+`advance`.
 
 **Transitions:** `{ type: 'cut' }` (default) performs a hard switch.
 `{ type: 'morph', dur: number }` smoothly interpolates paint properties
@@ -345,7 +364,8 @@ 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).
+a durationless final segment). An unreleased `advance: 'input'` hold blocks the
+wrap; after a wrap every hold is armed again.
 
 **Compilation:** `compileSequence()` returns an ordinary `SaverPlugin` — the
 viewer needs zero changes. All children share a single canvas; only the active
@@ -353,8 +373,20 @@ 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`.
+`applyTrack` (`setParam("sequence.segment", n)` over MCP). The
+`SequenceInstance` intercepts this path before delegation; remaining deltas are
+forwarded to the active child's `applyTrack`.
+
+The steer **moves the clock, not the frame**: it displaces the timeline so the
+target segment starts at its own `localT` 0 (its `life.enter` build replays)
+and then runs on the timer from there — the next animation frame resolves to
+the same segment instead of snapping back to the wall clock. A steer to
+segment `n` also counts as the presenter clicking past every `advance: 'input'`
+hold before `n`; holds at and after `n` stay armed, so steering backwards
+re-arms the ones in between. This is the whole clicker: a deck is a sequence
+whose slides carry `advance: 'input'`, and "next" is one `setParam`. Pinned by
+`sequence.test.ts` → "sequence.segment steering is sticky" and
+"advance: 'input' holds until released".
 
 **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

package/dist/index.d.ts

@@ -292,8 +292,12 @@ interface TextRevealSpec {
      * 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';
+    /**
+     * Reveal granularity: per-grapheme (default), per-word, per-line, or
+     * `glyphFade` — each glyph fades in over a staggered alpha ramp instead of
+     * appearing whole (the caption look). Still a pure function of `progress`.
+     */
+    mode?: 'typewriter' | 'word' | 'line' | 'glyphFade';
     /**
      * Self-typing rate in graphemes/second from scene start (media time). The
      * effective progress is `min(progress, speed·t/total)` — so a steered
@@ -309,6 +313,12 @@ interface TextRevealSpec {
         blink?: number;
         color?: string;
     };
+    /**
+     * `glyphFade` only: each glyph's fade window as a fraction of progress
+     * (0 exclusive to 1, default 0.15). Small = soft typewriter; large = a
+     * wave of overlapping fades. Ignored by the other modes.
+     */
+    fade?: number;
 }
 /** Rotate through sprite variants over time. Each entity offsets by its seeded phase. */
 interface CycleSpec {
@@ -637,6 +647,8 @@ declare function linkPairs(positions: Array<{
     x: number;
     y: number;
 }>, k: number, maxDist: number, doWrap: boolean, w: number, h: number): Array<[number, number]>;
+/** Em-width of a string under the same character-class table `breakTextBlock` uses. */
+declare function textWidthEm(str: string): number;
 interface TextBlockLine {
     text: string;
     widthEm: number;
@@ -656,8 +668,9 @@ declare function breakTextBlock(text: string, maxWidthEm: number): TextBlockLine
 declare function graphemeClusters(text: string): string[];
 interface TextRevealInput {
     progress?: number;
-    mode?: 'typewriter' | 'word' | 'line';
+    mode?: 'typewriter' | 'word' | 'line' | 'glyphFade';
     speed?: number;
+    fade?: number;
 }
 interface RevealState {
     /** Effective 0..1 progress after combining authored progress and speed at t. */
@@ -669,6 +682,12 @@ interface RevealState {
     /** Caret anchor: line index and the visible prefix on that line. */
     caretLine: number;
     caretPrefix: string;
+    /**
+     * `glyphFade` mode only: per-line per-grapheme alpha (0..1), indexed
+     * parallel to `graphemeClusters(lines[i].text)`. Alphas only decrease in
+     * reading order, so a renderer may stop at the first zero.
+     */
+    glyphAlphas?: number[][];
 }
 /**
  * Resolve which glyphs of a broken textBlock are visible at time `tMs`.
@@ -993,18 +1012,44 @@ interface ResolvedSegment {
     localT: number;
     /** Cumulative start time of this segment in the global timeline. */
     startT: number;
+    /**
+     * Present (true) when the timeline has run past this segment's duration but
+     * the segment has `advance: 'input'` and no input has released it yet — the
+     * scene keeps animating (`localT` keeps growing) while the show waits for
+     * the presenter.
+     */
+    held?: true;
 }
+interface ResolveOptions {
+    /**
+     * Segments below this index have been released by input: a `sequence.segment`
+     * steer to index `n` counts as the presenter clicking past every hold before
+     * `n`. `SequenceInstance` maintains this; callers resolving a bare timeline
+     * leave it at 0, so every `advance: 'input'` hold is honoured.
+     */
+    releasedBelow?: number;
+}
+/** Global start time of segment `index` — the prefix sum of the durations before it. */
+declare function segmentStart(seq: IdleSequence, index: number): 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).
+ * `advance: 'input'` makes a timed segment hold at its end instead of yielding
+ * to the next one — the clicker. `auto` (default) and `either` advance on the
+ * timer. A hold is released by a `sequence.segment` steer (see
+ * `ResolveOptions.releasedBelow`); the held scene keeps its clock running, so
+ * `localT` grows past `duration` rather than freezing.
+ *
+ * With `loop: true`, T wraps modulo the total duration of all segments — but
+ * only once every hold on the current lap has been released; after a wrap
+ * every hold is armed again. 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;
+declare function resolveSegment(seq: IdleSequence, T: number, opts?: ResolveOptions): ResolvedSegment;
 
 /**
  * Reproduces the hand-coded Fish Aquarium saver as pure DATA — the discriminating test
@@ -1148,4 +1193,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, 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 };
+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 ResolveOptions, 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, segmentStart, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, textWidthEm, validateSequence, validateSpec };

package/dist/index.js

@@ -221,7 +221,7 @@ var KNOWN_RECT = /* @__PURE__ */ new Set(["kind", "width", "aspect", "color", "c
 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", "reveal"]);
-var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret"]);
+var KNOWN_REVEAL = /* @__PURE__ */ new Set(["progress", "mode", "speed", "caret", "fade"]);
 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"]);
@@ -604,8 +604,11 @@ function validateSprite(sprite, path, err, warn) {
         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.mode !== void 0 && !["typewriter", "word", "line", "glyphFade"].includes(rv.mode)) {
+          err(`${path}.reveal.mode`, "must be 'typewriter' | 'word' | 'line' | 'glyphFade'");
+        }
+        if (rv.fade !== void 0 && (!isNum(rv.fade) || rv.fade <= 0 || rv.fade > 1)) {
+          err(`${path}.reveal.fade`, "must be between 0 (exclusive) and 1 (fraction of progress)");
         }
         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)`);
@@ -1462,6 +1465,17 @@ function revealState(lines, reveal, tMs) {
   const mode = reveal.mode ?? "typewriter";
   let fullLines = 0;
   let partialText = "";
+  let glyphAlphas;
+  if (mode === "glyphFade") {
+    const f = Math.min(1, Math.max(0.01, reveal.fade ?? 0.15));
+    let g = 0;
+    glyphAlphas = lineClusters.map(
+      (clusters) => clusters.map(() => {
+        const start = totalGraphemes > 0 ? g++ / totalGraphemes * (1 - f) : 0;
+        return Math.max(0, Math.min(1, (progress - start) / f));
+      })
+    );
+  }
   if (mode === "line") {
     fullLines = Math.round(progress * lines.length);
   } else if (mode === "word") {
@@ -1501,7 +1515,7 @@ function revealState(lines, reveal, tMs) {
     caretLine = 0;
     caretPrefix = "";
   }
-  return { progress, fullLines, partialText, caretLine, caretPrefix };
+  return { progress, fullLines, partialText, caretLine, caretPrefix, glyphAlphas };
 }
 
 // src/compile.ts
@@ -1510,7 +1524,13 @@ import {
 } from "@idle-screens/core";
 
 // src/sequence.ts
-function resolveSegment(seq, T) {
+function segmentStart(seq, index) {
+  let t = 0;
+  const n = Math.max(0, Math.min(index, seq.segments.length - 1));
+  for (let i = 0; i < n; i++) t += seq.segments[i].duration ?? 0;
+  return t;
+}
+function resolveSegment(seq, T, opts = {}) {
   const { segments, loop } = seq;
   if (segments.length === 0) return { index: 0, localT: 0, startT: 0 };
   let totalTimed = 0;
@@ -1518,24 +1538,33 @@ function resolveSegment(seq, T) {
     if (seg.duration != null) totalTimed += seg.duration;
     else break;
   }
-  let t = Math.max(0, T);
-  if (loop && totalTimed > 0) {
-    t = t % totalTimed;
-  }
-  let cumulative = 0;
-  for (let i = 0; i < segments.length; i++) {
-    const seg = segments[i];
-    if (seg.duration == null) {
-      return { index: i, localT: t - cumulative, startT: cumulative };
-    }
-    if (t < cumulative + seg.duration) {
-      return { index: i, localT: t - cumulative, startT: cumulative };
+  const t0 = Math.max(0, T);
+  const walk = (t, releasedBelow) => {
+    let cumulative = 0;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      if (seg.duration == null) {
+        return loop ? null : { index: i, localT: t - cumulative, startT: cumulative };
+      }
+      if (t < cumulative + seg.duration) {
+        return { index: i, localT: t - cumulative, startT: cumulative };
+      }
+      if (seg.advance === "input" && i >= releasedBelow) {
+        return { index: i, localT: t - cumulative, startT: cumulative, held: true };
+      }
+      cumulative += seg.duration;
     }
-    cumulative += seg.duration;
+    return null;
+  };
+  const first = walk(t0, opts.releasedBelow ?? 0);
+  if (first) return first;
+  if (loop && totalTimed > 0) {
+    const wrapped = walk(t0 % totalTimed, 0);
+    if (wrapped) return wrapped;
   }
   const last = segments.length - 1;
-  const lastStart = cumulative - (segments[last].duration ?? 0);
-  return { index: last, localT: t - lastStart, startT: lastStart };
+  const lastStart = totalTimed - (segments[last].duration ?? 0);
+  return { index: last, localT: t0 - lastStart, startT: lastStart };
 }
 
 // src/compile.ts
@@ -1853,11 +1882,39 @@ var SpecInstance = class {
       ctx.textBaseline = "top";
       ctx.textAlign = align;
       const xOff = align === "center" ? maxWPx / 2 : align === "right" ? maxWPx : 0;
-      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?.glyphAlphas) {
+        ctx.textAlign = "left";
+        const baseAlpha = ctx.globalAlpha;
+        for (let li = 0; li < lines.length; li++) {
+          const alphas = rs.glyphAlphas[li] ?? [];
+          if (alphas.length > 0 && alphas[0] <= 0) break;
+          const clusters = graphemeClusters(lines[li].text);
+          const lw = ctx.measureText(lines[li].text).width;
+          const x0 = align === "center" ? (maxWPx - lw) / 2 : align === "right" ? maxWPx - lw : 0;
+          let opaque = 0;
+          while (opaque < clusters.length && (alphas[opaque] ?? 0) >= 1) opaque++;
+          let prefix = "";
+          if (opaque > 0) {
+            prefix = clusters.slice(0, opaque).join("");
+            ctx.globalAlpha = baseAlpha;
+            ctx.fillText(prefix, x0, li * lh);
+          }
+          for (let gi = opaque; gi < clusters.length; gi++) {
+            const a = alphas[gi] ?? 0;
+            if (a <= 0) break;
+            ctx.globalAlpha = baseAlpha * a;
+            ctx.fillText(clusters[gi], x0 + ctx.measureText(prefix).width, li * lh);
+            prefix += clusters[gi];
+          }
+        }
+        ctx.globalAlpha = baseAlpha;
+      } else {
+        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;
@@ -2091,6 +2148,18 @@ var SequenceInstance = class {
   startT = 0;
   baseT = 0;
   lastT = 0;
+  /** The T most recently passed to renderFrame — the clock a steer displaces. */
+  renderedT = 0;
+  /**
+   * The clicker's two pieces of state. `clockOffset` is added to every T so
+   * a `sequence.segment` steer lands the timeline at the target segment's
+   * start and STAYS there as the wall clock keeps ticking — the steer moves
+   * the clock instead of fighting it. `releasedBelow` records that the steer
+   * counts as the presenter clicking past every `advance: 'input'` hold
+   * before the target (see `resolveSegment`).
+   */
+  clockOffset = 0;
+  releasedBelow = 0;
   constructor(seq, ctx) {
     this.seq = seq;
     let surface = ctx.surface ?? null;
@@ -2173,7 +2242,8 @@ var SequenceInstance = class {
     this.renderFrame(this.lastT, this.seed);
   }
   renderFrame(T, seed) {
-    const resolved = resolveSegment(this.seq, T);
+    this.renderedT = T;
+    const resolved = resolveSegment(this.seq, T + this.clockOffset, { releasedBelow: this.releasedBelow });
     const { index, localT } = resolved;
     const prevIdx = index > 0 ? index - 1 : -1;
     const morphActive = prevIdx >= 0 && this.canMorph(prevIdx) && localT < this.morphDur(prevIdx);
@@ -2242,14 +2312,9 @@ var SequenceInstance = class {
     const segDelta = deltas.find((d) => d.path === "sequence.segment");
     if (segDelta !== void 0 && typeof segDelta.value === "number") {
       const idx = Math.max(0, Math.min(this.seq.segments.length - 1, Math.round(segDelta.value)));
-      if (idx !== this.activeIndex) {
-        for (let i = 0; i < this.children.length; i++) {
-          if (i !== idx) this.releaseChild(i);
-        }
-        this.activeIndex = idx;
-        const child = this.ensureChild(idx);
-        child.renderFrame(0, this.seq.segments[idx].scene.seed ?? this.seq.seed ?? 0);
-      }
+      this.clockOffset = segmentStart(this.seq, idx) - this.renderedT;
+      this.releasedBelow = idx;
+      this.renderFrame(this.renderedT, this.seed);
     }
     const childDeltas = deltas.filter((d) => d.path !== "sequence.segment");
     if (childDeltas.length > 0 && this.activeIndex >= 0) {
@@ -2529,8 +2594,88 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
       });
     }
   }
+  const textBoxes = [];
+  for (let li = 0; li < spec.layers.length; li++) {
+    const layer = spec.layers[li];
+    const s = layer.sprite;
+    if (layer.motion.type !== "static") continue;
+    if (s.kind !== "text" && s.kind !== "textBlock") continue;
+    const label = layer.key ? `\`${layer.key}\`` : `layers[${li}]`;
+    for (const e of allEntities[li]) {
+      const p = positionAt(e, 0, w, h);
+      const box = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
+      textBoxes.push({ li, label, ...box });
+    }
+  }
+  const tolX = w * 0.01;
+  const tolY = h * 0.01;
+  const offFlagged = /* @__PURE__ */ new Set();
+  for (const b of textBoxes) {
+    if (offFlagged.has(b.li)) continue;
+    const edges = [];
+    if (b.x0 < -tolX) edges.push(`left edge by ~${Math.round(-b.x0)}px`);
+    if (b.x1 > w + tolX) edges.push(`right edge by ~${Math.round(b.x1 - w)}px`);
+    if (b.y0 < -tolY) edges.push(`top edge by ~${Math.round(-b.y0)}px`);
+    if (b.y1 > h + tolY) edges.push(`bottom edge by ~${Math.round(b.y1 - h)}px`);
+    if (edges.length === 0) continue;
+    offFlagged.add(b.li);
+    warnings.push({
+      path: `layers[${b.li}]`,
+      code: "text-off-screen",
+      message: `${b.label} text runs off the ${edges.join(" and the ")} at ${w}\xD7${h} \u2014 move position, or shrink fontSize / maxWidth`
+    });
+  }
+  const pairFlagged = /* @__PURE__ */ new Set();
+  for (let i = 0; i < textBoxes.length; i++) {
+    for (let j = i + 1; j < textBoxes.length; j++) {
+      const a = textBoxes[i];
+      const b = textBoxes[j];
+      if (a.li === b.li) continue;
+      const pair = `${Math.min(a.li, b.li)}:${Math.max(a.li, b.li)}`;
+      if (pairFlagged.has(pair)) continue;
+      const ix = Math.min(a.x1, b.x1) - Math.max(a.x0, b.x0);
+      const iy = Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0);
+      if (ix <= 0 || iy <= 0) continue;
+      const smaller = Math.min((a.x1 - a.x0) * (a.y1 - a.y0), (b.x1 - b.x0) * (b.y1 - b.y0));
+      if (smaller <= 0) continue;
+      const share = ix * iy / smaller;
+      if (share <= 0.1) continue;
+      pairFlagged.add(pair);
+      const [first, second] = a.li < b.li ? [a, b] : [b, a];
+      warnings.push({
+        path: `layers[${first.li}]`,
+        code: "text-overlap",
+        message: `${first.label} and ${second.label} text boxes overlap (~${Math.round(share * 100)}% of the smaller one) \u2014 they will paint over each other; move one or shrink it`
+      });
+    }
+  }
   return warnings;
 }
+function textBoxAt(s, e, p, spec, w, h) {
+  const m = s.font ? /(\d{1,5}(?:\.\d{1,4})?|\.\d{1,4})px/.exec(s.font) : null;
+  const fontScale = spec.units === "px" ? 1 : Math.min(w, h) / (spec.referenceViewport ?? LIMITS.referenceViewport);
+  const fh = m ? Number(m[1]) * fontScale : e.size;
+  const str = s.strings[e.spriteIndex] ?? s.strings[0] ?? "";
+  let fw = textWidthEm(str) * fh;
+  if (s.maxWidth) fw = Math.min(fw, s.maxWidth * (spec.units === "px" ? 1 : Math.min(w, h)));
+  const align = s.align ?? "center";
+  const baseline = s.baseline ?? "middle";
+  const x0 = align === "left" ? p.x : align === "right" ? p.x - fw : p.x - fw / 2;
+  const y0 = baseline === "top" ? p.y : baseline === "bottom" ? p.y - fh : p.y - fh / 2;
+  return { x0, y0, x1: x0 + fw, y1: y0 + fh };
+}
+function textBlockBoxAt(s, p, w, h) {
+  const unit = Math.min(w, h);
+  const fsPx = s.fontSize * unit;
+  const lh = (s.lineHeight ?? 1.4) * fsPx;
+  const maxWPx = s.maxWidth * unit;
+  const lines = breakTextBlock(s.text, maxWPx / fsPx);
+  const maxLineW = lines.reduce((mx, l) => Math.max(mx, l.widthEm), 0) * fsPx;
+  const totalH = lines.length * lh;
+  const align = s.align ?? "left";
+  const x0 = align === "center" ? p.x + (maxWPx - maxLineW) / 2 : align === "right" ? p.x + maxWPx - maxLineW : p.x;
+  return { x0, y0: p.y, x1: x0 + maxLineW, y1: p.y + totalH };
+}
 function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
   const warnings = [];
   for (let i = 0; i < seq.segments.length; i++) {
@@ -2729,7 +2874,17 @@ function textBlockRevealFraction(s, w, h, t) {
   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;
+  const rs = revealState(lines, s.reveal, t);
+  if (rs.glyphAlphas) {
+    let sum = 0;
+    let n = 0;
+    for (const line of rs.glyphAlphas) for (const a of line) {
+      sum += a;
+      n++;
+    }
+    return n > 0 ? sum / n : 1;
+  }
+  return rs.progress;
 }
 function luminanceGrid(spec, opts = {}) {
   const scene = buildScene(spec, opts);
@@ -4725,12 +4880,14 @@ export {
   resolveSpecPath,
   revealState,
   rotationAt,
+  segmentStart,
   sizeAt,
   spriteIndexAt,
   spriteVariants,
   steerablePaths,
   structuralSignature,
   textSprites,
+  textWidthEm,
   validateSequence,
   validateSpec
 };