@redrockswebdevelopment/formstack-form-testing 0.1.6 → 0.1.8

package/dist/index.js

@@ -290,6 +290,301 @@ function matchesPattern(value, pattern) {
 function isIgnored(value, patterns) {
     return patterns?.some((pattern) => matchesPattern(value, pattern)) ?? false;
 }
+function liveFormTargetMatches(source, event) {
+    if (source.internalLabel && event.internalLabel)
+        return source.internalLabel === event.internalLabel;
+    if (source.internalLabel && event.target.internalLabel)
+        return source.internalLabel === event.target.internalLabel;
+    if (source.fieldId != null && event.fieldId != null)
+        return String(source.fieldId) === String(event.fieldId);
+    if (source.fieldId != null && event.target.fieldId != null)
+        return String(source.fieldId) === String(event.target.fieldId);
+    return false;
+}
+function createLiveFormEffectTransactionId(prefix = "fspt-effect") {
+    return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function createLiveFormEffectController(adapter, options = {}) {
+    const startedAt = adapter.now?.() ?? Date.now();
+    const now = () => adapter.now?.() ?? Date.now();
+    const effects = new Map();
+    const traces = [];
+    const runCounts = new Map();
+    const latestSequenceByEffect = new Map();
+    const maxRunsPerTransaction = options.maxRunsPerTransaction ?? 25;
+    const emitTrace = (kind, detail, effectId, transactionId) => {
+        const event = {
+            kind,
+            at: new Date().toISOString(),
+            elapsedMs: Math.round(now() - startedAt),
+            ...(effectId ? { effectId } : {}),
+            ...(transactionId ? { transactionId } : {}),
+            detail,
+        };
+        if (options.trace !== false)
+            traces.push(event);
+        options.onTrace?.(event);
+    };
+    const runEffect = async (effect, event) => {
+        const transactionId = event.transactionId ?? createLiveFormEffectTransactionId();
+        if (effect.ignoreTransactions?.includes(transactionId)) {
+            emitTrace("effect-skip", { reason: "ignored-transaction" }, effect.id, transactionId);
+            return;
+        }
+        const runKey = `${transactionId}:${effect.id}`;
+        const runIndex = (runCounts.get(runKey) ?? 0) + 1;
+        runCounts.set(runKey, runIndex);
+        if (runIndex > maxRunsPerTransaction) {
+            emitTrace("effect-skip", { reason: "max-runs-exceeded", runIndex, maxRunsPerTransaction }, effect.id, transactionId);
+            return;
+        }
+        const sequence = (latestSequenceByEffect.get(effect.id) ?? 0) + 1;
+        latestSequenceByEffect.set(effect.id, sequence);
+        const waitForPhase = async () => {
+            if (effect.phase === "afterQuiet" || effect.phase === "afterValidation")
+                await adapter.waitForQuiet?.();
+            if (effect.phase === "afterValidation")
+                await adapter.validate?.({ validate: true });
+        };
+        emitTrace("effect-start", { phase: effect.phase ?? "afterValue", runIndex }, effect.id, transactionId);
+        try {
+            await waitForPhase();
+            if (effect.latestOnly !== false && latestSequenceByEffect.get(effect.id) !== sequence) {
+                emitTrace("effect-skip", { reason: "stale-run", sequence }, effect.id, transactionId);
+                return;
+            }
+            const context = {
+                event,
+                effectId: effect.id,
+                transactionId,
+                runIndex,
+                readField: (target) => adapter.readField(target),
+                writeField: async (target, value, writeOptions = {}) => {
+                    const writeTransactionId = writeOptions.transactionId ?? transactionId;
+                    emitTrace("write", {
+                        target,
+                        value,
+                        source: writeOptions.source ?? effect.id,
+                        suppressEffects: writeOptions.suppressEffects ?? false,
+                    }, effect.id, writeTransactionId);
+                    await adapter.writeField(target, value, {
+                        ...writeOptions,
+                        source: writeOptions.source ?? effect.id,
+                        transactionId: writeTransactionId,
+                    });
+                },
+                waitForQuiet: async (quietOptions) => {
+                    await adapter.waitForQuiet?.(quietOptions);
+                },
+                validate: async (validationOptions) => adapter.validate?.(validationOptions),
+                trace: (kind, detail = {}) => emitTrace(kind, detail, effect.id, transactionId),
+            };
+            await effect.handler(context);
+            emitTrace("effect-complete", { runIndex }, effect.id, transactionId);
+        }
+        catch (error) {
+            emitTrace("effect-error", { message: error instanceof Error ? error.message : String(error) }, effect.id, transactionId);
+            throw error;
+        }
+    };
+    const emit = async (event) => {
+        emitTrace("change", {
+            target: event.target,
+            fieldId: event.fieldId ?? null,
+            internalLabel: event.internalLabel ?? null,
+            source: event.source ?? null,
+        }, undefined, event.transactionId);
+        const matching = [...effects.values()].filter((effect) => effect.sources.some((source) => liveFormTargetMatches(source, event)));
+        for (const effect of matching)
+            await runEffect(effect, event);
+    };
+    const unsubscribe = adapter.onFieldChange((event) => {
+        void emit(event);
+    });
+    return {
+        register: (effect) => {
+            if (effects.has(effect.id))
+                throw new Error(`Live form effect "${effect.id}" is already registered.`);
+            effects.set(effect.id, effect);
+            emitTrace("registered", { sources: effect.sources, phase: effect.phase ?? "afterValue" }, effect.id);
+            return () => {
+                effects.delete(effect.id);
+            };
+        },
+        emit,
+        writeField: async (target, value, writeOptions = {}) => {
+            const transactionId = writeOptions.transactionId ?? createLiveFormEffectTransactionId();
+            emitTrace("write", { target, value, source: writeOptions.source ?? "controller", suppressEffects: writeOptions.suppressEffects ?? false }, undefined, transactionId);
+            await adapter.writeField(target, value, { ...writeOptions, transactionId });
+        },
+        readField: (target) => adapter.readField(target),
+        waitForQuiet: async (quietOptions) => {
+            await adapter.waitForQuiet?.(quietOptions);
+        },
+        validate: async (validationOptions) => adapter.validate?.(validationOptions),
+        traces: () => [...traces],
+        dispose: () => {
+            effects.clear();
+            unsubscribe();
+        },
+    };
+}
+export function createFormstackLiveFormEffectAdapter(options = {}) {
+    const readApi = () => {
+        const globalObject = globalThis;
+        const factory = globalObject.window && typeof globalObject.window === "object"
+            ? Reflect.get(globalObject.window, "fsApi")
+            : Reflect.get(globalObject, "fsApi");
+        const api = typeof factory === "function" ? Reflect.apply(factory, globalObject.window ?? globalObject, []) : 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 waitForForm = async () => {
+        const timeoutMs = options.waitForApiTimeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        let form = readApi();
+        while ((!form || typeof form !== "object") && Date.now() < deadline) {
+            await delay(50);
+            form = readApi();
+        }
+        if (!form || typeof form !== "object")
+            throw new Error("Formstack Live Form API did not become available.");
+        return form;
+    };
+    const resolveField = async (target) => {
+        const form = await waitForForm();
+        const getField = Reflect.get(form, "getField");
+        const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+        if (target.internalLabel && typeof getFieldByInternalLabel === "function") {
+            const field = Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel]);
+            if (field)
+                return field;
+        }
+        if (target.fieldId != null && typeof getField === "function")
+            return Reflect.apply(getField, form, [String(target.fieldId)]);
+        return null;
+    };
+    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 readFieldId = (field) => {
+        if (!field || typeof field !== "object")
+            return null;
+        const getId = Reflect.get(field, "getId");
+        if (typeof getId === "function")
+            return Reflect.apply(getId, field, []);
+        return Reflect.get(field, "id") ?? null;
+    };
+    const listeners = new Set();
+    let formListenerDispose = null;
+    const ensureFormListener = async () => {
+        if (formListenerDispose)
+            return;
+        const form = await waitForForm();
+        const registerFormEventListener = Reflect.get(form, "registerFormEventListener");
+        const unregisterFormEventListener = Reflect.get(form, "unregisterFormEventListener");
+        if (typeof registerFormEventListener !== "function")
+            return;
+        const formEventListener = {
+            type: "change",
+            onFormEvent: async (event) => {
+                const eventObject = event && typeof event === "object" ? event : {};
+                const data = Reflect.get(eventObject, "data");
+                const dataObject = data && typeof data === "object" ? data : {};
+                const fieldId = Reflect.get(dataObject, "fieldId") ?? null;
+                const field = fieldId == null ? null : typeof Reflect.get(form, "getField") === "function"
+                    ? Reflect.apply(Reflect.get(form, "getField"), form, [String(fieldId)])
+                    : null;
+                const currentValue = readFieldValue(field);
+                const internalLabel = field && typeof field === "object"
+                    ? Reflect.get(field, "internalLabel") ?? null
+                    : null;
+                const changeEvent = {
+                    target: fieldId == null ? {} : { fieldId },
+                    fieldId,
+                    internalLabel,
+                    currentValue,
+                    source: Reflect.get(dataObject, "type") ?? "formstack-change",
+                };
+                for (const listener of listeners)
+                    listener(changeEvent);
+            },
+        };
+        Reflect.apply(registerFormEventListener, form, [formEventListener]);
+        formListenerDispose = () => {
+            if (typeof unregisterFormEventListener === "function")
+                Reflect.apply(unregisterFormEventListener, form, [formEventListener]);
+            formListenerDispose = null;
+        };
+    };
+    return {
+        readField: async (target) => readFieldValue(await resolveField(target)),
+        writeField: async (target, value, writeOptions = {}) => {
+            const form = await waitForForm();
+            const field = await resolveField(target);
+            if (!field || typeof field !== "object")
+                throw new Error(`Unable to resolve Formstack field ${target.internalLabel ?? target.fieldId ?? "unknown"}.`);
+            const setValue = Reflect.get(field, "setValue");
+            if (typeof setValue !== "function")
+                throw new Error("Resolved Formstack field does not support setValue().");
+            const previousValue = readFieldValue(field);
+            await Promise.resolve(Reflect.apply(setValue, field, [value]));
+            if (options.notifyWrites ?? true) {
+                const notifyFormEventListeners = Reflect.get(form, "notifyFormEventListeners");
+                if (typeof notifyFormEventListeners === "function") {
+                    await Promise.resolve(Reflect.apply(notifyFormEventListeners, form, [
+                        "change",
+                        {
+                            fieldId: readFieldId(field),
+                            type: writeOptions.source ?? "effect-write",
+                            transactionId: writeOptions.transactionId,
+                            suppressEffects: writeOptions.suppressEffects ?? false,
+                            value,
+                        },
+                    ]));
+                }
+            }
+            if (!writeOptions.suppressEffects) {
+                const currentValue = readFieldValue(field);
+                const event = {
+                    target,
+                    fieldId: readFieldId(field),
+                    internalLabel: target.internalLabel ?? null,
+                    previousValue,
+                    currentValue,
+                    source: writeOptions.source ?? "effect-write",
+                    ...(writeOptions.transactionId ? { transactionId: writeOptions.transactionId } : {}),
+                };
+                for (const listener of listeners)
+                    listener(event);
+            }
+        },
+        onFieldChange: (listener) => {
+            listeners.add(listener);
+            void ensureFormListener();
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0)
+                    formListenerDispose?.();
+            };
+        },
+        waitForQuiet: async (quietOptions = {}) => {
+            await delay(quietOptions.quietMs ?? options.quietMs ?? 250);
+        },
+        validate: async (validationOptions = {}) => {
+            const form = await waitForForm();
+            if (!validationOptions.validate)
+                return null;
+            const validateForm = Reflect.get(form, "validateForm");
+            return typeof validateForm === "function" ? Reflect.apply(validateForm, form, []) : null;
+        },
+        now: () => Date.now(),
+    };
+}
 function defaultDiagnosticsOptions(options = {}) {
     return {
         failOnConsoleTypes: options.failOnConsoleTypes ?? ["error"],
@@ -1407,6 +1702,20 @@ export async function postMessageToIframe(page, options) {
 export function buildFormstackIframeBridgeMessage(message) {
     return message;
 }
+export function createFormstackIframeBridgeRequest(options) {
+    return buildFormstackIframeBridgeMessage({
+        channel: options.channel,
+        requestId: options.requestId ?? `fspt-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+        type: options.type,
+        ...(options.payload === undefined ? {} : { payload: options.payload }),
+    });
+}
+export function createFormstackIframePrefillRequest(options) {
+    return createFormstackIframeBridgeRequest({
+        ...options,
+        type: options.type ?? "prefill",
+    });
+}
 export async function waitForWindowMessage(page, options = {}) {
     if (!hasEvaluate(page)) {
         throw new Error("waitForWindowMessage requires a Playwright page with evaluate().");
@@ -1472,6 +1781,13 @@ export async function sendFormstackIframeBridgeMessage(page, options) {
     });
     return { posted, response };
 }
+export async function sendFormstackIframePrefillMessage(page, options) {
+    return sendFormstackIframeBridgeMessage(page, {
+        ...options,
+        type: options.type ?? "prefill",
+        responseType: options.responseType ?? `${options.type ?? "prefill"}:response`,
+    });
+}
 export async function waitForConsoleMessage(page, options = {}) {
     const timeoutMs = options.timeoutMs ?? 5_000;
     const startedAt = Date.now();
@@ -2440,6 +2756,57 @@ export async function waitForLiveFormEvent(page, options) {
         };
     }, options);
 }
+export function defaultLiveFormFieldEventPlan(kind = "unknown") {
+    if (["radio", "checkbox", "matrix", "rating"].includes(kind)) {
+        return {
+            eventTypes: ["input", "change", "blur"],
+            onlyCheckedChoices: true,
+            reason: "Choice-like fields should notify checked controls and then blur so custom scripts and validation see a user-like selection.",
+        };
+    }
+    if (["name", "address", "date", "datetime", "product"].includes(kind)) {
+        return {
+            eventTypes: ["input", "change", "blur"],
+            onlyCheckedChoices: false,
+            reason: "Compound fields can render several controls, so dispatch across all visible subcontrols after an API value write.",
+        };
+    }
+    if (["select"].includes(kind)) {
+        return {
+            eventTypes: ["change", "blur"],
+            onlyCheckedChoices: false,
+            reason: "Select fields primarily publish change events, with blur included for validation parity.",
+        };
+    }
+    if (["text", "textarea", "email", "phone", "number"].includes(kind)) {
+        return {
+            eventTypes: ["input", "change", "blur"],
+            onlyCheckedChoices: false,
+            reason: "Text-like fields should emit input, change, and blur to match Formstack custom-script and validation timing.",
+        };
+    }
+    return {
+        eventTypes: ["input", "change", "blur"],
+        onlyCheckedChoices: true,
+        reason: "Unknown fields use the conservative user-like event sequence while avoiding unchecked choice controls.",
+    };
+}
+function liveFormFieldTargetKey(target) {
+    if (target.internalLabel)
+        return target.internalLabel;
+    if (target.fieldId != null)
+        return String(target.fieldId);
+    return null;
+}
+function resolveLiveFormDispatchOptions(dispatch, fieldKind) {
+    if (dispatch === undefined || dispatch === false)
+        return null;
+    if (dispatch === true || dispatch === "auto") {
+        const { eventTypes, onlyCheckedChoices } = defaultLiveFormFieldEventPlan(fieldKind);
+        return { eventTypes, onlyCheckedChoices };
+    }
+    return dispatch;
+}
 export async function setLiveFormFieldValueTransaction(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("setLiveFormFieldValueTransaction requires a Playwright page with evaluate().");
@@ -2459,12 +2826,13 @@ export async function setLiveFormFieldValueTransaction(page, options) {
     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 : {}),
+    const dispatchOptions = resolveLiveFormDispatchOptions(options.dispatchDomEvents, options.fieldKind);
+    const domDispatch = dispatchOptions
+        ? await dispatchLiveFormFieldDomEvents(page, {
+            ...dispatchOptions,
             target: options.write.target,
-        });
+        })
+        : undefined;
     const readiness = options.readiness ? await readLiveFormReadiness(page, options.readiness) : undefined;
     const domFields = options.snapshot
         ? await snapshotLiveFormDomFields(page, typeof options.snapshot === "object" ? options.snapshot : {})
@@ -2527,9 +2895,10 @@ export async function setLiveFormFieldValueTimedTransaction(page, options) {
     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
+    const dispatchOptions = resolveLiveFormDispatchOptions(options.dispatchDomEvents, options.fieldKind);
+    const domDispatch = dispatchOptions
         ? await runPhase("dispatch-dom-events", () => dispatchLiveFormFieldDomEvents(page, {
-            ...(typeof options.dispatchDomEvents === "object" ? options.dispatchDomEvents : {}),
+            ...dispatchOptions,
             target: options.write.target,
         }))
         : undefined;
@@ -2556,6 +2925,104 @@ export async function setLiveFormFieldValueTimedTransaction(page, options) {
         ...(validation ? { validation } : {}),
     };
 }
+export async function waitForLiveFormReady(page, options = {}) {
+    const report = await waitForLiveFormReadiness(page, options);
+    if (options.throwOnBlockingFields !== false && !report.isReady) {
+        throw new Error(`Live form did not become ready; ${report.blockingFieldCount} field(s) are blocking.`);
+    }
+    return report;
+}
+export async function waitForLiveFormFieldStable(page, options) {
+    const quiet = options.quiet
+        ? await waitForLiveFormQuiet(page, typeof options.quiet === "object" ? options.quiet : {})
+        : undefined;
+    const value = options.value ? await waitForLiveFormFieldValue(page, { ...options.value, target: options.target }) : undefined;
+    const dom = options.dom ? await waitForLiveFormDomFieldState(page, { ...options.target, ...options.dom }) : undefined;
+    const stable = (quiet?.quiet ?? true) && (value ? (value.expectedValue === undefined ? value.fieldAvailable && !value.isEmpty : value.valueMatched === true) : true) && (dom?.matched ?? true);
+    return {
+        ...(quiet ? { quiet } : {}),
+        ...(value ? { value } : {}),
+        ...(dom ? { dom } : {}),
+        stable,
+    };
+}
+export async function waitForLiveFormValidationSettled(page, options = {}) {
+    const validation = await waitForLiveFormValidationState(page, {
+        ...options,
+        ...(options.requireNoErrors === false ? {} : { expectNoErrors: options.expectNoErrors ?? true }),
+    });
+    if (options.requireNoErrors !== false && validation.inlineErrors.length > 0) {
+        throw new Error(`Live form validation did not settle cleanly; found ${validation.inlineErrors.length} visible error(s).`);
+    }
+    return validation;
+}
+export async function waitForLiveFormLogicSettled(page, options = {}) {
+    const quiet = options.quiet
+        ? await waitForLiveFormQuiet(page, typeof options.quiet === "object" ? options.quiet : {})
+        : undefined;
+    const visibility = options.visibility ? await waitForLiveFormVisibility(page, options.visibility) : undefined;
+    const readiness = options.readiness ? await waitForLiveFormReadiness(page, options.readiness) : undefined;
+    const validation = options.validation
+        ? await waitForLiveFormValidationSettled(page, typeof options.validation === "object" ? options.validation : {})
+        : undefined;
+    return {
+        ...(quiet ? { quiet } : {}),
+        ...(visibility ? { visibility } : {}),
+        ...(readiness ? { readiness } : {}),
+        ...(validation ? { validation } : {}),
+        settled: (quiet?.quiet ?? true) && (visibility?.matched ?? true) && (readiness?.isReady ?? true) && ((validation?.inlineErrors.length ?? 0) === 0),
+    };
+}
+export async function performLiveFormFieldTransaction(page, options) {
+    return setLiveFormFieldValueTimedTransaction(page, {
+        ...options,
+        ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
+        dispatchDomEvents: options.dispatchDomEvents ?? (options.autoDispatchDomEvents === false ? false : "auto"),
+        afterQuiet: options.afterQuiet ?? true,
+    });
+}
+export async function answerProgressiveLiveFormField(page, options) {
+    const validationOptions = options.afterValidation === undefined ? undefined : typeof options.afterValidation === "object" ? options.afterValidation : {};
+    const transaction = await performLiveFormFieldTransaction(page, {
+        write: {
+            ...(options.write ?? {}),
+            target: options.target,
+            value: options.value,
+            notify: options.write?.notify ?? true,
+        },
+        ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
+        waitForEvent: options.waitForEvent ?? true,
+        afterQuiet: options.afterQuiet ?? true,
+        ...(validationOptions ? { afterValidation: validationOptions } : {}),
+    });
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const visibility = visibilityTargets.length > 0
+        ? await waitForLiveFormVisibility(page, { targets: visibilityTargets })
+        : undefined;
+    if (visibility && !visibility.matched) {
+        throw new Error("Progressive live form answer did not produce the expected visibility state.");
+    }
+    const resetValues = [];
+    for (const reset of options.expectReset ?? []) {
+        const value = await readLiveFormFieldValue(page, reset);
+        if (!value.isEmpty) {
+            throw new Error(`Expected progressive answer reset target ${reset.target.internalLabel ?? reset.target.fieldId ?? "unknown"} to be empty.`);
+        }
+        resetValues.push(value);
+    }
+    const validation = validationOptions
+        ? await waitForLiveFormValidationSettled(page, validationOptions)
+        : undefined;
+    return {
+        transaction,
+        ...(visibility ? { visibility } : {}),
+        resetValues,
+        ...(validation ? { validation } : {}),
+    };
+}
 function mergeTraceFieldValueTarget(target, options) {
     if (!target || options === false || options === undefined)
         return null;
@@ -2653,10 +3120,12 @@ export async function setLiveFormFieldValuesTransaction(page, options) {
     const domDispatches = [];
     const waitForEvents = options.waitForEvents ?? true;
     for (const writeOptions of options.writes) {
+        const fieldKey = liveFormFieldTargetKey(writeOptions.target);
         const transaction = await setLiveFormFieldValueTransaction(page, {
             write: writeOptions,
             waitForEvent: waitForEvents && writeOptions.notify === true,
             ...(options.dispatchDomEvents === undefined ? {} : { dispatchDomEvents: options.dispatchDomEvents }),
+            ...(fieldKey && options.fieldKinds?.[fieldKey] ? { fieldKind: options.fieldKinds[fieldKey] } : {}),
         });
         writes.push(transaction.write);
         if (transaction.event)
@@ -2901,6 +3370,14 @@ export const liveFormScenarioSteps = {
         name,
         run: (harness) => setLiveFormFieldValueTransaction(harness.page, options).then(() => undefined),
     }),
+    performFieldTransaction: (name, options) => ({
+        name,
+        run: (harness) => performLiveFormFieldTransaction(harness.page, options).then(() => undefined),
+    }),
+    answerProgressiveField: (name, options) => ({
+        name,
+        run: (harness) => answerProgressiveLiveFormField(harness.page, options).then(() => undefined),
+    }),
     writeFields: (name, options) => ({
         name,
         run: (harness) => setLiveFormFieldValuesTransaction(harness.page, options).then(() => undefined),
@@ -2908,12 +3385,30 @@ export const liveFormScenarioSteps = {
     expectReady: (name, options) => ({
         name,
         run: async (harness) => {
-            const readiness = await waitForLiveFormReadiness(harness.page, options);
+            const readiness = await waitForLiveFormReady(harness.page, options);
             if (!readiness.isReady) {
                 throw new Error(`Expected live form to be ready, but ${readiness.blockingFieldCount} field(s) are blocking.`);
             }
         },
     }),
+    expectFieldStable: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const stable = await waitForLiveFormFieldStable(harness.page, options);
+            if (!stable.stable) {
+                throw new Error("Expected live form field to become stable before timeout.");
+            }
+        },
+    }),
+    expectLogicSettled: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const settled = await waitForLiveFormLogicSettled(harness.page, options);
+            if (!settled.settled) {
+                throw new Error("Expected live form logic to settle before timeout.");
+            }
+        },
+    }),
     waitForQuiet: (name, options = {}) => ({
         name,
         run: async (harness) => {
@@ -3039,6 +3534,7 @@ function apiRecipeStep(name, target, value, options = {}) {
                 },
                 waitForEvent: options.waitForEvent ?? (options.notify ?? true),
                 ...(options.dispatchDomEvents === undefined ? {} : { dispatchDomEvents: options.dispatchDomEvents }),
+                ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
             });
             await maybeWaitForQuiet(harness.page, options);
         },
@@ -3094,7 +3590,8 @@ export const liveFormFieldRecipes = {
     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 } }),
+    setFieldApiAuto: (name, internalLabel, value, fieldKind, options = {}) => apiRecipeStep(name, { internalLabel }, value, { ...options, fieldKind, dispatchDomEvents: "auto" }),
+    setNameApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setNameApi(name, internalLabel, value, { ...options, fieldKind: options.fieldKind ?? "name", dispatchDomEvents: "auto" }),
+    setChoiceApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setChoiceApi(name, internalLabel, value, { ...options, fieldKind: options.fieldKind ?? "radio", dispatchDomEvents: "auto" }),
 };
 //# sourceMappingURL=index.js.map