@djangocfg/debuger 2.1.219

package/src/hooks/useStoreSnapshot.ts

@@ -0,0 +1,70 @@
+'use client';
+
+import { useState, useEffect, useRef } from 'react';
+
+// ============================================================================
+// Shallow equal (avoids unnecessary re-renders)
+// ============================================================================
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object') return false;
+  if (a === null || b === null) return false;
+  const keysA = Object.keys(a as object);
+  const keysB = Object.keys(b as object);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if ((a as Record<string, unknown>)[key] !== (b as Record<string, unknown>)[key]) return false;
+  }
+  return true;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Polling-based external Zustand store snapshot.
+ *
+ * Reads the store state via `getState()` on an interval — NOT via reactive
+ * subscription. This prevents debug panel renders from being triggered by
+ * high-frequency store updates and avoids Zustand v5 infinite loop issues
+ * (returning new object references from selectors without useShallow).
+ *
+ * Only polls while `active` is true (panel tab is visible).
+ *
+ * @param getState  A stable function that returns the current store state slice.
+ *                  Use `() => useMyStore.getState()` — the hook ref-stabilizes it.
+ * @param intervalMs  Poll interval in ms. Default 200ms.
+ * @param active  Whether to poll. Pass `isActive` from panel props.
+ *
+ * @example
+ * const snap = useStoreSnapshot(
+ *   () => useTimelineStore.getState(),
+ *   200,
+ *   isActive
+ * );
+ */
+export function useStoreSnapshot<T>(
+  getState: () => T,
+  intervalMs = 200,
+  active = true,
+): T {
+  const getStateRef = useRef(getState);
+  getStateRef.current = getState;
+
+  const [snapshot, setSnapshot] = useState<T>(() => getState());
+
+  useEffect(() => {
+    if (!active) return;
+
+    const id = setInterval(() => {
+      const next = getStateRef.current();
+      setSnapshot((prev) => (shallowEqual(prev, next) ? prev : next));
+    }, intervalMs);
+
+    return () => clearInterval(id);
+  }, [active, intervalMs]);
+
+  return snapshot;
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// ============================================================================
+// Components
+// ============================================================================
+
+export { DebugButton } from './DebugButton';
+export type { DebugButtonProps } from './DebugButton';
+
+export { DebugPanel } from './DebugPanel';
+export type { DebugPanelProps, CustomDebugTab } from './DebugPanel';
+
+// ============================================================================
+// Built-in panels
+// ============================================================================
+
+export { LogsPanel } from './panels/LogsPanel';
+export { AudioDebugPanel } from './panels/AudioDebugPanel';
+export { StorePanel } from './panels/StorePanel';
+export type { StorePanelProps } from './panels/StorePanel';
+
+// ============================================================================
+// Store
+// ============================================================================
+
+export { useDebugStore } from './store/debugStore';
+export type { DebugTab, DebugStore } from './store/debugStore';
+
+// ============================================================================
+// Logger (own, no ui-core dependency)
+// ============================================================================
+
+export { createDebugLogger, debugLog, useDebugLogStore, useDebugFilteredLogs, useDebugLogCount, useDebugErrorCount } from './logger';
+export type { LogEntry, LogLevel, LogFilter, Logger } from './logger';
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+export { useDebugShortcut } from './hooks/useDebugShortcut';
+
+export { useAudioEventLog } from './hooks/useAudioEventLog';
+export type { AudioLogEntry, UseAudioEventLogResult } from './hooks/useAudioEventLog';
+
+export { useCustomEventLog } from './hooks/useCustomEventLog';
+export type { CustomLogEntry } from './hooks/useCustomEventLog';
+
+export { useStoreSnapshot } from './hooks/useStoreSnapshot';
+
+// ============================================================================
+// Bridges (optional integrations with other packages)
+// ============================================================================
+
+export { installMonitorBridge } from './bridges';
+
+// ============================================================================
+// Emitters (also available from '@djangocfg/debuger/emitters')
+// ============================================================================
+
+export { subscribeAudioEvents, emitAudioEvent, hasAudioListeners, clearAudioEventBuffer } from './emitters/audioEmitter';
+export type { AudioDebugEvent, AudioEventKind } from './emitters/audioEmitter';
+
+export { subscribeCustomEvents, emitDebugEvent, hasCustomListeners } from './emitters/customEmitter';
+export type { CustomDebugEvent } from './emitters/customEmitter';

package/src/logger/index.ts

@@ -0,0 +1,3 @@
+export { createDebugLogger, debugLog } from './logger';
+export { useDebugLogStore, useDebugFilteredLogs, useDebugLogCount, useDebugErrorCount } from './logStore';
+export type { LogEntry, LogLevel, LogFilter, LogStore, Logger } from './types';

package/src/logger/logStore.ts

@@ -0,0 +1,89 @@
+'use client';
+
+import { create } from 'zustand';
+import type { LogStore, LogEntry, LogFilter } from './types';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MAX_LOGS = 1000;
+
+const DEFAULT_FILTER: LogFilter = {
+  levels: ['debug', 'info', 'warn', 'error', 'success'],
+};
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+let _counter = 0;
+
+function generateId(): string {
+  return `log-${Date.now()}-${++_counter}`;
+}
+
+function matchesFilter(entry: LogEntry, filter: LogFilter): boolean {
+  if (!filter.levels.includes(entry.level)) return false;
+
+  if (filter.component) {
+    if (!entry.component.toLowerCase().includes(filter.component.toLowerCase())) return false;
+  }
+
+  if (filter.search) {
+    const s = filter.search.toLowerCase();
+    const inMsg = entry.message.toLowerCase().includes(s);
+    const inData = entry.data ? JSON.stringify(entry.data).toLowerCase().includes(s) : false;
+    if (!inMsg && !inData) return false;
+  }
+
+  return true;
+}
+
+// ============================================================================
+// Store
+// ============================================================================
+
+export const useDebugLogStore = create<LogStore>((set, get) => ({
+  logs: [],
+  filter: DEFAULT_FILTER,
+
+  addLog: (entry) => {
+    const newEntry: LogEntry = {
+      ...entry,
+      id: generateId(),
+      timestamp: new Date(),
+    };
+    set((state) => {
+      const next = [...state.logs, newEntry];
+      return { logs: next.length > MAX_LOGS ? next.slice(-MAX_LOGS) : next };
+    });
+  },
+
+  clearLogs: () => set({ logs: [] }),
+
+  setFilter: (filter) =>
+    set((state) => ({ filter: { ...state.filter, ...filter } })),
+
+  getFilteredLogs: () => {
+    const { logs, filter } = get();
+    return logs.filter((e) => matchesFilter(e, filter));
+  },
+
+  exportLogs: () => JSON.stringify(get().logs, null, 2),
+}));
+
+// ============================================================================
+// Selector hooks
+// ============================================================================
+
+export const useDebugFilteredLogs = () => {
+  const logs = useDebugLogStore((s) => s.logs);
+  const filter = useDebugLogStore((s) => s.filter);
+  return logs.filter((e) => matchesFilter(e, filter));
+};
+
+export const useDebugLogCount = () => useDebugLogStore((s) => s.logs.length);
+
+export const useDebugErrorCount = () =>
+  useDebugLogStore((s) => s.logs.filter((l) => l.level === 'error').length);

package/src/logger/logger.ts

@@ -0,0 +1,95 @@
+/**
+ * Debug Logger
+ *
+ * Standalone logger for @djangocfg/debuger — no ui-core dependency.
+ * Writes to useDebugLogStore (shown in LogsPanel) and to console in dev.
+ */
+
+import { useDebugLogStore } from './logStore';
+import type { Logger, LogLevel } from './types';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const isDev = process.env.NODE_ENV !== 'production';
+const isBrowser = typeof window !== 'undefined';
+
+function extractStack(data?: Record<string, unknown>): {
+  cleanData: Record<string, unknown> | undefined;
+  stack: string | undefined;
+} {
+  if (!data) return { cleanData: undefined, stack: undefined };
+
+  const cleanData = { ...data };
+  let stack: string | undefined;
+
+  if (data.error instanceof Error) {
+    stack = data.error.stack;
+    cleanData.error = { name: data.error.name, message: data.error.message };
+  } else if (typeof data.error === 'object' && data.error !== null) {
+    const e = data.error as Record<string, unknown>;
+    if (typeof e.stack === 'string') stack = e.stack;
+    if (typeof e.message === 'string') cleanData.error = e.message;
+  }
+
+  return { cleanData, stack };
+}
+
+// ============================================================================
+// createLogger
+// ============================================================================
+
+export function createDebugLogger(component: string): Logger {
+  const write = (level: LogLevel, message: string, data?: Record<string, unknown>) => {
+    const { cleanData, stack } = extractStack(data);
+
+    if (isBrowser) {
+      useDebugLogStore.getState().addLog({ level, component, message, data: cleanData, stack });
+    }
+
+    if (isDev) {
+      const method = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log';
+      const prefix = `[${component}]`;
+      if (cleanData) {
+        console[method](prefix, message, cleanData);
+      } else {
+        console[method](prefix, message);
+      }
+    }
+  };
+
+  return {
+    debug:   (msg, data) => write('debug',   msg, data),
+    info:    (msg, data) => write('info',    msg, data),
+    warn:    (msg, data) => write('warn',    msg, data),
+    error:   (msg, data) => write('error',   msg, data),
+    success: (msg, data) => write('success', msg, data),
+  };
+}
+
+// ============================================================================
+// debugLog — one-shot helper (creates logger on each call, for non-hot paths)
+// ============================================================================
+
+export function debugLog(
+  component: string,
+  level: LogLevel,
+  message: string,
+  data?: Record<string, unknown>,
+): void {
+  const { cleanData, stack } = extractStack(data);
+
+  if (isBrowser) {
+    useDebugLogStore.getState().addLog({ level, component, message, data: cleanData, stack });
+  }
+
+  if (isDev) {
+    const method = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log';
+    if (cleanData) {
+      console[method](`[${component}]`, message, cleanData);
+    } else {
+      console[method](`[${component}]`, message);
+    }
+  }
+}

package/src/logger/types.ts

@@ -0,0 +1,39 @@
+// ============================================================================
+// Types
+// ============================================================================
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'success';
+
+export interface LogEntry {
+  id: string;
+  timestamp: Date;
+  level: LogLevel;
+  component: string;
+  message: string;
+  data?: Record<string, unknown>;
+  stack?: string;
+}
+
+export interface LogFilter {
+  levels: LogLevel[];
+  component?: string;
+  search?: string;
+}
+
+export interface LogStore {
+  logs: LogEntry[];
+  filter: LogFilter;
+  addLog: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
+  clearLogs: () => void;
+  setFilter: (filter: Partial<LogFilter>) => void;
+  getFilteredLogs: () => LogEntry[];
+  exportLogs: () => string;
+}
+
+export interface Logger {
+  debug: (message: string, data?: Record<string, unknown>) => void;
+  info: (message: string, data?: Record<string, unknown>) => void;
+  warn: (message: string, data?: Record<string, unknown>) => void;
+  error: (message: string, data?: Record<string, unknown>) => void;
+  success: (message: string, data?: Record<string, unknown>) => void;
+}

package/src/panels/AudioDebugPanel.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import React, { useCallback, useState } from 'react';
+import {
+  Button,
+  Badge,
+  ScrollArea,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { Trash2, Radio } from 'lucide-react';
+import { useAudioEventLog } from '../hooks/useAudioEventLog';
+import type { AudioEventKind } from '../emitters/audioEmitter';
+
+// ============================================================================
+// Types / constants
+// ============================================================================
+
+type DebugAudioMode = 'off' | 'on' | 'verbose';
+
+const DEBUG_MODES: DebugAudioMode[] = ['off', 'on', 'verbose'];
+
+const KIND_STYLES: Record<AudioEventKind, { label: string; className: string }> = {
+  play:   { label: 'play',   className: 'text-green-400' },
+  pause:  { label: 'pause',  className: 'text-yellow-400' },
+  seek:   { label: 'seek',   className: 'text-blue-400' },
+  ended:  { label: 'ended',  className: 'text-muted-foreground' },
+  sync:   { label: 'sync',   className: 'text-muted-foreground/50' },
+  load:   { label: 'load',   className: 'text-purple-400' },
+  error:  { label: 'error',  className: 'text-red-400' },
+  engine: { label: 'eng',    className: 'text-cyan-400' },
+  custom: { label: 'custom', className: 'text-orange-400' },
+};
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function getDebugAudioMode(): DebugAudioMode {
+  try {
+    const v = localStorage.getItem('DEBUG_AUDIO');
+    if (v === 'verbose') return 'verbose';
+    if (v) return 'on';
+  } catch { /* ssr */ }
+  return 'off';
+}
+
+function formatTs(ts: number): string {
+  const d = new Date(ts);
+  return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}.${String(d.getMilliseconds()).padStart(3, '0')}`;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+interface AudioDebugPanelProps {
+  isActive: boolean;
+}
+
+export function AudioDebugPanel({ isActive }: AudioDebugPanelProps) {
+  const { events, clear, seekRate, syncIntervalMs, kindCounts } = useAudioEventLog(isActive);
+  const [debugMode, setDebugMode] = useState<DebugAudioMode>(getDebugAudioMode);
+
+  const handleSetDebugAudio = useCallback((mode: DebugAudioMode) => {
+    if (mode === 'off') {
+      localStorage.removeItem('DEBUG_AUDIO');
+    } else {
+      localStorage.setItem('DEBUG_AUDIO', mode === 'verbose' ? 'verbose' : '1');
+    }
+    setDebugMode(mode);
+  }, []);
+
+  const kindEntries = Object.entries(kindCounts) as [AudioEventKind, number][];
+  const activeKinds = kindEntries.filter(([, count]) => count > 0);
+  const reversedEvents = [...events].reverse();
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Metrics bar */}
+      <div className="flex flex-wrap items-center gap-2 border-b border-border px-3 py-2 text-xs">
+        <span className="text-muted-foreground">
+          Sync interval:{' '}
+          <span className="text-foreground font-mono">
+            {syncIntervalMs !== null ? `${syncIntervalMs.toFixed(1)}ms` : '—'}
+          </span>
+        </span>
+        <span className="text-muted-foreground">
+          Seeks/s: <span className="text-foreground font-mono">{seekRate}</span>
+        </span>
+        <span className="text-muted-foreground">
+          Total: <span className="text-foreground font-mono">{events.length}</span>
+        </span>
+
+        <div className="flex gap-1 flex-wrap ml-auto">
+          {activeKinds.map(([kind, count]) => (
+            <Badge key={kind} variant="outline" className={cn('text-[10px] px-1 py-0', KIND_STYLES[kind]?.className)}>
+              {KIND_STYLES[kind]?.label ?? kind} {count}
+            </Badge>
+          ))}
+        </div>
+
+        <Button variant="ghost" size="icon" className="h-6 w-6 ml-1" onClick={clear}>
+          <Trash2 className="h-3.5 w-3.5" />
+        </Button>
+      </div>
+
+      {/* DEBUG_AUDIO toggles */}
+      <div className="flex items-center gap-1.5 border-b border-border px-3 py-1.5">
+        <span className="text-[10px] text-muted-foreground mr-1">DEBUG_AUDIO:</span>
+        {DEBUG_MODES.map((mode) => (
+          <button
+            key={mode}
+            type="button"
+            className={cn(
+              'text-[10px] px-2 py-0.5 rounded border transition-colors',
+              debugMode === mode
+                ? 'border-primary bg-primary/10 text-primary'
+                : 'border-border hover:bg-muted text-muted-foreground'
+            )}
+            onClick={() => handleSetDebugAudio(mode)}
+          >
+            {mode}
+          </button>
+        ))}
+      </div>
+
+      {/* Event log */}
+      <ScrollArea className="flex-1">
+        {reversedEvents.length === 0 ? (
+          <div className="flex flex-col items-center justify-center py-10 text-muted-foreground">
+            <Radio className="h-8 w-8 mb-2 opacity-40" />
+            <p className="text-sm">No audio events yet</p>
+            <p className="text-xs mt-1">
+              Wire <code className="text-xs">emitAudioEvent()</code> into your audio engine
+            </p>
+          </div>
+        ) : (
+          <div className="divide-y divide-border/30">
+            {reversedEvents.map((entry) => {
+              const style = KIND_STYLES[entry.kind] ?? { label: entry.kind, className: 'text-foreground' };
+              return (
+                <div key={entry.id} className="flex items-start gap-2 px-3 py-1 text-xs">
+                  <span className="font-mono text-muted-foreground shrink-0 w-[88px]">{formatTs(entry.ts)}</span>
+                  <span className={cn('shrink-0 w-12 font-medium', style.className)}>{style.label}</span>
+                  {entry.trackId && (
+                    <span className="shrink-0 font-mono text-muted-foreground">{entry.trackId.slice(0, 6)}</span>
+                  )}
+                  <span className="truncate text-foreground/80">{entry.msg}</span>
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </ScrollArea>
+    </div>
+  );
+}