screenci 0.0.68 → 0.0.69

package/dist/e2e/htmlRasterizer.e2e.js

@@ -0,0 +1,107 @@
+import { test, expect } from '@playwright/test';
+import { mkdtemp, rm, readFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import ffmpegStatic from 'ffmpeg-static';
+import { rasterizeAnimatedHtmlOverlay, rasterizeHtmlOverlay, } from '../src/htmlRasterizer.js';
+import { createScreenCIRuntimeContext, runWithScreenCIRuntimeContext, } from '../src/runtimeContext.js';
+const PNG_SIGNATURE = Buffer.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+test('rasterizes HTML to a transparent PNG sized to its content', async ({ page, }) => {
+    const dir = await mkdtemp(join(tmpdir(), 'screenci-html-e2e-'));
+    try {
+        const result = await runWithScreenCIRuntimeContext(createScreenCIRuntimeContext({ page, recordingDir: dir }), () => rasterizeHtmlOverlay({
+            name: 'badge',
+            html: '<div style="width:200px;height:80px;background:#f00">hi</div>',
+        }));
+        // boundingBox is reported in CSS pixels (the underlying PNG is rendered at
+        // the device scale factor for crispness).
+        expect(result.width).toBe(200);
+        expect(result.height).toBe(80);
+        const buffer = await readFile(result.path);
+        expect(buffer.subarray(0, 8)).toEqual(PNG_SIGNATURE);
+        expect(buffer.length).toBeGreaterThan(0);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test('does not require a fixed viewport: content larger than the default viewport still renders', async ({ page, }) => {
+    const dir = await mkdtemp(join(tmpdir(), 'screenci-html-e2e-'));
+    try {
+        const result = await runWithScreenCIRuntimeContext(createScreenCIRuntimeContext({ page, recordingDir: dir }), () => rasterizeHtmlOverlay({
+            name: 'wide',
+            html: '<div style="width:640px;height:120px;background:#0a0"></div>',
+        }));
+        expect(result.width).toBe(640);
+        expect(result.height).toBe(120);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test('rasterizes an animated overlay to a two-stream transparent clip', async ({ page, }) => {
+    const dir = await mkdtemp(join(tmpdir(), 'screenci-anim-e2e-'));
+    try {
+        const result = await runWithScreenCIRuntimeContext(createScreenCIRuntimeContext({ page, recordingDir: dir }), () => rasterizeAnimatedHtmlOverlay({
+            name: 'intro',
+            html: '<div style="width:200px;height:80px;background:#f00;' +
+                'animation:fade 1s linear">hi' +
+                '<style>@keyframes fade{from{opacity:0}to{opacity:1}}</style></div>',
+            durationMs: 500,
+            fps: 30,
+        }));
+        expect(result.width).toBe(200);
+        expect(result.height).toBe(80);
+        expect(result.durationMs).toBe(500);
+        expect(result.path.endsWith('.mp4')).toBe(true);
+        const buffer = await readFile(result.path);
+        expect(buffer.length).toBeGreaterThan(0);
+        // The clip must carry two video streams: color + alpha matte.
+        const ffmpegPath = ffmpegStatic;
+        const probe = spawnSync(ffmpegPath, ['-hide_banner', '-i', result.path], {
+            encoding: 'utf8',
+        });
+        const info = `${probe.stdout ?? ''}${probe.stderr ?? ''}`;
+        const videoStreams = (info.match(/Stream #0:\d+.*Video:/g) ?? []).length;
+        expect(videoStreams).toBe(2);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test('applies injected css so overlays can be styled with className', async ({ page, }) => {
+    const dir = await mkdtemp(join(tmpdir(), 'screenci-css-e2e-'));
+    try {
+        const result = await runWithScreenCIRuntimeContext(createScreenCIRuntimeContext({ page, recordingDir: dir }), () => rasterizeHtmlOverlay({
+            name: 'card',
+            html: '<div class="box"></div>',
+            css: '.box{width:120px;height:60px;background:#f00}',
+        }));
+        // Without injected CSS the bare <div> would collapse; the className sizes it.
+        expect(result.width).toBe(120);
+        expect(result.height).toBe(60);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test('capturePadding grows the captured box around the content', async ({ page, }) => {
+    const dir = await mkdtemp(join(tmpdir(), 'screenci-pad-e2e-'));
+    try {
+        const result = await runWithScreenCIRuntimeContext(createScreenCIRuntimeContext({ page, recordingDir: dir }), () => rasterizeHtmlOverlay({
+            name: 'padded',
+            html: '<div style="width:200px;height:80px;background:#0a0"></div>',
+            capturePadding: 40,
+        }));
+        // 40px of transparent padding on every side: 200+80 x 80+80.
+        expect(result.width).toBe(280);
+        expect(result.height).toBe(160);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+//# sourceMappingURL=htmlRasterizer.e2e.js.map

package/dist/e2e/htmlRasterizer.e2e.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlRasterizer.e2e.js","sourceRoot":"","sources":["../../e2e/htmlRasterizer.e2e.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { AspectRatio, FPS, Quality, RecordUploadPolicy, RecordOptions, RenderOptions, ScreenCIConfig, ExtendedScreenCIConfig, AutoZoomOptions, Easing, } from './src/types.js';
+export type { AspectRatio, FPS, Quality, RecordUploadPolicy, RecordOptions, RenderOptions, ScreenCIConfig, ExtendedScreenCIConfig, AutoZoomOptions, Easing, VideoEncoderPreset, } from './src/types.js';
 export { voices, modelTypes } from './src/voices.js';
 export type { VoiceKey, ModelVoiceKey, ElevenLabsVoiceKey, CustomVoiceRef, ModelType, } from './src/voices.js';
 export { defineConfig } from './src/config.js';
@@ -13,7 +13,9 @@ export { speed } from './src/speed.js';
 export { time } from './src/time.js';
 export { autoZoom } from './src/autoZoom.js';
 export { zoomTo, resetZoom } from './src/manualZoom.js';
-export { createAssets, createStudioAssets } from './src/asset.js';
-export type { AssetController, AssetConfig, Assets, SvgPath, PngPath, Mp4Path, ImageAssetConfig, VideoAssetConfig, } from './src/asset.js';
+export { createOverlays, createStudioOverlays, setOverlayCss, MAX_AUDIO_LEVEL, } from './src/asset.js';
+export type { OverlayController, OverlayConfig, OverlayInput, Overlays, ReactElementLike, OverlayPlacement, } from './src/asset.js';
+export { createAudio, createStudioAudio } from './src/audio.js';
+export type { AudioController, AudioConfig, AudioInput, AudioTracks, } from './src/audio.js';
 export type { ZoomTarget, ZoomTargetPoint } from './src/manualZoom.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,GAAG,EACH,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,MAAM,GACP,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACpD,YAAY,EACV,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACrE,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAC9E,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACjE,YAAY,EACV,eAAe,EACf,WAAW,EACX,MAAM,EACN,OAAO,EACP,OAAO,EACP,OAAO,EACP,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,GAAG,EACH,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,MAAM,EACN,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACpD,YAAY,EACV,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACrE,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAC9E,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,eAAe,GAChB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAC/D,YAAY,EACV,eAAe,EACf,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -11,5 +11,6 @@ export { speed } from './src/speed.js';
 export { time } from './src/time.js';
 export { autoZoom } from './src/autoZoom.js';
 export { zoomTo, resetZoom } from './src/manualZoom.js';
-export { createAssets, createStudioAssets } from './src/asset.js';
+export { createOverlays, createStudioOverlays, setOverlayCss, MAX_AUDIO_LEVEL, } from './src/asset.js';
+export { createAudio, createStudioAudio } from './src/audio.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAcA,mBAAmB;AACnB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AASpD,4BAA4B;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,4CAA4C;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAErE,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE9E,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAeA,mBAAmB;AACnB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AASpD,4BAA4B;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,4CAA4C;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAErE,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAE9E,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,eAAe,GAChB,MAAM,gBAAgB,CAAA;AASvB,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/src/asset.d.ts

@@ -1,85 +1,174 @@
 import type { IEventRecorder } from './events.js';
-export type SvgPath = `${string}.svg`;
-export type PngPath = `${string}.png`;
-export type Mp4Path = `${string}.mp4`;
+export { setOverlayCss } from './htmlRasterizer.js';
+export type { OverlayPlacement } from './events.js';
 /**
- * Image assets are timed overlays. The duration must be recorded up front so
- * rendering never needs to probe image files for timing.
+ * Minimal structural stand-in for a React element. Defined here so the core SDK
+ * never has to depend on `@types/react`: any JSX element is assignable to this,
+ * while a plain {@link OverlayConfig} object is not (it has no `type`/`props`).
+ * React itself is detected structurally at runtime and rendered lazily, so it
+ * stays an optional peer dependency.
  */
-export type ImageAssetConfig<TPath extends SvgPath | PngPath = SvgPath | PngPath> = {
-    path: TPath;
-    durationMs: number;
-    fullScreen: boolean;
-    audio?: never;
+export type ReactElementLike = {
+    type: unknown;
+    props: unknown;
+    key?: string | null;
 };
 /**
- * Video assets use their natural media duration. Audio is allowed only here so
- * the API cannot attach soundtrack controls to still-image overlays. When
- * omitted, audio defaults to full volume for `.mp4` playback.
+ * Display options for an overlay. Placement fields are flat (not nested) and
+ * each defaults independently: `relativeTo: 'recording'`, `x: 0`, `y: 0`, and
+ * `width: 1` when neither `width` nor `height` is given. The default box fills
+ * the recording area, whose final size is chosen later in the studio.
  */
-export type VideoAssetConfig<TPath extends Mp4Path = Mp4Path> = {
-    path: TPath;
+export type OverlayConfig = {
+    /** File path: `.html` (rendered), `.svg`/`.png` (image), or `.mp4` (video). */
+    path?: string;
+    /** A React element, rendered to a transparent PNG. Mutually exclusive with `path`. */
+    element?: ReactElementLike;
+    /** Reference box for placement coordinates. Defaults to `'recording'`. */
+    relativeTo?: 'screen' | 'recording';
+    /** Left edge as a 0..1 fraction of the reference box. Defaults to `0`. */
+    x?: number;
+    /** Top edge as a 0..1 fraction of the reference box. Defaults to `0`. */
+    y?: number;
+    /** Width as a 0..1 fraction. Defaults to `1` when `height` is not set. */
+    width?: number;
+    /** Height as a 0..1 fraction. Provide instead of `width` (exactly one). */
+    height?: number;
+    /** Fill the whole output frame. Overrides x/y/width/height. */
+    fullScreen?: boolean;
+    /**
+     * Visible length for the blocking call form (`await overlays.logo(1200)`).
+     * Omit when driving with `start()`/`end()`. Image/HTML/React overlays only.
+     *
+     * For animated overlays (`animate: true`) this is also the capture length: it
+     * is required when driving with `start()`/`end()` (the capture length is
+     * otherwise unknown).
+     */
+    durationMs?: number;
+    /**
+     * Capture the overlay as an animation so its CSS/JS animation plays back in
+     * the video (HTML files and React elements only). The animation is sampled
+     * over the resolved duration with a transparent background preserved.
+     */
+    animate?: boolean;
+    /** Animation capture frame rate. Only valid with `animate`. Defaults to `30`. */
+    fps?: number;
+    /**
+     * Extra CSS injected into the overlay document so it can be styled with
+     * `className` (for example a compiled Tailwind stylesheet). Merged on top of
+     * any global CSS set via `setOverlayCss`. HTML files and React elements only.
+     */
+    css?: string;
+    /**
+     * Transparent padding (CSS px) added around the overlay content. Lets an
+     * animation move, scale, or rotate beyond its box without being clipped (an
+     * automatic "stage"), at the cost of the placement sizing the padded box.
+     * HTML files and React elements only.
+     */
+    capturePadding?: number;
+    /**
+     * Soundtrack level for `.mp4` overlays as a linear gain. `1` (the default)
+     * plays the source at its natural level, `0` mutes it, and values above `1`
+     * boost it (e.g. `2` is twice the natural level). Capped at
+     * {@link MAX_AUDIO_LEVEL}.
+     */
     audio?: number;
-    fullScreen: boolean;
-    durationMs?: never;
 };
-export type AssetConfig = ImageAssetConfig<SvgPath | PngPath> | VideoAssetConfig<Mp4Path>;
-type AssetConfigForPath<TPath extends string> = string extends TPath ? AssetConfig : TPath extends SvgPath | PngPath ? ImageAssetConfig<TPath> : TPath extends Mp4Path ? VideoAssetConfig<TPath> : never;
+/**
+ * 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 declare const MAX_AUDIO_LEVEL = 4;
+/**
+ * A value accepted by {@link createOverlays} for each key:
+ *
+ * - a `string` file path (`.html`/`.svg`/`.png`/`.mp4`),
+ * - a React element, or
+ * - an {@link OverlayConfig} object.
+ */
+export type OverlayInput = string | ReactElementLike | OverlayConfig;
+export declare function setAssetSleepFn(fn: (ms: number) => void): void;
 export declare function setActiveAssetRecorder(recorder: IEventRecorder | null): void;
 export declare function resetRegisteredAssetPaths(): void;
+export declare function resetAssetChain(): void;
 export declare function validateRegisteredAssetPaths(testFilePath: string): Promise<void>;
 /**
- * An asset controller.
+ * An overlay controller.
+ *
+ * Calling it shows the overlay over a frozen frame for a fixed duration
+ * (blocking). Use `start()`/`end()` to keep the overlay on screen while the page
+ * is driven underneath.
  *
- * Calling it marks the asset in the recording timeline. The renderer places
- * the asset at this point in the video. Images use explicit `durationMs`
- * overlays; `.mp4` assets use the media file's natural duration.
+ * Overlays may overlap: several can be live at once (interleaved, not just
+ * nested), and a blocking overlay can run while others stay live. Each overlay
+ * you `start()` must be `end()`ed before the video function returns, and the
+ * same overlay cannot be started twice without ending it in between.
  *
  * @example
  * ```ts
- * await assets.intro()
- * await page.goto('/dashboard')
- * await assets.logo()
+ * // Blocking: hold the overlay for 1.2s, then continue.
+ * await overlays.logo(1200)
+ *
+ * // Live: keep the overlay up while interacting with the page.
+ * await overlays.badge.start()
+ * await page.click('#next')
+ * await overlays.badge.end()
+ *
+ * // Overlapping: two overlays live at the same time, ended independently.
+ * await overlays.badge.start()
+ * await overlays.logo.start()
+ * await page.click('#next')
+ * await overlays.badge.end()
+ * await overlays.logo.end()
  * ```
  */
-export type AssetController = () => Promise<void>;
-/** Typed asset controllers keyed by the names passed to {@link createAssets}. */
-export type Assets<T extends Record<string, AssetConfig>> = {
-    [K in keyof T]: AssetController;
+export type OverlayController = {
+    (durationMs?: number): Promise<void>;
+    start(): Promise<void>;
+    end(): Promise<void>;
+};
+/** Typed overlay controllers keyed by the names passed to {@link createOverlays}. */
+export type Overlays<T extends Record<string, OverlayInput>> = {
+    [K in keyof T]: OverlayController;
 };
 /**
- * Creates a set of typed asset controllers, one per key in the map.
+ * Creates a set of typed overlay controllers, one per key in the map. Each value
+ * is a file path string, a React element, or an {@link OverlayConfig} object.
  *
- * Calling a controller 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',
+ * x: 0, y: 0, width: 1`); override any field independently.
  *
  * @example
- * ```ts
- * const assets = createAssets({
- *   logo:  { path: './logo.png',  durationMs: 1200, fullScreen: false },
- *   intro: { path: './intro.mp4', fullScreen: true },
+ * ```tsx
+ * const overlays = createOverlays({
+ *   hint:  'callout.html',                       // HTML file
+ *   badge: <Badge label="New" />,                // React element
+ *   logo:  { path: 'logo.png', x: 0.05, y: 0.05, width: 0.2 },
+ *   intro: { path: 'intro.mp4', fullScreen: true },
  * })
  *
  * video('Product demo', async ({ page }) => {
- *   await assets.intro()
+ *   await overlays.intro()
  *   await page.goto('/dashboard')
- *   await assets.logo()
+ *   await overlays.logo(1200)
  * })
  * ```
  */
-export declare function createAssets<const T extends Record<string, AssetConfig>>(assetsMap: T & {
-    [K in keyof T]: AssetConfigForPath<T[K]['path']>;
-}): Assets<T>;
+export declare function createOverlays<const T extends Record<string, OverlayInput>>(overlays: T): Overlays<T>;
 /**
- * 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
@@ -87,15 +176,14 @@ export declare function createAssets<const T extends Record<string, AssetConfig>
  *
  * @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 declare function createStudioAssets<const K extends readonly [string, ...string[]]>(...keys: K): Record<K[number], AssetController>;
-export {};
+export declare function createStudioOverlays<const K extends readonly [string, ...string[]]>(...keys: K): Record<K[number], OverlayController>;
 //# sourceMappingURL=asset.d.ts.map

package/dist/src/asset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../../src/asset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AASjD,MAAM,MAAM,OAAO,GAAG,GAAG,MAAM,MAAM,CAAA;AACrC,MAAM,MAAM,OAAO,GAAG,GAAG,MAAM,MAAM,CAAA;AACrC,MAAM,MAAM,OAAO,GAAG,GAAG,MAAM,MAAM,CAAA;AAErC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,IACjD;IACF,IAAI,EAAE,KAAK,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,IAAI;IAC9D,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,WAAW,GACnB,gBAAgB,CAAC,OAAO,GAAG,OAAO,CAAC,GACnC,gBAAgB,CAAC,OAAO,CAAC,CAAA;AAE7B,KAAK,kBAAkB,CAAC,KAAK,SAAS,MAAM,IAAI,MAAM,SAAS,KAAK,GAChE,WAAW,GACX,KAAK,SAAS,OAAO,GAAG,OAAO,GAC7B,gBAAgB,CAAC,KAAK,CAAC,GACvB,KAAK,SAAS,OAAO,GACnB,gBAAgB,CAAC,KAAK,CAAC,GACvB,KAAK,CAAA;AAIb,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAE5E;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAIf;AAuBD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;AAEjD,iFAAiF;AACjF,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI;KACzD,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACtE,SAAS,EAAE,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;CAAE,GAClE,MAAM,CAAC,CAAC,CAAC,CAWX;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EAC9C,GAAG,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,CAgBhD"}
+{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../../src/asset.ts"],"names":[],"mappings":"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"}