@djangocfg/ui-tools 2.1.407 → 2.1.409

package/README.md

@@ -72,7 +72,7 @@ Subpaths come in three flavors:
 
 | Subpath | Ships | Notes |
 |---------|-------|-------|
-| `@djangocfg/ui-tools/chat` | `LazyChat`, `LazyChatLauncher`, plus the raw components (`ChatRoot`, `ChatLauncher`, `MessageBubble`, `Composer`, header buttons, …), transports (`createPydanticAIChatTransport`, `createHttpTransport`, …), hooks (`useChat`, `useChatAudio`, …), reducer/core/types/style tokens | Use the `Lazy*` wrappers when possible. The raw components are re-exported synchronously for callers that compose custom chat shells — importing them pulls the dependency graph eagerly. |
+| `@djangocfg/ui-tools/chat` | `LazyChat`, `LazyChatLauncher`, plus the raw components (`ChatRoot`, `ChatLauncher`, `MessageBubble`, `Composer`, `MessageBlocks`, header buttons, …), the composer kit (`ComposerMenuButton`, `ComposerBanner`, `ComposerToolPill`, `ComposerModelPicker`, `ComposerRichTextarea`, …), transports (`createPydanticAIChatTransport`, `createHttpTransport`, …), hooks (`useChat`, `useChatComposer`, …), reducer/core/types/style tokens | Use the `Lazy*` wrappers when possible. The raw components are re-exported synchronously for callers that compose custom chat shells — importing them pulls the dependency graph eagerly. |
 | `@djangocfg/ui-tools/code-editor` | `LazyEditor`, `LazyDiffEditor`, `useMonaco`, `useEditor`, `useLanguage`, `useEditorTheme`, `EditorProvider`, types | Monaco (~550 KB) loads only when an editor mounts. `useMonaco` does its own dynamic import. |
 | `@djangocfg/ui-tools/audio-player` | `LazyPlayer`, `PlayerProvider`, selector hooks, slot components (`Cover`, `Title`, `PlayButton`, `Waveform`, …), peaks-cache helpers, store, types | Slot components are presentational — safe synchronous re-exports. They only do anything inside a `<LazyPlayer>` provider. |
 | `@djangocfg/ui-tools/markdown-editor` | `LazyMarkdownEditor`, `mentionPresets`, types | TipTap + ProseMirror (~200 KB) only loads via the lazy wrapper. |
@@ -159,11 +159,13 @@ function Chat() {
 
 **What's wired by default:** desktop side-mode toggle (auto-hides on narrow screens), persisted dock prefs, two-step Escape, click-to-focus composer, mobile fullscreen with `dvh` heights, push-preview bubble for inbound messages while closed, **ChatGPT-style autoscroll** (sticky-to-bottom within 120 px, every user-send re-anchors the viewport), **bundled chat notification sounds** (sent/received/start/error/mention/notification, ~136KB inlined as `data:`-URLs inside the lazy chat chunk — zero host setup). Native hosts (cmdop_go / Tauri) pass `audio={{ silenced: true, onSoundEvent }}` to keep web silent while routing triggers to the backend.
 
-Need a fully custom input row (e.g. mention autocomplete via `MarkdownEditor`)? Pass `renderComposer={({ composer }) => <YourComposer composer={composer} />}` to `<ChatRoot>` — it replaces the default `<Composer>` while keeping autoscroll, JumpToLatest, and history behaviour. Story: `UI Tools / Chat / Mentions / Machine Mentions`.
+Need a fully custom input row (e.g. mention autocomplete via `MarkdownEditor`)? Pass `composer={{ render: ({ composer }) => <YourComposer composer={composer} /> }}` to `<ChatRoot>` — it replaces the default `<Composer>` while keeping autoscroll, JumpToLatest, and history behaviour. Story: `UI Tools / Chat / Composer / Mentions`.
 
-Drop `<VoiceComposerSlot />` from `@djangocfg/ui-tools/speech-recognition` into `composerToolbarEnd` for live mic-to-text — **zero props**, reads / writes the composer through `ComposerHandle` registered in chat context. Set `headerSlots={{ languagePicker: true }}` on `<ChatLauncher>` for a flag-button language picker (66 BCP-47 tags). Both auto-hide on Firefox / in-app browsers / missing `getUserMedia`. See [`SpeechRecognition`](#speech-recognition--quick-start) below.
+Drop `<VoiceComposerSlot />` from `@djangocfg/ui-tools/speech-recognition` into the composer's `slots.blockStart` (`composer={{ slots: { blockStart: <VoiceComposerSlot /> } }}`) for live mic-to-text — **zero props**, reads / writes the composer through `ComposerHandle` registered in chat context. Set `headerSlots={{ languagePicker: true }}` on `<ChatLauncher>` for a flag-button language picker (66 BCP-47 tags). Both auto-hide on Firefox / in-app browsers / missing `getUserMedia`. See [`SpeechRecognition`](#speech-recognition--quick-start) below.
 
-Full docs: [`Chat/README.md`](src/tools/Chat/README.md). Stories: `Tools/Chat/{Basic,Bubbles,ToolCalls,Personas,Launcher,Header,Audio & Actions,Voice composer}`.
+**Page-context.** The assistant can see the page the user is on. The `page-snapshot` engine (`src/lib/page-snapshot`) walks the live DOM into a token-efficient, redacted snapshot; wire `getDynamicMetadata` on `<ChatRoot>` / `<ChatProvider>` (typically from `usePageSnapshot().getChatMetadata`) and it rides the request `metadata`. When the assistant replies with `point` directives, `<HighlightOverlay>` (`src/tools/Chat/highlight`) spotlights the referenced elements. Story: `UI Tools/Chat/Highlight`.
+
+Full docs: [`Chat/README.md`](src/tools/Chat/README.md). Stories are grouped under `UI Tools/Chat` into `Getting Started`, `Messages`, `Composer`, `Launcher`, `Transports`, `Highlight` — plus `Overview` and a one-screen `Showcase`.
 
 ---
 
@@ -194,14 +196,11 @@ function Dictate() {
 For the chat composer:
 
 ```tsx
-import {
-  VoiceComposerSlot,
-  ChatHeaderLanguageButton,
-} from '@djangocfg/ui-tools/speech-recognition';
+import { VoiceComposerSlot } from '@djangocfg/ui-tools/speech-recognition';
 
 <ChatRoot
   transport={transport}
-  composerToolbarEnd={<VoiceComposerSlot />}
+  composer={{ slots: { blockStart: <VoiceComposerSlot /> } }}
 />
 
 // Plus a flag-button language picker in the dock header:
@@ -210,7 +209,7 @@ import {
 
 **What's wired by default:** auto-hide on Firefox / in-app WebViews / missing `getUserMedia` (via `useVoiceSupport`); live interim+final stream into the composer via `ComposerHandle` (works transparently for the built-in textarea Composer and a TipTap MarkdownEditor); typed prefix anchored; focus + cursor-to-end on start and every partial; 90-second countdown + 2.5-second silence auto-stop; Esc cancels (without closing the chat) / Enter finishes (without submitting); persisted prefs (`djangocfg-stt:prefs`); `<SpeechRecognitionProvider>` for sharing engine state across the tree. Language picker shows 66 BCP-47 tags sourced from the Chrome Web Speech demo with country flags. Custom engines through `createHttpEngine` (REST/Whisper), `createWebSocketEngine` (Deepgram-style streaming), or `createExternalEngine` (Wails / Tauri / native sidecar — `onStart` / `onStop` / `subscribe` and you're done).
 
-Full docs: [`SpeechRecognition/README.md`](src/tools/SpeechRecognition/README.md). Stories: `Tools/SpeechRecognition/{Basic, DictationField, PushToTalk, MicMeter, CustomEngine: HTTP, CustomEngine: WebSocket, Language & Device, Errors}` + `Tools/Chat/{Voice composer, Launcher}` (flag-button picker in the dock header). Unit-tested with vitest (`pnpm test`, 21 cases).
+Full docs: [`SpeechRecognition/README.md`](src/tools/SpeechRecognition/README.md). Stories: `UI Tools/Speech/{Dictation, ComposerSlot, PushToTalk, MicMeter, Engines, Languages, Errors}` + `UI Tools/Chat/Composer/Speech & Attachments` and `UI Tools/Chat/Launcher/Playground` (flag-button picker in the dock header). Unit-tested with vitest (`pnpm test`, 21 cases).
 
 ---