flowstride 1.0.20 → 1.0.22

package/dist/native/events.js

@@ -0,0 +1,308 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeEvents = exports.ArmedEvent = void 0;
+exports.matchesURL = matchesURL;
+const assertion_result_1 = require("../reporting/assertion_result");
+const zod_1 = require("zod");
+const validation_1 = require("./validation");
+const projectPaths_1 = require("../utils/projectPaths");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_util_1 = require("node:util");
+// The promise always resolves to an outcome, including timeout/cancellation. Arming a
+// waiter never leaves a rejecting promise while a following click is still pending.
+class ArmedEvent {
+    detach;
+    settled = false;
+    timer;
+    resolve;
+    promise = new Promise(resolve => { this.resolve = resolve; });
+    constructor(timeout, detach) {
+        this.detach = detach;
+        this.timer = setTimeout(() => this.fail(new Error('Armed event timed out.')), validation_1.positive.parse(timeout));
+    }
+    capture(value) { if (this.settled)
+        return; this.settled = true; clearTimeout(this.timer); this.detach(); this.resolve({ value }); }
+    fail(error) { if (this.settled)
+        return; this.settled = true; clearTimeout(this.timer); this.detach(); this.resolve({ error }); }
+    async take() { const result = await this.promise; if (result.error)
+        throw result.error; return result.value; }
+}
+exports.ArmedEvent = ArmedEvent;
+const urlPattern = zod_1.z.string().min(1).max(4000);
+function matchesURL(pattern, url) {
+    const regexp = pattern.split('**').map(part => part.split('*').map(bit => bit.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*');
+    return new RegExp(`^${regexp}$`).test(url);
+}
+const routeSchema = zod_1.z.object({ name: validation_1.name, url: urlPattern, method: zod_1.z.string().optional(),
+    mode: zod_1.z.enum(['fulfill', 'abort', 'continue', 'patch']).default('fulfill'), status: zod_1.z.number().int().min(100).max(599).optional(),
+    headers: validation_1.headers.optional(), json: zod_1.z.unknown().optional(), body: zod_1.z.string().optional(), fixture: zod_1.z.string().optional(),
+    contentType: zod_1.z.string().optional(), request: zod_1.z.object({ url: zod_1.z.string().url().optional(), method: zod_1.z.string().optional(), headers: validation_1.headers.optional(), body: zod_1.z.string().optional() }).strict().optional(),
+    times: validation_1.positive.optional(),
+}).strict();
+const armSchema = zod_1.z.object({ name: validation_1.name, url: urlPattern, method: zod_1.z.string().optional(), kind: zod_1.z.enum(['request', 'response']).default('response'), timeout: validation_1.positive.optional(), status: zod_1.z.number().int().optional() }).strict();
+const networkExpect = zod_1.z.object({ name: validation_1.name, status: zod_1.z.number().int().optional(), method: zod_1.z.string().optional(), header: zod_1.z.string().optional(), equals: zod_1.z.unknown().optional(), path: zod_1.z.string().optional(), contains: zod_1.z.string().optional() }).strict();
+class NativeEvents {
+    web;
+    config;
+    routes = new Map();
+    events = new Map();
+    captured = new Map();
+    routeErrors = [];
+    generation = 0;
+    downloads = new Map();
+    savedDownloads = new Map();
+    constructor(web, config) {
+        this.web = web;
+        this.config = config;
+    }
+    key(value) { return `${this.web.activeProfile}:${value}`; }
+    async network(action, input, reporter) {
+        if (this.routeErrors.length)
+            throw new Error(`Network route failed: ${this.routeErrors.shift()}`);
+        if (action === 'route') {
+            const data = routeSchema.parse(input), key = this.key(data.name), context = this.web.getContext();
+            if (this.routes.has(key))
+                throw new Error('Route name already exists; remove it before replacing it.');
+            const responseFields = ['status', 'headers', 'json', 'body', 'fixture', 'contentType'];
+            if (['abort', 'continue'].includes(data.mode) && responseFields.some(key => key in data) || data.mode !== 'continue' && data.request !== undefined)
+                throw new Error('Route options do not apply to the selected mode.');
+            if (data.mode === 'abort' && data.request)
+                throw new Error('Abort routes cannot modify requests.');
+            if (data.mode === 'patch' && data.json !== undefined && (!data.json || typeof data.json !== 'object' || Array.isArray(data.json)))
+                throw new Error('Response patches require a JSON object.');
+            if ([data.json !== undefined, data.body !== undefined, data.fixture !== undefined].filter(Boolean).length > 1)
+                throw new Error('Choose one route body source.');
+            const body = data.fixture ? (0, validation_1.readProjectFile)(this.config, data.fixture) : data.body;
+            let remaining = data.times ?? Infinity;
+            const generation = this.generation;
+            const operation = async (route) => {
+                if (remaining <= 0 || data.method && route.request().method().toUpperCase() !== data.method.toUpperCase())
+                    return route.fallback();
+                if (--remaining === 0)
+                    this.routes.delete(key);
+                if (data.mode === 'abort')
+                    return route.abort();
+                if (data.mode === 'continue')
+                    return route.continue({ ...data.request, postData: data.request?.body, headers: data.request?.headers ? { ...route.request().headers(), ...data.request.headers } : undefined });
+                if (data.mode === 'patch') {
+                    const response = await route.fetch();
+                    const original = data.json === undefined ? undefined : await response.json();
+                    await route.fulfill({ response, status: data.status, headers: data.headers ? { ...response.headers(), ...data.headers } : undefined,
+                        ...(data.json === undefined ? { body } : { json: { ...original, ...data.json } }) });
+                }
+                else
+                    await route.fulfill({ status: data.status ?? 200, headers: data.headers, contentType: data.contentType,
+                        ...(data.json === undefined ? { body: body ?? '' } : { json: data.json }) });
+            };
+            const handler = async (route) => {
+                try {
+                    await operation(route);
+                    if (remaining === 0)
+                        await context.unroute(data.url, handler);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (generation === this.generation) {
+                        this.routeErrors.push(message);
+                        this.web.pageErrors.push(`Native route: ${message}`);
+                    }
+                    await route.abort().catch(() => { });
+                }
+            };
+            await context.route(data.url, handler);
+            this.routes.set(key, { context, pattern: data.url, handler });
+            return;
+        }
+        if (action === 'unroute') {
+            const data = zod_1.z.object({ name: validation_1.name }).strict().parse(input), key = this.key(data.name), route = this.routes.get(key);
+            if (!route)
+                throw new Error('Unknown route.');
+            await route.context.unroute(route.pattern, route.handler);
+            this.routes.delete(key);
+            return;
+        }
+        if (action === 'arm') {
+            const data = armSchema.parse(input), key = this.key(data.name), context = this.web.getContext();
+            if (data.kind === 'request' && data.status !== undefined)
+                throw new Error('A request event has no response status.');
+            if (this.events.has(key))
+                throw new Error('Event name already armed.');
+            const listener = (event) => {
+                const request = data.kind === 'request' ? event : event.request();
+                if (!matchesURL(data.url, request.url()) || data.method && request.method().toUpperCase() !== data.method.toUpperCase() || data.kind === 'response' && data.status !== undefined && event.status() !== data.status)
+                    return;
+                armed.capture(event);
+            };
+            const armed = new ArmedEvent(data.timeout ?? this.config.timeout, () => data.kind === 'request' ? context.off('request', listener) : context.off('response', listener));
+            if (data.kind === 'request')
+                context.on('request', listener);
+            else
+                context.on('response', listener);
+            this.events.set(key, armed);
+            return;
+        }
+        if (action === 'wait') {
+            const data = zod_1.z.object({ name: validation_1.name }).strict().parse(input), key = this.key(data.name), armed = this.events.get(key);
+            if (!armed)
+                throw new Error('Arm the network event before triggering its request.');
+            try {
+                const event = await armed.take(), response = typeof event.status === 'function' ? event : undefined;
+                const request = response ? response.request() : event;
+                let body = request.postData();
+                if (response) {
+                    const length = Number(response.headers()['content-length'] || 0);
+                    if (length > 20 * 1024 * 1024)
+                        throw new Error('Captured response exceeds the 20 MiB limit.');
+                    const content = await response.body();
+                    if (content.length > 20 * 1024 * 1024)
+                        throw new Error('Captured response exceeds the 20 MiB limit.');
+                    body = content.toString('utf8');
+                }
+                try {
+                    body = JSON.parse(String(body));
+                }
+                catch { }
+                const result = { url: request.url(), method: request.method(), status: response?.status(), headers: response ? await response.allHeaders() : await request.allHeaders(), body };
+                this.captured.set(key, result);
+                return result;
+            }
+            finally {
+                this.events.delete(key);
+            }
+        }
+        if (action === 'expect') {
+            const data = networkExpect.parse(input), result = this.captured.get(this.key(data.name));
+            if (!result)
+                throw new Error('No captured event; call network.wait first.');
+            if (!['status', 'method', 'equals', 'contains'].some(key => key in data))
+                throw new Error('Provide a network expectation.');
+            const checks = [];
+            if (data.status !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('status', 'status', result.status === data.status, data.status, result.status));
+            if (data.method)
+                checks.push((0, assertion_result_1.assertionCheck)('method', 'method', result.method === data.method.toUpperCase(), data.method.toUpperCase(), result.method));
+            let actual = data.header ? result.headers[data.header.toLowerCase()] : result.body;
+            if (data.path)
+                for (const key of data.path.split('.'))
+                    actual = actual?.[key];
+            const protect = (value) => /password|passcode|secret|token|authorization|cookie|api.?key|otp/i.test((data.header || '') + ' ' + (data.path || '')) ? '[REDACTED]' : value;
+            if ('equals' in data)
+                checks.push((0, assertion_result_1.assertionCheck)('equals', (data.header ? 'header ' + data.header : data.path ? 'body path ' + data.path : 'body') + ' equals', (0, node_util_1.isDeepStrictEqual)(actual, data.equals), protect(data.equals), protect(actual)));
+            if (data.contains !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('contains', 'content contains', String(actual).includes(data.contains), protect(data.contains), protect(actual)));
+            (0, assertion_result_1.requireAssertion)('network.expect', 'captured network event ' + JSON.stringify(data.name), checks, reporter, { reason: checks.some(check => check.status === 'failed' && ['status', 'method'].includes(check.key)) ? 'Network status/method assertion failed.' : checks.some(check => check.status === 'failed') ? 'Network content assertion failed.' : undefined });
+            return;
+        }
+        throw new Error(`Unknown network action: ${action}`);
+    }
+    async download(action, input, reporter) {
+        if (action === 'arm') {
+            const data = zod_1.z.object({ name: validation_1.name, timeout: validation_1.positive.optional() }).strict().parse(input), key = this.key(data.name), page = this.web.getPage();
+            if (this.downloads.has(key))
+                throw new Error('Download name already armed.');
+            const listener = (download) => armed.capture(download);
+            const armed = new ArmedEvent(data.timeout ?? this.config.timeout, () => page.off('download', listener));
+            page.on('download', listener);
+            this.downloads.set(key, armed);
+            return;
+        }
+        if (action === 'save') {
+            const data = zod_1.z.object({ name: validation_1.name, file: zod_1.z.string().min(1) }).strict().parse(input), key = this.key(data.name), armed = this.downloads.get(key);
+            if (!armed)
+                throw new Error('Arm the download before clicking its trigger.');
+            try {
+                const download = await armed.take();
+                const file = (0, projectPaths_1.projectPath)(this.config.projectRoot || process.cwd(), data.file);
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+                if (node_fs_1.default.existsSync(file))
+                    throw new Error('Download destination exists; choose a new file.');
+                await download.saveAs(file);
+                const failure = await download.failure();
+                if (failure)
+                    throw new Error(`Download failed: ${failure}`);
+                this.savedDownloads.set(key, { file, suggested: download.suggestedFilename() });
+                return file;
+            }
+            finally {
+                this.downloads.delete(key);
+            }
+        }
+        if (action === 'expect') {
+            const data = zod_1.z.object({ name: validation_1.name, filename: zod_1.z.string().optional(), size: zod_1.z.number().int().nonnegative().optional(), minSize: zod_1.z.number().int().nonnegative().optional(), contains: zod_1.z.string().optional(), sha256: zod_1.z.string().regex(/^[a-f0-9]{64}$/).optional(), json: zod_1.z.unknown().optional() }).strict().parse(input);
+            if (!['filename', 'size', 'minSize', 'contains', 'sha256', 'json'].some(key => key in data))
+                throw new Error('Provide a download expectation.');
+            const saved = this.savedDownloads.get(this.key(data.name));
+            if (!saved)
+                throw new Error('Download not saved.');
+            const absolute = (0, projectPaths_1.projectPath)(this.config.projectRoot || process.cwd(), saved.file), length = node_fs_1.default.statSync(absolute).size;
+            const body = data.contains !== undefined || 'json' in data ? (0, validation_1.readProjectFile)(this.config, saved.file) : Buffer.alloc(0);
+            let sha256;
+            if (data.sha256) {
+                const hash = (0, node_crypto_1.createHash)('sha256');
+                for await (const chunk of node_fs_1.default.createReadStream(absolute))
+                    hash.update(chunk);
+                sha256 = hash.digest('hex');
+            }
+            const checks = [];
+            if (data.filename !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('filename', 'filename', saved.suggested === data.filename, data.filename, saved.suggested));
+            if (data.size !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('size', 'size', length === data.size, data.size, length));
+            if (data.minSize !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('minSize', 'minimum size', length >= data.minSize, data.minSize, length));
+            if (data.contains !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('contains', 'content contains', body.toString('utf8').includes(data.contains), data.contains, body.toString('utf8')));
+            if (data.sha256 !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('sha256', 'SHA-256', sha256 === data.sha256, data.sha256, sha256));
+            if ('json' in data) {
+                try {
+                    const actual = JSON.parse(body.toString('utf8'));
+                    checks.push((0, assertion_result_1.assertionCheck)('json', 'JSON content', (0, node_util_1.isDeepStrictEqual)(actual, data.json), data.json, actual));
+                }
+                catch (error) {
+                    checks.push({ ...(0, assertion_result_1.assertionCheck)('json', 'JSON content', false, data.json, body.toString('utf8')), reason: 'Downloaded content is not valid JSON: ' + (0, assertion_result_1.diagnosticValue)(error instanceof Error ? error.message : String(error)) });
+                }
+            }
+            (0, assertion_result_1.requireAssertion)('download.expect', 'saved download ' + JSON.stringify(data.name), checks, reporter, { reason: checks.some(check => check.status === 'failed') ? 'Download assertion failed.' : undefined });
+            return;
+        }
+        throw new Error(`Unknown download action: ${action}`);
+    }
+    async disposeProfile(profile) {
+        const prefix = profile + ':';
+        for (const map of [this.events, this.downloads])
+            for (const [key, event] of map)
+                if (key.startsWith(prefix)) {
+                    event.fail(new Error('Profile closed.'));
+                    map.delete(key);
+                }
+        for (const map of [this.captured, this.savedDownloads])
+            for (const key of map.keys())
+                if (key.startsWith(prefix))
+                    map.delete(key);
+        for (const [key, route] of this.routes)
+            if (key.startsWith(prefix)) {
+                await route.context.unroute(route.pattern, route.handler).catch(() => { });
+                this.routes.delete(key);
+            }
+    }
+    async dispose() {
+        this.generation++;
+        for (const armed of [...this.events.values(), ...this.downloads.values()])
+            armed.fail(new Error('Event cancelled during cleanup.'));
+        this.events.clear();
+        this.downloads.clear();
+        this.captured.clear();
+        this.savedDownloads.clear();
+        for (const route of this.routes.values())
+            await route.context.unroute(route.pattern, route.handler).catch(() => { });
+        this.routes.clear();
+        this.routeErrors = [];
+    }
+}
+exports.NativeEvents = NativeEvents;

package/dist/native/evidence.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { FlowstrideConfig } from '../types';
+export declare function serveDOMSnapshot(req: IncomingMessage, res: ServerResponse, config?: FlowstrideConfig): boolean;

package/dist/native/evidence.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveDOMSnapshot = serveDOMSnapshot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const projectPaths_1 = require("../utils/projectPaths");
+function serveDOMSnapshot(req, res, config) {
+    const url = new URL(req.url || '/', `http://${req.headers.host}`);
+    if (url.pathname !== '/evidence')
+        return false;
+    try {
+        if (req.method !== 'GET' || !config?.domSnapshots)
+            throw new Error('Unavailable');
+        const root = config.projectRoot || process.cwd();
+        const file = (0, projectPaths_1.projectPath)(root, url.searchParams.get('file') || '');
+        const directory = (0, projectPaths_1.projectPath)(root, config.artifactsDir || 'flowstride-artifacts');
+        const relative = node_path_1.default.relative(directory, file);
+        if (!relative || relative.startsWith('..') || node_path_1.default.isAbsolute(relative) || !file.endsWith('.dom.html') || !node_fs_1.default.statSync(file).isFile() || node_fs_1.default.statSync(file).size > 10 * 1024 * 1024)
+            throw new Error('Unavailable');
+        res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; sandbox", 'Cache-Control': 'no-store' });
+        node_fs_1.default.createReadStream(file).pipe(res);
+    }
+    catch {
+        res.writeHead(404);
+        res.end('Snapshot unavailable.');
+    }
+    return true;
+}

package/dist/native/functions.d.ts

@@ -0,0 +1,10 @@
+import { type AssertionReporter } from '../reporting/assertion_result';
+import type { Page } from 'playwright';
+export declare class NativeFunctions {
+    private installed;
+    private pages;
+    private counter;
+    private key;
+    execute(page: Page, action: string, input: unknown, timeout: number, reporter?: AssertionReporter): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/native/functions.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeFunctions = void 0;
+const assertion_result_1 = require("../reporting/assertion_result");
+const zod_1 = require("zod");
+const validation_1 = require("./validation");
+const node_util_1 = require("node:util");
+const target = zod_1.z.string().min(1).refine(value => value.split('.').every(key => /^[a-zA-Z_$][\w$]*$/.test(key) && !['__proto__', 'prototype', 'constructor'].includes(key)), 'Use a safe dotted function path.');
+const schema = zod_1.z.object({ name: validation_1.name, target, mode: zod_1.z.enum(['spy', 'return', 'throw']).default('spy'), value: zod_1.z.unknown().optional(), error: zod_1.z.string().optional(), async: zod_1.z.boolean().default(false), beforeLoad: zod_1.z.boolean().default(false) }).strict();
+function install(data) {
+    const symbol = Symbol.for('flowstride.function-doubles');
+    const registry = window[symbol] ||= Object.create(null);
+    if (registry[data.name])
+        throw new Error('Function double name already exists.');
+    const keys = data.target.replace(/^window\./, '').split('.');
+    let object = window;
+    for (const key of keys.slice(0, -1))
+        object = object[key];
+    const key = keys.at(-1), original = object[key], own = Object.getOwnPropertyDescriptor(object, key);
+    if (typeof original !== 'function')
+        throw new Error(`Target is not a function: ${data.target}`);
+    const calls = [];
+    const replacement = function (...args) {
+        let snapshot;
+        try {
+            snapshot = JSON.parse(JSON.stringify(args));
+        }
+        catch {
+            snapshot = args.map(value => String(value));
+        }
+        calls.push(snapshot);
+        if (data.mode === 'spy')
+            return original.apply(this, args);
+        if (data.mode === 'throw') {
+            const error = new Error(data.error || 'Stubbed function error');
+            if (data.async)
+                return Promise.reject(error);
+            throw error;
+        }
+        return data.async ? Promise.resolve(data.value) : data.value;
+    };
+    Object.defineProperty(object, key, { configurable: true, writable: true, value: replacement });
+    registry[data.name] = { calls, restore: () => { if (own)
+            Object.defineProperty(object, key, own);
+        else
+            delete object[key]; } };
+}
+class NativeFunctions {
+    installed = new Map();
+    pages = new WeakMap();
+    counter = 0;
+    key(page, name) { if (!this.pages.has(page))
+        this.pages.set(page, ++this.counter); return `${this.pages.get(page)}:${name}`; }
+    async execute(page, action, input, timeout, reporter) {
+        if (action === 'install') {
+            const data = schema.parse(input);
+            if (this.installed.has(this.key(page, data.name)))
+                throw new Error('Function double name already exists; restore it first.');
+            const script = data.beforeLoad ? await page.addInitScript(install, data) : undefined;
+            try {
+                if (!data.beforeLoad || page.url() !== 'about:blank')
+                    await page.evaluate(install, data);
+            }
+            catch (error) {
+                await script?.dispose();
+                throw error;
+            }
+            this.installed.set(this.key(page, data.name), { name: data.name, target: data.target, page, script });
+            return;
+        }
+        if (action === 'restore') {
+            const data = zod_1.z.object({ name: validation_1.name }).strict().parse(input), entry = this.installed.get(this.key(page, data.name));
+            if (!entry || entry.page !== page)
+                throw new Error('Unknown function double on this page.');
+            await entry.script?.dispose();
+            await page.evaluate(name => { const registry = window[Symbol.for('flowstride.function-doubles')]; registry?.[name]?.restore(); if (registry)
+                delete registry[name]; }, data.name);
+            this.installed.delete(this.key(page, data.name));
+            return;
+        }
+        if (action === 'expect') {
+            const data = zod_1.z.object({ name: validation_1.name, count: zod_1.z.number().int().nonnegative().optional(), minCount: zod_1.z.number().int().nonnegative().optional(), args: zod_1.z.array(zod_1.z.unknown()).optional(), timeout: validation_1.positive.optional() }).strict().parse(input);
+            if (!['count', 'minCount', 'args'].some(key => key in data))
+                throw new Error('Provide a call count or expected arguments.');
+            const started = Date.now(), limit = data.timeout ?? timeout;
+            const sensitive = /auth|login|password|passcode|secret|token|cookie|api.?key|otp/i.test(this.installed.get(this.key(page, data.name))?.target || data.name);
+            let latest = (0, assertion_result_1.reportAssertion)('stub.expect', 'function double ' + JSON.stringify(data.name), [{ key: 'calls', label: 'Recorded calls available', status: 'running' }], reporter, { status: 'running', timeout: limit, elapsed: 0 });
+            let closed = false;
+            try {
+                await (0, validation_1.poll)(async () => {
+                    const calls = await page.evaluate(name => window[Symbol.for('flowstride.function-doubles')]?.[name]?.calls, data.name);
+                    const checks = [(0, assertion_result_1.assertionCheck)('calls', 'Recorded calls available', Array.isArray(calls), 'recorded calls', Array.isArray(calls) ? calls.length : 'No function double found on this page')];
+                    if (Array.isArray(calls)) {
+                        if (data.count !== undefined)
+                            checks.push((0, assertion_result_1.assertionCheck)('count', 'call count', calls.length === data.count, data.count, calls.length));
+                        if (data.minCount !== undefined)
+                            checks.push((0, assertion_result_1.assertionCheck)('minCount', 'minimum call count', calls.length >= data.minCount, data.minCount, calls.length));
+                        if (data.args !== undefined)
+                            checks.push((0, assertion_result_1.assertionCheck)('args', 'matching call arguments', calls.some(call => (0, node_util_1.isDeepStrictEqual)(call, data.args)), sensitive ? "[REDACTED]" : data.args, sensitive ? "[REDACTED]" : calls));
+                    }
+                    if (!closed)
+                        latest = (0, assertion_result_1.reportAssertion)('stub.expect', 'function double ' + JSON.stringify(data.name), checks, reporter, { status: 'running', timeout: limit, elapsed: Date.now() - started });
+                    return checks.every(check => check.status === 'passed');
+                }, limit, `function double ${data.name}`);
+                closed = true;
+                reporter?.({ ...latest, status: 'passed', elapsed: Date.now() - started });
+            }
+            catch (error) {
+                closed = true;
+                const result = { ...latest, status: 'failed', elapsed: Date.now() - started, reason: (0, assertion_result_1.diagnosticValue)(error instanceof Error ? error.message : String(error)) };
+                if (!result.checks.some(check => check.status === 'failed'))
+                    result.checks.push({ key: 'read', label: 'Recorded calls could be read', status: 'failed', reason: result.reason });
+                reporter?.(result);
+                throw new assertion_result_1.AssertionFailure(result);
+            }
+            return;
+        }
+        throw new Error(`Unknown stub action: ${action}`);
+    }
+    async dispose() {
+        for (const entry of this.installed.values()) {
+            const name = entry.name;
+            await entry.script?.dispose().catch(() => { });
+            if (!entry.page.isClosed())
+                await entry.page.evaluate(name => { const registry = window[Symbol.for('flowstride.function-doubles')]; registry?.[name]?.restore(); if (registry)
+                    delete registry[name]; }, name).catch(() => { });
+        }
+        this.installed.clear();
+    }
+}
+exports.NativeFunctions = NativeFunctions;

package/dist/native/runtime.d.ts

@@ -0,0 +1,17 @@
+import type { AssertionResult } from '../reporting/assertion_result';
+import type { FlowstrideConfig } from '../types';
+import { WebAdapter } from '../adapters/web/playwright';
+import { NativeEvents } from './events';
+export declare class NativeRuntime {
+    private web;
+    private config;
+    readonly events: NativeEvents;
+    lastAssertion?: AssertionResult;
+    private assertionGeneration;
+    private functions;
+    private components;
+    constructor(web: WebAdapter, config: FlowstrideConfig);
+    execute(command: string, input?: unknown): Promise<unknown>;
+    captureDOM(step: string): Promise<string | undefined>;
+    dispose(): Promise<void>;
+}