@joewinke/jatui 0.38.5 → 0.39.0

package/CLAUDE.md

@@ -81,6 +81,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'`.
@@ -119,7 +150,7 @@ Item-by-item review surfaces (MOS review-ux, design mos-z8vgx). One `VerdictOpti
 | `ThumbnailGrid` | Generic thumbnail strip (chimaro port) — image tiles with text-tile fallback, +N overflow counter, remove/add affordances. Decoupled from any media library: pass `{id, url, alt}` items, or a `cell` snippet for full control of tile contents. `removeMode` — `'hover'` (default) reveals the × on hover/focus and keeps it visible on coarse (touch) pointers (ContextMenuTrigger pattern); `'always'` pins it for touch-first flows. `gridCols` (e.g. `'grid-cols-2 sm:grid-cols-4'`) switches the strip to a responsive CSS grid with column-filling tiles. | `items: ThumbnailItem[]`, `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `removeMode` (`hover\|always`), `addable`+`onAdd`, `onSelect`, `gridCols`, `class`, `cell` snippet |
 | `MediaWorkbench` | Full-featured image editor modal — upload, AI generate, AI edit, background removal, annotation canvas. **Preferred over `SmartImageEditor` for new image fields.** Two-column modal: preview left, 4 action tabs right (Generate, Edit, Remove BG, Annotate). Save uploads blob to `uploadEndpoint` or emits `onComplete`. Requires proxy endpoints from jst-23w1l.2. | `value` (bindable `string \| null`), `uploadEndpoint?` (default `/api/media`), `onComplete?`, `accept?` |
 | `MediaLightbox` | Full-screen media preview — z-9040 backdrop, arrow-key paging when given an array, `+/-/0` zoom, download action, Escape/backdrop close. **Use this for the general "just show it big" case** — replaces hand-rolled `fixed inset-0 z-[9040]` modals. For annotated / markup-overlaid image previews, use `ImageLightbox` instead. | `src?`, `filename?`, `kind?: 'image' \| 'video'`, `downloadUrl?`, `items?: MediaItem[]`, `initialIndex?`, `onClose?`, `zIndex?` |
-| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `Shift+T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, t theater, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed; a wheel/keyboard volume change also flashes a clear volume OSD — glyph, level bar and %, "Muted" at 0, opacity-only fade) and zoom over the band. Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `transcriptMaxHeight?` (pane bound — default `min(40vh, 28rem)` below, the player's height beside; the active-line follow scrolls only the pane; only a gesture that actually moves the PANE pauses it — a wheel that scrolls the page doesn't — behind a "Resume following" pill, and it resumes by itself on seek / line or chapter click / play after pause / `followResumeMs` (6000) idle while playing; a hovered chapter fills its whole span in the theme accent with full-height edges), `followResumeMs?`, `theater?` (bindable — theater mode, NOT fullscreen: control-bar button + `t`, the HOST lays the page out full-width; a side transcript moves below; remembered per viewer as the `player.theater` setting via `settingsStore`, else guarded localStorage), `theaterButton?` (true), `onTheaterChange?`, `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
+| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `Shift+T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, t theater, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed; a wheel/keyboard volume change also flashes a clear volume OSD — glyph, level bar and %, "Muted" at 0, opacity-only fade) and zoom over the band; Shift+wheel over the transcript steps line by line (a plain wheel over the transcript scrolls the pane natively — the page is never trapped). Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `transcriptMaxHeight?` (pane bound — default `min(40vh, 28rem)` below, the player's height beside; the active-line follow scrolls only the pane; only a gesture that actually moves the PANE pauses it — a wheel that scrolls the page doesn't — behind a "Resume following" pill, and it resumes by itself on seek / line or chapter click / play after pause / `followResumeMs` (6000) idle while playing; a hovered chapter fills its whole span in the theme accent with full-height edges), `followResumeMs?`, `theater?` (bindable — theater mode, NOT fullscreen: control-bar button + `t`, the HOST lays the page out full-width; a side transcript moves below; remembered per viewer as the `player.theater` setting via `settingsStore`, else guarded localStorage), `theaterButton?` (true), `onTheaterChange?`, `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
 | `MediaCapture` | One-tap audio/selfie-video/screen(+mic) recording — a host-agnostic PRIMITIVE. Owns permission requests, MIME negotiation, the record/stop state machine, live self-preview, and mixes screen+mic audio into one track via AudioContext. Never uploads anything — hands the finished clip to `onCapture` as a Blob and the host decides what to do with it. `onCapture` may be async; the component shows "processing" until it resolves. | `onCapture: (result: MediaCaptureResult) => void \| Promise<void>`, `modes?` (default all three), `maxDurationMs?` (default 120000), `label?`, `hint?`, `compact?`, `disabled?` |
 | `MultimodalCaptureField` | "Upload a file, or record yourself going over it" as one input surface — composes `FileDropzone` (capped to one file) with `MediaCapture`. File and recording are independent (either, both, or neither); neither half uploads anything, same "validate and hand back" contract as `FileDropzone`. | `onFileSelected?`, `onFileRemoved?`, `onCapture?`, `onRecordingRemoved?`, `accept?`, `maxFileSize?`, `modes?`, `maxDurationMs?`, `file?`/`fileUrl?`/`fileName?`, `recordingSummary?` |
 | `ListenControl` | "Listen to this page" — a compact pill that expands into a TWO-ROW playback bar over the host's PER-SENTENCE audio (TTS): row 1 = play/pause · chapter chip + current sentence (full remaining width) · ONE settings pill ("1.25× · Sarah" → speed 0.75–2× + voice menu) · close; row 2 = prev/next sentence and −15s/+15s · a document-wide progress bar with chapter ticks (a hatched tail marks the not-yet-synthesized part), time, close. The host supplies an async `source` (sentences/paragraphs with ids → audio URLs, streamed page by page so playback starts on the first chunk while the rest synthesizes; pages merge by id so late URLs fill in) and gets `onSegmentChange(id)` at every boundary for highlight + scroll-follow. Media Session (lock-screen/headset controls, one document-wide position), keyboard scoped to the player (Space/K, ←/→ sentences, Shift+←/→ ±15s, [ / ] speed, Escape), speed+voice persisted in localStorage, `bind:api` for hosts wiring their own global keys, reduced-motion aware, token-only theming, never overflows its host (border-box, `max-width: 100%`, `min-width: 0` chain), fixed sticky mini-bar (same two rows) on narrow screens. Internals in `src/lib/listen/` (one timeline across per-sentence files — `buildTimeline` offsets; see `video/` for the doctrine). Demo synthesizes real WAVs locally. | `source`, `voices?`, `voiceId?` (bindable), `chapters?`, `title?`, `triggerLabel?`, `open?` (bindable), `preload?`, `estimateSec?`, `storageKey?`, `onSegmentChange?`, `onOpenChange?`, `api?` (bindable), `class?`, `children?` (custom trigger) |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,51 @@
+# 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.

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>;

package/dist/components/FloatingActionBar.svelte

@@ -20,6 +20,22 @@
 	 * Per-action `disabled` renders the button dimmed and non-interactive;
 	 * per-action `loadingText` disables it and swaps the label for a
 	 * spinner + that text (mardukos fork) while other actions stay active.
+	 *
+	 * `placement="inline"` puts the bar in the normal flow at its container's
+	 * full width (for a host with its own sticky bar); the default floats
+	 * bottom-centre. Either way it wraps rather than run off a narrow screen.
+	 *
+	 * The root class is `fab-bar`, not `fab`: daisyUI 5 ships a `.fab`
+	 * (speed-dial) component whose rules hid every button of this bar in a
+	 * daisyUI 5 host (qimg-x9ifp.1).
+	 *
+	 * Theming: every colour is a custom property with the original dark value
+	 * as its fallback, so a host can map the bar onto its theme without
+	 * overriding internals: --fab-bg, --fab-fg, --fab-muted, --fab-border,
+	 * --fab-shadow, --fab-radius, --fab-btn-bg/-fg/-border/-hover/-radius,
+	 * --fab-primary-bg/-fg/-border/-hover, --fab-danger-bg/-fg/-border/-hover,
+	 * --fab-menu-bg/-radius/-shadow, --fab-focus, --fab-spinner. Set them on
+	 * any ancestor (the bar inherits them).
 	 */
 
 	import { fade } from 'svelte/transition';
@@ -49,6 +65,8 @@
 		label: string;
 		/** Optional colored dot (oklch string) */
 		dotColor?: string;
+		/** Optional key hint shown at the item's right edge (display only; the host binds it). */
+		hint?: string;
 		/** Optional SVG snippet rendered before the label */
 		iconSnippet?: import('svelte').Snippet;
 		/** Called when this item is clicked */
@@ -86,6 +104,13 @@
 		onClear?: () => void;
 		/** Label for the selection count (default: "selected") */
 		countLabel?: string;
+		/**
+		 * 'floating' (default): fixed, bottom-centre over the page.
+		 * 'inline': in the normal flow, full width of its container — for a
+		 * host that already has a sticky bar to put it in. Both wrap onto more
+		 * lines rather than run off a narrow screen.
+		 */
+		placement?: 'floating' | 'inline';
 	}
 
 	let {
@@ -96,6 +121,7 @@
 		loadingMessage = null,
 		onClear,
 		countLabel = 'selected',
+		placement = 'floating',
 	}: Props = $props();
 
 	let openDropdownId = $state<string | null>(null);
@@ -129,7 +155,7 @@
 </script>
 
 {#if count > 0}
-	<div class="fab" transition:fade={{ duration: 150 }}>
+	<div class="fab-bar" class:fab-inline={placement === 'inline'} role="group" aria-label="{count} {countLabel}" transition:fade={{ duration: 150 }}>
 		<span class="fab-count">{count} {countLabel}</span>
 
 		{#if loadingMessage}
@@ -176,13 +202,22 @@
 					class="fab-dropdown-wrapper"
 					role="group"
 					onclick={(e) => e.stopPropagation()}
-					onkeydown={(e) => e.stopPropagation()}
+					onkeydown={(e) => {
+						e.stopPropagation();
+						if (e.key === 'Escape' && openDropdownId === dropdown.id) {
+							e.preventDefault();
+							openDropdownId = null;
+							(e.currentTarget.querySelector('.fab-btn') as HTMLElement | null)?.focus();
+						}
+					}}
 				>
 					<button
 						type="button"
 						class="fab-btn {variantClass(dropdown.variant)}"
 						onclick={() => openDropdownId = openDropdownId === dropdown.id ? null : dropdown.id}
 						disabled={loading}
+						aria-haspopup="true"
+						aria-expanded={openDropdownId === dropdown.id}
 					>
 						{#if dropdown.icon}
 							<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="14" height="14">
@@ -205,7 +240,10 @@
 									{#if item.iconSnippet}
 										{@render item.iconSnippet()}
 									{/if}
-									{item.label}
+									<span class="fab-item-label">{item.label}</span>
+									{#if item.hint}
+										<kbd class="fab-key fab-item-hint">{item.hint}</kbd>
+									{/if}
 								</button>
 							{/each}
 						</div>
@@ -229,8 +267,11 @@
 {/if}
 
 <style>
-	.fab {
+	.fab-bar {
 		position: fixed;
+		max-width: calc(100vw - 1rem);
+		flex-wrap: wrap;
+		justify-content: center;
 		bottom: 1.5rem;
 		left: 50%;
 		transform: translateX(-50%);
@@ -239,23 +280,35 @@
 		align-items: center;
 		gap: 0.5rem;
 		padding: 0.5rem 0.75rem;
-		background: oklch(0.16 0.02 250);
-		border: 1px solid oklch(0.30 0.02 250);
-		border-radius: 0.75rem;
-		box-shadow: 0 8px 32px oklch(0.05 0 0 / 0.6), 0 2px 8px oklch(0.05 0 0 / 0.3);
+		background: var(--fab-bg, oklch(0.16 0.02 250));
+		border: 1px solid var(--fab-border, oklch(0.30 0.02 250));
+		border-radius: var(--fab-radius, 0.75rem);
+		box-shadow: var(--fab-shadow, 0 8px 32px oklch(0.05 0 0 / 0.6), 0 2px 8px oklch(0.05 0 0 / 0.3));
+		color: var(--fab-fg, oklch(0.85 0.02 250));
+	}
+	/* Inline: in the host's own bar, so no float, no shadow, its full width. */
+	.fab-bar.fab-inline {
+		position: static;
+		left: auto;
+		bottom: auto;
+		transform: none;
+		max-width: none;
+		width: 100%;
+		justify-content: flex-start;
+		box-shadow: var(--fab-shadow-inline, none);
 	}
 
 	.fab-count {
 		font-size: 0.8125rem;
 		font-weight: 600;
-		color: oklch(0.85 0.02 250);
+		color: var(--fab-fg, oklch(0.85 0.02 250));
 		white-space: nowrap;
 	}
 
 	.fab-divider {
 		width: 1px;
 		height: 1.25rem;
-		background: oklch(0.30 0.02 250);
+		background: var(--fab-border, oklch(0.30 0.02 250));
 	}
 
 	.fab-btn {
@@ -264,7 +317,7 @@
 		gap: 0.375rem;
 		padding: 0.375rem 0.625rem;
 		border: 1px solid transparent;
-		border-radius: 0.375rem;
+		border-radius: var(--fab-btn-radius, 0.375rem);
 		font-size: 0.75rem;
 		font-weight: 500;
 		cursor: pointer;
@@ -278,25 +331,25 @@
 
 	/* Variants */
 	.fab-btn-default {
-		background: oklch(0.25 0.02 250 / 0.5);
-		color: oklch(0.75 0.02 250);
-		border-color: oklch(0.35 0.02 250);
+		background: var(--fab-btn-bg, oklch(0.25 0.02 250 / 0.5));
+		color: var(--fab-btn-fg, oklch(0.75 0.02 250));
+		border-color: var(--fab-btn-border, oklch(0.35 0.02 250));
 	}
-	.fab-btn-default:hover { background: oklch(0.30 0.02 250); }
+	.fab-btn-default:hover { background: var(--fab-btn-hover, oklch(0.30 0.02 250)); }
 
 	.fab-btn-primary {
-		background: oklch(0.65 0.18 250 / 0.15);
-		color: oklch(0.82 0.14 250);
-		border-color: oklch(0.65 0.18 250 / 0.3);
+		background: var(--fab-primary-bg, oklch(0.65 0.18 250 / 0.15));
+		color: var(--fab-primary-fg, oklch(0.82 0.14 250));
+		border-color: var(--fab-primary-border, oklch(0.65 0.18 250 / 0.3));
 	}
-	.fab-btn-primary:hover { background: oklch(0.65 0.18 250 / 0.25); }
+	.fab-btn-primary:hover { background: var(--fab-primary-hover, oklch(0.65 0.18 250 / 0.25)); }
 
 	.fab-btn-danger {
-		background: oklch(0.55 0.18 30 / 0.15);
-		color: oklch(0.80 0.15 30);
-		border-color: oklch(0.55 0.18 30 / 0.3);
+		background: var(--fab-danger-bg, oklch(0.55 0.18 30 / 0.15));
+		color: var(--fab-danger-fg, oklch(0.80 0.15 30));
+		border-color: var(--fab-danger-border, oklch(0.55 0.18 30 / 0.3));
 	}
-	.fab-btn-danger:hover { background: oklch(0.55 0.18 30 / 0.25); }
+	.fab-btn-danger:hover { background: var(--fab-danger-hover, oklch(0.55 0.18 30 / 0.25)); }
 
 	.fab-btn-warning {
 		background: oklch(0.75 0.15 85 / 0.12);
@@ -328,19 +381,23 @@
 
 	.fab-btn-clear {
 		background: transparent;
-		color: oklch(0.65 0.02 250);
+		color: var(--fab-muted, oklch(0.65 0.02 250));
 		border-color: transparent;
 	}
 	.fab-btn-clear:hover {
-		background: oklch(0.25 0.02 250);
-		color: oklch(0.80 0.02 250);
+		background: var(--fab-btn-hover, oklch(0.25 0.02 250));
+		color: var(--fab-fg, oklch(0.80 0.02 250));
+	}
+	.fab-btn:focus-visible {
+		outline: 2px solid var(--fab-focus, currentColor);
+		outline-offset: 1px;
 	}
 
 	.fab-spinner {
 		width: 14px;
 		height: 14px;
-		border: 2px solid oklch(0.35 0.02 250);
-		border-top-color: oklch(0.70 0.15 240);
+		border: 2px solid var(--fab-border, oklch(0.35 0.02 250));
+		border-top-color: var(--fab-spinner, oklch(0.70 0.15 240));
 		border-radius: 50%;
 		animation: fab-spin 0.6s linear infinite;
 		flex-shrink: 0;
@@ -389,13 +446,17 @@
 		left: 50%;
 		transform: translateX(-50%);
 		min-width: 160px;
-		background: oklch(0.18 0.02 250);
-		border: 1px solid oklch(0.30 0.02 250);
-		border-radius: 0.5rem;
+		background: var(--fab-menu-bg, oklch(0.18 0.02 250));
+		border: 1px solid var(--fab-border, oklch(0.30 0.02 250));
+		border-radius: var(--fab-menu-radius, 0.5rem);
 		padding: 0.375rem;
-		box-shadow: 0 8px 24px oklch(0.05 0 0 / 0.5);
+		box-shadow: var(--fab-menu-shadow, 0 8px 24px oklch(0.05 0 0 / 0.5));
 		z-index: 60;
 	}
+	.fab-inline .fab-dropdown {
+		left: 0;
+		transform: none;
+	}
 	.fab-dropdown-item {
 		display: flex;
 		align-items: center;
@@ -404,7 +465,7 @@
 		padding: 0.375rem 0.625rem;
 		border: none;
 		background: transparent;
-		color: oklch(0.80 0.02 250);
+		color: var(--fab-fg, oklch(0.80 0.02 250));
 		font-size: 0.75rem;
 		text-align: left;
 		border-radius: 0.375rem;
@@ -412,8 +473,15 @@
 		transition: background 0.1s;
 		white-space: nowrap;
 	}
-	.fab-dropdown-item:hover { background: oklch(0.25 0.02 250); }
+	.fab-dropdown-item:hover,
+	.fab-dropdown-item:focus-visible { background: var(--fab-btn-hover, oklch(0.25 0.02 250)); outline: none; }
 
+	.fab-item-label {
+		flex: 1;
+	}
+	.fab-item-hint {
+		margin-left: 1rem;
+	}
 	.fab-dot {
 		width: 8px;
 		height: 8px;

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

@@ -22,6 +22,8 @@ export interface DropdownItem {
     label: string;
     /** Optional colored dot (oklch string) */
     dotColor?: string;
+    /** Optional key hint shown at the item's right edge (display only; the host binds it). */
+    hint?: string;
     /** Optional SVG snippet rendered before the label */
     iconSnippet?: import('svelte').Snippet;
     /** Called when this item is clicked */
@@ -57,6 +59,13 @@ interface Props {
     onClear?: () => void;
     /** Label for the selection count (default: "selected") */
     countLabel?: string;
+    /**
+     * 'floating' (default): fixed, bottom-centre over the page.
+     * 'inline': in the normal flow, full width of its container — for a
+     * host that already has a sticky bar to put it in. Both wrap onto more
+     * lines rather than run off a narrow screen.
+     */
+    placement?: 'floating' | 'inline';
 }
 declare const FloatingActionBar: import("svelte").Component<Props, {}, "">;
 type FloatingActionBar = ReturnType<typeof FloatingActionBar>;