@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/Chat/core/transport/http.ts

@@ -61,12 +61,28 @@ function mapStatusToCode(status: number): string {
   return 'http_error';
 }
 
-function withTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+/**
+ * Derive an AbortSignal that fires after `timeoutMs` or when the caller's
+ * `signal` aborts. The returned `clear()` MUST be called once the request
+ * settles — otherwise the timer keeps the AbortController (and its abort
+ * listener on the parent signal) alive until the full timeout elapses,
+ * leaking one timer + one listener per request.
+ */
+function withTimeout(
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+): { signal: AbortSignal; clear: () => void } {
   const ctrl = new AbortController();
   const onAbort = () => ctrl.abort();
   signal?.addEventListener('abort', onAbort, { once: true });
-  setTimeout(() => ctrl.abort(), timeoutMs);
-  return ctrl.signal;
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  return {
+    signal: ctrl.signal,
+    clear: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    },
+  };
 }
 
 export function createHttpTransport(config: HttpTransportConfig): ChatTransport {
@@ -85,13 +101,18 @@ export function createHttpTransport(config: HttpTransportConfig): ChatTransport
 
   return {
     async createSession(opts?: CreateSessionOptions): Promise<SessionInfo> {
-      const res = await fetchImpl(`${base}/sessions`, {
-        method: 'POST',
-        headers: await buildHeaders(),
-        body: JSON.stringify({ slug: config.slug, metadata: opts?.metadata ?? {} }),
-        signal: withTimeout(undefined, timeout),
-      });
-      return jsonOrThrow<SessionInfo>(res, 'createSession');
+      const t = withTimeout(undefined, timeout);
+      try {
+        const res = await fetchImpl(`${base}/sessions`, {
+          method: 'POST',
+          headers: await buildHeaders(),
+          body: JSON.stringify({ slug: config.slug, metadata: opts?.metadata ?? {} }),
+          signal: t.signal,
+        });
+        return await jsonOrThrow<SessionInfo>(res, 'createSession');
+      } finally {
+        t.clear();
+      }
     },
 
     async loadHistory(sessionId, cursor, limit): Promise<HistoryPage> {
@@ -101,12 +122,17 @@ export function createHttpTransport(config: HttpTransportConfig): ChatTransport
       const url = `${base}/sessions/${encodeURIComponent(sessionId)}/history${
         params.toString() ? `?${params.toString()}` : ''
       }`;
-      const res = await fetchImpl(url, {
-        method: 'GET',
-        headers: await buildHeaders(),
-        signal: withTimeout(undefined, timeout),
-      });
-      return jsonOrThrow<HistoryPage>(res, 'loadHistory');
+      const t = withTimeout(undefined, timeout);
+      try {
+        const res = await fetchImpl(url, {
+          method: 'GET',
+          headers: await buildHeaders(),
+          signal: t.signal,
+        });
+        return await jsonOrThrow<HistoryPage>(res, 'loadHistory');
+      } finally {
+        t.clear();
+      }
     },
 
     async *stream(
@@ -139,26 +165,39 @@ export function createHttpTransport(config: HttpTransportConfig): ChatTransport
 
     async send(sessionId, content, options?: SendOptions): Promise<ChatMessage> {
       const url = `${base}/sessions/${encodeURIComponent(sessionId)}/messages/buffered`;
-      const res = await fetchImpl(url, {
-        method: 'POST',
-        headers: await buildHeaders(),
-        body: JSON.stringify({
-          content,
-          attachments: options?.attachments ?? [],
-          metadata: options?.metadata ?? {},
-        }),
-        signal: options?.signal ?? withTimeout(undefined, timeout),
-      });
-      return jsonOrThrow<ChatMessage>(res, 'send');
+      // Honour a caller-supplied signal as-is; otherwise apply our own
+      // timeout (and clean it up in `finally`).
+      const t = options?.signal ? null : withTimeout(undefined, timeout);
+      try {
+        const res = await fetchImpl(url, {
+          method: 'POST',
+          headers: await buildHeaders(),
+          body: JSON.stringify({
+            content,
+            attachments: options?.attachments ?? [],
+            metadata: options?.metadata ?? {},
+          }),
+          signal: options?.signal ?? t!.signal,
+        });
+        return await jsonOrThrow<ChatMessage>(res, 'send');
+      } finally {
+        t?.clear();
+      }
     },
 
     async closeSession(sessionId: string): Promise<void> {
       const url = `${base}/sessions/${encodeURIComponent(sessionId)}`;
-      const res = await fetchImpl(url, {
-        method: 'DELETE',
-        headers: await buildHeaders(),
-        signal: withTimeout(undefined, timeout),
-      });
+      const t = withTimeout(undefined, timeout);
+      let res: Response;
+      try {
+        res = await fetchImpl(url, {
+          method: 'DELETE',
+          headers: await buildHeaders(),
+          signal: t.signal,
+        });
+      } finally {
+        t.clear();
+      }
       if (!res.ok && res.status !== 404) {
         throw new TransportError(`closeSession failed (${res.status})`, mapStatusToCode(res.status));
       }

package/src/tools/Chat/core/transport/sse.ts

@@ -7,7 +7,7 @@
  */
 
 import type { ChatStreamEvent } from '../../types';
-import { LIMITS } from '../../config';
+import { LIMITS } from '../../constants';
 
 interface RawEvent {
   event?: string;
@@ -49,12 +49,23 @@ export async function* parseSSE(
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let buffer = '';
-  let lastChunkAt = Date.now();
 
-  const idleCheck = () => {
-    if (Date.now() - lastChunkAt > idleMs) {
-      throw new Error(`SSE idle timeout (${idleMs}ms)`);
-    }
+  // Race `reader.read()` against an idle timer so a fully stalled
+  // connection — one that accepts the request but never sends a byte —
+  // is surfaced as an error instead of hanging the generator forever.
+  // The previous check only ran *after* a successful read, so it could
+  // never fire while `reader.read()` itself was blocked.
+  const readWithIdleTimeout = (): Promise<ReadableStreamReadResult<Uint8Array>> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const idle = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`SSE idle timeout (${idleMs}ms)`)),
+        idleMs,
+      );
+    });
+    return Promise.race([reader.read(), idle]).finally(() => {
+      if (timer) clearTimeout(timer);
+    }) as Promise<ReadableStreamReadResult<Uint8Array>>;
   };
 
   try {
@@ -62,10 +73,9 @@ export async function* parseSSE(
       if (options.signal?.aborted) {
         return;
       }
-      const { value, done } = await reader.read();
+      const { value, done } = await readWithIdleTimeout();
       if (done) break;
 
-      lastChunkAt = Date.now();
       buffer += decoder.decode(value, { stream: true });
 
       // Split on blank line which delimits SSE events.
@@ -86,8 +96,6 @@ export async function* parseSSE(
 
         separator = buffer.indexOf('\n\n');
       }
-
-      idleCheck();
     }
 
     // Flush any trailing partial event.

package/src/tools/Chat/highlight/HighlightOverlay.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+import { useEffect } from 'react';
+import { createPortal } from 'react-dom';
+
+import { SpotlightCanvas } from './SpotlightCanvas';
+import type { PointDirective, SpotlightRect } from './types';
+import { useHighlightTargets } from './useHighlightTargets';
+import { type RefResolver } from './resolveRef';
+
+/** Padding (px) drawn around each highlighted element. */
+const HIGHLIGHT_PADDING = 6;
+/** Corner radius (px) of the spotlight cut-out. */
+const HIGHLIGHT_RADIUS = 6;
+
+/** Props for `HighlightOverlay`. */
+export interface HighlightOverlayProps {
+  /** `point` directives from the AI's reply. Empty hides the overlay. */
+  directives: PointDirective[];
+  /** Resolves a CST ref to a live element (the snapshot's registry). */
+  resolver: RefResolver | null;
+  /** Auto-dismiss after N ms; 0 keeps it until directives clear. */
+  ttlMs?: number;
+  /** Called when the overlay dismisses (scrim click, Esc, or TTL). */
+  onDismiss?: () => void;
+}
+
+/**
+ * Draws an AI-driven spotlight over elements the assistant pointed at.
+ *
+ * Read-only: it highlights and optionally focuses elements — it never
+ * changes the user's data. The page stays interactive underneath; the
+ * scrim is purely visual and dismissable.
+ */
+export function HighlightOverlay({
+  directives,
+  resolver,
+  ttlMs = 6000,
+  onDismiss,
+}: HighlightOverlayProps) {
+  const targets = useHighlightTargets(directives, resolver);
+
+  // Auto-dismiss after the TTL once something is showing.
+  useEffect(() => {
+    if (targets.length === 0 || ttlMs <= 0) return;
+    const timer = window.setTimeout(() => onDismiss?.(), ttlMs);
+    return () => window.clearTimeout(timer);
+  }, [targets.length, ttlMs, onDismiss]);
+
+  // Dismiss on Escape.
+  useEffect(() => {
+    if (targets.length === 0) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onDismiss?.();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [targets.length, onDismiss]);
+
+  if (targets.length === 0 || typeof document === 'undefined') return null;
+
+  const rects: SpotlightRect[] = targets.map((t) => ({
+    rect: t.rect,
+    padding: HIGHLIGHT_PADDING,
+    radius: HIGHLIGHT_RADIUS,
+  }));
+
+  return createPortal(
+    <div
+      className="pointer-events-none fixed inset-0 z-[60]"
+      data-chat-highlight-overlay=""
+    >
+      {/* The scrim is click-dismissable; it does not block the page. */}
+      <div className="pointer-events-auto absolute inset-0">
+        <SpotlightCanvas
+          rects={rects}
+          pulseRing
+          onClick={() => onDismiss?.()}
+        />
+      </div>
+
+      {/* Captions beside each highlighted element. */}
+      {targets.map((t, i) =>
+        t.label ? (
+          <div
+            key={i}
+            className="bg-primary text-primary-foreground absolute rounded-md px-2 py-1 text-xs shadow-md"
+            style={{
+              left: t.rect.x,
+              top: t.rect.y + t.rect.height + HIGHLIGHT_PADDING + 6,
+              maxWidth: 240,
+            }}
+          >
+            {t.label}
+          </div>
+        ) : null,
+      )}
+    </div>,
+    document.body,
+  );
+}

package/src/tools/Chat/highlight/README.md

@@ -0,0 +1,103 @@
+# Chat highlight — AI-driven `point` directives
+
+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.
+
+---
+
+## The idea
+
+The chat sends the backend a snapshot of the user's page (the
+`page-snapshot` engine). Every interactive element in that snapshot got
+a short ref id — `@e4`. The assistant, knowing those refs, can reply:
+
+> "Click **Save** to apply your changes."
+
+…and attach a directive: `point at @e4`. This module resolves `@e4`
+back to the live DOM element and draws a spotlight on it.
+
+This is the intelligent successor to the old scripted product Tour —
+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.
+
+---
+
+## The round trip
+
+```
+ capture: page-snapshot engine assigns @e1, @e2, … to interactive nodes
+          and keeps a ref → element registry
+   │
+   ▼  snapshot sent with the chat message (request body metadata)
+ backend: the LLM, given the snapshot, may append a directive marker:
+          <<directives>[{"type":"point","ref":"@e4","focus":true}]</directives>>
+          the marker is parsed + validated, stripped from the reply,
+          and emitted as a `directive` SSE event
+   │
+   ▼  directive SSE event arrives on the client
+ this module: resolve @e4 → element via the snapshot registry,
+              draw the spotlight, optionally focus
+```
+
+---
+
+## Files
+
+| 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. |
+
+---
+
+## Usage
+
+```tsx
+import { HighlightOverlay } from '@djangocfg/ui-tools/.../Chat/highlight';
+
+<HighlightOverlay
+  directives={directivesFromLastDirectiveEvent}
+  resolver={snapshotRefRegistry}   // the page-snapshot ref registry
+  ttlMs={6000}
+  onDismiss={() => clearDirectives()}
+/>
+```
+
+- `directives` — the `directives` array from the latest `directive` SSE
+  event. Empty → the overlay renders nothing.
+- `resolver` — anything with `resolve(ref) => HTMLElement | null`. The
+  `page-snapshot` engine's `RefRegistry` satisfies this. Structurally
+  typed on purpose, so this module does not import the capture engine.
+
+---
+
+## Staleness
+
+A ref resolves against the snapshot that produced it. If the user has
+since navigated or the element was removed, `resolve()` returns null (or
+the element is detached) — that target is silently dropped. The overlay
+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.
+- It does not import the `page-snapshot` capture engine. It depends only
+  on the structural `RefResolver` interface, so the two stay
+  independent.
+- The directive type is `point` only. The shape is a discriminated
+  union on `type`, so a future write-style directive could be added —
+  but that is a different risk class (it would change user data) and is
+  deliberately out of scope here.

package/src/tools/Chat/highlight/SpotlightCanvas.tsx

@@ -0,0 +1,153 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { SpotlightRect } from './types';
+
+/**
+ * SVG-mask spotlight renderer — adapted from the former Tour component.
+ *
+ * Draws a dimmed full-screen overlay with rounded cut-outs over the
+ * target rects, plus a brand-coloured border and an attention pulse.
+ * Pure presentation: it takes geometry, not DOM elements.
+ */
+
+// Injected once — keyframes + transition classes for the SVG rects.
+const SPOTLIGHT_STYLES = `
+  @keyframes chat-spotlight-pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+  }
+  @keyframes chat-spotlight-ring {
+    0% { transform: scale(1); opacity: 0.8; }
+    100% { transform: scale(1.15); opacity: 0; }
+  }
+  .chat-spotlight-rect {
+    transition: x 300ms ease-out, y 300ms ease-out,
+                width 300ms ease-out, height 300ms ease-out;
+  }
+`;
+
+/** Props for the spotlight canvas. */
+export interface SpotlightCanvasProps {
+  /** Geometry of every element to spotlight. */
+  rects: SpotlightRect[];
+  /** Dim-overlay opacity, 0–1 (default: 0.5). */
+  opacity?: number;
+  /** Show an expanding attention ring (default: true). */
+  pulseRing?: boolean;
+  /** Dismiss the overlay when the scrim is clicked. */
+  onClick?: () => void;
+  className?: string;
+}
+
+export function SpotlightCanvas({
+  rects,
+  opacity = 0.5,
+  pulseRing = true,
+  onClick,
+  className,
+}: SpotlightCanvasProps) {
+  // Expand each rect by its padding and pre-compute the rounded box.
+  // Hooks run unconditionally — no early return before this.
+  const boxes = useMemo(
+    () =>
+      rects.map((target, index) => {
+        const x = target.rect.x - target.padding;
+        const y = target.rect.y - target.padding;
+        const width = target.rect.width + target.padding * 2;
+        const height = target.rect.height + target.padding * 2;
+        const rx = target.radius + 2;
+        const centerX = target.rect.x + target.rect.width / 2;
+        const centerY = target.rect.y + target.rect.height / 2;
+        return {
+          key: index,
+          x,
+          y,
+          width,
+          height,
+          rx,
+          transformOrigin: `${centerX}px ${centerY}px`,
+        };
+      }),
+    [rects],
+  );
+
+  if (rects.length === 0) return null;
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: SPOTLIGHT_STYLES }} />
+      <svg
+        className={cn('fixed inset-0 h-full w-full', className)}
+        aria-hidden="true"
+        onClick={onClick}
+      >
+        <defs>
+          <mask id="chat-spotlight-mask">
+            {/* White = visible dim; black cut-outs = transparent targets. */}
+            <rect fill="white" width="100%" height="100%" />
+            {boxes.map((b) => (
+              <rect
+                key={b.key}
+                fill="black"
+                className="chat-spotlight-rect"
+                x={b.x}
+                y={b.y}
+                width={b.width}
+                height={b.height}
+                rx={b.rx}
+                ry={b.rx}
+              />
+            ))}
+          </mask>
+        </defs>
+
+        {/* Dimmed scrim with the target cut-outs. */}
+        <rect
+          fill="black"
+          fillOpacity={opacity}
+          width="100%"
+          height="100%"
+          mask="url(#chat-spotlight-mask)"
+          className="transition-opacity duration-300"
+        />
+
+        {/* Attention pulse. */}
+        {pulseRing &&
+          boxes.map((b) => (
+            <rect
+              key={`pulse-${b.key}`}
+              className="fill-none stroke-primary stroke-2"
+              style={{
+                transformOrigin: b.transformOrigin,
+                animation: 'chat-spotlight-ring 1.5s ease-out infinite',
+              }}
+              x={b.x}
+              y={b.y}
+              width={b.width}
+              height={b.height}
+              rx={b.rx}
+              ry={b.rx}
+            />
+          ))}
+
+        {/* Solid border around each target. */}
+        {boxes.map((b) => (
+          <rect
+            key={`border-${b.key}`}
+            className="chat-spotlight-rect fill-none stroke-primary stroke-2"
+            x={b.x}
+            y={b.y}
+            width={b.width}
+            height={b.height}
+            rx={b.rx}
+            ry={b.rx}
+          />
+        ))}
+      </svg>
+    </>
+  );
+}

package/src/tools/Chat/highlight/__tests__/HighlightOverlay.test.tsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { HighlightOverlay } from '../HighlightOverlay';
+import type { RefResolver } from '../resolveRef';
+import type { CSTRefId, PointDirective } from '../types';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+// jsdom has no ResizeObserver — the overlay observes its targets, so
+// provide a no-op stub for the test environment.
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  (globalThis as Record<string, unknown>).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  };
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  document.body.innerHTML = '';
+});
+
+/** Resolver over a fixed map. */
+function makeResolver(map: Record<string, HTMLElement | null>): RefResolver {
+  return { resolve: (ref: CSTRefId) => map[ref] ?? null };
+}
+
+async function render(
+  directives: PointDirective[],
+  resolver: RefResolver | null,
+) {
+  await act(async () => {
+    root.render(
+      createElement(HighlightOverlay, { directives, resolver, ttlMs: 0 }),
+    );
+  });
+}
+
+describe('HighlightOverlay', () => {
+  it('renders nothing with no directives', async () => {
+    await render([], null);
+    expect(document.querySelector('[data-chat-highlight-overlay]')).toBeNull();
+  });
+
+  it('renders nothing when refs do not resolve', async () => {
+    await render([{ type: 'point', ref: '@e9' }], makeResolver({}));
+    expect(document.querySelector('[data-chat-highlight-overlay]')).toBeNull();
+  });
+
+  it('draws the overlay for a resolved ref', async () => {
+    const el = document.createElement('button');
+    el.textContent = 'Save';
+    document.body.appendChild(el);
+
+    await render(
+      [{ type: 'point', ref: '@e1' }],
+      makeResolver({ '@e1': el }),
+    );
+    expect(
+      document.querySelector('[data-chat-highlight-overlay]'),
+    ).not.toBeNull();
+    // The SVG spotlight canvas is mounted.
+    expect(document.querySelector('svg')).not.toBeNull();
+  });
+
+  it('renders a caption when the directive has a label', async () => {
+    const el = document.createElement('input');
+    document.body.appendChild(el);
+
+    await render(
+      [{ type: 'point', ref: '@e1', label: 'Type your key here' }],
+      makeResolver({ '@e1': el }),
+    );
+    expect(document.body.textContent).toContain('Type your key here');
+  });
+
+  it('focuses the element when the directive asks for focus', async () => {
+    const el = document.createElement('input');
+    document.body.appendChild(el);
+
+    await render(
+      [{ type: 'point', ref: '@e1', focus: true }],
+      makeResolver({ '@e1': el }),
+    );
+    expect(document.activeElement).toBe(el);
+  });
+
+  it('does not focus when focus is not requested', async () => {
+    const el = document.createElement('input');
+    document.body.appendChild(el);
+
+    await render(
+      [{ type: 'point', ref: '@e1' }],
+      makeResolver({ '@e1': el }),
+    );
+    expect(document.activeElement).not.toBe(el);
+  });
+});