flowstride 1.0.21 → 1.0.22

package/dist/cli/manual_server/workspace_server.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startManualWorkspaceServer = startManualWorkspaceServer;
+const localWorkspace_1 = require("../../security/localWorkspace");
 const projectPaths_1 = require("../../utils/projectPaths");
 const security_1 = require("../../manual/security");
 const http = __importStar(require("http"));
@@ -44,6 +45,72 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const ws_1 = require("ws");
 const chalk_1 = __importDefault(require("chalk"));
+/** Complete local persistence before publishing a usable media URL. */
+function receiveManualUpload(req, res, filePath, maxSize, limitMessage, onSaved, onChunk) {
+    let size = 0;
+    let saved = false;
+    let failure;
+    const output = fs.createWriteStream(filePath);
+    const sendFailure = () => {
+        if (!res.destroyed && !res.writableEnded && !res.headersSent) {
+            res.writeHead(failure?.status || 500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: failure?.message || 'Upload stream failed' }));
+        }
+    };
+    const fail = (status, message) => {
+        if (saved || failure)
+            return;
+        failure = { status, message };
+        output.destroy();
+        // Drain the rejected request without buffering it so the error can be sent.
+        req.resume();
+    };
+    output.on('error', () => fail(500, 'Upload stream failed'));
+    output.once('close', () => {
+        if (saved)
+            return;
+        // An early destroy may race the asynchronous file open. Cleanup belongs
+        // after close, when a partial file can no longer be recreated or written.
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                console.warn('[Upload]: Could not remove a partial media file.');
+        }
+        sendFailure();
+    });
+    output.once('finish', () => {
+        if (failure)
+            return;
+        saved = true;
+        Promise.resolve().then(() => onSaved(size)).catch(() => {
+            failure = { status: 500, message: 'Upload completion failed' };
+            sendFailure();
+        });
+    });
+    req.on('data', (chunk) => {
+        if (failure || saved)
+            return;
+        size += chunk.length;
+        if (size > maxSize) {
+            fail(413, limitMessage);
+            return;
+        }
+        onChunk?.(chunk);
+        if (!output.write(chunk)) {
+            req.pause();
+            output.once('drain', () => { if (!failure)
+                req.resume(); });
+        }
+    });
+    req.once('end', () => { if (!failure)
+        output.end(); });
+    req.once('aborted', () => fail(400, 'Upload aborted'));
+    req.once('error', () => fail(500, 'Upload stream failed'));
+    res.once('close', () => { if (!res.writableFinished)
+        fail(400, 'Upload aborted'); });
+}
 async function startManualWorkspaceServer() {
     const cliInstallPath = path.resolve(__dirname, "../../..");
     const uiDistPath = path.join(cliInstallPath, "src", "ui", "dist");
@@ -74,9 +141,18 @@ async function startManualWorkspaceServer() {
         ".webm": "video/webm",
     };
     const httpServer = http.createServer(async (req, res) => {
-        res.setHeader("Access-Control-Allow-Origin", "*");
-        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, X-File-Extension");
+        const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
+        const fetchSite = typeof req.headers['sec-fetch-site'] === 'string' ? req.headers['sec-fetch-site'] : undefined;
+        if (!(0, localWorkspace_1.isLocalWorkspaceRequest)(req.headers.host, origin, req.socket.localPort, fetchSite)) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end('Forbidden');
+            return;
+        }
+        if (origin)
+            res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-File-Extension');
         if (req.method === "OPTIONS") {
             res.writeHead(204);
             return res.end();
@@ -95,43 +171,11 @@ async function startManualWorkspaceServer() {
             }
             const safeFilename = `media_${Date.now()}_${Math.random().toString(36).substring(2, 9)}${ext.toLowerCase()}`;
             const filePath = (0, projectPaths_1.projectPath)(process.cwd(), path.join(mediaDir, safeFilename));
-            const MAX_SIZE = 104857600;
-            let uploadedSize = 0;
-            let isAborted = false;
-            const writeStream = fs.createWriteStream(filePath);
-            req.on("data", (chunk) => {
-                if (isAborted)
-                    return;
-                uploadedSize += chunk.length;
-                if (uploadedSize > MAX_SIZE) {
-                    isAborted = true;
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(413, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Payload Too Large. Max size is 100MB." }));
-                }
-                else {
-                    writeStream.write(chunk);
-                }
-            });
-            req.on("end", () => {
-                if (isAborted)
-                    return;
-                writeStream.end();
+            receiveManualUpload(req, res, filePath, 104857600, 'Payload Too Large. Max size is 100MB.', (uploadedSize) => {
                 console.log(chalk_1.default.blue(`\n[Reference Uploaded]: Securely saved ${safeFilename} (${(uploadedSize / 1024 / 1024).toFixed(2)} MB)`));
-                res.writeHead(200, { "Content-Type": "application/json" });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ url: `/media/${safeFilename}` }));
             });
-            req.on("error", (err) => {
-                if (!isAborted) {
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Upload stream failed" }));
-                }
-            });
             return;
         }
         if (req.method === "DELETE" && pathname === "/api/media") {
@@ -216,44 +260,12 @@ async function startManualWorkspaceServer() {
             }
             const safeFilename = `defect_${Date.now()}_${Math.random().toString(36).substring(2, 9)}${ext.toLowerCase()}`;
             const filePath = (0, projectPaths_1.projectPath)(process.cwd(), path.join(defectMediaDir, safeFilename));
-            const MAX_SIZE = 41943040; // Capped at 40MB
-            let uploadedSize = 0;
-            let isAborted = false;
-            const writeStream = fs.createWriteStream(filePath);
-            req.on("data", (chunk) => {
-                if (isAborted)
-                    return;
-                uploadedSize += chunk.length;
-                if (uploadedSize > MAX_SIZE) {
-                    isAborted = true;
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(413, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Payload Too Large. Max size is 40MB." }));
-                }
-                else {
-                    writeStream.write(chunk);
-                }
-            });
-            req.on("end", async () => {
-                if (isAborted)
-                    return;
-                writeStream.end();
+            receiveManualUpload(req, res, filePath, 41943040, 'Payload Too Large. Max size is 40MB.', () => {
                 const finalUrl = `/defect_media/${safeFilename}`;
                 console.log(chalk_1.default.green(`\n[Vault Success]: Defect Media secured locally at -> ${finalUrl}`));
-                res.writeHead(200, { "Content-Type": "application/json" });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ url: finalUrl }));
             });
-            req.on("error", (err) => {
-                if (!isAborted) {
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Upload stream failed" }));
-                }
-            });
             return;
         }
         if (req.method === "DELETE" && pathname === "/api/defect-media") {
@@ -727,7 +739,11 @@ async function startManualWorkspaceServer() {
             }
         }
     });
-    const wss = new ws_1.WebSocketServer({ server: httpServer });
+    const wss = new ws_1.WebSocketServer({
+        server: httpServer,
+        verifyClient: (info) => Boolean(info.origin) &&
+            (0, localWorkspace_1.isLocalWorkspaceRequest)(info.req.headers.host, info.origin, info.req.socket.localPort, typeof info.req.headers['sec-fetch-site'] === 'string' ? info.req.headers['sec-fetch-site'] : undefined),
+    });
     wss.on("connection", (ws) => {
         ws.send(JSON.stringify({ type: "CLI_CONTEXT", payload: { command: "open" } }));
         ws.on("error", (err) => {
@@ -738,7 +754,7 @@ async function startManualWorkspaceServer() {
         console.error(chalk_1.default.red(`\n[Error]: Failed to start manual workspace server: ${e.message}`));
         process.exit(1);
     });
-    httpServer.listen(0, async () => {
+    httpServer.listen(0, '127.0.0.1', async () => {
         try {
             const address = httpServer.address();
             const port = typeof address === "object" && address !== null ? address.port : null;
@@ -746,7 +762,7 @@ async function startManualWorkspaceServer() {
                 console.error(chalk_1.default.red("\n[Error]: Could not bind to an available port."));
                 process.exit(1);
             }
-            const localUrl = `http://localhost:${port}`;
+            const localUrl = `http://127.0.0.1:${port}`;
             console.log(chalk_1.default.yellow(`\n[Workspace]: Manual Design server running at ${localUrl}`));
             const { default: open } = await import("open");
             await open(localUrl);

package/dist/manual/security.d.ts

@@ -62,6 +62,8 @@ export declare const manualRunSchema: z.ZodObject<{
                 skipped: "skipped";
                 success: "success";
                 pending: "pending";
+                pass: "pass";
+                blocked: "blocked";
                 Pending: "Pending";
                 Current: "Current";
                 Passed: "Passed";
@@ -71,8 +73,6 @@ export declare const manualRunSchema: z.ZodObject<{
                 Pass: "Pass";
                 Fail: "Fail";
                 Success: "Success";
-                pass: "pass";
-                blocked: "blocked";
             }>;
             group_title: z.ZodOptional<z.ZodString>;
             id: z.ZodNumber;
@@ -144,6 +144,8 @@ export declare const manualCanvasSchema: z.ZodObject<{
             skipped: "skipped";
             success: "success";
             pending: "pending";
+            pass: "pass";
+            blocked: "blocked";
             Pending: "Pending";
             Current: "Current";
             Passed: "Passed";
@@ -153,8 +155,6 @@ export declare const manualCanvasSchema: z.ZodObject<{
             Pass: "Pass";
             Fail: "Fail";
             Success: "Success";
-            pass: "pass";
-            blocked: "blocked";
         }>;
         group_title: z.ZodOptional<z.ZodString>;
         id: z.ZodNumber;

package/dist/native/accessibility.d.ts

@@ -1,3 +1,4 @@
+import { type AssertionReporter } from '../reporting/assertion_result';
 import type { Page } from 'playwright';
 import type { FlowstrideConfig } from '../types';
-export declare function accessibility(page: Page, config: FlowstrideConfig, action: string, input: unknown): Promise<string | undefined>;
+export declare function accessibility(page: Page, config: FlowstrideConfig, action: string, input: unknown, reporter?: AssertionReporter): Promise<string | undefined>;

package/dist/native/accessibility.js

@@ -4,13 +4,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.accessibility = accessibility;
+const assertion_result_1 = require("../reporting/assertion_result");
 const zod_1 = require("zod");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const playwright_1 = __importDefault(require("@axe-core/playwright"));
 const validation_1 = require("./validation");
 const projectPaths_1 = require("../utils/projectPaths");
-async function accessibility(page, config, action, input) {
+async function accessibility(page, config, action, input, reporter) {
     if (action === 'scan') {
         const data = zod_1.z.object({ name: validation_1.name.default('accessibility'), include: zod_1.z.array(zod_1.z.string()).optional(), exclude: zod_1.z.array(zod_1.z.string()).optional(), tags: zod_1.z.array(zod_1.z.string()).optional(), rules: zod_1.z.array(zod_1.z.string()).optional(), disableRules: zod_1.z.array(zod_1.z.string()).optional(), impacts: zod_1.z.array(zod_1.z.enum(['minor', 'moderate', 'serious', 'critical'])).optional(), maxViolations: zod_1.z.number().int().nonnegative().default(0) }).strict().parse(input);
         let builder = new playwright_1.default({ page });
@@ -29,8 +30,7 @@ async function accessibility(page, config, action, input) {
         const file = (0, validation_1.evidencePath)(config, `${data.name}-${Date.now()}.json`);
         // Reports may contain application content. They remain in local evidence.
         node_fs_1.default.writeFileSync(file, JSON.stringify({ ...result, violations }, null, 2), { mode: 0o600 });
-        if (violations.length > data.maxViolations)
-            throw new Error(`Accessibility assertion failed: ${violations.length} violations (${violations.map(item => item.id).join(', ')}). Report: ${file}`);
+        (0, assertion_result_1.requireAssertion)('a11y.scan', 'accessibility scan ' + data.name, [(0, assertion_result_1.assertionCheck)('violations', 'Violation count within the allowed maximum', violations.length <= data.maxViolations, `at most ${data.maxViolations}`, violations.length)], reporter, { reason: violations.length > data.maxViolations ? `Accessibility assertion failed: ${violations.length} violations (${violations.map(item => item.id).slice(0, 30).join(', ')}). Report: ${file}` : undefined });
         return file;
     }
     if (action === 'snapshot') {
@@ -54,14 +54,30 @@ async function accessibility(page, config, action, input) {
         }
         else {
             const expected = (0, validation_1.readProjectFile)(config, baseline).toString('utf8').replace(/\r\n/g, '\n').trim();
-            if (expected !== snapshot.trim())
-                throw new Error(`ARIA baseline differs. Review the captured snapshot before updating: ${file}`);
+            (0, assertion_result_1.requireAssertion)('a11y.snapshot', 'ARIA baseline ' + data.baseline, [(0, assertion_result_1.assertionCheck)('baseline', 'ARIA baseline matches', expected === snapshot.trim(), expected, snapshot.trim())], reporter, { reason: expected !== snapshot.trim() ? `ARIA baseline differs. Review the captured snapshot before updating: ${file}` : undefined });
         }
         return file;
     }
     if (action === 'match') {
         const data = zod_1.z.object({ selector: zod_1.z.string().default('body'), yaml: zod_1.z.string().min(1), timeout: validation_1.positive.optional() }).strict().parse(input);
-        await (0, validation_1.poll)(async () => (await page.locator(data.selector).ariaSnapshot()).trim() === data.yaml.replace(/\r\n/g, '\n').trim(), data.timeout ?? config.timeout, 'ARIA snapshot differs');
+        const started = Date.now(), timeout = data.timeout ?? config.timeout;
+        let latest = (0, assertion_result_1.reportAssertion)('a11y.match', 'ARIA snapshot ' + data.selector, [{ key: 'snapshot', label: 'ARIA snapshot matches', status: 'running' }], reporter, { status: 'running', timeout, elapsed: 0 });
+        let closed = false;
+        try {
+            await (0, validation_1.poll)(async () => { const actual = (await page.locator(data.selector).ariaSnapshot()).trim(), expected = data.yaml.replace(/\r\n/g, '\n').trim(); const check = (0, assertion_result_1.assertionCheck)('snapshot', 'ARIA snapshot matches', actual === expected, expected, actual); if (!closed)
+                latest = (0, assertion_result_1.reportAssertion)('a11y.match', 'ARIA snapshot ' + data.selector, [check], reporter, { status: 'running', timeout, elapsed: Date.now() - started }); return check.status === 'passed'; }, timeout, 'ARIA snapshot differs');
+            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)) };
+            for (const check of result.checks)
+                if (check.status === 'running')
+                    check.status = 'failed';
+            reporter?.(result);
+            throw new assertion_result_1.AssertionFailure(result);
+        }
         return;
     }
     throw new Error(`Unknown accessibility action: ${action}`);

package/dist/native/assertions.d.ts

@@ -1,2 +1,3 @@
 import type { Page } from 'playwright';
-export declare function assertBrowser(page: Page, input: unknown, defaultTimeout: number): Promise<void>;
+import { type AssertionReporter } from '../reporting/assertion_result';
+export declare function assertBrowser(page: Page, input: unknown, defaultTimeout: number, reporter?: AssertionReporter): Promise<void>;

package/dist/native/assertions.js

@@ -8,6 +8,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = require("zod");
 const validation_1 = require("./validation");
 const node_util_1 = require("node:util");
+const assertion_result_1 = require("../reporting/assertion_result");
 let accessibilityBundle;
 async function installAccessibilityNames(page) {
     if (await page.evaluate(() => !!window.__FLOWSTRIDE_ACCESSIBILITY_NAMES__))
@@ -28,8 +29,8 @@ const schema = zod_1.z.object({ selector: zod_1.z.string().optional(), role: zod
     value: zod_1.z.unknown().optional(), attribute: zod_1.z.string().optional(), property: zod_1.z.string().optional(), key: zod_1.z.string().optional(),
     matches: zod_1.z.string().optional(), flags: zod_1.z.string().regex(/^[imsu]*$/).optional(), not: zod_1.z.boolean().default(false), timeout: validation_1.positive.optional(),
 }).strict();
-async function assertBrowser(page, input, defaultTimeout) {
-    const data = schema.parse(input), timeout = data.timeout ?? defaultTimeout;
+async function assertBrowser(page, input, defaultTimeout, reporter) {
+    const data = schema.parse(input), timeout = data.timeout ?? defaultTimeout, started = Date.now();
     const expected = data.matches !== undefined ? new RegExp(data.matches, data.flags) : data.value;
     const equals = (actual) => expected instanceof RegExp ? typeof actual === 'string' && expected.test(actual) : (0, node_util_1.isDeepStrictEqual)(actual, expected);
     const scope = data.frame ? page.frameLocator(data.frame) : page;
@@ -44,97 +45,179 @@ async function assertBrowser(page, input, defaultTimeout) {
         throw new Error('Assertion requires an attribute, property, or storage key.');
     if (data.condition === 'count' && (!Number.isSafeInteger(expected) || expected < 0))
         throw new Error('Count requires a nonnegative integer.');
-    await (0, validation_1.poll)(async () => {
-        if (['accessibleName', 'accessibleDescription'].includes(data.condition))
-            await installAccessibilityNames(page);
-        let matched;
-        switch (data.condition) {
-            case 'url':
-                matched = equals(page.url());
-                break;
-            case 'title':
-                matched = equals(await page.title());
-                break;
-            case 'localStorage':
-            case 'sessionStorage':
-                matched = equals(await page.evaluate(({ kind, key }) => window[kind].getItem(key), { kind: data.condition, key: data.key }));
-                break;
-            case 'count':
-                matched = equals(await locator.count());
-                break;
-            case 'attached':
-                matched = await locator.count() > 0;
-                break;
-            case 'hidden':
-                matched = await locator.count() === 0 || await locator.isHidden();
-                break;
-            case 'visible':
-                matched = await locator.isVisible();
-                break;
-            default: {
-                if (await locator.count() !== 1)
-                    return false;
-                switch (data.condition) {
-                    case 'enabled':
-                        matched = await locator.isEnabled();
-                        break;
-                    case 'disabled':
-                        matched = await locator.isDisabled();
-                        break;
-                    case 'editable':
-                        matched = await locator.isEditable();
-                        break;
-                    case 'checked':
-                        matched = await locator.isChecked();
-                        break;
-                    case 'focused':
-                        matched = await locator.evaluate(element => element === element.ownerDocument.activeElement);
-                        break;
-                    case 'empty':
-                        matched = await locator.evaluate(element => (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement ? element.value : element.textContent || '').length === 0);
-                        break;
-                    case 'text':
-                        matched = equals((await locator.textContent())?.replace(/\s+/g, ' ').trim());
-                        break;
-                    case 'containsText': {
-                        const text = (await locator.textContent() || '').replace(/\s+/g, ' ').trim();
-                        matched = expected instanceof RegExp ? expected.test(text) : text.includes(String(expected));
-                        break;
+    const target = elementCondition ? (data.role ? `${data.role}${data.name === undefined ? '' : ' named ' + JSON.stringify(data.name)}` : data.selector) + (data.frame ? ` inside frame ${data.frame}` : '') : data.key ? `${data.condition} key ${JSON.stringify(data.key)}` : `page ${data.condition}`;
+    const needsSingle = elementCondition && !['count', 'attached'].includes(data.condition);
+    let latest = (0, assertion_result_1.reportAssertion)('assert.that', target, [{ key: 'target', label: 'Target lookup: ' + target, status: 'running' }, { key: 'condition', label: 'condition: ' + data.condition, status: 'not_evaluated' }], reporter, { status: 'running', timeout, elapsed: 0 });
+    let closed = false, lastReadError;
+    const progress = (checks) => {
+        if (closed)
+            return;
+        latest = (0, assertion_result_1.reportAssertion)('assert.that', target, checks, reporter, { status: 'running', timeout, elapsed: Date.now() - started });
+    };
+    try {
+        await (0, validation_1.poll)(async () => {
+            let count, roleCount, actual, matched = false, evaluated = false;
+            let sensitive = !!data.key && /password|passcode|token|secret|authorization|cookie|api.?key|otp/i.test(data.key);
+            lastReadError = undefined;
+            try {
+                if (elementCondition) {
+                    count = await locator.count();
+                    roleCount = data.role && data.name !== undefined && count === 0 ? await scope.getByRole(data.role).count() : count;
+                    if (count === 1 && (['value', 'values'].includes(data.condition) || data.attribute === 'value' || data.property === 'value')) {
+                        sensitive ||= await locator.evaluate(element => {
+                            const hints = ['type', 'name', 'id', 'autocomplete'].map(key => element.getAttribute(key) || '').join(' ');
+                            return /password|passcode|token|secret|authorization|cookie|api.?key|one-time-code|otp/i.test(hints);
+                        });
                     }
-                    case 'value':
-                        matched = equals(await locator.inputValue());
-                        break;
-                    case 'values':
-                        matched = equals(await locator.evaluate(element => Array.from(element.selectedOptions).map(option => option.value)));
-                        break;
-                    case 'attribute': {
-                        const value = await locator.getAttribute(data.attribute);
-                        matched = expected === undefined ? value !== null : equals(value);
-                        break;
+                }
+                if (!needsSingle || count === 1 || count === 0 && ['visible', 'hidden'].includes(data.condition)) {
+                    evaluated = true;
+                    if (['accessibleName', 'accessibleDescription'].includes(data.condition))
+                        await installAccessibilityNames(page);
+                    switch (data.condition) {
+                        case 'url':
+                            actual = page.url();
+                            matched = equals(actual);
+                            break;
+                        case 'title':
+                            actual = await page.title();
+                            matched = equals(actual);
+                            break;
+                        case 'localStorage':
+                        case 'sessionStorage':
+                            actual = await page.evaluate(({ kind, key }) => window[kind].getItem(key), { kind: data.condition, key: data.key });
+                            matched = equals(actual);
+                            break;
+                        case 'count':
+                            actual = count;
+                            matched = equals(actual);
+                            break;
+                        case 'attached':
+                            actual = count > 0;
+                            matched = actual === true;
+                            break;
+                        case 'hidden':
+                            actual = count === 0 || await locator.isHidden();
+                            matched = actual === true;
+                            break;
+                        case 'visible':
+                            actual = await locator.isVisible();
+                            matched = actual === true;
+                            break;
+                        case 'enabled':
+                            actual = await locator.isEnabled();
+                            matched = actual === true;
+                            break;
+                        case 'disabled':
+                            actual = await locator.isDisabled();
+                            matched = actual === true;
+                            break;
+                        case 'editable':
+                            actual = await locator.isEditable();
+                            matched = actual === true;
+                            break;
+                        case 'checked':
+                            actual = await locator.isChecked();
+                            matched = actual === true;
+                            break;
+                        case 'focused':
+                            actual = await locator.evaluate(element => element === element.ownerDocument.activeElement);
+                            matched = actual === true;
+                            break;
+                        case 'empty':
+                            actual = await locator.evaluate(element => (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement ? element.value : element.textContent || '').length === 0);
+                            matched = actual === true;
+                            break;
+                        case 'text':
+                            actual = (await locator.textContent())?.replace(/\s+/g, ' ').trim();
+                            matched = equals(actual);
+                            break;
+                        case 'containsText':
+                            actual = (await locator.textContent() || '').replace(/\s+/g, ' ').trim();
+                            matched = expected instanceof RegExp ? expected.test(String(actual)) : String(actual).includes(String(expected));
+                            break;
+                        case 'value':
+                            actual = await locator.inputValue();
+                            matched = equals(actual);
+                            break;
+                        case 'values':
+                            actual = await locator.evaluate(element => Array.from(element.selectedOptions).map(option => option.value));
+                            matched = equals(actual);
+                            break;
+                        case 'attribute':
+                            actual = await locator.getAttribute(data.attribute);
+                            matched = expected === undefined ? actual !== null : equals(actual);
+                            break;
+                        case 'id':
+                            actual = await locator.getAttribute('id');
+                            matched = equals(actual);
+                            break;
+                        case 'css':
+                            actual = await locator.evaluate((element, key) => getComputedStyle(element).getPropertyValue(key), data.property);
+                            matched = equals(actual);
+                            break;
+                        case 'property':
+                            actual = await locator.evaluate((element, key) => element[key], data.property);
+                            matched = equals(actual);
+                            break;
+                        case 'accessibleName':
+                        case 'accessibleDescription':
+                            actual = await locator.evaluate((element, condition) => { const api = element.ownerDocument.defaultView.__FLOWSTRIDE_ACCESSIBILITY_NAMES__; return condition === 'accessibleName' ? api.computeAccessibleName(element) : api.computeAccessibleDescription(element); }, data.condition);
+                            matched = equals(actual);
+                            break;
+                        case 'inViewport':
+                            actual = await locator.evaluate(element => { const box = element.getBoundingClientRect(); return box.width > 0 && box.height > 0 && box.bottom > 0 && box.right > 0 && box.top < innerHeight && box.left < innerWidth; });
+                            matched = actual === true;
+                            break;
                     }
-                    case 'id':
-                        matched = equals(await locator.getAttribute('id'));
-                        break;
-                    case 'css':
-                        matched = equals(await locator.evaluate((element, key) => getComputedStyle(element).getPropertyValue(key), data.property));
-                        break;
-                    case 'property':
-                        matched = equals(await locator.evaluate((element, key) => element[key], data.property));
-                        break;
-                    case 'accessibleName':
-                    case 'accessibleDescription':
-                        matched = equals(await locator.evaluate((element, condition) => {
-                            const api = element.ownerDocument.defaultView.__FLOWSTRIDE_ACCESSIBILITY_NAMES__;
-                            return condition === 'accessibleName' ? api.computeAccessibleName(element) : api.computeAccessibleDescription(element);
-                        }, data.condition));
-                        break;
-                    case 'inViewport':
-                        matched = await locator.evaluate(element => { const box = element.getBoundingClientRect(); return box.width > 0 && box.height > 0 && box.bottom > 0 && box.right > 0 && box.top < innerHeight && box.left < innerWidth; });
-                        break;
-                    default: throw new Error('Unknown assertion condition.');
+                    if (data.not)
+                        matched = !matched;
                 }
             }
-        }
-        return data.not ? !matched : matched;
-    }, timeout, `${data.condition} ${data.selector || data.role || data.key || ''}`);
+            catch (error) {
+                lastReadError = (0, assertion_result_1.diagnosticValue)(error instanceof Error ? error.message : String(error));
+                evaluated = false;
+                matched = false;
+            }
+            const checks = [];
+            if (elementCondition) {
+                const absenceAllowed = count === 0 && matched;
+                const lookup = { key: 'target', label: count === 0 && absenceAllowed ? 'Target absent as expected' : 'Target found: ' + target, status: count === undefined ? 'failed' : count > 0 || absenceAllowed ? 'passed' : data.condition === 'count' ? 'not_evaluated' : 'failed', actual: count === undefined ? 'Could not resolve the target' : `${count} matching target(s)` };
+                if (lastReadError && count === undefined)
+                    lookup.reason = lastReadError;
+                const part = (key, label, found) => ({ key, label, status: found === true ? 'passed' : absenceAllowed || count === undefined || data.condition === 'count' ? 'not_evaluated' : found === false ? 'failed' : 'not_evaluated' });
+                lookup.children = [];
+                if (data.role)
+                    lookup.children.push(part('role', 'role: ' + data.role, roleCount === undefined ? undefined : roleCount > 0));
+                if (data.name !== undefined)
+                    lookup.children.push(part('name', 'name: ' + data.name, count === undefined || !roleCount ? undefined : count > 0));
+                if (data.selector)
+                    lookup.children.push(part('selector', 'selector: ' + data.selector, count === undefined ? undefined : count > 0));
+                checks.push(lookup);
+                if (needsSingle && count !== 0)
+                    checks.push(count === undefined ? { key: 'unique', label: 'Exactly one matching target', status: 'not_evaluated' } : (0, assertion_result_1.assertionCheck)('unique', 'Exactly one matching target', count === 1, 1, count));
+                else if (needsSingle)
+                    checks.push({ key: 'unique', label: 'Exactly one matching target', status: 'not_evaluated', reason: absenceAllowed ? 'A matching element is not required for this condition.' : 'Target lookup did not find an element.' });
+            }
+            const opposites = { visible: 'not visible', hidden: 'visible', attached: 'absent', enabled: 'disabled', disabled: 'enabled', editable: 'not editable', checked: 'unchecked', empty: 'not empty', focused: 'not focused', inViewport: 'outside the viewport' };
+            const positiveLabel = { inViewport: 'inside the viewport' };
+            const wanted = sensitive ? '[REDACTED]' : booleanConditions.includes(data.condition) ? (data.not ? opposites[data.condition] : positiveLabel[data.condition] || data.condition) : data.condition === 'attribute' && expected === undefined ? 'present' : `${data.not ? 'not ' : ''}${expected instanceof RegExp ? expected.toString() : (0, assertion_result_1.diagnosticValue)(expected)}`;
+            const observed = sensitive ? '[REDACTED]' : booleanConditions.includes(data.condition) && typeof actual === 'boolean' ? (actual ? positiveLabel[data.condition] || data.condition : opposites[data.condition]) : (0, assertion_result_1.diagnosticValue)(actual);
+            checks.push(evaluated ? (0, assertion_result_1.assertionCheck)('condition', 'condition: ' + data.condition + (data.attribute ? ' ' + data.attribute : data.property ? ' ' + data.property : ''), matched, wanted, observed) : { key: 'condition', label: 'condition: ' + data.condition, status: 'not_evaluated', expected: wanted, reason: lastReadError || 'The target could not be resolved uniquely.' });
+            if (lastReadError && checks.at(-1))
+                checks.at(-1).reason = lastReadError;
+            progress(checks);
+            return evaluated && matched;
+        }, timeout, `${data.condition} ${target}`);
+        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: 'Assertion could be evaluated', status: 'failed', reason: lastReadError || result.reason });
+        reporter?.(result);
+        throw new assertion_result_1.AssertionFailure(result);
+    }
 }

package/dist/native/deadline.d.ts

@@ -0,0 +1,2 @@
+/** Only commands whose validated contract accepts a timeout may override it. */
+export declare function nativeStepTimeout(command: string, input: unknown, fallback: number): number;