@tangle-network/ui 11.37.0 → 11.38.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tangle-network/ui
 
+## 11.38.1
+
+### Patch Changes
+
+- c049dc4: Bound shared surface dismissal by its scoped role deadline so missing CSS animation events cannot strand Radix cleanup or focus return. Preserve retained motion values on reopen.
+
+## 11.38.0
+
+### Minor Changes
+
+- f115dda: Wizard: the shared multi-step flow primitive. Compound composition (`<Wizard.Step>`), uncontrolled by default with a controlled escape hatch, per-step primary actions with async gating, mobile-first progress, themed by the existing semantic tokens. The end of bespoke stepper markup across products.
+
 ## 11.37.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -96,6 +96,7 @@ import { Pagination, PaginationProps } from "./primitives/pagination.js";
 import { StatusPill, StatusPillProps, StatusTone } from "./primitives/status-pill.js";
 import { Tag, TagProps } from "./primitives/tag.js";
 import { Chip, ChipProps } from "./primitives/chip.js";
+import { Wizard, WizardProps, WizardStep, WizardStepProps } from "./primitives/wizard.js";
 import { Metric, MetricProps, MetricStrip, MetricStripProps } from "./primitives/metric-strip.js";
 import { FilterField, FilterFieldProps, Toolbar, ToolbarProps } from "./primitives/toolbar.js";
 import { Logo, LogoProps, TangleKnot } from "./primitives.js";
@@ -134,4 +135,4 @@ import { QuestionPreview, QuestionPreviewProps } from "./tool-previews/question-
 import { DiffPreview, DiffPreviewProps } from "./tool-previews/diff-preview.js";
 import { RedactedDocSegment, RedactedDocument, RedactedDocumentData, RedactedDocumentProps, RevealResult } from "./redaction/redacted-document.js";
 import "./redaction.js";
-export { ActiveProjectActivity, ActiveSessionActivityOptions, ActiveSessionConnectionOptions, ActiveSessionConnectionState, ActiveSessionReconnectState, ActiveSessionRecord, ActiveSessionStatus, ActiveSessionTransportMode, ActiveSessionsState, AgentBranding, AgentStreamEvent, AgentTimeline, type AgentTimelineArtifactItem, type AgentTimelineCustomItem, type AgentTimelineItem, type AgentTimelineMessageItem, type AgentTimelineProps, type AgentTimelineStatusItem, type AgentTimelineTone, type AgentTimelineToolGroupItem, type AgentTimelineToolItem, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, type AlertTone, ApiSchema, type ApiSchemaProps, AppendUserMessageOptions, ApplySdkEventOptions, ApprovalCard, type ApprovalCardProps, type ApprovalDiffFile, ApprovalDiffSummary, type ApprovalPlanStep, ArtifactPane, type ArtifactPaneProps, AuthHeader, type AuthHeaderProps, AuthUser, AutomationStreamEvent, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, BeginAssistantMessageOptions, BotStreamEvent, Button, type ButtonProps, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Calendar, type CalendarDate, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardTitleProps, type CategoryTone, ChatAuthor, ChatContainer, type ChatContainerProps, ChatMessage, type ChatMessageProps, Checkbox, Chip, type ChipProps, CodeBlock, type CodeBlockProps, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, type CommandPreviewProps, CompleteAssistantMessageOptions, ConnectionState, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, type CopyButtonProps, CustomToolRenderer, DatePicker, type DatePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, type DiffPreviewProps, DisplayVariant, DropZone, type DropZoneProps, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, ExpandedToolDetail, type ExpandedToolDetailProps, type FeedSegment, FileArtifactPane, type FileArtifactPaneProps, FileCard, type FileCardProps, type FileDetails, type FileFormat, FileList, type FileListItem, type FileListProps, type FileNode, FilePreview, type FilePreviewKind, type FilePreviewProps, type FileTabData, FileTabs, type FileTabsProps, FileTree, type FileTreeProps, type FileTreeVisibilityOptions, type FileUploader, FilterField, type FilterFieldProps, FinalTextPart, GitHubLoginButton, type GitHubLoginButtonProps, GlobResultsPreview, type GlobResultsPreviewProps, GrepResultsPreview, type GrepResultsPreviewProps, GroupedMessage, Heading, type HeadingProps, type HeadingVariant, HelpText, type HelpTextProps, IconTile, type IconTileProps, InlineCode, type InlineCodeProps, InlineThinkingItem, type InlineThinkingItemProps, InlineToolItem, type InlineToolItemProps, Input, type InputProps, Label, LiveDuration, LoginLayout, type LoginLayoutProps, Logo, type LogoProps, Markdown, type MarkdownLinkChip, type MarkdownLinkChipResolver, type MarkdownProps, MessageAuthor, type MessageAuthorProps, MessageList, type MessageListProps, type MessageRole, MessageRun, MessageUser, Metric, type MetricProps, MetricStrip, type MetricStripProps, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, type OpenUIAction, type OpenUIActionsNode, OpenUIArtifactRenderer, type OpenUIArtifactRendererProps, type OpenUIBadgeNode, type OpenUICardNode, type OpenUICodeNode, type OpenUIComponentNode, type OpenUIGridNode, type OpenUIHeadingNode, type OpenUIKeyValueNode, type OpenUIMarkdownNode, type OpenUIPrimitive, type OpenUISchemaIssue, type OpenUISchemaValidation, type OpenUISeparatorNode, type OpenUIStackNode, type OpenUIStatNode, type OpenUITableNode, type OpenUITextNode, PageHeader, type PageHeaderProps, PageShell, type PageShellProps, Pagination, type PaginationProps, PdfViewer, type PdfViewerConfig, type PdfViewerProps, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, type QuestionPreviewProps, RadioGroup, RadioGroupItem, RealtimeSessionOptions, RealtimeSessionRegistry, RealtimeSessionRegistryProps, RealtimeSessionState, RealtimeSessionTarget, ReasoningPart, type RedactedDocSegment, RedactedDocument, type RedactedDocumentData, type RedactedDocumentProps, RegisterActiveSessionOptions, type RevealResult, RichFileTree, type RichFileTreeGitEntry, type RichFileTreeGitStatus, type RichFileTreeProps, type RichFileTreeThemeVars, Run, RunGroup, type RunGroupProps, type RunPhase, RunPhaseList, RunRowShell, type RunRowShellProps, type RunRowStatus, RunRowStatusDot, RunStats, SSEEvent, SdkSessionAttachment, SdkSessionEvent, SdkSessionSeed, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SessionMessage, SessionPart, SessionProjectKey, type SessionUser, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, type SidebarDropZoneProps, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, type StatCardProps, StatusPill, type StatusPillProps, type StatusTone, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, TRANSCRIPT_TEXT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableProps, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, type TagProps, TangleKnot, TaskList, type TaskListItem, type TaskListProps, type TaskStatus, TaskStreamEvent, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TerminalStreamEvent, TextPart, TextShimmer, type TextShimmerProps, Textarea, type TextareaProps, ThemeToggle, ThinkingIndicator, type ThinkingIndicatorProps, TimeSelect, type TimeSelectProps, type Toast, ToastContainer, ToastProvider, type Tone, type ToneClasses, type ToolCallData, ToolCallFeed, type ToolCallFeedProps, type ToolCallStatus, type ToolCallType, ToolCategory, ToolDisplayMetadata, ToolPart, ToolState, ToolStatus, ToolTime, Toolbar, type ToolbarProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UploadFile, UploadProgress, type UploadProgressProps, UseAuthOptions, UseAuthResult, UseRunGroupsOptions, UseSSEStreamOptions, UseSSEStreamResult, UseSdkSessionOptions, UseSdkSessionReturn, UseToolCallStreamReturn, UserMenu, type UserMenuProps, UserMessage, type UserMessageProps, WebSearchPreview, type WebSearchPreviewProps, WriteFilePreview, type WriteFilePreviewProps, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, codeBlockGrammar, configurePdfViewer, copyText, createAuthFetcher, detectFileFormat, fenceInfo, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatCalendarDate, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, localToday, messagesAtom, numericColumns, parseCalendarDate, parseCsv, parseToolEvent, partMapAtom, plainTextFromMarkdown, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, showsTaskPriority, tableCsv, taskProgress, taskStatus, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };
+export { ActiveProjectActivity, ActiveSessionActivityOptions, ActiveSessionConnectionOptions, ActiveSessionConnectionState, ActiveSessionReconnectState, ActiveSessionRecord, ActiveSessionStatus, ActiveSessionTransportMode, ActiveSessionsState, AgentBranding, AgentStreamEvent, AgentTimeline, type AgentTimelineArtifactItem, type AgentTimelineCustomItem, type AgentTimelineItem, type AgentTimelineMessageItem, type AgentTimelineProps, type AgentTimelineStatusItem, type AgentTimelineTone, type AgentTimelineToolGroupItem, type AgentTimelineToolItem, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, type AlertTone, ApiSchema, type ApiSchemaProps, AppendUserMessageOptions, ApplySdkEventOptions, ApprovalCard, type ApprovalCardProps, type ApprovalDiffFile, ApprovalDiffSummary, type ApprovalPlanStep, ArtifactPane, type ArtifactPaneProps, AuthHeader, type AuthHeaderProps, AuthUser, AutomationStreamEvent, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, BeginAssistantMessageOptions, BotStreamEvent, Button, type ButtonProps, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Calendar, type CalendarDate, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardTitleProps, type CategoryTone, ChatAuthor, ChatContainer, type ChatContainerProps, ChatMessage, type ChatMessageProps, Checkbox, Chip, type ChipProps, CodeBlock, type CodeBlockProps, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, type CommandPreviewProps, CompleteAssistantMessageOptions, ConnectionState, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, type CopyButtonProps, CustomToolRenderer, DatePicker, type DatePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, type DiffPreviewProps, DisplayVariant, DropZone, type DropZoneProps, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, ExpandedToolDetail, type ExpandedToolDetailProps, type FeedSegment, FileArtifactPane, type FileArtifactPaneProps, FileCard, type FileCardProps, type FileDetails, type FileFormat, FileList, type FileListItem, type FileListProps, type FileNode, FilePreview, type FilePreviewKind, type FilePreviewProps, type FileTabData, FileTabs, type FileTabsProps, FileTree, type FileTreeProps, type FileTreeVisibilityOptions, type FileUploader, FilterField, type FilterFieldProps, FinalTextPart, GitHubLoginButton, type GitHubLoginButtonProps, GlobResultsPreview, type GlobResultsPreviewProps, GrepResultsPreview, type GrepResultsPreviewProps, GroupedMessage, Heading, type HeadingProps, type HeadingVariant, HelpText, type HelpTextProps, IconTile, type IconTileProps, InlineCode, type InlineCodeProps, InlineThinkingItem, type InlineThinkingItemProps, InlineToolItem, type InlineToolItemProps, Input, type InputProps, Label, LiveDuration, LoginLayout, type LoginLayoutProps, Logo, type LogoProps, Markdown, type MarkdownLinkChip, type MarkdownLinkChipResolver, type MarkdownProps, MessageAuthor, type MessageAuthorProps, MessageList, type MessageListProps, type MessageRole, MessageRun, MessageUser, Metric, type MetricProps, MetricStrip, type MetricStripProps, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, type OpenUIAction, type OpenUIActionsNode, OpenUIArtifactRenderer, type OpenUIArtifactRendererProps, type OpenUIBadgeNode, type OpenUICardNode, type OpenUICodeNode, type OpenUIComponentNode, type OpenUIGridNode, type OpenUIHeadingNode, type OpenUIKeyValueNode, type OpenUIMarkdownNode, type OpenUIPrimitive, type OpenUISchemaIssue, type OpenUISchemaValidation, type OpenUISeparatorNode, type OpenUIStackNode, type OpenUIStatNode, type OpenUITableNode, type OpenUITextNode, PageHeader, type PageHeaderProps, PageShell, type PageShellProps, Pagination, type PaginationProps, PdfViewer, type PdfViewerConfig, type PdfViewerProps, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, type QuestionPreviewProps, RadioGroup, RadioGroupItem, RealtimeSessionOptions, RealtimeSessionRegistry, RealtimeSessionRegistryProps, RealtimeSessionState, RealtimeSessionTarget, ReasoningPart, type RedactedDocSegment, RedactedDocument, type RedactedDocumentData, type RedactedDocumentProps, RegisterActiveSessionOptions, type RevealResult, RichFileTree, type RichFileTreeGitEntry, type RichFileTreeGitStatus, type RichFileTreeProps, type RichFileTreeThemeVars, Run, RunGroup, type RunGroupProps, type RunPhase, RunPhaseList, RunRowShell, type RunRowShellProps, type RunRowStatus, RunRowStatusDot, RunStats, SSEEvent, SdkSessionAttachment, SdkSessionEvent, SdkSessionSeed, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SessionMessage, SessionPart, SessionProjectKey, type SessionUser, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, type SidebarDropZoneProps, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, type StatCardProps, StatusPill, type StatusPillProps, type StatusTone, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, TRANSCRIPT_TEXT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableProps, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, type TagProps, TangleKnot, TaskList, type TaskListItem, type TaskListProps, type TaskStatus, TaskStreamEvent, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TerminalStreamEvent, TextPart, TextShimmer, type TextShimmerProps, Textarea, type TextareaProps, ThemeToggle, ThinkingIndicator, type ThinkingIndicatorProps, TimeSelect, type TimeSelectProps, type Toast, ToastContainer, ToastProvider, type Tone, type ToneClasses, type ToolCallData, ToolCallFeed, type ToolCallFeedProps, type ToolCallStatus, type ToolCallType, ToolCategory, ToolDisplayMetadata, ToolPart, ToolState, ToolStatus, ToolTime, Toolbar, type ToolbarProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UploadFile, UploadProgress, type UploadProgressProps, UseAuthOptions, UseAuthResult, UseRunGroupsOptions, UseSSEStreamOptions, UseSSEStreamResult, UseSdkSessionOptions, UseSdkSessionReturn, UseToolCallStreamReturn, UserMenu, type UserMenuProps, UserMessage, type UserMessageProps, WebSearchPreview, type WebSearchPreviewProps, Wizard, type WizardProps, WizardStep, type WizardStepProps, WriteFilePreview, type WriteFilePreviewProps, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, codeBlockGrammar, configurePdfViewer, copyText, createAuthFetcher, detectFileFormat, fenceInfo, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatCalendarDate, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, localToday, messagesAtom, numericColumns, parseCalendarDate, parseCsv, parseToolEvent, partMapAtom, plainTextFromMarkdown, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, showsTaskPriority, tableCsv, taskProgress, taskStatus, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };

package/dist/index.js

@@ -53,6 +53,7 @@ import { StatusPill } from "./primitives/status-pill.js";
 import { CATEGORY_TONES, TONE_CLASSES, toneFor } from "./primitives/tone.js";
 import { Tag } from "./primitives/tag.js";
 import { Chip } from "./primitives/chip.js";
+import { Wizard, WizardStep } from "./primitives/wizard.js";
 import { IconTile, initialsOf } from "./primitives/icon-tile.js";
 import { Metric, MetricStrip } from "./primitives/metric-strip.js";
 import { FilterField, Toolbar } from "./primitives/toolbar.js";
@@ -118,4 +119,4 @@ import { addMessage, addParts, clearChat, isStreamingAtom, messagesAtom, partMap
 import { copyText } from "./utils/copy-text.js";
 import { timeAgo } from "./utils/time-ago.js";
 import { RedactedDocument } from "./redaction/redacted-document.js";
-export { AgentTimeline, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ApiSchema, ApprovalCard, ApprovalDiffSummary, ArtifactPane, AuthHeader, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ChatContainer, ChatMessage, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, ExpandedToolDetail, FileArtifactPane, FileCard, FileList, FilePreview, FileTabs, FileTree, FilterField, GitHubLoginButton, GlobResultsPreview, GrepResultsPreview, Heading, HelpText, IconTile, InlineCode, InlineThinkingItem, InlineToolItem, Input, Label, LiveDuration, LoginLayout, Logo, Markdown, MessageAuthor, MessageList, Metric, MetricStrip, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, OpenUIArtifactRenderer, PageHeader, PageShell, Pagination, PdfViewer, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, RadioGroup, RadioGroupItem, RealtimeSessionRegistry, RedactedDocument, RichFileTree, RunGroup, RunPhaseList, RunRowShell, RunRowStatusDot, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, TRANSCRIPT_TEXT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TaskList, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, ThinkingIndicator, TimeSelect, ToastContainer, ToastProvider, ToolCallFeed, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, UserMenu, UserMessage, WebSearchPreview, WriteFilePreview, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, codeBlockGrammar, configurePdfViewer, copyText, createAuthFetcher, detectFileFormat, fenceInfo, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatCalendarDate, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, localToday, messagesAtom, numericColumns, parseCalendarDate, parseCsv, parseToolEvent, partMapAtom, plainTextFromMarkdown, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, showsTaskPriority, tableCsv, taskProgress, taskStatus, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };
+export { AgentTimeline, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ApiSchema, ApprovalCard, ApprovalDiffSummary, ArtifactPane, AuthHeader, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ChatContainer, ChatMessage, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, ExpandedToolDetail, FileArtifactPane, FileCard, FileList, FilePreview, FileTabs, FileTree, FilterField, GitHubLoginButton, GlobResultsPreview, GrepResultsPreview, Heading, HelpText, IconTile, InlineCode, InlineThinkingItem, InlineToolItem, Input, Label, LiveDuration, LoginLayout, Logo, Markdown, MessageAuthor, MessageList, Metric, MetricStrip, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, OpenUIArtifactRenderer, PageHeader, PageShell, Pagination, PdfViewer, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, RadioGroup, RadioGroupItem, RealtimeSessionRegistry, RedactedDocument, RichFileTree, RunGroup, RunPhaseList, RunRowShell, RunRowStatusDot, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, TRANSCRIPT_TEXT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TaskList, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, ThinkingIndicator, TimeSelect, ToastContainer, ToastProvider, ToolCallFeed, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, UserMenu, UserMessage, WebSearchPreview, Wizard, WizardStep, WriteFilePreview, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, codeBlockGrammar, configurePdfViewer, copyText, createAuthFetcher, detectFileFormat, fenceInfo, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatCalendarDate, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, ixControl, ixControlAfter, ixControlSoft, ixField, ixRow, ixSelected, ixTabUnderline, localToday, messagesAtom, numericColumns, parseCalendarDate, parseCsv, parseToolEvent, partMapAtom, plainTextFromMarkdown, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, showsTaskPriority, tableCsv, taskProgress, taskStatus, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };

package/dist/lib/surface-motion.js

@@ -4,9 +4,10 @@ import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 import { animate, motionValue, styleEffect } from "motion";
 //#region src/lib/surface-motion.tsx
-/** Radix owns state, focus and presence; Motion only retargets the visible object. */
+/** Radix owns state and focus; visual retirement cannot wait for a CSS event. */
 const SurfaceMotion = React.forwardRef(({ kind, side = "right", asChild, "data-state": state, ...props }, forwardedRef) => {
 	const element = React.useRef(null);
+	const [retired, setRetired] = React.useState(false);
 	const values = React.useRef(null);
 	const controls = React.useRef([]);
 	const ref = React.useCallback((node) => {
@@ -24,7 +25,10 @@ const SurfaceMotion = React.forwardRef(({ kind, side = "right", asChild, "data-s
 		if (!node) return;
 		const preference = typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : void 0;
 		let cancelRender;
+		let retirement;
 		const run = () => {
+			clearTimeout(retirement);
+			setRetired(false);
 			const closed = state === "closed";
 			const bounds = node.getBoundingClientRect();
 			const hidden = {
@@ -46,6 +50,10 @@ const SurfaceMotion = React.forwardRef(({ kind, side = "right", asChild, "data-s
 				node.style.opacity = String(value.opacity);
 				node.style.transform = `translateX(${value.x}px) translateY(${value.y}px) scale(${value.scale})`;
 			};
+			if (closed) {
+				if (preference?.matches || seconds <= 0 || style.animationName === "none") setRetired(true);
+				else retirement = setTimeout(() => setRetired(true), seconds * 1e3);
+			}
 			if (preference?.matches || seconds <= 0 || style.animationName === "none") {
 				controls.current.forEach((control) => control.stop());
 				if (values.current) for (const key of [
@@ -84,6 +92,7 @@ const SurfaceMotion = React.forwardRef(({ kind, side = "right", asChild, "data-s
 		run();
 		preference?.addEventListener("change", run);
 		return () => {
+			clearTimeout(retirement);
 			preference?.removeEventListener("change", run);
 			cancelRender?.();
 		};
@@ -94,7 +103,7 @@ const SurfaceMotion = React.forwardRef(({ kind, side = "right", asChild, "data-s
 		props.style?.animation
 	]);
 	React.useEffect(() => () => controls.current.forEach((control) => control.stop()), []);
-	return /* @__PURE__ */ jsx(asChild ? Slot : "div", {
+	return state === "closed" && retired ? null : /* @__PURE__ */ jsx(asChild ? Slot : "div", {
 		...props,
 		"data-state": state,
 		ref

package/dist/primitives/wizard.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+//#region src/primitives/wizard.d.ts
+export interface WizardProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Drives the active step; omit for uncontrolled with `defaultStep`. */
+  step?: number;
+  defaultStep?: number;
+  onStepChange?: (step: number) => void;
+  /** Fires when the last step's primary action resolves. */
+  onFinished?: () => void;
+}
+export declare function Wizard({ children, step, defaultStep, onStepChange, onFinished, className, ...rest }: WizardProps): React.JSX.Element;
+export interface WizardStepProps {
+  /** Shown in the rail (and the mobile position line). Steps read at a glance; keep it one or two words. */
+  title: string;
+  children: React.ReactNode;
+  /** The footer's primary action label. Omit when the step renders its own actions. */
+  nextLabel?: string;
+  /** Runs before advancing. Resolve (or return a non-false value) to advance; return false or throw to stay — the step's own content shows why. */
+  onNext?: () => Promise<unknown> | unknown;
+  /** Disables the primary action (a required choice is still missing). */
+  nextDisabled?: boolean;
+  /** Hides the Back button for steps where going back makes no sense (a completed handshake). */
+  hideBack?: boolean;
+}
+export declare function WizardStep({ title, children, nextLabel, onNext, nextDisabled, hideBack }: WizardStepProps): React.JSX.Element;
+export interface Wizard extends React.FC<WizardProps> {
+  Step: typeof WizardStep;
+}
+//#endregion

package/dist/primitives/wizard.js

@@ -0,0 +1,158 @@
+import { cn } from "../lib/utils.js";
+import { Button } from "./button.js";
+import * as React from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Check, ChevronLeft } from "lucide-react";
+//#region src/primitives/wizard.tsx
+const WizardContext = React.createContext(null);
+function useWizardContext(component) {
+	const context = React.useContext(WizardContext);
+	if (!context) throw new Error(`<${component}> must be used inside <Wizard>`);
+	return context;
+}
+function Wizard({ children, step, defaultStep = 0, onStepChange, onFinished, className, ...rest }) {
+	const steps = React.Children.toArray(children).filter(React.isValidElement);
+	const [internal, setInternal] = React.useState(defaultStep);
+	const current = step !== void 0 ? step : internal;
+	const total = steps.length;
+	const goTo = React.useCallback((target) => {
+		const bounded = Math.max(0, Math.min(target, total - 1));
+		if (bounded === current) return;
+		onStepChange?.(bounded);
+		if (step === void 0) setInternal(bounded);
+	}, [
+		current,
+		onStepChange,
+		step,
+		total
+	]);
+	const context = React.useMemo(() => ({
+		current,
+		total,
+		goTo,
+		next: () => goTo(current + 1),
+		back: () => goTo(current - 1),
+		finish: () => onFinished?.()
+	}), [
+		current,
+		goTo,
+		onFinished,
+		total
+	]);
+	const titles = steps.map((child) => child.props.title);
+	const activeTitle = titles[current] ?? "";
+	return /* @__PURE__ */ jsx(WizardContext.Provider, {
+		value: context,
+		children: /* @__PURE__ */ jsxs("div", {
+			className: cn("w-full", className),
+			...rest,
+			children: [
+				/* @__PURE__ */ jsx("ol", {
+					"aria-label": "Steps",
+					className: "hidden items-center gap-2 sm:flex",
+					children: titles.map((title, index) => {
+						const state = index < current ? "done" : index === current ? "active" : "future";
+						const marker = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
+							className: cn("flex size-6 shrink-0 items-center justify-center rounded-full text-xs font-medium", state === "active" && "bg-primary text-primary-foreground", state === "done" && "bg-primary/15 text-primary", state === "future" && "bg-muted text-muted-foreground"),
+							children: state === "done" ? /* @__PURE__ */ jsx(Check, {
+								className: "size-3.5",
+								"aria-hidden": true
+							}) : index + 1
+						}), /* @__PURE__ */ jsx("span", {
+							className: cn("text-sm", state === "active" && "font-medium text-foreground", state === "done" && "text-foreground", state === "future" && "text-muted-foreground"),
+							children: title
+						})] });
+						return /* @__PURE__ */ jsxs(React.Fragment, { children: [index > 0 && /* @__PURE__ */ jsx("li", {
+							"aria-hidden": true,
+							className: "h-px flex-1 bg-border"
+						}), /* @__PURE__ */ jsx("li", { children: state === "future" ? /* @__PURE__ */ jsx("span", {
+							"aria-disabled": "true",
+							className: "flex items-center gap-2 p-1 opacity-70",
+							children: marker
+						}) : /* @__PURE__ */ jsx("button", {
+							type: "button",
+							onClick: () => goTo(index),
+							className: "-m-1 flex items-center gap-2 rounded-md p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+							children: marker
+						}) })] }, `${index}-${title}`);
+					})
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: "sm:hidden",
+					children: [/* @__PURE__ */ jsxs("p", {
+						className: "text-xs text-muted-foreground",
+						children: [
+							"Step ",
+							current + 1,
+							" of ",
+							total,
+							" · ",
+							/* @__PURE__ */ jsx("span", {
+								className: "font-medium text-foreground",
+								children: activeTitle
+							})
+						]
+					}), /* @__PURE__ */ jsx("div", {
+						className: "mt-2 h-1 overflow-hidden rounded-full bg-muted",
+						role: "progressbar",
+						"aria-valuemin": 1,
+						"aria-valuemax": total,
+						"aria-valuenow": current + 1,
+						"aria-label": `Step ${current + 1} of ${total}`,
+						children: /* @__PURE__ */ jsx("div", {
+							className: "h-full rounded-full bg-primary transition-all",
+							style: { width: `${(current + 1) / total * 100}%` }
+						})
+					})]
+				}),
+				steps.map((child, index) => index === current ? /* @__PURE__ */ jsx(React.Fragment, { children: child }, index) : null)
+			]
+		})
+	});
+}
+function WizardStep({ title, children, nextLabel, onNext, nextDisabled, hideBack }) {
+	const { current, total, goTo, back, finish } = useWizardContext("Wizard.Step");
+	const [busy, setBusy] = React.useState(false);
+	const isLast = current === total - 1;
+	async function runNext() {
+		if (!onNext) {
+			if (isLast) finish();
+			else goTo(current + 1);
+			return;
+		}
+		setBusy(true);
+		try {
+			if (await onNext() === false) return;
+			if (isLast) finish();
+			else goTo(current + 1);
+		} catch {} finally {
+			setBusy(false);
+		}
+	}
+	return /* @__PURE__ */ jsxs("section", {
+		"aria-label": title,
+		className: "pt-6",
+		children: [children, (nextLabel || !hideBack) && /* @__PURE__ */ jsxs("div", {
+			className: "mt-6 flex items-center justify-between gap-2 border-t border-border pt-4",
+			children: [!hideBack && current > 0 ? /* @__PURE__ */ jsxs(Button, {
+				type: "button",
+				variant: "ghost",
+				onClick: back,
+				children: [/* @__PURE__ */ jsx(ChevronLeft, {
+					className: "size-4",
+					"aria-hidden": true
+				}), " Back"]
+			}) : /* @__PURE__ */ jsx("span", {}), nextLabel && /* @__PURE__ */ jsx(Button, {
+				type: "button",
+				className: "w-full sm:w-auto",
+				onClick: () => void runNext(),
+				disabled: nextDisabled,
+				loading: busy,
+				children: nextLabel
+			})]
+		})]
+	});
+}
+Wizard.Step = WizardStep;
+//#endregion
+export { Wizard, WizardStep };

package/dist/primitives.d.ts

@@ -50,7 +50,8 @@ import { Pagination, PaginationProps } from "./primitives/pagination.js";
 import { StatusPill, StatusPillProps, StatusTone } from "./primitives/status-pill.js";
 import { Tag, TagProps } from "./primitives/tag.js";
 import { Chip, ChipProps } from "./primitives/chip.js";
+import { Wizard, WizardProps, WizardStep, WizardStepProps } from "./primitives/wizard.js";
 import { Metric, MetricProps, MetricStrip, MetricStripProps } from "./primitives/metric-strip.js";
 import { FilterField, FilterFieldProps, Toolbar, ToolbarProps } from "./primitives/toolbar.js";
 import { Logo, LogoProps, TangleKnot } from "@tangle-network/brand";
-export { Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, type AlertTone, ArtifactPane, type ArtifactPaneProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Button, type ButtonProps, CATEGORY_TONES, Calendar, type CalendarDate, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardTitleProps, type CategoryTone, Checkbox, Chip, type ChipProps, CodeBlock, type CodeBlockProps, Collapsible, CollapsibleContent, CollapsibleTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, type DatePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, type DropZoneProps, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, FilterField, type FilterFieldProps, Heading, type HeadingProps, type HeadingVariant, HelpText, type HelpTextProps, IconTile, type IconTileProps, InlineCode, type InlineCodeProps, Input, type InputProps, Label, Logo, type LogoProps, Metric, type MetricProps, MetricStrip, type MetricStripProps, PageHeader, type PageHeaderProps, PageShell, type PageShellProps, Pagination, type PaginationProps, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, type SidebarDropZoneProps, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, type StatCardProps, StatusPill, type StatusPillProps, type StatusTone, Switch, TONE_CLASSES, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableProps, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, type TagProps, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, type TextShimmerProps, Textarea, type TextareaProps, ThemeToggle, TimeSelect, type TimeSelectProps, type Toast, ToastContainer, ToastProvider, type Tone, type ToneClasses, Toolbar, type ToolbarProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UploadFile, UploadProgress, type UploadProgressProps, badgeVariants, buttonVariants, formatCalendarDate, initialsOf, localToday, parseCalendarDate, toneFor, useTheme, useToast };
+export { Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, type AlertTone, ArtifactPane, type ArtifactPaneProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Button, type ButtonProps, CATEGORY_TONES, Calendar, type CalendarDate, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CardTitleProps, type CategoryTone, Checkbox, Chip, type ChipProps, CodeBlock, type CodeBlockProps, Collapsible, CollapsibleContent, CollapsibleTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, type DatePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, type DropZoneProps, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, FilterField, type FilterFieldProps, Heading, type HeadingProps, type HeadingVariant, HelpText, type HelpTextProps, IconTile, type IconTileProps, InlineCode, type InlineCodeProps, Input, type InputProps, Label, Logo, type LogoProps, Metric, type MetricProps, MetricStrip, type MetricStripProps, PageHeader, type PageHeaderProps, PageShell, type PageShellProps, Pagination, type PaginationProps, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, type SidebarDropZoneProps, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, type StatCardProps, StatusPill, type StatusPillProps, type StatusTone, Switch, TONE_CLASSES, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableProps, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, type TagProps, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, type TextShimmerProps, Textarea, type TextareaProps, ThemeToggle, TimeSelect, type TimeSelectProps, type Toast, ToastContainer, ToastProvider, type Tone, type ToneClasses, Toolbar, type ToolbarProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UploadFile, UploadProgress, type UploadProgressProps, Wizard, type WizardProps, WizardStep, type WizardStepProps, badgeVariants, buttonVariants, formatCalendarDate, initialsOf, localToday, parseCalendarDate, toneFor, useTheme, useToast };

package/dist/primitives.js

@@ -49,8 +49,9 @@ import { StatusPill } from "./primitives/status-pill.js";
 import { CATEGORY_TONES, TONE_CLASSES, toneFor } from "./primitives/tone.js";
 import { Tag } from "./primitives/tag.js";
 import { Chip } from "./primitives/chip.js";
+import { Wizard, WizardStep } from "./primitives/wizard.js";
 import { IconTile, initialsOf } from "./primitives/icon-tile.js";
 import { Metric, MetricStrip } from "./primitives/metric-strip.js";
 import { FilterField, Toolbar } from "./primitives/toolbar.js";
 import { Logo, TangleKnot } from "@tangle-network/brand";
-export { Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, FilterField, Heading, HelpText, IconTile, InlineCode, Input, Label, Logo, Metric, MetricStrip, PageHeader, PageShell, Pagination, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, TimeSelect, ToastContainer, ToastProvider, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, badgeVariants, buttonVariants, formatCalendarDate, initialsOf, localToday, parseCalendarDate, toneFor, useTheme, useToast };
+export { Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, FilterField, Heading, HelpText, IconTile, InlineCode, Input, Label, Logo, Metric, MetricStrip, PageHeader, PageShell, Pagination, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, TimeSelect, ToastContainer, ToastProvider, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, Wizard, WizardStep, badgeVariants, buttonVariants, formatCalendarDate, initialsOf, localToday, parseCalendarDate, toneFor, useTheme, useToast };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.37.0",
+  "version": "11.38.1",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",

package/src/lib/surface-motion.tsx

@@ -12,10 +12,11 @@ type SurfaceProps = React.HTMLAttributes<HTMLDivElement> & {
   "data-state"?: string;
 };
 
-/** Radix owns state, focus and presence; Motion only retargets the visible object. */
+/** Radix owns state and focus; visual retirement cannot wait for a CSS event. */
 export const SurfaceMotion = React.forwardRef<HTMLDivElement, SurfaceProps>(
   ({ kind, side = "right", asChild, "data-state": state, ...props }, forwardedRef) => {
     const element = React.useRef<HTMLDivElement | null>(null);
+    const [retired, setRetired] = React.useState(false);
     const values = React.useRef<Record<"opacity" | "scale" | "x" | "y", MotionValue<number>> | null>(null);
     const controls = React.useRef<Array<ReturnType<typeof animate>>>([]);
     const ref = React.useCallback<React.RefCallback<HTMLDivElement>>((node) => {
@@ -31,7 +32,10 @@ export const SurfaceMotion = React.forwardRef<HTMLDivElement, SurfaceProps>(
       if (!node) return;
       const preference = typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : undefined;
       let cancelRender: (() => void) | undefined;
+      let retirement: ReturnType<typeof setTimeout> | undefined;
       const run = () => {
+        clearTimeout(retirement);
+        setRetired(false);
         const closed = state === "closed";
         const bounds = node.getBoundingClientRect();
         const hidden = {
@@ -49,6 +53,14 @@ export const SurfaceMotion = React.forwardRef<HTMLDivElement, SurfaceProps>(
           node.style.opacity = String(value.opacity);
           node.style.transform = `translateX(${value.x}px) translateY(${value.y}px) scale(${value.scale})`;
         };
+        // Radix may retain an exit until animationend. Retire this DOM node at
+        // the scoped deadline even when keyframes/events are missing or paused;
+        // its null ref lets Radix release presence, focus and modal resources.
+        // Reopen cancels retirement and keeps the same node and Motion values.
+        if (closed) {
+          if (preference?.matches || seconds <= 0 || style.animationName === "none") setRetired(true);
+          else retirement = setTimeout(() => setRetired(true), seconds * 1000);
+        }
         // Missing styles and reduced motion settle synchronously. No semantic
         // transition waits for a JavaScript completion callback.
         if (preference?.matches || seconds <= 0 || style.animationName === "none") {
@@ -73,13 +85,13 @@ export const SurfaceMotion = React.forwardRef<HTMLDivElement, SurfaceProps>(
       };
       run();
       preference?.addEventListener("change", run);
-      return () => { preference?.removeEventListener("change", run); cancelRender?.(); };
+      return () => { clearTimeout(retirement); preference?.removeEventListener("change", run); cancelRender?.(); };
     // Radix Popper temporarily suppresses animation until placement resolves.
     // Start the same retained values when that inline override clears.
     }, [state, kind, side, props.style?.animation]);
     React.useEffect(() => () => controls.current.forEach(control => control.stop()), []);
     const Component = asChild ? Slot : "div";
-    return <Component {...props} data-state={state} ref={ref} />;
+    return state === "closed" && retired ? null : <Component {...props} data-state={state} ref={ref} />;
   },
 );
 SurfaceMotion.displayName = "SurfaceMotion";

package/src/primitives/index.ts

@@ -217,6 +217,9 @@ export type { TagProps } from "./tag";
 export { Chip } from "./chip";
 export type { ChipProps } from "./chip";
 
+export { Wizard, WizardStep } from "./wizard";
+export type { WizardProps, WizardStepProps } from "./wizard";
+
 export { IconTile, initialsOf } from "./icon-tile";
 export type { IconTileProps } from "./icon-tile";
 

package/src/primitives/wizard.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import * as React from "react";
+import { Button } from "./button";
+import { Input } from "./input";
+import { Wizard } from "./wizard";
+
+const meta: Meta<typeof Wizard> = {
+  title: "Primitives/Wizard",
+  component: Wizard,
+};
+export default meta;
+
+/** The intended shape: linear steps, one primary action each, async gate in the middle. */
+export const ConnectNumber: StoryObj<typeof Wizard> = {
+  render: () => (
+    <div className="mx-auto max-w-lg rounded-xl border border-border bg-card p-6">
+      <Wizard onFinished={() => alert("connected")}>
+        <Wizard.Step title="Number" nextLabel="Continue">
+          <label className="grid gap-2 text-sm">
+            Your business number
+            <Input placeholder="+1 618 297 8214" />
+          </label>
+        </Wizard.Step>
+        <Wizard.Step title="Verify" nextLabel="I replied" onNext={() => new Promise(resolve => setTimeout(resolve, 800))}>
+          <p className="text-sm text-muted-foreground">
+            We sent a code to your phone. Reply to the message, then continue.
+          </p>
+        </Wizard.Step>
+        <Wizard.Step title="Done" nextLabel="Finish">
+          <p className="text-sm">Your number is live. Guests can text it now.</p>
+        </Wizard.Step>
+      </Wizard>
+    </div>
+  ),
+};
+
+/** A step whose content owns the actions entirely: no footer, no default chrome. */
+export const CustomActions: StoryObj<typeof Wizard> = {
+  render: () => (
+    <div className="mx-auto max-w-lg rounded-xl border border-border bg-card p-6">
+      <Wizard>
+        <Wizard.Step title="Choice">
+          <div className="grid gap-3">
+            <Button onClick={() => undefined}>Use my own number</Button>
+            <Button variant="outline" onClick={() => undefined}>Give me a Tangle number</Button>
+          </div>
+        </Wizard.Step>
+      </Wizard>
+    </div>
+  ),
+};

package/src/primitives/wizard.test.tsx

@@ -0,0 +1,106 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Wizard } from "./wizard";
+
+function Flow(props: Partial<React.ComponentProps<typeof Wizard>> = {}) {
+  return (
+    <Wizard {...props}>
+      <Wizard.Step title="Number" nextLabel="Continue">pick a number</Wizard.Step>
+      <Wizard.Step title="Verify" nextLabel="I replied">verify panel</Wizard.Step>
+      <Wizard.Step title="Done" nextLabel="Finish">done panel</Wizard.Step>
+    </Wizard>
+  );
+}
+
+describe("Wizard", () => {
+  it("renders the first step and the rail, marks the active step, hides future panels", () => {
+    render(<Flow />);
+    expect(screen.getByText("pick a number")).toBeVisible();
+    expect(screen.queryByText("verify panel")).toBeNull();
+    expect(screen.getByRole("list", { name: "Steps" })).toBeVisible();
+    expect(screen.getAllByText("Number").length).toBeGreaterThan(0);
+  });
+
+  it("advances on the primary action and mirrors onStepChange", async () => {
+    const onStepChange = vi.fn();
+    render(<Flow onStepChange={onStepChange} />);
+    await userEvent.click(screen.getByRole("button", { name: "Continue" }));
+    expect(screen.getByText("verify panel")).toBeVisible();
+    expect(onStepChange).toHaveBeenCalledWith(1);
+  });
+
+  it("back returns to the previous step; the first step has no back", async () => {
+    render(<Flow />);
+    await userEvent.click(screen.getByRole("button", { name: "Continue" }));
+    await userEvent.click(screen.getByRole("button", { name: "Back" }));
+    expect(screen.getByText("pick a number")).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Back" })).toBeNull();
+  });
+
+  it("future steps are not clickable; past steps are", async () => {
+    render(<Flow />);
+    fireEvent.click(screen.getByText("Verify")); // future: a span, not a button
+    expect(screen.getByText("pick a number")).toBeVisible();
+    await userEvent.click(screen.getByRole("button", { name: "Continue" }));
+    await userEvent.click(screen.getAllByRole("button", { name: /Number/ })[0]!); // past: clickable
+    expect(screen.getByText("pick a number")).toBeVisible();
+  });
+
+  it("an async onNext advances only on resolve; returning false keeps the step", async () => {
+    let resolveCheck: (value: unknown) => void = () => {};
+    const onNext = vi.fn(() => new Promise(resolve => { resolveCheck = resolve; }));
+    render(
+      <Wizard>
+        <Wizard.Step title="Check" nextLabel="Check" onNext={onNext}>checking</Wizard.Step>
+        <Wizard.Step title="Next">next panel</Wizard.Step>
+      </Wizard>,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Check" }));
+    expect(screen.getByText("checking")).toBeVisible(); // still here while pending
+    resolveCheck(true);
+    await waitFor(() => expect(screen.getByText("next panel")).toBeVisible());
+    expect(onNext).toHaveBeenCalledTimes(1);
+  });
+
+  it("a rejected onNext stays on the step without crashing", async () => {
+    const onNext = vi.fn(() => Promise.reject(new Error("no")));
+    render(
+      <Wizard>
+        <Wizard.Step title="Check" nextLabel="Check" onNext={onNext}>checking</Wizard.Step>
+        <Wizard.Step title="Next">next panel</Wizard.Step>
+      </Wizard>,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Check" }));
+    await waitFor(() => expect(screen.getByRole("button", { name: "Check" })).toBeEnabled());
+    expect(screen.getByText("checking")).toBeVisible();
+  });
+
+  it("the last step fires onFinished instead of advancing", async () => {
+    const onFinished = vi.fn();
+    render(<Flow onFinished={onFinished} defaultStep={2} />);
+    await userEvent.click(screen.getByRole("button", { name: "Finish" }));
+    expect(onFinished).toHaveBeenCalledTimes(1);
+    expect(screen.getByText("done panel")).toBeVisible();
+  });
+
+  it("step can drive externally (controlled) and omit the default footer action", () => {
+    render(
+      <Wizard step={1}>
+        <Wizard.Step title="One">one</Wizard.Step>
+        <Wizard.Step title="Two"><button type="button">custom</button></Wizard.Step>
+      </Wizard>,
+    );
+    expect(screen.getAllByText("Two").length).toBeGreaterThan(0);
+    expect(screen.getByText("custom")).toBeVisible();
+    expect(screen.queryByRole("button", { name: "Continue" })).toBeNull();
+  });
+
+  it("throws when a step is used outside a wizard", () => {
+    // Silence the expected console.error from React's error boundary path.
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(() => render(<Wizard.Step title="Alone">x</Wizard.Step>)).toThrow(/must be used inside/);
+    spy.mockRestore();
+  });
+});

package/src/primitives/wizard.tsx

@@ -0,0 +1,212 @@
+import { Check, ChevronLeft } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { Button } from "./button";
+
+/**
+ * A multi-step flow — onboarding, connection setup, anything where a person
+ * should see one decision at a time.
+ *
+ * The library owns the chrome (step rail, progress, footer); each step owns
+ * its content and its primary action. That separation is the point: products
+ * stop rebuilding stepper markup with drifting styles, and a person gets the
+ * same rhythm — one screen, one obvious action — in every Tangle app.
+ *
+ * Composition (DOM order is the step order):
+ *
+ * ```tsx
+ * <Wizard onFinished={() => navigate("/done")}>
+ *   <Wizard.Step title="Number" nextLabel="Continue">…</Wizard.Step>
+ *   <Wizard.Step title="Verify" nextLabel="I replied" onNext={() => check()}>…</Wizard.Step>
+ *   <Wizard.Step title="Done" nextLabel="Finish">…</Wizard.Step>
+ * </Wizard>
+ * ```
+ *
+ * - **Uncontrolled by default**; pass `step` to drive it (a background poll
+ *   can jump straight to Done). `onStepChange` mirrors every move.
+ * - **The step names its action.** `nextLabel` renders the footer's primary
+ *   button; an async `onNext` shows `loading` and advances only on resolve,
+ *   so failures keep the person on the step with the app's inline error.
+ *   Omit `nextLabel` for steps whose content renders its own actions.
+ * - **Forward is earned, backward is free.** Future steps are not clickable;
+ *   past steps are (people re-check earlier choices mid-flow).
+ * - **Mobile is a first-class shape**, not a squeezed desktop: below `sm` the
+ *   rail collapses to "Step 2 of 3 · Verify" and a thin progress bar.
+ *
+ * Wizard renders no card — compose it inside a `Card` when the surface needs
+ * one, so containers-within-containers stay a choice, not a default.
+ */
+
+interface WizardContextValue {
+  current: number;
+  total: number;
+  goTo: (step: number) => void;
+  next: () => void;
+  back: () => void;
+  /** Set by Wizard: fires onFinished when the final step's action resolves. */
+  finish: () => void;
+}
+
+const WizardContext = React.createContext<WizardContextValue | null>(null);
+
+function useWizardContext(component: string): WizardContextValue {
+  const context = React.useContext(WizardContext);
+  if (!context) throw new Error(`<${component}> must be used inside <Wizard>`);
+  return context;
+}
+
+export interface WizardProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Drives the active step; omit for uncontrolled with `defaultStep`. */
+  step?: number;
+  defaultStep?: number;
+  onStepChange?: (step: number) => void;
+  /** Fires when the last step's primary action resolves. */
+  onFinished?: () => void;
+}
+
+export function Wizard({ children, step, defaultStep = 0, onStepChange, onFinished, className, ...rest }: WizardProps) {
+  const steps = React.Children.toArray(children).filter(React.isValidElement) as React.ReactElement<WizardStepProps>[];
+  const [internal, setInternal] = React.useState(defaultStep);
+  const current = step !== undefined ? step : internal;
+  const total = steps.length;
+
+  const goTo = React.useCallback((target: number) => {
+    const bounded = Math.max(0, Math.min(target, total - 1));
+    if (bounded === current) return;
+    onStepChange?.(bounded);
+    if (step === undefined) setInternal(bounded);
+  }, [current, onStepChange, step, total]);
+
+  const context = React.useMemo<WizardContextValue>(() => ({
+    current,
+    total,
+    goTo,
+    next: () => goTo(current + 1),
+    back: () => goTo(current - 1),
+    finish: () => onFinished?.(),
+  }), [current, goTo, onFinished, total]);
+
+  const titles = steps.map(child => child.props.title);
+  const activeTitle = titles[current] ?? "";
+
+  return (
+    <WizardContext.Provider value={context}>
+      <div className={cn("w-full", className)} {...rest}>
+        {/* Desktop rail. */}
+        <ol aria-label="Steps" className="hidden items-center gap-2 sm:flex">
+          {titles.map((title, index) => {
+            const state = index < current ? "done" : index === current ? "active" : "future";
+            const marker = (
+              <>
+                <span className={cn(
+                  "flex size-6 shrink-0 items-center justify-center rounded-full text-xs font-medium",
+                  state === "active" && "bg-primary text-primary-foreground",
+                  state === "done" && "bg-primary/15 text-primary",
+                  state === "future" && "bg-muted text-muted-foreground",
+                )}>
+                  {state === "done" ? <Check className="size-3.5" aria-hidden /> : index + 1}
+                </span>
+                <span className={cn(
+                  "text-sm",
+                  state === "active" && "font-medium text-foreground",
+                  state === "done" && "text-foreground",
+                  state === "future" && "text-muted-foreground",
+                )}>{title}</span>
+              </>
+            );
+            return (
+              <React.Fragment key={`${index}-${title}`}>
+                {index > 0 && <li aria-hidden className="h-px flex-1 bg-border" />}
+                <li>
+                  {state === "future"
+                    ? <span aria-disabled="true" className="flex items-center gap-2 p-1 opacity-70">{marker}</span>
+                    : <button type="button" onClick={() => goTo(index)}
+                        className="-m-1 flex items-center gap-2 rounded-md p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+                        {marker}
+                      </button>}
+                </li>
+              </React.Fragment>
+            );
+          })}
+        </ol>
+        {/* Mobile: position + progress, not a squeezed rail. */}
+        <div className="sm:hidden">
+          <p className="text-xs text-muted-foreground">
+            Step {current + 1} of {total} · <span className="font-medium text-foreground">{activeTitle}</span>
+          </p>
+          <div className="mt-2 h-1 overflow-hidden rounded-full bg-muted" role="progressbar"
+            aria-valuemin={1} aria-valuemax={total} aria-valuenow={current + 1} aria-label={`Step ${current + 1} of ${total}`}>
+            <div className="h-full rounded-full bg-primary transition-all" style={{ width: `${((current + 1) / total) * 100}%` }} />
+          </div>
+        </div>
+        {steps.map((child, index) => index === current
+          ? <React.Fragment key={index}>{child}</React.Fragment>
+          : null)}
+      </div>
+    </WizardContext.Provider>
+  );
+}
+
+export interface WizardStepProps {
+  /** Shown in the rail (and the mobile position line). Steps read at a glance; keep it one or two words. */
+  title: string;
+  children: React.ReactNode;
+  /** The footer's primary action label. Omit when the step renders its own actions. */
+  nextLabel?: string;
+  /** Runs before advancing. Resolve (or return a non-false value) to advance; return false or throw to stay — the step's own content shows why. */
+  onNext?: () => Promise<unknown> | unknown;
+  /** Disables the primary action (a required choice is still missing). */
+  nextDisabled?: boolean;
+  /** Hides the Back button for steps where going back makes no sense (a completed handshake). */
+  hideBack?: boolean;
+}
+
+export function WizardStep({ title, children, nextLabel, onNext, nextDisabled, hideBack }: WizardStepProps) {
+  const { current, total, goTo, back, finish } = useWizardContext("Wizard.Step");
+  const [busy, setBusy] = React.useState(false);
+  const isLast = current === total - 1;
+
+  async function runNext() {
+    if (!onNext) {
+      if (isLast) finish(); else goTo(current + 1);
+      return;
+    }
+    setBusy(true);
+    try {
+      const result = await onNext();
+      if (result === false) return;
+      if (isLast) finish(); else goTo(current + 1);
+    } catch {
+      // Stay on the step; its content owns the error presentation. A rejected
+      // promise here must not surface as an unhandled flow crash.
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section aria-label={title} className="pt-6">
+      {children}
+      {(nextLabel || !hideBack) && (
+        <div className="mt-6 flex items-center justify-between gap-2 border-t border-border pt-4">
+          {!hideBack && current > 0
+            ? <Button type="button" variant="ghost" onClick={back}><ChevronLeft className="size-4" aria-hidden /> Back</Button>
+            : <span />}
+          {nextLabel && (
+            <Button type="button" className="w-full sm:w-auto" onClick={() => void runNext()} disabled={nextDisabled} loading={busy}>
+              {nextLabel}
+            </Button>
+          )}
+        </div>
+      )}
+    </section>
+  );
+}
+
+// Dot-notation composition (`<Wizard.Step>`), attached after both definitions
+// so each keeps a plain, tree-shakeable named export.
+export interface Wizard extends React.FC<WizardProps> {
+  Step: typeof WizardStep;
+}
+(Wizard as Wizard).Step = WizardStep;