@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/lib/page-snapshot/react/__tests__/use-page-snapshot-toggle.test.tsx

@@ -0,0 +1,62 @@
+// @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 { PageSnapshotProvider } from '../provider';
+import {
+  usePageSnapshotToggle,
+  type PageSnapshotToggle,
+} from '../use-page-snapshot-toggle';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+let toggle: PageSnapshotToggle | null = null;
+
+function Probe() {
+  toggle = usePageSnapshotToggle();
+  return null;
+}
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  toggle = null;
+});
+
+async function render() {
+  await act(async () => {
+    root.render(
+      createElement(PageSnapshotProvider, {
+        children: createElement(Probe),
+      }),
+    );
+  });
+}
+
+describe('usePageSnapshotToggle', () => {
+  it('starts not pressed', async () => {
+    await render();
+    expect(toggle!.pressed).toBe(false);
+    expect(toggle!.label).toMatch(/share/i);
+  });
+
+  it('toggles the opt-in on and off', async () => {
+    await render();
+
+    await act(async () => toggle!.toggle());
+    expect(toggle!.pressed).toBe(true);
+    expect(toggle!.label).toMatch(/stop sharing/i);
+
+    await act(async () => toggle!.toggle());
+    expect(toggle!.pressed).toBe(false);
+  });
+});

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

@@ -0,0 +1,162 @@
+'use client';
+
+import {
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { useLocationProperty } from '@djangocfg/ui-core/hooks';
+
+import type { CaptureEngineOptions, CaptureResult } from '../engine';
+import { PageSnapshotEngine } from '../engine';
+import {
+  PageSnapshotContext,
+  type PageSnapshotContextValue,
+} from './use-page-snapshot';
+
+/** Props for `PageSnapshotProvider`. */
+export interface PageSnapshotProviderProps {
+  /** Engine configuration. */
+  config?: CaptureEngineOptions;
+  /**
+   * Start opted-in. Default false — the user must explicitly enable
+   * sharing page context.
+   */
+  defaultLinked?: boolean;
+  children: ReactNode;
+}
+
+/**
+ * Provides the page-snapshot capability to the chat.
+ *
+ * - Constructs the engine lazily, browser-only (hydration-safe).
+ * - Holds the opt-in state.
+ * - `getChatMetadata` is the contributor handed to
+ *   `ChatProvider.getDynamicMetadata`: it captures a fresh snapshot at
+ *   send time (capture-on-submit) and returns `{ pageContext }`.
+ * - Auto-captures on route change; tracks staleness via content hash.
+ */
+export function PageSnapshotProvider({
+  config,
+  defaultLinked = false,
+  children,
+}: PageSnapshotProviderProps) {
+  const [isLinked, setIsLinked] = useState(defaultLinked);
+  const [isStale, setIsStale] = useState(false);
+  const [lastSnapshot, setLastSnapshot] = 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);
+  const getEngine = useCallback((): PageSnapshotEngine | null => {
+    if (typeof window === 'undefined') return null;
+    if (!engineRef.current) {
+      engineRef.current = new PageSnapshotEngine(config);
+    }
+    return engineRef.current;
+  }, [config]);
+
+  // The latest content hash — used to decide if the page changed.
+  const lastHashRef = useRef<string | null>(null);
+
+  /**
+   * Run a capture; on success update lastSnapshot + hash + staleness.
+   *
+   * Capture is synchronous (a DOM walk, single-digit ms) so there is no
+   * `isProcessing` flag to toggle around it — that would only add two
+   * needless re-renders.
+   */
+  const runCapture = useCallback(
+    (track: boolean): CaptureResult | null => {
+      const engine = getEngine();
+      if (!engine) return null;
+      try {
+        const result = engine.capture();
+        if (track) {
+          setLastSnapshot(result);
+          lastHashRef.current = result.payload.metadata.contentHash;
+          setIsStale(false);
+        }
+        return result;
+      } catch {
+        // Capture must never break the chat — fail soft.
+        return null;
+      }
+    },
+    [getEngine],
+  );
+
+  const capture = useCallback((): CaptureResult | null => {
+    if (!isLinked) return null;
+    return runCapture(true);
+  }, [isLinked, runCapture]);
+
+  const generatePreview = useCallback(
+    (): CaptureResult | null => runCapture(false),
+    [runCapture],
+  );
+
+  const refresh = useCallback(() => {
+    runCapture(true);
+  }, [runCapture]);
+
+  /**
+   * The chat metadata contributor. Captures fresh at call time — the
+   * chat invokes this synchronously at send (capture-on-submit).
+   */
+  const getChatMetadata = useCallback((): Record<string, unknown> | undefined => {
+    if (!isLinked) return undefined;
+    const result = capture();
+    if (!result) return undefined;
+    return { pageContext: result.payload };
+  }, [isLinked, capture]);
+
+  // Reactive pathname from ui-core's router abstraction. Framework-
+  // agnostic (History API under the hood) — no next/navigation
+  // dependency, works in Next / Vite / CRA / Electron alike.
+  const pathname = useLocationProperty(
+    () => window.location.pathname,
+    () => '/',
+  );
+
+  // Route change → auto-capture a fresh snapshot (capture, not send).
+  // Also covers the initial opt-in: when `isLinked` flips true this
+  // effect runs and populates `lastSnapshot`.
+  useEffect(() => {
+    if (!isLinked) return;
+    runCapture(true);
+    // `pathname` in deps: a new route re-captures automatically.
+  }, [isLinked, pathname, runCapture]);
+
+  const value = useMemo<PageSnapshotContextValue>(
+    () => ({
+      isLinked,
+      setIsLinked,
+      capture,
+      generatePreview,
+      getChatMetadata,
+      lastSnapshot,
+      isStale,
+      refresh,
+    }),
+    [
+      isLinked,
+      capture,
+      generatePreview,
+      getChatMetadata,
+      lastSnapshot,
+      isStale,
+      refresh,
+    ],
+  );
+
+  return (
+    <PageSnapshotContext.Provider value={value}>
+      {children}
+    </PageSnapshotContext.Provider>
+  );
+}

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

@@ -0,0 +1,47 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { usePageSnapshot } from './use-page-snapshot';
+
+/**
+ * The opt-in toggle's current state and click handler.
+ *
+ * Deliberately framework-/component-agnostic: it returns plain values,
+ * not a `ComposerAction`. The host wires these into whatever toggle
+ * control its composer uses — this keeps `page-snapshot` decoupled from
+ * the chat's component types.
+ */
+export interface PageSnapshotToggle {
+  /** Whether page-context sharing is currently on. */
+  pressed: boolean;
+  /** Flip the opt-in. */
+  toggle: () => void;
+  /** Suggested control label / tooltip — reflects the current state. */
+  label: string;
+}
+
+/**
+ * Drive an opt-in toggle for page-context sharing.
+ *
+ * @example
+ *   const snap = usePageSnapshotToggle();
+ *   // feed into a composer action:
+ *   { id: 'page-context', icon: <MonitorUp />, label: snap.label,
+ *     pressed: snap.pressed, onClick: snap.toggle }
+ */
+export function usePageSnapshotToggle(): PageSnapshotToggle {
+  const { isLinked, setIsLinked } = usePageSnapshot();
+
+  const toggle = useCallback(() => {
+    setIsLinked(!isLinked);
+  }, [isLinked, setIsLinked]);
+
+  return {
+    pressed: isLinked,
+    toggle,
+    label: isLinked
+      ? 'Stop sharing page context'
+      : 'Share page context with the assistant',
+  };
+}

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

@@ -0,0 +1,67 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+import type { CaptureResult } from '../engine';
+
+/**
+ * The page-snapshot context value.
+ *
+ * Exposes the opt-in state, capture, staleness, and a `getChatMetadata`
+ * contributor the host passes to `ChatProvider.getDynamicMetadata`.
+ */
+export interface PageSnapshotContextValue {
+  /** Whether the user has opted in to sharing page context. */
+  isLinked: boolean;
+  /** Toggle the opt-in. */
+  setIsLinked: (linked: boolean) => void;
+
+  /**
+   * Capture a snapshot for sending. Returns null when not linked, when
+   * not in a browser, or when capture fails. Updates `lastSnapshot` and
+   * clears the stale flag.
+   */
+  capture: () => CaptureResult | null;
+
+  /**
+   * Capture a snapshot for preview only — ignores the opt-in gate and
+   * does not update staleness state. Drives the preview drawer.
+   */
+  generatePreview: () => CaptureResult | null;
+
+  /**
+   * The chat metadata contributor. Returns `{ pageContext }` when
+   * linked, `undefined` otherwise. Passed to
+   * `ChatProvider.getDynamicMetadata` — invoked at send time, so it
+   * captures a fresh snapshot per message (capture-on-submit).
+   */
+  getChatMetadata: () => Record<string, unknown> | undefined;
+
+  /** The most recent captured snapshot, if any. */
+  lastSnapshot: CaptureResult | null;
+
+  /** Whether the captured context is stale vs the current page. */
+  isStale: boolean;
+
+  /** Force a fresh capture and clear staleness (e.g. chip "refresh"). */
+  refresh: () => void;
+}
+
+/** Internal context — consumed via `usePageSnapshot`. */
+export const PageSnapshotContext =
+  createContext<PageSnapshotContextValue | null>(null);
+
+/**
+ * Access the page-snapshot context.
+ *
+ * Must be used within a `PageSnapshotProvider`.
+ */
+export function usePageSnapshot(): PageSnapshotContextValue {
+  const ctx = useContext(PageSnapshotContext);
+  if (!ctx) {
+    throw new Error(
+      'usePageSnapshot must be used within a PageSnapshotProvider.',
+    );
+  }
+  return ctx;
+}

package/src/lib/page-snapshot/redaction/__tests__/audit.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { RedactionAuditor } from '../audit';
+
+describe('RedactionAuditor', () => {
+  it('counts scanned elements and redactions', () => {
+    const auditor = new RedactionAuditor();
+    auditor.markScanned();
+    auditor.markScanned();
+    auditor.log({ elementRole: 'input', triggerReason: 'heuristic' });
+
+    const report = auditor.report();
+    expect(report.totalElementsScanned).toBe(2);
+    expect(report.totalRedactedCount).toBe(1);
+    expect(report.entries[0].triggerReason).toBe('heuristic');
+    expect(auditor.redactedCount).toBe(1);
+  });
+
+  it('starts empty', () => {
+    const report = new RedactionAuditor().report();
+    expect(report.totalElementsScanned).toBe(0);
+    expect(report.totalRedactedCount).toBe(0);
+    expect(report.entries).toEqual([]);
+  });
+});

package/src/lib/page-snapshot/redaction/__tests__/heuristics.test.ts

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  hasIncludeAnnotation,
+  hasRedactAnnotation,
+  heuristicRedactKind,
+} from '../heuristics';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+function el(html: string): HTMLElement {
+  document.body.innerHTML = html;
+  return document.body.firstElementChild as HTMLElement;
+}
+
+describe('heuristicRedactKind', () => {
+  it('flags a password input', () => {
+    expect(heuristicRedactKind(el('<input type="password" />'))).toBe(
+      'password',
+    );
+  });
+
+  it('flags fields named like secrets', () => {
+    expect(heuristicRedactKind(el('<input name="api_key" />'))).toBe(
+      'sensitive-name',
+    );
+    expect(heuristicRedactKind(el('<input id="stripe-secret" />'))).toBe(
+      'sensitive-name',
+    );
+    expect(heuristicRedactKind(el('<input class="cvv-field" />'))).toBe(
+      'sensitive-name',
+    );
+  });
+
+  it('flags sensitive autocomplete values', () => {
+    expect(
+      heuristicRedactKind(el('<input autocomplete="current-password" />')),
+    ).toBe('autocomplete');
+    expect(
+      heuristicRedactKind(el('<input autocomplete="cc-number" />')),
+    ).toBe('autocomplete');
+  });
+
+  it('does not flag a normal text field', () => {
+    expect(heuristicRedactKind(el('<input name="company" />'))).toBeNull();
+    expect(heuristicRedactKind(el('<input id="search" />'))).toBeNull();
+  });
+});
+
+describe('hasRedactAnnotation', () => {
+  it('detects data-ai-redact on the element', () => {
+    expect(hasRedactAnnotation(el('<div data-ai-redact></div>'))).toBe(true);
+  });
+
+  it('detects data-ai-redact on an ancestor', () => {
+    document.body.innerHTML = `<div data-ai-redact><span id="c">x</span></div>`;
+    expect(hasRedactAnnotation(document.getElementById('c')!)).toBe(true);
+  });
+
+  it('is false on an un-annotated element', () => {
+    expect(hasRedactAnnotation(el('<div></div>'))).toBe(false);
+  });
+});
+
+describe('hasIncludeAnnotation', () => {
+  it('detects data-ai-include', () => {
+    expect(hasIncludeAnnotation(el('<input data-ai-include />'))).toBe(true);
+    expect(hasIncludeAnnotation(el('<input />'))).toBe(false);
+  });
+});

package/src/lib/page-snapshot/redaction/__tests__/luhn.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import { validateLuhn } from '../luhn';
+
+describe('validateLuhn', () => {
+  it('accepts known-valid card numbers', () => {
+    expect(validateLuhn('4242424242424242')).toBe(true); // Visa test
+    expect(validateLuhn('4111111111111111')).toBe(true); // Visa test
+    expect(validateLuhn('5555555555554444')).toBe(true); // Mastercard test
+  });
+
+  it('accepts valid numbers with separators', () => {
+    expect(validateLuhn('4242 4242 4242 4242')).toBe(true);
+    expect(validateLuhn('4242-4242-4242-4242')).toBe(true);
+  });
+
+  it('rejects checksum-invalid numbers', () => {
+    expect(validateLuhn('4242424242424243')).toBe(false);
+    expect(validateLuhn('1234567812345678')).toBe(false);
+  });
+
+  it('rejects too-short / too-long digit runs', () => {
+    expect(validateLuhn('1234')).toBe(false);
+    expect(validateLuhn('12345678901234567890')).toBe(false);
+  });
+});

package/src/lib/page-snapshot/redaction/__tests__/patterns.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { redactPatterns } from '../patterns';
+
+describe('redactPatterns', () => {
+  it('redacts a JWT', () => {
+    const jwt =
+      'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHDpoEx';
+    const { value, matched } = redactPatterns(`token is ${jwt} ok`);
+    expect(matched).toContain('jwt');
+    expect(value).not.toContain('eyJhbGci');
+    expect(value).toContain('‹redacted:jwt›');
+  });
+
+  it('redacts a bearer token', () => {
+    const { value, matched } = redactPatterns(
+      'Authorization: Bearer abcdef1234567890ABCDEF',
+    );
+    expect(matched).toContain('bearer-token');
+    expect(value).not.toContain('abcdef1234567890');
+  });
+
+  it('redacts API-key shapes', () => {
+    const { matched } = redactPatterns('key sk-abcdefghijklmnop1234 end');
+    expect(matched).toContain('api-key');
+  });
+
+  it('redacts an email address', () => {
+    const { value, matched } = redactPatterns('mail me at jane@acme.com now');
+    expect(matched).toContain('email');
+    expect(value).not.toContain('jane@acme.com');
+  });
+
+  it('redacts a Luhn-valid card number', () => {
+    const { value, matched } = redactPatterns('card 4242424242424242 charged');
+    expect(matched).toContain('credit-card');
+    expect(value).not.toContain('4242424242424242');
+  });
+
+  it('does NOT redact a Luhn-invalid long number (order id)', () => {
+    // 16 digits but not a valid card — must survive (false-positive guard).
+    const orderId = '1234567890123456';
+    const { value, matched } = redactPatterns(`order ${orderId} shipped`);
+    expect(matched).not.toContain('credit-card');
+    expect(value).toContain(orderId);
+  });
+
+  it('redacts a phone number with separators or +', () => {
+    expect(redactPatterns('call +1 (415) 555-2671 today').matched).toContain(
+      'phone',
+    );
+    expect(redactPatterns('ph: 415-555-2671').matched).toContain('phone');
+  });
+
+  it('leaves clean text untouched', () => {
+    const { value, matched } = redactPatterns('just a normal sentence');
+    expect(matched).toEqual([]);
+    expect(value).toBe('just a normal sentence');
+  });
+});

package/src/lib/page-snapshot/redaction/audit.ts

@@ -0,0 +1,58 @@
+/**
+ * Redaction audit — a record of what was scrubbed and why.
+ *
+ * Records only that a redaction happened — never the redacted value
+ * itself, so the audit trail is safe to log.
+ */
+
+/** Why a value was redacted. */
+export type RedactionReason = 'heuristic' | 'regex' | 'attribute';
+
+/** One redaction event. */
+export interface RedactionEntry {
+  /** Role/tag of the element involved. */
+  elementRole: string;
+  /** What triggered the redaction. */
+  triggerReason: RedactionReason;
+  /** Ref id, if the element had one. */
+  assignedRef?: string;
+}
+
+/** A full audit report for one capture. */
+export interface RedactionAuditReport {
+  timestamp: number;
+  totalElementsScanned: number;
+  totalRedactedCount: number;
+  entries: RedactionEntry[];
+}
+
+/** Collects redaction events during a capture. */
+export class RedactionAuditor {
+  private readonly entries: RedactionEntry[] = [];
+  private scanned = 0;
+
+  /** Record one scanned element. */
+  markScanned(): void {
+    this.scanned++;
+  }
+
+  /** Record one redaction. */
+  log(entry: RedactionEntry): void {
+    this.entries.push(entry);
+  }
+
+  /** How many redactions so far. */
+  get redactedCount(): number {
+    return this.entries.length;
+  }
+
+  /** Produce the final report. */
+  report(): RedactionAuditReport {
+    return {
+      timestamp: Date.now(),
+      totalElementsScanned: this.scanned,
+      totalRedactedCount: this.entries.length,
+      entries: [...this.entries],
+    };
+  }
+}

package/src/lib/page-snapshot/redaction/heuristics.ts

@@ -0,0 +1,75 @@
+/**
+ * Heuristic redaction — drop a whole field's value by element shape.
+ *
+ * Where patterns.ts scrubs sensitive substrings, this decides that an
+ * entire field is sensitive (a password input, an element named
+ * `*token*`/`*secret*`) and its value must never be captured at all.
+ *
+ * Safe-by-default: an un-annotated page is still covered — heuristics
+ * do not depend on developers adding `data-ai-redact`.
+ *
+ */
+
+/**
+ * Attribute-name / token pattern that marks a field as sensitive.
+ * Tested against id, name, class, autocomplete.
+ */
+const SENSITIVE_NAME_RE =
+  /(^|[\s_-])(password|passwd|pwd|secret|token|api[-_]?key|apikey|auth|bearer|cvv|cvc|card[-_]?number|cc[-_]?num|ssn|sin|tax[-_]?id|private[-_]?key|stripe|client[-_]?secret|access[-_]?key)([\s_-]|$)/i;
+
+/** autocomplete values that mark a sensitive field. */
+const SENSITIVE_AUTOCOMPLETE: ReadonlySet<string> = new Set([
+  'current-password',
+  'new-password',
+  'cc-number',
+  'cc-csc',
+  'one-time-code',
+]);
+
+/** Why a heuristic fired (used for the audit reason / token kind). */
+export type HeuristicKind = 'password' | 'sensitive-name' | 'autocomplete';
+
+/**
+ * Decide whether an element's value must be fully redacted by shape.
+ * Returns the heuristic kind, or null if the element is not sensitive.
+ */
+export function heuristicRedactKind(el: Element): HeuristicKind | null {
+  // A password input — never capture its value.
+  if (el instanceof HTMLInputElement && el.type === 'password') {
+    return 'password';
+  }
+
+  // autocomplete hint.
+  const autocomplete = el.getAttribute('autocomplete')?.toLowerCase();
+  if (autocomplete && SENSITIVE_AUTOCOMPLETE.has(autocomplete)) {
+    return 'autocomplete';
+  }
+
+  // id / name / class token pattern.
+  const tokens = [
+    el.id,
+    el.getAttribute('name') ?? '',
+    typeof el.className === 'string' ? el.className : '',
+  ].join(' ');
+  if (tokens.trim() && SENSITIVE_NAME_RE.test(tokens)) {
+    return 'sensitive-name';
+  }
+
+  return null;
+}
+
+/**
+ * Does this element (or an ancestor) carry `data-ai-redact` — an
+ * explicit developer instruction to drop the whole subtree.
+ */
+export function hasRedactAnnotation(el: Element): boolean {
+  return el.closest('[data-ai-redact]') !== null;
+}
+
+/**
+ * Does this element carry `data-ai-include` — an explicit override that
+ * forces a heuristically-blocked but known-safe value to be kept.
+ */
+export function hasIncludeAnnotation(el: Element): boolean {
+  return el.hasAttribute('data-ai-include');
+}