refactor(ui): self-correct the wizard step when its guard breaks

Replace the connection-reset remount mechanism (a reset epoch plus a
keyed wizard remount) with a render-phase reachability clamp. When the
active step's entry guard no longer holds, the wizard re-seats to the
furthest-reachable step using the same derivation it uses on mount,
adjusting state during render rather than via an effect. Reset becomes a
pure delete with no navigation.

Author: iagodahlem

packages/ui/src/components/ConfigureSSO/ConfigureSSOContext.tsx

@@ -46,19 +46,14 @@ export interface ConfigureSSOData {
    */
   primaryEmailAddress: EmailAddressResource | undefined;
   /**
-   * A monotonically-increasing counter bumped once per reset. The top-level
-   * `<Wizard>` is keyed on it, so a bump remounts the wizard and re-derives the
-   * furthest-reachable step for the now-no-connection state. Create never bumps
-   * it, so the create path keeps using a plain `goNext` (no remount, no flash).
-   */
-  resetEpoch: number;
-  /**
-   * Deletes the current connection, then bumps {@link resetEpoch} so the keyed
-   * top-level wizard remounts and re-derives the furthest-reachable step. Reads
-   * the reverification-wrapped `deleteConnection` mutation off the bundle. A
-   * no-op when there is no connection. Reset affordances call this instead of
-   * `useWizard().goToStep`, so they work from ANY footer (including nested SAML
-   * configure footers) without binding to a nested wizard.
+   * Deletes the current connection. Reset does NOT navigate: once the delete
+   * revalidates the source and drops `hasConnection`, the active step's entry
+   * guard breaks and the wizard self-corrects, re-seating to the
+   * furthest-reachable step (the same `initialState` derivation it uses on
+   * mount). Reads the reverification-wrapped `deleteConnection` mutation off the
+   * bundle. A no-op when there is no connection. Reset affordances call this
+   * instead of `useWizard().goToStep`, so they work from ANY footer (including
+   * nested SAML configure footers) without binding to a nested wizard.
    */
   resetConnection: () => Promise<void>;
 }
@@ -101,23 +96,19 @@ export const ConfigureSSOProvider = ({
   primaryEmailAddress,
   children,
 }: PropsWithChildren<ConfigureSSOProviderProps>): JSX.Element => {
-  // Bumped once per reset. The keyed top-level `<Wizard>` remounts on a bump and
-  // re-derives the furthest-reachable step for the now-no-connection state.
-  const [resetEpoch, setResetEpoch] = React.useState(0);
-
   const { deleteConnection } = mutations;
   const connectionId = enterpriseConnection?.id;
 
+  // Reset is pure deletion — no navigation. Deleting revalidates the source and
+  // drops `hasConnection`, which breaks the active step's entry guard; the
+  // wizard self-corrects in its render phase, re-seating to the
+  // furthest-reachable step (verified email → select-provider; unverified →
+  // verify-domain). Never a hardcoded step, never a remount.
   const resetConnection = React.useCallback(async () => {
     if (!connectionId) {
       return;
     }
     await deleteConnection(connectionId);
-    // The delete revalidates the source, dropping `hasConnection`. Bumping the
-    // epoch remounts the keyed wizard, whose `initialState` re-derives the
-    // furthest-reachable step (verified email → select-provider; unverified →
-    // verify-domain) — never a hardcoded step, never a blank pane.
-    setResetEpoch(e => e + 1);
   }, [connectionId, deleteConnection]);
 
   const value = React.useMemo<ConfigureSSOData>(
@@ -128,19 +119,9 @@ export const ConfigureSSOProvider = ({
       testRuns,
       mutations,
       primaryEmailAddress,
-      resetEpoch,
       resetConnection,
     }),
-    [
-      contentRef,
-      enterpriseConnection,
-      mutations,
-      connectionState,
-      testRuns,
-      primaryEmailAddress,
-      resetEpoch,
-      resetConnection,
-    ],
+    [contentRef, enterpriseConnection, mutations, connectionState, testRuns, primaryEmailAddress, resetConnection],
   );
 
   return <ConfigureSSOContext.Provider value={value}>{children}</ConfigureSSOContext.Provider>;

packages/ui/src/components/ConfigureSSO/ConfigureSSOSteps.tsx

@@ -25,7 +25,7 @@ import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationS
  * test satisfied, so a live connection short-circuits straight to confirmation.
  */
 export const ConfigureSSOSteps = (): JSX.Element => {
-  const { connectionState: c, resetEpoch } = useConfigureSSO();
+  const { connectionState: c } = useConfigureSSO();
   const card = useCardState();
 
   const steps = React.useMemo<WizardStepConfig[]>(
@@ -39,18 +39,17 @@ export const ConfigureSSOSteps = (): JSX.Element => {
     [c],
   );
 
-  // Keyed on `resetEpoch`: a reset bumps the epoch, remounting the wizard so its
-  // `initialState` re-derives the furthest-reachable step for the now-no-
-  // connection state. Create does NOT bump the epoch, so the create path keeps
-  // its plain `goNext` (no remount, no create-flash).
+  // Reset does NOT remount the wizard. Deleting the connection breaks the active
+  // step's entry guard, and the machine self-corrects in its render phase,
+  // re-seating to the furthest-reachable step (the same `initialState`
+  // derivation it uses on mount) — no key, no remount, no create-flash.
   //
   // `onStepChange` clears any card-level error whenever the active top-level step
   // actually changes, so a stale failure from one step doesn't leak into the next
   // on a breadcrumb jump or back-nav. The wizard fires it from its dispatch
   // handler — no wizard-level `useEffect` involved.
   return (
     <Wizard
-      key={resetEpoch}
       steps={steps}
       onStepChange={() => card.setError(undefined)}
     >

packages/ui/src/components/ConfigureSSO/ResetConnectionDialog.tsx

@@ -65,11 +65,11 @@ const ResetConnectionDialogContent = withCardStateProvider((props: ResetConnecti
     }
 
     try {
-      // `resetConnection` deletes the connection and bumps the reset epoch, which
-      // remounts the keyed top-level wizard so it re-derives the furthest-
-      // reachable step for the now-no-connection state. No `useWizard()` here —
-      // that lets this dialog be triggered from ANY footer (including the nested
-      // SAML configure footers) without binding to a nested wizard.
+      // `resetConnection` deletes the connection — a pure delete, no navigation.
+      // Dropping `hasConnection` breaks the active step's entry guard, so the
+      // wizard self-corrects to the furthest-reachable step. No `useWizard()`
+      // here — that lets this dialog be triggered from ANY footer (including the
+      // nested SAML configure footers) without binding to a nested wizard.
       await resetConnection();
       onClose();
     } catch (err) {

packages/ui/src/components/ConfigureSSO/__tests__/ResetConnectionDialog.test.tsx

@@ -6,10 +6,10 @@ import { render, screen, waitFor } from '@/test/utils';
 import { CardStateProvider } from '@/ui/elements/contexts';
 
 // The dialog no longer touches the wizard. On confirm it calls the context
-// `resetConnection()` — delete + reset-epoch bump — which remounts the keyed
-// top-level wizard so it re-derives the furthest-reachable step. That lets the
-// dialog be triggered from ANY footer (including nested SAML configure footers)
-// without binding to a nested wizard.
+// `resetConnection()` — a pure delete, no navigation — and the wizard
+// self-corrects to the furthest-reachable step once the active step's guard
+// breaks. That lets the dialog be triggered from ANY footer (including nested
+// SAML configure footers) without binding to a nested wizard.
 const resetConnection = vi.fn();
 
 const connectionMockState = vi.hoisted(() => ({
@@ -21,7 +21,7 @@ vi.mock('../ConfigureSSOContext', () => ({
     enterpriseConnection: connectionMockState.current,
     contentRef: { current: null },
     // The dialog's confirm calls the context `resetConnection`, which owns the
-    // reverification-wrapped delete plus the reset-epoch bump.
+    // reverification-wrapped delete. No navigation — the wizard self-corrects.
     resetConnection,
   }),
 }));

packages/ui/src/components/ConfigureSSO/elements/Step.tsx

@@ -198,10 +198,11 @@ FooterContinue.displayName = 'Step.Footer.Continue';
  * never on verify-domain / select-provider).
  *
  * It deliberately does NOT call `useWizard()`. The confirm path calls the
- * context `resetConnection()` (delete + epoch bump → keyed wizard remount →
- * re-derive to furthest-reachable), so this works from ANY footer — including
- * the nested SAML configure footers, which have their own (linear) wizard. That
- * is what kills the old per-step nested-binding trap.
+ * context `resetConnection()` (a pure delete; the wizard then self-corrects to
+ * the furthest-reachable step when the active step's guard breaks), so this
+ * works from ANY footer — including the nested SAML configure footers, which
+ * have their own (linear) wizard. That is what kills the old per-step
+ * nested-binding trap.
  *
  * `marginInlineStart: 'auto'` pushes it to the far-left of the `justify='end'`
  * footer row, matching the prior destructive affordance.

packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/useWizardMachine.test.tsx

@@ -183,6 +183,131 @@ describe('useWizardMachine — first/last and reachability derivations', () => {
   });
 });
 
+describe('useWizardMachine — reachability clamp (self-correct on a broken guard)', () => {
+  it('re-seats to the furthest-reachable step when the active step guard breaks between renders', () => {
+    // Start with c reachable; the machine seeds on c (furthest reachable).
+    let cOpen = true;
+    const open = () => cOpen;
+    const config = cfg([{ id: 'a' }, { id: 'b', guard: () => true }, { id: 'c', guard: open }]);
+    const { result, rerender } = renderMachine({ config });
+    expect(result.current.current).toBe('c');
+
+    // The connection backing c is deleted: c's guard now breaks. Re-render with a
+    // fresh config object so the memo sees new descriptors. The machine notices
+    // its active step is impossible and re-seats to the furthest-reachable step
+    // (b — a + b still reachable, c gated out).
+    cOpen = false;
+    act(() => {
+      rerender({
+        config: cfg([{ id: 'a' }, { id: 'b', guard: () => true }, { id: 'c', guard: open }]),
+        parentWizard: null,
+        initialStepId: undefined,
+        onStepChange: undefined,
+      });
+    });
+    expect(result.current.current).toBe('b');
+  });
+
+  it('re-seats all the way to the entry step when every later guard breaks', () => {
+    let unlocked = true;
+    const gate = () => unlocked;
+    const { result, rerender } = renderMachine({
+      config: cfg([{ id: 'a' }, { id: 'b', guard: gate }, { id: 'c', guard: gate }]),
+    });
+    expect(result.current.current).toBe('c');
+
+    unlocked = false;
+    act(() => {
+      rerender({
+        config: cfg([{ id: 'a' }, { id: 'b', guard: gate }, { id: 'c', guard: gate }]),
+        parentWizard: null,
+        initialStepId: undefined,
+        onStepChange: undefined,
+      });
+    });
+    expect(result.current.current).toBe('a');
+  });
+
+  it('does NOT move when a guard goes TRUE while the active step still holds (create-style change)', () => {
+    // Seed on a; b is gated out. Opening b later (a guard going TRUE) must not
+    // yank the user forward — a's guard still holds, so there is nothing to fix.
+    let bOpen = false;
+    const bGuard = () => bOpen;
+    const { result, rerender } = renderMachine({
+      config: cfg([{ id: 'a' }, { id: 'b', guard: bGuard }]),
+      initialStepId: 'a',
+    });
+    expect(result.current.current).toBe('a');
+
+    bOpen = true;
+    act(() => {
+      rerender({
+        config: cfg([{ id: 'a' }, { id: 'b', guard: bGuard }]),
+        parentWizard: null,
+        initialStepId: 'a',
+        onStepChange: undefined,
+      });
+    });
+    // a still holds — no clamp. The user advances only via an explicit goNext.
+    expect(result.current.current).toBe('a');
+  });
+
+  it('is a provably one-shot: the clamp re-seats to a guard-passing step and does not loop or re-fire', () => {
+    let cOpen = true;
+    const open = () => cOpen;
+    const { result, rerender } = renderMachine({
+      config: cfg([{ id: 'a' }, { id: 'b', guard: () => true }, { id: 'c', guard: open }]),
+    });
+    expect(result.current.current).toBe('c');
+
+    cOpen = false;
+    act(() => {
+      rerender({
+        config: cfg([{ id: 'a' }, { id: 'b', guard: () => true }, { id: 'c', guard: open }]),
+        parentWizard: null,
+        initialStepId: undefined,
+        onStepChange: undefined,
+      });
+    });
+    // Lands on a guard-passing step (b). A subsequent render with the same broken
+    // config does NOT move it again — b's guard holds, so the clamp is inert.
+    expect(result.current.current).toBe('b');
+    act(() => {
+      rerender({
+        config: cfg([{ id: 'a' }, { id: 'b', guard: () => true }, { id: 'c', guard: open }]),
+        parentWizard: null,
+        initialStepId: undefined,
+        onStepChange: undefined,
+      });
+    });
+    expect(result.current.current).toBe('b');
+  });
+
+  it('does not clamp a nested wizard (isNested) even when its active guard breaks', () => {
+    // A nested machine is guard-less in practice, but the clamp is gated on
+    // !isNested regardless: a nested wizard never re-seats, it bubbles instead.
+    let open = true;
+    const gate = () => open;
+    const { result, rerender } = renderMachine({
+      config: cfg([{ id: 'n0' }, { id: 'n1', guard: gate }]),
+      parentWizard: makeParent(),
+    });
+    expect(result.current.current).toBe('n1');
+
+    open = false;
+    act(() => {
+      rerender({
+        config: cfg([{ id: 'n0' }, { id: 'n1', guard: gate }]),
+        parentWizard: makeParent(),
+        initialStepId: undefined,
+        onStepChange: undefined,
+      });
+    });
+    // Nested: no clamp. current stays put despite the broken guard.
+    expect(result.current.current).toBe('n1');
+  });
+});
+
 describe('useWizardMachine — onStepChange', () => {
   it('fires with the new step id on a goNext / goPrev / goToStep that changes current', () => {
     const onStepChange = vi.fn();

packages/ui/src/components/ConfigureSSO/elements/Wizard/useWizardMachine.ts

@@ -85,6 +85,26 @@ export const useWizardMachine = ({
   const stateRef = React.useRef(state);
   stateRef.current = state;
 
+  // Reachability invariant (adjust-state-during-render — NOT a useEffect): if the
+  // active step's entry guard no longer holds (e.g. the connection backing it was
+  // deleted from a footer reset, or revoked elsewhere), the wizard is sitting on an
+  // impossible step. Re-seat to the furthest-reachable step — the SAME derivation
+  // used on mount (initialState). React discards this render and re-renders before
+  // paint, so the impossible frame never shows. Do NOT "fix" this by adding a
+  // goToStep: navigation here is emergent from the guard state, by design. The
+  // strict condition (current descriptor exists, its guard is false, and the
+  // re-seated step differs) makes it a provably one-shot — initialState always
+  // lands on a guard-passing step, so it cannot loop.
+  if (!isNested) {
+    const currentDescriptor = config.descriptors.find(d => d.id === state.current);
+    if (currentDescriptor && !guardHolds(currentDescriptor)) {
+      const seated = initialState(config);
+      if (seated.current !== state.current) {
+        setState(seated);
+      }
+    }
+  }
+
   // Position of `current` in the static descriptor array — the basis for both
   // first/last detection and the boundary-bubble decision below.
   const indexOfCurrent = (s: WizardState, cfg: WizardConfig): number =>