basalt-ui 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+# [2.6.0](https://github.com/jkrumm/basalt-ui/compare/v2.5.0...v2.6.0) (2026-10-14)
+
+
+### Bug Fixes
+
+* answer the DX trial's page-shape and queryFn questions in the shipped layer ([a84293a](https://github.com/jkrumm/basalt-ui/commit/a84293a2c7b2e0549f86cca4e4eb0ce38d56e3de))
+
+
+### Features
+
+* bind a basalt control to a field backed by an external store ([d5f0674](https://github.com/jkrumm/basalt-ui/commit/d5f06740aeec4841da83980b49f50c05e24dbca5))
+* write an externalField from its store, not a render ([5853413](https://github.com/jkrumm/basalt-ui/commit/5853413973d8e83c08567933d40a340e676d09d0))
+
+# [2.5.0](https://github.com/jkrumm/basalt-ui/compare/v2.4.0...v2.5.0) (2026-10-14)
+
+
+### Bug Fixes
+
+* keep short-chart y labels inside only and lift ref swatch contrast ([480ca90](https://github.com/jkrumm/basalt-ui/commit/480ca90ae9ed3d7c4b9d057051bbf5308e7a871b))
+* thread the short-chart label rule through composed panes ([7d56a17](https://github.com/jkrumm/basalt-ui/commit/7d56a17e6de2942a4ad7ceb385d59e40d6a4b1ff))
+
+
+### Features
+
+* carry a call-site fallback from a store field into its control ([cb8819b](https://github.com/jkrumm/basalt-ui/commit/cb8819bd36a832258616915778ab84786291fcb7))
+* make withFallback the only call-site fallback ([f946e67](https://github.com/jkrumm/basalt-ui/commit/f946e6750b52543389aea55bbf44fc11b6f2368d))
+* propagate the chat turn's trace context to the chat endpoint ([c321b55](https://github.com/jkrumm/basalt-ui/commit/c321b555f4f443046ec00c1eec10d2cd124c8390))
+* settle a superseded turn's trace and export the trace-context types ([7aa3781](https://github.com/jkrumm/basalt-ui/commit/7aa3781e807b0c89fc0e5dd6853240596ab000ff))
+
 # [2.4.0](https://github.com/jkrumm/basalt-ui/compare/v2.3.0...v2.4.0) (2026-10-14)
 
 

package/MIGRATING.md

@@ -66,18 +66,18 @@ There is one row per SURFACE, not per export, and a surface earns a row once any
 shipped lefthook preset both changed in 1.30.0 with no row that owned them — which is how a
 consumer read this index, found nothing, and diffed a KPI row that had silently gone 4-up → 2-up.
 
-| Surface | 1.27.0 | 1.28.0 | 1.29.0 | 1.30.0 | 1.30.1 | 1.30.2 | 1.31.0 | 1.32.0 | 1.32.1 | 1.33.0 | 1.34.0 | 1.34.1 | 1.35.0 | 1.36.0 | 1.36.1 | 1.37.0 | 1.37.1 | 1.38.0 | 1.38.1 | 1.39.0 | 1.40.0 | 1.40.1 | 1.40.2 | 1.40.3 | 1.41.0 | 2.0.0 | 2.0.1 | 2.0.2 | 2.0.3 | 2.0.4 | 2.0.5 | 2.1.0 | 2.2.0 | 2.3.0 | 2.4.0 | Unreleased |
-| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------- | ------ | ------ | -------------------------------------------------------------------------------------------- | ------ | ------ | ------ | ------ | ------ | ----------------------------------------------- | ------ | ------ | ------ | ------ | ------------------------------------------------------------ | ---------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| **tokens** (`./tokens`) | — | `--vx-divider` → `rgba()` on both schemes (§ Shell) | `--vx-space-touch-target` added (§ Additions) | eight spacing numbers (§ Chrome) | — | — | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0) | — | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes) | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0) | `CONTAINER_KEYS` (§ 1.34.0) | — | — | — | — | — | — | — | | `appShellInset` 20 → 16 (§ 1.38.1) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **charts** (`./charts`) | — | phone tier, `curve`, formatters, `state`, log axis (§ preamble) | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions) | responsive `height`, `legend.maxRows` (§ Charts) | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | — | container-class tier + `height` keys (§ 1.31.0) | — | `ResponsiveChartHeight` `sm` → key (§ Container recipes) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **shell** (`.`) | — | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions) | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome) | — | — | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | — | `useBreakpoint` removed (§ 1.34.0) | — | — | `useCoarsePointer()` (§ `useCoarsePointer()`) | — | — | — | — | | content gutter 16, block 8 from `sm` (§ 1.38.1) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **controls** (`./controls`) | `NumberFilter`, `field.number` (§ Controls) | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`) | — | — | — | — | — | — | — | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | — | — | — | `FormSection`/`FormRow`/`FormGroup`/`FormActions` move here (§ The form layout moves) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **forms** (`./forms`) | — | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation) | — | — | — | — | — | `FormGroup` row no longer stretches (§ Fixes) | — | — | — | — | the layout + `useForm`/`schemaResolver` deprecated, removed 1.37.0 (§ The form layout moves) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **data** (`./data/table`) | — | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`) | `./data` + `./query` + `./connectivity` dropped (§ Consolidation) | — | — | — | — | — | `renderCard` documented (§ `renderCard`) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **dashboard** (`.`) | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive | — | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **toolchain** (`./configs/*`) | — | — | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
-| **CLI** (`basalt-ui`) | — | — | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | the managed block moves `CLAUDE.md` → `AGENTS.md` (§ 1.41.0) | — | — | — | — | — | — | — | — | — | — | — |
-| **guards** | five rules → `error` (§ Guards) | six new ids at `warn` (§ preamble) | `query-dual-import` retired in 1.29.1 (§ Guards) | four rules → `error` (§ Guards) | — | — | — | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes) | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards) | — | — | — | `unknown-vx-token` → `error`; the token factories throw (§ Guards) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| Surface | 1.27.0 | 1.28.0 | 1.29.0 | 1.30.0 | 1.30.1 | 1.30.2 | 1.31.0 | 1.32.0 | 1.32.1 | 1.33.0 | 1.34.0 | 1.34.1 | 1.35.0 | 1.36.0 | 1.36.1 | 1.37.0 | 1.37.1 | 1.38.0 | 1.38.1 | 1.39.0 | 1.40.0 | 1.40.1 | 1.40.2 | 1.40.3 | 1.41.0 | 2.0.0 | 2.0.1 | 2.0.2 | 2.0.3 | 2.0.4 | 2.0.5 | 2.1.0 | 2.2.0 | 2.3.0 | 2.4.0 | 2.5.0 | 2.6.0 | Unreleased |
+| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------- | ------ | ------ | -------------------------------------------------------------------------------------------- | ------ | ------ | ------ | ------ | ------ | ----------------------------------------------- | ------ | ------ | ------ | ------ | ------------------------------------------------------------ | ---------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **tokens** (`./tokens`) | — | `--vx-divider` → `rgba()` on both schemes (§ Shell) | `--vx-space-touch-target` added (§ Additions) | eight spacing numbers (§ Chrome) | — | — | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0) | — | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes) | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0) | `CONTAINER_KEYS` (§ 1.34.0) | — | — | — | — | — | — | — | | `appShellInset` 20 → 16 (§ 1.38.1) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **charts** (`./charts`) | — | phone tier, `curve`, formatters, `state`, log axis (§ preamble) | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions) | responsive `height`, `legend.maxRows` (§ Charts) | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | — | container-class tier + `height` keys (§ 1.31.0) | — | `ResponsiveChartHeight` `sm` → key (§ Container recipes) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **shell** (`.`) | — | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions) | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome) | — | — | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | — | `useBreakpoint` removed (§ 1.34.0) | — | — | `useCoarsePointer()` (§ `useCoarsePointer()`) | — | — | — | — | | content gutter 16, block 8 from `sm` (§ 1.38.1) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **controls** (`./controls`) | `NumberFilter`, `field.number` (§ Controls) | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`) | — | — | — | — | — | — | — | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | — | — | — | `FormSection`/`FormRow`/`FormGroup`/`FormActions` move here (§ The form layout moves) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **forms** (`./forms`) | — | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation) | — | — | — | — | — | `FormGroup` row no longer stretches (§ Fixes) | — | — | — | — | the layout + `useForm`/`schemaResolver` deprecated, removed 1.37.0 (§ The form layout moves) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **data** (`./data/table`) | — | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`) | `./data` + `./query` + `./connectivity` dropped (§ Consolidation) | — | — | — | — | — | `renderCard` documented (§ `renderCard`) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **dashboard** (`.`) | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive | — | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **toolchain** (`./configs/*`) | — | — | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **CLI** (`basalt-ui`) | — | — | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | the managed block moves `CLAUDE.md` → `AGENTS.md` (§ 1.41.0) | — | — | — | — | — | — | — | — | — | — | — | — | — |
+| **guards** | five rules → `error` (§ Guards) | six new ids at `warn` (§ preamble) | `query-dual-import` retired in 1.29.1 (§ Guards) | four rules → `error` (§ Guards) | — | — | — | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes) | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards) | — | — | — | `unknown-vx-token` → `error`; the token factories throw (§ Guards) | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
 
 ---
 
@@ -992,6 +992,45 @@ optional, subpath-required peers.
 _Nothing yet. Author the next section under this heading as `## Unreleased — <title>`; the
 release renames it and opens a new one here._
 
+## 2.6.0 — external-store fields, a live query-fn-unwrap, page shape
+
+- `externalField({ values, fallback, labels, store })` (`basalt-ui/state`) returns a `FieldHandle`
+  over a value a foreign store owns (a zustand slice): `ViewTabs`, `SelectFilter` and `EnumFilter`
+  take it as `field=` like any store field. No URL, localStorage or memory lane; `store` is the
+  non-hook API (`{ get, set, subscribe }` — zustand's `getState`/`setState`/`subscribe`), read at
+  definition so `clear()` writes `set(fallback)` mounted or not; `fallback` must be one of `values`. Replaces a raw `SegmentedControl` behind
+  `theme-allow control-outside-home, raw-selection-control` (argo `timer-card.tsx`). Rule: `basalt-state`.
+- A card BODY is still not a control home. Mount the bound control in the card's header slot
+  (`<WidgetHeader actions={<ViewTabs field={timerMode} label="Timer mode" />} />`); no lint change.
+- **Lint, may surface new errors:** `basalt/query-fn-unwrap` was dead since 1.29.0 (it only saw the
+  removed `basalt-ui/query` import). It now also fires in files importing `basalt-ui`: an inline
+  `queryFn` calling `fetch(` must wrap the response in `unwrap()`. A mock `queryFn` returning plain
+  data is exempt.
+- The `basalt-app` skill's page example is the canonical shell page (`PageBar` only to fill a slot);
+  inside a `ChartCard` the card owns `state`, a bare chart kind owns its own.
+
+## 2.5.0 — call-site fallbacks for controls, chat trace headers, axis labels
+
+- `createLocalStore` fields take `withFallback(value)`: the same field (key, setter, `clear()`)
+  with a call-site unset value, for `use()` and any filter control as `field=`
+  (`<SelectFilter field={store.field.exercise.withFallback(leader)} />`). Never persisted; a reset
+  returns to it; `fallback` and `isDefault` on the derived handle report it. Rule: `basalt-state`.
+  `createSearchStore` fields do not take it: the URL lane drops a value equal to the definition's
+  fallback, so a second default would make one URL mean two things.
+- `use({ fallback })` is removed — replaced by `field.withFallback(value).use()`. It existed in
+  2.4.0 only and has no known consumers. argo `strength-composite-chart.tsx`: bind
+  `store.field.exercise.withFallback(leader)` instead of rebuilding the store per leader.
+- A `telemetry` sink may define `startChatTurn(turn)` returning `{ headers?: { traceparent,
+  tracestate? }, settle?(end) }`: `aiSdkTransport` sends those headers with that turn's chat
+  request (so the API span joins the dashboard trace) and `settle` runs once when the turn ends
+  (also on a superseded or failed turn). `Telemetry`, `ChatTurnTrace`, `ChatTurnEnd`,
+  `TraceHeaders` are exported. Optional: without the hook nothing changes. A cross-origin chat API
+  must allow `traceparent` in CORS.
+- Y-axis tick labels sit inside the plot only for a compact chart under the box's short height
+  (180 px), across every kind including `DualPanel` and `MirroredBars`; a regular-height chart
+  keeps them in the left gutter. Reference-line legend swatches meet the series-swatch contrast in
+  light and dark.
+
 ## 2.4.0 — chart gaps and legends, local-store fallbacks, the pre-commit hook
 
 All additive; no call site changes. Named consumers are argo `apps/dashboard/src/features/…`.

package/agent/rules/basalt-batteries.md

@@ -18,7 +18,7 @@ paths:
 
 ## Query
 
-- Wrap every `queryFn` response in `unwrap()`; it throws on the error branch and on `null` data. [basalt/query-fn-unwrap]
+- Wrap every API-client `queryFn` response in `unwrap()` (it throws on the error branch and on `null` data); a mock returning plain data needs none, and the lint sees only an inline `queryFn` calling `fetch(`. [basalt/query-fn-unwrap]
 - The client comes from `createBasaltRouter`; extend it via its `query:` option. [type createBasaltRouter]
 
 ## Forms

package/agent/rules/basalt-charts.md

@@ -24,7 +24,7 @@ Every cartesian chart is `CartesianChart` or a kind built on it; props are in th
 - Draw `plot.rows(key)` and `plot.visible`, never the `series` prop, so a legend toggle hides the mark. [type PlotContext]
 - A second axis is `y2` with a series `axis: 'right'`; there is no margin prop. [type CartesianChartProps]
 - Size is `height` (a number or per container class); the host measures the width. [type ResponsiveChartHeight]
-- A pending, failed or empty query is `state={{ pending, error, empty }}`, never `data ?? []`; a streamed chart's `<Suspense>` fallback is the same chart with `state={{ pending: true }}`, which fills the final box. [type ChartState]
+- A pending, failed or empty query is `state={{ pending, error, empty }}`, never `data ?? []`; a streamed chart's `<Suspense>` fallback is the same chart with `state={{ pending: true }}`, which fills the final box; inside a `ChartCard` the card owns `state` (header kept, body swapped), the kind only when bare. [type ChartState] [type ChartCardProps]
 - Zones, thresholds and reference lines are `zones`, `xZones` and `refLines` data. [type ZoneSpec]
 - Extra tooltip rows are `tooltip.rows` data, never markup. [type ChartTooltipConfig]
 - Charts share one cursor by default; `cursorGroup` isolates one, `chartCursor(group?)` reads it. [type chartCursor]

package/agent/rules/basalt-mantine.md

@@ -27,7 +27,7 @@ paths:
 - One `BasaltShell nav={NAV}` in `__root.tsx` wraps `<Outlet />`; never build `AppShell.*` parts or a `Burger`, and never wrap `<Outlet />` in `<ViewTransition>` (the router animates route changes in nav order). [basalt/hand-rolled-shell] [basalt/route-view-transition]
 - Shell extensions are typed data props (`globalActions`, `sidebarBlocks`, `brand`, `search`, `settingsMenuItems`, `account`), never `ReactNode` slots. [type BasaltShell]
 - Pass no `renderNavLink`, `renderBreadcrumbLink` or `withBorder`; the shell resolves links against the router and draws region edges. [type BasaltShell]
-- A page is named once, by its nav item's `label` (the breadcrumb), `PageBar.title` (no shell) or `PageTitle` (shell-less screen); no in-body `<Title order={1|2}>`. [basalt/in-body-page-title] [check-theme in-body-page-title]
+- A page is named once, by its nav item's `label` (the breadcrumb), `PageBar.title` (no shell) or `PageTitle` (shell-less screen); no in-body `<Title order={1|2}>`. [basalt/in-body-page-title] [check-theme in-body-page-title]; a shell page renders `<PageBar />` only to fill a slot (`actions`, `sync`, `tabs`, `filters`) and its `title` is ignored there. [type PageBar]
 - A nav item's mobile placement is its `mobile` field: `'tab'`, `'more'` or `'hidden'`. [type defineNav]
 
 ## Surfaces

package/agent/rules/basalt-state.md

@@ -19,12 +19,12 @@ State a control reads or writes is a field on a store; the URL wins over localSt
 ## Stores
 
 - Define filters, tabs, ranges and pagination as fields of `createSearchStore` (URL) or `createLocalStore` (no router), with `field.range|multi|enum|boolean`. [type createSearchStore]
-- Never `useState` for a filter, tab, range or view; a basalt control takes a `field` and has no `value` or `onChange`. [check-theme raw-selection-control]
+- Never `useState` for a filter, tab, range or view; a basalt control takes a `field` and has no `value` or `onChange`. A value another store owns (a zustand slice) binds as `externalField({ values, fallback, labels, store: { get, set, subscribe } })`, no lane, `clear()` writes the fallback. [check-theme raw-selection-control]
 - Declare lanes once at definition: `{ url, persist, history }`; `url: false` is local-only, `persist: false` is URL-only. [type field]
 - Option labels come from `.labels()` at definition, never a control prop. [type createSearchStore]
 - Route `validateSearch` is `store.validateSearch`; a wider search shape spreads `...store.validateSearch(raw)`. [type createSearchStore]
 - Read with `store.useValues()` or take the value as a prop; never `useSearch({ from: '<literal>' })`. [basalt/use-search-from-literal]
-- A handle's `use()` returns `[value, setValue]`; the setter owns the navigate and the persist; on a `createLocalStore` field a prop-derived default is `use({ fallback })` (unset only, never persisted; search stores lack it), never a store rebuilt per prop. [type field]
+- A handle's `use()` returns `[value, setValue]`; the setter owns the navigate and the persist; on a `createLocalStore` field a prop-derived default is `store.field.x.withFallback(value)`, passed to `use()` and to any control as `field=` (unset only, never persisted, a reset returns to it, `isDefault` follows it; search stores lack it, a derived handle does not derive again), never a store rebuilt per prop. [type field]
 - Count active filters and reset them with the store's `useActiveCount()` and `useReset()`; a reset unsets, it does not write the fallback. [type createSearchStore]
 - A color scheme is `useMantineColorScheme()`, never a store or `localStorage['theme']`. [check-theme localstorage-theme]
 - A preference that must survive navigation but is not URL-worthy uses `createPersistedState`, called once at module scope. [type createPersistedState]

package/agent/skills/basalt-app/SKILL.md

@@ -36,11 +36,12 @@ createRoot(document.getElementById('root')!).render(<BasaltProvider router={rout
 ```tsx
 // @check
 import { Link, createFileRoute, linkOptions } from '@tanstack/react-router'
-import { defineNav, navGroup, navTarget } from 'basalt-ui'
-// src/routes/dashboard.tsx — the breadcrumb and page title come from the nav item's `label`; export the component too (react/only-export-components)
+import { PageBar, defineNav, navGroup, navTarget } from 'basalt-ui'
+// src/routes/dashboard.tsx — the nav item's `label` is the page name (breadcrumb); export the component too (react/only-export-components)
 export const Route = createFileRoute('/dashboard')({ component: Dashboard })
 export function Dashboard() {
-  return <h2>Dashboard</h2>
+  // a PageBar only fills slots (actions, sync, tabs, filters); the body has no title
+  return <PageBar actions={[{ key: 'export', label: 'Export', primary: true }]} />
 }
 // src/lib/nav.tsx
 export const NAV = defineNav({
@@ -241,8 +242,7 @@ export function Chat() {
 
 ## Refresh after any upgrade
 
-1. `./node_modules/.bin/basalt-ui sync` (`--check` in CI, `--force` overwrites local edits).
-2. Read its output: edited files are skipped, retired files are deleted, the AGENTS.md block is rewritten.
+1. `./node_modules/.bin/basalt-ui sync` (`--check` in CI, `--force` overwrites local edits); read its output: edited files are skipped, retired files are deleted, the AGENTS.md block is rewritten.
 
 ## Upgrade 1.x to 2.0
 

package/configs/oxlint-plugin.js

@@ -3135,11 +3135,14 @@ const boundControlOutsideHome = {
 
 /** The `basalt-ui/query` subpath, exactly — kept for `query-fn-unwrap`'s own gate below. */
 const BASALT_QUERY_SOURCE = 'basalt-ui/query'
+/** `unwrap` ships from the root since 1.29.0; the `./query` subpath is gone, so the root counts too. */
+const QUERY_UNWRAP_SOURCES = new Set([BASALT_QUERY_SOURCE, 'basalt-ui'])
 
 // ── Rule 28 — query-fn-unwrap ───────────────────────────────────────────────────────────────────
 
 const QUERY_FN_UNWRAP_MESSAGE =
-  'queryFn fetches without unwrap() — `unwrap` throws on the error branch AND on a null data with ' +
+  'queryFn calls fetch( without unwrap() (scope: an inline queryFn with a literal fetch( call in a ' +
+  'file importing basalt-ui; a mock queryFn returning plain data is exempt) — `unwrap` throws on the error branch AND on a null data with ' +
   'no error (a 204, a silent transport failure), and both are caller bugs that have to surface as ' +
   'a rejected query rather than as `data: null` rendered through the success branch ' +
   '(agent/rules/basalt-batteries.md). Wrap the call: `queryFn: () => unwrap(client.thing.get())`. ' +
@@ -3165,7 +3168,7 @@ const UNWRAP_CALL = /\bunwrap\s*\(/
  * something else. A stricter version would need the call graph. The narrow version fires on the
  * form a consumer writes by reflex on day one, which is the one the law exists for.
  *
- * Scoped to files importing `basalt-ui/query` literally, for the reason {@link queryDualImport}
+ * Scoped to files importing `basalt-ui` or `basalt-ui/query` literally, for the reason {@link queryDualImport}
  * gives: without that gate it is an opinion about `fetch`, which basalt does not have.
  */
 // Ships: error
@@ -3182,7 +3185,7 @@ const queryFnUnwrap = {
 
     return {
       ImportDeclaration(node) {
-        if (node.source?.value === BASALT_QUERY_SOURCE) basaltQuery = true
+        if (QUERY_UNWRAP_SOURCES.has(node.source?.value)) basaltQuery = true
       },
       Property(node) {
         if (propertyKeyName(node) !== 'queryFn') return

package/configs/oxlint-plugin.test.ts

@@ -3157,6 +3157,14 @@ describe('basalt/query-fn-unwrap', () => {
     expect(rules).not.toContain('query-fn-unwrap')
   })
 
+  it('flags a fetching queryFn in a file importing the root barrel', () => {
+    const { code, rules } = run(
+      `import { unwrap } from 'basalt-ui'\nexport const o = { queryKey: ['t'], queryFn: () => fetch('/api/t') }\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-fn-unwrap')
+  })
+
   it('honours a theme-allow naming the rule', () => {
     const { code, rules } = run(
       `${IMPORT}export const o = {\n  queryKey: ['t'],\n` +

package/dist/agent/ai-sdk-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-transport.d.ts","sourceRoot":"","sources":["../../src/agent/ai-sdk-transport.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,SAAS,CAAA;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAK1D,OAAO,KAAK,EACV,aAAa,EAGb,SAAS,EAGV,MAAM,IAAI,CAAA;AAOX,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,GAAG,SAAS,CAAA;IAC/D,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACrD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,GAAG,SAAS,CAAA;CACrD,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAC7C,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAIzE,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IACvF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAC/E,CAAA;AA8RD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,SAAS,EAC9C,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,KAAK,CAAC,CA4DvB"}
+{"version":3,"file":"ai-sdk-transport.d.ts","sourceRoot":"","sources":["../../src/agent/ai-sdk-transport.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,SAAS,CAAA;AACxD,OAAO,KAAK,EAAsB,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAK9E,OAAO,KAAK,EACV,aAAa,EAGb,SAAS,EAGV,MAAM,IAAI,CAAA;AAOX,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,GAAG,SAAS,CAAA;IAC/D,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACrD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,GAAG,SAAS,CAAA;CACrD,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAC7C,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAIzE,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IACvF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAC/E,CAAA;AA8RD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,SAAS,EAC9C,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,KAAK,CAAC,CA+DvB"}

package/dist/agent/ai-sdk-transport.js

@@ -177,7 +177,10 @@ function aiSdkTransport(options) {
           messages: [userMessage],
           trigger: "submit-message",
           messageId: void 0,
-          abortSignal: signal
+          abortSignal: signal,
+          // Per-turn trace context goes to the chat endpoint only (merged over the static headers by
+          // AI SDK's HTTP transport); absent, the request is exactly what it was.
+          ...ctx?.headers !== void 0 ? { headers: ctx.headers } : {}
         });
         yield* diffChunkStream(chatId, chunkStream, readStream, signal);
       },

package/dist/agent/index.d.ts

@@ -18,7 +18,7 @@ export { toAgentError } from './error.js';
 export type { ChatMessage } from './history.js';
 export type { AgentThread, ThreadStatus, ThreadsStore } from './thread.js';
 export type { AgentOutcome, OutcomeResolver } from './outcome.js';
-export type { AgentTransport, ResumableAgentTransport } from './transport.js';
+export type { AgentStreamContext, AgentTransport, ResumableAgentTransport } from './transport.js';
 export { ThreadFeed } from './chat/thread-feed.js';
 export { ThreadFeedRow } from './chat/thread-feed-row.js';
 export type { MessageAffordances } from './chat/message-affordances.js';

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGzF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAGtC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC9D,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAG1E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGzF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAGtC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAG9F,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/agent/run-records.d.ts

@@ -11,12 +11,13 @@
  * being driven, long before the `setRuns` it queues renders. That window is what the record
  * covers: it outlives the run only until a render shows the outcome (`sweepFlushed`).
  */
+import type { ChatTurnEnd, ChatTurnTrace } from '../telemetry.js';
 /** The part of a rendered `runs` entry this module reads. */
 type RenderedRun<TPart> = {
     readonly status: string;
     readonly parts: TPart[];
 };
-export type RunEnd = 'settled' | 'failed' | 'stopped';
+export type RunEnd = ChatTurnEnd;
 export type RunRecord<TPart> = {
     readonly controller: AbortController;
     /** The unthrottled accumulator; `runs` may lag it by one throttle window. Emptied when the run ends. */
@@ -28,10 +29,18 @@ export type RunRecord<TPart> = {
     ended: RunEnd | undefined;
     /** A newer run began on the same thread (set by `beginRun` on the record it replaces). */
     superseded: boolean;
+    /** The turn's telemetry `settle`, run once by `settleTrace`. */
+    settle: ChatTurnTrace['settle'];
 };
 export type RunRecords<TPart> = Map<string, RunRecord<TPart>>;
-/** Registers a live run for `threadId`, replacing whatever record the previous run left. */
-export declare function beginRun<TPart>(records: RunRecords<TPart>, threadId: string, controller: AbortController): RunRecord<TPart>;
+/**
+ * Registers a live run for `threadId`, replacing whatever record the previous run left. A previous
+ * run still being driven is cut short: its trace settles as `stopped`. `settle` is the new turn's
+ * telemetry hook (absent for a resume).
+ */
+export declare function beginRun<TPart>(records: RunRecords<TPart>, threadId: string, controller: AbortController, settle?: ChatTurnTrace['settle']): RunRecord<TPart>;
+/** Runs the turn's telemetry `settle` once; a throwing consumer hook never breaks the run. */
+export declare function settleTrace<TPart>(record: RunRecord<TPart>, end: RunEnd): void;
 /** Marks a run as no longer driven and drops the content it held. */
 export declare function endRun<TPart>(record: RunRecord<TPart>, reason: RunEnd): void;
 /** True while `controller`'s run is still the thread's live one. */

package/dist/agent/run-records.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-records.d.ts","sourceRoot":"","sources":["../../src/agent/run-records.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-records.d.ts","sourceRoot":"","sources":["../../src/agent/run-records.ts"],"names":[],"mappings":"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"}

package/dist/agent/run-records.js

@@ -1,17 +1,29 @@
-function beginRun(records, threadId, controller) {
+function beginRun(records, threadId, controller, settle) {
   const record = {
     controller,
     parts: [],
     appended: false,
     resolving: false,
     ended: void 0,
-    superseded: false
+    superseded: false,
+    settle
   };
   const previous = records.get(threadId);
-  if (previous !== void 0) previous.superseded = true;
+  if (previous !== void 0) {
+    previous.superseded = true;
+    settleTrace(previous, "stopped");
+  }
   records.set(threadId, record);
   return record;
 }
+function settleTrace(record, end) {
+  const { settle } = record;
+  record.settle = void 0;
+  try {
+    settle?.(end);
+  } catch {
+  }
+}
 function endRun(record, reason) {
   record.ended = reason;
   record.parts = [];
@@ -65,5 +77,6 @@ export {
   isLatestRun,
   isLive,
   planStopWithTombstone,
+  settleTrace,
   sweepFlushed
 };

package/dist/agent/transport.d.ts

@@ -13,6 +13,15 @@
  *
  */
 import type { AgentPartDraft } from './parts.js';
+/**
+ * The third `stream` argument. `headers` are extra request headers for THIS turn's request to the
+ * transport's own endpoint — today the W3C trace context a telemetry sink's `startChatTurn`
+ * returned. Absent unless a sink contributed; a transport that ignores them keeps working.
+ */
+export type AgentStreamContext = {
+    readonly messageId: string;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+};
 /**
  * The injected transport seam. `stream(input, signal, ctx)` returns an async generator of parts.
  * Implement this interface for any backend — fetch-based SSE, AI SDK, or a mock.
@@ -40,9 +49,7 @@ import type { AgentPartDraft } from './parts.js';
  * }
  */
 export type AgentTransport<TPart = AgentPartDraft, TInput = string> = {
-    stream: (input: TInput, signal?: AbortSignal, ctx?: {
-        readonly messageId: string;
-    }) => AsyncGenerator<TPart>;
+    stream: (input: TInput, signal?: AbortSignal, ctx?: AgentStreamContext) => AsyncGenerator<TPart>;
     /** Optional: resume a previously-started run from its resumeToken (see StartPart). Transports that don't support resumption simply omit this. */
     resume?: ((resumeToken: string, signal?: AbortSignal) => AsyncGenerator<TPart>) | undefined;
 };

package/dist/agent/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/agent/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,cAAc,EAAE,MAAM,GAAG,MAAM,IAAI;IACpE,MAAM,EAAE,CACN,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,EACpB,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KACjC,cAAc,CAAC,KAAK,CAAC,CAAA;IAC1B,iJAAiJ;IACjJ,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,cAAc,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAA;CAC5F,CAAA;AAID;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,CAAC,KAAK,GAAG,cAAc,EAAE,MAAM,GAAG,MAAM,IAAI,cAAc,CAC3F,KAAK,EACL,MAAM,CACP,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,cAAc,CAAC,KAAK,CAAC,CAAA;IACrF,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAA;CAChC,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EACvC,CAAC,EAAE,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC/B,CAAC,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAK7C"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/agent/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAI7C;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;CAChE,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,cAAc,EAAE,MAAM,GAAG,MAAM,IAAI;IACpE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,kBAAkB,KAAK,cAAc,CAAC,KAAK,CAAC,CAAA;IAChG,iJAAiJ;IACjJ,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,cAAc,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAA;CAC5F,CAAA;AAID;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,CAAC,KAAK,GAAG,cAAc,EAAE,MAAM,GAAG,MAAM,IAAI,cAAc,CAC3F,KAAK,EACL,MAAM,CACP,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,cAAc,CAAC,KAAK,CAAC,CAAA;IACrF,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAA;CAChC,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EACvC,CAAC,EAAE,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC/B,CAAC,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAK7C"}

package/dist/agent/use-agent-thread-runs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-agent-thread-runs.d.ts","sourceRoot":"","sources":["../../src/agent/use-agent-thread-runs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-agent-thread-runs.d.ts","sourceRoot":"","sources":["../../src/agent/use-agent-thread-runs.ts"],"names":[],"mappings":"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"}

package/dist/agent/use-agent-thread-runs.js

@@ -7,6 +7,7 @@ import { createRunCommitter, isContentPart } from "./run-committer.js";
 import {
   beginRun,
   endRun,
+  settleTrace,
   failedThreadIds,
   dismissRun,
   hasLiveRun,
@@ -16,7 +17,7 @@ import {
   sweepFlushed
 } from "./run-records.js";
 import { isResumable } from "./transport.js";
-import { TelemetryContext, createEmitter, errorName, now } from "../telemetry.js";
+import { TelemetryContext, createLiveEmitter, errorName, now } from "../telemetry.js";
 function defaultToUserParts(input) {
   return [{ id: mintThreadId(), type: "text", text: input }];
 }
@@ -129,6 +130,7 @@ async function consumeAndFinalize(args) {
         status: outcome.status
       })
     );
+    settleTrace(record, "settled");
   } catch (err) {
     if (!live()) {
       if (record.ended === "stopped" && record.appended) onError?.({ threadId, error: err });
@@ -154,6 +156,7 @@ async function consumeAndFinalize(args) {
         failure: { error: err, agentError }
       })
     );
+    settleTrace(record, "failed");
     onError?.({ threadId, error: err });
   } finally {
     committer.cancel();
@@ -220,6 +223,15 @@ async function finalizeStop(args) {
     record.resolving = false;
   }
 }
+const TRACEPARENT = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/;
+const TRACESTATE_MEMBER = /^[\da-z][\w*/@-]{0,255}=[^\s,=]([^,=]{0,254}[^\s,=])?$/;
+function traceRequestHeaders(headers) {
+  const { traceparent, tracestate } = headers;
+  if (typeof traceparent !== "string" || !TRACEPARENT.test(traceparent)) return void 0;
+  const members = typeof tracestate === "string" ? tracestate.split(",") : [];
+  const valid = members.length > 0 && members.length <= 32 && members.every((member) => TRACESTATE_MEMBER.test(member.trim()));
+  return valid ? { traceparent, tracestate } : { traceparent };
+}
 function buildTurnEvent(args) {
   const { threadId, startedAt, firstContentAt, partCount, status, failure } = args;
   const endedAt = now();
@@ -274,10 +286,7 @@ function useAgentThreadRuns({
   const resolvedToUserParts = toUserParts ?? defaultToUserParts;
   const toUserPartsRef = useRef(resolvedToUserParts);
   toUserPartsRef.current = resolvedToUserParts;
-  const emitTelemetry = useMemo(
-    () => createEmitter((event) => telemetryRef.current?.(event)),
-    []
-  );
+  const emitTelemetry = useMemo(() => createLiveEmitter(() => telemetryRef.current), []);
   const resolveTransport = (threadId) => {
     const currentTransport = transportRef.current;
     if (typeof currentTransport !== "function") return currentTransport;
@@ -294,6 +303,7 @@ function useAgentThreadRuns({
         if (record.ended !== void 0) continue;
         abortedThreadIds.push(threadId);
         record.controller.abort();
+        settleTrace(record, "stopped");
       }
       recordsRef.current.clear();
       if (abortedThreadIds.length === 0) return;
@@ -374,8 +384,10 @@ function useAgentThreadRuns({
         return next;
       });
       const controller = new AbortController();
-      const record = beginRun(recordsRef.current, threadId, controller);
+      const trace = emitTelemetry.startChatTurn?.({ threadId, messageId: userMessage.id });
+      const record = beginRun(recordsRef.current, threadId, controller, trace?.settle);
       const resolvedTransport = resolveTransport(threadId);
+      const headers = trace?.headers === void 0 ? void 0 : traceRequestHeaders(trace.headers);
       void consumeAndFinalize({
         threadId,
         record,
@@ -385,7 +397,10 @@ function useAgentThreadRuns({
         // id instead of a second, unrelated one (R1 — see AgentTransport.stream's doc).
         generator: withPartIds(
           threadId,
-          resolvedTransport.stream(input, controller.signal, { messageId: userMessage.id })
+          resolvedTransport.stream(input, controller.signal, {
+            messageId: userMessage.id,
+            ...headers !== void 0 ? { headers } : {}
+          })
         ),
         userMessage,
         recordsRef,
@@ -433,6 +448,7 @@ function useAgentThreadRuns({
       const { appended, resolving } = record;
       endRun(record, "stopped");
       record.controller.abort();
+      settleTrace(record, "stopped");
       void finalizeStop({
         threadId,
         parts,

package/dist/charts/DualPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DualPanel.d.ts","sourceRoot":"","sources":["../../src/charts/DualPanel.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AASzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAcrF,uBAAuB;AACvB,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,IAAI,CACjC,WAAW,CAAC,CAAC,CAAC,EACZ,KAAK,GACL,OAAO,GACP,OAAO,GACP,UAAU,GACV,aAAa,GACb,SAAS,GACT,QAAQ,GACR,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,aAAa,GACb,eAAe,GACf,WAAW,CACd,CAAA;AAED,mEAAmE;AACnE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;IACjC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,6EAA6E;IAC7E,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC7B,sDAAsD;IACtD,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IACnD,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IACvD;2BACuB;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;IACvD,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,IAAI,IAAI,CAC3E,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,WAAW,GACX,MAAM,GACN,GAAG,GACH,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,aAAa,GACb,kBAAkB,GAClB,SAAS,GACT,WAAW,GACX,OAAO,CACV,GAAG;IACF,4BAA4B;IAC5B,MAAM,EAAE,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,CAAA;IACnC;6FACyF;IACzF,GAAG,CAAC,EACA;QACE,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;QACvD,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;QAC5C,uDAAuD;QACvD,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;KACpD,GACD,SAAS,CAAA;IACb;;;OAGG;IACH,WAAW,CAAC,EACR;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC1E,SAAS,CAAA;IACb,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IACpB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC,CAAA;AAiBD,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,EAClE,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAC1B,YAAY,CA8Nd"}
+{"version":3,"file":"DualPanel.d.ts","sourceRoot":"","sources":["../../src/charts/DualPanel.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AASzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAcrF,uBAAuB;AACvB,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,IAAI,CACjC,WAAW,CAAC,CAAC,CAAC,EACZ,KAAK,GACL,OAAO,GACP,OAAO,GACP,UAAU,GACV,aAAa,GACb,SAAS,GACT,QAAQ,GACR,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,aAAa,GACb,eAAe,GACf,WAAW,CACd,CAAA;AAED,mEAAmE;AACnE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;IACjC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,6EAA6E;IAC7E,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC7B,sDAAsD;IACtD,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IACnD,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IACvD;2BACuB;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;IACvD,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,IAAI,IAAI,CAC3E,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,WAAW,GACX,MAAM,GACN,GAAG,GACH,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,aAAa,GACb,kBAAkB,GAClB,SAAS,GACT,WAAW,GACX,OAAO,CACV,GAAG;IACF,4BAA4B;IAC5B,MAAM,EAAE,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,CAAA;IACnC;6FACyF;IACzF,GAAG,CAAC,EACA;QACE,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;QACvD,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;QAC5C,uDAAuD;QACvD,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;KACpD,GACD,SAAS,CAAA;IACb;;;OAGG;IACH,WAAW,CAAC,EACR;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC1E,SAAS,CAAA;IACb,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IACpB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC,CAAA;AAiBD,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,EAClE,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAC1B,YAAY,CAuOd"}

package/dist/charts/DualPanel.js

@@ -9,7 +9,7 @@ import { VX, alpha } from "../tokens/index.js";
 import { resolveContainerClass } from "../tokens/size-classes.js";
 import { defaultFormatX, defaultNumberFormat, engineRow, seriesRow, visibleSeries } from "./compile.js";
 import { barMark, emphasis, lineMark, markersOf, thinFill } from "./marks.js";
-import { PanelRung, paneX, paneY, rowsOf } from "./panel.js";
+import { PanelRung, chartHeightOf, paneX, paneY, rowsOf } from "./panel.js";
 import { xScaleFor } from "./scales.js";
 import { rowX } from "./types.js";
 const BAR_KEY = "__bar";
@@ -147,12 +147,20 @@ function DualPanel(props) {
           ],
           scales: {
             x: { scale: xScale(), axis: false },
-            y: paneY({ scale: topY, domain: topDomain, format: topFormat, ticks: TOP_TICKS, cls })
+            y: paneY({
+              scale: topY,
+              domain: topDomain,
+              format: topFormat,
+              ticks: TOP_TICKS,
+              cls,
+              height: chartHeightOf(h, topFraction, PANE_GAP)
+            })
           }
         };
       };
-      const barPane = ({ width }) => {
+      const barPane = ({ width, height: h }) => {
         const cls = resolveContainerClass(width);
+        const whole = chartHeightOf(h, 1 - topFraction, PANE_GAP);
         const barRows = barOn ? rowsOf(data, x, barSeries) : [];
         const dim = emphasis(highlighted, { key: BAR_KEY });
         return {
@@ -166,13 +174,14 @@ function DualPanel(props) {
             })
           ],
           scales: {
-            x: paneX({ scale: xScale(), model, format, cls }),
+            x: paneX({ scale: xScale(), model, format, cls, height: whole }),
             y: paneY({
               scale: barScale,
               domain: barDomain,
               format: bar.format,
               ticks: BAR_TICKS,
-              cls
+              cls,
+              height: whole
             })
           }
         };

package/dist/charts/MirroredBars.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MirroredBars.d.ts","sourceRoot":"","sources":["../../src/charts/MirroredBars.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AASzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,EAAW,MAAM,SAAS,CAAA;AAEhF,4BAA4B;AAC5B,MAAM,MAAM,eAAe,GAAG;IAC5B;8EAC0E;IAC1E,GAAG,EAAE,MAAM,CAAA;IACX,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACjC,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,2DAA2D;IAC3D,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAC9B,CAAA;AAED,oGAAoG;AACpG,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,IAAI,CACtC,WAAW,CAAC,CAAC,CAAC,EACd,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAChG,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CAChE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,WAAW,GACX,MAAM,GACN,GAAG,GACH,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,aAAa,GACb,SAAS,GACT,WAAW,GACX,OAAO,CACV,GAAG;IACF,qEAAqE;IACrE,MAAM,EAAE,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAA;IACxC,gCAAgC;IAChC,EAAE,EAAE,eAAe,CAAA;IACnB,gCAAgC;IAChC,IAAI,EAAE,eAAe,CAAA;IACrB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IAClD,6FAA6F;IAC7F,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IAC9C;;;OAGG;IACH,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;KAAE,GAAG,SAAS,CAAA;IAC/E,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAA;CAC7E,CAAA;AAgDD,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACvD,KAAK,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,YAAY,CAwKd"}
+{"version":3,"file":"MirroredBars.d.ts","sourceRoot":"","sources":["../../src/charts/MirroredBars.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AASzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,EAAW,MAAM,SAAS,CAAA;AAEhF,4BAA4B;AAC5B,MAAM,MAAM,eAAe,GAAG;IAC5B;8EAC0E;IAC1E,GAAG,EAAE,MAAM,CAAA;IACX,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACjC,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,2DAA2D;IAC3D,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAC9B,CAAA;AAED,oGAAoG;AACpG,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,IAAI,CACtC,WAAW,CAAC,CAAC,CAAC,EACd,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAChG,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CAChE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,WAAW,GACX,MAAM,GACN,GAAG,GACH,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,aAAa,GACb,SAAS,GACT,WAAW,GACX,OAAO,CACV,GAAG;IACF,qEAAqE;IACrE,MAAM,EAAE,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAA;IACxC,gCAAgC;IAChC,EAAE,EAAE,eAAe,CAAA;IACnB,gCAAgC;IAChC,IAAI,EAAE,eAAe,CAAA;IACrB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IAClD,6FAA6F;IAC7F,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;IAC9C;;;OAGG;IACH,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;KAAE,GAAG,SAAS,CAAA;IAC/E,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAA;CAC7E,CAAA;AAgDD,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACvD,KAAK,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,YAAY,CA0Kd"}