@vielzeug/codex 26.10.2 → 26.10.4

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 41 packages. Version: 26.10.1
+> Complete documentation for 41 packages. Version: 26.10.3
 
 ---
 
@@ -16480,7 +16480,7 @@ yarn add @vielzeug/prism
 
 ```ts
 import { createLineChart } from '@vielzeug/prism';
-import '@vielzeug/prism/theme';
+import '@vielzeug/prism/theme.css';
 
 const chart = createLineChart(document.getElementById('chart')!, {
   a11y: { ariaLabel: 'Revenue by month' },
@@ -16526,12 +16526,14 @@ chart.dispose();
 - **`createSparkline(container, config)`**: minimal inline line, area, bar, or stack chart
 - **`linearScale`, `timeScale`, `bandScale`**: standalone scales with nice tick generation
 - **`ChartHandle.update(data)`**: replace chart data synchronously without coupling to a state library
-- **`setTheme(theme)` / `resetTheme()`**: apply or clear custom colors, font, and grid tokens at runtime
+- **`setTheme(theme, { scope })` / `resetTheme({ scope })`**: apply or clear colors, font, grid, axis, text, and tooltip tokens globally or on one subtree at runtime
+- **Axes on by default**: line, area, and bar charts render both axes with gridlines on the value axis; `xAxis: false` / `yAxis: false` opt out
+- **Animations on by default**: every chart animates entry and updates through one rAF loop, honors reduced motion, and opts out with `transition: false`
 - **Series comparison**: hover or keyboard focus reports every series at the active key in the tooltip, `onHover`, and screen-reader announcements
 - **Keyboard navigation**: arrow keys, `Enter`, and `Escape` on every labelled chart except sparklines
 - **CSS custom properties**: full theme control via `--prism-*` tokens, with dark mode built in
 - **Responsive**: auto-resizes via `ResizeObserver`
-- **Devtools**: `debugChart()` from `@vielzeug/prism/devtools` logs mount/resize/dispose to `console.debug`
+- **`ChartHandle.tap()`**: observe resize and dispose events outside the render path, with zero cost when untapped
 - **`Symbol.dispose`**: explicit resource management following the TC39 proposal
 
 ## Documentation
@@ -16555,24 +16557,22 @@ chart.dispose();
 | `createLineChart()` | Render a line chart | Sync | Line keys must be numbers or dates |
 | `createAreaChart()` | Render an area chart | Sync | Line keys must be numbers or dates |
 | `createBarChart()` | Render grouped or stacked bars | Sync | Stacked negative values are clamped to zero |
-| `createPieChart()` | Render pie, donut, or semi-circle slices | Sync | Event callbacks use slice/index arguments |
+| `createPieChart()` | Render pie, donut, or semi-circle slices | Sync | `onHover` receives `null` when the pointer leaves |
 | `createRadarChart()` | Compare values across 3+ axes, such as hero stats | Sync | Events report a whole axis, not one series |
 | `createSparkline()` | Render an inline line, area, bar, or stack | Sync | Omitted `a11y` makes the chart decorative |
 | `linearScale()` | Create a numeric scale | Sync | `nice` defaults to `true` |
 | `timeScale()` | Create a date scale | Sync | Invalid dates produce an invalid domain |
 | `bandScale()` | Create a categorical scale | Sync | Unknown categories map to `0` and warn in development |
-| `setTheme()` | Set Prism CSS custom properties | Sync | Values apply to `document.documentElement` |
-| `resetTheme()` | Remove Prism theme overrides | Sync | Removes only properties managed by `setTheme()` |
+| `setTheme()` | Set Prism CSS custom properties | Sync | Writes to `document.documentElement` unless `scope` is given |
+| `resetTheme()` | Remove Prism theme overrides | Sync | Clears only properties `setTheme()` wrote, on the same target |
 | `seriesColor()` | Resolve a series palette color | Sync | Palette indexes wrap after eight colors |
-| `debugChart()` | Log chart lifecycle events | Sync | Import from `@vielzeug/prism/devtools` |
 
 ## Package Entry Point
 
 | Import | Purpose |
 | --- | --- |
 | `@vielzeug/prism` | Chart factories, scales, theme helpers, errors, and public types |
-| `@vielzeug/prism/theme` | Default CSS custom properties and dark-mode values |
-| `@vielzeug/prism/devtools` | Optional `debugChart()` lifecycle logging |
+| `@vielzeug/prism/theme.css` | Default CSS custom properties and dark-mode values |
 
 ## Chart Factories
 
@@ -16846,18 +16846,23 @@ const scale = bandScale({ domain: ['A', 'B'], range: [0, 200] });
 ### `setTheme()`
 
 ```ts
-function setTheme(theme: PrismTheme): void;
+function setTheme(theme: PrismTheme, options?: ThemeScope): void;
 ```
 
-Sets Prism color, font, and grid custom properties on `document.documentElement`.
+Sets Prism theme custom properties as inline styles on `options.scope` when given, otherwise on `document.documentElement`. Inline values outrank every stylesheet rule, including dark-mode selectors.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `theme` | `PrismTheme` | Tokens to write; omitted keys are left untouched |
+| `options.scope` | `HTMLElement` | Subtree to theme instead of `:root`; charts inside it resolve their `var(--prism-*)` lookups against these values |
 
 ### `resetTheme()`
 
 ```ts
-function resetTheme(): void;
+function resetTheme(options?: ThemeScope): void;
 ```
 
-Removes every custom property managed by `setTheme()`.
+Removes every custom property `setTheme()` can set from `options.scope` (default `documentElement`). Scoped and global calls are independent targets.
 
 ### `seriesColor()`
 
@@ -16876,11 +16881,16 @@ interface ChartHandle {
   readonly disposalSignal: AbortSignal;
   readonly disposed: boolean;
   readonly el: SVGSVGElement;
+  tap(handler: (event: PrismEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
   update(data: TData): void;
   dispose(): void;
   [Symbol.dispose](): void;
 }
 
+type PrismEvent =
+  | { readonly height: number; readonly type: 'resize'; readonly width: number }
+  | { readonly type: 'dispose' };
+
 interface ChartMargin {
   top: number;
   right: number;
@@ -16901,6 +16911,8 @@ type ChartA11y =
 
 `update()` renders synchronously and throws `PrismRenderError` after disposal. Omitting `a11y` makes the SVG decorative with `aria-hidden="true"`.
 
+`tap()` observes runtime behavior outside the render path: it receives `resize` and `dispose` events (see `PrismEvent`). It returns an unsubscribe function; pass `options.signal` to detach automatically. Handler errors are swallowed, and tapping a disposed handle returns a no-op unsubscribe.
+
 ---
 
 ### Data types
@@ -16967,9 +16979,10 @@ interface BaseChartConfig {
   onClick?: (event: ChartEvent) => void;
   onHover?: (event: ChartEvent | null) => void;
   tooltip?: boolean | TooltipConfig;
-  transition?: TransitionConfig;
-  xAxis?: XAxisConfig;
-  yAxis?: YAxisConfig;
+  transition?: TransitionOption; // motion is on by default; false renders synchronously
+  // Omitted renders the axis with defaults (value axis with gridlines); false suppresses it.
+  xAxis?: XAxisConfig | false;
+  yAxis?: YAxisConfig | false;
 }
 
 interface LineChartConfig extends BaseChartConfig {
@@ -16995,8 +17008,8 @@ interface PieChartConfig
   innerRadius?: number;
   cornerRadius?: number;
   padPixels?: number;
-  onClick?: (slice: PieSliceConfig, index: number) => void;
-  onHover?: (slice: PieSliceConfig | null, index: number | null) => void;
+  onClick?: (event: PieEvent) => void;
+  onHover?: (event: PieEvent | null) => void;
 }
 
 interface RadarChartConfig
@@ -17022,12 +17035,12 @@ interface SparklineConfig {
   cornerRadius?: number;
   curve?: 'linear' | 'monotone' | 'step';
   fillOpacity?: number; // overrides --prism-spark-fill-opacity (area variant)
-  onClick?: (index: number, value: number) => void;
-  onHover?: (index: number | null, value: number | null) => void;
+  onClick?: (event: SparklineEvent) => void;
+  onHover?: (event: SparklineEvent | null) => void;
   padPixels?: number;
   showEndPoint?: boolean; // default true: dot on the latest value (line, area)
   strokeWidth?: number;
-  transition?: TransitionConfig;
+  transition?: TransitionOption; // motion is on by default; false renders synchronously
 }
 ```
 
@@ -17061,6 +17074,12 @@ interface PieSliceConfig {
   label?: string;
 }
 
+interface PieEvent {
+  index: number;
+  originalEvent: Event;
+  slice: PieSliceConfig;
+}
+
 interface RadarAxisConfig {
   key: string;
   label: string;
@@ -17095,6 +17114,12 @@ interface StackSegment {
   color?: string;
   label?: string;
 }
+
+interface SparklineEvent {
+  index: number;
+  originalEvent: Event;
+  value: number;
+}
 ```
 
 A custom radar `tooltip.render` receives `datum.meta` with `axis`, `values`, and the default `text`.
@@ -17142,12 +17167,18 @@ interface LegendConfig {
 type LegendPosition = 'bottom' | 'left' | 'right' | 'top';
 
 interface TransitionConfig {
-  duration?: number;
-  easing?: EasingFn | 'ease-in' | 'ease-in-out' | 'ease-out' | 'linear';
-  preference?: 'always' | 'never' | 'system';
-  stagger?: number;
+  duration?: number; // ms per lane; default 300
+  easing?: EasingName | EasingFn;
+  preference?: 'always' | 'never' | 'system'; // 'system' (default) skips reduced-motion
+  stagger?: number; // ms per bar (bar) or series (radar); ignored elsewhere
 }
 
+// Motion is on by default. `false` renders every update synchronously,
+// `true` uses the chart defaults, or pass a config to tune them.
+type TransitionOption = TransitionConfig | boolean;
+
+type EasingName = 'ease-in' | 'ease-in-out' | 'ease-out' | 'back-out' | 'expo-out' | 'linear';
+
 type EasingFn = (t: number) => number;
 ```
 
@@ -17206,27 +17237,23 @@ type PieVariant = 'donut' | 'pie' | 'semi';
 type SparklineVariant = 'area' | 'bar' | 'line' | 'stack';
 
 interface PrismTheme {
+  axisColor?: string; // --prism-axis-color
   colors?: string[];
   fontFamily?: string;
   gridColor?: string;
   gridOpacity?: number;
+  textColor?: string; // --prism-text-color
+  textColorSecondary?: string; // --prism-text-color-secondary
+  tooltipBg?: string; // --prism-tooltip-bg
+  tooltipBorder?: string; // --prism-tooltip-border
+  tooltipColor?: string; // --prism-tooltip-color
 }
-```
-
-## Devtools
-
-### `debugChart()`
-
-```ts
-function debugChart(handle: T, options?: DebugChartOptions): T;
 
-interface DebugChartOptions {
-  label?: string; // log prefix; defaults to 'chart', producing [prism:chart]
+interface ThemeScope {
+  readonly scope?: HTMLElement;
 }
 ```
 
-Logs mount, resize, and disposal events to `console.debug` and returns the same handle. Import it and `DebugChartOptions` from `@vielzeug/prism/devtools`.
-
 ## Errors
 
 ### `PrismError`
@@ -17245,7 +17272,7 @@ Every chart needs a container element with defined dimensions and the theme CSS:
 
 ```ts
 import { createLineChart } from '@vielzeug/prism';
-import '@vielzeug/prism/theme';
+import '@vielzeug/prism/theme.css';
 
 const container = document.querySelector('#chart')!;
 const chart = createLineChart(container, {
@@ -17610,16 +17637,18 @@ chart.update([
 ```ts
 createPieChart(container, {
   data,
-  onHover: (slice, index) => {
-    // slice/index are null on mouseleave
-    if (slice) console.log(slice.label, slice.value);
+  onHover: (event) => {
+    // event is PieEvent | null (null on mouseleave)
+    if (event) console.log(event.index, event.slice.label, event.slice.value);
   },
-  onClick: (slice, index) => {
-    console.log('clicked', slice.label);
+  onClick: (event) => {
+    console.log('clicked', event.index, event.slice.label);
   },
 });
 ```
 
+`PieEvent` provides `index`, the hovered/clicked `slice` (`PieSliceConfig`), and the `originalEvent` (`MouseEvent` or `KeyboardEvent`).
+
 ## Radar Charts
 
 `createRadarChart` compares several values on one shape, such as a hero's stats. Each series supplies values keyed by `axis.key`:
@@ -17725,25 +17754,29 @@ spark.update([12, 18, 14, 22, 30]);
 
 ### Event Hooks
 
-Sparklines use simplified hooks: index-based rather than full `ChartEvent`. With a hook set, a marker follows the hovered value:
+Sparklines use simplified hooks: `SparklineEvent` rather than full `ChartEvent`. With a hook set, a marker follows the hovered value:
 
 ```ts
 const spark = createSparkline(container, {
   data: [10, 20, 30],
-  onHover: (index, value) => {
-    // index/value are null on mouseleave
-    if (index !== null) console.log(`Hovering point ${index}: ${value}`);
+  onHover: (event) => {
+    // event is SparklineEvent | null (null on mouseleave)
+    if (event) console.log(`Hovering point ${event.index}: ${event.value}`);
   },
-  onClick: (index, value) => {
-    console.log(`Clicked point ${index}: ${value}`);
+  onClick: (event) => {
+    console.log(`Clicked point ${event.index}: ${event.value}`);
   },
 });
 ```
 
+`SparklineEvent` provides `index`, the hovered/clicked `value`, and the `originalEvent`.
+
 > **Note:** Sparklines have no keyboard navigation. Label one with `a11y.ariaLabel` only when the trend carries meaning, and state the key value in surrounding text.
 
 ## Axes and Grid
 
+Both axes render by default: the value axis (y on vertical charts, x on horizontal ones) carries gridlines, the category axis does not. Set `xAxis: false` or `yAxis: false` to suppress one. An explicit config is used verbatim:
+
 ```ts
 {
   xAxis: {
@@ -17842,11 +17875,17 @@ const chart = createLineChart(container, {
 - `values`: every series at the same key (line, area, and bar charts)
 - `originalEvent`: the raw `MouseEvent` or, for keyboard navigation, `KeyboardEvent`
 
-> **Pie and radar events differ**: pie hooks receive `(slice: PieSliceConfig, index: number)`, and radar hooks receive a `RadarEvent` describing an axis. See [`PieChartConfig`](./api.md#chart-configurations) and [`createRadarChart()`](./api.md#createradarchart).
+> **Pie, radar, and sparkline events differ**: pie hooks receive a `PieEvent` (`index`, `slice`, `originalEvent`), sparkline hooks a `SparklineEvent` (`index`, `value`, `originalEvent`), and radar hooks a `RadarEvent` describing an axis. See [`PieChartConfig`](./api.md#chart-configurations) and [`createRadarChart()`](./api.md#createradarchart).
 
 ## Animations
 
-Pass a `transition` config to animate enter and update transitions:
+Every chart animates by default: bars grow from the baseline, line and area
+series rise out of the plot, pie slices sweep in and then morph between values,
+radar polygons reshape, and sparklines tween. Motion runs through one
+`requestAnimationFrame` loop and is skipped when the user prefers reduced motion
+(`preference: 'system'`, the default).
+
+Tune it with `transition`, or turn it off entirely:
 
 ```ts
 {
@@ -17858,14 +17897,23 @@ Pass a `transition` config to animate enter and update transitions:
 }
 ```
 
-All chart types use `requestAnimationFrame`-based interpolation and skip animation when the user prefers reduced motion (`preference: 'system'`, the default). Bar and radar charts apply `stagger` on entry; line, area, and pie charts ignore it.
+```ts
+{ transition: false }  // every update renders synchronously
+{ transition: true }   // the defaults, stated explicitly
+```
+
+Named easings are `'linear'`, `'ease-in'`, `'ease-out'`, `'ease-in-out'`,
+`'expo-out'` (a hard decelerate), and `'back-out'` (a small overshoot); pass a
+`(t: number) => number` for anything else. `stagger` applies to bar-chart bars
+and radar-chart series and is ignored elsewhere — bar charts cap the total
+staggered delay near 400 ms so a long category axis still finishes promptly.
 
 ## Theming
 
 Import the default theme:
 
 ```ts
-import '@vielzeug/prism/theme';
+import '@vielzeug/prism/theme.css';
 ```
 
 ### Programmatic Theme with `setTheme`
@@ -17876,14 +17924,17 @@ Call `setTheme` once at app startup to apply custom tokens programmatically:
 import { setTheme } from '@vielzeug/prism';
 
 setTheme({
+  axisColor: '#94a3b8', // sets --prism-axis-color
   colors: ['#6366f1', '#22d3ee', '#f59e0b', '#10b981'], // replaces --prism-color-1 through -4
   fontFamily: 'Inter, system-ui, sans-serif', // sets --prism-font-family
   gridColor: '#e2e8f0', // sets --prism-grid-color
   gridOpacity: 0.6, // sets --prism-grid-opacity
+  textColor: '#0f172a', // sets --prism-text-color
+  tooltipBg: '#0f172a', // sets --prism-tooltip-bg
 });
 ```
 
-`setTheme` writes to `document.documentElement` style, so it takes precedence over CSS file defaults. Call `resetTheme()` to clear every custom property `setTheme` can set and restore the default theme: useful for a theme-switcher's "reset" action or test teardown:
+`setTheme` writes inline custom properties, so it takes precedence over stylesheet defaults. Call `resetTheme()` to clear every custom property `setTheme` can set and restore the default theme: useful for a theme-switcher's "reset" action or test teardown:
 
 ```ts
 import { resetTheme } from '@vielzeug/prism';
@@ -17891,6 +17942,45 @@ import { resetTheme } from '@vielzeug/prism';
 resetTheme();
 ```
 
+### Theming One Subtree (component libraries)
+
+Pass `scope` to write the tokens onto one element instead of `document.documentElement`. Charts render inside it, so their `var(--prism-*)` lookups resolve against the scoped values without touching `:root` — the hook for apps whose theme lives in a JS palette object (MUI, Chakra, Backstage):
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { useTheme } from '@mui/material/styles';
+import { createBarChart, resetTheme, setTheme, type BarSeriesConfig } from '@vielzeug/prism';
+import '@vielzeug/prism/theme.css';
+
+function CostsChart({ series }: { series: BarSeriesConfig[] }) {
+  const theme = useTheme();
+  const containerRef = useRef(null);
+
+  useEffect(() => {
+    const scope = containerRef.current;
+
+    if (!scope) return;
+
+    // Scoped tokens win over :root inside this subtree and never leak out of it.
+    setTheme(
+      { axisColor: theme.palette.divider, textColor: theme.palette.text.primary },
+      { scope },
+    );
+
+    const chart = createBarChart(scope, { series });
+
+    return () => {
+      chart.dispose();
+      resetTheme({ scope });
+    };
+  }, [series, theme]);
+
+  return ;
+}
+```
+
+A scoped call and a global call are independent: `resetTheme({ scope })` clears only what `setTheme({ scope })` wrote.
+
 ### Custom Theme (CSS)
 
 ```css
@@ -17934,7 +18024,7 @@ Apply tokens to a specific container:
 | `--prism-crosshair-color` | `hsl(215deg 16% 47%)`      | Crosshair line         |
 | `--prism-crosshair-dash`  | `4 2`                      | Crosshair dash pattern |
 
-The palette follows Wong (2011) so adjacent series stay distinguishable under common color-vision deficiencies. Dark mode applies automatically through `prefers-color-scheme` or an `html.dark` class.
+The palette follows Wong (2011) so adjacent series stay distinguishable under common color-vision deficiencies. Dark mode applies through `prefers-color-scheme`, an `html.dark` class, or `data-prism-theme="dark"` on the chart container or any ancestor — the last is the hook for apps that switch theme in JS without owning ``.
 
 Radar charts add their own tokens, each defaulting to a shared one:
 
@@ -18017,22 +18107,27 @@ Call `update()` only while the handle is active. Updating a disposed chart throw
 
 Charts resize automatically when the container dimensions change. Prism uses `ResizeObserver` internally: no manual `resize()` call is needed.
 
-## Devtools
+## Runtime Observation
 
-Import `debugChart()` from the `/devtools` subpath to log a chart's mount, resize, and dispose events to `console.debug`. It's separate from prism's internal validation warnings (those run automatically in development, no import needed) and is tree-shaken from production bundles when this subpath isn't imported.
+Every handle exposes `tap()` to observe runtime behavior — resize and dispose — outside the render path. It reuses the chart's own `ResizeObserver`, so observing costs nothing extra, and handler errors are swallowed: observation never affects chart behavior.
 
 ```ts
 import { createLineChart } from '@vielzeug/prism';
-import { debugChart } from '@vielzeug/prism/devtools';
 
-const chart = debugChart(createLineChart(container, config), { label: 'revenue' });
-// [prism:revenue] mounted
-// [prism:revenue] resized  600×300
-chart.dispose();
-// [prism:revenue] disposed
+const chart = createLineChart(container, {
+  series: [{ data: [{ key: 1, value: 10 }], name: 'Revenue' }],
+});
+const controller = new AbortController();
+const unsubscribe = chart.tap(
+  (event) => {
+    if (event.type === 'resize') console.log('resized', event.width, event.height);
+    if (event.type === 'dispose') console.log('disposed');
+  },
+  { signal: controller.signal },
+);
 ```
 
-> `debugChart()` wraps and returns the same `ChartHandle` unchanged, so it drops into any `create*Chart()` call without restructuring your code.
+`tap()` returns an unsubscribe function; pass `options.signal` to detach automatically instead. The `resize` event carries the new `width`/`height` and fires after the chart re-laid-out; `dispose` fires once, before teardown completes. Tapping a disposed handle returns a no-op unsubscribe. This is separate from prism's internal validation warnings, which run automatically in development and are never part of the public API.
 
 ## Accessibility
 
@@ -18145,7 +18240,7 @@ void source.reload().catch(() => undefined);
 - Call `chart.dispose()` in your framework's unmount/cleanup phase to cancel transitions, disconnect resize observation, and remove DOM nodes.
 - Call `chart.update(data)` from your application state boundary; Prism does not require or own a state library.
 - Set `a11y: { ariaLabel: '…' }` on every chart that conveys meaningful data: unlabelled charts are hidden from assistive technology and receive no keyboard navigation.
-- Wrap a chart with `debugChart()` from the `/devtools` subpath only in development code paths; it is tree-shaken in production.
+- Observe lifecycle with `chart.tap(handler)` rather than polling `chart.disposed` or wrapping the container: it costs nothing when untapped and detaches via `signal`.
 - For SSR, skip chart creation server-side: Prism depends on DOM APIs and `ResizeObserver`. Render charts only after hydration in a `onMounted`/`useEffect` callback.
 
 ### Examples
@@ -28810,7 +28905,7 @@ sync.dispose();
 - **`flush()`**: a full cycle on demand: pull remote changes, then push dirty records; rejects on failure.
 - **Hide-flows**: flushes with `keepalive` on `pagehide`/`hidden`, runs a full cycle on return to the foreground.
 - **`tap()`**: typed `TandemEvent`s for pushes, pulls, invalid records, and warnings.
-- **Lifecycle-owned**: `dispose()`, `disposed`, `disposalSignal`, and `[Symbol.dispose]`.
+- **Lifecycle-owned**: `dispose()`, `disposed`, `disposalSignal`, and `[Symbol.dispose]`; post-dispose `changed()`/`flush()` fail with `TandemDisposedError`.
 
 ## Documentation
 
@@ -28837,7 +28932,7 @@ sync.dispose();
 
 | Import | Purpose |
 | --- | --- |
-| `@vielzeug/tandem` | `createSync`, port/gateway contracts, events, and types |
+| `@vielzeug/tandem` | `createSync`, `TandemError`, `TandemDisposedError`, port/gateway contracts, events, and types |
 
 ## Factories
 
@@ -28874,11 +28969,11 @@ sync.dispose();
 
 | Member | Description |
 | --- | --- |
-| `changed()` | Notes a local change and (re)starts the idle flush timer |
+| `changed()` | Notes a local change and (re)starts the idle flush timer; throws `TandemDisposedError` after `dispose` |
 | `dispose()` | Stops the scheduler, clears the timer, removes document/window listeners |
 | `disposed` | `true` once disposed |
 | `disposalSignal` | `AbortSignal` aborted on dispose |
-| `flush()` | Runs a full cycle: pull, then push; resolves when it completes, rejects when it fails, and is a no-op after `dispose` |
+| `flush()` | Runs a full cycle: pull, then push; resolves when it completes, rejects when it fails, and rejects with `TandemDisposedError` after `dispose` |
 | `tap(handler, options?)` | Observes `TandemEvent`s; returns an unsubscribe function |
 | `[Symbol.dispose]()` | Calls `dispose()` for `using` scopes |
 
@@ -28894,7 +28989,7 @@ The storage seam. The engine owns every rev comparison: it calls your gateway wi
 
 | Member | Contract |
 | --- | --- |
-| `records()` | This device's own records, remote mirrors excluded |
+| `records()` | This device's own records, remote mirrors excluded; sync or async, so a disk-backed gateway can read from storage instead of holding a mirror |
 | `pendingDeletions()` | Tombstones the server has not acknowledged |
 | `applyRecords(records)` | Upsert the given records: already filtered to what the server is ahead on; return the ids that failed validation |
 | `applyDeletions(deletions)` | Remove records deleted remotely |
@@ -28911,11 +29006,11 @@ type TandemEvent =
   | { readonly records: number; readonly type: 'pull' }
   | { readonly records: number; readonly type: 'push' }
   | { readonly message: string; readonly skipped: readonly string[]; readonly type: 'invalid' }
-  | { readonly message: string; readonly type: 'warning' }
+  | { readonly error: unknown; readonly message: string; readonly type: 'warning' }
   | { readonly type: 'dispose' };
 ```
 
-`invalid` reports record ids `applyRecords` refused; `warning` reports a rejected push or transport failure; `pull` and `push` report the record counts applied and pushed. `dispose` fires once, before tappers are cleared.
+`invalid` reports record ids `applyRecords` refused; `warning` reports a rejected push or transport failure and carries the original cause in `error` beside its `message`; `pull` and `push` report the record counts applied and pushed. `dispose` fires once, before tappers are cleared.
 
 ## Types
 
@@ -28945,13 +29040,13 @@ A record paired with the entity (table or kind) it belongs to.
 
 ```ts
 interface SyncDeletion {
-  readonly deletedAt: string;
+  readonly deletedAt?: string;
   readonly entity: string;
   readonly id: string;
 }
 ```
 
-A tombstone: a deletion that travels to the server on the next push.
+A tombstone: a deletion that travels to the server on the next push. `deletedAt` is set by whoever recorded the deletion and the engine never reads it: include it when your server wants the timestamp, omit it otherwise.
 
 ### `SyncState`
 
@@ -28986,7 +29081,23 @@ interface SyncOptions {
 
 ## Errors
 
-Tandem defines no error classes. A rejected `push` is expected input, not a failure: the engine pulls to reconcile and reports it as a `warning` event. `flush()` additionally rejects with the underlying port or gateway error; dirty records survive the failure and retry on the next cycle.
+### `TandemError`
+
+```ts
+class TandemError extends Error {}
+```
+
+Base class for every error Tandem throws; `instanceof TandemError` catches them all in one branch.
+
+### `TandemDisposedError`
+
+```ts
+class TandemDisposedError extends TandemError {}
+```
+
+Thrown by `changed()` and rejected by `flush()` after `dispose()`. A scheduler that stops silently is a sync engine's worst failure: the device keeps editing while nothing uploads, so a leaked handle fails loudly instead.
+
+Beyond disposal, Tandem defines no error classes. A rejected `push` is expected input, not a failure: the engine pulls to reconcile and reports it as a `warning` event. `flush()` additionally rejects with the underlying port or gateway error; dirty records survive the failure and retry on the next cycle.
 
 ### Usage Guide
 
@@ -29084,7 +29195,7 @@ try {
 }
 ```
 
-`flush()` pulls remote changes and then pushes dirty records, so it is also the wiring point for a returning network connection. It rejects when either half fails; the records stay dirty and the next cycle retries them. A `flush()` after `dispose()` resolves as a no-op.
+`flush()` pulls remote changes and then pushes dirty records, so it is also the wiring point for a returning network connection. It rejects when either half fails; the records stay dirty and the next cycle retries them. After `dispose()`, `flush()` rejects with `TandemDisposedError` and `changed()` throws it: a leaked scheduler fails loudly instead of silently stopping. If your reactive wiring can fire after disposal, unsubscribe from your store before disposing the handle, or guard with `sync.disposed`.
 
 Tandem also flushes on its own: it pushes with `keepalive: true` when the tab hides or closes, and runs a full cycle when the tab returns to the foreground. Serve the keepalive push with `navigator.sendBeacon` or a `keepalive` fetch so it survives the tab closing.
 
@@ -29114,7 +29225,7 @@ const unsubscribe = sync.tap((event) => {
       console.warn(event.message, event.skipped);
       break;
     case 'warning':
-      console.warn(event.message); // push rejected, network failure, etc.
+      console.warn(event.message, event.error); // push rejected, network failure, etc.
       break;
   }
 });
@@ -29190,7 +29301,7 @@ useEffect(() => {
 
 ## Working with Other Vielzeug Libraries
 
-- **Vault**: the usual `gateway` backend. Its IndexedDB adapter stores records and the sync-state row; `records()` reads the in-memory mirror, `applyRecords()` writes through the codec.
+- **Vault**: the usual `gateway` backend. Its IndexedDB adapter stores records and the sync-state row; `records()` reads them from storage (it may be async), `applyRecords()` writes through the codec.
 - **Postmaster**: complementary, not overlapping. Postmaster guarantees at-least-once delivery of discrete mutations; Tandem keeps whole-record state in step. Apps that need both run them side by side.
 - **Sentinel**: subscribe to `createNetwork()` and call `sync.flush()` when the connection returns; the cycle pulls and pushes, so remote changes land without waiting for the next foreground return.
 - **Ripple**: `store.subscribe(() => sync.changed())` is the idiomatic wiring for a signal-backed store.
@@ -29350,13 +29461,16 @@ guest.dispose();
 | --- | --- | --- | --- |
 | `hostTavern()` | Host a subject: pairing, command validation, snapshot broadcast | Sync factory | Disposing ends hosting for every guest |
 | `joinTavern()` | Join a session: consume invitation, produce answer | Async | The session lives only after the host accepts and the first snapshot mounts |
-| `TavernHost` | Host handle: invitation, answer acceptance, kick, notice relay | N/A | `dispose()` is idempotent |
-| `TavernGuest` | Guest handle: command forwarding, disposal | N/A | `dispose()` fires `onEnded` exactly once |
+| `TavernHost` | Host handle: invitation, answer acceptance, kick, notice relay, presence tap | N/A | `dispose()` is idempotent; control-plane methods throw `TavernDisposedError` after |
+| `TavernGuest` | Guest handle: command forwarding, rejection tap, disposal | N/A | `dispose()` fires `onEnded` exactly once |
+| `TavernHostEvent` | Host observability union for `tap()`: presence and warnings | N/A | Lifecycle transitions are callbacks, not events |
+| `TavernGuestEvent` | Guest observability union for `tap()`: rejections and warnings | N/A | `onJoined`/`onFailed` fire before the handle exists, so they stay callbacks |
 | `TavernCommands` | The host's command table | N/A | Unknown names and foreign subject ids reject without applying |
 | `TavernSubjects` | Snapshot reading, change and removal subscriptions | N/A | `snapshot` returning `null` skips the broadcast |
 | `TavernNotices` | Wire serialization of local notices | N/A | `toWire` returning `null` skips that notice |
 | `TavernError` | Base error for every Tavern failure | N/A | N/A |
 | `TavernPairingError` | The consumer pasted the wrong kind of pairing code | N/A | N/A |
+| `TavernDisposedError` | A stopped host or ended guest was used again | N/A | N/A |
 
 ## Package Entry Point
 
@@ -29366,7 +29480,7 @@ guest.dispose();
 
 ## `hostTavern(options)`
 
-Creates a mesh host for one subject. Guest commands are validated against the wire shape (Tavern's own protocol), checked against `commands.has` and the `subjectId`, then applied through `commands.apply`: throwing rejects the guest with the error's message. Local changes (via `subjects.onChanged`) re-broadcast `subjects.snapshot()`: coalesced on a microtask; `subjects.onRemoved` ends hosting. Peers are reported through `onPeersChanged`, `onPeerJoined`, and `onPeerLeft`; hosting ending: from removal or `dispose()`: fires `onEnded` exactly once. `relayNotice` serializes through `notices.toWire` and broadcasts to every guest.
+Creates a mesh host for one subject. Guest commands are validated against the wire shape (Tavern's own protocol), checked against `commands.has` and the `subjectId`, then applied through `commands.apply`: throwing rejects the guest with the error's message. Local changes (via `subjects.onChanged`) re-broadcast `subjects.snapshot()`: coalesced on a microtask; `subjects.onRemoved` ends hosting. Presence and transport warnings are reported through `tap()` as `TavernHostEvent`s, and the live peer list is the `peers` getter; hosting ending: from removal or `dispose()`: fires `onEnded` exactly once. `relayNotice` serializes through `notices.toWire` and broadcasts to every guest.
 
 **Returns:** `TavernHost`: the host handle.
 
@@ -29375,10 +29489,6 @@ Creates a mesh host for one subject. Guest commands are validated against the wi
 | `commands` | `TavernCommands` | The host's command table: the same object the host's own UI calls |
 | `notices?` | `TavernNotices` | Notice relay; omit to disable notice broadcasting |
 | `onEnded?` | `() => void` | Hosting ended: the subject was removed or `dispose()` ran. Fires exactly once |
-| `onPeersChanged?` | `(peers: MeshPeer[]) => void` | The full peer list, whenever it changes |
-| `onPeerJoined?` | `(peer: MeshPeer) => void` | A peer joined |
-| `onPeerLeft?` | `(peer: MeshPeer) => void` | A peer left |
-| `onWarning?` | `(message: string) => void` | A transport-level warning |
 | `rtc?` | `MeshRtcFactory` | WebRTC factory: the injection point for tests and non-browser runtimes |
 | `subjectId` | `string` | The id of the hosted subject: guest commands targeting anything else reject |
 | `subjects` | `TavernSubjects` | Snapshot reading, change and removal subscriptions |
@@ -29406,20 +29516,22 @@ const host = hostTavern({
 
 | Member | Returns | Description |
 | --- | --- | --- |
-| `acceptAnswerText(text)` | `Promise` | Consumes a guest's answer code; resolves with the peer once the channel opens. Throws `TavernPairingError` for any unusable code: wrong kind, malformed, expired: with the underlying error as `cause` |
-| `createInvitationText()` | `Promise` | Produces a single-use invitation code, QR-compact when the environment allows |
+| `acceptAnswerText(text)` | `Promise` | Consumes a guest's answer code; resolves with the peer once the channel opens. Throws `TavernPairingError` for any unusable code: wrong kind, malformed, expired: with the underlying error as `cause`. Throws `TavernDisposedError` after `dispose()` |
+| `createInvitationText()` | `Promise` | Produces a single-use invitation code, QR-compact when the environment allows. Throws `TavernDisposedError` after `dispose()` |
 | `disposalSignal` | `AbortSignal` | Aborted when hosting ends |
 | `dispose()` | `void` | Stops hosting: closes every channel and detaches all subscriptions. Idempotent; fires `onEnded` exactly once |
 | `disposed` | `boolean` | Whether hosting has ended |
-| `kick(peerId)` | `void` | Disconnects a peer; the guest observes a disconnect |
-| `relayNotice(notice)` | `void` | Relays one local notice to every guest; the serializer decides what crosses |
+| `kick(peerId)` | `void` | Disconnects a peer; the guest observes a disconnect. Throws `TavernDisposedError` after `dispose()` |
+| `peers` | `readonly MeshPeer[]` | The guests currently connected; current inside a `peer-joined`/`peer-left` tap event |
+| `relayNotice(notice)` | `void` | Relays one local notice to every guest; the serializer decides what crosses. A notice relayed after `dispose()` is dropped: ephemeral UI state with no audience left |
+| `tap(handler, options?)` | `() => void` | Observes `TavernHostEvent`s; returns an unsubscribe function |
 | `[Symbol.dispose]()` | `void` | Delegates to `dispose()`. Enables `using` declarations |
 
 ---
 
 ## `joinTavern(options)`
 
-Consumes an invitation and returns `{ answerText, guest }`. The guest mounts snapshots through `mount(snapshot)`: the first successful mount fires `onJoined`; wire notices are relayed through `notices.fromWire`; rejections through `onRejected`. Channel failures before the first mount fire `onFailed` (once); afterwards, a disconnect or `guest.dispose()` fires `onEnded` with the mounted subject exactly once. `guest.sendCommand` forwards a command to the host with the subject id the consumer routes by. An unusable invitation: wrong kind, malformed, expired: rejects with `TavernPairingError` and leaves no node or subscriptions behind.
+Consumes an invitation and returns `{ answerText, guest }`. The guest mounts snapshots through `mount(snapshot)`: the first successful mount fires `onJoined`; wire notices are relayed through `notices.fromWire`; host rejections and transport warnings arrive through `tap()` as `TavernGuestEvent`s. Channel failures before the first mount fire `onFailed` (once); afterwards, a disconnect or `guest.dispose()` fires `onEnded` with the mounted subject exactly once. `guest.sendCommand` forwards a command to the host with the subject id the consumer routes by. An unusable invitation: wrong kind, malformed, expired: rejects with `TavernPairingError` and leaves no node or subscriptions behind.
 
 **Returns:** `Promise`: the answer code to show back and the guest handle.
 
@@ -29432,8 +29544,6 @@ Consumes an invitation and returns `{ answerText, guest }`. The guest mounts sna
 | `onEnded?` | `(subject: Mounted) => void` | The channel ended after joining; the mounted value is passed for unmounting |
 | `onFailed?` | `(reason: string) => void` | The host never accepted the answer in time |
 | `onJoined?` | `(subject: Mounted) => void` | The mounted value once the first snapshot arrives |
-| `onRejected?` | `(message: string) => void` | The host rejected a forwarded command |
-| `onWarning?` | `(message: string) => void` | A transport-level warning |
 | `rtc?` | `MeshRtcFactory` | WebRTC factory: the injection point for tests and non-browser runtimes |
 
 **Example**
@@ -29448,6 +29558,9 @@ const { answerText, guest } = await joinTavern({
   onEnded: (subject) => unmountMirror(subject.id),
   onJoined: (subject) => mountMirror(subject),
 });
+guest.tap((event) => {
+  if (event.type === 'rejected') console.warn(event.commandId, event.message);
+});
 
 guest.sendCommand('doc-1', 'rename', ['New name']);
 guest.dispose();
@@ -29460,7 +29573,8 @@ guest.dispose();
 | `disposalSignal` | `AbortSignal` | Aborted when the session ends |
 | `dispose()` | `void` | Leaves the session and drops the channel. Fires `onEnded` exactly once |
 | `disposed` | `boolean` | Whether the session has ended: the channel dropped or `dispose()` ran |
-| `sendCommand(subjectId, name, args)` | `void` | Forwards a command to the host. Throws `TavernError` if the session has ended |
+| `sendCommand(subjectId, name, args)` | `void` | Forwards a command to the host. Throws `TavernDisposedError` if the session has ended |
+| `tap(handler, options?)` | `() => void` | Observes `TavernGuestEvent`s; returns an unsubscribe function |
 | `[Symbol.dispose]()` | `void` | Delegates to `dispose()`. Enables `using` declarations |
 
 ---
@@ -29501,16 +29615,23 @@ interface TavernNotices {
   fromWire(wire: unknown): void;
 }
 
+/** Notable host moments reported through `TavernHost.tap`. */
+type TavernHostEvent =
+  | { readonly peer: MeshPeer; readonly type: 'peer-joined' }
+  | { readonly peer: MeshPeer; readonly reason?: string; readonly type: 'peer-left' }
+  | { readonly error: unknown; readonly message: string; readonly type: 'warning' };
+
+/** Notable guest moments reported through `TavernGuest.tap`. */
+type TavernGuestEvent =
+  | { readonly commandId: string; readonly message: string; readonly type: 'rejected' }
+  | { readonly error: unknown; readonly message: string; readonly type: 'warning' };
+
 /** Options for `hostTavern`. */
 interface TavernHostOptions {
   commands: TavernCommands;
   notices?: TavernNotices;
   /** Hosting ended: the subject was removed or `dispose()` ran. Fires exactly once. */
   onEnded?(): void;
-  onPeersChanged?(peers: MeshPeer[]): void;
-  onPeerJoined?(peer: MeshPeer): void;
-  onPeerLeft?(peer: MeshPeer): void;
-  onWarning?(message: string): void;
   rtc?: MeshRtcFactory;
   subjectId: string;
   subjects: TavernSubjects;
@@ -29526,8 +29647,6 @@ interface TavernGuestOptions {
   onEnded?(subject: Mounted): void;
   onFailed?(reason: string): void;
   onJoined?(subject: Mounted): void;
-  onRejected?(message: string): void;
-  onWarning?(message: string): void;
   rtc?: MeshRtcFactory;
 }
 
@@ -29539,7 +29658,9 @@ interface TavernHost {
   dispose(): void;
   readonly disposed: boolean;
   kick(peerId: string): void;
+  readonly peers: readonly MeshPeer[];
   relayNotice(notice: unknown): void;
+  tap(handler: (event: TavernHostEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
   [Symbol.dispose](): void;
 }
 
@@ -29549,6 +29670,7 @@ interface TavernGuest {
   dispose(): void;
   readonly disposed: boolean;
   sendCommand(subjectId: string, name: string, args: readonly unknown[]): void;
+  tap(handler: (event: TavernGuestEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
   [Symbol.dispose](): void;
 }
 ```
@@ -29559,8 +29681,9 @@ interface TavernGuest {
 | --- | --- | --- |
 | `TavernError` | Base class for every Tavern failure: catch this to handle all Tavern errors in one branch | N/A |
 | `TavernPairingError` | A pairing code the consumer pasted could not be used: wrong kind, malformed, expired, or refused by the host. The mesh-level failure is chained as `cause` | `cause` |
+| `TavernDisposedError` | A stopped host (`kick`, `createInvitationText`, `acceptAnswerText`) or an ended guest (`sendCommand`) was used again | N/A |
 
-`TavernPairingError` extends `TavernError`. Every user-input pairing mistake: a garbage code, the wrong code kind, an expired invitation, a refused answer: surfaces as `TavernPairingError` from `acceptAnswerText` and `joinTavern`; transport-level failures (timeouts, connection errors) propagate unchanged. `TavernGuest.sendCommand` throws `TavernError` when the session has already ended.
+`TavernPairingError` and `TavernDisposedError` extend `TavernError`. Every user-input pairing mistake: a garbage code, the wrong code kind, an expired invitation, a refused answer: surfaces as `TavernPairingError` from `acceptAnswerText` and `joinTavern`; transport-level failures (timeouts, connection errors) propagate unchanged. Post-dispose use fails loudly with `TavernDisposedError`, mirroring mesh inside the Tavern error hierarchy.
 
 ### Usage Guide
 
@@ -29605,10 +29728,6 @@ const host = hostTavern({
     has: (name) => name in myStore,
   },
   onEnded: () => updateSessionUi(), // hosting ended: subject removed or disposed
-  onPeersChanged: (peers) => updatePeerList(peers),
-  onPeerJoined: (peer) => toast(`${peer.name ?? 'A guest'} joined`),
-  onPeerLeft: (peer) => toast(`${peer.name ?? 'A guest'} left`),
-  onWarning: (message) => log.warn(message),
   subjectId: 'doc-1',
   subjects: {
     onChanged: (listener) => myStore.onUpdated('doc-1', listener),
@@ -29617,6 +29736,14 @@ const host = hostTavern({
   },
 });
 
+// Presence and transport warnings arrive through tap(); the peer list is a getter.
+host.tap((event) => {
+  if (event.type === 'peer-joined') toast(`${event.peer.name ?? 'A guest'} joined`);
+  if (event.type === 'peer-left') toast(`${event.peer.name ?? 'A guest'} left`);
+  if (event.type === 'warning') log.warn(event.message, event.error);
+  updatePeerList(host.peers); // always current inside a presence event
+});
+
 const invitation = await host.createInvitationText();
 // Show the invitation (QR or copy/paste); the guest returns an answer code.
 await host.acceptAnswerText(answerCode);
@@ -29641,7 +29768,10 @@ const { answerText, guest } = await joinTavern({
   onEnded: (subject) => unmountMirror(subject.id),
   onFailed: (reason) => showError(reason),
   onJoined: (subject) => mountMirror(subject),
-  onRejected: (message) => showToast(message),
+});
+guest.tap((event) => {
+  if (event.type === 'rejected') showToast(event.message); // event.commandId names the command it answers
+  if (event.type === 'warning') log.warn(event.message, event.error);
 });
 
 guest.sendCommand('doc-1', 'rename', ['New name']);
@@ -29668,6 +29798,21 @@ host.relayNotice(localNotice);
 
 **Echo guard**: a tab that both hosts and guests must prevent re-broadcasting a wire-originated notice back to its own guests. One boolean set during `fromWire` and checked in `toWire` is sufficient: the consumer owns this because only they know their local event system.
 
+## Observe with tap()
+
+Both handles expose `tap()` for observability: presence and warnings on the host, rejections and warnings on the guest. Handler errors are swallowed, and the subscription detaches when its signal aborts or the session ends. Lifecycle transitions stay callbacks (`onEnded`, `onJoined`, `onFailed`) because they fire while `joinTavern` is still resolving, before you can hold the handle.
+
+```ts
+import type { TavernGuestEvent, TavernHostEvent } from '@vielzeug/tavern';
+
+host.tap((event: TavernHostEvent) => {
+  if (event.type === 'warning') log.warn(event.message, event.error); // the original error, not just text
+});
+guest.tap((event: TavernGuestEvent) => {
+  if (event.type === 'rejected') log.info(`command ${event.commandId} rejected: ${event.message}`);
+});
+```
+
 ## Handle Pairing Mistakes
 
 Every user-input pairing failure surfaces as `TavernPairingError` from both `acceptAnswerText` and `joinTavern`: a garbage code, the wrong code kind, an expired invitation, or an answer the host refuses. Catch it to show a helpful message instead of a raw error; the underlying mesh failure is chained as `cause` when you need it.
@@ -29688,7 +29833,7 @@ try {
 
 ## Working with Other Vielzeug Libraries
 
-Tavern builds on `@vielzeug/mesh` for the WebRTC transport, pairing codes, and QR-optimized codecs. You do not interact with mesh directly: tavern owns the protocol, but the `rtc` option accepts a `MeshRtcFactory` for testing or non-browser runtimes, and the peer and status types in callbacks are mesh types.
+Tavern builds on `@vielzeug/mesh` for the WebRTC transport, pairing codes, and QR-optimized codecs. You do not interact with mesh directly: tavern owns the protocol, but the `rtc` option accepts a `MeshRtcFactory` for testing or non-browser runtimes, and the peers carried by tap events and the {@link TavernHost.peers} getter are mesh types.
 
 ```ts
 import type { MeshRtcFactory } from '@vielzeug/mesh';