flowstride 1.0.20-rc.6 → 1.0.21

package/dist/adapters/web/playwright.js

@@ -37,21 +37,194 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebAdapter = void 0;
-const projectPaths_1 = require("../../utils/projectPaths");
+const validation_1 = require("../../native/validation");
 const playwright_1 = require("playwright");
+const projectPaths_1 = require("../../utils/projectPaths");
+const playwright_2 = require("playwright");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const playwright_extra_1 = require("playwright-extra");
 const puppeteer_extra_plugin_stealth_1 = __importDefault(require("puppeteer-extra-plugin-stealth"));
-playwright_extra_1.chromium.use((0, puppeteer_extra_plugin_stealth_1.default)());
+const chromium = (0, playwright_extra_1.addExtra)(playwright_1.chromium);
+chromium.use((0, puppeteer_extra_plugin_stealth_1.default)());
 class WebAdapter {
     config;
+    activeProfile = 'default';
+    profiles = new Map();
+    contextOptions = {};
+    onPageChanged;
+    profileNames() { return [...this.profiles.keys()]; }
+    getContext() { if (!this.context)
+        throw new Error('Browser not initialised'); return this.context; }
+    async createProfile(profileName, options = {}) {
+        const key = validation_1.name.parse(profileName);
+        if (this.profiles.has(key))
+            throw new Error(`Browser profile already exists: ${key}`);
+        if (!this.browser)
+            throw new Error('Browser not initialised');
+        const { storageState: _defaultAuthentication, ...inherited } = this.contextOptions;
+        const settings = { ...inherited, ...(0, validation_1.validateContextOptions)(options, this.config.browser, this.config.projectRoot) };
+        if (this.config.har)
+            settings.recordHar = { path: (0, validation_1.evidencePath)(this.config, `${key}-${Date.now()}.har`), content: 'embed', mode: 'full' };
+        const context = await this.browser.newContext(settings);
+        context.setDefaultTimeout(this.config.timeout);
+        context.on('page', page => page.on('pageerror', error => this.pageErrors.push(error.message)));
+        context.on('dialog', async (dialog) => { if (this.dialogHandler)
+            await this.dialogHandler(dialog);
+        else if (this.config.defaultDialogBehavior === 'accept')
+            await dialog.accept().catch(() => { });
+        else
+            await dialog.dismiss().catch(() => { }); });
+        try {
+            const page = await context.newPage();
+            this.profiles.set(key, { context, page, options: settings, tracing: false });
+            if (this.config.trace)
+                await this.beginTrace(key);
+            await this.useProfile(key);
+        }
+        catch (error) {
+            await context.close();
+            this.profiles.delete(key);
+            throw error;
+        }
+    }
+    async useProfile(profileName) {
+        const profile = this.profiles.get(profileName);
+        if (!profile || profile.page.isClosed())
+            throw new Error(`Browser profile is not available: ${profileName}`);
+        const previous = this.profiles.get(this.activeProfile);
+        if (previous && this.page && !this.page.isClosed() && this.context === previous.context)
+            previous.page = this.page;
+        // Initializers belong to their own page, even while another profile is active.
+        this.context = profile.context;
+        this.page = profile.page;
+        this.activeProfile = profileName;
+        await this.page.bringToFront();
+        await this.onPageChanged?.();
+    }
+    async closeProfile(profileName) {
+        if (profileName === 'default')
+            throw new Error('The default profile remains available until file completion.');
+        const profile = this.profiles.get(profileName);
+        if (!profile)
+            throw new Error(`Unknown profile: ${profileName}`);
+        await this.finishProfile(profileName);
+        this.profiles.delete(profileName);
+        if (this.activeProfile === profileName)
+            await this.useProfile('default');
+    }
+    async beginTrace(profileName = this.activeProfile, file) {
+        const profile = this.profiles.get(profileName);
+        if (!profile || profile.tracing)
+            throw new Error('Profile missing or already tracing.');
+        await profile.context.tracing.start({ screenshots: true, snapshots: true, sources: false });
+        profile.tracing = true;
+        profile.tracePath = (0, validation_1.evidencePath)(this.config, file || `${profileName}-${Date.now()}-trace.zip`);
+    }
+    async endTrace(profileName = this.activeProfile) {
+        const profile = this.profiles.get(profileName);
+        if (!profile?.tracing || !profile.tracePath)
+            throw new Error('Trace is not active.');
+        await profile.context.tracing.stop({ path: profile.tracePath });
+        profile.tracing = false;
+        return profile.tracePath;
+    }
+    async finishProfile(key, videoTargetPath) {
+        const profile = this.profiles.get(key);
+        if (!profile)
+            return;
+        await this.clearSessionStorageRestore(profile.page);
+        if (profile.tracing)
+            await this.endTrace(key);
+        const video = profile.page.video();
+        await profile.context.close();
+        if (video) {
+            const target = videoTargetPath || (key !== 'default' ? (0, validation_1.evidencePath)(this.config, `${key}-${Date.now()}.webm`) : undefined);
+            if (target)
+                await video.saveAs(target);
+        }
+    }
+    async checkpointProfiles() {
+        const result = { active: this.activeProfile, dialogHandler: this.dialogHandler, profiles: [] };
+        const current = this.profiles.get(this.activeProfile);
+        if (current && this.page)
+            current.page = this.page;
+        for (const [key, profile] of this.profiles) {
+            const pages = [];
+            for (const page of profile.context.pages())
+                pages.push({ url: page.url(), active: page === profile.page,
+                    sessionStorage: await page.evaluate(() => ({ ...window.sessionStorage })).catch(() => ({})) });
+            result.profiles.push({ key, options: profile.options, storageState: await profile.context.storageState({ indexedDB: true }), pages });
+        }
+        return result;
+    }
+    async restoreProfiles(snapshot) {
+        await this.clearSessionStorageRestore();
+        for (const [key] of this.profiles)
+            await this.finishProfile(key, (0, validation_1.evidencePath)(this.config, `${key}-${Date.now()}-attempt.webm`));
+        this.profiles.clear();
+        this.dialogHandler = snapshot.dialogHandler;
+        for (const saved of snapshot.profiles) {
+            const context = await this.browser.newContext({ ...saved.options, storageState: saved.storageState,
+                ...(this.config.har ? { recordHar: { path: (0, validation_1.evidencePath)(this.config, `${saved.key}-${Date.now()}-retry.har`), content: 'embed' } } : {}) });
+            context.setDefaultTimeout(this.config.timeout);
+            context.on('page', page => page.on('pageerror', error => this.pageErrors.push(error.message)));
+            context.on('dialog', async (dialog) => { if (this.dialogHandler)
+                await this.dialogHandler(dialog);
+            else if (this.config.defaultDialogBehavior === 'accept')
+                await dialog.accept().catch(() => { });
+            else
+                await dialog.dismiss().catch(() => { }); });
+            let selected;
+            for (const tab of saved.pages) {
+                const page = await context.newPage();
+                if (tab.active || !selected)
+                    selected = page;
+                if (/^https?:/.test(tab.url)) {
+                    const origin = new URL(tab.url).origin;
+                    const seed = await page.addInitScript(({ origin, values }) => { if (window === window.top && location.origin === origin)
+                        for (const [key, value] of Object.entries(values))
+                            sessionStorage.setItem(key, String(value)); }, { origin, values: tab.sessionStorage });
+                    try {
+                        await page.goto(tab.url, { waitUntil: 'domcontentloaded' });
+                    }
+                    finally {
+                        await seed.dispose();
+                    }
+                }
+            }
+            selected ||= await context.newPage();
+            this.profiles.set(saved.key, { context, page: selected, options: saved.options, tracing: false });
+            if (this.config.trace)
+                await this.beginTrace(saved.key);
+        }
+        this.context = null;
+        this.page = null;
+        await this.useProfile(snapshot.active);
+    }
     pageErrors = [];
     browser = null;
     context = null;
     page = null;
     discoveredPages = [];
     dialogHandler = null;
+    sessionStorageRestores = new Map();
+    get pendingSessionStorageRestore() { return this.sessionStorageRestores.values().next().value || null; }
+    async clearSessionStorageRestore(target) {
+        for (const [page, pending] of this.sessionStorageRestores) {
+            if (target && page !== target)
+                continue;
+            this.sessionStorageRestores.delete(page);
+            pending.page.off('framenavigated', pending.onNavigation);
+            try {
+                await pending.script.dispose();
+            }
+            catch (error) {
+                if (!pending.page.isClosed())
+                    throw error;
+            }
+        }
+    }
     constructor(config) {
         this.config = config;
     }
@@ -60,7 +233,13 @@ class WebAdapter {
             throw new Error("Browser not initialised");
         return this.page;
     }
+    getBrowserInfo() {
+        if (!this.browser)
+            throw new Error('Browser not initialised');
+        return { engine: this.browser.browserType().name(), version: this.browser.version(), headless: !!this.config.headless };
+    }
     async initialise(audioInjectionPath) {
+        await this.clearSessionStorageRestore();
         const launchArgs = this.config.headless
             ? [
                 "--use-fake-ui-for-media-stream",
@@ -76,23 +255,48 @@ class WebAdapter {
         if (audioInjectionPath) {
             launchArgs.push(`--use-file-for-fake-audio-capture=${audioInjectionPath}`);
         }
-        this.browser = await playwright_extra_1.chromium.launch({
+        let engine = this.config.browser === 'firefox' ? playwright_1.firefox : this.config.browser === 'webkit' ? playwright_1.webkit : chromium;
+        if ((!this.config.browser || this.config.browser === 'chromium') && this.config.browserOptions?.userAgent) {
+            const configuredChromium = (0, playwright_extra_1.addExtra)(playwright_1.chromium);
+            const stealth = (0, puppeteer_extra_plugin_stealth_1.default)();
+            stealth.enabledEvasions.delete('user-agent-override');
+            configuredChromium.use(stealth);
+            engine = configuredChromium;
+        }
+        if (audioInjectionPath && this.config.browser && this.config.browser !== 'chromium')
+            throw new Error('Audio file injection requires Chromium.');
+        this.profiles.clear();
+        this.activeProfile = 'default';
+        this.discoveredPages = [];
+        this.dialogHandler = null;
+        this.browser = await engine.launch({
             headless: this.config.headless,
             // Native CI finalizes videos before closing the browser on cancellation.
             ...(this.config.ci ? { handleSIGINT: false, handleSIGTERM: false } : {}),
-            args: launchArgs,
+            args: !this.config.browser || this.config.browser === 'chromium' ? launchArgs : [],
         });
+        if (this.browser.browserType().name() !== (this.config.browser || 'chromium')) {
+            await this.browser.close();
+            this.browser = null;
+            throw new Error('The launched browser does not match the requested browser.');
+        }
         const videoDir = (0, projectPaths_1.projectPath)(process.cwd(), path.join('.flowstride', 'videos'));
         if (!fs.existsSync(videoDir))
             fs.mkdirSync(videoDir, { recursive: true });
         const profile = this.config.device === 'phone' || this.config.device === 'landscape'
-            ? { ...playwright_1.devices['Pixel 7'], viewport: this.config.device === 'landscape' ? { width: 844, height: 390 } : { width: 390, height: 844 } }
+            ? { ...playwright_2.devices['Pixel 7'], viewport: this.config.device === 'landscape' ? { width: 844, height: 390 } : { width: 390, height: 844 } }
             : { viewport: { width: 1280, height: 800 }, userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' };
+        if (this.config.browser && this.config.browser !== 'chromium')
+            delete profile.userAgent;
         const viewport = this.config.viewport || profile.viewport;
-        this.context = await this.browser.newContext({
+        this.contextOptions = {
             ...profile, viewport,
+            ...(this.config.browser === 'firefox' ? { isMobile: false } : {}),
+            ...(0, validation_1.validateContextOptions)(this.config.browserOptions, this.config.browser, this.config.projectRoot),
             ...(this.config.recordVideo === false ? {} : { recordVideo: { dir: videoDir, size: viewport } }),
-        });
+        };
+        this.context = await this.browser.newContext({ ...this.contextOptions,
+            ...(this.config.har ? { recordHar: { path: (0, validation_1.evidencePath)(this.config, `default-${Date.now()}.har`), content: 'embed', mode: 'full' } } : {}) });
         this.pageErrors = [];
         this.context.on('page', page => page.on('pageerror', error => this.pageErrors.push(error.message)));
         this.context.on("dialog", async (dialog) => {
@@ -114,6 +318,9 @@ class WebAdapter {
         });
         this.page = await this.context.newPage();
         this.page.setDefaultTimeout(this.config.timeout);
+        this.profiles.set('default', { context: this.context, page: this.page, options: this.contextOptions, tracing: false });
+        if (this.config.trace)
+            await this.beginTrace();
     }
     async acceptDialog() {
         this.dialogHandler = async (dialog) => {
@@ -183,9 +390,26 @@ class WebAdapter {
         await this.page.bringToFront();
         await this.page.waitForLoadState("domcontentloaded").catch(() => { });
     }
-    async injectStorage(cookies, localStorage, fallbackDomain) {
+    async injectStorage(cookies, localStorage, fallbackDomain, sessionStorage, storageOrigin) {
         if (!this.context || !this.page)
             return;
+        await this.clearSessionStorageRestore(this.page);
+        const page = this.page;
+        const originOf = (value) => {
+            try {
+                const url = new URL(value || '');
+                return ['http:', 'https:'].includes(url.protocol) ? url.origin : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const hasSessionStorage = !!sessionStorage && Object.keys(sessionStorage).length > 0;
+        const origin = storageOrigin !== undefined ? originOf(storageOrigin)
+            : originOf(page.url()) || originOf(this.config.baseUrl);
+        if (hasSessionStorage && !origin) {
+            throw new Error('Session storage restoration requires a saved HTTP(S) origin, an open application page, or baseUrl.');
+        }
         if (cookies && cookies.length > 0) {
             const formattedCookies = [];
             for (const cookie of cookies) {
@@ -232,6 +456,32 @@ class WebAdapter {
                 }, localStorage);
             }
         }
+        if (hasSessionStorage) {
+            const restore = (data) => {
+                if (window !== window.top || window.location.origin !== data.origin)
+                    return;
+                for (const [key, value] of Object.entries(data.values))
+                    window.sessionStorage.setItem(key, value);
+            };
+            const data = { origin: origin, values: sessionStorage };
+            if (originOf(page.url()) === origin) {
+                await page.evaluate(restore, data);
+            }
+            else {
+                // Seed before application scripts run; remove the seed after the first
+                // matching document so reloads preserve later application changes.
+                const script = await page.addInitScript(restore, data);
+                const onNavigation = (frame) => {
+                    if (frame !== page.mainFrame() || originOf(frame.url()) !== origin)
+                        return;
+                    void this.clearSessionStorageRestore(page).catch(() => {
+                        console.warn('[Session]: Could not remove the completed session storage initializer.');
+                    });
+                };
+                this.sessionStorageRestores.set(page, { page, script, onNavigation });
+                page.on('framenavigated', onNavigation);
+            }
+        }
     }
     async getState() {
         const cookies = (await this.context?.cookies()) || [];
@@ -250,7 +500,14 @@ class WebAdapter {
                 console.warn("Warning: Could not access storage. Ensure page is loaded.");
             }
         }
-        return { cookies, localStorage, sessionStorage };
+        let storageOrigin;
+        try {
+            const url = new URL(this.page?.url() || '');
+            if (['http:', 'https:'].includes(url.protocol))
+                storageOrigin = url.origin;
+        }
+        catch { }
+        return { cookies, localStorage, sessionStorage, storageOrigin };
     }
     getCurrentUrl() {
         return this.page ? this.page.url() : "about:blank";
@@ -1195,23 +1452,30 @@ class WebAdapter {
         }, { id, text, status, error });
     }
     async shutdown(videoTargetPath) {
+        const failures = [];
         try {
-            const video = this.page?.video();
-            if (this.context) {
-                await this.context.close();
-            }
-            if (video && videoTargetPath) {
-                await video.saveAs(videoTargetPath);
+            await this.clearSessionStorageRestore();
+            const active = this.profiles.get(this.activeProfile);
+            if (active && this.page)
+                active.page = this.page;
+            for (const [key] of this.profiles) {
+                try {
+                    await this.finishProfile(key, key === 'default' ? videoTargetPath : undefined);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
             }
         }
-        catch (err) {
-            console.warn("[WebAdapter]: Warning during browser shutdown or video transfer.");
-        }
         finally {
-            if (this.browser) {
-                await this.browser.close().catch(() => { });
-            }
+            await this.browser?.close().catch(error => failures.push(error));
+            this.profiles.clear();
+            this.context = null;
+            this.page = null;
+            this.browser = null;
         }
+        if (failures.length)
+            throw new AggregateError(failures, 'Browser evidence finalization failed.');
     }
 }
 exports.WebAdapter = WebAdapter;

package/dist/ci/config.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCIEnvironment = isCIEnvironment;
 exports.loadNativeConfig = loadNativeConfig;
+const distribution_1 = require("./distribution");
+const validation_1 = require("../native/validation");
 const projectPaths_1 = require("../utils/projectPaths");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -22,13 +24,24 @@ function loadNativeConfig(root, options) {
     }
     else if (options.config)
         throw new Error(`Configuration not found: ${file}`);
-    const config = { ...input, projectRoot: node_path_1.default.resolve(root), timeout: input.timeout ?? 30000, headless: input.headless ?? true,
+    const config = { ...input, browser: options.browser ?? input.browser ?? "chromium", retries: input.retries ?? 0, shard: options.shard ?? input.shard, shardHistory: options.shardHistory ?? input.shardHistory, updateBaselines: !!options.updateBaselines, projectRoot: node_path_1.default.resolve(root), timeout: input.timeout ?? 30000, headless: input.headless ?? true,
         ci: !!options.ci || isCIEnvironment(), bail: options.bail || input.bail || false, device: options.device ?? input.device ?? 'desktop',
         artifactsDir: input.artifactsDir ?? 'flowstride-artifacts', testDir: input.testDir ?? 'flows',
         defaultDialogBehavior: input.defaultDialogBehavior ?? 'dismiss',
         recordVideo: input.recordVideo ?? true, browserErrors: input.browserErrors ?? 'fail',
         isCloudSyncActive: options.isCloudSyncActive ?? false, machineToken: options.machineToken ?? null,
         workspaceId: options.workspaceId ?? null, manifest: options.manifest ?? null };
+    if (!['chromium', 'firefox', 'webkit'].includes(config.browser))
+        throw new Error('browser must be chromium, firefox, or webkit.');
+    config.browserOptions = (0, validation_1.validateContextOptions)(input.browserOptions, config.browser, root);
+    if (!Number.isSafeInteger(config.retries) || config.retries < 0 || config.retries > 10)
+        throw new Error('retries must be an integer from 0 to 10.');
+    for (const key of ['trace', 'har', 'domSnapshots', 'failOnFlaky'])
+        if (config[key] !== undefined && typeof config[key] !== 'boolean')
+            throw new Error(`${key} must be boolean.`);
+    (0, distribution_1.parseShard)(config.shard);
+    if (config.ci && config.updateBaselines)
+        throw new Error('Baseline updates are not allowed in CI.');
     if (config.ci && input.cloudSync !== true)
         config.isCloudSyncActive = false;
     if (options.headless || config.ci)

package/dist/ci/distribution.d.ts

@@ -0,0 +1,38 @@
+import type { FlowstrideConfig } from '../types';
+export declare function parseShard(value?: string): {
+    index: number;
+    total: number;
+};
+export declare function executionPlan(target: string, config?: FlowstrideConfig): {
+    files: string[];
+    allFiles: string[];
+    setupFiles: string[];
+    suiteHash: string;
+    configHash: string;
+    shard: {
+        index: number;
+        total: number;
+    };
+    flowRoot: string;
+};
+export declare function mergeResults(summaries: string[], output?: string): {
+    protocol: number;
+    engine: any;
+    browser: any;
+    browsers: any[];
+    status: string;
+    metrics: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        incomplete: number;
+    };
+    steps: any[];
+    attempts: any[];
+    errors: string[];
+    timings: Record<string, number>;
+    files: string[];
+    duration: number;
+    distribution: any;
+};

package/dist/ci/distribution.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseShard = parseShard;
+exports.executionPlan = executionPlan;
+exports.mergeResults = mergeResults;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const projectPaths_1 = require("../utils/projectPaths");
+function parseShard(value) {
+    if (value === undefined)
+        return { index: 1, total: 1 };
+    const match = /^(\d+)\/(\d+)$/.exec(value);
+    if (!match)
+        throw new Error('shard must be index/total, e.g. 1/4.');
+    const index = Number(match[1]), total = Number(match[2]);
+    if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || index < 1 || index > total || total > 256)
+        throw new Error('Shard index must be between 1 and total (maximum 256).');
+    return { index, total };
+}
+function executionPlan(target, config) {
+    const root = config?.projectRoot || process.cwd(), files = (0, projectPaths_1.discoverFlows)(target, root);
+    const flowRoot = node_fs_1.default.statSync(target).isDirectory() ? target : node_path_1.default.dirname(target);
+    const shard = parseShard(config?.shard);
+    const identity = (file) => (0, projectPaths_1.flowIdentity)(file, flowRoot);
+    const suiteHash = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(files.map(file => [identity(file), (0, node_crypto_1.createHash)('sha256').update(node_fs_1.default.readFileSync(file)).digest('hex')]))).digest('hex');
+    // Configuration affects compatibility, but only a hash leaves this process.
+    const configHash = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify([require('../../package.json').name, require('../../package.json').version, config?.browser || 'chromium', config?.device || 'desktop', config?.browserOptions || {}, config?.retries || 0, config?.baseUrl || '', config?.timeout || 30000, config?.headless, config?.browserErrors, config?.failOnFlaky, config?.recordVideo, config?.trace, config?.har])).digest('hex');
+    let history = {};
+    if (config?.shardHistory) {
+        history = JSON.parse(node_fs_1.default.readFileSync((0, projectPaths_1.projectPath)(root, config.shardHistory), 'utf8'));
+        if (!history || Array.isArray(history) || typeof history !== 'object' || Object.values(history).some(value => typeof value !== 'number' || !Number.isFinite(value) || value < 0))
+            throw new Error('Shard history must map file names to nonnegative durations.');
+    }
+    const setup = files.filter(file => file.endsWith('.first.flow'));
+    const standard = files.filter(file => !file.endsWith('.first.flow'));
+    const bins = Array.from({ length: shard.total }, () => []), weights = bins.map(() => 0);
+    for (const file of [...standard].sort((a, b) => (history[identity(b)] ?? 1) - (history[identity(a)] ?? 1) || identity(a).localeCompare(identity(b)))) {
+        const index = weights.indexOf(Math.min(...weights));
+        bins[index].push(file);
+        weights[index] += history[identity(file)] ?? 1;
+    }
+    const assigned = new Set([...setup, ...bins[shard.index - 1]]);
+    return { files: files.filter(file => assigned.has(file)), allFiles: files.map(identity), setupFiles: setup.map(identity), suiteHash, configHash, shard, flowRoot };
+}
+function mergeResults(summaries, output = 'flowstride-merged') {
+    const root = process.cwd(), out = (0, projectPaths_1.projectPath)(root, output);
+    if (node_fs_1.default.existsSync(out))
+        throw new Error('Merge output already exists; choose a new directory.');
+    if (!summaries.length)
+        throw new Error('Provide one summary per shard.');
+    const inputs = summaries.map(file => { const absolute = (0, projectPaths_1.projectPath)(root, file); return { file: absolute, report: JSON.parse(node_fs_1.default.readFileSync(absolute, 'utf8')) }; });
+    const first = inputs[0].report;
+    if (first.protocol !== 1 || !first.distribution?.suiteHash)
+        throw new Error('Only native distributed reports can be merged.');
+    const total = first.distribution.shard.total, seen = new Set(), seenFiles = new Set(), setup = new Set(first.distribution.setupFiles);
+    const errors = [], steps = [], attempts = [], timings = {};
+    for (const { report } of inputs) {
+        const dist = report.distribution;
+        if (report.protocol !== 1 || report.engine !== first.engine || !dist || dist.suiteHash !== first.distribution.suiteHash || dist.configHash !== first.distribution.configHash || dist.shard.total !== total || JSON.stringify(dist.allFiles) !== JSON.stringify(first.distribution.allFiles) || JSON.stringify(dist.setupFiles) !== JSON.stringify(first.distribution.setupFiles))
+            throw new Error('Shards belong to different suites or browser configurations.');
+        const { index } = parseShard(`${dist.shard.index}/${dist.shard.total}`);
+        if (seen.has(index))
+            throw new Error('Duplicate shard.');
+        seen.add(index);
+        if (!['passed', 'failed', 'interrupted'].includes(report.status) || !Array.isArray(report.steps) || !Array.isArray(report.files) || !Array.isArray(report.errors))
+            throw new Error('Invalid shard report.');
+        if (!report.metrics || ['total', 'passed', 'failed', 'skipped', 'incomplete'].some(key => !Number.isSafeInteger(report.metrics[key]) || report.metrics[key] < 0) || report.metrics.passed + report.metrics.failed + report.metrics.skipped + report.metrics.incomplete !== report.metrics.total)
+            throw new Error('Inconsistent shard metrics.');
+        if (report.status === 'passed' && (report.errors.length || report.metrics.failed || report.metrics.incomplete || report.steps.some((step) => !['passed', 'skipped', 'not_tested'].includes(step.status))))
+            throw new Error('A passing shard contains failures or unfinished work.');
+        const duplicateSetup = new Set();
+        for (const file of report.files) {
+            if (!dist.allFiles.includes(file))
+                throw new Error('Unexpected file in shard.');
+            if (seenFiles.has(file)) {
+                if (!setup.has(file))
+                    throw new Error('File appears in more than one shard.');
+                duplicateSetup.add(file);
+            }
+            seenFiles.add(file);
+        }
+        for (const step of report.steps)
+            steps.push({ ...step, shard: index });
+        attempts.push(...(report.attempts || []).map((attempt) => ({ ...attempt, shard: index })));
+        errors.push(...report.errors.map((error) => `Shard ${index}: ${error}`));
+        for (const [file, duration] of Object.entries(report.timings || {}))
+            if (typeof duration === 'number' && duration >= 0)
+                timings[file] = Math.max(timings[file] || 0, duration);
+    }
+    if (seen.size !== total)
+        throw new Error(`Missing shards: expected ${total}, received ${seen.size}.`);
+    if (first.distribution.allFiles.some((file) => !seenFiles.has(file)))
+        throw new Error('Merged reports omit test files.');
+    const statuses = inputs.map(input => input.report.status), status = statuses.includes('interrupted') ? 'interrupted' : statuses.includes('failed') || errors.length ? 'failed' : 'passed';
+    const metrics = inputs.reduce((all, { report }) => { for (const key of ['total', 'passed', 'failed', 'skipped', 'incomplete']) {
+        const n = report.metrics?.[key];
+        if (!Number.isSafeInteger(n) || n < 0)
+            throw new Error('Invalid shard metrics.');
+        all[key] += n;
+    } return all; }, { total: 0, passed: 0, failed: 0, skipped: 0, incomplete: 0 });
+    // Preserve shard-level metrics (setup executes independently on each machine).
+    const merged = { protocol: 1, engine: first.engine, browser: first.browser, browsers: inputs.flatMap(({ report }) => (report.browsers || []).map((info) => ({ ...info, shard: report.distribution.shard.index }))), status, metrics, steps, attempts, errors, timings, files: [...seenFiles], duration: Math.max(...inputs.map(input => input.report.duration)), distribution: { ...first.distribution, merged: true, setupRunsPerShard: true } };
+    node_fs_1.default.mkdirSync(out, { recursive: true, mode: 0o700 });
+    try {
+        for (const { file, report } of inputs) {
+            const source = (0, projectPaths_1.projectPath)(root, node_path_1.default.join(node_path_1.default.dirname(file), node_path_1.default.basename(report.artifactsDir || '')));
+            if (!node_fs_1.default.existsSync(source) || !node_fs_1.default.statSync(source).isDirectory())
+                throw new Error('Shard evidence directory is missing. Preserve each summary alongside its run directory.');
+            const destination = node_path_1.default.join(out, `shard-${report.distribution.shard.index}`);
+            node_fs_1.default.mkdirSync(destination);
+            let bytes = 0;
+            for (const name of node_fs_1.default.readdirSync(source)) {
+                const item = (0, projectPaths_1.projectPath)(root, node_path_1.default.join(source, name)), stat = node_fs_1.default.lstatSync(item);
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    throw new Error('Shard evidence must contain regular files only.');
+                bytes += stat.size;
+                if (bytes > 500 * 1024 * 1024)
+                    throw new Error('Shard evidence exceeds the 500 MiB merge limit.');
+                node_fs_1.default.copyFileSync(item, node_path_1.default.join(destination, name));
+            }
+        }
+        node_fs_1.default.writeFileSync(node_path_1.default.join(out, 'summary.json'), JSON.stringify(merged, null, 2));
+        node_fs_1.default.writeFileSync(node_path_1.default.join(out, 'timings.json'), JSON.stringify(timings, null, 2));
+        return merged;
+    }
+    catch (error) {
+        node_fs_1.default.rmSync(out, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/ci/init.d.ts

@@ -1 +1,4 @@
-export declare function initCI(provider: string): void;
+export declare function initCI(provider: string, options?: {
+    browsers?: string;
+    shards?: string;
+}): void;

package/dist/ci/init.js

@@ -7,15 +7,26 @@ exports.initCI = initCI;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("./config");
-function initCI(provider) {
+function initCI(provider, options = {}) {
     if (provider !== 'github')
         throw new Error('Supported provider: github.');
+    const browsers = (options.browsers || 'chromium').split(',');
+    const shards = Number(options.shards || 1);
+    if (!browsers.length || new Set(browsers).size !== browsers.length || browsers.some(browser => !['chromium', 'firefox', 'webkit'].includes(browser)))
+        throw new Error('Choose unique browser names separated by commas.');
+    if (!Number.isSafeInteger(shards) || shards < 1 || shards > 256)
+        throw new Error('shards must be 1..256.');
+    const matrix = browsers.length > 1 || shards > 1;
+    const strategy = matrix ? `\n    strategy:\n      fail-fast: false\n      matrix:\n        browser: ${JSON.stringify(browsers)}\n        shard: ${JSON.stringify(Array.from({ length: shards }, (_, index) => index + 1))}` : '';
+    const selection = matrix ? ' --browser ${{ matrix.browser }} --shard ${{ matrix.shard }}/' + shards : browsers[0] !== 'chromium' ? ' --browser ' + browsers[0] : '';
+    const install = matrix ? ' ${{ matrix.browser }}' : ' ' + browsers[0];
+    const artifact = matrix ? 'flowstride-results-${{ matrix.browser }}-${{ matrix.shard }}' : 'flowstride-results';
     const file = node_path_1.default.resolve('.github/workflows/flowstride.yml');
     if (node_fs_1.default.existsSync(file))
         throw new Error('Flowstride workflow already exists; it was not overwritten.');
     const artifacts = node_path_1.default.relative(process.cwd(), (0, config_1.loadNativeConfig)(process.cwd(), {}).artifactsDir);
     const parent = node_path_1.default.dirname(file);
     node_fs_1.default.mkdirSync(parent, { recursive: true });
-    node_fs_1.default.writeFileSync(file, `name: Flowstride\non:\n  push:\n  pull_request:\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262\n        with:\n          persist-credentials: false\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020\n        with:\n          node-version: 24\n          cache: npm\n      - run: npm ci\n      - name: Install matching browser dependencies\n        run: npx --no-install flowstride install --with-deps\n      - name: Run native Flowstride\n        run: npx --no-install flowstride run --ci\n      - name: Retain test evidence\n        if: always()\n        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02\n        with:\n          name: flowstride-results\n          path: ${JSON.stringify(artifacts + "/")}\n          retention-days: 14\n`, { flag: 'wx' });
+    node_fs_1.default.writeFileSync(file, `name: Flowstride\non:\n  push:\n  pull_request:\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20${strategy}\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262\n        with:\n          persist-credentials: false\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020\n        with:\n          node-version: 24\n          cache: npm\n      - run: npm ci\n      - name: Install matching browser dependencies\n        run: npx --no-install flowstride install --with-deps${install}\n      - name: Run native Flowstride\n        run: npx --no-install flowstride run --ci${selection}\n      - name: Retain test evidence\n        if: always()\n        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02\n        with:\n          name: ${artifact}\n          path: ${JSON.stringify(artifacts + "/")}\n          retention-days: 14\n`, { flag: 'wx' });
     console.log(`Created ${file}. Commit it when ready. This template uses the project-locked Flowstride installation.`);
 }