@glissade/narrate 0.63.2 → 0.64.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { AssetRef, AudioClip, Key, Track } from "@glissade/core";
 import { FilterSpec, Text } from "@glissade/scene";
+import { SafeArea } from "@glissade/scene/diagnostics";
 
 //#region src/index.d.ts
 
@@ -254,6 +255,14 @@ interface CaptionCue {
  * drives the burned track AND the .srt/.vtt sidecars, so they match.
  */
 declare function splitCaption(segment: TimedSegment, maxChars?: number): CaptionCue[];
+/**
+ * The canonical caption node id — the SINGLE source of truth `captionNode`,
+ * `captionTrack`, and `captionSafeArea` all pair on. Keeping it one string means
+ * `captionSafeArea(size).owner === captionNode(size).id` BY CONSTRUCTION, so a
+ * caption never SELF-COLLIDES with its own reserved band (the owner + its subtree
+ * are subtree-matched exempt in CAPTION_COLLISION).
+ */
+declare const CAPTION_NODE_ID = "captions";
 declare function captionTrack(timing: NarrationTiming, opts?: CaptionTrackOptions): Track<string>;
 interface CaptionStyle {
   fontFamily?: string;
@@ -286,6 +295,40 @@ declare function captionNode(size: {
   w: number;
   h: number;
 }, style?: CaptionStyle): Text;
+/**
+ * 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 /
+ * 0.18 portrait), and the band reserves a DEFAULT (2-line) caption block above that
+ * baseline down to the frame bottom, using captionNode's own font fraction /
+ * lineHeight / default maxLines. ONE `Math.round` → integer-stable + deterministic;
+ * landscape and portrait yield different tops (the platform-safe-area asymmetry).
+ */
+declare function captionTop(size: {
+  w: number;
+  h: number;
+}): number;
+/**
+ * Build the reserved caption-band {@link SafeArea} for `critique`/`assess`'s
+ * `safeAreas` from narrate's OWN caption layout — the bottom band from
+ * {@link captionTop} to the frame bottom, OWNED by the caption node. Feed it to
+ * `assess(scene, tl, { safeAreas: [captionSafeArea(size)] })`: the caption + its
+ * children FILL the band (owner subtree-matched, no self-collision) while any other
+ * node intruding it raises CAPTION_COLLISION.
+ *
+ * The default `owner` is {@link CAPTION_NODE_ID} — the SAME id `captionNode(size)`
+ * pairs on — so the default is safe by construction. If you RENAME the caption node
+ * (`captionNode(size, …)` with a custom id via `new Text({ id })`), pass
+ * `captionSafeArea(size, { owner: '<your-id>' })` to keep the owner aligned (else the
+ * renamed caption becomes a non-owner intruding its own band — a false positive).
+ * Integer-pinned bounds (reuses {@link captionTop}; no new float math).
+ */
+declare function captionSafeArea(size: {
+  w: number;
+  h: number;
+}, opts?: {
+  owner?: string;
+}): SafeArea;
 interface DuckOptions {
   /** gain while narration speaks; default 0.25 */
   duck?: number;
@@ -375,4 +418,4 @@ declare function music(timing: MusicTiming, at?: number): MusicAnchors;
 declare function toSrt(timing: NarrationTiming): string;
 declare function toVtt(timing: NarrationTiming): string;
 //#endregion
-export { BedMode, CaptionCue, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, VoiceBlend, VoiceBlendEntry, VoiceSpec, captionNode, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };
+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 };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { key, track } from "@glissade/core";
 import { Text, breakLines, estimatingMeasurer, glow, quantize } from "@glissade/scene";
+import "@glissade/scene/diagnostics";
 //#region src/index.ts
 /**
 * @glissade/narrate — narration + captions, the PURE side. TTS happens only
@@ -155,8 +156,16 @@ function splitCaption(segment, maxChars) {
 		end: segment.start + (i + 1) * span
 	}));
 }
+/**
+* The canonical caption node id — the SINGLE source of truth `captionNode`,
+* `captionTrack`, and `captionSafeArea` all pair on. Keeping it one string means
+* `captionSafeArea(size).owner === captionNode(size).id` BY CONSTRUCTION, so a
+* caption never SELF-COLLIDES with its own reserved band (the owner + its subtree
+* are subtree-matched exempt in CAPTION_COLLISION).
+*/
+const CAPTION_NODE_ID = "captions";
 function captionTrack(timing, opts = {}) {
-	const target = opts.target ?? "captions/text";
+	const target = opts.target ?? `captions/text`;
 	const budget = timing.captionSplit?.maxChars;
 	const keys = [key(0, "", { interp: "hold" })];
 	let cursor = 0;
@@ -185,7 +194,7 @@ function captionNode(size, style = {}) {
 	const lineHeight = style.lineHeight ?? 1.3;
 	const bottomY = Math.round(size.h * (1 - inset));
 	const node = new Text({
-		id: "captions",
+		id: CAPTION_NODE_ID,
 		text: "",
 		align: "center",
 		fontSize: baseFont,
@@ -226,6 +235,47 @@ function captionNode(size, style = {}) {
 	return node;
 }
 /**
+* 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 /
+* 0.18 portrait), and the band reserves a DEFAULT (2-line) caption block above that
+* baseline down to the frame bottom, using captionNode's own font fraction /
+* lineHeight / default maxLines. ONE `Math.round` → integer-stable + deterministic;
+* landscape and portrait yield different tops (the platform-safe-area asymmetry).
+*/
+function captionTop(size) {
+	const portrait = size.h > size.w;
+	const inset = portrait ? .18 : .1;
+	const fontFrac = portrait ? .052 : .06;
+	return Math.round(size.h * (1 - inset) - Math.min(size.w, size.h) * fontFrac * 1.3 * 2);
+}
+/**
+* Build the reserved caption-band {@link SafeArea} for `critique`/`assess`'s
+* `safeAreas` from narrate's OWN caption layout — the bottom band from
+* {@link captionTop} to the frame bottom, OWNED by the caption node. Feed it to
+* `assess(scene, tl, { safeAreas: [captionSafeArea(size)] })`: the caption + its
+* children FILL the band (owner subtree-matched, no self-collision) while any other
+* node intruding it raises CAPTION_COLLISION.
+*
+* The default `owner` is {@link CAPTION_NODE_ID} — the SAME id `captionNode(size)`
+* pairs on — so the default is safe by construction. If you RENAME the caption node
+* (`captionNode(size, …)` with a custom id via `new Text({ id })`), pass
+* `captionSafeArea(size, { owner: '<your-id>' })` to keep the owner aligned (else the
+* renamed caption becomes a non-owner intruding its own band — a false positive).
+* Integer-pinned bounds (reuses {@link captionTop}; no new float math).
+*/
+function captionSafeArea(size, opts = {}) {
+	return {
+		bounds: {
+			minX: 0,
+			minY: captionTop(size),
+			maxX: size.w,
+			maxY: size.h
+		},
+		owner: opts.owner ?? "captions"
+	};
+}
+/**
 * The bed-ducking envelope every narrated video needs: duck windows are the
 * narration segments, with attack/release ramps and near-window merging. Pause
 * beats join in by their `bed` mode — `hold` (default) keeps the bed ducked
@@ -383,4 +433,4 @@ 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";
 }
 //#endregion
-export { NarrationError, captionNode, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };
+export { CAPTION_NODE_ID, NarrationError, 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.63.2",
+  "version": "0.64.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.63.2",
-    "@glissade/scene": "0.63.2"
+    "@glissade/core": "0.64.0",
+    "@glissade/scene": "0.64.0"
   },
   "peerDependencies": {
     "kokoro-js": "^1.2.0"