screenci 0.0.68 → 0.0.70

package/dist/src/asset.js

@@ -1,19 +1,55 @@
-import { access } from 'fs/promises';
+import { overlayRect } from './overlayRect.js';
+import { access, readFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
-import { getScreenCIRuntimeContext, getRuntimeAssetRecorder, setRuntimeAssetRecorder, } from './runtimeContext.js';
+import { resolveRecordingTimingDuration } from './runtimeMode.js';
+import { resolveOverlayCss, DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR, DEFAULT_ANIMATION_FPS, } from './htmlRasterizer.js';
+export { setOverlayCss } from './htmlRasterizer.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,296 @@ 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.
+ * A config can draw its content from exactly one source: a file `path`, a React
+ * `element`, or an inline `html` fragment.
  *
- * 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.
+ * 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).
+ *
+ * Placement defaults to the full recording area (`relativeTo: 'recording'`);
+ * override any field independently. Coordinates are CSS px of the recording
+ * viewport.
  *
  * @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
+ *   note:  { html: '<div class="note">Tip</div>', x: 1340, y: 110, width: 380 },
+ *   logo:  { path: 'logo.png', x: 96, y: 96, width: 240 },
+ *   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)
  * })
  * ```
+ *
+ * A value can also be an {@link OverlayConfigFactory} `(props) => OverlayConfig`,
+ * making the overlay programmatic. Calling `overlays.name(props)` builds and
+ * returns a controller you then drive with `(durationMs)`, `start()`, or
+ * `end()`. The factory runs (and its config is validated) on each call, so
+ * content and placement can depend on runtime values.
  */
-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 `.screenci.tsx` files with its own automatic
+    // runtime, which produces `{ __pw_type: 'jsx', ... }` nodes instead.
+    return value.__pw_type === 'jsx';
+}
+function buildOverlayController(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.
+    if (typeof input === 'function') {
+        return (props) => buildOverlayFromConfig(name, input(props));
+    }
+    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;
+    const hasHtml = config.html !== undefined;
+    const sourceCount = Number(hasPath) + Number(hasElement) + Number(hasHtml);
+    if (sourceCount > 1) {
+        throw new Error(`[screenci] Overlay "${name}" must provide only one of "path", "element", or "html".`);
+    }
+    if (sourceCount === 0) {
+        throw new Error(`[screenci] Overlay "${name}" must provide a "path", an "element", or inline "html".`);
+    }
+    if (hasHtml) {
+        validateInlineHtmlFragment(name, config.html);
+    }
+    const placementSource = resolvePlacementSource(name, config, {
+        hasElement,
+        hasHtml,
+        hasPath,
+    });
+    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,
+        }),
+    };
+    // speed/time re-time a moving picture, so they only apply to .mp4 video
+    // overlays. Images, HTML, React, and animated overlays have no source rate.
+    if ((config.speed !== undefined || config.time !== undefined) &&
+        (hasElement || hasHtml || getAssetExtension(config.path ?? '') !== '.mp4')) {
+        throw new Error(`[screenci] Overlay "${name}" only supports speed/time on .mp4 video overlays.`);
+    }
+    // React element or inline HTML fragment: rendered to markup lazily at
+    // recording time. Both follow the identical placement/animate/css/padding
+    // path; only how the markup is produced differs.
+    if (hasElement || hasHtml) {
+        const getMarkup = hasElement
+            ? () => renderElementToMarkup(name, config.element)
+            : () => Promise.resolve(config.html);
+        if (animate) {
+            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, config.fps, config.durationMs, renderOpts);
+        }
+        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, config.durationMs, renderOpts);
+    }
+    const path = config.path;
+    const extension = getAssetExtension(path);
+    // Image/video file overlays never use `over` (rejected in
+    // resolvePlacementSource), so the source is always a concrete placement for
+    // them. The `.html` file branch supports `over`, so it keeps the source.
+    const placement = placementSource.kind === 'fixed'
+        ? placementSource.placement
+        : resolveOverlayPlacement(name, config);
+    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, placementSource, fullScreen, config.fps, config.durationMs, renderOpts);
+        }
+        return createRenderedOverlayController(name, getMarkup, placementSource, 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 !== undefined && { 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.`);
+        }
+        validateSpeedTime(`Overlay "${name}" (${path})`, config.speed, config.time);
+        registeredAssetPaths.add(path);
+        return createFileOverlayController(name, {
+            kind: 'video',
+            path,
+            ...(placement !== undefined && { placement }),
+            fullScreen,
+            ...(config.audio !== undefined && { audio: config.audio }),
+            ...(config.speed !== undefined && { speed: config.speed }),
+            ...(config.time !== undefined && { time: config.time }),
+        });
+    }
+    throw new Error(`[screenci] Overlay "${name}" must use one of: .html, .svg, .png, .mp4. Received: ${path}`);
+}
+/**
+ * Validates an inline `html` overlay fragment. It must be non-empty and must
+ * not contain document-level tags (`<!doctype>`, `<html>`, `<head>`, `<body>`):
+ * screenci wraps the markup in its own document before rasterizing, so a full
+ * document here would nest documents and break the capture. Mirrors the
+ * fragment contract of a React `element`.
+ */
+function validateInlineHtmlFragment(name, html) {
+    if (html.trim().length === 0) {
+        throw new Error(`[screenci] Overlay "${name}" inline "html" must not be empty.`);
+    }
+    const lower = html.toLowerCase();
+    const forbidden = [
+        { token: '<!doctype', label: '<!doctype>' },
+        { token: '<html', label: '<html>' },
+        { token: '<head', label: '<head>' },
+        { token: '<body', label: '<body>' },
+    ];
+    for (const { token, label } of forbidden) {
+        if (lower.includes(token)) {
+            throw new Error(`[screenci] Overlay "${name}" inline "html" must be a fragment, not a full HTML document. Remove the ${label} tag; screenci wraps the markup in a document for you.`);
+        }
+    }
+}
+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 +362,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 +385,435 @@ 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);
         }
-        const activeRecorder = getRuntimeAssetRecorder();
-        activeRecorder.addAssetStart(name, toRecordedAssetStart(name, config));
-        return Promise.resolve();
+    }, (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, placementSource, fullScreen, 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
+    // identical overlays render once. See overlayFlush.ts.
+    let resolvedHtml;
+    let resolvedPlacement;
+    let skipped = false;
+    return createAssetControllerCore(name, () => Promise.resolve(), (recorder, mode) => {
+        // `resolvedHtml` is set only once the overlay has resolved, so it is the
+        // "is resolved" signal. `resolvedPlacement` may legitimately stay
+        // undefined (a fill-the-recording overlay emits no placement).
+        if (skipped || resolvedHtml === undefined)
+            return;
+        let durationMsForEvent;
+        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().`);
+            }
+            validateDurationMs(name, `overlay "${name}"`, durationMsForEvent);
+        }
+        recorder.addPendingAssetStart(name, {
+            kind: 'image',
+            ...(durationMsForEvent !== undefined && {
+                durationMs: durationMsForEvent,
+            }),
+            fullScreen,
+            ...(resolvedPlacement !== undefined && {
+                placement: resolvedPlacement,
+            }),
+            request: {
+                kind: 'image',
+                name,
+                html: resolvedHtml,
+                css: resolveOverlayCss(renderOpts.css),
+                capturePadding: renderOpts.capturePadding ?? 0,
+                deviceScaleFactor: DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR,
+            },
+        });
+    }, async () => {
+        if (resolvedHtml !== undefined || skipped)
+            return;
+        // Resolving 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 { placement, sizePx } = await resolvePlacement(placementSource);
+        resolvedPlacement = placement;
+        const markup = await getMarkup();
+        resolvedHtml =
+            sizePx !== undefined ? sizeWrapMarkup(markup, sizePx) : markup;
+    });
+}
+/**
+ * An animated overlay rendered to a transparent clip, 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).
+ *
+ * Markup and duration are captured during the test; the clip itself is encoded
+ * after the test (see overlayFlush.ts). Because no rasterization happens during
+ * 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 = {}) {
+    let resolved;
+    let skipped = false;
+    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).`);
+        }
+        validateDurationMs(name, `overlay "${name}"`, configDurationMs);
+        return configDurationMs;
     };
+    return createAssetControllerCore(name, () => Promise.resolve(), (recorder, mode) => {
+        if (skipped || resolved === undefined)
+            return;
+        recorder.addPendingAssetStart(name, {
+            kind: 'animation',
+            ...(mode.type === 'blocking' && { durationMs: resolved.durationMs }),
+            fullScreen,
+            ...(resolved.placement !== undefined && {
+                placement: resolved.placement,
+            }),
+            request: {
+                kind: 'animation',
+                name,
+                html: resolved.html,
+                css: resolveOverlayCss(renderOpts.css),
+                capturePadding: renderOpts.capturePadding ?? 0,
+                deviceScaleFactor: DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR,
+                fps: fps ?? DEFAULT_ANIMATION_FPS,
+                durationMs: resolved.durationMs,
+            },
+        });
+    }, 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) {
+            skipped = true;
+            return;
+        }
+        const durationMs = resolveDurationMs(mode);
+        const { placement, sizePx } = await resolvePlacement(placementSource);
+        const markup = await getMarkup();
+        resolved = {
+            html: sizePx !== undefined ? sizeWrapMarkup(markup, sizePx) : markup,
+            durationMs,
+            ...(placement !== undefined && { placement }),
+        };
+    });
 }
 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.`);
+}
+/**
+ * Upper bound for a playback-speed multiplier. `16` is already an extreme rate;
+ * the cap guards against accidental runaway values producing degenerate output.
+ */
+export const MAX_SPEED = 16;
+/**
+ * Validates a `speed`/`time` pair shared by `.mp4` overlays and audio tracks.
+ * `speed` must be a finite multiplier in `(0, MAX_SPEED]`; `time` must be a
+ * finite duration greater than 0 (ms). They are mutually exclusive.
+ */
+export function validateSpeedTime(label, speed, time) {
+    if (speed !== undefined && time !== undefined) {
+        throw new Error(`[screenci] ${label} must set only one of speed or time, not both.`);
+    }
+    if (speed !== undefined &&
+        (!Number.isFinite(speed) || speed <= 0 || speed > MAX_SPEED)) {
+        throw new Error(`[screenci] ${label} must provide a finite speed greater than 0 and at most ${MAX_SPEED}. 2 plays twice as fast, 0.5 at half speed.`);
+    }
+    if (time !== undefined && (!Number.isFinite(time) || time <= 0)) {
+        throw new Error(`[screenci] ${label} must provide a finite time (ms) greater than 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'.`);
+    }
+    const hasWidth = 'width' in placement && placement.width !== undefined;
+    const sizeLabel = hasWidth ? 'width' : 'height';
+    const sizeValue = hasWidth
+        ? placement.width
+        : placement.height;
+    for (const [label, value] of [
+        ['x', placement.x],
+        ['y', placement.y],
+    ]) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            throw new Error(`[screenci] Overlay "${name}" ${label} must be a non-negative number of CSS pixels. Received: ${String(value)}`);
+        }
     }
-    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.`);
+    if (typeof sizeValue !== 'number' ||
+        !Number.isFinite(sizeValue) ||
+        sizeValue <= 0) {
+        throw new Error(`[screenci] Overlay "${name}" ${sizeLabel} must be a positive number of CSS pixels. Received: ${String(sizeValue)}`);
+    }
+    const aspectRatio = placement.aspectRatio;
+    if (aspectRatio !== undefined &&
+        (typeof aspectRatio !== 'number' ||
+            !Number.isFinite(aspectRatio) ||
+            aspectRatio <= 0)) {
+        throw new Error(`[screenci] Overlay "${name}" aspectRatio must be a positive number (width / height). Received: ${String(aspectRatio)}`);
     }
 }
-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}. Coordinates are CSS pixels in the recording viewport,
+ * with the defaults `relativeTo: 'recording'`, `x: 0`, `y: 0`. When neither
+ * `width` nor `height` is given (and no other placement field is set), it returns
+ * `undefined`: the overlay fills the recording area, which the renderer resolves
+ * since the recording size is known there.
+ */
+function resolveOverlayPlacement(name, config) {
+    if (config.fullScreen === true) {
+        return { fullScreen: true };
+    }
+    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 hasSize = config.width !== undefined || config.height !== undefined;
+    if (!hasSize) {
+        const positioned = config.x !== undefined ||
+            config.y !== undefined ||
+            config.relativeTo !== undefined ||
+            config.aspectRatio !== undefined;
+        if (positioned) {
+            throw new Error(`[screenci] Overlay "${name}" must set "width" or "height" (in CSS px) when positioning it. Omit all placement fields to fill the recording area, or set "fullScreen".`);
+        }
+        // Fill the recording area (resolved by the renderer, which knows its size).
+        return undefined;
+    }
+    const relativeTo = config.relativeTo ?? 'recording';
+    const x = config.x ?? 0;
+    const y = config.y ?? 0;
+    const aspectRatio = config.aspectRatio;
+    const placement = config.height !== undefined
+        ? {
+            relativeTo,
+            x,
+            y,
+            height: config.height,
+            ...(aspectRatio !== undefined && { aspectRatio }),
+        }
+        : {
+            relativeTo,
+            x,
+            y,
+            width: config.width,
+            ...(aspectRatio !== undefined && { aspectRatio }),
         };
+    validatePlacement(name, placement);
+    return placement;
+}
+/**
+ * Chooses the placement source for an overlay. With {@link OverlayConfig.over}
+ * the placement is deferred to recording time (the element box is unknown until
+ * the page runs); otherwise it is resolved from the flat config fields now.
+ */
+function resolvePlacementSource(name, config, flags) {
+    if (config.margin !== undefined && config.over === undefined) {
+        throw new Error(`[screenci] Overlay "${name}" sets "margin" without "over". "margin" only applies when positioning over a locator.`);
     }
-    if (extension === '.mp4') {
-        const videoConfig = config;
+    if (config.over === undefined) {
+        return { kind: 'fixed', placement: resolveOverlayPlacement(name, config) };
+    }
+    const isRendered = flags.hasElement ||
+        flags.hasHtml ||
+        (flags.hasPath && getAssetExtension(config.path ?? '') === '.html');
+    if (!isRendered) {
+        throw new Error(`[screenci] Overlay "${name}" can only use "over" with a React element, inline "html", or an .html file (the overlay is sized to the element's box).`);
+    }
+    if (config.fullScreen === true) {
+        throw new Error(`[screenci] Overlay "${name}" cannot set both "over" and "fullScreen".`);
+    }
+    if (config.x !== undefined ||
+        config.y !== undefined ||
+        config.width !== undefined ||
+        config.height !== undefined ||
+        config.relativeTo !== undefined) {
+        throw new Error(`[screenci] Overlay "${name}" cannot combine "over" with x/y/width/height/relativeTo. The placement comes from the locator's box.`);
+    }
+    const margin = config.margin ?? 0;
+    if (!Number.isFinite(margin) || margin < 0) {
+        throw new Error(`[screenci] Overlay "${name}" must provide a finite "margin" greater than or equal to 0. Received: ${String(config.margin)}`);
+    }
+    return { kind: 'over', over: config.over, margin };
+}
+/**
+ * Resolves a {@link PlacementSource} to a concrete placement at recording time.
+ * For an `over` source it reads the locator's box (plus margin) via
+ * {@link overlayRect} and returns the element's pixel size so the markup can be
+ * sized to match, making the rasterized overlay frame the element exactly.
+ */
+async function resolvePlacement(source) {
+    if (source.kind === 'fixed') {
+        return { placement: source.placement };
+    }
+    const rect = await overlayRect(source.over, { margin: source.margin });
+    return {
+        placement: {
+            relativeTo: rect.relativeTo,
+            x: rect.x,
+            y: rect.y,
+            width: rect.width ?? rect.pixels.width,
+        },
+        sizePx: { width: rect.pixels.width, height: rect.pixels.height },
+    };
+}
+/**
+ * Wraps overlay markup in a box of the given CSS pixel size so the rasterized
+ * PNG carries the element's aspect ratio. The renderer then derives the overlay
+ * height from that aspect, landing it exactly on the element's box. The wrapped
+ * content should fill the box (for example `width:100%;height:100%`).
+ */
+function sizeWrapMarkup(html, size) {
+    return `<div style="width:${size.width}px;height:${size.height}px;box-sizing:border-box">${html}</div>`;
+}
+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,
+            ...(resolved.placement !== undefined && {
+                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,
+        ...(resolved.placement !== undefined && { placement: resolved.placement }),
+        ...(resolved.speed !== undefined && { speed: resolved.speed }),
+        ...(resolved.time !== undefined && { time: resolved.time }),
+    };
 }
 //# sourceMappingURL=asset.js.map