screenci 0.0.71 → 0.0.73

package/dist/src/builder.js

@@ -0,0 +1,212 @@
+import { fileURLToPath } from 'node:url';
+import { resolveLocaleForLanguage } from './locales.js';
+import { parseRequestedLanguages } from './runtimeMode.js';
+import { logger } from './logger.js';
+import { normalizeLocalizeSpec, } from './localize.js';
+import { validateStudioDeclaration } from './studio.js';
+function variantVideoName(baseTitle, variant) {
+    return variant === null ? baseTitle : `${baseTitle} ${variant.key}`;
+}
+/**
+ * Expand the localize / each fan-out specs into the concrete list of Playwright
+ * tests to register. Pure and exported for testing.
+ *
+ * - With no `localize`, each variant yields a single language-agnostic test.
+ * - In `'shared'` mode, each variant yields one test that carries every language
+ *   (narration is overdubbed at render); the `--languages` filter does not split
+ *   a shared recording.
+ * - In `'per-language'` mode, each variant yields one test per language,
+ *   intersected with the `--languages` filter when present. A variant whose
+ *   languages are entirely filtered out yields nothing. The browser locale is set
+ *   per language unless `browserLocale` is `false`.
+ */
+export function expandRegistrations(params) {
+    const { baseTitle, localize, studio, eachVariants, requestedLanguages } = params;
+    const variants = eachVariants ?? [null];
+    const registrations = [];
+    for (const variant of variants) {
+        const videoName = variantVideoName(baseTitle, variant);
+        const recordOptions = variant?.recordOptions ?? null;
+        const use = variant?.use ?? null;
+        const variantLabel = variant === null ? '' : `${variant.key} `;
+        if (localize === null) {
+            registrations.push({
+                describeTitle: variant?.key ?? baseTitle,
+                leafTitle: videoName,
+                videoName,
+                language: null,
+                locale: null,
+                recordOptions,
+                use,
+                localize: null,
+                studio,
+            });
+            continue;
+        }
+        if (localize.mode === 'shared') {
+            registrations.push({
+                describeTitle: `${variantLabel}shared`.trim(),
+                leafTitle: videoName,
+                videoName,
+                language: null,
+                locale: null,
+                recordOptions,
+                use,
+                localize,
+                studio,
+            });
+            continue;
+        }
+        const languages = requestedLanguages === null
+            ? localize.languages
+            : localize.languages.filter((lang) => requestedLanguages.includes(lang));
+        for (const lang of languages) {
+            registrations.push({
+                describeTitle: `${variantLabel}${lang}`,
+                leafTitle: `${videoName} [${lang}]`,
+                videoName,
+                language: lang,
+                locale: localize.browserLocale
+                    ? resolveLocaleForLanguage(lang, localize.locales)
+                    : null,
+                recordOptions,
+                use,
+                localize,
+                studio,
+            });
+        }
+    }
+    return registrations;
+}
+/** Internal option keys the page/context fixtures read off a registered test. */
+const SCREENCI_LANGUAGE_OPTION = '_screenciLanguage';
+const SCREENCI_VIDEO_NAME_OPTION = '_screenciVideoName';
+const SCREENCI_LOCALIZE_OPTION = '_screenciLocalize';
+const SCREENCI_STUDIO_OPTION = '_screenciStudio';
+const SCREENCI_SOURCE_FILE_OPTION = '_screenciSourceFile';
+/** Absolute path of this module, used to skip our own frames when capturing. */
+const BUILDER_MODULE_PATH = fileURLToPath(import.meta.url);
+/** Normalize a V8 call-site filename (which may be a `file://` URL) to a path. */
+function callSiteFile(frame) {
+    const fileName = frame.getFileName();
+    if (!fileName)
+        return null;
+    return fileName.startsWith('file://') ? fileURLToPath(fileName) : fileName;
+}
+/**
+ * Capture the source file of the user's `.screenci` script that called the
+ * builder. Playwright attributes `testInfo.file` to this module (the test is
+ * registered here, not in the user's file), so asset paths authored relative to
+ * the script would otherwise resolve against this package. We walk the call
+ * stack and return the first frame outside this module, which is the script.
+ * Returns `null` if no such frame is found (fixtures then fall back to
+ * `testInfo.file`).
+ */
+function captureSourceFile() {
+    const originalPrepare = Error.prepareStackTrace;
+    const originalLimit = Error.stackTraceLimit;
+    try {
+        Error.stackTraceLimit = 50;
+        Error.prepareStackTrace = (_error, stack) => stack;
+        const stack = new Error().stack;
+        if (!Array.isArray(stack))
+            return null;
+        for (const frame of stack) {
+            const file = callSiteFile(frame);
+            if (file !== null && file !== BUILDER_MODULE_PATH) {
+                return file;
+            }
+        }
+        return null;
+    }
+    finally {
+        Error.prepareStackTrace = originalPrepare;
+        Error.stackTraceLimit = originalLimit;
+    }
+}
+function registerOne(test, reg, details, body, modifier, sourceFile) {
+    const useOptions = {
+        ...(reg.use ?? {}),
+        ...(reg.recordOptions !== null ? { recordOptions: reg.recordOptions } : {}),
+        ...(reg.locale !== null ? { locale: reg.locale } : {}),
+        [SCREENCI_LANGUAGE_OPTION]: reg.language ?? undefined,
+        [SCREENCI_VIDEO_NAME_OPTION]: reg.videoName,
+        [SCREENCI_LOCALIZE_OPTION]: reg.localize ?? undefined,
+        [SCREENCI_STUDIO_OPTION]: reg.studio ?? undefined,
+        [SCREENCI_SOURCE_FILE_OPTION]: sourceFile ?? undefined,
+    };
+    const register = modifier ? test[modifier] : test;
+    test.describe(reg.describeTitle, () => {
+        test.use(useOptions);
+        if (details !== undefined) {
+            register(reg.leafTitle, details, body);
+        }
+        else {
+            register(reg.leafTitle, body);
+        }
+    });
+}
+function normalizeVariants(variants) {
+    if (variants.length === 0) {
+        throw new Error('video.each() requires at least one variant, e.g. .each([{ key: "mobile" }]).');
+    }
+    const seen = new Set();
+    for (const variant of variants) {
+        if (seen.has(variant.key)) {
+            throw new Error(`Duplicate video.each() variant key "${variant.key}". Variant keys must be unique.`);
+        }
+        seen.add(variant.key);
+    }
+    return variants;
+}
+/**
+ * Create a fan-out builder bound to a registrar test instance. `video.localize`
+ * and `video.each` are the `localize`/`each` methods of a root builder created
+ * with this factory. `Args` is the medium's fixture arg type (video/screenshot).
+ */
+export function createVideoBuilder(test, state = { localize: null, studio: null, eachVariants: null }) {
+    const runTerminal = (modifier, title, detailsOrBody, maybeBody) => {
+        const hasDetails = typeof detailsOrBody !== 'function';
+        const details = hasDetails ? detailsOrBody : undefined;
+        const body = (hasDetails ? maybeBody : detailsOrBody);
+        // Captured here, at the user's call site, so the script's path survives
+        // even though Playwright records the test as declared in this module.
+        const sourceFile = captureSourceFile();
+        // Studio-managed names must be unique and disjoint from the seeded localize
+        // names. Validate once, here, where both the localize spec and the studio
+        // declaration are known (they can be chained in either order).
+        validateStudioDeclaration(state.studio, state.localize?.narration?.seededNames ?? [], state.localize?.text?.seededNames ?? []);
+        const registrations = expandRegistrations({
+            baseTitle: title,
+            localize: state.localize,
+            studio: state.studio,
+            eachVariants: state.eachVariants,
+            requestedLanguages: parseRequestedLanguages(),
+        });
+        if (registrations.length === 0) {
+            logger.warn(`[screenci] "${title}" was skipped: none of its declared languages match the --languages filter.`);
+            return;
+        }
+        for (const reg of registrations) {
+            registerOne(test, reg, details, body, modifier, sourceFile);
+        }
+    };
+    const callable = ((title, detailsOrBody, maybeBody) => runTerminal(undefined, title, detailsOrBody, maybeBody));
+    for (const modifier of ['only', 'skip', 'fixme', 'fail']) {
+        callable[modifier] = ((title, detailsOrBody, maybeBody) => runTerminal(modifier, title, detailsOrBody, maybeBody));
+    }
+    callable.localize = ((spec) => createVideoBuilder(test, {
+        ...state,
+        localize: normalizeLocalizeSpec(spec),
+    }));
+    callable.studio = ((declaration) => createVideoBuilder(test, {
+        ...state,
+        studio: declaration,
+    }));
+    callable.each = (variants) => createVideoBuilder(test, {
+        ...state,
+        eachVariants: normalizeVariants(variants),
+    });
+    return callable;
+}
+//# sourceMappingURL=builder.js.map

package/dist/src/builder.js.map

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

package/dist/src/config.d.ts

@@ -19,7 +19,7 @@ import type { ScreenCIConfig, ExtendedScreenCIConfig } from './types.js';
  *
  * export default defineConfig({
  *   projectName: 'my-project',
- *   videoDir: './videos',
+ *   recordingDir: './recordings',
  *   use: {
  *     baseURL: 'https://app.example.com',
  *     recordOptions: {

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AASxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CA8H3E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AASxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAuI3E"}

package/dist/src/config.js

@@ -1,4 +1,4 @@
-import { DEFAULT_VIDEO_DIR, DEFAULT_RECORD_UPLOAD_POLICY, DEFAULT_TIMEOUT, DEFAULT_ACTION_TIMEOUT, DEFAULT_NAVIGATION_TIMEOUT, } from './defaults.js';
+import { DEFAULT_RECORDING_DIR, DEFAULT_RECORD_UPLOAD_POLICY, DEFAULT_TIMEOUT, DEFAULT_ACTION_TIMEOUT, DEFAULT_NAVIGATION_TIMEOUT, } from './defaults.js';
 /**
  * Defines a screenci configuration file.
  *
@@ -19,7 +19,7 @@ import { DEFAULT_VIDEO_DIR, DEFAULT_RECORD_UPLOAD_POLICY, DEFAULT_TIMEOUT, DEFAU
  *
  * export default defineConfig({
  *   projectName: 'my-project',
- *   videoDir: './videos',
+ *   recordingDir: './recordings',
  *   use: {
  *     baseURL: 'https://app.example.com',
  *     recordOptions: {
@@ -76,8 +76,14 @@ export function defineConfig(config) {
     if (Object.prototype.hasOwnProperty.call(config, 'testDir') &&
         config.testDir !== undefined) {
         throw new Error('screenci does not support "testDir" option. ' +
-            'Use "videoDir" instead to specify the directory containing your *.screenci.* files. ' +
-            'Defaults to "./videos".');
+            'Use "recordingDir" instead to specify the directory containing your *.screenci.* files. ' +
+            'Defaults to "./recordings".');
+    }
+    // Runtime check for the renamed videoDir option
+    if ('videoDir' in config) {
+        throw new Error('screenci renamed "videoDir" to "recordingDir". ' +
+            'Rename the option in your config to specify the directory containing your *.screenci.* files. ' +
+            'Defaults to "./recordings".');
     }
     // Runtime check for testMatch
     if ('testMatch' in config) {
@@ -90,7 +96,7 @@ export function defineConfig(config) {
             'Tests must succeed immediately or fail to ensure proper video recording. ' +
             'screenci automatically sets retries to 0.');
     }
-    const { videoDir, record, test, ...rest } = config;
+    const { recordingDir, record, test, ...rest } = config;
     const reporter = rest.reporter !== undefined ? normalizeReporter(rest.reporter) : undefined;
     // recording does not need tracing, also it takes resources so that is why forced off
     const trace = isRecording ? 'off' : rest.use?.trace;
@@ -109,9 +115,9 @@ export function defineConfig(config) {
         actionTimeout: rest.use?.actionTimeout ?? DEFAULT_ACTION_TIMEOUT,
         navigationTimeout: rest.use?.navigationTimeout ?? DEFAULT_NAVIGATION_TIMEOUT,
     };
-    // Map videoDir to testDir and keep screenci-managed defaults in place.
+    // Map recordingDir to testDir and keep screenci-managed defaults in place.
     return {
-        testDir: videoDir ?? DEFAULT_VIDEO_DIR,
+        testDir: recordingDir ?? DEFAULT_RECORDING_DIR,
         testMatch: [
             '**/*.screenci.?(c|m)[jt]s?(x)',
             // Deprecated alias kept only for backward compatibility: legacy

package/dist/src/config.js.map

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

package/dist/src/cue.d.ts

@@ -1,5 +1,8 @@
-import type { IEventRecorder } from './events.js';
-import { type ModelVoiceKey, type ElevenLabsVoiceKey, type Lang, type CustomVoiceRef, type ModelType } from './voices.js';
+import type { IEventRecorder, VoiceLanguageMeta } from './events.js';
+import { type VoiceKey, type Lang, type CustomVoiceRef } from './voices.js';
+import type { TopLevelVoiceConfig, LangNarrationOverride } from './voiceConfig.js';
+export type { TopLevelVoiceConfig, LangNarrationOverride };
+import type { NormalizedNarration } from './localize.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;
@@ -50,107 +53,6 @@ export type CueMapValue = string | NarrationCueObject;
 export type Cues<T extends Record<string, CueMapValue>> = {
     [K in keyof T]: NarrationCue;
 };
-/**
- * Top-level voice configuration shared across all languages.
- * `seed` is not allowed here — use per-language `voice` overrides instead.
- *
- * Built-in model voices support expressive/consistent model controls.
- * ElevenLabs voices support only the numeric settings documented below.
- */
-type ElevenLabsVoiceSettings = {
-    /** Voice stability for ElevenLabs `eleven_multilingual_v2`. Valid range: 0 to 1. */
-    stability?: number;
-    /** Similarity enhancement for ElevenLabs `eleven_multilingual_v2`. Valid range: 0 to 1. */
-    similarityBoost?: number;
-    /** Style exaggeration for ElevenLabs `eleven_multilingual_v2`. Valid range: 0 to 1. */
-    style?: number;
-    /** Playback speed for ElevenLabs `eleven_multilingual_v2`. Valid range: 0.7 to 1.2. */
-    speed?: number;
-    /** Enables ElevenLabs speaker boost. Defaults to `true`. */
-    useSpeakerBoost?: boolean;
-};
-type ElevenLabsVoiceConfig = ElevenLabsVoiceSettings & {
-    name: ElevenLabsVoiceKey | CustomVoiceRef;
-    modelType?: never;
-    accent?: never;
-    pacing?: never;
-};
-export type TopLevelVoiceConfig = ElevenLabsVoiceConfig | {
-    name: ModelVoiceKey;
-    /** Speaking style prompt for expressive synthesis. Business tier only. Implies `expressive` model type. */
-    style: string;
-    /** Can be omitted when `style` is set — `expressive` is implied. Business tier only. */
-    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: ModelVoiceKey;
-    style?: never;
-    accent?: never;
-    /** Speaking rate for consistent synthesis. Valid range: 0.25 to 2. */
-    pacing?: number;
-    /** TTS model type — `modelTypes.expressive` or `modelTypes.consistent`. Defaults to `consistent`. */
-    modelType?: Exclude<ModelType, 'expressive'> | undefined;
-};
-/**
- * Per-language narration override. Can override the top-level voice name and
- * optionally set a `seed` for TTS generation.
- *
- * The voice name discriminates provider-specific settings: built-in model
- * voices use expressive/consistent controls, while ElevenLabs voices use the
- * numeric `eleven_multilingual_v2` controls.
- */
-export type LangNarrationOverride = (ElevenLabsVoiceConfig & {
-    /**
-     * Integer seed included in the audio cache key and forwarded to ElevenLabs.
-     * A different seed always forces regeneration.
-     */
-    seed?: number;
-}) | {
-    name: ModelVoiceKey;
-    /**
-     * 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. Business tier only. Implies `expressive` model type. */
-    style: string;
-    /** Can be omitted when `style` is set — `expressive` is implied. Business tier only. */
-    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: ModelVoiceKey;
-    /**
-     * 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;
-    /** Speaking rate for consistent synthesis. Valid range: 0.25 to 2. */
-    pacing?: number;
-    /** TTS model type — `modelTypes.expressive` or `modelTypes.consistent`. Defaults to `consistent`. */
-    modelType?: Exclude<ModelType, 'expressive'> | undefined;
-};
 /** 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;
 /**
@@ -220,27 +122,42 @@ type NarrationInput<M extends Partial<Record<Lang, NarrationLanguageInput>>> = {
  */
 export declare function createNarration<M extends Partial<Record<Lang, NarrationLanguageInput>>>(input: NarrationInput<M>): Cues<AllCues<M>>;
 /**
- * Creates typed narration controllers whose text and voice are configured on
- * the ScreenCI Studio page instead of in code. Business tier only.
- *
- * Each key becomes a cue with the same behavior as {@link createNarration}
- * cues — callable, with explicit `start()` and `end()` methods. Languages,
- * narration text, and voice settings all come from Studio.
- *
- * On the first upload of a studio-mode video, rendering is held until the
- * video is configured in Studio (the CLI prints a direct link). Later uploads
- * reuse the saved Studio configuration automatically.
+ * Asserts that a narration input's language keys match a video's declared
+ * languages exactly. Used by the `narration` fixture so the languages declared
+ * via `video.languages([...])` stay the single source of truth: a missing or
+ * unexpected language fails loudly instead of silently drifting.
+ */
+export declare function assertNarrationLanguagesMatch(input: Record<string, unknown>, declared: readonly string[]): void;
+/**
+ * Builds narration controllers for Studio-managed cues declared via
+ * `video.studio({ narration: [...] })`. Their text and voice are configured on
+ * the ScreenCI Studio page instead of in code. Each name becomes a cue with the
+ * same behavior as a seeded narration cue (callable, with `start()`/`end()`);
+ * languages, narration text, and voice all come from Studio.
  *
- * @example
- * ```ts
- * const narration = createStudioNarration('intro', 'checkout', 'outro')
+ * Internal: the `narration` fixture merges these with the seeded localize cues.
+ */
+export declare function buildStudioNarrationCues(names: readonly string[]): Record<string, NarrationCue>;
+/**
+ * Resolve a single voice config into its recorded name and language metadata.
+ * Unlike {@link buildCuesFromInput}, the config here is already fully resolved by
+ * the localize voice cascade, so there is no top-level/override merge: every
+ * provider setting comes from this one config.
+ */
+export declare function resolveVoiceMeta(config: TopLevelVoiceConfig | LangNarrationOverride): {
+    name: VoiceKey | CustomVoiceRef;
+    meta: VoiceLanguageMeta;
+};
+/**
+ * Build the narration cue controllers for a localized recording, directly from
+ * the normalized localize spec. Per-cue voice can override the per-language
+ * (`voiceByLang`) and config/global (`defaultVoice`) voices, so the cascade is
+ * resolved per `(cue, language)` here rather than routed through
+ * {@link buildCuesFromInput} (which is per-language only).
  *
- * await narration.intro()
- * await page.goto('/checkout')
- * await narration.checkout.start()
- * await narration.checkout.end()
- * ```
+ * Seeded cues emit translations carrying the resolved voice + spoken text (the
+ * recorder filters to the active language). Studio-managed cues emit studio cue
+ * starts whose content is owned by Studio.
  */
-export declare function createStudioNarration<const K extends readonly [string, ...string[]]>(...keys: K): Cues<Record<K[number], CueMapValue>>;
-export {};
+export declare function buildLocalizedNarrationCues(narration: NormalizedNarration, voiceByLang: Partial<Record<string, LangNarrationOverride>>, defaultVoice: TopLevelVoiceConfig | LangNarrationOverride | undefined): Record<string, NarrationCue>;
 //# sourceMappingURL=cue.d.ts.map

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

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