@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/lib/page-snapshot/cst/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Compact Semantic Tree (CST) — the snapshot representation.
+ *
+ * A token-efficient typed tree of a rendered page: interactive elements
+ * carry short stable ref ids, containers give structure, prose collapses
+ * into Markdown text nodes. ~90–95% smaller than raw HTML.
+ *
+ */
+
+/** Short stable ref of an interactive CST node, e.g. "@e4". */
+export type CSTRefId = `@e${number}`;
+
+/** Roles an interactive node can take. */
+export type CSTInteractiveRole =
+  | 'button'
+  | 'link'
+  | 'textbox'
+  | 'checkbox'
+  | 'radio'
+  | 'combobox'
+  | 'select'
+  | 'textarea'
+  | 'slider'
+  | 'spinbutton'
+  | 'searchbox'
+  | 'switch'
+  | 'tab'
+  | 'menuitem'
+  | 'dialog';
+
+/** Roles a container node can take. */
+export type CSTContainerRole =
+  | 'form'
+  | 'table'
+  | 'list'
+  | 'section'
+  | 'grid'
+  | 'navigation'
+  | 'region';
+
+/** Discriminated union of every CST node kind. */
+export type CSTNode =
+  | CSTRootNode
+  | CSTInteractiveNode
+  | CSTContainerNode
+  | CSTTextNode;
+
+/** Root of a snapshot tree. */
+export interface CSTRootNode {
+  type: 'root';
+  /** Page title (document.title). */
+  title: string;
+  /** Page URL at capture time. */
+  url: string;
+  children: CSTNode[];
+}
+
+/**
+ * An interactive element — button, input, select, etc.
+ * The `ref` is the address the AI uses to point at it later.
+ */
+export interface CSTInteractiveNode {
+  type: 'interactive';
+  role: CSTInteractiveRole;
+  /** Stable ref id, unique within the snapshot. */
+  ref: CSTRefId;
+  /** Accessible name. */
+  name: string;
+  /** Current value, if any (already redaction-processed). */
+  value?: string;
+  /** Placeholder text, if any. */
+  placeholder?: string;
+  disabled?: boolean;
+  checked?: boolean;
+  expanded?: boolean;
+  required?: boolean;
+}
+
+/** A structural grouping — form, table, section, etc. */
+export interface CSTContainerNode {
+  type: 'container';
+  role: CSTContainerRole;
+  /** Optional accessible name / heading. */
+  name?: string;
+  children: CSTNode[];
+}
+
+/** A run of static prose, collapsed into compact Markdown. */
+export interface CSTTextNode {
+  type: 'text';
+  /** Pruned structural text formatted as simplified Markdown. */
+  content: string;
+}
+
+/** Type guard: is this an interactive node. */
+export function isInteractiveNode(node: CSTNode): node is CSTInteractiveNode {
+  return node.type === 'interactive';
+}
+
+/** Type guard: is this a container node. */
+export function isContainerNode(node: CSTNode): node is CSTContainerNode {
+  return node.type === 'container';
+}
+
+/** Type guard: is this a text node. */
+export function isTextNode(node: CSTNode): node is CSTTextNode {
+  return node.type === 'text';
+}
+
+/** Nodes that can have children. */
+export function hasChildren(
+  node: CSTNode,
+): node is CSTRootNode | CSTContainerNode {
+  return node.type === 'root' || node.type === 'container';
+}

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

@@ -0,0 +1,176 @@
+/**
+ * PageSnapshotEngine — the capture orchestrator.
+ *
+ * Client-side only. Walks the live DOM into a CST snapshot, folds
+ * repetitive structure, enforces the token budget, and emits a
+ * PageContextPayload plus a ref registry for `point` directives.
+ *
+ * Pipeline: scope → walk → fold → budget → serialize → metadata.
+ */
+
+import { enforceBudget, type DegradationLevel } from './capture/budget';
+import { foldSiblings } from './capture/fold';
+import { resolveScope, type ScopeStrategy, type ScopeTier } from './capture/scope';
+import { noopRedact, walkDOM } from './capture/walk';
+import type { RedactValue } from './capture/walk';
+import type { CSTNode, CSTRefId, CSTRootNode } from './cst/types';
+import type { PageContextPayload, SnapshotMetadata } from './cst/payload';
+import { CST_SCHEMA_VERSION } from './cst/payload';
+import { serializeCST } from './cst/serialize';
+import { RedactionAuditor } from './redaction/audit';
+import { createRedactor } from './redaction';
+import { RefRegistry } from './refs/registry';
+import { hashSnapshot } from './staleness/hash';
+import { estimateTokens } from './tokens';
+
+/** Default token budget — sized for real data tables. */
+export const DEFAULT_TOKEN_BUDGET = 8_000;
+
+/** Options for constructing the engine. */
+export interface CaptureEngineOptions {
+  /** Scope strategy (default: 'container' — auto-detect content). */
+  scope?: ScopeStrategy;
+  /** Token budget for the snapshot (default: DEFAULT_TOKEN_BUDGET). */
+  tokenBudget?: number;
+  /** Explicit target selector; overrides auto-detection. */
+  targetSelector?: string;
+}
+
+/** Telemetry from one capture run. */
+export interface CaptureTelemetry {
+  /** Wall-clock duration of the capture, ms. */
+  executionTimeMs: number;
+  /** DOM elements visited. */
+  nodesVisited: number;
+  /** Estimated tokens of the serialized snapshot. */
+  tokenEstimate: number;
+  /** Redactions performed. */
+  redactedCount: number;
+  /** Sibling chains folded. */
+  foldedCount: number;
+  /** Which scope tier produced the capture root. */
+  scopeTier: ScopeTier;
+  /** What budget degradation, if any, was applied. */
+  degradation: DegradationLevel;
+}
+
+/** Result of a capture. */
+export interface CaptureResult {
+  payload: PageContextPayload;
+  telemetry: CaptureTelemetry;
+  /** Per-snapshot ref → element map, for resolving `point` directives. */
+  refs: RefRegistry;
+}
+
+/** Resolve options with defaults applied. */
+function resolveOptions(
+  options: CaptureEngineOptions,
+): Required<Omit<CaptureEngineOptions, 'targetSelector'>> &
+  Pick<CaptureEngineOptions, 'targetSelector'> {
+  return {
+    scope: options.scope ?? 'container',
+    tokenBudget: options.tokenBudget ?? DEFAULT_TOKEN_BUDGET,
+    targetSelector: options.targetSelector,
+  };
+}
+
+/** Monotonic id source for snapshots within a session. */
+let snapshotSeq = 0;
+
+/**
+ * The capture engine. One instance per consumer (e.g. the chat).
+ */
+export class PageSnapshotEngine {
+  private readonly options: ReturnType<typeof resolveOptions>;
+
+  constructor(options: CaptureEngineOptions = {}) {
+    this.options = resolveOptions(options);
+  }
+
+  /**
+   * Capture a snapshot of the current page.
+   */
+  capture(): CaptureResult {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      throw new Error(
+        'PageSnapshotEngine.capture: cannot run outside a browser.',
+      );
+    }
+
+    const startTime = performance.now();
+    const auditor = new RedactionAuditor();
+    const redactValue: RedactValue = this.buildRedactor(auditor);
+    const refs = new RefRegistry(`snap-${++snapshotSeq}`);
+
+    // Scope → walk (each root) → merge.
+    const scope = resolveScope({
+      strategy: this.options.scope,
+      targetSelector: this.options.targetSelector,
+    });
+
+    let walked: CSTNode[] = [];
+    let nodesVisited = 0;
+    for (const root of scope.roots) {
+      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);
+      }
+    }
+
+    // Fold repetitive structure, then enforce the token budget.
+    const folded = foldSiblings(walked);
+    const budgeted = enforceBudget(folded.children, this.options.tokenBudget);
+
+    const root: CSTRootNode = {
+      type: 'root',
+      title: document.title,
+      url: window.location.href,
+      children: budgeted.children,
+    };
+
+    const serialized = serializeCST(root);
+    const tokenEstimate = estimateTokens(serialized);
+    const executionTimeMs = performance.now() - startTime;
+
+    const metadata: SnapshotMetadata = {
+      representation: 'CST',
+      tokenEstimate,
+      captureTimestamp: Date.now(),
+      schemaVersion: CST_SCHEMA_VERSION,
+      contentHash: hashSnapshot(serialized),
+      redactedCount: auditor.redactedCount,
+      foldedCount: folded.foldedCount,
+    };
+
+    const payload: PageContextPayload = {
+      url: window.location.href,
+      route: window.location.pathname,
+      params: {},
+      title: document.title,
+      snapshot: root,
+      metadata,
+    };
+
+    return {
+      payload,
+      refs,
+      telemetry: {
+        executionTimeMs,
+        nodesVisited,
+        tokenEstimate,
+        redactedCount: auditor.redactedCount,
+        foldedCount: folded.foldedCount,
+        scopeTier: scope.tier,
+        degradation: budgeted.degradation,
+      },
+    };
+  }
+
+  /** Build the redaction function bound to this run's auditor. */
+  private buildRedactor(auditor: RedactionAuditor): RedactValue {
+    return createRedactor(auditor) ?? noopRedact;
+  }
+}

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

@@ -0,0 +1,93 @@
+/**
+ * @djangocfg/ui-tools — page-snapshot
+ *
+ * Client-side capture engine: walks a live React/Next.js DOM into a
+ * compact, token-efficient, redacted CST snapshot for an AI chat that
+ * understands the page the user is looking at.
+ *
+ * Internal to `ui-tools` — consumed by `tools/Chat`. Kept as a folder
+ * (not a standalone package) while it has a single consumer; promote to
+ * a package only when something outside `ui-tools` needs it.
+ */
+
+// Engine.
+export {
+  PageSnapshotEngine,
+  DEFAULT_TOKEN_BUDGET,
+  type CaptureEngineOptions,
+  type CaptureResult,
+  type CaptureTelemetry,
+} from './engine';
+
+// CST types.
+export type {
+  CSTNode,
+  CSTRootNode,
+  CSTInteractiveNode,
+  CSTContainerNode,
+  CSTTextNode,
+  CSTRefId,
+  CSTInteractiveRole,
+  CSTContainerRole,
+} from './cst/types';
+export {
+  isInteractiveNode,
+  isContainerNode,
+  isTextNode,
+  hasChildren,
+} from './cst/types';
+
+// Payload.
+export {
+  CST_SCHEMA_VERSION,
+  type PageContextPayload,
+  type SnapshotMetadata,
+  type SnapshotRepresentation,
+} from './cst/payload';
+
+// Directives — shared with the chat for AI-driven highlight/focus.
+export {
+  isPointDirective,
+  type UIDirective,
+  type PointDirective,
+  type ChatResponseMeta,
+} from './cst/directives';
+
+// Redaction (audit surface).
+export {
+  RedactionAuditor,
+  type RedactionAuditReport,
+  type RedactionReason,
+  type RedactionEntry,
+} from './redaction/audit';
+
+// Refs.
+export { RefRegistry } from './refs/registry';
+
+// Utilities.
+export { estimateTokens } from './tokens';
+export { serializeCST } from './cst/serialize';
+export { hashSnapshot } from './staleness/hash';
+export { type ScopeStrategy } from './capture/scope';
+
+// React surface.
+export {
+  PageSnapshotProvider,
+  type PageSnapshotProviderProps,
+} from './react/provider';
+export {
+  usePageSnapshot,
+  type PageSnapshotContextValue,
+} from './react/use-page-snapshot';
+export {
+  usePageSnapshotToggle,
+  type PageSnapshotToggle,
+} from './react/use-page-snapshot-toggle';
+export {
+  PageSnapshotChip,
+  type PageSnapshotChipProps,
+} from './react/PageSnapshotChip';
+export {
+  PageSnapshotPreview,
+  type PageSnapshotPreviewProps,
+} from './react/PageSnapshotPreview';

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

@@ -0,0 +1,72 @@
+'use client';
+
+import { useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { Eye, MonitorUp, RefreshCw } from 'lucide-react';
+
+import { PageSnapshotPreview } from './PageSnapshotPreview';
+import { usePageSnapshot } from './use-page-snapshot';
+
+/** Props for `PageSnapshotChip`. */
+export interface PageSnapshotChipProps {
+  className?: string;
+}
+
+/**
+ * A small status chip the user sees near the composer when page-context
+ * sharing is on. Communicates three things:
+ *   - that the screen is currently shared ("Screen connected"),
+ *   - whether the captured context is stale vs the page they now see,
+ *   - a way to inspect exactly what is shared (opens the preview drawer).
+ *
+ * Renders nothing when the user has not opted in — no opt-in, no chip.
+ */
+export function PageSnapshotChip({ className }: PageSnapshotChipProps) {
+  const { isLinked, isStale, refresh } = usePageSnapshot();
+  const [previewOpen, setPreviewOpen] = useState(false);
+
+  // No chip at all until the user opts in.
+  if (!isLinked) return null;
+
+  return (
+    <>
+      <div
+        className={cn(
+          'inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-xs',
+          isStale
+            ? 'border-amber-500/40 text-amber-600 dark:text-amber-400'
+            : 'border-border text-muted-foreground',
+          className,
+        )}
+      >
+        <MonitorUp className="size-3.5" aria-hidden />
+        <span>{isStale ? 'Screen changed' : 'Screen connected'}</span>
+
+        {/* Refresh — only meaningful once the context is stale. */}
+        {isStale && (
+          <button
+            type="button"
+            onClick={refresh}
+            className="hover:text-foreground inline-flex items-center"
+            aria-label="Refresh page context"
+          >
+            <RefreshCw className="size-3.5" aria-hidden />
+          </button>
+        )}
+
+        {/* Inspect — opens the preview drawer (the trust surface). */}
+        <button
+          type="button"
+          onClick={() => setPreviewOpen(true)}
+          className="hover:text-foreground inline-flex items-center"
+          aria-label="Preview shared page context"
+        >
+          <Eye className="size-3.5" aria-hidden />
+        </button>
+      </div>
+
+      <PageSnapshotPreview open={previewOpen} onOpenChange={setPreviewOpen} />
+    </>
+  );
+}

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

@@ -0,0 +1,78 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from '@djangocfg/ui-core/components';
+
+import { usePageSnapshot } from './use-page-snapshot';
+
+/** Props for `PageSnapshotPreview`. */
+export interface PageSnapshotPreviewProps {
+  /** Whether the drawer is open. */
+  open: boolean;
+  /** Called when the user dismisses the drawer. */
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * The trust surface: a side drawer that shows the user exactly what
+ * page-context snapshot would be sent to the AI — already redacted.
+ *
+ * It captures fresh on open (preview mode, ignoring the opt-in gate) so
+ * what the user sees is what the next message would actually carry.
+ */
+export function PageSnapshotPreview({
+  open,
+  onOpenChange,
+}: PageSnapshotPreviewProps) {
+  const { generatePreview } = usePageSnapshot();
+
+  // Capture a preview only while the drawer is open — no point walking
+  // the DOM otherwise. Re-runs whenever the drawer is (re)opened.
+  const preview = useMemo(
+    () => (open ? generatePreview() : null),
+    [open, generatePreview],
+  );
+
+  const json = useMemo(
+    () =>
+      preview
+        ? JSON.stringify(preview.payload.snapshot, null, 2)
+        : '',
+    [preview],
+  );
+
+  const meta = preview?.payload.metadata;
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent side="right" className="flex w-[28rem] max-w-[90vw] flex-col">
+        <SheetHeader>
+          <SheetTitle>Page context preview</SheetTitle>
+          <SheetDescription>
+            This is exactly what the assistant sees about your screen.
+            Sensitive values are already removed.
+          </SheetDescription>
+        </SheetHeader>
+
+        {meta && (
+          <div className="text-muted-foreground flex flex-wrap gap-x-4 gap-y-1 text-xs">
+            <span>~{meta.tokenEstimate} tokens</span>
+            <span>{meta.redactedCount} redacted</span>
+            <span>{meta.foldedCount} groups folded</span>
+          </div>
+        )}
+
+        <pre className="bg-muted/50 min-h-0 flex-1 overflow-auto rounded-md p-3 text-xs leading-relaxed">
+          {json || 'Nothing to preview.'}
+        </pre>
+      </SheetContent>
+    </Sheet>
+  );
+}

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

@@ -0,0 +1,54 @@
+// @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 { PageSnapshotChip } from '../PageSnapshotChip';
+import { PageSnapshotProvider } from '../provider';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+async function render(defaultLinked: boolean) {
+  await act(async () => {
+    root.render(
+      createElement(PageSnapshotProvider, {
+        defaultLinked,
+        children: createElement(PageSnapshotChip, {}),
+      }),
+    );
+  });
+}
+
+describe('PageSnapshotChip', () => {
+  it('renders nothing when not opted in', async () => {
+    await render(false);
+    expect(container.textContent).toBe('');
+  });
+
+  it('shows "Screen connected" when opted in', async () => {
+    await render(true);
+    expect(container.textContent).toContain('Screen connected');
+  });
+
+  it('exposes a preview button when opted in', async () => {
+    await render(true);
+    const previewBtn = container.querySelector(
+      '[aria-label="Preview shared page context"]',
+    );
+    expect(previewBtn).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+import { act } from 'react';
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { PageSnapshotProvider } from '../provider';
+import {
+  usePageSnapshot,
+  type PageSnapshotContextValue,
+} from '../use-page-snapshot';
+
+// React 19 act() environment flag.
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+/** Latest context value, captured by the probe component each render. */
+let ctx: PageSnapshotContextValue | null = null;
+
+/** Probe component — publishes the context value to the test. */
+function Probe() {
+  ctx = usePageSnapshot();
+  return null;
+}
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  ctx = null;
+});
+
+/** Render the provider with the probe inside; flushes effects. */
+async function render(defaultLinked = false) {
+  await act(async () => {
+    root.render(
+      createElement(PageSnapshotProvider, {
+        defaultLinked,
+        children: createElement(Probe),
+      }),
+    );
+  });
+}
+
+describe('PageSnapshotProvider / usePageSnapshot', () => {
+  it('defaults to not linked', async () => {
+    await render();
+    expect(ctx!.isLinked).toBe(false);
+    expect(ctx!.lastSnapshot).toBeNull();
+  });
+
+  it('capture() returns null while not linked', async () => {
+    await render();
+    let result: unknown;
+    act(() => {
+      result = ctx!.capture();
+    });
+    expect(result).toBeNull();
+  });
+
+  it('getChatMetadata() returns undefined while not linked', async () => {
+    await render();
+    expect(ctx!.getChatMetadata()).toBeUndefined();
+  });
+
+  it('generatePreview() works even when not linked (preview gate)', async () => {
+    document.body.innerHTML += '<main><h1>Preview Page</h1></main>';
+    await render();
+    let preview: ReturnType<PageSnapshotContextValue['generatePreview']>;
+    act(() => {
+      preview = ctx!.generatePreview();
+    });
+    expect(preview!).not.toBeNull();
+    expect(preview!.payload.snapshot.type).toBe('root');
+  });
+
+  it('opting in captures an initial snapshot', async () => {
+    document.body.innerHTML += '<main><h1>Linked Page</h1></main>';
+    await render();
+    await act(async () => {
+      ctx!.setIsLinked(true);
+    });
+    expect(ctx!.isLinked).toBe(true);
+    expect(ctx!.lastSnapshot).not.toBeNull();
+  });
+
+  it('getChatMetadata() returns { pageContext } when linked', async () => {
+    document.body.innerHTML += '<main><h1>Meta Page</h1></main>';
+    await render(true);
+    let meta: Record<string, unknown> | undefined;
+    await act(async () => {
+      meta = ctx!.getChatMetadata();
+    });
+    expect(meta).toBeDefined();
+    expect(meta).toHaveProperty('pageContext');
+  });
+});