@iota-uz/sdk 0.13.0 → 0.15.0

package/README.md

@@ -11,6 +11,7 @@ subpath APIs are built from separate internal workspace modules:
 - `@iota-uz/sdk/lens`
 - `@iota-uz/sdk/lens/styles.css`
 - `@iota-uz/sdk/identity`
+- `@iota-uz/sdk/testing` (Playwright Node process only; optional `@playwright/test` peer)
 
 Version 0.5 is a clean break: legacy root, BiChat, applet, Tailwind, and asset
 exports are intentionally absent. Solid is the standard client-route renderer;
@@ -26,3 +27,5 @@ compiled stylesheet once at their root:
 import { Button, Input } from '@iota-uz/sdk/solid-ui'
 import '@iota-uz/sdk/solid-ui/standalone.css'
 ```
+
+Browser test projects import synchronization helpers and lifecycle/scenario fixture adapters from `@iota-uz/sdk/testing`. Helpers attach observers before actions and reject missing requests, HTMX refusal and missing readiness. Component hosts reuse explicit font/chart readiness while preserving existing approved screenshot baselines. The source workflow and adapter contracts are documented in `web/testing/README.md`.

package/dist/client-host/identity.d.ts

@@ -1,9 +1,9 @@
-export declare const SDK_RELEASE_VERSION = "0.13.0";
-export declare const SDK_SOURCE_COMMIT = "469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e";
+export declare const SDK_RELEASE_VERSION = "0.15.0";
+export declare const SDK_SOURCE_COMMIT = "9ceb321bfda838bf3c3333f6f465db1b9c81cf72";
 export declare const SDK_PROTOCOL_VERSION = "1.0.0";
 export declare const SDK_IDENTITY: Readonly<{
-    releaseVersion: "0.13.0";
-    sourceCommit: "469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e";
+    releaseVersion: "0.15.0";
+    sourceCommit: "9ceb321bfda838bf3c3333f6f465db1b9c81cf72";
     protocolVersion: "1.0.0";
 }>;
 export interface SDKRuntimeIdentity {

package/dist/client-host/identity.js

@@ -1,6 +1,6 @@
 import { CLIENT_HOST_PROTOCOL_VERSION } from './protocol';
-export const SDK_RELEASE_VERSION = '0.13.0';
-export const SDK_SOURCE_COMMIT = '469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e';
+export const SDK_RELEASE_VERSION = '0.15.0';
+export const SDK_SOURCE_COMMIT = '9ceb321bfda838bf3c3333f6f465db1b9c81cf72';
 export const SDK_PROTOCOL_VERSION = CLIENT_HOST_PROTOCOL_VERSION;
 export const SDK_IDENTITY = Object.freeze({
     releaseVersion: SDK_RELEASE_VERSION,

package/dist/sdk-identity.cjs

@@ -1,6 +1,6 @@
 'use strict'
-const SDK_RELEASE_VERSION = "0.13.0"
-const SDK_SOURCE_COMMIT = "469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e"
+const SDK_RELEASE_VERSION = "0.15.0"
+const SDK_SOURCE_COMMIT = "9ceb321bfda838bf3c3333f6f465db1b9c81cf72"
 const SDK_PROTOCOL_VERSION = "1.0.0"
-const SDK_IDENTITY = Object.freeze({"releaseVersion":"0.13.0","sourceCommit":"469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e","protocolVersion":"1.0.0"})
+const SDK_IDENTITY = Object.freeze({"releaseVersion":"0.15.0","sourceCommit":"9ceb321bfda838bf3c3333f6f465db1b9c81cf72","protocolVersion":"1.0.0"})
 module.exports = { SDK_RELEASE_VERSION, SDK_SOURCE_COMMIT, SDK_PROTOCOL_VERSION, SDK_IDENTITY }

package/dist/sdk-identity.js

@@ -1,4 +1,4 @@
-export const SDK_RELEASE_VERSION = "0.13.0"
-export const SDK_SOURCE_COMMIT = "469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e"
+export const SDK_RELEASE_VERSION = "0.15.0"
+export const SDK_SOURCE_COMMIT = "9ceb321bfda838bf3c3333f6f465db1b9c81cf72"
 export const SDK_PROTOCOL_VERSION = "1.0.0"
-export const SDK_IDENTITY = Object.freeze({"releaseVersion":"0.13.0","sourceCommit":"469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e","protocolVersion":"1.0.0"})
+export const SDK_IDENTITY = Object.freeze({"releaseVersion":"0.15.0","sourceCommit":"9ceb321bfda838bf3c3333f6f465db1b9c81cf72","protocolVersion":"1.0.0"})

package/dist/sdk-identity.json

@@ -1,5 +1,5 @@
 {
-  "releaseVersion": "0.13.0",
-  "sourceCommit": "469a4ea27a96fa0b7a3a6dc83cd10738157d6e1e",
+  "releaseVersion": "0.15.0",
+  "sourceCommit": "9ceb321bfda838bf3c3333f6f465db1b9c81cf72",
   "protocolVersion": "1.0.0"
 }

package/dist/testing/driver.d.ts

@@ -0,0 +1,21 @@
+import type { EnvironmentDescriptor, EnvironmentLifecycle } from './index.js';
+export type DriverDescriptor = EnvironmentDescriptor & {
+    environmentId: string;
+    buildRevision: string;
+    schemaFingerprint: string;
+    baselineFingerprint: string;
+    capabilities: readonly string[];
+    artifactDirectory: string;
+};
+/** One persistent, shell-free driver owns every environment it creates. */
+export declare function createProcessEnvironmentDriver<Spec>(options: {
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    spec(workerIndex: number): Spec;
+    timeoutMs?: number;
+}): {
+    lifecycle: EnvironmentLifecycle<DriverDescriptor>;
+    close: () => Promise<void>;
+};

package/dist/testing/driver.js

@@ -0,0 +1,90 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+/** One persistent, shell-free driver owns every environment it creates. */
+export function createProcessEnvironmentDriver(options) {
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+        throw new Error('timeoutMs must be a positive integer');
+    const child = spawn(options.command, [...options.args ?? []], { cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'] });
+    const pending = new Map();
+    let stderr = '';
+    let closed = false;
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-16_384); });
+    const rejectAll = (error) => {
+        closed = true;
+        for (const request of pending.values()) {
+            clearTimeout(request.timer);
+            request.reject(error);
+        }
+        pending.clear();
+    };
+    const exit = new Promise((resolve, reject) => {
+        child.once('error', error => { rejectAll(error); reject(error); });
+        child.once('exit', (code, signal) => {
+            const error = new Error(`Test environment driver exited (${code ?? signal}): ${stderr}`);
+            rejectAll(error);
+            if (code === 0)
+                resolve();
+            else
+                reject(error);
+        });
+    });
+    // Keep unexpected process exits observed even before the caller closes the driver.
+    void exit.catch(() => { });
+    const lines = createInterface({ input: child.stdout });
+    lines.on('line', line => {
+        let response;
+        try {
+            response = JSON.parse(line);
+        }
+        catch {
+            rejectAll(new Error('Test environment driver emitted invalid JSON'));
+            child.kill('SIGINT');
+            return;
+        }
+        const request = pending.get(response.id);
+        if (!request)
+            return;
+        pending.delete(response.id);
+        clearTimeout(request.timer);
+        if (response.error)
+            request.reject(new Error(`${response.error.code}: ${response.error.message}`));
+        else
+            request.resolve(response.descriptor);
+    });
+    const invoke = (request) => {
+        if (closed)
+            return Promise.reject(new Error('Test environment driver is closed'));
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new Error('Test environment driver request timed out'));
+                child.kill('SIGINT');
+            }, timeoutMs);
+            pending.set(id, { resolve, reject, timer });
+            child.stdin.write(`${JSON.stringify({ id, ...request })}\n`, error => {
+                if (error) {
+                    clearTimeout(timer);
+                    pending.delete(id);
+                    reject(error);
+                }
+            });
+        });
+    };
+    const lifecycle = {
+        start: async (workerIndex) => {
+            const descriptor = await invoke({ operation: 'start', spec: options.spec(workerIndex) });
+            if (!descriptor?.environmentId || !descriptor?.baseURL || !descriptor?.artifactDirectory) {
+                child.kill('SIGINT');
+                throw new Error('Incomplete test environment descriptor');
+            }
+            return { ...descriptor, runId: descriptor.environmentId, artifactDir: descriptor.artifactDirectory };
+        },
+        // Driver start returns only after the configured real readiness probe succeeds.
+        ready: async () => { },
+        stop: async (environment) => { await invoke({ operation: 'stop', environmentId: environment.environmentId }); },
+    };
+    return { lifecycle, close: async () => { child.stdin.end(); await exit; lines.close(); } };
+}

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,13 @@
+import type { Browser, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from '@playwright/test';
+import { type EnvironmentDescriptor, type EnvironmentLifecycle, type ScenarioControl, type ScenarioLease, type IdentityLease } from './index.js';
+export declare function createEnvironmentTest<E extends EnvironmentDescriptor, Input, State, Key, Identity>(base: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>, options: {
+    lifecycle: EnvironmentLifecycle<E>;
+    scenarios(environment: E): ScenarioControl<Input, State>;
+    identity(environment: E, browser: Browser, key: Key): Promise<Identity>;
+}): TestType<PlaywrightTestArgs & PlaywrightTestOptions & {
+    scenario: ScenarioLease<Input, State>;
+    identity: IdentityLease<Key, Identity>;
+}, PlaywrightWorkerArgs & PlaywrightWorkerOptions & {
+    environment: E;
+    workerIdentity: IdentityLease<Key, Identity>;
+}>;

package/dist/testing/fixtures.js

@@ -0,0 +1,30 @@
+import { lazyIdentities, withEnvironment } from './index.js';
+export function createEnvironmentTest(base, options) {
+    return base.extend({
+        environment: [async ({}, use, info) => {
+                await withEnvironment(options.lifecycle, info.workerIndex, use);
+            }, { scope: 'worker' }],
+        workerIdentity: [async ({ environment, browser }, use) => {
+                await use(lazyIdentities(key => options.identity(environment, browser, key)));
+            }, { scope: 'worker' }],
+        baseURL: async ({ environment }, use) => { await use(environment.baseURL); },
+        identity: async ({ workerIdentity }, use) => { await use(workerIdentity); },
+        scenario: async ({ environment }, use, info) => {
+            const control = options.scenarios(environment);
+            const scopes = [];
+            try {
+                await use(async (input) => {
+                    const scope = `${environment.runId}-w${info.workerIndex}-r${info.retry}-${crypto.randomUUID()}`;
+                    scopes.push(scope);
+                    return control.prepare(input, scope);
+                });
+            }
+            finally {
+                const results = await Promise.allSettled(scopes.map(scope => control.dispose(scope)));
+                const errors = results.filter((result) => result.status === 'rejected').map(result => result.reason);
+                if (errors.length)
+                    throw new AggregateError(errors, 'Scenario teardown failed');
+            }
+        },
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,64 @@
+import type { Locator, Page, Response } from '@playwright/test';
+export type WaitOptions = {
+    timeoutMs?: number;
+};
+export type RequestMatch = {
+    method: string;
+    pathname: string;
+};
+export type ResponseMatch = RequestMatch | ((response: Response) => boolean);
+export type ValidationResult = {
+    controlName: string;
+    message: string;
+};
+export type ComponentCase = {
+    id: string;
+    state: string;
+    locale: string;
+    theme: 'light' | 'dark';
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export declare function actionAndResponse(page: Page, match: ResponseMatch, action: () => Promise<unknown>, options?: WaitOptions): Promise<Response>;
+/** Installs the event observer before the action and follows replacement targets by selector. */
+export declare function actionAndHtmxSettled(page: Page, target: string, action: () => Promise<unknown>, options?: WaitOptions): Promise<void>;
+export declare function actionAndValidationRefusal(page: Page, form: Locator, action: () => Promise<unknown>): Promise<ValidationResult>;
+export declare function expectComponentReady(page: Page, root: Locator, options?: WaitOptions & {
+    readinessAttribute?: string;
+}): Promise<void>;
+export interface ComponentHost {
+    cases(): Promise<readonly ComponentCase[]>;
+    navigate(page: Page, componentCase: ComponentCase): Promise<Locator>;
+}
+export declare function openComponentCase(page: Page, host: ComponentHost, componentCase: ComponentCase, options?: WaitOptions): Promise<Locator>;
+export declare function actionAndHtmxResponse(page: Page, match: ResponseMatch, action: () => Promise<unknown>, options?: WaitOptions): Promise<Response>;
+export interface EnvironmentDescriptor {
+    runId: string;
+    baseURL: string;
+    artifactDir: string;
+}
+export interface EnvironmentLifecycle<E extends EnvironmentDescriptor> {
+    start(workerIndex: number): Promise<E>;
+    ready(environment: E): Promise<void>;
+    stop(environment: E): Promise<void>;
+}
+export interface ScenarioControl<Input, Result> {
+    prepare(input: Input, scopeId: string): Promise<Result>;
+    dispose(scopeId: string): Promise<void>;
+}
+/** Teardown runs even when readiness, the scenario or the browser assertion fails. */
+export declare function withEnvironment<E extends EnvironmentDescriptor, Result>(lifecycle: EnvironmentLifecycle<E>, workerIndex: number, use: (environment: E) => Promise<Result>): Promise<Result>;
+export declare function withScenario<Input, State, Result>(control: ScenarioControl<Input, State>, input: Input, scopeId: string, use: (state: State) => Promise<Result>): Promise<Result>;
+/** Instantiate per worker/environment; identities are materialised only when requested. */
+export declare function lazyIdentities<Key, State>(create: (identity: Key) => Promise<State>): (identity: Key) => Promise<State>;
+export type ScenarioLease<Input, State> = (input: Input) => Promise<State>;
+export type IdentityLease<Key, State> = (identity: Key) => Promise<State>;
+export { createEnvironmentTest } from './fixtures.js';
+export { createProcessEnvironmentDriver, type DriverDescriptor } from './driver.js';
+export declare function expectFontsReady(page: Page, options?: WaitOptions): Promise<void>;
+export declare function expectChartsReady(charts: Locator, options?: WaitOptions & {
+    allowEmpty?: boolean;
+}): Promise<void>;
+export { createHttpScenarioControl, ScenarioControlError, type ScenarioInput, type ScenarioResult } from './scenarios.js';

package/dist/testing/index.js

@@ -0,0 +1,253 @@
+function timeout(options = {}) {
+    const value = options.timeoutMs ?? 10_000;
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error('timeoutMs must be a positive integer');
+    return value;
+}
+export async function actionAndResponse(page, match, action, options = {}) {
+    const response = page.waitForResponse(r => typeof match === 'function' ? match(r) : r.request().method() === match.method.toUpperCase() && new URL(r.url()).pathname === match.pathname, { timeout: timeout(options) });
+    const [result] = await Promise.all([response, action()]);
+    return result;
+}
+/** Installs the event observer before the action and follows replacement targets by selector. */
+export async function actionAndHtmxSettled(page, target, action, options = {}) {
+    const key = `sdk-htmx-${crypto.randomUUID()}`;
+    await page.evaluate(({ key, target }) => {
+        const state = { pending: 0, swapped: false, settled: false, failed: false };
+        const requests = new WeakSet();
+        const matches = (event) => {
+            const detail = event.detail;
+            const element = detail?.target ?? detail?.elt;
+            return element instanceof Element && (element.matches(target) || Boolean(element.closest(target)));
+        };
+        const before = (event) => {
+            const detail = event.detail;
+            if (matches(event) && detail?.xhr && !requests.has(detail.xhr)) {
+                requests.add(detail.xhr);
+                state.pending++;
+                state.settled = false;
+            }
+        };
+        const correlated = (event) => { const xhr = event.detail?.xhr; return xhr && requests.has(xhr); };
+        const swap = (event) => { if (correlated(event))
+            state.swapped = true; };
+        const settle = (event) => { if (correlated(event) && state.swapped) {
+            requests.delete(event.detail.xhr);
+            state.pending--;
+            state.settled = state.pending === 0;
+        } };
+        const error = (event) => { if (correlated(event))
+            state.failed = true; };
+        document.addEventListener('htmx:beforeRequest', before);
+        document.addEventListener('htmx:afterSwap', swap);
+        document.addEventListener('htmx:afterSettle', settle);
+        document.addEventListener('htmx:responseError', error);
+        window[key] = { state, dispose: () => {
+                document.removeEventListener('htmx:beforeRequest', before);
+                document.removeEventListener('htmx:afterSwap', swap);
+                document.removeEventListener('htmx:afterSettle', settle);
+                document.removeEventListener('htmx:responseError', error);
+            } };
+    }, { key, target });
+    try {
+        await action();
+        await page.waitForFunction(key => window[key].state.settled || window[key].state.failed, key, { timeout: timeout(options) });
+        const failed = await page.evaluate(key => window[key].state.failed, key);
+        if (failed)
+            throw new Error(`HTMX response failed for ${target}`);
+        await page.locator(target).waitFor({ state: 'visible', timeout: timeout(options) });
+    }
+    finally {
+        await page.evaluate(key => { window[key]?.dispose(); delete window[key]; }, key);
+    }
+}
+export async function actionAndValidationRefusal(page, form, action) {
+    const key = `sdk-validation-${crypto.randomUUID()}`;
+    await form.evaluate((element, key) => {
+        const state = { invalid: null, submitted: false };
+        const invalid = (event) => {
+            const control = event.target;
+            state.invalid ??= { controlName: control.name, message: control.validationMessage };
+        };
+        const submit = () => { state.submitted = true; };
+        element.addEventListener('invalid', invalid, true);
+        element.addEventListener('submit', submit);
+        window[key] = { state, dispose: () => { element.removeEventListener('invalid', invalid, true); element.removeEventListener('submit', submit); } };
+    }, key);
+    const submission = await form.evaluate(element => {
+        const f = element;
+        return { url: new URL(f.getAttribute('hx-post') ?? f.action, location.href).href, method: f.hasAttribute('hx-post') ? 'POST' : f.method.toUpperCase() };
+    });
+    let submittedRequest = false;
+    const observe = (request) => {
+        if (request.url().split('?')[0] === submission.url.split('?')[0] && request.method() === submission.method)
+            submittedRequest = true;
+    };
+    page.on('request', observe);
+    try {
+        await action();
+        if (submittedRequest)
+            throw new Error('Native validation unexpectedly issued a submission request');
+        return await page.evaluate(key => {
+            const state = window[key].state;
+            if (!state.invalid || state.submitted)
+                throw new Error('Expected native validation refusal without submission');
+            return state.invalid;
+        }, key);
+    }
+    finally {
+        page.off('request', observe);
+        await page.evaluate(key => { window[key]?.dispose(); delete window[key]; }, key);
+    }
+}
+export async function expectComponentReady(page, root, options = {}) {
+    await waitForCondition(async () => await root.getAttribute(options.readinessAttribute ?? 'data-component-ready') === 'true', timeout(options), 'Component readiness marker missing');
+    await page.waitForFunction(() => document.fonts.status === 'loaded', undefined, { timeout: timeout(options) });
+    await root.waitFor({ state: 'visible', timeout: timeout(options) });
+}
+export async function openComponentCase(page, host, componentCase, options = {}) {
+    await page.setViewportSize(componentCase.viewport);
+    const root = await host.navigate(page, componentCase);
+    await expectComponentReady(page, root, options);
+    return root;
+}
+export async function actionAndHtmxResponse(page, match, action, options = {}) {
+    const key = `sdk-response-${crypto.randomUUID()}`;
+    await page.evaluate(key => {
+        const records = [];
+        const requests = new WeakMap();
+        const observed = new Set();
+        const before = (event) => {
+            const d = event.detail;
+            if (!d?.xhr)
+                return;
+            const record = { url: new URL(d.requestConfig.path, location.href).href, method: String(d.requestConfig.verb).toUpperCase(), status: 0, settled: false, failed: false, aborted: false };
+            records.push(record);
+            requests.set(d.xhr, record);
+            // A removed swap target no longer bubbles its lifecycle events to document.
+            for (const element of [d.elt, d.target]) {
+                if (!(element instanceof Element) || observed.has(element))
+                    continue;
+                observed.add(element);
+                element.addEventListener('htmx:afterSettle', update);
+                element.addEventListener('htmx:responseError', update);
+                element.addEventListener('htmx:sendAbort', update);
+                element.addEventListener('htmx:sendError', update);
+            }
+        };
+        const update = (event) => {
+            const d = event.detail;
+            const record = d?.xhr && requests.get(d.xhr);
+            if (!record)
+                return;
+            record.url = d.xhr.responseURL || record.url;
+            record.status = d.xhr.status;
+            record.failed = event.type === 'htmx:responseError' || event.type === 'htmx:sendError';
+            record.aborted = event.type === 'htmx:sendAbort';
+            record.settled = event.type === 'htmx:afterSettle';
+        };
+        document.addEventListener('htmx:beforeRequest', before);
+        document.addEventListener('htmx:afterSettle', update);
+        document.addEventListener('htmx:responseError', update);
+        document.addEventListener('htmx:sendAbort', update);
+        document.addEventListener('htmx:sendError', update);
+        window[key] = { records, dispose: () => {
+                document.removeEventListener('htmx:beforeRequest', before);
+                document.removeEventListener('htmx:afterSettle', update);
+                document.removeEventListener('htmx:responseError', update);
+                document.removeEventListener('htmx:sendAbort', update);
+                document.removeEventListener('htmx:sendError', update);
+                for (const element of observed) {
+                    element.removeEventListener('htmx:afterSettle', update);
+                    element.removeEventListener('htmx:responseError', update);
+                    element.removeEventListener('htmx:sendAbort', update);
+                    element.removeEventListener('htmx:sendError', update);
+                }
+            } };
+    }, key);
+    try {
+        const response = await actionAndResponse(page, match, action, options);
+        const identity = { url: response.url(), method: response.request().method(), status: response.status() };
+        await page.waitForFunction(({ key, identity }) => {
+            const records = window[key].records.filter((r) => r.url === identity.url && r.method === identity.method);
+            return records.some((r) => !r.aborted && (r.settled || r.failed)) && records.every((r) => r.settled || r.failed || r.aborted);
+        }, { key, identity }, { timeout: timeout(options) });
+        const failure = await page.evaluate(({ key, identity }) => {
+            const records = window[key].records.filter((r) => r.url === identity.url && r.method === identity.method && !r.aborted);
+            const latest = records.at(-1);
+            return latest?.failed ? latest.status : null;
+        }, { key, identity });
+        if (failure !== null)
+            throw new Error(`HTMX request failed: ${failure} ${response.url()}`);
+        if (!response.ok())
+            throw new Error(`HTMX request failed: ${response.status()} ${response.url()}`);
+        return response;
+    }
+    finally {
+        await page.evaluate(key => { window[key]?.dispose(); delete window[key]; }, key);
+    }
+}
+/** Teardown runs even when readiness, the scenario or the browser assertion fails. */
+export async function withEnvironment(lifecycle, workerIndex, use) {
+    const environment = await lifecycle.start(workerIndex);
+    let failed = false;
+    let failure;
+    try {
+        await lifecycle.ready(environment);
+        return await use(environment);
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
+        throw error;
+    }
+    finally {
+        try {
+            await lifecycle.stop(environment);
+        }
+        catch (error) {
+            if (failed)
+                throw new AggregateError([failure, error], 'Environment failed and teardown failed');
+            throw error;
+        }
+    }
+}
+export async function withScenario(control, input, scopeId, use) {
+    try {
+        return await use(await control.prepare(input, scopeId));
+    }
+    finally {
+        await control.dispose(scopeId);
+    }
+}
+/** Instantiate per worker/environment; identities are materialised only when requested. */
+export function lazyIdentities(create) {
+    const identities = new Map();
+    return identity => {
+        let state = identities.get(identity);
+        if (!state) {
+            state = create(identity).catch(error => { identities.delete(identity); throw error; });
+            identities.set(identity, state);
+        }
+        return state;
+    };
+}
+export { createEnvironmentTest } from './fixtures.js';
+export { createProcessEnvironmentDriver } from './driver.js';
+export async function expectFontsReady(page, options = {}) {
+    await page.waitForFunction(() => document.fonts.status === 'loaded', undefined, { timeout: timeout(options) });
+}
+export async function expectChartsReady(charts, options = {}) {
+    await waitForCondition(async () => charts.evaluateAll((elements, allowEmpty) => (allowEmpty || elements.length > 0) && elements.every(element => element.getAttribute('data-chart-ready') === 'true'), options.allowEmpty ?? false), timeout(options), 'Chart readiness missing');
+    if (!options.allowEmpty)
+        await charts.first().waitFor({ state: 'visible', timeout: timeout(options) });
+}
+async function waitForCondition(condition, timeoutMs, diagnostic) {
+    const deadline = Date.now() + timeoutMs;
+    while (!(await condition())) {
+        if (Date.now() >= deadline)
+            throw new Error(diagnostic);
+        await new Promise(resolve => setTimeout(resolve, Math.min(16, Math.max(1, deadline - Date.now()))));
+    }
+}
+export { createHttpScenarioControl, ScenarioControlError } from './scenarios.js';

package/dist/testing/scenarios.d.ts

@@ -0,0 +1,29 @@
+import type { ScenarioControl, WaitOptions } from './index.js';
+export type ScenarioInput = {
+    name: string;
+    version: string;
+    seed: string;
+    now: string;
+    params: Record<string, unknown>;
+};
+export type ScenarioResult<Data = Record<string, unknown>> = {
+    scopeId: string;
+    name: string;
+    version: string;
+    seed: string;
+    now: string;
+    refs: Record<string, {
+        kind: string;
+        id: string;
+    }>;
+    data: Data;
+};
+export declare class ScenarioControlError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number, message: string);
+}
+export declare function createHttpScenarioControl<Data = Record<string, unknown>>(environment: {
+    environmentId: string;
+    baseURL: string;
+}, token: string, options?: WaitOptions): ScenarioControl<ScenarioInput, ScenarioResult<Data>>;

package/dist/testing/scenarios.js

@@ -0,0 +1,38 @@
+export class ScenarioControlError extends Error {
+    code;
+    status;
+    constructor(code, status, message) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'ScenarioControlError';
+    }
+}
+export function createHttpScenarioControl(environment, token, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || token.length < 32)
+        throw new Error('A positive timeout and a control credential of at least 32 characters are required');
+    const invoke = async (pathname, method, body) => {
+        const response = await fetch(new URL(pathname, environment.baseURL), { method, redirect: 'manual', signal: AbortSignal.timeout(timeoutMs),
+            headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) }, body: body === undefined ? undefined : JSON.stringify(body) });
+        if (!response.ok) {
+            const text = await response.text();
+            let error = {};
+            try {
+                error = JSON.parse(text);
+            }
+            catch { }
+            throw new ScenarioControlError(error.code ?? `http_${response.status}`, response.status, error.message ?? `Scenario control returned HTTP ${response.status}`);
+        }
+        if (response.headers.get('X-Test-Environment-ID') !== environment.environmentId)
+            throw new ScenarioControlError('environment_mismatch', response.status, 'Scenario endpoint belongs to another environment');
+        return response.json();
+    };
+    return {
+        prepare: async (input, scopeId) => {
+            await invoke('/__test__/scopes', 'POST', { scopeId });
+            return await invoke('/__test__/scenarios/prepare', 'POST', { ...input, scopeId });
+        },
+        dispose: async (scopeId) => { await invoke(`/__test__/scopes/${encodeURIComponent(scopeId)}`, 'DELETE'); },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iota-uz/sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Canonical JavaScript distribution for iota-sdk.",
   "license": "MIT",
   "repository": {
@@ -49,12 +49,17 @@
       "types": "./dist/lens/index.d.ts",
       "import": "./dist/lens/index.js"
     },
-    "./lens/styles.css": "./dist/lens/style.css"
+    "./lens/styles.css": "./dist/lens/style.css",
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
-    "solid-js": "^1.9.0"
+    "solid-js": "^1.9.0",
+    "@playwright/test": "^1.55.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -65,6 +70,9 @@
     },
     "solid-js": {
       "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
     }
   }
 }