screenci 0.0.68 → 0.0.69

package/dist/src/asset.js

@@ -1,19 +1,55 @@
-import { access } from 'fs/promises';
+import { access, readFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
-import { getScreenCIRuntimeContext, getRuntimeAssetRecorder, setRuntimeAssetRecorder, } from './runtimeContext.js';
+import { resolveRecordingTimingDuration } from './runtimeMode.js';
+import { rasterizeHtmlOverlay, rasterizeAnimatedHtmlOverlay, } from './htmlRasterizer.js';
+export { setOverlayCss } from './htmlRasterizer.js';
+import { isInsideHide, isInsideTime } from './timelineBlock.js';
+import { getScreenCIRuntimeContext, getRuntimeAssetRecorder, getRuntimePage, getRuntimeRecordingDir, setRuntimeAssetRecorder, resetAssetRuntimeState, } from './runtimeContext.js';
+/**
+ * Upper bound for an audio level (linear gain). `4` is +12 dB, plenty of
+ * headroom for a boost while guarding against accidental extreme distortion.
+ */
+export const MAX_AUDIO_LEVEL = 4;
 const registeredAssetPaths = new Set();
+// 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;
+// Blocking sleep — spin until the elapsed time has passed. Injectable for tests.
+let sleepFn = (ms) => {
+    const end = performance.now() + ms;
+    while (performance.now() < end) {
+        /* spin */
+    }
+};
+export function setAssetSleepFn(fn) {
+    sleepFn = fn;
+}
+function sleepForAssetFrameGap() {
+    const durationMs = resolveRecordingTimingDuration(2 * ONE_FRAME_MS);
+    if (durationMs <= 0)
+        return;
+    sleepFn(durationMs);
+}
 export function setActiveAssetRecorder(recorder) {
     setRuntimeAssetRecorder(recorder);
+    resetAssetRuntimeState();
 }
 export function resetRegisteredAssetPaths() {
     registeredAssetPaths.clear();
 }
+export function resetAssetChain() {
+    resetAssetRuntimeState();
+}
 export async function validateRegisteredAssetPaths(testFilePath) {
     for (const assetPath of registeredAssetPaths) {
         await validateAssetPath(assetPath, testFilePath);
     }
 }
-async function validateAssetPath(assetPath, testFilePath) {
+/**
+ * Resolves an overlay file path to an existing absolute path, trying it as-is
+ * and relative to the test file. Throws when no candidate exists.
+ */
+async function resolveExistingAssetPath(assetPath, testFilePath) {
     const candidates = [assetPath];
     if (testFilePath !== null) {
         candidates.push(resolve(dirname(testFilePath), assetPath));
@@ -21,7 +57,7 @@ async function validateAssetPath(assetPath, testFilePath) {
     for (const candidate of candidates) {
         try {
             await access(candidate);
-            return;
+            return candidate;
         }
         catch {
             // try next candidate
@@ -29,46 +65,229 @@ async function validateAssetPath(assetPath, testFilePath) {
     }
     throw new Error(`Asset file not found: ${assetPath}`);
 }
+async function validateAssetPath(assetPath, testFilePath) {
+    await resolveExistingAssetPath(assetPath, testFilePath);
+}
 /**
- * Creates a set of typed asset controllers, one per key in the map.
+ * Creates a set of typed overlay controllers, one per key in the map. Each value
+ * is a file path string, a React element, or an {@link OverlayConfig} object.
+ *
+ * Calling a controller shows the overlay in the recording timeline. Image
+ * (`.svg`/`.png`), HTML, and React overlays need a `durationMs` (in the config
+ * or passed to the blocking call) unless driven with `start()`/`end()`; `.mp4`
+ * overlays use their natural duration and default `audio` to `1` (natural level).
  *
- * Calling a controller marks the asset in the recording timeline.
- * `.svg`/`.png` assets require explicit `durationMs`; `.mp4` assets use their
- * natural duration and default `audio` to `1` when omitted.
+ * Placement defaults to the full recording area (`relativeTo: 'recording',
+ * x: 0, y: 0, width: 1`); override any field independently.
  *
  * @example
- * ```ts
- * const assets = createAssets({
- *   logo:  { path: './logo.png',  durationMs: 1200, fullScreen: false },
- *   intro: { path: './intro.mp4', fullScreen: true },
+ * ```tsx
+ * const overlays = createOverlays({
+ *   hint:  'callout.html',                       // HTML file
+ *   badge: <Badge label="New" />,                // React element
+ *   logo:  { path: 'logo.png', x: 0.05, y: 0.05, width: 0.2 },
+ *   intro: { path: 'intro.mp4', fullScreen: true },
  * })
  *
  * video('Product demo', async ({ page }) => {
- *   await assets.intro()
+ *   await overlays.intro()
  *   await page.goto('/dashboard')
- *   await assets.logo()
+ *   await overlays.logo(1200)
  * })
  * ```
  */
-export function createAssets(assetsMap) {
+export function createOverlays(overlays) {
     const result = {};
-    for (const name in assetsMap) {
-        const config = assetsMap[name];
-        validateAssetConfig(name, config);
-        registeredAssetPaths.add(config.path);
-        result[name] = createAssetController(name, config);
+    for (const name in overlays) {
+        result[name] = buildOverlayController(name, overlays[name]);
     }
     return result;
 }
+function isReactElementLike(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    // A real React element carries a symbol `$$typeof`.
+    if (typeof value.$$typeof === 'symbol')
+        return true;
+    // Playwright transpiles JSX in `.video.tsx` files with its own automatic
+    // runtime, which produces `{ __pw_type: 'jsx', ... }` nodes instead.
+    return value.__pw_type === 'jsx';
+}
+function buildOverlayController(name, input) {
+    if (typeof input === 'string') {
+        return buildOverlayFromConfig(name, { path: input });
+    }
+    if (isReactElementLike(input)) {
+        return buildOverlayFromConfig(name, { element: input });
+    }
+    return buildOverlayFromConfig(name, input);
+}
+function buildOverlayFromConfig(name, config) {
+    const hasPath = config.path !== undefined;
+    const hasElement = config.element !== undefined;
+    if (hasPath && hasElement) {
+        throw new Error(`[screenci] Overlay "${name}" must provide only one of "path" or "element".`);
+    }
+    if (!hasPath && !hasElement) {
+        throw new Error(`[screenci] Overlay "${name}" must provide a "path" or an "element".`);
+    }
+    const placement = resolveOverlayPlacement(name, config);
+    const fullScreen = config.fullScreen ?? false;
+    const animate = config.animate === true;
+    if (config.fps !== undefined && !animate) {
+        throw new Error(`[screenci] Overlay "${name}" sets "fps" without "animate: true". "fps" only applies to animated overlays.`);
+    }
+    if (animate && config.fps !== undefined) {
+        if (!Number.isFinite(config.fps) || config.fps <= 0) {
+            throw new Error(`[screenci] Overlay "${name}" must provide a finite "fps" greater than 0. Received: ${String(config.fps)}`);
+        }
+    }
+    if (config.capturePadding !== undefined &&
+        (!Number.isFinite(config.capturePadding) || config.capturePadding < 0)) {
+        throw new Error(`[screenci] Overlay "${name}" must provide a finite "capturePadding" greater than or equal to 0. Received: ${String(config.capturePadding)}`);
+    }
+    const renderOpts = {
+        ...(config.css !== undefined && { css: config.css }),
+        ...(config.capturePadding !== undefined && {
+            capturePadding: config.capturePadding,
+        }),
+    };
+    // React element: rendered to markup lazily at recording time.
+    if (hasElement) {
+        const element = config.element;
+        const getMarkup = () => renderElementToMarkup(name, element);
+        if (animate) {
+            return createAnimatedOverlayController(name, getMarkup, placement, fullScreen, config.fps, config.durationMs, renderOpts);
+        }
+        return createRenderedOverlayController(name, getMarkup, placement, fullScreen, config.durationMs, renderOpts);
+    }
+    const path = config.path;
+    const extension = getAssetExtension(path);
+    if (animate && extension !== '.html') {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot animate: "animate" is only supported for HTML files and React elements.`);
+    }
+    if ((config.css !== undefined || config.capturePadding !== undefined) &&
+        extension !== '.html') {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "css" or "capturePadding": they are only supported for HTML files and React elements.`);
+    }
+    // HTML file: read + rasterize to a transparent PNG (or an animated clip).
+    if (extension === '.html') {
+        registeredAssetPaths.add(path);
+        const getMarkup = () => readHtmlOverlayFile(path);
+        if (animate) {
+            return createAnimatedOverlayController(name, getMarkup, placement, fullScreen, config.fps, config.durationMs, renderOpts);
+        }
+        return createRenderedOverlayController(name, getMarkup, placement, fullScreen, config.durationMs, renderOpts);
+    }
+    // File-backed image / video overlays.
+    if (extension === '.svg' || extension === '.png') {
+        if (config.audio !== undefined) {
+            throw new Error(`[screenci] Overlay "${name}" (${path}) is an image and must not provide audio. Use durationMs instead.`);
+        }
+        if (config.durationMs !== undefined) {
+            validateDurationMs(name, path, config.durationMs);
+        }
+        registeredAssetPaths.add(path);
+        return createFileOverlayController(name, {
+            kind: 'image',
+            path,
+            placement,
+            fullScreen,
+            ...(config.durationMs !== undefined && { durationMs: config.durationMs }),
+        });
+    }
+    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.audio !== undefined &&
+            (!Number.isFinite(config.audio) ||
+                config.audio < 0 ||
+                config.audio > MAX_AUDIO_LEVEL)) {
+            throw new Error(`[screenci] Overlay "${name}" (${path}) must provide a finite audio value between 0 and ${MAX_AUDIO_LEVEL} for .mp4 overlays. 1 is the natural level, 0 is silent, and values above 1 boost it.`);
+        }
+        registeredAssetPaths.add(path);
+        return createFileOverlayController(name, {
+            kind: 'video',
+            path,
+            placement,
+            fullScreen,
+            ...(config.audio !== undefined && { audio: config.audio }),
+        });
+    }
+    throw new Error(`[screenci] Overlay "${name}" must use one of: .html, .svg, .png, .mp4. Received: ${path}`);
+}
+async function renderElementToMarkup(name, element) {
+    let reactDomServer;
+    let react;
+    try {
+        reactDomServer = (await import('react-dom/server'));
+        react = (await import('react'));
+    }
+    catch {
+        throw new Error(`[screenci] Overlay "${name}" is a React element, which requires "react" and "react-dom" to be installed. Run: npm i react react-dom (plus @types/react @types/react-dom for TypeScript). Re-run "screenci init" and answer yes to React overlay support to scaffold this.`);
+    }
+    // Playwright's JSX runtime produces `__pw_type` nodes rather than real React
+    // elements; convert them (invoking function components, whose bodies are also
+    // pw-jsx) before handing the tree to react-dom.
+    const renderable = isPwJsxNode(element)
+        ? pwJsxToReactNode(element, react)
+        : element;
+    return reactDomServer.renderToStaticMarkup(renderable);
+}
+function isPwJsxNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__pw_type === 'jsx');
+}
+function isPwFragment(type) {
+    return (typeof type === 'object' &&
+        type !== null &&
+        type.__pw_jsx_fragment === true);
+}
+function pwChildrenToArray(children) {
+    if (children === undefined || children === null)
+        return [];
+    return Array.isArray(children) ? children : [children];
+}
+/**
+ * Converts a Playwright JSX node tree into real React nodes. Function components
+ * are invoked (their bodies are pw-jsx too) and their output converted, so the
+ * result is a host-element/primitive tree that react-dom can render statically.
+ */
+function pwJsxToReactNode(node, react) {
+    const createElement = react.createElement;
+    if (Array.isArray(node)) {
+        return node.map((child) => pwJsxToReactNode(child, react));
+    }
+    if (!isPwJsxNode(node))
+        return node;
+    const { type, props } = node;
+    if (isPwFragment(type)) {
+        const kids = pwChildrenToArray(props?.children).map((c) => pwJsxToReactNode(c, react));
+        return createElement(react.Fragment, null, ...kids);
+    }
+    if (typeof type === 'function') {
+        return pwJsxToReactNode(type(props ?? {}), react);
+    }
+    const { children, ...rest } = props ?? {};
+    const kids = pwChildrenToArray(children).map((c) => pwJsxToReactNode(c, react));
+    return createElement(type, rest, ...kids);
+}
+async function readHtmlOverlayFile(path) {
+    const testFilePath = getScreenCIRuntimeContext().testFilePath;
+    const resolved = await resolveExistingAssetPath(path, testFilePath);
+    return readFile(resolved, 'utf-8');
+}
 /**
- * Creates typed asset controllers whose files and display options are
+ * Creates typed overlay controllers whose files and display options are
  * configured on the ScreenCI Studio page instead of in code. Business tier
  * only.
  *
- * Each key becomes a callable asset controller with the same timeline
- * behavior as {@link createAssets} controllers. The file (`.svg`, `.png`, or
- * `.mp4`), full-screen mode, image duration, and video audio level all come
- * from Studio.
+ * Each key becomes a callable overlay controller with the same timeline
+ * behavior as {@link createOverlays} controllers, including `start()`/`end()`.
+ * The file (`.svg`, `.png`, or `.mp4`), placement, image duration, and video
+ * audio level 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
@@ -76,20 +295,20 @@ export function createAssets(assetsMap) {
  *
  * @example
  * ```ts
- * const assets = createStudioAssets('intro', 'logo')
+ * const overlays = createStudioOverlays('intro', 'logo')
  *
  * video('Product demo', async ({ page }) => {
- *   await assets.intro()
+ *   await overlays.intro()
  *   await page.goto('/dashboard')
- *   await assets.logo()
+ *   await overlays.logo()
  * })
  * ```
  */
-export function createStudioAssets(...keys) {
+export function createStudioOverlays(...keys) {
     const seen = new Set();
     for (const key of keys) {
         if (seen.has(key)) {
-            throw new Error(`Duplicate asset key "${key}" passed to createStudioAssets. Asset keys must be unique.`);
+            throw new Error(`Duplicate overlay key "${key}" passed to createStudioOverlays. Overlay keys must be unique.`);
         }
         seen.add(key);
     }
@@ -99,80 +318,316 @@ export function createStudioAssets(...keys) {
     }
     return result;
 }
-function createStudioAssetController(name) {
-    return () => {
-        const activeRecorder = getRuntimeAssetRecorder();
-        activeRecorder.addStudioAssetStart(name);
-        return Promise.resolve();
+function createActiveAssetRun(startedWithExplicitStart) {
+    let resolve;
+    const finished = new Promise((resolveFn) => {
+        resolve = resolveFn;
+    });
+    return { finished, resolveFinished: resolve, startedWithExplicitStart };
+}
+/**
+ * Ends a single live overlay identified by name, emitting its `assetEnd`,
+ * holding a frame, and clearing it from the active map. Overlays may overlap,
+ * so ending one never touches the others.
+ */
+function endLiveAsset(name, reason) {
+    const context = getScreenCIRuntimeContext();
+    const run = context.asset.activeRuns.get(name);
+    if (run === undefined)
+        return;
+    getRuntimeAssetRecorder().addAssetEnd(name, reason);
+    sleepForAssetFrameGap();
+    context.asset.activeRuns.delete(name);
+    run.resolveFinished();
+}
+function createAssetControllerCore(name, validate, emitStart, 
+/**
+ * Optional async step run after {@link validate} and before {@link emitStart},
+ * receiving the resolved start mode. Used by animated overlays to rasterize
+ * the clip once the capture length (mode duration) is known.
+ */
+prepare) {
+    const start = async (startedWithExplicitStart = true) => {
+        await validate();
+        await prepare?.({ type: 'live' });
+        const recorder = getRuntimeAssetRecorder();
+        const context = getScreenCIRuntimeContext();
+        if (context.asset.activeRuns.has(name)) {
+            throw new Error(`[screenci] Overlay "${name}" is already started. Call end() for it before starting it again.`);
+        }
+        const run = createActiveAssetRun(startedWithExplicitStart);
+        context.asset.activeRuns.set(name, run);
+        emitStart(recorder, { type: 'live' });
+    };
+    const end = async () => {
+        const context = getScreenCIRuntimeContext();
+        const run = context.asset.activeRuns.get(name);
+        if (run === undefined) {
+            throw new Error(`Cannot call end() for overlay "${name}" because it is not a started overlay`);
+        }
+        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 }),
+        };
+        await validate();
+        await prepare?.(mode);
+        const recorder = getRuntimeAssetRecorder();
+        emitStart(recorder, mode);
+    });
+    controller.start = () => start(true);
+    controller.end = end;
+    return controller;
 }
-function createAssetController(name, config) {
-    return async () => {
+function createStudioAssetController(name) {
+    return createAssetControllerCore(name, () => Promise.resolve(), (recorder) => recorder.addStudioAssetStart(name));
+}
+function createFileOverlayController(name, resolved) {
+    return createAssetControllerCore(name, async () => {
         const testFilePath = getScreenCIRuntimeContext().testFilePath;
         if (testFilePath !== null) {
-            await validateAssetPath(config.path, testFilePath);
+            await validateAssetPath(resolved.path, testFilePath);
+        }
+    }, (recorder, mode) => {
+        recorder.addAssetStart(name, toRecordedFileStart(name, resolved, mode));
+    });
+}
+/**
+ * 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, placement, fullScreen, durationMs, renderOpts = {}) {
+    let generated;
+    let skipped = false;
+    return createAssetControllerCore(name, async () => {
+        if (generated !== undefined || skipped)
+            return;
+        // Generating an overlay needs an active recording page and output dir.
+        // Outside recording (e.g. plain test runs) there is nothing to upload, so
+        // the controller is a no-op, mirroring the no-op recorder.
+        if (getRuntimePage() === null || getRuntimeRecordingDir() === null) {
+            skipped = true;
+            return;
+        }
+        const html = await getMarkup();
+        const result = await rasterizeHtmlOverlay({
+            name,
+            html,
+            ...(renderOpts.css !== undefined && { css: renderOpts.css }),
+            ...(renderOpts.capturePadding !== undefined && {
+                capturePadding: renderOpts.capturePadding,
+            }),
+        });
+        generated = { path: result.path, fileHash: result.fileHash };
+    }, (recorder, mode) => {
+        if (generated === undefined)
+            return;
+        recorder.addAssetStart(name, toRecordedRenderedStart(name, {
+            placement,
+            fullScreen,
+            ...(durationMs !== undefined && { durationMs }),
+        }, generated, mode));
+    });
+}
+/**
+ * An animated overlay rendered to a transparent clip at recording time, from
+ * either an HTML file or a React element. The capture length is resolved from
+ * the call argument or config `durationMs`; `start()`/`end()` requires a config
+ * `durationMs` (the capture length is otherwise unknown).
+ */
+function createAnimatedOverlayController(name, getMarkup, placement, fullScreen, fps, configDurationMs, renderOpts = {}) {
+    let generated;
+    const resolveDurationMs = (mode) => {
+        if (mode.type === 'blocking') {
+            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).`);
+            }
+            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).`);
         }
-        const activeRecorder = getRuntimeAssetRecorder();
-        activeRecorder.addAssetStart(name, toRecordedAssetStart(name, config));
-        return Promise.resolve();
+        validateDurationMs(name, `overlay "${name}"`, configDurationMs);
+        return configDurationMs;
     };
+    return createAssetControllerCore(name, () => Promise.resolve(), (recorder, mode) => {
+        if (generated === undefined)
+            return;
+        recorder.addAssetStart(name, {
+            kind: 'animation',
+            path: generated.path,
+            fileHash: generated.fileHash,
+            ...(mode.type === 'blocking' && { durationMs: generated.durationMs }),
+            fullScreen,
+            placement,
+        });
+    }, async (mode) => {
+        // Outside recording there is nothing to upload, so the controller is a
+        // no-op, mirroring the no-op recorder and the static rendered controller.
+        if (getRuntimePage() === null || getRuntimeRecordingDir() === null) {
+            return;
+        }
+        const durationMs = resolveDurationMs(mode);
+        const html = await getMarkup();
+        const rasterize = async () => {
+            const result = await rasterizeAnimatedHtmlOverlay({
+                name,
+                html,
+                durationMs,
+                ...(fps !== undefined && { fps }),
+                ...(renderOpts.css !== undefined && { css: renderOpts.css }),
+                ...(renderOpts.capturePadding !== undefined && {
+                    capturePadding: renderOpts.capturePadding,
+                }),
+            });
+            generated = {
+                path: result.path,
+                fileHash: result.fileHash,
+                durationMs,
+            };
+        };
+        // Capturing the animation (screenshotting each frame + encoding) takes
+        // real wall-clock that would otherwise be baked into the recording as a
+        // long frozen pause before the overlay appears. Cut that time from the
+        // output by wrapping the capture in a hide block. On a cache hit this is
+        // ~instant, so the cut is a negligible sliver. Skip the wrapping when
+        // already inside a hide()/time() block (a hide cannot nest, and the
+        // surrounding block already governs that time).
+        if (isInsideHide() || isInsideTime()) {
+            await rasterize();
+            return;
+        }
+        const recorder = getRuntimeAssetRecorder();
+        recorder.addHideStart();
+        try {
+            await rasterize();
+        }
+        finally {
+            recorder.addHideEnd();
+        }
+    });
 }
 function getAssetExtension(path) {
     const dotIndex = path.lastIndexOf('.');
     if (dotIndex === -1)
         return null;
     const extension = path.slice(dotIndex).toLowerCase();
-    if (extension === '.svg' || extension === '.png' || extension === '.mp4') {
+    if (extension === '.html' ||
+        extension === '.svg' ||
+        extension === '.png' ||
+        extension === '.mp4') {
         return extension;
     }
     return null;
 }
-function validateAssetConfig(name, config) {
-    const extension = getAssetExtension(config.path);
-    if (extension === null) {
-        throw new Error(`[screenci] Asset "${name}" must use one of: .svg, .png, .mp4. Received: ${config.path}`);
+function isFiniteNonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function validateDurationMs(name, path, durationMs) {
+    if (!isFiniteNonNegative(durationMs)) {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) must provide a finite durationMs greater than or equal to 0.`);
     }
-    if (extension === '.svg' || extension === '.png') {
-        if ('audio' in config && config.audio !== undefined) {
-            throw new Error(`[screenci] Asset "${name}" (${config.path}) is an image asset and must not provide audio. Use durationMs instead.`);
-        }
-        if (!('durationMs' in config) ||
-            config.durationMs === undefined ||
-            !Number.isFinite(config.durationMs) ||
-            config.durationMs < 0) {
-            throw new Error(`[screenci] Asset "${name}" (${config.path}) must provide a finite durationMs greater than or equal to 0.`);
+}
+function validatePlacement(name, placement) {
+    if ('fullScreen' in placement) {
+        if (placement.fullScreen !== true) {
+            throw new Error(`[screenci] Overlay "${name}" fullScreen must be true when set.`);
         }
         return;
     }
-    if ('durationMs' in config && config.durationMs !== undefined) {
-        throw new Error(`[screenci] Asset "${name}" (${config.path}) is a video asset and must not provide durationMs. Its natural media duration is used instead.`);
+    const relativeTo = placement.relativeTo;
+    if (relativeTo !== 'screen' && relativeTo !== 'recording') {
+        throw new Error(`[screenci] Overlay "${name}" relativeTo must be 'screen' or 'recording'.`);
     }
-    if ('audio' in config &&
-        config.audio !== undefined &&
-        (!Number.isFinite(config.audio) || config.audio < 0 || config.audio > 1)) {
-        throw new Error(`[screenci] Asset "${name}" (${config.path}) must provide a finite audio value between 0 and 1 for .mp4 assets when audio is specified. Use audio: 0 for silent playback.`);
+    const hasWidth = 'width' in placement && placement.width !== undefined;
+    const entries = [
+        ['x', placement.x],
+        ['y', placement.y],
+        hasWidth
+            ? ['width', placement.width]
+            : ['height', placement.height],
+    ];
+    for (const [label, value] of entries) {
+        if (typeof value !== 'number' ||
+            !Number.isFinite(value) ||
+            value < 0 ||
+            value > 1) {
+            throw new Error(`[screenci] Overlay "${name}" ${label} must be a number between 0 and 1 (normalized fraction). Received: ${String(value)}`);
+        }
     }
 }
-function toRecordedAssetStart(name, config) {
-    const extension = getAssetExtension(config.path);
-    if (extension === '.svg' || extension === '.png') {
-        const imageConfig = config;
-        return {
-            kind: 'image',
-            path: imageConfig.path,
-            durationMs: imageConfig.durationMs,
-            fullScreen: imageConfig.fullScreen,
-        };
+/**
+ * Resolves an {@link OverlayConfig}'s flat placement fields into the event-shape
+ * {@link OverlayPlacement}, applying the defaults `relativeTo: 'recording'`,
+ * `x: 0`, `y: 0`, and `width: 1` (when neither width nor height is given). The
+ * default box therefore fills the recording area.
+ */
+function resolveOverlayPlacement(name, config) {
+    if (config.fullScreen === true) {
+        return { fullScreen: true };
     }
-    if (extension === '.mp4') {
-        const videoConfig = config;
+    if (config.width !== undefined && config.height !== undefined) {
+        throw new Error(`[screenci] Overlay "${name}" must set only one of width or height (the other is derived from the aspect ratio).`);
+    }
+    const relativeTo = config.relativeTo ?? 'recording';
+    const x = config.x ?? 0;
+    const y = config.y ?? 0;
+    const placement = config.height !== undefined
+        ? { relativeTo, x, y, height: config.height }
+        : { relativeTo, x, y, width: config.width ?? 1 };
+    validatePlacement(name, placement);
+    return placement;
+}
+function toRecordedRenderedStart(name, resolved, generated, mode) {
+    let durationMs;
+    if (mode.type === 'blocking') {
+        durationMs = mode.durationMs ?? resolved.durationMs;
+        if (durationMs === 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().`);
+        }
+        validateDurationMs(name, `overlay "${name}"`, durationMs);
+    }
+    return {
+        kind: 'image',
+        path: generated.path,
+        fileHash: generated.fileHash,
+        ...(durationMs !== undefined && { durationMs }),
+        fullScreen: resolved.fullScreen,
+        placement: resolved.placement,
+    };
+}
+function toRecordedFileStart(name, resolved, mode) {
+    if (resolved.kind === 'image') {
+        let durationMs;
+        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().`);
+            }
+            validateDurationMs(name, resolved.path, durationMs);
+        }
         return {
-            kind: 'video',
-            path: videoConfig.path,
-            audio: videoConfig.audio ?? 1,
-            fullScreen: videoConfig.fullScreen,
+            kind: 'image',
+            path: resolved.path,
+            ...(durationMs !== undefined && { durationMs }),
+            fullScreen: resolved.fullScreen,
+            placement: resolved.placement,
         };
     }
-    throw new Error(`[screenci] Asset "${name}" has an unsupported path: ${config.path}`);
+    return {
+        kind: 'video',
+        path: resolved.path,
+        audio: resolved.audio ?? 1,
+        fullScreen: resolved.fullScreen,
+        placement: resolved.placement,
+    };
 }
 //# sourceMappingURL=asset.js.map