@eifi1/ui-kit 0.54.0 → 0.55.0

package/src/tour/use-tour-url-sync.ts

@@ -1,266 +0,0 @@
-import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from "react";
-import * as ReactRouter from "react-router";
-import { useLocation, useNavigate, type Navigator } from "react-router";
-import { useSearchParamsState } from "../hooks/use-search-param-state";
-import { useTourOptional, type TourEngine, type TourStart } from "./tour";
-import { liveEngine } from "./tour-engine";
-import { devWarnings } from "./tour-gates";
-
-/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */
-
-export interface UseTourUrlSyncOptions {
-  /**
-   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the
-   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points
-   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:
-   * the parameters are kept until it settles. Under a `TourProvider` the third argument is
-   * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves
-   * both; the fourth is its whole engine, read live (0.50.1, `TourEngine`: `stop`, `next`,
-   * `active`, …). Without a provider `start` and the engine's methods do nothing (a
-   * development build warns) and the engine reads as idle.
-   */
-  launch: (
-    id: string,
-    options: { startIndex: number },
-    start: TourStart,
-    engine: TourEngine,
-  ) => void | Promise<unknown>;
-  /**
-   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the
-   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so
-   * an F5 mid-tour resumes the right variant at the right step. Default `true`.
-   */
-  ready?: boolean;
-  /**
-   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's
-   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.
-   */
-  stepAliases?: readonly string[];
-}
-
-type Place = { pathname: string; search: string; hash: string };
-
-/**
- * Has the router already moved on from the location React is still rendering?
- * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built
- * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.
- *
- * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build
- *   review 0.43, kastlan A2), so the router's own state answers — a navigation still
- *   loading, or a location it has committed that React has not rendered yet.
- * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and
- *   carries where it is.
- * - Anything else answers "not in flight".
- */
-function navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {
-  const state = dataRouter?.router?.state;
-  if (state && (state.navigation?.state ?? "idle") !== "idle") return true;
-  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;
-  if (!live) return false;
-  return (
-    live.pathname !== rendered.pathname ||
-    (live.search ?? "") !== rendered.search ||
-    (live.hash ?? "") !== rendered.hash
-  );
-}
-
-type NavigationProbe = { navigator?: Navigator } | null;
-const NO_NAVIGATION = createContext<NavigationProbe>(null);
-/** The data router's state, as `useSearchParamState` reads it. */
-type DataRouterProbe = {
-  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };
-} | null;
-const NO_DATA_ROUTER = createContext<DataRouterProbe>(null);
-const DataRouterContext: Context<DataRouterProbe> = (() => {
-  try {
-    return (
-      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??
-      NO_DATA_ROUTER
-    );
-  } catch {
-    return NO_DATA_ROUTER;
-  }
-})();
-/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:
- *  a test's partial `vi.mock("react-router")` throws on an export it does not define. */
-const NavigationContext: Context<NavigationProbe> = (() => {
-  try {
-    return (
-      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??
-      NO_NAVIGATION
-    );
-  } catch {
-    return NO_NAVIGATION;
-  }
-})();
-
-/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based.
- *  Floored, as the aliases always were (FLW-9): `?tourStep=2.5` was index 1.5. */
-function stepOf(params: URLSearchParams, aliases: readonly string[]): number {
-  const step = Number(params.get("tourStep"));
-  if (params.has("tourStep")) return Number.isFinite(step) && step >= 1 ? Math.floor(step) - 1 : 0;
-  for (const alias of aliases) {
-    const value = Number(params.get(alias));
-    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
-  }
-  return 0;
-}
-
-/**
- * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,
- * on the kit's engine (`useTourOptional`):
- *
- * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app
- *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —
- *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.
- * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied
- *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.
- * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.
- *
- * Mount it once inside the router and the `TourProvider`. Without a provider it still
- * launches through `launch` and never mirrors.
- */
-export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const { pathname, search, hash } = location;
-  const history = useContext(NavigationContext)?.navigator;
-  const dataRouter = useContext(DataRouterContext);
-  const engine = useTourOptional();
-  const active = engine?.active ?? false;
-  const activeId = engine?.activeId ?? null;
-  const index = engine?.index ?? 0;
-  const urlTour = new URLSearchParams(search).get("tour");
-  const aliases = stepAliases.join("\n");
-
-  const launchRef = useRef(launch);
-  const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);
-  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS, NO_PROVIDER_ENGINE));
-  const activeIdRef = useRef(activeId);
-  useLayoutEffect(() => {
-    launchRef.current = launch;
-    startRef.current = engine?.start ?? noProviderStart;
-    live.set(engine ?? NO_PROVIDER_ENGINE);
-    activeIdRef.current = active ? activeId : null;
-  });
-  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */
-  const seenRef = useRef<string | null>(null);
-  /** A deep link waiting for `ready`. */
-  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);
-  /** A launch under way (an app's `prepare()`). */
-  const launchingRef = useRef(false);
-  /** Bumped when a launch settles, so the mirror looks again. */
-  const [settled, setSettled] = useState(0);
-
-  useEffect(() => {
-    if (urlTour !== seenRef.current) {
-      seenRef.current = urlTour;
-      // Its own mirror writing the running tour back is no new link.
-      pendingRef.current =
-        urlTour && urlTour !== activeIdRef.current
-          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split("\n") : []) }
-          : null;
-    }
-    const pending = pendingRef.current;
-    if (!pending || !ready) return;
-    pendingRef.current = null;
-    launchingRef.current = true;
-    void Promise.resolve()
-      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine))
-      // Said, as `TourProvider`'s own `launch` path says it (FLW-9): swallowed, a launch
-      // that failed was a tour that silently did not start — in kastlan after its
-      // launcher had already turned practice mode on.
-      .catch((error: unknown) => console.error(error))
-      .finally(() => {
-        launchingRef.current = false;
-        setSettled((n) => n + 1);
-      });
-    // Only a change of the parameter, or readiness, starts a tour.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [urlTour, ready]);
-
-  useEffect(() => {
-    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;
-    // A link not yet used keeps its parameters: a reload in that window resumes.
-    if (pendingRef.current || launchingRef.current) return;
-    const tourId = active && activeId ? activeId : null;
-    const own = ["tour", "tourStep", ...(aliases ? aliases.split("\n") : [])];
-    const current = new URLSearchParams(search);
-    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace
-    // clobbers a page's own just-issued navigation, keksdose feedback #4).
-    if (!tourId && !own.some((key) => current.has(key))) return;
-    const next = new URLSearchParams(search);
-    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the
-    // tour's own) go.
-    for (const key of tourId ? own.slice(2) : own) next.delete(key);
-    if (tourId) {
-      next.set("tour", tourId);
-      next.set("tourStep", String(index + 1));
-    }
-    if (next.toString() === current.toString()) return;
-    // Spelled out, not `setSearchParams` ("?…" drops the hash, keksdose dev#495).
-    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [active, activeId, index, pathname, search, hash, settled, aliases]);
-}
-
-/** `start` for a launcher run with no `TourProvider` above `useTourUrlSync`. */
-const noProviderStart: TourStart = () => {
-  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.");
-};
-
-const noProviderCall = () => {
-  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.");
-};
-/** The engine for a launcher run with no `TourProvider` above `useTourUrlSync`: idle. */
-const NO_PROVIDER_ENGINE: TourEngine = {
-  active: false,
-  activeId: null,
-  start: noProviderStart,
-  stop: noProviderCall,
-  next: noProviderCall,
-  prev: noProviderCall,
-  goToStep: noProviderCall,
-  index: 0,
-  total: 0,
-  position: 0,
-  count: 0,
-};
-const ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE) as (keyof TourEngine)[];
-
-/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */
-
-/** The catalogue's state filter. */
-export type TourStateFilter = "all" | "todo" | "done";
-
-/** The catalogue's filters: the search, the group (`null`: every group), the state. */
-export interface TourCatalogueFilter {
-  query: string;
-  group: string | null;
-  state: TourStateFilter;
-}
-
-const STATES: readonly TourStateFilter[] = ["all", "todo", "done"];
-
-/**
- * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each
- * written with `replace` (typing does not bury the Back button), the defaults as the
- * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.
- * `params` renames them (kastlan's `?group`). Requires a react-router Router.
- */
-export function useTourCatalogueUrlState(
-  params: { query?: string; group?: string; state?: string } = {},
-): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {
-  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({
-    query: { param: params.query ?? "q", default: "", history: "replace" },
-    group: { param: params.group ?? "topic", default: null, history: "replace", parse: (raw) => raw || undefined },
-    state: {
-      param: params.state ?? "state",
-      default: "all",
-      history: "replace",
-      parse: (raw) => STATES.find((x) => x === raw),
-    },
-  });
-  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.
-  return { ...filter, onChange: setFilter };
-}

package/src/tour.ts

@@ -1,21 +0,0 @@
-// `@eifi1/ui-kit/tour` — guided tours.
-// A re-slicing of the main barrel, not a new API.
-export * from "./tour/tour";
-// 0.43.0: the tours page (docs/tours-harmonization.md §3, §8) — keksdose's catalogue, its
-// card, the NEW and reset rules, device progress and the URL. `useTourUrlSync` and
-// `useTourCatalogueUrlState` need react-router (a peer already, for /shell).
-export { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from "./tour/tour-catalogue";
-export type { TourCatalogueProps, TourCatalogueCardProps, TourCatalogueLabels } from "./tour/tour-catalogue";
-export { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from "./tour/tour-info";
-export type { TourInfo, TourGroup, TourUpdate, TourCompletions } from "./tour/tour-info";
-// 0.44.0: the writer outside a page (§9.2).
-export { useTourProgress, resetTourProgress, completeTour } from "./tour/use-tour-progress";
-export type { UseTourProgressOptions, TourProgress } from "./tour/use-tour-progress";
-// 0.45.0: progress on the account (§10.2–§10.3) and the end of a session.
-export { signOutTourProgress } from "./tour/use-tour-progress";
-export type { TourProgressAccount, TourProgressAdopt, TourProgressBody } from "./tour/use-tour-progress";
-export { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync";
-export type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from "./tour/use-tour-url-sync";
-// 0.50.0: guided form tours (docs/tours-harmonization.md §11) — "Guide me" inside a form.
-export { TourGuideButton, DEFAULT_TOUR_GUIDE_LABELS } from "./tour/tour-guide-button";
-export type { TourGuideButtonProps, TourGuideLabels } from "./tour/tour-guide-button";

package/src/vite-env.d.ts

@@ -1,23 +0,0 @@
-// Minimal ambient typing for the Vite-injected `import.meta.env` so the package
-// type-checks standalone (consumers provide the real values at build time).
-interface ImportMetaEnv {
-  readonly DEV: boolean;
-  /** Set by vitest, and by nothing else. `DEV` cannot answer "am I under test" —
-   *  a test run is neither a dev build nor a production one, and vitest reports
-   *  `DEV=true` — so anything that should be quiet in a suite has to ask this. */
-  readonly VITEST?: boolean;
-}
-interface ImportMeta {
-  readonly env: ImportMetaEnv;
-  /**
-   * Vite's compile-time glob. Declared here rather than by pulling in
-   * `vite/client` (which drags every asset-module shim with it) or `@types/node`
-   * (which this package deliberately does not depend on — it ships browser code).
-   *
-   * It is what lets a TEST read the package's own sources: `field-invalid.test.tsx`
-   * sweeps the component directory to find a field-shaped control that forgot a
-   * prop, which is the kind of guard the consumer app writes with `readFileSync`
-   * and cannot be written that way here.
-   */
-  glob<T = unknown>(pattern: string, options?: { query?: string; import?: string; eager?: boolean }): Record<string, T>;
-}

package/src/wizard/stepper-nav.tsx

@@ -1,360 +0,0 @@
-import { useId, useLayoutEffect, useMemo, useRef, useState } from "react";
-import type { ReactElement, ReactNode } from "react";
-import { Check } from "lucide-react";
-import { cn } from "../lib/cn";
-import { Button } from "../components/button";
-import { Spinner } from "../components/spinner";
-import type { ButtonVariant } from "../components/button-look";
-import { Modal } from "../components/modal";
-import { alertFrameClass } from "../components/alert-banner";
-import { WizardContextProvider } from "./wizard-context";
-import { DEFAULT_WIZARD_LABELS } from "./types";
-import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import type { UseWizardReturn, WizardFinishResult, WizardLabels } from "./types";
-import type { CommitScope } from "../components/write-lock";
-import { useTourGateRelease } from "../tour/tour-gates";
-
-/**
- * The chrome around a wizard: the step indicator, the step content, and the
- * Cancel / Back / Skip / Next / Finish bar — plus the cancel-confirmation
- * dialog, because "are you sure you want to lose this" is part of the wizard's
- * contract rather than something each app should re-decide.
- *
- * It is a component and not a set of parts for one reason: which button shows,
- * and whether it is enabled, is a function of `wizard` state that was getting
- * re-derived (and re-derived slightly differently) at every call site. Finish is
- * gated on `canFinish`, Next and Skip on `nextBlocked`, and Skip only appears on
- * an `optional` step that is not the last — that policy lives here now.
- *
- * The `<StepperNav>` is also what publishes {@link WizardContextProvider}, which
- * is how a mounted step registers its own validator. A step's
- * `useRhfWizardStep` / `useWizardStepValidate` therefore only works inside one.
- *
- * Which buttons show is read off `wizard` (`canCancel`, `canGoBack`, `canDone`,
- * `isCommitStep`), so the policy options — `cancellable`, `onExit`, `commits`,
- * `onDone` — are all set on `useWizard`. What is set HERE is how the Finish button
- * looks and what wraps it, because that is presentation and usually depends on
- * state the app holds (a "replace everything" toggle, a write lock — `finishCommit`).
- *
- * `TData`'s constraint is `UseWizardOptions`' (its mapped half is for `Parameters<>`).
- */
-export function StepperNav<TData extends object & { [K in keyof TData]: unknown }>({
-  wizard,
-  children,
-  title,
-  description,
-  className,
-  labels,
-  finishVariant = "accent",
-  finishDisabled = false,
-  finishCommit,
-  finishDisabledReason,
-  doneDisabled = false,
-  renderFinish,
-}: {
-  wizard: UseWizardReturn<TData>;
-  children: ReactNode;
-  title?: ReactNode;
-  description?: ReactNode;
-  className?: string;
-  labels?: LabelOverride<WizardLabels>;
-  /** The Finish button's variant — `"danger"` for a destructive commit (an import
-   *  that replaces what is there). Default `"accent"`. Next keeps `"accent"`. */
-  finishVariant?: ButtonVariant;
-  /** Disable Finish for a reason of the app's own, on top of the kit's gates
-   *  (`canFinish`, submitting, validating). */
-  finishDisabled?: boolean;
-  /**
-   * Finish COMMITS — {@link Button}'s `commit`, handed to the Finish button. Under a
-   * locked {@link WriteLockProvider} it is `aria-disabled` but focusable, with the lock's
-   * reason in the kit Tooltip, and a click (or Enter) does not run `wizard.finish`.
-   * Every other button of the bar stays live: the steps before the commit write nothing,
-   * so the whole wizard can still be walked through on a read-only page.
-   *
-   * keksdose G1: its YNAB import runs the mapping wizard on the read-only demo (dev#497)
-   * and locks only the confirm step's Finish — by cloning `commit` into the element
-   * `renderFinish` hands it, because StepperNav took no `commit` of its own. That clone
-   * still works; this is the same thing without one. Named `finishCommit` beside
-   * `finishVariant` / `finishDisabled` rather than a bare `commit`, which on a component
-   * with five buttons would not say which one saves — and would read like `useWizard`'s
-   * `commits`, which is a step's policy, not a lock.
-   */
-  finishCommit?: CommitScope;
-  /**
-   * Why Finish is not available — {@link Button}'s `disabledReason` on the Finish button:
-   * `aria-disabled` and focusable, the reason in the kit Tooltip and on the button's
-   * `aria-describedby`, `wizard.finish` not run. The explained form of `finishDisabled`
-   * (a native `disabled` takes the button out of the tab order, so its reason never
-   * reaches a keyboard). Under a lock with `finishCommit`, the lock's reason wins.
-   */
-  finishDisabledReason?: ReactNode;
-  /**
-   * Disable Done — the button of the last step after a commit — while the step still
-   * has work of its own running. keksdose's YNAB import ends on a recurring step whose
-   * convert loop writes one rule at a time (ynab-import-panel.tsx): leaving mid-loop
-   * abandons the rest. Until now the panel dropped `onDone` for the duration, which
-   * takes the button away instead of saying "not yet": disabled, it stays where the
-   * eye left it and comes back to life when the loop ends.
-   */
-  doneDisabled?: boolean;
-  /**
-   * Wrap the Finish button: receives the kit's button element — already labelled,
-   * gated and wired to `wizard.finish` — and returns what to render in its place.
-   *
-   * ```tsx
-   * renderFinish={(button) => <SaveGuard lock={lock}>{button}</SaveGuard>}
-   * ```
-   *
-   * A wrapper and not a replacement (`finishButton: (props) => …`) or a hook
-   * (`onBeforeFinish`): the app's need is to put something AROUND the commit — a
-   * write-lock tooltip, which has to sit on a wrapping element because a disabled
-   * button receives no pointer events — while the kit keeps owning what the button
-   * says and when it is enabled. A replacement would hand every app the gating to
-   * re-derive (the problem this component exists to end); `onBeforeFinish` can veto
-   * a click but cannot explain a disabled button. The element is a plain `<Button>`,
-   * so a wrapper that clones it with `disabled` works as expected.
-   *
-   * For the write lock itself there is no need to wrap any more: `finishCommit` (and
-   * `finishDisabledReason`) put the kit Button's own Tooltip on Finish. An element
-   * cloned with `commit` here keeps working the same way.
-   */
-  renderFinish?: (button: ReactElement) => ReactNode;
-}) {
-  const l = useKitLabels("wizard", DEFAULT_WIZARD_LABELS, labels);
-  const cancelTitleId = useId();
-
-  // The step area never shrinks below the tallest step shown so far, so the button
-  // bar does not jump up and down as Next and Back move between a long step and a
-  // short one. This replaces a fixed `min-h-[300px]` (carried over from Kastlan,
-  // whose steps are all long forms), which did the same for steps under 300px but
-  // left a short wizard — two fields a step — with a ~200px hole above its buttons.
-  // Measured rather than guessed: the floor is whatever the app's own steps need.
-  const contentRef = useRef<HTMLDivElement>(null);
-  const [contentFloor, setContentFloor] = useState(0);
-  useLayoutEffect(() => {
-    const el = contentRef.current;
-    if (!el || typeof ResizeObserver === "undefined") return;
-    const observer = new ResizeObserver(() => {
-      const h = el.offsetHeight;
-      setContentFloor((floor) => (h > floor ? h : floor));
-    });
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, []);
-
-  const contextValue = useMemo(
-    () => ({
-      registerStepValidate: wizard.registerStepValidate,
-      setNextBlocked: wizard.setNextBlocked,
-    }),
-    [wizard.registerStepValidate, wizard.setNextBlocked],
-  );
-
-  // Finish is only valid once every step before the last has been completed or
-  // skipped (derived once in useWizard). Prevents a restored last-step index
-  // (empty data after a reload) from firing an empty submit.
-  const canFinish = wizard.canFinish;
-
-  // A running tour's `awaitGate` steps (0.50, docs/tours-harmonization.md §11.9): Next
-  // releases "wizard-next" when the wizard moved and refuses it when a validator kept it
-  // in place; Finish releases "wizard-finish" once `onComplete` resolved and refuses it,
-  // with the error's message, when it threw. No-ops without a TourProvider or a tour.
-  const tourGates = useTourGateRelease();
-  // `useWizard`'s goNext/finish resolve their outcome at run time (see their types); a
-  // wizard object built some other way resolves nothing, and nothing is signalled.
-  const goNext = async () => {
-    const moved = (await wizard.goNext()) as unknown as boolean | undefined;
-    if (moved === true) tourGates.release("wizard-next");
-    else if (moved === false) tourGates.refuse("wizard-next");
-  };
-  const finish = async () => {
-    const result = (await wizard.finish()) as unknown as WizardFinishResult | undefined;
-    if (!result) return;
-    if (result.ok) tourGates.release("wizard-finish");
-    else tourGates.refuse("wizard-finish", result.error);
-  };
-
-  // Pending while the step's validators run (an async server check): a spinner and
-  // `aria-busy`, and disabled — the hook's own re-entry guard still refuses a second
-  // press, this just stops it looking like the first one did nothing.
-  const pending = wizard.isValidating;
-  const stepNextLabel = wizard.currentStep.nextLabel;
-
-  // Every branch below assigns it; no initial value to overwrite.
-  let forwardButton: ReactNode;
-  if (wizard.isCommitStep) {
-    const finishButton = (
-      <Button
-        variant={finishVariant}
-        data-tour="wizard-finish"
-        onClick={() => void finish()}
-        // The kit Button's lock: a reason (its own or, with `commit`, the provider's)
-        // wins over `disabled` and keeps the button reachable, saying why.
-        commit={finishCommit}
-        disabledReason={finishDisabledReason}
-        disabled={wizard.isSubmitting || pending || !canFinish || finishDisabled}
-        aria-busy={wizard.isSubmitting || pending || undefined}
-      >
-        {/* Decorative: the button's text is what a reader hears. */}
-        {pending && <Spinner label={null} className="size-4" />}
-        {wizard.isSubmitting ? l.submitting : (stepNextLabel ?? l.finish)}
-      </Button>
-    );
-    forwardButton = renderFinish ? renderFinish(finishButton) : finishButton;
-  } else if (wizard.isLastStep) {
-    // The last step after a commit. Nothing to finish; Done only when the app gave
-    // an `onDone` — otherwise the step carries its own way out.
-    forwardButton = wizard.canDone ? (
-      <Button variant="accent" data-tour="wizard-done" onClick={wizard.done} disabled={doneDisabled}>
-        {stepNextLabel ?? l.done ?? DEFAULT_WIZARD_LABELS.done}
-      </Button>
-    ) : null;
-  } else {
-    forwardButton = (
-      <Button
-        variant="accent"
-        data-tour="wizard-next"
-        onClick={() => void goNext()}
-        disabled={wizard.nextBlocked || pending}
-        aria-busy={pending || undefined}
-      >
-        {pending && <Spinner label={null} className="size-4" />}
-        {stepNextLabel ?? l.next}
-      </Button>
-    );
-  }
-
-  return (
-    <div className={cn("flex flex-col gap-6", className)}>
-      {(title || description) && (
-        <div>
-          {title && <h1 className="text-2xl font-bold tracking-tight text-primary">{title}</h1>}
-          {description && <p className="mt-1 text-sm text-muted">{description}</p>}
-        </div>
-      )}
-
-      {/* Step indicator */}
-      <nav aria-label={l.steps}>
-        <ol className="flex w-full items-center">
-          {wizard.steps.map((step, index) => {
-            const status = wizard.stepStatus(index);
-            const isLast = index === wizard.steps.length - 1;
-
-            return (
-              <li key={step.id} className={cn("flex items-center", !isLast && "flex-1")}>
-                <button
-                  type="button"
-                  onClick={() => wizard.goToStep(index)}
-                  // `canGoToStep` adds the commit lock: once past a committing step,
-                  // the steps up to it are done with and cannot be reopened.
-                  disabled={status === "upcoming" || !wizard.canGoToStep(index)}
-                  aria-current={status === "active" ? "step" : undefined}
-                  className={cn(
-                    "group flex flex-col items-center gap-1.5",
-                    status === "upcoming" ? "cursor-default" : "cursor-pointer",
-                  )}
-                >
-                  {/* Circle */}
-                  <span
-                    className={cn(
-                      "flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-xs font-semibold transition-colors",
-                      status === "completed" && "border-brand bg-brand text-brand-contrast",
-                      status === "active" && "border-brand bg-surface text-brand",
-                      status === "upcoming" && "border-subtle bg-surface text-placeholder",
-                      status === "skipped" && "border-subtle bg-surface-2 text-muted",
-                    )}
-                  >
-                    {status === "completed" ? <Check className="size-4" /> : index + 1}
-                  </span>
-                  {/* Label — hidden on mobile, where the line below carries it */}
-                  <span
-                    className={cn(
-                      "hidden text-xs font-medium md:block",
-                      status === "active" || status === "completed" ? "text-primary" : "text-muted",
-                    )}
-                  >
-                    {step.label}
-                  </span>
-                </button>
-
-                {/* Connector line */}
-                {!isLast && (
-                  <div
-                    className={cn("mx-2 h-0.5 flex-1", status === "completed" ? "bg-brand" : "bg-[var(--border)]")}
-                  />
-                )}
-              </li>
-            );
-          })}
-        </ol>
-        {/* Mobile: the labels above are hidden, so name the current step here */}
-        <p className="mt-2 text-center text-sm font-medium text-primary md:hidden">
-          {l.step(wizard.currentStepIndex + 1, wizard.steps.length)}
-          {" — "}
-          {wizard.currentStep.label}
-        </p>
-      </nav>
-
-      {/* Step content */}
-      <WizardContextProvider value={contextValue}>
-        <div style={contentFloor > 0 ? { minHeight: contentFloor } : undefined}>
-          <div ref={contentRef}>{children}</div>
-        </div>
-      </WizardContextProvider>
-
-      {/* Submit error */}
-      {wizard.error && (
-        <div role="alert" className={cn("text-sm text-danger", alertFrameClass("danger"))}>
-          {wizard.error}
-        </div>
-      )}
-
-      {/* Navigation bar */}
-      <div className="flex items-center justify-between border-t border-subtle pt-4">
-        {/* The empty span keeps the right-hand group on the right when Cancel is off. */}
-        {wizard.canCancel ? (
-          <Button variant="secondary" onClick={wizard.cancel}>
-            {l.cancel}
-          </Button>
-        ) : (
-          <span />
-        )}
-        <div className="flex items-center gap-2">
-          {wizard.canGoBack && (
-            // Disabled, not hidden, while the commit runs: it comes back if the commit
-            // fails, and a button that vanishes mid-click is its own kind of surprise.
-            <Button variant="secondary" onClick={wizard.goBack} disabled={wizard.isSubmitting}>
-              {l.back}
-            </Button>
-          )}
-          {wizard.currentStep.optional && !wizard.isLastStep && !wizard.isCommitStep && (
-            <Button variant="ghost" onClick={wizard.skip} disabled={wizard.nextBlocked || wizard.isValidating}>
-              {l.skip}
-            </Button>
-          )}
-          {forwardButton}
-        </div>
-      </div>
-
-      {/* Cancel confirmation */}
-      {wizard.showCancelDialog && (
-        <Modal onClose={wizard.dismissCancel} labelledBy={cancelTitleId} className="space-y-4">
-          <div className="space-y-1.5">
-            <h2 id={cancelTitleId} className="text-lg font-semibold text-primary">
-              {l.cancelTitle}
-            </h2>
-            <p className="text-sm text-muted">{l.confirmCancel}</p>
-          </div>
-          <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
-            <Button variant="secondary" onClick={wizard.dismissCancel}>
-              {l.cancelDismissLabel}
-            </Button>
-            <Button variant="danger" onClick={wizard.confirmCancel}>
-              {l.cancelConfirmLabel}
-            </Button>
-          </div>
-        </Modal>
-      )}
-    </div>
-  );
-}