Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(playable): verify scenarios in headless Chromium

yhh3a6fbb17862c
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index ab7e3c529..c1595bad6 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -37,6 +37,40 @@ env:
test_frame_lifecycle
jobs:
+ playable-runtime:
+ name: Playable headless checks
+ runs-on: ubuntu-latest
+ needs: build-emscripten
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ - uses: ./.github/actions/setup
+ - name: Download this commit's Web runtime
+ uses: actions/download-artifact@v8
+ with:
+ name: wasm-web
+ path: build/wasm/web/
+ - name: Build the shipping SDK
+ run: pnpm --filter ./sdk build
+ - name: Install headless Chromium
+ run: pnpm exec playwright install --with-deps chromium
+ - name: Check the verifier's failure paths
+ run: node --test tools/tests/verify-playable.e2e.mjs
+ - name: Export and check the real playable in eight local network mocks
+ shell: bash
+ run: |
+ for playable_network in mintegral unity applovin mraid tiktok pangle google meta; do
+ node pipeline/bin/estella.mjs export examples/playable-ad --profile "$playable_network" --wasm build/wasm/web --out "output/playable-ci-export-$playable_network" --json "output/playable-ci-export-$playable_network.json" || exit 1
+ node tools/verify-playable.mjs "output/playable-ci-export-$playable_network/index.html" --report "output/playable-ci-export-$playable_network.json" --scenario examples/playable-ad/playable-check.json --out "output/playable-ci-check-$playable_network" --store-url https://example.com/store || exit 1
+ done
+ - name: Upload hash-bound local observations and screenshots
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: playable-local-mock-checks
+ path: output/playable-ci-*
+ retention-days: 3
+
# The engine binaries, and nothing else: every gate below waits on this job, so
# a step here that no downstream job reads is a delay on all of them.
build-emscripten:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1eeb68d55..155cd7000 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,10 @@ published separately; it ships inside the editor.
- **Sprites retain parent-induced shear in every draw mode.** Ordinary, nine-slice and tiled geometry follows the complete parent transform, and camera bounds use the same basis. Mirrored tiled grids retain positive tile steps before applying signed axes, including the capped fallback. Zero-area sprites skip geometry; existing material, UV and batch state is preserved.
+### Added
+
+- **Playable scenarios run in headless Chromium and save bound evidence.** A CLI replays declared canvas clicks and host callbacks, records trusted pointers and user activation, checks hidden input and animation, and fails on unexpected requests, page errors, event mismatches, lost history or changed inputs. Reports and screenshots retain delivery/scenario/tool hashes and pending acceptance; eight network mocks run on the example in CI using that commit's Web runtime. No local editor or browser window is opened.
+
## [0.82.0] - 2026-10-14
### Added
diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
index 90cc36521..d0c3fd79b 100644
--- a/docs/astro/src/content/docs/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/publishing/overview.mdx
@@ -132,6 +132,16 @@ Playable exports include `playableCheck` in their result; the package dialog dis
Use `pnpm preview:playable path/to/index.html --report export-result.json` from the engine repository for a local container mock. It prints a loopback URL and does not open a browser. Ready, Show and Hide simulate host callbacks; the viewport selector changes aspect ratio, and Save Log records store calls with the original HTML hash. MRAID can use `--store-url` for your destination. The served copy substitutes mandatory SDK scripts and blocks external requests; the delivered HTML stays unchanged. These mock records do not replace official SDK or device acceptance.
+For repeatable **headless local observations**, use Node 20+ and install Chromium with `pnpm exec playwright install chromium`, then run:
+
+```bash
+pnpm verify:playable output/playable/index.html --report output/playable.json --scenario examples/playable-ad/playable-check.json --out output/playable-observations --store-url https://example.com/store
+```
+
+Adapt the scenario to your scene. Version 1 declares `viewports` and `steps`: `click` uses normalized canvas `x`/`y`; `expect` names `store-click`, `game-end` or `game-retry` with an exact `count` and optional `userActivation`. `host` sends `ready`, `show` or `hide`; `frozen` compares canvas screenshots over `ms`; `wait` and `snapshot` record timing/images. Optional `networks` limits a step or expectation explicitly. Each viewport starts fresh. The shipping example checks portrait/landscape, CTA, completion/retry and supported hidden lifecycle; Google/Meta lifecycle remains pending.
+
+The command always uses headless Chromium with muted audio, without the editor. `runtime-check.json` saves original HTML/delivery, export-report, scenario, verifier and mock hashes, browser version, events and screenshot hashes. Unexpected requests—including CSP-blocked attempts—page errors, event-count/activation mismatches, hidden animation/input, truncation, failed static/export results and changed inputs fail verification. Windows/POSIX archive paths both resolve by the adjacent ZIP filename. The verdict is **local-mock**, covering the requested observations only; it substitutes host SDK scripts and observes active browser activation rather than proving an SDK's synchronous gesture rule. Original SDK behavior, audio lifecycle, quality review, official tools and device acceptance remain pending.
+
The required host SDK check verifies literal script tags and their placement. Google Exit API belongs in head; TikTok/Pangle must load before game scripts in body. Missing scripts, incorrect positions and delayed TikTok/Pangle SDK loading fail this static check. Actual SDK availability and CTA behavior remain runtime checks.
With a full export result, preview also checks the adjacent ZIP’s delivery hash; changing config while keeping identical HTML still invalidates the old report. Saved logs carry both hashes and the archive filename. Without delivery evidence they identify HTML only. A visible notice and log field disclose when older events were omitted from the 1,000-entry history.
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
index 1cfe57989..22545e516 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
@@ -116,6 +116,16 @@ MRAID 安装按钮须通过 `playableCta(storeUrl)` 传入目标地址,或由
在引擎仓库执行 `pnpm preview:playable path/to/index.html --report export-result.json` 可启动本地容器模拟,只打印回环地址,不自动打开浏览器。Ready、Show、Hide 模拟宿主回调,可切换横竖屏;Save Log 保存商店调用及原 HTML 哈希。MRAID 可通过 `--store-url` 配置商店地址。预览副本替换必需 SDK 并阻止外部请求,原导出 HTML 不变;模拟记录不代替官方 SDK 或真机验收。
+要重复执行**无头本地观察**,使用 Node 20+,先执行 `pnpm exec playwright install chromium`,再运行:
+
+```bash
+pnpm verify:playable output/playable/index.html --report output/playable.json --scenario examples/playable-ad/playable-check.json --out output/playable-observations --store-url https://example.com/store
+```
+
+请按自己的场景调整点击计划。版本 1 声明 `viewports` 和 `steps`:`click` 的 `x`/`y` 是相对 canvas 的归一化坐标;`expect` 指定 `store-click`、`game-end` 或 `game-retry` 的准确 `count`,以及可选 `userActivation`。`host` 发送 `ready`、`show`、`hide`;`frozen` 在 `ms` 间隔比较画面;`wait`、`snapshot` 记录等待及截图。步骤或期望可用 `networks` 明确限定,每个视口独立启动。示例覆盖横竖屏、CTA、完成/重玩及支持的隐藏生命周期;Google/Meta 生命周期保持待验证。
+
+命令仅使用无头 Chromium,静音且不启动编辑器。`runtime-check.json` 记录原 HTML/交付文件、导出报告、场景计划、检查器和 mock 哈希,浏览器版本、事件及截图哈希。非预期请求(含 CSP 阻止的尝试)、页面错误、事件数量/激活状态不符、隐藏动画或输入、日志丢失、静态/导出失败及输入变更都使检查失败。Windows/POSIX 旧归档路径均按相邻 ZIP 文件名定位。结论仅为 **local-mock**,覆盖明确请求的观察;宿主 SDK 被替换,浏览器激活状态观察不能证明原 SDK 的同步调用规则。原 SDK 行为、音频生命周期、质量复核、官方工具和真机验收仍待完成。
+
必需宿主 SDK 检查会核对真实的 script 标签及其位置:Google Exit API 位于 head,TikTok/Pangle 位于 body 且在游戏脚本之前。缺少脚本、位置错误或 TikTok/Pangle SDK 延迟加载都会使静态检查失败。真实 SDK 是否可用及 CTA 行为仍需运行验证。
提供完整导出结果时,预览还会核对同目录 ZIP 的交付哈希;只改配置而 HTML 不变,也会使旧报告失效。保存的日志记录两种哈希和文件名;缺少交付证据时明确标为仅关联 HTML。事件历史最多保留 1,000 条,界面和日志会说明省略了多少早期记录。
diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.md
index 18c329323..d1e25816e 100644
--- a/examples/playable-ad/README.md
+++ b/examples/playable-ad/README.md
@@ -88,3 +88,27 @@ filename, not the old absolute output path. A changed archive is rejected even
when index.html stayed identical. Saved logs include both hashes and the delivery
filename; HTML-only previews are labeled as such. Event history retains the last
1,000 entries and displays/saves the count of omitted earlier events.
+
+Run the same scene without a browser window using its declarative click scenario
+(Node 20+ and Playwright Chromium):
+
+```bash
+pnpm exec playwright install chromium
+pnpm verify:playable output/playable-ad/index.html --report output/playable-ad.json --scenario examples/playable-ad/playable-check.json --out output/playable-check --store-url https://example.com/store
+```
+
+Use your actual export paths. The store URL here is a test destination; the mock
+records it without opening it. `runtime-check.json` and canvas screenshots bind
+the original HTML, actual delivery, export report, scenario, verifier and mock
+hashes. The command always launches headless Chromium and mutes audio; it does not
+launch the editor. A failed export/static check, unexpected request (including a
+blocked attempt), page error, wrong event count, hidden input/animation, truncated
+history or input changes makes verification fail.
+
+`playable-check.json` declares canvas-relative coordinates, observed intervals
+and per-network expectations. Each viewport starts fresh. Store checks observe
+trusted pointer releases and active browser user activation; they do not prove
+the original SDK's synchronous gesture requirements. Google/Meta lifecycle steps
+are explicitly not applicable, with missing coverage retained as pending. All
+records remain `local-mock`: original host SDK behavior, visual/audio quality,
+audio lifecycle, official tools and physical devices still need separate review.
diff --git a/examples/playable-ad/playable-check.json b/examples/playable-ad/playable-check.json
new file mode 100644
index 000000000..e5ab53ee8
--- /dev/null
+++ b/examples/playable-ad/playable-check.json
@@ -0,0 +1,18 @@
+{
+ "version": 1,
+ "description": "Local host observations only. Store hooks are mocked; this is not network/device acceptance.",
+ "viewports": [{ "width": 360, "height": 640 }, { "width": 800, "height": 400 }],
+ "steps": [
+ { "type": "click", "name": "Install from a trusted click", "x": 0.5, "y": 0.82, "expect": { "event": "store-click", "count": 1, "userActivation": true } },
+ { "type": "click", "name": "Select left ship", "x": 0.2, "y": 0.45 },
+ { "type": "click", "name": "Select middle ship", "x": 0.5, "y": 0.45 },
+ { "type": "click", "name": "Complete the fleet", "x": 0.8, "y": 0.45, "expect": { "event": "game-end", "count": 1, "networks": ["mintegral"] } },
+ { "type": "host", "name": "Hide the creative", "command": "hide", "networks": ["mraid", "unity", "applovin", "mintegral", "tiktok", "pangle"] },
+ { "type": "frozen", "name": "Hidden animation stays frozen", "ms": 250, "networks": ["mraid", "unity", "applovin", "mintegral", "tiktok", "pangle"] },
+ { "type": "click", "name": "Hidden CTA accepts no input", "x": 0.5, "y": 0.82, "expect": { "event": "store-click", "count": 0 }, "observeMs": 300, "networks": ["mraid", "unity", "applovin", "mintegral", "tiktok", "pangle"] },
+ { "type": "host", "name": "Resume the creative", "command": "show", "networks": ["mraid", "unity", "applovin", "mintegral", "tiktok", "pangle"] },
+ { "type": "click", "name": "Resumed CTA accepts a trusted click", "x": 0.5, "y": 0.82, "expect": { "event": "store-click", "count": 1, "userActivation": true }, "networks": ["mraid", "unity", "applovin", "mintegral", "tiktok", "pangle"] },
+ { "type": "click", "name": "Retry the completed game", "x": 0.5, "y": 0.96, "expect": { "event": "game-retry", "count": 1, "userActivation": true }, "networks": ["mintegral"] },
+ { "type": "snapshot", "name": "Final canvas" }
+ ]
+}
diff --git a/package.json b/package.json
index 15dbe3131..186f25ebb 100644
--- a/package.json
+++ b/package.json
@@ -42,7 +42,8 @@
"verify:remote-capture": "node tools/verify-remote-capture.mjs --platform web && node tools/verify-remote-capture.mjs --platform wechat",
"verify:hotupdate": "node tools/with-env.mjs ESTELLA_HOTUPDATE_FIXTURE=1 -- pnpm --filter @estella/pipeline exec vitest run tests/hotupdate-verify-fixture.test.ts && node tools/run-electron.mjs tools/launchers/headless-hotupdate-verify.mjs",
"verify:cache-budget": "node tools/run-electron.mjs tools/launchers/cache-budget-render-verify.mjs",
- "preview:playable": "node tools/playable-preview.mjs"
+ "preview:playable": "node tools/playable-preview.mjs",
+ "verify:playable": "node tools/verify-playable.mjs"
},
"dependencies": {
"chalk": "^5.3.0",
@@ -63,6 +64,7 @@
"electron": "^42.4.1",
"esbuild": "^0.27.0",
"madge": "^8.0.0",
+ "playwright": "1.62.1",
"vitest": "^2.1.9"
}
}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 662608150..6832cb505 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -30,6 +30,9 @@ importers:
madge:
specifier: ^8.0.0
version: 8.0.0([email protected])
+ playwright:
+ specifier: 1.62.1
+ version: 1.62.1
vitest:
specifier: ^2.1.9
@@ -2228,6 +2231,11 @@ packages:
resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==}
+ resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+ engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+ os: [darwin]
+
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -3008,6 +3016,16 @@ packages:
resolution: {integrity: sha512-emEcLuomt2j03vxD54giVB4SxTjnsqkU692xZOZXHDVoYyypEm+b3jpiTcc+Cf+myooc+/Ly0z01jqeNHVgJGw==}
engines: {node: '>=16.0.0'}
+ resolution: {integrity: sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==}
+ engines: {node: '>=20'}
+ hasBin: true
+
+ resolution: {integrity: sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==}
+ engines: {node: '>=20'}
+ hasBin: true
+
resolution: {integrity: sha512-uysumyrvkUX0rX/dEVqt8gC3sTBzd4zoWfLeS29nb53imdaXVvLINYXTI2GNqzaMuvacNx4uJQ8+b3zXR0pkgQ==}
engines: {node: '>=10.4.0'}
@@ -5792,6 +5810,9 @@ snapshots:
+ optional: true
+
optional: true
@@ -6519,6 +6540,14 @@ snapshots:
pvutils: 1.1.5
tslib: 2.8.1
+
+ dependencies:
+ playwright-core: 1.62.1
+ optionalDependencies:
+ fsevents: 2.3.2
+
dependencies:
'@xmldom/xmldom': 0.8.13
diff --git a/tools/playable-preview.mjs b/tools/playable-preview.mjs
index b3b6b6102..992f7e62c 100644
--- a/tools/playable-preview.mjs
+++ b/tools/playable-preview.mjs
@@ -113,7 +113,7 @@ export async function createPlayablePreview({ htmlFile, network, storeUrl = '',
deliveryFile = path.basename(htmlFile);
if (result.zipFile) {
if (typeof result.zipFile !== 'string') throw new Error('The export result ZIP filename must be a string.');
- deliveryFile = path.basename(result.zipFile);
+ deliveryFile = path.win32.basename(path.posix.basename(result.zipFile));
if (!/^[A-Za-z0-9_]+\.zip$/.test(deliveryFile) || /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])\.zip$/i.test(deliveryFile)) throw new Error('The report needs a portable ZIP filename.');
delivery = await readFile(path.join(path.dirname(path.resolve(htmlFile)), deliveryFile));
} else if (report.deliverySha256 !== htmlSha256) throw new Error('ZIP identity needs the full export result with zipFile, beside its HTML.');
@@ -144,7 +144,7 @@ export async function createPlayablePreview({ htmlFile, network, storeUrl = '',
else { response.writeHead(404); response.end('Not found'); }
});
await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
- return { server, url: `http://127.0.0.1:${server.address().port}/`, htmlSha256, deliverySha256,
+ return { server, url: `http://127.0.0.1:${server.address().port}/`, network, htmlSha256, deliverySha256, deliveryFile,
close: () => new Promise(resolve => { server.close(resolve); server.closeAllConnections?.(); }) };
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 6f1cbc69a..e922dd002 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -34,6 +34,9 @@ export const NOTED = {
{ note: 'Sprites retain parent-induced shear in every draw mode.' },
'fix(text): preserve long bitmap strings and cull hidden glyphs':
{ note: 'Long native bitmap text preserves UTF-8 content without uploading hidden glyphs.' },
+ 'feat(playable): verify scenarios in headless Chromium':
+ { note: 'Playable scenarios run in headless Chromium and save bound evidence.' },
+
'feat(playable): adapt asset quality to measured delivery budgets':
{ note: 'Playable asset quality adapts to the measured delivery budget.' },
'feat(editor): show playable asset optimization decisions':
diff --git a/tools/tests/playable-preview.test.ts b/tools/tests/playable-preview.test.ts
index 140453847..beece43cd 100644
--- a/tools/tests/playable-preview.test.ts
+++ b/tools/tests/playable-preview.test.ts
@@ -72,14 +72,17 @@ describe('local playable mock', () => {
const original = zip(0), deliverySha256 = createHash('sha256').update(original).digest('hex');
await writeFile(zipFile, original);
const reportFile = path.join(root, 'report.json');
- await writeFile(reportFile, JSON.stringify({ zipFile: '/previous/export/playable.zip',
- playableCheck: { network: 'pangle', htmlSha256: initial.htmlSha256, deliverySha256 } }));
- const preview = await createPlayablePreview({ htmlFile: file, reportFile });
- try {
- expect(preview.deliverySha256).toBe(deliverySha256);
- expect(await (await fetch(preview.url)).text()).toContain(deliverySha256);
- expect(await readFile(zipFile)).toEqual(original);
- } finally { await preview.close(); }
+ for (const previousPath of ['/previous/export/playable.zip', 'C:\\previous\\export\\playable.zip']) {
+ await writeFile(reportFile, JSON.stringify({ zipFile: previousPath,
+ playableCheck: { network: 'pangle', htmlSha256: initial.htmlSha256, deliverySha256 } }));
+ const preview = await createPlayablePreview({ htmlFile: file, reportFile });
+ try {
+ expect(preview.deliveryFile).toBe('playable.zip');
+ expect(preview.deliverySha256).toBe(deliverySha256);
+ expect(await (await fetch(preview.url)).text()).toContain(deliverySha256);
+ expect(await readFile(zipFile)).toEqual(original);
+ } finally { await preview.close(); }
+ }
await writeFile(zipFile, zip(1));
expect(createHash('sha256').update(await readFile(file)).digest('hex')).toBe(initial.htmlSha256);
await expect(createPlayablePreview({ htmlFile: file, reportFile })).rejects.toThrow(/delivered file differs/);
diff --git a/tools/tests/verify-playable.e2e.mjs b/tools/tests/verify-playable.e2e.mjs
new file mode 100644
index 000000000..4391e2209
--- /dev/null
+++ b/tools/tests/verify-playable.e2e.mjs
@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { verifyPlayable } from '../verify-playable.mjs';
+
+const active = { type: 'click', x: 0.5, y: 0.5, expect: { event: 'store-click', count: 1, userActivation: true }, observeMs: 100 };
+const scenario = { version: 1, viewports: [{ width: 200, height: 200 }], steps: [active,
+ { type: 'host', command: 'hide' }, { type: 'frozen', ms: 200 },
+ { type: 'click', x: 0.5, y: 0.5, expect: { event: 'store-click', count: 0 }, observeMs: 100 },
+ { type: 'host', command: 'show' }, active] };
+
+/** A real WebGL page for the verifier, not an engine/render acceptance fixture. */
+function creative({ fetchExternal = false, fetchLocalSdk = false, hiddenClick = false, hiddenAnimation = false, overflow = false } = {}) {
+ return `<!doctype html><html><head><style>body{margin:0}canvas{width:100vw;height:100vh;display:block}</style></head><body><canvas width="200" height="200"></canvas><script>
+ mraid.addEventListener('ready',()=>{});
+ const canvas=document.querySelector('canvas'),gl=canvas.getContext('webgl');
+ const shader=(type,code)=>{const s=gl.createShader(type);gl.shaderSource(s,code);gl.compileShader(s);return s};
+ const program=gl.createProgram();gl.attachShader(program,shader(gl.VERTEX_SHADER,'attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}'));
+ gl.attachShader(program,shader(gl.FRAGMENT_SHADER,'precision mediump float;uniform float phase;void main(){gl_FragColor=vec4(phase,.4,.8,1.);}'));gl.linkProgram(program);gl.useProgram(program);
+ const buffer=gl.createBuffer();gl.bindBuffer(gl.ARRAY_BUFFER,buffer);gl.bufferData(gl.ARRAY_BUFFER,new Float32Array([-1,-1,3,-1,-1,3]),gl.STATIC_DRAW);
+ const p=gl.getAttribLocation(program,'p');gl.enableVertexAttribArray(p);gl.vertexAttribPointer(p,2,gl.FLOAT,false,0,0);let phase=0;
+ function draw(){if(mraid.isViewable()||${hiddenAnimation}){phase=(phase+.07)%1;gl.uniform1f(gl.getUniformLocation(program,'phase'),phase);gl.drawArrays(gl.TRIANGLES,0,3)}requestAnimationFrame(draw)}draw();
+ canvas.addEventListener('pointerup',()=>{if(mraid.isViewable()||${hiddenClick})mraid.open('https://example.com/store')});
+ ${fetchExternal ? "fetch('https://example.invalid/forbidden').catch(()=>{})" : ''}
+ ${fetchLocalSdk ? "fetch('/host-sdk.js',{method:'POST'}).catch(()=>{})" : ''}
+ ${overflow ? "for(let i=0;i<4100;i++)window.postMessage({source:'estella-playable-preview',type:'event',name:'noise',data:{}},location.origin)" : ''}
+ </script></body></html>`;
+}
+
+async function fixture(options, run, plan = scenario, staticFailure = false) {
+ const root = await mkdtemp(path.join(tmpdir(), 'estella-playable-runner-'));
+ const htmlFile = path.join(root, 'index.html'), scenarioFile = path.join(root, 'scenario.json'), reportFile = path.join(root, 'export.json'), outDir = path.join(root, 'results');
+ const html = creative(options), hash = createHash('sha256').update(html).digest('hex');
+ await writeFile(htmlFile, html); await writeFile(scenarioFile, JSON.stringify(plan));
+ await writeFile(reportFile, JSON.stringify({ ok: !options?.exportFailure, errors: options?.exportFailure ? ['Synthetic failed asset cook'] : [], playableCheck: { network: 'mraid', htmlSha256: hash, deliverySha256: hash,
+ checks: staticFailure ? [{ id: 'delivery-size', status: 'fail', detail: 'Synthetic failed static check' }] : [] } }));
+ try {
+ const result = await verifyPlayable({ htmlFile, scenarioFile, reportFile, outDir, timeoutMs: 1000,
+ onProgress: options?.tamper ? () => { writeFileSync(htmlFile, html + '\n<!-- changed -->'); } : undefined });
+ await run(result, JSON.parse(await readFile(path.join(outDir, 'runtime-check.json'), 'utf8')));
+ } finally {
+ const target = path.resolve(root), temp = path.resolve(tmpdir());
+ if (!target.startsWith(temp + path.sep) || !path.basename(target).startsWith('estella-playable-runner-')) throw new Error('Unexpected runner fixture cleanup');
+ await rm(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+}
+
+test('headless runner records trusted clicks, hidden freeze/input, hashes and pending acceptance', async () => {
+ await fixture({}, async (result, saved) => {
+ assert.equal(result.status, 'checks-passed'); assert.equal(saved.mode, 'local-mock'); assert.equal(saved.headless, true);
+ assert.equal(saved.identityScope, 'delivery'); assert.match(saved.verifierSha256, /^[a-f0-9]{64}$/); assert.match(saved.scenarioSha256, /^[a-f0-9]{64}$/);
+ assert.ok(saved.pending.some(note => note.includes('Original host SDK')));
+ assert.ok(saved.cases[0].steps.filter(step => step.type === 'click').every(step => step.trustedPointer));
+ assert.ok(saved.cases[0].drawCalls > 0); assert.equal(saved.cases[0].truncatedEvents, 0);
+ assert.ok(saved.cases[0].requests.every(request => request.expected));
+ assert.equal(saved.cases[0].steps.find(step => step.type === 'frozen').beforeSha256, saved.cases[0].steps.find(step => step.type === 'frozen').afterSha256);
+ });
+});
+test('blocked external fetch is a failure even when the game handles the rejection', async () => {
+ await fixture({ fetchExternal: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.ok(result.cases[0].events.some(event => event.name === 'blocked-request'));
+ });
+});
+test('fetching an allowed SDK path as a POST is still an unexpected request', async () => {
+ await fixture({ fetchLocalSdk: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.ok(result.cases[0].requests.some(request => request.method === 'POST' && !request.expected));
+ });
+});
+test('missing CTA calls fail the actual step and retain the observed count', async () => {
+ await fixture({}, async result => {
+ assert.equal(result.status, 'failed'); assert.equal(result.cases[0].steps[0].status, 'failed');
+ assert.equal(result.cases[0].steps[0].observedCount, 1);
+ }, { ...scenario, steps: [{ ...active, expect: { event: 'store-click', count: 2 } }] });
+});
+test('hidden CTA accepting input fails', async () => {
+ await fixture({ hiddenClick: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.equal(result.cases[0].steps[3].status, 'failed');
+ assert.equal(result.cases[0].steps[3].observedCount, 1);
+ });
+});
+test('hidden animation continuing fails the screenshot comparison', async () => {
+ await fixture({ hiddenAnimation: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.equal(result.cases[0].steps[2].status, 'failed');
+ });
+});
+test('event truncation cannot be reported as complete evidence', async () => {
+ await fixture({ overflow: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.ok(result.cases[0].truncatedEvents > 0);
+ });
+});
+test('input file mutation during verification invalidates the result', async () => {
+ await fixture({ tamper: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.ok(result.errors.some(error => error.includes('changed during verification')));
+ });
+});
+test('passing runtime observations cannot mask a failed static check', async () => {
+ await fixture({}, async result => {
+ assert.equal(result.status, 'failed'); assert.equal(result.staticFailures.length, 1);
+ assert.ok(result.cases[0].steps.every(step => step.status === 'passed'));
+ }, scenario, true);
+});
+test('a failed asset export stays failed even when the remaining UI works', async () => {
+ await fixture({ exportFailure: true }, async result => {
+ assert.equal(result.status, 'failed'); assert.deepEqual(result.exportErrors, ['Synthetic failed asset cook']);
+ assert.ok(result.cases[0].steps.every(step => step.status === 'passed'));
+ });
+});
diff --git a/tools/tests/verify-playable.test.ts b/tools/tests/verify-playable.test.ts
new file mode 100644
index 000000000..218eebd6a
--- /dev/null
+++ b/tools/tests/verify-playable.test.ts
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { validatePlayableScenario } from '../verify-playable.mjs';
+
+const valid = { version: 1, viewports: [{ width: 360, height: 640 }], steps: [{ type: 'click', x: 0.5, y: 0.82, expect: { event: 'store-click', count: 1, userActivation: true } }] };
+describe('playable scenario input', () => {
+ it('accepts the shipping example and declares which networks support lifecycle checks', () => {
+ const scenario = validatePlayableScenario(JSON.parse(readFileSync(new URL('../../examples/playable-ad/playable-check.json', import.meta.url), 'utf8')));
+ expect(scenario.viewports).toHaveLength(2);
+ expect(scenario.steps.find((step: any) => step.type === 'host' && step.command === 'hide').networks).not.toContain('google');
+ });
+ it.each([
+ { ...valid, headless: false }, { ...valid, version: 2 }, { ...valid, viewports: [] },
+ { ...valid, viewports: [{ width: 0, height: 640 }] }, { ...valid, steps: [] },
+ { ...valid, steps: [{ type: 'eval', code: 'gameReady()' }] },
+ { ...valid, steps: [{ type: 'click', x: 1.5, y: 0.5 }] },
+ { ...valid, steps: [{ type: 'click', x: 0.5, y: 0.5, expect: null }] },
+ { ...valid, steps: [{ type: 'click', x: 0.5, y: 0.5, expect: { event: 'store-click', count: -1 } }] },
+ { ...valid, steps: [{ type: 'click', x: 0.5, y: 0.5, networks: ['unimplemented-network'] }] },
+ { ...valid, steps: [{ type: 'host', command: 'show', expect: { event: 'store-click', count: 1 } }] },
+ { ...valid, steps: [{ type: 'frozen', ms: 100000 }] },
+ ])('rejects ambiguous/unsupported scenario instructions', scenario => {
+ expect(() => validatePlayableScenario(scenario)).toThrow();
+ });
+});
diff --git a/tools/verify-playable.mjs b/tools/verify-playable.mjs
new file mode 100644
index 000000000..9d871799a
--- /dev/null
+++ b/tools/verify-playable.mjs
@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPlayablePreview } from './playable-preview.mjs';
+
+const NETWORKS = ['generic', 'mraid', 'unity', 'applovin', 'mintegral', 'tiktok', 'pangle', 'google', 'meta'];
+const LIFECYCLE = ['mraid', 'unity', 'applovin', 'mintegral', 'tiktok', 'pangle'];
+const sha = value => createHash('sha256').update(value).digest('hex');
+const integer = (value, min, max) => Number.isInteger(value) && value >= min && value <= max;
+
+/** Declarative input only: scenarios cannot inject code or choose a headed browser. */
+export function validatePlayableScenario(scenario) {
+ const object = (value, allowed) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => allowed.includes(key));
+ const networks = value => value === undefined || (Array.isArray(value) && value.length > 0 && value.every(id => NETWORKS.includes(id)));
+ if (!object(scenario, ['version', 'description', 'viewports', 'steps']) || scenario.version !== 1
+ || !Array.isArray(scenario.viewports) || !integer(scenario.viewports.length, 1, 4)
+ || !scenario.viewports.every(v => object(v, ['width', 'height']) && integer(v.width, 1, 4096) && integer(v.height, 1, 4096))
+ || !Array.isArray(scenario.steps) || !integer(scenario.steps.length, 1, 200)) throw new Error('Scenario needs version 1, 1–4 viewports and 1–200 steps.');
+ for (const [index, step] of scenario.steps.entries()) {
+ const fields = { click: ['x', 'y', 'expect', 'observeMs'], host: ['command'], wait: ['ms'], frozen: ['ms'], snapshot: [] };
+ if (!object(step, ['type', 'name', 'networks', ...(fields[step?.type] ?? [])]) || !networks(step.networks)
+ || (step.name !== undefined && typeof step.name !== 'string')) throw new Error(`Invalid scenario step ${index + 1}.`);
+ if (step.type === 'click') {
+ if (![step.x, step.y].every(v => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1)
+ || (step.observeMs !== undefined && !integer(step.observeMs, 100, 2000))) throw new Error(`Click ${index + 1} needs normalized canvas coordinates and a bounded observation interval.`);
+ if (step.expect !== undefined && (!object(step.expect, ['event', 'count', 'userActivation', 'networks'])
+ || !['store-click', 'game-end', 'game-retry'].includes(step.expect.event) || !integer(step.expect.count, 0, 20)
+ || !networks(step.expect.networks) || (step.expect.userActivation !== undefined && typeof step.expect.userActivation !== 'boolean'))) throw new Error(`Invalid event expectation at step ${index + 1}.`);
+ } else if (step.type === 'host') {
+ if (!['ready', 'show', 'hide'].includes(step.command)) throw new Error(`Invalid host command at step ${index + 1}.`);
+ } else if (step.type === 'wait' || step.type === 'frozen') {
+ if (!integer(step.ms, 100, step.type === 'frozen' ? 2000 : 10000)) throw new Error(`Invalid wait interval at step ${index + 1}.`);
+ } else if (step.type !== 'snapshot') throw new Error(`Unknown scenario action ${step.type}.`);
+ }
+ return scenario;
+}
+
+/** Runs in the creative before its scripts; observation does not call game handlers. */
+function installProbe() {
+ const probe = { events: [], dropped: 0, drawCalls: 0, pointerUps: 0, lastPointerTrusted: false };
+ window.__ESTELLA_PLAYABLE_CHECK__ = probe;
+ window.addEventListener('message', event => {
+ if (event.source !== window || event.origin !== location.origin || event.data?.source !== 'estella-playable-preview' || event.data.type !== 'event') return;
+ if (probe.events.length >= 4096) { probe.dropped++; return; }
+ probe.events.push({ ...event.data, timeMs: Math.round(performance.now()) });
+ });
+ window.addEventListener('pointerup', event => { probe.pointerUps++; probe.lastPointerTrusted = event.isTrusted; }, true);
+ for (const proto of [window.WebGLRenderingContext?.prototype, window.WebGL2RenderingContext?.prototype]) {
+ if (!proto) continue;
+ for (const name of ['drawArrays', 'drawElements', 'drawArraysInstanced', 'drawElementsInstanced']) {
+ const original = proto[name];
+ if (!original) continue;
+ proto[name] = function (...args) { const result = original.apply(this, args); probe.drawCalls++; return result; };
+ }
+ }
+}
+
+/** Requested observations in a local mock; this never upgrades network/device acceptance. */
+export async function verifyPlayable({ htmlFile, reportFile, scenarioFile, outDir, network, storeUrl = '', timeoutMs = 15000, chromium, onProgress = () => {} }) {
+ if (!integer(timeoutMs, 1000, 60000)) throw new Error('Timeout must be 1000–60000 ms.');
+ const scenarioBytes = await readFile(scenarioFile), scenario = validatePlayableScenario(JSON.parse(scenarioBytes));
+ const reportBytes = reportFile ? await readFile(reportFile) : undefined;
+ const exported = reportBytes ? JSON.parse(reportBytes) : undefined;
+ const staticReport = exported?.playableCheck ?? exported;
+ const verifierSha256 = sha(await readFile(fileURLToPath(import.meta.url)));
+ const mockSha256 = sha(await readFile(new URL('./playable-preview.mjs', import.meta.url)));
+ const preview = await createPlayablePreview({ htmlFile, reportFile, network, storeUrl });
+ const result = { version: 1, mode: 'local-mock', status: 'checks-passed', headless: true,
+ network: preview.network, identityScope: preview.deliverySha256 ? 'delivery' : 'html-only',
+ htmlSha256: preview.htmlSha256, deliverySha256: preview.deliverySha256, deliveryFile: preview.deliveryFile,
+ scenarioSha256: sha(scenarioBytes), exportReportSha256: reportBytes ? sha(reportBytes) : undefined,
+ verifierSha256, mockSha256, storeUrl,
+ staticFailures: Array.isArray(staticReport?.checks) ? staticReport.checks.filter(check => check.status === 'fail') : [],
+ exportErrors: Array.isArray(exported?.errors) ? exported.errors : [],
+ pending: ['Original host SDK behavior (the mock substitutes it)', 'Official network acceptance', 'Device acceptance', 'Visual and audio quality review', 'Audio lifecycle was not observed'],
+ requestedCoverage: {
+ cta: scenario.steps.some(step => step.type === 'click' && step.expect?.event === 'store-click' && step.expect.count > 0 && (!step.networks || step.networks.includes(preview.network)) && (!step.expect.networks || step.expect.networks.includes(preview.network))),
+ hiddenLifecycle: scenario.steps.some(step => step.type === 'host' && step.command === 'hide' && (!step.networks || step.networks.includes(preview.network))),
+ dynamicRequests: true,
+ }, cases: [], errors: [] };
+ if (!result.requestedCoverage.cta) result.pending.push('CTA interaction was not requested by this scenario');
+ if (!result.requestedCoverage.hiddenLifecycle) result.pending.push('Hidden lifecycle was not requested for this network');
+ if (!Array.isArray(staticReport?.checks)) result.pending.push('Static export checks were not provided');
+ let browser;
+ try {
+ await mkdir(outDir, { recursive: true });
+ if (reportFile && sha(await readFile(reportFile)) !== sha(reportBytes)) throw new Error('Export report changed during setup.');
+ chromium ??= (await import('playwright')).chromium;
+ browser = await chromium.launch({ headless: true, args: ['--enable-unsafe-swiftshader', '--use-angle=swiftshader', '--mute-audio'] });
+ result.browser = { name: 'chromium', version: browser.version(), node: process.version };
+ for (const [caseIndex, viewport] of scenario.viewports.entries()) {
+ const record = { viewport, steps: [], requests: [], pageErrors: [], dialogs: [], popups: 0, screenshots: [], events: [], truncatedEvents: 0 };
+ result.cases.push(record);
+ const context = await browser.newContext({ viewport, serviceWorkers: 'block' });
+ let page;
+ try {
+ const origin = new URL(preview.url).origin;
+ await context.route('**/*', async route => {
+ if (new URL(route.request().url()).origin !== origin) await route.abort();
+ else await route.continue();
+ });
+ context.on('request', request => {
+ const url = new URL(request.url());
+ if (!['http:', 'https:'].includes(url.protocol)) return;
+ const type = request.resourceType();
+ const allowed = (url.pathname === '/creative' && type === 'document' && !record.requests.some(item => item.type === 'document'))
+ || (url.pathname === '/host-sdk.js' && type === 'script') || (url.pathname === '/favicon.ico' && type === 'other');
+ record.requests.push({ url: url.origin + url.pathname, method: request.method(), type,
+ expected: url.origin === origin && request.method() === 'GET' && allowed });
+ });
+ context.on('page', popup => { if (page && popup !== page) { record.popups++; void popup.close().catch(() => {}); } });
+ page = await context.newPage();
+ page.setDefaultTimeout(timeoutMs);
+ page.on('pageerror', error => record.pageErrors.push(error.message));
+ page.on('dialog', dialog => { record.dialogs.push({ type: dialog.type(), message: dialog.message().slice(0, 1024) }); void dialog.dismiss().catch(() => {}); });
+ page.on('websocket', socket => record.requests.push({ url: socket.url(), type: 'websocket', expected: false }));
+ await page.addInitScript(installProbe);
+ await page.goto(`${preview.url}creative?store=${encodeURIComponent(storeUrl)}`, { waitUntil: 'domcontentloaded' });
+ const events = () => page.evaluate(() => window.__ESTELLA_PLAYABLE_CHECK__.events);
+ const host = async command => {
+ if (command === 'ready' && preview.network === 'mintegral') throw new Error('Mintegral readiness is announced by the creative, not the host.');
+ if (command === 'hide' && !LIFECYCLE.includes(preview.network)) throw new Error(`The mock has no verified hide lifecycle for ${preview.network}.`);
+ const before = (await events()).length;
+ await page.evaluate(command => window.postMessage({ source: 'estella-playable-preview', type: 'command', command }, location.origin), command);
+ await page.waitForFunction(({ command, before }) => window.__ESTELLA_PLAYABLE_CHECK__.events.slice(before).some(event => event.name === 'host-command' && event.data.command === command), { command, before });
+ await page.waitForTimeout(100);
+ };
+ if (['mraid', 'unity', 'applovin'].includes(preview.network)) {
+ await page.waitForFunction(() => window.__ESTELLA_PLAYABLE_CHECK__.events.some(event => event.name === 'listener-added' && event.data.name === 'ready'));
+ await host('ready');
+ } else if (preview.network === 'mintegral') {
+ await page.waitForFunction(() => window.__ESTELLA_PLAYABLE_CHECK__.events.some(event => event.name === 'creative-ready'));
+ } else await page.waitForFunction(() => window.__ESTELLA_PLAYABLE_CHECK__.events.some(event => event.name === 'mock-installed'));
+ await host('show');
+ await page.waitForFunction(() => window.__ESTELLA_PLAYABLE_CHECK__.drawCalls > 0);
+ const canvas = page.locator('canvas').first();
+ for (const [stepIndex, step] of scenario.steps.entries()) {
+ const outcome = { index: stepIndex + 1, name: step.name ?? step.type, type: step.type, command: step.command, status: 'running' };
+ record.steps.push(outcome);
+ if (step.networks && !step.networks.includes(preview.network)) { outcome.status = 'not-applicable'; continue; }
+ if (step.type === 'host') await host(step.command);
+ else if (step.type === 'wait') await page.waitForTimeout(step.ms);
+ else if (step.type === 'frozen') {
+ const before = await canvas.screenshot(); await page.waitForTimeout(step.ms);
+ const after = await canvas.screenshot(); outcome.beforeSha256 = sha(before); outcome.afterSha256 = sha(after); outcome.observeMs = step.ms;
+ for (const [suffix, bytes] of [['before', before], ['after', after]]) {
+ const name = `case-${caseIndex + 1}-step-${stepIndex + 1}-${suffix}.png`;
+ await writeFile(path.join(outDir, name), bytes); record.screenshots.push({ file: name, sha256: sha(bytes) });
+ }
+ if (outcome.beforeSha256 !== outcome.afterSha256) throw new Error(`Step ${stepIndex + 1}: hidden canvas changed during the observation interval.`);
+ } else if (step.type === 'snapshot') {
+ const name = `case-${caseIndex + 1}-step-${stepIndex + 1}.png`, bytes = await canvas.screenshot();
+ await writeFile(path.join(outDir, name), bytes); record.screenshots.push({ file: name, sha256: sha(bytes) });
+ } else {
+ const before = (await events()).length, pointers = await page.evaluate(() => window.__ESTELLA_PLAYABLE_CHECK__.pointerUps);
+ const rect = await canvas.boundingBox(); if (!rect || rect.width <= 0 || rect.height <= 0) throw new Error('Canvas has no clickable area.');
+ await page.mouse.click(rect.x + rect.width * step.x, rect.y + rect.height * step.y, { delay: 40 });
+ outcome.trustedPointer = await page.evaluate(pointers => window.__ESTELLA_PLAYABLE_CHECK__.pointerUps === pointers + 1 && window.__ESTELLA_PLAYABLE_CHECK__.lastPointerTrusted, pointers);
+ if (!outcome.trustedPointer) throw new Error(`Step ${stepIndex + 1}: no trusted pointer release observed.`);
+ const expected = step.expect && (!step.expect.networks || step.expect.networks.includes(preview.network)) ? step.expect : undefined;
+ if (expected) outcome.expected = expected;
+ if (expected?.count > 0) {
+ try { await page.waitForFunction(({ before, expected }) => window.__ESTELLA_PLAYABLE_CHECK__.events.slice(before).filter(event => event.name === expected.event).length >= expected.count, { before, expected }); }
+ catch {
+ outcome.observedCount = (await events()).slice(before).filter(event => event.name === expected.event).length;
+ throw new Error(`Step ${stepIndex + 1}: expected ${expected.count} ${expected.event} event(s), observed ${outcome.observedCount}.`);
+ }
+ }
+ outcome.observeMs = step.observeMs ?? 300;
+ await page.waitForTimeout(outcome.observeMs);
+ if (expected) {
+ const observed = (await events()).slice(before).filter(event => event.name === expected.event);
+ outcome.expected = expected; outcome.observedCount = observed.length;
+ if (observed.length !== expected.count || (expected.userActivation && observed.some(event => !event.gesture))) throw new Error(`Step ${stepIndex + 1}: ${expected.event} count or active user activation did not match.`);
+ } else if (step.expect) outcome.expectationStatus = 'not-applicable';
+ }
+ outcome.status = 'passed';
+ onProgress({ case: caseIndex + 1, step: stepIndex + 1, name: outcome.name });
+ }
+ await page.waitForTimeout(300);
+ } catch (error) {
+ record.error = error.message; result.status = 'failed';
+ if (record.steps.at(-1)?.status === 'running') record.steps.at(-1).status = 'failed';
+ }
+ finally {
+ if (page) {
+ const probe = await page.evaluate(() => window.__ESTELLA_PLAYABLE_CHECK__ && ({ events: window.__ESTELLA_PLAYABLE_CHECK__.events, dropped: window.__ESTELLA_PLAYABLE_CHECK__.dropped, drawCalls: window.__ESTELLA_PLAYABLE_CHECK__.drawCalls, pointerUps: window.__ESTELLA_PLAYABLE_CHECK__.pointerUps })).catch(() => null);
+ if (probe) { record.events = probe.events; record.truncatedEvents = probe.dropped; record.drawCalls = probe.drawCalls; record.pointerUps = probe.pointerUps; }
+ else record.error ??= 'Creative observation state was lost.';
+ const bytes = await page.locator('canvas').first().screenshot().catch(() => null);
+ if (bytes) { const name = `case-${caseIndex + 1}-final.png`; await writeFile(path.join(outDir, name), bytes); record.screenshots.push({ file: name, sha256: sha(bytes) }); }
+ }
+ if (record.error || record.truncatedEvents || record.pageErrors.length || record.dialogs.length || record.popups
+ || record.requests.some(request => !request.expected) || record.events.some(event => ['page-error', 'blocked-request'].includes(event.name))) result.status = 'failed';
+ await context.close();
+ }
+ }
+ if (sha(await readFile(htmlFile)) !== preview.htmlSha256 || sha(await readFile(scenarioFile)) !== result.scenarioSha256
+ || (reportFile && sha(await readFile(reportFile)) !== result.exportReportSha256)
+ || (preview.deliverySha256 && sha(await readFile(path.join(path.dirname(path.resolve(htmlFile)), preview.deliveryFile))) !== preview.deliverySha256)) throw new Error('An input artifact changed during verification.');
+ if (result.staticFailures.length || staticReport?.status === 'failed' || exported?.ok === false) result.status = 'failed';
+ } catch (error) { result.status = 'failed'; result.errors.push(error.message); }
+ finally {
+ if (browser) await browser.close().catch(error => { result.status = 'failed'; result.errors.push(`Browser cleanup: ${error.message}`); });
+ await preview.close();
+ }
+ await mkdir(outDir, { recursive: true });
+ await writeFile(path.join(outDir, 'runtime-check.json'), JSON.stringify(result, null, 2) + '\n');
+ return result;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ const args = process.argv.slice(2), allowed = ['scenario', 'report', 'out', 'network', 'store-url', 'timeout'];
+ if (!args.length || args.includes('--help')) {
+ console.log('node tools/verify-playable.mjs <index.html> --scenario <scenario.json> --out <directory> [--report <export-result.json>] [--network <id>] [--store-url <url>] [--timeout <ms>]\nAlways headless. Requires Playwright Chromium (pnpm exec playwright install chromium). Results are local mocks, not network/device approval.');
+ } else {
+ try {
+ const options = {};
+ for (let i = 1; i < args.length; i += 2) {
+ const key = args[i].replace(/^--/, '');
+ if (!args[i].startsWith('--') || !allowed.includes(key) || !args[i + 1] || options[key] !== undefined) throw new Error('Unknown, missing or duplicate option. Use --help.');
+ options[key] = args[i + 1];
+ }
+ if (!options.scenario || !options.out) throw new Error('--scenario and --out are required.');
+ verifyPlayable({ htmlFile: path.resolve(args[0]), reportFile: options.report && path.resolve(options.report),
+ scenarioFile: path.resolve(options.scenario), outDir: path.resolve(options.out), network: options.network,
+ storeUrl: options['store-url'], timeoutMs: Number(options.timeout ?? 15000),
+ onProgress: value => console.log(`Case ${value.case}, step ${value.step}: ${value.name}`),
+ }).then(result => { console.log(`${result.status} · local-mock · ${result.cases.length} viewport(s)\n${path.resolve(options.out, 'runtime-check.json')}`); process.exitCode = result.status === 'checks-passed' ? 0 : 1; })
+ .catch(error => { console.error(error.message); process.exitCode = 1; });
+ } catch (error) { console.error(error.message); process.exitCode = 1; }
+ }
+}