@djangocfg/ui-tools 2.1.409 → 2.1.412

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.409",
+  "version": "2.1.412",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -154,13 +154,13 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.409",
-    "@djangocfg/ui-core": "^2.1.409",
+    "@djangocfg/i18n": "^2.1.412",
+    "@djangocfg/ui-core": "^2.1.412",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "tailwindcss": "^4.1.18",
     "zustand": "^5.0.0"
   },
@@ -210,19 +210,19 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.409",
-    "@djangocfg/typescript-config": "^2.1.409",
-    "@djangocfg/ui-core": "^2.1.409",
+    "@djangocfg/i18n": "^2.1.412",
+    "@djangocfg/typescript-config": "^2.1.412",
+    "@djangocfg/ui-core": "^2.1.412",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
-    "@types/node": "^24.7.2",
-    "@types/react": "^19.1.0",
-    "@types/react-dom": "^19.1.0",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "tailwindcss": "^4.1.18",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",

package/src/{tools/Chat/highlight → lib/browser-bridge}/README.md

@@ -1,8 +1,9 @@
-# Chat highlight — AI-driven `point` directives
+# Chat bridge — how the AI drives the user's page
 
 When the assistant answers a question about the page, it can also
-**point at the screen** — highlight and optionally focus the relevant
-elements. This module renders that.
+**act on it** — point at the screen, move focus, scroll an element into
+view. This module is that control surface, plus the overlay that draws
+the spotlight.
 
 ---
 
@@ -22,8 +23,9 @@ the spotlight is the same, but *what* it points at is decided by the AI
 in context, not a hard-coded step list. The SVG renderer here is in
 fact adapted from that deleted Tour component.
 
-**Read-only.** A `point` directive highlights / focuses an element. It
-never types, clicks, or changes the user's data.
+**Read-only by default.** A `point` directive highlights / focuses an
+element; it never types, clicks, or changes the user's data. The
+write-style commands (`fill`, `click`) are deliberately stubbed.
 
 ---
 
@@ -46,23 +48,42 @@ never types, clicks, or changes the user's data.
 
 ---
 
-## Files
+## Layout
 
-| File | Responsibility |
-|------|----------------|
-| `types.ts` | `PointDirective`, `HighlightTarget`, `SpotlightRect`, `CSTRefId`. |
-| `resolveRef.ts` | `resolveRefs()` — CST ref → live DOM element via a `RefResolver`. Drops stale / detached refs. |
-| `useHighlightTargets.ts` | Hook: directives → geometry-tracked targets. Re-measures on scroll/resize, scrolls the first off-screen target in, focuses on request, drops a target when its element leaves the DOM. |
-| `SpotlightCanvas.tsx` | Pure SVG-mask renderer — dimmed scrim with rounded cut-outs, border, pulse ring. Takes geometry, not elements. |
-| `HighlightOverlay.tsx` | The component: hook + canvas + captions, portalled to `body`, auto-dismiss (TTL / Esc / scrim click). |
-| `index.ts` | Public barrel. |
+The module has two layers — `browser-bridge/` is *how the AI drives the
+browser*, `overlay/` is *how a highlight is drawn*.
+
+```
+browser-bridge/
+  index.ts             Public barrel.
+  registry.ts          BridgeCommand interface + the command registry.
+  setBridgeResolver.ts Holds the live ref→element resolver the commands read.
+  directive-bus.ts     SSE `directive` event → singleton bus.
+  window.ts            installChatBridge — dev-only window.__chatBridge.
+  commands/
+    index.ts           Registers + re-exports every built-in command.
+    highlight.ts       highlight, focus, clear.
+    scroll.ts          scrollTo.
+    inspect.ts         inspect.
+    write.ts           fill, click (stubs — need a confirmation gate).
+  overlay/
+    index.ts           Overlay barrel.
+    types.ts           PointDirective, HighlightTarget, SpotlightRect, CSTRefId.
+    resolveRef.ts      resolveRefs() — CST ref → live element via a RefResolver.
+    useHighlightTargets.ts  Hook: directives → geometry-tracked targets.
+    SpotlightCanvas.tsx     Pure SVG-mask renderer (scrim, cut-outs, pulse).
+    HighlightOverlay.tsx    The component: hook + canvas + captions.
+```
+
+Commands are one-per-file: adding a capability is a new file in
+`commands/`, registered in `commands/index.ts`.
 
 ---
 
 ## Usage
 
 ```tsx
-import { HighlightOverlay } from '@djangocfg/ui-tools/.../Chat/highlight';
+import { HighlightOverlay } from '@djangocfg/ui-tools/chat';
 
 <HighlightOverlay
   directives={directivesFromLastDirectiveEvent}
@@ -78,6 +99,11 @@ import { HighlightOverlay } from '@djangocfg/ui-tools/.../Chat/highlight';
   `page-snapshot` engine's `RefRegistry` satisfies this. Structurally
   typed on purpose, so this module does not import the capture engine.
 
+In development, `installChatBridge()` exposes the registry on
+`window.__chatBridge` — run `__chatBridge.help()` for the command list,
+or `__chatBridge.highlight(['@e4'])` to see the spotlight without an
+AI / SSE round-trip.
+
 ---
 
 ## Staleness
@@ -91,9 +117,11 @@ only ever shows live elements.
 
 ## Decoupling notes
 
-- This module lives under `Chat/` because `point` is a chat feature and
-  it has exactly one consumer. If a second consumer ever appears,
-  promote it to a shared location — not before.
+- This module lives under `lib/` — it is infrastructure ("the AI reads
+  and acts on the user's page"), the sibling of `lib/page-snapshot/`.
+  Chat is merely a consumer: it re-exports this barrel via
+  `@djangocfg/ui-tools/chat`. `lib/` must never import from `tools/`,
+  so the bridge carries its own minimal `logger.ts`.
 - It does not import the `page-snapshot` capture engine. It depends only
   on the structural `RefResolver` interface, so the two stay
   independent.

package/src/lib/browser-bridge/commands/chat.ts

@@ -0,0 +1,42 @@
+'use client';
+
+/**
+ * Chat commands — drive the chat conversation from the bridge.
+ *
+ * `sendMessage` posts a message exactly as if typed into the composer
+ * (same transport, same SSE response). Useful for testing the chat —
+ * incl. the page-context highlight flow — from the devtools console
+ * without retyping prompts.
+ */
+
+import { log } from '../logger';
+import { registerBridgeCommand } from '../registry';
+import { getActiveSender } from '../setBridgeResolver';
+
+/**
+ * sendMessage — send a chat message programmatically.
+ *
+ * Goes through the same `sendMessage` the composer uses, so the full
+ * round-trip runs (transport, streamed reply, any directives). Resolves
+ * when the send is dispatched; the reply streams asynchronously after.
+ */
+export const sendMessage = registerBridgeCommand({
+  name: 'sendMessage',
+  description: 'sendMessage(text) — send a chat message as if typed',
+  mutates: true,
+  run: async (text: string): Promise<{ sent: boolean }> => {
+    const sender = getActiveSender();
+    if (!sender) {
+      log.warn('bridge.sendMessage: no chat sender registered');
+      return { sent: false };
+    }
+    const content = String(text ?? '').trim();
+    if (!content) {
+      log.warn('bridge.sendMessage: empty message');
+      return { sent: false };
+    }
+    log.info('bridge.sendMessage', { chars: content.length });
+    await sender(content);
+    return { sent: true };
+  },
+});

package/src/lib/browser-bridge/commands/highlight.ts

@@ -0,0 +1,70 @@
+'use client';
+
+/**
+ * Spotlight commands — `highlight`, `focus`, `clear`.
+ *
+ * All three drive the directive bus the AI uses, so the overlay reacts
+ * identically whether the source is an SSE event or a console call.
+ */
+
+import { log } from '../logger';
+import { pushDirectives, clearDirectives } from '../directive-bus';
+import { registerBridgeCommand } from '../registry';
+import type { CSTRefId, PointDirective } from '../overlay/types';
+
+/** Coerce loose console input ("@e4" or ["@e4","@e5"]) into a ref list. */
+function toRefList(input: CSTRefId | CSTRefId[]): CSTRefId[] {
+  return Array.isArray(input) ? input : [input];
+}
+
+/**
+ * highlight — spotlight one or more elements by CST ref.
+ * Drives the same directive bus the AI uses, so the overlay reacts
+ * identically whether the source is an SSE event or a console call.
+ */
+export const highlight = registerBridgeCommand({
+  name: 'highlight',
+  description: 'highlight(refs, opts?) — spotlight element(s) by CST ref',
+  mutates: false,
+  run: (
+    refs: CSTRefId | CSTRefId[],
+    opts?: { focus?: boolean; label?: string },
+  ): { dispatched: number } => {
+    const list = toRefList(refs);
+    const directives: PointDirective[] = list.map((ref) => ({
+      type: 'point',
+      ref,
+      focus: opts?.focus,
+      label: opts?.label,
+    }));
+    log.info('bridge.highlight', { refs: list, opts });
+    pushDirectives(directives);
+    return { dispatched: directives.length };
+  },
+});
+
+/**
+ * focus — spotlight a single element AND move keyboard focus into it.
+ * A thin convenience over `highlight` with `focus: true`.
+ */
+export const focus = registerBridgeCommand({
+  name: 'focus',
+  description: 'focus(ref, label?) — highlight an element and focus it',
+  mutates: false,
+  run: (ref: CSTRefId, label?: string): { dispatched: number } => {
+    log.info('bridge.focus', { ref, label });
+    pushDirectives([{ type: 'point', ref, focus: true, label }]);
+    return { dispatched: 1 };
+  },
+});
+
+/** clear — dismiss any active highlight overlay. */
+export const clear = registerBridgeCommand({
+  name: 'clear',
+  description: 'clear() — remove the active highlight overlay',
+  mutates: false,
+  run: (): void => {
+    log.info('bridge.clear');
+    clearDirectives();
+  },
+});

package/src/lib/browser-bridge/commands/index.ts

@@ -0,0 +1,15 @@
+'use client';
+
+/**
+ * Built-in bridge commands.
+ *
+ * Importing this module registers every command into the shared
+ * registry (registration is a side effect of each command file). New
+ * capabilities are added as a new file here, re-exported below.
+ */
+
+export { highlight, focus, clear } from './highlight';
+export { scrollTo } from './scroll';
+export { inspect } from './inspect';
+export { fill, click } from './write';
+export { sendMessage } from './chat';

package/src/lib/browser-bridge/commands/inspect.ts

@@ -0,0 +1,31 @@
+'use client';
+
+/**
+ * inspect command — a read-only probe of ref freshness.
+ */
+
+import { log } from '../logger';
+import { registerBridgeCommand } from '../registry';
+import { getActiveResolver } from '../setBridgeResolver';
+import { resolveRefs } from '../overlay/resolveRef';
+import type { CSTRefId } from '../overlay/types';
+
+/**
+ * inspect — report which CST refs currently resolve to live elements.
+ * A read-only probe: useful for the AI (or a tester) to confirm the
+ * snapshot is still fresh before pointing at something.
+ */
+export const inspect = registerBridgeCommand({
+  name: 'inspect',
+  description: 'inspect(refs) — report which refs resolve to live elements',
+  mutates: false,
+  run: (refs: CSTRefId[]): { resolved: CSTRefId[]; missing: CSTRefId[] } => {
+    const ok = new Set(resolveRefs(refs, getActiveResolver()).map((r) => r.ref));
+    const result = {
+      resolved: refs.filter((r) => ok.has(r)),
+      missing: refs.filter((r) => !ok.has(r)),
+    };
+    log.info('bridge.inspect', result);
+    return result;
+  },
+});

package/src/lib/browser-bridge/commands/scroll.ts

@@ -0,0 +1,31 @@
+'use client';
+
+/**
+ * scroll command — bring an element into view without a spotlight.
+ */
+
+import { log } from '../logger';
+import { registerBridgeCommand } from '../registry';
+import { getActiveResolver } from '../setBridgeResolver';
+import { resolveRefs } from '../overlay/resolveRef';
+import type { CSTRefId } from '../overlay/types';
+
+/**
+ * scrollTo — bring an element into view without drawing a spotlight.
+ * Resolves the ref directly (no overlay) and scrolls.
+ */
+export const scrollTo = registerBridgeCommand({
+  name: 'scrollTo',
+  description: 'scrollTo(ref) — scroll an element into view',
+  mutates: false,
+  run: (ref: CSTRefId): { ok: boolean } => {
+    const [resolved] = resolveRefs([ref], getActiveResolver());
+    if (!resolved) {
+      log.warn('bridge.scrollTo: ref did not resolve', { ref });
+      return { ok: false };
+    }
+    resolved.element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    log.info('bridge.scrollTo', { ref });
+    return { ok: true };
+  },
+});

package/src/lib/browser-bridge/commands/write.ts

@@ -0,0 +1,45 @@
+'use client';
+
+/**
+ * Write-style command stubs — `fill`, `click`.
+ *
+ * Filling an input or clicking a control changes the user's data, so
+ * each needs an explicit confirmation gate before it can be enabled.
+ * They are registered (so they appear in `__chatBridge.help()`) but
+ * intentionally not implemented yet.
+ */
+
+import { log } from '../logger';
+import { registerBridgeCommand } from '../registry';
+import type { CSTRefId } from '../overlay/types';
+
+/**
+ * Stub for a future write-style command. Filling an input changes the
+ * user's data, so it needs an explicit confirmation gate before it can
+ * be enabled — intentionally not implemented yet.
+ */
+export const fill = registerBridgeCommand({
+  name: 'fill',
+  description: 'fill(ref, value) — [not implemented] type into an input',
+  mutates: true,
+  run: (ref: CSTRefId, value: string): { ok: false; reason: string } => {
+    log.warn('bridge.fill: not implemented (needs a confirmation gate)', {
+      ref,
+      value,
+    });
+    return { ok: false, reason: 'not-implemented' };
+  },
+});
+
+/** Stub for a future write-style command — see `fill`. */
+export const click = registerBridgeCommand({
+  name: 'click',
+  description: 'click(ref) — [not implemented] click an element',
+  mutates: true,
+  run: (ref: CSTRefId): { ok: false; reason: string } => {
+    log.warn('bridge.click: not implemented (needs a confirmation gate)', {
+      ref,
+    });
+    return { ok: false, reason: 'not-implemented' };
+  },
+});

package/src/lib/browser-bridge/directive-bus.ts

@@ -0,0 +1,120 @@
+'use client';
+
+/**
+ * AI directive bus — receives `point` directives off the chat SSE
+ * stream and exposes them to the highlight overlay.
+ *
+ * The backend emits a `directive` SSE event carrying highlight/focus
+ * instructions keyed by CST ref ids. A host transport observes the raw
+ * frame and calls `pushDirectives`; the chat UI subscribes through
+ * `useChatDirectives` and feeds the result to `<HighlightOverlay>`.
+ *
+ * A singleton bus keeps the transport (which has no React context)
+ * decoupled from the consuming component.
+ */
+
+import { useSyncExternalStore } from 'react';
+
+import { log } from './logger';
+import type { PointDirective } from './overlay/types';
+
+// ─── Wire parsing ───────────────────────────────────────────────────
+
+/** A CST ref looks like "@e4". */
+const REF_RE = /^@e\d+$/;
+
+/**
+ * Validate the raw `directives` array from a `directive` SSE frame.
+ *
+ * The backend already validates refs against the snapshot, but the wire
+ * is untyped at this boundary — drop anything malformed so a bad frame
+ * can never crash the overlay.
+ */
+export function parseDirectives(raw: unknown): PointDirective[] {
+  if (!Array.isArray(raw)) {
+    log.warn('parseDirectives: payload is not an array', { raw });
+    return [];
+  }
+  const out: PointDirective[] = [];
+  let dropped = 0;
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') {
+      dropped++;
+      continue;
+    }
+    const d = item as Record<string, unknown>;
+    if (d.type !== 'point') {
+      dropped++;
+      continue;
+    }
+    if (typeof d.ref !== 'string' || !REF_RE.test(d.ref)) {
+      log.warn('parseDirectives: dropped directive with bad ref', { ref: d.ref });
+      dropped++;
+      continue;
+    }
+    const directive: PointDirective = {
+      type: 'point',
+      ref: d.ref as PointDirective['ref'],
+    };
+    if (d.highlight === false) directive.highlight = false;
+    if (d.focus === true) directive.focus = true;
+    if (typeof d.label === 'string' && d.label.trim()) {
+      directive.label = d.label.trim();
+    }
+    out.push(directive);
+  }
+  log.info('parseDirectives', { in: raw.length, out: out.length, dropped });
+  return out;
+}
+
+// ─── Singleton bus ──────────────────────────────────────────────────
+
+let current: PointDirective[] = [];
+const subscribers = new Set<() => void>();
+
+function notify(): void {
+  for (const s of subscribers) s();
+}
+
+/**
+ * Transport-side entry point. Replaces the active directive set — the
+ * latest `directive` event for a turn wins; an empty array clears the
+ * overlay. Called synchronously from a host transport's event handler.
+ */
+export function pushDirectives(directives: PointDirective[]): void {
+  log.info('pushDirectives → bus', {
+    count: directives.length,
+    refs: directives.map((d) => d.ref),
+    subscribers: subscribers.size,
+  });
+  current = directives;
+  notify();
+}
+
+/** Clear the active directives (e.g. when the overlay is dismissed). */
+export function clearDirectives(): void {
+  if (current.length === 0) return;
+  log.info('clearDirectives');
+  current = [];
+  notify();
+}
+
+function subscribe(cb: () => void): () => void {
+  subscribers.add(cb);
+  return () => subscribers.delete(cb);
+}
+
+function getSnapshot(): PointDirective[] {
+  return current;
+}
+
+/** Stable empty reference for the SSR snapshot. */
+const EMPTY: PointDirective[] = [];
+
+/**
+ * Subscribe to the active `point` directives. Re-renders the caller
+ * whenever a new `directive` event arrives or the set is cleared.
+ */
+export function useChatDirectives(): PointDirective[] {
+  return useSyncExternalStore(subscribe, getSnapshot, () => EMPTY);
+}

package/src/lib/browser-bridge/index.ts

@@ -0,0 +1,56 @@
+'use client';
+
+/**
+ * Chat bridge — how the AI drives the user's live page.
+ *
+ * Two layers:
+ *
+ * - `bridge/` proper — the command registry, the built-in commands, and
+ *   the directive transport (SSE → singleton bus). This is the AI's
+ *   control surface over the browser.
+ * - `overlay/` — how a `point` directive is drawn: ref resolution,
+ *   geometry tracking, and the SVG-mask spotlight.
+ *
+ * Read-only by default. Commands that would change the user's data
+ * (`fill`, `click`) are deliberately stubbed.
+ */
+
+// Overlay — how a highlight is drawn.
+export {
+  HighlightOverlay,
+  type HighlightOverlayProps,
+  SpotlightCanvas,
+  type SpotlightCanvasProps,
+  useHighlightTargets,
+  resolveRefs,
+  type RefResolver,
+  type PointDirective,
+  type HighlightTarget,
+  type SpotlightRect,
+  type CSTRefId,
+} from './overlay';
+
+// Directive transport — SSE `directive` event → singleton bus.
+export {
+  useChatDirectives,
+  pushDirectives,
+  clearDirectives,
+  parseDirectives,
+} from './directive-bus';
+
+// Command registry + the ref resolver the commands read.
+export {
+  registerBridgeCommand,
+  getBridgeCommand,
+  type BridgeCommand,
+} from './registry';
+export {
+  setBridgeResolver,
+  setBridgeSender,
+  type BridgeSender,
+} from './setBridgeResolver';
+
+// `window.__chatBridge` install (dev-gated). Importing this transitively
+// pulls in `./commands`, whose modules register the built-in commands
+// into the registry as a side effect.
+export { installChatBridge, type ChatBridge } from './window';

package/src/lib/browser-bridge/logger.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser-bridge dev logger.
+ *
+ * A self-contained namespaced `consola` logger for the bridge subsystem
+ * (page-context `point` directives: SSE event → bus → overlay). It is a
+ * sibling of `lib/page-snapshot/`, so it must NOT reach up into `tools/` —
+ * the bridge is infrastructure, Chat is merely a consumer.
+ *
+ * Mirrors the gating of the chat logger (`tools/Chat/core/logger.ts`): the
+ * `chat:directives` sub-logger is silenced unless `isDev`, so noisy bridge
+ * events never leak into production builds. Kept local and minimal — only
+ * the `directives` scope is needed here.
+ */
+import { consola } from 'consola';
+
+import { isDev } from '@djangocfg/ui-core/lib';
+
+/**
+ * Namespaced logger for bridge directives. Tagged `chat:directives` to stay
+ * consistent with the chat logger's scope naming. No-ops in production.
+ */
+export const log = consola.withTag('chat').withTag('directives');
+
+// Silence in production — bridge directive logs are dev-only diagnostics.
+if (!isDev) {
+  log.level = -999;
+}

package/src/{tools/Chat/highlight → lib/browser-bridge/overlay}/HighlightOverlay.tsx

@@ -3,6 +3,7 @@
 import { useEffect } from 'react';
 import { createPortal } from 'react-dom';
 
+import { log } from '../logger';
 import { SpotlightCanvas } from './SpotlightCanvas';
 import type { PointDirective, SpotlightRect } from './types';
 import { useHighlightTargets } from './useHighlightTargets';
@@ -40,6 +41,16 @@ export function HighlightOverlay({
 }: HighlightOverlayProps) {
   const targets = useHighlightTargets(directives, resolver);
 
+  // Trace why the overlay does or does not show — the common failure is
+  // directives arriving with no resolver, or refs that resolve to nothing.
+  useEffect(() => {
+    log.info('HighlightOverlay render', {
+      directives: directives.length,
+      hasResolver: resolver !== null,
+      resolvedTargets: targets.length,
+    });
+  }, [directives, resolver, targets.length]);
+
   // Auto-dismiss after the TTL once something is showing.
   useEffect(() => {
     if (targets.length === 0 || ttlMs <= 0) return;
@@ -67,6 +78,9 @@ export function HighlightOverlay({
 
   return createPortal(
     <div
+      // Above page content (sticky headers ~z-40) but below the chat
+      // companion/dock tiers (99/100) — it points at page elements, so it
+      // must not cover the chat or any ui-core overlay.
       className="pointer-events-none fixed inset-0 z-[60]"
       data-chat-highlight-overlay=""
     >