@glissade/narrate 0.67.0 → 0.68.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { AssetRef, AudioClip, Key, Track } from "@glissade/core";
-import { FilterSpec, Text } from "@glissade/scene";
+import { FilterSpec, Text, TextMeasurer } from "@glissade/scene";
 import { SafeArea } from "@glissade/scene/diagnostics";
 
 //#region src/index.d.ts
@@ -86,14 +86,13 @@ interface NarrationScript {
    */
   align?: string;
   /**
-   * Split long caption segments into timed sub-cues at ~`maxChars` (on word
-   * boundaries, using per-word timings when present). Persisted into the timing
-   * manifest so the burned track and the .srt/.vtt sidecars split identically.
+   * Split long caption segments into timed sub-cues. `{ maxChars }` = the legacy
+   * char-budget word-boundary split; `{ mode: 'band' }` = the measured band-fit split
+   * (per-locale sentence→clause→word, needs the render size/style via captionTrack's
+   * opts). Persisted so the burned track and the .srt/.vtt sidecars split identically.
    * Omit for no split (the default).
    */
-  captionSplit?: {
-    maxChars: number;
-  };
+  captionSplit?: CaptionSplitPolicy;
   /**
    * Anchor budgets (s): per-id ceilings on a segment's (or pause's) beat length,
    * checked by `gs narration-lint` (Tier-1, can fail CI). Committed with the
@@ -165,10 +164,8 @@ interface NarrationTiming {
   segments: TimedSegment[];
   /** explicit pause windows, addressable like segments; omitted when none */
   pauses?: TimedPause[];
-  /** caption split budget, committed so burned + sidecar split identically */
-  captionSplit?: {
-    maxChars: number;
-  };
+  /** caption split policy, committed so burned + sidecar split identically */
+  captionSplit?: CaptionSplitPolicy;
   /**
    * Anchor budgets (s) carried from the script — per id, segments + pauses.
    * `gs narration-lint` reads them from the committed manifest (Tier-1). A
@@ -240,6 +237,23 @@ interface CaptionTrackOptions {
   target?: string;
   /** v1 granularity is per segment; 'word' is reserved (karaoke highlight, later) */
   granularity?: 'segment';
+  /**
+   * Render context for `captionSplit: { mode: 'band' }` — the SAME `size` + `style`
+   * the paired `captionNode(size, style)` uses, so the band-fit split measures what
+   * the render lays out (measure-consistency). REQUIRED when the policy is band mode
+   * (throws without `size`); ignored for the legacy `{ maxChars }` path.
+   */
+  size?: {
+    w: number;
+    h: number;
+  };
+  style?: CaptionStyle;
+  /** the measurer the render lays out with (band mode) — defaults to the process fallback. */
+  measurer?: TextMeasurer;
+  /** band-mode measurer-fail-loud opt-out (LOUD: an estimate-split may overflow at render). */
+  estimate?: boolean;
+  /** band-mode boundary locale (falls back to the policy's `locale`). */
+  locale?: string;
 }
 /** One caption cue within a segment's window. */
 interface CaptionCue {
@@ -247,6 +261,23 @@ interface CaptionCue {
   start: number;
   end: number;
 }
+/**
+ * How to split long caption segments into sub-cues:
+ * - `{ maxChars }` — the legacy char-budget, word-boundary split ({@link splitCaption}).
+ * - `{ mode: 'band', locale? }` — the measured band-fit split ({@link captionAutoSplit}):
+ *   breaks at per-locale sentence → clause → word so every cue fits the caption band at
+ *   the min-legible floor. Needs the render context (size + style) supplied via
+ *   {@link CaptionTrackOptions}. `maxLines` / `minLegiblePx` deliberately live in
+ *   {@link CaptionStyle} (NOT here) — they must match the paired `captionNode`'s layout
+ *   for measure-consistency, so there is ONE source of truth for them; only `locale`
+ *   (a split-only, render-irrelevant concern) rides the policy.
+ */
+type CaptionSplitPolicy = {
+  maxChars: number;
+} | {
+  mode: 'band';
+  locale?: string;
+};
 /**
  * Split a segment's caption into timed sub-cues at ~`maxChars` (word-boundary).
  * With per-word timings, each sub-cue is timed from its first word; without
@@ -285,16 +316,73 @@ interface CaptionStyle {
   maxLines?: number;
   /** floor for auto-shrink, as a fraction of the base font size (autoFit only); default 0.7 */
   minScale?: number;
+  /**
+   * Absolute legibility floor in px — the auto-shrink (and the band-split fit)
+   * never go below this, on top of the `minScale` fraction. Off by default
+   * (byte-identical), so the floor stays `round(baseFont·minScale)` unless set.
+   * `captionAutoSplit` splits so every cue fits at this same floor.
+   */
+  minLegiblePx?: number;
 }
-/**
- * Bottom-centered captions inside the platform-safe area: portrait scenes
- * (9:16 cutdowns live under reels/shorts UI chrome) sit higher than
- * landscape. Same node id pairs with captionTrack's default target.
- */
 declare function captionNode(size: {
   w: number;
   h: number;
 }, style?: CaptionStyle): Text;
+/**
+ * Thrown by {@link captionAutoSplit} when a single word in a cue is too wide to fit
+ * the caption band even at the min-legible floor — it can't be split further, so the
+ * author must intervene rather than the caption silently degrading legibility or
+ * dropping words (a hard throw, no clamp). Names the word + its segment id + the fixes
+ * in priority order: reword/shorten the word FIRST (it is almost always a URL or a long
+ * token), and only as a last resort — since they trade the legibility the split exists
+ * to protect — widen the band or lower the min font.
+ */
+declare class CaptionFitError extends Error {
+  readonly word: string;
+  readonly segmentId: string;
+  readonly bandWidth: number;
+  readonly minFontPx: number;
+  constructor(word: string, segmentId: string, bandWidth: number, minFontPx: number);
+}
+/**
+ * Band-fit caption auto-split options. The render CONTEXT so the split's fit-measure
+ * matches the render's layout (measure-consistency): `size` + `style` MUST be the same
+ * a paired `captionNode(size, style)` uses — both derive the band via `captionBandParams`.
+ */
+interface CaptionAutoSplitOpts {
+  /** the scene size the caption renders into (drives band width + base font). */
+  size: {
+    w: number;
+    h: number;
+  };
+  /** the SAME style passed to captionNode (widthFrac / fontSize / minScale / minLegiblePx / maxLines). */
+  style?: CaptionStyle;
+  /**
+   * the measurer the RENDER lays out with — MUST be the same for measure-consistency.
+   * Defaults to the process fallback (fails loud without a real one — see `estimate`).
+   */
+  measurer?: TextMeasurer;
+  /**
+   * measurer-fail-loud opt-out, and LOUD for captions: an estimate-split may OVERFLOW
+   * the band when rendered with real metrics (cues fit only if the render also
+   * estimates). Prefer a real measurer for a guaranteed fit. Default false (fail loud).
+   */
+  estimate?: boolean;
+  /** BCP-47 locale for per-locale boundary detection (sentence + word segmentation). */
+  locale?: string;
+}
+/**
+ * Split a segment's caption into timed sub-cues that each FIT the caption band at the
+ * min-legible floor — the measured, band-aware alternative to {@link splitCaption}'s
+ * char-count budget. Splits at per-locale **sentence → clause → word** boundaries (via
+ * `splitToFit`), so a long line breaks at meaningful points, never mid-thought. A cue
+ * that already fits stays whole (a short caption is a single cue → the default is a
+ * no-op). Sub-cue timing mirrors splitCaption: with per-word timings each cue starts at
+ * its first word; without them the segment window divides evenly. Throws
+ * {@link CaptionFitError} when a single word can't fit even alone. Pure / build-time
+ * (like splitText) — the fit measurer never enters the render or cert hash.
+ */
+declare function captionAutoSplit(segment: TimedSegment, opts: CaptionAutoSplitOpts): CaptionCue[];
 /**
  * The TOP (device px) of the reserved caption band — the Y above which foreground
  * art is safe and below which it collides with captions. Derived from `captionNode`'s
@@ -415,7 +503,7 @@ interface MusicAnchors {
 declare function validateMusicTiming(timing: MusicTiming): void;
 /** Beat-grid anchors over a music manifest; `at` places the clip on the timeline. */
 declare function music(timing: MusicTiming, at?: number): MusicAnchors;
-declare function toSrt(timing: NarrationTiming): string;
-declare function toVtt(timing: NarrationTiming): string;
+declare function toSrt(timing: NarrationTiming, ctx?: Pick<CaptionTrackOptions, 'size' | 'style' | 'measurer' | 'estimate' | 'locale'>): string;
+declare function toVtt(timing: NarrationTiming, ctx?: Pick<CaptionTrackOptions, 'size' | 'style' | 'measurer' | 'estimate' | 'locale'>): string;
 //#endregion
-export { BedMode, CAPTION_NODE_ID, CaptionCue, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, VoiceBlend, VoiceBlendEntry, VoiceSpec, captionNode, captionSafeArea, captionTop, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };
+export { BedMode, CAPTION_NODE_ID, CaptionAutoSplitOpts, CaptionCue, CaptionFitError, CaptionSplitPolicy, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, VoiceBlend, VoiceBlendEntry, VoiceSpec, captionAutoSplit, captionNode, captionSafeArea, captionTop, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { key, track } from "@glissade/core";
 import { Text, breakLines, estimatingMeasurer, glow, quantize } from "@glissade/scene";
 import "@glissade/scene/diagnostics";
+import { TextFitError, splitToFit } from "@glissade/scene/type";
 //#region src/index.ts
 /**
 * @glissade/narrate — narration + captions, the PURE side. TTS happens only
@@ -164,34 +165,58 @@ function splitCaption(segment, maxChars) {
 * are subtree-matched exempt in CAPTION_COLLISION).
 */
 const CAPTION_NODE_ID = "captions";
+/**
+* Dispatch a segment to its cues by the {@link CaptionSplitPolicy}: band mode →
+* {@link captionAutoSplit} (needs the render `size`/`style` from `ctx`, fails loud
+* without `size`); `{ maxChars }` or absent → {@link splitCaption} (byte-identical to
+* pre-0.68). The SAME dispatch drives the burned track AND the .srt/.vtt sidecars, so
+* they match by construction.
+*/
+function segmentCues(segment, policy, ctx) {
+	if (policy && "mode" in policy && policy.mode === "band") {
+		if (!ctx.size) throw new Error("captionTrack: captionSplit { mode: 'band' } needs the render size — pass { size } (and the same { style } you pass to captionNode) so the band-fit split matches the caption band.");
+		const locale = policy.locale ?? ctx.locale;
+		return captionAutoSplit(segment, {
+			size: ctx.size,
+			...ctx.style !== void 0 ? { style: ctx.style } : {},
+			...ctx.measurer !== void 0 ? { measurer: ctx.measurer } : {},
+			...ctx.estimate !== void 0 ? { estimate: ctx.estimate } : {},
+			...locale !== void 0 ? { locale } : {}
+		});
+	}
+	return splitCaption(segment, policy && "maxChars" in policy ? policy.maxChars : void 0);
+}
 function captionTrack(timing, opts = {}) {
 	const target = opts.target ?? `captions/text`;
-	const budget = timing.captionSplit?.maxChars;
 	const keys = [key(0, "", { interp: "hold" })];
 	let cursor = 0;
 	for (const s of timing.segments) {
 		if (s.start > cursor + 1e-9) {
 			if (keys[keys.length - 1].value !== "") keys.push(key(cursor, "", { interp: "hold" }));
 		}
-		for (const cue of splitCaption(s, budget)) if (cue.start <= 1e-9) keys[0] = key(0, cue.text, { interp: "hold" });
+		for (const cue of segmentCues(s, timing.captionSplit, opts)) if (cue.start <= 1e-9) keys[0] = key(0, cue.text, { interp: "hold" });
 		else keys.push(key(cue.start, cue.text, { interp: "hold" }));
 		cursor = s.start + s.duration;
 	}
 	keys.push(key(cursor, "", { interp: "hold" }));
 	return track(target, "string", keys);
 }
-/**
-* Bottom-centered captions inside the platform-safe area: portrait scenes
-* (9:16 cutdowns live under reels/shorts UI chrome) sit higher than
-* landscape. Same node id pairs with captionTrack's default target.
-*/
-function captionNode(size, style = {}) {
+function captionBandParams(size, style) {
 	const portrait = size.h > size.w;
-	const inset = style.bottomInsetFrac ?? (portrait ? .18 : .1);
 	const baseFont = style.fontSize ?? Math.round(Math.min(size.w, size.h) * (portrait ? .052 : .06));
-	const fontFamily = style.fontFamily ?? "sans-serif";
-	const width = Math.round(size.w * (style.widthFrac ?? .82));
-	const lineHeight = style.lineHeight ?? 1.3;
+	return {
+		portrait,
+		fontFamily: style.fontFamily ?? "sans-serif",
+		baseFont,
+		width: Math.round(size.w * (style.widthFrac ?? .82)),
+		lineHeight: style.lineHeight ?? 1.3,
+		maxLines: Math.max(1, style.maxLines ?? 2),
+		minFont: Math.max(1, style.minLegiblePx ?? 0, Math.round(baseFont * (style.minScale ?? .7)))
+	};
+}
+function captionNode(size, style = {}) {
+	const { portrait, fontFamily, baseFont, width, lineHeight, maxLines, minFont } = captionBandParams(size, style);
+	const inset = style.bottomInsetFrac ?? (portrait ? .18 : .1);
 	const bottomY = Math.round(size.h * (1 - inset));
 	const node = new Text({
 		id: CAPTION_NODE_ID,
@@ -206,8 +231,6 @@ function captionNode(size, style = {}) {
 		filters: style.filters ?? glow("#000000cc", 3, 1)
 	});
 	if (style.autoFit) {
-		const maxLines = Math.max(1, style.maxLines ?? 2);
-		const minFont = Math.max(1, Math.round(baseFont * (style.minScale ?? .7)));
 		const lineCountAt = (font, m) => {
 			const t = node.text();
 			if (!t) return 0;
@@ -235,6 +258,89 @@ function captionNode(size, style = {}) {
 	return node;
 }
 /**
+* Thrown by {@link captionAutoSplit} when a single word in a cue is too wide to fit
+* the caption band even at the min-legible floor — it can't be split further, so the
+* author must intervene rather than the caption silently degrading legibility or
+* dropping words (a hard throw, no clamp). Names the word + its segment id + the fixes
+* in priority order: reword/shorten the word FIRST (it is almost always a URL or a long
+* token), and only as a last resort — since they trade the legibility the split exists
+* to protect — widen the band or lower the min font.
+*/
+var CaptionFitError = class extends Error {
+	word;
+	segmentId;
+	bandWidth;
+	minFontPx;
+	constructor(word, segmentId, bandWidth, minFontPx) {
+		super(`captionAutoSplit: segment ${JSON.stringify(segmentId)} has a word ${JSON.stringify(word)} too wide to fit the ${bandWidth}px caption band at the ${minFontPx}px min-legible floor and cannot be split further — reword/shorten the word, or (last resort, trades legibility) widen the caption widthFrac or lower minScale/minLegiblePx.`);
+		this.word = word;
+		this.segmentId = segmentId;
+		this.bandWidth = bandWidth;
+		this.minFontPx = minFontPx;
+		this.name = "CaptionFitError";
+	}
+};
+/**
+* Split a segment's caption into timed sub-cues that each FIT the caption band at the
+* min-legible floor — the measured, band-aware alternative to {@link splitCaption}'s
+* char-count budget. Splits at per-locale **sentence → clause → word** boundaries (via
+* `splitToFit`), so a long line breaks at meaningful points, never mid-thought. A cue
+* that already fits stays whole (a short caption is a single cue → the default is a
+* no-op). Sub-cue timing mirrors splitCaption: with per-word timings each cue starts at
+* its first word; without them the segment window divides evenly. Throws
+* {@link CaptionFitError} when a single word can't fit even alone. Pure / build-time
+* (like splitText) — the fit measurer never enters the render or cert hash.
+*/
+function captionAutoSplit(segment, opts) {
+	const { fontFamily, width, maxLines, minFont } = captionBandParams(opts.size, opts.style ?? {});
+	const font = {
+		family: fontFamily,
+		size: minFont,
+		weight: 400
+	};
+	const end = segment.start + segment.duration;
+	let parts;
+	try {
+		parts = splitToFit(segment.text, {
+			maxWidth: width,
+			font,
+			maxLines,
+			...opts.measurer !== void 0 ? { measurer: opts.measurer } : {},
+			...opts.estimate !== void 0 ? { estimate: opts.estimate } : {},
+			...opts.locale !== void 0 ? { locale: opts.locale } : {}
+		});
+	} catch (e) {
+		if (e instanceof TextFitError) throw new CaptionFitError(e.token, segment.id, width, minFont);
+		throw e;
+	}
+	if (parts.length <= 1) return [{
+		text: segment.text,
+		start: segment.start,
+		end
+	}];
+	if (segment.words && segment.words.length > 0) {
+		const cues = [];
+		let wi = 0;
+		for (let pi = 0; pi < parts.length; pi++) {
+			const startWord = segment.words[Math.min(wi, segment.words.length - 1)];
+			wi += Math.max(1, parts[pi].split(/\s+/).filter(Boolean).length);
+			const cueEnd = pi + 1 < parts.length && wi < segment.words.length ? segment.words[wi].start : end;
+			cues.push({
+				text: parts[pi],
+				start: startWord.start,
+				end: cueEnd
+			});
+		}
+		return cues;
+	}
+	const span = segment.duration / parts.length;
+	return parts.map((text, i) => ({
+		text,
+		start: segment.start + i * span,
+		end: segment.start + (i + 1) * span
+	}));
+}
+/**
 * The TOP (device px) of the reserved caption band — the Y above which foreground
 * art is safe and below which it collides with captions. Derived from `captionNode`'s
 * OWN layout: the caption baseline sits at `h·(1−inset)` (inset 0.10 landscape /
@@ -426,11 +532,26 @@ function srtTime(t, sep) {
 	const p = (n, w) => String(n).padStart(w, "0");
 	return `${p(h, 2)}:${p(m, 2)}:${p(s, 2)}${sep}${p(f, 3)}`;
 }
-function toSrt(timing) {
-	return timing.segments.flatMap((s) => splitCaption(s, timing.captionSplit?.maxChars)).map((c, i) => `${i + 1}\n${srtTime(c.start, ",")} --> ${srtTime(c.end, ",")}\n${c.text}`).join("\n\n") + "\n";
+/**
+* Sidecar cues, tolerant of band mode: with a render `ctx` (size/style) band mode
+* splits exactly like the burned track (burned == sidecar); WITHOUT one — a text
+* sidecar has no pixel band — a band-mode segment stays a single cue (the split is a
+* burned-caption concern). The legacy `{ maxChars }` path needs no context.
+*/
+function sidecarCues(timing, ctx) {
+	const policy = timing.captionSplit;
+	const bandNoContext = policy !== void 0 && "mode" in policy && !ctx.size;
+	return timing.segments.flatMap((s) => bandNoContext ? [{
+		text: s.text,
+		start: s.start,
+		end: s.start + s.duration
+	}] : segmentCues(s, policy, ctx));
+}
+function toSrt(timing, ctx = {}) {
+	return sidecarCues(timing, ctx).map((c, i) => `${i + 1}\n${srtTime(c.start, ",")} --> ${srtTime(c.end, ",")}\n${c.text}`).join("\n\n") + "\n";
 }
-function toVtt(timing) {
-	return "WEBVTT\n\n" + timing.segments.flatMap((s) => splitCaption(s, timing.captionSplit?.maxChars)).map((c) => `${srtTime(c.start, ".")} --> ${srtTime(c.end, ".")}\n${c.text}`).join("\n\n") + "\n";
+function toVtt(timing, ctx = {}) {
+	return "WEBVTT\n\n" + sidecarCues(timing, ctx).map((c) => `${srtTime(c.start, ".")} --> ${srtTime(c.end, ".")}\n${c.text}`).join("\n\n") + "\n";
 }
 //#endregion
-export { CAPTION_NODE_ID, NarrationError, captionNode, captionSafeArea, captionTop, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };
+export { CAPTION_NODE_ID, CaptionFitError, NarrationError, captionAutoSplit, captionNode, captionSafeArea, captionTop, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "glissade narration + captions: TTS at prepare time (gs narrate), deterministic caching, narration-anchored timeline beats, and captions as plain tracks. Render stays offline.",
   "license": "Apache-2.0",
   "engines": {
@@ -22,8 +22,8 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.67.0",
-    "@glissade/scene": "0.67.0"
+    "@glissade/core": "0.68.0",
+    "@glissade/scene": "0.68.0"
   },
   "peerDependencies": {
     "kokoro-js": "^1.2.0"