@djangocfg/ui-tools 2.1.409 → 2.1.411

package/src/lib/page-snapshot/react/provider.tsx

@@ -11,6 +11,12 @@ import {
 
 import { useLocationProperty } from '@djangocfg/ui-core/hooks';
 
+import {
+  installChatBridge,
+  setBridgeResolver,
+} from '../../browser-bridge';
+import { useChatSettings } from '../../../tools/Chat/settings';
+
 import type { CaptureEngineOptions, CaptureResult } from '../engine';
 import { PageSnapshotEngine } from '../engine';
 import {
@@ -23,10 +29,17 @@ export interface PageSnapshotProviderProps {
   /** Engine configuration. */
   config?: CaptureEngineOptions;
   /**
-   * Start opted-in. Default false — the user must explicitly enable
-   * sharing page context.
+   * Opt-in value used when nothing is stored yet. Default false — the
+   * user must explicitly enable sharing page context. Once the user
+   * toggles it, the choice is persisted and this is ignored.
    */
   defaultLinked?: boolean;
+  /**
+   * localStorage key for the centralized chat-settings object that holds
+   * the opt-in (along with the rest of the chat's persisted settings).
+   * Override to scope the chat settings per app / per chat.
+   */
+  storageKey?: string;
   children: ReactNode;
 }
 
@@ -43,12 +56,42 @@ export interface PageSnapshotProviderProps {
 export function PageSnapshotProvider({
   config,
   defaultLinked = false,
+  storageKey,
   children,
 }: PageSnapshotProviderProps) {
-  const [isLinked, setIsLinked] = useState(defaultLinked);
+  // The opt-in choice persists across sessions — the user enables screen
+  // sharing once and it is remembered. It now lives in the centralized
+  // chat-settings object (`ChatSettings.pageContext.linked`) instead of a
+  // standalone key, so the chat owns all its persisted state in one place.
+  const settingsDefaults = useMemo(
+    () => ({ pageContext: { linked: defaultLinked } }),
+    [defaultLinked],
+  );
+  const { settings, setPageContextLinked } = useChatSettings({
+    storageKey,
+    defaults: settingsDefaults,
+  });
+  const isLinked = settings.pageContext.linked;
+  const setIsLinked = setPageContextLinked;
   const [isStale, setIsStale] = useState(false);
   const [lastSnapshot, setLastSnapshot] = useState<CaptureResult | null>(null);
 
+  // The snapshot that actually rode the most recent chat message.
+  //
+  // CST ref ids (`@eN`) are positional — assigned by DOM-order traversal
+  // at capture time — so they are NOT stable across captures: `@e22` of
+  // one snapshot need not be `@e22` of another. A `point` directive the
+  // assistant returns cites refs from the snapshot it was given. To
+  // resolve that directive correctly the overlay must use the registry
+  // of *that* snapshot, not a newer one.
+  //
+  // `lastSnapshot` tracks the live page and is overwritten by every
+  // route-change auto-capture, so it cannot be trusted for directive
+  // resolution. This state holds the sent snapshot and is only ever
+  // replaced on the next send — it survives route changes that happen
+  // while a reply (and its directives) is still streaming in.
+  const [sentSnapshot, setSentSnapshot] = useState<CaptureResult | null>(null);
+
   // Engine is browser-only. Construct it once, lazily, after mount —
   // a ref (not state) since it never needs to trigger a re-render.
   const engineRef = useRef<PageSnapshotEngine | null>(null);
@@ -112,6 +155,10 @@ export function PageSnapshotProvider({
     if (!isLinked) return undefined;
     const result = capture();
     if (!result) return undefined;
+    // This is the snapshot the assistant will see — pin it so any
+    // `point` directive in the reply resolves against the exact ref
+    // registry that produced the refs the assistant cited.
+    setSentSnapshot(result);
     return { pageContext: result.payload };
   }, [isLinked, capture]);
 
@@ -132,6 +179,24 @@ export function PageSnapshotProvider({
     // `pathname` in deps: a new route re-captures automatically.
   }, [isLinked, pathname, runCapture]);
 
+  // Install the dev-only `window.__chatBridge` once — manual testing of
+  // highlight / focus commands without an AI round-trip.
+  useEffect(() => {
+    installChatBridge();
+  }, []);
+
+  // Keep the bridge's ref resolver pointed at the latest snapshot, so
+  // console-driven `window.__chatBridge.highlight()` commands resolve
+  // refs against the current page. This is intentionally the *latest*
+  // snapshot, not `sentSnapshot`: manual testing highlights what is on
+  // screen now. AI-directive resolution is a separate path — it uses
+  // `sentSnapshot` (see `DirectiveOverlay`) so it stays pinned to the
+  // registry the assistant actually saw.
+  useEffect(() => {
+    setBridgeResolver(lastSnapshot?.refs ?? null);
+    return () => setBridgeResolver(null);
+  }, [lastSnapshot]);
+
   const value = useMemo<PageSnapshotContextValue>(
     () => ({
       isLinked,
@@ -140,6 +205,7 @@ export function PageSnapshotProvider({
       generatePreview,
       getChatMetadata,
       lastSnapshot,
+      sentSnapshot,
       isStale,
       refresh,
     }),
@@ -149,6 +215,7 @@ export function PageSnapshotProvider({
       generatePreview,
       getChatMetadata,
       lastSnapshot,
+      sentSnapshot,
       isStale,
       refresh,
     ],

package/src/lib/page-snapshot/react/use-page-snapshot.ts

@@ -40,6 +40,16 @@ export interface PageSnapshotContextValue {
   /** The most recent captured snapshot, if any. */
   lastSnapshot: CaptureResult | null;
 
+  /**
+   * The snapshot that rode the most recent chat message — the one the
+   * assistant was given. CST ref ids are positional, so a `point`
+   * directive in the reply must be resolved against *this* snapshot's
+   * ref registry, never `lastSnapshot` (which the route-change
+   * auto-capture overwrites) and never a fresh capture (which re-numbers
+   * refs). Null until the first message is sent.
+   */
+  sentSnapshot: CaptureResult | null;
+
   /** Whether the captured context is stale vs the current page. */
   isStale: boolean;
 

package/src/lib/page-snapshot/refs/__tests__/locator.test.ts

@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { computeLocator, resolveLocator } from '../locator';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('computeLocator', () => {
+  it('builds an id selector when the element has a unique id', () => {
+    const el = document.createElement('button');
+    el.id = 'submit-btn';
+    el.textContent = 'Submit';
+    document.body.appendChild(el);
+
+    const locator = computeLocator(el, 'button');
+    expect(locator.selector).toBe('#submit-btn');
+    expect(locator.role).toBe('button');
+    expect(locator.name).toBe('Submit');
+    expect(locator.tag).toBe('button');
+  });
+
+  it('prefers data-testid over a structural path', () => {
+    const el = document.createElement('a');
+    el.setAttribute('data-testid', 'nav-home');
+    el.textContent = 'Home';
+    document.body.appendChild(el);
+
+    expect(computeLocator(el, 'link').selector).toBe('a[data-testid="nav-home"]');
+  });
+
+  it('falls back to a structural path when no stable attribute exists', () => {
+    document.body.innerHTML = '<section><div></div><a>One</a><a>Two</a></section>';
+    const second = document.body.querySelectorAll('a')[1] as HTMLElement;
+
+    const locator = computeLocator(second, 'link');
+    expect(locator.selector).toContain('nth-of-type');
+    // The structural path must re-find the same element.
+    expect(document.querySelector(locator.selector)).toBe(second);
+  });
+});
+
+describe('resolveLocator', () => {
+  it('resolves via selector when structure is intact', () => {
+    const el = document.createElement('button');
+    el.id = 'go';
+    el.textContent = 'Go';
+    document.body.appendChild(el);
+
+    const locator = computeLocator(el, 'button');
+    expect(resolveLocator(locator)).toBe(el);
+  });
+
+  it('resolves by role + name when the selector breaks', () => {
+    // Capture with a structural path (no stable attribute).
+    document.body.innerHTML = '<div><a>Browse Catalog</a></div>';
+    const original = document.body.querySelector('a') as HTMLElement;
+    const locator = computeLocator(original, 'link');
+
+    // Re-render shifts the element: extra wrapper + sibling inserted, so
+    // the captured nth-of-type path no longer matches it.
+    document.body.innerHTML =
+      '<header><nav><span>x</span><a>Browse Catalog</a></nav></header>';
+
+    const resolved = resolveLocator(locator);
+    expect(resolved).not.toBeNull();
+    expect(resolved?.textContent).toBe('Browse Catalog');
+  });
+
+  it('returns null when the element is genuinely gone', () => {
+    const el = document.createElement('a');
+    el.textContent = 'Vanishing Link';
+    document.body.appendChild(el);
+    const locator = computeLocator(el, 'link');
+
+    document.body.innerHTML = '';
+    expect(resolveLocator(locator)).toBeNull();
+  });
+
+  it('matches an ARIA-roled element by role + name', () => {
+    document.body.innerHTML =
+      '<div role="button" aria-label="Open menu">≡</div>';
+    const original = document.body.firstElementChild as HTMLElement;
+    const locator = computeLocator(original, 'button');
+
+    // Recreate the node — same role + accessible name, new identity.
+    document.body.innerHTML =
+      '<span></span><div role="button" aria-label="Open menu">≡</div>';
+    const fresh = document.body.querySelectorAll('[role="button"]')[0];
+
+    expect(resolveLocator(locator)).toBe(fresh);
+  });
+});

package/src/lib/page-snapshot/refs/__tests__/registry.test.ts

@@ -1,8 +1,13 @@
 // @vitest-environment jsdom
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 
+import { computeLocator } from '../locator';
 import { RefRegistry } from '../registry';
 
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
 describe('RefRegistry', () => {
   it('reports unknown refs as unresolved', () => {
     const reg = new RefRegistry('snap-1');
@@ -13,12 +18,63 @@ describe('RefRegistry', () => {
   });
 
   it('resolves a registered ref to its element', () => {
-    const reg = new RefRegistry('snap-1');
     const el = document.createElement('button');
-    reg.set('@e1', el);
+    el.textContent = 'Save';
+    document.body.appendChild(el);
+
+    const reg = new RefRegistry('snap-1');
+    reg.set('@e1', computeLocator(el, 'button'));
 
     expect(reg.has('@e1')).toBe(true);
     expect(reg.resolve('@e1')).toBe(el);
     expect(reg.size).toBe(1);
   });
+
+  it('resolves after the original node is replaced by a re-render', () => {
+    // Capture against the original node.
+    const original = document.createElement('a');
+    original.id = 'browse';
+    original.textContent = 'Browse Catalog';
+    document.body.appendChild(original);
+
+    const reg = new RefRegistry('snap-1');
+    reg.set('@e1', computeLocator(original, 'link'));
+
+    // React re-render: the node is recreated as a fresh, equivalent one.
+    original.remove();
+    const fresh = document.createElement('a');
+    fresh.id = 'browse';
+    fresh.textContent = 'Browse Catalog';
+    document.body.appendChild(fresh);
+
+    const resolved = reg.resolve('@e1');
+    expect(resolved).toBe(fresh);
+    expect(resolved).not.toBe(original);
+  });
+
+  it('returns null when the element is genuinely gone', () => {
+    const el = document.createElement('button');
+    el.textContent = 'Delete';
+    document.body.appendChild(el);
+
+    const reg = new RefRegistry('snap-1');
+    reg.set('@e1', computeLocator(el, 'button'));
+
+    el.remove();
+    expect(reg.resolve('@e1')).toBeNull();
+  });
+
+  it('exposes the stored locator for diagnostics', () => {
+    const el = document.createElement('a');
+    el.textContent = 'Home';
+    document.body.appendChild(el);
+
+    const reg = new RefRegistry('snap-1');
+    reg.set('@e1', computeLocator(el, 'link'));
+
+    const locator = reg.getLocator('@e1');
+    expect(locator?.role).toBe('link');
+    expect(locator?.name).toBe('Home');
+    expect(reg.getLocator('@e9')).toBeUndefined();
+  });
 });

package/src/lib/page-snapshot/refs/locator.ts

@@ -0,0 +1,218 @@
+/**
+ * Re-locatable ref descriptors.
+ *
+ * A snapshot is captured when a chat message is sent; the AI's
+ * `point` directive arrives seconds later. In between, React re-renders
+ * the page — the chat panel expands, content streams in, lists update —
+ * and React recreates DOM nodes. Any `HTMLElement` reference frozen at
+ * capture time is then detached (`isConnected === false`) and useless.
+ *
+ * So a ref must NOT be stored as a node pointer. It is stored as a
+ * `RefLocator`: a description rich enough to FIND the element again in
+ * whatever DOM exists at resolve time. `resolveLocator` runs a live
+ * query against the current `document` — it never dereferences a stale
+ * pointer.
+ */
+
+import { accessibleName } from '../capture/accessible-name';
+import { tagName } from '../capture/dom-utils';
+import type { CSTInteractiveRole } from '../cst/types';
+
+/**
+ * A description that can re-find an interactive element in the live DOM.
+ *
+ * `role` + `name` is the primary locator: the AI cited an element by the
+ * accessible name the CST gave it, so "the visible `link` named 'Browse
+ * Catalog'" survives node-identity changes and even position shifts.
+ * `selector` is a structural tiebreaker used to disambiguate when
+ * several elements share the same role + name.
+ */
+export interface RefLocator {
+  /** Interactive role, as classified by the CST walk. */
+  role: CSTInteractiveRole;
+  /** Accessible name — the label the AI was shown for this element. */
+  name: string;
+  /** lowercased tag name, used to filter candidates. */
+  tag: string;
+  /**
+   * A CSS selector that re-finds the element. Built from a stable
+   * attribute (`id` / `data-testid` / `name`) when one exists, else a
+   * structural `nth-of-type` path from the nearest id'd ancestor or
+   * `<body>`. A tiebreaker, not the source of truth — React can
+   * recreate nodes and shift positions, breaking the path.
+   */
+  selector: string;
+}
+
+/** Attributes that, when present, give a stable unique-ish selector. */
+const STABLE_ATTRS = ['data-testid', 'id', 'name'] as const;
+
+/** True when a selector matches exactly one element in `document`. */
+function isUnique(selector: string): boolean {
+  try {
+    return document.querySelectorAll(selector).length === 1;
+  } catch {
+    return false;
+  }
+}
+
+/** Escape a value for use inside a CSS attribute selector. */
+function cssEscape(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(value);
+  }
+  return value.replace(/[^a-zA-Z0-9_-]/g, (ch) => `\\${ch}`);
+}
+
+/**
+ * Build a structural `nth-of-type` path from the nearest id'd ancestor
+ * (or `<body>`) down to `el`. Survives re-renders that recreate nodes
+ * but keep the same tag structure and ordering — the common React case.
+ */
+function structuralPath(el: HTMLElement): string {
+  const parts: string[] = [];
+  let node: Element | null = el;
+  while (node && node !== document.body && node !== document.documentElement) {
+    const id = node.getAttribute('id');
+    if (id) {
+      parts.unshift(`#${cssEscape(id)}`);
+      return parts.join(' > ');
+    }
+    const tag = tagName(node);
+    const parent: Element | null = node.parentElement;
+    if (!parent) {
+      parts.unshift(tag);
+      break;
+    }
+    let index = 1;
+    for (const sib of Array.from(parent.children)) {
+      if (sib === node) break;
+      if (tagName(sib) === tag) index += 1;
+    }
+    parts.unshift(`${tag}:nth-of-type(${index})`);
+    node = parent;
+  }
+  return parts.length ? `body > ${parts.join(' > ')}` : 'body';
+}
+
+/**
+ * Compute a re-locatable descriptor for an interactive element at
+ * capture time. `role` is already known from classification; `name` is
+ * derived with the same accessible-name logic the CST walk uses, so the
+ * locator's name matches exactly what the AI was shown.
+ */
+export function computeLocator(
+  el: HTMLElement,
+  role: CSTInteractiveRole,
+): RefLocator {
+  let selector = '';
+  for (const attr of STABLE_ATTRS) {
+    const raw = el.getAttribute(attr);
+    if (!raw) continue;
+    const candidate =
+      attr === 'id'
+        ? `#${cssEscape(raw)}`
+        : `${tagName(el)}[${attr}="${cssEscape(raw)}"]`;
+    if (isUnique(candidate)) {
+      selector = candidate;
+      break;
+    }
+  }
+  if (!selector) selector = structuralPath(el);
+
+  return {
+    role,
+    name: accessibleName(el),
+    tag: tagName(el),
+    selector,
+  };
+}
+
+/** True when an element is rendered (has layout) — prefers visible hits. */
+function isRendered(el: HTMLElement): boolean {
+  if (!el.isConnected) return false;
+  // offsetParent is null for display:none; width/height covers fixed
+  // and body-level elements that legitimately have no offsetParent.
+  return (
+    el.offsetParent !== null ||
+    el.getClientRects().length > 0
+  );
+}
+
+/**
+ * Find a connected element matching a locator against the live DOM.
+ *
+ * Resolution order:
+ *  1. the structural / attribute selector — if it yields exactly one
+ *     connected element, trust it;
+ *  2. the role + accessible name — scan candidate tags, match the live
+ *     accessible name, prefer a rendered element. This is the resilient
+ *     path: it does not depend on node identity or position.
+ *  3. give up — the element is genuinely gone (stale ref).
+ */
+export function resolveLocator(locator: RefLocator): HTMLElement | null {
+  // 1. Selector — a precise hit when structure held.
+  try {
+    const hits = document.querySelectorAll<HTMLElement>(locator.selector);
+    if (hits.length === 1 && hits[0].isConnected) return hits[0];
+  } catch {
+    // Malformed selector — fall through to the role+name match.
+  }
+
+  // 2. Role + accessible name — robust to node recreation.
+  const candidates = collectByRoleName(locator);
+  if (candidates.length === 0) return null;
+  return candidates.find(isRendered) ?? candidates[0];
+}
+
+/** Tags worth scanning for a given role when matching by role + name. */
+function tagsForRole(role: CSTInteractiveRole): string[] {
+  switch (role) {
+    case 'link':
+      return ['a'];
+    case 'button':
+      return ['button', 'a', 'input'];
+    case 'textbox':
+    case 'searchbox':
+      return ['input', 'textarea'];
+    case 'checkbox':
+    case 'radio':
+    case 'slider':
+    case 'spinbutton':
+      return ['input'];
+    case 'select':
+    case 'combobox':
+      return ['select'];
+    case 'textarea':
+      return ['textarea'];
+    default:
+      return ['button', 'a', 'input'];
+  }
+}
+
+/**
+ * Collect connected elements whose role + accessible name match the
+ * locator. Also scans `[role=...]` so ARIA-roled elements are found.
+ */
+function collectByRoleName(locator: RefLocator): HTMLElement[] {
+  const seen = new Set<HTMLElement>();
+  const selectors = [
+    ...tagsForRole(locator.role),
+    `[role="${locator.role}"]`,
+  ];
+  const out: HTMLElement[] = [];
+  for (const sel of selectors) {
+    let nodes: NodeListOf<HTMLElement>;
+    try {
+      nodes = document.querySelectorAll<HTMLElement>(sel);
+    } catch {
+      continue;
+    }
+    for (const node of Array.from(nodes)) {
+      if (seen.has(node) || !node.isConnected) continue;
+      seen.add(node);
+      if (accessibleName(node) === locator.name) out.push(node);
+    }
+  }
+  return out;
+}

package/src/lib/page-snapshot/refs/registry.ts

@@ -1,37 +1,52 @@
 /**
- * Ref registry — maps CST ref ids (`@e4`) back to DOM elements.
+ * Ref registry — maps CST ref ids (`@e4`) to a way of re-finding the
+ * element in the live DOM.
  *
- * Built during the DOM walk; kept after serialization so AI-driven
- * highlight/focus directives can resolve a ref to a live element.
- * Elements are held weakly so a removed node can be garbage-collected —
- * an unresolvable ref is the "stale" case.
+ * The registry deliberately does NOT hold `HTMLElement` references.
+ * Between snapshot capture (chat-message send) and directive
+ * application (the `directive` SSE event, seconds later), React
+ * re-renders the page and recreates DOM nodes — any frozen node pointer
+ * is detached by then and resolves to nothing. Instead each ref stores
+ * a `RefLocator` and `resolve()` runs a live-DOM query at call time.
  */
 
 import type { CSTRefId } from '../cst/types';
+import { resolveLocator, type RefLocator } from './locator';
 
 /**
- * A per-snapshot ref → element map. Elements are held weakly so a
- * removed node can be garbage-collected — an unresolvable ref is the
- * "stale" case.
+ * A per-snapshot `ref → RefLocator` map. Locators are inert data, so
+ * the registry stays valid across re-renders — `resolve()` re-queries
+ * the current DOM every call rather than dereferencing a stale node.
  */
 export class RefRegistry {
   /** Unique id of the snapshot these refs belong to. */
   readonly snapshotId: string;
 
-  private readonly map = new Map<CSTRefId, WeakRef<HTMLElement>>();
+  private readonly map = new Map<CSTRefId, RefLocator>();
 
   constructor(snapshotId: string) {
     this.snapshotId = snapshotId;
   }
 
-  /** Register a ref → element pair (called during the walk). */
-  set(ref: CSTRefId, element: HTMLElement): void {
-    this.map.set(ref, new WeakRef(element));
+  /** Register a ref → locator pair (called during the walk). */
+  set(ref: CSTRefId, locator: RefLocator): void {
+    this.map.set(ref, locator);
   }
 
-  /** Resolve a ref to its element, or null if gone / unknown (stale). */
+  /**
+   * Resolve a ref to a live element, or null if it cannot be found in
+   * the current DOM (stale). Runs a fresh query every call — safe to
+   * call long after capture, across any number of re-renders.
+   */
   resolve(ref: CSTRefId): HTMLElement | null {
-    return this.map.get(ref)?.deref() ?? null;
+    const locator = this.map.get(ref);
+    if (!locator) return null;
+    return resolveLocator(locator);
+  }
+
+  /** The stored locator for a ref, if known (mainly for diagnostics). */
+  getLocator(ref: CSTRefId): RefLocator | undefined {
+    return this.map.get(ref);
   }
 
   /** Whether a ref is known to this snapshot (regardless of liveness). */

package/src/tools/Chat/README.md

@@ -57,7 +57,7 @@ export function MyChat() {
 - **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).
+- **AI bridge directives.** `bridge/` — when the assistant returns `point` directives, `<HighlightOverlay>` resolves each CST ref to a live element and draws an SVG-mask spotlight (optionally moves focus). The bridge also exposes a command registry the AI drives the page through. Read-only by default: it points at the UI, never changes data. See [`bridge/README.md`](./bridge/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.

package/src/tools/Chat/constants.ts

@@ -12,7 +12,30 @@ export const CSS_VARS = {
   reserve: '--djc-chat-reserve',
 } as const;
 
-export const DEFAULT_Z_INDEX = 9000;
+/**
+ * Z-index tier for the floating chat surface.
+ *
+ * The chat dock is page furniture — a peer of page content, not a modal.
+ * It must sit ABOVE the page yet BELOW every `@djangocfg/ui-core` overlay
+ * (sheet 200, drawer 500, dialog 600, anchored overlays 700) so that any
+ * dialog — including one launched from inside the chat — always wins.
+ *
+ *   dock        100   the chat surface
+ *   companion    99   FAB / greeting / unread preview (behind the open dock)
+ *   tooltip     101   chat-header tooltips (just above the dock, still
+ *                     below ui-core's modal/overlay tiers)
+ */
+export const Z_INDEX = {
+  /** The chat dock surface. */
+  dock: 100,
+  /** FAB, greeting bubble and unread preview — sit just below the dock. */
+  companion: 99,
+  /** Tooltips portaled out of the chat header — just above the dock. */
+  tooltip: 101,
+} as const;
+
+/** @deprecated Use {@link Z_INDEX.dock}. Kept for the public API surface. */
+export const DEFAULT_Z_INDEX = Z_INDEX.dock;
 
 export const LIMITS = {
   /** Max characters per single message. */