@aiscene/core 9.0.6 → 9.0.8

package/dist/es/dump/screenshot-store.mjs

@@ -1,7 +1,9 @@
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
-import { extractImageByIdSync } from "./html-utils.mjs";
+import { collectImageScriptIds, extractImageByIdSync } from "./html-utils.mjs";
+import { imageFileExtensionForMimeType, imageRefFileExtension, normalizeImageUrlRef, normalizeScreenshotRef, normalizeStoredImageRef } from "./image-reference.mjs";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -12,26 +14,28 @@ function _define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
-function normalizeScreenshotRef(value) {
-    if ('object' != typeof value || null === value) return null;
-    const record = value;
-    if ('midscene_screenshot_ref' === record.type && 'string' == typeof record.id && 'number' == typeof record.capturedAt && ('inline' === record.storage || 'file' === record.storage) && ('image/png' === record.mimeType || 'image/jpeg' === record.mimeType)) {
-        if ('file' === record.storage && 'string' != typeof record.path) return null;
-        return record;
-    }
-    return null;
+const base64ImageDataUrlPattern = /^data:(image\/[a-z0-9.+-]+)(?:;[^,]*)?;base64,([a-z0-9+/=\s]+)$/i;
+function parseBase64ImageDataUrl(imageUrl) {
+    const match = imageUrl.match(base64ImageDataUrlPattern);
+    if (!match) throw new Error('ReportImageStore: reference image must be a valid base64 image data URL');
+    const mimeType = match[1].toLowerCase();
+    return {
+        mimeType,
+        extension: imageFileExtensionForMimeType(mimeType),
+        rawBase64: match[2].replace(/\s/g, '')
+    };
 }
-function extensionByMimeType(mimeType) {
-    return 'image/jpeg' === mimeType ? 'jpeg' : 'png';
+function isBase64ImageDataUrl(value) {
+    return base64ImageDataUrlPattern.test(value);
 }
-function resolveScreenshotSource(refInput, options) {
-    const ref = normalizeScreenshotRef(refInput);
+function resolveImageSource(refInput, options) {
+    const ref = normalizeStoredImageRef(refInput);
     const id = ref?.id ?? options.fallbackId;
     const mimeType = ref?.mimeType ?? options.fallbackMimeType;
-    if (!id || !mimeType) throw new Error('ScreenshotStore: screenshot id and mimeType are required to resolve screenshot');
+    if (!id || !mimeType) throw new Error('ReportImageStore: image id and mimeType are required to resolve an image');
     const resolveReportRelativePath = (filePath)=>isAbsolute(filePath) ? filePath : join(dirname(options.reportPath), filePath);
     if (ref?.storage === 'file') {
-        if (!ref.path) throw new Error(`ScreenshotStore: screenshot ref "${ref.id}" missing file path`);
+        if (!ref.path) throw new Error(`ReportImageStore: image ref "${ref.id}" missing file path`);
         const explicitFilePath = resolveReportRelativePath(ref.path);
         if (existsSync(explicitFilePath)) return {
             type: 'file',
@@ -47,58 +51,137 @@ function resolveScreenshotSource(refInput, options) {
         mimeType,
         dataUri: inlineDataUri
     };
-    const siblingScreenshotPath = join(dirname(options.reportPath), 'screenshots', `${id}.${extensionByMimeType(mimeType)}`);
-    if (existsSync(siblingScreenshotPath)) return {
+    const extension = ref ? imageRefFileExtension(ref) : imageFileExtensionForMimeType(options.fallbackMimeType);
+    if (options.imageDirectory) {
+        const companionImagePath = join(options.imageDirectory, `${id}.${extension}`);
+        if (existsSync(companionImagePath)) return {
+            type: 'file',
+            id,
+            mimeType,
+            filePath: companionImagePath
+        };
+    }
+    const siblingImagePath = join(dirname(options.reportPath), 'screenshots', `${id}.${extension}`);
+    if (existsSync(siblingImagePath)) return {
         type: 'file',
         id,
         mimeType,
-        filePath: siblingScreenshotPath
+        filePath: siblingImagePath
     };
-    throw new Error(`ScreenshotStore: cannot resolve screenshot "${id}" from ${options.reportPath}`);
+    throw new Error(`ReportImageStore: cannot resolve image "${id}" from ${options.reportPath}`);
 }
-class ScreenshotStore {
+function resolveScreenshotSource(refInput, options) {
+    const ref = normalizeScreenshotRef(refInput);
+    return resolveImageSource(ref, options);
+}
+class ReportImageStore {
     async persist(screenshot) {
+        await this.ensureExistingInlineImageIdsLoaded();
         const shouldWriteFileCopy = 'directory' === this.mode || this.alsoWriteFileCopy;
         const fileRef = shouldWriteFileCopy ? await this.persistToSharedFileIfNeeded(screenshot, {
             markAsPersisted: 'directory' === this.mode
         }) : null;
         if ('inline' === this.mode) {
-            if (!this.writeInlineImage) throw new Error('ScreenshotStore: writeInlineImage is required in inline mode');
+            if (!this.writeInlineImage) throw new Error('ReportImageStore: writeInlineImage is required in inline mode');
             if (!this.writtenInlineIds.has(screenshot.id)) {
                 await this.writeInlineImage(screenshot.id, screenshot.base64);
                 this.writtenInlineIds.add(screenshot.id);
             }
             return screenshot.markPersistedInline(this.reportPath);
         }
-        if (!fileRef) throw new Error('ScreenshotStore: file persistence is required in directory mode');
+        if (!fileRef) throw new Error('ReportImageStore: file persistence is required in directory mode');
         return fileRef;
     }
+    async persistReferenceImage(imageUrl) {
+        await this.ensureExistingInlineImageIdsLoaded();
+        const { mimeType, extension, rawBase64 } = parseBase64ImageDataUrl(imageUrl);
+        const id = `reference-${createHash('sha256').update(mimeType).update('\0').update(Buffer.from(rawBase64, 'base64')).digest('hex')}`;
+        const shouldWriteFileCopy = 'directory' === this.mode || this.alsoWriteFileCopy;
+        const fileLocation = shouldWriteFileCopy ? await this.writeImageFileIfNeeded({
+            id,
+            extension,
+            rawBase64
+        }) : null;
+        if ('inline' === this.mode) {
+            if (!this.writeInlineImage) throw new Error('ReportImageStore: writeInlineImage is required in inline mode');
+            if (!this.writtenInlineIds.has(id)) {
+                await this.writeInlineImage(id, imageUrl);
+                this.writtenInlineIds.add(id);
+            }
+            return {
+                type: 'midscene_image_url_ref',
+                id,
+                mimeType,
+                storage: 'inline'
+            };
+        }
+        if (!fileLocation) throw new Error('ReportImageStore: file persistence is required in directory mode');
+        return {
+            type: 'midscene_image_url_ref',
+            id,
+            mimeType,
+            storage: 'file',
+            path: fileLocation.relativePath
+        };
+    }
+    async ensureExistingInlineImageIdsLoaded() {
+        if (!this.shouldReuseExistingInlineReport) return;
+        if (!this.existingInlineImageIdsPromise) this.existingInlineImageIdsPromise = (async ()=>{
+            try {
+                const imageIds = await collectImageScriptIds(this.reportPath);
+                for (const imageId of imageIds)this.writtenInlineIds.add(imageId);
+            } catch (error) {
+                if ('object' == typeof error && null !== error && 'code' in error && 'ENOENT' === error.code) return;
+                throw new Error(`ReportImageStore: failed to index existing inline images from ${this.reportPath}`, {
+                    cause: error
+                });
+            }
+        })();
+        await this.existingInlineImageIdsPromise;
+    }
     async persistToSharedFileIfNeeded(screenshot, options) {
+        const { relativePath, absolutePath } = await this.writeImageFileIfNeeded({
+            id: screenshot.id,
+            extension: screenshot.extension,
+            rawBase64: screenshot.rawBase64
+        });
+        if (options.markAsPersisted) return screenshot.markPersistedToPath(relativePath, absolutePath);
+        return screenshot.registerPersistedFileCopy(relativePath, absolutePath);
+    }
+    async writeImageFileIfNeeded(image) {
         const screenshotsDir = this.screenshotsDir;
-        if (!screenshotsDir) throw new Error('ScreenshotStore: screenshotsDir is required when file persistence is enabled');
+        if (!screenshotsDir) throw new Error('ReportImageStore: screenshotsDir is required when file persistence is enabled');
         if (!existsSync(screenshotsDir)) mkdirSync(screenshotsDir, {
             recursive: true
         });
-        const relativePath = `./screenshots/${screenshot.id}.${screenshot.extension}`;
-        const absolutePath = join(screenshotsDir, `${screenshot.id}.${screenshot.extension}`);
-        if (!this.writtenFileIds.has(screenshot.id)) {
-            const buffer = Buffer.from(screenshot.rawBase64, 'base64');
-            await writeFile(absolutePath, buffer);
-            this.writtenFileIds.add(screenshot.id);
+        const fileName = `${image.id}.${image.extension}`;
+        const relativePath = `./screenshots/${fileName}`;
+        const absolutePath = join(screenshotsDir, fileName);
+        if (!this.writtenFileIds.has(image.id)) {
+            await writeFile(absolutePath, Buffer.from(image.rawBase64, 'base64'));
+            this.writtenFileIds.add(image.id);
         }
-        if (options.markAsPersisted) return screenshot.markPersistedToPath(relativePath, absolutePath);
-        return screenshot.registerPersistedFileCopy(relativePath, absolutePath);
+        return {
+            relativePath,
+            absolutePath
+        };
     }
-    loadBase64(refInput) {
-        const ref = normalizeScreenshotRef(refInput);
-        if (!ref) throw new Error('ScreenshotStore: invalid screenshot reference');
-        const resolved = resolveScreenshotSource(ref, {
-            reportPath: this.reportPath
+    loadDataUri(refInput) {
+        const ref = normalizeStoredImageRef(refInput);
+        if (!ref) throw new Error('ReportImageStore: invalid image reference');
+        const resolved = resolveImageSource(ref, {
+            reportPath: this.reportPath,
+            imageDirectory: this.screenshotsDir
         });
         if ('data-uri' === resolved.type) return resolved.dataUri;
         const data = readFileSync(resolved.filePath);
         return `data:${resolved.mimeType};base64,${data.toString('base64')}`;
     }
+    loadBase64(refInput) {
+        const screenshotRef = normalizeScreenshotRef(refInput);
+        if (!screenshotRef) throw new Error('ReportImageStore: invalid screenshot reference');
+        return this.loadDataUri(screenshotRef);
+    }
     cleanup() {
         if ('directory' === this.mode && this.screenshotsDir && existsSync(this.screenshotsDir)) rmSync(this.screenshotsDir, {
             recursive: true,
@@ -106,6 +189,7 @@ class ScreenshotStore {
         });
         this.writtenInlineIds.clear();
         this.writtenFileIds.clear();
+        this.existingInlineImageIdsPromise = void 0;
     }
     constructor(options){
         _define_property(this, "mode", void 0);
@@ -115,13 +199,16 @@ class ScreenshotStore {
         _define_property(this, "alsoWriteFileCopy", void 0);
         _define_property(this, "writtenInlineIds", new Set());
         _define_property(this, "writtenFileIds", new Set());
+        _define_property(this, "shouldReuseExistingInlineReport", void 0);
+        _define_property(this, "existingInlineImageIdsPromise", void 0);
         this.mode = options.mode;
         this.reportPath = options.reportPath;
         this.screenshotsDir = options.screenshotsDir;
         this.writeInlineImage = options.writeInlineImage;
         this.alsoWriteFileCopy = options.alsoWriteFileCopy ?? options.ensureFileCopy ?? false;
+        this.shouldReuseExistingInlineReport = Boolean(options.reuseExistingReport && 'inline' === this.mode);
     }
 }
-export { ScreenshotStore, normalizeScreenshotRef, resolveScreenshotSource };
+export { ReportImageStore, ReportImageStore as ScreenshotStore, imageRefFileExtension, isBase64ImageDataUrl, normalizeImageUrlRef, normalizeScreenshotRef, normalizeStoredImageRef, parseBase64ImageDataUrl, resolveImageSource, resolveScreenshotSource };
 
 //# sourceMappingURL=screenshot-store.mjs.map

package/dist/es/dump/screenshot-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"dump/screenshot-store.mjs","sources":["../../../src/dump/screenshot-store.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';\nimport { writeFile as writeFileAsync } from 'node:fs/promises';\nimport { dirname, isAbsolute, join } from 'node:path';\nimport type { ScreenshotItem } from '../screenshot-item';\nimport { extractImageByIdSync } from './html-utils';\n\nexport interface ScreenshotRef {\n  type: 'midscene_screenshot_ref';\n  id: string;\n  capturedAt: number;\n  mimeType: 'image/png' | 'image/jpeg';\n  storage: 'inline' | 'file';\n  path?: string;\n}\n\nexport function normalizeScreenshotRef(value: unknown): ScreenshotRef | null {\n  if (typeof value !== 'object' || value === null) return null;\n  const record = value as Record<string, unknown>;\n\n  if (\n    record.type === 'midscene_screenshot_ref' &&\n    typeof record.id === 'string' &&\n    typeof record.capturedAt === 'number' &&\n    (record.storage === 'inline' || record.storage === 'file') &&\n    (record.mimeType === 'image/png' || record.mimeType === 'image/jpeg')\n  ) {\n    if (record.storage === 'file' && typeof record.path !== 'string') {\n      return null;\n    }\n    return record as unknown as ScreenshotRef;\n  }\n\n  return null;\n}\n\ntype ResolvedScreenshotSource =\n  | {\n      type: 'data-uri';\n      id: string;\n      mimeType: ScreenshotRef['mimeType'];\n      dataUri: string;\n    }\n  | {\n      type: 'file';\n      id: string;\n      mimeType: ScreenshotRef['mimeType'];\n      filePath: string;\n    };\n\nfunction extensionByMimeType(mimeType: ScreenshotRef['mimeType']): string {\n  return mimeType === 'image/jpeg' ? 'jpeg' : 'png';\n}\n\nexport function resolveScreenshotSource(\n  refInput: unknown,\n  options: {\n    reportPath: string;\n    fallbackId?: string;\n    fallbackMimeType?: ScreenshotRef['mimeType'];\n  },\n): ResolvedScreenshotSource {\n  const ref = normalizeScreenshotRef(refInput);\n  const id = ref?.id ?? options.fallbackId;\n  const mimeType = ref?.mimeType ?? options.fallbackMimeType;\n\n  if (!id || !mimeType) {\n    throw new Error(\n      'ScreenshotStore: screenshot id and mimeType are required to resolve screenshot',\n    );\n  }\n\n  const resolveReportRelativePath = (filePath: string): string =>\n    isAbsolute(filePath)\n      ? filePath\n      : join(dirname(options.reportPath), filePath);\n\n  if (ref?.storage === 'file') {\n    if (!ref.path) {\n      throw new Error(\n        `ScreenshotStore: screenshot ref \"${ref.id}\" missing file path`,\n      );\n    }\n\n    const explicitFilePath = resolveReportRelativePath(ref.path);\n    if (existsSync(explicitFilePath)) {\n      return {\n        type: 'file',\n        id,\n        mimeType,\n        filePath: explicitFilePath,\n      };\n    }\n  }\n\n  const inlineDataUri = extractImageByIdSync(options.reportPath, id);\n  if (inlineDataUri) {\n    return {\n      type: 'data-uri',\n      id,\n      mimeType,\n      dataUri: inlineDataUri,\n    };\n  }\n\n  const siblingScreenshotPath = join(\n    dirname(options.reportPath),\n    'screenshots',\n    `${id}.${extensionByMimeType(mimeType)}`,\n  );\n  if (existsSync(siblingScreenshotPath)) {\n    return {\n      type: 'file',\n      id,\n      mimeType,\n      filePath: siblingScreenshotPath,\n    };\n  }\n\n  throw new Error(\n    `ScreenshotStore: cannot resolve screenshot \"${id}\" from ${options.reportPath}`,\n  );\n}\n\nexport class ScreenshotStore {\n  private readonly mode: 'inline' | 'directory';\n  private readonly reportPath: string;\n  private readonly screenshotsDir?: string;\n  private readonly writeInlineImage?: (\n    id: string,\n    base64: string,\n  ) => void | Promise<void>;\n  private readonly alsoWriteFileCopy: boolean;\n  private readonly writtenInlineIds = new Set<string>();\n  private readonly writtenFileIds = new Set<string>();\n\n  constructor(options: {\n    mode: 'inline' | 'directory';\n    reportPath: string;\n    screenshotsDir?: string;\n    writeInlineImage?: (id: string, base64: string) => void | Promise<void>;\n    alsoWriteFileCopy?: boolean;\n    /** @deprecated Use alsoWriteFileCopy instead. */\n    ensureFileCopy?: boolean;\n  }) {\n    this.mode = options.mode;\n    this.reportPath = options.reportPath;\n    this.screenshotsDir = options.screenshotsDir;\n    this.writeInlineImage = options.writeInlineImage;\n    this.alsoWriteFileCopy =\n      options.alsoWriteFileCopy ?? options.ensureFileCopy ?? false;\n  }\n\n  async persist(screenshot: ScreenshotItem): Promise<ScreenshotRef> {\n    const shouldWriteFileCopy =\n      this.mode === 'directory' || this.alsoWriteFileCopy;\n    const fileRef = shouldWriteFileCopy\n      ? await this.persistToSharedFileIfNeeded(screenshot, {\n          markAsPersisted: this.mode === 'directory',\n        })\n      : null;\n\n    if (this.mode === 'inline') {\n      if (!this.writeInlineImage) {\n        throw new Error(\n          'ScreenshotStore: writeInlineImage is required in inline mode',\n        );\n      }\n      if (!this.writtenInlineIds.has(screenshot.id)) {\n        await this.writeInlineImage(screenshot.id, screenshot.base64);\n        this.writtenInlineIds.add(screenshot.id);\n      }\n      return screenshot.markPersistedInline(this.reportPath);\n    }\n\n    if (!fileRef) {\n      throw new Error(\n        'ScreenshotStore: file persistence is required in directory mode',\n      );\n    }\n    return fileRef;\n  }\n\n  private async persistToSharedFileIfNeeded(\n    screenshot: ScreenshotItem,\n    options: {\n      markAsPersisted: boolean;\n    },\n  ): Promise<ScreenshotRef> {\n    const screenshotsDir = this.screenshotsDir;\n    if (!screenshotsDir) {\n      throw new Error(\n        'ScreenshotStore: screenshotsDir is required when file persistence is enabled',\n      );\n    }\n    if (!existsSync(screenshotsDir)) {\n      mkdirSync(screenshotsDir, { recursive: true });\n    }\n\n    const relativePath = `./screenshots/${screenshot.id}.${screenshot.extension}`;\n    const absolutePath = join(\n      screenshotsDir,\n      `${screenshot.id}.${screenshot.extension}`,\n    );\n\n    if (!this.writtenFileIds.has(screenshot.id)) {\n      const buffer = Buffer.from(screenshot.rawBase64, 'base64');\n      await writeFileAsync(absolutePath, buffer);\n      this.writtenFileIds.add(screenshot.id);\n    }\n\n    if (options.markAsPersisted) {\n      return screenshot.markPersistedToPath(relativePath, absolutePath);\n    }\n\n    return screenshot.registerPersistedFileCopy(relativePath, absolutePath);\n  }\n\n  loadBase64(refInput: unknown): string {\n    const ref = normalizeScreenshotRef(refInput);\n    if (!ref) {\n      throw new Error('ScreenshotStore: invalid screenshot reference');\n    }\n\n    const resolved = resolveScreenshotSource(ref, {\n      reportPath: this.reportPath,\n    });\n\n    if (resolved.type === 'data-uri') {\n      return resolved.dataUri;\n    }\n\n    const data = readFileSync(resolved.filePath);\n    return `data:${resolved.mimeType};base64,${data.toString('base64')}`;\n  }\n\n  cleanup(): void {\n    if (\n      this.mode === 'directory' &&\n      this.screenshotsDir &&\n      existsSync(this.screenshotsDir)\n    ) {\n      rmSync(this.screenshotsDir, { recursive: true, force: true });\n    }\n    this.writtenInlineIds.clear();\n    this.writtenFileIds.clear();\n  }\n}\n"],"names":["normalizeScreenshotRef","value","record","extensionByMimeType","mimeType","resolveScreenshotSource","refInput","options","ref","id","Error","resolveReportRelativePath","filePath","isAbsolute","join","dirname","explicitFilePath","existsSync","inlineDataUri","extractImageByIdSync","siblingScreenshotPath","ScreenshotStore","screenshot","shouldWriteFileCopy","fileRef","screenshotsDir","mkdirSync","relativePath","absolutePath","buffer","Buffer","writeFileAsync","resolved","data","readFileSync","rmSync","Set"],"mappings":"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"}
+{"version":3,"file":"dump/screenshot-store.mjs","sources":["../../../src/dump/screenshot-store.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';\nimport { writeFile as writeFileAsync } from 'node:fs/promises';\nimport { dirname, isAbsolute, join } from 'node:path';\nimport type { ScreenshotItem } from '../screenshot-item';\nimport { collectImageScriptIds, extractImageByIdSync } from './html-utils';\nimport {\n  type ImageUrlRef,\n  type ScreenshotRef,\n  type StoredImageRef,\n  imageFileExtensionForMimeType,\n  imageRefFileExtension,\n  normalizeImageUrlRef,\n  normalizeScreenshotRef,\n  normalizeStoredImageRef,\n} from './image-reference';\n\nexport type {\n  ImageUrlRef,\n  ScreenshotRef,\n  StoredImageRef,\n} from './image-reference';\nexport {\n  imageRefFileExtension,\n  normalizeImageUrlRef,\n  normalizeScreenshotRef,\n  normalizeStoredImageRef,\n} from './image-reference';\n\nconst base64ImageDataUrlPattern =\n  /^data:(image\\/[a-z0-9.+-]+)(?:;[^,]*)?;base64,([a-z0-9+/=\\s]+)$/i;\n\ntype ResolvedImageSource =\n  | {\n      type: 'data-uri';\n      id: string;\n      mimeType: StoredImageRef['mimeType'];\n      dataUri: string;\n    }\n  | {\n      type: 'file';\n      id: string;\n      mimeType: StoredImageRef['mimeType'];\n      filePath: string;\n    };\n\nexport function parseBase64ImageDataUrl(imageUrl: string): {\n  mimeType: `image/${string}`;\n  extension: string;\n  rawBase64: string;\n} {\n  const match = imageUrl.match(base64ImageDataUrlPattern);\n  if (!match) {\n    throw new Error(\n      'ReportImageStore: reference image must be a valid base64 image data URL',\n    );\n  }\n  const mimeType = match[1].toLowerCase() as `image/${string}`;\n  return {\n    mimeType,\n    extension: imageFileExtensionForMimeType(mimeType),\n    rawBase64: match[2].replace(/\\s/g, ''),\n  };\n}\n\nexport function isBase64ImageDataUrl(value: string): boolean {\n  return base64ImageDataUrlPattern.test(value);\n}\n\nexport function resolveImageSource(\n  refInput: unknown,\n  options: {\n    reportPath: string;\n    imageDirectory?: string;\n    fallbackId?: string;\n    fallbackMimeType?: ScreenshotRef['mimeType'];\n  },\n): ResolvedImageSource {\n  const ref = normalizeStoredImageRef(refInput);\n  const id = ref?.id ?? options.fallbackId;\n  const mimeType = ref?.mimeType ?? options.fallbackMimeType;\n\n  if (!id || !mimeType) {\n    throw new Error(\n      'ReportImageStore: image id and mimeType are required to resolve an image',\n    );\n  }\n\n  const resolveReportRelativePath = (filePath: string): string =>\n    isAbsolute(filePath)\n      ? filePath\n      : join(dirname(options.reportPath), filePath);\n\n  if (ref?.storage === 'file') {\n    if (!ref.path) {\n      throw new Error(\n        `ReportImageStore: image ref \"${ref.id}\" missing file path`,\n      );\n    }\n\n    const explicitFilePath = resolveReportRelativePath(ref.path);\n    if (existsSync(explicitFilePath)) {\n      return {\n        type: 'file',\n        id,\n        mimeType,\n        filePath: explicitFilePath,\n      };\n    }\n  }\n\n  const inlineDataUri = extractImageByIdSync(options.reportPath, id);\n  if (inlineDataUri) {\n    return {\n      type: 'data-uri',\n      id,\n      mimeType,\n      dataUri: inlineDataUri,\n    };\n  }\n\n  const extension = ref\n    ? imageRefFileExtension(ref)\n    : imageFileExtensionForMimeType(options.fallbackMimeType!);\n  if (options.imageDirectory) {\n    const companionImagePath = join(\n      options.imageDirectory,\n      `${id}.${extension}`,\n    );\n    if (existsSync(companionImagePath)) {\n      return {\n        type: 'file',\n        id,\n        mimeType,\n        filePath: companionImagePath,\n      };\n    }\n  }\n\n  const siblingImagePath = join(\n    dirname(options.reportPath),\n    'screenshots',\n    `${id}.${extension}`,\n  );\n  if (existsSync(siblingImagePath)) {\n    return {\n      type: 'file',\n      id,\n      mimeType,\n      filePath: siblingImagePath,\n    };\n  }\n\n  throw new Error(\n    `ReportImageStore: cannot resolve image \"${id}\" from ${options.reportPath}`,\n  );\n}\n\nexport function resolveScreenshotSource(\n  refInput: unknown,\n  options: {\n    reportPath: string;\n    imageDirectory?: string;\n    fallbackId?: string;\n    fallbackMimeType?: ScreenshotRef['mimeType'];\n  },\n): ResolvedImageSource {\n  const ref = normalizeScreenshotRef(refInput);\n  return resolveImageSource(ref, options);\n}\n\nexport class ReportImageStore {\n  private readonly mode: 'inline' | 'directory';\n  private readonly reportPath: string;\n  private readonly screenshotsDir?: string;\n  private readonly writeInlineImage?: (\n    id: string,\n    base64: string,\n  ) => void | Promise<void>;\n  private readonly alsoWriteFileCopy: boolean;\n  private readonly writtenInlineIds = new Set<string>();\n  private readonly writtenFileIds = new Set<string>();\n  private readonly shouldReuseExistingInlineReport: boolean;\n  private existingInlineImageIdsPromise?: Promise<void>;\n\n  constructor(options: {\n    mode: 'inline' | 'directory';\n    reportPath: string;\n    screenshotsDir?: string;\n    writeInlineImage?: (id: string, base64: string) => void | Promise<void>;\n    alsoWriteFileCopy?: boolean;\n    /** @deprecated Use alsoWriteFileCopy instead. */\n    ensureFileCopy?: boolean;\n    /** Reuse inline image assets already present in reportPath. */\n    reuseExistingReport?: boolean;\n  }) {\n    this.mode = options.mode;\n    this.reportPath = options.reportPath;\n    this.screenshotsDir = options.screenshotsDir;\n    this.writeInlineImage = options.writeInlineImage;\n    this.alsoWriteFileCopy =\n      options.alsoWriteFileCopy ?? options.ensureFileCopy ?? false;\n    this.shouldReuseExistingInlineReport = Boolean(\n      options.reuseExistingReport && this.mode === 'inline',\n    );\n  }\n\n  async persist(screenshot: ScreenshotItem): Promise<ScreenshotRef> {\n    await this.ensureExistingInlineImageIdsLoaded();\n    const shouldWriteFileCopy =\n      this.mode === 'directory' || this.alsoWriteFileCopy;\n    const fileRef = shouldWriteFileCopy\n      ? await this.persistToSharedFileIfNeeded(screenshot, {\n          markAsPersisted: this.mode === 'directory',\n        })\n      : null;\n\n    if (this.mode === 'inline') {\n      if (!this.writeInlineImage) {\n        throw new Error(\n          'ReportImageStore: writeInlineImage is required in inline mode',\n        );\n      }\n      if (!this.writtenInlineIds.has(screenshot.id)) {\n        await this.writeInlineImage(screenshot.id, screenshot.base64);\n        this.writtenInlineIds.add(screenshot.id);\n      }\n      return screenshot.markPersistedInline(this.reportPath);\n    }\n\n    if (!fileRef) {\n      throw new Error(\n        'ReportImageStore: file persistence is required in directory mode',\n      );\n    }\n    return fileRef;\n  }\n\n  async persistReferenceImage(imageUrl: string): Promise<ImageUrlRef> {\n    await this.ensureExistingInlineImageIdsLoaded();\n    const { mimeType, extension, rawBase64 } =\n      parseBase64ImageDataUrl(imageUrl);\n    const id = `reference-${createHash('sha256')\n      .update(mimeType)\n      .update('\\0')\n      .update(Buffer.from(rawBase64, 'base64'))\n      .digest('hex')}`;\n    const shouldWriteFileCopy =\n      this.mode === 'directory' || this.alsoWriteFileCopy;\n    const fileLocation = shouldWriteFileCopy\n      ? await this.writeImageFileIfNeeded({ id, extension, rawBase64 })\n      : null;\n\n    if (this.mode === 'inline') {\n      if (!this.writeInlineImage) {\n        throw new Error(\n          'ReportImageStore: writeInlineImage is required in inline mode',\n        );\n      }\n      if (!this.writtenInlineIds.has(id)) {\n        await this.writeInlineImage(id, imageUrl);\n        this.writtenInlineIds.add(id);\n      }\n      return {\n        type: 'midscene_image_url_ref',\n        id,\n        mimeType,\n        storage: 'inline',\n      };\n    }\n\n    if (!fileLocation) {\n      throw new Error(\n        'ReportImageStore: file persistence is required in directory mode',\n      );\n    }\n    return {\n      type: 'midscene_image_url_ref',\n      id,\n      mimeType,\n      storage: 'file',\n      path: fileLocation.relativePath,\n    };\n  }\n\n  private async ensureExistingInlineImageIdsLoaded(): Promise<void> {\n    if (!this.shouldReuseExistingInlineReport) return;\n    if (!this.existingInlineImageIdsPromise) {\n      this.existingInlineImageIdsPromise = (async () => {\n        try {\n          const imageIds = await collectImageScriptIds(this.reportPath);\n          for (const imageId of imageIds) this.writtenInlineIds.add(imageId);\n        } catch (error) {\n          if (\n            typeof error === 'object' &&\n            error !== null &&\n            'code' in error &&\n            error.code === 'ENOENT'\n          ) {\n            return;\n          }\n          throw new Error(\n            `ReportImageStore: failed to index existing inline images from ${this.reportPath}`,\n            { cause: error },\n          );\n        }\n      })();\n    }\n    await this.existingInlineImageIdsPromise;\n  }\n\n  private async persistToSharedFileIfNeeded(\n    screenshot: ScreenshotItem,\n    options: {\n      markAsPersisted: boolean;\n    },\n  ): Promise<ScreenshotRef> {\n    const { relativePath, absolutePath } = await this.writeImageFileIfNeeded({\n      id: screenshot.id,\n      extension: screenshot.extension,\n      rawBase64: screenshot.rawBase64,\n    });\n\n    if (options.markAsPersisted) {\n      return screenshot.markPersistedToPath(relativePath, absolutePath);\n    }\n\n    return screenshot.registerPersistedFileCopy(relativePath, absolutePath);\n  }\n\n  private async writeImageFileIfNeeded(image: {\n    id: string;\n    extension: string;\n    rawBase64: string;\n  }): Promise<{ relativePath: string; absolutePath: string }> {\n    const screenshotsDir = this.screenshotsDir;\n    if (!screenshotsDir) {\n      throw new Error(\n        'ReportImageStore: screenshotsDir is required when file persistence is enabled',\n      );\n    }\n    if (!existsSync(screenshotsDir)) {\n      mkdirSync(screenshotsDir, { recursive: true });\n    }\n\n    const fileName = `${image.id}.${image.extension}`;\n    const relativePath = `./screenshots/${fileName}`;\n    const absolutePath = join(screenshotsDir, fileName);\n    if (!this.writtenFileIds.has(image.id)) {\n      await writeFileAsync(\n        absolutePath,\n        Buffer.from(image.rawBase64, 'base64'),\n      );\n      this.writtenFileIds.add(image.id);\n    }\n    return { relativePath, absolutePath };\n  }\n\n  loadDataUri(refInput: unknown): string {\n    const ref = normalizeStoredImageRef(refInput);\n    if (!ref) {\n      throw new Error('ReportImageStore: invalid image reference');\n    }\n\n    const resolved = resolveImageSource(ref, {\n      reportPath: this.reportPath,\n      imageDirectory: this.screenshotsDir,\n    });\n\n    if (resolved.type === 'data-uri') {\n      return resolved.dataUri;\n    }\n\n    const data = readFileSync(resolved.filePath);\n    return `data:${resolved.mimeType};base64,${data.toString('base64')}`;\n  }\n\n  /** @deprecated Use loadDataUri. */\n  loadBase64(refInput: unknown): string {\n    const screenshotRef = normalizeScreenshotRef(refInput);\n    if (!screenshotRef) {\n      throw new Error('ReportImageStore: invalid screenshot reference');\n    }\n    return this.loadDataUri(screenshotRef);\n  }\n\n  cleanup(): void {\n    if (\n      this.mode === 'directory' &&\n      this.screenshotsDir &&\n      existsSync(this.screenshotsDir)\n    ) {\n      rmSync(this.screenshotsDir, { recursive: true, force: true });\n    }\n    this.writtenInlineIds.clear();\n    this.writtenFileIds.clear();\n    this.existingInlineImageIdsPromise = undefined;\n  }\n}\n\n/** @deprecated Use ReportImageStore. */\nexport { ReportImageStore as ScreenshotStore };\n"],"names":["base64ImageDataUrlPattern","parseBase64ImageDataUrl","imageUrl","match","Error","mimeType","imageFileExtensionForMimeType","isBase64ImageDataUrl","value","resolveImageSource","refInput","options","ref","normalizeStoredImageRef","id","resolveReportRelativePath","filePath","isAbsolute","join","dirname","explicitFilePath","existsSync","inlineDataUri","extractImageByIdSync","extension","imageRefFileExtension","companionImagePath","siblingImagePath","resolveScreenshotSource","normalizeScreenshotRef","ReportImageStore","screenshot","shouldWriteFileCopy","fileRef","rawBase64","createHash","Buffer","fileLocation","imageIds","collectImageScriptIds","imageId","error","relativePath","absolutePath","image","screenshotsDir","mkdirSync","fileName","writeFileAsync","resolved","data","readFileSync","screenshotRef","rmSync","undefined","Set","Boolean"],"mappings":"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"}

package/dist/es/dump/task-service-dump.mjs

@@ -0,0 +1,17 @@
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function isServiceDump(value) {
+    return isRecord(value) && 'string' == typeof value.type && isRecord(value.taskInfo);
+}
+function getTaskServiceDump(task) {
+    const log = task?.log;
+    if (isRecord(log) && isServiceDump(log.dump)) return log.dump;
+    return null;
+}
+function getTaskSearchArea(task) {
+    return task?.searchArea ?? getTaskServiceDump(task)?.taskInfo?.searchArea;
+}
+export { getTaskSearchArea, getTaskServiceDump };
+
+//# sourceMappingURL=task-service-dump.mjs.map

package/dist/es/dump/task-service-dump.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dump/task-service-dump.mjs","sources":["../../../src/dump/task-service-dump.ts"],"sourcesContent":["import type { ExecutionTask, Rect, ServiceDump } from '../types';\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n\nfunction isServiceDump(value: unknown): value is ServiceDump {\n  return (\n    isRecord(value) &&\n    typeof value.type === 'string' &&\n    isRecord(value.taskInfo)\n  );\n}\n\nexport function getTaskServiceDump(\n  task?: ExecutionTask | null,\n): ServiceDump | null {\n  const log = task?.log as unknown;\n\n  if (isRecord(log) && isServiceDump(log.dump)) {\n    return log.dump;\n  }\n\n  return null;\n}\n\nexport function getTaskSearchArea(\n  task?: ExecutionTask | null,\n): Rect | undefined {\n  return task?.searchArea ?? getTaskServiceDump(task)?.taskInfo?.searchArea;\n}\n"],"names":["isRecord","value","isServiceDump","getTaskServiceDump","task","log","getTaskSearchArea"],"mappings":"AAEA,SAASA,SAASC,KAAc;IAC9B,OAAO,AAAiB,YAAjB,OAAOA,SAAsBA,AAAU,SAAVA;AACtC;AAEA,SAASC,cAAcD,KAAc;IACnC,OACED,SAASC,UACT,AAAsB,YAAtB,OAAOA,MAAM,IAAI,IACjBD,SAASC,MAAM,QAAQ;AAE3B;AAEO,SAASE,mBACdC,IAA2B;IAE3B,MAAMC,MAAMD,MAAM;IAElB,IAAIJ,SAASK,QAAQH,cAAcG,IAAI,IAAI,GACzC,OAAOA,IAAI,IAAI;IAGjB,OAAO;AACT;AAEO,SAASC,kBACdF,IAA2B;IAE3B,OAAOA,MAAM,cAAcD,mBAAmBC,OAAO,UAAU;AACjE"}

package/dist/es/dump/task-status.mjs

@@ -0,0 +1,18 @@
+function deriveTaskStatus(task) {
+    const isFinished = 'finished' === task.status;
+    if ('failed' === task.status) return 'failed';
+    if (isFinished && (task.error || task.errorMessage)) return 'failed';
+    if (isFinished && 'WaitFor' === task.subType && false === task.output) return 'warning';
+    if ('Assert' === task.subType && isFinished && false === task.output) return 'failed';
+    if ('pending' === task.status) return 'pending';
+    if ('running' === task.status) return 'running';
+    if ('cancelled' === task.status) return 'cancelled';
+    return 'passed';
+}
+function deriveCaseStatus(executions) {
+    for (const execution of executions)for (const task of execution.tasks ?? [])if ('failed' === deriveTaskStatus(task)) return 'failed';
+    return 'passed';
+}
+export { deriveCaseStatus, deriveTaskStatus };
+
+//# sourceMappingURL=task-status.mjs.map

package/dist/es/dump/task-status.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dump/task-status.mjs","sources":["../../../src/dump/task-status.ts"],"sourcesContent":["/**\n * Single source of truth for turning raw task/execution dump data into a\n * semantic status.\n *\n * Both the report sidebar (per-step status icon) and the merged-report\n * status aggregation must agree on what \"failed\" means, otherwise a merged\n * report can mark a failing case as passed. Keeping the rules here — as pure\n * functions over plain dump fields — lets the front-end icons and the backend\n * `mergeReportFiles` attribute derivation share the exact same logic.\n */\nimport type { ExecutionTask, TestStatus } from '../types';\n\n/**\n * The subset of a task's fields needed to derive its status, picked from\n * `ExecutionTask` so the field names/types stay defined in one place. It is a\n * structural subset, so both the full `ExecutionTask` and the front-end task\n * variants (which carry extra fields) satisfy it.\n */\nexport type TaskStatusFields = Partial<\n  Pick<ExecutionTask, 'status' | 'subType' | 'error' | 'errorMessage'> & {\n    // `output` is only ever compared to `false`; keep it `unknown` rather than\n    // the picked generic `any` so the field stays type-safe for callers.\n    output: unknown;\n  }\n>;\n\nexport type DerivedTaskStatus =\n  | 'passed'\n  | 'failed'\n  | 'warning'\n  | 'pending'\n  | 'running'\n  | 'cancelled';\n\n/**\n * Derive a single task's semantic status from its raw dump fields. Mirrors the\n * historical `getStatusIcon` logic in the report sidebar so icons and merged\n * status never diverge.\n */\nexport function deriveTaskStatus(task: TaskStatusFields): DerivedTaskStatus {\n  const isFinished = task.status === 'finished';\n\n  // Hard failure: the task threw / was aborted (status === 'failed', e.g. a\n  // failed Assert which throws `Assertion failed`, or a locate failure), or it\n  // finished but still carries an error.\n  if (task.status === 'failed') {\n    return 'failed';\n  }\n  if (isFinished && (task.error || task.errorMessage)) {\n    return 'failed';\n  }\n\n  // A `WaitFor` that finished falsy is a warning, not a hard failure.\n  if (isFinished && task.subType === 'WaitFor' && task.output === false) {\n    return 'warning';\n  }\n\n  // An `Assert` that finished with a false result is a failure. Callers using\n  // `keepRawResponse` (including the YAML player) receive `{ pass: false }`\n  // and throw at the orchestration layer after this task has been recorded.\n  if (task.subType === 'Assert' && isFinished && task.output === false) {\n    return 'failed';\n  }\n\n  if (task.status === 'pending') return 'pending';\n  if (task.status === 'running') return 'running';\n  if (task.status === 'cancelled') return 'cancelled';\n\n  // finished, no error\n  return 'passed';\n}\n\n/**\n * Aggregate the tasks of one case (a list of executions) into a single\n * `TestStatus`. A case is `failed` when any of its tasks derives to `failed`;\n * otherwise it is `passed`. Warnings, pending/running/cancelled steps do not by\n * themselves fail a case.\n *\n * This only ever produces `passed` / `failed`; the finer `timedOut` /\n * `skipped` / `interrupted` statuses can only come from a source report that\n * already recorded them (e.g. a Playwright run), which callers should prefer\n * when available.\n */\nexport function deriveCaseStatus(\n  executions: Array<{ tasks?: TaskStatusFields[] }>,\n): TestStatus {\n  for (const execution of executions) {\n    for (const task of execution.tasks ?? []) {\n      if (deriveTaskStatus(task) === 'failed') {\n        return 'failed';\n      }\n    }\n  }\n  return 'passed';\n}\n"],"names":["deriveTaskStatus","task","isFinished","deriveCaseStatus","executions","execution"],"mappings":"AAuCO,SAASA,iBAAiBC,IAAsB;IACrD,MAAMC,aAAaD,AAAgB,eAAhBA,KAAK,MAAM;IAK9B,IAAIA,AAAgB,aAAhBA,KAAK,MAAM,EACb,OAAO;IAET,IAAIC,cAAeD,CAAAA,KAAK,KAAK,IAAIA,KAAK,YAAW,GAC/C,OAAO;IAIT,IAAIC,cAAcD,AAAiB,cAAjBA,KAAK,OAAO,IAAkBA,AAAgB,UAAhBA,KAAK,MAAM,EACzD,OAAO;IAMT,IAAIA,AAAiB,aAAjBA,KAAK,OAAO,IAAiBC,cAAcD,AAAgB,UAAhBA,KAAK,MAAM,EACxD,OAAO;IAGT,IAAIA,AAAgB,cAAhBA,KAAK,MAAM,EAAgB,OAAO;IACtC,IAAIA,AAAgB,cAAhBA,KAAK,MAAM,EAAgB,OAAO;IACtC,IAAIA,AAAgB,gBAAhBA,KAAK,MAAM,EAAkB,OAAO;IAGxC,OAAO;AACT;AAaO,SAASE,iBACdC,UAAiD;IAEjD,KAAK,MAAMC,aAAaD,WACtB,KAAK,MAAMH,QAAQI,UAAU,KAAK,IAAI,EAAE,CACtC,IAAIL,AAA2B,aAA3BA,iBAAiBC,OACnB,OAAO;IAIb,OAAO;AACT"}

package/dist/es/element-describer.mjs

@@ -0,0 +1,198 @@
+import { assert } from "@aiscene/shared/utils";
+import { createScreenshotBoundUIContext } from "./agent/utils.mjs";
+import { buildDetailedLocateParam } from "./yaml/utils.mjs";
+const distanceOfTwoPoints = (p1, p2)=>{
+    const [x1, y1] = p1;
+    const [x2, y2] = p2;
+    return Math.round(Math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2));
+};
+const includedInRect = (point, rect)=>{
+    const [x, y] = point;
+    const { left, top, width, height } = rect;
+    return x >= left && x <= left + width && y >= top && y <= top + height;
+};
+const buildLocateValidatorResult = (expectCenter, located, verifyLocateOption)=>{
+    const distance = distanceOfTwoPoints(expectCenter, located.center);
+    const included = includedInRect(expectCenter, located.rect);
+    const pass = distance <= (verifyLocateOption?.centerDistanceThreshold || 20) || included;
+    return {
+        pass,
+        rect: located.rect,
+        center: located.center,
+        centerDistance: distance,
+        includedInRect: included
+    };
+};
+function assertPositiveSize(size, label) {
+    assert(size && Number.isFinite(size.width) && Number.isFinite(size.height) && size.width > 0 && size.height > 0, `${label} must include positive width and height`);
+}
+const mapPointToScreenshotSpace = (center, screenshotSize, opt)=>{
+    const coordinateSpace = opt.coordinateSpace || 'screenshot';
+    if ('screenshot' === coordinateSpace) return center;
+    assertPositiveSize(opt.logicalSize, 'logicalSize is required when coordinateSpace is logical');
+    return [
+        center[0] * screenshotSize.width / opt.logicalSize.width,
+        center[1] * screenshotSize.height / opt.logicalSize.height
+    ];
+};
+const createScreenshotBoundLocatorContext = async (center, opt)=>{
+    const screenshotContext = opt?.screenshotBase64 ? await createScreenshotBoundUIContext(opt.screenshotBase64, opt) : void 0;
+    const targetCenter = screenshotContext ? mapPointToScreenshotSpace(center, screenshotContext.shotSize, opt || {}) : center;
+    return {
+        screenshotContext,
+        locateOpt: screenshotContext ? {
+            uiContext: screenshotContext
+        } : void 0,
+        targetCenter
+    };
+};
+async function verifyLocator(runtime, prompt, locateOpt, expectCenter, verifyLocateOption) {
+    return locateAndVerify(runtime, prompt, expectCenter, {
+        centerDistanceThreshold: verifyLocateOption?.centerDistanceThreshold,
+        deepLocate: verifyLocateOption?.deepLocate,
+        uiContext: locateOpt?.uiContext
+    });
+}
+function applyLocatorVerifyFn(locatorVerifyFn, input) {
+    if (!locatorVerifyFn) return input.verifyResult;
+    const customResult = locatorVerifyFn(input);
+    if ('boolean' == typeof customResult) return {
+        ...input.verifyResult,
+        pass: customResult
+    };
+    return customResult;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function describeElementAtPoint(runtime, center, opt) {
+    const { verifyPrompt = true, retryLimit = 3 } = opt || {};
+    const { screenshotContext, locateOpt, targetCenter } = await createScreenshotBoundLocatorContext(center, opt);
+    let success = false;
+    let retryCount = 0;
+    let resultPrompt = '';
+    const autoRetryDeepDescribe = opt?.deepDescribe === void 0;
+    const autoRetryDeepLocate = opt?.deepLocate === void 0;
+    let deepDescribe = opt?.deepDescribe || false;
+    let deepLocate = opt?.deepLocate || false;
+    let verifyResult;
+    let lastError;
+    let failureStage;
+    while(!success && retryCount < retryLimit){
+        if (retryCount >= 1 && autoRetryDeepDescribe) deepDescribe = true;
+        if (retryCount >= 1 && autoRetryDeepLocate) deepLocate = true;
+        const describeModelRuntime = runtime.describeModelRuntime;
+        const locateModelRuntime = runtime.locateModelRuntime;
+        const retryRuntime = {
+            ...runtime,
+            describeModelRuntime,
+            locateModelRuntime
+        };
+        const describeOpt = screenshotContext ? {
+            deepDescribe,
+            context: screenshotContext
+        } : {
+            deepDescribe
+        };
+        let text;
+        try {
+            text = await retryRuntime.service.describe(targetCenter, retryRuntime.describeModelRuntime, describeOpt);
+        } catch (error) {
+            return {
+                prompt: resultPrompt,
+                deepLocate,
+                deepDescribe,
+                verifyResult,
+                success: false,
+                error: errorMessage(error),
+                failureStage: 'describe'
+            };
+        }
+        if (!text.description) return {
+            prompt: resultPrompt,
+            deepLocate,
+            deepDescribe,
+            verifyResult,
+            success: false,
+            error: `failed to describe element at [${targetCenter}]`,
+            failureStage: 'describe'
+        };
+        resultPrompt = text.description;
+        if (!verifyPrompt) {
+            opt?.onProgress?.({
+                prompt: resultPrompt,
+                deepDescribe,
+                deepLocate
+            });
+            success = true;
+            break;
+        }
+        try {
+            const candidateVerifyResult = await verifyLocator(retryRuntime, resultPrompt, locateOpt, targetCenter, {
+                ...opt,
+                deepLocate
+            });
+            verifyResult = applyLocatorVerifyFn(opt?.locatorVerifyFn, {
+                prompt: resultPrompt,
+                expectCenter: targetCenter,
+                retryCount,
+                verifyResult: candidateVerifyResult
+            });
+            opt?.onProgress?.({
+                prompt: resultPrompt,
+                deepDescribe,
+                deepLocate,
+                verifyResult
+            });
+            if (verifyResult.pass) {
+                success = true;
+                break;
+            }
+            lastError = void 0;
+            failureStage = 'verify';
+        } catch (error) {
+            lastError = errorMessage(error);
+            failureStage = 'verify';
+            opt?.onProgress?.({
+                prompt: resultPrompt,
+                deepDescribe,
+                deepLocate
+            });
+        }
+        retryCount++;
+    }
+    return {
+        prompt: resultPrompt,
+        deepLocate,
+        deepDescribe,
+        verifyResult,
+        success,
+        error: success || !verifyPrompt ? void 0 : lastError || 'describeElementAtPoint verify failed',
+        failureStage: success ? void 0 : failureStage
+    };
+}
+async function verifyElementDescriptionAtPoint(runtime, description, center, opt) {
+    assert(description?.trim(), "description must not be empty");
+    const { locateOpt, targetCenter } = await createScreenshotBoundLocatorContext(center, opt);
+    return verifyLocator(runtime, description, locateOpt, targetCenter, opt);
+}
+async function locateAndVerify(runtime, description, center, opt) {
+    assert(description?.trim(), "description must not be empty");
+    const { screenshotContext, targetCenter } = await createScreenshotBoundLocatorContext(center, opt);
+    const context = opt?.uiContext || screenshotContext;
+    const locateParam = buildDetailedLocateParam(description, {
+        cacheable: opt?.cacheable,
+        deepLocate: opt?.deepLocate,
+        xpath: opt?.xpath
+    });
+    assert(locateParam, 'cannot get locate param for service locate');
+    const locateResult = await runtime.service.locate(locateParam, context ? {
+        context
+    } : {}, runtime.locateModelRuntime, opt?.abortSignal);
+    assert(locateResult.element, `Element not found: ${description}`);
+    const verifyResult = buildLocateValidatorResult(targetCenter, locateResult.element, opt);
+    return verifyResult;
+}
+export { describeElementAtPoint, verifyElementDescriptionAtPoint, verifyLocator };
+
+//# sourceMappingURL=element-describer.mjs.map

package/dist/es/element-describer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-describer.mjs","sources":["../../src/element-describer.ts"],"sourcesContent":["import type { ModelRuntime } from '@/ai-model/models';\nimport { assert } from '@aiscene/shared/utils';\nimport { createScreenshotBoundUIContext } from './agent/utils';\nimport type Service from './service';\nimport type {\n  AgentDescribeElementAtPointResult,\n  LocateOption,\n  LocateResultElement,\n  LocateValidatorResult,\n  LocatorValidatorOption,\n  Rect,\n  Size,\n  UIContext,\n} from './types';\nimport { buildDetailedLocateParam } from './yaml/utils';\n\nexport type DescribeElementCoordinateSpace = 'screenshot' | 'logical';\n\nexport type LocatorVerifyFn = (input: {\n  prompt: string;\n  expectCenter: [number, number];\n  retryCount: number;\n  verifyResult: LocateValidatorResult;\n}) => LocateValidatorResult | boolean;\n\nexport type DescribeElementAtPointOptions = {\n  verifyPrompt?: boolean;\n  retryLimit?: number;\n  deepDescribe?: boolean;\n  deepLocate?: boolean;\n  locatorVerifyFn?: LocatorVerifyFn;\n  screenshotBase64?: string;\n  screenshotSize?: Size;\n  coordinateSpace?: DescribeElementCoordinateSpace;\n  logicalSize?: Size;\n  onProgress?: (progress: {\n    prompt?: string;\n    deepDescribe?: boolean;\n    deepLocate?: boolean;\n    verifyResult?: LocateValidatorResult;\n  }) => void;\n} & LocatorValidatorOption;\n\ntype ScreenshotBoundContextOptions = {\n  screenshotBase64?: string;\n  screenshotSize?: Size;\n  coordinateSpace?: DescribeElementCoordinateSpace;\n  logicalSize?: Size;\n};\n\nexport type VerifyElementDescriptionAtPointOptions =\n  ScreenshotBoundContextOptions & LocatorValidatorOption;\n\ntype LocateAndVerifyOptions = VerifyElementDescriptionAtPointOptions &\n  Pick<LocateOption, 'cacheable' | 'deepLocate' | 'xpath'> & {\n    abortSignal?: AbortSignal;\n  };\n\nexport type ElementDescriberRuntime = {\n  service: Pick<Service, 'describe' | 'locate'>;\n  describeModelRuntime: ModelRuntime;\n  locateModelRuntime: ModelRuntime;\n};\n\ntype ServiceDescribeOptions = NonNullable<\n  Parameters<ElementDescriberRuntime['service']['describe']>[2]\n>;\n\nconst distanceOfTwoPoints = (p1: [number, number], p2: [number, number]) => {\n  const [x1, y1] = p1;\n  const [x2, y2] = p2;\n  return Math.round(Math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2));\n};\n\nconst includedInRect = (point: [number, number], rect: Rect) => {\n  const [x, y] = point;\n  const { left, top, width, height } = rect;\n  return x >= left && x <= left + width && y >= top && y <= top + height;\n};\n\nconst buildLocateValidatorResult = (\n  expectCenter: [number, number],\n  located: Pick<LocateResultElement, 'center' | 'rect'>,\n  verifyLocateOption?: LocatorValidatorOption,\n): LocateValidatorResult => {\n  const distance = distanceOfTwoPoints(expectCenter, located.center);\n  const included = includedInRect(expectCenter, located.rect);\n  const pass =\n    distance <= (verifyLocateOption?.centerDistanceThreshold || 20) || included;\n  return {\n    pass,\n    rect: located.rect,\n    center: located.center,\n    centerDistance: distance,\n    includedInRect: included,\n  };\n};\n\nfunction assertPositiveSize(\n  size: Size | undefined,\n  label: string,\n): asserts size is Size {\n  assert(\n    size &&\n      Number.isFinite(size.width) &&\n      Number.isFinite(size.height) &&\n      size.width > 0 &&\n      size.height > 0,\n    `${label} must include positive width and height`,\n  );\n}\n\nconst mapPointToScreenshotSpace = (\n  center: [number, number],\n  screenshotSize: Size,\n  opt: ScreenshotBoundContextOptions,\n): [number, number] => {\n  const coordinateSpace = opt.coordinateSpace || 'screenshot';\n  if (coordinateSpace === 'screenshot') {\n    return center;\n  }\n\n  assertPositiveSize(\n    opt.logicalSize,\n    'logicalSize is required when coordinateSpace is logical',\n  );\n  return [\n    (center[0] * screenshotSize.width) / opt.logicalSize.width,\n    (center[1] * screenshotSize.height) / opt.logicalSize.height,\n  ];\n};\n\nconst createScreenshotBoundLocatorContext = async (\n  center: [number, number],\n  opt?: ScreenshotBoundContextOptions,\n): Promise<{\n  screenshotContext?: UIContext;\n  locateOpt?: LocateOption;\n  targetCenter: [number, number];\n}> => {\n  const screenshotContext = opt?.screenshotBase64\n    ? await createScreenshotBoundUIContext(opt.screenshotBase64, opt)\n    : undefined;\n  const targetCenter = screenshotContext\n    ? mapPointToScreenshotSpace(center, screenshotContext.shotSize, opt || {})\n    : center;\n  return {\n    screenshotContext,\n    locateOpt: screenshotContext ? { uiContext: screenshotContext } : undefined,\n    targetCenter,\n  };\n};\n\nexport async function verifyLocator(\n  runtime: Pick<ElementDescriberRuntime, 'service' | 'locateModelRuntime'>,\n  prompt: string,\n  locateOpt: LocateOption | undefined,\n  expectCenter: [number, number],\n  verifyLocateOption?: LocatorValidatorOption &\n    Pick<LocateOption, 'deepLocate'>,\n): Promise<LocateValidatorResult> {\n  return locateAndVerify(runtime, prompt, expectCenter, {\n    centerDistanceThreshold: verifyLocateOption?.centerDistanceThreshold,\n    deepLocate: verifyLocateOption?.deepLocate,\n    uiContext: locateOpt?.uiContext,\n  });\n}\n\nfunction applyLocatorVerifyFn(\n  locatorVerifyFn: LocatorVerifyFn | undefined,\n  input: Parameters<LocatorVerifyFn>[0],\n): LocateValidatorResult {\n  if (!locatorVerifyFn) {\n    return input.verifyResult;\n  }\n  const customResult = locatorVerifyFn(input);\n  if (typeof customResult === 'boolean') {\n    return {\n      ...input.verifyResult,\n      pass: customResult,\n    };\n  }\n  return customResult;\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nexport async function describeElementAtPoint(\n  runtime: ElementDescriberRuntime,\n  center: [number, number],\n  opt?: DescribeElementAtPointOptions,\n): Promise<AgentDescribeElementAtPointResult> {\n  const { verifyPrompt = true, retryLimit = 3 } = opt || {};\n  const { screenshotContext, locateOpt, targetCenter } =\n    await createScreenshotBoundLocatorContext(center, opt);\n\n  let success = false;\n  let retryCount = 0;\n  let resultPrompt = '';\n  const autoRetryDeepDescribe = opt?.deepDescribe === undefined;\n  const autoRetryDeepLocate = opt?.deepLocate === undefined;\n  let deepDescribe = opt?.deepDescribe || false;\n  let deepLocate = opt?.deepLocate || false;\n  let verifyResult: LocateValidatorResult | undefined;\n  let lastError: string | undefined;\n  let failureStage: AgentDescribeElementAtPointResult['failureStage'];\n\n  while (!success && retryCount < retryLimit) {\n    if (retryCount >= 1 && autoRetryDeepDescribe) {\n      deepDescribe = true;\n    }\n    if (retryCount >= 1 && autoRetryDeepLocate) {\n      deepLocate = true;\n    }\n    const describeModelRuntime = runtime.describeModelRuntime;\n    const locateModelRuntime = runtime.locateModelRuntime;\n    const retryRuntime: ElementDescriberRuntime = {\n      ...runtime,\n      describeModelRuntime,\n      locateModelRuntime,\n    };\n    const describeOpt: ServiceDescribeOptions = screenshotContext\n      ? {\n          deepDescribe,\n          context: screenshotContext,\n        }\n      : {\n          deepDescribe,\n        };\n    let text: Awaited<\n      ReturnType<ElementDescriberRuntime['service']['describe']>\n    >;\n    try {\n      text = await retryRuntime.service.describe(\n        targetCenter,\n        retryRuntime.describeModelRuntime,\n        describeOpt,\n      );\n    } catch (error) {\n      return {\n        prompt: resultPrompt,\n        deepLocate,\n        deepDescribe,\n        verifyResult,\n        success: false,\n        error: errorMessage(error),\n        failureStage: 'describe',\n      };\n    }\n    if (!text.description) {\n      return {\n        prompt: resultPrompt,\n        deepLocate,\n        deepDescribe,\n        verifyResult,\n        success: false,\n        error: `failed to describe element at [${targetCenter}]`,\n        failureStage: 'describe',\n      };\n    }\n    resultPrompt = text.description;\n    if (!verifyPrompt) {\n      opt?.onProgress?.({\n        prompt: resultPrompt,\n        deepDescribe,\n        deepLocate,\n      });\n      success = true;\n      break;\n    }\n\n    try {\n      const candidateVerifyResult = await verifyLocator(\n        retryRuntime,\n        resultPrompt,\n        locateOpt,\n        targetCenter,\n        {\n          ...opt,\n          deepLocate,\n        },\n      );\n      verifyResult = applyLocatorVerifyFn(opt?.locatorVerifyFn, {\n        prompt: resultPrompt,\n        expectCenter: targetCenter,\n        retryCount,\n        verifyResult: candidateVerifyResult,\n      });\n      opt?.onProgress?.({\n        prompt: resultPrompt,\n        deepDescribe,\n        deepLocate,\n        verifyResult,\n      });\n      if (verifyResult.pass) {\n        success = true;\n        break;\n      }\n      lastError = undefined;\n      failureStage = 'verify';\n    } catch (error) {\n      lastError = errorMessage(error);\n      failureStage = 'verify';\n      opt?.onProgress?.({\n        prompt: resultPrompt,\n        deepDescribe,\n        deepLocate,\n      });\n    }\n    retryCount++;\n  }\n\n  return {\n    prompt: resultPrompt,\n    deepLocate,\n    deepDescribe,\n    verifyResult,\n    success,\n    error:\n      success || !verifyPrompt\n        ? undefined\n        : lastError || 'describeElementAtPoint verify failed',\n    failureStage: success ? undefined : failureStage,\n  };\n}\n\nexport async function verifyElementDescriptionAtPoint(\n  runtime: ElementDescriberRuntime,\n  description: string,\n  center: [number, number],\n  opt?: VerifyElementDescriptionAtPointOptions,\n): Promise<LocateValidatorResult> {\n  assert(description?.trim(), 'description must not be empty');\n  const { locateOpt, targetCenter } = await createScreenshotBoundLocatorContext(\n    center,\n    opt,\n  );\n\n  return verifyLocator(runtime, description, locateOpt, targetCenter, opt);\n}\n\nasync function locateAndVerify(\n  runtime: Pick<ElementDescriberRuntime, 'service' | 'locateModelRuntime'>,\n  description: string,\n  center: [number, number],\n  opt?: LocateAndVerifyOptions & {\n    uiContext?: UIContext;\n  },\n): Promise<LocateValidatorResult> {\n  assert(description?.trim(), 'description must not be empty');\n  const { screenshotContext, targetCenter } =\n    await createScreenshotBoundLocatorContext(center, opt);\n  const context = opt?.uiContext || screenshotContext;\n  const locateParam = buildDetailedLocateParam(description, {\n    cacheable: opt?.cacheable,\n    deepLocate: opt?.deepLocate,\n    xpath: opt?.xpath,\n  });\n  assert(locateParam, 'cannot get locate param for service locate');\n\n  const locateResult = await runtime.service.locate(\n    locateParam,\n    context ? { context } : {},\n    runtime.locateModelRuntime,\n    opt?.abortSignal,\n  );\n  assert(locateResult.element, `Element not found: ${description}`);\n  const verifyResult = buildLocateValidatorResult(\n    targetCenter,\n    locateResult.element,\n    opt,\n  );\n  return verifyResult;\n}\n"],"names":["distanceOfTwoPoints","p1","p2","x1","y1","x2","y2","Math","includedInRect","point","rect","x","y","left","top","width","height","buildLocateValidatorResult","expectCenter","located","verifyLocateOption","distance","included","pass","assertPositiveSize","size","label","assert","Number","mapPointToScreenshotSpace","center","screenshotSize","opt","coordinateSpace","createScreenshotBoundLocatorContext","screenshotContext","createScreenshotBoundUIContext","undefined","targetCenter","verifyLocator","runtime","prompt","locateOpt","locateAndVerify","applyLocatorVerifyFn","locatorVerifyFn","input","customResult","errorMessage","error","Error","String","describeElementAtPoint","verifyPrompt","retryLimit","success","retryCount","resultPrompt","autoRetryDeepDescribe","autoRetryDeepLocate","deepDescribe","deepLocate","verifyResult","lastError","failureStage","describeModelRuntime","locateModelRuntime","retryRuntime","describeOpt","text","candidateVerifyResult","verifyElementDescriptionAtPoint","description","context","locateParam","buildDetailedLocateParam","locateResult"],"mappings":"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"}

package/dist/es/errors.mjs

@@ -0,0 +1,20 @@
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class ServiceError extends Error {
+    constructor(message, dump){
+        super(message), _define_property(this, "dump", void 0);
+        this.name = 'ServiceError';
+        this.dump = dump;
+    }
+}
+export { ServiceError };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/es/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","sources":["../../src/errors.ts"],"sourcesContent":["import type { ServiceDump } from './types';\n\nexport class ServiceError extends Error {\n  dump: ServiceDump;\n\n  constructor(message: string, dump: ServiceDump) {\n    super(message);\n    this.name = 'ServiceError';\n    this.dump = dump;\n  }\n}\n"],"names":["ServiceError","Error","message","dump"],"mappings":";;;;;;;;;;AAEO,MAAMA,qBAAqBC;IAGhC,YAAYC,OAAe,EAAEC,IAAiB,CAAE;QAC9C,KAAK,CAACD,UAHR;QAIE,IAAI,CAAC,IAAI,GAAG;QACZ,IAAI,CAAC,IAAI,GAAGC;IACd;AACF"}