@donggui/core 1.5.4-donggui.3

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

@@ -0,0 +1,52 @@
+export declare const escapeContent: (html: string) => string;
+export declare const unescapeContent: (html: string) => string;
+/** Chunk size for streaming file operations (64KB) */
+export declare const STREAMING_CHUNK_SIZE: number;
+/**
+ * Callback for processing matched tags during streaming.
+ * @param content - The content between open and close tags
+ * @returns true to stop scanning, false to continue
+ */
+type TagMatchCallback = (content: string) => boolean;
+/**
+ * Stream through a file and find tags matching the pattern.
+ * Memory usage: O(chunk_size + tag_size), not O(file_size).
+ *
+ * @param filePath - Absolute path to the file
+ * @param openTag - Opening tag to search for
+ * @param closeTag - Closing tag
+ * @param onMatch - Callback for each matched tag content
+ */
+export declare function streamScanTags(filePath: string, openTag: string, closeTag: string, onMatch: TagMatchCallback): void;
+/**
+ * Synchronously extract a specific image's base64 data from an HTML file by its id.
+ * Uses streaming to avoid loading the entire file into memory.
+ *
+ * @param htmlPath - Absolute path to the HTML file
+ * @param imageId - The id of the image to extract
+ * @returns The base64 data string, or null if not found
+ */
+export declare function extractImageByIdSync(htmlPath: string, imageId: string): string | null;
+/**
+ * Stream image script tags from source file directly to output file.
+ * Memory usage: O(single_image_size), not O(all_images_size).
+ *
+ * @param srcFilePath - Source HTML file path
+ * @param destFilePath - Destination file path to append to
+ */
+export declare function streamImageScriptsToFile(srcFilePath: string, destFilePath: string): void;
+/**
+ * Extract the LAST dump script content from HTML file using streaming.
+ * Memory usage: O(dump_size), not O(file_size).
+ *
+ * @param filePath - Absolute path to the HTML file
+ * @returns The dump script content (trimmed), or empty string if not found
+ */
+export declare function extractLastDumpScriptSync(filePath: string): string;
+export declare function parseImageScripts(html: string): Record<string, string>;
+export declare function parseDumpScript(html: string): string;
+export declare function parseDumpScriptAttributes(html: string): Record<string, string>;
+export declare function generateImageScriptTag(id: string, data: string): string;
+export declare function getBaseUrlFixScript(): string;
+export declare function generateDumpScriptTag(json: string, attributes?: Record<string, string>): string;
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Recursively restore image references in parsed data.
+ * Replaces { $screenshot: "id" } with lazy { get base64() {...}, capturedAt } objects.
+ * The resolver is only called when .base64 is first accessed.
+ */
+export declare function restoreImageReferences<T>(data: T, resolveImage: (id: string) => string): T;

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

@@ -0,0 +1,5 @@
+/**
+ * Dump module - utilities for HTML parsing and image restoration.
+ */
+export { restoreImageReferences } from './image-restoration';
+export { escapeContent, unescapeContent, parseImageScripts, parseDumpScript, parseDumpScriptAttributes, generateImageScriptTag, generateDumpScriptTag, } from './html-utils';

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import Service from './service/index';
+import { TaskRunner } from './task-runner';
+import { getVersion } from './utils';
+export { plan, AiLocateElement, getMidsceneLocationSchema, PointSchema, SizeSchema, RectSchema, TMultimodalPromptSchema, TUserPromptSchema, type TMultimodalPrompt, type TUserPrompt, } from './ai-model/index';
+export { MIDSCENE_MODEL_NAME, type CreateOpenAIClientFn, } from '@midscene/shared/env';
+export type * from './types';
+export { ServiceError, ExecutionDump, GroupedActionDump, type IExecutionDump, type IGroupedActionDump, } from './types';
+export { z };
+export default Service;
+export { TaskRunner, Service, getVersion };
+export type { MidsceneYamlScript, MidsceneYamlTask, MidsceneYamlFlowItem, MidsceneYamlConfigResult, MidsceneYamlConfig, MidsceneYamlScriptWebEnv, MidsceneYamlScriptAndroidEnv, MidsceneYamlScriptIOSEnv, MidsceneYamlScriptEnv, LocateOption, DetailedLocateParam, } from './yaml';
+export { Agent, type AgentOpt, type AiActOptions, createAgent } from './agent';
+export { restoreImageReferences, escapeContent, unescapeContent, parseImageScripts, parseDumpScript, parseDumpScriptAttributes, generateImageScriptTag, generateDumpScriptTag, } from './dump';
+export type { IReportGenerator } from './report-generator';
+export { ReportGenerator, nullReportGenerator } from './report-generator';
+export { ScreenshotItem } from './screenshot-item';

package/dist/types/report-generator.d.ts

@@ -0,0 +1,48 @@
+import type { GroupedActionDump } from './types';
+export interface IReportGenerator {
+    /**
+     * Schedule a dump update. Writes are queued internally to guarantee serial execution.
+     * This method returns immediately (fire-and-forget).
+     * Screenshots are written and memory is released during this call.
+     */
+    onDumpUpdate(dump: GroupedActionDump): void;
+    /**
+     * Wait for all queued write operations to complete.
+     */
+    flush(): Promise<void>;
+    /**
+     * Finalize the report. Calls flush() internally.
+     */
+    finalize(dump: GroupedActionDump): Promise<string | undefined>;
+    getReportPath(): string | undefined;
+}
+export declare const nullReportGenerator: IReportGenerator;
+export declare class ReportGenerator implements IReportGenerator {
+    private reportPath;
+    private screenshotMode;
+    private autoPrint;
+    private writtenScreenshots;
+    private firstWriteDone;
+    private imageEndOffset;
+    private initialized;
+    private writeQueue;
+    private destroyed;
+    constructor(options: {
+        reportPath: string;
+        screenshotMode: 'inline' | 'directory';
+        autoPrint?: boolean;
+    });
+    static create(reportFileName: string, opts: {
+        generateReport?: boolean;
+        outputFormat?: 'single-html' | 'html-and-external-assets';
+        autoPrintReportMsg?: boolean;
+    }): IReportGenerator;
+    onDumpUpdate(dump: GroupedActionDump): void;
+    flush(): Promise<void>;
+    finalize(dump: GroupedActionDump): Promise<string | undefined>;
+    getReportPath(): string | undefined;
+    private printReportPath;
+    private doWrite;
+    private writeInlineReport;
+    private writeDirectoryReport;
+}

package/dist/types/report.d.ts

@@ -0,0 +1,15 @@
+import type { ReportFileWithAttributes } from './types';
+export declare class ReportMergingTool {
+    private reportInfos;
+    append(reportInfo: ReportFileWithAttributes): void;
+    clear(): void;
+    /**
+     * Check if a report is in directory mode (html-and-external-assets).
+     * Directory mode reports: {name}/index.html + {name}/screenshots/
+     */
+    private isDirectoryModeReport;
+    mergeReports(reportFileName?: 'AUTO' | string, opts?: {
+        rmOriginalReports?: boolean;
+        overwrite?: boolean;
+    }): string | null;
+}

package/dist/types/screenshot-item.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Serialization format for ScreenshotItem
+ * - { $screenshot: "id" } - inline mode, references imageMap in HTML
+ * - { base64: "path" } - directory mode, references external file path
+ */
+export type ScreenshotSerializeFormat = {
+    $screenshot: string;
+    capturedAt: number;
+} | {
+    base64: string;
+    capturedAt: number;
+};
+/**
+ * ScreenshotItem encapsulates screenshot data.
+ *
+ * Supports lazy loading after memory release:
+ * - inline mode: reads from HTML file using streaming (extractImageByIdSync)
+ * - directory mode: reads from file on disk
+ *
+ * After persistence, memory is released but the screenshot can be recovered
+ * on-demand from disk, making it safe to release memory at any time.
+ */
+export declare class ScreenshotItem {
+    private _id;
+    private _base64;
+    private _format;
+    private _capturedAt;
+    private _persistedAs;
+    private _persistedPath;
+    private _persistedHtmlPath;
+    private constructor();
+    /** Create a new ScreenshotItem from base64 data */
+    static create(base64: string, capturedAt: number): ScreenshotItem;
+    get id(): string;
+    /** Get the image format (png or jpeg) */
+    get format(): 'png' | 'jpeg';
+    /** Get the file extension for this screenshot */
+    get extension(): string;
+    /** Get screenshot capture timestamp in milliseconds */
+    get capturedAt(): number;
+    get base64(): string;
+    /** Check if base64 data is still available in memory (not yet released) */
+    hasBase64(): boolean;
+    /**
+     * Mark as persisted to HTML (inline mode).
+     * Releases base64 memory, but keeps HTML path for lazy loading recovery.
+     * @param htmlPath - absolute path to the HTML file containing the image
+     */
+    markPersistedInline(htmlPath: string): void;
+    /**
+     * Mark as persisted to file (directory mode).
+     * Releases base64 memory, but keeps file path for lazy loading recovery.
+     * @param relativePath - relative path for serialization (e.g., "./screenshots/id.jpeg")
+     * @param absolutePath - absolute path for lazy loading recovery
+     */
+    markPersistedToPath(relativePath: string, absolutePath: string): void;
+    /** Serialize for JSON - format depends on persistence state */
+    toSerializable(): ScreenshotSerializeFormat;
+    /** Check if a value is a serialized ScreenshotItem reference (inline or directory mode) */
+    static isSerialized(value: unknown): value is ScreenshotSerializeFormat;
+    /**
+     * Get base64 data without the data URI prefix.
+     * Useful for writing raw binary data to files.
+     */
+    get rawBase64(): string;
+}

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

@@ -0,0 +1,23 @@
+import type { AIDescribeElementResponse, DetailedLocateParam, LocateResultWithDump, Rect, ServiceExtractOption, ServiceExtractParam, ServiceExtractResult, ServiceTaskInfo, UIContext } from '../types';
+import type { IModelConfig } from '@midscene/shared/env';
+import type { TMultimodalPrompt } from '../common';
+export interface LocateOpts {
+    context?: UIContext;
+}
+export type AnyValue<T> = {
+    [K in keyof T]: unknown extends T[K] ? any : T[K];
+};
+interface ServiceOptions {
+    taskInfo?: Omit<ServiceTaskInfo, 'durationMs'>;
+}
+export default class Service {
+    contextRetrieverFn: () => Promise<UIContext> | UIContext;
+    taskInfo?: Omit<ServiceTaskInfo, 'durationMs'>;
+    constructor(context: UIContext | (() => Promise<UIContext> | UIContext), opt?: ServiceOptions);
+    locate(query: DetailedLocateParam, opt: LocateOpts, modelConfig: IModelConfig, abortSignal?: AbortSignal): Promise<LocateResultWithDump>;
+    extract<T>(dataDemand: ServiceExtractParam, modelConfig: IModelConfig, opt?: ServiceExtractOption, pageDescription?: string, multimodalPrompt?: TMultimodalPrompt, context?: UIContext): Promise<ServiceExtractResult<T>>;
+    describe(target: Rect | [number, number], modelConfig: IModelConfig, opt?: {
+        deepLocate?: boolean;
+    }): Promise<Pick<AIDescribeElementResponse, 'description'>>;
+}
+export {};

package/dist/types/service/utils.d.ts

@@ -0,0 +1,2 @@
+import type { PartialServiceDumpFromSDK, ServiceDump } from '../types';
+export declare function createServiceDump(data: PartialServiceDumpFromSDK): ServiceDump;

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

@@ -0,0 +1,25 @@
+import type { AbstractInterface } from '../device';
+type DeviceClass = new (...args: any[]) => AbstractInterface;
+export interface SkillCLIOptions {
+    scriptName: string;
+    DeviceClass: DeviceClass;
+}
+/**
+ * Launch a Skill CLI for a custom interface Device class.
+ * This enables AI coding assistants (Claude Code, Cline, etc.) to control
+ * your custom interface through CLI commands.
+ *
+ * @example
+ * ```typescript
+ * #!/usr/bin/env node
+ * import { runSkillCLI } from '@midscene/core/skill';
+ * import { SampleDevice } from './sample-device';
+ *
+ * runSkillCLI({
+ *   DeviceClass: SampleDevice,
+ *   scriptName: 'my-device',
+ * });
+ * ```
+ */
+export declare function runSkillCLI(options: SkillCLIOptions): Promise<void>;
+export {};

package/dist/types/task-runner.d.ts

@@ -0,0 +1,48 @@
+import { ExecutionDump, type ExecutionTask, type ExecutionTaskApply, type ExecutionTaskProgressOptions, type UIContext } from './types';
+type TaskRunnerInitOptions = ExecutionTaskProgressOptions & {
+    tasks?: ExecutionTaskApply[];
+    onTaskUpdate?: (runner: TaskRunner, error?: TaskExecutionError) => Promise<void> | void;
+};
+type TaskRunnerOperationOptions = {
+    allowWhenError?: boolean;
+};
+export declare class TaskRunner {
+    name: string;
+    tasks: ExecutionTask[];
+    status: 'init' | 'pending' | 'running' | 'completed' | 'error';
+    onTaskStart?: ExecutionTaskProgressOptions['onTaskStart'];
+    private readonly uiContextBuilder;
+    private readonly onTaskUpdate?;
+    constructor(name: string, uiContextBuilder: () => Promise<UIContext>, options?: TaskRunnerInitOptions);
+    private emitOnTaskUpdate;
+    private lastUiContext?;
+    private getUiContext;
+    private captureScreenshot;
+    private attachRecorderItem;
+    private markTaskAsPending;
+    private normalizeStatusFromError;
+    append(task: ExecutionTaskApply[] | ExecutionTaskApply, options?: TaskRunnerOperationOptions): Promise<void>;
+    appendAndFlush(task: ExecutionTaskApply[] | ExecutionTaskApply, options?: TaskRunnerOperationOptions): Promise<{
+        output: any;
+        thought?: string;
+    } | undefined>;
+    flush(options?: TaskRunnerOperationOptions): Promise<{
+        output: any;
+        thought?: string;
+    } | undefined>;
+    isInErrorState(): boolean;
+    latestErrorTask(): ExecutionTask | null;
+    dump(): ExecutionDump;
+    appendErrorPlan(errorMsg: string): Promise<{
+        output: undefined;
+        runner: TaskRunner;
+    }>;
+}
+export declare class TaskExecutionError extends Error {
+    runner: TaskRunner;
+    errorTask: ExecutionTask | null;
+    constructor(message: string, runner: TaskRunner, errorTask: ExecutionTask | null, options?: {
+        cause?: unknown;
+    });
+}
+export {};

package/dist/types/task-timing.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionTask } from './types';
+type ExecutionTaskTiming = NonNullable<ExecutionTask['timing']>;
+type NumericTimingField = {
+    [K in keyof ExecutionTaskTiming]-?: ExecutionTaskTiming[K] extends number | undefined ? K : never;
+}[keyof ExecutionTaskTiming];
+export type TimingSettableField = Exclude<NumericTimingField, 'start' | 'end' | 'cost'>;
+export declare function setTimingFieldOnce(timing: ExecutionTaskTiming | undefined, field: TimingSettableField): void;
+export {};

package/dist/types/tree.d.ts

@@ -0,0 +1,4 @@
+import type { BaseElement, ElementTreeNode } from '@midscene/shared/types';
+import { trimAttributes, truncateText } from '@midscene/shared/extractor';
+export { trimAttributes, truncateText };
+export declare function descriptionOfTree<ElementType extends BaseElement = BaseElement>(tree: ElementTreeNode<ElementType>, truncateTextLength?: number, filterNonTextContent?: boolean, visibleOnly?: boolean): string;