@joewinke/jatui 0.38.6 → 0.40.0

package/CLAUDE.md

@@ -22,9 +22,10 @@ Then import:
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
 | `TextInput` | Text input with label, error, icon slots | `label`, `value` (bindable), `placeholder`, `error`, `disabled` |
-| `TextArea` | Multiline text input | `label`, `value` (bindable), `placeholder`, `rows`, `error`, `maxlength` |
+| `TextArea` | Multiline text input. Auto-grow (`autoResize`, or implied by `maxRows`) grows a whole line at a time from `minRows` (default `rows`) to `maxRows`, then scrolls — CSS `field-sizing: content` where supported, row-quantized JS fallback (`textareaRowsHeight`) elsewhere. | `label`, `value` (bindable), `placeholder`, `rows`, `minRows?`, `maxRows?`, `autoResize?`, `error`, `maxlength` |
 | `SelectInput` | Dropdown select | `label`, `value` (bindable), `options: SelectOption[]`, `placeholder` |
 | `PhoneInput` | Intl phone (country dropdown + tel input, outputs E.164; caps national digits per country). Fires `onChange(value)` on every change. | `value` (bindable), `name`, `defaultCountry`, `required`, `onChange` |
+| `PinInput` | One box per character for PINs and one-time codes. Every cell is `autocomplete="one-time-code"` with no maxlength, so SMS autofill / WebOTP (which drop the whole code into the focused cell) fill all cells from the first; paste distributes from the caret; `dir="ltr"`, `inputmode`/`pattern` numeric. Pure helpers: `applyPinCellInput`, `distributePin`, `isPinComplete`. | `value` (bindable), `length` (6), `numeric`, `masked`, `name?`, `autocomplete?` (`one-time-code`), `error`, `label`, `oncomplete` |
 | `ChipInput` | Tag/chip entry with suggestions | `chips` (bindable), `suggestions: SuggestionGroup[]`, `placeholder` |
 | `SearchDropdown` | Searchable dropdown with grouped results, keyboard nav, avatar/initials options. `appendToBody` escapes table/overflow stacking contexts; `variant='chip'` renders a compact pill; `size='sm'` a smaller trigger; `dropup` opens upward; `clearable` shows an × when a value is set. `onSearch` turns the built-in search box into a debounced server-side search hook (fires on open/clear with `''`; internal filtering is bypassed — the consumer updates `groups`). Exposes `openDropdown()`. | `groups: SearchDropdownGroup[]`, `value`, `onChange`, `placeholder`, `variant`, `size`, `dropup`, `appendToBody`, `clearable`, `colorFn`, `onSearch`, `searchDebounceMs` |
 | `FilterDropdown` | Multi-select filter dropdown | `label`, `options: string[]`, `selected: Set<string>` (bindable) |
@@ -56,13 +57,16 @@ Then import:
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
 | `Button` | Styled button with variants | `variant`, `size`, `loading`, `disabled`, `onclick` |
+| `IconButton` | Icon-only button with a **required** `label` (the aria-label; also the tooltip text with `tooltip`). Square/circle, toggle `pressed` (aria-pressed + selection surface), `href` → `<a>`, `variant="overlay"` for chrome over media. Use instead of hand-written `btn btn-sm btn-circle btn-ghost`. | `label`, `variant?` (ghost\|outline\|soft\|primary\|secondary\|error\|overlay), `size?`, `shape?` ('square'\|'circle'), `pressed?`, `tooltip?: boolean \| string`, `href?`, `children` (icon) |
+| `CloseButton` | The one ✕ for dialogs, drawers, sheets, toasts and lightboxes — an IconButton with a built-in X whose stroke is a true CSS pixel at every size. Modal, Drawer, BottomSheet and MediaLightbox use it. | `label?` ('Close'), `size?` ('sm'), `variant?`, `shape?` ('circle'), `tooltip?`, `onclick` |
+| `LinkButton` | Text action styled as a link: `<a>` with `href`, `<button>` without; underline on hover (or always). `external` adds new-tab + rel=noopener + an SR hint. | `href?`, `tone?` (inherit\|primary\|muted\|error), `size?`, `underline?`, `external?`, `disabled?`, `onclick?`, `children` |
 | `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) |
 | `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **Escape is owned by the dialog element itself** (not the window handler) — Modal focuses the dialog on open, so `trapKeys`' stopPropagation would otherwise swallow Esc before the window listener sees it; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?` |
 | `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
-| `Drawer` | Slide-out side panel | `open` (bindable), `side`, `children` (snippet) |
+| `Drawer` | Slide-out side panel. Header ✕ is a `CloseButton`; the body carries `use:scrollEdge` (opt out with `scrollEdge={false}`). | `open` (bindable), `side`, `scrollEdge?`, `children` (snippet) |
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
 | `Sparkline` | Inline mini chart | `data: number[]`, `width`, `height`, `color` |
 | `LazyImage` | Image with lazy loading + placeholder | `src`, `alt`, `placeholder` |
@@ -81,6 +85,37 @@ Then import:
 | `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) |
 
+### Agent surfaces (BoardUI wave 2)
+
+"Agent is working" UI. Free BoardUI items (agent-thinking, agent-log, composer-loader, notification-center) were ported under MIT — see `THIRD_PARTY_NOTICES.md`; AgentTaskList, Questionnaire and ContextMeter are clean-room. Demos: `/components/agent-thinking`, `agent-log`, `agent-task-list`, `questionnaire`, `context-meter`, `notification-center`, `composer-glow`, `streamed-text`.
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `ShimmerText` | A highlight that sweeps across text. Every gradient stop comes from ONE tone via `color-mix`, so any token colour shimmers the same way. Decorative (`.jatui-motion-ambient`): solid text in the tone under `data-motion="calm"`, reduced motion or `active={false}`. | `text?` / `children`, `tone?` ('subtle'\|'default'\|'strong'\|'primary' or any CSS colour), `duration?` (2600 ms), `active?`, `as?`, `class?` |
+| `AgentThinking` | The "agent is working" status line: an indicator, a shimmering label and an elapsed timer. Variants: `wave` / `spin` (3×3 dot comet, pure CSS), `stars` (sparkles), `infinity` (comet on a figure-eight). One `role="status"`; the timer is `aria-hidden`, so screen readers hear the label once. The indicator keeps running on calm (it carries meaning) but stops under reduced motion; the shimmer stops on calm. `startedAt` keeps the true elapsed time when a row re-mounts. | `variant?`, `label?` ('Thinking'), `tone?`, `shimmer?`, `showTimer?`, `startedAt?` (epoch ms), `size?` ('sm'\|'md'), `class?` |
+| `AgentLog` | Streaming agent transcript. Rows grow in: height 0→auto, a brief blur and lift, and a soft fading clip edge (a registered `--jatui-reveal-fade` mask, removed once the row settles). A curved tree guide draws beside each row; the elbow is fixed at 14px so wrapped labels branch at their first line, the trunk is 1px, and it mirrors in RTL. An optional `working` line (AgentThinking "stars") sits at the tail, off the guide. Durations come from `--motion-*` with glide easing. Rows present on first render don't animate, and nothing animates under reduced motion. Fill it with `items` + a `row` snippet, or with `AgentLogRow` children. `bridge` connects a nested list to its parent row's glyph. Pace it with `createRevealTicker`. | `items`, `row` (snippet), `key?`, `working?`, `workingTimer?`, `guide?`, `bridge?`, `appear?`, `live?` (role="log"), `ariaLabel?`, `children?` |
+| `AgentLogRow` | One row of an `AgentLog`: grow-in, soft clip edge and its piece of the guide. Use it directly in children mode. | `first?`, `last?`, `guide?`, `animate?`, `as?` ('li'\|'div'), `class?`, `children` |
+| `AgentTaskList` | An agent's plan as it runs, built on `AgentLog`: tasks → steps. Each task header and each step is one reveal unit. With `revealed` unset a timer paces them (`startDelay` / `stepInterval` / `delayFor`); set it to drive from real events (`Infinity` shows everything). A running task's title shimmers; a done or failed task still reads as running until its steps have appeared. Steps take truncating resource `chips` (icon component or glyph, optional `href`). A step with `sources` branches into a "Sources" row of overlapping site marks: `maxSources` (6) then "+N", a title + domain tooltip on hover/focus, a link when `href` is set, the host's `favicon` URL or a letter tile (no bundled logos). `collapseOnComplete`: `true` folds each finished task once the log moves past it, `'all'` folds them together at the end; failed tasks stay open. The header is a real button (`aria-expanded` / `aria-controls`). `onComplete` fires once. | `tasks: AgentTask[]`, `revealed?`, `stepInterval?`, `startDelay?`, `delayFor?`, `collapseOnComplete?: boolean \| 'all'`, `working?`, `maxSources?`, `sourcesLabel?`, `statusLabels?`, `foldedSummary?`, `onComplete?`, `onToggle?`, `ariaLabel?` |
+| `Questionnaire` | Plan-mode question card shaped like Claude Code's AskUserQuestion: pass a tool call's `questions` (`{question, header?, options: {label, description?, preview?}[], multiSelect?}[]`) straight through; answers come back aligned as `{ values: string[] (option labels), other? }[]`. One question per step, each a `fieldset` / `legend`. Single = radiogroup with roving tabindex (arrows move focus, Space/Enter/click pick, auto-advance after `advanceDelay`); multi = checkbox group. Digit keys 1..N pick and N+1 ticks Other (a component-scoped keydown, never a window listener, ignored while typing). Free-text "Other" row: typing ticks it, Enter sends in single mode. An option's `preview` shows as a monospace pane while it is focused or selected. Footer step pills (jump to any; `aria-current="step"`; answered pills marked) + Previous / Next / Done → `onComplete`. "Question 2 of 4" in the header and in a polite live region. Card height eases between steps on `--motion-move` and content glides in the direction of travel; neither under reduced motion. Pure logic in `agent/questionnaire.ts`. | `questions`, `answers?` (bindable), `step?` (bindable), `onComplete?`, `onChange?`, `allowOther?` (true), `otherLabel?`, `otherPlaceholder?`, `advanceDelay?` (180, `false` disables), `submitLabel?` ('Done'), `nextLabel?`, `previousLabel?`, `title?`, `requireAll?` (true), `disabled?`, `class?` |
+| `ContextMeter` | Context-window meter split by token bucket. Stacked bar coloured from a token palette (primary / secondary / accent / info / success / warning, then `color-mix` variants), with free space as the track. Total line reads "820k / 1M (82%)". `role="meter"` carries valuenow/min/max/valuetext. An `aria-expanded` button reveals a `<table>` breakdown with a "Free space" row; segments with `group` fold under a collapsible header row. Deferred buckets are listed with a dash and left out of both the bar and the total. Warning tint at `warnAt`, error at ≥100% (bar widths rescale to fill exactly 100%). Pairs with `QuotaMeter` for plan limits. | `max`, `segments: {id?, label, tokens, deferred?, color?, group?}[]`, `groups?: {id, label, defaultExpanded?}[]`, `label?` ('Context'), `unit?` ('tokens'), `expanded` (bindable), `warnAt?` (0.8), `collapsible?` (true), `class?` |
+| `NotificationCenter` | Inbox panel: title + "N unread" + "Mark all read"; a tab list with count chips (default All / Mentions / System by `category`; `bind:tab` or uncontrolled `defaultTab`; arrows / Home / End switch tabs). Items are newest first under Today / Yesterday / This week / Earlier headers (`groupNotificationsByDate`, `now` injectable). Roving focus via `createListNav`, scoped to the list: j/k/arrows move, Enter opens → `onOpen(item)` or follows `href`. Opening an item or clicking one of its actions marks it read. The host owns read state (`read`); the component also tracks read ids locally, so it works uncontrolled. The unread dot is announced (sr-only "Unread"). Status glyph or `Avatar`; `<time>` via `formatRelativeTime`, refreshed each minute. Empty state via `Empty` ("You're all caught up"). | `items: NotificationItem[]`, `tabs?: {id, label, filter?}[]`, `tab` (bindable), `defaultTab?`, `onTabChange?`, `onOpen?`, `onMarkRead?(ids)`, `onMarkAllRead?` (omitted → `onMarkRead` gets every unread id), `groupByDate?` (true), `now?`, `maxHeight?` ('32rem'), `title?`, `emptyTitle?`, `emptyDescription?` |
+| `ComposerGlow` | Opt-in ambient rim light around a composer while the agent works: an SVG `<rect rx>` stroke with a pathLength=100 dash laps the box in three layers (crisp line, glow, bloom clipped inside; SVG `feGaussianBlur`, so iOS stays soft); a ResizeObserver keeps the viewBox equal to the px box. Token colours only (info → primary → `color-mix` midpoint → secondary → accent). Fades in/out on `active`; the lap runs only while visible. Under `data-motion="calm"` / reduced motion there is no frozen arc: it shows a static primary focus-ring tint. Paints a `--color-base-100` surface, so the wrapped composer must be transparent. | `active`, `speed?` (4.5 s/lap), `intensity?` ('subtle'\|'normal'\|'vivid'), `radius?` (px or CSS; default box radius), `class?`, `children` |
+| `StreamedText` | Streamed assistant text revealed per paragraph/line, never per token: an append-only splitter (`splitStreamedText`, index keys, code fences kept whole) mounts each block once with a short fade + un-blur on motion tokens, after which it only grows. History doesn't animate; reduced motion is static; a subtle caret shows while `streaming`. `renderBlock` lets the host render markdown per block. Recipe: show `AgentThinking` until the first *text* part exists, not while the request status is "submitted". | `text`, `streaming?`, `split?` ('paragraph'\|'line'), `as?`, `class?`, `renderBlock?: Snippet<[string, number]>` |
+
+**Upgrades in this wave (all additive):**
+- **`Steps`** (`progress/Steps.svelte`) — `collapsible?`, `collapsed?` (bindable), `summary?: string | Snippet` (default "3 steps left" / "All steps done", live while folded; the header is a real `aria-expanded` / `aria-controls` button), `orientation?` ('horizontal'\|'vertical'; vertical also shows descriptions), `activeProgress?` (0–1, a mini ProgressRing on the active node and in the folded header), `completionDelay?` + `onFinished?` (fires once after `current` passes the last step; re-arms if `current` drops back). Unset, the markup is unchanged. Helpers: `stepsSummary`, `stepsRemaining`, `isStepsFinished`, `clampStepProgress`.
+- **`MessageInput`** — `busy?` + `onStop?` swap the send button for a same-size "Stop generating" button; Escape in the input stops (an open mention list still takes Escape first); while busy, Enter doesn't send and the draft is kept. `statusTab?: Snippet` renders a slim strip attached to the input's top edge.
+- **`MessageItem`** — the action toolbar and timestamp also appear on keyboard focus (`group-focus-within`), not only on hover.
+
+```typescript
+// Reveal pacing for AgentLog / AgentTaskList. Every option may be a value or a getter.
+import { createRevealTicker } from "jatui"
+// const t = createRevealTicker({ total: () => n, stepInterval?, startDelay?, revealed?: () => count | undefined,
+//   delayFor?: (i) => ms, run?, onComplete })  → t.revealed, t.complete, t.replay()
+// `revealed` defined = event-driven (no timer). onComplete fires once per completion.
+// The timing core is also exported as a plain class: RevealCore (injectable clock).
+```
+
 ### Tables (subpath: `jatui/table`)
 
 Requires peer `@tanstack/table-core`. `import { DataTable, flexRender, columnResize } from 'jatui/table'`.
@@ -189,11 +224,13 @@ 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) |
+| `Breadcrumb` | Location trail in a `<nav aria-label>`; the last item is `aria-current="page"`. `maxItems` keeps the root + the last `maxItems - 1` and folds the middle into a `…` button whose menu lists the hidden levels (arrows/Home/End/Escape, click-outside; pure `collapseBreadcrumb`). Leading icons via `item.icon` (component taking `{size,class}`) or the `icon` snippet. | `items: BreadcrumbItem[]`, `maxItems?`, `icon?` (snippet `(item, i)`), `ariaLabel?` |
 | `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) |
+| `use:scrollEdge` (action) | Progressive-blur fade on a scroll region's edge once content scrolls under it: a stationary `aria-hidden` sticky strip inside the scroller with two masked backdrop-blur layers + a surface→transparent gradient, each ramping opacity 0→1 over the first `size` px of scroll distance (nothing drawn at rest). Keep headers OUTSIDE the scroller; chat threads (stick-to-bottom) want `edges: 'bottom'`. Opacity-only, reduced-motion safe. Pure: `edgeOpacity`, `edgeDistances`. | `edges?` ('top'\|'bottom'\|'both'), `size?` (24), `surface?` (`--jatui-surface`), `blur?` (true), `enabled?` |
 
 **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`.
 
@@ -332,8 +369,8 @@ const callbacks: AnnotationCallbacks = {
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
-| `ThemeSelector` | DaisyUI theme switcher with preview dots | `themes`, `defaultTheme`, `dropUp`, `storageKey`, `onThemeChange` |
-| `ThemeToggle` | Icon-only sun<->moon light/dark toggle with an animated morph (transform+opacity on motion tokens; instant under reduced-motion; spring flattens on `data-motion="calm"`). A pure control — flips the bindable `theme` and fires `onchange`; storage stays with the consumer. | `theme` (bindable), `lightTheme`, `darkTheme`, `onchange`, `size` |
+| `ThemeSelector` | DaisyUI theme switcher with preview dots. `reveal` wipes the new theme in from the clicked item (`themeWipe`). | `themes`, `defaultTheme`, `dropUp`, `storageKey`, `onThemeChange`, `reveal?: boolean \| 'hard' \| 'soft'` |
+| `ThemeToggle` | Icon-only sun<->moon light/dark toggle with an animated morph (transform+opacity on motion tokens; instant under reduced-motion; spring flattens on `data-motion="calm"`). A pure control — flips the bindable `theme` and fires `onchange`; storage stays with the consumer. `reveal` runs the flip inside a `themeWipe` circular View Transition from the button (keyboard activation grows from its centre). | `theme` (bindable), `lightTheme`, `darkTheme`, `onchange`, `size`, `reveal?: boolean \| 'hard' \| 'soft'` |
 
 ### Keyboard Navigation
 
@@ -495,6 +532,12 @@ import { groupRows, groupPathKey, type GroupLevel, type GroupedItem } from "jatu
 // 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 }
 
+// Theme change reveal — circular View Transition from the click (or, for a
+// keyboard activation, the control's centre). Single-flight, level-scaled
+// duration, reduced-motion = instant. ThemeToggle/ThemeSelector `reveal` use it.
+import { themeWipe } from "jatui"
+// themeWipe(event, () => setTheme(next), { edge: 'soft' })  // edge: 'hard' (default) | 'soft'
+
 // Date formatting
 import { formatRelativeTime, formatDate, formatShortDate, formatDateTime } from "jatui"
 
@@ -614,7 +657,13 @@ Three rules keep DaisyUI swappable instead of load-bearing:
    internal skin, like vendored CSS — never part of a component's public
    props/API.
 3. **jatui owns the token layer.** Components consume `--jatui-*`
-   (`styles/tokens.css`: radius/spacing/border) and `--motion-*`
+   (`styles/tokens.css`: radius/spacing/border, plus the colour-intent layer —
+   `--jatui-focus-ring{,-width,-offset}`, `--jatui-surface`, `--jatui-hover-bg`,
+   `--jatui-pressed-bg`, `--jatui-separator`, `--jatui-selection-{bg,edge,solid,solid-fg}`,
+   `--jatui-chart-{1..5,grid,axis}`, `--jatui-event-{1..6}{,-bg,-fg}`,
+   `--jatui-status-{positive,caution,negative,neutral}`; all `color-mix` over DaisyUI
+   semantic vars, re-declared on `[data-theme]` so nested themes recompute — use
+   them with an inline fallback) and `--motion-*`
    (`styles/motion.css`: easing/duration) custom properties. DaisyUI theme
    variables feed INTO those tokens (as fallback-chained inputs), never
    appear directly in component styles for values the tokens cover.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,67 @@
+# Third-party notices
+
+jatui is MIT licensed (see `LICENSE`). Some files adapt code from the projects
+below; each such file also carries the notice in its header comment.
+
+## BoardUI (free tier)
+
+<https://github.com/BoardUI/boardui> — MIT License
+
+```
+MIT License
+
+Copyright (c) 2026 Mertcan Dundar Esmergul (BoardUI)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Files adapted from BoardUI free components:
+
+- `src/lib/components/agent/agentThinking.ts`, `AgentThinking.svelte`,
+  `ShimmerText.svelte` — from `agent-thinking` (dot-grid comet curve, sparkle
+  and figure-eight geometry, single-tone shimmer gradient).
+- `src/lib/components/agent/AgentLog.svelte`, `AgentLogRow.svelte`, `agentLog.ts`,
+  `revealCore.ts` — from `agent-log` (grow-in row, soft reveal mask, one-pen
+  tree guide, reveal ticker).
+- `src/lib/components/agent/ComposerGlow.svelte` — from `composer-loader`
+  (perimeter/dash math, layered SVG blur).
+- `src/lib/components/agent/StreamedText.svelte` — the per-block reveal idea from
+  `agent-chat`.
+- `src/lib/components/NotificationCenter.svelte`, `notificationCenter.ts` — from
+  `notification-center`.
+
+BoardUI Pro items are not covered by the MIT licence. `AgentTaskList`,
+`Questionnaire` and `ContextMeter` were built from public behaviour only; no Pro
+source was read or copied.
+
+### Wave 1 (jatui-owg2z) — ideas only, written fresh for Svelte 5
+
+None of these files is a close port, so none carries the BoardUI notice. They
+follow ideas from BoardUI's free items:
+
+- `IconButton`, `CloseButton`, `LinkButton`: BoardUI icon-button, close-button
+  and link-button.
+- `use:scrollEdge`: BoardUI's scroll-region progressive-blur guidance.
+- Colour-intent tokens in `styles/tokens.css`: BoardUI's semantic theme vars,
+  reduced to a thin `color-mix` layer over DaisyUI.
+- `PinInput` one-time-code autofill: BoardUI input-otp.
+- `TextArea` `minRows`/`maxRows`: BoardUI textarea.
+- `themeWipe` fixes and `ThemeToggle`/`ThemeSelector` `reveal`: BoardUI theme
+  toggle.
+- `Breadcrumb` `maxItems` and icons: BoardUI breadcrumb.

package/dist/actions/scrollEdge.d.ts

@@ -0,0 +1,55 @@
+/**
+ * scrollEdge — progressive-blur fade on the edge of a scroll region.
+ *
+ *   <div class="overflow-y-auto" use:scrollEdge>…</div>                 top edge
+ *   <div class="overflow-y-auto" use:scrollEdge={{ edges: 'both' }}>…</div>
+ *   <div use:scroller.action use:scrollEdge={{ edges: 'bottom' }}>…</div> chat (stick-to-bottom)
+ *
+ * When content has scrolled under an edge, that edge softens: a stationary,
+ * `pointer-events: none`, `aria-hidden` overlay with three layers —
+ *
+ *   1. a tall band of light backdrop blur (1px), masked to fade out,
+ *   2. a shorter band of heavier blur (4px), masked the same way,
+ *   3. a surface → transparent gradient.
+ *
+ * Each layer's opacity ramps 0 → 1 over the first `size` px of scroll
+ * distance from that edge, so at rest (scrollTop 0) nothing is drawn and
+ * the first line of content is never dimmed. Opacity goes on the LAYERS,
+ * never their parent: a translucent parent becomes a backdrop root and the
+ * blur would sample nothing.
+ *
+ * The overlay lives inside the scroller as a `position: sticky` strip with a
+ * negative margin, so it needs no positioned wrapper and takes no layout
+ * space. Keep headers OUTSIDE the scroller — the edge belongs to the scroll
+ * area, not the chrome above it. Opacity-only, so it is reduced-motion safe.
+ *
+ * Idea from BoardUI's scroll-region guidance (MIT); written fresh.
+ */
+export type ScrollEdgeSide = 'top' | 'bottom' | 'both';
+export interface ScrollEdgeOptions {
+    /** Which edge(s) fade. Default 'top'. Chat threads that stick to the bottom want 'bottom'. */
+    edges?: ScrollEdgeSide;
+    /** Height of the fade band and the scroll distance the ramp runs over, px. Default 24. */
+    size?: number;
+    /** Colour the gradient blends into. Default the `--jatui-surface` token (base-100). */
+    surface?: string;
+    /** Backdrop blur layers. false = gradient only (cheaper on huge lists). Default true. */
+    blur?: boolean;
+    /** Turn it off without unmounting the action. Default true. */
+    enabled?: boolean;
+}
+/** Opacity for an edge given how far content has scrolled past it. Pure. */
+export declare function edgeOpacity(distance: number, size: number): number;
+/** Scroll distance past the top and bottom edges of a scroller. Pure. */
+export declare function edgeDistances(m: {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}): {
+    top: number;
+    bottom: number;
+};
+export declare function scrollEdge(node: HTMLElement, options?: ScrollEdgeOptions): {
+    update(next?: ScrollEdgeOptions): void;
+    destroy(): void;
+};

package/dist/actions/scrollEdge.js

@@ -0,0 +1,144 @@
+/**
+ * scrollEdge — progressive-blur fade on the edge of a scroll region.
+ *
+ *   <div class="overflow-y-auto" use:scrollEdge>…</div>                 top edge
+ *   <div class="overflow-y-auto" use:scrollEdge={{ edges: 'both' }}>…</div>
+ *   <div use:scroller.action use:scrollEdge={{ edges: 'bottom' }}>…</div> chat (stick-to-bottom)
+ *
+ * When content has scrolled under an edge, that edge softens: a stationary,
+ * `pointer-events: none`, `aria-hidden` overlay with three layers —
+ *
+ *   1. a tall band of light backdrop blur (1px), masked to fade out,
+ *   2. a shorter band of heavier blur (4px), masked the same way,
+ *   3. a surface → transparent gradient.
+ *
+ * Each layer's opacity ramps 0 → 1 over the first `size` px of scroll
+ * distance from that edge, so at rest (scrollTop 0) nothing is drawn and
+ * the first line of content is never dimmed. Opacity goes on the LAYERS,
+ * never their parent: a translucent parent becomes a backdrop root and the
+ * blur would sample nothing.
+ *
+ * The overlay lives inside the scroller as a `position: sticky` strip with a
+ * negative margin, so it needs no positioned wrapper and takes no layout
+ * space. Keep headers OUTSIDE the scroller — the edge belongs to the scroll
+ * area, not the chrome above it. Opacity-only, so it is reduced-motion safe.
+ *
+ * Idea from BoardUI's scroll-region guidance (MIT); written fresh.
+ */
+/** Opacity for an edge given how far content has scrolled past it. Pure. */
+export function edgeOpacity(distance, size) {
+    if (!(size > 0) || !Number.isFinite(distance))
+        return 0;
+    return Math.min(1, Math.max(0, distance / size));
+}
+/** Scroll distance past the top and bottom edges of a scroller. Pure. */
+export function edgeDistances(m) {
+    return {
+        top: Math.max(0, m.scrollTop),
+        bottom: Math.max(0, m.scrollHeight - m.clientHeight - m.scrollTop)
+    };
+}
+const DEFAULT_SURFACE = 'var(--jatui-surface, var(--color-base-100, Canvas))';
+function strip(side, o) {
+    const el = document.createElement('div');
+    el.setAttribute('aria-hidden', 'true');
+    el.dataset.scrollEdge = side;
+    const s = el.style;
+    s.position = 'sticky';
+    s.display = 'block';
+    s[side] = '0';
+    s.height = `${o.size}px`;
+    s[side === 'top' ? 'marginBottom' : 'marginTop'] = `-${o.size}px`;
+    s.pointerEvents = 'none';
+    s.zIndex = '1';
+    s.gridColumn = '1 / -1'; // a grid scroller must not give the strip its own cell
+    s.flexShrink = '0';
+    s.alignSelf = 'stretch';
+    const dir = side === 'top' ? 'to bottom' : 'to top';
+    const anchor = side === 'top' ? 'top: 0' : 'bottom: 0';
+    const layers = [];
+    if (o.blur) {
+        layers.push(`${anchor}; height: 100%; backdrop-filter: blur(1px); -webkit-backdrop-filter: blur(1px); mask-image: linear-gradient(${dir}, #000, transparent); -webkit-mask-image: linear-gradient(${dir}, #000, transparent)`, `${anchor}; height: 66%; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); mask-image: linear-gradient(${dir}, #000, transparent); -webkit-mask-image: linear-gradient(${dir}, #000, transparent)`);
+    }
+    layers.push(`${anchor}; height: 100%; background: linear-gradient(${dir}, ${o.surface}, transparent)`);
+    for (const css of layers) {
+        const layer = document.createElement('div');
+        layer.style.cssText = `position: absolute; left: 0; right: 0; ${css}; opacity: var(--jatui-scroll-edge-o, 0); transition: opacity var(--motion-instant, 80ms) linear;`;
+        el.appendChild(layer);
+    }
+    return el;
+}
+export function scrollEdge(node, options = {}) {
+    let opts = resolve(options);
+    let top = null;
+    let bottom = null;
+    let frame = 0;
+    let ro = null;
+    function resolve(o) {
+        return {
+            edges: o.edges ?? 'top',
+            size: o.size ?? 24,
+            surface: o.surface ?? DEFAULT_SURFACE,
+            blur: o.blur ?? true,
+            enabled: o.enabled ?? true
+        };
+    }
+    function measure() {
+        frame = 0;
+        const d = edgeDistances(node);
+        top?.style.setProperty('--jatui-scroll-edge-o', String(edgeOpacity(d.top, opts.size)));
+        bottom?.style.setProperty('--jatui-scroll-edge-o', String(edgeOpacity(d.bottom, opts.size)));
+    }
+    function schedule() {
+        if (frame)
+            return;
+        frame = requestAnimationFrame(measure);
+    }
+    function mount() {
+        unmount();
+        if (!opts.enabled)
+            return;
+        if (opts.edges !== 'bottom') {
+            top = strip('top', opts);
+            node.prepend(top);
+        }
+        if (opts.edges !== 'top') {
+            bottom = strip('bottom', opts);
+            node.append(bottom);
+        }
+        measure();
+    }
+    function unmount() {
+        top?.remove();
+        bottom?.remove();
+        top = bottom = null;
+    }
+    node.addEventListener('scroll', schedule, { passive: true });
+    if (typeof ResizeObserver !== 'undefined') {
+        ro = new ResizeObserver(schedule);
+        ro.observe(node);
+    }
+    // Content growth changes the bottom distance without a scroll event.
+    const mo = typeof MutationObserver !== 'undefined' ? new MutationObserver(schedule) : null;
+    mo?.observe(node, { childList: true, subtree: true, characterData: true });
+    mount();
+    return {
+        update(next = {}) {
+            const prev = opts;
+            opts = resolve(next);
+            const same = Object.keys(opts).every((k) => opts[k] === prev[k]);
+            if (same)
+                schedule();
+            else
+                mount();
+        },
+        destroy() {
+            node.removeEventListener('scroll', schedule);
+            ro?.disconnect();
+            mo?.disconnect();
+            if (frame)
+                cancelAnimationFrame(frame);
+            unmount();
+        }
+    };
+}

package/dist/artifact-blocks/blocks/diagram/DiagramBlock.svelte.d.ts

@@ -6,7 +6,7 @@ declare const DiagramBlock: import("svelte").Component<BlockProps<{
         id: string;
         label: string;
         sublabel?: string | undefined;
-        kind?: "data" | "input" | "output" | "note" | "default" | "decision" | "external" | "terminal" | "process" | "subroutine" | undefined;
+        kind?: "data" | "input" | "output" | "note" | "default" | "external" | "decision" | "terminal" | "process" | "subroutine" | undefined;
         tone?: "error" | "warning" | "info" | "success" | "primary" | "secondary" | "neutral" | "accent" | undefined;
         shape?: "circle" | "rect" | "stadium" | "pill" | "diamond" | undefined;
     }[];

package/dist/artifact-blocks/blocks/diagram/schema.d.ts

@@ -39,8 +39,8 @@ export declare const diagramParamsSchema: z.ZodObject<{
             output: "output";
             note: "note";
             default: "default";
-            decision: "decision";
             external: "external";
+            decision: "decision";
             terminal: "terminal";
             process: "process";
             subroutine: "subroutine";

package/dist/components/BottomSheet.svelte

@@ -26,6 +26,8 @@
              settles on the snap nearest the post-drag height.
 -->
 <script lang="ts">
+	import CloseButton from './CloseButton.svelte';
+	import { scrollEdge as scrollEdgeAction } from '../actions/scrollEdge';
 	import { onMount, untrack } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
 	import type { Snippet } from 'svelte';
@@ -49,6 +51,7 @@
 		onclose = () => {},
 		shortcutRegistry,
 		shortcutContext = 'bottom-sheet',
+		scrollEdge = true,
 		children
 	}: {
 		open?: boolean;
@@ -70,6 +73,8 @@
 		shortcutRegistry?: ShortcutRegistry;
 		/** Context name pushed while open. Default `'bottom-sheet'`. */
 		shortcutContext?: string;
+		/** Soft progressive-blur fade at the top of the content once it scrolls (`use:scrollEdge`). Ignored with `fullHeight` (the slot owns scrolling). Default true. */
+		scrollEdge?: boolean;
 		children?: Snippet;
 	} = $props();
 
@@ -254,12 +259,7 @@
 		{#if title}
 			<div class="flex-shrink-0 flex items-center justify-between px-4 py-2 border-b border-base-200">
 				<span class="text-sm font-semibold">{title}</span>
-				<button
-					type="button"
-					class="btn btn-sm btn-ghost btn-circle"
-					aria-label="Close"
-					onclick={dismiss}
-				>✕</button>
+				<CloseButton label="Close" onclick={dismiss} />
 			</div>
 		{/if}
 
@@ -273,6 +273,7 @@
 				: keyboardInset > 0
 					? `padding-bottom: ${keyboardInset}px;`
 					: ''}
+			use:scrollEdgeAction={{ enabled: scrollEdge && !(fullHeight && !isDual) }}
 		>
 			{@render children?.()}
 		</div>

package/dist/components/BottomSheet.svelte.d.ts

@@ -20,6 +20,8 @@ type $$ComponentProps = {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'bottom-sheet'`. */
     shortcutContext?: string;
+    /** Soft progressive-blur fade at the top of the content once it scrolls (`use:scrollEdge`). Ignored with `fullHeight` (the slot owns scrolling). Default true. */
+    scrollEdge?: boolean;
     children?: Snippet;
 };
 declare const BottomSheet: import("svelte").Component<$$ComponentProps, {}, "open">;

package/dist/components/BulkActionBar.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	/**
-	 * BulkActionBar — floating action bar for listNav selections.
+	 * BulkActionBar — floating action bar for listNav or clickSelection selections.
 	 *
 	 * Simpler API than `FloatingActionBar`: takes a `Set` or `Array` of
 	 * selected ids and a flat `actions[]`. Renders nothing when the
@@ -47,6 +47,27 @@
 	 *       onClear={() => nav.clearSelection()}
 	 *     />
 	 *
+	 * Usage — with the mouse (createClickSelection): click selects one,
+	 * Ctrl/⌘-click toggles, Shift-click selects a range in display order,
+	 * Shift+arrows extend, Ctrl/⌘ A selects all, Esc clears. Feed its
+	 * `ordered` (display order) or `picked` (selection order) to the bar:
+	 *
+	 *     const sel = createClickSelection({ ids: () => rows.map((r) => r.id) });
+	 *
+	 *     {#each rows as r (r.id)}
+	 *       <button class:selected={sel.has(r.id)} onclick={(e) => sel.click(r.id, e)}>…</button>
+	 *     {/each}
+	 *     <svelte:window onkeydown={(e) => sel.handleKeydown(e, { next: neighbour })} />
+	 *
+	 *     <BulkActionBar
+	 *       selection={sel.ordered}
+	 *       actions={[{ label: 'Delete', onSelect: () => del(sel.ordered), destructive: true }]}
+	 *       onClear={() => sel.clear()}
+	 *     />
+	 *
+	 * listNav is the keyboard-only alternative (x / V / Shift+J/K). Pick ONE
+	 * selection owner per surface; see createClickSelection for combining them.
+	 *
 	 * Usage — grouped:
 	 *
 	 *     <BulkActionBar
@@ -93,7 +114,9 @@
 		label: string;
 		/** Optional SVG path string for a 24×24 icon on the group button. */
 		icon?: string;
-		/** Actions rendered inside the dropdown. `destructive` on a nested action
+		/** Actions rendered inside the dropdown; a nested action's `key` shows as a
+		 * hint at the item's right edge but is NOT bound (bind it in the host).
+		 * `destructive` on a nested action
 		 * currently only affects semantics for readers — the dropdown item row
 		 * is styled uniformly. */
 		actions: BulkAction[];
@@ -120,6 +143,8 @@
 		loadingMessage?: string | null;
 		/** Label for the count. Default "selected". */
 		countLabel?: string;
+		/** 'floating' (default, fixed bottom-centre) or 'inline' (in the host's own bar). */
+		placement?: 'floating' | 'inline';
 	}
 
 	let {
@@ -130,6 +155,7 @@
 		loading = false,
 		loadingMessage = null,
 		countLabel = 'selected',
+		placement = 'floating',
 	}: Props = $props();
 
 	const count = $derived(
@@ -179,6 +205,9 @@
 			items: g.actions.map((a) => ({
 				label: a.label,
 				onclick: a.onSelect,
+				// Inside a group a key is a hint only: the host binds it (BulkActionBar
+				// registers hotkeys for flat actions alone).
+				hint: a.key,
 			})),
 		})),
 	);
@@ -192,4 +221,5 @@
 	{loadingMessage}
 	{onClear}
 	{countLabel}
+	{placement}
 />

package/dist/components/BulkActionBar.svelte.d.ts

@@ -27,7 +27,9 @@ export interface BulkActionGroup {
     label: string;
     /** Optional SVG path string for a 24×24 icon on the group button. */
     icon?: string;
-    /** Actions rendered inside the dropdown. `destructive` on a nested action
+    /** Actions rendered inside the dropdown; a nested action's `key` shows as a
+     * hint at the item's right edge but is NOT bound (bind it in the host).
+     * `destructive` on a nested action
      * currently only affects semantics for readers — the dropdown item row
      * is styled uniformly. */
     actions: BulkAction[];
@@ -53,6 +55,8 @@ interface Props {
     loadingMessage?: string | null;
     /** Label for the count. Default "selected". */
     countLabel?: string;
+    /** 'floating' (default, fixed bottom-centre) or 'inline' (in the host's own bar). */
+    placement?: 'floating' | 'inline';
 }
 declare const BulkActionBar: import("svelte").Component<Props, {}, "">;
 type BulkActionBar = ReturnType<typeof BulkActionBar>;