@mindscraft/branch-video-agent-cli 0.3.6 → 0.4.0

package/dist/playtest/report.js

@@ -0,0 +1,34 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+function escapeXml(value) {
+    return String(value)
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+export function createJUnitXml(report) {
+    const scenarioFindingKeys = new Set(report.scenarios.flatMap((scenario) => scenario.findings.map((finding) => `${finding.code}\u0000${finding.message}`)));
+    const gateFindings = report.findings.filter((finding) => !scenarioFindingKeys.has(`${finding.code}\u0000${finding.message}`));
+    const failures = report.scenarios.filter((scenario) => scenario.status === 'failed').length + gateFindings.length;
+    const duration = report.scenarios.reduce((sum, scenario) => sum + scenario.durationMs, 0) / 1000;
+    const scenarioCases = report.scenarios.map((scenario) => {
+        const finding = scenario.findings[0];
+        const failure = finding
+            ? `<failure type="${escapeXml(finding.code)}" message="${escapeXml(finding.message)}">${escapeXml(JSON.stringify(finding.details ?? null))}</failure>`
+            : '';
+        return `<testcase classname="branch-video-playtest" name="${escapeXml(scenario.id)}" time="${(scenario.durationMs / 1000).toFixed(3)}">${failure}</testcase>`;
+    }).join('');
+    const gateCases = gateFindings.map((finding, index) => (`<testcase classname="branch-video-playtest.gate" name="gate-${index + 1}-${escapeXml(finding.code)}" time="0.000"><failure type="${escapeXml(finding.code)}" message="${escapeXml(finding.message)}">${escapeXml(JSON.stringify(finding.details ?? null))}</failure></testcase>`)).join('');
+    const tests = report.scenarios.length + gateFindings.length;
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="branch-video-playtest" tests="${tests}" failures="${failures}" time="${duration.toFixed(3)}">${scenarioCases}${gateCases}</testsuite>\n`;
+}
+export async function writePlaytestReport(reportDir, report) {
+    await mkdir(reportDir, { recursive: true });
+    const jsonPath = path.join(reportDir, 'branch-video-playtest-report.json');
+    const junitPath = path.join(reportDir, 'junit.xml');
+    await writeFile(jsonPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    await writeFile(junitPath, createJUnitXml(report), 'utf8');
+    return { jsonPath, junitPath };
+}

package/dist/playtest/runner.d.ts

@@ -0,0 +1,23 @@
+import type { PlaytestContract, PlaytestLimits, PlaytestScenario, PlaytestScenarioResult } from './types.js';
+type ScriptRecord = Record<string, any>;
+interface RunnerOptions {
+    script: ScriptRecord;
+    contract: PlaytestContract;
+    scenarios: PlaytestScenario[];
+    playerUrl: string;
+    draftScriptUrl?: string;
+    reportDir: string;
+    concurrency: number;
+    limits: PlaytestLimits;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export declare function runPlaytestScenarios(options: RunnerOptions): Promise<PlaytestScenarioResult[]>;
+export declare function createDraftPlayerUrl(baseUrl: string): {
+    playerUrl: string;
+    scriptUrl: string;
+};
+export declare function createPublishedPlayerUrl(playUrl: string): string;
+export {};

package/dist/playtest/runner.js

@@ -0,0 +1,571 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { chromium } from 'playwright';
+import { PlaytestError } from './errors.js';
+function locatorFor(frame, spec) {
+    if (spec.by === 'role')
+        return frame.getByRole(spec.role, { name: spec.name, exact: spec.exact });
+    if (spec.by === 'label')
+        return frame.getByLabel(spec.label, { exact: spec.exact });
+    if (spec.by === 'testId')
+        return frame.getByTestId(spec.testId);
+    return frame.locator(spec.selector);
+}
+async function runWebStep(frame, step) {
+    const locator = locatorFor(frame, step.locator);
+    if (step.action === 'click')
+        await locator.click();
+    else if (step.action === 'fill')
+        await locator.fill(step.value);
+    else if (step.action === 'selectOption')
+        await locator.selectOption(step.value);
+    else if (step.action === 'check')
+        await locator.setChecked(step.checked ?? true);
+    else if (step.action === 'press')
+        await locator.press(step.key);
+    else if (step.action === 'dragTo')
+        await locator.dragTo(locatorFor(frame, step.target));
+    else if (step.action === 'setInputFiles')
+        await locator.setInputFiles(step.files);
+    else
+        await locator.waitFor({ state: step.state ?? 'visible', timeout: step.timeoutMs });
+}
+function appendInstrumentationQuery(rawUrl) {
+    const url = new URL(rawUrl);
+    url.searchParams.set('embedPlatform', 'web_player_sdk');
+    url.searchParams.set('playtest', 'true');
+    return url.toString();
+}
+function rawMessageValue(message) {
+    if (message?.value !== undefined)
+        return message.value;
+    if (message?.data?.value !== undefined)
+        return message.data.value;
+    if (message?.data?.result !== undefined)
+        return message.data.result;
+    if (message?.data?.UEStatus !== undefined)
+        return message.data.UEStatus;
+    if (message?.data?.data?.UEStatus !== undefined)
+        return message.data.data.UEStatus;
+    if (message?.data?.data?.data?.UEStatus !== undefined)
+        return message.data.data.data.UEStatus;
+    return message?.data;
+}
+function comparableMessageValue(value) {
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : value;
+}
+function matchesRawMessage(observed, expected) {
+    const actual = observed.data;
+    const actualEventName = actual?.eventName ?? actual?.type ?? actual?.event;
+    if (actualEventName !== expected.eventName)
+        return false;
+    const expectedValue = expected.value ?? expected.data?.value ?? expected.data;
+    return JSON.stringify(comparableMessageValue(rawMessageValue(actual))) === JSON.stringify(comparableMessageValue(expectedValue));
+}
+function getNode(script, nodeId) {
+    return script.graph?.nodes?.[nodeId] || {};
+}
+async function waitForPlayerFrame(page, playerUrl, timeout) {
+    const expected = new URL(playerUrl);
+    const iframe = page.locator('iframe[title="BV playtest player"]');
+    const handle = await iframe.elementHandle({ timeout });
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        const frame = await handle?.contentFrame();
+        if (frame) {
+            try {
+                const actual = new URL(frame.url());
+                if (actual.origin === expected.origin && actual.pathname === expected.pathname)
+                    return frame;
+            }
+            catch {
+                // Navigation has not committed yet.
+            }
+        }
+        await page.waitForTimeout(50);
+    }
+    throw new PlaytestError('PLAYER_LOAD_FAILED', `Player iframe did not load ${playerUrl}`);
+}
+async function waitForNode(frame, nodeId, timeout) {
+    try {
+        await frame.waitForFunction((expectedNodeId) => (globalThis.document.querySelector('[data-bv-node-id]')?.getAttribute('data-bv-node-id') === expectedNodeId), nodeId, { timeout });
+    }
+    catch {
+        const actual = await frame.locator('[data-bv-node-id]').first().getAttribute('data-bv-node-id').catch(() => null);
+        throw new PlaytestError('ROUTE_TARGET_MISMATCH', `Expected node ${nodeId}, reached ${actual || 'none'}`, { expected: nodeId, actual });
+    }
+}
+async function startPlayback(frame, entryNodeId, entryNodeType, timeout) {
+    const startButton = frame.getByRole('button', { name: '开始体验' });
+    if (await startButton.isVisible().catch(() => false))
+        await startButton.click();
+    await frame.locator('[data-bv-node-id]').first().waitFor({ state: 'visible', timeout });
+    const current = await frame.locator('[data-bv-node-id]').first().getAttribute('data-bv-node-id');
+    if (current !== entryNodeId) {
+        const observed = await readObservedMessages(frame);
+        const sawEntry = observed.some((message) => JSON.stringify(message.data).includes(entryNodeId));
+        if (!sawEntry && entryNodeType !== 'start') {
+            throw new PlaytestError('NODE_NOT_RENDERED', `Entry node ${entryNodeId} was not observed before ${current || 'none'}`);
+        }
+    }
+}
+async function assertNodeMedia(frame, node) {
+    if (node.type === 'video') {
+        const video = frame.locator('video').first();
+        await video.waitFor({ state: 'visible' });
+        const state = await video.evaluate(async (element) => {
+            if (element.readyState < 1) {
+                await new Promise((resolve, reject) => {
+                    const timer = globalThis.setTimeout(() => reject(new Error('loadedmetadata timeout')), 10000);
+                    element.addEventListener('loadedmetadata', () => { globalThis.clearTimeout(timer); resolve(); }, { once: true });
+                    element.addEventListener('error', () => { globalThis.clearTimeout(timer); reject(new Error('video error')); }, { once: true });
+                });
+            }
+            const before = element.currentTime;
+            await element.play().catch(() => undefined);
+            await new Promise((resolve) => globalThis.setTimeout(resolve, 200));
+            return { readyState: element.readyState, duration: element.duration, progressed: element.currentTime > before };
+        });
+        if (state.readyState < 1 || !Number.isFinite(state.duration)) {
+            throw new PlaytestError('MEDIA_LOAD_FAILED', `Video media failed on node ${node.id}`, state);
+        }
+    }
+    if (node.type === 'image') {
+        const image = frame.locator('img').filter({ visible: true }).first();
+        await image.waitFor({ state: 'visible' });
+        const loaded = await image.evaluate((element) => element.complete && element.naturalWidth > 0);
+        if (!loaded)
+            throw new PlaytestError('MEDIA_LOAD_FAILED', `Image media failed on node ${node.id}`);
+    }
+    if (node.type === 'web') {
+        await frame.locator('iframe[title="Web 页面"]').waitFor({ state: 'visible' });
+    }
+}
+async function readObservedMessages(frame) {
+    return frame.evaluate(() => globalThis.__bvPlaytestObservedMessages || []).catch(() => []);
+}
+async function executeWebEdge(frame, node, edge, contract) {
+    const explicitRoutes = new Set((node.branchConfig?.rules || [])
+        .filter((rule) => rule.trigger?.type === 'message')
+        .map((rule) => String(rule.trigger.value)));
+    const recipe = edge.trigger.type === 'message'
+        ? contract.webResults.find((candidate) => candidate.nodeId === edge.from && candidate.routeValue === String(edge.trigger.value))
+        : contract.webResults.find((candidate) => candidate.nodeId === edge.from && !explicitRoutes.has(candidate.routeValue));
+    if (!recipe)
+        throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `No recipe for ${edge.from}:${String(edge.trigger.value)}`);
+    const webFrame = frame.childFrames().find((candidate) => candidate.url() !== 'about:blank');
+    if (!webFrame)
+        throw new PlaytestError('WEB_FRAME_LOAD_FAILED', `Web iframe did not load on node ${edge.from}`);
+    const before = (await readObservedMessages(frame)).length;
+    for (const step of recipe.steps)
+        await runWebStep(webFrame, step);
+    try {
+        await frame.waitForFunction((payload) => {
+            const { start, rawMessage } = payload;
+            const messages = (globalThis.__bvPlaytestObservedMessages || []).slice(start);
+            const expectedEvent = rawMessage.eventName;
+            const expectedValue = rawMessage.value ?? rawMessage.data?.value ?? rawMessage.data;
+            return messages.some((entry) => {
+                const actual = entry.data;
+                const eventName = actual?.eventName ?? actual?.type ?? actual?.event;
+                const value = actual?.value
+                    ?? actual?.data?.value
+                    ?? actual?.data?.result
+                    ?? actual?.data?.UEStatus
+                    ?? actual?.data?.data?.UEStatus
+                    ?? actual?.data?.data?.data?.UEStatus
+                    ?? actual?.data;
+                const comparableActual = typeof value === 'string' || typeof value === 'number' ? String(value) : value;
+                const comparableExpected = typeof expectedValue === 'string' || typeof expectedValue === 'number' ? String(expectedValue) : expectedValue;
+                return eventName === expectedEvent && JSON.stringify(comparableActual) === JSON.stringify(comparableExpected);
+            });
+        }, { start: before, rawMessage: recipe.rawMessage }, { timeout: 10000 });
+    }
+    catch {
+        const observed = (await readObservedMessages(frame)).slice(before);
+        throw new PlaytestError('WEB_MESSAGE_NOT_EMITTED', `Web actions did not emit the expected raw message for ${edge.from}:${recipe.routeValue}`, { observed });
+    }
+    const emitted = (await readObservedMessages(frame)).slice(before);
+    if (!emitted.some((message) => matchesRawMessage(message, recipe.rawMessage))) {
+        throw new PlaytestError('WEB_MESSAGE_NOT_EMITTED', `Expected Web raw message was not recorded for ${edge.from}:${recipe.routeValue}`);
+    }
+}
+function chooseResultOption(interaction, result) {
+    const type = String(interaction.interactive?.type || '');
+    if (type.toLowerCase().includes('judge')) {
+        const correct = interaction.interactive?.correctAnswer !== false;
+        return [String(result === 'correct' ? correct : !correct)];
+    }
+    const options = interaction.interactive?.options || [];
+    const correct = options.filter((option) => option.isCorrect).map((option) => String(option.id));
+    const wrong = options.filter((option) => !option.isCorrect).map((option) => String(option.id));
+    if (result === 'correct')
+        return correct.length ? correct : options.slice(0, 1).map((option) => String(option.id));
+    if (result === 'partial') {
+        if (correct.length > 1)
+            return [correct[0]];
+        if (correct.length && wrong.length)
+            return [correct[0], wrong[0]];
+    }
+    return wrong.length ? [wrong[0]] : options.slice(-1).map((option) => String(option.id));
+}
+async function clickAction(frame, action) {
+    const control = frame.locator(`[data-bv-action="${action}"]`).first();
+    const nestedButton = control.locator('button').first();
+    if (await nestedButton.count())
+        await nestedButton.click();
+    else
+        await control.click();
+}
+async function executeNativeInteraction(frame, node, edge, contract) {
+    const interaction = (node.interactions || []).find((candidate) => candidate.id === edge.ownerId);
+    if (!interaction)
+        throw new PlaytestError('INTERACTION_NOT_RENDERED', `Interaction ${edge.ownerId} is absent from node ${edge.from}`);
+    if (node.type === 'web' && interaction.trigger?.type === 'message') {
+        await executeWebEdge(frame, node, {
+            ...edge,
+            owner: 'node',
+            ownerId: node.id,
+            trigger: { type: 'message', value: interaction.trigger.value },
+        }, contract);
+    }
+    else if (interaction.trigger?.type === 'time' && node.type === 'video') {
+        await frame.locator('video').first().evaluate((element, time) => {
+            element.currentTime = time + 0.05;
+            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
+        }, Number(interaction.trigger.value || 0));
+    }
+    else if (interaction.trigger?.type === 'time' && Number(interaction.trigger.value || 0) > 0) {
+        await frame.page().waitForTimeout(Number(interaction.trigger.value) * 1000 + 50);
+    }
+    else if (interaction.trigger?.type === 'complete' && node.type === 'video') {
+        await frame.locator('video').first().evaluate((element) => {
+            element.dispatchEvent(new globalThis.Event('ended', { bubbles: true }));
+        });
+    }
+    await frame.locator(`[data-bv-interaction-id="${edge.ownerId}"]`).waitFor({ state: 'attached' });
+    if (edge.trigger.type === 'timeout') {
+        await frame.page().waitForTimeout((Number(interaction.timeLimit || 0) + 2.5) * 1000);
+        return;
+    }
+    const interactionType = String(interaction.interactive?.type || '');
+    const resultValue = edge.trigger.type === 'result'
+        ? String(edge.trigger.value)
+        : edge.trigger.type === 'legacy'
+            ? String(edge.trigger.value) === 'true'
+                ? 'correct'
+                : String(edge.trigger.value) === 'partial'
+                    ? 'partial'
+                    : 'incorrect'
+            : 'incorrect';
+    if (interactionType === 'score_settlement') {
+        await clickAction(frame, 'confirm-settlement');
+        return;
+    }
+    if (interactionType === 'logic_chain') {
+        const ids = (interaction.interactive?.chainOptions || []).map((option) => String(option.id));
+        const orderedIds = resultValue === 'correct' ? ids : [...ids].reverse();
+        for (const optionId of orderedIds) {
+            await frame.locator(`[data-bv-option-id="${optionId}"]`).first().click();
+        }
+        await clickAction(frame, 'submit');
+        return;
+    }
+    if (interactionType === 'blank_fill') {
+        const blanks = interaction.interactive?.blanks || [];
+        const options = interaction.interactive?.options || [];
+        for (let index = 0; index < blanks.length; index += 1) {
+            const blank = blanks[index];
+            const correctId = String(blank.correctOptionId || '');
+            const wrongId = String(options.find((option) => String(option.id) !== correctId)?.id || correctId);
+            const optionId = resultValue === 'incorrect' || (resultValue === 'partial' && index > 0) ? wrongId : correctId;
+            await frame.locator(`[data-bv-option-id="${optionId}"]`).first().dragTo(frame.locator(`[data-bv-blank-id="${blank.id}"]`));
+        }
+        await clickAction(frame, 'submit');
+        return;
+    }
+    if (interactionType === 'input_fill') {
+        const blanks = interaction.interactive?.blanks || [];
+        for (let index = 0; index < blanks.length; index += 1) {
+            const blank = blanks[index];
+            const shouldBeWrong = resultValue === 'incorrect' || (resultValue === 'partial' && index > 0);
+            const answer = shouldBeWrong ? '__wrong__' : (blank.correctAnswers?.[0] ?? 'playtest');
+            const control = frame.locator(`[data-bv-blank-id="${blank.id}"]`);
+            if (blank.type === 'number') {
+                await control.click();
+                for (const key of String(answer))
+                    await control.press(key);
+            }
+            else {
+                await control.fill(String(answer));
+            }
+        }
+        await clickAction(frame, 'submit');
+        return;
+    }
+    let optionIds = [];
+    if (edge.trigger.type === 'option')
+        optionIds = [String(edge.trigger.value)];
+    else if (edge.trigger.type === 'options')
+        optionIds = Array.isArray(edge.trigger.value) ? edge.trigger.value.map(String) : [];
+    else if (edge.trigger.type === 'result')
+        optionIds = chooseResultOption(interaction, String(edge.trigger.value));
+    else if (edge.trigger.type === 'legacy') {
+        const legacy = String(edge.trigger.value);
+        optionIds = legacy === 'true'
+            ? chooseResultOption(interaction, 'correct')
+            : legacy === 'partial'
+                ? chooseResultOption(interaction, 'partial')
+                : chooseResultOption(interaction, 'incorrect');
+    }
+    if (interaction.interactive?.collectMode?.mode === 'all') {
+        optionIds = (interaction.interactive?.options || []).map((option) => String(option.id));
+    }
+    if (optionIds.length) {
+        for (const optionId of optionIds) {
+            const option = frame.locator(`[data-bv-option-id="${optionId}"]`);
+            if (await option.count())
+                await option.first().click();
+            else {
+                const optionText = interaction.interactive?.options?.find((candidate) => String(candidate.id) === optionId)?.text;
+                if (!optionText)
+                    throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `No real control for option ${optionId} in interaction ${edge.ownerId}`);
+                await frame.getByText(String(optionText), { exact: true }).click();
+            }
+        }
+        const submit = frame.locator('[data-bv-action="submit"]');
+        if (await submit.isVisible().catch(() => false))
+            await clickAction(frame, 'submit');
+        return;
+    }
+    const inputs = frame.locator(`[data-bv-interaction-id="${edge.ownerId}"] input`);
+    if (await inputs.count()) {
+        const blanks = interaction.interactive?.blanks || [];
+        for (let index = 0; index < await inputs.count(); index += 1) {
+            const answer = blanks[index]?.correctAnswers?.[0] ?? blanks[index]?.answer ?? blanks[index]?.correctAnswer ?? blanks[index]?.answers?.[0] ?? 'playtest';
+            await inputs.nth(index).fill(String(edge.trigger.value === 'incorrect' ? '__wrong__' : answer));
+        }
+        await clickAction(frame, 'submit');
+        return;
+    }
+    throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `No real DOM driver is available for ${edge.ownerId}:${edge.trigger.type}`);
+}
+async function executeEdge(frame, edge, options) {
+    const node = getNode(options.script, edge.from);
+    await assertNodeMedia(frame, node);
+    if (edge.owner === 'interaction') {
+        await executeNativeInteraction(frame, node, edge, options.contract);
+    }
+    else if (node.type === 'web' && (edge.trigger.type === 'message' || edge.default)) {
+        await executeWebEdge(frame, node, edge, options.contract);
+    }
+    else if (node.type === 'video' && edge.trigger.type === 'time') {
+        await frame.locator('video').first().evaluate((element, time) => {
+            element.currentTime = time + 0.05;
+            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
+        }, Number(edge.trigger.value));
+    }
+    else if (node.type === 'video' && edge.trigger.type === 'complete') {
+        await frame.locator('video').first().evaluate((element) => {
+            if (Number.isFinite(element.duration) && element.duration > 0)
+                element.currentTime = Math.max(0, element.duration - 0.01);
+            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
+            element.dispatchEvent(new globalThis.Event('ended', { bubbles: true }));
+        });
+    }
+    else if (edge.trigger.type === 'enter') {
+        // Start/enter transitions are produced by the runtime itself.
+    }
+    else if (node.type === 'image' && edge.trigger.type === 'complete') {
+        const durationMs = (node.config?.slides || []).reduce((sum, slide) => sum + Number(slide.duration || 0) * 1000, 0);
+        await frame.page().waitForTimeout(Math.min(durationMs + 250, options.limits.scenarioTimeoutMs / 2));
+    }
+    else {
+        throw new PlaytestError('EDGE_DRIVER_UNSUPPORTED', `No real runtime driver for edge ${edge.id}`);
+    }
+    if (edge.actionType === 'end') {
+        try {
+            await frame.waitForFunction(() => (globalThis.document.querySelector('[data-bv-ended]')?.getAttribute('data-bv-ended') === 'true'), undefined, { timeout: Math.min(10000, options.limits.scenarioTimeoutMs) });
+        }
+        catch {
+            throw new PlaytestError('ROUTE_TARGET_MISMATCH', `Edge ${edge.id} did not reach the ended state`);
+        }
+    }
+    else if (edge.actionType === 'seek' && node.type === 'video' && Number.isFinite(Number(edge.action.time))) {
+        await frame.waitForFunction((expectedTime) => {
+            const video = globalThis.document.querySelector('video');
+            return video && Math.abs(Number(video.currentTime) - Number(expectedTime)) < 0.5;
+        }, Number(edge.action.time), { timeout: Math.min(10000, options.limits.scenarioTimeoutMs) });
+    }
+    else {
+        await waitForNode(frame, edge.to, Math.min(10000, options.limits.scenarioTimeoutMs));
+    }
+}
+async function createContext(browser, options, scenarioDir) {
+    const launchOptions = {
+        viewport: options.viewport,
+        recordVideo: { dir: scenarioDir, size: options.viewport },
+        permissions: options.contract.microphoneWavPath ? ['microphone'] : [],
+    };
+    if (options.contract.storageStatePath)
+        launchOptions.storageState = options.contract.storageStatePath;
+    return browser.newContext(launchOptions);
+}
+async function runScenario(browser, scenario, options) {
+    const startedAt = Date.now();
+    const scenarioDir = path.join(options.reportDir, 'artifacts', scenario.id);
+    await mkdir(scenarioDir, { recursive: true });
+    const context = await createContext(browser, options, scenarioDir);
+    const page = await context.newPage();
+    const logs = [];
+    const findings = [];
+    const warnings = [];
+    const visitedNodes = [];
+    const coveredEdges = [];
+    const artifacts = {};
+    let playerReady = false;
+    let traceStopped = false;
+    page.on('console', (message) => {
+        const text = message.text();
+        logs.push(`[console:${message.type()}] ${text}`);
+        const isNetworkOrTelemetryNoise = /failed to load resource|net::|telemetry|analytics|favicon/i.test(text);
+        const isComponentException = /uncaught|unhandled|error boundary|component stack|TypeError|ReferenceError|React/i.test(text);
+        if (playerReady && message.type() === 'error' && !isNetworkOrTelemetryNoise && isComponentException) {
+            findings.push({ code: 'COMPONENT_CONSOLE_ERROR', message: text, scenarioId: scenario.id });
+        }
+        else if (message.type() === 'error') {
+            warnings.push({ code: 'BROWSER_CONSOLE_WARNING', message: text, scenarioId: scenario.id });
+        }
+    });
+    page.on('pageerror', (error) => {
+        logs.push(`[pageerror] ${error.stack || error.message}`);
+        if (playerReady)
+            findings.push({ code: 'COMPONENT_RUNTIME_ERROR', message: error.message, scenarioId: scenario.id });
+    });
+    page.on('requestfailed', (request) => {
+        const message = `${request.method()} ${request.url()} ${request.failure()?.errorText || ''}`;
+        logs.push(`[requestfailed] ${message}`);
+        warnings.push({ code: 'REQUEST_FAILED_WARNING', message, scenarioId: scenario.id });
+    });
+    await context.addInitScript(() => {
+        const browserWindow = globalThis;
+        browserWindow.__bvPlaytestObservedMessages = [];
+        browserWindow.addEventListener('message', (event) => {
+            browserWindow.__bvPlaytestObservedMessages.push({ data: event.data, origin: event.origin, at: Date.now() });
+        });
+    });
+    await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+    if (options.draftScriptUrl) {
+        await page.route(options.draftScriptUrl, (route) => route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            headers: { 'access-control-allow-origin': '*' },
+            body: JSON.stringify(options.script),
+        }));
+    }
+    let timeoutHandle;
+    const scenarioTimeout = new Promise((_, reject) => {
+        timeoutHandle = globalThis.setTimeout(() => reject(new PlaytestError('SCENARIO_TIMEOUT', `Scenario ${scenario.id} exceeded ${options.limits.scenarioTimeoutMs}ms`)), options.limits.scenarioTimeoutMs);
+    });
+    try {
+        await Promise.race([(async () => {
+                await page.setContent('<!doctype html><html><body style="margin:0"><iframe title="BV playtest player" style="border:0;width:1280px;height:720px"></iframe></body></html>');
+                await page.locator('iframe[title="BV playtest player"]').evaluate((element, url) => { element.src = url; }, options.playerUrl);
+                const playerFrame = await waitForPlayerFrame(page, options.playerUrl, options.limits.scenarioTimeoutMs);
+                const entryNodeId = String(options.script.graph?.entryNodeId || '');
+                await startPlayback(playerFrame, entryNodeId, String(getNode(options.script, entryNodeId).type || ''), options.limits.scenarioTimeoutMs);
+                playerReady = true;
+                await assertNodeMedia(playerFrame, getNode(options.script, entryNodeId));
+                visitedNodes.push(String(options.script.graph?.entryNodeId || ''));
+                for (const edge of scenario.edges) {
+                    await executeEdge(playerFrame, edge, options);
+                    coveredEdges.push(edge.id);
+                    if (!edge.to.startsWith('@'))
+                        visitedNodes.push(edge.to);
+                }
+            })(), scenarioTimeout]);
+    }
+    catch (error) {
+        const failure = error instanceof PlaytestError ? error : new PlaytestError('SCENARIO_FAILED', error instanceof Error ? error.message : String(error));
+        findings.push({ code: failure.code, message: failure.message, scenarioId: scenario.id, edgeId: scenario.targetEdgeId, details: failure.details });
+        const screenshotPath = path.join(scenarioDir, 'failure.png');
+        await page.screenshot({ path: screenshotPath, fullPage: true }).catch(() => undefined);
+        artifacts.screenshot = screenshotPath;
+    }
+    finally {
+        if (timeoutHandle)
+            globalThis.clearTimeout(timeoutHandle);
+        const logPath = path.join(scenarioDir, 'browser.log');
+        await writeFile(logPath, `${logs.join('\n')}\n`, 'utf8');
+        artifacts.browserLog = logPath;
+        const tracePath = path.join(scenarioDir, 'trace.zip');
+        await context.tracing.stop({ path: tracePath }).then(() => { traceStopped = true; }).catch(() => undefined);
+        if (traceStopped)
+            artifacts.trace = tracePath;
+        const video = page.video();
+        await context.close();
+        if (video) {
+            const videoPath = await video.path().catch(() => null);
+            if (videoPath)
+                artifacts.video = videoPath;
+        }
+    }
+    return {
+        id: scenario.id,
+        targetEdgeId: scenario.targetEdgeId,
+        status: findings.length ? 'failed' : 'passed',
+        durationMs: Date.now() - startedAt,
+        visitedNodes: [...new Set(visitedNodes)],
+        coveredEdges,
+        findings,
+        warnings,
+        artifacts,
+    };
+}
+export async function runPlaytestScenarios(options) {
+    let browser;
+    try {
+        browser = await chromium.launch({
+            headless: true,
+            args: options.contract.microphoneWavPath
+                ? ['--use-fake-ui-for-media-stream', '--use-fake-device-for-media-stream', `--use-file-for-fake-audio-capture=${path.resolve(options.contract.microphoneWavPath)}`]
+                : [],
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/executable.*doesn.t exist|browser.*not found|playwright install/i.test(message)) {
+            throw new PlaytestError('PLAYWRIGHT_BROWSER_MISSING', 'Playwright Chromium is not installed. Run: npx playwright install chromium', { cause: message });
+        }
+        throw error;
+    }
+    try {
+        const results = new Array(options.scenarios.length);
+        let nextIndex = 0;
+        const workers = Array.from({ length: Math.min(options.concurrency, options.scenarios.length) }, async () => {
+            while (nextIndex < options.scenarios.length) {
+                const index = nextIndex;
+                nextIndex += 1;
+                results[index] = await runScenario(browser, options.scenarios[index], options);
+            }
+        });
+        await Promise.all(workers);
+        return results;
+    }
+    finally {
+        await browser.close();
+    }
+}
+export function createDraftPlayerUrl(baseUrl) {
+    const scriptUrl = 'https://branch-video-playtest.invalid/script.json';
+    const playerUrl = new URL('/branch-video', baseUrl);
+    playerUrl.searchParams.set('script', scriptUrl);
+    return { playerUrl: appendInstrumentationQuery(playerUrl.toString()), scriptUrl };
+}
+export function createPublishedPlayerUrl(playUrl) {
+    const url = new URL(playUrl);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new PlaytestError('VALIDATION_ERROR', 'published playUrl must be an HTTP(S) URL');
+    }
+    return url.toString();
+}

package/dist/playtest/scenarios.d.ts

@@ -0,0 +1,2 @@
+import type { PlaytestLimits, PlaytestScenario } from './types.js';
+export declare function buildPlaytestScenarios(script: unknown, limits: PlaytestLimits, nodeVisitLimits?: Record<string, number>): PlaytestScenario[];