screenci 0.0.89 → 0.0.91

package/dist/src/asset.js

@@ -3,12 +3,12 @@ import { parseTimelineOffset } from './timelineOffset.js';
 import { validateCrop, resolveSourceTrim } from './sourceTrim.js';
 import { overlayRect } from './overlayRect.js';
 import { captureCallerFile } from './callerFile.js';
+import { buildClientOverlayDocument } from './clientOverlay.js';
 import { logMissingAsset } from './missingAssetLog.js';
 import { access, readFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
 import { resolveRecordingTimingDuration } from './runtimeMode.js';
-import { resolveOverlayCss, DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR, DEFAULT_ANIMATION_FPS, } from './htmlRasterizer.js';
-export { setOverlayCss } from './htmlRasterizer.js';
+import { DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR, DEFAULT_ANIMATION_FPS, } 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
@@ -186,8 +186,8 @@ async function validateAssetPath(assetPath, testFilePath) {
  * `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`
+ * (`.svg`/`.png`), HTML, and React overlays need a `duration` (in the config
+ * or passed to `.for(...)`) 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'`);
@@ -207,13 +207,13 @@ async function validateAssetPath(assetPath, testFilePath) {
  * video('Product demo', async ({ page }) => {
  *   await overlays.intro()
  *   await page.goto('/dashboard')
- *   await overlays.logo(1200)
+ *   await overlays.logo.for(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
+ * returns a controller you then drive with `.for(...)`, `start()`, or
  * `end()`. The factory runs (and its config is validated) on each call, so
  * content and placement can depend on runtime values.
  */
@@ -224,56 +224,43 @@ export function createOverlays(overlays) {
     }
     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 render dependency (selected(...)) embeds another render's output. It is a
     // plain (branded) object, so it is matched before the generic config path,
-    // which would otherwise reject it for having no path/element/html.
+    // which would otherwise reject it for having no path.
     if (isDependencyOverlayInput(input)) {
         return createDependencyOverlayController(name, input);
     }
-    // A factory is the only callable input. React elements and config objects are
-    // plain objects, so this branch never captures them. The config (and its
-    // validation) is built per call so props can vary placement and content.
+    // A factory is the only callable input. 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);
+    if (config.path === undefined) {
+        throw new Error(`[screenci] Overlay "${name}" must provide a "path" (a .tsx, .html, .svg, .png, or .mp4 file).`);
     }
-    const placementSource = resolvePlacementSource(name, config, {
-        hasElement,
-        hasHtml,
-        hasPath,
-    });
+    const path = config.path;
+    const extension = getAssetExtension(path);
+    if (extension === null) {
+        throw new Error(`[screenci] Overlay "${name}" must use one of: .tsx, .html, .svg, .png, .mp4. Received: ${path}`);
+    }
+    const isRendered = extension === '.tsx' || extension === '.html';
+    const tsxConfig = config;
+    // The video-only fields live on MediaOverlayConfig; read them through this
+    // accessor since the union member is selected at runtime by the extension.
+    const media = config;
+    // `props` are a .tsx-page-only concept (enforced at the type level too).
+    if (tsxConfig.props !== undefined && extension !== '.tsx') {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "props": props are only supported for .tsx page overlays.`);
+    }
+    const placementSource = resolvePlacementSource(name, config, { isRendered });
     const fullScreen = config.fill === 'screen';
     const pinToScreen = config.pinToScreen === true;
     const overMouse = config.overMouse === true;
@@ -288,74 +275,58 @@ function buildOverlayFromConfig(name, config) {
             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)}`);
+    if (animate && !isRendered) {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot animate: "animate" is only supported for .html and .tsx page overlays.`);
     }
-    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')) {
+    // speed/time/start/end re-time a moving picture, so they only apply to .mp4
+    // video overlays.
+    if ((media.speed !== undefined || media.time !== undefined) &&
+        extension !== '.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, pinToScreen, overMouse, config.fps, configDurationMs, renderOpts);
-        }
-        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, overMouse, configDurationMs, 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.`);
-    }
-    // crop applies to image and video files (not rasterized .html); source trim
-    // (start/end) re-times a moving picture, so it applies to .mp4 videos only.
-    if (config.crop !== undefined && extension === '.html') {
-        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "crop": crop is only supported for image (.svg/.png) and video (.mp4) file overlays.`);
-    }
-    if ((config.start !== undefined || config.end !== undefined) &&
+    if ((media.start !== undefined || media.end !== undefined) &&
         extension !== '.mp4') {
         throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "start"/"end": source trim is only supported for .mp4 video overlays.`);
     }
-    // HTML file: read + rasterize to a transparent PNG (or an animated clip).
-    if (extension === '.html') {
+    // crop applies to image and video files only (not rendered pages).
+    if (media.crop !== undefined && isRendered) {
+        throw new Error(`[screenci] Overlay "${name}" (${path}) cannot use "crop": crop is only supported for image (.svg/.png) and video (.mp4) file overlays.`);
+    }
+    // .tsx (client-rendered React page) and .html (full document) both rasterize
+    // to a transparent PNG (or animated clip). They differ only in how the full
+    // document is produced: a .tsx is bundled and mounts its React app into the
+    // overlay root (so we wait for it to mount before measuring); a .html file is
+    // loaded as-is.
+    if (isRendered) {
         registerAssetPath(path);
-        const getMarkup = () => readHtmlOverlayFile(path);
+        const awaitMount = extension === '.tsx';
+        const getDocument = extension === '.tsx'
+            ? () => {
+                const testFilePath = getScreenCIRuntimeContext().testFilePath;
+                const entryPath = testFilePath !== null
+                    ? resolve(dirname(testFilePath), path)
+                    : resolve(path);
+                return buildClientOverlayDocument(entryPath, tsxConfig.props);
+            }
+            : () => readHtmlOverlayFile(path);
+        const renderOpts = awaitMount ? { awaitMount: true } : {};
         if (animate) {
-            return createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, overMouse, config.fps, configDurationMs, renderOpts);
+            return createAnimatedOverlayController(name, getDocument, placementSource, fullScreen, pinToScreen, overMouse, config.fps, configDurationMs, renderOpts);
         }
-        return createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, overMouse, configDurationMs, renderOpts);
+        return createRenderedOverlayController(name, getDocument, placementSource, fullScreen, pinToScreen, overMouse, configDurationMs, renderOpts);
     }
+    // Image/video file overlays never use `over` (rejected in
+    // resolvePlacementSource), so the source is always a concrete placement.
+    const placement = placementSource.kind === 'fixed'
+        ? placementSource.placement
+        : resolveOverlayPlacement(name, config);
     // File-backed image / video overlays.
     if (extension === '.svg' || extension === '.png') {
-        if (config.volume !== undefined) {
+        if (media.volume !== undefined) {
             throw new Error(`[screenci] Overlay "${name}" (${path}) is an image and must not provide volume. Use duration instead.`);
         }
-        if (config.crop !== undefined) {
-            validateCrop(`Overlay "${name}" (${path})`, config.crop);
+        if (media.crop !== undefined) {
+            validateCrop(`Overlay "${name}" (${path})`, media.crop);
         }
         registerAssetPath(path);
         return createFileOverlayController(name, {
@@ -366,24 +337,24 @@ function buildOverlayFromConfig(name, config) {
             ...(pinToScreen && { pinToScreen: true }),
             ...(overMouse && { overMouse: true }),
             ...(configDurationMs !== undefined && { durationMs: configDurationMs }),
-            ...(config.crop !== undefined && { crop: config.crop }),
+            ...(media.crop !== undefined && { crop: media.crop }),
         });
     }
     if (extension === '.mp4') {
         if (config.duration !== undefined) {
             throw new Error(`[screenci] Overlay "${name}" (${path}) is a video and must not provide duration. Its natural media duration is used instead.`);
         }
-        if (config.volume !== undefined &&
-            (!Number.isFinite(config.volume) ||
-                config.volume < 0 ||
-                config.volume > MAX_AUDIO_LEVEL)) {
+        if (media.volume !== undefined &&
+            (!Number.isFinite(media.volume) ||
+                media.volume < 0 ||
+                media.volume > MAX_AUDIO_LEVEL)) {
             throw new Error(`[screenci] Overlay "${name}" (${path}) must provide a finite volume between 0 and ${MAX_AUDIO_LEVEL} for .mp4 overlays. 1 is the natural level, 0 is silent, and values above 1 boost it.`);
         }
-        validateSpeedTime(`Overlay "${name}" (${path})`, config.speed, config.time);
-        if (config.crop !== undefined) {
-            validateCrop(`Overlay "${name}" (${path})`, config.crop);
+        validateSpeedTime(`Overlay "${name}" (${path})`, media.speed, media.time);
+        if (media.crop !== undefined) {
+            validateCrop(`Overlay "${name}" (${path})`, media.crop);
         }
-        const { sourceStart, sourceEnd } = resolveSourceTrim(`Overlay "${name}" (${path})`, config.start, config.end);
+        const { sourceStart, sourceEnd } = resolveSourceTrim(`Overlay "${name}" (${path})`, media.start, media.end);
         registerAssetPath(path);
         return createFileOverlayController(name, {
             kind: 'video',
@@ -392,161 +363,15 @@ function buildOverlayFromConfig(name, config) {
             fullScreen,
             ...(pinToScreen && { pinToScreen: true }),
             ...(overMouse && { overMouse: true }),
-            ...(config.volume !== undefined && { audio: config.volume }),
-            ...(config.speed !== undefined && { speed: config.speed }),
-            ...(config.time !== undefined && { time: config.time }),
-            ...(config.crop !== undefined && { crop: config.crop }),
+            ...(media.volume !== undefined && { audio: media.volume }),
+            ...(media.speed !== undefined && { speed: media.speed }),
+            ...(media.time !== undefined && { time: media.time }),
+            ...(media.crop !== undefined && { crop: media.crop }),
             ...(sourceStart !== undefined && { sourceStart }),
             ...(sourceEnd !== undefined && { sourceEnd }),
         });
     }
-    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.`);
-        }
-    }
-    validateSingleRootElement(name, html);
-}
-/**
- * HTML void elements: they never have a closing tag, so they do not open a
- * nesting level when counting top-level nodes.
- */
-const VOID_ELEMENTS = new Set([
-    'area',
-    'base',
-    'br',
-    'col',
-    'embed',
-    'hr',
-    'img',
-    'input',
-    'link',
-    'meta',
-    'param',
-    'source',
-    'track',
-    'wbr',
-]);
-/**
- * Ensures an inline `html` fragment has exactly one top-level (root) element and
- * no loose top-level text, so it wraps cleanly into screenci's overlay document
- * and sizes predictably. Multiple siblings (for example `<div/><div/>`) or stray
- * text outside the root are rejected. The markup inside the root may be anything,
- * including `<script>`/`<style>`, which are left to the overlay renderer.
- *
- * This is a lightweight tag scanner, not a full HTML parser: it tracks nesting
- * depth across opening, closing, void, and self-closing tags (skipping comments
- * and quoted attribute values) which covers ordinary fragment markup.
- */
-function validateSingleRootElement(name, html) {
-    const fail = () => {
-        throw new Error(`[screenci] Overlay "${name}" inline "html" must contain a single root element (for example '<div class="badge">New</div>'). Wrap multiple top-level nodes in one container.`);
-    };
-    // Drop comments so they never count as top-level content.
-    const stripped = html.replace(/<!--[\s\S]*?-->/g, '');
-    const tagRe = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
-    let depth = 0;
-    let rootElements = 0;
-    let lastIndex = 0;
-    let match;
-    while ((match = tagRe.exec(stripped)) !== null) {
-        const before = stripped.slice(lastIndex, match.index);
-        if (depth === 0 && before.trim().length > 0)
-            fail();
-        lastIndex = match.index + match[0].length;
-        const isClosing = match[1] === '/';
-        const tagName = match[2].toLowerCase();
-        const selfClosing = match[4] === '/';
-        if (isClosing) {
-            depth = Math.max(0, depth - 1);
-            continue;
-        }
-        if (depth === 0)
-            rootElements += 1;
-        if (!selfClosing && !VOID_ELEMENTS.has(tagName))
-            depth += 1;
-    }
-    if (stripped.slice(lastIndex).trim().length > 0 && depth === 0)
-        fail();
-    if (rootElements !== 1)
-        fail();
-}
-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);
+    throw new Error(`[screenci] Overlay "${name}" must use one of: .tsx, .html, .svg, .png, .mp4. Received: ${path}`);
 }
 async function readHtmlOverlayFile(path) {
     const testFilePath = getScreenCIRuntimeContext().testFilePath;
@@ -555,7 +380,7 @@ async function readHtmlOverlayFile(path) {
 }
 /**
  * Builds overlay controllers for Studio-managed overlays declared via
- * `video.studio({ overlays: [...] })`. Their file (`.svg`, `.png`, or `.mp4`),
+ * `video.overlays(editable([...]))`. Their file (`.svg`, `.png`, or `.mp4`),
  * placement, image duration, and video audio level are configured on the
  * ScreenCI Studio page instead of in code. Each name becomes a callable overlay
  * controller with the same timeline behavior as a {@link createOverlays}
@@ -609,13 +434,20 @@ function resolveOverlayAnchor(until) {
 }
 /**
  * Resolves a relative length string (`.for('2s')` or a config `duration`) into
- * milliseconds. Seconds and timecodes only: a percentage is rejected because a
- * relative length has nothing to take a percentage of (use `.until('<n>%')` for
- * an absolute position instead).
+ * milliseconds. Numbers are already milliseconds. String seconds and timecodes
+ * are accepted; a percentage is rejected because a relative length has nothing
+ * to take a percentage of (use `.until('<n>%')` for an absolute position
+ * instead).
  */
 function resolveRelativeDuration(value, label) {
+    if (typeof value === 'number') {
+        if (!isFiniteNonNegative(value)) {
+            throw new Error(`[screenci] ${label} must be a finite number of milliseconds greater than or equal to 0. Received: ${String(value)}.`);
+        }
+        return value;
+    }
     if (typeof value !== 'string') {
-        throw new Error(`[screenci] ${label} must be a time string such as '2s' or '0:02', got ${typeof value}.`);
+        throw new Error(`[screenci] ${label} must be a time string such as '2s' or '0:02', or a number of milliseconds, got ${typeof value}.`);
     }
     const parsed = parseTimelineOffset(value);
     if (parsed.kind === 'percent') {
@@ -623,7 +455,7 @@ function resolveRelativeDuration(value, label) {
     }
     return parsed.ms;
 }
-/** Parses an optional config `duration` (a relative time string) into ms. */
+/** Parses an optional config `duration` (relative time string or ms number) into ms. */
 function resolveConfigDuration(name, duration) {
     if (duration === undefined)
         return undefined;
@@ -775,14 +607,15 @@ 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.
+ * An overlay rendered to a transparent PNG at recording time, from either a full
+ * `.html` document or a bundled `.tsx` page. `getDocument` produces the full
+ * overlay document to rasterize.
  */
-function createRenderedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, overMouse, 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.
+function createRenderedOverlayController(name, getDocument, placementSource, fullScreen, pinToScreen, overMouse, durationMs, renderOpts = {}) {
+    // The document and placement are resolved during the test (cheap: a file read
+    // or an esbuild bundle, 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;
@@ -822,8 +655,7 @@ function createRenderedOverlayController(name, getMarkup, placementSource, fullS
                 kind: 'image',
                 name,
                 html: resolvedHtml,
-                css: resolveOverlayCss(renderOpts.css),
-                capturePadding: renderOpts.capturePadding ?? 0,
+                ...(renderOpts.awaitMount === true && { awaitMount: true }),
                 deviceScaleFactor: DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR,
             },
         });
@@ -840,16 +672,18 @@ function createRenderedOverlayController(name, getMarkup, placementSource, fullS
             }
             const { placement, sizePx } = await resolvePlacement(placementSource);
             resolvedPlacement = placement;
-            const markup = await getMarkup();
+            const document = await getDocument();
             resolvedHtml =
-                sizePx !== undefined ? sizeWrapMarkup(markup, sizePx) : markup;
+                sizePx !== undefined
+                    ? injectOverlayRootSize(document, sizePx)
+                    : document;
         },
     });
 }
 /**
  * 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
+ * config `duration`; `start()`/`end()` requires a config `duration` (the
  * capture length is otherwise unknown).
  *
  * Markup and duration are captured during the test; the clip itself is encoded
@@ -857,7 +691,7 @@ function createRenderedOverlayController(name, getMarkup, placementSource, fullS
  * the recording, the old "hide block" that cut capture wall-clock from the
  * timeline is no longer needed.
  */
-function createAnimatedOverlayController(name, getMarkup, placementSource, fullScreen, pinToScreen, overMouse, fps, configDurationMs, renderOpts = {}) {
+function createAnimatedOverlayController(name, getDocument, placementSource, fullScreen, pinToScreen, overMouse, fps, configDurationMs, renderOpts = {}) {
     let resolved;
     let skipped = false;
     const resolveDurationMs = (mode) => {
@@ -898,8 +732,7 @@ function createAnimatedOverlayController(name, getMarkup, placementSource, fullS
                 kind: 'animation',
                 name,
                 html: resolved.html,
-                css: resolveOverlayCss(renderOpts.css),
-                capturePadding: renderOpts.capturePadding ?? 0,
+                ...(renderOpts.awaitMount === true && { awaitMount: true }),
                 deviceScaleFactor: DEFAULT_OVERLAY_DEVICE_SCALE_FACTOR,
                 fps: fps ?? DEFAULT_ANIMATION_FPS,
                 durationMs: resolved.durationMs,
@@ -915,9 +748,11 @@ function createAnimatedOverlayController(name, getMarkup, placementSource, fullS
             }
             const durationMs = resolveDurationMs(mode);
             const { placement, sizePx } = await resolvePlacement(placementSource);
-            const markup = await getMarkup();
+            const document = await getDocument();
             resolved = {
-                html: sizePx !== undefined ? sizeWrapMarkup(markup, sizePx) : markup,
+                html: sizePx !== undefined
+                    ? injectOverlayRootSize(document, sizePx)
+                    : document,
                 durationMs,
                 ...(placement !== undefined && { placement }),
             };
@@ -929,7 +764,8 @@ function getAssetExtension(path) {
     if (dotIndex === -1)
         return null;
     const extension = path.slice(dotIndex).toLowerCase();
-    if (extension === '.html' ||
+    if (extension === '.tsx' ||
+        extension === '.html' ||
         extension === '.svg' ||
         extension === '.png' ||
         extension === '.mp4') {
@@ -1069,11 +905,8 @@ function resolvePlacementSource(name, config, flags) {
     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 (!flags.isRendered) {
+        throw new Error(`[screenci] Overlay "${name}" can only use "over" with a .html or .tsx page overlay (the overlay is sized to the element's box).`);
     }
     if (config.fill !== undefined) {
         throw new Error(`[screenci] Overlay "${name}" cannot set both "over" and "fill".`);
@@ -1113,13 +946,25 @@ async function resolvePlacement(source) {
     };
 }
 /**
- * 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%`).
+ * Injects a fixed CSS-pixel size for the overlay root into a full overlay
+ * document, so the rasterized PNG carries the element's box (used by `over`,
+ * which sizes the overlay to a locator). The renderer then lands it exactly on
+ * the element's box. The page's content should fill the root
+ * (`width:100%;height:100%`). Applied by inserting a `<style>` right after
+ * `<head>` (or at the start of the document if there is no head), sizing
+ * `#screenci-overlay-root` and falling back to `body`.
  */
-function sizeWrapMarkup(html, size) {
-    return `<div style="width:${size.width}px;height:${size.height}px;box-sizing:border-box">${html}</div>`;
+function injectOverlayRootSize(document, size) {
+    const style = `<style>html,body{margin:0}` +
+        `#screenci-overlay-root,body{` +
+        `width:${size.width}px;height:${size.height}px;box-sizing:border-box}` +
+        `</style>`;
+    const headMatch = /<head[^>]*>/i.exec(document);
+    if (headMatch !== null) {
+        const at = headMatch.index + headMatch[0].length;
+        return document.slice(0, at) + style + document.slice(at);
+    }
+    return style + document;
 }
 function toRecordedFileStart(name, resolved, mode) {
     if (resolved.kind === 'image') {