@glissade/narrate 0.34.0 → 0.35.0-pre.1

package/dist/index.d.ts

@@ -198,6 +198,17 @@ interface NarrationAnchors {
   duration(id: string): number;
   /** start + offset — a sub-beat inside a segment or pause window */
   at(id: string, offset?: number): number;
+  /**
+   * The absolute start (seconds) of a WORD inside a segment — the provider's
+   * per-word timestamp (`words[]` in the timing manifest), so a visual can land
+   * ON the spoken word instead of a whole segment early/late. `nth` (0-based)
+   * disambiguates a repeated word. Throws if the segment has no word timings
+   * (the provider didn't supply them) or the word/occurrence isn't found —
+   * fail-loud, so a stale ref can't silently drift to segment.start.
+   */
+  word(segId: string, word: string, nth?: number): number;
+  /** Like `word` but the word's END second (its `end` timestamp). */
+  wordEnd(segId: string, word: string, nth?: number): number;
   /**
    * Assert every id exists in the manifest — a build-time fast-fail that lists
    * ALL unknown ids at once (vs. discovering stale refs one render at a time

package/dist/index.js

@@ -28,7 +28,8 @@ function narration(timing) {
 		if (byId.has(s.id)) throw new NarrationError(`duplicate narration id '${s.id}'`);
 		byId.set(s.id, {
 			start: s.start,
-			duration: s.duration
+			duration: s.duration,
+			...s.words ? { words: s.words } : {}
 		});
 	}
 	for (const p of timing.pauses ?? []) {
@@ -43,11 +44,26 @@ function narration(timing) {
 		if (!b) throw new NarrationError(`no narration beat '${id}' (have: ${[...byId.keys()].join(", ")})`);
 		return b;
 	};
+	/** locate the nth (0-based) occurrence of `word` in a segment's word timings,
+	*  matching on a punctuation/case-normalized token so 'busy' finds 'busy.' */
+	const findWord = (segId, word, nth) => {
+		const b = beat(segId);
+		if (!b.words || b.words.length === 0) throw new NarrationError(`narration beat '${segId}' has no word timings (the provider supplied none) — use .at('${segId}', offset) instead`);
+		const norm = (w) => w.toLowerCase().replace(/[^\p{L}\p{N}']/gu, "");
+		const target = norm(word);
+		const matches = b.words.filter((w) => norm(w.word) === target);
+		if (matches.length === 0) throw new NarrationError(`narration word '${word}' not found in beat '${segId}' (words: ${b.words.map((w) => w.word).join(" ")})`);
+		const hit = matches[nth];
+		if (hit === void 0) throw new NarrationError(`narration word '${word}' occurrence ${nth} not found in beat '${segId}' (only ${matches.length} occurrence${matches.length > 1 ? "s" : ""})`);
+		return hit;
+	};
 	const anchors = {
 		start: (id) => beat(id).start,
 		end: (id) => beat(id).start + beat(id).duration,
 		duration: (id) => beat(id).duration,
 		at: (id, offset = 0) => beat(id).start + offset,
+		word: (segId, w, nth = 0) => findWord(segId, w, nth).start,
+		wordEnd: (segId, w, nth = 0) => findWord(segId, w, nth).end,
 		require: (ids) => {
 			const missing = ids.filter((id) => !byId.has(id));
 			if (missing.length > 0) throw new NarrationError(`narration references unknown id${missing.length > 1 ? "s" : ""} ${missing.map((m) => `'${m}'`).join(", ")} — have: ${[...byId.keys()].join(", ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.34.0",
+  "version": "0.35.0-pre.1",
   "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.34.0",
-    "@glissade/scene": "0.34.0"
+    "@glissade/core": "0.35.0-pre.1",
+    "@glissade/scene": "0.35.0-pre.1"
   },
   "peerDependencies": {
     "kokoro-js": "^1.2.0"