From 33ded9889726335ca4d1de4fe46819d7144cd7cf Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Tue, 11 Aug 2026 14:21:33 +0200
Subject: [PATCH 1/4] Offer a footer Cancel on a stepper command dialog

The X in the header was the only way out of a wizard, which is easy to
miss on a long or destructive flow and disappears entirely when the dialog
is presented without a visible header. The cancel path itself already
existed - the X routes through it - so this only surfaces it as a button.

It is opt-in, because turning it on by default would silently re-lay-out
every wizard already in use. The button sits leftmost, before Previous and
outside the spacer, so it stays in the same place when Previous appears on
the second step rather than sliding across as the footer fills.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UWugkmN6NmoemKeTvSKNDg
---
 Source/CommandDialog/StepperCommandDialog.tsx | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Source/CommandDialog/StepperCommandDialog.tsx b/Source/CommandDialog/StepperCommandDialog.tsx
index c739bee..5376936 100644
--- a/Source/CommandDialog/StepperCommandDialog.tsx
+++ b/Source/CommandDialog/StepperCommandDialog.tsx
@@ -71,6 +71,14 @@ export interface StepperCommandDialogProps<TCommand extends object, TResponse =
     nextLabel?: string;
     /** Label for the previous step button. Defaults to `'Previous'`. */
     previousLabel?: string;
+    /**
+     * Show a Cancel action in the footer. Defaults to `false`, leaving the X in the header as the
+     * only way to dismiss. Turn it on for a wizard whose dismissal should be as reachable as its
+     * submit — a destructive or long flow, or one presented without a visible header.
+     */
+    showCancel?: boolean;
+    /** Label for the footer cancel button. Defaults to `'Cancel'`. */
+    cancelLabel?: string;
     /**
      * Extra CSS class name forwarded to the underlying PrimeReact Dialog root.
      * Use the inherited `pt`/`ptOptions`/`unstyled` props to customize the Stepper.
@@ -104,6 +112,8 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
     okLabel = 'Submit',
     nextLabel = 'Next',
     previousLabel = 'Previous',
+    showCancel = false,
+    cancelLabel = 'Cancel',
     orientation = 'horizontal',
     headerPosition,
     linear = true,
@@ -136,6 +146,8 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
     okLabel?: string;
     nextLabel?: string;
     previousLabel?: string;
+    showCancel?: boolean;
+    cancelLabel?: string;
     dialogClassName?: string;
     dialogPt?: PrimeDialogProps['pt'];
     dialogPtOptions?: PrimeDialogProps['ptOptions'];
@@ -238,6 +250,15 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
 
     const footer = (
         <div className="flex items-center w-full gap-3">
+            {showCancel && (
+                <Button
+                    label={cancelLabel}
+                    icon="pi pi-times"
+                    onClick={() => handleClose(DialogResult.Cancelled)}
+                    disabled={isBusy}
+                    outlined
+                />
+            )}
             {!isFirstStep && (
                 <Button
                     label={previousLabel}
@@ -418,6 +439,8 @@ const StepperCommandDialogComponent = <TCommand extends object = object, TRespon
         okLabel,
         nextLabel,
         previousLabel,
+        showCancel,
+        cancelLabel,
         orientation,
         headerPosition,
         linear,
@@ -455,6 +478,8 @@ const StepperCommandDialogComponent = <TCommand extends object = object, TRespon
                 okLabel={okLabel}
                 nextLabel={nextLabel}
                 previousLabel={previousLabel}
+                showCancel={showCancel}
+                cancelLabel={cancelLabel}
                 orientation={orientation}
                 headerPosition={headerPosition}
                 linear={linear}

From 09a399adc50763f146004dbaaeeff05140523558 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Tue, 11 Aug 2026 14:51:47 +0200
Subject: [PATCH 2/4] Pin the footer cancel to the arm it is supposed to take

Asserting that a button with the right label renders proves almost
nothing here: the dialog already has a close path, and a cancel that
quietly closed as confirmed would look identical in static markup. These
specs run in a DOM, click the real button, and assert which arm ran - the
cancel callback fired, the confirm callback did not, and the dialog
context closed as cancelled. A control spec drives submit through the same
harness, so "confirm never ran" is falsifiable rather than assumed.

Position is asserted as footer layout including the spacer, not as button
order. Order alone cannot tell "before the spacer" from "after it" on the
first step, where there is no Previous to sit between - which is the one
cell where the claim that cancel stays put actually needed proving.

Busy is asserted behaviorally: a click during execution is ignored, and
honored again once it finishes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UWugkmN6NmoemKeTvSKNDg
---
 .../given/a_stepper_dialog_in_the_dom.ts      |  38 +++
 .../and_it_is_asked_for.ts                    | 115 +++++++++
 .../and_it_is_clicked.ts                      | 126 ++++++++++
 .../and_it_is_given_a_label.ts                | 116 ++++++++++
 .../and_it_is_not_asked_for.ts                | 112 +++++++++
 .../and_submit_is_clicked_instead.ts          | 127 ++++++++++
 .../and_the_command_is_executing.ts           | 219 ++++++++++++++++++
 7 files changed, 853 insertions(+)
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_asked_for.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_clicked.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_given_a_label.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_not_asked_for.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_submit_is_clicked_instead.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts

diff --git a/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts b/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts
index a923f70..644a0d9 100644
--- a/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts
+++ b/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts
@@ -85,6 +85,44 @@ export const click = async (dialog: StepperDialogInTheDom, label: string) => {
 export const buttonLabels = (dialog: StepperDialogInTheDom): string[] =>
     Array.from(dialog.container.querySelectorAll('button')).map(button => button.textContent ?? '');
 
+/**
+ * The footer laid out the way it is composed: every button by its label, and the flexible spacer
+ * that divides the dismissal side from the progression side as `'spacer'`. Buttons on their own
+ * cannot say which side of that spacer a button sits on, and on a step that offers no Previous
+ * that is the only thing separating "leads the footer" from "trails it".
+ * @param dialog - The mounted dialog.
+ * @returns The footer's children, in document order.
+ */
+export const footerLayout = (dialog: StepperDialogInTheDom): string[] => {
+    const footer = dialog.container.querySelector('[data-testid="dialog"]')?.firstElementChild;
+
+    return Array.from(footer?.children ?? [])
+        .map(child => child.tagName === 'BUTTON' ? child.textContent ?? '' : 'spacer');
+};
+
+/**
+ * The labels of the buttons the dialog currently renders as disabled, in document order.
+ * Read alongside {@link buttonLabels} so a spec can tell "the button is disabled" apart
+ * from "the button is not there at all".
+ * @param dialog - The mounted dialog.
+ * @returns The disabled button labels, in document order.
+ */
+export const disabledButtonLabels = (dialog: StepperDialogInTheDom): string[] =>
+    Array.from(dialog.container.querySelectorAll('button'))
+        .filter(button => button.disabled)
+        .map(button => button.textContent ?? '');
+
+/**
+ * Runs work that resolves a promise the spec itself holds - settling a command execution,
+ * say - and lets React process everything it triggers before returning.
+ * @param work - The work to run.
+ */
+export const settle = async (work: () => void) => {
+    await act(async () => {
+        work();
+    });
+};
+
 /**
  * The headers of the step panels the wizard actually rendered, in render order.
  * @param dialog - The mounted dialog.
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_asked_for.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_asked_for.ts
new file mode 100644
index 0000000..ea69152
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_asked_for.ts
@@ -0,0 +1,115 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    click,
+    footerLayout,
+    render,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => undefined,
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => ({}),
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+class TestCommand {
+    name: string = '';
+}
+
+const step = (header: string) => React.createElement(StepperPanel, { header }, `${header} content`);
+
+const aWizardOfferingCancel = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        showCancel: true,
+    },
+    step('Step 1'), step('Step 2'), step('Step 3'));
+
+// Dismissal has to sit in the same place all the way through the wizard, or the user learns a
+// position on step one that a later step takes away from them. Previous is the button that comes
+// and goes, so the whole footer is described at each step: that pins the order Cancel keeps, and
+// pins that Previous really did appear - an order proven only where nothing else moves proves
+// nothing about moving. The spacer is described too, because on the first step there is no
+// Previous, and without it "leads the footer" and "trails it" produce the same list of buttons.
+describe('when a stepper dialog is asked for a footer cancel', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerOnTheFirstStep: string[];
+    let footerOnAMiddleStep: string[];
+    let footerOnTheLastStep: string[];
+
+    beforeEach(async () => {
+        dialog = await render(aWizardOfferingCancel());
+        footerOnTheFirstStep = footerLayout(dialog);
+
+        await click(dialog, 'Next');
+        footerOnAMiddleStep = footerLayout(dialog);
+
+        await click(dialog, 'Next');
+        footerOnTheLastStep = footerLayout(dialog);
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_lead_the_footer_with_cancel_on_the_first_step', () => {
+        footerOnTheFirstStep.should.deep.equal(['Cancel', 'spacer', 'Next']);
+    });
+
+    it('should_keep_cancel_leading_the_footer_once_previous_appears', () => {
+        footerOnAMiddleStep.should.deep.equal(['Cancel', 'Previous', 'spacer', 'Next']);
+    });
+
+    it('should_keep_cancel_leading_the_footer_on_the_last_step', () => {
+        footerOnTheLastStep.should.deep.equal(['Cancel', 'Previous', 'spacer', 'Submit']);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_clicked.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_clicked.ts
new file mode 100644
index 0000000..c877765
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_clicked.ts
@@ -0,0 +1,126 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    buttonLabels,
+    click,
+    render,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => ({}),
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+class TestCommand {
+    name: string = '';
+}
+
+const step = (header: string) => React.createElement(StepperPanel, { header }, `${header} content`);
+
+const onCancel = vi.fn(() => true);
+const onConfirm = vi.fn(() => true);
+
+const aWizardOfferingCancel = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        showCancel: true,
+        onCancel,
+        onConfirm,
+    },
+    step('Step 1'), step('Step 2'));
+
+// Closing is not the point - the dialog closes on submit too. The point is *which* arm of
+// handleClose the button takes, so the dialog is given a cancel handler and a confirm handler
+// that are told apart by which one ran, and the result handed to the dialog context is read as a
+// value rather than as "something happened". Cancelled is 4 in the mocked DialogResult; Ok is 3.
+describe('when the footer cancel is clicked', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerBeforeClicking: string[];
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        onConfirm.mockClear();
+
+        dialog = await render(aWizardOfferingCancel());
+        footerBeforeClicking = buttonLabels(dialog);
+
+        await click(dialog, 'Cancel');
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_have_offered_a_cancel_to_click', () => {
+        footerBeforeClicking.should.deep.equal(['Cancel', 'Next']);
+    });
+
+    it('should_invoke_the_cancel_callback_once', () => {
+        onCancel.mock.calls.length.should.equal(1);
+    });
+
+    it('should_leave_the_confirm_callback_alone', () => {
+        onConfirm.mock.calls.length.should.equal(0);
+    });
+
+    it('should_close_through_the_dialog_context_once', () => {
+        closeDialog.mock.calls.length.should.equal(1);
+    });
+
+    it('should_close_with_cancelled', () => {
+        closeDialog.mock.calls[0][0].should.equal(4);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_given_a_label.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_given_a_label.ts
new file mode 100644
index 0000000..8e7e696
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_given_a_label.ts
@@ -0,0 +1,116 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    buttonLabels,
+    click,
+    render,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => ({}),
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+class TestCommand {
+    name: string = '';
+}
+
+const step = (header: string) => React.createElement(StepperPanel, { header }, `${header} content`);
+
+const onCancel = vi.fn(() => true);
+
+const aWizardOfferingADiscard = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        showCancel: true,
+        cancelLabel: 'Discard',
+        onCancel,
+    },
+    step('Step 1'), step('Step 2'));
+
+// A wizard that throws work away wants to say so, so the label is the caller's. Renaming a button
+// is only worth anything if the renamed button is still the one that cancels, so the label and the
+// arm it takes are pinned together - a label the dialog forwarded to some other control would
+// satisfy the first claim on its own.
+describe('when a footer cancel is given a label of its own', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerBeforeClicking: string[];
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+
+        dialog = await render(aWizardOfferingADiscard());
+        footerBeforeClicking = buttonLabels(dialog);
+
+        await click(dialog, 'Discard');
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_lead_the_footer_with_that_label', () => {
+        footerBeforeClicking.should.deep.equal(['Discard', 'Next']);
+    });
+
+    it('should_still_invoke_the_cancel_callback_when_clicked', () => {
+        onCancel.mock.calls.length.should.equal(1);
+    });
+
+    it('should_still_close_with_cancelled', () => {
+        closeDialog.mock.calls[0][0].should.equal(4);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_not_asked_for.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_not_asked_for.ts
new file mode 100644
index 0000000..2c00172
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_it_is_not_asked_for.ts
@@ -0,0 +1,112 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    click,
+    footerLayout,
+    render,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => undefined,
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => ({}),
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+class TestCommand {
+    name: string = '';
+}
+
+const step = (header: string) => React.createElement(StepperPanel, { header }, `${header} content`);
+
+const aWizardWithoutACancelProp = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+    },
+    step('Step 1'), step('Step 2'), step('Step 3'));
+
+// The footer cancel is opt-in, so the wizard that never mentions it must look exactly as it did
+// before the prop existed. Each step is described by the whole footer - spacer included - rather
+// than by the absence of one label: a dialog whose footer rendered nothing at all also has no
+// Cancel in it, and that is a worse bug than the one being guarded against.
+describe('when a stepper dialog is never asked for a footer cancel', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerOnTheFirstStep: string[];
+    let footerOnAMiddleStep: string[];
+    let footerOnTheLastStep: string[];
+
+    beforeEach(async () => {
+        dialog = await render(aWizardWithoutACancelProp());
+        footerOnTheFirstStep = footerLayout(dialog);
+
+        await click(dialog, 'Next');
+        footerOnAMiddleStep = footerLayout(dialog);
+
+        await click(dialog, 'Next');
+        footerOnTheLastStep = footerLayout(dialog);
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_offer_next_alone_on_the_first_step', () => {
+        footerOnTheFirstStep.should.deep.equal(['spacer', 'Next']);
+    });
+
+    it('should_offer_previous_and_next_alone_on_a_middle_step', () => {
+        footerOnAMiddleStep.should.deep.equal(['Previous', 'spacer', 'Next']);
+    });
+
+    it('should_offer_previous_and_submit_alone_on_the_last_step', () => {
+        footerOnTheLastStep.should.deep.equal(['Previous', 'spacer', 'Submit']);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_submit_is_clicked_instead.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_submit_is_clicked_instead.ts
new file mode 100644
index 0000000..68b6ae3
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_submit_is_clicked_instead.ts
@@ -0,0 +1,127 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    buttonLabels,
+    click,
+    render,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+    const commandInstance = {
+        execute: async () => ({ isSuccess: true, isValid: true, validationResults: [], response: {} }),
+    };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => commandInstance,
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+class TestCommand {
+    name: string = '';
+}
+
+const step = (header: string) => React.createElement(StepperPanel, { header }, `${header} content`);
+
+const onCancel = vi.fn(() => true);
+const onConfirm = vi.fn(() => true);
+
+const aWizardOfferingCancel = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        showCancel: true,
+        onCancel,
+        onConfirm,
+    },
+    step('Step 1'), step('Step 2'));
+
+// The control for the cancel arm next door. It runs the exact same harness - same handlers, same
+// dialog context, a footer that still carries Cancel - down the confirm path, so that "the confirm
+// callback never ran" and "the context was closed with Cancelled" are claims this setup is able to
+// falsify. Without it, a footer whose buttons all took the confirm arm and a footer whose confirm
+// arm was unreachable would look identical.
+describe('when submit is clicked on a wizard that also offers a footer cancel', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerBeforeClicking: string[];
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        onConfirm.mockClear();
+
+        dialog = await render(aWizardOfferingCancel());
+        await click(dialog, 'Next');
+        footerBeforeClicking = buttonLabels(dialog);
+
+        await click(dialog, 'Submit');
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_have_offered_cancel_alongside_submit', () => {
+        footerBeforeClicking.should.deep.equal(['Cancel', 'Previous', 'Submit']);
+    });
+
+    it('should_invoke_the_confirm_callback_once', () => {
+        onConfirm.mock.calls.length.should.equal(1);
+    });
+
+    it('should_leave_the_cancel_callback_alone', () => {
+        onCancel.mock.calls.length.should.equal(0);
+    });
+
+    it('should_close_with_ok', () => {
+        closeDialog.mock.calls[0][0].should.equal(3);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts
new file mode 100644
index 0000000..f486188
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts
@@ -0,0 +1,219 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    buttonLabels,
+    click,
+    disabledButtonLabels,
+    render,
+    settle,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+// The dialog is only busy for as long as the command it submitted is still running, so the spec
+// owns that promise and decides when it finishes. `execute` reads the holder on every call rather
+// than closing over one promise, which is what lets each spec start from a fresh, unsettled run.
+const { execution } = vi.hoisted(() => {
+    const execution: { settle: (result: unknown) => void; promise: Promise<unknown> } = {
+        settle: () => { },
+        promise: Promise.resolve({ isSuccess: false, isValid: true }),
+    };
+
+    return { execution };
+});
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+    const commandInstance = { execute: () => execution.promise };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => commandInstance,
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+/** Arms a fresh command run that will not finish until the spec says so. */
+const anUnfinishedCommandRun = () => {
+    execution.promise = new Promise(resolve => {
+        execution.settle = resolve as (result: unknown) => void;
+    });
+};
+
+/** Finishes the armed run the way a rejected command does - the dialog stays open. */
+const aRejectedResult = { isSuccess: false, isValid: true };
+
+class TestCommand {
+    name: string = '';
+}
+
+const step = (header: string) => React.createElement(StepperPanel, { header }, `${header} content`);
+
+const onCancel = vi.fn(() => true);
+
+const aWizardOfferingCancel = (...steps: React.ReactElement[]) => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        showCancel: true,
+        onCancel,
+    },
+    ...steps);
+
+// Busy is only reachable through Submit, and Submit only exists on the last step - so the state the
+// dialog guards against is "the user pressed Submit and the command has not come back yet". A
+// disabled attribute is asserted next to what it is supposed to buy: the click that a live Cancel
+// would have honored does nothing while the command runs, and is honored again once it returns.
+// Reading the attribute alone would pass just as happily on a dialog that disabled Cancel forever.
+describe('when the command submitted from the last step has not returned', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerBeforeSubmitting: string[];
+    let disabledBeforeSubmitting: string[];
+    let footerWhileRunning: string[];
+    let disabledWhileRunning: string[];
+    let cancelCallsWhileRunning: number;
+    let disabledAfterReturning: string[];
+    let cancelCallsAfterReturning: number;
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        anUnfinishedCommandRun();
+
+        dialog = await render(aWizardOfferingCancel(step('Step 1'), step('Step 2'), step('Step 3')));
+        await click(dialog, 'Next');
+        await click(dialog, 'Next');
+        footerBeforeSubmitting = buttonLabels(dialog);
+        disabledBeforeSubmitting = disabledButtonLabels(dialog);
+
+        await click(dialog, 'Submit');
+        footerWhileRunning = buttonLabels(dialog);
+        disabledWhileRunning = disabledButtonLabels(dialog);
+
+        await click(dialog, 'Cancel');
+        cancelCallsWhileRunning = onCancel.mock.calls.length;
+
+        await settle(() => execution.settle(aRejectedResult));
+        disabledAfterReturning = disabledButtonLabels(dialog);
+
+        await click(dialog, 'Cancel');
+        cancelCallsAfterReturning = onCancel.mock.calls.length;
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_have_reached_the_last_step_with_cancel_live', () => {
+        footerBeforeSubmitting.should.deep.equal(['Cancel', 'Previous', 'Submit']);
+    });
+
+    it('should_not_have_had_cancel_disabled_before_submitting', () => {
+        disabledBeforeSubmitting.should.not.contain('Cancel');
+    });
+
+    it('should_keep_cancel_in_the_footer_while_the_command_runs', () => {
+        footerWhileRunning.should.deep.equal(['Cancel', 'Previous', 'Submit']);
+    });
+
+    it('should_disable_cancel_while_the_command_runs', () => {
+        disabledWhileRunning.should.contain('Cancel');
+    });
+
+    it('should_ignore_a_cancel_click_while_the_command_runs', () => {
+        cancelCallsWhileRunning.should.equal(0);
+    });
+
+    it('should_release_cancel_once_the_command_returns', () => {
+        disabledAfterReturning.should.not.contain('Cancel');
+    });
+
+    it('should_honor_a_cancel_click_once_the_command_returns', () => {
+        cancelCallsAfterReturning.should.equal(1);
+    });
+});
+
+// A one-step wizard is its own first and last step, which is the only shape where the busy footer
+// carries no Previous - the cell of the state machine where Cancel is the leading button *and* the
+// dialog is working. On a middle step there is no Submit to press and Previous is itself disabled
+// while busy, so a busy middle step cannot be reached at all.
+describe('when the command submitted from the only step has not returned', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerWhileRunning: string[];
+    let disabledWhileRunning: string[];
+    let cancelCallsWhileRunning: number;
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        anUnfinishedCommandRun();
+
+        dialog = await render(aWizardOfferingCancel(step('Only Step')));
+        await click(dialog, 'Submit');
+        footerWhileRunning = buttonLabels(dialog);
+        disabledWhileRunning = disabledButtonLabels(dialog);
+
+        await click(dialog, 'Cancel');
+        cancelCallsWhileRunning = onCancel.mock.calls.length;
+
+        await settle(() => execution.settle(aRejectedResult));
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_still_lead_the_footer_with_cancel', () => {
+        footerWhileRunning.should.deep.equal(['Cancel', 'Submit']);
+    });
+
+    it('should_disable_cancel_while_the_command_runs', () => {
+        disabledWhileRunning.should.contain('Cancel');
+    });
+
+    it('should_ignore_a_cancel_click_while_the_command_runs', () => {
+        cancelCallsWhileRunning.should.equal(0);
+    });
+});

From ff9cd5b269548a333a2fd2b0c0c9bd765c7a9f15 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Tue, 11 Aug 2026 18:06:46 +0200
Subject: [PATCH 3/4] Withdraw every dismissal route while the command runs

The footer Cancel was disabled once the command was executing, but the header
close and Escape were not, and the busy flag was only raised after awaiting a
consumer's onBeforeExecute transform. An async transform therefore left a
window in which the command was already committed to running while Cancel was
still live: the operator cancelled, the dialog closed reporting cancellation,
and the write landed anyway.

Raise the busy flag as the first statement of the submit path and gate the
header close and Escape on it, so the dialog stops offering an outcome it
cannot deliver.

The existing "ignore a cancel click while the command runs" assertion could
not fail. jsdom returns early from click() on a disabled control, so it only
ever observed the disabled attribute -- the same fact its sibling asserts --
and deleting the click handler outright left the second suite green. That
suite now settles the run and clicks again, so the handler is pinned where it
is used, and the misleading assertion is renamed to what it measures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UWugkmN6NmoemKeTvSKNDg
---
 Source/CommandDialog/StepperCommandDialog.tsx |  31 +++-
 .../given/a_stepper_dialog_in_the_dom.ts      |  10 ++
 .../and_escape_is_pressed.ts                  | 167 +++++++++++++++++
 .../and_the_header_close_is_used.ts           | 159 ++++++++++++++++
 .../and_an_async_transform_has_not_settled.ts | 169 ++++++++++++++++++
 .../and_the_command_is_executing.ts           |  22 ++-
 6 files changed, 549 insertions(+), 9 deletions(-)
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_escape_is_pressed.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_the_header_close_is_used.ts
 create mode 100644 Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_an_async_transform_has_not_settled.ts

diff --git a/Source/CommandDialog/StepperCommandDialog.tsx b/Source/CommandDialog/StepperCommandDialog.tsx
index 5376936..23e50ed 100644
--- a/Source/CommandDialog/StepperCommandDialog.tsx
+++ b/Source/CommandDialog/StepperCommandDialog.tsx
@@ -63,7 +63,12 @@ export interface StepperCommandDialogProps<TCommand extends object, TResponse =
     onClose?: CloseDialog;
     /** Confirm callback — called only after successful command execution. */
     onConfirm?: ConfirmCallback;
-    /** Cancel callback — invoked when the dialog X button is clicked. */
+    /**
+     * Cancel callback — invoked for every dismissal that is not a successful submit: the X in the
+     * dialog header, the Escape key, and the footer Cancel button when `showCancel` is on. Return
+     * `true` to let the dialog close through the dialog context. None of the three is offered while
+     * the command is executing.
+     */
     onCancel?: CancelCallback;
     /** Label for the submit button shown on the last step when valid. Defaults to `'Submit'`. */
     okLabel?: string;
@@ -212,16 +217,23 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
         }
     };
 
+    // Busy is set before anything is awaited, not just around execute(). `onBeforeExecute` may be
+    // async, and from the moment Submit is pressed the dialog is committed to running the command -
+    // so every dismissal has to be withdrawn for the whole window, not only for the part of it the
+    // request is in flight. Setting it after the transform would leave Cancel live while the command
+    // is already on its way: the operator cancels, the dialog closes reporting cancellation, the
+    // transform resolves, and the command executes anyway. The `finally` is what releases it, so the
+    // flag is cleared on the failure paths and on a transform that throws just as it is on success.
     const handleSubmit = async () => {
-        if (onBeforeExecute) {
-            const applied = applyBeforeExecute(onBeforeExecute, commandInstance);
-            setCommandValues(applied instanceof Promise ? await applied : applied);
-        }
-
         setIsBusy(true);
         let result: ICommandResult<TResponse>;
 
         try {
+            if (onBeforeExecute) {
+                const applied = applyBeforeExecute(onBeforeExecute, commandInstance);
+                setCommandValues(applied instanceof Promise ? await applied : applied);
+            }
+
             result = await (commandInstance as unknown as { execute: () => Promise<ICommandResult<TResponse>> }).execute();
         } finally {
             setIsBusy(false);
@@ -294,6 +306,10 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
         </div>
     );
 
+    // The header X and the Escape key are withdrawn on the same flag as the footer Cancel. A
+    // dismissal that still worked mid-flight would close the dialog and then let onSuccess fire on a
+    // dialog that is already gone. PrimeReact gates Escape behind `closable` too, so `closeOnEscape`
+    // is stated rather than load-bearing - it keeps the Escape path guarded on its own terms.
     return (
         <PrimeDialog
             header={headerElement}
@@ -304,7 +320,8 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
             style={{ width, ...style }}
             contentStyle={contentStyle}
             resizable={resizable}
-            closable
+            closable={!isBusy}
+            closeOnEscape={!isBusy}
             className={dialogClassName}
             pt={dialogPt}
             ptOptions={dialogPtOptions}
diff --git a/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts b/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts
index 644a0d9..ae5b11d 100644
--- a/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts
+++ b/Source/CommandDialog/for_StepperCommandDialog/given/a_stepper_dialog_in_the_dom.ts
@@ -74,6 +74,16 @@ export const click = async (dialog: StepperDialogInTheDom, label: string) => {
     });
 };
 
+/**
+ * Presses Escape on the document, which is where a dialog listens for it — the key is not sent to
+ * any one element, so there is no dialog argument to pass.
+ */
+export const pressEscape = async () => {
+    await act(async () => {
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+    });
+};
+
 /**
  * The labels of every button the dialog currently offers. Rendered elements come
  * from the jsdom realm and carry no `should`, so the footer is described as plain
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_escape_is_pressed.ts b/Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_escape_is_pressed.ts
new file mode 100644
index 0000000..f807416
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_escape_is_pressed.ts
@@ -0,0 +1,167 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    click,
+    pressEscape,
+    render,
+    settle,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+// The dialog is only busy for as long as the command it submitted is still running, so the spec
+// owns that promise and decides when it finishes.
+const { execution } = vi.hoisted(() => {
+    const execution: { settle: (result: unknown) => void; promise: Promise<unknown> } = {
+        settle: () => { },
+        promise: Promise.resolve({ isSuccess: false, isValid: true }),
+    };
+
+    return { execution };
+});
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+// PrimeReact hides on Escape only while `closable && closeOnEscape` - both default to true, and its
+// Dialog computes exactly that conjunction before subscribing to the key. The mock reproduces the
+// conjunction so Escape is exercised as a dismissal rather than read back as a prop value.
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: {
+        closable?: boolean;
+        closeOnEscape?: boolean;
+        onHide?: () => void;
+        footer?: React.ReactNode;
+        children?: React.ReactNode;
+    }) => {
+        const closesOnEscape = props.closable !== false && props.closeOnEscape !== false;
+        const onHide = props.onHide;
+
+        React.useEffect(() => {
+            if (!closesOnEscape) {
+                return () => { };
+            }
+
+            const dismiss = (event: KeyboardEvent) => {
+                if (event.key === 'Escape') {
+                    onHide?.();
+                }
+            };
+
+            document.addEventListener('keydown', dismiss);
+            return () => document.removeEventListener('keydown', dismiss);
+        }, [closesOnEscape, onHide]);
+
+        return React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children);
+    },
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+    const commandInstance = { execute: () => execution.promise };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => commandInstance,
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+/** Arms a fresh command run that will not finish until the spec says so. */
+const anUnfinishedCommandRun = () => {
+    execution.promise = new Promise(resolve => {
+        execution.settle = resolve as (result: unknown) => void;
+    });
+};
+
+/** Finishes the armed run the way a rejected command does - the dialog stays open. */
+const aRejectedResult = { isSuccess: false, isValid: true };
+
+class TestCommand {
+    name: string = '';
+}
+
+const onCancel = vi.fn(() => true);
+
+const aWizard = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        onCancel,
+    },
+    React.createElement(StepperPanel, { header: 'Only Step' }, 'Only Step content'));
+
+// Escape is the dismissal with no control to disable - the dialog can only refuse it by telling
+// PrimeReact not to listen while the command runs. Pressing it in both states is what separates
+// "refused for now" from "never listened at all": the second press, after the command has returned,
+// has to be honored, or the silence during the run says nothing about the guard.
+describe('when escape is pressed on a wizard whose command has not returned', () => {
+    let dialog: StepperDialogInTheDom;
+    let cancelCallsWhileRunning: number;
+    let cancelCallsAfterReturning: number;
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        anUnfinishedCommandRun();
+
+        dialog = await render(aWizard());
+        await click(dialog, 'Submit');
+
+        await pressEscape();
+        cancelCallsWhileRunning = onCancel.mock.calls.length;
+
+        await settle(() => execution.settle(aRejectedResult));
+
+        await pressEscape();
+        cancelCallsAfterReturning = onCancel.mock.calls.length;
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_not_dismiss_on_escape_while_the_command_runs', () => {
+        cancelCallsWhileRunning.should.equal(0);
+    });
+
+    it('should_dismiss_on_escape_once_the_command_returns', () => {
+        cancelCallsAfterReturning.should.equal(1);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_the_header_close_is_used.ts b/Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_the_header_close_is_used.ts
new file mode 100644
index 0000000..0a8e600
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_dismissing_while_the_command_runs/and_the_header_close_is_used.ts
@@ -0,0 +1,159 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    buttonLabels,
+    click,
+    render,
+    settle,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+// The dialog is only busy for as long as the command it submitted is still running, so the spec
+// owns that promise and decides when it finishes.
+const { execution } = vi.hoisted(() => {
+    const execution: { settle: (result: unknown) => void; promise: Promise<unknown> } = {
+        settle: () => { },
+        promise: Promise.resolve({ isSuccess: false, isValid: true }),
+    };
+
+    return { execution };
+});
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+// PrimeReact renders the header close control only while `closable` (default true). The mock
+// renders that control on the same condition instead of handing the prop back, so the spec presses
+// the X the operator would press rather than reading what the dialog asked for.
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: {
+        closable?: boolean;
+        onHide?: () => void;
+        footer?: React.ReactNode;
+        children?: React.ReactNode;
+    }) => React.createElement(
+        'div',
+        { 'data-testid': 'dialog' },
+        props.closable === false ? null : React.createElement('button', { onClick: () => props.onHide?.() }, 'X'),
+        props.footer,
+        props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+    const commandInstance = { execute: () => execution.promise };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => commandInstance,
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+/** Arms a fresh command run that will not finish until the spec says so. */
+const anUnfinishedCommandRun = () => {
+    execution.promise = new Promise(resolve => {
+        execution.settle = resolve as (result: unknown) => void;
+    });
+};
+
+/** Finishes the armed run the way a rejected command does - the dialog stays open. */
+const aRejectedResult = { isSuccess: false, isValid: true };
+
+class TestCommand {
+    name: string = '';
+}
+
+const onCancel = vi.fn(() => true);
+
+const aWizard = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        onCancel,
+    },
+    React.createElement(StepperPanel, { header: 'Only Step' }, 'Only Step content'));
+
+// The footer is not the only way out of this dialog: the header carries an X that closes it through
+// the same cancel arm. Withdrawing the footer Cancel while the command runs and leaving the X live
+// would close a working dialog anyway - and then report cancellation for a command that goes on to
+// succeed. The withdrawal is read as a window rather than as a state: the X is gone while the
+// command runs and back once it returns, and the click it takes then is honored, so a dialog that
+// simply never offered an X could not pass.
+describe('when the header close is used on a wizard whose command has not returned', () => {
+    let dialog: StepperDialogInTheDom;
+    let offeredWhileRunning: string[];
+    let offeredAfterReturning: string[];
+    let cancelCallsAfterReturning: number;
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        anUnfinishedCommandRun();
+
+        dialog = await render(aWizard());
+        await click(dialog, 'Submit');
+        offeredWhileRunning = buttonLabels(dialog);
+
+        await click(dialog, 'X');
+
+        await settle(() => execution.settle(aRejectedResult));
+        offeredAfterReturning = buttonLabels(dialog);
+
+        await click(dialog, 'X');
+        cancelCallsAfterReturning = onCancel.mock.calls.length;
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_withdraw_the_header_close_while_the_command_runs', () => {
+        offeredWhileRunning.should.deep.equal(['Submit']);
+    });
+
+    it('should_offer_the_header_close_again_once_the_command_returns', () => {
+        offeredAfterReturning.should.deep.equal(['X', 'Submit']);
+    });
+
+    it('should_honor_the_header_close_once_the_command_returns', () => {
+        cancelCallsAfterReturning.should.equal(1);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_an_async_transform_has_not_settled.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_an_async_transform_has_not_settled.ts
new file mode 100644
index 0000000..d60e227
--- /dev/null
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_an_async_transform_has_not_settled.ts
@@ -0,0 +1,169 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { vi } from 'vitest';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { StepperCommandDialog } from '../../StepperCommandDialog';
+import {
+    buttonLabels,
+    click,
+    render,
+    settle,
+    unmount,
+    type StepperDialogInTheDom
+} from '../given/a_stepper_dialog_in_the_dom';
+
+// `onBeforeExecute` may be async, so pressing Submit opens a window in which the dialog has
+// committed to running the command but the request has not gone out yet. The spec owns the
+// transform's promise so it can hold the dialog inside that window and act on it; `execution`
+// counts the runs, because the whole question is whether a command the operator cancelled ran
+// anyway.
+const { execution } = vi.hoisted(() => ({ execution: { calls: 0 } }));
+
+const { closeDialog } = vi.hoisted(() => ({ closeDialog: vi.fn() }));
+
+vi.mock('primereact/dialog', () => ({
+    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'dialog' }, props.footer, props.children),
+}));
+
+vi.mock('primereact/stepper', () => ({
+    Stepper: (props: { children?: React.ReactNode; activeStep?: number }) =>
+        React.createElement('div', { 'data-testid': 'stepper', 'data-active-step': props.activeStep }, props.children),
+}));
+
+vi.mock('primereact/stepperpanel', () => ({
+    StepperPanel: (props: { header?: string; children?: React.ReactNode }) =>
+        React.createElement('div', { 'data-testid': 'stepper-panel', 'data-header': props.header }, props.children),
+}));
+
+vi.mock('primereact/button', () => ({
+    Button: (props: { label?: string; disabled?: boolean; onClick?: () => void }) =>
+        React.createElement('button', { disabled: props.disabled, onClick: props.onClick }, props.label),
+}));
+
+vi.mock('@cratis/arc.react/dialogs', () => ({
+    DialogResult: { None: 0, Yes: 1, No: 2, Ok: 3, Cancelled: 4 },
+    useDialogContext: () => ({ closeDialog }),
+}));
+
+// The context object is created once rather than per call: this spec renders for real, so an
+// identity that changed on every render would re-run the stepper's error effect forever. The
+// command settles immediately and rejected - the delay under test is the transform's, and a
+// rejected result keeps the dialog open so the state after the window is still observable.
+vi.mock('@cratis/arc.react/commands', () => {
+    const commandFormContext = {
+        isValid: true,
+        setCommandValues: () => { },
+        setCommandResult: () => { },
+        getFieldError: () => undefined,
+    };
+    const commandInstance = {
+        name: '',
+        execute: () => {
+            execution.calls += 1;
+            return Promise.resolve({ isSuccess: false, isValid: true });
+        },
+    };
+
+    return {
+        CommandForm: (props: { children?: React.ReactNode }) =>
+            React.createElement('div', null, props.children),
+        useCommandFormContext: () => commandFormContext,
+        useCommandInstance: () => commandInstance,
+        CommandFormFieldWrapper: (props: { field?: React.ReactNode }) =>
+            React.createElement('div', null, props.field),
+    };
+});
+
+class TestCommand {
+    name: string = '';
+}
+
+const transform: { settle: (values: TestCommand) => void; promise: Promise<TestCommand> } = {
+    settle: () => { },
+    promise: Promise.resolve(new TestCommand()),
+};
+
+/** Arms a fresh transform that will not hand back values until the spec says so. */
+const aTransformThatHasNotSettled = () => {
+    transform.promise = new Promise<TestCommand>(resolve => {
+        transform.settle = resolve;
+    });
+};
+
+const onCancel = vi.fn(() => true);
+const onBeforeExecute = vi.fn(() => transform.promise);
+
+const aWizardOfferingCancel = () => React.createElement(
+    StepperCommandDialog<TestCommand>,
+    {
+        command: TestCommand as unknown as new () => object,
+        visible: true,
+        title: 'Test Dialog',
+        showCancel: true,
+        onCancel,
+        onBeforeExecute,
+    },
+    React.createElement(StepperPanel, { header: 'Only Step' }, 'Only Step content'));
+
+// The dangerous cell of the state machine: submit committed, command not yet sent. A Cancel honored
+// here is a lie - the dialog reports cancellation, the transform then resolves, and the write lands
+// regardless. Which is why the spec does not stop at "Cancel did nothing": it settles the transform
+// and reads that the command really did run, so the silence from the dialog context is measured
+// against a run that happened rather than against a submit that quietly went nowhere.
+describe('when cancel is clicked while an async before-execute transform is still running', () => {
+    let dialog: StepperDialogInTheDom;
+    let footerWhileTransforming: string[];
+    let executeCallsWhileTransforming: number;
+    let closeDialogCallsWhileTransforming: number;
+    let executeCallsAfterSettling: number;
+    let cancelCallsAfterSettling: number;
+
+    beforeEach(async () => {
+        closeDialog.mockClear();
+        onCancel.mockClear();
+        onBeforeExecute.mockClear();
+        execution.calls = 0;
+        aTransformThatHasNotSettled();
+
+        dialog = await render(aWizardOfferingCancel());
+        await click(dialog, 'Submit');
+        footerWhileTransforming = buttonLabels(dialog);
+        executeCallsWhileTransforming = execution.calls;
+
+        await click(dialog, 'Cancel');
+        closeDialogCallsWhileTransforming = closeDialog.mock.calls.length;
+
+        await settle(() => transform.settle(new TestCommand()));
+        executeCallsAfterSettling = execution.calls;
+
+        await click(dialog, 'Cancel');
+        cancelCallsAfterSettling = onCancel.mock.calls.length;
+    });
+
+    afterEach(async () => await unmount(dialog));
+
+    it('should_still_render_a_cancel_to_click', () => {
+        footerWhileTransforming.should.deep.equal(['Cancel', 'Submit']);
+    });
+
+    it('should_not_have_run_the_command_yet', () => {
+        executeCallsWhileTransforming.should.equal(0);
+    });
+
+    it('should_report_no_cancellation_to_the_dialog_context', () => {
+        closeDialogCallsWhileTransforming.should.equal(0);
+    });
+
+    it('should_run_the_command_the_submit_committed_to', () => {
+        executeCallsAfterSettling.should.equal(1);
+    });
+
+    it('should_honor_a_cancel_click_once_the_command_returns', () => {
+        cancelCallsAfterSettling.should.equal(1);
+    });
+});
diff --git a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts
index f486188..2b2f515 100644
--- a/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts
+++ b/Source/CommandDialog/for_StepperCommandDialog/when_offering_a_footer_cancel/and_the_command_is_executing.ts
@@ -164,7 +164,12 @@ describe('when the command submitted from the last step has not returned', () =>
         disabledWhileRunning.should.contain('Cancel');
     });
 
-    it('should_ignore_a_cancel_click_while_the_command_runs', () => {
+    // Named for what it measures. A disabled control never dispatches a click, so this does not
+    // observe a handler turning the click away - it observes that Cancel is out of the click path
+    // altogether. It is kept rather than deleted as a twin of the disabled attribute because it is
+    // the "before" half of the window: without it, the honored click below would be satisfied just
+    // as well by a click that landed while the command was still running.
+    it('should_take_cancel_out_of_the_click_path_while_the_command_runs', () => {
         cancelCallsWhileRunning.should.equal(0);
     });
 
@@ -181,11 +186,17 @@ describe('when the command submitted from the last step has not returned', () =>
 // carries no Previous - the cell of the state machine where Cancel is the leading button *and* the
 // dialog is working. On a middle step there is no Submit to press and Previous is itself disabled
 // while busy, so a busy middle step cannot be reached at all.
+//
+// The run is settled and Cancel clicked a second time for the same reason as next door: the click
+// while busy is turned away by a disabled attribute, not by a handler, so on its own it would pass
+// on a dialog that never wired the button up at all. Clicking again once the command has returned
+// is what puts the onClick inside this suite's reach.
 describe('when the command submitted from the only step has not returned', () => {
     let dialog: StepperDialogInTheDom;
     let footerWhileRunning: string[];
     let disabledWhileRunning: string[];
     let cancelCallsWhileRunning: number;
+    let cancelCallsAfterReturning: number;
 
     beforeEach(async () => {
         closeDialog.mockClear();
@@ -201,6 +212,9 @@ describe('when the command submitted from the only step has not returned', () =>
         cancelCallsWhileRunning = onCancel.mock.calls.length;
 
         await settle(() => execution.settle(aRejectedResult));
+
+        await click(dialog, 'Cancel');
+        cancelCallsAfterReturning = onCancel.mock.calls.length;
     });
 
     afterEach(async () => await unmount(dialog));
@@ -213,7 +227,11 @@ describe('when the command submitted from the only step has not returned', () =>
         disabledWhileRunning.should.contain('Cancel');
     });
 
-    it('should_ignore_a_cancel_click_while_the_command_runs', () => {
+    it('should_take_cancel_out_of_the_click_path_while_the_command_runs', () => {
         cancelCallsWhileRunning.should.equal(0);
     });
+
+    it('should_honor_a_cancel_click_once_the_command_returns', () => {
+        cancelCallsAfterReturning.should.equal(1);
+    });
 });

From bf0816c4fbcdd1a5c6940f9c8672ae051ad29b18 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Tue, 11 Aug 2026 18:06:46 +0200
Subject: [PATCH 4/4] Document the footer cancel and correct what the stepper
 promises

showCancel and cancelLabel shipped as public props with no documentation, and
the surrounding prose still claimed cancel is always available via the header
X -- which was never the whole truth and is now wrong in a second way, since
no dismissal route is offered while the command runs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UWugkmN6NmoemKeTvSKNDg
---
 Documentation/StepperCommandDialog/index.md   | 48 ++++++++---
 .../StepperCommandDialog.stories.tsx          | 82 +++++++++++++++++++
 2 files changed, 120 insertions(+), 10 deletions(-)

diff --git a/Documentation/StepperCommandDialog/index.md b/Documentation/StepperCommandDialog/index.md
index b369880..a4dfb0d 100644
--- a/Documentation/StepperCommandDialog/index.md
+++ b/Documentation/StepperCommandDialog/index.md
@@ -12,7 +12,7 @@ The `StepperCommandDialog` component provides a multi-step wizard dialog interfa
 - All steps share a single command form — one command is submitted at the end
 - Submit button only appears on the last step when all fields are valid
 - Previous button hidden on the first step; Next button hidden on the last step
-- Cancel via the X button in the upper-right corner — no footer Cancel button
+- Cancel via the X button in the dialog header or the Escape key, and — with `showCancel` — a Cancel button in the footer
 - Step number circles change color to indicate validation state (red = errors, green = visited and valid)
 - Non-active steps are visually dimmed to keep focus on the current step
 - Busy state management during command execution
@@ -93,11 +93,13 @@ function MyComponent() {
 - `onUnauthorized`: Callback invoked when authorization fails
 - `onValidationFailure`: Callback invoked on validation errors with the validation results
 - `onConfirm`: Confirm callback — called only after successful command execution
-- `onCancel`: Cancel callback — invoked when the X button is clicked
+- `onCancel`: Cancel callback — invoked for every dismissal that is not a successful submit: the X in the dialog header, the Escape key, and the footer Cancel button when `showCancel` is on
 - `onClose`: Fallback close callback
 - `okLabel`: Label for the submit button shown on the last step when valid (default: `'Submit'`)
 - `nextLabel`: Label for the next step button (default: `'Next'`)
 - `previousLabel`: Label for the previous step button (default: `'Previous'`)
+- `showCancel`: Adds a Cancel button as the first item in the footer (default: `false`)
+- `cancelLabel`: Label for the footer cancel button (default: `'Cancel'`)
 - `isValid`: Additional validity gate combined with command form validity
 - `width`: Dialog width (default: `'600px'`)
 - `resizable`: Whether the dialog can be resized
@@ -169,21 +171,47 @@ This is useful when the dialog opens with pre-populated values that may already
 
 ## Navigation and Submit
 
-| Step position | Footer content |
-|---|---|
-| First step | Next |
-| Middle step | Previous, Next |
-| Last step (invalid) | Previous |
-| Last step (valid) | Previous, Submit |
+| Step position | Footer content | Footer content with `showCancel` |
+|---|---|---|
+| First step | Next | Cancel, Next |
+| Middle step | Previous, Next | Cancel, Previous, Next |
+| Last step (invalid) | Previous | Cancel, Previous |
+| Last step (valid) | Previous, Submit | Cancel, Previous, Submit |
+
+The Submit button is hidden until the user reaches the last step **and** all command form fields across every step pass validation.
+
+## Cancelling
+
+Dismissal is always reachable from the X button in the dialog header and from the Escape key. Both run `onCancel` and close with `DialogResult.Cancelled`.
 
-Cancel is always available via the X button in the dialog header. The Submit button is hidden until the user reaches the last step **and** all command form fields across every step pass validation.
+Set `showCancel` to add a Cancel button to the footer as well. It leads the footer on every step — on the dismissal side of the divider, opposite Next and Submit — and takes exactly the same path as the header X. Use it for a wizard whose dismissal should be as reachable as its submit: a destructive or long flow, or one presented without a visible header. `cancelLabel` renames it.
+
+```tsx
+<StepperCommandDialog<DeleteEnvironment>
+    command={DeleteEnvironment}
+    title="Delete environment"
+    okLabel="Delete"
+    showCancel
+    cancelLabel="Keep environment"
+    onCancel={() => closeDialog(DialogResult.Cancelled)}
+>
+    <StepperPanel header="Environment">
+        <DropdownField<DeleteEnvironment> value={c => c.environmentId} title="Environment" options={environments} />
+    </StepperPanel>
+    <StepperPanel header="Confirm">
+        <InputTextField<DeleteEnvironment> value={c => c.confirmationText} title="Type the environment name to confirm" />
+    </StepperPanel>
+</StepperCommandDialog>
+```
 
 ## Busy State
 
 `StepperCommandDialog` automatically manages a busy state during command execution:
 
 - When Submit is clicked, the Submit button shows a loading spinner and all navigation buttons are disabled.
-- Once execution completes (success or failure), the buttons return to their normal state.
+- Every route out of the dialog is withdrawn for the same window: the footer Cancel is disabled, the header X is not rendered, and Escape does not dismiss. A dialog can therefore never report cancellation for a command that goes on to execute anyway.
+- The window opens the moment Submit is pressed — including while an `async` `onBeforeExecute` transform is still resolving, before the command has been sent.
+- Once execution completes (success or failure), the buttons and every dismissal route return to their normal state.
 
 ## Step Structure
 
diff --git a/Source/CommandDialog/StepperCommandDialog.stories.tsx b/Source/CommandDialog/StepperCommandDialog.stories.tsx
index 1ede92e..d7462d8 100644
--- a/Source/CommandDialog/StepperCommandDialog.stories.tsx
+++ b/Source/CommandDialog/StepperCommandDialog.stories.tsx
@@ -467,6 +467,88 @@ export const WithResponseTypeAndCallbacks: Story = {
     },
 };
 
+/**
+ * `showCancel` adds a Cancel button to the footer, where it leads every step on the dismissal side
+ * of the divider, opposite Next and Submit; `cancelLabel` renames it. The command behind this
+ * wizard takes two seconds, so submitting also shows what the busy window does to every route out
+ * of the dialog: the footer Cancel greys out and the header X disappears until the command returns.
+ */
+export const WithFooterCancel: Story = {
+    render: () => {
+        const [visible, setVisible] = useState(false);
+        const [outcome, setOutcome] = useState('');
+
+        return (
+            <div className="storybook-wrapper">
+                <p className="mb-3 text-sm text-color-secondary">
+                    The footer leads with a renamed Cancel. Fill both steps and click Create to run a 2-second
+                    command — while it runs, neither the footer Cancel nor the header X can dismiss the dialog.
+                </p>
+                <button
+                    className="p-button p-component mb-3"
+                    onClick={() => {
+                        setOutcome('');
+                        setVisible(true);
+                    }}
+                >
+                    Open Dialog
+                </button>
+
+                {outcome && (
+                    <div className="p-3 mt-3 bg-green-100 border-round">
+                        <strong>Outcome:</strong> {outcome}
+                    </div>
+                )}
+
+                <StepperCommandDialog<SlowCreateProjectCommand>
+                    command={SlowCreateProjectCommand}
+                    visible={visible}
+                    title="Create New Project"
+                    okLabel="Create"
+                    showCancel
+                    cancelLabel="Discard draft"
+                    autoServerValidate={false}
+                    onConfirm={async () => {
+                        setOutcome('Created');
+                        setVisible(false);
+                    }}
+                    onCancel={() => {
+                        setOutcome('Discarded');
+                        setVisible(false);
+                    }}
+                >
+                    <StepperPanel header="Basic Info">
+                        <InputTextField<SlowCreateProjectCommand>
+                            value={c => c.name}
+                            title="Project Name"
+                            placeholder="Enter project name (min 2 chars)"
+                        />
+                        <InputTextField<SlowCreateProjectCommand>
+                            value={c => c.email}
+                            title="Contact Email"
+                            placeholder="Enter contact email"
+                            type="email"
+                        />
+                    </StepperPanel>
+                    <StepperPanel header="Details">
+                        <TextAreaField<SlowCreateProjectCommand>
+                            value={c => c.description}
+                            title="Description"
+                            placeholder="Describe the project (min 10 chars)"
+                            rows={4}
+                        />
+                        <NumberField<SlowCreateProjectCommand>
+                            value={c => c.budget}
+                            title="Budget"
+                            placeholder="Enter budget (must be > 0)"
+                        />
+                    </StepperPanel>
+                </StepperCommandDialog>
+            </div>
+        );
+    },
+};
+
 /**
  * A step rendered as `{condition && <StepperPanel/>}` disappears entirely when the condition
  * is false. Toggle the optional step off and the dialog must behave as a genuine two-step