bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/recipes/vue/wizard-form.md

@@ -0,0 +1,1418 @@
+---
+title: Wizard Form (Vue)
+summary: Mailchimp-grade 4-step campaign wizard — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary, BbSmoothHeight step swaps, the step in the URL, save-draft everywhere and a dirty route-leave guard, all through one coopting page context.
+---
+
+# Recipe: Wizard Form (Vue)
+
+A Mailchimp-grade "Create campaign" wizard for a **plain Vue SPA with
+vue-router**: four steps (Audience → Content → Schedule → Review) behind a
+custom stepper header, per-step validation gating forward progress, the
+active step mirrored into the URL, save-draft everywhere, and a dirty-state
+leave guard — all driven by one coopting page context so every leaf
+component takes zero props beyond the id the segment peek renders.
+
+Sibling recipes: [Nuxt](../nuxt/wizard-form.md) ·
+[Inertia](../inertia/wizard-form.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app root.
+- [App Layout](../../guides/app-layout.md) and
+  [Page Shell](../../guides/page-shell.md) copied into
+  `src/components/layout/` per their guides — the page renders inside this
+  chrome.
+
+## Key ideas
+
+- **One coopting page context.** `provideCampaignWizard()` joins the
+  page-shell stack once and owns the draft, the current step, the live
+  validation, and every action. All seven leaves call
+  `useCampaignWizard()` and nothing else — the only prop on the page is
+  the id the segment peek renders.
+- **The stepper is derived state, not navigation chrome.** A step is
+  reachable exactly when every step before it validates — the same
+  predicate `goNext()` uses — so jumping from the header can never outrun
+  the validation gate. Steps already passed show `done` (checkmarked),
+  reachable future steps stay numbered (`upcoming`), and `locked` steps
+  render as disabled `BbBaseButton`s.
+- **Validation is computed live, surfaced on demand.** `issues`
+  recomputes on every keystroke, but the `BbAlert` summary and the inline
+  field errors appear only after a blocked Next (`attempted`), and shrink
+  live as the user fixes each problem.
+- **The step lives in the URL, the draft lives on the server.** `?step=3`
+  is mirrored with `router.replace`; on refresh the saved draft is
+  re-fetched and the requested step is clamped to the first incomplete
+  one, so a shared link can never open a locked step.
+- **One `BbSmoothHeight` wraps the alert + step outlet together**, so the
+  step swap _and_ the validation summary appearing both glide instead of
+  snapping. Conditional regions inside a step (the scheduled-date fields)
+  need no wrapper of their own — the same resize observer catches them.
+- **Back and Save draft are always free; validation only guards forward.**
+  The page's one `variant="primary"` is the final Send/Schedule submit,
+  with `:loading` riding `ctx.submitting`.
+- **Leaving is guarded by a snapshot compare.** `dirty` is a JSON diff
+  against the last saved draft; `onBeforeRouteLeave` + `useConfirm` ask
+  before losing changes, and both submit and discard reset the snapshot so
+  they never double-prompt.
+
+## Page anatomy
+
+```
+CampaignWizard/
+	Index.vue          ← assembly: PageShell slots, stepper, BbSmoothHeight outlet, footer
+	context.ts         ← coopting page context (shell + draft + step + validation + actions)
+	StepperHeader.vue  ← BbBaseButton steps with done/current/upcoming/locked states
+	AudienceStep.vue   ← segment select, audience filters, live recipient estimate
+	ContentStep.vue    ← subject/preheader, body, template picker, send-test
+	ScheduleStep.vue   ← send-now vs scheduled, date + timezone
+	ReviewStep.vue     ← read-only summary with per-section Edit links
+	WizardFooter.vue   ← Back · Save draft · Next / Send with :loading
+	SegmentPeek.vue    ← sidebar workbench for the selected segment
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer) and [Page Shell](../../guides/page-shell.md).
+Wizard archetype: no filter rail, no tabs, no table, no pagination, no bulk
+bar — the work surface is the step outlet.
+
+## Action inventory
+
+| #   | Action                      | Trigger                          | Mechanism                                                      |
+| --- | --------------------------- | -------------------------------- | -------------------------------------------------------------- |
+| 1   | Advance a step (validated)  | footer **Next** (secondary)      | `goNext()` — blocks and raises the `BbAlert` summary on issues |
+| 2   | Go back                     | footer **Back** (ghost)          | `goBack()` — never validated                                   |
+| 3   | Jump to an unlocked step    | stepper header                   | `goToStep()`; locked steps are disabled `BbBaseButton`s        |
+| 4   | Edit a section from Review  | per-section **Edit** links       | `goToStep()` back to that step                                 |
+| 5   | Save draft                  | footer ghost, on every step      | `saveDraft()` → API + snapshot reset + toast                   |
+| 6   | Send a test email           | Content step ghost               | `sendTest()` — validates content first, auto-loading button    |
+| 7   | Send / schedule campaign    | Review, the page's one `primary` | `submit()` with `:loading`, whole-wizard validation            |
+| 8   | Discard draft               | topbar, destructive              | `useConfirm` → delete + navigate to `/campaigns`               |
+| 9   | Peek the segment            | segment name (Audience & Review) | `peekSegment()` → shell stack                                  |
+| 10  | Leave with unsaved changes  | any route navigation             | `onBeforeRouteLeave` guard → `useConfirm`                      |
+| 11  | Restore position on refresh | URL `?step=N`                    | step mirrored via `router.replace`, clamped on load            |
+
+## The code
+
+### context.ts
+
+```ts
+// CampaignWizard/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	watchEffect,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { onBeforeRouteLeave, useRoute, useRouter } from 'vue-router';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { api } from '@/api';
+import type { Campaign, Segment } from '@/types';
+
+/**
+ * What the sidebar can show: the audience segment behind the campaign.
+ * `title` is what `PageShell`'s `#sidebar-title` slot renders — without it the
+ * peek opens with an empty header.
+ */
+export type PeekItem = { type: 'segment'; id: number; title: string };
+
+export type StepKey = 'audience' | 'content' | 'schedule' | 'review';
+export type StepStatus = 'done' | 'current' | 'upcoming' | 'locked';
+export type SendMode = 'now' | 'scheduled';
+
+export const STEPS: Array<{ key: StepKey; label: string }> = [
+	{ key: 'audience', label: 'Audience' },
+	{ key: 'content', label: 'Content' },
+	{ key: 'schedule', label: 'Schedule' },
+	{ key: 'review', label: 'Review' },
+];
+
+export interface CampaignTemplate {
+	id: string;
+	name: string;
+	description: string;
+}
+
+export const TEMPLATES: CampaignTemplate[] = [
+	{
+		id: 'product-update',
+		name: 'Product update',
+		description: 'Hero image, feature blocks, one CTA.',
+	},
+	{
+		id: 'newsletter',
+		name: 'Newsletter',
+		description: 'Multi-story digest with section dividers.',
+	},
+	{
+		id: 'plain-text',
+		name: 'Plain text',
+		description: 'No chrome — reads like a personal email.',
+	},
+];
+
+export const TIMEZONES = [
+	{ label: 'Rome (CET)', value: 'Europe/Rome' },
+	{ label: 'London (GMT)', value: 'Europe/London' },
+	{ label: 'New York (ET)', value: 'America/New_York' },
+	{ label: 'Chicago (CT)', value: 'America/Chicago' },
+	{ label: 'Los Angeles (PT)', value: 'America/Los_Angeles' },
+	{ label: 'Tokyo (JST)', value: 'Asia/Tokyo' },
+	{ label: 'Sydney (AEST)', value: 'Australia/Sydney' },
+];
+
+export const COUNTRIES = [
+	{ label: 'Italy', value: 'IT' },
+	{ label: 'France', value: 'FR' },
+	{ label: 'Germany', value: 'DE' },
+	{ label: 'United Kingdom', value: 'GB' },
+	{ label: 'United States', value: 'US' },
+	{ label: 'Canada', value: 'CA' },
+];
+
+/** Everything the four steps edit. Persisted verbatim by saveDraft/submit. */
+export interface CampaignDraft {
+	// Audience
+	segmentId: number | null;
+	/** Empty array = every country in the segment. */
+	countries: string[];
+	/** Skip contacts already emailed in the last 7 days. */
+	excludeRecent: boolean;
+	// Content
+	subject: string;
+	preheader: string;
+	body: string;
+	templateId: string | null;
+	// Schedule
+	sendMode: SendMode;
+	/** ISO string from BbDatePickerInput; only meaningful when scheduled. */
+	sendAt: string | null;
+	timezone: string;
+}
+
+export interface StepIssue {
+	/** Draft field the issue belongs to — leaves match on it for inline errors. */
+	field: string;
+	message: string;
+}
+
+export interface CampaignWizardContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	// -- Wizard state ----------------------------------------------------------
+	loading: Ref<boolean>;
+	campaign: Ref<Campaign | null>;
+	draft: CampaignDraft;
+	step: Ref<StepKey>;
+	dirty: ComputedRef<boolean>;
+	lastSavedAt: Ref<string | null>;
+	submitting: Ref<boolean>;
+	// -- Validation ------------------------------------------------------------
+	issues: ComputedRef<Record<StepKey, StepIssue[]>>;
+	/** Steps whose Next was blocked at least once — only they show errors. */
+	attempted: Record<StepKey, boolean>;
+	stepStatus: (key: StepKey) => StepStatus;
+	fieldErrors: (step: StepKey, field: string) => string[];
+	// -- Audience intel --------------------------------------------------------
+	selectedSegment: Ref<Segment | null>;
+	estimatedRecipients: Ref<number | null>;
+	// -- Peek grammar ----------------------------------------------------------
+	peekSegment: () => void;
+	// -- Actions (complete: API + state + toast) --------------------------------
+	goToStep: (key: StepKey) => void;
+	goBack: () => void;
+	goNext: () => void;
+	saveDraft: () => Promise<void>;
+	sendTest: () => Promise<void>;
+	submit: () => Promise<void>;
+	discardDraft: () => Promise<void>;
+}
+
+const key: InjectionKey<CampaignWizardContext> = Symbol('campaign-wizard');
+
+export function provideCampaignWizard(): CampaignWizardContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+	const route = useRoute();
+	const router = useRouter();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+
+	// -- Wizard state -----------------------------------------------------------
+	// Route: `{ path: '/campaigns/:id/edit', component: … }` — the param name
+	// here must match the one your route declares.
+	const campaignId = Number(route.params.id);
+	const campaign = ref<Campaign | null>(null);
+	const loading = ref(true);
+
+	const draft = reactive<CampaignDraft>({
+		segmentId: null,
+		countries: [],
+		excludeRecent: true,
+		subject: '',
+		preheader: '',
+		body: '',
+		templateId: null,
+		sendMode: 'now',
+		sendAt: null,
+		timezone: 'Europe/Rome',
+	});
+
+	// -- Validation ---------------------------------------------------------------
+	// Live on every keystroke; SURFACED only per `attempted` (set when a Next
+	// or submit is blocked), so untouched steps never open covered in red.
+	const issues = computed<Record<StepKey, StepIssue[]>>(() => {
+		const audience: StepIssue[] = [];
+		if (draft.segmentId === null)
+			audience.push({
+				field: 'segmentId',
+				message: 'Choose the segment this campaign goes to.',
+			});
+
+		const content: StepIssue[] = [];
+		if (!draft.subject.trim())
+			content.push({ field: 'subject', message: 'Write a subject line.' });
+		else if (draft.subject.length > 150)
+			content.push({
+				field: 'subject',
+				message: 'Keep the subject under 150 characters.',
+			});
+		if (!draft.body.trim())
+			content.push({
+				field: 'body',
+				message: 'The email body cannot be empty.',
+			});
+		if (draft.templateId === null)
+			content.push({ field: 'templateId', message: 'Pick a template.' });
+
+		const schedule: StepIssue[] = [];
+		if (draft.sendMode === 'scheduled') {
+			if (!draft.sendAt)
+				schedule.push({ field: 'sendAt', message: 'Pick a send date.' });
+			if (!draft.timezone)
+				schedule.push({ field: 'timezone', message: 'Pick a timezone.' });
+		}
+
+		return { audience, content, schedule, review: [] };
+	});
+
+	const attempted = reactive<Record<StepKey, boolean>>({
+		audience: false,
+		content: false,
+		schedule: false,
+		review: false,
+	});
+
+	const fieldErrors = (stepKey: StepKey, field: string): string[] =>
+		attempted[stepKey]
+			? issues.value[stepKey]
+					.filter((issue) => issue.field === field)
+					.map((issue) => issue.message)
+			: [];
+
+	// -- Step machine ---------------------------------------------------------------
+	const step = ref<StepKey>('audience');
+
+	const indexOf = (stepKey: StepKey) =>
+		STEPS.findIndex((item) => item.key === stepKey);
+
+	// The single gating predicate: a step is reachable when every step
+	// before it validates. Next, the stepper, and submit all derive from it.
+	const unlocked = (stepKey: StepKey) =>
+		STEPS.slice(0, indexOf(stepKey)).every(
+			(item) => issues.value[item.key].length === 0
+		);
+
+	const stepStatus = (stepKey: StepKey): StepStatus => {
+		if (stepKey === step.value) return 'current';
+		// Only steps already passed count as done — unlocked future steps stay
+		// numbered (upcoming), not checkmarked.
+		if (indexOf(stepKey) < indexOf(step.value)) return 'done';
+		return unlocked(stepKey) ? 'upcoming' : 'locked';
+	};
+
+	const firstIncompleteStep = (): StepKey =>
+		STEPS.find((item) => issues.value[item.key].length > 0)?.key ?? 'review';
+
+	const goToStep = (stepKey: StepKey) => {
+		if (stepKey !== step.value && stepStatus(stepKey) === 'locked') return;
+		step.value = stepKey;
+	};
+
+	const goBack = () => {
+		const previous = STEPS[indexOf(step.value) - 1];
+		if (previous) step.value = previous.key;
+	};
+
+	const goNext = () => {
+		const current = step.value;
+		if (issues.value[current].length > 0) {
+			attempted[current] = true; // raises the alert + inline errors
+			return;
+		}
+		attempted[current] = false;
+		const next = STEPS[indexOf(current) + 1];
+		if (next) step.value = next.key;
+	};
+
+	// Mirror the step into the URL so refresh and shared links restore it.
+	watch(step, (next) => {
+		void router.replace({
+			query: { ...route.query, step: String(indexOf(next) + 1) },
+		});
+	});
+
+	// -- Audience intel ---------------------------------------------------------------
+	// The select's v-model holds only the id; Review and the summary box need
+	// the record. Same resolve-by-id pattern as the flagship's customer pill.
+	const selectedSegment = ref<Segment | null>(null);
+	watchEffect(async () => {
+		selectedSegment.value =
+			draft.segmentId === null ? null : await api.segments.get(draft.segmentId);
+	});
+
+	const estimatedRecipients = ref<number | null>(null);
+	watchEffect(async () => {
+		if (draft.segmentId === null) {
+			estimatedRecipients.value = null;
+			return;
+		}
+		estimatedRecipients.value = await api.segments.estimate(draft.segmentId, {
+			countries: [...draft.countries],
+			excludeRecent: draft.excludeRecent,
+		});
+	});
+
+	// -- Peek grammar ----------------------------------------------------------------
+	const peekSegment = () => {
+		if (draft.segmentId !== null)
+			shell.push({ type: 'segment', id: draft.segmentId }, true);
+	};
+
+	// -- Persistence + dirty guard ------------------------------------------------------
+	const snapshot = ref('');
+	const lastSavedAt = ref<string | null>(null);
+	const dirty = computed(
+		() => !loading.value && JSON.stringify(draft) !== snapshot.value
+	);
+
+	// Registered here because provideCampaignWizard() runs in the setup of the
+	// route component (Index.vue) — exactly where vue-router allows it.
+	onBeforeRouteLeave(async () => {
+		if (!dirty.value) return true;
+		return confirm({
+			variant: 'destructive',
+			title: 'Leave campaign setup?',
+			text: 'You have unsaved changes. Leave and lose them, or stay and save the draft.',
+			yes: 'Leave',
+			no: 'Keep editing',
+		});
+	});
+
+	// The client gate only guards FORWARD navigation — it never blocks this call.
+	// The endpoint, though, runs the same whole-draft validation the final submit
+	// runs, so saving a half-filled draft rejects with 422. Handle it: an
+	// unhandled rejection here surfaces as a console error and the user gets no
+	// feedback at all.
+	const saveDraft = async () => {
+		try {
+			await api.campaigns.update(campaignId, { ...draft });
+		} catch (error) {
+			const err = error as { status?: number };
+			if (err.status === 422) {
+				toast({
+					title: 'Finish the highlighted fields before saving.',
+					variant: 'destructive',
+				});
+				return;
+			}
+			toast({
+				title: 'Something went wrong. Try again.',
+				variant: 'destructive',
+			});
+			return;
+		}
+		snapshot.value = JSON.stringify(draft);
+		lastSavedAt.value = new Date().toISOString();
+		toast({ title: 'Draft saved.', variant: 'success' });
+	};
+
+	const sendTest = async () => {
+		if (issues.value.content.length > 0) {
+			attempted.content = true; // same surfacing as a blocked Next
+			return;
+		}
+		await api.campaigns.sendTest(campaignId, { ...draft });
+		toast({ title: 'Test email sent to your address.', variant: 'success' });
+	};
+
+	const submitting = ref(false);
+	const submit = async () => {
+		// Whole-wizard validation: land the user on the first broken step.
+		const incomplete = STEPS.find((item) => issues.value[item.key].length > 0);
+		if (incomplete) {
+			attempted[incomplete.key] = true;
+			step.value = incomplete.key;
+			return;
+		}
+		submitting.value = true;
+		try {
+			await api.campaigns.update(campaignId, { ...draft });
+			await api.campaigns.send(campaignId);
+			snapshot.value = JSON.stringify(draft); // the guard has nothing left to protect
+			toast({
+				title:
+					draft.sendMode === 'now'
+						? 'Campaign is on its way.'
+						: 'Campaign scheduled.',
+				variant: 'success',
+			});
+			await router.push('/campaigns');
+		} finally {
+			submitting.value = false;
+		}
+	};
+
+	const discardDraft = async () => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Discard draft',
+			text: `Delete "${campaign.value?.name ?? 'this campaign'}" and everything entered so far? This cannot be undone.`,
+			yes: 'Discard',
+			no: 'Keep draft',
+		});
+		if (!ok) return;
+		snapshot.value = JSON.stringify(draft); // don't double-prompt via the leave guard
+		await api.campaigns.delete(campaignId);
+		toast({ title: 'Draft discarded.', variant: 'success' });
+		await router.push('/campaigns');
+	};
+
+	// -- Load ------------------------------------------------------------------------
+	// The wizard edits a server-side draft (the list page created it before
+	// navigating here, Mailchimp-style), so a refresh restores every field —
+	// and ?step restores the position, clamped so it can't open a locked step.
+	const initialize = async () => {
+		// `get` resolves `null` for an unknown id (a hand-typed URL), so it cannot
+		// be destructured blind — that both fails to type-check and throws at
+		// runtime. Baseline the snapshot either way, otherwise an empty draft
+		// reads as "unsaved changes" and the leave guard fires on a dead page.
+		const loaded = await api.campaigns.get(campaignId);
+		if (loaded) {
+			campaign.value = loaded.campaign;
+			Object.assign(draft, loaded.draft);
+		}
+		snapshot.value = JSON.stringify(draft);
+		const requested = STEPS[Number(route.query.step) - 1]?.key ?? 'audience';
+		step.value =
+			stepStatus(requested) === 'locked' ? firstIncompleteStep() : requested;
+		loading.value = false;
+	};
+	void initialize();
+
+	const ctx: CampaignWizardContext = {
+		shell,
+		loading,
+		campaign,
+		draft,
+		step,
+		dirty,
+		lastSavedAt,
+		submitting,
+		issues,
+		attempted,
+		stepStatus,
+		fieldErrors,
+		selectedSegment,
+		estimatedRecipients,
+		peekSegment,
+		goToStep,
+		goBack,
+		goNext,
+		saveDraft,
+		sendTest,
+		submit,
+		discardDraft,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useCampaignWizard(): CampaignWizardContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useCampaignWizard() called outside CampaignWizard');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- CampaignWizard/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left; save state + the destructive escape right.
+		     Wizard archetype: no page search, no filter rail, no tabs. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs class="min-w-0 flex-auto" :items="crumbs" />
+				<div class="flex shrink-0 items-center gap-3">
+					<span v-if="savedLabel" class="text-xs text-gray-500">{{
+						savedLabel
+					}}</span>
+					<BbButton
+						prepend:icon="lucide:trash-2"
+						variant="destructive"
+						@click="ctx.discardDraft"
+					>
+						Discard draft
+					</BbButton>
+				</div>
+			</div>
+		</template>
+
+		<div class="mx-auto flex w-full max-w-3xl flex-col gap-5 p-4">
+			<header class="flex flex-col gap-0.5">
+				<h1 class="text-lg font-semibold">
+					{{ ctx.campaign.value?.name ?? 'New campaign' }}
+				</h1>
+				<p class="text-sm text-gray-500">
+					Set up the audience, content and schedule, then review and send.
+				</p>
+			</header>
+
+			<StepperHeader />
+
+			<!-- One wrapper around the alert AND the step outlet: the step swap
+			     and the validation summary appearing/shrinking both glide. -->
+			<!-- Enable height motion only after mount so first paint does not
+			     animate in; later step swaps still glide. -->
+			<BbSmoothHeight :disabled="!stepHeightReady">
+				<div class="flex flex-col gap-4">
+					<BbAlert
+						v-if="summaryIssues.length"
+						hide-close
+						icon="lucide:circle-x"
+						:title="`Fix ${summaryIssues.length} ${summaryIssues.length === 1 ? 'issue' : 'issues'} to continue`"
+						variant="destructive"
+					>
+						<template #text>
+							<ul class="list-disc pl-4">
+								<li v-for="issue in summaryIssues" :key="issue.field">
+									{{ issue.message }}
+								</li>
+							</ul>
+						</template>
+					</BbAlert>
+
+					<div v-if="ctx.loading.value" class="flex justify-center p-10">
+						<BbSpinner />
+					</div>
+					<AudienceStep v-else-if="ctx.step.value === 'audience'" />
+					<ContentStep v-else-if="ctx.step.value === 'content'" />
+					<ScheduleStep v-else-if="ctx.step.value === 'schedule'" />
+					<ReviewStep v-else />
+				</div>
+			</BbSmoothHeight>
+
+			<WizardFooter />
+		</div>
+
+		<!-- Clicking the segment's NAME peeks it — Audience step and Review. -->
+		<template #sidebar>
+			<SegmentPeek
+				v-if="ctx.shell.current.value?.type === 'segment'"
+				:segment-id="ctx.shell.current.value.id"
+			/>
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue';
+import {
+	BbAlert,
+	BbBreadcrumbs,
+	BbButton,
+	BbSmoothHeight,
+	BbSpinner,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideCampaignWizard } from './context';
+import AudienceStep from './AudienceStep.vue';
+import ContentStep from './ContentStep.vue';
+import ReviewStep from './ReviewStep.vue';
+import ScheduleStep from './ScheduleStep.vue';
+import SegmentPeek from './SegmentPeek.vue';
+import StepperHeader from './StepperHeader.vue';
+import WizardFooter from './WizardFooter.vue';
+
+const ctx = provideCampaignWizard();
+
+/** Keep SmoothHeight off while the first paint settles (initial load swaps
+ * spinner → step content); enable after 300ms for step-to-step glides. */
+const stepHeightReady = ref(false);
+onMounted(() => {
+	setTimeout(() => {
+		stepHeightReady.value = true;
+	}, 300);
+});
+
+const crumbs = computed(() => [
+	{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
+	{ key: 'campaigns', text: 'Campaigns', to: '/campaigns' },
+	{ key: 'setup', text: ctx.campaign.value?.name ?? 'New campaign' },
+]);
+
+// The summary shows only the CURRENT step's issues, and only once the user
+// tried to leave it — it shrinks live as each problem is fixed.
+const summaryIssues = computed(() =>
+	ctx.attempted[ctx.step.value] ? ctx.issues.value[ctx.step.value] : []
+);
+
+const savedLabel = computed(() => {
+	if (ctx.dirty.value) return 'Unsaved changes';
+	if (!ctx.lastSavedAt.value) return null;
+	const time = new Date(ctx.lastSavedAt.value).toLocaleTimeString('en-US', {
+		hour: 'numeric',
+		minute: '2-digit',
+	});
+	return `Draft saved at ${time}`;
+});
+</script>
+```
+
+### StepperHeader.vue
+
+```vue
+<!-- CampaignWizard/StepperHeader.vue -->
+<template>
+	<nav aria-label="Campaign setup steps" class="flex items-center gap-1">
+		<template v-for="(stepMeta, index) in STEPS" :key="stepMeta.key">
+			<!-- Connector line between steps. -->
+			<div
+				v-if="index > 0"
+				aria-hidden="true"
+				class="h-px min-w-3 flex-1 bg-[var(--bb-border)]"
+			/>
+
+			<!-- The primitive gives element semantics + disabled handling; the
+			     look is entirely ours. Done and upcoming steps jump, locked
+			     steps are inert. -->
+			<BbBaseButton
+				:aria-current="status(stepMeta.key) === 'current' ? 'step' : undefined"
+				class="flex items-center gap-2 rounded-[var(--bb-radius)] px-2 py-1.5 text-sm focus-visible:ring-2 focus-visible:ring-[var(--bb-primary)]"
+				:class="{
+					'bg-[var(--bb-hover)] font-medium':
+						status(stepMeta.key) === 'current',
+					'hover:bg-[var(--bb-hover)]': ['done', 'upcoming'].includes(
+						status(stepMeta.key)
+					),
+					'text-gray-400': status(stepMeta.key) === 'locked',
+				}"
+				:disabled="status(stepMeta.key) === 'locked'"
+				@click="() => ctx.goToStep(stepMeta.key)"
+			>
+				<span
+					class="flex size-5 shrink-0 items-center justify-center rounded-full border text-xs"
+					:class="{
+						'border-transparent bg-[var(--bb-primary)] text-[var(--bb-primary-fg)]':
+							status(stepMeta.key) === 'done',
+						'border-[var(--bb-primary)] text-[color:var(--bb-primary)]':
+							status(stepMeta.key) === 'current',
+						'border-[var(--bb-border)]': status(stepMeta.key) === 'locked',
+					}"
+				>
+					<BbIcon
+						v-if="status(stepMeta.key) === 'done'"
+						icon="lucide:check"
+						size="12"
+					/>
+					<template v-else>{{ index + 1 }}</template>
+				</span>
+				{{ stepMeta.label }}
+			</BbBaseButton>
+		</template>
+	</nav>
+</template>
+
+<script setup lang="ts">
+import { BbBaseButton, BbIcon } from 'bitboss-ui';
+import { STEPS, useCampaignWizard, type StepKey } from './context';
+
+const ctx = useCampaignWizard();
+
+const status = (key: StepKey) => ctx.stepStatus(key);
+</script>
+```
+
+### AudienceStep.vue
+
+```vue
+<!-- CampaignWizard/AudienceStep.vue -->
+<template>
+	<section class="flex flex-col gap-4">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">Who gets this email?</h2>
+			<p class="text-sm text-gray-500">
+				Pick a segment, then narrow it with delivery filters.
+			</p>
+		</div>
+
+		<!-- Query-aware items function: the select searches the API as you type. -->
+		<BbSelect
+			v-model="ctx.draft.segmentId"
+			:errors="segmentErrors"
+			item-text="name"
+			item-value="id"
+			:items="searchSegments"
+			label="Segment"
+			label-mode="outside"
+			placeholder="Search segments…"
+			required
+		/>
+
+		<!-- Resolved segment + live estimate: the context owns both fetches. -->
+		<div
+			v-if="ctx.selectedSegment.value"
+			class="flex flex-col gap-1 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<BbButton size="sm" variant="link" @click="ctx.peekSegment">
+					{{ ctx.selectedSegment.value.name }}
+				</BbButton>
+				<span class="text-xs text-gray-500">
+					Last synced {{ shortDate(ctx.selectedSegment.value.lastSyncedAt) }}
+				</span>
+			</div>
+			<p class="text-gray-500">
+				{{ number.format(ctx.selectedSegment.value.contactCount) }} contacts in
+				the segment ·
+				<strong class="text-[var(--bb-text)]">
+					{{
+						ctx.estimatedRecipients.value === null
+							? '…'
+							: number.format(ctx.estimatedRecipients.value)
+					}}
+				</strong>
+				estimated recipients after filters
+			</p>
+		</div>
+
+		<BbSelect
+			v-model="ctx.draft.countries"
+			:items="COUNTRIES"
+			item-text="label"
+			item-value="value"
+			label="Limit to countries"
+			label-mode="outside"
+			multiple
+			placeholder="All countries"
+		/>
+
+		<BbSwitch
+			v-model="ctx.draft.excludeRecent"
+			description="Avoids fatigue: anyone who already received a campaign this week is skipped."
+			label="Skip contacts emailed in the last 7 days"
+		/>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbSelect, BbSwitch } from 'bitboss-ui';
+import { COUNTRIES, useCampaignWizard } from './context';
+import { api } from '@/api';
+import type { Segment } from '@/types';
+
+const ctx = useCampaignWizard();
+
+const searchSegments = (query: string): Promise<Segment[]> =>
+	api.segments.list({ search: query });
+
+// Inline errors appear only after a blocked Next (attempted), per the context.
+const segmentErrors = computed(() => ctx.fieldErrors('audience', 'segmentId'));
+
+const number = new Intl.NumberFormat('en-US');
+const shortDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+	});
+</script>
+```
+
+### ContentStep.vue
+
+```vue
+<!-- CampaignWizard/ContentStep.vue -->
+<template>
+	<section class="flex flex-col gap-4">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">What does it say?</h2>
+			<p class="text-sm text-gray-500">
+				Subject and preheader are what people see in the inbox list.
+			</p>
+		</div>
+
+		<BbTextInput
+			v-model="ctx.draft.subject"
+			:description="`${ctx.draft.subject.length}/150 characters`"
+			:errors="errorsFor('subject')"
+			label="Subject line"
+			label-mode="outside"
+			placeholder="The July roast drop is here — 20% off subscriptions"
+			required
+		/>
+
+		<BbTextInput
+			v-model="ctx.draft.preheader"
+			description="Optional. Shows after the subject in most inboxes — keep it under 90 characters."
+			label="Preheader"
+			label-mode="outside"
+			placeholder="Three new single origins, roasted this week."
+		/>
+
+		<!-- Fixed rows on purpose: an auto-growing textarea inside BbSmoothHeight
+		     would re-animate the outlet on every line break while typing. -->
+		<BbTextarea
+			v-model="ctx.draft.body"
+			:errors="errorsFor('body')"
+			label="Body"
+			label-mode="outside"
+			placeholder="Write the email…"
+			required
+			:rows="10"
+		/>
+
+		<BbRadioGroup
+			v-model="ctx.draft.templateId"
+			:errors="errorsFor('templateId')"
+			item-text="name"
+			item-value="id"
+			:items="TEMPLATES"
+			legend="Template"
+			name="template"
+			required
+		>
+			<!-- Name + one-line description per option, from the same items. -->
+			<template #label="{ item, text }">
+				<span class="flex flex-col">
+					<span>{{ text }}</span>
+					<span class="text-xs text-gray-500">{{ item.description }}</span>
+				</span>
+			</template>
+		</BbRadioGroup>
+
+		<!-- Auto-loading: the button tracks the async handler by itself. -->
+		<div>
+			<BbButton
+				prepend:icon="lucide:send"
+				variant="ghost"
+				@click="ctx.sendTest"
+			>
+				Send test email
+			</BbButton>
+		</div>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbRadioGroup, BbTextarea, BbTextInput } from 'bitboss-ui';
+import { TEMPLATES, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const errorsFor = (field: string) => ctx.fieldErrors('content', field);
+</script>
+```
+
+### ScheduleStep.vue
+
+```vue
+<!-- CampaignWizard/ScheduleStep.vue -->
+<template>
+	<section class="flex flex-col gap-4">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">When does it go out?</h2>
+			<p class="text-sm text-gray-500">
+				Send it as soon as you confirm, or pick a date.
+			</p>
+		</div>
+
+		<BbRadioGroup
+			v-model="ctx.draft.sendMode"
+			item-text="label"
+			item-value="value"
+			:items="[
+				{
+					label: 'Send now — goes out as soon as you confirm on Review',
+					value: 'now',
+				},
+				{ label: 'Schedule for later', value: 'scheduled' },
+			]"
+			legend="When to send"
+			name="send-mode"
+		/>
+
+		<!-- No inner BbSmoothHeight: the page-level wrapper's resize observer
+		     already animates this region appearing and disappearing. -->
+		<div
+			v-if="ctx.draft.sendMode === 'scheduled'"
+			class="grid gap-4 sm:grid-cols-2"
+		>
+			<BbDatePickerInput
+				v-model="ctx.draft.sendAt"
+				description="Campaigns go out at 9:00 AM local to the timezone you pick."
+				:errors="errorsFor('sendAt')"
+				label="Send date"
+				label-mode="outside"
+				:min="today"
+				required
+			/>
+			<BbSelect
+				v-model="ctx.draft.timezone"
+				:errors="errorsFor('timezone')"
+				item-text="label"
+				item-value="value"
+				:items="TIMEZONES"
+				label="Timezone"
+				label-mode="outside"
+				required
+			/>
+		</div>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { BbDatePickerInput, BbRadioGroup, BbSelect } from 'bitboss-ui';
+import { TIMEZONES, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const errorsFor = (field: string) => ctx.fieldErrors('schedule', field);
+
+// BbDatePickerInput's min takes YYYY-MM-DD.
+const today = new Date().toISOString().slice(0, 10);
+</script>
+```
+
+### ReviewStep.vue
+
+```vue
+<!-- CampaignWizard/ReviewStep.vue -->
+<template>
+	<section class="flex flex-col gap-5">
+		<div class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">Review and send</h2>
+			<p class="text-sm text-gray-500">
+				Everything below is what goes out. Edit any section — your progress is
+				kept.
+			</p>
+		</div>
+
+		<!-- Audience -->
+		<section
+			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+					Audience
+				</h3>
+				<BbButton
+					prepend:icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.goToStep('audience')"
+				>
+					Edit
+				</BbButton>
+			</div>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-gray-500">Segment</dt>
+				<dd>
+					<BbButton size="sm" variant="link" @click="ctx.peekSegment">
+						{{ ctx.selectedSegment.value?.name ?? '—' }}
+					</BbButton>
+				</dd>
+				<dt class="text-gray-500">Countries</dt>
+				<dd>{{ countryNames || 'All countries' }}</dd>
+				<dt class="text-gray-500">Fatigue filter</dt>
+				<dd>
+					{{
+						ctx.draft.excludeRecent
+							? 'Skipping contacts emailed in the last 7 days'
+							: 'Off'
+					}}
+				</dd>
+				<dt class="text-gray-500">Estimated recipients</dt>
+				<dd class="font-medium">
+					{{
+						ctx.estimatedRecipients.value === null
+							? '—'
+							: number.format(ctx.estimatedRecipients.value)
+					}}
+				</dd>
+			</dl>
+		</section>
+
+		<!-- Content -->
+		<section
+			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+					Content
+				</h3>
+				<BbButton
+					prepend:icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.goToStep('content')"
+				>
+					Edit
+				</BbButton>
+			</div>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-gray-500">Subject</dt>
+				<dd class="font-medium">{{ ctx.draft.subject }}</dd>
+				<dt class="text-gray-500">Preheader</dt>
+				<dd>{{ ctx.draft.preheader || '—' }}</dd>
+				<dt class="text-gray-500">Template</dt>
+				<dd>{{ templateName }}</dd>
+				<dt class="text-gray-500">Body</dt>
+				<dd class="text-gray-500">{{ bodyExcerpt }}</dd>
+			</dl>
+		</section>
+
+		<!-- Schedule -->
+		<section
+			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
+		>
+			<div class="flex items-center justify-between gap-2">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+					Schedule
+				</h3>
+				<BbButton
+					prepend:icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.goToStep('schedule')"
+				>
+					Edit
+				</BbButton>
+			</div>
+			<p>{{ scheduleSummary }}</p>
+		</section>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { COUNTRIES, TEMPLATES, TIMEZONES, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const number = new Intl.NumberFormat('en-US');
+
+const countryNames = computed(() =>
+	ctx.draft.countries
+		.map(
+			(code) =>
+				COUNTRIES.find((country) => country.value === code)?.label ?? code
+		)
+		.join(', ')
+);
+
+const templateName = computed(
+	() =>
+		TEMPLATES.find((template) => template.id === ctx.draft.templateId)?.name ??
+		'—'
+);
+
+const bodyExcerpt = computed(() =>
+	ctx.draft.body.length > 140
+		? `${ctx.draft.body.slice(0, 140)}…`
+		: ctx.draft.body
+);
+
+const scheduleSummary = computed(() => {
+	if (ctx.draft.sendMode === 'now')
+		return 'Sends immediately after you confirm.';
+	if (!ctx.draft.sendAt) return '—';
+	const date = new Date(ctx.draft.sendAt).toLocaleDateString('en-US', {
+		weekday: 'short',
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+	const zone =
+		TIMEZONES.find((timezone) => timezone.value === ctx.draft.timezone)
+			?.label ?? ctx.draft.timezone;
+	return `Scheduled for ${date} · 9:00 AM · ${zone}`;
+});
+</script>
+```
+
+### WizardFooter.vue
+
+```vue
+<!-- CampaignWizard/WizardFooter.vue -->
+<template>
+	<footer class="flex items-center justify-between gap-2 border-t pt-4">
+		<!-- Back is always free — never validated, only bounded. -->
+		<BbButton
+			:disabled="isFirst"
+			prepend:icon="lucide:chevron-left"
+			variant="ghost"
+			@click="ctx.goBack"
+		>
+			Back
+		</BbButton>
+
+		<div class="flex items-center gap-2">
+			<!-- On every step, whatever the validation state. -->
+			<BbButton
+				prepend:icon="lucide:save"
+				variant="ghost"
+				@click="ctx.saveDraft"
+			>
+				Save draft
+			</BbButton>
+
+			<BbButton
+				v-if="!isReview"
+				append:icon="lucide:chevron-right"
+				variant="secondary"
+				@click="ctx.goNext"
+			>
+				Next
+			</BbButton>
+
+			<!-- The page's single primary. -->
+			<BbButton
+				v-else
+				:loading="ctx.submitting.value"
+				prepend:icon="lucide:send"
+				variant="primary"
+				@click="ctx.submit"
+			>
+				{{
+					ctx.draft.sendMode === 'now' ? 'Send campaign' : 'Schedule campaign'
+				}}
+			</BbButton>
+		</div>
+	</footer>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { STEPS, useCampaignWizard } from './context';
+
+const ctx = useCampaignWizard();
+
+const isFirst = computed(() => ctx.step.value === STEPS[0].key);
+const isReview = computed(() => ctx.step.value === 'review');
+</script>
+```
+
+### SegmentPeek.vue
+
+```vue
+<!-- CampaignWizard/SegmentPeek.vue -->
+<template>
+	<div v-if="segment" class="flex flex-col gap-4 text-sm">
+		<header class="flex flex-col gap-0.5">
+			<h2 class="text-base font-semibold">{{ segment.name }}</h2>
+			<p class="text-xs text-gray-500">
+				{{ number.format(segment.contactCount) }} contacts · last synced
+				{{ longDate(segment.lastSyncedAt) }}
+			</p>
+		</header>
+
+		<!-- Stat strip. -->
+		<div class="grid grid-cols-3 gap-2">
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Avg. open rate</p>
+				<p class="font-semibold">{{ percent(segment.openRate) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Avg. click rate</p>
+				<p class="font-semibold">{{ percent(segment.clickRate) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Unsubscribes / mo</p>
+				<p class="font-semibold">
+					{{ number.format(segment.monthlyUnsubscribes) }}
+				</p>
+			</div>
+		</div>
+
+		<!-- The segment's definition, so "who is in here" is answerable in place. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Conditions
+			</h3>
+			<ul class="flex flex-col gap-1">
+				<li v-for="rule in segment.rules" :key="rule" class="flex gap-2">
+					<BbIcon
+						class="mt-0.5 shrink-0 text-gray-400"
+						icon="lucide:filter"
+						size="14"
+					/>
+					<span>{{ rule }}</span>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Recent campaigns to this segment: fatigue check before sending. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Recent campaigns
+			</h3>
+			<ul class="flex flex-col">
+				<li
+					v-for="recent in segment.recentCampaigns"
+					:key="recent.id"
+					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
+				>
+					<span>{{ recent.name }}</span>
+					<span class="text-xs text-gray-500">{{
+						longDate(recent.sentAt)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/segments/${segment.id}`"
+				variant="ghost"
+			>
+				Open segment
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, watchEffect } from 'vue';
+import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { api } from '@/api';
+import type { SegmentDetail } from '@/types';
+
+const props = defineProps<{ segmentId: number }>();
+
+const segment = ref<SegmentDetail | null>(null);
+watchEffect(async () => {
+	segment.value = await api.segments.getDetail(props.segmentId);
+});
+
+const number = new Intl.NumberFormat('en-US');
+const percent = (value: number) => `${(value * 100).toFixed(1)}%`;
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** `shell` is joined once in
+  `provideCampaignWizard()`; seven components share the draft, the step
+  machine, validation and every action through one `useCampaignWizard()`
+  call. The only data prop on the page is `SegmentPeek`'s `segment-id`;
+  no component receives a callback.
+- **One gating predicate rules everything.** `unlocked(step)` — every
+  step before it validates — drives the stepper's `upcoming`/`locked`
+  states, `goToStep`'s guard, and (via `issues[current]`) `goNext`. A
+  stepper jump is therefore exactly as safe as pressing Next the right
+  number of times; the header can never smuggle the user past validation.
+  Only steps already passed count as `done` — a defaulted step (Schedule
+  starts valid on "send now") stays numbered (`upcoming`), not
+  checkmarked, until the user actually moves past it, though it is
+  jumpable straight away: there is genuinely nothing left to do there.
+- **Live issues, deferred surfacing.** Recomputing `issues` on every
+  keystroke keeps the stepper and the summary truthful, but errors render
+  only for `attempted` steps — a form that opens covered in red before the
+  user typed anything is the classic wizard failure. Once raised, the
+  summary and inline errors shrink live as each fix lands, and the inputs
+  take plain `:errors` arrays (a non-empty `errors` prop already implies
+  the error state — no separate `has-errors` wiring).
+- **Steps are four components, not one with a `type` prop.** Each step
+  owns its inputs, its formatting helpers, and nothing else; the assembly
+  is a `v-if` chain inside the `BbSmoothHeight` outlet. A single
+  `WizardStep` with a renderer switch is the API-monster seed.
+- **`BbBaseButton` is the right stepper primitive.** The steps are
+  clickable surfaces whose look is entirely bespoke — token-styled pills
+  with a number/check bullet — and the primitive contributes what CSS
+  can't: a real `<button>`, native `disabled` for locked steps, and a
+  focus scaffold (the visible ring is ours, per its guide). `aria-current="step"`
+  is set manually — the prop-based `ariaCurrentValue` only applies to
+  exact-active _links_.
+- **One `BbSmoothHeight`, wrapping alert + outlet.** Both height changes
+  on this page — the step swap and the summary toggling — animate through
+  the same wrapper, so they compose into one glide when Next is blocked.
+  Regions that appear _inside_ a step (the scheduled-date grid) are caught
+  by the same resize observer; and the body textarea keeps fixed `rows`
+  because an auto-growing textarea inside the wrapper would re-animate the
+  outlet on every line break. Height motion is enabled only after mount
+  (`:disabled` until a 300ms `onMounted` flag flips), so the first paint
+  never animates in.
+- **Refresh restores everything** because the two halves of wizard state
+  live in the right places: field values on the server (the list page
+  created the draft record before navigating here, so `saveDraft` is an
+  update, not a create), position in the URL. On load the requested
+  `?step` is clamped to the first incomplete step, so a stale or forged
+  link degrades to the right place instead of an unusable locked screen.
+- **The guard, submit and discard share one snapshot.** `dirty` is a JSON
+  compare against the last save; `submit` and `discardDraft` reset the
+  snapshot before navigating so the route-leave confirm never re-asks
+  about changes that were just sent or deliberately destroyed.
+- **Sizing:** everything follows `md`-first — footer, topbar and step
+  forms use default-size buttons and regular inputs; `sm` appears only on
+  the dense inline surfaces (Review's Edit/segment links, the peek
+  footer). One `variant="primary"` (Send/Schedule); Next is `secondary`;
+  Save draft, Back and Send test are ghosts; the two destructive actions
+  (discard, leave-with-changes) both ride `useConfirm`.
+
+## Variations
+
+- **Branching steps**: make `STEPS` a computed — e.g. an A/B test
+  campaign inserts a "Variants" step after Content. The status predicate,
+  URL mapping and footer already work off the array, so nothing else
+  changes.
+- **Autosave**: debounce a watcher on `draft` that calls a silent
+  `saveDraft` (no toast); the footer button and the topbar save-state stay
+  as the manual escape, and the leave guard almost never fires.
+- **Vertical checklist stepper** (Mailchimp's actual layout): swap
+  `StepperHeader` for a left rail where each step row also shows its
+  one-line summary and the step bodies expand in place — the context and
+  its predicate are unchanged.
+- **Send time**: add an hour `BbSelect` beside the timezone and fold it
+  into `sendAt` on save, replacing the fixed 9:00 AM policy.