@redrockswebdevelopment/formstack-form-testing 0.1.0 → 0.1.2

package/dist/index.js

@@ -7,6 +7,283 @@ export class FormBrowserDiagnosticsError extends Error {
         this.diagnostics = diagnostics;
     }
 }
+export class FormScenarioRunError extends Error {
+    result;
+    constructor(result) {
+        const failedStep = result.steps.find((step) => step.status === "failed");
+        super(failedStep ? `Form scenario "${result.name}" failed at step "${failedStep.name}": ${failedStep.error?.message ?? "unknown error"}` : `Form scenario "${result.name}" failed.`);
+        this.name = "FormScenarioRunError";
+        this.result = result;
+    }
+}
+export const liveFormFieldTypeCoverage = {
+    address: {
+        kind: "address",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Compound address values can be written through Live Form API, while layout and subfield UX should be asserted through DOM controls.",
+        recommendedHelpers: ["buildLiveFormAddressValue", "setLiveFormFieldValueTransaction", "fillAddress", "readLiveFormDomFieldState"],
+    },
+    checkbox: {
+        kind: "checkbox",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Checkbox values are stable when using option values. Multi-select UX should still dispatch DOM events or use DOM interaction.",
+        recommendedHelpers: ["buildLiveFormCheckboxValue", "setLiveFormFieldValueTransaction", "setCheckboxes", "waitForLiveFormQuiet"],
+    },
+    date: {
+        kind: "date",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Date API state can be set reliably, but split/calendar renderer variants should be verified through DOM assertions.",
+        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormFieldValueTransaction", "fillDateTime", "readLiveFormDomFieldState"],
+    },
+    datetime: {
+        kind: "datetime",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Date/time API state can be set, but visible split controls may lag or vary by renderer.",
+        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormFieldValueTransaction", "fillDateTime", "readLiveFormDomFieldState"],
+    },
+    description: {
+        kind: "description",
+        strategy: "assertion-only",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Description fields do not collect user values; test rendered content, visibility, and styling.",
+        recommendedHelpers: ["snapshotLiveFormDomFields", "waitForLiveFormVisibility"],
+    },
+    embed: {
+        kind: "embed",
+        strategy: "assertion-only",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Embed fields generally provide scripts/styles/markup; test side effects and diagnostics, not value writes.",
+        recommendedHelpers: ["createFormBrowserMonitor", "waitForConsoleMessage", "waitForWindowFlag", "snapshotLiveFormDomFields"],
+    },
+    email: {
+        kind: "email",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Email fields behave like text fields with validation-specific assertions.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillEmail", "waitForLiveFormValidationState"],
+    },
+    file: {
+        kind: "file",
+        strategy: "dom-only",
+        apiWrite: false,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "File fields must be tested through browser file upload controls, not generic Live Form API setValue payloads.",
+        recommendedHelpers: ["uploadFile", "liveFormFieldRecipes.uploadFileDom", "readLiveFormDomFieldState"],
+    },
+    matrix: {
+        kind: "matrix",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Matrix selections can be written by row/column labels or selected through DOM cells.",
+        recommendedHelpers: ["buildLiveFormMatrixValue", "setLiveFormFieldValueTransaction", "selectMatrixCell", "readLiveFormDomFieldState"],
+    },
+    name: {
+        kind: "name",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Name compound fields support direct API values and stable subfield DOM automation.",
+        recommendedHelpers: ["buildLiveFormNameValue", "setLiveFormFieldValueTransaction", "fillName", "readLiveFormReadiness"],
+    },
+    number: {
+        kind: "number",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Number fields use simple value payloads; use validation assertions for numeric constraints.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillNumber", "waitForLiveFormValidationState"],
+    },
+    pagebreak: {
+        kind: "pagebreak",
+        strategy: "layout-only",
+        apiWrite: false,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Page breaks do not collect values; test navigation, visible page state, and progress UI.",
+        recommendedHelpers: ["clickNext", "clickPrevious", "waitForLiveFormVisibility"],
+    },
+    payment: {
+        kind: "payment",
+        strategy: "excluded",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: false,
+        paymentRisk: true,
+        reason: "Payment fields are intentionally excluded from generic helpers because custom embedded code can trigger Formstack attestation and compliance review.",
+        recommendedHelpers: ["createFormBrowserMonitor"],
+    },
+    phone: {
+        kind: "phone",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Phone fields use simple value payloads; use DOM and validation assertions for formatting behavior.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillPhone", "waitForLiveFormValidationState"],
+    },
+    product: {
+        kind: "product",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Product API state can be set, but visible quantity and amount UI can diverge by product configuration.",
+        recommendedHelpers: ["buildLiveFormProductValue", "setLiveFormFieldValueTransaction", "fillProduct", "readLiveFormDomFieldState"],
+    },
+    radio: {
+        kind: "radio",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Radio fields are stable when using option values. Dispatch DOM change for custom scripts.",
+        recommendedHelpers: ["buildLiveFormChoiceValue", "setLiveFormFieldValueTransaction", "chooseRadio", "waitForLiveFormQuiet"],
+    },
+    rating: {
+        kind: "rating",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Rating values can be written through API, but visual stars/buttons should be asserted separately.",
+        recommendedHelpers: ["buildLiveFormRatingValue", "setLiveFormFieldValueTransaction", "setRating", "readLiveFormDomFieldState"],
+    },
+    section: {
+        kind: "section",
+        strategy: "layout-only",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Sections group content and logic visibility; test rendered content and conditional visibility.",
+        recommendedHelpers: ["snapshotLiveFormDomFields", "waitForLiveFormVisibility"],
+    },
+    select: {
+        kind: "select",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Select fields support stable option values through API or DOM select operations.",
+        recommendedHelpers: ["buildLiveFormSelectValue", "setLiveFormFieldValueTransaction", "selectOption", "readLiveFormDomFieldState"],
+    },
+    signature: {
+        kind: "signature",
+        strategy: "dom-only",
+        apiWrite: false,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Signature fields require specialized canvas/user-event automation; the portable helper safely supports clearing and DOM assertions.",
+        recommendedHelpers: ["clearSignature", "liveFormFieldRecipes.clearSignatureDom", "readLiveFormDomFieldState"],
+    },
+    textarea: {
+        kind: "textarea",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Textarea fields use simple value payloads and stable DOM fill operations.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillTextarea", "readLiveFormDomFieldState"],
+    },
+    text: {
+        kind: "text",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Text fields use simple value payloads and stable DOM fill operations.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillText", "readLiveFormDomFieldState"],
+    },
+    unknown: {
+        kind: "unknown",
+        strategy: "excluded",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: false,
+        reason: "Unknown fields need discovery before using generic automation.",
+        recommendedHelpers: ["discoverLiveFormFieldShapes", "snapshotLiveFormDomFields"],
+    },
+};
+export function getLiveFormFieldTypeCoverage(kind) {
+    return liveFormFieldTypeCoverage[kind];
+}
+export function summarizeLiveFormFieldCoverage(reportOrFields) {
+    const fields = "fields" in reportOrFields ? reportOrFields.fields : reportOrFields;
+    const countsByKind = {};
+    const fieldsWithCoverage = fields.map((field) => {
+        countsByKind[field.inferredKind] = (countsByKind[field.inferredKind] ?? 0) + 1;
+        return { ...field, coverage: getLiveFormFieldTypeCoverage(field.inferredKind) };
+    });
+    const uncovered = fields.filter((field) => field.inferredKind === "unknown");
+    const paymentFields = fields.filter((field) => field.inferredKind === "payment");
+    return {
+        fields: fieldsWithCoverage,
+        countsByKind,
+        uncovered,
+        paymentFields,
+        hasUnknownFields: uncovered.length > 0,
+        hasPaymentFields: paymentFields.length > 0,
+    };
+}
+export async function readLiveFormFieldCoverage(page, options = {}) {
+    return summarizeLiveFormFieldCoverage(await discoverLiveFormFieldShapes(page, options));
+}
+function formatCoverageField(field) {
+    return `${field.inferredKind}:${field.internalLabel ?? field.domId ?? "unlabeled"}`;
+}
+export function assertLiveFormFieldCoverage(report, options = {}) {
+    const failures = [];
+    if (!options.allowUnknown && report.hasUnknownFields) {
+        failures.push(`unknown fields: ${report.uncovered.map(formatCoverageField).join(", ")}`);
+    }
+    if (!options.allowPayment && report.hasPaymentFields) {
+        failures.push(`payment fields: ${report.paymentFields.map(formatCoverageField).join(", ")}`);
+    }
+    const allowedStrategies = new Set(options.allowedStrategies ?? []);
+    if (allowedStrategies.size > 0) {
+        const invalid = report.fields.filter((field) => !allowedStrategies.has(field.coverage.strategy));
+        if (invalid.length > 0) {
+            failures.push(`fields outside allowed strategies: ${invalid.map((field) => `${formatCoverageField(field)}=${field.coverage.strategy}`).join(", ")}`);
+        }
+    }
+    const disallowedStrategies = new Set(options.disallowedStrategies ?? []);
+    if (disallowedStrategies.size > 0) {
+        const invalid = report.fields.filter((field) => disallowedStrategies.has(field.coverage.strategy));
+        if (invalid.length > 0) {
+            failures.push(`fields using disallowed strategies: ${invalid.map((field) => `${formatCoverageField(field)}=${field.coverage.strategy}`).join(", ")}`);
+        }
+    }
+    for (const requiredKind of options.requiredKinds ?? []) {
+        if ((report.countsByKind[requiredKind] ?? 0) === 0) {
+            failures.push(`missing required field kind: ${requiredKind}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(`Live form field coverage assertion failed: ${failures.join("; ")}`);
+    }
+}
 function matchesPattern(value, pattern) {
     return typeof pattern === "string" ? value.includes(pattern) : pattern.test(value);
 }
@@ -103,6 +380,2126 @@ export function createFormBrowserMonitor(page, options = {}) {
         },
     };
 }
+function hasEvaluate(page) {
+    return typeof page.evaluate === "function";
+}
+export function readValuePath(value, path) {
+    if (!path)
+        return value;
+    return path.split(".").reduce((current, segment) => {
+        if (current === null || current === undefined || typeof current !== "object")
+            return undefined;
+        return Reflect.get(current, segment);
+    }, value);
+}
+export function isLiveFormFieldValueEmpty(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.trim().length === 0;
+    if (typeof value === "number" || typeof value === "boolean")
+        return false;
+    if (Array.isArray(value))
+        return value.length === 0 || value.every((item) => isLiveFormFieldValueEmpty(item));
+    if (typeof value === "object") {
+        const meaningfulValues = Object.entries(value).filter(([key]) => key !== "otherValue");
+        return meaningfulValues.length === 0 || meaningfulValues.every(([, item]) => isLiveFormFieldValueEmpty(item));
+    }
+    return false;
+}
+export function buildLiveFormNameValue(value, current = {}) {
+    return {
+        ...(current && typeof current === "object" ? current : {}),
+        ...value,
+    };
+}
+export function buildLiveFormAddressValue(value, current = {}) {
+    return {
+        ...(current && typeof current === "object" ? current : {}),
+        ...value,
+    };
+}
+export function buildLiveFormChoiceValue(value, otherValue = "") {
+    return { value, otherValue };
+}
+export function buildLiveFormSelectValue(value) {
+    return { value };
+}
+export function buildLiveFormCheckboxValue(values, otherValue = null) {
+    return Object.fromEntries([...values.map((value, index) => [String(index), value]), ["otherValue", otherValue]]);
+}
+export function buildLiveFormDateTimeValue(value, current = {}) {
+    return {
+        ...(current && typeof current === "object" ? current : {}),
+        ...(value.month !== undefined ? { M: value.month } : {}),
+        ...(value.day !== undefined ? { D: value.day } : {}),
+        ...(value.year !== undefined ? { Y: value.year } : {}),
+        ...(value.hour !== undefined ? { H: value.hour } : {}),
+        ...(value.minutes !== undefined ? { I: value.minutes } : {}),
+        ...(value.seconds !== undefined ? { S: value.seconds } : {}),
+        ...(value.ampm !== undefined ? { A: value.ampm } : {}),
+    };
+}
+export function buildLiveFormProductValue(value, current = {}) {
+    return {
+        ...(current && typeof current === "object" ? current : {}),
+        ...value,
+    };
+}
+export function buildLiveFormRatingValue(value) {
+    return { value: String(value) };
+}
+export function buildLiveFormMatrixValue(selections) {
+    return {
+        value: selections.map((selection) => {
+            if (typeof selection === "string")
+                return selection;
+            return `${selection.row} = ${selection.column}`;
+        }),
+    };
+}
+export async function readLiveFormFieldValue(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormFieldValue requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (readOptions) => {
+        const waitForApiTimeoutMs = readOptions.waitForApiTimeoutMs ?? 10_000;
+        const readPath = (value, path) => {
+            if (!path)
+                return value;
+            return path.split(".").reduce((current, segment) => {
+                if (current === null || current === undefined || typeof current !== "object")
+                    return undefined;
+                return Reflect.get(current, segment);
+            }, value);
+        };
+        const isEmpty = (value) => {
+            if (value === null || value === undefined)
+                return true;
+            if (typeof value === "string")
+                return value.trim().length === 0;
+            if (typeof value === "number" || typeof value === "boolean")
+                return false;
+            if (Array.isArray(value))
+                return value.length === 0 || value.every((item) => isEmpty(item));
+            if (typeof value === "object") {
+                const meaningfulValues = Object.entries(value).filter(([key]) => key !== "otherValue");
+                return meaningfulValues.length === 0 || meaningfulValues.every(([, item]) => isEmpty(item));
+            }
+            return false;
+        };
+        const valuesEqual = (left, right) => {
+            if (Object.is(left, right))
+                return true;
+            try {
+                return JSON.stringify(left) === JSON.stringify(right);
+            }
+            catch {
+                return false;
+            }
+        };
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const deadline = Date.now() + waitForApiTimeoutMs;
+        let form = null;
+        while (Date.now() < deadline) {
+            form = readApi().form;
+            if (form && typeof form === "object")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const apiAvailable = Boolean(form && typeof form === "object");
+        if (!apiAvailable || !form || typeof form !== "object") {
+            return {
+                apiAvailable: false,
+                fieldAvailable: false,
+                id: null,
+                value: null,
+                selectedValue: null,
+                ...(readOptions.valuePath === undefined ? {} : { valuePath: readOptions.valuePath }),
+                ...(readOptions.expectedValue === undefined ? {} : { expectedValue: readOptions.expectedValue, valueMatched: false }),
+                isEmpty: true,
+            };
+        }
+        const getField = Reflect.get(form, "getField");
+        const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+        const field = readOptions.target.fieldId != null && typeof getField === "function"
+            ? Reflect.apply(getField, form, [String(readOptions.target.fieldId)])
+            : readOptions.target.internalLabel && typeof getFieldByInternalLabel === "function"
+                ? Reflect.apply(getFieldByInternalLabel, form, [readOptions.target.internalLabel])
+                : null;
+        const fieldAvailable = Boolean(field && typeof field === "object");
+        if (!fieldAvailable || !field || typeof field !== "object") {
+            return {
+                apiAvailable: true,
+                fieldAvailable: false,
+                id: null,
+                value: null,
+                selectedValue: null,
+                ...(readOptions.valuePath === undefined ? {} : { valuePath: readOptions.valuePath }),
+                ...(readOptions.expectedValue === undefined ? {} : { expectedValue: readOptions.expectedValue, valueMatched: false }),
+                isEmpty: true,
+            };
+        }
+        const getId = Reflect.get(field, "getId");
+        const getValue = Reflect.get(field, "getValue");
+        const id = typeof getId === "function" ? Reflect.apply(getId, field, []) : Reflect.get(field, "id") ?? null;
+        const value = typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+        const selectedValue = readPath(value, readOptions.valuePath);
+        return {
+            apiAvailable: true,
+            fieldAvailable: true,
+            id,
+            value,
+            selectedValue,
+            ...(readOptions.valuePath === undefined ? {} : { valuePath: readOptions.valuePath }),
+            ...(readOptions.expectedValue === undefined ? {} : { expectedValue: readOptions.expectedValue, valueMatched: valuesEqual(selectedValue, readOptions.expectedValue) }),
+            isEmpty: isEmpty(selectedValue),
+        };
+    }, options);
+}
+export async function waitForLiveFormFieldValue(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormFieldValue(page, options);
+    const isMatched = (report) => options.expectedValue === undefined ? report.fieldAvailable && !report.isEmpty : report.valueMatched === true;
+    while (!isMatched(latest) && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormFieldValue(page, options);
+    }
+    return latest;
+}
+export async function readLiveFormReadiness(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormReadiness requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (readinessOptions) => {
+        const fieldTargets = readinessOptions.fieldTargets ?? [];
+        const waitForApiTimeoutMs = readinessOptions.waitForApiTimeoutMs ?? 10_000;
+        const readPath = (value, path) => {
+            if (!path)
+                return value;
+            return path.split(".").reduce((current, segment) => {
+                if (current === null || current === undefined || typeof current !== "object")
+                    return undefined;
+                return Reflect.get(current, segment);
+            }, value);
+        };
+        const isEmpty = (value) => {
+            if (value === null || value === undefined)
+                return true;
+            if (typeof value === "string")
+                return value.trim().length === 0;
+            if (typeof value === "number" || typeof value === "boolean")
+                return false;
+            if (Array.isArray(value))
+                return value.length === 0 || value.every((item) => isEmpty(item));
+            if (typeof value === "object") {
+                const meaningfulValues = Object.entries(value).filter(([key]) => key !== "otherValue");
+                return meaningfulValues.length === 0 || meaningfulValues.every(([, item]) => isEmpty(item));
+            }
+            return false;
+        };
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const deadline = Date.now() + waitForApiTimeoutMs;
+        let form = null;
+        while (Date.now() < deadline) {
+            form = readApi().form;
+            if (form && typeof form === "object")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const apiAvailable = Boolean(form && typeof form === "object");
+        if (!apiAvailable || !form || typeof form !== "object") {
+            return {
+                apiAvailable: false,
+                fields: [],
+                blockingFieldCount: 0,
+                isReady: false,
+            };
+        }
+        const getFieldTarget = (target) => {
+            const getField = Reflect.get(form, "getField");
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            if (target.fieldId != null && typeof getField === "function")
+                return Reflect.apply(getField, form, [String(target.fieldId)]);
+            if (target.internalLabel && typeof getFieldByInternalLabel === "function") {
+                return Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel]);
+            }
+            return null;
+        };
+        const snapshotField = (field, target) => {
+            if (!field || typeof field !== "object") {
+                const required = target.required ?? true;
+                return {
+                    target,
+                    available: false,
+                    id: null,
+                    value: null,
+                    required,
+                    apiHidden: false,
+                    hidden: false,
+                    domVisible: null,
+                    requiredValuePaths: target.requiredValuePaths ?? [],
+                    missingValuePaths: target.requiredValuePaths ?? [],
+                    isComplete: false,
+                    isBlocking: required,
+                };
+            }
+            const getId = Reflect.get(field, "getId");
+            const getValue = Reflect.get(field, "getValue");
+            const getGeneralAttribute = Reflect.get(field, "getGeneralAttribute");
+            let value = null;
+            let required = target.required ?? false;
+            let apiHidden = false;
+            try {
+                value = typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+            }
+            catch {
+                value = null;
+            }
+            try {
+                if (typeof getGeneralAttribute === "function") {
+                    required = target.required ?? Reflect.apply(getGeneralAttribute, field, ["required"]) === true;
+                    apiHidden = Reflect.apply(getGeneralAttribute, field, ["hidden"]) === true;
+                }
+            }
+            catch {
+                required = target.required ?? false;
+            }
+            const id = typeof getId === "function" ? Reflect.apply(getId, field, []) : Reflect.get(field, "id") ?? null;
+            const idRoot = id == null
+                ? null
+                : document.querySelector(`#fsCell${CSS.escape(String(id))}, #fsFieldCell${CSS.escape(String(id))}, [data-testid="field-${CSS.escape(String(id))}"]`);
+            const domRoot = idRoot ?? (target.internalLabel != null
+                ? document.querySelector(`[data-internal-label="${CSS.escape(target.internalLabel)}"]`)
+                : null);
+            const isActuallyVisible = (element) => {
+                if (!(element instanceof HTMLElement))
+                    return null;
+                for (let current = element; current; current = current.parentElement) {
+                    const style = getComputedStyle(current);
+                    const rect = current.getBoundingClientRect();
+                    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0)
+                        return false;
+                    if (rect.width <= 0 || rect.height <= 0)
+                        return false;
+                }
+                return element.getClientRects().length > 0;
+            };
+            const domVisible = isActuallyVisible(domRoot);
+            const hidden = apiHidden || domVisible === false;
+            const requiredValuePaths = target.requiredValuePaths ?? [];
+            const missingValuePaths = requiredValuePaths.length > 0
+                ? requiredValuePaths.filter((path) => isEmpty(readPath(value, path)))
+                : isEmpty(value)
+                    ? [""]
+                    : [];
+            const isComplete = missingValuePaths.length === 0;
+            const isBlocking = required && !hidden && !isComplete;
+            return {
+                target,
+                available: true,
+                id,
+                value,
+                required,
+                apiHidden,
+                hidden,
+                domVisible,
+                requiredValuePaths,
+                missingValuePaths,
+                isComplete,
+                isBlocking,
+            };
+        };
+        const fields = [];
+        if (readinessOptions.includeAllFields) {
+            const getFields = Reflect.get(form, "getFields");
+            const allFields = typeof getFields === "function" ? Reflect.apply(getFields, form, []) : [];
+            if (Array.isArray(allFields)) {
+                for (const field of allFields)
+                    fields.push(snapshotField(field, { label: "all-fields" }));
+            }
+        }
+        for (const target of fieldTargets) {
+            fields.push(snapshotField(getFieldTarget(target), target));
+        }
+        const blockingFieldCount = fields.filter((field) => field.isBlocking).length;
+        return {
+            apiAvailable: true,
+            fields,
+            blockingFieldCount,
+            isReady: blockingFieldCount === 0,
+        };
+    }, options);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function waitForLiveFormReadiness(page, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormReadiness(page, options);
+    while (!latest.isReady && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormReadiness(page, options);
+    }
+    return latest;
+}
+export async function waitForLiveFormQuiet(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("waitForLiveFormQuiet requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (quietOptions) => {
+        const startedAt = typeof performance === "undefined" ? Date.now() : performance.now();
+        const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+        const quietMs = quietOptions.quietMs ?? 250;
+        const timeoutMs = quietOptions.timeoutMs ?? 5_000;
+        const waitForApiTimeoutMs = quietOptions.waitForApiTimeoutMs ?? 2_000;
+        const eventTypes = quietOptions.eventTypes ?? ["input", "change", "blur", "click", "submit"];
+        const formEventTypes = quietOptions.formEventTypes ?? ["change", "calculations-complete", "validation-complete", "submit", "error"];
+        const observeMutations = quietOptions.observeMutations ?? true;
+        const mutationSelector = quietOptions.mutationSelector ?? "form, [id^='fsForm-'], body";
+        const includeEvents = quietOptions.includeEvents ?? true;
+        const events = [];
+        let lastEventAt = now();
+        const elapsedMs = () => Math.round(now() - startedAt);
+        const record = (kind, type, detail) => {
+            lastEventAt = now();
+            if (includeEvents) {
+                events.push({
+                    kind,
+                    type,
+                    elapsedMs: elapsedMs(),
+                    detail,
+                });
+            }
+        };
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const apiDeadline = Date.now() + waitForApiTimeoutMs;
+        let form = null;
+        while (Date.now() < apiDeadline) {
+            form = readApi().form;
+            if (form && typeof form === "object")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const apiAvailable = Boolean(form && typeof form === "object");
+        const domListener = (event) => {
+            const target = event.target instanceof Element ? event.target : null;
+            record("dom-event", event.type, {
+                targetId: target?.getAttribute("id") ?? null,
+                targetName: target?.getAttribute("name") ?? null,
+                internalLabel: target?.closest("[data-internal-label]")?.getAttribute("data-internal-label") ?? null,
+            });
+        };
+        for (const eventType of eventTypes)
+            document.addEventListener(eventType, domListener, true);
+        const mutationTarget = document.querySelector(mutationSelector) ?? document.body;
+        const mutationObserver = observeMutations && typeof MutationObserver !== "undefined" && mutationTarget
+            ? new MutationObserver((mutations) => {
+                const mutationTypes = [...new Set(mutations.map((mutation) => mutation.type))];
+                const changedFieldLabels = [
+                    ...new Set(mutations
+                        .flatMap((mutation) => [mutation.target, ...Array.from(mutation.addedNodes), ...Array.from(mutation.removedNodes)])
+                        .filter((node) => node instanceof Element)
+                        .map((element) => element.closest("[data-internal-label]")?.getAttribute("data-internal-label"))
+                        .filter((label) => Boolean(label))),
+                ].slice(0, 20);
+                record("mutation", "mutation", {
+                    count: mutations.length,
+                    types: mutationTypes,
+                    changedFieldLabels,
+                });
+            })
+            : null;
+        mutationObserver?.observe(mutationTarget, {
+            attributes: true,
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributeFilter: ["class", "style", "aria-invalid", "hidden", "data-internal-label"],
+        });
+        const formEventListeners = apiAvailable && form && typeof form === "object"
+            ? formEventTypes.map((type) => ({
+                type,
+                onFormEvent: (event) => {
+                    const eventObject = event && typeof event === "object" ? event : {};
+                    record("form-event", type, {
+                        formId: Reflect.get(eventObject, "formId") ?? null,
+                        data: Reflect.get(eventObject, "data") ?? null,
+                    });
+                },
+            }))
+            : [];
+        const registerFormEventListener = apiAvailable && form && typeof form === "object" ? Reflect.get(form, "registerFormEventListener") : null;
+        const unregisterFormEventListener = apiAvailable && form && typeof form === "object" ? Reflect.get(form, "unregisterFormEventListener") : null;
+        if (typeof registerFormEventListener === "function") {
+            for (const listener of formEventListeners)
+                Reflect.apply(registerFormEventListener, form, [listener]);
+        }
+        const deadline = Date.now() + timeoutMs;
+        try {
+            while (Date.now() < deadline) {
+                const quietForMs = Math.round(now() - lastEventAt);
+                if (quietForMs >= quietMs) {
+                    return {
+                        apiAvailable,
+                        quiet: true,
+                        timedOut: false,
+                        elapsedMs: elapsedMs(),
+                        quietForMs,
+                        eventCount: events.length,
+                        ...(includeEvents ? { events } : {}),
+                    };
+                }
+                await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(quietMs - quietForMs, 10))));
+            }
+            return {
+                apiAvailable,
+                quiet: false,
+                timedOut: true,
+                elapsedMs: elapsedMs(),
+                quietForMs: Math.round(now() - lastEventAt),
+                eventCount: events.length,
+                ...(includeEvents ? { events } : {}),
+            };
+        }
+        finally {
+            for (const eventType of eventTypes)
+                document.removeEventListener(eventType, domListener, true);
+            mutationObserver?.disconnect();
+            if (typeof unregisterFormEventListener === "function") {
+                for (const listener of formEventListeners)
+                    Reflect.apply(unregisterFormEventListener, form, [listener]);
+            }
+        }
+    }, options);
+}
+export async function installLiveFormInitialValidationGuard(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("installLiveFormInitialValidationGuard requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (guardOptions) => {
+        const waitForApiTimeoutMs = guardOptions.waitForApiTimeoutMs ?? 10_000;
+        const restoreDelayMs = guardOptions.restoreDelayMs ?? 700;
+        const restoreOnFirstFocusout = guardOptions.restoreOnFirstFocusout ?? true;
+        const guardedFields = [];
+        const missingTargets = [];
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const deadline = Date.now() + waitForApiTimeoutMs;
+        let form = null;
+        while (Date.now() < deadline) {
+            form = readApi().form;
+            if (form && typeof form === "object")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const apiAvailable = Boolean(form && typeof form === "object");
+        if (!apiAvailable || !form || typeof form !== "object") {
+            return {
+                apiAvailable: false,
+                installed: false,
+                guardedFieldCount: 0,
+                missingTargets: guardOptions.targets,
+            };
+        }
+        const resolveField = (target) => {
+            const getField = Reflect.get(form, "getField");
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            if (target.fieldId != null && typeof getField === "function")
+                return Reflect.apply(getField, form, [String(target.fieldId)]);
+            if (target.internalLabel && typeof getFieldByInternalLabel === "function") {
+                return Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel]);
+            }
+            return null;
+        };
+        const readSkipValidation = (field) => {
+            if (!field || typeof field !== "object")
+                return undefined;
+            const getGeneralAttribute = Reflect.get(field, "getGeneralAttribute");
+            return typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, ["shouldForceSkipValidation"]) : undefined;
+        };
+        const setSkipValidation = (field, value) => {
+            if (!field || typeof field !== "object")
+                return;
+            const setGeneralAttribute = Reflect.get(field, "setGeneralAttribute");
+            if (typeof setGeneralAttribute === "function")
+                Reflect.apply(setGeneralAttribute, field, ["shouldForceSkipValidation", value]);
+        };
+        for (const target of guardOptions.targets) {
+            const field = resolveField(target);
+            if (!field || typeof field !== "object") {
+                missingTargets.push(target);
+                continue;
+            }
+            guardedFields.push({ field, target, previousValue: readSkipValidation(field) });
+            setSkipValidation(field, true);
+        }
+        const restore = () => {
+            for (const entry of guardedFields)
+                setSkipValidation(entry.field, entry.previousValue === true);
+            document.removeEventListener("focusout", onFocusout, true);
+            Reflect.deleteProperty(window, "__fsptInitialValidationGuardRestore");
+        };
+        const matchesTarget = (element, target) => {
+            if (target.controlIds?.some((id) => element.id === id || element.closest(`#${CSS.escape(id)}`)))
+                return true;
+            if (target.controlSelectors?.some((selector) => element.matches(selector) || element.closest(selector)))
+                return true;
+            if (target.internalLabel && element.closest(`[data-internal-label="${CSS.escape(target.internalLabel)}"]`))
+                return true;
+            if (target.fieldId != null && element.closest(`#fsCell${CSS.escape(String(target.fieldId))}`))
+                return true;
+            return false;
+        };
+        function onFocusout(event) {
+            if (!restoreOnFirstFocusout || !(event.target instanceof Element))
+                return;
+            if (!guardOptions.targets.some((target) => matchesTarget(event.target, target)))
+                return;
+            window.setTimeout(restore, restoreDelayMs);
+        }
+        Object.defineProperty(window, "__fsptInitialValidationGuardRestore", {
+            configurable: true,
+            value: restore,
+        });
+        if (restoreOnFirstFocusout)
+            document.addEventListener("focusout", onFocusout, true);
+        return {
+            apiAvailable: true,
+            installed: guardedFields.length > 0,
+            guardedFieldCount: guardedFields.length,
+            missingTargets,
+        };
+    }, options);
+}
+export async function setLiveFormFieldValue(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("setLiveFormFieldValue requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (writeOptions) => {
+        const timeoutMs = writeOptions.timeoutMs ?? 5_000;
+        const intervalMs = writeOptions.intervalMs ?? 50;
+        const settleMs = writeOptions.settleMs ?? 100;
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const valuesEqual = (left, right) => {
+            if (Object.is(left, right))
+                return true;
+            try {
+                return JSON.stringify(left) === JSON.stringify(right);
+            }
+            catch {
+                return false;
+            }
+        };
+        const readFieldValue = (field) => {
+            if (!field || typeof field !== "object")
+                return null;
+            const getValue = Reflect.get(field, "getValue");
+            return typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+        };
+        const resolveField = (form) => {
+            if (!form || typeof form !== "object")
+                return null;
+            const getField = Reflect.get(form, "getField");
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            if (writeOptions.target.fieldId != null && typeof getField === "function") {
+                return Reflect.apply(getField, form, [String(writeOptions.target.fieldId)]);
+            }
+            if (writeOptions.target.internalLabel && typeof getFieldByInternalLabel === "function") {
+                return Reflect.apply(getFieldByInternalLabel, form, [writeOptions.target.internalLabel]);
+            }
+            return null;
+        };
+        const { form } = readApi();
+        const apiAvailable = Boolean(form && typeof form === "object");
+        if (!apiAvailable || !form || typeof form !== "object") {
+            return {
+                apiAvailable: false,
+                fieldAvailable: false,
+                id: null,
+                previousValue: null,
+                expectedValue: writeOptions.value,
+                finalValue: null,
+                valueMatched: false,
+                notified: false,
+            };
+        }
+        const field = resolveField(form);
+        const fieldAvailable = Boolean(field && typeof field === "object");
+        if (!fieldAvailable || !field || typeof field !== "object") {
+            return {
+                apiAvailable: true,
+                fieldAvailable: false,
+                id: null,
+                previousValue: null,
+                expectedValue: writeOptions.value,
+                finalValue: null,
+                valueMatched: false,
+                notified: false,
+            };
+        }
+        const setValue = Reflect.get(field, "setValue");
+        const previousValue = readFieldValue(field);
+        if (typeof setValue !== "function") {
+            return {
+                apiAvailable: true,
+                fieldAvailable: true,
+                id: Reflect.get(field, "id") ?? null,
+                previousValue,
+                expectedValue: writeOptions.value,
+                finalValue: previousValue,
+                valueMatched: false,
+                notified: false,
+            };
+        }
+        await Promise.resolve(Reflect.apply(setValue, field, [writeOptions.value]));
+        let finalValue = readFieldValue(field);
+        if (writeOptions.waitForValue ?? true) {
+            const deadline = Date.now() + timeoutMs;
+            while (!valuesEqual(finalValue, writeOptions.value) && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, intervalMs));
+                finalValue = readFieldValue(field);
+            }
+        }
+        if (settleMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, settleMs));
+        let notifyResult = null;
+        if (writeOptions.notify) {
+            const notifyFormEventListeners = Reflect.get(form, "notifyFormEventListeners");
+            notifyResult =
+                typeof notifyFormEventListeners === "function"
+                    ? await Promise.resolve(Reflect.apply(notifyFormEventListeners, form, [
+                        "change",
+                        {
+                            fieldId: Reflect.get(field, "id") ?? null,
+                            type: "api-setValue",
+                            value: writeOptions.value,
+                        },
+                    ]))
+                    : null;
+        }
+        finalValue = readFieldValue(field);
+        return {
+            apiAvailable: true,
+            fieldAvailable: true,
+            id: Reflect.get(field, "id") ?? null,
+            previousValue,
+            expectedValue: writeOptions.value,
+            finalValue,
+            valueMatched: valuesEqual(finalValue, writeOptions.value),
+            notified: writeOptions.notify === true,
+            ...(writeOptions.notify ? { notifyResult } : {}),
+        };
+    }, options);
+}
+export async function snapshotLiveFormDomFields(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("snapshotLiveFormDomFields requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((snapshotOptions) => {
+        const selector = snapshotOptions.selector ?? "[data-internal-label]";
+        const textMaxLength = snapshotOptions.textMaxLength ?? 160;
+        return Array.from(document.querySelectorAll(selector)).map((element) => ({
+            internalLabel: element.getAttribute("data-internal-label"),
+            id: element.id,
+            text: element.textContent?.replace(/\s+/g, " ").trim().slice(0, textMaxLength) ?? "",
+            controls: Array.from(element.querySelectorAll("input, textarea, select")).map((control) => {
+                const input = control;
+                return {
+                    tagName: control.tagName.toLowerCase(),
+                    type: control.getAttribute("type"),
+                    id: control.getAttribute("id"),
+                    name: control.getAttribute("name"),
+                    value: control.getAttribute("value"),
+                    currentValue: "value" in input ? input.value : null,
+                    checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? control.checked : null,
+                };
+            }),
+        }));
+    }, options);
+}
+export async function readLiveFormDomFieldState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormDomFieldState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const controlSnapshot = (control) => {
+            const input = control;
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type: control.getAttribute("type"),
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: control.getAttribute("value"),
+                currentValue: "value" in input ? input.value : null,
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? control.checked : null,
+            };
+        };
+        const root = stateOptions.selector != null
+            ? document.querySelector(stateOptions.selector)
+            : stateOptions.internalLabel != null
+                ? document.querySelector(`[data-internal-label="${CSS.escape(stateOptions.internalLabel)}"]`)
+                : stateOptions.fieldId == null
+                    ? null
+                    : document.querySelector(`#fsCell${CSS.escape(String(stateOptions.fieldId))}, #fsFieldCell${CSS.escape(String(stateOptions.fieldId))}, [data-testid="field-${CSS.escape(String(stateOptions.fieldId))}"]`);
+        const fieldMatched = Boolean(root);
+        const field = root
+            ? {
+                internalLabel: root.getAttribute("data-internal-label"),
+                id: root.id,
+                text: root.textContent?.replace(/\s+/g, " ").trim().slice(0, 160) ?? "",
+                controls: Array.from(root.querySelectorAll("input, textarea, select")).map(controlSnapshot),
+            }
+            : null;
+        const controls = root == null
+            ? []
+            : Array.from(root.querySelectorAll(stateOptions.controlSelector ?? "input, textarea, select")).map(controlSnapshot);
+        const controlMatched = controls.some((control) => {
+            const valueMatched = stateOptions.expectedValue === undefined || control.currentValue === stateOptions.expectedValue || control.value === stateOptions.expectedValue;
+            const checkedMatched = stateOptions.expectedChecked === undefined || control.checked === stateOptions.expectedChecked;
+            return valueMatched && checkedMatched;
+        });
+        return {
+            matched: fieldMatched && controlMatched,
+            fieldMatched,
+            controlMatched,
+            field,
+            controls,
+            ...(stateOptions.expectedValue === undefined ? {} : { expectedValue: stateOptions.expectedValue }),
+            ...(stateOptions.expectedChecked === undefined ? {} : { expectedChecked: stateOptions.expectedChecked }),
+        };
+    }, options);
+}
+export async function waitForLiveFormDomFieldState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormDomFieldState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormDomFieldState(page, options);
+    }
+    return latest;
+}
+export async function dispatchLiveFormFieldDomEvents(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("dispatchLiveFormFieldDomEvents requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((dispatchOptions) => {
+        const eventTypes = dispatchOptions.eventTypes ?? ["input", "change"];
+        const root = dispatchOptions.target.internalLabel != null
+            ? document.querySelector(`[data-internal-label="${CSS.escape(dispatchOptions.target.internalLabel)}"]`)
+            : dispatchOptions.target.fieldId == null
+                ? null
+                : document.querySelector(`#fsCell${CSS.escape(String(dispatchOptions.target.fieldId))}, [data-testid="field-${CSS.escape(String(dispatchOptions.target.fieldId))}"]`);
+        const allControls = root ? Array.from(root.querySelectorAll("input, textarea, select")) : [];
+        const controls = dispatchOptions.onlyCheckedChoices ?? true
+            ? allControls.filter((control) => {
+                if (control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type))
+                    return control.checked;
+                if (control instanceof HTMLInputElement && control.type === "hidden")
+                    return false;
+                return true;
+            })
+            : allControls;
+        for (const control of controls) {
+            for (const type of eventTypes) {
+                control.dispatchEvent(new Event(type, { bubbles: true }));
+            }
+        }
+        return {
+            matchedControlCount: controls.length,
+            dispatchedEventCount: controls.length * eventTypes.length,
+            controls: controls.map((control) => ({
+                tagName: control.tagName.toLowerCase(),
+                type: control.getAttribute("type"),
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: control.getAttribute("value"),
+                currentValue: "value" in control ? control.value : null,
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type) ? control.checked : null,
+            })),
+        };
+    }, options);
+}
+export async function installWindowMessageRecorder(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("installWindowMessageRecorder requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((recorderOptions) => {
+        const propertyName = recorderOptions.propertyName ?? "__fsptWindowMessages";
+        const allowedOrigins = recorderOptions.allowedOrigins ?? [];
+        const records = [];
+        const listener = (event) => {
+            if (allowedOrigins.length > 0 && !allowedOrigins.includes(event.origin))
+                return;
+            records.push({
+                origin: event.origin,
+                data: event.data,
+            });
+        };
+        window.addEventListener("message", listener);
+        Object.defineProperty(window, propertyName, {
+            configurable: true,
+            value: {
+                records,
+                dispose: () => window.removeEventListener("message", listener),
+                clear: () => {
+                    records.length = 0;
+                },
+            },
+        });
+        return { installed: true, propertyName };
+    }, options);
+}
+export async function readWindowMessageRecords(page, propertyName = "__fsptWindowMessages") {
+    if (!hasEvaluate(page)) {
+        throw new Error("readWindowMessageRecords requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((name) => {
+        const recorder = Reflect.get(window, name);
+        return Array.isArray(recorder?.records) ? [...recorder.records] : [];
+    }, propertyName);
+}
+export async function clearWindowMessageRecords(page, propertyName = "__fsptWindowMessages") {
+    if (!hasEvaluate(page)) {
+        throw new Error("clearWindowMessageRecords requires a Playwright page with evaluate().");
+    }
+    await page.evaluate((name) => {
+        const recorder = Reflect.get(window, name);
+        if (typeof recorder?.clear === "function")
+            recorder.clear();
+    }, propertyName);
+}
+export async function postMessageToIframe(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("postMessageToIframe requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((postOptions) => {
+        const iframe = document.querySelector(postOptions.iframeSelector);
+        if (!(iframe instanceof HTMLIFrameElement) || !iframe.contentWindow)
+            return false;
+        iframe.contentWindow.postMessage(postOptions.message, postOptions.targetOrigin);
+        return true;
+    }, options);
+}
+export function buildFormstackIframeBridgeMessage(message) {
+    return message;
+}
+export async function waitForWindowMessage(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("waitForWindowMessage requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (waitOptions) => {
+        const startedAt = typeof performance === "undefined" ? Date.now() : performance.now();
+        const propertyName = waitOptions.propertyName ?? "__fsptWindowMessages";
+        const timeoutMs = waitOptions.timeoutMs ?? 5_000;
+        const deadline = Date.now() + timeoutMs;
+        const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+        const matches = (record) => {
+            const data = record.data && typeof record.data === "object" ? record.data : {};
+            if (waitOptions.channel && Reflect.get(data, "channel") !== waitOptions.channel)
+                return false;
+            if (waitOptions.requestId && Reflect.get(data, "requestId") !== waitOptions.requestId)
+                return false;
+            if (waitOptions.type && Reflect.get(data, "type") !== waitOptions.type)
+                return false;
+            return true;
+        };
+        while (Date.now() < deadline) {
+            const recorder = Reflect.get(window, propertyName);
+            const records = Array.isArray(recorder?.records) ? recorder.records : [];
+            const record = records.find(matches);
+            if (record) {
+                return {
+                    matched: true,
+                    timedOut: false,
+                    elapsedMs: Math.round(now() - startedAt),
+                    record,
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        return {
+            matched: false,
+            timedOut: true,
+            elapsedMs: Math.round(now() - startedAt),
+        };
+    }, options);
+}
+export async function sendFormstackIframeBridgeMessage(page, options) {
+    await installWindowMessageRecorder(page, {
+        ...(options.propertyName === undefined ? {} : { propertyName: options.propertyName }),
+        ...(options.allowedOrigins === undefined ? {} : { allowedOrigins: options.allowedOrigins }),
+    });
+    const posted = await postMessageToIframe(page, {
+        iframeSelector: options.iframeSelector,
+        targetOrigin: options.targetOrigin,
+        message: buildFormstackIframeBridgeMessage({
+            channel: options.channel,
+            requestId: options.requestId,
+            type: options.type,
+            ...(options.payload === undefined ? {} : { payload: options.payload }),
+        }),
+    });
+    const response = await waitForWindowMessage(page, {
+        channel: options.channel,
+        requestId: options.requestId,
+        type: options.responseType ?? `${options.type}:response`,
+        ...(options.propertyName === undefined ? {} : { propertyName: options.propertyName }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    });
+    return { posted, response };
+}
+export async function waitForConsoleMessage(page, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let settled = false;
+        const cleanup = () => {
+            page.off?.("console", handler);
+        };
+        const finish = (report) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(report);
+        };
+        const handler = (message) => {
+            const type = message.type();
+            const text = message.text();
+            if (options.type && type !== options.type)
+                return;
+            if (options.text && !matchesPattern(text, options.text))
+                return;
+            finish({
+                matched: true,
+                timedOut: false,
+                elapsedMs: Date.now() - startedAt,
+                message: { type, text },
+            });
+        };
+        page.on("console", handler);
+        setTimeout(() => {
+            finish({
+                matched: false,
+                timedOut: true,
+                elapsedMs: Date.now() - startedAt,
+            });
+        }, timeoutMs);
+    });
+}
+export async function waitForWindowFlag(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("waitForWindowFlag requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (flagOptions) => {
+        const startedAt = Date.now();
+        const timeoutMs = flagOptions.timeoutMs ?? 5_000;
+        const intervalMs = flagOptions.intervalMs ?? 50;
+        const deadline = Date.now() + timeoutMs;
+        const read = () => flagOptions.path.split(".").reduce((current, segment) => {
+            if (current === null || current === undefined || typeof current !== "object")
+                return undefined;
+            return Reflect.get(current, segment);
+        }, window);
+        const matches = (value) => {
+            if (flagOptions.expectedValue === undefined)
+                return Boolean(value);
+            return Object.is(value, flagOptions.expectedValue);
+        };
+        let value = read();
+        while (!matches(value) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            value = read();
+        }
+        const matched = matches(value);
+        return {
+            matched,
+            timedOut: !matched,
+            elapsedMs: Date.now() - startedAt,
+            path: flagOptions.path,
+            value,
+        };
+    }, options);
+}
+export async function readLiveFormValidationState(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormValidationState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (validationOptions) => {
+        const factory = Reflect.get(window, "fsApi");
+        const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+        const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+        const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+        const form = Array.isArray(forms) ? forms[0] ?? null : null;
+        const apiAvailable = Boolean(form && typeof form === "object");
+        let result = null;
+        if (validationOptions.validate && apiAvailable && form && typeof form === "object") {
+            const validateForm = Reflect.get(form, "validateForm");
+            result = typeof validateForm === "function" ? await Promise.resolve(Reflect.apply(validateForm, form, [])) : null;
+        }
+        const isVisible = (element) => {
+            if (!(element instanceof HTMLElement))
+                return false;
+            for (let current = element; current; current = current.parentElement) {
+                const style = getComputedStyle(current);
+                const rect = current.getBoundingClientRect();
+                if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0)
+                    return false;
+                if (rect.width <= 0 || rect.height <= 0)
+                    return false;
+            }
+            return element.getClientRects().length > 0;
+        };
+        const inlineErrors = Array.from(document.querySelectorAll('[id^="inline-error-field"], .fsError, [role="alert"]'))
+            .map((element) => ({
+            id: element.getAttribute("id"),
+            text: element.textContent?.replace(/\s+/g, " ").trim().slice(0, 240) ?? "",
+            visible: isVisible(element),
+        }))
+            .filter((error) => validationOptions.includeEmptyErrors === true || error.text.length > 0)
+            .filter((error) => validationOptions.includeHiddenErrors === true || error.visible)
+            .map(({ id, text }) => ({ id, text }));
+        return {
+            apiAvailable,
+            validated: validationOptions.validate === true,
+            result,
+            inlineErrors,
+        };
+    }, options);
+}
+export async function waitForLiveFormValidationState(page, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    const matches = (state) => {
+        if (options.expectNoErrors === true)
+            return state.inlineErrors.length === 0;
+        if (options.expectedErrorCount !== undefined && state.inlineErrors.length !== options.expectedErrorCount)
+            return false;
+        if (options.errorText !== undefined) {
+            const errorText = options.errorText;
+            return state.inlineErrors.some((error) => typeof errorText === "string" ? error.text.includes(errorText) : errorText.test(error.text));
+        }
+        return state.inlineErrors.length > 0;
+    };
+    let latest = await readLiveFormValidationState(page, options);
+    while (!matches(latest) && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormValidationState(page, options);
+    }
+    return latest;
+}
+export async function waitForLiveFormVisibility(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("waitForLiveFormVisibility requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (visibilityOptions) => {
+        const timeoutMs = visibilityOptions.timeoutMs ?? 5_000;
+        const intervalMs = visibilityOptions.intervalMs ?? 50;
+        const deadline = Date.now() + timeoutMs;
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return Array.isArray(forms) ? forms[0] ?? null : null;
+        };
+        const snapshot = () => {
+            const form = readApi();
+            return visibilityOptions.targets.map((target) => {
+                let id = target.fieldId ?? null;
+                if (!id && form && typeof form === "object" && target.internalLabel) {
+                    const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+                    const field = typeof getFieldByInternalLabel === "function"
+                        ? Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel])
+                        : null;
+                    id = field && typeof field === "object" ? Reflect.get(field, "id") ?? null : null;
+                }
+                const idRoot = id == null
+                    ? null
+                    : document.querySelector(`#fsCell${CSS.escape(String(id))}, #fsFieldCell${CSS.escape(String(id))}, [data-testid="field-${CSS.escape(String(id))}"]`);
+                const root = target.selector != null
+                    ? document.querySelector(target.selector)
+                    : idRoot ?? (target.internalLabel != null
+                        ? document.querySelector(`[data-internal-label="${CSS.escape(target.internalLabel)}"]`)
+                        : null);
+                const visible = root instanceof HTMLElement
+                    ? (() => {
+                        for (let current = root; current; current = current.parentElement) {
+                            const style = getComputedStyle(current);
+                            const rect = current.getBoundingClientRect();
+                            if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0)
+                                return false;
+                            if (rect.width <= 0 || rect.height <= 0)
+                                return false;
+                        }
+                        return root.getClientRects().length > 0;
+                    })()
+                    : null;
+                return {
+                    target,
+                    id,
+                    visible,
+                    matched: visible === target.visible,
+                };
+            });
+        };
+        let fields = snapshot();
+        while (!fields.every((field) => field.matched) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            fields = snapshot();
+        }
+        const matched = fields.every((field) => field.matched);
+        return {
+            matched,
+            timedOut: !matched,
+            fields,
+        };
+    }, options);
+}
+export async function readLiveFormStateDrift(page, options = {}) {
+    const readiness = await readLiveFormReadiness(page, options);
+    const domFields = await snapshotLiveFormDomFields(page, options.snapshot ?? {});
+    const domByLabel = new Map(domFields.map((field) => [field.internalLabel, field]));
+    const issues = [];
+    for (const field of readiness.fields) {
+        const label = field.target.internalLabel ?? null;
+        const domField = label ? domByLabel.get(label) : undefined;
+        if (field.available && label && !domField) {
+            issues.push({
+                internalLabel: label,
+                fieldId: field.id,
+                kind: "missing-dom",
+                message: "Field is available through Live Form API but no matching data-internal-label root was found in the DOM.",
+            });
+        }
+        if (!field.available && domField) {
+            issues.push({
+                internalLabel: label,
+                fieldId: field.id,
+                kind: "missing-api",
+                message: "Field root exists in the DOM but the Live Form API target was not available.",
+            });
+        }
+        if (field.domVisible !== null && field.hidden === field.domVisible) {
+            issues.push({
+                internalLabel: label,
+                fieldId: field.id,
+                kind: "visibility",
+                message: "Effective hidden state does not align with DOM visibility.",
+            });
+        }
+    }
+    return {
+        readiness,
+        domFields,
+        issues,
+        hasDrift: issues.length > 0,
+    };
+}
+export async function discoverLiveFormFieldShapes(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("discoverLiveFormFieldShapes requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((discoverOptions) => {
+        const selector = discoverOptions.selector ?? "[data-internal-label]";
+        const includeValues = discoverOptions.includeValues ?? true;
+        const factory = Reflect.get(window, "fsApi");
+        const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+        const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+        const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+        const form = Array.isArray(forms) ? forms[0] ?? null : null;
+        const apiAvailable = Boolean(form && typeof form === "object");
+        const getApiField = (internalLabel) => {
+            if (!internalLabel || !form || typeof form !== "object")
+                return null;
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            return typeof getFieldByInternalLabel === "function"
+                ? Reflect.apply(getFieldByInternalLabel, form, [internalLabel])
+                : null;
+        };
+        const controlSnapshot = (control) => {
+            const input = control;
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type: control.getAttribute("type"),
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: control.getAttribute("value"),
+                currentValue: "value" in input ? input.value : null,
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? control.checked : null,
+            };
+        };
+        const inferKind = (element, controls) => {
+            const text = element.textContent?.toLowerCase() ?? "";
+            const classes = element.className.toString().toLowerCase();
+            const types = new Set(controls.map((control) => control.type ?? control.tagName));
+            const internalLabel = element.getAttribute("data-internal-label")?.toLowerCase() ?? "";
+            const id = element.getAttribute("id")?.toLowerCase() ?? "";
+            const dataTestId = element.getAttribute("data-testid")?.toLowerCase() ?? "";
+            if (internalLabel.includes("payment") ||
+                internalLabel.includes("credit_card") ||
+                internalLabel.includes("credit-card") ||
+                classes.includes("payment") ||
+                text.includes("credit card") ||
+                controls.some((control) => control.name?.toLowerCase().includes("payment") || control.name?.toLowerCase().includes("credit"))) {
+                return "payment";
+            }
+            if (internalLabel.includes("code_embed") || text.startsWith(":root{") || text.includes("<script"))
+                return "embed";
+            if (controls.length === 0) {
+                if (classes.includes("pagebreak") || classes.includes("page-break") || dataTestId.includes("pagebreak") || id.includes("pagebreak")) {
+                    return "pagebreak";
+                }
+                if (classes.includes("description") || internalLabel.includes("description") || dataTestId.includes("description")) {
+                    return "description";
+                }
+                return "section";
+            }
+            if (classes.includes("matrix") || internalLabel.includes("matrix") || element.querySelector("[id^='matrix-row-'], table"))
+                return "matrix";
+            if (classes.includes("rating") || internalLabel.includes("rating"))
+                return "rating";
+            if (classes.includes("signature") || internalLabel.includes("signature"))
+                return "signature";
+            if (classes.includes("product") || internalLabel.includes("product") || types.has("product"))
+                return "product";
+            if (classes.includes("address") || controls.some((control) => control.id?.includes("-address")))
+                return "address";
+            if (classes.includes("name") || controls.some((control) => control.id?.includes("-first") || control.id?.includes("-last")))
+                return "name";
+            if (types.has("checkbox"))
+                return "checkbox";
+            if (types.has("radio"))
+                return "radio";
+            if (types.has("file"))
+                return "file";
+            if (controls.some((control) => control.tagName === "select"))
+                return "select";
+            if (controls.some((control) => control.tagName === "textarea"))
+                return "textarea";
+            if (types.has("email"))
+                return "email";
+            if (types.has("tel"))
+                return "phone";
+            if (types.has("number") || internalLabel.includes("number"))
+                return "number";
+            if (internalLabel.includes("date_time") || internalLabel.includes("datetime") || text.includes("am/pm") || text.includes("minutes"))
+                return "datetime";
+            if (types.has("date") || internalLabel.includes("date"))
+                return "date";
+            if (types.has("text"))
+                return "text";
+            return "unknown";
+        };
+        const isActuallyVisible = (element) => {
+            if (!(element instanceof HTMLElement))
+                return false;
+            for (let current = element; current; current = current.parentElement) {
+                const style = getComputedStyle(current);
+                const rect = current.getBoundingClientRect();
+                if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0)
+                    return false;
+                if (rect.width <= 0 || rect.height <= 0)
+                    return false;
+            }
+            return element.getClientRects().length > 0;
+        };
+        const fields = Array.from(document.querySelectorAll(selector)).map((element) => {
+            const internalLabel = element.getAttribute("data-internal-label");
+            const apiField = getApiField(internalLabel);
+            const getValue = apiField && typeof apiField === "object" ? Reflect.get(apiField, "getValue") : null;
+            const getGeneralAttribute = apiField && typeof apiField === "object" ? Reflect.get(apiField, "getGeneralAttribute") : null;
+            const apiValue = includeValues && typeof getValue === "function" ? Reflect.apply(getValue, apiField, []) : undefined;
+            const apiHidden = typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, apiField, ["hidden"]) === true : undefined;
+            const controls = Array.from(element.querySelectorAll("input, textarea, select")).map(controlSnapshot);
+            const domVisible = isActuallyVisible(element);
+            return {
+                internalLabel,
+                fieldId: apiField && typeof apiField === "object" ? Reflect.get(apiField, "id") ?? null : null,
+                domId: element.id,
+                labelText: element.textContent?.replace(/\s+/g, " ").trim().slice(0, 160) ?? "",
+                apiAvailable: Boolean(apiField && typeof apiField === "object"),
+                ...(includeValues ? { apiValue } : {}),
+                ...(apiHidden === undefined ? {} : { apiHidden }),
+                domVisible,
+                controlCount: controls.length,
+                controlTypes: [...new Set(controls.map((control) => control.type ?? control.tagName))],
+                inferredKind: inferKind(element, controls),
+                controls,
+            };
+        });
+        return { apiAvailable, fields };
+    }, options);
+}
+export async function submitWithLiveFormLifecycleProbe(page, options = {}) {
+    const submitSelector = options.submitSelector ?? formstackSelectors.submitButton;
+    return runWithLiveFormLifecycleProbe(page, options, async () => {
+        try {
+            await page.locator(submitSelector).first().click(options.clickTimeoutMs === undefined ? undefined : { timeout: options.clickTimeoutMs });
+            return { clicked: true };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (hasEvaluate(page)) {
+                await page.evaluate((detail) => {
+                    const probe = Reflect.get(window, "__fsptLiveFormLifecycleProbe");
+                    if (typeof probe?.record === "function")
+                        probe.record("submit-error", detail);
+                }, { message, phase: "click" });
+            }
+            if (options.throwOnClickFailure ?? false)
+                throw error;
+            return { clicked: false, error: message };
+        }
+    });
+}
+export async function probeLiveFormLifecycle(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("probeLiveFormLifecycle requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (probeOptions) => {
+        const startedAt = typeof performance === "undefined" ? Date.now() : performance.now();
+        const eventTypes = probeOptions.eventTypes ?? ["input", "change", "blur", "focus", "click", "submit"];
+        const events = [];
+        const fieldTargets = probeOptions.fieldTargets ?? [];
+        const waitForApiTimeoutMs = probeOptions.waitForApiTimeoutMs ?? 10_000;
+        const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+        const record = (kind, detail) => {
+            const at = now();
+            const event = {
+                kind,
+                at,
+                elapsedMs: Math.round(at - startedAt),
+                detail,
+            };
+            events.push(event);
+            return event;
+        };
+        const safeText = (value) => {
+            const text = value?.replace(/\s+/g, " ").trim() ?? "";
+            return text ? text.slice(0, 180) : null;
+        };
+        const selectorForElement = (target) => {
+            if (!(target instanceof Element))
+                return null;
+            const id = target.getAttribute("id");
+            if (id)
+                return `#${CSS.escape(id)}`;
+            const name = target.getAttribute("name");
+            if (name)
+                return `[name="${CSS.escape(name)}"]`;
+            const internalLabel = target.closest("[data-internal-label]")?.getAttribute("data-internal-label");
+            if (internalLabel)
+                return `[data-internal-label="${CSS.escape(internalLabel)}"]`;
+            return target.tagName.toLowerCase();
+        };
+        const serializeControl = (control) => {
+            const input = control;
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type: control instanceof HTMLInputElement ? input.type : null,
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: "value" in input ? input.value : null,
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? control.checked : null,
+                disabled: "disabled" in input ? input.disabled : null,
+                required: "required" in input ? input.required : null,
+                ariaInvalid: control.getAttribute("aria-invalid"),
+            };
+        };
+        const listener = (event) => {
+            const target = event.target;
+            const element = target instanceof Element ? target : null;
+            const fieldRoot = element?.closest("[data-internal-label], [id^='fsCell'], [data-testid^='field-']");
+            const fsCell = element?.closest("[id^='fsCell']");
+            const idDerivedField = element?.getAttribute("id")?.match(/^field(\d+)/)?.[1] ?? null;
+            record("dom-event", {
+                type: event.type,
+                selector: selectorForElement(target),
+                fieldId: fieldRoot?.getAttribute("data-fs-field-id") ??
+                    fsCell?.id?.replace(/^fsCell/, "") ??
+                    idDerivedField ??
+                    fieldRoot?.id?.replace(/^fsCell/, "") ??
+                    null,
+                internalLabel: fieldRoot?.getAttribute("data-internal-label") ?? null,
+                control: element ? serializeControl(element) : null,
+            });
+        };
+        for (const type of eventTypes) {
+            document.addEventListener(type, listener, true);
+        }
+        record("probe-installed", {
+            eventTypes,
+            fieldTargetCount: fieldTargets.length,
+        });
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { api, form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const deadline = Date.now() + waitForApiTimeoutMs;
+        let apiAvailable = false;
+        let form = null;
+        while (Date.now() < deadline) {
+            const resolved = readApi();
+            form = resolved.form;
+            if (form && typeof form === "object") {
+                apiAvailable = true;
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        if (apiAvailable) {
+            const getFields = Reflect.get(form, "getFields");
+            const rawFields = typeof getFields === "function" ? Reflect.apply(getFields, form, []) : [];
+            record("fs-api-ready", {
+                fieldCount: Array.isArray(rawFields) ? rawFields.length : null,
+                methods: Object.keys(form).filter((key) => typeof Reflect.get(form, key) === "function").sort(),
+            });
+        }
+        else {
+            record("fs-api-timeout", { timeoutMs: waitForApiTimeoutMs });
+        }
+        const getFieldTarget = (target) => {
+            if (!apiAvailable || !form || typeof form !== "object")
+                return null;
+            const getField = Reflect.get(form, "getField");
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            if (target.fieldId != null && typeof getField === "function")
+                return Reflect.apply(getField, form, [String(target.fieldId)]);
+            if (target.internalLabel && typeof getFieldByInternalLabel === "function") {
+                return Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel]);
+            }
+            return null;
+        };
+        const snapshotField = (field, target) => {
+            if (!field || typeof field !== "object") {
+                record("field-snapshot", { target, available: false });
+                return;
+            }
+            const getId = Reflect.get(field, "getId");
+            const getValue = Reflect.get(field, "getValue");
+            const getFieldInfo = Reflect.get(field, "getFieldInfo");
+            const getGeneralAttribute = Reflect.get(field, "getGeneralAttribute");
+            const setValue = Reflect.get(field, "setValue");
+            let value = null;
+            let info = null;
+            let required = null;
+            let hidden = null;
+            let skipValidation = null;
+            try {
+                value = typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+            }
+            catch (error) {
+                value = { error: error instanceof Error ? error.message : String(error) };
+            }
+            try {
+                info = typeof getFieldInfo === "function" ? Reflect.apply(getFieldInfo, field, []) : null;
+            }
+            catch {
+                info = null;
+            }
+            try {
+                required = typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, ["required"]) : null;
+                hidden = typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, ["hidden"]) : null;
+                skipValidation =
+                    typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, ["shouldForceSkipValidation"]) : null;
+            }
+            catch {
+                required = null;
+            }
+            record("field-snapshot", {
+                target,
+                available: true,
+                id: typeof getId === "function" ? Reflect.apply(getId, field, []) : null,
+                hasSetValue: typeof setValue === "function",
+                value,
+                info,
+                required,
+                hidden,
+                shouldForceSkipValidation: skipValidation,
+            });
+        };
+        if (apiAvailable && form && typeof form === "object") {
+            if (probeOptions.includeAllFields) {
+                const getFields = Reflect.get(form, "getFields");
+                const fields = typeof getFields === "function" ? Reflect.apply(getFields, form, []) : [];
+                if (Array.isArray(fields)) {
+                    for (const field of fields)
+                        snapshotField(field, { label: "all-fields" });
+                }
+            }
+            for (const target of fieldTargets) {
+                snapshotField(getFieldTarget(target), target);
+            }
+        }
+        if (probeOptions.validate && apiAvailable && form && typeof form === "object") {
+            const validateForm = Reflect.get(form, "validateForm");
+            try {
+                const result = typeof validateForm === "function" ? await Promise.resolve(Reflect.apply(validateForm, form, [])) : null;
+                record("validation-result", { result });
+            }
+            catch (error) {
+                record("validation-error", { message: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        if (probeOptions.submit && apiAvailable && form && typeof form === "object") {
+            const submitForm = Reflect.get(form, "submitForm");
+            try {
+                const result = typeof submitForm === "function" ? await Promise.resolve(Reflect.apply(submitForm, form, [])) : null;
+                record("submit-invoked", { result });
+            }
+            catch (error) {
+                record("submit-error", { message: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        for (const type of eventTypes) {
+            document.removeEventListener(type, listener, true);
+        }
+        const validation = events.find((event) => event.kind === "validation-result" || event.kind === "validation-error");
+        const submit = events.find((event) => event.kind === "submit-invoked" || event.kind === "submit-error");
+        return {
+            apiAvailable,
+            events,
+            fieldSnapshots: events.filter((event) => event.kind === "field-snapshot"),
+            ...(validation ? { validation } : {}),
+            ...(submit ? { submit } : {}),
+        };
+    }, options);
+}
+export async function runWithLiveFormLifecycleProbe(page, options, run) {
+    if (!hasEvaluate(page)) {
+        throw new Error("runWithLiveFormLifecycleProbe requires a Playwright page with evaluate().");
+    }
+    await page.evaluate(async (probeOptions) => {
+        const startedAt = typeof performance === "undefined" ? Date.now() : performance.now();
+        const eventTypes = probeOptions.eventTypes ?? ["input", "change", "blur", "focus", "click", "submit"];
+        const formEventTypes = probeOptions.formEventTypes ?? [];
+        const waitForApiTimeoutMs = probeOptions.waitForApiTimeoutMs ?? 10_000;
+        const events = [];
+        const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+        const record = (kind, detail) => {
+            const at = now();
+            const event = { kind, at, elapsedMs: Math.round(at - startedAt), detail };
+            events.push(event);
+            return event;
+        };
+        const controlValue = (element) => {
+            if (!element)
+                return null;
+            const input = element;
+            return {
+                tagName: element.tagName.toLowerCase(),
+                type: element instanceof HTMLInputElement ? input.type : null,
+                id: element.getAttribute("id"),
+                name: element.getAttribute("name"),
+                value: "value" in input ? input.value : null,
+                checked: element instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? element.checked : null,
+                ariaInvalid: element.getAttribute("aria-invalid"),
+            };
+        };
+        const listener = (event) => {
+            const element = event.target instanceof Element ? event.target : null;
+            const fieldRoot = element?.closest("[data-internal-label], [id^='fsCell'], [data-testid^='field-']");
+            const fsCell = element?.closest("[id^='fsCell']");
+            const idDerivedField = element?.getAttribute("id")?.match(/^field(\d+)/)?.[1] ?? null;
+            record("dom-event", {
+                type: event.type,
+                fieldId: fieldRoot?.getAttribute("data-fs-field-id") ??
+                    fsCell?.id?.replace(/^fsCell/, "") ??
+                    idDerivedField ??
+                    fieldRoot?.id?.replace(/^fsCell/, "") ??
+                    null,
+                internalLabel: fieldRoot?.getAttribute("data-internal-label") ?? null,
+                control: controlValue(element),
+            });
+        };
+        for (const type of eventTypes)
+            document.addEventListener(type, listener, true);
+        record("probe-installed", { eventTypes, formEventTypes });
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const deadline = Date.now() + waitForApiTimeoutMs;
+        let form = null;
+        while (formEventTypes.length > 0 && Date.now() < deadline) {
+            form = readApi().form;
+            if (form && typeof form === "object")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const formEventListeners = formEventTypes.length > 0 && form && typeof form === "object"
+            ? formEventTypes.map((type) => ({
+                type,
+                onFormEvent: (event) => {
+                    const eventObject = event && typeof event === "object" ? event : {};
+                    record("form-event", {
+                        type,
+                        formId: Reflect.get(eventObject, "formId") ?? null,
+                        data: Reflect.get(eventObject, "data") ?? null,
+                        hasPreventDefault: typeof Reflect.get(eventObject, "preventDefault") === "function",
+                    });
+                },
+            }))
+            : [];
+        if (form && typeof form === "object" && formEventListeners.length > 0) {
+            const registerFormEventListener = Reflect.get(form, "registerFormEventListener");
+            if (typeof registerFormEventListener === "function") {
+                for (const formEventListener of formEventListeners) {
+                    Reflect.apply(registerFormEventListener, form, [formEventListener]);
+                }
+            }
+        }
+        Object.defineProperty(window, "__fsptLiveFormLifecycleProbe", {
+            configurable: true,
+            value: {
+                events,
+                eventTypes,
+                formEventListeners,
+                listener,
+                record,
+            },
+        });
+    }, options);
+    const result = await run();
+    const report = await page.evaluate(async (probeOptions) => {
+        const postRunSettleMs = probeOptions.postRunSettleMs ?? 100;
+        if (postRunSettleMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, postRunSettleMs));
+        const probe = Reflect.get(window, "__fsptLiveFormLifecycleProbe");
+        if (!probe) {
+            return {
+                apiAvailable: false,
+                events: [],
+                fieldSnapshots: [],
+            };
+        }
+        if (probeOptions.postRunQuietMs !== undefined) {
+            const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+            const quietMs = probeOptions.postRunQuietMs;
+            const quietTimeoutMs = probeOptions.postRunQuietTimeoutMs ?? 2_500;
+            const deadline = Date.now() + quietTimeoutMs;
+            let timedOut = false;
+            while (Date.now() < deadline) {
+                const lastEvent = probe.events.at(-1);
+                const elapsedSinceLastEvent = lastEvent ? now() - lastEvent.at : quietMs;
+                if (elapsedSinceLastEvent >= quietMs)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, Math.max(10, Math.min(50, quietMs - elapsedSinceLastEvent))));
+            }
+            const lastEvent = probe.events.at(-1);
+            if (lastEvent && now() - lastEvent.at < quietMs)
+                timedOut = true;
+            probe.record("quiet-wait", {
+                quietMs,
+                timeoutMs: quietTimeoutMs,
+                timedOut,
+                lastEventKind: lastEvent?.kind ?? null,
+                lastEventElapsedMs: lastEvent?.elapsedMs ?? null,
+            });
+        }
+        const factory = Reflect.get(window, "fsApi");
+        const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+        const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+        const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+        const form = Array.isArray(forms) ? forms[0] ?? null : null;
+        const apiAvailable = Boolean(form && typeof form === "object");
+        if (apiAvailable && form && typeof form === "object") {
+            const getFields = Reflect.get(form, "getFields");
+            const fields = typeof getFields === "function" ? Reflect.apply(getFields, form, []) : [];
+            probe.record("fs-api-ready", {
+                fieldCount: Array.isArray(fields) ? fields.length : null,
+            });
+            const targets = probeOptions.includeAllFields && Array.isArray(fields) ? fields : [];
+            for (const field of targets) {
+                const getId = Reflect.get(field, "getId");
+                const getGeneralAttribute = Reflect.get(field, "getGeneralAttribute");
+                const getValue = Reflect.get(field, "getValue");
+                const getFieldInfo = Reflect.get(field, "getFieldInfo");
+                const keys = Object.keys(field).sort();
+                const methodNames = keys.filter((key) => typeof Reflect.get(field, key) === "function");
+                const idCandidates = [];
+                for (const candidate of ["id", "fieldId", "_id"])
+                    idCandidates.push(Reflect.get(field, candidate));
+                try {
+                    if (typeof getId === "function")
+                        idCandidates.push(Reflect.apply(getId, field, []));
+                }
+                catch {
+                    idCandidates.push("getId:error");
+                }
+                try {
+                    if (typeof getGeneralAttribute === "function")
+                        idCandidates.push(Reflect.apply(getGeneralAttribute, field, ["id"]));
+                }
+                catch {
+                    idCandidates.push("getGeneralAttribute:id:error");
+                }
+                let value = null;
+                let info = null;
+                try {
+                    value = typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+                }
+                catch (error) {
+                    value = { error: error instanceof Error ? error.message : String(error) };
+                }
+                try {
+                    info = typeof getFieldInfo === "function" ? Reflect.apply(getFieldInfo, field, []) : null;
+                }
+                catch {
+                    info = null;
+                }
+                probe.record("field-snapshot", {
+                    id: idCandidates.find((candidate) => candidate !== undefined && candidate !== null && candidate !== "") ?? null,
+                    idCandidates,
+                    keys,
+                    methodNames,
+                    value,
+                    info,
+                });
+            }
+            if (probeOptions.validate) {
+                const validateForm = Reflect.get(form, "validateForm");
+                try {
+                    const validation = typeof validateForm === "function" ? await Promise.resolve(Reflect.apply(validateForm, form, [])) : null;
+                    const inlineErrors = Array.from(document.querySelectorAll('[id^="inline-error-field"], .fsError, [role="alert"]')).map((element) => ({
+                        id: element.getAttribute("id"),
+                        text: element.textContent?.replace(/\s+/g, " ").trim().slice(0, 240) ?? "",
+                    }));
+                    probe.record("validation-result", { result: validation, inlineErrors });
+                }
+                catch (error) {
+                    probe.record("validation-error", { message: error instanceof Error ? error.message : String(error) });
+                }
+            }
+        }
+        if (apiAvailable && form && typeof form === "object" && Array.isArray(probe.formEventListeners)) {
+            const unregisterFormEventListener = Reflect.get(form, "unregisterFormEventListener");
+            if (typeof unregisterFormEventListener === "function") {
+                for (const formEventListener of probe.formEventListeners) {
+                    Reflect.apply(unregisterFormEventListener, form, [formEventListener]);
+                }
+            }
+        }
+        for (const type of probe.eventTypes)
+            document.removeEventListener(type, probe.listener, true);
+        Reflect.deleteProperty(window, "__fsptLiveFormLifecycleProbe");
+        const validation = probe.events.find((event) => event.kind === "validation-result" || event.kind === "validation-error");
+        const submit = probe.events.find((event) => event.kind === "submit-invoked" || event.kind === "submit-error");
+        return {
+            apiAvailable,
+            events: probe.events,
+            fieldSnapshots: probe.events.filter((event) => event.kind === "field-snapshot"),
+            ...(validation ? { validation } : {}),
+            ...(submit ? { submit } : {}),
+        };
+    }, options);
+    return { result, report };
+}
+export async function waitForLiveFormEvent(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("waitForLiveFormEvent requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (waitOptions) => {
+        const startedAt = typeof performance === "undefined" ? Date.now() : performance.now();
+        const timeoutMs = waitOptions.timeoutMs ?? 5_000;
+        const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return { form: Array.isArray(forms) ? forms[0] ?? null : null };
+        };
+        const deadline = Date.now() + timeoutMs;
+        let form = null;
+        while (Date.now() < deadline) {
+            form = readApi().form;
+            if (form && typeof form === "object")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const elapsedMs = () => Math.round(now() - startedAt);
+        if (!form || typeof form !== "object") {
+            return {
+                matched: false,
+                timedOut: true,
+                elapsedMs: elapsedMs(),
+            };
+        }
+        const findField = (target) => {
+            if (!target)
+                return null;
+            const byInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            if (target.internalLabel && typeof byInternalLabel === "function") {
+                const field = Reflect.apply(byInternalLabel, form, [target.internalLabel]);
+                if (field)
+                    return field;
+            }
+            const getFields = Reflect.get(form, "getFields");
+            const fields = typeof getFields === "function" ? Reflect.apply(getFields, form, []) : [];
+            if (!Array.isArray(fields))
+                return null;
+            const targetFieldId = target.fieldId == null ? null : String(target.fieldId);
+            return (fields.find((field) => {
+                if (!field || typeof field !== "object")
+                    return false;
+                const fieldId = Reflect.get(field, "id");
+                return targetFieldId !== null && String(fieldId) === targetFieldId;
+            }) ?? null);
+        };
+        const targetField = findField(waitOptions.target);
+        const targetFieldId = targetField && typeof targetField === "object"
+            ? Reflect.get(targetField, "id") ?? null
+            : waitOptions.target?.fieldId ?? null;
+        const targetFieldIdString = targetFieldId == null ? null : String(targetFieldId);
+        const registerFormEventListener = Reflect.get(form, "registerFormEventListener");
+        const unregisterFormEventListener = Reflect.get(form, "unregisterFormEventListener");
+        if (typeof registerFormEventListener !== "function") {
+            return {
+                matched: false,
+                timedOut: true,
+                elapsedMs: elapsedMs(),
+                targetFieldId,
+            };
+        }
+        let matchedEvent;
+        let resolveWait;
+        const wait = new Promise((resolve) => {
+            resolveWait = resolve;
+        });
+        const timeout = setTimeout(() => resolveWait?.(), Math.max(0, deadline - Date.now()));
+        const listeners = waitOptions.eventTypes.map((type) => ({
+            type,
+            onFormEvent: (event) => {
+                const eventObject = event && typeof event === "object" ? event : {};
+                const data = Reflect.get(eventObject, "data");
+                const dataFieldId = data && typeof data === "object" ? Reflect.get(data, "fieldId") : null;
+                const dataType = data && typeof data === "object" ? Reflect.get(data, "type") : null;
+                const fieldMatches = targetFieldIdString === null || String(dataFieldId ?? "") === targetFieldIdString;
+                const dataTypeMatches = !waitOptions.dataType || dataType === waitOptions.dataType;
+                if (!fieldMatches || !dataTypeMatches || matchedEvent)
+                    return;
+                matchedEvent = {
+                    type,
+                    formId: Reflect.get(eventObject, "formId") ?? null,
+                    data,
+                    hasPreventDefault: typeof Reflect.get(eventObject, "preventDefault") === "function",
+                };
+                resolveWait?.();
+            },
+        }));
+        for (const listener of listeners) {
+            Reflect.apply(registerFormEventListener, form, [listener]);
+        }
+        await wait;
+        clearTimeout(timeout);
+        if (typeof unregisterFormEventListener === "function") {
+            for (const listener of listeners) {
+                Reflect.apply(unregisterFormEventListener, form, [listener]);
+            }
+        }
+        return {
+            matched: Boolean(matchedEvent),
+            timedOut: !matchedEvent,
+            elapsedMs: elapsedMs(),
+            targetFieldId,
+            ...(matchedEvent ? { event: matchedEvent } : {}),
+        };
+    }, options);
+}
+export async function setLiveFormFieldValueTransaction(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("setLiveFormFieldValueTransaction requires a Playwright page with evaluate().");
+    }
+    const shouldWaitForEvent = options.waitForEvent === true || (options.waitForEvent === undefined && options.write.notify === true);
+    const defaultEventOptions = {
+        eventTypes: ["change"],
+        target: options.write.target,
+        dataType: "api-setValue",
+        ...(options.write.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
+    };
+    const eventOptions = typeof options.waitForEvent === "object"
+        ? options.waitForEvent
+        : shouldWaitForEvent
+            ? defaultEventOptions
+            : null;
+    const eventPromise = eventOptions ? waitForLiveFormEvent(page, eventOptions) : null;
+    const write = await setLiveFormFieldValue(page, options.write);
+    const event = eventPromise ? await eventPromise : undefined;
+    const domDispatch = options.dispatchDomEvents === undefined || options.dispatchDomEvents === false
+        ? undefined
+        : await dispatchLiveFormFieldDomEvents(page, {
+            ...(typeof options.dispatchDomEvents === "object" ? options.dispatchDomEvents : {}),
+            target: options.write.target,
+        });
+    const readiness = options.readiness ? await readLiveFormReadiness(page, options.readiness) : undefined;
+    const domFields = options.snapshot
+        ? await snapshotLiveFormDomFields(page, typeof options.snapshot === "object" ? options.snapshot : {})
+        : undefined;
+    return {
+        write,
+        ...(event ? { event } : {}),
+        ...(domDispatch ? { domDispatch } : {}),
+        ...(readiness ? { readiness } : {}),
+        ...(domFields ? { domFields } : {}),
+    };
+}
+export async function setLiveFormFieldValueTimedTransaction(page, options) {
+    const timeline = [];
+    const startedAt = Date.now();
+    const runPhase = async (name, run) => {
+        const phaseStartedAt = Date.now();
+        try {
+            const result = await run();
+            const endedAt = Date.now();
+            timeline.push({
+                name,
+                startedAtMs: phaseStartedAt - startedAt,
+                endedAtMs: endedAt - startedAt,
+                durationMs: endedAt - phaseStartedAt,
+                ok: true,
+            });
+            return result;
+        }
+        catch (error) {
+            const endedAt = Date.now();
+            timeline.push({
+                name,
+                startedAtMs: phaseStartedAt - startedAt,
+                endedAtMs: endedAt - startedAt,
+                durationMs: endedAt - phaseStartedAt,
+                ok: false,
+                detail: { message: error instanceof Error ? error.message : String(error) },
+            });
+            throw error;
+        }
+    };
+    const beforeReadiness = options.beforeReadiness
+        ? await runPhase("before-readiness", () => readLiveFormReadiness(page, options.beforeReadiness))
+        : undefined;
+    const beforeDomFields = options.beforeSnapshot
+        ? await runPhase("before-snapshot", () => snapshotLiveFormDomFields(page, typeof options.beforeSnapshot === "object" ? options.beforeSnapshot : {}))
+        : undefined;
+    const shouldWaitForEvent = options.waitForEvent === true || (options.waitForEvent === undefined && options.write.notify === true);
+    const defaultEventOptions = {
+        eventTypes: ["change"],
+        target: options.write.target,
+        ...(options.write.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
+    };
+    const eventOptions = typeof options.waitForEvent === "object"
+        ? options.waitForEvent
+        : shouldWaitForEvent
+            ? defaultEventOptions
+            : undefined;
+    const eventPromise = eventOptions ? waitForLiveFormEvent(page, eventOptions) : null;
+    const write = await runPhase("write", () => setLiveFormFieldValue(page, options.write));
+    const event = eventPromise ? await runPhase("wait-for-event", () => eventPromise) : undefined;
+    const domDispatch = options.dispatchDomEvents
+        ? await runPhase("dispatch-dom-events", () => dispatchLiveFormFieldDomEvents(page, {
+            ...(typeof options.dispatchDomEvents === "object" ? options.dispatchDomEvents : {}),
+            target: options.write.target,
+        }))
+        : undefined;
+    const quiet = options.afterQuiet
+        ? await runPhase("after-quiet", () => waitForLiveFormQuiet(page, typeof options.afterQuiet === "object" ? options.afterQuiet : {}))
+        : undefined;
+    const readiness = options.readiness ? await runPhase("readiness", () => readLiveFormReadiness(page, options.readiness)) : undefined;
+    const validation = options.afterValidation
+        ? await runPhase("after-validation", () => waitForLiveFormValidationState(page, typeof options.afterValidation === "object" ? options.afterValidation : {}))
+        : undefined;
+    const domFields = options.snapshot
+        ? await runPhase("snapshot", () => snapshotLiveFormDomFields(page, typeof options.snapshot === "object" ? options.snapshot : {}))
+        : undefined;
+    return {
+        timeline,
+        write,
+        ...(event ? { event } : {}),
+        ...(domDispatch ? { domDispatch } : {}),
+        ...(readiness ? { readiness } : {}),
+        ...(domFields ? { domFields } : {}),
+        ...(beforeReadiness ? { beforeReadiness } : {}),
+        ...(beforeDomFields ? { beforeDomFields } : {}),
+        ...(quiet ? { quiet } : {}),
+        ...(validation ? { validation } : {}),
+    };
+}
+export async function setLiveFormFieldValuesTransaction(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("setLiveFormFieldValuesTransaction requires a Playwright page with evaluate().");
+    }
+    const writes = [];
+    const events = [];
+    const domDispatches = [];
+    const waitForEvents = options.waitForEvents ?? true;
+    for (const writeOptions of options.writes) {
+        const transaction = await setLiveFormFieldValueTransaction(page, {
+            write: writeOptions,
+            waitForEvent: waitForEvents && writeOptions.notify === true,
+            ...(options.dispatchDomEvents === undefined ? {} : { dispatchDomEvents: options.dispatchDomEvents }),
+        });
+        writes.push(transaction.write);
+        if (transaction.event)
+            events.push(transaction.event);
+        if (transaction.domDispatch)
+            domDispatches.push(transaction.domDispatch);
+    }
+    const readiness = options.readiness ? await readLiveFormReadiness(page, options.readiness) : undefined;
+    const domFields = options.snapshot
+        ? await snapshotLiveFormDomFields(page, typeof options.snapshot === "object" ? options.snapshot : {})
+        : undefined;
+    return {
+        writes,
+        events,
+        domDispatches,
+        ...(readiness ? { readiness } : {}),
+        ...(domFields ? { domFields } : {}),
+    };
+}
 async function setControlValue(locator, value) {
     try {
         await locator.fill(value);
@@ -167,12 +2564,12 @@ export function createFormTestHarness(page, options = {}) {
         selectOption: (internalLabel, value) => page.locator(formstackSelectors.fieldInputByInternalLabel(internalLabel)).first().selectOption(value),
         chooseRadio: (internalLabel, value) => page.locator(formstackSelectors.optionLabelByValue(internalLabel, "radio", value)).first().click(),
         setCheckbox: (internalLabel, value, checked) => {
-            const locator = page.locator(formstackSelectors.optionLabelByValue(internalLabel, "checkbox", value)).first();
-            return checked ? locator.click() : locator.click();
+            const locator = page.locator(formstackSelectors.optionInput(internalLabel, "checkbox", value)).first();
+            return checked ? locator.check() : locator.uncheck();
         },
         setCheckboxes: async (internalLabel, values) => {
             for (const value of values) {
-                await page.locator(formstackSelectors.optionLabelByValue(internalLabel, "checkbox", value)).first().click();
+                await page.locator(formstackSelectors.optionInput(internalLabel, "checkbox", value)).first().check();
             }
         },
         selectMatrixCell: (fieldId, row, column) => page.locator(formstackSelectors.matrixInputByPosition(fieldId, row, column)).first().check(),
@@ -194,10 +2591,38 @@ function stepName(step, index) {
 function stepRunner(step) {
     return typeof step === "function" ? step : step.run;
 }
+function errorReport(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    return {
+        name: "Error",
+        message: String(error),
+    };
+}
 export async function runFormScenario(page, scenario, options = {}) {
     const monitor = createFormBrowserMonitor(page, scenario.diagnostics ?? options.diagnostics);
     const harness = createFormTestHarness(page, options);
     const steps = [];
+    const started = Date.now();
+    const startedAt = new Date(started).toISOString();
+    const buildResult = (status) => {
+        const ended = Date.now();
+        return {
+            name: scenario.name,
+            status,
+            startedAt,
+            endedAt: new Date(ended).toISOString(),
+            durationMs: ended - started,
+            steps,
+            diagnostics: monitor.report(),
+            ...(options.artifacts === undefined ? {} : { artifacts: options.artifacts }),
+        };
+    };
     try {
         if (scenario.url) {
             await page.goto(scenario.url);
@@ -208,18 +2633,42 @@ export async function runFormScenario(page, scenario, options = {}) {
             if (!step) {
                 continue;
             }
-            await stepRunner(step)(harness);
-            steps.push({ name: stepName(step, index) });
+            const name = stepName(step, index);
+            const stepStarted = Date.now();
+            try {
+                await stepRunner(step)(harness);
+                const stepEnded = Date.now();
+                steps.push({
+                    name,
+                    status: "passed",
+                    startedAt: new Date(stepStarted).toISOString(),
+                    endedAt: new Date(stepEnded).toISOString(),
+                    durationMs: stepEnded - stepStarted,
+                });
+            }
+            catch (error) {
+                const stepEnded = Date.now();
+                steps.push({
+                    name,
+                    status: "failed",
+                    startedAt: new Date(stepStarted).toISOString(),
+                    endedAt: new Date(stepEnded).toISOString(),
+                    durationMs: stepEnded - stepStarted,
+                    error: errorReport(error),
+                });
+                throw new FormScenarioRunError(buildResult("failed"));
+            }
         }
         const shouldThrow = options.throwOnDiagnostics ?? true;
         if (shouldThrow) {
-            monitor.assertNoErrors();
+            try {
+                monitor.assertNoErrors();
+            }
+            catch {
+                throw new FormScenarioRunError(buildResult("failed"));
+            }
         }
-        return {
-            name: scenario.name,
-            steps,
-            diagnostics: monitor.report(),
-        };
+        return buildResult("passed");
     }
     finally {
         monitor.detach();
@@ -228,4 +2677,194 @@ export async function runFormScenario(page, scenario, options = {}) {
 export function defineFormScenario(scenario) {
     return scenario;
 }
+export const liveFormScenarioSteps = {
+    writeField: (name, options) => ({
+        name,
+        run: (harness) => setLiveFormFieldValueTransaction(harness.page, options).then(() => undefined),
+    }),
+    writeFields: (name, options) => ({
+        name,
+        run: (harness) => setLiveFormFieldValuesTransaction(harness.page, options).then(() => undefined),
+    }),
+    expectReady: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const readiness = await waitForLiveFormReadiness(harness.page, options);
+            if (!readiness.isReady) {
+                throw new Error(`Expected live form to be ready, but ${readiness.blockingFieldCount} field(s) are blocking.`);
+            }
+        },
+    }),
+    waitForQuiet: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const quiet = await waitForLiveFormQuiet(harness.page, options);
+            if (!quiet.quiet) {
+                throw new Error("Expected live form to become quiet before timeout.");
+            }
+        },
+    }),
+    expectFieldCoverage: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const coverage = await readLiveFormFieldCoverage(harness.page, options);
+            assertLiveFormFieldCoverage(coverage, options);
+        },
+    }),
+    expectFieldValue: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const value = await waitForLiveFormFieldValue(harness.page, options);
+            const matched = options.expectedValue === undefined ? value.fieldAvailable && !value.isEmpty : value.valueMatched === true;
+            if (!matched) {
+                throw new Error("Expected live form field value condition was not met.");
+            }
+        },
+    }),
+    expectDomFieldState: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const state = await waitForLiveFormDomFieldState(harness.page, options);
+            if (!state.matched) {
+                throw new Error("Expected live form DOM field state condition was not met.");
+            }
+        },
+    }),
+    expectValidationErrors: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const validation = await waitForLiveFormValidationState(harness.page, options);
+            const expectedCountMatched = options.expectedErrorCount === undefined || validation.inlineErrors.length === options.expectedErrorCount;
+            const errorText = options.errorText;
+            const textMatched = errorText === undefined ||
+                validation.inlineErrors.some((error) => typeof errorText === "string" ? error.text.includes(errorText) : errorText.test(error.text));
+            if (validation.inlineErrors.length === 0 || !expectedCountMatched || !textMatched) {
+                throw new Error("Expected live form validation errors were not present.");
+            }
+        },
+    }),
+    expectNoValidationErrors: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const validation = await waitForLiveFormValidationState(harness.page, { ...options, expectNoErrors: true });
+            if (validation.inlineErrors.length > 0) {
+                throw new Error(`Expected no live form validation errors, but found ${validation.inlineErrors.length}.`);
+            }
+        },
+    }),
+    expectConsoleMessage: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const consoleMessage = await waitForConsoleMessage(harness.page, options);
+            if (!consoleMessage.matched) {
+                throw new Error("Expected console message was not observed before timeout.");
+            }
+        },
+    }),
+    expectWindowFlag: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const flag = await waitForWindowFlag(harness.page, options);
+            if (!flag.matched) {
+                throw new Error(`Expected window flag "${options.path}" condition was not met before timeout.`);
+            }
+        },
+    }),
+    expectVisibility: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const visibility = await waitForLiveFormVisibility(harness.page, options);
+            if (!visibility.matched) {
+                throw new Error("Expected live form visibility conditions were not met.");
+            }
+        },
+    }),
+    expectNoStateDrift: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const drift = await readLiveFormStateDrift(harness.page, options);
+            if (drift.hasDrift) {
+                throw new Error(`Expected no live form state drift, but found ${drift.issues.length} issue(s).`);
+            }
+        },
+    }),
+    submitAndProbe: (name, options = {}) => ({
+        name,
+        run: (harness) => submitWithLiveFormLifecycleProbe(harness.page, options).then(() => undefined),
+    }),
+};
+async function maybeWaitForQuiet(page, options) {
+    if (!options.waitForQuiet)
+        return;
+    const quiet = await waitForLiveFormQuiet(page, typeof options.waitForQuiet === "object" ? options.waitForQuiet : {});
+    if (!quiet.quiet) {
+        throw new Error("Expected live form to become quiet before timeout.");
+    }
+}
+function apiRecipeStep(name, target, value, options = {}) {
+    return {
+        name,
+        run: async (harness) => {
+            await setLiveFormFieldValueTransaction(harness.page, {
+                write: {
+                    target,
+                    value,
+                    notify: options.notify ?? true,
+                },
+                waitForEvent: options.waitForEvent ?? (options.notify ?? true),
+                ...(options.dispatchDomEvents === undefined ? {} : { dispatchDomEvents: options.dispatchDomEvents }),
+            });
+            await maybeWaitForQuiet(harness.page, options);
+        },
+    };
+}
+export const liveFormFieldRecipes = {
+    fillTextDom: (name, internalLabel, value) => ({
+        name,
+        run: (harness) => harness.fillText(internalLabel, value),
+    }),
+    fillNameDom: (name, internalLabel, value) => ({
+        name,
+        run: (harness) => harness.fillName(internalLabel, value),
+    }),
+    fillAddressDom: (name, internalLabel, value) => ({
+        name,
+        run: (harness) => harness.fillAddress(internalLabel, value),
+    }),
+    chooseRadioDom: (name, internalLabel, value) => ({
+        name,
+        run: (harness) => harness.chooseRadio(internalLabel, value),
+    }),
+    setCheckboxDom: (name, internalLabel, value, checked) => ({
+        name,
+        run: (harness) => harness.setCheckbox(internalLabel, value, checked),
+    }),
+    selectMatrixCellDom: (name, fieldId, row, column) => ({
+        name,
+        run: (harness) => harness.selectMatrixCell(fieldId, row, column),
+    }),
+    setRatingDom: (name, fieldId, zeroBasedIndex) => ({
+        name,
+        run: (harness) => harness.setRating(fieldId, zeroBasedIndex),
+    }),
+    uploadFileDom: (name, internalLabel, files) => ({
+        name,
+        run: (harness) => harness.uploadFile(internalLabel, files),
+    }),
+    clearSignatureDom: (name, internalLabel) => ({
+        name,
+        run: (harness) => harness.clearSignature(internalLabel),
+    }),
+    setNameApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormNameValue(value), options),
+    setAddressApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormAddressValue(value), options),
+    setChoiceApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormChoiceValue(value), options),
+    setSelectApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormSelectValue(value), options),
+    setCheckboxesApi: (name, internalLabel, values, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormCheckboxValue(values), options),
+    setDateTimeApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormDateTimeValue(value), options),
+    setMatrixApi: (name, internalLabel, selections, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormMatrixValue(selections), options),
+    setRatingApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormRatingValue(value), options),
+    setProductApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormProductValue(value), options),
+    setNameApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setNameApi(name, internalLabel, value, { ...options, dispatchDomEvents: { eventTypes: ["input", "change", "blur"], onlyCheckedChoices: false } }),
+    setChoiceApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setChoiceApi(name, internalLabel, value, { ...options, dispatchDomEvents: { eventTypes: ["input", "change", "blur"], onlyCheckedChoices: true } }),
+};
 //# sourceMappingURL=index.js.map