bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,1486 @@
+---
+title: Wizard Form (Nuxt)
+summary: Mailchimp-grade 4-step campaign wizard for Nuxt — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary, BbSmoothHeight step swaps, the step mirrored into the URL with navigateTo, useAsyncData + FetchError 422 handling merged into the same validation summary, save-draft everywhere and a dirty route-leave guard, all through one coopting page context.
+---
+
+# Recipe: Wizard Form (Nuxt)
+
+The same Mailchimp-grade "Create campaign" wizard adapted for **Nuxt**: 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.
+Anatomy, components, the context shape, copy and data are identical to the
+Vue recipe; only the data/URL/mutation layer changes — the draft loads
+through `useAsyncData`, mutations go through `$fetch` with `FetchError` 422
+errors merged into the same per-step validation summary, and the step
+mirrors into the URL with `navigateTo`.
+
+Sibling recipes: [Vue](../vue/wizard-form.md) ·
+[Inertia](../inertia/wizard-form.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue`.
+- [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.
+- Server routes: `GET /api/campaigns/:id` (returns `{ campaign, draft }`),
+  `PATCH /api/campaigns/:id` (save draft — `422` with
+  `{ errors: { field: ['message'] } }` on validation failure),
+  `POST /api/campaigns/:id/send-test`, `POST /api/campaigns/:id/send`,
+  `DELETE /api/campaigns/:id`; plus `GET /api/segments/:id`,
+  `GET /api/segments/:id/estimate`, `GET /api/segments` (query-aware
+  search) and `GET /api/segments/:id/detail` for the peek.
+
+## 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 and merges server errors.** `issues`
+  recomputes on every keystroke from client-side checks _and_ any `422`
+  field errors left over from the last save, so a failed save surfaces on
+  the owning step exactly like a blocked Next. The `BbAlert` summary and
+  the inline field errors still appear only after a blocked Next
+  (`attempted`), and shrink live as each problem clears.
+- **The step lives in the URL, the draft lives on the server.** `?step=3`
+  is mirrored with `navigateTo({ query }, { replace: true })`; on refresh
+  `useAsyncData` re-fetches the saved draft 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` (works unchanged in
+  Nuxt) + `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()` → `$fetch` PATCH + snapshot reset + toast                  |
+| 6   | Send a test email           | Content step ghost               | `sendTest()` → `$fetch` POST, validates content first                    |
+| 7   | Send / schedule campaign    | Review, the page's one `primary` | `submit()` with `:loading`, whole-wizard validation, `$fetch` PATCH+POST |
+| 8   | Discard draft               | topbar, destructive              | `useConfirm` → `$fetch` DELETE + `navigateTo('/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 `navigateTo(..., { replace: true })`, 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 } from 'vue-router';
+import { FetchError } from 'ofetch';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import type { Campaign, Segment } from '@/types';
+
+/** What the sidebar can show: the audience segment behind the campaign. */
+export type PeekItem = { type: 'segment'; id: number };
+
+export type StepKey = 'audience' | 'content' | 'schedule' | 'review';
+export type StepStatus = 'done' | 'current' | 'upcoming' | 'locked';
+export type SendMode = 'now' | 'scheduled';
+
+export const STEPS: { 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');
+
+/** Which step owns each server-validated field — used to route a failed
+ * save's 422 errors onto the right step, merged into `issues` below. */
+const FIELDS_BY_STEP: Record<StepKey, string[]> = {
+	audience: ['segmentId'],
+	content: ['subject', 'body', 'templateId'],
+	schedule: ['sendAt', 'timezone'],
+	review: [],
+};
+const stepForField = (field: string): StepKey | undefined =>
+	(Object.keys(FIELDS_BY_STEP) as StepKey[]).find((stepKey) =>
+		FIELDS_BY_STEP[stepKey].includes(field)
+	);
+
+export function provideCampaignWizard(): CampaignWizardContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+	const route = useRoute();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+
+	// -- Wizard state -----------------------------------------------------------
+	const campaignId = Number(route.params.campaignId);
+
+	const draft = reactive<CampaignDraft>({
+		segmentId: null,
+		countries: [],
+		excludeRecent: true,
+		subject: '',
+		preheader: '',
+		body: '',
+		templateId: null,
+		sendMode: 'now',
+		sendAt: null,
+		timezone: 'Europe/Rome',
+	});
+
+	// The draft lives on the server (the list page created it before
+	// navigating here, Mailchimp-style); useAsyncData both fetches it and
+	// gives the page a reactive `pending` flag.
+	const { data } = useAsyncData('campaign', () =>
+		$fetch<{ campaign: Campaign; draft: CampaignDraft }>(
+			`/api/campaigns/${campaignId}`
+		)
+	);
+	const campaign = computed(() => data.value?.campaign ?? null);
+	const loading = computed(() => data.value === null);
+
+	// -- Server-side (422) errors, merged into `issues` below so the stepper,
+	// the alert summary and the inline errors all read one source. -------------
+	const serverErrors = reactive<Record<string, string[]>>({});
+
+	// -- Validation ---------------------------------------------------------------
+	// Live on every keystroke; SURFACED only per `attempted` (set when a Next,
+	// submit or save 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.' });
+		}
+
+		// Merge server (422) errors onto the step that owns each field, so a
+		// failed save surfaces exactly like a blocked Next.
+		const withServerErrors = (
+			stepKey: StepKey,
+			list: StepIssue[]
+		): StepIssue[] => [
+			...list,
+			...FIELDS_BY_STEP[stepKey]
+				.filter((field) => serverErrors[field]?.length)
+				.flatMap((field) =>
+					serverErrors[field].map((message) => ({ field, message }))
+				),
+		];
+
+		return {
+			audience: withServerErrors('audience', audience),
+			content: withServerErrors('content', content),
+			schedule: withServerErrors('schedule', 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. `navigateTo` + `replace: true` is Nuxt's
+	// router.replace — no full navigation, no extra history entry.
+	watch(step, (next) => {
+		void navigateTo(
+			{ query: { ...route.query, step: String(indexOf(next) + 1) } },
+			{ replace: true }
+		);
+	});
+
+	// -- 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 $fetch<Segment>(`/api/segments/${draft.segmentId}`);
+	});
+
+	const estimatedRecipients = ref<number | null>(null);
+	watchEffect(async () => {
+		if (draft.segmentId === null) {
+			estimatedRecipients.value = null;
+			return;
+		}
+		estimatedRecipients.value = await $fetch<number>(
+			`/api/segments/${draft.segmentId}/estimate`,
+			{
+				query: {
+					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
+	);
+
+	// Seed the draft once the fetch lands, and clamp ?step so a stale or
+	// forged link can't open a locked step.
+	watch(
+		data,
+		(response) => {
+			if (!response) return;
+			Object.assign(draft, response.draft);
+			snapshot.value = JSON.stringify(draft);
+			const requested = STEPS[Number(route.query.step) - 1]?.key ?? 'audience';
+			step.value =
+				stepStatus(requested) === 'locked' ? firstIncompleteStep() : requested;
+		},
+		{ immediate: true }
+	);
+
+	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',
+		});
+	});
+
+	// -- Actions --------------------------------------------------------------------
+	// `$fetch` throws a typed `FetchError`; 422 means field errors — merge
+	// them into `serverErrors` (read by `issues` above) and jump to the
+	// first broken step, exactly like a blocked Next.
+	const applyServerErrors = (error: unknown): void => {
+		if (!(error instanceof FetchError) || error.statusCode !== 422) throw error;
+		Object.keys(serverErrors).forEach((field) => delete serverErrors[field]);
+		const incoming = (error.data?.errors as Record<string, string[]>) ?? {};
+		Object.assign(serverErrors, incoming);
+		const brokenStep = Object.keys(incoming)
+			.map(stepForField)
+			.find((found): found is StepKey => Boolean(found));
+		if (brokenStep) {
+			attempted[brokenStep] = true;
+			step.value = brokenStep;
+		}
+	};
+
+	const saveDraft = async () => {
+		Object.keys(serverErrors).forEach((field) => delete serverErrors[field]);
+		try {
+			await $fetch(`/api/campaigns/${campaignId}`, {
+				method: 'PATCH',
+				body: { ...draft },
+			});
+			snapshot.value = JSON.stringify(draft);
+			lastSavedAt.value = new Date().toISOString();
+			toast({ title: 'Draft saved.', variant: 'success' });
+		} catch (error) {
+			applyServerErrors(error);
+		}
+	};
+
+	const sendTest = async () => {
+		if (issues.value.content.length > 0) {
+			attempted.content = true; // same surfacing as a blocked Next
+			return;
+		}
+		await $fetch(`/api/campaigns/${campaignId}/send-test`, {
+			method: 'POST',
+			body: { ...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;
+		Object.keys(serverErrors).forEach((field) => delete serverErrors[field]);
+		try {
+			await $fetch(`/api/campaigns/${campaignId}`, {
+				method: 'PATCH',
+				body: { ...draft },
+			});
+			await $fetch(`/api/campaigns/${campaignId}/send`, { method: 'POST' });
+			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 navigateTo(`/campaigns/${campaignId}`);
+		} catch (error) {
+			applyServerErrors(error);
+		} 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 $fetch(`/api/campaigns/${campaignId}`, { method: 'DELETE' });
+		toast({ title: 'Draft discarded.', variant: 'success' });
+		await navigateTo('/campaigns');
+	};
+
+	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 type { Segment } from '@/types';
+
+const ctx = useCampaignWizard();
+
+// A small JSON endpoint — query-aware, so it stays a live search instead of
+// a static lazy list.
+const searchSegments = (query: string): Promise<Segment[]> =>
+	$fetch<Segment[]>('/api/segments', { query: { 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 type { SegmentDetail } from '@/types';
+
+const props = defineProps<{ segmentId: number }>();
+
+const segment = ref<SegmentDetail | null>(null);
+watchEffect(async () => {
+	segment.value = await $fetch<SegmentDetail>(
+		`/api/segments/${props.segmentId}/detail`
+	);
+});
+
+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.
+- **`FetchError` is the error contract for saves.** `statusCode === 422`
+  means field errors — `applyServerErrors` merges `error.data.errors` into
+  `serverErrors`, which `issues` folds onto the owning step, so a failed
+  save renders in the exact same `BbAlert` summary and inline errors as a
+  client-side block, and jumps the user to the first broken step. Live
+  issues, deferred surfacing still holds: errors render only for
+  `attempted` steps, and shrink as each fix lands.
+- **The step lives in the URL, the draft lives on the server.** `?step=3`
+  mirrors via `navigateTo({ query }, { replace: true })` — no extra
+  history entry; `useAsyncData` re-fetches the saved draft on load, and
+  the requested step is clamped to the first incomplete one, so a stale or
+  forged link degrades to the right place instead of an unusable locked
+  screen.
+- **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.
+- **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 `onBeforeRouteLeave` (works unchanged in
+  Nuxt) 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.