@appinternalleads/ui 0.2.0

package/src/components/onboarding/export-format/ExportFormatView.tsx

@@ -0,0 +1,114 @@
+import { Box, Icon, MotionView, Pressable, Text, useSwap } from '../../../core';
+import { Callout, CodeBlock, RadioGroup } from '../../../ds';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import type { OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { usePatternStatus, useSceneReport } from '../shared/runtime';
+import { EXPORT_PRESETS, validateExportFormat, type ExportFormatSettings } from './contract';
+import { currentFormat, type ExportSeed } from './engine';
+import { useExportFormat, type ExportOperations, type ExportRequest } from './runtime';
+import { guarded } from '../shared/guard';
+
+export type ExportFormatProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<ExportFormatSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  result?: OnboardingResult;
+  operations?: ExportOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: ExportSeed;
+  onChange?: (format: string) => void;
+  onExport?: (req: ExportRequest) => void;
+  /** The host's clipboard. Omitted on the web, the browser's is used. */
+  onCopy?: (text: string) => void | Promise<void>;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Export Format** — option rows (C2, B3) with a sky file tile each (a code glyph for text, a
+ * file glyph for binary), and a preview well: "Preview" with a Copy that flashes "Copied" (M8,
+ * announced), the file name, and the output cross-fading per format (M4). Binary formats show
+ * their structure. Chip = the format (M5) → "Exporting…" → "Exported" | "Export failed".
+ */
+function ExportFormatView(props: ExportFormatProps) {
+  const config = resolveConfig(EXPORT_PRESETS, props.preset, props.config);
+  const issues = validateExportFormat(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, operations, reload, initial, onChange, onExport, onCopy, onScene, testID,
+}: Omit<ExportFormatProps, 'config'> & { config: ExportFormatSettings }) {
+  const { colors } = useDs();
+  const pattern = usePatternStatus(status ?? (config.formats.length ? 'ready' : 'empty'), reload);
+  const rt = useExportFormat({ config, operations, result, initial, onChange, onExport, onCopy });
+  const v = rt.view;
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+  const f = config.formats.length ? currentFormat(config, rt.state) : undefined;
+  const previewFade = useSwap(rt.state.format);
+  const copyFade = useSwap(rt.state.copied ? 'copied' : 'copy');
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={v.chip}
+      hint={v.footerHint}
+      primary={{ label: v.primaryLabel, onPress: rt.exportNow, disabled: !v.canExport, busy: rt.state.exp === 'exporting' }}>
+      <Box gap="s3">
+        <RadioGroup
+          label="Export format"
+          variant="rows"
+          value={rt.state.format}
+          onChange={rt.pick}
+          disabled={v.locked}
+          options={config.formats.map(x => ({ value: x.value, label: x.label, description: x.description, icon: x.binary ? 'file' : 'code', type: 'file' as const }))}
+        />
+        {f ? (
+          <Box gap="s2" style={{ borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken, padding: 12 }}>
+            <Box row align="center" justify="space-between">
+              <Text variant="caption" color="textPrimary" style={{ fontSize: 12, fontWeight: '600' }}>Preview</Text>
+              <Pressable
+                aria-label={rt.state.copied ? config.copiedLabel : `${config.copyLabel} preview`}
+                onPress={() => { void rt.copy(); }}
+                height={28}
+                px="s2"
+                radius="field"
+                style={{ backgroundColor: colors.surface1, borderWidth: 1, borderColor: colors.hairlineStrong }}>
+                <MotionView style={{ opacity: copyFade, flexDirection: 'row', alignItems: 'center', gap: 4 }}>
+                  <Icon name={rt.state.copied ? 'tick' : 'copy'} size={13} color={rt.state.copied ? colors.status.executed : colors.textPrimary} />
+                  <Text variant="caption" style={{ fontSize: 12, fontWeight: '600', color: rt.state.copied ? colors.status.executed : colors.textPrimary }}>
+                    {rt.state.copied ? config.copiedLabel : config.copyLabel}
+                  </Text>
+                </MotionView>
+              </Pressable>
+            </Box>
+            <Box role="status" aria-live="polite" style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', left: -10000 }}>
+              <Text>{rt.state.copied ? config.copiedLabel : ''}</Text>
+            </Box>
+            <MotionView style={{ opacity: previewFade, gap: 6 }}>
+              <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 12 }}>
+                {`${config.sampleName}.${f.ext}${f.binary ? ' · structure' : ''}`}
+              </Text>
+              <CodeBlock bare code={f.preview} minHeight={132} />
+            </MotionView>
+          </Box>
+        ) : null}
+        {rt.state.exp === 'failed' ? <Callout alert title={config.failTitle}>{config.failBody}</Callout> : null}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** ExportFormat, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const ExportFormat = guarded(ExportFormatView, EXPORT_PRESETS, 'ExportFormat');

package/src/components/onboarding/export-format/contract.ts

@@ -0,0 +1,54 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Export Format (handoff §3.7)** — pick the default export format and see what its output
+ * looks like. **Binary formats show a structure summary, not fake bytes.**
+ */
+
+export type ExportFormatOption = {
+  value: string;
+  label: string;
+  /** The file extension — `csv`. */
+  ext: string;
+  description: string;
+  /** Text formats: a real sample. Binary formats: a structure summary ("Sheet 1 · 3 columns · …"). */
+  preview: string;
+  binary: boolean;
+};
+
+export const EXPORT_SCENES = ['default', 'other', 'copied', 'exporting', 'exported', 'failed', 'loading', 'empty', 'error'] as const;
+export type ExportScene = (typeof EXPORT_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const EXPORT_IN_FLIGHT: readonly string[] = ['exporting', 'copied'];
+
+export type ExportFormatSettings = HeaderConfig & LoadCopy & {
+  formats: ExportFormatOption[];
+  defaultFormat: string;
+  /** The file's base name — `weekly-signups`. */
+  sampleName: string;
+  ship?: ExportScene;
+  exportLabel: string;
+  exportingLabel: string;
+  exportedLabel: string;
+  exportedHint: string;
+  copyLabel: string;
+  copiedLabel: string;
+  failTitle: string;
+  failBody: string;
+};
+
+export const EXPORT_PRESETS = presetsJson as unknown as PresetsFile<ExportFormatSettings>;
+
+export function validateExportFormat(c: ExportFormatSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.formats)) return [{ path: 'formats', message: 'formats must be a list.' }];
+  const issues: OnboardingIssue[] = [];
+  const values = new Set<string>();
+  c.formats.forEach((f, i) => {
+    if (values.has(f.value)) issues.push({ path: `formats[${i}].value`, message: `The value “${f.value}” is used twice.` });
+    values.add(f.value);
+    if (!f.ext) issues.push({ path: `formats[${i}].ext`, message: 'Every format needs an extension.' });
+  });
+  if (c.formats.length && !values.has(c.defaultFormat)) issues.push({ path: 'defaultFormat', message: `“${c.defaultFormat}” is not one of the formats.` });
+  return issues;
+}

package/src/components/onboarding/export-format/engine.ts

@@ -0,0 +1,66 @@
+import type { StateChipTone } from '../../../ds';
+import type { ExportFormatSettings, ExportScene } from './contract';
+
+/** **The Export Format engine** — pure: the chosen format, the copy flash and the export lifecycle. */
+
+export type ExportPhase = 'idle' | 'exporting' | 'exported' | 'failed';
+export type ExportState = { format: string; copied: boolean; exp: ExportPhase };
+export type ExportSeed = Partial<ExportState>;
+
+export type ExportAction =
+  | { type: 'pick'; format: string }
+  | { type: 'copied'; on: boolean }
+  | { type: 'export' }
+  | { type: 'exported' }
+  | { type: 'failed' }
+  | { type: 'reset'; state: ExportState };
+
+export function initialExport(c: ExportFormatSettings, seed: ExportSeed = {}): ExportState {
+  return { format: seed.format ?? c.defaultFormat, copied: seed.copied ?? false, exp: seed.exp ?? 'idle' };
+}
+
+export function exportSeed(c: ExportFormatSettings, scene: ExportScene): ExportSeed {
+  if (scene === 'other') return { format: (c.formats[1] ?? c.formats[0])?.value };
+  if (scene === 'copied') return { copied: true };
+  if (scene === 'exporting' || scene === 'exported' || scene === 'failed') return { exp: scene };
+  return {};
+}
+
+export function reduceExport(s: ExportState, a: ExportAction): ExportState {
+  switch (a.type) {
+    /* Radios are locked while exporting; a new format makes "Exported" a new question. */
+    case 'pick': return s.exp === 'exporting' ? s : { format: a.format, copied: false, exp: 'idle' };
+    case 'copied': return { ...s, copied: a.on };
+    case 'export': return s.exp === 'exporting' || s.exp === 'exported' ? s : { ...s, exp: 'exporting' };
+    case 'exported': return s.exp === 'exporting' ? { ...s, exp: 'exported' } : s;
+    case 'failed': return s.exp === 'exporting' ? { ...s, exp: 'failed' } : s;
+    case 'reset': return a.state;
+  }
+}
+
+export function currentFormat(c: ExportFormatSettings, s: ExportState) {
+  return c.formats.find(f => f.value === s.format) ?? c.formats[0]!;
+}
+
+export function fileNameOf(c: ExportFormatSettings, s: ExportState): string {
+  /* An empty `formats` list is the empty scene: the name without an extension, never a crash. */
+  const f = c.formats.find(x => x.value === s.format) ?? c.formats[0];
+  return f ? `${c.sampleName}.${f.ext}` : c.sampleName;
+}
+
+export function exportView(c: ExportFormatSettings, s: ExportState) {
+  const f = c.formats.find(x => x.value === s.format) ?? c.formats[0];
+  const file = fileNameOf(c, s);
+  const chip: { tone: StateChipTone; label: string } = s.exp === 'exporting' ? { tone: 'neutral', label: c.exportingLabel }
+    : s.exp === 'exported' ? { tone: 'success', label: c.exportedLabel }
+    : s.exp === 'failed' ? { tone: 'attention', label: 'Export failed' }
+    : { tone: 'neutral', label: (f?.label ?? '') };
+  return {
+    scene: (s.exp !== 'idle' ? s.exp : s.copied ? 'copied' : s.format === c.defaultFormat ? 'default' : 'other') as ExportScene,
+    chip,
+    footerHint: s.exp === 'exported' ? `${c.exportedHint} · ${file}` : s.exp === 'exporting' ? `Generating ${file}…` : file,
+    primaryLabel: s.exp === 'exporting' ? c.exportingLabel : s.exp === 'exported' ? c.exportedLabel : s.exp === 'failed' ? c.retryLabel : `${c.exportLabel} ${(f?.label ?? '')}`,
+    canExport: s.exp !== 'exporting' && s.exp !== 'exported',
+    locked: s.exp === 'exporting',
+  };
+}

package/src/components/onboarding/export-format/index.ts

@@ -0,0 +1,10 @@
+export {
+  EXPORT_PRESETS, EXPORT_SCENES, EXPORT_IN_FLIGHT, validateExportFormat,
+  type ExportFormatOption, type ExportFormatSettings, type ExportScene,
+} from './contract';
+export {
+  currentFormat, exportSeed, exportView, fileNameOf, initialExport, reduceExport,
+  type ExportAction, type ExportPhase, type ExportSeed, type ExportState,
+} from './engine';
+export { useExportFormat, type ExportOperations, type ExportRequest } from './runtime';
+export { ExportFormat, type ExportFormatProps } from './ExportFormatView';

package/src/components/onboarding/export-format/presets.json

@@ -0,0 +1,251 @@
+{
+  "component": "export-format",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "file",
+    "icon": "download",
+    "title": "Default export format",
+    "subtitle": "Used whenever someone exports from Analytics.",
+    "sampleName": "weekly-signups",
+    "defaultFormat": "csv",
+    "formats": [
+      {
+        "value": "csv",
+        "label": "CSV",
+        "ext": "csv",
+        "description": "Opens in any spreadsheet",
+        "preview": "date,signups,source\n2026-09-14,1284,organic\n2026-09-15,1310,paid\n2026-09-16,1197,referral\n2026-09-17,1352,organic",
+        "binary": false
+      },
+      {
+        "value": "json",
+        "label": "JSON",
+        "ext": "json",
+        "description": "For scripts and APIs",
+        "preview": "[\n  { \"date\": \"2026-09-14\", \"signups\": 1284, \"source\": \"organic\" },\n  { \"date\": \"2026-09-15\", \"signups\": 1310, \"source\": \"paid\" },\n  { \"date\": \"2026-09-16\", \"signups\": 1197, \"source\": \"referral\" }\n]",
+        "binary": false
+      },
+      {
+        "value": "xlsx",
+        "label": "XLSX",
+        "ext": "xlsx",
+        "description": "Excel workbook with types kept",
+        "preview": "Workbook · 1 sheet\nSheet 1 · 3 columns · 1,284 rows\nColumns: date (date), signups (number), source (text)",
+        "binary": true
+      },
+      {
+        "value": "parquet",
+        "label": "Parquet",
+        "ext": "parquet",
+        "description": "Columnar, for data warehouses",
+        "preview": "Parquet · snappy compression\n1 row group · 3 columns · 1,284 rows\nSchema: date DATE, signups INT32, source STRING",
+        "binary": true
+      }
+    ],
+    "exportLabel": "Export",
+    "exportingLabel": "Exporting…",
+    "exportedLabel": "Exported",
+    "exportedHint": "Saved to Downloads",
+    "copyLabel": "Copy",
+    "copiedLabel": "Copied",
+    "failTitle": "Export failed",
+    "failBody": "The file couldn’t be generated. Your settings haven’t changed; retry to try again.",
+    "emptyTitle": "No formats available",
+    "emptyBody": "Exports are turned off for this workspace.",
+    "emptyCta": "Refresh"
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "icon": "doc",
+      "title": "Report export",
+      "subtitle": "The default when sharing a report outside the app.",
+      "sampleName": "q3-board-report",
+      "defaultFormat": "pdf",
+      "formats": [
+        {
+          "value": "pdf",
+          "label": "PDF",
+          "ext": "pdf",
+          "description": "Fixed layout for sharing and print",
+          "preview": "PDF · 12 pages · A4 portrait\nFonts embedded · 2.4 MB\nSections: Summary, Revenue, Hiring, Risks",
+          "binary": true
+        },
+        {
+          "value": "docx",
+          "label": "DOCX",
+          "ext": "docx",
+          "description": "Editable in Word or Google Docs",
+          "preview": "Word document · 12 pages\nHeading styles kept · comments removed\nImages: 6 charts as PNG",
+          "binary": true
+        },
+        {
+          "value": "md",
+          "label": "Markdown",
+          "ext": "md",
+          "description": "Plain text for wikis and repos",
+          "preview": "# Q3 board report\n\n## Summary\nRevenue grew 18% quarter on quarter.\n\n| Metric | Q2 | Q3 |\n| --- | --- | --- |\n| ARR | $4.1M | $4.8M |",
+          "binary": false
+        },
+        {
+          "value": "html",
+          "label": "HTML",
+          "ext": "html",
+          "description": "For the web or email",
+          "preview": "<article>\n  <h1>Q3 board report</h1>\n  <h2>Summary</h2>\n  <p>Revenue grew 18% quarter on quarter.</p>\n</article>",
+          "binary": false
+        }
+      ]
+    },
+    "case3": {
+      "type": "file",
+      "icon": "calendar",
+      "title": "Calendar export",
+      "subtitle": "How events leave the scheduler.",
+      "sampleName": "team-offsite",
+      "defaultFormat": "ics",
+      "formats": [
+        {
+          "value": "ics",
+          "label": "ICS",
+          "ext": "ics",
+          "description": "Adds to any calendar app",
+          "preview": "BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Team offsite\nDTSTART:20261014T090000Z\nDTEND:20261014T170000Z\nEND:VEVENT\nEND:VCALENDAR",
+          "binary": false
+        },
+        {
+          "value": "csv",
+          "label": "CSV",
+          "ext": "csv",
+          "description": "One row per event",
+          "preview": "subject,start,end,location\nTeam offsite,2026-10-14 09:00,2026-10-14 17:00,Lisbon\nRetro,2026-10-15 10:00,2026-10-15 11:00,Lisbon",
+          "binary": false
+        },
+        {
+          "value": "json",
+          "label": "JSON",
+          "ext": "json",
+          "description": "For scripts and integrations",
+          "preview": "{\n  \"events\": [\n    { \"subject\": \"Team offsite\", \"start\": \"2026-10-14T09:00:00Z\", \"location\": \"Lisbon\" }\n  ]\n}",
+          "binary": false
+        }
+      ]
+    },
+    "case4": {
+      "icon": "code",
+      "title": "Token export",
+      "subtitle": "Format the design tokens ship in.",
+      "sampleName": "solarium-tokens",
+      "defaultFormat": "css",
+      "formats": [
+        {
+          "value": "css",
+          "label": "CSS variables",
+          "ext": "css",
+          "description": "Drop into any stylesheet",
+          "preview": ":root {\n  --color-primary: oklch(58% .14 40);\n  --radius-card: 16px;\n  --space-3: 12px;\n  --motion-base: 160ms;\n}",
+          "binary": false
+        },
+        {
+          "value": "json",
+          "label": "JSON",
+          "ext": "json",
+          "description": "Style Dictionary compatible",
+          "preview": "{\n  \"color\": { \"primary\": { \"value\": \"oklch(58% .14 40)\" } },\n  \"radius\": { \"card\": { \"value\": \"16px\" } }\n}",
+          "binary": false
+        },
+        {
+          "value": "ts",
+          "label": "TypeScript",
+          "ext": "ts",
+          "description": "Typed constants for apps",
+          "preview": "export const tokens = {\n  color: { primary: \"oklch(58% .14 40)\" },\n  radius: { card: 16 },\n  space: { 3: 12 },\n} as const;",
+          "binary": false
+        },
+        {
+          "value": "rn",
+          "label": "RN theme",
+          "ext": "ts",
+          "description": "React Native theme object",
+          "preview": "export const theme = {\n  colors: { primary: \"oklch(58% .14 40)\" },\n  radii: { card: 16 },\n  spacing: [0, 4, 8, 12, 16],\n};",
+          "binary": false
+        }
+      ]
+    },
+    "case5": {
+      "icon": "receipt",
+      "title": "Invoice export",
+      "subtitle": "Sent to your accountant each month.",
+      "sampleName": "INV-2041",
+      "defaultFormat": "pdf",
+      "ship": "failed",
+      "failBody": "The accounting connection timed out. Nothing was sent; retry to try again.",
+      "formats": [
+        {
+          "value": "pdf",
+          "label": "PDF",
+          "ext": "pdf",
+          "description": "Branded invoice for the customer",
+          "preview": "PDF · 1 page · A4\nInvoice INV-2041 · total $4,280.00\nLogo and brand colours applied",
+          "binary": true
+        },
+        {
+          "value": "csv",
+          "label": "CSV",
+          "ext": "csv",
+          "description": "Line items for spreadsheets",
+          "preview": "invoice,date,customer,total,currency\nINV-2041,2026-09-30,Harbor Legal,4280.00,USD",
+          "binary": false
+        },
+        {
+          "value": "ubl",
+          "label": "UBL XML",
+          "ext": "xml",
+          "description": "E-invoicing standard",
+          "preview": "<Invoice>\n  <cbc:ID>INV-2041</cbc:ID>\n  <cbc:IssueDate>2026-09-30</cbc:IssueDate>\n  <cac:LegalMonetaryTotal>\n    <cbc:PayableAmount currencyID=\"USD\">4280.00</cbc:PayableAmount>\n  </cac:LegalMonetaryTotal>\n</Invoice>",
+          "binary": false
+        },
+        {
+          "value": "iif",
+          "label": "QuickBooks IIF",
+          "ext": "iif",
+          "description": "Import into QuickBooks Desktop",
+          "preview": "!TRNS\tTRNSTYPE\tDATE\tACCNT\tAMOUNT\nTRNS\tINVOICE\t09/30/2026\tAccounts Receivable\t4280.00",
+          "binary": false
+        }
+      ]
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · Analytics",
+      "title": "Data export",
+      "scenario": "An analyst sets how tables leave the analytics tool. Two text formats preview real rows; two binary formats show their structure."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · Docs",
+      "title": "Report export",
+      "scenario": "A writer chooses how reports are shared outside the app."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Scheduling",
+      "title": "Calendar export",
+      "scenario": "A scheduler picks how events are exported. There are only three rows."
+    },
+    "case4": {
+      "eyebrow": "Case study 4 · Design systems",
+      "title": "Design tokens",
+      "scenario": "A design-system team picks the format tokens are published in."
+    },
+    "case5": {
+      "eyebrow": "Case study 5 · Finance",
+      "title": "Invoice export",
+      "scenario": "A bookkeeper sends invoices to accounting. The board ships in the failed state."
+    }
+  }
+}

package/src/components/onboarding/export-format/runtime.ts

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { abortableDelay, useOperationRunner } from '../../../runtime/operations';
+import type { OnboardingResult } from '../shared/contract';
+import { ONBOARDING_TIMING, createMockOperation, type OnboardingOperation } from '../shared/mock';
+import { runOutcome } from '../shared/runtime';
+import type { ExportFormatSettings } from './contract';
+import {
+  currentFormat, exportSeed, exportView, fileNameOf, initialExport, reduceExport,
+  type ExportAction, type ExportSeed, type ExportState,
+} from './engine';
+
+export type ExportRequest = { format: string; fileName: string };
+export type ExportOperations = {
+  export: OnboardingOperation<ExportRequest>;
+  /** How long "Copied" stays — default `ONBOARDING_TIMING.copied` (1600ms). A preview holds it with `holdOperation()`. */
+  copied?: OnboardingOperation<void>;
+};
+
+/**
+ * **The Export Format runtime** — the reducer, the export operation and the "Copied" flash
+ * (`ONBOARDING_TIMING.copied`). `onCopy` is the host's clipboard; omitted on the web the browser
+ * clipboard is used when it exists, and a refused clipboard is not "Copied".
+ */
+export function useExportFormat({
+  config, operations, result = 'success', initial, onChange, onExport, onCopy,
+}: {
+  config: ExportFormatSettings;
+  operations?: ExportOperations;
+  result?: OnboardingResult;
+  initial?: ExportSeed;
+  onChange?: (format: string) => void;
+  onExport?: (req: ExportRequest) => void;
+  onCopy?: (text: string) => void | Promise<void>;
+}) {
+  const seed = () => initialExport(config, initial ?? (config.ship ? exportSeed(config, config.ship) : {}));
+  const [state, send] = useReducer((s: ExportState, a: ExportAction) => reduceExport(s, a), undefined, seed);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const runner = useOperationRunner();
+  const exportOp = useMemo(
+    () => operations?.export ?? createMockOperation<ExportRequest>({ latencyMs: ONBOARDING_TIMING.save, fail: () => result === 'error' }),
+    [operations, result],
+  );
+
+  const key = JSON.stringify([config, initial ?? null]);
+  const seeded = useRef(key);
+  useEffect(() => {
+    if (seeded.current === key) return;
+    seeded.current = key;
+    runner.cancel('export');
+    send({ type: 'reset', state: seed() });
+  });
+
+  const run = useCallback(() => {
+    const s = stateRef.current;
+    const req = { format: s.format, fileName: fileNameOf(config, s) };
+    runOutcome(runner, 'export', exportOp, req, {
+      ok: () => { send({ type: 'exported' }); onExport?.(req); },
+      fail: () => send({ type: 'failed' }),
+    });
+  }, [runner, exportOp, config, onExport]);
+
+  const flashCopied = useCallback(() => {
+    send({ type: 'copied', on: true });
+    const wait = operations?.copied;
+    runner.run('copied', async ctx => { if (wait) await wait(undefined, { signal: ctx.signal }); else await abortableDelay(ONBOARDING_TIMING.copied, ctx.signal); }, {
+      onOk: () => send({ type: 'copied', on: false }),
+      onError: () => send({ type: 'copied', on: false }),
+    });
+  }, [runner, operations?.copied]);
+
+  /* A restored session finishes what it was doing: an export in flight, a "Copied" flash. */
+  useEffect(() => {
+    if (stateRef.current.exp === 'exporting') run();
+    if (stateRef.current.copied) flashCopied();
+  }, [key]);
+
+  const formatKey = state.format;
+  const reported = useRef(formatKey);
+  useEffect(() => {
+    if (reported.current === formatKey) return;
+    reported.current = formatKey;
+    onChange?.(formatKey);
+  }, [formatKey]);
+
+  return {
+    state,
+    view: exportView(config, state),
+    pick: (format: string) => send({ type: 'pick', format }),
+    exportNow: () => {
+      if (!exportView(config, stateRef.current).canExport) return;
+      send({ type: 'export' });
+      run();
+    },
+    copy: async () => {
+      const text = currentFormat(config, stateRef.current).preview;
+      const clip = (globalThis as { navigator?: { clipboard?: { writeText: (s: string) => Promise<void> } } }).navigator?.clipboard;
+      try {
+        if (onCopy) await onCopy(text);
+        else await clip?.writeText(text);
+      } catch {
+        return;
+      }
+      flashCopied();
+    },
+  };
+}