@flikk/ui 1.0.0-beta.30 → 1.0.0-beta.31

package/CHANGELOG.md

@@ -5,6 +5,103 @@ All notable changes to Flikkui will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.0.0-beta.31] - 2026-07-31
+
+### Breaking Changes
+
+- **Icon library swapped: `@heroicons/react` → `@phosphor-icons/react`** — The required icon peer dependency is now Phosphor (`>=2.1.0`); Heroicons is no longer used anywhere in the library. Migration for consumers: `yarn remove @heroicons/react && yarn add @phosphor-icons/react`. **No component API changes** — every icon slot stays `ReactNode`, so icons you pass in (from any library) keep working; only the *built-in* glyphs (chevrons, dismiss ✕, check marks, status icons, etc.) changed shape from Heroicons to the visually close Phosphor equivalents at `regular` weight (`bold` where the old icons used `strokeWidth≥2`, replacing the old `24/solid` uses — one consistent weight voice). Rationale: the Figma design kit standardised on the Phosphor library, and this aligns code with design 1:1. Bundle note: Phosphor modules carry all six weights (~3–6× per icon, ~10–15 KB gzipped total for the ~25 built-in chrome icons); the generative icon vocabulary (`DEFAULT_ICONS`) keeps its library-agnostic names, so generative specs and `generative.schema.json` are unchanged.
+
+- **Color role `neutral` renamed to `mono`** — The gray/low-emphasis color role is now `mono` everywhere: the prop value (`color="mono"` on Button, Badge, Alert, Toast, KPI, Metric, Link, Spinner, CustomCursor), the `SemanticColor` / `ButtonColor` unions, and the CSS variables (`--color-mono-50…950`, `--color-mono`, `--color-mono-contrast`). The old name collided with Tailwind's own `neutral` color palette — mapping `neutral` in `tailwind.preset.cjs` shadowed Tailwind's real neutral so consumers couldn't reach it, and it blocked the goal of every role being usable as a shorthand (`bg-mono`, `bg-primary`, …) without stealing a Tailwind palette name. The preset now maps `mono` and no longer maps `neutral`, so `bg-neutral-*` / `bg-slate-*` / `bg-zinc-*` all resolve to Tailwind's real palettes again. There is **no `neutral` alias** at the prop level. Migration: replace `color="neutral"` → `color="mono"` and `var(--color-neutral-*)` → `var(--color-mono-*)`. Note: `--color-neutral-*` still resolves (to Tailwind's own neutral, a near-identical gray in the default theme) but no longer tracks the themed role — use `--color-mono-*` for the role.
+- **Charts — ~25 dead props removed from the public API** — `BarChart`, `StackedBarChart` and `AreaChart` each declared `extends StandardVisualProps` with no `Omit`. That interface is the *union* of every chart's visual props, so each chart inherited the others': they type-checked, appeared in the generative schema (an LLM could emit them), and were never read. `BaseChartProps` doesn't extend `HTMLAttributes` and the spread targets are plain `<div>`s, so they couldn't even be forwarded — `<BarChart curved />` reached a div as an unknown attribute. Each chart's props are now narrowed with `Omit` to what it implements, matching what `LineChart`/`ComboChart`/`HorizontalBarChart` already did. Removed:
+  - **`BarChart`** — `orientation`, `curved`, `curveType`, `showDots`, `fillOpacity`, `showStroke`, `stacked`, `dotRadius`, `cellRadius`, `strokeWidth`. For horizontal bars use the new `HorizontalBarChart` (`orientation` was a second, non-functional way to ask for the same thing).
+  - **`StackedBarChart`** — the same ten, plus `gap` (segment separation is a fixed hairline, not a tunable) and `radius` (its `@deprecated` → `barRadius` mapping was never implemented, so unlike `BarChart`/`AreaChart`/`LineChart` it never worked at all).
+  - **`AreaChart`** — `barRadius`, `cellRadius`, `gap`.
+  - **`ComboChart`** — `fillOpacity`, `showStroke`, `cellRadius`. Its `SeriesType` is `'bar' | 'line'` with no area member, so the area-fill props had nothing to apply to.
+  - **`ScatterPlot`** — `variant`. Scatter points are flat single-colour marks; there is no gradient/minimal treatment to select.
+  - **`cellRadius` is gone library-wide** — it was declared "for heatmap cells" and `Heatmap` never referenced it.
+  - **Axis family** — `color` and `fontSize` are removed from `BaseAxisProps` and `AxisTickProps` (so from `XAxis`, `YAxis`, `ValueXAxis`, `CategoryYAxis`), and `color` from `HorizontalGrid`. Axis lines and labels are themed via CSS variables (`stroke-[var(--color-border)]`); `color` was accepted, defaulted to `"currentColor"`, and ignored, and `fontSize` had no implementation anywhere. Restyle an axis with `className`, or change the token.
+- **Charts — `CHART_DEFAULTS` and the exported `*_DEFAULTS` objects lost their dead keys** — each `*_DEFAULTS` spread `...CHART_DEFAULTS`, so every chart published a default for every other chart's props. They now list only what their component reads. `CHART_DEFAULTS` also drops `cellRadius`, `orientation`, and `radius` (nothing consulted the last one — the deprecated `radius` *prop* still works on `BarChart`/`AreaChart`/`LineChart`, falling back to `barRadius`/`dotRadius`). These objects are publicly exported, so reads like `BAR_CHART_DEFAULTS.curved` no longer compile.
+- **`AvatarGroup` — `spacing` prop removed** — The group now renders one fixed overlap (the former `"normal"`, `-ml-3`). The three-value scale was a styling axis with an inverted, confusing vocabulary — `"tight"` meant *more* overlap (`-ml-5`) and `"loose"` meant *less* (`-ml-2`), the reverse of how the words read — and it duplicated what `className` already does better. The `AvatarGroupSpacing` type is no longer exported. Migration: drop the prop; to restore a custom overlap, pass it through `className` (e.g. `className="[&>*+*]:-ml-5"`). Internal call sites that used `"loose"`/`"tight"` (`CalendarEvent`, Popover stories) now use the single default, so their avatars sit fractionally differently.
+- **`Segmented` — default width is now fit-content** — The control previously stretched to fill its parent by default (its `flex` root is block-level, so it spanned full width regardless of the `block` prop, which was effectively a no-op). It now shrinks to fit its segments by default, and `block` genuinely opts into full width — matching the documented `block` contract and the iOS/shadcn segmented-control convention. Migration: add `block` to any `Segmented` that should span its container.
+- **Control heights and button padding retuned — every form control and Button changes size** — No API change, but the default values move, so consumer layouts shift. Heights (`--form-min-h-sm/md/lg`) go from **32/40/48px → 32/36/40px**, an even 4px step where the old ramp jumped 8px; button horizontal padding (`--button-px-sm/md/lg`) goes from **12/12/20px → 10/12/14px**, a consistent +2 ramp (`sm` and `md` previously collided at 12px and `lg` was an outlier). This lands the ramp on the same scale Untitled UI and shadcn use, with our `lg` (40px) at the industry-standard default height. Blast radius is wider than the token names suggest: `--button-min-h-*` and `--button-icon-size-*` both alias `--form-min-h-*`, so this resizes every form control, every Button, and every icon-only Button. Icon-only `sm` stays 32×32, clear of WCAG 2.2 SC 2.5.8's 24×24 floor. `--form-px-*` is deliberately untouched (12/14/16) — controls get shorter but keep their horizontal padding. To keep the old sizing, override the three height tokens in your own CSS.
+- **`--radius-base` default is now 8px** (was 12px) — Every derived radius in the library scales from this one token, so the default theme is uniformly less round. Set `--radius-base: 12px` to restore the previous look.
+- **Default chart series colors are no longer the semantic status palette** — Multi-series charts previously drew from `primary`/`warning`/`success`/`danger` at two lightness steps, which meant a categorical series could read as a *status* (a red series looking like an error). They now resolve from the new dedicated `--color-chart-1…5` palette. An explicit `config[key].color` is unaffected and still wins, including the bare-token shorthand (`"success"` → `var(--color-success)`). To restore the old look, set the colors explicitly in `config`, or override `--color-chart-1…5`.
+- **`--hero-card-radius` retired** — `HeroCard` had its own radius token at 3× base (vs `Card`'s 1.5×) on the belief that it needed a rounder look. It is a *presentation* of Card, not a distinct container, so it now shares `--card-radius`. Per-instance overrides still work via `className`. Migration: if you set `--hero-card-radius`, move that value onto the HeroCard's `className` or override `--card-radius`.
+
+### Added
+
+- **AI — `AgentStatus`, `Reasoning` and `SourceCitation`** (`@flikk/ui/ai`) — `AgentStatus` is the single agent-activity-row primitive and owns the reasoning disclosure through a `mode` prop, so one component covers the three ways a chat surfaces the same row: a live status line (`Thinking… 4s`), a collapsible "show your work", and each step inside it. `mode` and the lifecycle `status` stay **orthogonal** — a reasoning block is itself active or settled. The reasoning body is not always a step list: `steps={[{label,status,duration}]}` renders an `<ol>` of nested rows, while `children` render **raw**, so prose and markdown stay valid HTML. `Reasoning` is a thin preset over `mode="reasoning"` (`Reasoning.Step` aliases a status row). `SourceCitation` renders inline citation chips with preview popovers. Both share one `StatusIndicator` glyph, whose active spinner is a CSS `animate-spin` comet — motion only does enter/exit, since a single-value `rotate` target flattens to a static transform. New public hook **`useElapsedTime`** powers `startedAt`: the duration ticks on its own while active, takes one exact final reading on settle, then freezes, and the clock is only read inside an effect so there is no `Date.now()` in render to hydrate-mismatch.
+- **`HorizontalBarChart`** (`@flikk/ui/charts`) — Categories run down the left, values extend right. It shares `BarChart`'s data model and none of its axis wiring (the value/category axes are swapped), so it ships as its own component rather than an `orientation` flag. Use it when category names are long or numerous, or when the chart ranks items — a column chart cannot fit "United Kingdom" under its axis. Three new shared axis primitives came with it, because the axis layer had no horizontal support at all: `ValueXAxis` (a value axis rendered horizontally, Heckbert nice ticks), `CategoryYAxis` (a category axis rendered vertically), and `VerticalGrid`. 🔴 Note the axis family splits by what an axis **measures**, not which way it points — `XAxis` is a category axis despite being horizontal.
+- **`LollipopChart`** (`@flikk/ui/charts`) — Stem-and-dot marks with a staggered entrance, an always-on stem gradient + soft glow, hover/keyboard-focus/pinned-selection states (controlled and uncontrolled `selected`/`defaultSelected`), and a dot↔pill morph that animates a single `rx`-interpolating `motion.rect`. Uses the shared `XAxis` and `X_AXIS_MARGIN` so its baseline aligns with every other chart.
+- **`Button` — `iconStart` / `iconEnd`** — Button had no icon prop at all: `children` covers icons via the flex gap, which holds for hand-written code, but **a generative UI spec is JSON** — it can *name* an icon, never pass a React element — so an LLM literally could not put an icon on a button. This is the "one contract, two front doors" pattern §2 already established for collection `items` arrays and Card's flat `title`/`subtitle` slot-props. Button deliberately takes the **icon slots only** and *not* `contentStart`/`contentEnd`: an icon can be named, an arbitrary `ReactNode` cannot, so content slots would buy the generative path nothing. Composite stays the idiom and every existing call site is untouched — pass neither slot and `children` renders exactly as before. `theme.iconSizes` uses `[&>svg]:size-*` so a bare `<SearchIcon />` with no `className` still lands at the right size per button size (14/16/20 for sm/md/lg); a caller's own `className` still wins. The icon wrappers are `aria-hidden`, so the accessible name stays the label alone.
+- **`Tooltip` — controlled mode** — New `isOpen` / `defaultIsOpen` / `onOpenChange` props, plus a `recalcTrigger` escape hatch for triggers that move without firing a scroll or resize event (a dragged `Slider` thumb, for instance). `aria-describedby` is now merged with any existing value instead of clobbering it.
+- **`Modal` — `darkMode` prop** — Mirrors `Button`'s: applies the `dark` class to the modal container so a modal can render dark while the page is light.
+- **`InputAddress` — `showCountrySelector` / `showPostalCode`** — Lets either field be hidden for address formats that don't use them. Because the fields render as one merged perimeter, the corner radii are position-aware: the last visible field carries the bottom corners, and a lone bottom field spans the full row instead of splitting into two columns.
+- **`InputOTP` — `charset` prop (`numeric | alphanumeric`)** — Drives the sanitizer, `pattern` and `inputMode` together, so the on-screen keyboard, the accepted characters and the validation hint can't drift apart.
+- **`OfflineIndicator` — `action` prop** — Takes `{ label, onClick }` for a link-styled button (mirroring `Toast`'s `action`) or any `ReactNode`. Also gains full-bleed banner positions and reduced-motion fallback variants.
+- **`CommandPalette` — `onCommandSelect(id)`** — Fires alongside each command's own `onSelect`, so a single top-level callback can observe selection (this is what lets the generative registry bind commands through the standard action mechanism instead of synthesizing per-item callbacks).
+- **`Checkbox` / `Radio` — selection ripple** — A shared ripple animation on check, with reduced-motion coverage.
+- **Preset theme "Ember"** — A third shipped theme: orange primary, zinc neutrals, Plus Jakarta Sans, pill geometry and a 24px base radius. Registered in the Storybook theme switcher alongside Iris and Jade.
+- **Four new themeable token systems** — (1) **Per-container padding**: `--card-px/py`, `--modal-px/py`, `--drawer-px/py`, `--metric-content-p-sm/md/lg`, so a theme can make the brand-visible containers roomier or tighter without touching every padded element in the library. (2) **Three-tier radius ceilings**: `--surface-radius-cap-xs/sm/lg` wrap every content-bearing container's derived radius in a `min()`, so a theme chasing pill *controls* at a large `--radius-base` can't round a padded container past what its own padding can absorb (a curve-vs-padding collision that visually eats into header text). Controls stay uncapped — going fully pill there is correct. (3) **Per-role font sizes**: `--card-title-size`, `--modal-title-size`, `--drawer-title-size`, `--page-heading-title-size`, `--section-title-size`, `--metric-value-size-*`, `--kpi-value-size-*` — `--font-scale` can only resize the *whole* UI, so these let a theme resize a single role. Each defaults to a `--text-*` rung, so `--font-scale` still flows through. (4) **`--color-chart-1…5`**: a categorical chart palette decoupled from the semantic status colors. Sixteen components whose radius/padding/title-size had drifted into a bare uncapped `calc()` were wired onto these systems.
+- **Generative UI — curated set expanded from 32 to 66 components** — Forms were entirely uncurated before this (Input, Select, Combobox, Textarea, Checkbox, Switch, Slider, InputOTP, TimePicker, InputDate, InputCounter, InputTag), joined by 16 more Core/Data Display entries (Spinner, Skeleton, Link, Kbd, DotSeparator, Icon, Pagination, Message, MenuItem, Calendar, GanttChart, AspectRatio, ButtonGroup, Masonry, ScrollArea, HeroCard), `Tree` and `CommandPalette`, and the five remaining charts the manifest had deferred as "bespoke prop systems" (RadarChart, ScatterPlot, FunnelChart, ActivityRings, Heatmap). Notable: `Calendar`'s schema carries ISO strings with a `render:` wrapper coercing string→Date inbound and Date→ISO outbound; `CommandPalette` forces `isOpen: true` (it renders through the shared `Overlay`, so a spec node is always a full-screen modal) and supports only the flat `CommandItem[]` shape.
+- **`flikkui init` CLI** (separate `flikkui` package, `npx flikkui init`) — Implements the setup command the installation docs have long referenced. Detects framework, package manager and Tailwind; installs `@flikk/ui@beta` plus any missing required peers; injects the `styles.css` (and optional preset theme) import; and wires the Tailwind v4 dark variant. Zero runtime dependencies. Every project ends in exactly one explicit outcome — auto-wired (Next App/Pages Router, Vite), a named-framework manual snippet (CRA, Remix/RR7, Gatsby, Astro), a generic snippet, or a refusal with a stated reason (no `package.json`, React Native/Expo, React < 18). Theme imports are capability-checked against the installed package version. 128 unit tests + fixtures. Tracked in `packages/cli/CHANGELOG.md`.
+- **Figma design-kit generator (`yarn build:figma-tokens`)** — Design-ops tooling, deliberately **not** wired into `yarn build`. Parses `src/styles/theme.css` and emits `dist/figma-variables.json`: variables split across `Flikk/Primitives` (single mode) and `Flikk/Semantic` (Light/Dark), plus shadow effect styles derived from the `--elevation-surface-*` ladder. Mode-dependence is **derived, not curated** — a token is Semantic iff `.dark` overrides it *or it transitively references something that is*. Unknown value forms are a **hard failure (exit 1), never a guess**: the evaluator understands exactly four computed families, so adding a new one must break this build. See `docs/figma-component.md`.
+
+- **`Avatar` / `AvatarGroup` — `size` now accepts an exact pixel number** — `size={30}` sizes the circle to exactly 30px alongside the existing `"xs" | "sm" | "md" | "lg" | "xl"` rungs (`AvatarSize = AvatarSizeToken | number`; the new `AvatarSizeToken` type is exported). The type already admitted `number` but no implementation backed it: the theme's `Record<AvatarSize, string>` lookup returned `undefined` for a number, so `size={30}` type-checked and rendered an avatar with **no size class at all**. This is a fix as much as a feature. Note that `className="size-[30px]"` is not an equivalent workaround — the shipped `styles.css` only contains classes found in this library's own source and `tailwindcss` is an optional peer, so an arbitrary size utility resolves to nothing for consumers who don't run Tailwind themselves. Geometry is exact; decorations (glyph, status dot, verified badge, text gap) snap to the nearest rung (30 → `sm`). Token sizes render byte-for-byte identical to before. Implementation note: the circle now always carries the class `size-[var(--avatar-size)]` with the value supplied inline via the `--avatar-size` custom property, so anything targeting the old per-token `size-[var(--avatar-size-md)]` class in CSS will no longer match.
+- **Preset themes (`flikkui/themes/*`) + first theme "Iris"** — The library now ships swappable preset theme files: plain CSS-variable override files imported after `styles.css` (`import 'flikkui/themes/iris.css'`) — no config, no JS, no rebuild. The default look is unchanged and needs no import ("Neutral" is baked into `styles.css`). **Iris** restyles the whole library: Tailwind indigo primary ramp, slate-tinted neutrals and borders, Bricolage Grotesque type, and a rounder 16px base radius — with its own dark-mode values (theme files carry explicit `.dark` overrides inside `@layer theme` so dark mode composes correctly). Storybook gets a toolbar theme switcher (paintbrush icon) that live-swaps themes, including combined with dark mode. Custom themes are the same file format — see the Preset themes section in `docs/INSTALLATION.md`. A second preset, **Jade**, reshapes geometry and type as well as color: Tailwind emerald primary, warm stone neutrals (hueless in dark), Poppins on a 14px text scale, and pill-leaning controls (`--radius-base: 20px`, taller form/button heights with wider padding).
+- **Chip-tier padding tokens — themeable Badge / Pill / Tag / Kbd spacing** — The four small "chip" controls now read their padding from CSS variables instead of hardcoded Tailwind literals, so a theme can grow (or tighten) them alongside its buttons and inputs — the same reasoning as the per-component container padding and type-role tokens (a global knob can't make *only* badges roomier). New tokens: `--badge-px-sm/md`, `--badge-py-sm/md`, `--badge-pill-px-sm/md`; `--pill-px-sm/md/lg`, `--pill-py-sm/md/lg`; `--tag-px-sm/md`, `--tag-pl-md`, `--tag-py-sm/md`; `--kbd-px-sm/md`. Defaults are byte-for-byte identical to the previous literals, so the default theme is unchanged. Radius needs no new token — `--badge-radius` now derives from `--radius-base` (`calc(var(--radius-base) * 0.75)`, was a hardcoded `6px` that silently ignored the base, so a large `--radius-base` now rounds badges too), Kbd already derived, and Pill/Tag are intrinsic `rounded-full`. The `jade` and `ember` presets set these so their badges/pills/tags match their spacious geometry. Chip **gap** and Kbd **height** stay literal for now.
+- **`--font-scale` — one-knob type scale** — The base theme now defines the whole Tailwind `--text-xs…9xl` ramp as `calc(<tailwind default> * var(--font-scale))`. At the default `1` every utility is byte-for-byte Tailwind (`text-sm` = 14px); a theme or consumer sets a single factor (Jade: `0.875` → 14px-based text) and the entire ramp plus line-heights follow. Each step is `round()`ed to a whole pixel so scaled sizes stay clean (13px, not 13.125px). Text-only — spacing and px geometry tokens are unaffected.
+- **Control type-size tokens — themeable Button / Input / Segmented label size** — The control tier had every *box* axis tokenised (`--form-min-h-*`, `--form-px/py-*`, `--form-radius`) while its *type* stayed a hardcoded `text-sm` / `text-base` in each `.theme.ts`, so a theme could retune a control's height and padding but never its label. New tokens: `--form-text-size-sm/md/lg` with `--button-text-size-*` and `--segmented-text-size-*` aliasing it (mirroring how `--button-min-h-*` already aliases `--form-min-h-*`), each paired with a `--*-line-height-*` token. Consumed by Button, Segmented, and — via `formsBaseTheme.sizes.*.text` — Input, Select, Textarea, Combobox, DatePicker, DateRangePicker, TimePicker and RichTextEditor. Defaults are byte-for-byte identical to the literals they replaced (sm/md 14px/20px, lg 16px/24px) and each points at a `--text-*` rung, so `--font-scale` still flows through and the default theme is visually unchanged apart from the Segmented fix below. Note the ramp is deliberately **two rungs across three sizes** — sm and md share 14px and only lg steps to 16px; the small sizes are separated by box, not type.
+- **`InputOTP` — `size` prop (`sm | md | lg | xl`)** — `InputOTP` was the only text-entry form control without one, so an OTP could not be lined up with an adjacent `sm` or `lg` `Input`. `sm`/`md`/`lg` resolve to the same heights as the equivalent `Input` size; **`xl` is a new OTP-only rung** (48px in the default theme) for standalone verification screens where the code is the focus of the page. Defaults to `lg`. New tokens: `--otp-slot-size-sm/md/lg/xl`, `--otp-text-size-*` and `--otp-line-height-*`. `sm`/`md`/`lg` alias `--form-min-h-*` and `xl` derives from `--form-min-h-lg` (`calc(… * 1.2)`), so all four track a theme that retunes the form ramp — a hardcoded `xl` would have rendered *smaller than `lg`* under the `jade` (36/44/52) and `ember` (40/48/56) presets. The digit type ramp (16/16/18/20px) deliberately runs one rung hotter than form body text: an OTP numeral is a display glyph, not label text. The digit and the caret now scale with the slot; both were previously fixed at 18px and 20px regardless of size.
+- **`DotPattern` — `fadeDirection="center"`** — A new inverse-radial fade: dots stay solid toward the edges and fade out in the center (the opposite of `"radial"`), producing a vignette that keeps the content area behind the pattern clear. Tunable via `fadeSize` like the other directions. `DotPatternFadeDirection` is now `"radial" | "center" | "top" | "bottom" | "left" | "right"`.
+
+### Changed
+
+- **`InputOTP` slots are no longer responsive** — They previously stepped from `--form-min-h-md` to `--form-min-h-lg` at the `sm` breakpoint, which cannot coexist with an explicit `size` prop. The default `size="lg"` renders identically to the previous desktop output; narrow viewports now render at the same size rather than one rung smaller, and can opt into `size="sm"` — something that was impossible before. **Breaking for custom themes:** `InputOTPTheme.inputGroupStyle` (a single string) is replaced by `inputGroupSizes` and `charSizes`, both `Record<InputOTPSize, string>`. This only affects consumers passing a custom `theme` to `InputOTP`, and it is a compile-time type error, never a silent visual change.
+- **`--color-neutral` + `--color-neutral-contrast`** — neutral gains the same bare-default machinery as the semantic hues (900 in light, 200 in dark, auto-derived contrast text). `Button`'s filled-neutral now uses the token pair instead of hand-picked rungs + hardcoded `text-white`/`dark:` inversions (its light-mode per-color border classes were also removed — dead code, always beaten by the universal `border-black/25` edge; the live color-matched `dark:border-*` classes remain).
+- **Muted/placeholder/disabled text — one token source, no dark-mode bypasses** — `--color-text-placeholder` and `--color-text-muted` are now alpha-derived from `--color-text-primary` via `color-mix` (40% / 57% light, 40% / 50% dark), so they automatically track the theme's text color in both modes and on any surface. The ~30 hardcoded `dark:text-[var(--color-neutral-N)]` / `dark:placeholder:text-[var(--color-neutral-500)]` classes scattered across forms, CommandPalette, Calendar, Message, Pagination, Sidebar and the date/time pickers are removed — they bypassed the tokens and pinned dark text to neutral ramp rungs, which broke preset themes (an Iris dark placeholder rendered slate-blue; same disease as the Segmented fix below). Dark `--color-text-disabled` is now `neutral-600` (the value every picker was overriding to) instead of `neutral-400`. Visual deltas in the default theme are minor: dark helper text slightly dimmer, dark input icons slightly brighter (the two camps now share one muted value), dark disabled text dimmer.
+- **`Table` — smaller row-expand toggle** — The data-driven expand/collapse control was a full 32px outlined `Button` (form-control height), which read as oversized against row content. It's now a compact ~24px borderless ghost icon button (`variant="ghost"`, `size-6`), matching the conventional table expand affordance. Behavior and a11y labels are unchanged.
+- **`--color-success` default is now the `-600` step** (was `-500`) — matches danger/warning, and the auto-derived white `-contrast` text now passes WCAG AA on filled success surfaces (white on success-500 was ~2.7:1). Filled success Badges/Alerts/Toasts render a slightly darker teal; the full 50–950 ramp is unchanged.
+- **Dark glass gradients moved onto the surface ladder** — `--glass-gradient-outer/inner` dark values now reference `--surface-1/3/4` instead of the deprecated `--color-background-secondary/tertiary` aliases (visually near-identical), so the aliases' scheduled removal can't break `GlassEffect` in dark mode.
+- **`InputOTP` rebuilt around a single native input** — The control was N separate `Input` elements; it is now one invisible native input overlaying the visual slots. This fixes paste-with-separators truncation (`123-456` no longer loses characters) and caret drift, and is what makes the new `charset` prop able to drive sanitizer, `pattern` and `inputMode` from one place. Public API is otherwise unchanged.
+- **`Slider` — drag tooltip rebuilt on the shared `Tooltip`** — The bespoke SVG liquid-lens filter and custom drag bubble are replaced by the shared `Tooltip` (in its new controlled mode, with `recalcTrigger` so the tooltip follows the dragged thumb). The solid glass-look thumb styling moved into the theme file, so it's overridable like every other component's.
+- **`Link` — primary variant tints from the base `--color-primary` token** — Was pinned to the fixed `-600`/`-300` rungs, so it ignored whatever rung a theme parks the token at. Under every shipped preset this resolves to `primary-600` in light — identical to before — and one rung deeper in dark. The default Neutral theme, where primary aliases the mono ramp, renders a darker link than before. The animated underline is also offset 1px so it clears descenders.
+- **Form dropdowns — one option treatment across `Select` / `Combobox` / `Mention` / `InputTag`** — Combobox and InputTag rendered full-bleed square option rows while Select and Mention rendered inset rounded ones. All four already shared `formsBaseTheme.dropdownStyles`; the base simply withheld the two classes the treatment needs, so each call site re-decided it and two got it wrong. The `p-1` container inset and the option's `rounded-[var(--radius-base)]` now live in the shared base — which already assumed this treatment, since it sets `gap-0.5` between rows and draws an inset hairline ring on hover, neither of which reads correctly on a square full-bleed row.
+- **Press/hover feedback consolidated into one shared module** — `src/components/core/shared/interaction.animations.ts` (`createPressVariants` + press/release/hover transitions) is now the single source for Button, Pill and Badge; `Pill.animations.ts` is removed. Press-down is a fast ~80ms tween (feedback must be near-instant), release a stiff spring with slight overshoot. `Alert`, `DatePicker` and `SelectableCard` also drop their one-off transitions for the shared spring presets.
+
+### Removed
+
+- **Unused internal theme tokens** — deleted from `theme.css`; never consumed by any component nor documented: `--form-focus-ring-*`, `--form-outline-*`, `--glass-layer-*`, `--segmented-active-bg/-shadow`, `--chat-bubble-border-*`, all `--carousel-*`, the dead `--popover-*` set (shadow, border-width, backdrop-opacity, offsets, max-widths, paddings — `--popover-radius` stays), `--nav-item-min-h/-px/-py` (`--nav-item-radius` stays), the `--shadow-color-*` presets, and `--font-cursive` (its font was only ever loaded inside Storybook).
+
+### Fixed
+
+- **`PromptInput` — the invalid focus ring now uses the shared `--color-danger` token** — Its invalid state drew the `ring-4` glow from `--color-danger-500` in light mode, while every other form control (via `formsBaseTheme.states.invalid`) uses `--color-danger` (the 600 rung). Dark mode already agreed on both sides (`--color-danger-500` at 20%), so the two disagreed *only* in light — and the inset danger border on the very same line already used `--color-danger`, making the rule internally inconsistent as well. The light ring is now marginally deeper red and consistent with Input/Select/Textarea/OTP. No API change; the `dark:` value is untouched. Regression test added. This also lets the component share the Figma kit's single `Rings/Invalid` effect style instead of needing a one-off.
+- **`Segmented` — `size="lg"` now steps its label up to 16px** — Segmented's box tokens are straight aliases of the shared form ramp (`--segmented-min-h-*` → `--form-min-h-*`), but its type was pinned to `text-sm` at **all three** sizes, so `lg` grew its height and padding while the label stayed at 14px — out of step with Button and Input, which both step 14px → 16px at `lg`. `lg` labels now render at 16px/24px like every other large control. **The control's height is unchanged** (still 40px; the taller line-height fits inside the existing `min-h`), so this is a type fix, not a layout shift. `sm` and `md` are untouched. The Figma design kit's `Segmented item` `lg` variants were re-pushed to match. Regression test added.
+- **Dead props — five public props were accepted and typed but never read** — each silently did nothing when passed. All five are now implemented, with regression tests:
+  - **`ScatterPlot` — `legend`** — inherited from `StandardChartDisplayProps` but never destructured, so the legend was hardcoded to always-render-at-bottom and every value (`"top"`, `"bottom"`, `"none"`) did nothing. It now honours all three, resolved through the same shared `resolveLegendPosition` every other chart uses, satisfying the documented contract that ScatterPlot renders the shared `ChartLegend` from `legend`. **Behavior change:** an omitted `legend` now resolves to `"bottom"` for multi-category data and `"none"` for single-category — so a single-category scatter no longer shows a one-item legend by default. Pass `legend="bottom"` to keep it.
+  - **`Modal` — `darkMode`** — documented as applying the `dark` class to the container, but never destructured, so it fell through `...props` into `Overlay` (which doesn't declare it either) and dead-ended. It now applies `dark` to the modal container, matching the existing `Input`/`BarChart`/`LollipopChart` implementations of the same prop.
+  - **`Sidebar.Toggle` — `expandIcon` / `collapseIcon`** — destructured but unused; the toggle always rendered its hardcoded chevron. Both are now wired, falling back to the default chevron when omitted. Semantics are **action-based**, matching the button's own aria-label: `expandIcon` shows while the sidebar is *collapsed* (clicking expands), `collapseIcon` while *expanded*. A custom icon renders as-is — the default chevron's 180° flip is only applied to the chevron itself. The JSDoc, which described the opposite (state-based) meaning, was corrected.
+  - **`InputAddress` — `showCountrySelector` / `showPostalCode`** — typed but never read (the component has no rest spread, so they dead-ended entirely). Both now hide their field. Because the fields render as one merged perimeter, the radii are position-aware: the last visible field carries the bottom corners, and a lone bottom field spans the full row.
+  - **`ScatterPlot` — `gridClassName`** — destructured but unused, while `svgClassName`/`dotClassName`/`axisClassName` all worked. It now styles the grid lines (plumbed through the shared `YAxis`, which draws ScatterPlot's grid), matching `AreaChart`'s existing `gridClassName`.
+- **`tailwind.preset.cjs` — `bg-primary` now matches component colors** — Each semantic color's `DEFAULT` was pinned to a fixed rung (`primary-600`, `success-500`, …), so consumer shorthands like `bg-primary` resolved to a different color than the library's own components (which paint the bare `--color-primary` base — `-900` in the monochrome base theme, `-600` in a colored theme). DEFAULTs now point at the bare `var(--color-*)` base, so `bg-primary` equals what components render and follows the active theme and dark mode. Also pruned deprecated `background-quaternary/quinary` maps, added the surface ladder + `border-secondary`/`border-hover`, and corrected the `--form-radius`/`--button-radius` token names. The `@flikk/ui/theme.css` v4 entry's broken `dist` relative import and a stale `--form-rounded` token in `shadcn-compat.css` were fixed too.
+- **Dark-mode active scrollbar thumb color** — `--ui-scrollbar-thumb-active` used invalid mixed rgb syntax (`rgb(75 85 99, 0.75)`), so the declaration failed at computed-value time and the active thumb lost its intended dark tint. Now `rgb(75 85 99 / 0.75)`.
+- **`Badge` — `iconStart` no longer hugs the edge** — the icon wrapper applied a `-ml-1` optical tuck unconditionally, which cancelled the regular badge's 4px padding and left the icon ~1px from the border. The tuck is now pill-only (pills have the extra `pillSizes` padding to absorb it), mirroring the avatar slot's existing pill/non-pill conditional. Badge width with text-only content is unchanged.
+- **`PromptInput` — model-menu icon stacked above the label** — The model selector passed its icon inside `Dropdown.Item` children, where MenuItem's block-level `truncate` label span (plus Tailwind preflight's `svg { display: block }`) broke it onto its own line. The icon now goes through the proper `startContent` slot and renders inline with the label.
+- **`Dropdown` — menu gets a `max-w-[20rem]` cap** — A long item label stretched the menu unboundedly (MenuItem's `truncate` could never engage without a width bound). Long labels now ellipsize at 320px.
+- **`Dropdown.Trigger` — no longer overrides a `Button` trigger's styling** — The trigger injected a translucent `surface-hover` tint (on hover, and while the menu is open) onto whatever it wrapped. For a *filled* `Button` — which hovers via a `brightness` filter, not a `hover:bg-*` — that tint had nothing to override and instead replaced the solid fill, so a filled trigger (e.g. the chevron half of a filled split button) went see-through/dark on hover and mismatched its sibling. The tint is now skipped for `Button` children (Buttons are self-styled and bring their own hover/active/variant states); plain/custom trigger elements still get it. Fixes the `ButtonGroup` "Split Button" filled example.
+- **`Calendar` — consistent selected & hover styling across single/range modes** — Range start/end days had their own fill/text rules and no hover override, so hovering an endpoint fell through to the generic neutral day-hover (a muddy grey with poor contrast) and looked different from a single-selected day. Endpoints now route through `data-selected`, inheriting the exact same fill, text, top-border, and hover as a single-selected cell (one source of truth for "a selected day"). In-range (between) days no longer carry a bespoke hover either — they use the same base day-hover as normal days, so a hovered cell looks identical whether or not it sits inside a range.
+- **`Table` — jerk at the end of row collapse** — Expanding rows use a height-animating container inside a full-width colspan `<td>`. That cell was picking up ~20px of vertical padding from the table's `[&_td]:py-*` descendant rule (which out-specifies the cell's own `p-0`), so the cell held a ~21px residual height after the animator had already collapsed to 0 — then snapped to 0 when the row unmounted, jerking the rows below. The expanded cell now forces `!p-0` so it tracks the animator down to ~0 (mirrors Accordion, where the animating container carries no padding and the inner content owns it). Padding for expanded content is owned by `expandedRowRender`, as before.
+- **`Segmented` — dark-mode background no longer collides with consumer utilities** — The theme hardcoded raw Tailwind classes (`bg-neutral-100 dark:bg-neutral-900` on the track, `dark:bg-neutral-800` on the sliding indicator). These emit global class names that a consumer's own `bg-neutral-*` utility could override by source order, permanently pinning the control's background to one tone regardless of the `.dark` class. The track now paints from `--color-surface-sunken` and the indicator from `--color-surface` (theme-aware CSS variables, no `dark:` variants), so it follows the theme correctly and can't collide. Visually unchanged. (PER-292)
+- **`Avatar` — status dot stranded outside the circle** — The dot was corner-anchored (`left-0 bottom-0`), but an avatar is a *circle*: its bounding-box corner sits ~41% further from the centre than the edge does, so the dot floated off the arc. It now centres on the circle's 45° point via one proportional rule (`left-[14.6%] bottom-[14.6%]` plus half-translates), which holds at every size including the new arbitrary numeric ones. Three further fixes fell out of the same pass: **(1)** the ring was a flat 2px at every rung, making it proportionally 3.3× heavier on `xs` than `xl` — dot and ring now ramp together, holding the badge's total footprint near 30% of the avatar across the ladder (was 42%→25%); **(2)** the `offline` dot moved off `--color-text-muted` — the text tokens are `color-mix` alpha derivations, so as a *fill* the dot went translucent and the photo showed through; it now uses `--color-mono-500`, the only rung clearing WCAG 1.4.11's 3:1 against its ring in **both** modes; **(3)** `isolate` added to the circle, since `relative` with `z-index: auto` creates no stacking context, so the contents' `z-10` escaped and painted over the sibling status dot.
+- **`Select` — `searchPlaceholder` was ignored** — The prop was declared and documented, but the search input hardcoded `"Search..."`, trapping a user-facing string (every built-in visible string must be overridable). It's now threaded through the Select context to the input. The default was inconsistent too — `SelectProps` documented `"Search..."` while the implementation defaulted to `"Search options..."`; both are `"Search..."` now. This is also what `InputAddress`'s new `showCountrySelector` depended on, since it was already passing `searchPlaceholder` to the country Select.
+- **`Message` — system bubble radius bypassed the surface cap** — It derived from a bare `calc()` on `--radius-base`. It's a tiny, tight-padding chip, so it now takes `--surface-radius-cap-xs`; without the cap, a theme chasing pill controls at a large base rounded the corners past what the bubble's own padding could absorb.
+- **`Metric` — `label` is now optional** — It was required with no reason to be; a metric can legitimately render a value alone. The generative schema is regenerated to match.
+- **Generative — `registry.tsx` was missing `"use client"`** — It renders JSX with a real event handler (Calendar's `render` wraps the underlying `onChange`) but carried no directive, a genuine gap under the RSC deep-import rule. Separately, the `audit-use-client` script's browser-global heuristic was flagging `schema.generated.ts` on the literal word "navigator" inside an unrelated description string; that file is pure JSON-shaped data and is now excluded from the audit rather than given a directive the generator would strip on the next run.
+- **Generative schema was stale for `InputOTP`** — The new `size` prop landed without a `yarn build:generative` regen, so the committed schema still advertised OTP without it and an LLM had no way to emit a sized OTP. Regenerated and committed as part of this release.
+- **`Calendar` — focus rings clipped by the height animation** — The days grid is inside a container animating height with `overflow: hidden`, which cropped the focus ring on edge cells. The grid is now padded so the ring clears. An unused `navButtonStyle` theme key was also removed.
+
 ## [1.0.0-beta.30] - 2026-07-04
 
 ### Breaking Changes

package/dist/components/ai/AgentStatus/AgentStatus.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { AgentStatusProps } from "./AgentStatus.types";
+export declare const AgentStatus: React.ForwardRefExoticComponent<AgentStatusProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ai/AgentStatus/AgentStatus.js

@@ -0,0 +1,144 @@
+"use client";
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import React__default, { useMemo, useId, useState, useEffect } from 'react';
+import { CaretRight } from '@phosphor-icons/react';
+import { useReducedMotion, motion, AnimatePresence } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { useElapsedTime } from '../../../hooks/useElapsedTime.js';
+import { Shimmer } from '../../effects/Shimmer/Shimmer.js';
+import { AIStatusIndicator } from '../shared/StatusIndicator.js';
+import { createTriggerIconVariants, accordionAnimations, accordionContentAnimations } from '../../core/Accordion/Accordion.animations.js';
+import { agentStatusTheme } from './AgentStatus.theme.js';
+
+const formatDuration = (duration) => {
+    const safe = Math.max(0, duration);
+    // Round once, up front. Rounding the minutes and seconds halves independently
+    // lets a value like 119.7 render as "1m 60s".
+    const rounded = safe < 60 ? Math.round(safe * 10) / 10 : Math.round(safe);
+    if (rounded < 60) {
+        return `${rounded.toFixed(Number.isInteger(rounded) ? 0 : 1)}s`;
+    }
+    return `${Math.floor(rounded / 60)}m ${rounded % 60}s`;
+};
+// The indicator + shimmering label + duration, without a root element. Both the
+// standalone status row (a <div role="status">) and the reasoning summary (a
+// phrasing <span> inside the trigger <button>) render this, so the visual row is
+// identical while each host picks a content-model-valid wrapper — a <div> may not
+// nest inside a <button>.
+const StatusRowInner = ({ theme, status, label, isActive, indicator, icon, wrap, activeSuffix, shimmerDuration, shimmerSpread, shimmerColor, shimmerHighlightColor, shownDuration, }) => {
+    const labelClass = cn(theme.labelStyle, wrap ? "" : "truncate");
+    return (jsxs(Fragment, { children: [indicator && (jsx("span", { className: theme.iconStyle, "aria-hidden": "true", children: icon !== null && icon !== void 0 ? icon : (jsx(AIStatusIndicator, { state: status, className: theme.indicatorStyles[status] })) })), isActive ? (jsx(Shimmer, { active: true, duration: shimmerDuration, spread: shimmerSpread, color: shimmerColor, highlightColor: shimmerHighlightColor, className: labelClass, children: jsxs(Fragment, { children: [label, activeSuffix] }) })) : (jsx("span", { className: labelClass, children: label })), shownDuration !== undefined && (
+            // aria-hidden: inside an aria-atomic live region a ticking timer would
+            // re-announce the whole label on every tick.
+            jsx("span", { className: theme.durationStyle, "aria-hidden": "true", children: formatDuration(shownDuration) }))] }));
+};
+const AgentStatus = React__default.forwardRef(({ mode = "status", status = "active", label, duration, startedAt, icon, indicator, wrap = false, activeSuffix = "…", shimmerDuration = 2, shimmerSpread = 16, shimmerColor = "color-mix(in oklab, var(--color-text-muted) 75%, transparent)", shimmerHighlightColor = "var(--color-text-primary)", live = "polite", steps, children, open, defaultOpen = false, onOpenChange, divider = true, className, theme: themeOverrides, ...rest }, ref) => {
+    // All hooks run unconditionally, before the mode branch.
+    const theme = useMemo(() => ({
+        ...agentStatusTheme,
+        ...themeOverrides,
+        stateStyles: {
+            ...agentStatusTheme.stateStyles,
+            ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.stateStyles,
+        },
+        indicatorStyles: {
+            ...agentStatusTheme.indicatorStyles,
+            ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.indicatorStyles,
+        },
+    }), [themeOverrides]);
+    const isReasoning = mode === "reasoning";
+    const isActive = status === "active";
+    // Ticks while active, freezes on settle. An explicit `duration` wins outright, so
+    // don't read the clock at all in that case — passing `startedAt` anyway would leave
+    // an interval re-rendering this row 10x/second only to discard every reading.
+    const ticked = useElapsedTime(duration === undefined ? startedAt : undefined, {
+        active: isActive,
+    });
+    const shownDuration = duration !== null && duration !== void 0 ? duration : ticked;
+    // A status row always carries an indicator; a reasoning summary drops it once
+    // settled, because the chevron carries the affordance from there. Either default
+    // yields to an explicit `indicator`, and a custom `icon` opts back in — you only
+    // pass an icon in order to see it.
+    const showIndicator = indicator !== null && indicator !== void 0 ? indicator : (isReasoning ? isActive || icon !== undefined : true);
+    const reactId = useId();
+    const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+    const shouldReduceMotion = useReducedMotion();
+    const isControlled = open !== undefined;
+    const hasOnOpenChange = onOpenChange !== undefined;
+    const hasSteps = steps !== undefined;
+    const hasChildren = children !== undefined;
+    // Dev warnings belong in an effect, not the render body: `startedAt` re-renders this
+    // component ten times a second, and a render-body warning reprints on every tick.
+    // The deps are booleans on purpose — depending on `steps`/`children`/`onOpenChange`
+    // directly would re-fire on every parent render and bring the flood back.
+    useEffect(() => {
+        if (process.env.NODE_ENV === "production" || !isReasoning)
+            return;
+        /* eslint-disable no-console */
+        if (isControlled && defaultOpen) {
+            console.warn("[AgentStatus]: both `open` and `defaultOpen` were provided — `open` (controlled) wins.");
+        }
+        if (isControlled && !hasOnOpenChange) {
+            console.warn("[AgentStatus]: `open` was provided without `onOpenChange`, so the reasoning block can never be toggled. Pass `defaultOpen` for uncontrolled usage.");
+        }
+        if (hasSteps && hasChildren) {
+            console.warn("[AgentStatus]: both `steps` and `children` were provided — `steps` takes precedence.");
+        }
+        /* eslint-enable no-console */
+    }, [
+        isReasoning,
+        isControlled,
+        defaultOpen,
+        hasOnOpenChange,
+        hasSteps,
+        hasChildren,
+    ]);
+    // Shimmer + theme config shared with the nested rows a reasoning block renders.
+    // Memoized so a ticking summary duration doesn't churn the step list's props.
+    const sharedRowProps = useMemo(() => ({
+        activeSuffix,
+        shimmerDuration,
+        shimmerSpread,
+        shimmerColor,
+        shimmerHighlightColor,
+        theme: themeOverrides,
+    }), [
+        activeSuffix,
+        shimmerDuration,
+        shimmerSpread,
+        shimmerColor,
+        shimmerHighlightColor,
+        themeOverrides,
+    ]);
+    // steps => structured list of rows; otherwise raw children (prose / markdown
+    // / mixed). Memoized so it survives the 100ms duration ticks while active —
+    // only the summary row's duration should re-render, not the whole step list.
+    const reasoningBody = useMemo(() => {
+        if (steps) {
+            return (jsx("ol", { className: theme.stepsStyle, children: steps.map((step, index) => {
+                    var _a, _b;
+                    return (jsx("li", { className: theme.stepItemStyle, children: jsx(AgentStatus, { mode: "status", status: (_a = step.status) !== null && _a !== void 0 ? _a : "complete", label: step.label, duration: step.duration, wrap: true, live: "off", ...sharedRowProps }) }, (_b = step.id) !== null && _b !== void 0 ? _b : index));
+                }) }));
+        }
+        return children !== undefined ? (jsx("div", { className: theme.proseStyle, children: children })) : null;
+    }, [steps, children, theme, sharedRowProps]);
+    // ===== STATUS MODE: a single activity row =====
+    if (!isReasoning) {
+        return (jsx("div", { ref: ref, role: "status", "aria-live": live, "aria-atomic": "true", "data-state": status, className: cn(theme.baseStyle, theme.stateStyles[status], className), ...rest, children: jsx(StatusRowInner, { theme: theme, status: status, label: label, isActive: isActive, indicator: showIndicator, icon: icon, wrap: wrap, activeSuffix: activeSuffix, shimmerDuration: shimmerDuration, shimmerSpread: shimmerSpread, shimmerColor: shimmerColor, shimmerHighlightColor: shimmerHighlightColor, shownDuration: shownDuration }) }));
+    }
+    // ===== REASONING MODE: a collapsible disclosure of the same rows =====
+    const contentId = `${reactId}-reasoning`;
+    const triggerId = `${contentId}-trigger`;
+    const isOpen = isControlled ? open : uncontrolledOpen;
+    const instantTransition = shouldReduceMotion ? { duration: 0 } : undefined;
+    const toggle = () => {
+        const next = !isOpen;
+        if (!isControlled)
+            setUncontrolledOpen(next);
+        onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange(next);
+    };
+    return (jsxs("div", { ref: ref, "data-state": isOpen ? "open" : "closed", className: cn(theme.reasoningRootStyle, className), ...rest, children: [jsx("button", { id: triggerId, type: "button", className: theme.triggerStyle, "aria-expanded": isOpen, "aria-controls": isOpen ? contentId : undefined, onClick: toggle, children: jsxs("span", { className: theme.triggerContentStyle, children: [jsx("span", { className: cn(theme.baseStyle, theme.stateStyles[status]), "aria-live": live, "aria-atomic": "true", children: jsx(StatusRowInner, { theme: theme, status: status, label: label, isActive: isActive, indicator: showIndicator, icon: icon, wrap: false, activeSuffix: activeSuffix, shimmerDuration: shimmerDuration, shimmerSpread: shimmerSpread, shimmerColor: shimmerColor, shimmerHighlightColor: shimmerHighlightColor, shownDuration: shownDuration }) }), jsx(motion.span, { className: theme.chevronStyle, initial: false, animate: isOpen ? "open" : "closed", variants: createTriggerIconVariants(90), transition: instantTransition, "aria-hidden": "true", children: jsx(CaretRight, { className: "size-full" }) })] }) }), divider && jsx("div", { className: theme.dividerStyle, "aria-hidden": "true" }), jsx(AnimatePresence, { initial: false, children: isOpen && (jsx(motion.div, { id: contentId, role: "region", "aria-labelledby": triggerId, className: theme.contentStyle, "data-state": "open", initial: "collapsed", animate: "open", exit: "collapsed", variants: accordionAnimations, transition: instantTransition, children: jsx(motion.div, { className: theme.contentInnerStyle, initial: "collapsed", animate: "open", exit: "collapsed", variants: accordionContentAnimations, transition: instantTransition, children: reasoningBody }) })) })] }));
+});
+AgentStatus.displayName = "AgentStatus";
+
+export { AgentStatus };

package/dist/components/ai/AgentStatus/AgentStatus.theme.d.ts

@@ -0,0 +1,2 @@
+import type { AgentStatusTheme } from "./AgentStatus.types";
+export declare const agentStatusTheme: AgentStatusTheme;

package/dist/components/ai/AgentStatus/AgentStatus.theme.js

@@ -0,0 +1,37 @@
+const agentStatusTheme = {
+    baseStyle: "inline-flex min-w-0 items-center gap-2 text-sm",
+    iconStyle: "flex size-4 shrink-0 items-center justify-center",
+    // truncate is applied at the call site (only when `wrap` is off) so steps can wrap.
+    labelStyle: "min-w-0 font-medium",
+    durationStyle: "shrink-0 text-sm tabular-nums text-[var(--color-text-muted)]",
+    stateStyles: {
+        idle: "text-[var(--color-text-muted)]",
+        active: "text-[var(--color-text-secondary)]",
+        complete: "text-[var(--color-text-muted)]",
+        pending: "text-[var(--color-text-placeholder)]",
+        error: "text-[var(--color-danger)]",
+    },
+    indicatorStyles: {
+        idle: "text-[var(--color-text-muted)]",
+        active: "text-[var(--color-primary)]",
+        complete: "text-[var(--color-success)]",
+        pending: "text-[var(--color-text-placeholder)]",
+        error: "text-[var(--color-danger)]",
+    },
+    // --- reasoning mode: borderless inline disclosure ---
+    reasoningRootStyle: "w-full min-w-0",
+    triggerStyle: "flex w-full items-center py-2 text-left transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--color-primary)]",
+    triggerContentStyle: "inline-flex min-w-0 items-center gap-1.5",
+    chevronStyle: "inline-flex size-3.5 shrink-0 items-center justify-center text-[var(--color-text-muted)]",
+    dividerStyle: "h-px w-full bg-[var(--color-border)]",
+    contentStyle: "w-full min-w-0 overflow-hidden",
+    contentInnerStyle: "w-full min-w-0 pt-3",
+    stepsStyle: "space-y-2",
+    stepItemStyle: "min-w-0",
+    // Raw children (prose / markdown / mixed). flex-col so any child — a <p>, a
+    // MarkdownRenderer, or an inline-flex AgentStatus row — stacks vertically; the
+    // gap lives on the container, so it survives child margin resets.
+    proseStyle: "flex flex-col gap-3 text-sm leading-relaxed text-[var(--color-text-secondary)] [&_p]:m-0",
+};
+
+export { agentStatusTheme };

package/dist/components/ai/AgentStatus/AgentStatus.types.d.ts

@@ -0,0 +1,116 @@
+import React from "react";
+export type AgentStatusState = "idle" | "active" | "complete" | "pending" | "error";
+/**
+ * Presentation mode. `status` is a single activity row; `reasoning` turns that
+ * same row into a collapsible disclosure whose body holds steps and/or prose.
+ * The two axes are independent — a `reasoning` block is itself `active`,
+ * `complete`, etc.
+ */
+export type AgentStatusMode = "status" | "reasoning";
+/** A single reasoning step — a serializable AgentStatus row. */
+export interface AgentStatusStepData {
+    id?: React.Key;
+    label: React.ReactNode;
+    status?: AgentStatusState;
+    /** Elapsed or final step duration in seconds. */
+    duration?: number;
+}
+export interface AgentStatusTheme {
+    baseStyle: string;
+    iconStyle: string;
+    labelStyle: string;
+    durationStyle: string;
+    stateStyles: Record<AgentStatusState, string>;
+    indicatorStyles: Record<AgentStatusState, string>;
+    reasoningRootStyle: string;
+    triggerStyle: string;
+    triggerContentStyle: string;
+    chevronStyle: string;
+    dividerStyle: string;
+    contentStyle: string;
+    contentInnerStyle: string;
+    stepsStyle: string;
+    stepItemStyle: string;
+    proseStyle: string;
+}
+export interface AgentStatusThemeOverrides extends Omit<Partial<AgentStatusTheme>, "stateStyles" | "indicatorStyles"> {
+    stateStyles?: Partial<AgentStatusTheme["stateStyles"]>;
+    indicatorStyles?: Partial<AgentStatusTheme["indicatorStyles"]>;
+}
+export interface AgentStatusProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Single status row (default) or a collapsible reasoning disclosure. @default "status" */
+    mode?: AgentStatusMode;
+    /** Current execution state. Active labels shimmer; settled labels are static. */
+    status?: AgentStatusState;
+    /** Human-readable activity, for example "Thinking" or "Searching sources". */
+    label: React.ReactNode;
+    /**
+     * Elapsed or final duration in seconds. Takes precedence over `startedAt`, so
+     * pass it when the duration is authoritative (for example, returned by the server).
+     */
+    duration?: number;
+    /**
+     * Epoch milliseconds the activity began. The duration then ticks on its own
+     * while `status` is `"active"` and freezes the moment it settles — no timer
+     * wiring in the consumer. Ignored when `duration` is supplied.
+     */
+    startedAt?: number;
+    /** Optional icon. When omitted, the animated semantic indicator is rendered. */
+    icon?: React.ReactNode;
+    /**
+     * Show the leading status indicator (or custom `icon`). Set `false` for an
+     * icon-less, text-only row — the label then sits flush left.
+     *
+     * Defaults differ by mode: a `status` row always shows one, while a `reasoning`
+     * summary shows one only while active (the chevron carries the affordance once
+     * settled) — unless an `icon` is supplied, which opts back in. Pass explicitly
+     * to override either default.
+     * @default true in `status` mode; active-only in `reasoning` mode
+     */
+    indicator?: boolean;
+    /**
+     * Let the label wrap onto multiple lines instead of truncating. Steps render
+     * with this on; the standalone/summary row truncates by default.
+     * @default false
+     */
+    wrap?: boolean;
+    /** Text appended while active. @default "…" */
+    activeSuffix?: React.ReactNode;
+    /** Active shimmer cycle duration in seconds. @default 2 */
+    shimmerDuration?: number;
+    /** Width of the active shimmer highlight band. @default 16 */
+    shimmerSpread?: number;
+    /** Base color for the active shimmer text. */
+    shimmerColor?: string;
+    /** Highlight color for the active shimmer sweep. */
+    shimmerHighlightColor?: string;
+    /**
+     * Accessible announcement behavior. `"polite"` waits for a pause rather than
+     * interrupting, which is what a background activity warrants.
+     * @default "polite"
+     */
+    live?: "off" | "polite" | "assertive";
+    /**
+     * Structured reasoning steps. Rendered as a list of AgentStatus rows.
+     * Ignored unless `mode="reasoning"`.
+     */
+    steps?: AgentStatusStepData[];
+    /**
+     * Free-form reasoning body — prose, a `<MarkdownRenderer>`, or a mix of prose
+     * and `<AgentStatus>` rows. Rendered raw (not wrapped in a list), so paragraphs
+     * are valid. `steps` takes precedence when both are supplied.
+     */
+    children?: React.ReactNode;
+    /** Controlled expanded state (reasoning mode). */
+    open?: boolean;
+    /** Initial expanded state for uncontrolled reasoning usage. @default false */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Render the full-width hairline under the reasoning trigger.
+     * @default true
+     */
+    divider?: boolean;
+    className?: string;
+    theme?: AgentStatusThemeOverrides;
+}

package/dist/components/ai/AgentStatus/index.d.ts

@@ -0,0 +1,3 @@
+export { AgentStatus } from "./AgentStatus";
+export { agentStatusTheme } from "./AgentStatus.theme";
+export type { AgentStatusProps, AgentStatusState, AgentStatusMode, AgentStatusStepData, AgentStatusTheme, AgentStatusThemeOverrides, } from "./AgentStatus.types";

package/dist/components/ai/CodeBlock/CodeBlock.js

@@ -3,7 +3,7 @@ import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import React__default, { useState, useMemo, useCallback, useRef } from 'react';
 import { Prism } from 'react-syntax-highlighter';
 import { oneDark, oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism';
-import { DocumentTextIcon, DocumentCheckIcon, DocumentDuplicateIcon } from '@heroicons/react/24/outline';
+import { FileText, ListChecks, Copy } from '@phosphor-icons/react';
 import { codeBlockTheme } from './CodeBlock.theme.js';
 import { LanguageIcon } from './LanguageIcon.js';
 import { cn } from '../../../utils/cn.js';
@@ -177,7 +177,7 @@ const CodeBlock = React__default.forwardRef(({ children, language = "text", show
     // `lineProps` starts counting from line 1 every time, regardless of
     // `showLineNumbers`.
     lineCounterRef.current = 0;
-    return (jsxs("div", { ref: ref, className: cn(mergedTheme.baseStyle, className), ...props, children: [showHeader && (jsxs("div", { className: mergedTheme.header, children: [jsx("div", { className: mergedTheme.headerLeft, children: filename && (jsxs(Fragment, { children: [jsx(DocumentTextIcon, { className: "size-4 text-[var(--color-text-muted)]" }), jsx("span", { className: mergedTheme.filename, children: filename })] })) }), jsxs("div", { className: mergedTheme.headerRight, children: [showLanguage && (jsxs("div", { className: "flex items-center gap-2", children: [jsx(LanguageIcon, { language: language, className: "size-4" }), jsx("span", { className: mergedTheme.languageLabel, children: displayLanguage })] })), copyable && (jsx("button", { onClick: handleCopy, className: cn(mergedTheme.copyButton, copied && mergedTheme.copySuccess), "aria-label": copied ? "Copied!" : "Copy code", title: copied ? "Copied!" : "Copy code", children: copied ? (jsx(DocumentCheckIcon, { className: "size-4" })) : (jsx(DocumentDuplicateIcon, { className: "size-4" })) }))] })] })), jsx("div", { className: mergedTheme.codeWrapper, style: {
+    return (jsxs("div", { ref: ref, className: cn(mergedTheme.baseStyle, className), ...props, children: [showHeader && (jsxs("div", { className: mergedTheme.header, children: [jsx("div", { className: mergedTheme.headerLeft, children: filename && (jsxs(Fragment, { children: [jsx(FileText, { className: "size-4 text-[var(--color-text-muted)]" }), jsx("span", { className: mergedTheme.filename, children: filename })] })) }), jsxs("div", { className: mergedTheme.headerRight, children: [showLanguage && (jsxs("div", { className: "flex items-center gap-2", children: [jsx(LanguageIcon, { language: language, className: "size-4" }), jsx("span", { className: mergedTheme.languageLabel, children: displayLanguage })] })), copyable && (jsx("button", { onClick: handleCopy, className: cn(mergedTheme.copyButton, copied && mergedTheme.copySuccess), "aria-label": copied ? "Copied!" : "Copy code", title: copied ? "Copied!" : "Copy code", children: copied ? (jsx(ListChecks, { className: "size-4" })) : (jsx(Copy, { className: "size-4" })) }))] })] })), jsx("div", { className: mergedTheme.codeWrapper, style: {
                     maxHeight: maxHeight,
                     overflowY: maxHeight ? "auto" : undefined,
                 }, children: jsx(Prism, { language: language, style: syntaxTheme === "dark" ? oneDark : oneLight, showLineNumbers: showLineNumbers, wrapLines: true, wrapLongLines: wrapLines, lineProps: lineProps, lineNumberStyle: {
@@ -192,7 +192,7 @@ const CodeBlock = React__default.forwardRef(({ children, language = "text", show
                         fontSize: "0.875rem",
                         lineHeight: "1.5",
                         background: "transparent",
-                    }, children: code }) }), !showHeader && copyable && (jsx("button", { onClick: handleCopy, className: cn("absolute top-2 right-2", mergedTheme.copyButton, copied && mergedTheme.copySuccess), "aria-label": copied ? "Copied!" : "Copy code", title: copied ? "Copied!" : "Copy code", children: copied ? (jsx(DocumentCheckIcon, { className: "size-4" })) : (jsx(DocumentDuplicateIcon, { className: "size-4" })) }))] }));
+                    }, children: code }) }), !showHeader && copyable && (jsx("button", { onClick: handleCopy, className: cn("absolute top-2 right-2", mergedTheme.copyButton, copied && mergedTheme.copySuccess), "aria-label": copied ? "Copied!" : "Copy code", title: copied ? "Copied!" : "Copy code", children: copied ? (jsx(ListChecks, { className: "size-4" })) : (jsx(Copy, { className: "size-4" })) }))] }));
 });
 CodeBlock.displayName = "CodeBlock";
 

package/dist/components/ai/CodeBlock/CodeBlock.theme.js

@@ -6,7 +6,7 @@ const codeBlockTheme = {
     filename: "text-sm font-medium text-[var(--color-text-secondary)] truncate",
     languageLabel: "text-xs uppercase tracking-wider font-semibold text-[var(--color-text-muted)]",
     codeWrapper: "overflow-x-auto",
-    highlightedLine: " -mx-4 px-4 bg-[var(--color-primary-50)] border-l-2 border-l-[var(--color-primary)] dark:bg-[var(--color-neutral-400)]/5 dark:border-l-[var(--color-neutral-200)]",
+    highlightedLine: " -mx-4 px-4 bg-[var(--color-primary-50)] border-l-2 border-l-[var(--color-primary)] dark:bg-[var(--color-mono-400)]/5 dark:border-l-[var(--color-mono-200)]",
     diffAddition: "-mx-4 px-4 bg-[var(--color-success-50)] border-l-4 border-l-[var(--color-success)] dark:bg-[var(--color-success-600)]/20 dark:border-l-[var(--color-success-700)]",
     diffDeletion: "-mx-4 px-4 bg-[var(--color-danger-50)] border-l-4 border-l-[var(--color-danger)] dark:bg-[var(--color-danger-600)]/20 dark:border-l-[var(--color-danger-700)]",
     copyButton: "p-1.5 rounded-[calc(var(--radius-base)*0.75)] text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",