feat(core): integrate StorageProvider and directory-based reports

[quanru]

Summary

This PR implements a clean refactoring to integrate StorageProvider abstraction and directory-based report functionality. All changes follow an incremental approach, preserving backward compatibility.

Key Changes

1. StorageProvider Abstraction (Stage 1)

• Added StorageProvider interface for screenshot storage
• Implemented MemoryStorage (default, in-memory)
• Implemented FileStorage (file-based for Node.js)

2. Async ScreenshotItem (Stage 2)

BREAKING CHANGES:

• ScreenshotItem.create() is now async → Promise<ScreenshotItem>
• ScreenshotItem.getData() is now async → Promise<string>
• Serialization format changed: string → { $screenshot: "id" }

New methods:

• migrateTo(): Migrate between storage providers
• restore(): Deserialize from { $screenshot: id }
• isSerialized(): Check if value is serialized format

3. ExecutionDump Extension (Stage 3)

Incrementally extended with new methods while preserving all existing ones:

• collectScreenshots(): Collect all screenshot items
• toSerializableFormat(): Async conversion with new format

4. GroupedActionDump Extension (Stage 4)

Incrementally extended with new methods while preserving all existing ones:

• collectAllScreenshots(): Collect screenshots from all executions
• toHTML(): Generate HTML with serialized screenshots
• writeToDirectory(): Write report as directory with separate PNG files

Added ReportWriter utility class for flexible report generation.

5. Agent Integration (Stage 5)

• Added AgentOpt.useDirectoryReport option (default: false)
• Added AgentOpt.storageProvider option
• Updated writeOutActionDumps() to support both report modes
• Used fire-and-forget pattern for async operations

6. Async Call Fixes (Stage 6)

Fixed all ScreenshotItem.create() and getData() calls across:

• 8 source files in @midscene/core
• 6 test files (including complete rewrite of screenshot-item.test.ts)

7. Integration Package Fixes (Stage 7)

Fixed async API compatibility issues in downstream packages:

@midscene/web-integration:

• Modified WebUIContext type to make screenshot optional
• Added lazy loading support for ScreenshotItem in StaticPage
• Added screenshotBase64 field for synchronous initialization
• Fixed async getData() calls with await

@midscene/visualizer:

• Made generateAnimationScripts() and allScriptsFromDump() async
• Added await to all getData() calls (7 locations in replay-scripts.ts)
• Converted forEach loops to for...of loops to support await
• Used React hooks (useState + useEffect) for async data loading in components
• Fixed async calls in usePlaygroundExecution hook

Test fixes:

• Added await to fakeService() call in task-runner tests
• Made test beforeEach async where needed
• Added await to all ScreenshotItem.create() and getData() calls in tests

Architecture Decisions

1. Incremental Extension: Extended existing classes instead of replacing them
2. Backward Compatibility: All original methods preserved
3. Avoided Unnecessary Changes: No import style modifications or refactoring
4. Dynamic Imports: Used await import() to avoid bundling Node modules
5. Fire-and-Forget Pattern: Used void promise.catch() for non-blocking async
6. Optional Screenshot Field: Made screenshot optional in WebUIContext to support both formats
7. React Hooks for Async: Used useState + useEffect pattern for async data in React components

Test Results

✅ All builds passing
✅ @midscene/core: All tests passing
✅ @midscene/web: All tests passing
✅ @midscene/visualizer: Build successful

Breaking Changes

• ScreenshotItem.create() requires await
• ScreenshotItem.getData() requires await
• Serialization format changed (handled by new deserializer)

Migration Guide

For existing code using ScreenshotItem:

// Before
const item = ScreenshotItem.create(base64);
const data = item.getData();

// After
const item = await ScreenshotItem.create(base64);
const data = await item.getData();

For React components using screenshot data:

// Before
const screenshotBase64 = screenshot.getData();

// After - use React hooks
const [screenshotBase64, setScreenshotBase64] = useState<string>('');
useEffect(() => {
  screenshot.getData().then(setScreenshotBase64);
}, [screenshot]);

Commits Summary

Core implementation (9 commits):

1. Add StorageProvider abstraction
2. Make ScreenshotItem async with provider support
3. Extend ExecutionDump with serialization methods
4. Extend GroupedActionDump with directory report support
5. Integrate directory reports into Agent
6. Fix async calls in @midscene/core source files
7. Fix async calls in @midscene/core tests
8. Commit message translation to English
9. Linter fixes

Integration fixes (4 commits):

1. Fix @midscene/web-integration async API compatibility
2. Fix @midscene/visualizer async getData() calls
3. Fix visualizer for loop syntax
4. Fix test async calls

Total: 13 commits, 27 files changed, 840 additions, 183 deletions

Related Issues

This PR continues the work from feat/local-imgs branch with a clean, incremental approach based on the main branch.

[netlify]

❌ Deploy Preview for midscene failed. Why did it fail? →

Name	Link
🔨 Latest commit	726b3d6
🔍 Latest deploy log	https://app.netlify.com/projects/midscene/deploys/6969f675ae8462000848fdbb