@vielzeug/codex 26.10.1 → 26.10.3

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 41 packages. Version: 26.10.0
+> Complete documentation for 41 packages. Version: 26.10.2
 
 ---
 
@@ -6370,6 +6370,7 @@ list.addEventListener('keydown', (event) => {
 | Zero dependencies | n/a |  |
 | RTL mirroring | Manual | Built in |
 | Grid navigation | Flat only | `createGridNavigation()` |
+| Quick Look grids | Manual Space handling | `createQuickLookGrid()` |
 | Typeahead | Manual | Optional via `typeahead` |
 | Focus restoration | Manual capture | `captureFocus()` / `restoreFocus()` |
 
@@ -6413,6 +6414,7 @@ container.removeEventListener('keydown', onKeydown);
 
 - `createListNavigation()`: pure composite navigation with explicit handled/change results
 - `createGridNavigation()`: two-dimensional arrow-key navigation with fixed or measured columns
+- `createQuickLookGrid()`: tile-grid arrow browsing with a Space preview key for card pickers
 - Orientation and direction support: vertical/horizontal/both with LTR/RTL defaults
 - Dynamic item queries: disabled filtering and loop control
 - Optional typeahead: label-based navigation in key-driven lists
@@ -6439,6 +6441,7 @@ container.removeEventListener('keydown', onKeydown);
 | --- | --- | --- | --- |
 | `createListNavigation()` | Build keyboard navigation for composite widgets | Sync | Apply returned changes to DOM focus |
 | `createGridNavigation()` | Build two-dimensional arrow-key navigation for grids | Sync | Columns resolve per navigation: responsive grids need a getter |
+| `createQuickLookGrid()` | Build arrow-key tile browsing with a preview key for card grids | Sync | The preview key consumes Space: the focused button never activates |
 | `restoreFocus()` | Restore focus to a target or fallback | Sync | Returns `false` when neither target can receive focus |
 | `rescueFocus()` | Re-home focus after the focused element unmounts | Sync | Returns `false` when focus is already on a real element |
 | `captureFocus()` | Capture active focus for one later restoration | Sync | The returned function is one-shot |
@@ -6536,6 +6539,41 @@ Unlike `createListNavigation`, items are not skipped when disabled: skipping in
 
 ---
 
+### `createQuickLookGrid()`
+
+```ts
+function createQuickLookGrid(options: QuickLookGridOptions): QuickLookGrid;
+```
+
+Creates keyboard browsing over a tile grid with a Quick Look key: arrows and Home/End move focus through the items (delegating to `createGridNavigation()`) and `inspectKey` previews the item under the event instead of activating it: the pair every card picker needs.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `QuickLookGridOptions` | Item lookup, active-index source, column resolution, preview key, wrapping, and inspection callback. |
+
+**Returns:** `QuickLookGrid`.
+
+**Example**
+
+```ts
+import { createQuickLookGrid } from '@vielzeug/focus';
+
+const quickLook = createQuickLookGrid({
+  getItems: () => [...grid.querySelectorAll('.tile')],
+  onInspect: (item, index) => previewCard(index),
+});
+
+grid.addEventListener('keydown', (event) => quickLook.handleKeydown(event));
+```
+
+| Member | Return | Contract |
+| --- | --- | --- |
+| `handleKeydown(event)` | `void` | Routes one `keydown`: navigation keys move focus to the reported item, `inspectKey` calls `preventDefault()`/`stopPropagation()` then `onInspect(item, index)`. Unrecognized, already-prevented, composing, modifier, and disabled events pass through. |
+
+`columns` defaults to the rendered row length at the active item (items sharing its top edge), which follows the grid's own responsive wrapping without a media query; supply `columns` to read a track list instead. `getActiveIndex` defaults to the item that is or contains `document.activeElement`; supply it when focus sits on a wrapper around the item. `inspectKey` defaults to `' '` (Space), the platform preview key. The recognizer pairs with a pointer long-press at the call site as the touch counterpart of `onInspect`.
+
+---
+
 ### `restoreFocus()`
 
 ```ts
@@ -6696,6 +6734,20 @@ type GridNavigation = {
   set(index: number): void;
 };
 
+type QuickLookGridOptions = {
+  columns?: GridColumns;
+  disabled?: MaybeGetter;
+  getActiveIndex?: () => number;
+  getItems: () => readonly HTMLElement[];
+  inspectKey?: string;
+  loop?: boolean;
+  onInspect: (item: HTMLElement, index: number) => void;
+};
+
+type QuickLookGrid = {
+  handleKeydown(event: KeyboardEvent): void;
+};
+
 type FocusTarget = HTMLElement | SVGElement | null | undefined | (() => HTMLElement | SVGElement | null | undefined);
 
 type RestoreFocusOptions = {
@@ -6823,6 +6875,25 @@ grid.addEventListener('keydown', (event) => {
 
 `columns` resolves on every navigation, so responsive grids can read a media query and measured grids can read the rendered row length. Clamping is the default; set `loop: true` to wrap moves around the grid's edges by flat index. Items are never skipped when disabled: skipping in two dimensions would break row alignment.
 
+## Browse Card Grids with Quick Look
+
+Use `createQuickLookGrid()` for card pickers, where arrows walk the tiles and Space previews the focused card instead of activating it: the WAI-ARIA Quick Look convention. The primitive pairs the navigation with the preview key, consumes the Space press so the focused button never toggles, and reports the item through `onInspect`:
+
+```ts
+import { createQuickLookGrid } from '@vielzeug/focus';
+
+const tiles = () => [...grid.querySelectorAll('.tile')];
+
+const quickLook = createQuickLookGrid({
+  getItems: tiles,
+  onInspect: (_item, index) => openPreview(index),
+});
+
+grid.addEventListener('keydown', (event) => quickLook.handleKeydown(event));
+```
+
+Leave `columns` unset to measure the rendered row length at the focused tile, which follows the grid's own responsive wrapping without a media query. Supply `getActiveIndex` when focus may sit on a wrapper around the item rather than the item itself. Enter keeps activating the focused tile through its own handler: only the preview key is intercepted. A pointer long-press recognizer is the touch counterpart of `onInspect`; pair them at the call site.
+
 ## Restore Focus
 
 Capture focus before opening a transient surface, then invoke the one-shot restorer when it closes:
@@ -16460,7 +16531,7 @@ chart.dispose();
 - **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
@@ -16484,7 +16555,7 @@ 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` |
@@ -16493,7 +16564,6 @@ chart.dispose();
 | `setTheme()` | Set Prism CSS custom properties | Sync | Values apply to `document.documentElement` |
 | `resetTheme()` | Remove Prism theme overrides | Sync | Removes only properties managed by `setTheme()` |
 | `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
 
@@ -16501,7 +16571,6 @@ chart.dispose();
 | --- | --- |
 | `@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 |
 
 ## Chart Factories
 
@@ -16805,11 +16874,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;
@@ -16830,6 +16904,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
@@ -16839,6 +16915,8 @@ interface Datum {
   key: TKey;
   value: number;
   meta?: Record;
+  dash?: string; // stroke-dasharray for this datum's marks, e.g. '5 5'
+  opacity?: number; // opacity multiplier 0-1 for this datum's marks, e.g. 0.4
 }
 
 type ContinuousDatum = Datum;
@@ -16847,6 +16925,7 @@ interface Series {
   name: string;
   data: TDatum[];
   color?: string;
+  id?: string; // stable data-series-id on the series group; defaults to series-
 }
 
 interface ChartEvent {
@@ -16864,6 +16943,23 @@ interface SeriesValue {
 
 Line and area series use `ContinuousDatum`; bar series accept the complete `Datum` key range. On line, area, and bar charts, `datum`/`series` name the series nearest the pointer, and `values` lists every series at that key (a missing value is `undefined`). `originalEvent` is a `MouseEvent`, or a `KeyboardEvent` for keyboard navigation.
 
+#### Per-datum presentation
+
+`dash` and `opacity` style an individual datum's marks without splitting the series — the usual case is a forecast tail where points past "today" are faded or dashed. They are styling-only: interaction, tooltip, and accessibility behavior never change. Support is per chart type:
+
+| Chart | `dash` | `opacity` |
+| --- | --- | --- |
+| Bar | `stroke-dasharray` on the datum's `rect`, plus a 1px series-color stroke so the dash is visible on the fill. | Element `opacity` on the datum's `rect`. |
+| Line | The segment from this datum to the next (Chart.js-style segments). The last datum's `dash` has no segment and is ignored. | That same segment, plus this datum's own point marker. |
+| Area | The top line's segment from this datum to the next (last datum ignored). The fill keeps the series-level treatment. | Same segment on the top line. |
+| Sparkline, pie, radar | Ignored. | Ignored. |
+
+Consecutive datums that share one `dash`/`opacity` render as a single path run. Absent fields keep the series/theme default, and a series with no presentation fields renders byte-identically to a chart that never used them. See [Forecast / emphasis styling](./usage.md#forecast--emphasis-styling).
+
+#### Stable series identity
+
+`Series.id` is rendered as `data-series-id` on the chart's series group (`.prism-line-series`, `.prism-bar-series`, `.prism-area-series`, `.prism-radar-series`) so tooltips, tests, and external CSS can address a series without positional assumptions. Characters outside `[A-Za-z0-9_-]` are replaced with `-`. It defaults to `series-`, which only stays stable while the series order does — set `id` to survive reordering.
+
 ---
 
 ### Chart configurations
@@ -16904,8 +17000,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
@@ -16931,8 +17027,8 @@ 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;
@@ -16970,6 +17066,12 @@ interface PieSliceConfig {
   label?: string;
 }
 
+interface PieEvent {
+  index: number;
+  originalEvent: Event;
+  slice: PieSliceConfig;
+}
+
 interface RadarAxisConfig {
   key: string;
   label: string;
@@ -17004,6 +17106,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`.
@@ -17122,20 +17230,6 @@ interface PrismTheme {
 }
 ```
 
-## Devtools
-
-### `debugChart()`
-
-```ts
-function debugChart(handle: T, options?: DebugChartOptions): T;
-
-interface DebugChartOptions {
-  label?: string; // log prefix; defaults to 'chart', producing [prism:chart]
-}
-```
-
-Logs mount, resize, and disposal events to `console.debug` and returns the same handle. Import it and `DebugChartOptions` from `@vielzeug/prism/devtools`.
-
 ## Errors
 
 ### `PrismError`
@@ -17380,6 +17474,66 @@ const chart = createAreaChart(container, {
 
 `fillOpacity` overrides the theme opacity for one series.
 
+## Forecast / emphasis styling
+
+A single series often mixes points that should look different — actuals plus a
+forecast tail, or a run that crossed a budget. Rather than split the series,
+carry `dash` and `opacity` on the individual datums. They are styling-only:
+tooltips, hover, keyboard, and screen-reader behavior never change.
+
+For a forecast tail, map a parallel `types` array onto the datums:
+
+```ts
+import { createLineChart } from '@vielzeug/prism';
+
+const types = ['REAL', 'REAL', 'FORECAST', 'FORECAST'];
+
+const chart = createLineChart(container, {
+  series: [
+    {
+      name: 'Cost',
+      data: values.map((value, i) => ({
+        key: months[i],
+        value,
+        ...(types[i] === 'FORECAST' ? { dash: '5 5', opacity: 0.4 } : {}),
+      })),
+    },
+  ],
+});
+```
+
+On a line chart, a datum's `dash` styles the segment from that point to the
+next, so the forecast run renders dashed while the actuals stay solid; its
+`opacity` fades that segment and the point marker. The last datum's `dash` has
+no segment to paint and is ignored. On a bar chart, both fields apply to that
+datum's own bar — a `dash` adds a 1px series-color stroke so the dash reads on
+the filled rect. On an area chart they style the top line only; the fill keeps
+its series-level treatment.
+
+The same mapping fades bars:
+
+```ts
+import { createBarChart } from '@vielzeug/prism';
+
+const chart = createBarChart(container, {
+  series: [
+    {
+      name: 'Cost',
+      data: values.map((value, i) => ({
+        key: months[i],
+        value,
+        ...(types[i] === 'FORECAST' ? { dash: '5 5', opacity: 0.4 } : {}),
+      })),
+    },
+  ],
+});
+```
+
+Because the fields live on the data, a normal `update(newSeries)` re-applies
+them; removing the fields on the next update clears the styling. A series with
+no `dash`/`opacity` anywhere renders exactly as it did before these fields
+existed.
+
 ## Pie, Donut, and Semi-circle Charts
 
 All three variants use `createPieChart` with the `variant` field:
@@ -17459,16 +17613,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`:
@@ -17574,21 +17730,23 @@ 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
@@ -17691,7 +17849,7 @@ 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
 
@@ -17866,22 +18024,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
 
@@ -17994,7 +18157,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
@@ -28659,7 +28822,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
 
@@ -28686,7 +28849,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
 
@@ -28723,11 +28886,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 |
 
@@ -28743,7 +28906,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 |
@@ -28760,11 +28923,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
 
@@ -28794,13 +28957,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`
 
@@ -28835,7 +28998,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
 
@@ -28933,7 +29112,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.
 
@@ -28963,7 +29142,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;
   }
 });
@@ -29039,7 +29218,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.
@@ -29199,13 +29378,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
 
@@ -29215,7 +29397,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.
 
@@ -29224,10 +29406,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 |
@@ -29255,20 +29433,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.
 
@@ -29281,8 +29461,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**
@@ -29297,6 +29475,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();
@@ -29309,7 +29490,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 |
 
 ---
@@ -29350,16 +29532,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;
@@ -29375,8 +29564,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;
 }
 
@@ -29388,7 +29575,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;
 }
 
@@ -29398,6 +29587,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;
 }
 ```
@@ -29408,8 +29598,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
 
@@ -29454,10 +29645,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),
@@ -29466,6 +29653,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);
@@ -29490,7 +29685,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']);
@@ -29517,6 +29715,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.
@@ -29537,7 +29750,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';