screenci 0.0.69 → 0.0.70

package/dist/src/asset.js

@@ -1,9 +1,9 @@
+import { overlayRect } from './overlayRect.js';
 import { access, readFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
 import { resolveRecordingTimingDuration } from './runtimeMode.js';
-import { rasterizeHtmlOverlay, rasterizeAnimatedHtmlOverlay, } from './htmlRasterizer.js';
+import { resolveOverlayCss, DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR, DEFAULT_ANIMATION_FPS, } 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
@@ -71,21 +71,25 @@ async function validateAssetPath(assetPath, testFilePath) {
 /**
  * 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 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',
- * x: 0, y: 0, width: 1`); override any field independently.
+ * Placement defaults to the full recording area (`relativeTo: 'recording'`);
+ * override any field independently. Coordinates are CSS px of the recording
+ * viewport.
  *
  * @example
  * ```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 },
+ *   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 },
  * })
  *
@@ -95,6 +99,12 @@ async function validateAssetPath(assetPath, testFilePath) {
  *   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 createOverlays(overlays) {
     const result = {};
@@ -109,11 +119,17 @@ function isReactElementLike(value) {
     // 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
+    // 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 });
     }
@@ -125,13 +141,22 @@ function buildOverlayController(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".`);
+    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 (!hasPath && !hasElement) {
-        throw new Error(`[screenci] Overlay "${name}" must provide a "path" or an "element".`);
+    if (hasHtml) {
+        validateInlineHtmlFragment(name, config.html);
     }
-    const placement = resolveOverlayPlacement(name, config);
+    const placementSource = resolvePlacementSource(name, config, {
+        hasElement,
+        hasHtml,
+        hasPath,
+    });
     const fullScreen = config.fullScreen ?? false;
     const animate = config.animate === true;
     if (config.fps !== undefined && !animate) {
@@ -152,17 +177,32 @@ function buildOverlayFromConfig(name, config) {
             capturePadding: config.capturePadding,
         }),
     };
-    // React element: rendered to markup lazily at recording time.
-    if (hasElement) {
-        const element = config.element;
-        const getMarkup = () => renderElementToMarkup(name, element);
+    // 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, placement, fullScreen, config.fps, config.durationMs, renderOpts);
+            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, config.fps, config.durationMs, renderOpts);
         }
-        return createRenderedOverlayController(name, getMarkup, placement, fullScreen, 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.`);
     }
@@ -175,9 +215,9 @@ function buildOverlayFromConfig(name, config) {
         registeredAssetPaths.add(path);
         const getMarkup = () => readHtmlOverlayFile(path);
         if (animate) {
-            return createAnimatedOverlayController(name, getMarkup, placement, fullScreen, config.fps, config.durationMs, renderOpts);
+            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, config.fps, config.durationMs, renderOpts);
         }
-        return createRenderedOverlayController(name, getMarkup, placement, fullScreen, config.durationMs, renderOpts);
+        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, config.durationMs, renderOpts);
     }
     // File-backed image / video overlays.
     if (extension === '.svg' || extension === '.png') {
@@ -191,7 +231,7 @@ function buildOverlayFromConfig(name, config) {
         return createFileOverlayController(name, {
             kind: 'image',
             path,
-            placement,
+            ...(placement !== undefined && { placement }),
             fullScreen,
             ...(config.durationMs !== undefined && { durationMs: config.durationMs }),
         });
@@ -206,17 +246,44 @@ function buildOverlayFromConfig(name, config) {
                 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,
+            ...(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;
@@ -402,47 +469,77 @@ 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, placement, fullScreen, durationMs, renderOpts = {}) {
-    let generated;
+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, async () => {
-        if (generated !== undefined || skipped)
+    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;
-        // Generating an overlay needs an active recording page and output dir.
+        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 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));
+        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 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).
+ * 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, placement, fullScreen, fps, configDurationMs, renderOpts = {}) {
-    let generated;
+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;
@@ -459,60 +556,41 @@ function createAnimatedOverlayController(name, getMarkup, placement, fullScreen,
         return configDurationMs;
     };
     return createAssetControllerCore(name, () => Promise.resolve(), (recorder, mode) => {
-        if (generated === undefined)
+        if (skipped || resolved === undefined)
             return;
-        recorder.addAssetStart(name, {
+        recorder.addPendingAssetStart(name, {
             kind: 'animation',
-            path: generated.path,
-            fileHash: generated.fileHash,
-            ...(mode.type === 'blocking' && { durationMs: generated.durationMs }),
+            ...(mode.type === 'blocking' && { durationMs: resolved.durationMs }),
             fullScreen,
-            placement,
+            ...(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 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,
-            };
+        const { placement, sizePx } = await resolvePlacement(placementSource);
+        const markup = await getMarkup();
+        resolved = {
+            html: sizePx !== undefined ? sizeWrapMarkup(markup, sizePx) : markup,
+            durationMs,
+            ...(placement !== undefined && { placement }),
         };
-        // 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) {
@@ -536,6 +614,28 @@ function validateDurationMs(name, path, durationMs) {
         throw new Error(`[screenci] Overlay "${name}" (${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) {
@@ -548,27 +648,38 @@ function validatePlacement(name, placement) {
         throw new Error(`[screenci] Overlay "${name}" relativeTo must be 'screen' or 'recording'.`);
     }
     const hasWidth = 'width' in placement && placement.width !== undefined;
-    const entries = [
+    const sizeLabel = hasWidth ? 'width' : 'height';
+    const sizeValue = hasWidth
+        ? placement.width
+        : placement.height;
+    for (const [label, value] of [
         ['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)}`);
+    ]) {
+        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 (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)}`);
+    }
 }
 /**
  * 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.
+ * {@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) {
@@ -577,33 +688,104 @@ function resolveOverlayPlacement(name, 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 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 }
-        : { relativeTo, x, y, width: config.width ?? 1 };
+        ? {
+            relativeTo,
+            x,
+            y,
+            height: config.height,
+            ...(aspectRatio !== undefined && { aspectRatio }),
+        }
+        : {
+            relativeTo,
+            x,
+            y,
+            width: config.width,
+            ...(aspectRatio !== undefined && { aspectRatio }),
+        };
     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);
+/**
+ * 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 (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 {
-        kind: 'image',
-        path: generated.path,
-        fileHash: generated.fileHash,
-        ...(durationMs !== undefined && { durationMs }),
-        fullScreen: resolved.fullScreen,
-        placement: resolved.placement,
+        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;
@@ -619,7 +801,9 @@ function toRecordedFileStart(name, resolved, mode) {
             path: resolved.path,
             ...(durationMs !== undefined && { durationMs }),
             fullScreen: resolved.fullScreen,
-            placement: resolved.placement,
+            ...(resolved.placement !== undefined && {
+                placement: resolved.placement,
+            }),
         };
     }
     return {
@@ -627,7 +811,9 @@ function toRecordedFileStart(name, resolved, mode) {
         path: resolved.path,
         audio: resolved.audio ?? 1,
         fullScreen: resolved.fullScreen,
-        placement: resolved.placement,
+        ...(resolved.placement !== undefined && { placement: resolved.placement }),
+        ...(resolved.speed !== undefined && { speed: resolved.speed }),
+        ...(resolved.time !== undefined && { time: resolved.time }),
     };
 }
 //# sourceMappingURL=asset.js.map