@aiscene/core 9.0.6 → 9.0.8

package/dist/types/ai-model/workflows/recorder-generation/common.d.ts

@@ -0,0 +1,89 @@
+import { type MidsceneRecorderEvent, type MidsceneRecorderMarkdownScreenshotAsset, type MidsceneRecorderSemantic, type MidsceneRecorderTarget } from '@aiscene/shared/recorder';
+export interface EventCounts {
+    navigation: number;
+    click: number;
+    input: number;
+    scroll: number;
+    total: number;
+}
+export interface InputDescription {
+    description: string;
+    value: string;
+}
+export interface ProcessedEvent {
+    hashId: string;
+    type: string;
+    timestamp: number;
+    source?: string;
+    actionType?: string;
+    url?: string;
+    title?: string;
+    semantic?: MidsceneRecorderSemantic;
+    description?: string;
+    value?: string;
+    typedText?: string;
+    inputIndex?: number;
+    isSequentialInput?: boolean;
+    hasNeighborInput?: boolean;
+    previousInputDescription?: string;
+    previousActionDescription?: string;
+    nextActionDescription?: string;
+    neighborInputValues?: string[];
+    pageInfo?: any;
+    elementRect?: any;
+    screenshotPath?: string;
+}
+export interface EventSummary {
+    testName: string;
+    startUrl: string;
+    eventCounts: EventCounts;
+    urls: string[];
+    clickDescriptions: string[];
+    inputDescriptions: InputDescription[];
+    events: ProcessedEvent[];
+}
+export interface RecorderGenerationContext {
+    summary: EventSummary;
+    screenshotAssets: MidsceneRecorderMarkdownScreenshotAsset[];
+}
+export type ChromeRecordedEvent = MidsceneRecorderEvent;
+export interface RecorderGenerationOptions {
+    testName?: string;
+    includeTimestamps?: boolean;
+    maxScreenshots?: number;
+    description?: string;
+    /** Language for human-readable generated content (e.g. 'English', 'Chinese'). Keys and API names are kept as-is. */
+    language?: string;
+    navigationInfo?: {
+        urls?: string[];
+        titles?: string[];
+        initialViewport?: {
+            width?: number;
+            height?: number;
+        };
+    };
+}
+export interface RecorderGenerationInput extends RecorderGenerationOptions {
+    target: MidsceneRecorderTarget;
+    events: MidsceneRecorderEvent[];
+}
+export interface FilteredEvents {
+    navigationEvents: ChromeRecordedEvent[];
+    clickEvents: ChromeRecordedEvent[];
+    inputEvents: ChromeRecordedEvent[];
+    scrollEvents: ChromeRecordedEvent[];
+}
+export declare function compactRecorderSemanticForGeneration(semantic?: MidsceneRecorderSemantic): MidsceneRecorderSemantic | undefined;
+export declare const validateEvents: (events: ChromeRecordedEvent[]) => void;
+export declare const getScreenshotsForLLM: (events: ChromeRecordedEvent[], maxScreenshots?: number) => string[];
+export declare const filterEventsByType: (events: ChromeRecordedEvent[]) => FilteredEvents;
+export declare const createEventCounts: (filteredEvents: FilteredEvents, totalEvents: number) => EventCounts;
+export declare const extractInputDescriptions: (inputEvents: ChromeRecordedEvent[]) => InputDescription[];
+export declare const processEventsForLLM: (events: ChromeRecordedEvent[], screenshotPathByEventHash?: Map<string, string>) => ProcessedEvent[];
+export declare const prepareEventSummary: (events: ChromeRecordedEvent[], options?: {
+    testName?: string;
+    maxScreenshots?: number;
+    screenshotPathByEventHash?: Map<string, string>;
+}) => EventSummary;
+export declare function prepareRecorderGenerationContext(input: RecorderGenerationInput): RecorderGenerationContext;
+export declare const createMessageContent: (promptText: string, screenshots?: string[], includeScreenshots?: boolean) => any[];

package/dist/types/ai-model/workflows/recorder-generation/index.d.ts

@@ -0,0 +1,7 @@
+export { generatePlaywrightTest, generatePlaywrightTestStream, } from './playwright';
+export { convertRecordLogIntoMarkdown, createRecorderMarkdownReplayPrompt, generateRecorderMarkdownReplay, } from './markdown';
+export { generateRecorderSessionMetadata } from './metadata';
+export { generateRecorderYamlTest, generateRecorderYamlTestStream, generateYamlTest, generateYamlTestStream, } from './yaml';
+export type { RecorderMarkdownGenerationInput } from './markdown';
+export type { RecorderGeneratedMetadata, RecorderMetadataGenerationInput, } from './metadata';
+export type { RecorderYamlGenerationInput, YamlGenerationOptions, } from './yaml';

package/dist/types/ai-model/workflows/recorder-generation/markdown.d.ts

@@ -0,0 +1,7 @@
+import type { IModelConfig } from '@aiscene/shared/env';
+import type { ChatCompletionMessageParam } from 'openai/resources/index';
+import { type RecorderGenerationInput } from './common';
+export type RecorderMarkdownGenerationInput = RecorderGenerationInput;
+export declare function createRecorderMarkdownReplayPrompt(input: RecorderMarkdownGenerationInput): ChatCompletionMessageParam[];
+export declare function generateRecorderMarkdownReplay(input: RecorderMarkdownGenerationInput, modelConfig: IModelConfig): Promise<string>;
+export declare function convertRecordLogIntoMarkdown(log: RecorderMarkdownGenerationInput, modelConfig: IModelConfig): Promise<string>;

package/dist/types/ai-model/workflows/recorder-generation/metadata.d.ts

@@ -0,0 +1,13 @@
+import type { IModelConfig } from '@aiscene/shared/env';
+import { type MidsceneRecorderEvent, type MidsceneRecorderTarget } from '@aiscene/shared/recorder';
+export interface RecorderMetadataGenerationInput {
+    target: MidsceneRecorderTarget;
+    events: MidsceneRecorderEvent[];
+    fallbackName?: string;
+    maxScreenshots?: number;
+}
+export interface RecorderGeneratedMetadata {
+    title?: string;
+    description?: string;
+}
+export declare function generateRecorderSessionMetadata(input: RecorderMetadataGenerationInput, modelConfig: IModelConfig): Promise<RecorderGeneratedMetadata>;

package/dist/types/ai-model/workflows/recorder-generation/playwright.d.ts

@@ -0,0 +1,26 @@
+import type { StreamingAIResponse, StreamingCodeGenerationOptions } from '../../../types';
+import type { IModelConfig } from '@aiscene/shared/env';
+import { type ChromeRecordedEvent, type EventCounts, type EventSummary, type InputDescription, type ProcessedEvent, createEventCounts, createMessageContent, extractInputDescriptions, filterEventsByType, getScreenshotsForLLM, prepareEventSummary, processEventsForLLM, validateEvents } from './common';
+export interface PlaywrightGenerationOptions {
+    testName?: string;
+    includeScreenshots?: boolean;
+    includeTimestamps?: boolean;
+    maxScreenshots?: number;
+    description?: string;
+    viewportSize?: {
+        width: number;
+        height: number;
+    };
+    waitForNetworkIdle?: boolean;
+    waitForNetworkIdleTimeout?: number;
+}
+export type { ChromeRecordedEvent, EventCounts, InputDescription, ProcessedEvent, EventSummary, };
+export { getScreenshotsForLLM, filterEventsByType, createEventCounts, extractInputDescriptions, processEventsForLLM, prepareEventSummary, createMessageContent, validateEvents, };
+/**
+ * Generates Playwright test code from recorded events
+ */
+export declare const generatePlaywrightTest: (events: ChromeRecordedEvent[], options: PlaywrightGenerationOptions, modelConfig: IModelConfig) => Promise<string>;
+/**
+ * Generates Playwright test code from recorded events with streaming support
+ */
+export declare const generatePlaywrightTestStream: (events: ChromeRecordedEvent[], options: PlaywrightGenerationOptions & StreamingCodeGenerationOptions, modelConfig: IModelConfig) => Promise<StreamingAIResponse>;

package/dist/types/ai-model/workflows/recorder-generation/yaml.d.ts

@@ -0,0 +1,17 @@
+import type { StreamingAIResponse, StreamingCodeGenerationOptions } from '../../../types';
+import type { IModelConfig } from '@aiscene/shared/env';
+import { type ChromeRecordedEvent, type EventCounts, type EventSummary, type FilteredEvents, type InputDescription, type ProcessedEvent, type RecorderGenerationContext, type RecorderGenerationInput, type RecorderGenerationOptions, createEventCounts, createMessageContent, extractInputDescriptions, filterEventsByType, getScreenshotsForLLM, prepareEventSummary, prepareRecorderGenerationContext, processEventsForLLM, validateEvents } from './common';
+export type YamlGenerationOptions = RecorderGenerationOptions;
+export type RecorderYamlGenerationInput = RecorderGenerationInput;
+export type { ChromeRecordedEvent, EventCounts, EventSummary, FilteredEvents, InputDescription, ProcessedEvent, RecorderGenerationContext, };
+export { createEventCounts, createMessageContent, extractInputDescriptions, filterEventsByType, getScreenshotsForLLM, prepareEventSummary, prepareRecorderGenerationContext, processEventsForLLM, validateEvents, };
+export declare const generateRecorderYamlTest: (input: RecorderYamlGenerationInput, modelConfig: IModelConfig) => Promise<string>;
+export declare const generateRecorderYamlTestStream: (input: RecorderYamlGenerationInput, options: StreamingCodeGenerationOptions, modelConfig: IModelConfig) => Promise<StreamingAIResponse>;
+/**
+ * Generates YAML test configuration from recorded events using AI
+ */
+export declare const generateYamlTest: (events: ChromeRecordedEvent[], options: YamlGenerationOptions, modelConfig: IModelConfig) => Promise<string>;
+/**
+ * Generates YAML test configuration from recorded events using AI with streaming support
+ */
+export declare const generateYamlTestStream: (events: ChromeRecordedEvent[], options: YamlGenerationOptions & StreamingCodeGenerationOptions, modelConfig: IModelConfig) => Promise<StreamingAIResponse>;

package/dist/types/common.d.ts

@@ -260,6 +260,8 @@ export declare const getMidsceneLocationSchema: () => z.ZodObject<{
     xpath: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
 }, z.ZodTypeAny, "passthrough">>;
 export declare const ifMidsceneLocatorField: (field: any) => boolean;
+export declare const userPromptToString: (prompt: TUserPrompt) => string;
+export declare const userPromptToMultimodalPrompt: (prompt: TUserPrompt) => TMultimodalPrompt | undefined;
 export declare const dumpMidsceneLocatorField: (field: any) => string;
 export declare const findAllMidsceneLocatorField: (zodType?: z.ZodType<any>, requiredOnly?: boolean) => string[];
 export declare const dumpActionParam: (jsonObject: Record<string, any>, zodSchema: z.ZodType<any>) => Record<string, any>;

package/dist/types/constants.d.ts

@@ -0,0 +1 @@
+export declare const IS_REPORT_BUILD: boolean;

package/dist/types/device/index.d.ts

@@ -6,6 +6,10 @@ import type { ElementCacheFeature, Rect, Size } from '../types';
 export interface FileChooserHandler {
     accept(files: string[]): Promise<void>;
 }
+export interface FileChooserRegistration {
+    dispose: () => void;
+    getError: () => Error | undefined | Promise<Error | undefined>;
+}
 export interface MjpegStreamFrame {
     /** Raw base64-encoded image bytes WITHOUT a `data:image/...;base64,` prefix. */
     data: string;
@@ -19,6 +23,15 @@ export interface MjpegStreamOptions {
     onFrame(frame: MjpegStreamFrame): void;
     onError?(error: unknown): void;
 }
+export interface DeviceFrameRef {
+    ref: unknown;
+    capturedAt: number;
+}
+export interface DeviceFrameSource {
+    latest(): DeviceFrameRef | null;
+    decode(refs: DeviceFrameRef[]): Promise<string[]>;
+    stop(): Promise<void> | void;
+}
 /** A point in device-pixel coordinates on the screen. */
 export interface PointerPoint {
     x: number;
@@ -124,10 +137,7 @@ export declare abstract class AbstractInterface {
     abstract describe?(): string;
     abstract beforeInvokeAction?(actionName: string, param: any): Promise<void>;
     abstract afterInvokeAction?(actionName: string, param: any): Promise<void>;
-    registerFileChooserListener?(handler: (chooser: FileChooserHandler) => Promise<void>): Promise<{
-        dispose: () => void;
-        getError: () => Error | undefined;
-    }>;
+    registerFileChooserListener?(handler: (chooser: FileChooserHandler) => Promise<void>): Promise<FileChooserRegistration>;
     abstract getElementsNodeTree?: () => Promise<ElementNode>;
     abstract url?: () => string | Promise<string>;
     abstract evaluateJavaScript?<T = any>(script: string): Promise<T>;
@@ -139,6 +149,7 @@ export declare abstract class AbstractInterface {
     getDeviceLocalTimeString?(format?: string): Promise<string>;
     /** URL of native MJPEG stream for real-time screen preview (e.g. WDA MJPEG server) */
     mjpegStreamUrl?: string;
+    openFrameSource?(): Promise<DeviceFrameSource | undefined>;
     /**
      * Optional in-process MJPEG frame producer. Implementations can push raw
      * base64 frames here when there is no standalone native MJPEG URL, e.g.

package/dist/types/device/input-strategy.d.ts

@@ -0,0 +1,44 @@
+/** Supported strategies for sending text through a platform input backend. */
+export declare const inputStrategies: readonly ["legacy", "sequential", "bulk"];
+/**
+ * `legacy` preserves the platform's pre-existing behavior, `sequential` sends
+ * one Unicode code point per Midscene backend call, and `bulk` sends the full
+ * value in one backend call where supported.
+ */
+export type InputStrategy = (typeof inputStrategies)[number];
+/** Input fields that may be configured at action or platform level. */
+export type TextInputOptions = {
+    keyboardTypeDelay?: number;
+    inputStrategy?: InputStrategy;
+};
+/** Effective text input configuration after layered defaults are resolved. */
+export type ResolvedTextInputOptions = {
+    keyboardTypeDelay?: number;
+    inputStrategy: InputStrategy;
+};
+/** Platform callbacks used to send text one Unicode code point at a time. */
+export type SequentialTextInputHandlers = {
+    sendCharacter: (character: string) => unknown;
+    wait: (delayMs: number) => unknown;
+};
+/**
+ * Resolve an input strategy and reject combinations whose intent conflicts.
+ * Prefer `resolveTextInputOptions` when both action and platform defaults exist.
+ */
+export declare function resolveInputStrategy(inputStrategy: InputStrategy | undefined, keyboardTypeDelay?: number): InputStrategy;
+/** Resolve action-level text input options over platform-level defaults. */
+export declare function resolveTextInputOptions(actionOptions?: TextInputOptions, platformDefaults?: TextInputOptions): ResolvedTextInputOptions;
+/**
+ * Whether resolved options require Midscene to send Unicode code points
+ * separately.
+ */
+export declare function shouldInputSequentially({ inputStrategy, keyboardTypeDelay, }: ResolvedTextInputOptions): boolean;
+/**
+ * Send text one Unicode code point at a time with one canonical delay policy.
+ * `delayAfterLast` exists only for platforms whose legacy behavior included a
+ * trailing delay; explicit sequential input should leave it disabled.
+ */
+export declare function sendTextSequentially(text: string, handlers: SequentialTextInputHandlers, options?: {
+    delayMs?: number;
+    delayAfterLast?: boolean;
+}): Promise<void>;

package/dist/types/dump/html-utils.d.ts

@@ -35,6 +35,7 @@ export declare function extractImageByIdSync(htmlPath: string, imageId: string):
  * @param destFilePath - Destination file path to append to
  */
 export declare function streamImageScriptsToFile(srcFilePath: string, destFilePath: string): void;
+export declare function collectImageScriptIds(filePath: string): Promise<Set<string>>;
 /**
  * Extract the LAST dump script content from HTML file using streaming.
  * Memory usage: O(dump_size), not O(file_size).

package/dist/types/dump/image-reference.d.ts

@@ -0,0 +1,36 @@
+/** Serialized reference to a captured screenshot stored by a report. */
+export interface ScreenshotRef {
+    type: 'midscene_screenshot_ref';
+    id: string;
+    capturedAt: number;
+    mimeType: 'image/png' | 'image/jpeg';
+    storage: 'inline' | 'file';
+    path?: string;
+}
+/** Serialized reference to a multimodal prompt image URL stored by a report. */
+export interface ImageUrlRef {
+    type: 'midscene_image_url_ref';
+    id: string;
+    mimeType: `image/${string}`;
+    storage: 'inline' | 'file';
+    path?: string;
+}
+/** Any image asset reference supported by report serialization. */
+export type StoredImageRef = ScreenshotRef | ImageUrlRef;
+/** Validate and normalize a serialized screenshot reference. */
+export declare function normalizeScreenshotRef(value: unknown): ScreenshotRef | null;
+/** Validate and normalize a serialized multimodal prompt image reference. */
+export declare function normalizeImageUrlRef(value: unknown): ImageUrlRef | null;
+/** Validate any serialized report image reference. */
+export declare function normalizeStoredImageRef(value: unknown): StoredImageRef | null;
+/** Resolve the report asset extension for an image MIME type. */
+export declare function imageFileExtensionForMimeType(mimeType: string): string;
+/** Resolve a supported report image MIME type from its file extension. */
+export declare function imageMimeTypeForFileExtension(extension: string): `image/${string}` | null;
+/** Resolve the file extension used by a serialized report image reference. */
+export declare function imageRefFileExtension(ref: StoredImageRef): string;
+/**
+ * Resolve the report-relative asset path for an image reference.
+ * Explicit serialized paths win; inline refs use the standard screenshots dir.
+ */
+export declare function reportImageAssetPath(ref: StoredImageRef): string;

package/dist/types/dump/report-action-dump.d.ts

@@ -0,0 +1,127 @@
+import { ScreenshotItem } from '../screenshot-item';
+import type { ExecutionTask, IExecutionDump, IReportActionDump } from '../types';
+import { type ImageUrlRef } from './screenshot-store';
+/**
+ * ExecutionDump class for serializing and deserializing execution dumps
+ */
+export declare class ExecutionDump implements IExecutionDump {
+    id?: string;
+    logTime: number;
+    name: string;
+    description?: string;
+    tasks: ExecutionTask[];
+    aiActContext?: string;
+    private readonly referenceImageUrls;
+    constructor(data: IExecutionDump, options?: {
+        referenceImageUrls?: readonly string[];
+    });
+    /**
+     * Serialize the ExecutionDump to a JSON string
+     */
+    serialize(indents?: number): string;
+    /**
+     * Convert to a plain object for JSON serialization
+     */
+    toJSON(): IExecutionDump;
+    /**
+     * Create an ExecutionDump instance from a serialized JSON string
+     */
+    static fromSerializedString(serialized: string): ExecutionDump;
+    /**
+     * Create an ExecutionDump instance from a plain object
+     */
+    static fromJSON(data: IExecutionDump): ExecutionDump;
+    /**
+     * Collect all ScreenshotItem instances from tasks.
+     * Scans through uiContext and recorder items to find screenshots.
+     *
+     * @returns Array of ScreenshotItem instances
+     */
+    collectScreenshots(): ScreenshotItem[];
+    /**
+     * Return persistable base64 reference-image URLs explicitly registered while
+     * building this execution. This sidecar is excluded from serialized dumps.
+     */
+    getReferenceImageUrls(): readonly string[];
+}
+/**
+ * ReportActionDump class for serializing and deserializing report action dumps
+ */
+export declare class ReportActionDump implements IReportActionDump {
+    sdkVersion: string;
+    groupName: string;
+    groupDescription?: string;
+    modelBriefs: IReportActionDump['modelBriefs'];
+    executions: ExecutionDump[];
+    deviceType?: string;
+    constructor(data: IReportActionDump);
+    /**
+     * Serialize the ReportActionDump to a JSON string
+     * Uses typed report references for persisted screenshots.
+     */
+    serialize(indents?: number): string;
+    /**
+     * Serialize a report dump while replacing persisted multimodal prompt image
+     * URLs with their compact report asset references.
+     *
+     * @param referenceImageRefsByUrl Maps registered prompt image URLs to assets.
+     * @param indents Optional JSON indentation.
+     * @returns The serialized report dump.
+     */
+    serializeWithReferenceImages(referenceImageRefsByUrl: ReadonlyMap<string, ImageUrlRef>, indents?: number): string;
+    /**
+     * Serialize the ReportActionDump with inline screenshots to a JSON string.
+     * Each ScreenshotItem is replaced with { base64: "...", capturedAt }.
+     */
+    serializeWithInlineScreenshots(indents?: number): string;
+    /**
+     * Convert to a plain object for JSON serialization
+     */
+    toJSON(): IReportActionDump;
+    /**
+     * Create a ReportActionDump instance from a serialized JSON string
+     */
+    static fromSerializedString(serialized: string): ReportActionDump;
+    /**
+     * Create a ReportActionDump instance from a plain object
+     */
+    static fromJSON(data: IReportActionDump): ReportActionDump;
+    /**
+     * Collect all ScreenshotItem instances from all executions.
+     *
+     * @returns Array of all ScreenshotItem instances across all executions
+     */
+    collectAllScreenshots(): ScreenshotItem[];
+    /**
+     * Serialize the dump to files with screenshots as separate PNG files.
+     * Creates:
+     * - {basePath} - dump JSON with { $screenshot: id } references
+     * - {basePath}.screenshots/ - PNG files
+     *
+     * @param basePath - Base path for the dump file
+     */
+    serializeToFiles(basePath: string): void;
+    /**
+     * Read dump from files and return JSON string with inline screenshots.
+     * Reads the dump JSON and screenshot files, then inlines the base64 data.
+     *
+     * @param basePath - Base path for the dump file
+     * @returns JSON string with inline screenshots ({ base64: "..." } format)
+     */
+    static fromFilesAsInlineJson(basePath: string): string;
+    /**
+     * Clean up all files associated with a serialized dump.
+     *
+     * @param basePath - Base path for the dump file
+     */
+    static cleanupFiles(basePath: string): void;
+    /**
+     * Get all file paths associated with a serialized dump.
+     *
+     * @param basePath - Base path for the dump file
+     * @returns Array of all associated file paths
+     */
+    static getFilePaths(basePath: string): string[];
+}
+export type GroupedActionDump = ReportActionDump;
+export declare const GroupedActionDump: typeof ReportActionDump;

package/dist/types/dump/report-dump-compactor.d.ts

@@ -0,0 +1,7 @@
+export interface ReportDumpCompactionResult {
+    beforeBytes: number;
+    afterBytes: number;
+    beforeDumpCount: number;
+    afterDumpCount: number;
+}
+export declare function compactReportDumps(reportPath: string): Promise<ReportDumpCompactionResult>;

package/dist/types/dump/screenshot-store.d.ts

@@ -1,30 +1,37 @@
 import type { ScreenshotItem } from '../screenshot-item';
-export interface ScreenshotRef {
-    type: 'midscene_screenshot_ref';
-    id: string;
-    capturedAt: number;
-    mimeType: 'image/png' | 'image/jpeg';
-    storage: 'inline' | 'file';
-    path?: string;
-}
-export declare function normalizeScreenshotRef(value: unknown): ScreenshotRef | null;
-type ResolvedScreenshotSource = {
+import { type ImageUrlRef, type ScreenshotRef, type StoredImageRef } from './image-reference';
+export type { ImageUrlRef, ScreenshotRef, StoredImageRef, } from './image-reference';
+export { imageRefFileExtension, normalizeImageUrlRef, normalizeScreenshotRef, normalizeStoredImageRef, } from './image-reference';
+type ResolvedImageSource = {
     type: 'data-uri';
     id: string;
-    mimeType: ScreenshotRef['mimeType'];
+    mimeType: StoredImageRef['mimeType'];
     dataUri: string;
 } | {
     type: 'file';
     id: string;
-    mimeType: ScreenshotRef['mimeType'];
+    mimeType: StoredImageRef['mimeType'];
     filePath: string;
 };
+export declare function parseBase64ImageDataUrl(imageUrl: string): {
+    mimeType: `image/${string}`;
+    extension: string;
+    rawBase64: string;
+};
+export declare function isBase64ImageDataUrl(value: string): boolean;
+export declare function resolveImageSource(refInput: unknown, options: {
+    reportPath: string;
+    imageDirectory?: string;
+    fallbackId?: string;
+    fallbackMimeType?: ScreenshotRef['mimeType'];
+}): ResolvedImageSource;
 export declare function resolveScreenshotSource(refInput: unknown, options: {
     reportPath: string;
+    imageDirectory?: string;
     fallbackId?: string;
     fallbackMimeType?: ScreenshotRef['mimeType'];
-}): ResolvedScreenshotSource;
-export declare class ScreenshotStore {
+}): ResolvedImageSource;
+export declare class ReportImageStore {
     private readonly mode;
     private readonly reportPath;
     private readonly screenshotsDir?;
@@ -32,6 +39,8 @@ export declare class ScreenshotStore {
     private readonly alsoWriteFileCopy;
     private readonly writtenInlineIds;
     private readonly writtenFileIds;
+    private readonly shouldReuseExistingInlineReport;
+    private existingInlineImageIdsPromise?;
     constructor(options: {
         mode: 'inline' | 'directory';
         reportPath: string;
@@ -40,10 +49,18 @@ export declare class ScreenshotStore {
         alsoWriteFileCopy?: boolean;
         /** @deprecated Use alsoWriteFileCopy instead. */
         ensureFileCopy?: boolean;
+        /** Reuse inline image assets already present in reportPath. */
+        reuseExistingReport?: boolean;
     });
     persist(screenshot: ScreenshotItem): Promise<ScreenshotRef>;
+    persistReferenceImage(imageUrl: string): Promise<ImageUrlRef>;
+    private ensureExistingInlineImageIdsLoaded;
     private persistToSharedFileIfNeeded;
+    private writeImageFileIfNeeded;
+    loadDataUri(refInput: unknown): string;
+    /** @deprecated Use loadDataUri. */
     loadBase64(refInput: unknown): string;
     cleanup(): void;
 }
-export {};
+/** @deprecated Use ReportImageStore. */
+export { ReportImageStore as ScreenshotStore };

package/dist/types/dump/task-service-dump.d.ts

@@ -0,0 +1,3 @@
+import type { ExecutionTask, Rect, ServiceDump } from '../types';
+export declare function getTaskServiceDump(task?: ExecutionTask | null): ServiceDump | null;
+export declare function getTaskSearchArea(task?: ExecutionTask | null): Rect | undefined;

package/dist/types/dump/task-status.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Single source of truth for turning raw task/execution dump data into a
+ * semantic status.
+ *
+ * Both the report sidebar (per-step status icon) and the merged-report
+ * status aggregation must agree on what "failed" means, otherwise a merged
+ * report can mark a failing case as passed. Keeping the rules here — as pure
+ * functions over plain dump fields — lets the front-end icons and the backend
+ * `mergeReportFiles` attribute derivation share the exact same logic.
+ */
+import type { ExecutionTask, TestStatus } from '../types';
+/**
+ * The subset of a task's fields needed to derive its status, picked from
+ * `ExecutionTask` so the field names/types stay defined in one place. It is a
+ * structural subset, so both the full `ExecutionTask` and the front-end task
+ * variants (which carry extra fields) satisfy it.
+ */
+export type TaskStatusFields = Partial<Pick<ExecutionTask, 'status' | 'subType' | 'error' | 'errorMessage'> & {
+    output: unknown;
+}>;
+export type DerivedTaskStatus = 'passed' | 'failed' | 'warning' | 'pending' | 'running' | 'cancelled';
+/**
+ * Derive a single task's semantic status from its raw dump fields. Mirrors the
+ * historical `getStatusIcon` logic in the report sidebar so icons and merged
+ * status never diverge.
+ */
+export declare function deriveTaskStatus(task: TaskStatusFields): DerivedTaskStatus;
+/**
+ * Aggregate the tasks of one case (a list of executions) into a single
+ * `TestStatus`. A case is `failed` when any of its tasks derives to `failed`;
+ * otherwise it is `passed`. Warnings, pending/running/cancelled steps do not by
+ * themselves fail a case.
+ *
+ * This only ever produces `passed` / `failed`; the finer `timedOut` /
+ * `skipped` / `interrupted` statuses can only come from a source report that
+ * already recorded them (e.g. a Playwright run), which callers should prefer
+ * when available.
+ */
+export declare function deriveCaseStatus(executions: Array<{
+    tasks?: TaskStatusFields[];
+}>): TestStatus;

package/dist/types/element-describer.d.ts

@@ -0,0 +1,43 @@
+import type { ModelRuntime } from './ai-model/models';
+import type Service from './service';
+import type { AgentDescribeElementAtPointResult, LocateOption, LocateValidatorResult, LocatorValidatorOption, Size } from './types';
+export type DescribeElementCoordinateSpace = 'screenshot' | 'logical';
+export type LocatorVerifyFn = (input: {
+    prompt: string;
+    expectCenter: [number, number];
+    retryCount: number;
+    verifyResult: LocateValidatorResult;
+}) => LocateValidatorResult | boolean;
+export type DescribeElementAtPointOptions = {
+    verifyPrompt?: boolean;
+    retryLimit?: number;
+    deepDescribe?: boolean;
+    deepLocate?: boolean;
+    locatorVerifyFn?: LocatorVerifyFn;
+    screenshotBase64?: string;
+    screenshotSize?: Size;
+    coordinateSpace?: DescribeElementCoordinateSpace;
+    logicalSize?: Size;
+    onProgress?: (progress: {
+        prompt?: string;
+        deepDescribe?: boolean;
+        deepLocate?: boolean;
+        verifyResult?: LocateValidatorResult;
+    }) => void;
+} & LocatorValidatorOption;
+type ScreenshotBoundContextOptions = {
+    screenshotBase64?: string;
+    screenshotSize?: Size;
+    coordinateSpace?: DescribeElementCoordinateSpace;
+    logicalSize?: Size;
+};
+export type VerifyElementDescriptionAtPointOptions = ScreenshotBoundContextOptions & LocatorValidatorOption;
+export type ElementDescriberRuntime = {
+    service: Pick<Service, 'describe' | 'locate'>;
+    describeModelRuntime: ModelRuntime;
+    locateModelRuntime: ModelRuntime;
+};
+export declare function verifyLocator(runtime: Pick<ElementDescriberRuntime, 'service' | 'locateModelRuntime'>, prompt: string, locateOpt: LocateOption | undefined, expectCenter: [number, number], verifyLocateOption?: LocatorValidatorOption & Pick<LocateOption, 'deepLocate'>): Promise<LocateValidatorResult>;
+export declare function describeElementAtPoint(runtime: ElementDescriberRuntime, center: [number, number], opt?: DescribeElementAtPointOptions): Promise<AgentDescribeElementAtPointResult>;
+export declare function verifyElementDescriptionAtPoint(runtime: ElementDescriberRuntime, description: string, center: [number, number], opt?: VerifyElementDescriptionAtPointOptions): Promise<LocateValidatorResult>;
+export {};

package/dist/types/errors.d.ts

@@ -0,0 +1,5 @@
+import type { ServiceDump } from './types';
+export declare class ServiceError extends Error {
+    dump: ServiceDump;
+    constructor(message: string, dump: ServiceDump);
+}

package/dist/types/report-html-template.d.ts

@@ -0,0 +1 @@
+export declare const REPORT_HTML_TEMPLATE = "REPLACE_ME_WITH_REPORT_HTML";