@djangocfg/ui-tools 2.1.408 → 2.1.409

package/README.md

@@ -163,7 +163,9 @@ Need a fully custom input row (e.g. mention autocomplete via `MarkdownEditor`)?
 
 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 are grouped under `UI Tools/Chat` into `Getting Started`, `Messages`, `Composer`, `Launcher`, `Transports` — plus `Overview` and a one-screen `Showcase`.
+**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`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.408",
+  "version": "2.1.409",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -154,8 +154,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.408",
-    "@djangocfg/ui-core": "^2.1.408",
+    "@djangocfg/i18n": "^2.1.409",
+    "@djangocfg/ui-core": "^2.1.409",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -210,9 +210,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.408",
-    "@djangocfg/typescript-config": "^2.1.408",
-    "@djangocfg/ui-core": "^2.1.408",
+    "@djangocfg/i18n": "^2.1.409",
+    "@djangocfg/typescript-config": "^2.1.409",
+    "@djangocfg/ui-core": "^2.1.409",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/Chat/README.md

@@ -56,6 +56,8 @@ export function MyChat() {
 - **Voice composer slot.** `<VoiceComposerSlot />` drops into `composer.slots.blockStart` with **zero props** — reads/writes the composer through the `ComposerHandle` registered in chat context. The built-in `<Composer>` and TipTap-backed `MarkdownEditor` register themselves automatically; custom composers wire it via `useRegisterComposer({ focus, moveCursorToEnd, getValue, setValue })`. Auto-gates on Firefox / in-app WebViews / missing `getUserMedia`, preserves typed prefix, 90-second countdown, silence auto-stop, Esc / Enter hotkeys, start / stop earcons. See [`SpeechRecognition`](../SpeechRecognition/README.md).
 - **Language flag button.** `headerSlots.languagePicker: true` slots a 28×28 country flag into the dock header — opens a searchable `<Combobox>` with 66 BCP-47 tags from the Chrome Web Speech catalogue. Selection persists via `useSpeechPrefs`, picked up by every `useSpeechRecognition` downstream. (Raw `<ChatHeaderLanguageButton>` still exported for custom shells.)
 - **Auto-focus on stream end.** `<ChatProvider>` re-focuses the registered composer on the streaming → idle edge — type → send → read → keep typing without reaching for the mouse. Works for **every** usage pattern (`ChatRoot`, hand-rolled `ChatProvider` + `Composer`, headless), not just `ChatRoot`. Opt out with `<ChatProvider autoFocusOnStreamEnd={false}>`. The standalone `useAutoFocusOnStreamEnd()` hook is still exported for advanced cases (focus a non-composer target, drive `isStreaming` from your own store).
+- **Page-context snapshot.** Optional `getDynamicMetadata` contributor on `<ChatProvider>` / `<ChatRoot>` — called fresh at send time, merged into transport `metadata`. Pairs with the `page-snapshot` engine (`src/lib/page-snapshot`) to attach a token-efficient, redacted snapshot of the page the user is looking at, so the assistant can answer in context. The snapshot rides a separate `metadata` field, never the message text.
+- **AI highlight directives.** `highlight/` — when the assistant returns `point` directives, `<HighlightOverlay>` resolves each CST ref to a live element and draws an SVG-mask spotlight (optionally moves focus). Read-only: it points at the UI, never changes data. See [`highlight/README.md`](./highlight/README.md).
 - **Centralized colors.** Role-aware className tokens (`BUBBLE_SURFACE` / `ANCHOR` / `TOGGLE` / `DESTRUCTIVE_SURFACE`) + hooks (`useChatBubbleStyles`, `useChatRoleStyles`, `useChatDestructiveStyles`).
 - **Responsive.** FAB `size='responsive'` (default): phone → `sm`, tablet → `md`, desktop → `lg`. Side mode is desktop-only and falls back to popover below `lg`.
 - **Mobile fullscreen.** Dock auto-fills viewport below 768px via `useIsMobile`. Heights use `dvh/svh/lvh` so iOS Safari URL bar doesn't clip the chat.
@@ -671,9 +673,17 @@ for await (const event of parseSSE(res, { map: createPydanticAISSEMap() })) {
 
   // behavior
   focusOnEmptyClick                // default true
+
+  // page context — extra metadata computed fresh per send
+  getDynamicMetadata={() => ({ pageContext })}
 />
 ```
 
+`getDynamicMetadata` is forwarded to the `<ChatProvider>` that `ChatRoot`
+creates; it is **ignored** when `ChatRoot` mounts under an ambient
+provider — set it on that provider instead. Typically wired from
+`usePageSnapshot().getChatMetadata` (see `src/lib/page-snapshot`).
+
 The `slots.header` / `slots.empty` accept either a `ReactNode` or a render
 function — there is no separate `renderHeader` / `renderEmpty` prop and no
 "which one wins" precedence. `composer.render` fully replaces the built-in

package/src/tools/Chat/shell/ChatRoot.tsx

@@ -148,10 +148,28 @@ export interface ChatRootProps {
    * @default true
    */
   focusOnEmptyClick?: boolean;
+  /**
+   * Contribute extra transport metadata, computed fresh per send.
+   * Forwarded to the `<ChatProvider>` this component creates — ignored
+   * when mounted under an ambient provider (set it on that provider
+   * instead). Used to attach the page-context snapshot.
+   */
+  getDynamicMetadata?: () => Record<string, unknown> | undefined;
 }
 
 export function ChatRoot(props: ChatRootProps) {
-  const { transport, config, session, streaming, audio, debug, className, listClassName, ...rest } = props;
+  const {
+    transport,
+    config,
+    session,
+    streaming,
+    audio,
+    debug,
+    className,
+    listClassName,
+    getDynamicMetadata,
+    ...rest
+  } = props;
   // When mounted under a launcher-owned `<ChatProvider>`, reuse that
   // provider instead of wrapping in a second one. This lets host code
   // freely nest `<ChatRoot>` inside `<ChatLauncher>` without losing
@@ -175,6 +193,7 @@ export function ChatRoot(props: ChatRootProps) {
       audio={audio}
       debug={debug}
       blockRegistry={rest.messages?.blockRegistry}
+      getDynamicMetadata={getDynamicMetadata}
     >
       <ChatRootShell className={className} listClassName={listClassName} parts={rest} />
     </ChatProvider>