@djangocfg/ui-tools 2.1.404 → 2.1.408

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

@@ -0,0 +1,75 @@
+/**
+ * Redaction entry point — scrub secrets / PII from a captured value.
+ *
+ * Two layers, applied at traverse time:
+ *   1. heuristic — a whole field redacted by element shape
+ *      (password input, `*token*`-named field).
+ *   2. pattern — sensitive substrings scrubbed out of otherwise-kept
+ *      text (JWT, API keys, emails, Luhn-validated cards, …).
+ *
+ * Safe-by-default: an un-annotated page is still covered. `data-ai-redact`
+ * (drop subtree) is handled in the walk; `data-ai-include` overrides the
+ * heuristic layer for a known-safe value.
+ *
+ */
+
+import type { RedactContext, RedactValue } from '../capture/walk';
+import type { RedactionAuditor, RedactionReason } from './audit';
+import {
+  hasIncludeAnnotation,
+  heuristicRedactKind,
+} from './heuristics';
+import { redactPatterns } from './patterns';
+
+export type { RedactionAuditReport, RedactionReason } from './audit';
+export { RedactionAuditor } from './audit';
+
+/** Token substituted for a fully-redacted value. */
+export function redactionToken(kind: string): string {
+  return `‹redacted:${kind}›`;
+}
+
+/**
+ * Build a redaction function bound to an auditor.
+ *
+ * The returned `RedactValue` is the hook the DOM walk calls for every
+ * captured input value and text run.
+ */
+export function createRedactor(auditor: RedactionAuditor): RedactValue {
+  return (value: string, context: RedactContext): string => {
+    auditor.markScanned();
+    if (!value) return value;
+
+    const { element, kind, ref } = context;
+
+    // Layer 1 — heuristic field-level redaction (input values only;
+    // static text has no single owning field shape).
+    if (kind === 'value') {
+      const heuristic = heuristicRedactKind(element);
+      if (heuristic && !hasIncludeAnnotation(element)) {
+        auditor.log({
+          elementRole: element.tagName.toLowerCase(),
+          triggerReason: 'heuristic',
+          assignedRef: ref,
+        });
+        return redactionToken(heuristic);
+      }
+    }
+
+    // Layer 2 — pattern substring redaction.
+    const { value: scrubbed, matched } = redactPatterns(value);
+    if (matched.length > 0) {
+      const reason: RedactionReason = 'regex';
+      for (const _name of matched) {
+        auditor.log({
+          elementRole: element.tagName.toLowerCase(),
+          triggerReason: reason,
+          assignedRef: ref,
+        });
+      }
+      return scrubbed;
+    }
+
+    return value;
+  };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Luhn checksum — validates credit-card-shaped digit runs so order
+ * numbers and IDs are not falsely redacted as cards.
+ *
+ */
+
+/** Validate a digit string with the Luhn algorithm. */
+export function validateLuhn(digits: string): boolean {
+  const normalized = digits.replace(/\D/g, '');
+  if (normalized.length < 13 || normalized.length > 19) return false;
+
+  let sum = 0;
+  let double = false;
+  for (let i = normalized.length - 1; i >= 0; i--) {
+    let digit = normalized.charCodeAt(i) - 48; // '0' === 48
+    if (digit < 0 || digit > 9) return false;
+    if (double) {
+      digit *= 2;
+      if (digit > 9) digit -= 9;
+    }
+    sum += digit;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Redaction pattern catalog — secret / PII value patterns.
+ *
+ * Applied to string values (input values, static text) — these scrub
+ * sensitive substrings out of otherwise-keepable text. A separate
+ * heuristic layer (heuristics.ts) drops whole fields by element shape.
+ *
+ */
+
+import { validateLuhn } from './luhn';
+
+/** A named value-redaction rule. */
+export interface RedactionPattern {
+  /** Identifier, surfaced in the audit report. */
+  name: string;
+  /** Matcher applied to string values (must be global for replaceAll). */
+  test: RegExp;
+  /**
+   * Optional extra check on a match before redacting — used to avoid
+   * false positives (e.g. Luhn for cards). Return true to redact.
+   */
+  confirm?: (match: string) => boolean;
+}
+
+/** Placeholder a matched secret/PII substring is replaced with. */
+export function patternToken(name: string): string {
+  return `‹redacted:${name}›`;
+}
+
+/**
+ * The catalog. Order matters — more specific patterns first so a token
+ * is not partially eaten by a broader rule.
+ */
+export const REDACTION_PATTERNS: RedactionPattern[] = [
+  {
+    // JWT — three base64url segments.
+    name: 'jwt',
+    test: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+  },
+  {
+    // Bearer / authorization header value.
+    name: 'bearer-token',
+    test: /\bBearer\s+[A-Za-z0-9\-._~+/]{16,}=*/gi,
+  },
+  {
+    // Common API-key prefixes (Stripe, OpenAI, GitHub, generic sk-/pk-).
+    name: 'api-key',
+    test: /\b(?:sk|pk|rk|ghp|gho|github_pat|xox[baprs])[-_][A-Za-z0-9-_]{16,}\b/g,
+  },
+  {
+    // AWS access key id.
+    name: 'aws-key',
+    test: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+  },
+  {
+    // Email address (RFC-5322-ish, pragmatic).
+    name: 'email',
+    test: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  },
+  {
+    // IBAN — country code + check digits + up to 30 alphanumerics.
+    name: 'iban',
+    test: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g,
+  },
+  {
+    // Credit-card-shaped digit runs — Luhn-confirmed to avoid eating
+    // order numbers and other long IDs.
+    name: 'credit-card',
+    test: /\b(?:\d[ -]?){13,19}\b/g,
+    confirm: validateLuhn,
+  },
+  {
+    // Phone number — must look like a phone, not just a long digit run.
+    // Requires either a leading "+" or separators (space/()/-), and a
+    // digit count in the 7–15 range. A bare 16-digit string is an ID,
+    // not a phone, and must survive.
+    name: 'phone',
+    test: /\+?\d[\d\s().-]{5,}\d/g,
+    confirm: (m) => {
+      const digits = m.replace(/\D/g, '');
+      if (digits.length < 7 || digits.length > 15) return false;
+      const hasPlus = m.trimStart().startsWith('+');
+      const hasSeparators = /[\s().-]/.test(m);
+      return hasPlus || hasSeparators;
+    },
+  },
+];
+
+/**
+ * Redact every pattern match within a string.
+ * Returns the scrubbed string and the names of patterns that fired.
+ */
+export function redactPatterns(value: string): {
+  value: string;
+  matched: string[];
+} {
+  let result = value;
+  const matched: string[] = [];
+
+  for (const pattern of REDACTION_PATTERNS) {
+    // Fresh lastIndex each pattern.
+    pattern.test.lastIndex = 0;
+    result = result.replace(pattern.test, (match) => {
+      if (pattern.confirm && !pattern.confirm(match)) return match;
+      if (!matched.includes(pattern.name)) matched.push(pattern.name);
+      return patternToken(pattern.name);
+    });
+  }
+
+  return { value: result, matched };
+}

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

@@ -0,0 +1,24 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+
+import { RefRegistry } from '../registry';
+
+describe('RefRegistry', () => {
+  it('reports unknown refs as unresolved', () => {
+    const reg = new RefRegistry('snap-1');
+    expect(reg.has('@e9')).toBe(false);
+    expect(reg.resolve('@e9')).toBeNull();
+    expect(reg.size).toBe(0);
+    expect(reg.snapshotId).toBe('snap-1');
+  });
+
+  it('resolves a registered ref to its element', () => {
+    const reg = new RefRegistry('snap-1');
+    const el = document.createElement('button');
+    reg.set('@e1', el);
+
+    expect(reg.has('@e1')).toBe(true);
+    expect(reg.resolve('@e1')).toBe(el);
+    expect(reg.size).toBe(1);
+  });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * Ref registry — maps CST ref ids (`@e4`) back to DOM elements.
+ *
+ * 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.
+ */
+
+import type { CSTRefId } from '../cst/types';
+
+/**
+ * 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.
+ */
+export class RefRegistry {
+  /** Unique id of the snapshot these refs belong to. */
+  readonly snapshotId: string;
+
+  private readonly map = new Map<CSTRefId, WeakRef<HTMLElement>>();
+
+  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));
+  }
+
+  /** Resolve a ref to its element, or null if gone / unknown (stale). */
+  resolve(ref: CSTRefId): HTMLElement | null {
+    return this.map.get(ref)?.deref() ?? null;
+  }
+
+  /** Whether a ref is known to this snapshot (regardless of liveness). */
+  has(ref: CSTRefId): boolean {
+    return this.map.has(ref);
+  }
+
+  /** Number of registered refs. */
+  get size(): number {
+    return this.map.size;
+  }
+}

package/src/lib/page-snapshot/staleness/__tests__/hash.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { serializeCST } from '../../cst/serialize';
+import type { CSTRootNode } from '../../cst/types';
+import { hashSnapshot } from '../hash';
+
+const sampleRoot: CSTRootNode = {
+  type: 'root',
+  title: 'Billing Settings',
+  url: 'https://app.example.com/settings/billing',
+  children: [{ type: 'text', content: 'Configure your subscription.' }],
+};
+
+describe('hashSnapshot', () => {
+  it('is stable for identical input', () => {
+    const s = serializeCST(sampleRoot);
+    expect(hashSnapshot(s)).toBe(hashSnapshot(s));
+  });
+
+  it('changes when the snapshot changes', () => {
+    const a = hashSnapshot(serializeCST(sampleRoot));
+    const mutated: CSTRootNode = { ...sampleRoot, title: 'Other Page' };
+    const b = hashSnapshot(serializeCST(mutated));
+    expect(a).not.toBe(b);
+  });
+
+  it('returns an 8-char hex string', () => {
+    expect(hashSnapshot('anything')).toMatch(/^[0-9a-f]{8}$/);
+  });
+
+  it('handles an empty string', () => {
+    expect(hashSnapshot('')).toMatch(/^[0-9a-f]{8}$/);
+  });
+});

package/src/lib/page-snapshot/staleness/hash.ts

@@ -0,0 +1,20 @@
+/**
+ * Snapshot content hash — staleness detection.
+ *
+ * A fast non-cryptographic hash (FNV-1a, 32-bit). Two captures of an
+ * unchanged page produce the same hash; a changed page produces a
+ * different one. Used to decide whether to send a fresh snapshot.
+ */
+
+/** FNV-1a 32-bit hash of a string, returned as a hex string. */
+export function hashSnapshot(serialized: string): string {
+  // FNV-1a constants (32-bit).
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < serialized.length; i++) {
+    hash ^= serialized.charCodeAt(i);
+    // hash *= 16777619, kept in 32-bit range via Math.imul.
+    hash = Math.imul(hash, 0x01000193);
+  }
+  // Unsigned, hex.
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Token estimation.
+ *
+ * A cheap heuristic — chars / 4.2 — good enough to drive budget
+ * decisions client-side. The backend does the authoritative count.
+ */
+
+/** Average characters per token, empirically ~4.2 for mixed UI text. */
+const CHARS_PER_TOKEN = 4.2;
+
+/** Estimate the token count of a string. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}

package/src/tools/AudioPlayer/context/PlayerProvider.tsx

@@ -89,12 +89,17 @@ export function PlayerProvider(props: PlayerProviderProps) {
   const [source] = useState(() => createAudioSnapshotSource(audio));
   const [levelsStore] = useState<LevelsStore>(() => createLevelsStore());
 
+  const [activePeaks, setActivePeaks] = useState<Float32Array | undefined>(
+    () => peaksProp ?? getPeaksFromCache(src),
+  );
+
   // Seed peaks-from-prop into the module cache so other consumers benefit too.
-  if (peaksProp && getPeaksFromCache(src) === undefined) {
-    setPeaks(src, peaksProp);
-  }
-  const initialPeaks = peaksProp ?? getPeaksFromCache(src);
-  const [activePeaks, setActivePeaks] = useState<Float32Array | undefined>(initialPeaks);
+  // Done in an effect (not render) to keep render pure under StrictMode.
+  useEffect(() => {
+    if (peaksProp && getPeaksFromCache(src) === undefined) {
+      setPeaks(src, peaksProp);
+    }
+  }, [src, peaksProp]);
 
   // Apply src / preload / loop / volume / muted imperatively.
   useEffect(() => {
@@ -147,10 +152,10 @@ export function PlayerProvider(props: PlayerProviderProps) {
     });
   }, [audio, volumeIsControlled, mutedIsControlled]);
 
-  // When src changes, swap in cached peaks if available; clear otherwise.
+  // When src changes, swap in peaks: prop wins, then module cache, else clear.
   useEffect(() => {
-    setActivePeaks(getPeaksFromCache(src));
-  }, [src]);
+    setActivePeaks(peaksProp ?? getPeaksFromCache(src));
+  }, [src, peaksProp]);
 
   // Lifecycle event hooks.
   useEffect(() => {
@@ -306,9 +311,3 @@ export function PlayerProvider(props: PlayerProviderProps) {
     </AudioRefCtx.Provider>
   );
 }
-
-// Internal helper for parts that want to expose peaks-update from the lazy hook.
-export function usePeaksSetter() {
-  // The provider seeds peaks via setPeaks() in the module cache; consumers
-  // re-read on src change. usePeaks hook re-uses the cache directly.
-}

package/src/tools/AudioPlayer/hooks/useAudioElementEvents.ts

@@ -9,6 +9,7 @@ const TRACKED = [
   'play',
   'pause',
   'ended',
+  'loadstart',
   'loadedmetadata',
   'durationchange',
   'emptied',
@@ -17,6 +18,13 @@ const TRACKED = [
   'error',
 ] as const;
 
+// A detached <audio> whose `src` 404s (or points at a dead host) often never
+// fires an `error` event — it stalls in NETWORK_LOADING indefinitely. After
+// this long without metadata/canplay/error we synthesize a network error so
+// the UI can surface it instead of showing a stuck skeleton forever.
+const LOAD_WATCHDOG_MS = 12_000;
+const SYNTHETIC_NETWORK_ERROR = 2;
+
 type Snapshot = {
   paused: boolean;
   ended: boolean;
@@ -25,13 +33,14 @@ type Snapshot = {
   errorCode: number | null;
 };
 
-function readSnapshot(audio: HTMLAudioElement): Snapshot {
+function readSnapshot(audio: HTMLAudioElement, stalled: boolean): Snapshot {
+  const nativeCode = audio.error?.code ?? null;
   return {
     paused: audio.paused,
     ended: audio.ended,
     duration: Number.isFinite(audio.duration) ? audio.duration : 0,
     ready: audio.readyState >= 2,
-    errorCode: audio.error?.code ?? null,
+    errorCode: nativeCode ?? (stalled ? SYNTHETIC_NETWORK_ERROR : null),
   };
 }
 
@@ -46,19 +55,59 @@ function snapshotsEqual(a: Snapshot, b: Snapshot): boolean {
 }
 
 export function createAudioSnapshotSource(audio: HTMLAudioElement) {
-  let cached: Snapshot = readSnapshot(audio);
+  let stalled = false;
+  let cached: Snapshot = readSnapshot(audio, stalled);
   return {
     subscribe(cb: () => void): () => void {
+      let watchdog: ReturnType<typeof setTimeout> | null = null;
+
+      const clearWatchdog = () => {
+        if (watchdog !== null) {
+          clearTimeout(watchdog);
+          watchdog = null;
+        }
+      };
       const refresh = () => {
-        const next = readSnapshot(audio);
+        const next = readSnapshot(audio, stalled);
         if (!snapshotsEqual(cached, next)) {
           cached = next;
           cb();
         }
       };
-      for (const e of TRACKED) audio.addEventListener(e, refresh);
+      const armWatchdog = () => {
+        clearWatchdog();
+        if (audio.readyState >= 2 || audio.error) return;
+        watchdog = setTimeout(() => {
+          watchdog = null;
+          if (audio.readyState < 2 && !audio.error) {
+            stalled = true;
+            refresh();
+          }
+        }, LOAD_WATCHDOG_MS);
+      };
+      const onProgress = (e: Event) => {
+        if (e.type === 'loadstart' || e.type === 'emptied') {
+          // New load cycle — drop any prior stall and restart the watchdog.
+          stalled = false;
+          armWatchdog();
+        } else if (audio.readyState >= 2 || audio.error) {
+          // Real progress (or a native error) clears a pending stall timer.
+          clearWatchdog();
+          if (stalled) stalled = false;
+        }
+        refresh();
+      };
+
+      for (const e of TRACKED) audio.addEventListener(e, onProgress);
+      // Re-sync immediately: events (error, loadedmetadata, …) may have fired
+      // between source creation and this subscription. Without this, a stale
+      // snapshot from construction time would never update — e.g. a `src` that
+      // already errored would stay stuck on `loading`.
+      armWatchdog();
+      refresh();
       return () => {
-        for (const e of TRACKED) audio.removeEventListener(e, refresh);
+        clearWatchdog();
+        for (const e of TRACKED) audio.removeEventListener(e, onProgress);
       };
     },
     getSnapshot(): Snapshot {

package/src/tools/AudioPlayer/lazy.tsx

@@ -3,39 +3,25 @@
 /**
  * `@djangocfg/ui-tools/audio-player` subpath entrypoint.
  *
- * `LazyPlayer` is the only heavy export — it dynamically imports the full
- * `Player` tree (PlayerShell + Layout + Cover + Waveform + Controls + audio
- * decoding helpers). Everything else listed here is light:
- *   - types are erased,
- *   - the Zustand store, context hooks, and selectors carry no UI,
- *   - the slot components (`Cover`, `Title`, `PlayButton`, `Waveform`, …)
- *     are presentational React components that read from PlayerContext —
- *     they only become meaningful inside a `<PlayerProvider>` (which only
- *     exists inside `LazyPlayer` once loaded).
+ * `LazyPlayer` is exported as a direct (synchronous) alias of `Player`. We
+ * intentionally avoid `React.lazy` + `import('./Player')` here: under bundlers
+ * that pre-bundle subpath entries (Vite optimizeDeps in Next.js/Vite/SB), the
+ * dynamic import creates a second chunk that re-instantiates the React
+ * Contexts (AudioRefCtx/ControlsCtx/MetaCtx/StateCtx/LevelsCtx). The slot
+ * components and selector hooks re-exported below would then read from a
+ * different context instance than `<PlayerProvider>` writes to, which made
+ * `usePlayerAudio` throw "must be used inside <PlayerProvider>".
  *
- * Consumers building a fully custom layout: render `<LazyPlayer>` once to
- * get the provider, then arrange slot components inside via render-children
- * pattern, or use the bare `Player` re-exported from the root barrel.
+ * Heavy audio-decoding work (peaks, AudioContext) already happens lazily at
+ * runtime via effects inside `PlayerProvider`/`PlayerShell` — there is no
+ * benefit to splitting the React shell behind a second chunk.
  */
 
-import { createLazyComponent } from '../../components';
-import type { PlayerProps } from './types';
-
 // ============================================================================
-// Lazy heavy component
+// Player component (synchronous; previously lazy — see note above)
 // ============================================================================
 
-export const LazyPlayer = createLazyComponent<PlayerProps>(
-  () => import('./Player').then((mod) => ({ default: mod.Player })),
-  {
-    displayName: 'LazyAudioPlayer',
-    fallback: (
-      <div className="rounded-lg border border-border/60 bg-card px-4 py-6 text-sm text-muted-foreground">
-        Loading audio player…
-      </div>
-    ),
-  },
-);
+export { Player, Player as LazyPlayer } from './Player';
 
 // ============================================================================
 // Light surface — types, store, context, slot components, hooks

package/src/tools/AudioPlayer/parts/Meta/TimeDisplay.tsx

@@ -14,9 +14,7 @@ export function TimeDisplay() {
   useEffect(() => {
     const el = currentRef.current;
     if (!el) return;
-    let raf = 0;
     let last = -1;
-    let timer: ReturnType<typeof setInterval> | null = null;
     const write = () => {
       const t = audio.currentTime;
       if (Math.abs(t - last) < 0.5) return;
@@ -28,14 +26,13 @@ export function TimeDisplay() {
     audio.addEventListener('seeked', onSeek);
     audio.addEventListener('timeupdate', onSeek);
     // Backup poll when timeupdate is throttled (e.g. background tab → visible).
-    timer = setInterval(() => {
+    const timer = setInterval(() => {
       if (!audio.paused) write();
     }, READ_INTERVAL_MS);
     return () => {
-      cancelAnimationFrame(raf);
       audio.removeEventListener('seeked', onSeek);
       audio.removeEventListener('timeupdate', onSeek);
-      if (timer) clearInterval(timer);
+      clearInterval(timer);
     };
   }, [audio]);