@godscene/core 1.7.11

package/dist/es/report-markdown.mjs

@@ -0,0 +1,216 @@
+import { basename } from "node:path";
+import { extractInsightParam, paramStr, typeStr } from "./agent/ui-utils.mjs";
+import { ScreenshotItem } from "./screenshot-item.mjs";
+import { normalizeScreenshotRef } from "./dump/screenshot-store.mjs";
+function toExecutionDump(execution) {
+    if (!execution || 'object' != typeof execution) throw new Error('executionToMarkdown: execution is required');
+    if (!Array.isArray(execution.tasks)) throw new Error('executionToMarkdown: execution.tasks must be an array');
+    if (!execution.name) throw new Error('executionToMarkdown: execution.name is required');
+    return execution;
+}
+function toReportDump(report) {
+    if (!report || 'object' != typeof report) throw new Error('reportToMarkdown: report is required');
+    if (!Array.isArray(report.executions)) throw new Error('reportToMarkdown: report.executions must be an array');
+    return report;
+}
+function formatTime(ts) {
+    if ('number' != typeof ts || Number.isNaN(ts)) return 'N/A';
+    return new Date(ts).toISOString();
+}
+function resolveTaskTiming(task) {
+    const timing = task.timing;
+    if (!timing) return {};
+    const start = timing.start ?? timing.callAiStart ?? timing.callActionStart;
+    const end = timing.end ?? timing.callAiEnd ?? timing.callActionEnd ?? timing.captureAfterCallingSnapshotEnd;
+    const cost = timing.cost ?? ('number' == typeof start && 'number' == typeof end ? end - start : void 0);
+    return {
+        start,
+        end,
+        cost
+    };
+}
+function safeTaskParam(task) {
+    const readable = paramStr(task);
+    if (readable) return readable;
+    if ('Insight' === task.type) return extractInsightParam(task.param).content;
+    return '';
+}
+function formatSize(size) {
+    if (!size || 'number' != typeof size.width || 'number' != typeof size.height || Number.isNaN(size.width) || Number.isNaN(size.height)) return;
+    return `${size.width} x ${size.height}`;
+}
+function extractLocateCenter(task) {
+    const outputCenter = task.output?.element?.center;
+    if (Array.isArray(outputCenter) && outputCenter.length >= 2 && 'number' == typeof outputCenter[0] && 'number' == typeof outputCenter[1]) return [
+        outputCenter[0],
+        outputCenter[1]
+    ];
+    const paramLocateCenter = task.param?.locate?.center;
+    if (Array.isArray(paramLocateCenter) && paramLocateCenter.length >= 2 && 'number' == typeof paramLocateCenter[0] && 'number' == typeof paramLocateCenter[1]) return [
+        paramLocateCenter[0],
+        paramLocateCenter[1]
+    ];
+    const paramCenter = task.param?.center;
+    if (Array.isArray(paramCenter) && paramCenter.length >= 2 && 'number' == typeof paramCenter[0] && 'number' == typeof paramCenter[1]) return [
+        paramCenter[0],
+        paramCenter[1]
+    ];
+}
+function tryExtractBase64(screenshot) {
+    if (!screenshot || 'object' != typeof screenshot) return;
+    const s = screenshot;
+    if ('string' == typeof s.base64 && s.base64.length > 0) return s.base64;
+}
+function screenshotAttachment(screenshot, screenshotBaseDir, executionIndex, taskIndex) {
+    if (screenshot instanceof ScreenshotItem) {
+        const ext = screenshot.extension;
+        const suggestedFileName = `execution-${executionIndex + 1}-task-${taskIndex + 1}-${screenshot.id}.${ext}`;
+        const filePath = `${screenshotBaseDir}/${suggestedFileName}`;
+        return {
+            markdown: `\n![task-${taskIndex + 1}](${filePath})`,
+            attachment: {
+                id: screenshot.id,
+                suggestedFileName,
+                filePath,
+                mimeType: `image/${'jpeg' === ext ? 'jpeg' : 'png'}`,
+                executionIndex,
+                taskIndex,
+                base64Data: tryExtractBase64(screenshot)
+            }
+        };
+    }
+    const ref = normalizeScreenshotRef(screenshot);
+    if (ref) {
+        const ext = 'image/jpeg' === ref.mimeType ? 'jpeg' : 'png';
+        const suggestedFileName = `execution-${executionIndex + 1}-task-${taskIndex + 1}-${ref.id}.${ext}`;
+        const filePath = ref.path || `${screenshotBaseDir}/${suggestedFileName}`;
+        return {
+            markdown: `\n![task-${taskIndex + 1}](${filePath})`,
+            attachment: {
+                id: ref.id,
+                suggestedFileName,
+                filePath,
+                mimeType: ref.mimeType,
+                executionIndex,
+                taskIndex,
+                base64Data: tryExtractBase64(screenshot)
+            }
+        };
+    }
+    const base64 = tryExtractBase64(screenshot);
+    if (base64) {
+        const ext = base64.startsWith('data:image/jpeg') ? 'jpeg' : 'png';
+        const id = `restored-${executionIndex + 1}-${taskIndex + 1}`;
+        const suggestedFileName = `execution-${executionIndex + 1}-task-${taskIndex + 1}-${id}.${ext}`;
+        const filePath = `${screenshotBaseDir}/${suggestedFileName}`;
+        return {
+            markdown: `\n![task-${taskIndex + 1}](${filePath})`,
+            attachment: {
+                id,
+                suggestedFileName,
+                filePath,
+                mimeType: `image/${ext}`,
+                executionIndex,
+                taskIndex,
+                base64Data: base64
+            }
+        };
+    }
+    throw new Error(`executionToMarkdown: missing screenshot for execution #${executionIndex + 1} task #${taskIndex + 1}`);
+}
+function recorderMarkdownSection(recorder, screenshotBaseDir, executionIndex, taskIndex) {
+    if (!recorder?.length) return {
+        lines: [],
+        attachments: []
+    };
+    const lines = [
+        '',
+        '### Recorder'
+    ];
+    const attachments = [];
+    recorder.forEach((item, recorderIndex)=>{
+        lines.push(`- #${recorderIndex + 1} type=${item.type}, ts=${formatTime(item.ts)}, timing=${item.timing || 'N/A'}`);
+        if (!item.screenshot) return;
+        const imageResult = screenshotAttachment(item.screenshot, screenshotBaseDir, executionIndex, taskIndex);
+        lines.push(imageResult.markdown);
+        attachments.push(imageResult.attachment);
+    });
+    return {
+        lines,
+        attachments
+    };
+}
+function renderExecution(executionRaw, executionIndex, options) {
+    const execution = toExecutionDump(executionRaw);
+    const screenshotBaseDir = options?.screenshotBaseDir ?? './screenshots';
+    const lines = [];
+    const attachments = [];
+    lines.push(`# ${execution.name}`);
+    if (execution.description) lines.push('', execution.description);
+    lines.push('', `- Execution start: ${formatTime(execution.logTime)}`);
+    lines.push(`- Task count: ${execution.tasks.length}`);
+    execution.tasks.forEach((task, taskIndex)=>{
+        const title = typeStr(task);
+        const detail = safeTaskParam(task);
+        const time = resolveTaskTiming(task);
+        lines.push('', `## ${taskIndex + 1}. ${title}${detail ? ` - ${detail}` : ''}`);
+        lines.push(`- Status: ${task.status || 'unknown'}`);
+        lines.push(`- Start: ${formatTime(time.start)}`);
+        lines.push(`- End: ${formatTime(time.end)}`);
+        lines.push(`- Cost(ms): ${'number' == typeof time.cost ? time.cost : 'N/A'}`);
+        lines.push(`- Screen size: ${formatSize(task.uiContext?.shotSize) || 'N/A'}`);
+        if ('Locate' === task.subType) {
+            const locateCenter = extractLocateCenter(task);
+            if (locateCenter) lines.push(`- Locate center: (${locateCenter[0]}, ${locateCenter[1]})`);
+        }
+        if (task.errorMessage) lines.push(`- Error: ${task.errorMessage}`);
+        if (task.uiContext?.screenshot) {
+            const imageResult = screenshotAttachment(task.uiContext.screenshot, screenshotBaseDir, executionIndex, taskIndex);
+            lines.push(imageResult.markdown);
+            attachments.push(imageResult.attachment);
+        }
+        const recorderSection = recorderMarkdownSection(task.recorder, screenshotBaseDir, executionIndex, taskIndex);
+        if (recorderSection.lines.length) {
+            lines.push(...recorderSection.lines);
+            attachments.push(...recorderSection.attachments);
+        }
+    });
+    return {
+        markdown: lines.join('\n'),
+        attachments
+    };
+}
+function reportFileName(execution, executionIndex) {
+    const safeName = execution.name.trim().replace(/\s+/g, '-').replace(/[^a-zA-Z0-9-_]/g, '') || `execution-${executionIndex + 1}`;
+    return `${executionIndex + 1}-${basename(safeName)}.md`;
+}
+function executionToMarkdown(execution, options) {
+    return renderExecution(execution, 0, options);
+}
+function reportToMarkdown(report) {
+    const reportDump = toReportDump(report);
+    const executionResults = reportDump.executions.map((execution, index)=>{
+        const rendered = renderExecution(execution, index);
+        return {
+            executionIndex: index,
+            executionName: execution.name,
+            markdown: rendered.markdown,
+            attachments: rendered.attachments,
+            suggestedFileName: reportFileName(execution, index)
+        };
+    });
+    const attachments = executionResults.flatMap((item)=>item.attachments);
+    const header = [
+        `# ${reportDump.groupName}`,
+        reportDump.groupDescription ? `\n${reportDump.groupDescription}` : '',
+        `\n- SDK Version: ${reportDump.sdkVersion}`,
+        `- Execution count: ${reportDump.executions.length}`,
+        '\n## Suggested execution markdown files',
+        ...executionResults.map((item)=>`- ${item.suggestedFileName} (${item.executionName})`)
+    ].filter(Boolean).join('\n');
+    return {
+        markdown: `${header}\n\n${executionResults.map((item)=>item.markdown).join('\n\n---\n\n')}`,
+        attachments
+    };
+}
+export { executionToMarkdown, reportToMarkdown };

package/dist/es/report.mjs

@@ -0,0 +1,287 @@
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { getMidsceneRunSubDir } from "@godscene/shared/common";
+import { antiEscapeScriptTag, logMsg } from "@godscene/shared/utils";
+import { getReportFileName } from "./agent/index.mjs";
+import { extractAllDumpScriptsSync, extractLastDumpScriptSync, getBaseUrlFixScript, streamDumpScriptsSync, streamImageScriptsToFile } from "./dump/html-utils.mjs";
+import { normalizeScreenshotRef, resolveScreenshotSource } from "./dump/screenshot-store.mjs";
+import { ReportActionDump } from "./types.mjs";
+import { getReportTpl, getVersion, reportHTMLContent } from "./utils.mjs";
+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;
+}
+function isDirectoryModeReport(reportFilePath) {
+    const reportDir = dirname(reportFilePath);
+    return 'index.html' === basename(reportFilePath) && existsSync(join(reportDir, 'screenshots'));
+}
+function dedupeExecutionsKeepLatest(executions) {
+    let noIdCounter = 0;
+    const deduped = new Map();
+    for (const exec of executions){
+        const key = exec.id || `__no_id_${noIdCounter++}`;
+        deduped.set(key, exec);
+    }
+    return Array.from(deduped.values());
+}
+function peekReportSdkVersion(reportFilePath) {
+    try {
+        const dump = extractLastDumpScriptSync(reportFilePath);
+        if (!dump) return;
+        const match = dump.match(/"sdkVersion"\s*:\s*"([^"]+)"/);
+        return match?.[1];
+    } catch  {
+        return;
+    }
+}
+const warnedMismatchedVersions = new Set();
+class ReportMergingTool {
+    createEmptyDumpString(groupName, groupDescription) {
+        return new ReportActionDump({
+            sdkVersion: '',
+            groupName,
+            groupDescription,
+            modelBriefs: [],
+            executions: []
+        }).serialize();
+    }
+    append(reportInfo) {
+        if (reportInfo.reportFilePath) {
+            const sourceVersion = peekReportSdkVersion(reportInfo.reportFilePath);
+            const currentVersion = getVersion();
+            if (sourceVersion && currentVersion && sourceVersion !== currentVersion && !warnedMismatchedVersions.has(sourceVersion)) {
+                warnedMismatchedVersions.add(sourceVersion);
+                logMsg(`[@godscene/core] ReportMergingTool version mismatch: source report was written by @godscene/core@${sourceVersion} but the merger is @godscene/core@${currentVersion}. This commonly means @godscene/core and the device package (e.g. @godscene/android) resolve to different versions in node_modules. Merged output may silently drop intermediate steps. Align the versions and reinstall (rm -rf node_modules package-lock.json && npm install).`);
+            }
+        }
+        this.reportInfos.push(reportInfo);
+    }
+    clear() {
+        this.reportInfos = [];
+    }
+    mergeDumpScripts(contents) {
+        const unescaped = contents.map((c)=>antiEscapeScriptTag(c)).filter((c)=>c.length > 0);
+        if (0 === unescaped.length) return '';
+        if (1 === unescaped.length) return unescaped[0];
+        const base = ReportActionDump.fromSerializedString(unescaped[0]);
+        const allExecutions = [
+            ...base.executions
+        ];
+        for(let i = 1; i < unescaped.length; i++){
+            const other = ReportActionDump.fromSerializedString(unescaped[i]);
+            allExecutions.push(...other.executions);
+        }
+        base.executions = dedupeExecutionsKeepLatest(allExecutions);
+        return base.serialize();
+    }
+    mergeReports(reportFileName = 'AUTO', opts) {
+        const { rmOriginalReports = false, overwrite = false } = opts ?? {};
+        if (0 === this.reportInfos.length) {
+            logMsg('No reports to merge');
+            return null;
+        }
+        const targetDir = getMidsceneRunSubDir('report');
+        const hasDirectoryModeReport = this.reportInfos.some((info)=>{
+            const reportFilePath = info.reportFilePath;
+            return Boolean(reportFilePath && isDirectoryModeReport(reportFilePath));
+        });
+        const resolvedName = 'AUTO' === reportFileName ? getReportFileName('merged-report') : reportFileName;
+        const outputFilePath = hasDirectoryModeReport ? resolve(targetDir, resolvedName, 'index.html') : resolve(targetDir, `${resolvedName}.html`);
+        if ('AUTO' !== reportFileName && existsSync(outputFilePath)) {
+            if (!overwrite) throw new Error(`Report file already exists: ${outputFilePath}\nSet overwrite to true to overwrite this file.`);
+            if (hasDirectoryModeReport) rmSync(dirname(outputFilePath), {
+                recursive: true,
+                force: true
+            });
+            else unlinkSync(outputFilePath);
+        }
+        if (hasDirectoryModeReport) mkdirSync(dirname(outputFilePath), {
+            recursive: true
+        });
+        logMsg(`Start merging ${this.reportInfos.length} reports...\nCreating template file...`);
+        try {
+            const htmlEndTag = '</html>';
+            const tpl = getReportTpl();
+            const htmlEndIdx = tpl.lastIndexOf(htmlEndTag);
+            const tplWithoutClose = -1 !== htmlEndIdx ? tpl.slice(0, htmlEndIdx) : tpl;
+            appendFileSync(outputFilePath, tplWithoutClose);
+            if (hasDirectoryModeReport) appendFileSync(outputFilePath, getBaseUrlFixScript());
+            for(let i = 0; i < this.reportInfos.length; i++){
+                const reportInfo = this.reportInfos[i];
+                logMsg(`Processing report ${i + 1}/${this.reportInfos.length}`);
+                const { reportAttributes } = reportInfo;
+                let dumpString = this.createEmptyDumpString(reportAttributes.testTitle, reportAttributes.testDescription);
+                let mergedGroupId = `merged-group-${i}`;
+                if (reportInfo.reportFilePath) {
+                    if (isDirectoryModeReport(reportInfo.reportFilePath)) {
+                        const reportDir = dirname(reportInfo.reportFilePath);
+                        const screenshotsDir = join(reportDir, 'screenshots');
+                        const mergedScreenshotsDir = join(dirname(outputFilePath), 'screenshots');
+                        mkdirSync(mergedScreenshotsDir, {
+                            recursive: true
+                        });
+                        for (const file of readdirSync(screenshotsDir)){
+                            const src = join(screenshotsDir, file);
+                            const dest = join(mergedScreenshotsDir, file);
+                            copyFileSync(src, dest);
+                        }
+                    } else streamImageScriptsToFile(reportInfo.reportFilePath, outputFilePath);
+                    const allDumps = extractAllDumpScriptsSync(reportInfo.reportFilePath).filter((d)=>d.openTag.includes('data-group-id'));
+                    const groupIdMatch = allDumps[0]?.openTag.match(/data-group-id="([^"]+)"/);
+                    if (groupIdMatch) mergedGroupId = decodeURIComponent(groupIdMatch[1]);
+                    const extractedDumpString = allDumps.length > 0 ? this.mergeDumpScripts(allDumps.map((d)=>d.content)) : extractLastDumpScriptSync(reportInfo.reportFilePath);
+                    if (extractedDumpString) dumpString = extractedDumpString;
+                }
+                const reportHtmlStr = `${reportHTMLContent({
+                    dumpString,
+                    attributes: {
+                        'data-group-id': mergedGroupId,
+                        playwright_test_duration: reportAttributes.testDuration,
+                        playwright_test_status: reportAttributes.testStatus,
+                        playwright_test_title: reportAttributes.testTitle,
+                        playwright_test_id: reportAttributes.testId,
+                        playwright_test_description: reportAttributes.testDescription,
+                        is_merged: true
+                    }
+                }, void 0, void 0, false)}\n`;
+                appendFileSync(outputFilePath, reportHtmlStr);
+            }
+            appendFileSync(outputFilePath, `${htmlEndTag}\n`);
+            logMsg(`Successfully merged new report: ${outputFilePath}`);
+            if (rmOriginalReports) {
+                for (const info of this.reportInfos)if (info.reportFilePath) try {
+                    if (isDirectoryModeReport(info.reportFilePath)) {
+                        const reportDir = dirname(info.reportFilePath);
+                        rmSync(reportDir, {
+                            recursive: true,
+                            force: true
+                        });
+                    } else unlinkSync(info.reportFilePath);
+                } catch (error) {
+                    logMsg(`Error deleting report ${info.reportFilePath}: ${error}`);
+                }
+                logMsg(`Removed ${this.reportInfos.length} original reports`);
+            }
+            return outputFilePath;
+        } catch (error) {
+            logMsg(`Error in mergeReports: ${error}`);
+            throw error;
+        }
+    }
+    constructor(){
+        _define_property(this, "reportInfos", []);
+    }
+}
+function collectDedupedExecutions(htmlPath) {
+    let baseDump = null;
+    let executionSerial = 0;
+    const latestSerialByExecutionId = new Map();
+    streamDumpScriptsSync(htmlPath, (dumpScript)=>{
+        if (!dumpScript.openTag.includes('data-group-id')) return false;
+        const groupedDump = ReportActionDump.fromSerializedString(antiEscapeScriptTag(dumpScript.content));
+        for (const execution of groupedDump.executions){
+            executionSerial += 1;
+            if (execution.id) latestSerialByExecutionId.set(execution.id, executionSerial);
+        }
+        return false;
+    });
+    const executions = [];
+    executionSerial = 0;
+    streamDumpScriptsSync(htmlPath, (dumpScript)=>{
+        if (!dumpScript.openTag.includes('data-group-id')) return false;
+        const groupedDump = ReportActionDump.fromSerializedString(antiEscapeScriptTag(dumpScript.content));
+        if (!baseDump) baseDump = groupedDump;
+        for (const execution of groupedDump.executions){
+            executionSerial += 1;
+            if (!execution.id || latestSerialByExecutionId.get(execution.id) === executionSerial) executions.push(execution);
+        }
+        return false;
+    });
+    if (!baseDump) throw new Error(`No report dump scripts found in ${htmlPath}`);
+    return {
+        baseDump,
+        executions
+    };
+}
+function extensionByMimeType(mimeType) {
+    if ('image/png' === mimeType) return 'png';
+    if ('image/jpeg' === mimeType) return 'jpeg';
+    throw new Error(`Unsupported screenshot mime type: ${mimeType}`);
+}
+function externalizeScreenshotsInExecution(execution, opts) {
+    const visit = (node)=>{
+        if (Array.isArray(node)) {
+            for (const item of node)visit(item);
+            return;
+        }
+        if ('object' != typeof node || null === node) return;
+        const ref = normalizeScreenshotRef(node);
+        if (ref) {
+            const ext = extensionByMimeType(ref.mimeType);
+            const fileName = `${ref.id}.${ext}`;
+            const relativePath = `./screenshots/${fileName}`;
+            const absolutePath = join(opts.screenshotsDir, fileName);
+            if (!opts.writtenFiles.has(fileName)) {
+                const resolved = resolveScreenshotSource(ref, {
+                    reportPath: opts.htmlPath
+                });
+                if ('data-uri' === resolved.type) {
+                    const rawBase64 = resolved.dataUri.replace(/^data:image\/[a-zA-Z+]+;base64,/, '');
+                    writeFileSync(absolutePath, Buffer.from(rawBase64, 'base64'));
+                } else copyFileSync(resolved.filePath, absolutePath);
+                opts.writtenFiles.add(fileName);
+            }
+            ref.storage = 'file';
+            ref.path = relativePath;
+            return;
+        }
+        for (const value of Object.values(node))visit(value);
+    };
+    visit(execution);
+}
+function splitReportHtmlByExecution(options) {
+    const { htmlPath, outputDir } = options;
+    const screenshotsDir = join(outputDir, 'screenshots');
+    mkdirSync(outputDir, {
+        recursive: true
+    });
+    mkdirSync(screenshotsDir, {
+        recursive: true
+    });
+    const executionJsonFiles = [];
+    const writtenScreenshotFiles = new Set();
+    const { baseDump, executions } = collectDedupedExecutions(htmlPath);
+    let fileIndex = 0;
+    for (const execution of executions){
+        fileIndex += 1;
+        externalizeScreenshotsInExecution(execution, {
+            htmlPath,
+            screenshotsDir,
+            writtenFiles: writtenScreenshotFiles
+        });
+        const singleExecutionDump = new ReportActionDump({
+            sdkVersion: baseDump.sdkVersion,
+            groupName: baseDump.groupName,
+            groupDescription: baseDump.groupDescription,
+            modelBriefs: baseDump.modelBriefs,
+            deviceType: baseDump.deviceType,
+            executions: [
+                execution
+            ]
+        });
+        const jsonFilePath = join(outputDir, `${fileIndex}.execution.json`);
+        writeFileSync(jsonFilePath, singleExecutionDump.serialize(2), 'utf-8');
+        executionJsonFiles.push(jsonFilePath);
+    }
+    return {
+        executionJsonFiles,
+        screenshotFiles: Array.from(writtenScreenshotFiles).sort().map((fileName)=>join(screenshotsDir, fileName))
+    };
+}
+export { ReportMergingTool, collectDedupedExecutions, dedupeExecutionsKeepLatest, isDirectoryModeReport, splitReportHtmlByExecution };

package/dist/es/screenshot-item.mjs

@@ -0,0 +1,120 @@
+import { readFileSync } from "node:fs";
+import { uuid } from "@godscene/shared/utils";
+import { extractImageByIdSync } from "./dump/html-utils.mjs";
+import { normalizeScreenshotRef } from "./dump/screenshot-store.mjs";
+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;
+}
+function detectFormat(base64) {
+    if (base64.startsWith('data:image/jpeg')) return 'jpeg';
+    if (base64.startsWith('data:image/jpg')) return 'jpeg';
+    return 'png';
+}
+class ScreenshotItem {
+    static create(base64, capturedAt) {
+        return new ScreenshotItem(uuid(), base64, capturedAt);
+    }
+    get id() {
+        return this._id;
+    }
+    get format() {
+        return this._format;
+    }
+    get extension() {
+        return 'jpeg' === this._format ? 'jpeg' : 'png';
+    }
+    get capturedAt() {
+        return this._capturedAt;
+    }
+    get base64() {
+        if (null !== this._base64) return this._base64;
+        const loadFromFile = ()=>{
+            if (null === this._persistedPath) throw new Error(`Screenshot ${this._id}: file recovery path missing`);
+            const buffer = readFileSync(this._persistedPath);
+            return `data:image/${this._format};base64,${buffer.toString('base64')}`;
+        };
+        const loadFromInline = ()=>{
+            if (null === this._persistedHtmlPath) throw new Error(`Screenshot ${this._id}: HTML recovery path missing`);
+            const data = extractImageByIdSync(this._persistedHtmlPath, this._id);
+            if (data) return data;
+            throw new Error(`Screenshot ${this._id}: cannot recover from HTML (id not found in ${this._persistedHtmlPath})`);
+        };
+        if (this._serializedRef?.storage === 'file') return loadFromFile();
+        if (this._serializedRef?.storage === 'inline') return loadFromInline();
+        if (null !== this._persistedPath) return loadFromFile();
+        if (null !== this._persistedHtmlPath) return loadFromInline();
+        throw new Error(`Screenshot ${this._id}: base64 data released without recovery path`);
+    }
+    hasBase64() {
+        return null !== this._base64;
+    }
+    markPersistedInline(htmlPath) {
+        const ref = this.createRef('inline');
+        this._serializedRef = ref;
+        this._persistedHtmlPath = htmlPath;
+        this._base64 = null;
+        return ref;
+    }
+    registerPersistedFileCopy(relativePath, absolutePath) {
+        const ref = this.createRef('file', relativePath);
+        this._persistedPath = absolutePath;
+        this._base64 = null;
+        return ref;
+    }
+    markPersistedToPath(relativePath, absolutePath) {
+        const ref = this.registerPersistedFileCopy(relativePath, absolutePath);
+        this._serializedRef = ref;
+        return ref;
+    }
+    toSerializable() {
+        return this._serializedRef ?? {
+            type: 'midscene_screenshot_ref',
+            id: this._id,
+            capturedAt: this._capturedAt,
+            mimeType: 'jpeg' === this._format ? 'image/jpeg' : 'image/png',
+            storage: 'inline'
+        };
+    }
+    static isSerialized(value) {
+        return null !== normalizeScreenshotRef(value);
+    }
+    createRef(storage, relativePath) {
+        const baseRef = {
+            type: 'midscene_screenshot_ref',
+            id: this._id,
+            capturedAt: this._capturedAt,
+            mimeType: 'jpeg' === this._format ? 'image/jpeg' : 'image/png',
+            storage
+        };
+        if ('file' === storage) return {
+            ...baseRef,
+            storage,
+            path: relativePath
+        };
+        return baseRef;
+    }
+    get rawBase64() {
+        return this.base64.replace(/^data:image\/(png|jpeg|jpg);base64,/, '');
+    }
+    constructor(id, base64, capturedAt){
+        _define_property(this, "_id", void 0);
+        _define_property(this, "_base64", void 0);
+        _define_property(this, "_format", void 0);
+        _define_property(this, "_capturedAt", void 0);
+        _define_property(this, "_serializedRef", null);
+        _define_property(this, "_persistedPath", null);
+        _define_property(this, "_persistedHtmlPath", null);
+        this._id = id;
+        this._base64 = base64;
+        this._format = detectFormat(base64);
+        this._capturedAt = capturedAt;
+    }
+}
+export { ScreenshotItem };