basalt-ui 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+# [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)
+
+
+### Bug Fixes
+
+* guard band edge rules in one place and share the tooltip row builders ([75a386b](https://github.com/jkrumm/basalt-ui/commit/75a386b677518e24fc7b13ab7c49c3469c1aaa9d))
+* let the managed pre-commit pass when every staged file is lint-ignored ([dbaa6bc](https://github.com/jkrumm/basalt-ui/commit/dbaa6bce1ea0eefbecee0666ea94c656f81d5b18))
+
+
+### Features
+
+* connect a series across null rows ([3c14ed1](https://github.com/jkrumm/basalt-ui/commit/3c14ed18583710c9b742cd5fa0139c75c06beb4d))
+* cursor dots for marks-drawn series and edge rules on bands ([27bb5b2](https://github.com/jkrumm/basalt-ui/commit/27bb5b228e6212f9e86737aa7868ed375fd66cda))
+* dashed tooltip swatches for reference and dashed series ([5938eb8](https://github.com/jkrumm/basalt-ui/commit/5938eb859fb571a527394b157ab47614406b5444))
+* let a store field take a fallback derived at the call site ([3c12371](https://github.com/jkrumm/basalt-ui/commit/3c12371536a73b45418b1f75ff3479fa4012bd23))
+* reference lines name themselves in the legend ([b49ae5b](https://github.com/jkrumm/basalt-ui/commit/b49ae5bb0317aa99f02e33bcb72f5f493351ddd9))
+* tooltipFormat on the DualPanel bar and top specs ([bde88fe](https://github.com/jkrumm/basalt-ui/commit/bde88fe59de3cdc931a94ed52a696cec3987ab86))
+
 # [2.3.0](https://github.com/jkrumm/basalt-ui/compare/v2.2.0...v2.3.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 | 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 | 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,73 @@ 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.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/…`.
+
+- `createLocalStore` fields take `use({ fallback })`: a call-site default (e.g. a prop-derived
+  leader) that applies only while the field is unset and is never persisted, so a reset returns to
+  it. Replace a store rebuilt per prop with it. `createSearchStore` fields do not take it yet.
+- The managed lefthook oxlint step passes `--no-error-on-unmatched-pattern`, so a commit whose
+  staged files are all in `ignorePatterns` no longer fails; a real lint error still does. Picked up
+  through the extended preset.
+
+- `ChartTooltipRow` takes `swatch: 'solid' | 'dashed'`. A series with `dash: 'dashed'` now lists a
+  dashed swatch in its own tooltip row on `CartesianChart`, `Lines`, `Bars` and `DualPanel` (it was
+  solid while the legend and the line were dashed), and a `tooltip.rows` entry sets it itself. A
+  `color` per point needs no new option: `tooltip.rows(d)` already receives the datum, so the row's
+  `color` can be a function of it (garmin-health `recovery-trend-chart.tsx`, its `Zone` row). argo:
+  `garmin-health/charts/stress-chart.tsx` (the dashed `Overnight` line).
+- `RefLine.legend: { label, mark? }` gives a reference line its own legend entry (the line's color,
+  dashed as `dashed`, role `reference`; a toggle hides the line, keyed by its index in `refLines`; series keys starting `__ref-` are reserved and throw in dev), so a threshold needs no always-`null`
+  series. argo `strength-tracker/charts/weekly-volume-chart.tsx`: delete `LANDMARK_LEGEND` and put
+  `legend: { label: 'MEV' }` on the three `refLines`.
+- `DualPanelBar.tooltipFormat` and `DualPanelProps.top.tooltipFormat` format the tooltip rows while
+  `format` keeps the axis ticks (default: `format`; `formatValue` still wins per row). argo
+  `strength-tracker/charts/momentum-chart.tsx`: drop the separate `formatValue` copy of the axis format.
+- `ChartSeries.cursorValue: (d) => number | null` gives a series drawn from your own `marks` a cursor
+  dot: the y at each datum, shown while the cursor is on that x, in the series color. Pass a series
+  with `getValue: () => null` (no tooltip row) and the mark stays yours. argo
+  `astro-window/charts/sky-panorama.tsx` (the sun track).
+- `ZoneSpec.edge` (`side: 'top' | 'bottom' | 'both'`) and `XZoneSpec.edge` (`'start' | 'end' | 'both'`)
+  draw a rule along the band's boundary, with `color`, `dashed` and `width`. A bound at the plot edge
+  (infinite, outside the domain, or an omitted x bound) draws none. argo
+  `astro-window/charts/night-timeline-chart.tsx`: the shooting-window `rect` + two `ruleX` become one
+  `xZones` entry with `edge: { side: 'both', color: VX.accent, width: 2 }`.
+- `ChartSeries.gaps: 'break' | 'connect'` (`Lines`; default `'break'`, today's behaviour). `'connect'`
+  draws the line, and its `area`, through the series' non-null points only, so a series that is null
+  on most shared x values is one continuous line instead of dots and stubs. Markers stay on real
+  points; the cursor and tooltip read the value at the hovered x (no value, no row). argo
+  `strength-tracker/charts/relative-progression-chart.tsx` and `one-rm-trend-chart.tsx`: set
+  `gaps: 'connect'` on each lift's series.
+- Not added: a per-datum `fill` for the engine's `rect`. `@tanstack/charts` 1.1.0 types `RectOptions.fill`
+  as a `string`; its `color` channel resolves through the chart's own color scale, which `marks` cannot
+  reach. Keep one `rect` per fill bucket (argo `astro-window/charts/sky-panorama.tsx`, skyglow).
+- The night-timeline lines can use `chartCurve(s.curve ?? 'monotone')` from 2.3.0 unchanged; nothing
+  is missing there.
+
 ## 2.3.0 — optional-safe chart props, `chartCurve`, zone-coloured area
 
 - Every optional prop of `ChartState`, `ChartSeries`, `AxisConfig`, the tooltip config and the chart

package/agent/rules/basalt-state.md

@@ -24,7 +24,7 @@ State a control reads or writes is a field on a store; the URL wins over localSt
 - 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. [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/configs/lefthook.yml

@@ -37,9 +37,12 @@
 pre-commit:
   parallel: true
   commands:
+    # `--no-error-on-unmatched-pattern`: oxlint exits 1 ("No files found to lint") when EVERY staged
+    # file is excluded by `ignorePatterns` (a consumer's `scripts/`), failing a commit that touches
+    # only ignored files. A real error in a non-ignored staged file still fails.
     oxlint:
       glob: '*.{ts,tsx,js,jsx}'
-      run: bunx oxlint {staged_files}
+      run: bunx oxlint --no-error-on-unmatched-pattern {staged_files}
     # `css` is load-bearing, not tidiness: oxfmt formats stylesheets, so without it a CSS-only
     # commit passes the hook and then fails the same check in CI. `oxlint` above deliberately
     # stops at JS — it has nothing to say about CSS.

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":"AAyCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,WAAW,CAAA;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAcxC,OAAO,KAAK,EAAe,aAAa,EAAgB,YAAY,EAAE,MAAM,UAAU,CAAA;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,cAAc,CAAA;AAI1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IACxC;IACE,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAC3B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAC3B,CAAA;AAIL,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,SAAS,IAAI;IACtD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EACd,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC7B,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IACzD,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IACnC,uFAAuF;IACvF,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,KAAK,CAAC,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,EAAE,CAAC,GAAG,SAAS,CAAA;IAC/D;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EACb,CAAC,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GACxE,SAAS,CAAA;IACb;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CAC3C,CAAA;AAID,MAAM,MAAM,wBAAwB,CAAC,KAAK,GAAG,SAAS,IAAI;IACxD,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AAqYD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,QAAQ,GAAG,SAAS,EAAE,EACrE,SAAS,EACT,KAAK,EACL,cAAc,EACd,WAAW,EACX,OAAO,EACP,QAAc,EACd,SAAS,GACV,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAwUjE"}
+{"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/CartesianChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CartesianChart.d.ts","sourceRoot":"","sources":["../../src/charts/CartesianChart.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAiB,YAAY,EAAa,MAAM,OAAO,CAAA;AAGnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAKpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEvE,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG;IACxB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,sDAAsD;IACtD,KAAK,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;CACjC,CAAA;AAgCD,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG;IACzB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC3B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,IAAI,CACnC,mBAAmB,CAAC,CAAC,EAAE,MAAM,CAAC,EAC9B,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CACpE,GAAG;IACF,qCAAqC;IACrC,MAAM,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,CAAA;IACjC,6FAA6F;IAC7F,OAAO,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,mBAAmB,CAAA;IACnD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,YAAY,CAuErE;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAC/C,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,GAC7C,YAAY,CAmBd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAChD,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC/B,YAAY,CAEd"}
+{"version":3,"file":"CartesianChart.d.ts","sourceRoot":"","sources":["../../src/charts/CartesianChart.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAiB,YAAY,EAAa,MAAM,OAAO,CAAA;AAGnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAKpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEvE,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG;IACxB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,sDAAsD;IACtD,KAAK,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;CACjC,CAAA;AAgCD,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG;IACzB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC3B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,IAAI,CACnC,mBAAmB,CAAC,CAAC,EAAE,MAAM,CAAC,EAC9B,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CACpE,GAAG;IACF,qCAAqC;IACrC,MAAM,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,CAAA;IACjC,6FAA6F;IAC7F,OAAO,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,mBAAmB,CAAA;IACnD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,YAAY,CAuErE;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAC/C,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,GAC7C,YAAY,CAwBd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAChD,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC/B,YAAY,CAEd"}

package/dist/charts/CartesianChart.js

@@ -1,7 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useId, useMemo, useState } from "react";
 import { useInChartCard } from "./card-context.js";
-import { compileCartesian } from "./compile.js";
+import { compileCartesian, refLegendSeries } from "./compile.js";
 import { ChartEngine, idPrefixOf } from "./host.js";
 import { ChartLegend, legendEntries } from "./legend.js";
 import { INITIAL_WIDTH, useChartSize } from "./sizing.js";
@@ -97,10 +97,14 @@ function CartesianRung(props) {
     (ctx) => compileCartesian({ ...stable, ...ctx }),
     [stable]
   );
+  const legendSeries = useMemo(
+    () => [...stable.series, ...refLegendSeries(stable.refLines)],
+    [stable.series, stable.refLines]
+  );
   return /* @__PURE__ */ jsx(
     ChartShell,
     {
-      series,
+      series: legendSeries,
       compile,
       ariaLabel,
       ...legend !== void 0 && { legend },

package/dist/charts/DualPanel.d.ts

@@ -10,8 +10,10 @@ export type DualPanelBar<T> = {
     positive: string;
     /** The fill below zero. */
     negative: string;
-    /** Tick and tooltip formatter. */
+    /** Tick formatter, and the tooltip's too unless `tooltipFormat` is given. */
     format: (v: number) => string;
+    /** The tooltip row's formatter. Default: `format`. */
+    tooltipFormat?: ((v: number) => string) | undefined;
     /** The tooltip row's value, for a unit or a decimal `format` cannot carry. */
     formatValue?: ((v: number, d: T) => string) | undefined;
     /** Default `'auto'`: a symmetric `[-maxAbs, maxAbs]` from the data, rounded to nice ticks. A tuple
@@ -28,6 +30,8 @@ export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<Ca
     top?: {
         domain?: readonly [number, number] | 'auto' | undefined;
         format?: ((v: number) => string) | undefined;
+        /** The lines' tooltip formatter. Default: `format`. */
+        tooltipFormat?: ((v: number) => string) | undefined;
     } | undefined;
     /**
      * Shades the band between two top lines (by key), where both are visible. `aboveFill` colours the

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,kCAAkC;IAClC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC7B,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;KAC7C,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,CA4Md"}
+{"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"}