middlewright 0.1.0 → 0.1.2

package/dist/plugins/video-mode.d.ts

@@ -1,11 +1,91 @@
 import type { Plugin, OverrideableMethod } from "../plugin-system.ts";
+export type VideoModeSpan = {
+    start: number;
+    end: number;
+};
+export type VideoModeOutputs = {
+    player?: string;
+    raw?: string;
+    rendered?: string;
+};
+export type VideoModeOutputPaths = {
+    metadata: string;
+    player: string;
+    raw: string;
+    rendered: string;
+    reportPlayer: string;
+};
+export type VideoModeSourceRange = {
+    start?: number;
+    end?: number;
+};
+export type VideoModeRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type VideoModeViewport = {
+    width: number;
+    height: number;
+};
+export type VideoModeHighlight = VideoModeSpan & {
+    actionEnd?: number;
+    color: string;
+    image?: string;
+    method?: OverrideableMethod;
+    rect: VideoModeRect;
+    thickness: number;
+    viewport: VideoModeViewport;
+};
+export type VideoModeMetadata = {
+    schemaVersion: 1;
+    timebase: "ms";
+    deadAir: VideoModeSpan[];
+    highlights: VideoModeHighlight[];
+    outputs: VideoModeOutputs;
+    sourceRange: VideoModeSourceRange;
+};
+export type VideoModeControls = {
+    /**
+     * Run invisible video bookkeeping and write the elapsed span as dead air.
+     */
+    deadAir<T>(action: () => Promise<T>): Promise<T>;
+    /** Milliseconds since video-mode started recording metadata for this test. */
+    getVideoTimestamp(): number;
+    /** Parsed video-mode metadata JSON after the test, or the current in-memory snapshot during the test. */
+    metadata(): Promise<VideoModeMetadata>;
+    /** Absolute artifact paths for the current test's video-mode outputs. */
+    outputPaths(): VideoModeOutputPaths;
+    /** Render the video from this source timestamp, in ms. Defaults to the current video timestamp. */
+    setStartTime(ms?: number): void;
+    /** Render the video until this source timestamp, in ms. Defaults to the current video timestamp. */
+    setEndTime(ms?: number): void;
+};
+export type VideoModePageExtension = {
+    videoMode: VideoModeControls;
+};
+export type VideoModePlugin = Plugin<VideoModePageExtension> & VideoModeControls;
+export type VideoModeOutlineHighlightStyle = `${number}px solid ${string}`;
+export type VideoModeHighlightOptions = boolean | {
+    /** Highlight duration in the rendered video (ms). Default: 1000 */
+    duration?: number;
+    mode: "pointer";
+} | {
+    /** Highlight duration in the rendered video (ms). Default: 1000 */
+    duration?: number;
+    mode: "outline";
+    /** Outline style for the rendered video. Default: '3px solid gold' */
+    style?: VideoModeOutlineHighlightStyle;
+};
 export type VideoModeOptions = {
-    /** Pause duration before action (ms). Default: 1000 */
-    pauseBefore?: number;
-    /** Pause duration after test (ms). Default: 3000 */
-    pauseAfterTest?: number;
-    /** Highlight style. Default: '3px solid gold' */
-    highlightStyle?: string;
+    /**
+     * Render action annotations. `true` uses pointer mode with default options.
+     * Default: true
+     */
+    highlight?: VideoModeHighlightOptions;
+    /** Final hold duration in the rendered video (ms). Default: 3000 */
+    finalHold?: number;
     /** Methods to skip highlighting. Default: ['waitFor'] */
     skipMethods?: OverrideableMethod[];
     /**
@@ -14,9 +94,29 @@ export type VideoModeOptions = {
      * flows that shouldn't be slowed down. Default: []
      */
     skipStackFrames?: string[];
+    /**
+     * Maximum rendered duration for each dead-air span. Longer spans are sped up
+     * so they fit within this duration.
+     */
+    deadAirThreshold?: number;
+    /**
+     * Where the rendered video starts, trimming the blank "startup" lead-in
+     * (about:blank, the loading shell, the pre-hydration app frame) so it opens on
+     * real content instead of a white screen. An explicit `setStartTime()` always
+     * wins over this.
+     *
+     * - `"auto"` (default): pick a sensible strategy — currently the blank
+     *   detector below. Chosen so consumers get lead-in trimming just by upgrading.
+     * - `"detect-blank"`: find where the leading blank frames end in the recorded
+     *   pixels (the first frame that differs from the opening frame) and start
+     *   there, when that lead-in is long enough to be worth trimming.
+     * - `["selector", css]`: start the moment `css` first becomes visible (waited
+     *   for live, once); falls back to blank detection if it never appears.
+     * - `"never"`: don't trim. Use this for a video whose exact frames you assert
+     *   on, since trimming shifts the timeline.
+     */
+    trimStart?: VideoModeTrimStart;
 };
-/**
- * Highlights elements before actions and pauses for video recording.
- * Also pauses after tests complete for better video endings.
- */
-export declare const videoMode: (options?: VideoModeOptions) => Plugin;
+export type VideoModeTrimStart = "auto" | "detect-blank" | "never" | ["selector", string];
+/** Records video-mode facts and renders annotations into the recorded video. */
+export declare const videoMode: (options?: VideoModeOptions) => VideoModePlugin;