screenci 0.0.75 → 0.0.78

package/dist/src/asset.js

@@ -1,4 +1,9 @@
+import { timelineAnchorFields, } from './events.js';
+import { parseTimelineOffset } from './timelineOffset.js';
+import { validateCrop, resolveSourceTrim } from './sourceTrim.js';
 import { overlayRect } from './overlayRect.js';
+import { captureCallerFile } from './callerFile.js';
+import { logger } from './logger.js';
 import { access, readFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
 import { resolveRecordingTimingDuration } from './runtimeMode.js';
@@ -10,7 +15,66 @@ import { getScreenCIRuntimeContext, getRuntimeAssetRecorder, getRuntimePage, get
  * headroom for a boost while guarding against accidental extreme distortion.
  */
 export const MAX_AUDIO_LEVEL = 4;
-const registeredAssetPaths = new Set();
+/** Brand identifying a {@link selected} render-dependency overlay input. */
+const DEPENDENCY_INPUT_BRAND = '__screenciSelectedDependency';
+/**
+ * Embed another render's output as an overlay (a "render dependency"). Pass the
+ * project-unique `name` of a video or screenshot; screenci embeds that target's
+ * selected render for the matching language (falling back to its latest finished
+ * render before anything is selected). When the target's selection changes, this
+ * recording's dependents automatically re-render to embed the new output.
+ *
+ * No local file is read for a `selected(...)` overlay: the medium and concrete
+ * output are looked up by the backend at render time. Screenshots may only embed
+ * other screenshots; videos may embed either.
+ *
+ * The embed plays the target's audio. Pass `{ inheritSubtitles: true }` to also
+ * carry the target's narration subtitles up into the surrounding video's subtitle
+ * track for the window it plays, wherever the surrounding video has no competing
+ * narration of its own (off by default).
+ *
+ * @example
+ * ```ts
+ * video.overlays({ intro: selected('Intro Clip') })(
+ *   'Full Demo',
+ *   async ({ page, overlays }) => {
+ *     await overlays.intro()
+ *     await page.goto('/dashboard')
+ *   }
+ * )
+ * ```
+ */
+export function selected(name, options) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+        throw new Error('[screenci] selected(name) requires the non-empty name of a video or screenshot to embed.');
+    }
+    return {
+        [DEPENDENCY_INPUT_BRAND]: true,
+        name,
+        config: options ?? {},
+    };
+}
+function isDependencyOverlayInput(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[DEPENDENCY_INPUT_BRAND] === true);
+}
+/**
+ * Overlay file paths registered by {@link createOverlays}, each attributed to
+ * the `.screenci` script that declared it (or `null` when the caller could not
+ * be determined). Attribution lets {@link validateRegisteredAssetPaths} check
+ * only the assets a given recording's script declared, so unrelated assets
+ * registered by other test files sharing the worker are not validated against
+ * the wrong test file.
+ */
+const registeredAssets = [];
+function registerAssetPath(path) {
+    const ownerFile = captureCallerFile(import.meta.url);
+    if (registeredAssets.some((entry) => entry.path === path && entry.ownerFile === ownerFile)) {
+        return;
+    }
+    registeredAssets.push({ ownerFile, path });
+}
 // One frame at 24fps — ensures at least one rendered frame captures each asset
 // state when an overlay is started and ended back-to-back.
 const ONE_FRAME_MS = 1000 / 24;
@@ -35,14 +99,26 @@ export function setActiveAssetRecorder(recorder) {
     resetAssetRuntimeState();
 }
 export function resetRegisteredAssetPaths() {
-    registeredAssetPaths.clear();
+    registeredAssets.length = 0;
 }
 export function resetAssetChain() {
     resetAssetRuntimeState();
 }
+/**
+ * Validates the overlay files declared by the `.screenci` script at
+ * {@link testFilePath} (plus any unattributed registrations), resolving each
+ * as-is and relative to that file. Throws "Asset file not found" on the first
+ * missing file. Wired into the record flow so a missing overlay fails fast
+ * before the test body runs, rather than only when the overlay is first shown.
+ *
+ * Assets attributed to a different test file are skipped: another script sharing
+ * the worker may legitimately reference a file that does not resolve here.
+ */
 export async function validateRegisteredAssetPaths(testFilePath) {
-    for (const assetPath of registeredAssetPaths) {
-        await validateAssetPath(assetPath, testFilePath);
+    for (const { ownerFile, path } of registeredAssets) {
+        if (ownerFile !== null && ownerFile !== testFilePath)
+            continue;
+        await validateAssetPath(path, testFilePath);
     }
 }
 /**
@@ -65,8 +141,27 @@ async function resolveExistingAssetPath(assetPath, testFilePath) {
     }
     throw new Error(`Asset file not found: ${assetPath}`);
 }
+const warnedMissingOverlayPaths = new Set();
+export function resetMissingOverlayWarnings() {
+    warnedMissingOverlayPaths.clear();
+}
+/**
+ * Checks that an overlay file exists. A missing file is not fatal: the overlay
+ * is recovered from a previous upload of this video (matched by name/path) at
+ * upload time, so a gitignored overlay file does not have to be committed. The
+ * overlay is composited by the renderer, not into the local recording, so a
+ * missing file does not change what is captured locally.
+ */
 async function validateAssetPath(assetPath, testFilePath) {
-    await resolveExistingAssetPath(assetPath, testFilePath);
+    try {
+        await resolveExistingAssetPath(assetPath, testFilePath);
+    }
+    catch {
+        if (warnedMissingOverlayPaths.has(assetPath))
+            return;
+        warnedMissingOverlayPaths.add(assetPath);
+        logger.warn(`Locally missing overlay: ${assetPath}. It will be reused from a previous upload of this video if available, otherwise the upload fails.`);
+    }
 }
 /**
  * Creates a set of typed overlay controllers, one per key in the map. Each value
@@ -124,6 +219,12 @@ function isReactElementLike(value) {
     return value.__pw_type === 'jsx';
 }
 function buildOverlayController(name, input) {
+    // A render dependency (selected(...)) embeds another render's output. It is a
+    // plain (branded) object, so it is matched before the generic config path,
+    // which would otherwise reject it for having no path/element/html.
+    if (isDependencyOverlayInput(input)) {
+        return createDependencyOverlayController(name, input);
+    }
     // A factory is the only callable input. React elements and config objects are
     // plain objects, so this branch never captures them. The config (and its
     // validation) is built per call so props can vary placement and content.
@@ -158,7 +259,10 @@ function buildOverlayFromConfig(name, config) {
         hasPath,
     });
     const fullScreen = config.fill === 'screen';
+    const pinToScreen = config.pinToScreen === true;
     const animate = config.animate === true;
+    // Parse the relative `duration` string into ms once; reused by every branch.
+    const configDurationMs = resolveConfigDuration(name, config.duration);
     if (config.fps !== undefined && !animate) {
         throw new Error(`[screenci] Overlay "${name}" sets "fps" without "animate: true". "fps" only applies to animated overlays.`);
     }
@@ -191,9 +295,9 @@ function buildOverlayFromConfig(name, config) {
             ? () => renderElementToMarkup(name, config.element)
             : () => Promise.resolve(config.html);
         if (animate) {
-            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, config.fps, config.durationMs, renderOpts);
+            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, config.fps, configDurationMs, renderOpts);
         }
-        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, config.durationMs, renderOpts);
+        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, configDurationMs, renderOpts);
     }
     const path = config.path;
     const extension = getAssetExtension(path);
@@ -210,35 +314,46 @@ function buildOverlayFromConfig(name, config) {
         extension !== '.html') {
         throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "css" or "capturePadding": they are only supported for HTML files and React elements.`);
     }
+    // crop applies to image and video files (not rasterized .html); source trim
+    // (start/end) re-times a moving picture, so it applies to .mp4 videos only.
+    if (config.crop !== undefined && extension === '.html') {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "crop": crop is only supported for image (.svg/.png) and video (.mp4) file overlays.`);
+    }
+    if ((config.start !== undefined || config.end !== undefined) &&
+        extension !== '.mp4') {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "start"/"end": source trim is only supported for .mp4 video overlays.`);
+    }
     // HTML file: read + rasterize to a transparent PNG (or an animated clip).
     if (extension === '.html') {
-        registeredAssetPaths.add(path);
+        registerAssetPath(path);
         const getMarkup = () => readHtmlOverlayFile(path);
         if (animate) {
-            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, config.fps, config.durationMs, renderOpts);
+            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, config.fps, configDurationMs, renderOpts);
         }
-        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, config.durationMs, renderOpts);
+        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, configDurationMs, renderOpts);
     }
     // File-backed image / video overlays.
     if (extension === '.svg' || extension === '.png') {
         if (config.volume !== undefined) {
-            throw new Error(`[screenci] Overlay "${name}" (${path}) is an image and must not provide volume. Use durationMs instead.`);
+            throw new Error(`[screenci] Overlay "${name}" (${path}) is an image and must not provide volume. Use duration instead.`);
         }
-        if (config.durationMs !== undefined) {
-            validateDurationMs(name, path, config.durationMs);
+        if (config.crop !== undefined) {
+            validateCrop(`Overlay "${name}" (${path})`, config.crop);
         }
-        registeredAssetPaths.add(path);
+        registerAssetPath(path);
         return createFileOverlayController(name, {
             kind: 'image',
             path,
             ...(placement !== undefined && { placement }),
             fullScreen,
-            ...(config.durationMs !== undefined && { durationMs: config.durationMs }),
+            ...(pinToScreen && { pinToScreen: true }),
+            ...(configDurationMs !== undefined && { durationMs: configDurationMs }),
+            ...(config.crop !== undefined && { crop: config.crop }),
         });
     }
     if (extension === '.mp4') {
-        if (config.durationMs !== undefined) {
-            throw new Error(`[screenci] Overlay "${name}" (${path}) is a video and must not provide durationMs. Its natural media duration is used instead.`);
+        if (config.duration !== undefined) {
+            throw new Error(`[screenci] Overlay "${name}" (${path}) is a video and must not provide duration. Its natural media duration is used instead.`);
         }
         if (config.volume !== undefined &&
             (!Number.isFinite(config.volume) ||
@@ -247,15 +362,23 @@ function buildOverlayFromConfig(name, config) {
             throw new Error(`[screenci] Overlay "${name}" (${path}) must provide a finite volume between 0 and ${MAX_AUDIO_LEVEL} for .mp4 overlays. 1 is the natural level, 0 is silent, and values above 1 boost it.`);
         }
         validateSpeedTime(`Overlay "${name}" (${path})`, config.speed, config.time);
-        registeredAssetPaths.add(path);
+        if (config.crop !== undefined) {
+            validateCrop(`Overlay "${name}" (${path})`, config.crop);
+        }
+        const { sourceStart, sourceEnd } = resolveSourceTrim(`Overlay "${name}" (${path})`, config.start, config.end);
+        registerAssetPath(path);
         return createFileOverlayController(name, {
             kind: 'video',
             path,
             ...(placement !== undefined && { placement }),
             fullScreen,
+            ...(pinToScreen && { pinToScreen: true }),
             ...(config.volume !== undefined && { audio: config.volume }),
             ...(config.speed !== undefined && { speed: config.speed }),
             ...(config.time !== undefined && { time: config.time }),
+            ...(config.crop !== undefined && { crop: config.crop }),
+            ...(sourceStart !== undefined && { sourceStart }),
+            ...(sourceEnd !== undefined && { sourceEnd }),
         });
     }
     throw new Error(`[screenci] Overlay "${name}" must use one of: .html, .svg, .png, .mp4. Received: ${path}`);
@@ -428,6 +551,65 @@ export function buildStudioOverlays(names) {
     }
     return result;
 }
+/**
+ * Build overlay controllers for a `video.overlays(...)` declaration. Studio
+ * (array) names become Studio-managed controllers; code (object) names resolve
+ * their config for the active language (`byLang[language] ?? shared`) and become
+ * regular overlay controllers. Per-language mode realizes one language per pass,
+ * so the active-language config is the one captured.
+ */
+export function buildOverlays(feature, language) {
+    const result = {};
+    if (!feature)
+        return result;
+    for (const name of feature.studioNames) {
+        result[name] = createStudioAssetController(name);
+    }
+    for (const name of feature.codeNames) {
+        const input = (language !== undefined ? feature.byLang[language]?.[name] : undefined) ??
+            feature.shared[name];
+        if (input === undefined)
+            continue;
+        result[name] = buildOverlayController(name, input);
+    }
+    return result;
+}
+/**
+ * Resolves a string overlay position into the anchor recorded on the asset start.
+ * Throws on a non-string value so callers that meant a numeric duration are not
+ * silently misrouted into the parser.
+ */
+function resolveOverlayAnchor(until) {
+    if (typeof until !== 'string') {
+        throw new Error(`overlay positions must be a string such as '0:10' or '56%', got ${typeof until}`);
+    }
+    const parsed = parseTimelineOffset(until);
+    return parsed.kind === 'percent'
+        ? { percent: parsed.fraction }
+        : { outputMs: parsed.ms };
+}
+/**
+ * Resolves a relative length string (`.for('2s')` or a config `duration`) into
+ * milliseconds. Seconds and timecodes only: a percentage is rejected because a
+ * relative length has nothing to take a percentage of (use `.until('<n>%')` for
+ * an absolute position instead).
+ */
+function resolveRelativeDuration(value, label) {
+    if (typeof value !== 'string') {
+        throw new Error(`[screenci] ${label} must be a time string such as '2s' or '0:02', got ${typeof value}.`);
+    }
+    const parsed = parseTimelineOffset(value);
+    if (parsed.kind === 'percent') {
+        throw new Error(`[screenci] ${label} cannot be a percentage ('${value}'); a relative length needs a concrete time like '2s' or '0:02'. Use .until('${value}') for an absolute position.`);
+    }
+    return parsed.ms;
+}
+/** Parses an optional config `duration` (a relative time string) into ms. */
+function resolveConfigDuration(name, duration) {
+    if (duration === undefined)
+        return undefined;
+    return resolveRelativeDuration(duration, `Overlay "${name}" duration`);
+}
 function createActiveAssetRun(startedWithExplicitStart) {
     let resolve;
     const finished = new Promise((resolveFn) => {
@@ -478,19 +660,27 @@ prepare) {
         endLiveAsset(name, 'wait');
         await run.finished;
     };
-    const controller = (async (durationMs) => {
-        // A blocking overlay holds a frozen frame for a fixed duration. It never
-        // registers a live run and never ends overlays that are already live, so it
-        // can run while other overlays stay composited across the frozen frame.
-        const mode = {
-            type: 'blocking',
-            ...(durationMs !== undefined && { durationMs }),
-        };
+    // A blocking overlay holds a frozen frame. It never registers a live run and
+    // never ends overlays that are already live, so it can run while other overlays
+    // stay composited across the frame.
+    const runBlocking = async (mode) => {
         await validate();
         await prepare?.(mode);
         const recorder = getRuntimeAssetRecorder();
         emitStart(recorder, mode);
+    };
+    const controller = (async () => {
+        // Bare call: hold for the source's natural length. Length-less overlays
+        // (image/html/element) reject this downstream and must use .for()/.until().
+        await runBlocking({ type: 'blocking' });
+    });
+    controller.for = (duration) => runBlocking({
+        type: 'blocking',
+        durationMs: resolveRelativeDuration(duration, `Overlay "${name}" .for(duration)`),
     });
+    // A string position sets an absolute point to stay visible until (resolved at
+    // render time, so a percentage is kept symbolic).
+    controller.until = (position) => runBlocking({ type: 'blocking', until: resolveOverlayAnchor(position) });
     controller.start = () => start(true);
     controller.end = end;
     return controller;
@@ -498,6 +688,60 @@ prepare) {
 function createStudioAssetController(name) {
     return createAssetControllerCore(name, () => Promise.resolve(), (recorder) => recorder.addStudioAssetStart(name));
 }
+/**
+ * Builds the controller for a {@link selected} render-dependency overlay. No
+ * local file is read: the controller emits an `assetStart` carrying the target's
+ * name (an {@link OverlayDependencyRef}); the backend resolves it to a concrete
+ * output at render time. Placement is fixed (no `over`), so it is resolved up
+ * front. A blocking call needs a duration (from the call or config); a
+ * `start()`/`end()` window needs none.
+ */
+function createDependencyOverlayController(name, input) {
+    // `over`/`margin` are not in DependencyOverlayOptions, so placement is always
+    // fixed here (an embedded render has no live element to size against).
+    const placement = resolveOverlayPlacement(name, input.config);
+    const fullScreen = input.config.fill === 'screen';
+    const pinToScreen = input.config.pinToScreen === true;
+    const configDurationMs = resolveConfigDuration(name, input.config.duration);
+    if (input.config.crop !== undefined) {
+        validateCrop(`Dependency overlay "${name}"`, input.config.crop);
+    }
+    // start/end are valid only when the target resolves to a VIDEO; the backend
+    // rejects them for a screenshot dependency (the medium is unknown until then).
+    const { sourceStart, sourceEnd } = resolveSourceTrim(`Dependency overlay "${name}"`, input.config.start, input.config.end);
+    return createAssetControllerCore(name, () => Promise.resolve(), (recorder, mode) => {
+        let durationMs;
+        let until;
+        if (mode.type === 'blocking') {
+            if (mode.until !== undefined) {
+                until = mode.until;
+            }
+            else {
+                // No length => natural duration. Valid for a video dependency; the
+                // backend rejects a screenshot dependency with no length when it
+                // resolves the concrete medium.
+                durationMs = mode.durationMs ?? configDurationMs;
+            }
+        }
+        recorder.addAssetStart(name, {
+            kind: 'dependency',
+            dependency: {
+                name: input.name,
+                ...(input.config.inheritSubtitles === true && {
+                    inheritSubtitles: true,
+                }),
+            },
+            ...(durationMs !== undefined && { durationMs }),
+            ...timelineAnchorFields(until),
+            fullScreen,
+            ...(pinToScreen && { pinToScreen: true }),
+            ...(placement !== undefined && { placement }),
+            ...(input.config.crop !== undefined && { crop: input.config.crop }),
+            ...(sourceStart !== undefined && { sourceStart }),
+            ...(sourceEnd !== undefined && { sourceEnd }),
+        });
+    });
+}
 function createFileOverlayController(name, resolved) {
     return createAssetControllerCore(name, async () => {
         const testFilePath = getScreenCIRuntimeContext().testFilePath;
@@ -512,7 +756,7 @@ function createFileOverlayController(name, resolved) {
  * An overlay rendered to a transparent PNG at recording time, from either an
  * HTML file or a React element. `getMarkup` produces the HTML to rasterize.
  */
-function createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, durationMs, renderOpts = {}) {
+function createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, durationMs, renderOpts = {}) {
     // The markup and placement are resolved during the test (cheap:
     // renderToStaticMarkup / a string, plus a boundingBox read for `over`), but
     // rasterization (a browser screenshot) is deferred to after the test so
@@ -527,19 +771,27 @@ function createRenderedOverlayController(name, getMarkup, placementSource, fullS
         if (skipped || resolvedHtml === undefined)
             return;
         let durationMsForEvent;
+        let until;
         if (mode.type === 'blocking') {
-            durationMsForEvent = mode.durationMs ?? durationMs;
-            if (durationMsForEvent === undefined) {
-                throw new Error(`[screenci] Overlay "${name}" needs a duration: pass one to the call (overlays.${name}(1000)), set durationMs in the config, or drive it with .start()/.end().`);
+            if (mode.until !== undefined) {
+                until = mode.until;
+            }
+            else {
+                durationMsForEvent = mode.durationMs ?? durationMs;
+                if (durationMsForEvent === undefined) {
+                    throw new Error(`[screenci] Overlay "${name}" needs a length: use .for('2s'), .until('0:05'), set "duration" in the config, or drive it with .start()/.end().`);
+                }
+                validateDurationMs(name, `overlay "${name}"`, durationMsForEvent);
             }
-            validateDurationMs(name, `overlay "${name}"`, durationMsForEvent);
         }
         recorder.addPendingAssetStart(name, {
             kind: 'image',
             ...(durationMsForEvent !== undefined && {
                 durationMs: durationMsForEvent,
             }),
+            ...timelineAnchorFields(until),
             fullScreen,
+            ...(pinToScreen && { pinToScreen: true }),
             ...(resolvedPlacement !== undefined && {
                 placement: resolvedPlacement,
             }),
@@ -580,20 +832,23 @@ function createRenderedOverlayController(name, getMarkup, placementSource, fullS
  * the recording, the old "hide block" that cut capture wall-clock from the
  * timeline is no longer needed.
  */
-function createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, fps, configDurationMs, renderOpts = {}) {
+function createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, fps, configDurationMs, renderOpts = {}) {
     let resolved;
     let skipped = false;
     const resolveDurationMs = (mode) => {
         if (mode.type === 'blocking') {
+            if (mode.until !== undefined) {
+                throw new Error(`[screenci] Animated overlay "${name}" cannot use .until('0:10'); its capture length must be fixed. Use .for('2s'), set "duration" in the config, or drive it with .start()/.end() (with "duration" in the config).`);
+            }
             const durationMs = mode.durationMs ?? configDurationMs;
             if (durationMs === undefined) {
-                throw new Error(`[screenci] Animated overlay "${name}" needs a duration: pass one to the call (overlays.${name}(1000)), set durationMs in the config, or drive it with .start()/.end() (with durationMs in the config).`);
+                throw new Error(`[screenci] Animated overlay "${name}" needs a length: use .for('2s'), set "duration" in the config, or drive it with .start()/.end() (with "duration" in the config).`);
             }
             validateDurationMs(name, `overlay "${name}"`, durationMs);
             return durationMs;
         }
         if (configDurationMs === undefined) {
-            throw new Error(`[screenci] Animated overlay "${name}" driven with .start()/.end() needs durationMs in its config (the capture length is otherwise unknown).`);
+            throw new Error(`[screenci] Animated overlay "${name}" driven with .start()/.end() needs "duration" in its config (the capture length is otherwise unknown).`);
         }
         validateDurationMs(name, `overlay "${name}"`, configDurationMs);
         return configDurationMs;
@@ -603,8 +858,13 @@ function createAnimatedOverlayController(name, getMarkup, placementSource, fullS
             return;
         recorder.addPendingAssetStart(name, {
             kind: 'animation',
-            ...(mode.type === 'blocking' && { durationMs: resolved.durationMs }),
+            // Always carry the capture length, for blocking and live overlays alike.
+            // A live animated overlay plays out to this length (the renderer holds a
+            // frozen-frame tail when it is longer than the start()/end() window), so
+            // it needs the duration even when an assetEnd also bounds the window.
+            durationMs: resolved.durationMs,
             fullScreen,
+            ...(pinToScreen && { pinToScreen: true }),
             ...(resolved.placement !== undefined && {
                 placement: resolved.placement,
             }),
@@ -836,31 +1096,52 @@ function sizeWrapMarkup(html, size) {
 function toRecordedFileStart(name, resolved, mode) {
     if (resolved.kind === 'image') {
         let durationMs;
+        let until;
         if (mode.type === 'blocking') {
-            durationMs = mode.durationMs ?? resolved.durationMs;
-            if (durationMs === undefined) {
-                throw new Error(`[screenci] Overlay "${name}" (${resolved.path}) needs a duration: pass one to the call (overlays.${name}(1000)), set durationMs in the config, or drive it with .start()/.end().`);
+            if (mode.until !== undefined) {
+                until = mode.until;
+            }
+            else {
+                durationMs = mode.durationMs ?? resolved.durationMs;
+                if (durationMs === undefined) {
+                    throw new Error(`[screenci] Overlay "${name}" (${resolved.path}) needs a length: use .for('2s'), .until('0:05'), set "duration" in the config, or drive it with .start()/.end().`);
+                }
+                validateDurationMs(name, resolved.path, durationMs);
             }
-            validateDurationMs(name, resolved.path, durationMs);
         }
         return {
             kind: 'image',
             path: resolved.path,
             ...(durationMs !== undefined && { durationMs }),
+            ...timelineAnchorFields(until),
             fullScreen: resolved.fullScreen,
+            ...(resolved.pinToScreen && { pinToScreen: true }),
             ...(resolved.placement !== undefined && {
                 placement: resolved.placement,
             }),
+            ...(resolved.crop !== undefined && { crop: resolved.crop }),
         };
     }
+    if (mode.type === 'blocking' && mode.until !== undefined) {
+        throw new Error(`[screenci] Overlay "${name}" (${resolved.path}) is a video and cannot use .until('0:10'); a video overlay plays for its natural length. Drive it with .start()/.end() to control its window.`);
+    }
+    if (mode.type === 'blocking' && mode.durationMs !== undefined) {
+        throw new Error(`[screenci] Overlay "${name}" (${resolved.path}) is a video and cannot use .for('2s'); a video overlay plays for its natural length. Use a bare call (overlays.${name}()), speed/time to re-time it, or .start()/.end() to control its window.`);
+    }
     return {
         kind: 'video',
         path: resolved.path,
         audio: resolved.audio ?? 1,
         fullScreen: resolved.fullScreen,
+        ...(resolved.pinToScreen && { pinToScreen: true }),
         ...(resolved.placement !== undefined && { placement: resolved.placement }),
         ...(resolved.speed !== undefined && { speed: resolved.speed }),
         ...(resolved.time !== undefined && { time: resolved.time }),
+        ...(resolved.crop !== undefined && { crop: resolved.crop }),
+        ...(resolved.sourceStart !== undefined && {
+            sourceStart: resolved.sourceStart,
+        }),
+        ...(resolved.sourceEnd !== undefined && { sourceEnd: resolved.sourceEnd }),
     };
 }
 //# sourceMappingURL=asset.js.map