@djangocfg/ui-tools 2.1.409 → 2.1.412

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

@@ -19,6 +19,25 @@ if (typeof globalThis.ResizeObserver === 'undefined') {
   };
 }
 
+// jsdom has no IntersectionObserver — the overlay uses it to wait for
+// an off-screen target to become visible. Stub it to report the
+// observed element as immediately intersecting so the wait resolves.
+if (typeof globalThis.IntersectionObserver === 'undefined') {
+  (globalThis as Record<string, unknown>).IntersectionObserver = class {
+    private cb: (entries: unknown[]) => void;
+    constructor(cb: (entries: unknown[]) => void) {
+      this.cb = cb;
+    }
+    observe(target: Element) {
+      this.cb([
+        { target, isIntersecting: true, intersectionRatio: 1 },
+      ]);
+    }
+    unobserve() {}
+    disconnect() {}
+  };
+}
+
 let container: HTMLDivElement;
 let root: Root;
 
@@ -109,4 +128,37 @@ describe('HighlightOverlay', () => {
     );
     expect(document.activeElement).not.toBe(el);
   });
+
+  it('scrolls an off-screen target into view before drawing it', async () => {
+    const el = document.createElement('button');
+    document.body.appendChild(el);
+
+    // Report the element below the viewport so it counts as off-screen.
+    el.getBoundingClientRect = () =>
+      ({ top: 5000, left: 0, bottom: 5040, right: 80, width: 80, height: 40, x: 0, y: 5000 }) as DOMRect;
+
+    let scrolled = false;
+    el.scrollIntoView = () => {
+      scrolled = true;
+    };
+
+    await render(
+      [{ type: 'point', ref: '@e1' }],
+      makeResolver({ '@e1': el }),
+    );
+
+    // Let the visibility wait resolve and its rAF-scheduled re-measure
+    // run, so the now-ready target is drawn.
+    await act(async () => {
+      await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    });
+
+    // The off-screen target was scrolled into view, and once the
+    // (stubbed) IntersectionObserver reports it visible the overlay
+    // draws the spotlight.
+    expect(scrolled).toBe(true);
+    expect(
+      document.querySelector('[data-chat-highlight-overlay]'),
+    ).not.toBeNull();
+  });
 });

package/src/{tools/Chat/highlight → lib/browser-bridge/overlay}/__tests__/resolveRef.test.ts

@@ -1,6 +1,8 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it } from 'vitest';
 
+import { computeLocator } from '../../../page-snapshot/refs/locator';
+import { RefRegistry } from '../../../page-snapshot/refs/registry';
 import { resolveRefs, type RefResolver } from '../resolveRef';
 import type { CSTRefId } from '../types';
 
@@ -53,3 +55,40 @@ describe('resolveRefs', () => {
     expect(out.map((o) => o.ref)).toEqual(['@e1']);
   });
 });
+
+describe('resolveRefs against a live RefRegistry', () => {
+  it('resolves a ref after the captured node is recreated by a re-render', () => {
+    // Capture: the snapshot registry stores a locator, not a node.
+    const original = document.createElement('a');
+    original.id = 'cta';
+    original.textContent = 'Browse Catalog';
+    document.body.appendChild(original);
+
+    const registry = new RefRegistry('snap-1');
+    registry.set('@e1', computeLocator(original, 'link'));
+
+    // React re-render replaces the node with a fresh equivalent — the
+    // original is now detached, exactly the production failure mode.
+    original.remove();
+    const fresh = document.createElement('a');
+    fresh.id = 'cta';
+    fresh.textContent = 'Browse Catalog';
+    document.body.appendChild(fresh);
+
+    const out = resolveRefs(['@e1'], registry);
+    expect(out).toHaveLength(1);
+    expect(out[0].element).toBe(fresh);
+  });
+
+  it('drops a ref whose element is genuinely gone', () => {
+    const el = document.createElement('button');
+    el.textContent = 'Delete';
+    document.body.appendChild(el);
+
+    const registry = new RefRegistry('snap-1');
+    registry.set('@e1', computeLocator(el, 'button'));
+
+    el.remove();
+    expect(resolveRefs(['@e1'], registry)).toEqual([]);
+  });
+});

package/src/{tools/Chat/highlight → lib/browser-bridge/overlay}/index.ts

@@ -1,18 +1,21 @@
 'use client';
 
 /**
- * Chat highlight — AI-driven `point` directives.
+ * Highlight overlay — how a `point` directive is drawn.
  *
- * When the assistant returns `point` directives, this module resolves
- * the CST refs to live elements and draws a spotlight overlay over
- * them (and optionally focuses one). Read-only: it never changes the
- * user's data.
+ * Resolves CST refs to live elements, tracks their geometry, and draws
+ * an SVG-mask spotlight over them. Read-only: it highlights and
+ * optionally focuses elements, never changes the user's data.
  */
 
 export { HighlightOverlay, type HighlightOverlayProps } from './HighlightOverlay';
 export { SpotlightCanvas, type SpotlightCanvasProps } from './SpotlightCanvas';
 export { useHighlightTargets } from './useHighlightTargets';
 export { resolveRefs, type RefResolver } from './resolveRef';
+export {
+  waitForVisible,
+  type WaitForVisibleOptions,
+} from './waitForVisible';
 export type {
   PointDirective,
   HighlightTarget,

package/src/{tools/Chat/highlight → lib/browser-bridge/overlay}/resolveRef.ts

@@ -8,6 +8,11 @@
  *
  * A ref that no longer resolves is "stale" — the element was removed or
  * the user navigated away. Callers treat a null result as stale.
+ *
+ * The registry resolves each ref with a live-DOM query, so a ref
+ * survives React recreating nodes between capture and directive
+ * application. The `isConnected` check below is a defensive backstop —
+ * a live query already returns connected elements.
  */
 
 import type { CSTRefId } from './types';

package/src/{tools/Chat/highlight → lib/browser-bridge/overlay}/useHighlightTargets.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 
 import { resolveRefs, type RefResolver } from './resolveRef';
 import type { HighlightTarget, PointDirective } from './types';
+import { waitForVisible } from './waitForVisible';
 
 /** Is a rect fully inside the viewport. */
 function isOnScreen(rect: DOMRect): boolean {
@@ -20,8 +21,10 @@ function isOnScreen(rect: DOMRect): boolean {
  * targets.
  *
  * - resolves each ref to a DOM element (drops stale ones);
+ * - scrolls an off-screen target into view and waits until it is
+ *   actually visible before exposing it — so the spotlight is drawn at
+ *   the element's settled position, never mid-scroll;
  * - measures rects and keeps them fresh on scroll / resize;
- * - scrolls the first off-screen target into view;
  * - moves focus into a target when the directive asked for it;
  * - drops a target automatically if its element leaves the DOM.
  *
@@ -57,11 +60,21 @@ export function useHighlightTargets(
       return;
     }
 
-    // Measure all targets — called now and on every scroll / resize.
+    let cancelled = false;
+
+    // A pair is only drawn once `ready` is true. Already-visible
+    // targets are ready immediately; off-screen ones become ready
+    // after their scroll-into-view settles (or its safety timeout).
+    const ready = new WeakSet<HTMLElement>();
+
+    // Measure all *ready* targets — called now and on every
+    // scroll / resize. Off-screen-but-not-yet-settled targets are
+    // skipped so their spotlight is never drawn at a stale position.
     const measure = () => {
       const next: HighlightTarget[] = [];
       for (const { element, directive } of pairs) {
         if (!element.isConnected) continue; // element left the DOM
+        if (!ready.has(element)) continue; // still scrolling into view
         next.push({
           element,
           rect: element.getBoundingClientRect(),
@@ -78,37 +91,55 @@ export function useHighlightTargets(
       frame = requestAnimationFrame(measure);
     };
 
-    // Scroll the first target into view if it is off-screen.
-    const first = pairs[0].element;
-    const firstOffScreen = !isOnScreen(first.getBoundingClientRect());
-    if (firstOffScreen) {
-      first.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    // Split targets into the ones already on screen and the ones that
+    // need to be scrolled into view first.
+    const offScreen: HTMLElement[] = [];
+    for (const { element } of pairs) {
+      if (isOnScreen(element.getBoundingClientRect())) {
+        ready.add(element);
+      } else {
+        offScreen.push(element);
+      }
     }
 
-    // Focus a target if requested — after any scroll settles.
+    // Scroll each off-screen target into view, then wait until it is
+    // actually visible before marking it ready and re-measuring.
+    for (const element of offScreen) {
+      element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      void waitForVisible(element).then(() => {
+        if (cancelled || !element.isConnected) return;
+        ready.add(element);
+        schedule();
+      });
+    }
+
+    // Focus a target if requested — after its scroll-into-view settles
+    // so focus() does not fight the smooth scroll.
     const focusPair = pairs.find((p) => p.directive.focus);
-    let focusTimer = 0;
     if (focusPair) {
       const el = focusPair.element;
-      focusTimer = window.setTimeout(
-        () => {
-          if (!el.isConnected) return;
-          // Make a non-focusable element focusable so focus() lands.
-          const nativelyFocusable = [
-            'INPUT',
-            'TEXTAREA',
-            'SELECT',
-            'BUTTON',
-            'A',
-          ].includes(el.tagName);
-          if (el.tabIndex < 0 && !nativelyFocusable) el.tabIndex = -1;
-          el.focus({ preventScroll: true });
-        },
-        firstOffScreen ? 400 : 0,
-      );
+      const applyFocus = () => {
+        if (cancelled || !el.isConnected) return;
+        // Make a non-focusable element focusable so focus() lands.
+        const nativelyFocusable = [
+          'INPUT',
+          'TEXTAREA',
+          'SELECT',
+          'BUTTON',
+          'A',
+        ].includes(el.tagName);
+        if (el.tabIndex < 0 && !nativelyFocusable) el.tabIndex = -1;
+        el.focus({ preventScroll: true });
+      };
+      if (isOnScreen(el.getBoundingClientRect())) {
+        applyFocus();
+      } else {
+        void waitForVisible(el).then(applyFocus);
+      }
     }
 
-    // Initial measure + keep geometry fresh.
+    // Initial measure (draws any already-visible targets) + keep
+    // geometry fresh.
     measure();
     window.addEventListener('scroll', schedule, true);
     window.addEventListener('resize', schedule);
@@ -116,8 +147,8 @@ export function useHighlightTargets(
     for (const { element } of pairs) observer.observe(element);
 
     return () => {
+      cancelled = true;
       cancelAnimationFrame(frame);
-      window.clearTimeout(focusTimer);
       window.removeEventListener('scroll', schedule, true);
       window.removeEventListener('resize', schedule);
       observer.disconnect();

package/src/lib/browser-bridge/overlay/waitForVisible.ts

@@ -0,0 +1,70 @@
+/**
+ * Wait until an element is actually visible in the viewport.
+ *
+ * The highlight overlay scrolls an off-screen target into view before
+ * drawing its spotlight — but `scrollIntoView({ behavior: 'smooth' })`
+ * settles asynchronously, so measuring the rect right after the call
+ * yields a stale (mid-scroll or still off-screen) position. This waits
+ * for the browser to confirm the element is on screen.
+ */
+
+/** Options for {@link waitForVisible}. */
+export interface WaitForVisibleOptions {
+  /**
+   * Fraction of the element that must be inside the viewport before it
+   * counts as visible (IntersectionObserver threshold).
+   */
+  threshold?: number;
+  /**
+   * Safety cap (ms). If the element never reaches the threshold — e.g.
+   * it is larger than the viewport, or hidden — the promise resolves
+   * anyway so the overlay never hangs. Fail soft.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Resolve once `element` is at least `threshold` visible in the
+ * viewport, or once `timeoutMs` elapses — whichever comes first.
+ *
+ * Always resolves (never rejects): a never-intersecting element must
+ * not stall the overlay. The boolean result reports whether the
+ * element became visible (`true`) or the timeout fired (`false`), for
+ * callers that want to log it.
+ */
+export function waitForVisible(
+  element: Element,
+  { threshold = 0.5, timeoutMs = 800 }: WaitForVisibleOptions = {},
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    // No IntersectionObserver (old/test env) — resolve immediately and
+    // let the caller measure as before.
+    if (typeof IntersectionObserver === 'undefined') {
+      resolve(false);
+      return;
+    }
+
+    let settled = false;
+    const finish = (visible: boolean) => {
+      if (settled) return;
+      settled = true;
+      window.clearTimeout(timer);
+      observer.disconnect();
+      resolve(visible);
+    };
+
+    const timer = window.setTimeout(() => finish(false), timeoutMs);
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+            finish(true);
+            return;
+          }
+        }
+      },
+      { threshold },
+    );
+    observer.observe(element);
+  });
+}

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

@@ -0,0 +1,41 @@
+'use client';
+
+/**
+ * Bridge command registry — the named, callable capabilities the chat
+ * assistant can run against the user's live page.
+ *
+ * The registry is the core of the bridge: directives, the dev
+ * `window.__chatBridge`, and e2e tests all dispatch the same commands
+ * through it, so a new capability is added without touching any caller.
+ */
+
+/** One bridge command — a named, documented, callable capability. */
+export interface BridgeCommand<A extends unknown[] = unknown[], R = unknown> {
+  /** Invocation name, also the `window.__chatBridge` key. */
+  name: string;
+  /** One-line human description — shown by `__chatBridge.help()`. */
+  description: string;
+  /** Whether the command mutates the user's data (vs read-only). */
+  mutates: boolean;
+  /** The implementation. */
+  run: (...args: A) => R;
+}
+
+/** Every registered command, keyed by name. */
+export const registry = new Map<string, BridgeCommand>();
+
+/**
+ * Register (or replace) a bridge command. Returns the command so it can
+ * be exported directly. Replacing is allowed — handy for HMR.
+ */
+export function registerBridgeCommand<A extends unknown[], R>(
+  cmd: BridgeCommand<A, R>,
+): BridgeCommand<A, R> {
+  registry.set(cmd.name, cmd as BridgeCommand);
+  return cmd;
+}
+
+/** Look up a registered command by name. */
+export function getBridgeCommand(name: string): BridgeCommand | undefined {
+  return registry.get(name);
+}

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

@@ -0,0 +1,42 @@
+'use client';
+
+/**
+ * Live connections handed to the bridge by the React layer.
+ *
+ * The bridge has no React context, so providers publish their
+ * capabilities here on mount and retract them on unmount:
+ *
+ *  - the ref→element resolver, owned by `PageSnapshotProvider`;
+ *  - the chat `sendMessage` function, owned by `ChatProvider`.
+ *
+ * Bridge commands read them through the getters below.
+ */
+
+import { type RefResolver } from './overlay/resolveRef';
+
+let activeResolver: RefResolver | null = null;
+
+/** Called by `PageSnapshotProvider` to publish / retract its resolver. */
+export function setBridgeResolver(resolver: RefResolver | null): void {
+  activeResolver = resolver;
+}
+
+/** Read the resolver currently published by the provider, if any. */
+export function getActiveResolver(): RefResolver | null {
+  return activeResolver;
+}
+
+/** Sends a message into the chat — same path as the composer's send. */
+export type BridgeSender = (content: string) => Promise<void> | void;
+
+let activeSender: BridgeSender | null = null;
+
+/** Called by `ChatProvider` to publish / retract its `sendMessage`. */
+export function setBridgeSender(sender: BridgeSender | null): void {
+  activeSender = sender;
+}
+
+/** Read the chat sender currently published by the provider, if any. */
+export function getActiveSender(): BridgeSender | null {
+  return activeSender;
+}

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

@@ -0,0 +1,76 @@
+'use client';
+
+/**
+ * `window.__chatBridge` — exposes the bridge registry in development so
+ * the commands can be driven manually without an AI / SSE round-trip.
+ *
+ * Run `__chatBridge.highlight(['@e4'])` in the console to see the
+ * spotlight directly. A dev affordance, not a public API surface — it
+ * is gated on `isDev` and is a no-op on the server and in production.
+ */
+
+import { isDev } from '@djangocfg/ui-core/lib';
+
+import { log } from './logger';
+import { registry } from './registry';
+import {
+  highlight,
+  focus,
+  clear,
+  inspect,
+  scrollTo,
+  fill,
+  click,
+  sendMessage,
+} from './commands';
+
+/** Shape exposed on `window.__chatBridge`. */
+export interface ChatBridge {
+  highlight: typeof highlight.run;
+  focus: typeof focus.run;
+  scrollTo: typeof scrollTo.run;
+  clear: typeof clear.run;
+  inspect: typeof inspect.run;
+  fill: typeof fill.run;
+  click: typeof click.run;
+  sendMessage: typeof sendMessage.run;
+  /** List every registered command with its description. */
+  help: () => void;
+}
+
+declare global {
+  interface Window {
+    __chatBridge?: ChatBridge;
+  }
+}
+
+/**
+ * Install `window.__chatBridge` for manual testing. No-op on the server
+ * and in production (gated on `isDev`) — the bridge is a dev affordance,
+ * not a public API surface.
+ */
+export function installChatBridge(): void {
+  if (typeof window === 'undefined' || !isDev) return;
+
+  window.__chatBridge = {
+    highlight: highlight.run,
+    focus: focus.run,
+    scrollTo: scrollTo.run,
+    clear: clear.run,
+    inspect: inspect.run,
+    fill: fill.run,
+    click: click.run,
+    sendMessage: sendMessage.run,
+    help: () => {
+      // eslint-disable-next-line no-console
+      console.table(
+        [...registry.values()].map((c) => ({
+          command: c.name,
+          mutates: c.mutates,
+          description: c.description,
+        })),
+      );
+    },
+  };
+  log.info('window.__chatBridge installed — run __chatBridge.help()');
+}

package/src/lib/page-snapshot/capture/walk.ts

@@ -17,6 +17,7 @@ import type {
   CSTRefId,
   CSTTextNode,
 } from '../cst/types';
+import { computeLocator, type RefLocator } from '../refs/locator';
 import { accessibleName } from './accessible-name';
 import {
   classify,
@@ -51,9 +52,14 @@ export const noopRedact: RedactValue = (value) => value;
 export interface WalkResult {
   /** Captured child nodes (the root node is assembled by the engine). */
   children: CSTNode[];
-  /** Map of assigned ref id → element — kept so directives can later
-   *  resolve a CST ref back to the live DOM node. */
-  refMap: Map<CSTRefId, HTMLElement>;
+  /**
+   * Map of assigned ref id → re-locatable descriptor. A descriptor —
+   * not a node pointer — because React recreates DOM nodes between
+   * capture and directive application; a frozen `HTMLElement` would be
+   * detached by then. The descriptor re-finds the element in the live
+   * DOM at resolve time.
+   */
+  refMap: Map<CSTRefId, RefLocator>;
   /** Number of elements visited. */
   nodesVisited: number;
 }
@@ -69,7 +75,7 @@ export interface WalkOptions {
 /** Mutable state threaded through one walk. */
 interface WalkState {
   redact: RedactValue;
-  refMap: Map<CSTRefId, HTMLElement>;
+  refMap: Map<CSTRefId, RefLocator>;
   refCounter: number;
   visited: number;
   maxNodes: number;
@@ -98,7 +104,9 @@ function controlValue(el: Element): string | undefined {
 function buildInteractive(el: HTMLElement, state: WalkState): CSTInteractiveNode {
   const role = interactiveRole(el)!;
   const ref = `@e${state.refCounter++}` as CSTRefId;
-  state.refMap.set(ref, el);
+  // Store a re-locatable descriptor, never the node itself — the node
+  // will be recreated by React before the directive arrives.
+  state.refMap.set(ref, computeLocator(el, role));
 
   const rawValue = controlValue(el);
   const value =

package/src/lib/page-snapshot/engine.ts

@@ -58,7 +58,12 @@ export interface CaptureTelemetry {
 export interface CaptureResult {
   payload: PageContextPayload;
   telemetry: CaptureTelemetry;
-  /** Per-snapshot ref → element map, for resolving `point` directives. */
+  /**
+   * Per-snapshot ref registry, for resolving `point` directives. Holds
+   * re-locatable descriptors (not node pointers) so a ref still
+   * resolves after React re-renders the page between capture and
+   * directive application.
+   */
   refs: RefRegistry;
 }
 
@@ -114,9 +119,9 @@ export class PageSnapshotEngine {
       const result = walkDOM(root, { redactValue });
       walked = walked.concat(result.children);
       nodesVisited += result.nodesVisited;
-      // Carry the walk's refs into the snapshot registry.
-      for (const [ref, el] of result.refMap) {
-        refs.set(ref as CSTRefId, el);
+      // Carry the walk's ref locators into the snapshot registry.
+      for (const [ref, locator] of result.refMap) {
+        refs.set(ref as CSTRefId, locator);
       }
     }
 

package/src/lib/page-snapshot/index.ts

@@ -63,6 +63,11 @@ export {
 
 // Refs.
 export { RefRegistry } from './refs/registry';
+export {
+  computeLocator,
+  resolveLocator,
+  type RefLocator,
+} from './refs/locator';
 
 // Utilities.
 export { estimateTokens } from './tokens';