@idle-screens/schema 3.1.0 → 3.2.0

package/dist/index.js

@@ -42,7 +42,16 @@ var LIMITS = {
   maxPathPoints: 24,
   minPathDuration: 2e3,
   // ms — a path lap can't be faster than this
-  maxGridColumns: 100
+  maxGridColumns: 100,
+  maxTextBlockLength: 2e3,
+  minTextBlockFontSize: 0.01,
+  maxTextBlockFontSize: 0.2,
+  maxTextBlockMaxWidth: 1,
+  maxSegments: 24,
+  minSegmentDuration: 1e3,
+  // ms — flash-safety floor: segment cuts are luminance transitions
+  maxTransitionDur: 5e3,
+  minTransitionDur: 200
 };
 
 // src/validate.ts
@@ -78,6 +87,7 @@ 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_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"]);
@@ -108,6 +118,14 @@ function validateSpec(spec) {
   if (spec.units !== void 0 && spec.units !== "px" && spec.units !== "viewport") {
     err("units", "must be 'px' | 'viewport'");
   }
+  if (spec.units === "px" && Array.isArray(spec.layers)) {
+    for (const l of spec.layers) {
+      if (isObj(l) && isObj(l.sprite) && l.sprite.kind === "textBlock") {
+        err("units", "textBlock dimensions are viewport fractions \u2014 units: 'px' is not supported with textBlock sprites");
+        break;
+      }
+    }
+  }
   if (spec.referenceViewport !== void 0) {
     if (!isNum(spec.referenceViewport) || spec.referenceViewport < 100 || spec.referenceViewport > 8640) {
       err("referenceViewport", "must be a number between 100 and 8640");
@@ -407,8 +425,28 @@ function validateSprite(sprite, path, err, warn) {
     }
     color(sprite.color, `${path}.color`, err);
     validatePalette(sprite, path, err);
+  } else if (sprite.kind === "textBlock") {
+    knownSet = KNOWN_TEXT_BLOCK;
+    if (typeof sprite.text !== "string" || sprite.text.length === 0) {
+      err(`${path}.text`, "must be a non-empty string");
+    } else if (sprite.text.length > LIMITS.maxTextBlockLength) {
+      err(`${path}.text`, `must be at most ${LIMITS.maxTextBlockLength} characters`);
+    }
+    if (!isNum(sprite.maxWidth) || sprite.maxWidth <= 0 || sprite.maxWidth > LIMITS.maxTextBlockMaxWidth) {
+      err(`${path}.maxWidth`, `must be a positive number up to ${LIMITS.maxTextBlockMaxWidth} (viewport fraction)`);
+    }
+    if (!isNum(sprite.fontSize) || sprite.fontSize < LIMITS.minTextBlockFontSize || sprite.fontSize > LIMITS.maxTextBlockFontSize) {
+      err(`${path}.fontSize`, `must be between ${LIMITS.minTextBlockFontSize} and ${LIMITS.maxTextBlockFontSize} (viewport fraction)`);
+    }
+    if (sprite.lineHeight !== void 0 && (!isNum(sprite.lineHeight) || sprite.lineHeight < 0.5 || sprite.lineHeight > 4)) {
+      err(`${path}.lineHeight`, "must be between 0.5 and 4 (multiplier)");
+    }
+    if (sprite.align !== void 0 && !["left", "center", "right"].includes(sprite.align)) {
+      err(`${path}.align`, "must be 'left' | 'center' | 'right'");
+    }
+    if (sprite.color !== void 0) color(sprite.color, `${path}.color`, err);
   } else {
-    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect");
+    err(`${path}.kind`, "must be emoji | text | circle | ring | streak | rect | textBlock");
     return;
   }
   for (const k of unknownKeys(sprite, knownSet)) {
@@ -576,6 +614,86 @@ ${r.errors.map((e) => `  ${e.path || "<root>"}: ${e.message}`).join("\n")}`);
   }
   return spec;
 }
+function validateSequence(seq) {
+  const errors = [];
+  const warnings = [];
+  const err = (path, message) => void errors.push({ path, message });
+  if (!isObj(seq)) return { valid: false, errors: [{ path: "", message: "sequence must be an object" }], warnings: [] };
+  if (seq.format !== "idle-sequence") err("format", "must be 'idle-sequence'");
+  if (seq.schemaVersion !== SCHEMA_VERSION) err("schemaVersion", `must be ${SCHEMA_VERSION}`);
+  if (!isStr(seq.id) || seq.id.trim() === "") err("id", "must be a non-empty string");
+  if (!isStr(seq.label) || seq.label.trim() === "") err("label", "must be a non-empty string");
+  if (seq.seed !== void 0 && !isNum(seq.seed)) err("seed", "must be a number");
+  if (typeof seq.loop !== "boolean") err("loop", "must be a boolean");
+  if (!Array.isArray(seq.segments) || seq.segments.length === 0) {
+    err("segments", "must be a non-empty array");
+    return { valid: false, errors, warnings };
+  }
+  if (seq.segments.length > LIMITS.maxSegments) {
+    err("segments", `at most ${LIMITS.maxSegments} segments`);
+  }
+  const keys = /* @__PURE__ */ new Set();
+  let hasDurationless = false;
+  for (let i = 0; i < seq.segments.length; i++) {
+    const s = seq.segments[i];
+    const p = `segments[${i}]`;
+    if (!isObj(s)) {
+      err(p, "must be an object");
+      continue;
+    }
+    if (!isStr(s.key) || s.key.trim() === "") {
+      err(`${p}.key`, "must be a non-empty string");
+    } else if (keys.has(s.key)) {
+      err(`${p}.key`, `duplicate key '${s.key}'`);
+    } else {
+      keys.add(s.key);
+    }
+    if (s.duration !== void 0) {
+      if (hasDurationless) {
+        err(`${p}.duration`, "a segment after a durationless segment may not have a duration");
+      }
+      if (!isNum(s.duration) || s.duration < LIMITS.minSegmentDuration) {
+        err(`${p}.duration`, `must be >= ${LIMITS.minSegmentDuration} ms`);
+      }
+    } else {
+      if (i < seq.segments.length - 1) {
+        err(`${p}.duration`, "only the final segment may omit duration");
+      }
+      hasDurationless = true;
+    }
+    if (s.advance !== void 0 && !["auto", "input", "either"].includes(s.advance)) {
+      err(`${p}.advance`, "must be 'auto' | 'input' | 'either'");
+    }
+    if (s.transition !== void 0) {
+      if (!isObj(s.transition)) {
+        err(`${p}.transition`, "must be an object");
+      } else if (s.transition.type !== "cut") {
+        err(`${p}.transition.type`, "must be 'cut' (fade not yet supported)");
+      }
+    }
+    if (isObj(s.scene)) {
+      const sceneResult = validateSpec(s.scene);
+      for (const e of sceneResult.errors) errors.push({ path: `${p}.scene.${e.path}`, message: e.message });
+      if (sceneResult.warnings) {
+        for (const w of sceneResult.warnings) warnings.push({ path: `${p}.scene.${w.path}`, code: w.code, message: w.message });
+      }
+    } else {
+      err(`${p}.scene`, "must be a valid SaverSpec object");
+    }
+  }
+  if (seq.loop === true && hasDurationless) {
+    err("loop", "loop: true requires all segments to have a duration");
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function assertValidSequence(seq) {
+  const r = validateSequence(seq);
+  if (!r.valid) {
+    throw new Error(`invalid sequence:
+${r.errors.map((e) => `  ${e.path || "<root>"}: ${e.message}`).join("\n")}`);
+  }
+  return seq;
+}
 
 // src/simulate.ts
 var WARP_NEAR = 0.08;
@@ -660,7 +778,7 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
   }
   const out = [];
   for (let i = 0; i < effectiveCount; i++) {
-    const size = sprite.kind === "circle" || sprite.kind === "ring" ? rng.range(sprite.radius[0], sprite.radius[1]) * 2 * scale : sprite.kind === "streak" ? rng.range(sprite.length[0], sprite.length[1]) * scale : sprite.kind === "rect" ? rng.range(sprite.width[0], sprite.width[1]) * scale : rng.range(smin, smax) * scale;
+    const size = sprite.kind === "textBlock" ? sprite.fontSize * scale : sprite.kind === "circle" || sprite.kind === "ring" ? rng.range(sprite.radius[0], sprite.radius[1]) * 2 * scale : sprite.kind === "streak" ? rng.range(sprite.length[0], sprite.length[1]) * scale : sprite.kind === "rect" ? rng.range(sprite.width[0], sprite.width[1]) * scale : rng.range(smin, smax) * scale;
     const size2 = sprite.kind === "rect" ? size * (sprite.aspect ? rng.range(sprite.aspect[0], sprite.aspect[1]) : 1) : void 0;
     let vx = 0;
     let vy = 0;
@@ -1044,6 +1162,51 @@ function linkPairs(positions, k, maxDist, doWrap, w, h) {
   }
   return out;
 }
+var CHAR_NARROW = new Set(`iIljtf1!|.,;:'"()[]{}`);
+var CHAR_WIDE = new Set("mwMWGOQD@%");
+function charWidthEm(ch) {
+  if (ch === " " || ch === "	") return 0.3;
+  if (CHAR_NARROW.has(ch)) return 0.35;
+  if (CHAR_WIDE.has(ch)) return 0.72;
+  return 0.55;
+}
+function textWidthEm(str) {
+  let w = 0;
+  for (let i = 0; i < str.length; i++) w += charWidthEm(str[i]);
+  return w;
+}
+function breakTextBlock(text, maxWidthEm) {
+  const paragraphs = text.split("\n");
+  const lines = [];
+  for (const para of paragraphs) {
+    if (para.length === 0) {
+      lines.push({ text: "", widthEm: 0 });
+      continue;
+    }
+    const words = para.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0) {
+      lines.push({ text: "", widthEm: 0 });
+      continue;
+    }
+    let lineText = words[0];
+    let lineW = textWidthEm(lineText);
+    const spaceW = charWidthEm(" ");
+    for (let i = 1; i < words.length; i++) {
+      const word = words[i];
+      const wordW = textWidthEm(word);
+      if (lineW + spaceW + wordW <= maxWidthEm) {
+        lineText += " " + word;
+        lineW += spaceW + wordW;
+      } else {
+        lines.push({ text: lineText, widthEm: lineW });
+        lineText = word;
+        lineW = wordW;
+      }
+    }
+    lines.push({ text: lineText, widthEm: lineW });
+  }
+  return lines;
+}
 
 // src/compile.ts
 import {
@@ -1173,12 +1336,41 @@ function structuralSignature(spec) {
         l.sprite.kind === "rect" ? [s.width, s.aspect] : void 0,
         Array.isArray(s.colors) ? s.colors.length : void 0,
         s.colorWeights,
-        l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : void 0
+        l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : l.sprite.kind === "textBlock" ? [l.sprite.fontSize] : void 0
       ];
     })
   ]);
 }
 
+// src/sequence.ts
+function resolveSegment(seq, T) {
+  const { segments, loop } = seq;
+  if (segments.length === 0) return { index: 0, localT: 0, startT: 0 };
+  let totalTimed = 0;
+  for (const seg of segments) {
+    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 };
+    }
+    cumulative += seg.duration;
+  }
+  const last = segments.length - 1;
+  const lastStart = cumulative - (segments[last].duration ?? 0);
+  return { index: last, localT: t - lastStart, startT: lastStart };
+}
+
 // src/compile.ts
 var DEFAULT_STEER_DUR = 1e3;
 function hexToRgba(hex, alpha) {
@@ -1226,12 +1418,14 @@ var SpecInstance = class {
     let canvas;
     if (ctx.surface) {
       canvas = ctx.surface;
+      this.ownsCanvas = false;
     } else {
       const el = document.createElement("canvas");
       el.style.cssText = "display:block;width:100%;height:100%";
       el.setAttribute("aria-hidden", "true");
       ctx.host.appendChild(el);
       canvas = el;
+      this.ownsCanvas = true;
     }
     this.canvas = canvas;
     const c2d = canvas.getContext("2d", { alpha: false });
@@ -1247,6 +1441,7 @@ var SpecInstance = class {
   }
   spec;
   canvas;
+  ownsCanvas;
   ctx;
   saverCtx;
   seed;
@@ -1365,7 +1560,7 @@ var SpecInstance = class {
     const headAlpha = alphaAt(e, t) * lifeA;
     const headSize = sizeAt(e, t);
     const sprite = built.layer.sprite;
-    const resolvedColor = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" ? sprite.color ?? "#e6e8ef" : "#e6e8ef";
+    const resolvedColor = sprite.kind === "circle" || sprite.kind === "ring" || sprite.kind === "streak" || sprite.kind === "rect" ? sprite.colors?.[e.colorIndex] ?? sprite.color : sprite.kind === "text" || sprite.kind === "textBlock" ? sprite.color ?? "#e6e8ef" : "#e6e8ef";
     const isSoft = sprite.kind === "circle" && sprite.soft;
     const wrap2 = built.layer.wrap !== false;
     const head = this.entityPos(e, t, parentE);
@@ -1472,6 +1667,28 @@ var SpecInstance = class {
       ctx.restore();
       return;
     }
+    if (sprite.kind === "textBlock") {
+      const unitScale2 = Math.min(this.w, this.h);
+      const fsPx = sprite.fontSize * unitScale2;
+      const lh = (sprite.lineHeight ?? 1.4) * fsPx;
+      const maxWPx = sprite.maxWidth * unitScale2;
+      const maxWEm = maxWPx / fsPx;
+      const lines = breakTextBlock(sprite.text, maxWEm);
+      const align = sprite.align ?? "left";
+      ctx.save();
+      ctx.translate(p.x, p.y);
+      if (rot) ctx.rotate(rot);
+      ctx.font = `${fsPx}px system-ui, sans-serif`;
+      ctx.fillStyle = sprite.color ?? "#e6e8ef";
+      ctx.textBaseline = "top";
+      ctx.textAlign = align;
+      const xOff = align === "center" ? maxWPx / 2 : align === "right" ? maxWPx : 0;
+      for (let li = 0; li < lines.length; li++) {
+        ctx.fillText(lines[li].text, xOff, li * lh);
+      }
+      ctx.restore();
+      return;
+    }
     ctx.save();
     ctx.translate(p.x, p.y);
     if (rot) ctx.rotate(rot);
@@ -1641,7 +1858,7 @@ var SpecInstance = class {
   }
   dispose() {
     this.stop();
-    if (typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
+    if (this.ownsCanvas && typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
   }
 };
 function compileSaver(spec) {
@@ -1652,6 +1869,129 @@ function compileSaver(spec) {
     spec: valid
   };
 }
+var SequenceInstance = class {
+  seq;
+  childCtx;
+  canvas;
+  children;
+  activeIndex = -1;
+  paused = false;
+  constructor(seq, ctx) {
+    this.seq = seq;
+    let surface = ctx.surface ?? null;
+    let canvas = null;
+    if (!surface && typeof document !== "undefined") {
+      canvas = document.createElement("canvas");
+      canvas.style.cssText = "display:block;width:100%;height:100%";
+      canvas.setAttribute("aria-hidden", "true");
+      ctx.host.appendChild(canvas);
+      surface = canvas;
+    }
+    this.canvas = canvas;
+    this.childCtx = { ...ctx, surface, reducedMotion: true };
+    this.children = new Array(seq.segments.length).fill(null);
+  }
+  childScene(index) {
+    const seg = this.seq.segments[index];
+    if (seg.scene.seed != null) return seg.scene;
+    if (this.seq.seed != null) return { ...seg.scene, seed: this.seq.seed + index };
+    return seg.scene;
+  }
+  ensureChild(index) {
+    if (index < 0 || index >= this.seq.segments.length) index = 0;
+    let child = this.children[index];
+    if (!child) {
+      child = new SpecInstance(this.childScene(index), this.childCtx);
+      this.children[index] = child;
+      if (this.paused) child.setPaused(true);
+    }
+    return child;
+  }
+  releaseChild(index) {
+    const child = this.children[index];
+    if (child) {
+      child.dispose();
+      this.children[index] = null;
+    }
+  }
+  renderFrame(T, seed) {
+    const resolved = resolveSegment(this.seq, T);
+    const { index, localT } = resolved;
+    if (index !== this.activeIndex) {
+      for (let i = 0; i < this.children.length; i++) {
+        if (i !== index) this.releaseChild(i);
+      }
+      this.activeIndex = index;
+    }
+    const child = this.ensureChild(index);
+    const childSeed = this.seq.segments[index].scene.seed ?? this.seq.seed ?? seed;
+    child.renderFrame(localT, childSeed);
+  }
+  setPaused(paused) {
+    this.paused = paused;
+    for (const child of this.children) {
+      child?.setPaused(paused);
+    }
+  }
+  resize(width, height, dpr) {
+    for (const child of this.children) {
+      child?.resize(width, height, dpr);
+    }
+  }
+  applyTrack(track) {
+    const deltas = track?.deltas ?? [];
+    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);
+      }
+    }
+    const childDeltas = deltas.filter((d) => d.path !== "sequence.segment");
+    if (childDeltas.length > 0 && this.activeIndex >= 0) {
+      const child = this.children[this.activeIndex];
+      child?.applyTrack({ ...track, deltas: childDeltas });
+    }
+  }
+  dispose() {
+    for (let i = 0; i < this.children.length; i++) {
+      this.releaseChild(i);
+    }
+    if (this.canvas) this.canvas.remove();
+  }
+};
+function sequenceManifest(seq) {
+  const maxTotal = seq.segments.reduce((max, s) => {
+    const t = s.scene.layers.reduce((n, l) => n + l.count, 0);
+    return Math.max(max, t);
+  }, 0);
+  const costTier = maxTotal < 30 ? "idle" : maxTotal < 150 ? "low" : maxTotal < 400 ? "medium" : "high";
+  return {
+    id: seq.id,
+    label: seq.label,
+    timeModel: "closed-form",
+    passthrough: false,
+    minBackend: "canvas2d",
+    costTier,
+    motionIntensity: "moderate",
+    reducedMotionFallback: "static",
+    a11y: { flashSafe: true },
+    workerReady: false
+  };
+}
+function compileSequence(spec) {
+  const valid = assertValidSequence(spec);
+  return {
+    manifest: sequenceManifest(valid),
+    mount: (ctx) => new SequenceInstance(valid, ctx),
+    spec: valid
+  };
+}
 
 // src/advise.ts
 import { createRng as createRng2 } from "@idle-screens/core";
@@ -1671,7 +2011,7 @@ function spriteLuma(layer, e) {
   if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
     return hexLuma(s.colors?.[e.colorIndex] ?? s.color);
   }
-  if (s.kind === "text") return hexLuma(s.color ?? "#e6e8ef");
+  if (s.kind === "text" || s.kind === "textBlock") return hexLuma(s.color ?? "#e6e8ef");
   return 0.75;
 }
 function spriteHex(layer, e) {
@@ -1679,7 +2019,7 @@ function spriteHex(layer, e) {
   if (s.kind === "circle" || s.kind === "ring" || s.kind === "streak" || s.kind === "rect") {
     return s.colors?.[e.colorIndex] ?? s.color;
   }
-  if (s.kind === "text") return s.color ?? "#e6e8ef";
+  if (s.kind === "text" || s.kind === "textBlock") return s.color ?? "#e6e8ef";
   return null;
 }
 function backgroundLuma(spec) {
@@ -1734,7 +2074,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
     const layer = spec.layers[li];
     const entities = allEntities[li];
     totalEntities += entities.length;
-    const isText = layer.sprite.kind === "text";
+    const isText = layer.sprite.kind === "text" || layer.sprite.kind === "textBlock";
     const isStaticText = isText && layer.motion.type === "static";
     if (isStaticText) textLayerCount++;
     if (layer.motion.type !== "static") motionLayerCount++;
@@ -1793,7 +2133,18 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }) {
     const entities = allEntities[li];
     for (const e of entities) {
       const r = e.size / 2;
-      const pixArea = layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
+      let pixArea;
+      if (layer.sprite.kind === "circle") {
+        pixArea = Math.PI * r * r;
+      } else if (layer.sprite.kind === "textBlock") {
+        const fsPx = layer.sprite.fontSize * scale;
+        const lh = (layer.sprite.lineHeight ?? 1.4) * fsPx;
+        const maxWPx = layer.sprite.maxWidth * scale;
+        const lines = breakTextBlock(layer.sprite.text, maxWPx / fsPx);
+        pixArea = maxWPx * lines.length * lh * 0.55;
+      } else {
+        pixArea = e.size * e.size;
+      }
       totalCoverage += pixArea * e.alpha / (w * h);
     }
     if (layer.links) {
@@ -2021,6 +2372,24 @@ function textBox(s, e, p) {
     halfY: fh * 0.6
   };
 }
+function textBlockBox(s, _e, p, w, h) {
+  const unitScale = Math.min(w, h);
+  const fsPx = s.fontSize * unitScale;
+  const lh = (s.lineHeight ?? 1.4) * fsPx;
+  const maxWPx = s.maxWidth * unitScale;
+  const maxWEm = maxWPx / fsPx;
+  const lines = breakTextBlock(s.text, maxWEm);
+  const totalH = lines.length * lh;
+  const maxLineW = lines.reduce((m, l) => Math.max(m, l.widthEm), 0) * fsPx;
+  const align = s.align ?? "left";
+  const cx = align === "center" ? p.x + maxWPx / 2 : align === "right" ? p.x + maxWPx - maxLineW / 2 : p.x + maxLineW / 2;
+  return {
+    cx,
+    cy: p.y + totalH / 2,
+    halfX: maxLineW / 2,
+    halfY: totalH / 2
+  };
+}
 function luminanceGrid(spec, opts = {}) {
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
@@ -2142,6 +2511,12 @@ function luminanceGrid(spec, opts = {}) {
           centerY = box.cy;
           halfX = box.halfX;
           halfY = box.halfY;
+        } else if (s.kind === "textBlock") {
+          const box = textBlockBox(s, e, p, w, h);
+          centerX = box.cx;
+          centerY = box.cy;
+          halfX = box.halfX;
+          halfY = box.halfY;
         }
         const circular = s.kind === "circle" || s.kind === "ring";
         const soft = s.kind === "circle" && !!s.soft;
@@ -2153,7 +2528,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" ? 0.55 : 1;
+        const inkWeight = s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1;
         for (let r = r0; r <= r1; r++) {
           for (let c = c0; c <= c1; c++) {
             const dx = (c + 0.5) * cellW - centerX;
@@ -2312,6 +2687,13 @@ function textSprites(spec, opts = {}) {
   const t = opts.t ?? 5e3;
   const out = [];
   scene.layers.forEach(({ layer, entities }, layerIndex) => {
+    if (layer.sprite.kind === "textBlock") {
+      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) });
+      return;
+    }
     if (layer.sprite.kind !== "text") return;
     const s = layer.sprite;
     const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
@@ -2362,6 +2744,9 @@ function dominanceRanking(spec, opts = {}) {
       } else if (s.kind === "text") {
         const box = textBox(s, e, { x: 0, y: 0 });
         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;
       } else entArea = sz * sz * 0.55;
       area += entArea * a;
       if (layer.trail) {
@@ -3213,6 +3598,36 @@ var DASHBOARD_SPEC = {
   ]
 };
 
+// src/examples/haiku.ts
+var HAIKU_SPEC = {
+  schemaVersion: 1,
+  id: "haiku",
+  label: "Haiku",
+  seed: 42,
+  background: { type: "solid", color: "#080812" },
+  layers: [
+    {
+      count: 1,
+      sprite: {
+        kind: "textBlock",
+        text: "An old silent pond\nA frog jumps into the pond \u2014\nSplash! Silence again.",
+        maxWidth: 0.8,
+        fontSize: 0.05,
+        lineHeight: 1.8,
+        align: "center",
+        color: "#c8cad4"
+      },
+      motion: { type: "static" },
+      position: { x: 0.1, y: 0.35 }
+    },
+    {
+      count: 30,
+      sprite: { kind: "circle", radius: [5e-4, 15e-4], color: "#3a3a5c" },
+      motion: { type: "drift", speed: [2e-3, 6e-3], angle: 270 }
+    }
+  ]
+};
+
 // src/examples/lanterns.ts
 var LANTERNS_SPEC = {
   schemaVersion: 1,
@@ -3906,7 +4321,8 @@ var SCHEMA_EXAMPLES = [
   { id: "polygons", label: "Polygons", spec: POLYGONS_SPEC },
   { id: "matrix-rain", label: "Matrix Rain", spec: MATRIX_RAIN_SPEC },
   { id: "procession", label: "Night Procession", spec: PROCESSION_SPEC },
-  { id: "nostalghia-candle", label: "Nostalghia's Candle", spec: NOSTALGHIA_CANDLE_SPEC }
+  { id: "nostalghia-candle", label: "Nostalghia's Candle", spec: NOSTALGHIA_CANDLE_SPEC },
+  { id: "haiku", label: "Haiku", spec: HAIKU_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -3920,6 +4336,7 @@ export {
   DASHBOARD_SPEC,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
+  HAIKU_SPEC,
   LANTERNS_SPEC,
   LIMITS,
   MATRIX_RAIN_SPEC,
@@ -3937,9 +4354,12 @@ export {
   adviseSpec,
   alphaAt,
   applyDeltasToSpec,
+  assertValidSequence,
   assertValidSpec,
+  breakTextBlock,
   buildEntities,
   compileSaver,
+  compileSequence,
   describeScene,
   diffScenes,
   dominanceRanking,
@@ -3956,6 +4376,7 @@ export {
   positionAt,
   renderBrailleMap,
   renderDensityMap,
+  resolveSegment,
   resolveSpecPath,
   rotationAt,
   sizeAt,
@@ -3964,6 +4385,7 @@ export {
   steerablePaths,
   structuralSignature,
   textSprites,
+  validateSequence,
   validateSpec
 };
 //# sourceMappingURL=index.js.map