screenci 0.0.14 → 0.0.16

package/dist/index.d.ts

@@ -1,16 +1,16 @@
-export type { AspectRatio, FPS, Quality, Trace, RecordOptions, RenderOptions, ResolvedRenderOptions, ScreenCIConfig, ExtendedScreenCIConfig, CaptionConfig, AutoZoomOptions, Easing, PostClickMove, ClickBeforeFillOption, } from './src/types.js';
+export type { AspectRatio, FPS, Quality, Trace, RecordOptions, RenderOptions, ResolvedRenderOptions, ScreenCIConfig, ExtendedScreenCIConfig, CueConfig, AutoZoomOptions, Easing, PostClickMove, ClickBeforeFillOption, } from './src/types.js';
 export { RENDER_OPTIONS_DEFAULTS } from './src/types.js';
 export { voices, modelTypes, languageRegions, isCustomVoiceRef, } from './src/voices.js';
 export type { VoiceKey, VoiceName, VoiceForLang, CustomVoiceRef, ModelType, } from './src/voices.js';
-export type { RecordingEvent, RecordingData, ElementRect, VideoStartEvent, InputEvent, MouseMoveEvent, MouseDownEvent, MouseUpEvent, MouseShowEvent, MouseHideEvent, MouseWaitEvent, CaptionStartEvent, CaptionEndEvent, VideoCaptionStartEvent, HideStartEvent, HideEndEvent, AutoZoomStartEvent, AutoZoomEndEvent, } from './src/events.js';
+export type { RecordingEvent, RecordingData, ElementRect, VideoStartEvent, InputEvent, MouseMoveEvent, MouseDownEvent, MouseUpEvent, MouseShowEvent, MouseHideEvent, MouseWaitEvent, CueStartEvent, CueEndEvent, VideoCueStartEvent, HideStartEvent, HideEndEvent, AutoZoomStartEvent, AutoZoomEndEvent, } from './src/events.js';
 export { DEFAULT_ASPECT_RATIO, DEFAULT_FPS, DEFAULT_QUALITY, DEFAULT_TRACE, DEFAULT_SEND_TRACES, DEFAULT_VIDEO_DIR, DEFAULT_VIDEO_OPTIONS, } from './src/defaults.js';
 export { getDimensions } from './src/dimensions.js';
 export { defineConfig } from './src/config.js';
 export { video } from './src/video.js';
 export type { ScreenCIPage, ScreenCILocator } from './src/types.js';
-export { createVoiceOvers, createVideoCaptions } from './src/caption.js';
-export type { CaptionController, Captions, VideoCaptionEntry, VideoCaptions, TopLevelVoiceConfig, LangVoiceOverride, CaptionMapValue, } from './src/caption.js';
-export type { CaptionTranslation, VideoCaptionTranslation, VideoCaptionTranslationFile, VoiceLanguageMeta, } from './src/events.js';
+export { createNarration, createVideoCues } from './src/cue.js';
+export type { CueController, Cues, VideoCueEntry, VideoCues, TopLevelVoiceConfig, LangNarrationOverride, CueMapValue, } from './src/cue.js';
+export type { CueTranslation, VideoCueTranslation, VideoCueTranslationFile, VoiceLanguageMeta, } from './src/events.js';
 export { hide } from './src/hide.js';
 export { autoZoom } from './src/autoZoom.js';
 export { createAssets } from './src/asset.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,GAAG,EACH,OAAO,EACP,KAAK,EACL,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,MAAM,EACN,aAAa,EACb,qBAAqB,GACtB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAGxD,OAAO,EACL,MAAM,EACN,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAA;AAGxB,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,eAAe,EACf,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,GAChB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,GAClB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,GAAG,EACH,OAAO,EACP,KAAK,EACL,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,SAAS,EACT,eAAe,EACf,MAAM,EACN,aAAa,EACb,qBAAqB,GACtB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAGxD,OAAO,EACL,MAAM,EACN,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAA;AAGxB,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,eAAe,EACf,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC/D,YAAY,EACV,aAAa,EACb,IAAI,EACJ,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,qBAAqB,EACrB,WAAW,GACZ,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -7,9 +7,9 @@ export { DEFAULT_ASPECT_RATIO, DEFAULT_FPS, DEFAULT_QUALITY, DEFAULT_TRACE, DEFA
 export { getDimensions } from './src/dimensions.js';
 // Re-export config function
 export { defineConfig } from './src/config.js';
-// Re-export video fixture and caption
+// Re-export video fixture and cue
 export { video } from './src/video.js';
-export { createVoiceOvers, createVideoCaptions } from './src/caption.js';
+export { createNarration, createVideoCues } from './src/cue.js';
 export { hide } from './src/hide.js';
 export { autoZoom } from './src/autoZoom.js';
 export { createAssets } from './src/asset.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAExD,mBAAmB;AACnB,OAAO,EACL,MAAM,EACN,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AA+BxB,2BAA2B;AAC3B,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6BAA6B;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,4BAA4B;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,sCAAsC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAgBxE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAExD,mBAAmB;AACnB,OAAO,EACL,MAAM,EACN,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AA+BxB,2BAA2B;AAC3B,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6BAA6B;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,4BAA4B;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,kCAAkC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAgB/D,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/src/browserLaunchOptions.d.ts

@@ -0,0 +1,5 @@
+export declare function getChromiumLaunchOptions(shouldRecord: boolean): {
+    headless: false;
+    args: string[];
+} | undefined;
+//# sourceMappingURL=browserLaunchOptions.d.ts.map

package/dist/src/browserLaunchOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserLaunchOptions.d.ts","sourceRoot":"","sources":["../../src/browserLaunchOptions.ts"],"names":[],"mappings":"AAcA,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,OAAO,GAC1D;IACE,QAAQ,EAAE,KAAK,CAAA;IACf,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,GACD,SAAS,CASZ"}

package/dist/src/browserLaunchOptions.js

@@ -0,0 +1,23 @@
+const RECORDING_CHROMIUM_ARGS = [
+    '--window-position=0,0',
+    '--kiosk',
+    '--disable-translate',
+    '--disable-spell-checking',
+    '--disable-notifications', // no permission popups
+    '--disable-save-password-bubble', // no "save password?" dialog
+    '--deny-permission-prompts',
+    '--disable-save-password-bubble', // no "save password?" dialog
+    '--disable-infobars', // no "Chrome is being controlled by..." bar
+    '--no-first-run', // skip first-run UI
+    '--hide-scrollbars', // scrollbars invisible in recordings
+];
+export function getChromiumLaunchOptions(shouldRecord) {
+    if (!shouldRecord) {
+        return undefined;
+    }
+    return {
+        headless: false,
+        args: [...RECORDING_CHROMIUM_ARGS],
+    };
+}
+//# sourceMappingURL=browserLaunchOptions.js.map

package/dist/src/browserLaunchOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserLaunchOptions.js","sourceRoot":"","sources":["../../src/browserLaunchOptions.ts"],"names":[],"mappings":"AAAA,MAAM,uBAAuB,GAAG;IAC9B,uBAAuB;IACvB,SAAS;IACT,qBAAqB;IACrB,0BAA0B;IAC1B,yBAAyB,EAAE,uBAAuB;IAClD,gCAAgC,EAAE,6BAA6B;IAC/D,2BAA2B;IAC3B,gCAAgC,EAAE,6BAA6B;IAC/D,oBAAoB,EAAE,4CAA4C;IAClE,gBAAgB,EAAE,oBAAoB;IACtC,mBAAmB,EAAE,qCAAqC;CAClD,CAAA;AAEV,MAAM,UAAU,wBAAwB,CAAC,YAAqB;IAM5D,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,CAAC,GAAG,uBAAuB,CAAC;KACnC,CAAA;AACH,CAAC"}

package/dist/src/cue.d.ts

@@ -0,0 +1,276 @@
+import type { IEventRecorder } from './events.js';
+import type { VoiceKey, VoiceForLang, Lang, CustomVoiceRef, ModelType } from './voices.js';
+export declare const ONE_FRAME_MS: number;
+export declare function setSleepFn(fn: (ms: number) => void): void;
+export declare function setActiveCueRecorder(recorder: IEventRecorder | null): void;
+export declare function resetCueChain(): void;
+export declare function resetRegisteredCustomVoiceRefs(): void;
+export declare function validateCustomVoiceRefs(testFilePath: string): Promise<void>;
+/**
+ * A narration controller. Awaiting it starts the narration segment.
+ *
+ * @example
+ * ```ts
+ * await narration.intro
+ * await page.goto('/dashboard')
+ * await narration.nextStep
+ * ```
+ */
+export type CueController = PromiseLike<void>;
+type NarrationCueObject = {
+    text: string;
+} | {
+    media: string;
+    subtitle?: string;
+} | {
+    path: string;
+    subtitle?: string;
+};
+/** A single narration cue value in a multi-language map. */
+export type CueMapValue = string | NarrationCueObject;
+export type Cues<T extends Record<string, CueMapValue>> = {
+    [K in keyof T]: CueController;
+} & {
+    /**
+     * Waits for the current narration segment to finish before the next action.
+     *
+     * Only needed when an action must happen _after_ narration ends.
+     * Consecutive `await narration.x` calls sequence automatically — each
+     * one ends the previous before starting.
+     *
+     * @example
+     * ```ts
+     * await narration.intro
+     * await narration.wait() // wait for intro audio to finish
+     * await page.click('#next')  // click happens after intro ends
+     * ```
+     */
+    wait(): Promise<void>;
+};
+export type VideoCueEntry = string | {
+    path: string;
+    subtitle?: string;
+};
+export type VideoCues<T extends Record<string, VideoCueEntry>> = {
+    [K in keyof T]: CueController;
+} & {
+    /**
+     * Waits for the current narration segment to finish before the next action.
+     * @see {@link Cues.wait}
+     */
+    wait(): Promise<void>;
+};
+/**
+ * Top-level voice configuration shared across all languages.
+ * `seed` is not allowed here — use per-language `voice` overrides instead.
+ *
+ * Use `style` for expressive synthesis, or `modelType` for an explicit
+ * model choice. `style` and `modelType` are mutually exclusive.
+ */
+export type TopLevelVoiceConfig = {
+    name: VoiceKey | CustomVoiceRef;
+    /** Speaking style prompt for expressive synthesis. Implies `expressive` model type. */
+    style: string;
+    /** Can be omitted when `style` is set — `expressive` is implied. */
+    modelType?: 'expressive';
+    /**
+     * Accent description for expressive synthesis.
+     * The more specific, the better — e.g. `'Southern American English'` or `'Received Pronunciation British'`.
+     * Omitted from the prompt when not set — the voice uses its natural default.
+     */
+    accent?: string;
+    /**
+     * Pacing description for expressive synthesis.
+     * Describes the overall speed and tempo — e.g. `'Measured and deliberate'` or `'Brisk and energetic'`.
+     */
+    pacing?: string;
+} | {
+    name: VoiceKey | CustomVoiceRef;
+    style?: never;
+    accent?: never;
+    pacing?: never;
+    /** TTS model type — `modelTypes.expressive` or `modelTypes.consistent`. Defaults to `consistent`. */
+    modelType?: ModelType;
+};
+/**
+ * Per-language narration override. Can override the top-level voice name and
+ * optionally set a `seed` for TTS generation.
+ *
+ * Use `style` for expressive synthesis, or `modelType` for an explicit
+ * model choice. `style` and `modelType` are mutually exclusive.
+ */
+export type LangNarrationOverride = {
+    name: VoiceKey | CustomVoiceRef;
+    /**
+     * Integer seed included in the audio cache key. A different seed always forces
+     * regeneration. Consistent output is not guaranteed across all voice types.
+     */
+    seed?: number;
+    /** Speaking style prompt for expressive synthesis. Implies `expressive` model type. */
+    style: string;
+    /** Can be omitted when `style` is set — `expressive` is implied. */
+    modelType?: 'expressive';
+    /**
+     * Accent description for expressive synthesis.
+     * The more specific, the better — e.g. `'Southern American English'` or `'Received Pronunciation British'`.
+     * Omitted from the prompt when not set — the voice uses its natural default.
+     */
+    accent?: string;
+    /**
+     * Pacing description for expressive synthesis.
+     * Describes the overall speed and tempo — e.g. `'Measured and deliberate'` or `'Brisk and energetic'`.
+     */
+    pacing?: string;
+} | {
+    name: VoiceKey | CustomVoiceRef;
+    /**
+     * Integer seed included in the audio cache key. A different seed always forces
+     * regeneration. Consistent output is not guaranteed across all voice types.
+     */
+    seed?: number;
+    style?: never;
+    accent?: never;
+    pacing?: never;
+    /** TTS model type — `modelTypes.expressive` or `modelTypes.consistent`. Defaults to `consistent`. */
+    modelType?: ModelType;
+};
+/** Converts a union type to an intersection: `A | B` → `A & B` */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Produces a record requiring every key that appears in any language's cues.
+ * Uses each language's key set with CueMapValue values before intersecting,
+ * so value types don't conflict (e.g. string vs { path, subtitle } for the same key).
+ */
+type LanguageEntryBase = {
+    voice?: LangNarrationOverride;
+    region?: string;
+};
+type LanguageCuesEntry<C extends Record<string, CueMapValue>> = LanguageEntryBase & {
+    cues: C;
+};
+type AllCues<M extends Partial<Record<Lang, LanguageCuesEntry<Record<string, CueMapValue>>>>> = UnionToIntersection<{
+    [L in keyof M]: M[L] extends {
+        cues: infer C;
+    } ? Record<keyof C & string, CueMapValue> : never;
+}[keyof M]> & Record<string, CueMapValue>;
+type LangNarrationOverrideForLang<L extends string> = {
+    name: (L extends Lang ? VoiceForLang<L> : VoiceKey) | CustomVoiceRef;
+    seed?: number;
+    style: string;
+    modelType?: 'expressive';
+    accent?: string;
+    pacing?: string;
+} | {
+    name: (L extends Lang ? VoiceForLang<L> : VoiceKey) | CustomVoiceRef;
+    seed?: number;
+    style?: never;
+    accent?: never;
+    pacing?: never;
+    modelType?: ModelType;
+};
+type LanguagesMap<M extends Partial<Record<Lang, LanguageCuesEntry<Record<string, CueMapValue>>>>> = M & {
+    [L in keyof M]: {
+        voice?: L extends string ? LangNarrationOverrideForLang<L> : never;
+        /** BCP-47 region code for TTS synthesis, e.g. `languageRegions.en.US`. */
+        region?: string;
+    } & {
+        cues: AllCues<M>;
+    };
+};
+/**
+ * Creates a set of typed narration controllers, one per key in the map.
+ *
+ * Each controller has `start()` and `end()`.
+ * At render time screenci generates narration, and syncs the audio to the
+ * recording. You write text; the voice is handled for you.
+ *
+ * The top-level `voice` applies to all languages. Override it per-language via
+ * the `voice` field inside each language entry. Only language-level overrides
+ * may set `seed`.
+ *
+ * TypeScript enforces that every language has the same cue keys.
+ * Forget a translation key → compile error.
+ *
+ * @example
+ * ```ts
+ * const narration = createNarration({
+ *   voice: { name: voices.Ava, style: 'Clear and friendly' },
+ *   languages: {
+ *     en: { cues: { intro: 'Welcome.', next: 'Click here.' } },
+ *     fi: {
+ *       voice: { name: voices.Nora, style: 'Selkeä opastus', seed: 42 },
+ *       cues: { intro: 'Tervetuloa.', next: 'Napsauta tästä.' },
+ *     },
+ *   },
+ * })
+ *
+ * // Await a narration segment directly to start it:
+ * await narration.intro
+ * await page.goto('/dashboard')
+ *
+ * // Consecutive narration segments sequence automatically:
+ * await narration.intro
+ * await narration.next  // ends intro, then starts next
+ *
+ * // Wait for audio to finish before an action:
+ * await narration.intro
+ * await narration.wait()
+ * await page.click('#start')
+ * ```
+ */
+export declare function createNarration<M extends Partial<Record<Lang, LanguageCuesEntry<Record<string, CueMapValue>>>>>(input: {
+    voice: TopLevelVoiceConfig;
+    languages: LanguagesMap<M>;
+}): Cues<AllCues<M>>;
+type RequireAllSameVideoKeys<M extends Partial<Record<Lang, {
+    cues: Record<string, VideoCueEntry>;
+}>>> = {
+    [L in keyof M]: {
+        cues: UnionToIntersection<M[keyof M] extends {
+            cues: infer C;
+        } ? C : never>;
+    };
+};
+/**
+ * Creates cue controllers backed by pre-recorded asset files instead of
+ * TTS-generated audio. Each entry maps a name to either an asset path string
+ * or an object with `assetPath` and an optional `subtitle` text.
+ *
+ * At render time the asset file is used directly as narration audio.
+ * If `subtitle` is provided, words are spread with equal timing across the
+ * audio duration (no word-level TTS data available).
+ *
+ * Same constraints as `createNarration`: cannot overlap with other cues,
+ * and cannot fall inside input events.
+ *
+ * Two overloads:
+ *
+ * **1. Single-language:**
+ * ```ts
+ * const cues = createVideoCues({
+ *   intro: '/assets/intro.mp3',
+ *   demo: { assetPath: '/assets/demo.mp3', subtitle: 'Watch the demo.' },
+ * })
+ * ```
+ *
+ * **2. Multi-language (type-safe):**
+ * TypeScript enforces that every language has the same cue keys.
+ * ```ts
+ * const cues = createVideoCues({
+ *   en: { cues: { intro: '/assets/en/intro.mp3' } },
+ *   fi: { cues: { intro: '/assets/fi/intro.mp3' } },
+ * })
+ * ```
+ */
+export declare function createVideoCues<T extends Record<string, VideoCueEntry>>(cuesMap: T): VideoCues<T>;
+export declare function createVideoCues<L extends Lang, T extends Record<string, VideoCueEntry>>(languagesMap: {
+    [K in L]: {
+        cues: T;
+    };
+} & RequireAllSameVideoKeys<{
+    [K in L]: {
+        cues: Record<string, VideoCueEntry>;
+    };
+}>): VideoCues<T & Record<string, VideoCueEntry>>;
+export {};
+//# sourceMappingURL=cue.d.ts.map

package/dist/src/cue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cue.d.ts","sourceRoot":"","sources":["../../src/cue.ts"],"names":[],"mappings":"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"}