@joewinke/jatui 0.26.0 → 0.27.0

package/CLAUDE.md

@@ -56,6 +56,7 @@ Then import:
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
 | `Button` | Styled button with variants | `variant`, `size`, `loading`, `disabled`, `onclick` |
+| `ProgressButton` | Multi-phase async submit button (upstreamed from the JAT IDE): walks through the **named phases** of the work (`phases: [{key,label}]` in order) instead of a blank spinner — spinner + current phase label with shimmer, a fill bar that advances to `(index+1)/N`, disabled while busy, green check-flash on `success`. Caller owns the state machine (`phase` / `success`). Renders through the shared `Button`, so `class` composes with join patterns. | `phase?` (null = idle), `phases?: Phase[]`, `idleLabel?`, `success?`, `successLabel?`, `variant?`, `size?`, `disabled?`, `type?`, `class?`, `onclick?`, `children` |
 | `Badge` | Status/label badge | `variant`, `size`, `children` (snippet) |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
@@ -65,7 +66,10 @@ Then import:
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
 | `Sparkline` | Inline mini chart | `data: number[]`, `width`, `height`, `color` |
 | `LazyImage` | Image with lazy loading + placeholder | `src`, `alt`, `placeholder` |
+| `Empty` | Zero-state surface — v1 thin copy/children block still works; pass `title` for the v2 hero layout (upstreamed from the IDE's EmptyState): named `glyph` (11 curated Heroicons), `size` (sm/md/lg), `pulse` (reduced-motion gated, tinted with `--color-primary`), `icon` snippet override, CTA `actions` snippet, `description`, extra `children` below. | `title` (opts into v2), `description`, `glyph`, `size`, `pulse`, `icon`/`actions` (snippets), `copy`, `class`, `children` |
+| `ErrorState` | Standard "this failed" surface (upstreamed from the IDE's ErrorState) — error-token themed icon, optional Retry button, extra `actions`, collapsible `details` block for raw error output. Centered card mirroring `Empty` v2. | `title`, `message`, `details`, `retryLabel`, `onRetry`, `size`, `actions` (snippet) |
 | `HunkDiffView` | Side-by-side diff with line numbers, red/green backgrounds, strikethrough on removed lines, inline word-level highlights via the `diff` lib. Used for reviewing YAML/text changes per hunk. | `oldText: string \| null`, `newText: string \| null`, `unified?: boolean` |
+| `JumpToLatest` | "Jump to latest" pill for streaming transcripts (pairs with `createStickToBottom`) — shows when the reader has scrolled away from the live edge, badges the unread arrival count, jumps + resumes following on click. Position inside a `relative` wrapper that also holds the scroll element. | `visible`, `unreadCount`, `label`, `onclick` |
 | `ContextMenu` | Floating right-click (or programmatic) action menu, positioned via `use:floating` at a cursor point. Real `<button>`s, per-item `icon`/`variant`/`disabled`, dividers, click-outside + Escape dismiss, arrow-key/Home/End roving nav (focus starts on the first item). Items may declare `submit: SubmitConfig` to POST to a SvelteKit form action instead of (or in addition to) `onSelect` — a hidden `<form>` is built, requestSubmit()ed, then removed, so `use:enhance` fires exactly like a regular form submission. **Items also support nested `submenu: ContextMenuItem[]`** (right-side popover on hover/focus/ArrowRight, chevron indicator, ArrowLeft/Escape closes just the submenu — submenus open on parent-item focus **without stealing focus into the submenu**; ArrowRight is the explicit "enter the submenu" gesture) **and inline `content: Snippet`** (replaces the default icon+label row with an arbitrary widget — the wrapping button still closes the menu, so widgets that shouldn't must `event.stopPropagation()`). `autoFocus` (default true) can be set false to suppress auto-focus of the first item on open. | `open` (bindable), `x`, `y`, `items: ContextMenuItem[]`, `header?`, `zIndex?`, `autoFocus?`, `onClose?` |
 | `ContextMenuTrigger` | Wraps content with the standard right-click + "⋯" touch affordance, backed by `ContextMenu`. Use instead of hand-rolling `oncontextmenu` + a kebab button per row/card. | `items: ContextMenuItem[]`, `children` (snippet), `header?`, `triggerLabel?`, `hideButton?`, `zIndex?`, `class?` |
 | `Tooltip` | Component-shaped wrapper around the shared `use:tooltip` action — for cases where you can't easily add an attribute to the target element (wrap a chip / badge / icon in the tooltip instead). Warm/cool window + `aria-describedby` are shared with the action. Prefer `use:tooltip` directly when you own the element. | `content: string`, `placement?`, `delayMs?`, `disabled?`, `display?`, `children` (snippet) |
@@ -75,6 +79,7 @@ Then import:
 | `BatchJobTable` | Generic queue runner (harvested from vid-gen's BatchGenerator) — `<BatchJobTable generics T>` over bindable `JobRow<T>[]`; host supplies async `run(data, {signal, attempt, reportProgress})`. Concurrency cap, optional per-run `processLimit` (quota budget), rolling-average ETA, per-row status badge / progress / elapsed / retry / skip / cancel / reorder — each cell a snippet override (`statusCell`, `progressCell`, `elapsedCell`, `actionsCell`), host data columns via `headers` + `cells`, extra toolbar content via `toolbar`. Uses `showToast` / `showConfirm` (mount `ToastHost` + `ConfirmDialog`). Exposes `start()`/`pause()`/`cancel()`/`retryFailed()`/`clearFinished()`. Pure scheduling helpers exported too (`nextJobsToStart`, `moveJob`, `summarizeJobs`, `toJobRows`). | `jobs` (bindable), `run`, `concurrencyLimit?` (3), `processLimit?`, `autoStart?`, `notify?`, `confirmDestructive?`, `onJobDone?`, `onJobFailed?`, `onBatchDone?` |
 | `QuotaMeter` | "312 / 500 credits · resets in 4h 10m" bar — warning tint at `warnAt`, error at 100%. Presentational; the host owns the ledger. | `used`, `limit`, `resetsAt?`, `label?`, `unit?`, `warnAt?` (0.8), `size?` |
 | `VariantMatrixPicker` | Category/option chip grid for building a combinatorial variant matrix (harvested from vid-gen's FrameVariantGenerator, presets stripped — caller-supplied `categories`). Each category tab shows a live selection count and an additive/multiplicative badge: multiplicative selections cartesian-multiply the total, additive ones stack flat onto every combination. Live combination count in the footer; algebra exported separately as pure functions (`generateCombinations`, `countCombinations`, `variantCategoryMode`, `findVariantOption`, `generateVariantFilename`). | `categories: VariantCategory[]`, `selected` (bindable `VariantSelection`), `forceMode?`, `showCount?` (true), `countLabel?`, `onChange?`, `class?` |
+| `BottomSheet` | Mobile bottom sheet (upstreamed from the JAT IDE — jatui-rl7w6.2): drag handle with pointer capture, backdrop close, optional header. `snap='dual'` enables the inspector pattern — peek → expanded snap heights with flick-momentum release (fast flick ≥ 0.5 px/ms wins over position; flick down from peek dismisses) and `visualViewport` keyboard avoidance so content clears the soft keyboard. | `open` (bindable), `title?`, `zIndex?` (70), `fullHeight?`, `snap?` ('single'\|'dual'), `peekFraction?` (0.4), `expandedFraction?` (0.9), `onclose?`, `children` (snippet) |
 
 ### Tables (subpath: `jatui/table`)
 
@@ -82,7 +87,15 @@ Requires peer `@tanstack/table-core`. `import { DataTable, flexRender, columnRes
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
-| `DataTable` | TanStack-backed table (generic over the row type): sorting, selection, client pagination, skeleton. Grid-mode hooks per jat `docs/design/datatable-virtualisation-group-rows.md` §3.3: `getRowId` (keys selection/expansion/api by id, renders `data-row-id`); controlled sort — `bind:sorting`, `initialSorting`, `manualSorting` (caller pre-sorts `data`), `onSortingChange(next, {field, shiftKey})`; `rowProps(row, item)` → `{class, attrs, onclick, oncontextmenu, ondragover, ondrop}` (`attrs` for `data-nav-id`, aria); `onRowClick(row, e)` (skips clicks on interactive children); `headerProps(columnId)`; `expandedRow` snippet `(row, {colspan})` — click/Enter toggles unless `isExpanded(row)` makes it controlled; `empty` snippet; `variant` `zebra`/`plain`/`unstyled` + `tableClass`; `bind:api` → `orderedRowIds()`, `scrollToRow(id)`. Sortable headers are keyboard-operable. | `data`, `columns`, `sortable`, `selectable`, `paginated`, `getRowId?`, `sorting?` (bindable), `rowProps?`, `onRowClick?`, `expandedRow?`, `empty?`, `variant?`, `api?` (bindable) |
+| `DataTable` | TanStack-backed table (generic over the row type): sorting, selection, client pagination, skeleton. Grid-mode hooks per jat `docs/design/datatable-virtualisation-group-rows.md` §3.3: `getRowId` (keys selection/expansion/api by id, renders `data-row-id`); controlled sort — `bind:sorting`, `initialSorting`, `manualSorting` (caller pre-sorts `data`), `onSortingChange(next, {field, shiftKey})`; `rowProps(row, item)` → `{class, attrs, onclick, oncontextmenu, ondragover, ondrop}` (`attrs` for `data-nav-id`, aria); `onRowClick(row, e)` (skips clicks on interactive children); `headerProps(columnId)`; `expandedRow` snippet `(row, {colspan})` — click/Enter toggles unless `isExpanded(row)` makes it controlled; `empty` snippet; `variant` `zebra`/`plain`/`unstyled` + `tableClass`; `bind:api` → `orderedRowIds()`, `scrollToRow(id)`. Sortable headers are keyboard-operable. **Grid mode** (all opt-in; default markup is snapshot-gated against 0.26.0): `groupBy: GroupLevel[]` renders `groupRows` header rows (`data-group-key` = `::`-joined path), `bind:collapsed` / `onCollapsedChange`, `groupLabel`, `groupHeader` snippet `(group, {toggle, colspan, collapsed})` renders the header CELLS; `stickyHeader` + `stickyGroupHeaders` (offset by the thead height and `--dt-group-row-h`); `maxHeight` makes the table its own scroller (else sticky clips horizontal overflow); `virtual={{ createRowWindow, estimateRowSize, overscan, threshold, scrollRoot }}` windows the body with spacer rows that keep zebra parity — pass `createRowWindow` from `jatui/virtual` so `jatui/table` never needs the virtual-core peer; read once at mount; `pinnedRowIds`; `ariaGrid` → `grid`/`treegrid`, `aria-selected`, `aria-level`, `aria-rowindex`/`rowcount` (windowed tables always get the rowindex pair); `ariaLabel`. One TanStack instance per mount, updated with `setOptions` — a selection or sort change re-renders no cell. | `data`, `columns`, `sortable`, `selectable`, `paginated`, `getRowId?`, `sorting?` (bindable), `rowProps?`, `onRowClick?`, `expandedRow?`, `empty?`, `variant?`, `api?` (bindable), `groupBy?`, `collapsed?` (bindable), `groupHeader?`, `stickyHeader?`, `stickyGroupHeaders?`, `maxHeight?`, `virtual?`, `pinnedRowIds?`, `ariaGrid?` |
+
+### Graph (subpath: `jatui/graph`)
+
+Requires peer `@xyflow/svelte` (install it — the IDE's build breaks on `import … from 'jatui/graph'` without it). `import { GraphCanvas, JatuiNode, type GraphCanvasApi } from 'jatui/graph'`.
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `GraphCanvas` | Svelte Flow wrapper with the DaisyUI → `--xy-*` theme bridge — read-only status graphs AND node editors. Props mirror `SvelteFlow`'s own names, so xyflow docs apply. Custom `nodeTypes` merge over `{ jatuiNode }` (**keep the object stable** — xyflow re-mounts every node when its identity changes); `edgeTypes`/`defaultEdgeOptions`; editing (`isValidConnection`, `onconnect`, `onbeforedelete`/`ondelete`, `deleteKey`, `snapToGrid`/`snapGrid`, `connectionMode`, key options, `zoomOnDoubleClick`); events forwarded verbatim (`onnodeclick`/`onNodeClick` alias, `onnodecontextmenu`, `onnodedragstart`/`stop`, `onedgeclick`, `onpaneclick`, `onselectionchange`, `onmoveend`). `bind:viewport` stays live even when seeded `undefined`. `children` renders INSIDE `<SvelteFlow>` (Panels, anything calling `useSvelteFlow()`). `bind:this` exposes `api: GraphCanvasApi` (`fitView`, `zoomTo` — centre-anchored, `getZoom`, `setCenter`, `screenToFlowPosition`, `getViewport`; all no-ops before init) plus the same methods (except `fitView`, whose name the prop owns) directly. The no-at-rest-shadow rule strips the node **wrapper** shadow inside `.graph-canvas` only — draw status glows on an inner element. xyflow has no `onnodedoubleclick`: handle `ondblclick` inside the node component. Use `$state.raw` for nodes/edges. | `nodes`/`edges` (bindable), `viewport` (bindable), `nodeTypes?`, `edgeTypes?`, `readonly?`, `fitView?`, `minimap?: boolean \| MiniMapProps`, `background?: false \| BackgroundProps`, `controls?`, `minZoom?`/`maxZoom?`, `children?` |
 
 ### Media
 
@@ -104,6 +117,20 @@ Requires peer `@tanstack/table-core`. `import { DataTable, flexRender, columnRes
 
 **Types:** `VideoChapter`, `VideoSpeakerTurn`, `VideoTranscriptSegment`, `VideoBookmark`, `VideoWaveform`, `VideoSpeakerTalkTime`. `VideoWaveform.peaks` normalise against their own max, so 0–1, 0–99 and 0–255 arrays all work.
 
+### Table (subpath: `jatui/table`)
+
+`DataTable` (TanStack table-core), `flexRender`, `columnResize` and two column-management companions (upstreamed from the jat IDE, audit jat-1alfp U9):
+
+| Component / util | Purpose | Key Props |
+|-----------|---------|-----------|
+| `ManageColumnsDropdown` | Show/hide + drag-reorder table columns, with a search filter and a last-visible-column lock (can't hide the final column). Panel renders with `position:fixed` viewport coordinates by default (`appendToBody`, SearchDropdown pattern) so it can never be clipped by an `overflow-x:auto`/`overflow:hidden` ancestor — the clipping bug the IDE copy still has (jat-hwt1h). Consumer owns the state: pass `columnOrder` + `hiddenColumns` and apply the `onReorder`/`onToggleVisibility` callbacks; `onReset` adds a "Reset to default" footer. | `columnOrder`, `hiddenColumns: Set<string>`, `getLabel`, `onReorder`, `onToggleVisibility`, `onReset?`, `label?`, `appendToBody?` (default true) |
+| `columnStorage` | localStorage persistence for column settings — `saveColumnSettings(key, settings)` / `loadColumnSettings(key, allColumnIds)`. Load merges newly added column ids at the end and drops removed ones; returns null when nothing saved (or corrupt/absent localStorage — SSR-safe silent no-ops). | — |
+
+```typescript
+import type { ColumnSettings } from 'jatui/table'
+import { saveColumnSettings, loadColumnSettings } from 'jatui/table'
+```
+
 ### Meetings (subpath: `jatui/meet`)
 
 Real-time video-meeting UI. `livekit-client` is an **OPTIONAL peer dep**, lazily
@@ -145,12 +172,30 @@ import { loadLiveKit, isLiveKitAvailable, LiveKitNotInstalledError } from 'jatui
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
+| `PageHeader` | The standard route header (upstreamed from the JAT IDE): uppercase/tracked "instrument label" title + slots for a count chip, subtitle, leading `icon` snippet, right-aligned `actions` cluster, `meta` metrics strip and content below the header row. `sticky` pins it to the top of the scroll container; `size='lg'` for landing screens. All color via `--color-*` tokens; entrance animation reduced-motion gated (`animate`, default off). | `title`, `subtitle?`, `count?`, `size?` ('md'\|'lg'), `sticky?`, `animate?`, `icon?`/`actions?`/`meta?`/`children` (snippets) |
 | `ResizablePanel` | Resizable container | `minWidth`, `maxWidth`, `defaultWidth` |
 | `ResizableDivider` | Drag handle between panels | `onResize` |
 | `InfiniteGrid` | Cursor-paged infinite-scroll grid (from chimaro). `loadMore(cursor, {signal})` resolves `{items, nextCursor, total?}` (`nextCursor: null` = end); cells render through the `renderItem(item, i)` snippet. Change `resetKey` to start over — the in-flight page is aborted and a late page for the old key is dropped. One request in flight; items de-duped by `getKey`; short pages auto-chain until the sentinel leaves the screen; distinct skeleton / empty / exhausted / error(+Retry) states; non-item rows are `overflow-anchor: none` so scroll anchoring can't runaway-load. Scroll root = `root` or nearest scrollable ancestor. Exposes `reset()`/`retry()`. Not virtualized. Pure core: `createInfiniteLoader`. | `loadMore`, `renderItem` (snippet), `getKey?`, `resetKey?`, `columns?` / `minItemWidth?`, `gap?`, `root?`, `loadAhead?` (400px), `skeleton?`/`empty?`/`end?`/`error?` (snippets), `emptyText?`, `endText?`, `onStateChange?` |
 | `InfiniteSearchGrid` | Search box + `InfiniteGrid`. Query is debounced, then becomes the grid's `resetKey` (Enter commits now, Escape clears). Below `minQueryLength` no request is made and `prompt` shows. All other `InfiniteGrid` props pass through. | `search(query, cursor, {signal})`, `renderItem` (snippet), `query` (bindable), `debounceMs?` (300), `minQueryLength?` (0), `placeholder?`, `noResultsText?`/`noResults?`, `prompt?`/`promptText?`, `toolbar?` (snippet) |
 | `SectionNav` | Sticky in-page section index for long single-column pages — vertical rail beside the content on xl+, wrapping chip row above it below xl. Built-in scroll-spy (omit `activeId` and it just works; `bind:activeId` to observe/control — the spy writes back to it): on every observer callback + rAF-throttled scroll/resize it measures ALL sections and activates the last one whose top is at/above the activation line (`activationRatio`, default 0.3 of the scroller height); at the bottom of the page the last section wins. Clicking an item activates it immediately and holds the spy off until the smooth scroll lands (`scrollend`, or 800ms after the last scroll event); reduced-motion scrolls instantly. Pure decision fn exported as `computeActiveSection(rects, viewport, scroll, ratio?)`. Amber dot per `dirtyIds` marks sections holding unsaved edits. `go()` scrolls AND moves focus so keyboard/SR users land where the click did. j/k/Enter via `listNav`. Layout contract: parent is a `flex flex-wrap gap-8 items-start` row, content column `flex-1 min-w-0`; sections need `id` + `scroll-mt-*`. | `sections: {id,label}[]`, `activeId?` (bindable), `dirtyIds?: Set<string>`, `ariaLabel?`, `spy?`, `activationRatio?` (0.3) |
 
+**Windowing (subpath: `jatui/virtual`, optional peer `@tanstack/virtual-core`).** `createRowWindow(opts)` is headless variable-height windowing built on **spacer rows**, not absolute positioning, so it works inside a `<table>` and keeps `table-layout: fixed` and sticky `<thead>`s. It returns reactive `items` (`{index, key, start, size, end, gapBefore, sticky, pinned}`), `paddingTop`, `paddingBottom`, `totalSize` and `windowed`, plus `use:win.anchor` (on the `<tbody>` or list container, whose top is item 0's top) and `use:win.measure={item.key}` (on each item; a shared ResizeObserver re-measures it). Reading a row's height for the first time, or later re-measuring one above the viewport, shifts `scrollTop` by the delta so nothing jumps. The anchor gets `overflow-anchor: none` so native scroll anchoring doesn't correct the shift a second time. The options are reactive getters: `count`, `getKey`, `estimateSize`, `pinned()` (keys kept rendered, e.g. an open editor or exiting row), `stickyIndices()` (a flat list, or one array per level `[projectHdrs, epicHdrs]`; the active header of each level stays rendered, and an inner header never outlives its outer group), and `threshold` (render everything below N; pass it as a getter to make it reactive). Also `scrollRoot` (`'auto'` = the nearest ancestor that really scrolls, else the window; it re-resolves on resize), `overscan` (6), `scrollPaddingStart/End` and `initialViewportSize` (800; used for SSR and first paint). Methods: `scrollToIndex`/`scrollToKey(…, {align})` (queued until mount), `indexOf`, `remeasure()`. Render `item.gapBefore` as a spacer before the item; it is non-zero only when a pinned or sticky item sits outside the slice. Pure policy helpers are exported too (`extractWindowIndices`, `activeStickyIndices`, `layoutWindow`, `findScrollRoot`, `RowWindowEngine`). Demo: `/components/row-window`.
+
+```svelte
+<script>
+  import { createRowWindow } from 'jatui/virtual'
+  const win = createRowWindow({ count: () => rows.length, getKey: (i) => rows[i].id, estimateSize: () => 44 })
+</script>
+<tbody use:win.anchor>
+  <tr style:height="{win.paddingTop}px"></tr>
+  {#each win.items as it (it.key)}
+    {#if it.gapBefore}<tr style:height="{it.gapBefore}px"></tr>{/if}
+    <tr use:win.measure={it.key}>…rows[it.index]…</tr>
+  {/each}
+  <tr style:height="{win.paddingBottom}px"></tr>
+</tbody>
+```
+
 ### Audio & Voice
 
 | Component | Purpose | Key Props |
@@ -237,6 +282,8 @@ const callbacks: AnnotationCallbacks = {
 
 **Shortcut registry** (`createShortcutRegistry()`, or the lazy `getShortcutRegistry()` singleton) — the data source for the overlay, so apps stop hand-wiring a keydown handler plus a separate list for the overlay. Shortcuts register against a **context** and return an unregister fn (return it from `$effect`). Contexts form a stack: `global` is the bottom, `pushContext(name, { modal?, label? })` returns a pop fn, the top context shadows the same combo lower down, and a `modal` context suppresses everything beneath it (including `global`). Handled for you: no firing while typing in text inputs/textarea/select/contenteditable (opt in per shortcut with `allowInInput`), IME composition and `defaultPrevented` events are skipped, `mod` = ⌘ on macOS / Ctrl elsewhere, exact modifier matching (`?` doesn't need `shift`), and macOS Option combos fall back to `event.code`. Per shortcut: `enabled()`, `allowRepeat`, `preventDefault`, `group` (overlay section), `hidden`, `label` (keycap override).
 
+**keyboardScope** (`use:keyboardScope({ 'mod+s': save, … })` or bare `createKeyboardScope(container)`) — the *container-local* complement to the registry's context stack (upstreamed from the JAT IDE): embed-safe shortcuts for a self-contained widget (pane, drawer, embedded panel) inside a busy host page. Ownership is decided from DOM engagement, not a pushed context: a shortcut fires when focus is inside the container, or when the target is body/html AND the most recent pointerdown/focusin (capture-phase) landed inside — the "engaged" heuristic, so a pane owns Delete/mod+Z right after a click without permanently stealing the keys. Never fires while typing in a text-entry element (shares the registry's `isTypingTarget`), even for modifier combos. `comboFor(event)` normalizes a keydown to the handler-map key (fixed `shift,alt,mod` order; `mod` = ⌘/Ctrl; backspace ≡ delete). Use the registry for app keymaps; use keyboardScope inside an embeddable widget that must own a few keys.
+
 ```svelte
 <script>
   import { createShortcutRegistry, KeyboardShortcutsOverlay, SIDEBAR_TOGGLE_KEY } from "jatui"
@@ -252,6 +299,14 @@ const callbacks: AnnotationCallbacks = {
 <KeyboardShortcutsOverlay registry={shortcuts} />
 ```
 
+**Rebinding.** Give a definition an `id` and its `key` (a string or an array of combos) becomes the *default*. The live binding is the user's override: pass `bindings: localStorageBindingStore('app.shortcuts', { migrate? })` (or any `BindingStore`) to `createShortcutRegistry`, then `registry.rebind(id, 'ctrl+shift+n' | [] | null, { onConflict: 'reject' | 'swap' | 'allow' })`, `resetBinding(id)`, `resetAllBindings()`. Stored entries that can't be parsed are never dropped silently: they are warned once and listed by `rejectedBindings()` as `{ id, raw, reason }`. Registered entries re-resolve on every change, so components never re-register. `declare([...])` catalogues ids before their component mounts, and `bindings()` / `binding(id)` list them for a settings page. `await registry.ready` for an async store. Combos are stored canonically. `normalizeCombo('Super+Up')` → `meta+arrowup`; it accepts the IDE's legacy spellings (`Command`/`Win`/`Super`, `Space`, `Up`…). `comboFromEvent(e)` records a binding from a keydown, and `validateCombo(k, { requireModifier })` checks one the user typed. Duplicate `id` in one context throws in dev.
+
+**Conflicts.** `findConflicts(keys, { id?, context? })` lists what a binding would collide with, and `allConflicts({ minSeverity? })` lists every pair among registrations + declarations once (newer side as `source`) — run it with `minSeverity: 'error'` in a test over your catalogue. Kinds: `same-context` (error — one of them is dead), `shadows` / `shadowed-by` (warning — co-active contexts, the upper wins), `modal-blocked` (info — the upper context is modal), `reserved` (browser combos: `mod+t/w/n` error, copy/paste/save/find/… and `mod+b` warning; override with `reserved`, default `BROWSER_RESERVED_COMBOS`). Which contexts can be stacked comes from `contextGraph: { ctx: [contexts it sits above] }` (transitive; `global` is beneath all; without it, non-global contexts only meet `global`). Contexts are modal once pushed `{ modal: true }` or when listed in `modalContexts`. `rebind()` rejects any error-severity conflict (a reserved block even under `swap`), and a successful rebind returns the remaining `conflicts` for display.
+
+**Beyond combos.** `attach()` listens for keydown, keyup and blur. `onRelease(e)` on a definition fires on the keyup of the same *physical* key (`event.code`) after it fired, whatever modifiers remain (push-to-talk); a blur drops pending releases without calling them. `onModifierChange({ alt, ctrl, shift, meta })` (registry option) reports held-modifier changes and resets on blur, so an Alt-held hint layer can't stick. `registerHandler({ context?, handle(e) → boolean, allowInInput?, preventDefault?, describe? })` adds a raw handler (count prefixes, `m<letter>` chords) that runs inside the context walk *after* that context's combos, newest first; returning false continues the walk, a modal suppresses it, it is never rebindable or conflict-checked, and `describe()` rows reach `toSections`. `isTypingTarget: (target, event) => boolean` replaces the typing test (compose with the exported `isTypingTarget`). `pushContext(name, { layer })` — frames sort by layer, then push order, so an app-level surface at `layer: 1` stays above routes that mount later. `pushContext(name, { modal: true, passthrough: ['global.sidebar', 'mod+\\'] })` lets listed ids/combos from beneath still fire (raw handlers never pass). `formatBinding(id)` → live keycap or null (for hints, tooltips, menu accelerators). `toSections({ includeDeclared: true })` also lists `declare()`d ids nothing has registered yet. `handleKeyup(e)` / `handleBlur()` dispatch by hand.
+
+**Dialogs join the stack.** `Modal`, `Drawer`, `BottomSheet`, `ConfirmModal`, `ConfirmDialog` and `InputDialog` take `shortcutRegistry` (+ optional `shortcutContext` name); while open they push a modal context so page shortcuts don't fire behind them.
+
 **Sidebar convention: `SIDEBAR_TOGGLE_KEY` = `mod+\`** (Ctrl+\ / ⌘\). Do NOT use Ctrl+B: Chrome reserves it (bookmarks bar). Also avoid Ctrl+T/W/N, which the browser keeps. The overlay owns `?` by default, so don't register it — but if a host app already has its own global `?` handler registered first, the overlay respects `event.defaultPrevented` and stays out of the way (one overlay per keypress). Helpers: `formatShortcut(def | "mod+k", platform?)` → `⌘K` / `Ctrl+K`, `isTypingTarget(el)`, `parseShortcutCombo`, `detectShortcutPlatform`.
 
 ### Maps (Google Maps)
@@ -299,6 +354,39 @@ if (await showConfirm({ title: "Delete?", body: warnBody, danger: true })) { ...
 ## Utilities
 
 ```typescript
+// Streaming-transcript auto-scroll (upstreamed from the JAT IDE — jatui-rl7w6.3).
+// Reader-aware follow: follows the live edge ONLY while the reader is at it;
+// upward scroll/wheel/keys/selection suspend following; coalesces sticks per
+// frame; surfaces an unread count for a JumpToLatest pill.
+import { createStickToBottom, type StickState, type StickController } from "jatui"
+import { JumpToLatest } from "jatui"
+// const scroller = createStickToBottom({ onState: (s) => (stick = s) })
+// <div use:scroller.action class="overflow-y-auto">…</div>
+// <JumpToLatest visible={!stick.atBottom} unreadCount={stick.unread} onclick={scroller.jumpToLatest} />
+// scroller.requestStick()    // gated follow (streamed content)
+// scroller.requestStick(true) // force (the reader's own send, errors)
+
+// ANSI terminal output → HTML (upstreamed from the JAT IDE — jatui-rl7w6.3).
+// SGR colors incl. 24-bit/256-color, bold/dim/italic/underline/reverse, WCAG
+// contrast auto-foreground on backgrounds, URL linkification, ECMA-48 strict
+// stripAnsi (text after bare two-byte escapes survives), incremental stateful
+// parsing and per-line hierarchy classes for <pre>-based terminal surfaces.
+import { ansiToHtml, ansiToHtmlStateful, ansiToHtmlWithLinks, ansiToHtmlWithHierarchy, linkifyUrls, stripAnsi, classifyLine, parseOutputLines, createDefaultAnsiState } from "jatui"
+import type { AnsiState, ParsedLine } from "jatui"
+
+// Mobile gesture kit (upstreamed from the JAT IDE — jatui-rl7w6.2).
+// swipe: one-finger horizontal drag with deadzone/directional-ratio gating,
+// rubber-banded offset emission and distance-or-velocity commit.
+import { swipe } from "jatui"     // use:swipe={{ onSwipeLeft, onSwipeRight, onOffsetChange, allowLeft, allowRight, enabled }}
+import type { SwipeOptions } from "jatui"
+// longpress: press-and-hold (touch, haptic where supported) + right-click (mouse)
+// context affordance; cancels on movement, swallows the synthesized tap after firing.
+import { longpress } from "jatui" // use:longpress={{ onLongPress(detail), duration? (450), moveTolerance? (10), enabled? }}
+import type { LongPressOptions, LongPressDetail } from "jatui"
+// snapFlick: pure snap-point + flick-momentum math behind BottomSheet dual mode.
+import { resolveSnapTarget, keyboardInsetPx, clampSnapHeight, FLICK_VELOCITY_PX_MS } from "jatui"
+import type { SnapName, SnapHeight, SnapInput, SnapResult } from "jatui"
+
 // Video playback advisors (ported from extension-library — mos-5lzns.27).
 // Pure functions: no DOM, no settings reads, never write playbackRate. The
 // player's rate composer / resume-at-sentence / audio-graph tasks consume
@@ -322,6 +410,16 @@ import { pollOperation, PollTimeoutError } from "jatui"
 //   { intervalMs, timeoutMs, backoff, signal, onProgress })  — rejects on timeout / abort / thrown check
 import { formatElapsed, rollingAverage, estimateRemainingMs } from "jatui"
 
+// Recurring poll with coordinated exponential backoff (upstreamed from the JAT IDE — jatui-rl7w6.5).
+import { createPollLoop } from "jatui"
+// const poller = createPollLoop({ name: 'agents', intervalMs: 3000, maxIntervalMs: 60_000,
+//   tick: () => store.fetch() })   // resolve false / throw = failure → backoff; true/void = ok
+// poller.start(); poller.stop(); poller.reset()
+// Skips ticks while document.hidden (resumes the moment the tab is visible), never
+// overlaps ticks, backs off exponentially with ±jitter capped at maxIntervalMs.
+// Framework-free; the recurring-poll companion to pollOperation (one-shot).
+import { computeBackoffDelayMs } from "jatui"   // pure delay math (doubles, cap 2^6×, floored at intervalMs)
+
 // Variant combination algebra (jatui-m4uz3.8) — pure functions behind VariantMatrixPicker.
 import { generateCombinations, countCombinations, type VariantCategory, type VariantSelection } from "jatui"
 // VariantCategory — { id, label, icon?, mode?: 'multiplicative' | 'additive', options: VariantOption[] }
@@ -329,6 +427,13 @@ import { generateCombinations, countCombinations, type VariantCategory, type Var
 // VariantSelection — { [categoryId]: string[] }  (selected option ids per category)
 // generateCombinations(categories, selected, { forceMode? }) → [{ modifierIds, prompt, options }]
 
+// Grouped render list (jatui-u6d4e.2) — pure, also on 'jatui/table'. Flattens filtered+sorted rows
+// into header|row items for a table/row window; rows keep input order, groups ordered by level.compare.
+// collapsed = Set of "::"-joined path keys ("jat::jat-vte6e"); showHeader=false renders rows ungrouped.
+import { groupRows, groupPathKey, type GroupLevel, type GroupedItem } from "jatui"
+// groupRows(rows, [{ key: t => t.project }, { key: t => t.epic }], { getRowId, collapsed, label? })
+//   → { kind:'group', key, path, depth, label, rows, count, collapsed } | { kind:'row', row, id, depth, groupPath, position }
+
 // Date formatting
 import { formatRelativeTime, formatDate, formatShortDate, formatDateTime } from "jatui"
 

package/dist/actions/keyboardScope.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Embed-safe keyboard shortcuts for a self-contained widget (pane, drawer,
+ * embedded panel) living inside a busy host page. Upstreamed from the JAT
+ * IDE (adoption audit U6, jatui-rl7w6.5; originally jat-nvxkt in JST).
+ *
+ * Modeled on wayflow's `dom/src/keyboard.ts` `createKeyboardScope`: a shortcut
+ * fires when focus is inside the container, OR when the event target is
+ * body/html (the state right after clicking empty space, or before anything
+ * has ever been focused) AND the most recent pointerdown/focusin landed
+ * inside the container. That "engaged" heuristic means a pane owns
+ * Delete/mod+Z immediately after a click, without permanently stealing
+ * those keys from the rest of the host page.
+ *
+ * Relationship to the shortcut registry (`createShortcutRegistry`): the
+ * registry resolves shortcuts against a *named context stack* for page-level
+ * keymaps and carries the `?` overlay. keyboardScope is the container-local
+ * complement — it decides ownership from DOM engagement (what was last
+ * clicked/focused), not from a pushed context, so a self-contained widget
+ * needs no cooperation from its host. Use the registry for app keymaps;
+ * use keyboardScope inside an embeddable widget that must own a few keys.
+ *
+ * Usage — Svelte action, handler map keyed by normalized combo:
+ *
+ *   <div use:keyboardScope={{
+ *     'mod+s': () => save(),
+ *     'mod+e': () => toggleEdit(),
+ *     'escape': () => close(),
+ *   }}>...</div>
+ *
+ * Usage — bare factory, for code that isn't a Svelte action (e.g. wiring the
+ * predicate into an existing keydown handler):
+ *
+ *   const scope = createKeyboardScope(container)
+ *   if (scope.isInScope(event.target)) { ... }
+ *   scope.destroy()
+ *
+ * Combo strings combine modifiers in the fixed order shift, alt, mod, then
+ * the base key, joined by "+" (e.g. "shift+mod+z"). 'mod' resolves to Cmd on
+ * Mac, Ctrl elsewhere. Backspace normalizes to the same combo as Delete.
+ *
+ * Matching wayflow's own `interaction.ts` dispatcher, shortcuts never fire
+ * while the event target is a text-entry element (input/textarea/select
+ * /contenteditable — non-text input types like checkbox/button are exempt)
+ * — even for modifier combos — so typing in an input never triggers the
+ * widget's shortcuts.
+ */
+export interface KeyboardScope {
+    isInScope: (target: EventTarget | null) => boolean;
+    destroy: () => void;
+}
+export declare function createKeyboardScope(container: HTMLElement): KeyboardScope;
+export type KeyboardScopeHandlers = Record<string, (event: KeyboardEvent) => void>;
+/** Normalizes a keydown event into a combo string, e.g. "mod+z", "delete". */
+export declare function comboFor(event: KeyboardEvent): string;
+export declare function keyboardScope(node: HTMLElement, handlers: KeyboardScopeHandlers): {
+    update(next: KeyboardScopeHandlers): void;
+    destroy(): void;
+};

package/dist/actions/keyboardScope.js

@@ -0,0 +1,110 @@
+/**
+ * Embed-safe keyboard shortcuts for a self-contained widget (pane, drawer,
+ * embedded panel) living inside a busy host page. Upstreamed from the JAT
+ * IDE (adoption audit U6, jatui-rl7w6.5; originally jat-nvxkt in JST).
+ *
+ * Modeled on wayflow's `dom/src/keyboard.ts` `createKeyboardScope`: a shortcut
+ * fires when focus is inside the container, OR when the event target is
+ * body/html (the state right after clicking empty space, or before anything
+ * has ever been focused) AND the most recent pointerdown/focusin landed
+ * inside the container. That "engaged" heuristic means a pane owns
+ * Delete/mod+Z immediately after a click, without permanently stealing
+ * those keys from the rest of the host page.
+ *
+ * Relationship to the shortcut registry (`createShortcutRegistry`): the
+ * registry resolves shortcuts against a *named context stack* for page-level
+ * keymaps and carries the `?` overlay. keyboardScope is the container-local
+ * complement — it decides ownership from DOM engagement (what was last
+ * clicked/focused), not from a pushed context, so a self-contained widget
+ * needs no cooperation from its host. Use the registry for app keymaps;
+ * use keyboardScope inside an embeddable widget that must own a few keys.
+ *
+ * Usage — Svelte action, handler map keyed by normalized combo:
+ *
+ *   <div use:keyboardScope={{
+ *     'mod+s': () => save(),
+ *     'mod+e': () => toggleEdit(),
+ *     'escape': () => close(),
+ *   }}>...</div>
+ *
+ * Usage — bare factory, for code that isn't a Svelte action (e.g. wiring the
+ * predicate into an existing keydown handler):
+ *
+ *   const scope = createKeyboardScope(container)
+ *   if (scope.isInScope(event.target)) { ... }
+ *   scope.destroy()
+ *
+ * Combo strings combine modifiers in the fixed order shift, alt, mod, then
+ * the base key, joined by "+" (e.g. "shift+mod+z"). 'mod' resolves to Cmd on
+ * Mac, Ctrl elsewhere. Backspace normalizes to the same combo as Delete.
+ *
+ * Matching wayflow's own `interaction.ts` dispatcher, shortcuts never fire
+ * while the event target is a text-entry element (input/textarea/select
+ * /contenteditable — non-text input types like checkbox/button are exempt)
+ * — even for modifier combos — so typing in an input never triggers the
+ * widget's shortcuts.
+ */
+import { isTypingTarget } from '../utils/keyboardShortcutRegistry';
+export function createKeyboardScope(container) {
+    const contains = (target) => target instanceof Node && container.contains(target);
+    // Capture phase so scoping is decided before any handler can stopPropagation.
+    let engaged = false;
+    const track = (event) => {
+        engaged = contains(event.target);
+    };
+    document.addEventListener('pointerdown', track, true);
+    document.addEventListener('focusin', track, true);
+    return {
+        isInScope: (target) => contains(target) ||
+            ((target === document.body || target === document.documentElement) && engaged),
+        destroy() {
+            document.removeEventListener('pointerdown', track, true);
+            document.removeEventListener('focusin', track, true);
+        },
+    };
+}
+const isMac = typeof navigator !== 'undefined' && /Mac/.test(navigator.platform ?? '');
+const KEY_ALIASES = {
+    backspace: 'delete',
+};
+/** Normalizes a keydown event into a combo string, e.g. "mod+z", "delete". */
+export function comboFor(event) {
+    const parts = [];
+    if (event.shiftKey)
+        parts.push('shift');
+    if (event.altKey)
+        parts.push('alt');
+    if (isMac ? event.metaKey : event.ctrlKey)
+        parts.push('mod');
+    const rawKey = event.key.toLowerCase();
+    parts.push(KEY_ALIASES[rawKey] ?? rawKey);
+    return parts.join('+');
+}
+export function keyboardScope(node, handlers) {
+    let current = handlers;
+    const scope = createKeyboardScope(node);
+    // Bound to document, not the node: the body/html-targeted branch of
+    // isInScope only ever sees events whose target IS document.body/.html,
+    // which never bubble through the container.
+    function onKeydown(event) {
+        if (!scope.isInScope(event.target))
+            return;
+        if (isTypingTarget(event.target))
+            return;
+        const handler = current[comboFor(event)];
+        if (!handler)
+            return;
+        event.preventDefault();
+        handler(event);
+    }
+    document.addEventListener('keydown', onKeydown);
+    return {
+        update(next) {
+            current = next;
+        },
+        destroy() {
+            document.removeEventListener('keydown', onKeydown);
+            scope.destroy();
+        },
+    };
+}

package/dist/actions/listNav.d.ts

@@ -61,6 +61,29 @@
  *     if (nav.handleKeydown(e)) return;
  *     // ...page-specific shortcuts
  *   }
+ *
+ * Windowed / virtualised lists (`getOrderedIds` + `revealItem`):
+ *
+ *   A windowed list only renders the rows near the viewport, so a DOM query
+ *   stops j/k at the window edge and `*` misses every unrendered row. Pass
+ *   `getOrderedIds` and the controller navigates over that id list instead;
+ *   the DOM query (or `getItems`) is then only used to find the elements that
+ *   ARE rendered, so the focus/selection classes can be painted on them.
+ *   When the cursor lands on an id with no rendered element, `revealItem(id)`
+ *   is called to scroll it into the window; the focus class is painted once
+ *   the row mounts (same frame if the reveal renders synchronously, otherwise
+ *   on a following animation frame, or on the next `refresh()`).
+ *
+ *   <div use:listNav={{
+ *     getOrderedIds: () => table.orderedRowIds(),
+ *     revealItem: (id) => table.scrollToRow(id),
+ *     onSelect: (el) => openDetail(el.dataset.navId!),
+ *   }}>
+ *     <!-- only the windowed rows, each with data-nav-id -->
+ *   </div>
+ *
+ *   Enter/Space need a rendered element (`onSelect` receives it), so they
+ *   pass through when the focused row has been scrolled out of the window.
  */
 import type { Action } from 'svelte/action';
 export interface ListNavOptions {
@@ -76,8 +99,13 @@ export interface ListNavOptions {
     onSelect?: (item: HTMLElement, index: number) => void;
     /** Fired when Escape is pressed. Default behaviour: clears focus. */
     onEscape?: () => void;
-    /** Fired whenever the focused index changes (including cleared focus). */
-    onFocusChange?: (item: HTMLElement | null, index: number) => void;
+    /**
+     * Fired whenever the focused index changes (including cleared focus). With
+     * {@link getOrderedIds}, `item` is null while the focused row is not
+     * rendered (index is still >= 0); it fires again with the element once the
+     * revealed row mounts. `id` is the focused item's id (null when cleared).
+     */
+    onFocusChange?: (item: HTMLElement | null, index: number, id: string | null) => void;
     /** When true, j at the last item wraps to first (and vice-versa). Default: true. */
     wraparound?: boolean;
     /** Class applied to the currently focused item. Default: `jk-focused`. */
@@ -100,6 +128,21 @@ export interface ListNavOptions {
      * your items use a different attribute (e.g. `data-rule-nav-id`).
      */
     getItemId?: (el: HTMLElement) => string | null | undefined;
+    /**
+     * Return every navigable item id in list order, rendered or not (e.g. a
+     * DataTable's `orderedRowIds()`). When given, it replaces the DOM query as
+     * the source of positions: j/k/G/counts/selection all range over these ids,
+     * and `getItems` / {@link itemSelector} only locate the rendered subset
+     * (matched by {@link getItemId}). Called on every navigation event.
+     */
+    getOrderedIds?: () => readonly string[];
+    /**
+     * Bring an unrendered item into the rendered window (e.g. a DataTable's
+     * `scrollToRow(id)`). Called before an id from {@link getOrderedIds} is
+     * focused when no element for it is rendered. Rendered items are scrolled
+     * with `scrollIntoView` as usual.
+     */
+    revealItem?: (id: string) => void;
 }
 export interface KeyboardShortcut {
     key: string;
@@ -115,6 +158,8 @@ export interface ListNavController {
     clear(): void;
     /** Re-apply the focused class after items change (e.g. after a filter). */
     refresh(): void;
+    /** Id of the focused item (null when nothing is focused or it has no id). */
+    focusedId(): string | null;
     /** Read-only snapshot of selected item ids. */
     selectedIds(): Set<string>;
     /** Toggle selection. With no arg, toggles the focused item. */
@@ -123,7 +168,7 @@ export interface ListNavController {
     setSelection(ids: Iterable<string>): void;
     /** Drop the selection and exit visual mode. */
     clearSelection(): void;
-    /** Toggle select-all of the currently visible items. */
+    /** Select every item (every id from `getOrderedIds` when given, else the rendered items). */
     selectAll(): void;
     /** True while visual-mode (V) is active. */
     isSelecting(): boolean;