@djangocfg/ui-tools 2.1.407 → 2.1.409

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.407",
+  "version": "2.1.409",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -51,11 +51,6 @@
       "import": "./src/tools/Uploader/index.ts",
       "require": "./src/tools/Uploader/index.ts"
     },
-    "./tour": {
-      "types": "./src/tools/Tour/index.ts",
-      "import": "./src/tools/Tour/index.ts",
-      "require": "./src/tools/Tour/index.ts"
-    },
     "./code-editor": {
       "types": "./src/tools/CodeEditor/lazy.tsx",
       "import": "./src/tools/CodeEditor/lazy.tsx",
@@ -159,8 +154,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.407",
-    "@djangocfg/ui-core": "^2.1.407",
+    "@djangocfg/i18n": "^2.1.409",
+    "@djangocfg/ui-core": "^2.1.409",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -212,18 +207,18 @@
   },
   "optionalDependencies": {
     "@mapbox/mapbox-gl-draw": "^1.4.3",
-    "@maplibre/maplibre-gl-geocoder": "^1.7.0",
-    "material-file-icons": "^2.4.0"
+    "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.407",
-    "@djangocfg/typescript-config": "^2.1.407",
-    "@djangocfg/ui-core": "^2.1.407",
+    "@djangocfg/i18n": "^2.1.409",
+    "@djangocfg/typescript-config": "^2.1.409",
+    "@djangocfg/ui-core": "^2.1.409",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
+    "jsdom": "^29.1.1",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
     "react": "^19.1.0",

package/src/components/FloatingToolbar/index.tsx

@@ -1,10 +1,39 @@
 'use client';
 
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
 
 import './FloatingToolbar.css';
 import { useScrollIsolation } from './hooks/useScrollIsolation';
 
+/**
+ * Track whether the container actually overflows. Scroll isolation
+ * (and its "Click to scroll" overlay) only makes sense when there is
+ * something to scroll — a fully-visible block must stay interactive.
+ */
+function useIsScrollable(ref: React.RefObject<HTMLElement | null>): boolean {
+  const [scrollable, setScrollable] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const measure = () => {
+      // 1px tolerance for sub-pixel rounding.
+      setScrollable(
+        el.scrollHeight - el.clientHeight > 1 ||
+          el.scrollWidth - el.clientWidth > 1,
+      );
+    };
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return scrollable;
+}
+
 export interface FloatingToolbarProps {
   /** Ref to the container element the toolbar anchors to */
   containerRef: React.RefObject<HTMLElement | null>;
@@ -39,11 +68,16 @@ export const FloatingToolbar: React.FC<FloatingToolbarProps> = ({
   zIndex = 30,
   scrollIsolation = true,
 }) => {
-  const { locked, unlock } = useScrollIsolation(containerRef, scrollIsolation);
+  // Isolation only engages when the container can actually scroll —
+  // a block that fully fits never shows the "Click to scroll" overlay.
+  const isScrollable = useIsScrollable(containerRef);
+  const isolationActive = scrollIsolation && isScrollable;
+
+  const { locked, unlock } = useScrollIsolation(containerRef, isolationActive);
   const [overlayHovered, setOverlayHovered] = useState(false);
 
   const overlay =
-    scrollIsolation && locked ? (
+    isolationActive && locked ? (
       <div
         onClick={unlock}
         onMouseEnter={() => setOverlayHovered(true)}

package/src/lib/page-snapshot/__tests__/capture-integration.test.ts

@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { PageSnapshotEngine } from '../engine';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+/**
+ * Integration: capture realistic pages end-to-end through the engine
+ * (scope → walk → fold → budget). Verifies the P1 success criteria —
+ * a 100-row data table, with folding, stays within budget.
+ */
+describe('capture integration', () => {
+  it('captures a settings form sensibly and well under budget', () => {
+    document.body.innerHTML = `
+      <nav>global nav</nav>
+      <main>
+        <h1>Billing Settings</h1>
+        <form>
+          <label for="company">Company</label>
+          <input id="company" type="text" value="Acme Inc" />
+          <label for="plan">Plan</label>
+          <select id="plan"><option selected>Pro</option></select>
+          <button type="submit">Save</button>
+        </form>
+      </main>`;
+
+    const { payload, telemetry } = new PageSnapshotEngine().capture();
+    const json = JSON.stringify(payload.snapshot);
+
+    // Content is present, chrome is not.
+    expect(json).toContain('Billing Settings');
+    expect(json).toContain('Company');
+    expect(json).not.toContain('global nav');
+
+    // Comfortably small.
+    expect(payload.metadata.tokenEstimate).toBeLessThan(500);
+    expect(telemetry.degradation).toBe('none');
+    expect(telemetry.scopeTier).toBe('tier2-main');
+  });
+
+  it('captures a 100-row table within budget thanks to folding', () => {
+    const rows = Array.from(
+      { length: 100 },
+      (_, i) => `
+        <tr>
+          <td>Client ${i}</td>
+          <td>client${i}@example.com</td>
+          <td><button>Edit</button></td>
+        </tr>`,
+    ).join('');
+    document.body.innerHTML = `
+      <main>
+        <table><tbody>${rows}</tbody></table>
+      </main>`;
+
+    const { payload, telemetry } = new PageSnapshotEngine().capture();
+
+    // Folding fired — the 100 identical rows collapsed.
+    expect(telemetry.foldedCount).toBeGreaterThan(0);
+
+    // The whole snapshot stays within the default 8k budget.
+    expect(payload.metadata.tokenEstimate).toBeLessThan(8_000);
+
+    // The collapse marker is present.
+    expect(JSON.stringify(payload.snapshot)).toContain('collapsed');
+  });
+
+  it('a 100-row table WITHOUT folding would be far larger (sanity)', () => {
+    // Same table; confirm the folded result is dramatically smaller
+    // than the raw row count would imply (~100 rows × 3 cells).
+    const rows = Array.from(
+      { length: 100 },
+      (_, i) => `<tr><td>Client ${i}</td><td>x${i}</td></tr>`,
+    ).join('');
+    document.body.innerHTML = `<main><table><tbody>${rows}</tbody></table></main>`;
+
+    const { payload } = new PageSnapshotEngine().capture();
+    const interactiveAndText = JSON.stringify(payload.snapshot).length;
+    // Folded snapshot is small — nowhere near 100 rows of serialized CST.
+    expect(interactiveAndText).toBeLessThan(4_000);
+  });
+});

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

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+
+import { PageSnapshotEngine } from '../engine';
+import { CST_SCHEMA_VERSION } from '../cst/payload';
+
+describe('PageSnapshotEngine (P0 skeleton)', () => {
+  it('returns a schema-valid empty snapshot', () => {
+    const { payload, telemetry } = new PageSnapshotEngine({
+      scope: 'full',
+    }).capture();
+
+    expect(payload.snapshot.type).toBe('root');
+    expect(payload.snapshot.children).toEqual([]);
+    expect(payload.title).toBe(document.title);
+    expect(payload.url).toBe(window.location.href);
+    expect(payload.route).toBe(window.location.pathname);
+
+    expect(payload.metadata.schemaVersion).toBe(CST_SCHEMA_VERSION);
+    expect(payload.metadata.representation).toBe('CST');
+    expect(payload.metadata.contentHash).toMatch(/^[0-9a-f]{8}$/);
+    expect(payload.metadata.tokenEstimate).toBeGreaterThan(0);
+    expect(payload.metadata.redactedCount).toBe(0);
+    expect(payload.metadata.foldedCount).toBe(0);
+
+    expect(telemetry.nodesVisited).toBe(0);
+    expect(telemetry.executionTimeMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it('produces a stable content hash across repeated captures', () => {
+    const engine = new PageSnapshotEngine();
+    const a = engine.capture().payload.metadata.contentHash;
+    const b = engine.capture().payload.metadata.contentHash;
+    expect(a).toBe(b);
+  });
+});

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

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { PageSnapshotEngine } from '../engine';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+/** Capture the page and return the serialized snapshot string. */
+function snapshotJson(): string {
+  return JSON.stringify(new PageSnapshotEngine().capture().payload.snapshot);
+}
+
+/**
+ * Integration: redaction runs inside the engine's capture pipeline, in
+ * the browser, before any snapshot would leave the device. Verifies the
+ * P2 success criteria — no secret/PII reaches the serialized snapshot.
+ */
+describe('redaction integration', () => {
+  it('redacts a password field value (safe by default, no annotation)', () => {
+    document.body.innerHTML = `
+      <main>
+        <form>
+          <label for="p">Password</label>
+          <input id="p" type="password" value="hunter2-secret" />
+        </form>
+      </main>`;
+    const json = snapshotJson();
+    expect(json).not.toContain('hunter2-secret');
+    expect(json).toContain('‹redacted:password›');
+  });
+
+  it('redacts a secret-named field', () => {
+    document.body.innerHTML = `
+      <main><input name="api_key" type="text" value="raw-key-value-123" /></main>`;
+    const json = snapshotJson();
+    expect(json).not.toContain('raw-key-value-123');
+  });
+
+  it('redacts PII patterns inside static text', () => {
+    document.body.innerHTML = `
+      <main><p>Contact: jane.doe@example.com or call later</p></main>`;
+    const json = snapshotJson();
+    expect(json).not.toContain('jane.doe@example.com');
+    expect(json).toContain('‹redacted:email›');
+  });
+
+  it('drops a data-ai-redact subtree entirely', () => {
+    document.body.innerHTML = `
+      <main>
+        <div data-ai-redact>
+          <input type="text" value="confidential-block-value" />
+          <p>secret paragraph</p>
+        </div>
+        <p>public paragraph</p>
+      </main>`;
+    const json = snapshotJson();
+    expect(json).not.toContain('confidential-block-value');
+    expect(json).not.toContain('secret paragraph');
+    expect(json).toContain('[redacted]');
+    expect(json).toContain('public paragraph');
+  });
+
+  it('data-ai-include overrides a heuristic block for a safe value', () => {
+    // A field named "token" would normally be redacted; data-ai-include
+    // forces the (known-safe, public) value through.
+    document.body.innerHTML = `
+      <main>
+        <input name="public_token_name" data-ai-include
+               type="text" value="PUBLIC-PROJECT-ALPHA" />
+      </main>`;
+    const json = snapshotJson();
+    expect(json).toContain('PUBLIC-PROJECT-ALPHA');
+  });
+
+  it('reports redactions in the capture telemetry', () => {
+    document.body.innerHTML = `
+      <main>
+        <input type="password" value="p1" />
+        <input name="secret_key" value="s1" />
+      </main>`;
+    const { telemetry } = new PageSnapshotEngine().capture();
+    expect(telemetry.redactedCount).toBeGreaterThanOrEqual(2);
+  });
+
+  it('leaves a normal page completely untouched', () => {
+    document.body.innerHTML = `
+      <main>
+        <input name="company" type="text" value="Acme Inc" />
+        <p>Welcome to the dashboard</p>
+      </main>`;
+    const { payload, telemetry } = new PageSnapshotEngine().capture();
+    const json = JSON.stringify(payload.snapshot);
+    expect(json).toContain('Acme Inc');
+    expect(json).toContain('Welcome to the dashboard');
+    expect(telemetry.redactedCount).toBe(0);
+  });
+});

package/src/lib/page-snapshot/__tests__/tokens.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { estimateTokens } from '../tokens';
+
+describe('estimateTokens', () => {
+  it('returns 0 for an empty string', () => {
+    expect(estimateTokens('')).toBe(0);
+  });
+
+  it('scales with length (~chars / 4.2)', () => {
+    expect(estimateTokens('a'.repeat(42))).toBe(10);
+  });
+
+  it('rounds up partial tokens', () => {
+    expect(estimateTokens('abc')).toBe(1);
+  });
+});

package/src/lib/page-snapshot/capture/__tests__/budget.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { enforceBudget } from '../budget';
+import type { CSTNode } from '../../cst/types';
+
+describe('enforceBudget', () => {
+  it('leaves a small snapshot untouched', () => {
+    const children: CSTNode[] = [
+      { type: 'text', content: 'short' },
+      { type: 'interactive', role: 'button', ref: '@e1', name: 'Go' },
+    ];
+    const result = enforceBudget(children, 8_000);
+    expect(result.degradation).toBe('none');
+    expect(result.children).toEqual(children);
+  });
+
+  it('truncates long text when over budget', () => {
+    const children: CSTNode[] = [
+      { type: 'text', content: 'x'.repeat(5_000) },
+    ];
+    const result = enforceBudget(children, 100);
+    expect(result.degradation).toBe('truncated');
+    const text = result.children[0];
+    expect(text.type).toBe('text');
+    if (text.type === 'text') {
+      expect(text.content).toContain('(truncated)');
+      expect(text.content.length).toBeLessThan(200);
+    }
+  });
+
+  it('falls back to interactive-only when truncation is not enough', () => {
+    // Many text nodes — truncation alone still over a tiny budget.
+    const children: CSTNode[] = Array.from({ length: 200 }, (_, i) => ({
+      type: 'text' as const,
+      content: `paragraph ${i} `.repeat(20),
+    }));
+    children.push({
+      type: 'interactive',
+      role: 'button',
+      ref: '@e1',
+      name: 'Submit',
+    });
+    const result = enforceBudget(children, 50);
+    expect(result.degradation).toBe('interactive-only');
+    // Only the interactive node survives.
+    expect(result.children.every((n) => n.type === 'interactive')).toBe(true);
+    expect(result.children).toHaveLength(1);
+  });
+});

package/src/lib/page-snapshot/capture/__tests__/chrome-filter.test.ts

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { isChrome } from '../chrome-filter';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+function el(html: string): HTMLElement {
+  document.body.innerHTML = html;
+  return document.body.firstElementChild as HTMLElement;
+}
+
+describe('isChrome', () => {
+  it('flags landmark chrome tags', () => {
+    expect(isChrome(el('<nav>links</nav>'))).toBe(true);
+    expect(isChrome(el('<header>top</header>'))).toBe(true);
+    expect(isChrome(el('<footer>bottom</footer>'))).toBe(true);
+    expect(isChrome(el('<aside>side</aside>'))).toBe(true);
+  });
+
+  it('flags landmark chrome roles', () => {
+    expect(isChrome(el('<div role="navigation">x</div>'))).toBe(true);
+    expect(isChrome(el('<div role="banner">x</div>'))).toBe(true);
+  });
+
+  it('flags chrome by class/id name pattern', () => {
+    expect(isChrome(el('<div class="sidebar">x</div>'))).toBe(true);
+    expect(isChrome(el('<div id="app-navbar">x</div>'))).toBe(true);
+    expect(isChrome(el('<div class="breadcrumb">x</div>'))).toBe(true);
+  });
+
+  it('never flags content landmarks', () => {
+    expect(isChrome(el('<main>content</main>'))).toBe(false);
+    expect(isChrome(el('<div role="main">content</div>'))).toBe(false);
+  });
+
+  it('does not flag a plain content div', () => {
+    expect(isChrome(el('<div class="card-body">data</div>'))).toBe(false);
+  });
+
+  it('content-named element wins over an unlikely token', () => {
+    // "main-content" contains "content" → not chrome despite layout-ish name
+    expect(isChrome(el('<div class="main-content">x</div>'))).toBe(false);
+  });
+});

package/src/lib/page-snapshot/capture/__tests__/fold.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+
+import { foldSiblings } from '../fold';
+import type { CSTNode } from '../../cst/types';
+
+/** Build N identically-shaped interactive rows. */
+function rows(n: number, role: 'button' = 'button'): CSTNode[] {
+  return Array.from({ length: n }, (_, i) => ({
+    type: 'container' as const,
+    role: 'section' as const,
+    children: [
+      { type: 'interactive' as const, role, ref: `@e${i + 1}` as const, name: `Row ${i}` },
+    ],
+  }));
+}
+
+describe('foldSiblings', () => {
+  it('does not fold short chains (< 5)', () => {
+    const { children, foldedCount } = foldSiblings(rows(4));
+    expect(foldedCount).toBe(0);
+    expect(children).toHaveLength(4);
+  });
+
+  it('folds a long chain of identical siblings', () => {
+    const { children, foldedCount } = foldSiblings(rows(100));
+    expect(foldedCount).toBe(1);
+    // 3 kept + 1 collapse marker.
+    expect(children).toHaveLength(4);
+    expect(children[3]).toEqual({
+      type: 'text',
+      content: '[… 97 more similar items collapsed]',
+    });
+  });
+
+  it('keeps the first 3 instances', () => {
+    const { children } = foldSiblings(rows(20));
+    expect(children.slice(0, 3).every((n) => n.type === 'container')).toBe(true);
+  });
+
+  it('does not fold structurally different siblings', () => {
+    const mixed: CSTNode[] = [
+      { type: 'interactive', role: 'button', ref: '@e1', name: 'A' },
+      { type: 'interactive', role: 'textbox', ref: '@e2', name: 'B' },
+      { type: 'interactive', role: 'checkbox', ref: '@e3', name: 'C' },
+      { type: 'interactive', role: 'link', ref: '@e4', name: 'D' },
+      { type: 'interactive', role: 'select', ref: '@e5', name: 'E' },
+      { type: 'interactive', role: 'tab', ref: '@e6', name: 'F' },
+    ];
+    const { foldedCount, children } = foldSiblings(mixed);
+    expect(foldedCount).toBe(0);
+    expect(children).toHaveLength(6);
+  });
+
+  it('folds nested repetitive lists too', () => {
+    const table: CSTNode[] = [
+      { type: 'container', role: 'table', children: rows(50) },
+    ];
+    const { children, foldedCount } = foldSiblings(table);
+    expect(foldedCount).toBe(1);
+    const tableNode = children[0];
+    expect(tableNode.type).toBe('container');
+    if (tableNode.type === 'container') {
+      expect(tableNode.children).toHaveLength(4); // 3 + marker
+    }
+  });
+});

package/src/lib/page-snapshot/capture/__tests__/scope.test.ts

@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { resolveScope } from '../scope';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+/**
+ * jsdom does not lay out elements, so geometry-based tiers (3 dialog
+ * sizing, heuristic scoring) can only be smoke-tested. These tests
+ * cover the structural tier selection — which is the part that matters
+ * for ladder ordering.
+ */
+describe('resolveScope — tier ladder', () => {
+  it('honors an explicit target selector first', () => {
+    document.body.innerHTML = `<main id="m">content</main><div id="t">x</div>`;
+    const scope = resolveScope({ strategy: 'container', targetSelector: '#t' });
+    expect(scope.tier).toBe('explicit-selector');
+    expect(scope.roots[0].id).toBe('t');
+  });
+
+  it("'full' strategy forces body", () => {
+    document.body.innerHTML = `<main>content</main>`;
+    const scope = resolveScope({ strategy: 'full' });
+    expect(scope.tier).toBe('tier4-body');
+    expect(scope.roots[0]).toBe(document.body);
+  });
+
+  it('Tier 1 — picks [data-ai-context] over <main>', () => {
+    document.body.innerHTML = `
+      <main>main content</main>
+      <div data-ai-context>annotated region</div>
+    `;
+    const scope = resolveScope({ strategy: 'container' });
+    expect(scope.tier).toBe('tier1-annotation');
+    expect(scope.roots[0].dataset.aiContext).toBe('');
+  });
+
+  it('Tier 1 — ignores data-ai-context="exclude"', () => {
+    document.body.innerHTML = `
+      <main>main content</main>
+      <div data-ai-context="exclude">excluded</div>
+    `;
+    const scope = resolveScope({ strategy: 'container' });
+    // Annotation tier yields nothing usable → falls to <main>.
+    expect(scope.tier).toBe('tier2-main');
+  });
+
+  it('Tier 2 — picks <main> when no annotation', () => {
+    document.body.innerHTML = `
+      <nav>navigation</nav>
+      <main id="m">main content here</main>
+    `;
+    const scope = resolveScope({ strategy: 'container' });
+    expect(scope.tier).toBe('tier2-main');
+    expect(scope.roots[0].id).toBe('m');
+  });
+
+  it('Tier 2 — role="main" also counts', () => {
+    document.body.innerHTML = `<div role="main" id="m">content</div>`;
+    const scope = resolveScope({ strategy: 'container' });
+    expect(scope.tier).toBe('tier2-main');
+    expect(scope.roots[0].id).toBe('m');
+  });
+
+  it('Tier 4 — falls back to body when nothing else matches', () => {
+    // No main, no annotation, no sized blocks (jsdom = zero geometry).
+    document.body.innerHTML = `<span>just text</span>`;
+    const scope = resolveScope({ strategy: 'container' });
+    expect(scope.tier).toBe('tier4-body');
+  });
+});