@vllnt/ui 0.2.1 → 0.3.0-canary.a42d8f4

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to `@vllnt/ui` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+> Target version: **`0.3.0`** — shipping as `0.3.0-canary.<sha>` on the npm `canary` tag on every merge to main. The stable `latest` release is gated on the [ROADMAP.md](../../ROADMAP.md) shipping criteria and is not yet published.
+
+### Added
+
+- **Release intelligence surface** — `/changelog`, `/releases`, `/rss.xml`, and `/atom.xml` expose one changelog source through HTML, GitHub release cards, and feed readers. `/docs/changelog` redirects to `/changelog`.
+- **Hooks + utility primitives** — `CopyButton` (+ `useCopyToClipboard` hook), `Banner` + `BannerAction`, `Kbd`, `EmptyState`, `DocumentSiblingNav`.
+- **Pricing + identity cards** — `PricingTable` + `PricingPlan`, `HistoricalFigureCard`, `CivilizationCard` (+ `CivilizationComparison`).
+- **Newsletter** — `NewsletterSignup` (state-machine driven submit flow).
+- **AI compound families** — `ModelComparison` (+ `Column`, `Meta`, `Vote`), `PromptTemplates`, `AgentActivity`, `AISidebar`, `AIArtifact`.
+- **Era / financial** — `EraComparison`, `TransactionList`.
+- **Forms** — `Form`, `MultiSelect`, `SegmentedControl`, `TagsInput`, `AutoReload`.
+- **Educational** — `KnowledgeCheck` (inline question runner).
+- **Charts + timelines** — `GanttChart`, `ParallelTimeline`, `Timeline` + `TimelineItem`, `HistoricTimeline`, `InteractiveTimeline`, `ChronologicalTimeline`, `TreeView`.
+- **Document + reading** — `PrimarySourceViewer` compound family.
+- **Maps + geography** — `Map2D`, `ChoroplethMap`, `RouteMap`, `HeatMapOverlay`, `GeographyQuizMap`, `MapTimeline`, `StoryMap`, `Globe3D`.
+- **Canvas foundation** — `CanvasShell`, `CanvasView`, `InfinitePlane`, `ViewportBookmarks`, `WorldBreadcrumbs`, `TopBar`, `LeftRail`, `RightDock`, `ZoomHud`, `MiniMapPanel`, `WorkspaceSwitcher`.
+- **Canvas selection + manipulation** — `SelectionHalo`, `SnapGuides`, `FloatingToolbar`, `MultiSelectLasso`, `FollowMode`, `HandoffBeacon`.
+- **Canvas spatial objects** — `ObjectCard`, `ObjectHandle`, `AnchorPort`, `ConnectorEdge`, `EdgeLabel`, `GroupHull`.
+- **Canvas collaboration primitives** — `LiveCursor`, `CommentPin`, `PresenceSyncIndicator`, `PresenceStack`, `SelectionPresence`, `ThreadBubble`.
+- **Inspector + dock panels** — `PropertySection`, `ObjectInspector`, `RelationshipInspector`, `RuntimeOverviewPanel`, `RoutingAssignmentPanel`, `PolicyDeliveryPanel`.
+- **Runtime overlays** — `AlertPulse`, `ThresholdRing`, `StickyMetric`, `HeatOverlay`, `StateBadgeOverlay`, `MetricCluster`, `JarvisDock`, `ContextLens`.
+- **Time navigation** — `TimelineScrubber`, `PlaybackGhost`, `BottomActivityStrip`, `RunTimeline`.
+- Total component count: **225** (up from 140).
+
+- **A11y heading-level override** — every title-bearing component (`ProfileSection`, `FAQ`, `Slideshow`, `WorldClockBar`, `TableOfContentsPanel`, `TableOfContents`, `KeyboardShortcutsHelp`, `Watchlist`, `OrderBook`, `HorizontalScrollRow`, `MarketTreemap`, `ActivityHeatmap`, `Glossary`, `StatusBoard`, `CodePlayground`, `Comparison`, `Quiz`, `Exercise`, `ShareSection`, `CompletionDialog`, `Checklist`, `LearningObjectives`, `CandlestickChart`, `StepByStep`) accepts an `as` prop (`"h1"`–`"h6"`); multi-title components (`ContentIntro`, `TutorialComplete`) expose `titleAs` + `tocLabelAs` / `sectionLabelAs`. Defaults preserve existing heading tags. `HeadingTag` is re-exported from `@vllnt/ui`.
+
+### Changed
+
+- Registry installs use a **hybrid CLI strategy** — leaf component source is inlined, sibling registry items resolve via `@vllnt/ui` to keep installs minimal and dedupe shared primitives.
+
+### Notes
+
+- `ROADMAP.md` added at repo root tracking 50 open issues across 8 phases gating the `0.3.0` cut.
+- `0.3.0` requires the codebase-health gate (`react-doctor` CI + 0 errors), the agent-first surface (`/llms.txt`, `/mcp`, sitemap, JSON-LD), and the rebuilt landing page before shipping.
+
 ## [0.2.1] - 2026-04-21
 
 ### Fixed

package/README.md

@@ -44,7 +44,7 @@ export default {
 ```
 
 The preset configures:
-- **Colors**: `primary`, `secondary`, `muted`, `accent`, `destructive`, `background`, `foreground`, `card`, `popover`, `border`, `input`, `ring` — all as `hsl(var(--name))` for theming
+- **Colors**: `primary`, `secondary`, `muted`, `accent`, `destructive`, `background`, `foreground`, `card`, `popover`, `border`, `input`, `ring` — all as `oklch(var(--name) / <alpha-value>)` for theming
 - **Border radius**: `lg`, `md`, `sm` via `--radius` CSS variable
 - **Animations**: `accordion-down`, `accordion-up`, `shimmer`
 - **Font**: `mono` family via `--font-mono` variable
@@ -83,45 +83,59 @@ export function Example() {
 | `@vllnt/ui/tailwind-preset` | Tailwind CSS preset config |
 | `@vllnt/ui/styles.css` | Full styles (Tailwind base + theme variables + utilities) |
 | `@vllnt/ui/themes/default.css` | Theme CSS variables only (no Tailwind base) |
+| `@vllnt/ui/themes/presets.css` | Built-in color presets (applied via `data-theme`) |
 
 ## Theming
 
-All colors use HSL CSS variables. Override them after importing styles:
+All colors are **OKLCH channel** CSS variables (`L C H`), consumed as
+`oklch(var(--name) / <alpha-value>)`. Override them after importing styles:
 
 ```css
 /* Light theme */
 :root {
-  --background: 0 0% 100%;
-  --foreground: 0 0% 3.9%;
-  --primary: 222.2 47.4% 11.2%;
-  --primary-foreground: 210 40% 98%;
-  --secondary: 210 40% 96.1%;
-  --secondary-foreground: 222.2 47.4% 11.2%;
-  --muted: 210 40% 96.1%;
-  --muted-foreground: 215.4 16.3% 46.9%;
-  --accent: 210 40% 96.1%;
-  --accent-foreground: 222.2 47.4% 11.2%;
-  --destructive: 0 84.2% 60.2%;
-  --destructive-foreground: 0 0% 98%;
-  --border: 214.3 31.8% 91.4%;
-  --input: 214.3 31.8% 91.4%;
-  --ring: 222.2 84% 4.9%;
+  --background: 1 0 0;
+  --foreground: 0.1445 0 0;
+  --primary: 0.2044 0 0;
+  --primary-foreground: 0.9848 0 0;
+  --secondary: 0.9703 0 0;
+  --secondary-foreground: 0.2044 0 0;
+  --muted: 0.9703 0 0;
+  --muted-foreground: 0.5555 0 0;
+  --accent: 0.9703 0 0;
+  --accent-foreground: 0.2044 0 0;
+  --destructive: 0.6368 0.2078 25.326;
+  --destructive-foreground: 0.9848 0 0;
+  --border: 0.9219 0 0;
+  --input: 0.9219 0 0;
+  --ring: 0.1445 0 0;
   --radius: 0.5rem;
-  --card: 0 0% 100%;
-  --card-foreground: 0 0% 3.9%;
-  --popover: 0 0% 100%;
-  --popover-foreground: 0 0% 3.9%;
+  --card: 1 0 0;
+  --card-foreground: 0.1445 0 0;
+  --popover: 1 0 0;
+  --popover-foreground: 0.1445 0 0;
 }
 
 /* Dark theme (applied via class="dark" on html/body) */
 .dark {
-  --background: 0 0% 3.9%;
-  --foreground: 0 0% 98%;
+  --background: 0 0 0;
+  --foreground: 0.9848 0 0;
   /* ... override other variables */
 }
 ```
 
-Use `@vllnt/ui/themes/default.css` instead of `@vllnt/ui/styles.css` if you only want the variables without Tailwind base layer styles.
+Use `@vllnt/ui/themes/default.css` instead of `@vllnt/ui/styles.css` if you only
+want the variables without the Tailwind base layer.
+
+### Runtime presets & the theme editor
+
+Import `@vllnt/ui/themes/presets.css` and switch between built-in color presets
+at runtime with `<ThemeSwitcher />` (or `setThemePreset` / `useThemePreset`),
+which set `data-theme` on the document root. Render `<ThemePresetProvider />`
+once near the root to restore the saved preset before paint.
+
+To design and export your own theme, use the visual editor at
+[`/themes`](https://ui.vllnt.ai/themes) — it exports a CSS block, a
+`npx shadcn add` command, or design tokens.
 
 ## Component Patterns
 
@@ -218,7 +232,7 @@ import {
 | `Alert` | `{ Alert, AlertTitle, AlertDescription, alertVariants }` | Static alert banner |
 | `Badge` | `{ Badge, badgeVariants }` | Inline status label. Variants: default, secondary, destructive, outline |
 | `Skeleton` | `{ Skeleton }` | Loading placeholder |
-| `Spinner` | `{ Spinner }` | Loading spinner |
+| `Spinner` | `{ Spinner, UnicodeSpinner }` | Styled spinner + ASCII-art `UnicodeSpinner` for terminals / code blocks |
 
 ### Navigation
 
@@ -242,7 +256,7 @@ import {
 | `BarChart` | `{ BarChart }` | Chart component |
 | `LineChart` | `{ LineChart }` | Chart component |
 | `CodeBlock` | `{ CodeBlock }` | Syntax-highlighted code via `react-syntax-highlighter` |
-| `FlowDiagram` | `{ FlowDiagram }` | Flow diagram via `@xyflow/react` |
+| `FlowDiagram` | `{ FlowDiagram, FlowControls, FlowFullscreen, FlowErrorBoundary, useFlowDiagram }` | Flow diagram via `@xyflow/react`. Extras: custom controls, fullscreen wrapper, error boundary, and the `useFlowDiagram` hook for imperative access. |
 | `TableOfContents` | `{ TableOfContents }` | Page table of contents |
 
 ### App Components
@@ -276,7 +290,10 @@ import {
 | `Flashcard` | `{ Flashcard }` | Flip-card for spaced repetition |
 | `Stepper` | `{ Stepper }` | Linear progress stepper |
 | `Tour` | `{ Tour }` | Guided product tour |
-| `Annotation` | `{ Annotation }` | Inline annotation / highlight |
+| `Annotation` | `{ Annotation, Highlight }` | Inline annotation block + inline `Highlight` span for in-prose emphasis |
+| `LearningObjectives` | `{ LearningObjectives, Prerequisites, Summary }` | Objectives list plus companion `Prerequisites` and `Summary` blocks |
+| `KeyConcept` | `{ KeyConcept, Glossary }` | Concept callout + `Glossary` term list |
+| `Comparison` | `{ Comparison, BeforeAfter }` | Side-by-side compare block + `BeforeAfter` slider |
 | `CompletionDialog` | `{ CompletionDialog }` | End-of-flow celebration dialog |
 | `TruncatedText` | `{ TruncatedText }` | Expand-on-overflow text block |
 | `TableOfContentsPanel` | `{ TableOfContentsPanel }` | Sidebar TOC panel |
@@ -334,7 +351,7 @@ import {
 | `BorderBeam` | `{ BorderBeam }` | Animated gradient border |
 | `Marquee` | `{ Marquee }` | Infinite scroll marquee |
 | `NumberTicker` | `{ NumberTicker }` | Animated number counter |
-| `Spinner` | `{ Spinner }` | Rich loading-spinner library |
+| `Spinner` | `{ Spinner, UnicodeSpinner }` | Styled spinner + ASCII-art `UnicodeSpinner` for terminals / code blocks |
 
 ### Form Additions
 
@@ -386,10 +403,22 @@ import { cn } from "@vllnt/ui";
 <div className={cn("p-4 bg-primary", isActive && "bg-accent", className)} />
 ```
 
+### Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useDebounce(value, delayMs)` | Returns the value after `delayMs` of idle — ideal for search inputs. |
+| `useHorizontalScroll(ref)` | Drives the behavior used by `HorizontalScrollRow` — wheel → horizontal scroll, scroll-snap helpers. |
+| `useMobile(breakpoint?)` | Boolean for "viewport is below breakpoint" (default `768`). SSR-safe. |
+| `useSidebar()` | Reads `SidebarProvider` state — `{ open, setOpen, toggle }`. Throws outside a provider. |
+| `useFlowDiagram(options)` | Imperative controller for `FlowDiagram` — fit view, zoom, export to PNG. |
+| `useSocialFab()` | Drives the open/close state of `SocialFab`. |
+
 ```tsx
-import { useDebounce } from "@vllnt/ui";
+import { useDebounce, useMobile } from "@vllnt/ui";
 
-const debouncedValue = useDebounce(searchTerm, 300);
+const query = useDebounce(input, 300);
+const isMobile = useMobile();
 ```
 
 ## Types

package/dist/components/accordion/accordion.js

@@ -104,7 +104,7 @@ function AccordionTrigger({
           "span",
           {
             className: cn(
-              "h-4 w-4 flex-shrink-0 transition-transform duration-200",
+              "size-4 flex-shrink-0 transition-transform duration-200",
               isOpen && "rotate-180"
             ),
             children: icon
@@ -113,7 +113,7 @@ function AccordionTrigger({
           "svg",
           {
             className: cn(
-              "h-4 w-4 flex-shrink-0 transition-transform duration-200",
+              "size-4 flex-shrink-0 transition-transform duration-200",
               isOpen && "rotate-180"
             ),
             fill: "none",

package/dist/components/activity-heatmap/activity-heatmap.js

@@ -72,19 +72,21 @@ function getGridData(data, endDate, weeks) {
     });
   });
 }
+const MONTH_LABEL_FORMATTER = new Intl.DateTimeFormat("en-US", {
+  month: "short",
+  timeZone: "UTC"
+});
+const TOOLTIP_DATE_FORMATTER = new Intl.DateTimeFormat("en-US", {
+  day: "numeric",
+  month: "short",
+  timeZone: "UTC",
+  year: "numeric"
+});
 function formatMonthLabel(date) {
-  return new Intl.DateTimeFormat("en-US", {
-    month: "short",
-    timeZone: "UTC"
-  }).format(date);
+  return MONTH_LABEL_FORMATTER.format(date);
 }
 function formatTooltip(date, count) {
-  const formattedDate = new Intl.DateTimeFormat("en-US", {
-    day: "numeric",
-    month: "short",
-    timeZone: "UTC",
-    year: "numeric"
-  }).format(date);
+  const formattedDate = TOOLTIP_DATE_FORMATTER.format(date);
   return `${count} activity ${count === 1 ? "event" : "events"} on ${formattedDate}`;
 }
 function HeatmapGrid({
@@ -127,15 +129,15 @@ function HeatmapGrid({
     ),
     /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-end gap-2 text-xs text-muted-foreground", children: [
       /* @__PURE__ */ jsx("span", { children: "Less" }),
-      LEVEL_CLASS_NAMES.map((className, index) => /* @__PURE__ */ jsx(
+      LEVEL_CLASS_NAMES.map((className) => /* @__PURE__ */ jsx(
         "span",
         {
           className: cn(
-            "h-3 w-3 rounded-[3px] border border-border/40",
+            "size-3 rounded-[3px] border border-border/40",
             className
           )
         },
-        `legend-${index}`
+        `legend-${className}`
       )),
       /* @__PURE__ */ jsx("span", { children: "More" })
     ] })
@@ -143,6 +145,7 @@ function HeatmapGrid({
 }
 const ActivityHeatmap = React.forwardRef(
   ({
+    as: Heading = "h2",
     className,
     data,
     description,
@@ -155,7 +158,7 @@ const ActivityHeatmap = React.forwardRef(
     const gridData = getGridData(data, normalizedEndDate, weeks);
     return /* @__PURE__ */ jsxs("div", { className: cn("space-y-4", className), ref, ...props, children: [
       /* @__PURE__ */ jsxs("div", { className: "space-y-1", children: [
-        /* @__PURE__ */ jsx("h2", { className: "text-lg font-semibold tracking-tight", children: title }),
+        /* @__PURE__ */ jsx(Heading, { className: "text-lg font-semibold tracking-tight", children: title }),
         description ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: description }) : null
       ] }),
       /* @__PURE__ */ jsx("div", { className: "overflow-x-auto rounded-lg border bg-card p-4 shadow-sm", children: /* @__PURE__ */ jsx(HeatmapGrid, { gridData, weeks }) })

package/dist/components/activity-log/activity-log.js

@@ -1,8 +1,9 @@
+"use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { forwardRef, useMemo, useState } from "react";
 import { ArrowRight, ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../../lib/utils";
-import { Avatar, AvatarFallback } from "../avatar";
+import { Avatar, AvatarFallback } from "../avatar/avatar";
 import { Badge } from "../badge";
 import { Button } from "../button";
 import {
@@ -81,7 +82,7 @@ function PaginationControls({
         size: "sm",
         variant: "outline",
         children: [
-          /* @__PURE__ */ jsx(ChevronLeft, { className: "h-4 w-4" }),
+          /* @__PURE__ */ jsx(ChevronLeft, { className: "size-4" }),
           "Previous"
         ]
       }
@@ -110,7 +111,7 @@ function PaginationControls({
         variant: "outline",
         children: [
           "Next",
-          /* @__PURE__ */ jsx(ChevronRight, { className: "h-4 w-4" })
+          /* @__PURE__ */ jsx(ChevronRight, { className: "size-4" })
         ]
       }
     )
@@ -131,18 +132,18 @@ function ActivityRow({ item }) {
       {
         "aria-hidden": "true",
         className: cn(
-          "absolute left-4 top-3 h-3 w-3 rounded-full ring-4 ring-background",
+          "absolute left-4 top-3 size-3 rounded-full ring-4 ring-background",
           palette.markerClassName
         )
       }
     ),
     /* @__PURE__ */ jsx("div", { className: "rounded-lg border bg-background/70 p-4", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [
       /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 items-start gap-3", children: [
-        /* @__PURE__ */ jsx(Avatar, { className: "h-9 w-9 border bg-muted", children: /* @__PURE__ */ jsx(AvatarFallback, { children: getInitials(item.actor) }) }),
+        /* @__PURE__ */ jsx(Avatar, { className: "size-9 border bg-muted", children: /* @__PURE__ */ jsx(AvatarFallback, { children: getInitials(item.actor) }) }),
         /* @__PURE__ */ jsxs("div", { className: "min-w-0 space-y-1", children: [
           /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [
             /* @__PURE__ */ jsx("span", { className: "font-medium text-foreground", children: item.actor }),
-            /* @__PURE__ */ jsx(ArrowRight, { className: "h-3.5 w-3.5 text-muted-foreground" }),
+            /* @__PURE__ */ jsx(ArrowRight, { className: "size-3.5 text-muted-foreground" }),
             /* @__PURE__ */ jsx("span", { className: "text-sm text-muted-foreground", children: item.action }),
             item.target ? /* @__PURE__ */ jsx("span", { className: "truncate text-sm font-medium text-foreground", children: item.target }) : null
           ] }),

package/dist/components/agent-activity/agent-activity.js

@@ -0,0 +1,311 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useState
+} from "react";
+import {
+  AlertTriangle,
+  CheckCircle2,
+  ChevronDown,
+  Circle,
+  Loader2,
+  MinusCircle
+} from "lucide-react";
+import { cn } from "../../lib/utils";
+const STATUS_CLASSES = {
+  completed: {
+    iconClass: "text-emerald-600 dark:text-emerald-400",
+    ringClass: "ring-emerald-500/30",
+    rowClass: "border-border bg-background"
+  },
+  error: {
+    iconClass: "text-destructive",
+    ringClass: "ring-destructive/40",
+    rowClass: "border-destructive/40 bg-destructive/5"
+  },
+  pending: {
+    iconClass: "text-muted-foreground",
+    ringClass: "ring-border",
+    rowClass: "border-border bg-muted/20 text-muted-foreground"
+  },
+  running: {
+    iconClass: "text-primary",
+    ringClass: "ring-primary/30",
+    rowClass: "border-primary/30 bg-primary/5"
+  },
+  skipped: {
+    iconClass: "text-muted-foreground/60",
+    ringClass: "ring-border",
+    rowClass: "border-border bg-background text-muted-foreground/80"
+  }
+};
+const DEFAULT_STATUS_ICON = {
+  completed: /* @__PURE__ */ jsx(CheckCircle2, { "aria-hidden": "true", className: "size-4" }),
+  error: /* @__PURE__ */ jsx(AlertTriangle, { "aria-hidden": "true", className: "size-4" }),
+  pending: /* @__PURE__ */ jsx(Circle, { "aria-hidden": "true", className: "size-4" }),
+  running: /* @__PURE__ */ jsx(Loader2, { "aria-hidden": "true", className: "size-4 animate-spin" }),
+  skipped: /* @__PURE__ */ jsx(MinusCircle, { "aria-hidden": "true", className: "size-4" })
+};
+const StepContext = createContext({ status: "pending" });
+const DEFAULT_LABELS = {
+  activity: "Activity",
+  collapse: "Hide details",
+  elapsed: "Elapsed",
+  expand: "Show details"
+};
+const ACTIVITY_LIVE_REGION_ROLE = {
+  completed: "status",
+  error: "status",
+  idle: "status",
+  running: "log"
+};
+const AgentActivity = forwardRef(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      elapsed,
+      labels,
+      status = "idle",
+      ...rest
+    } = props;
+    const resolvedLabels = { ...DEFAULT_LABELS, ...labels };
+    return /* @__PURE__ */ jsxs(
+      "section",
+      {
+        "aria-live": status === "running" ? "polite" : "off",
+        className: cn(
+          "flex flex-col gap-3 rounded-2xl border bg-background p-4",
+          className
+        ),
+        "data-status": status,
+        ref,
+        role: ACTIVITY_LIVE_REGION_ROLE[status],
+        ...rest,
+        children: [
+          /* @__PURE__ */ jsxs("header", { className: "flex items-center justify-between gap-3", children: [
+            /* @__PURE__ */ jsx("h3", { className: "text-sm font-semibold tracking-tight text-foreground", children: resolvedLabels.activity }),
+            elapsed ? /* @__PURE__ */ jsx(
+              "span",
+              {
+                "aria-label": resolvedLabels.elapsed,
+                className: "text-xs font-mono text-muted-foreground",
+                children: elapsed
+              }
+            ) : null
+          ] }),
+          /* @__PURE__ */ jsx("ol", { className: "flex flex-col gap-2", children })
+        ]
+      }
+    );
+  }
+);
+AgentActivity.displayName = "AgentActivity";
+function getDisplayName(value) {
+  if (value !== null && (typeof value === "object" || typeof value === "function") && "displayName" in value && typeof value.displayName === "string") {
+    return value.displayName;
+  }
+  return void 0;
+}
+function isAgentStepDetailElement(child) {
+  if (child === null || typeof child !== "object") return false;
+  if (!("type" in child)) return false;
+  return getDisplayName(child.type) === "AgentStepDetail";
+}
+function splitChildren(children) {
+  const items = Array.isArray(children) ? children : [children];
+  return items.reduce(
+    (split, child) => {
+      if (isAgentStepDetailElement(child)) {
+        split.body.push(child);
+      } else {
+        split.header.push(child);
+      }
+      return split;
+    },
+    { body: [], header: [] }
+  );
+}
+function StepRow({
+  detailsId,
+  hasDetails,
+  header,
+  icon,
+  iconClass,
+  labels,
+  onToggle,
+  open
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-3 px-3 py-2", children: [
+    /* @__PURE__ */ jsx(
+      "span",
+      {
+        "aria-hidden": "true",
+        className: cn(
+          "mt-0.5 inline-flex size-5 shrink-0 items-center justify-center",
+          iconClass
+        ),
+        children: icon
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: header }),
+    hasDetails ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        "aria-controls": detailsId,
+        "aria-expanded": open,
+        "aria-label": open ? labels.collapse : labels.expand,
+        className: "ml-auto inline-flex size-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-foreground/10 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        onClick: onToggle,
+        type: "button",
+        children: /* @__PURE__ */ jsx(
+          ChevronDown,
+          {
+            "aria-hidden": "true",
+            className: cn(
+              "size-4 transition-transform",
+              open ? "rotate-180" : "rotate-0"
+            )
+          }
+        )
+      }
+    ) : null
+  ] });
+}
+const AgentStep = forwardRef(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      defaultOpen = true,
+      icon,
+      status,
+      ...rest
+    } = props;
+    const split = useMemo(() => splitChildren(children), [children]);
+    const palette = STATUS_CLASSES[status];
+    const hasDetails = split.body.length > 0;
+    const [open, setOpen] = useState(defaultOpen);
+    const detailsId = useId();
+    const handleToggle = useCallback(() => {
+      setOpen((value) => !value);
+    }, []);
+    const contextValue = useMemo(
+      () => ({ status }),
+      [status]
+    );
+    const resolvedIcon = icon ?? DEFAULT_STATUS_ICON[status];
+    return /* @__PURE__ */ jsx(
+      "li",
+      {
+        className: cn(
+          "rounded-xl border ring-1",
+          palette.rowClass,
+          palette.ringClass,
+          className
+        ),
+        "data-status": status,
+        ref,
+        ...rest,
+        children: /* @__PURE__ */ jsxs(StepContext.Provider, { value: contextValue, children: [
+          /* @__PURE__ */ jsx(
+            StepRow,
+            {
+              detailsId,
+              hasDetails,
+              header: split.header,
+              icon: resolvedIcon,
+              iconClass: palette.iconClass,
+              labels: DEFAULT_LABELS,
+              onToggle: handleToggle,
+              open
+            }
+          ),
+          hasDetails && open ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: "border-t border-border/60 px-3 py-2 text-xs",
+              id: detailsId,
+              children: /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-2 pl-8", children: split.body })
+            }
+          ) : null
+        ] })
+      }
+    );
+  }
+);
+AgentStep.displayName = "AgentStep";
+const AgentStepTitle = forwardRef(({ className, ...rest }, ref) => /* @__PURE__ */ jsx(
+  "p",
+  {
+    className: cn(
+      "text-sm font-medium leading-tight text-foreground",
+      className
+    ),
+    ref,
+    ...rest
+  }
+));
+AgentStepTitle.displayName = "AgentStepTitle";
+const AgentStepDuration = forwardRef(({ className, ...rest }, ref) => /* @__PURE__ */ jsx(
+  "span",
+  {
+    className: cn("font-mono text-xs text-muted-foreground", className),
+    ref,
+    ...rest
+  }
+));
+AgentStepDuration.displayName = "AgentStepDuration";
+const AgentStepProgress = forwardRef(({ className, label = "Step progress", value, ...rest }, ref) => {
+  const clamped = Math.max(0, Math.min(100, value));
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "aria-label": label,
+      "aria-valuemax": 100,
+      "aria-valuemin": 0,
+      "aria-valuenow": clamped,
+      className: cn("h-1.5 w-full rounded-full bg-muted", className),
+      ref,
+      role: "progressbar",
+      ...rest,
+      children: /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: "block h-full rounded-full bg-primary transition-[width]",
+          style: { width: `${clamped.toString()}%` }
+        }
+      )
+    }
+  );
+});
+AgentStepProgress.displayName = "AgentStepProgress";
+const AgentStepDetail = forwardRef(
+  ({ className, ...rest }, ref) => /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn("text-xs text-muted-foreground", className),
+      ref,
+      ...rest
+    }
+  )
+);
+AgentStepDetail.displayName = "AgentStepDetail";
+function useAgentStepStatus() {
+  return useContext(StepContext).status;
+}
+export {
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepProgress,
+  AgentStepTitle,
+  useAgentStepStatus
+};

package/dist/components/agent-activity/index.js

@@ -0,0 +1,18 @@
+import {
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepProgress,
+  AgentStepTitle,
+  useAgentStepStatus
+} from "./agent-activity";
+export {
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepProgress,
+  AgentStepTitle,
+  useAgentStepStatus
+};