@djangocfg/debuger 2.1.219

package/src/DebugPanel.tsx

@@ -0,0 +1,171 @@
+'use client';
+
+import React, { useMemo, useState, useEffect } from 'react';
+import { installMonitorBridge } from './bridges';
+import {
+  Button,
+  Badge,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useDebugErrorCount } from './logger';
+import {
+  X, Bug, Minimize2, Maximize2,
+  ScrollText, Radio,
+} from 'lucide-react';
+import { useDebugStore } from './store/debugStore';
+import type { DebugTab } from './store/debugStore';
+import { LogsPanel } from './panels/LogsPanel';
+import { AudioDebugPanel } from './panels/AudioDebugPanel';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CustomDebugTab {
+  /** Unique id — will be added to DebugTab union at runtime */
+  id: string;
+  label: string;
+  icon: React.ElementType;
+  panel: React.ComponentType<{ isActive: boolean }>;
+}
+
+export interface DebugPanelProps {
+  /** Additional app-specific tabs */
+  tabs?: CustomDebugTab[];
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  defaultHeight?: number;
+  defaultWidth?: number;
+}
+
+// ============================================================================
+// Built-in tabs
+// ============================================================================
+
+const BUILTIN_TABS = [
+  { id: 'logs',  label: 'Logs',  icon: ScrollText },
+  { id: 'audio', label: 'Audio', icon: Radio },
+] as const;
+
+const POSITION_CLASSES: Record<NonNullable<DebugPanelProps['position']>, string> = {
+  'bottom-right': 'bottom-4 right-4',
+  'bottom-left':  'bottom-4 left-4',
+  'top-right':    'top-4 right-4',
+  'top-left':     'top-4 left-4',
+};
+
+// ============================================================================
+// Component
+// ============================================================================
+
+export function DebugPanel({
+  tabs: customTabs = [],
+  position = 'bottom-left',
+  defaultHeight = 480,
+  defaultWidth = 560,
+}: DebugPanelProps) {
+  const isOpen = useDebugStore((s) => s.isOpen);
+  const activeTab = useDebugStore((s) => s.tab);
+  const setTab = useDebugStore((s) => s.setTab);
+  const close = useDebugStore((s) => s.close);
+  const errorCount = useDebugErrorCount();
+
+  const [isMinimized, setIsMinimized] = useState(false);
+
+  useEffect(() => {
+    const unsub = installMonitorBridge();
+    return () => unsub?.();
+  }, []);
+
+  const allTabs = useMemo(() => [
+    ...BUILTIN_TABS,
+    ...customTabs.map((t) => ({ id: t.id, label: t.label, icon: t.icon })),
+  ], [customTabs]);
+
+  const panelHeight = isMinimized ? 48 : defaultHeight;
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      className={cn(
+        'fixed z-[100] flex flex-col overflow-hidden rounded-lg border border-border bg-background shadow-xl',
+        POSITION_CLASSES[position]
+      )}
+      style={{ width: defaultWidth, height: panelHeight }}
+    >
+      {/* Header */}
+      <div className="flex items-center gap-2 border-b border-border bg-muted/50 px-3 py-2 shrink-0">
+        <Bug className="h-4 w-4 text-primary" />
+        <span className="text-sm font-medium">Debug</span>
+
+        {errorCount > 0 && (
+          <Badge variant="destructive" className="ml-1 text-[10px]">{errorCount} errors</Badge>
+        )}
+
+        {/* Tab bar */}
+        {!isMinimized && (
+          <div className="flex items-center gap-0.5 ml-3">
+            {allTabs.map((tab) => {
+              const Icon = tab.icon;
+              const isActive = activeTab === tab.id;
+              return (
+                <button
+                  key={tab.id}
+                  type="button"
+                  onClick={() => setTab(tab.id as DebugTab)}
+                  className={cn(
+                    'flex items-center gap-1.5 px-2 py-0.5 rounded text-xs transition-colors',
+                    isActive
+                      ? 'bg-background text-foreground shadow-sm'
+                      : 'text-muted-foreground hover:text-foreground hover:bg-muted'
+                  )}
+                >
+                  <Icon className="h-3 w-3" />
+                  {tab.label}
+                </button>
+              );
+            })}
+          </div>
+        )}
+
+        <div className="flex items-center gap-1 ml-auto">
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => setIsMinimized((v) => !v)}>
+                {isMinimized ? <Maximize2 className="h-3.5 w-3.5" /> : <Minimize2 className="h-3.5 w-3.5" />}
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{isMinimized ? 'Expand' : 'Minimize'}</TooltipContent>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon" className="h-6 w-6" onClick={close}>
+                <X className="h-3.5 w-3.5" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Close</TooltipContent>
+          </Tooltip>
+        </div>
+      </div>
+
+      {/* Panel content */}
+      {!isMinimized && (
+        <div className="flex-1 overflow-hidden">
+          {activeTab === 'logs' && <LogsPanel isActive={activeTab === 'logs'} />}
+          {activeTab === 'audio' && <AudioDebugPanel isActive={activeTab === 'audio'} />}
+          {customTabs.map((tab) => {
+            const Panel = tab.panel;
+            return (
+              <div key={tab.id} className={cn('h-full', activeTab !== tab.id && 'hidden')}>
+                <Panel isActive={activeTab === tab.id} />
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/bridges/index.ts

@@ -0,0 +1 @@
+export { installMonitorBridge } from './monitorBridge';

package/src/bridges/monitorBridge.ts

@@ -0,0 +1,63 @@
+'use client';
+
+/**
+ * monitorBridge — subscribes to @djangocfg/monitor store and forwards
+ * captured events into debugger's logStore.
+ *
+ * Call once at app startup (e.g. inside DebugPanel or a provider).
+ * Safe to call multiple times — only installs one subscription.
+ *
+ * @example
+ * import { installMonitorBridge } from '@djangocfg/debuger/bridges'
+ * installMonitorBridge()
+ */
+
+import { monitorStore } from '@djangocfg/monitor/client';
+import { useDebugLogStore } from '../logger/logStore';
+import type { LogLevel } from '../logger/types';
+
+let _installed = false;
+
+export function installMonitorBridge(): (() => void) | undefined {
+  if (typeof window === 'undefined') return;
+  if (_installed) return;
+
+  let prevLen = monitorStore.getState().buffer.length;
+
+  const unsub = monitorStore.subscribe((state) => {
+    const buffer = state.buffer;
+    if (buffer.length <= prevLen) { prevLen = buffer.length; return; }
+    const newEvents = buffer.slice(prevLen);
+    prevLen = buffer.length;
+
+    for (const event of newEvents) {
+      const level: LogLevel =
+        event.level === 'error' ? 'error'
+        : event.level === 'warn' ? 'warn'
+        : 'info';
+
+      useDebugLogStore.getState().addLog({
+        level,
+        component: `monitor:${event.event_type ?? 'event'}`,
+        message: event.message ?? '',
+        data: {
+          ...(event.url && { url: event.url }),
+          ...(event.session_id && { session_id: event.session_id }),
+          ...(event.http_status !== undefined && {
+            http_status: event.http_status,
+            http_method: event.http_method,
+            http_url: event.http_url,
+          }),
+          ...(event.extra ? { extra: event.extra } : {}),
+        },
+        stack: event.stack_trace,
+      });
+    }
+  });
+
+  _installed = true;
+  return () => {
+    unsub();
+    _installed = false;
+  };
+}

package/src/emitters/Emitter.ts

@@ -0,0 +1,51 @@
+/**
+ * Generic typed event emitter
+ *
+ * Zero-cost: emit() is a no-op when no listeners are registered for an event.
+ * SSR-safe: no browser APIs used.
+ * No dependencies.
+ *
+ * Usage:
+ *   type MyEvents = { 'user:login': { id: string }; 'page:view': { path: string } };
+ *   export const myEmitter = new Emitter<MyEvents>();
+ *   myEmitter.on('user:login', ({ id }) => console.log(id));
+ *   myEmitter.emit('user:login', { id: '123' });
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type EventMap = Record<string, any>;
+
+export class Emitter<TEvents extends EventMap> {
+  private listeners = new Map<keyof TEvents, Set<(data: unknown) => void>>();
+
+  /**
+   * Emit an event. No-op if no listeners are registered.
+   */
+  emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void {
+    const handlers = this.listeners.get(event);
+    if (!handlers || handlers.size === 0) return;
+    handlers.forEach((h) => h(data));
+  }
+
+  /**
+   * Subscribe to an event. Returns an unsubscribe function.
+   */
+  on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.listeners.get(event)!.add(handler as any);
+    return () => this.listeners.get(event)?.delete(handler as any);
+  }
+
+  /** True when at least one listener is registered for this event (hot-path guard) */
+  hasListeners<K extends keyof TEvents>(event: K): boolean {
+    return (this.listeners.get(event)?.size ?? 0) > 0;
+  }
+
+  /** Remove all listeners (useful for testing / cleanup) */
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/emitters/audioEmitter.ts

@@ -0,0 +1,74 @@
+/**
+ * Audio/Media Engine Event Emitter
+ *
+ * Universal zero-cost pub/sub for audio/media player debug events.
+ * No React dependency — pure TypeScript module.
+ *
+ * Wire into your audio engine:
+ *   import { emitAudioEvent } from '@org/debuger/emitters';
+ *   emitAudioEvent({ kind: 'play', trackId: 'abc', ts: Date.now(), msg: 'started' });
+ */
+
+import { Emitter } from './Emitter';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type AudioEventKind =
+  | 'play'
+  | 'pause'
+  | 'seek'
+  | 'ended'
+  | 'sync'    // periodic sync tick (RAF loop)
+  | 'load'
+  | 'error'
+  | 'engine'  // engine lifecycle: start/stop/create/destroy
+  | 'custom';
+
+export interface AudioDebugEvent {
+  kind: AudioEventKind;
+  ts: number;
+  /** Track/player ID (short prefix) */
+  trackId?: string;
+  msg: string;
+  /** Arbitrary metadata: positions, drift, etc. */
+  data?: Record<string, unknown>;
+}
+
+type AudioEvents = { event: AudioDebugEvent };
+
+// ============================================================================
+// Singleton emitter + ring-buffer
+// ============================================================================
+
+const _emitter = new Emitter<AudioEvents>();
+
+/** Ring-buffer of recent events — replayed to new subscribers */
+const BUFFER_SIZE = 200;
+const _buffer: AudioDebugEvent[] = [];
+
+/** Emit an audio debug event. Zero-cost when no panel is open. */
+export const emitAudioEvent = (event: AudioDebugEvent): void => {
+  // Always buffer (capped) so late subscribers get recent history
+  if (_buffer.length >= BUFFER_SIZE) _buffer.shift();
+  _buffer.push(event);
+  _emitter.emit('event', event);
+};
+
+/**
+ * Subscribe to audio debug events.
+ * Immediately replays buffered events to the new subscriber,
+ * then delivers live events. Returns unsubscribe function.
+ */
+export const subscribeAudioEvents = (fn: (e: AudioDebugEvent) => void): (() => void) => {
+  // Replay history so the panel sees events that happened before it opened
+  for (const e of _buffer) fn(e);
+  return _emitter.on('event', fn);
+};
+
+/** Clear the ring-buffer (called from the panel's Clear button) */
+export const clearAudioEventBuffer = (): void => { _buffer.length = 0; };
+
+/** True when at least one listener is active (use as hot-path guard) */
+export const hasAudioListeners = (): boolean => _emitter.hasListeners('event');

package/src/emitters/customEmitter.ts

@@ -0,0 +1,42 @@
+/**
+ * Custom Debug Event Emitter
+ *
+ * Generic channel for consuming apps to send arbitrary debug events
+ * without coupling to any specific domain.
+ *
+ *   import { emitDebugEvent } from '@org/debuger/emitters';
+ *   emitDebugEvent({ channel: 'pipeline', kind: 'slot:updated', ts: Date.now(), msg: '...' });
+ */
+
+import { Emitter } from './Emitter';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CustomDebugEvent {
+  /** Logical grouping — matches registered custom tab id */
+  channel: string;
+  kind: string;
+  ts: number;
+  msg: string;
+  data?: Record<string, unknown>;
+}
+
+type CustomEvents = { event: CustomDebugEvent };
+
+// ============================================================================
+// Singleton emitter
+// ============================================================================
+
+const _emitter = new Emitter<CustomEvents>();
+
+/** Emit a custom debug event. Zero-cost when no panel is open. */
+export const emitDebugEvent = (event: CustomDebugEvent): void =>
+  _emitter.emit('event', event);
+
+/** Subscribe to custom debug events. Returns unsubscribe function. */
+export const subscribeCustomEvents = (fn: (e: CustomDebugEvent) => void): (() => void) =>
+  _emitter.on('event', fn);
+
+export const hasCustomListeners = (): boolean => _emitter.hasListeners('event');

package/src/emitters/index.ts

@@ -0,0 +1,10 @@
+// Generic typed emitter class
+export { Emitter } from './Emitter';
+
+// Audio / media engine events
+export { subscribeAudioEvents, emitAudioEvent, hasAudioListeners, clearAudioEventBuffer } from './audioEmitter';
+export type { AudioDebugEvent, AudioEventKind } from './audioEmitter';
+
+// Generic custom channel events
+export { subscribeCustomEvents, emitDebugEvent, hasCustomListeners } from './customEmitter';
+export type { CustomDebugEvent } from './customEmitter';

package/src/hooks/useAudioEventLog.ts

@@ -0,0 +1,147 @@
+'use client';
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { subscribeAudioEvents, clearAudioEventBuffer } from '../emitters/audioEmitter';
+import type { AudioDebugEvent, AudioEventKind } from '../emitters/audioEmitter';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AudioLogEntry extends AudioDebugEvent {
+  /** Local unique key for React rendering */
+  id: string;
+}
+
+export interface UseAudioEventLogResult {
+  events: AudioLogEntry[];
+  clear: () => void;
+  /** Seek events per second (rolling 5s window) */
+  seekRate: number;
+  /** Average interval between 'sync' ticks in ms (e.g. RAF loop cadence) */
+  syncIntervalMs: number | null;
+  /** Running count per event kind */
+  kindCounts: Partial<Record<AudioEventKind, number>>;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MAX_EVENTS = 200;
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Subscribes to audio debug events and maintains a ring-buffer log.
+ *
+ * RAF batching: incoming events are queued in a ref and flushed into React
+ * state once per animation frame — prevents render storms at 60fps.
+ *
+ * Only subscribes while `active` is true (panel tab is visible).
+ */
+export function useAudioEventLog(active: boolean): UseAudioEventLogResult {
+  const [events, setEvents] = useState<AudioLogEntry[]>([]);
+  const [syncIntervalMs, setSyncIntervalMs] = useState<number | null>(null);
+  const [kindCounts, setKindCounts] = useState<Partial<Record<AudioEventKind, number>>>({});
+  const [seekRate, setSeekRate] = useState(0);
+
+  // Refs — mutated in the emitter callback without triggering renders
+  const queueRef = useRef<AudioLogEntry[]>([]);
+  const counterRef = useRef(0);
+  const lastSyncTs = useRef<number | null>(null);
+  const seekTimestamps = useRef<number[]>([]);
+  const kindCountsRef = useRef<Partial<Record<AudioEventKind, number>>>({});
+
+  const clear = useCallback(() => {
+    clearAudioEventBuffer();
+    queueRef.current = [];
+    counterRef.current = 0;
+    kindCountsRef.current = {};
+    seekTimestamps.current = [];
+    lastSyncTs.current = null;
+    setEvents([]);
+    setSyncIntervalMs(null);
+    setKindCounts({});
+    setSeekRate(0);
+  }, []);
+
+  // Subscribe — enqueue events without touching React state
+  useEffect(() => {
+    if (!active) return;
+
+    const unsubscribe = subscribeAudioEvents((event) => {
+      const entry: AudioLogEntry = { ...event, id: String(++counterRef.current) };
+      queueRef.current.push(entry);
+
+      // Track sync interval (no setState — RAF will pick it up)
+      if (event.kind === 'sync') {
+        if (lastSyncTs.current !== null) {
+          const interval = event.ts - lastSyncTs.current;
+          // Store on ref; RAF flush will call setSyncIntervalMs
+          (entry as AudioLogEntry & { _interval?: number })._interval = interval;
+        }
+        lastSyncTs.current = event.ts;
+      }
+
+      // Track seeks
+      if (event.kind === 'seek') {
+        seekTimestamps.current.push(event.ts);
+      }
+
+      // Accumulate kind counts on ref
+      kindCountsRef.current = {
+        ...kindCountsRef.current,
+        [event.kind]: (kindCountsRef.current[event.kind] ?? 0) + 1,
+      };
+    });
+
+    return unsubscribe;
+  }, [active]);
+
+  // RAF flush loop — drains queue into React state once per frame
+  useEffect(() => {
+    if (!active) return;
+    let rafId: number;
+
+    const flush = () => {
+      if (queueRef.current.length > 0) {
+        const incoming = queueRef.current.splice(0);
+
+        // Extract sync interval from last sync event in batch
+        const lastSync = [...incoming].reverse().find((e) => e.kind === 'sync') as
+          | (AudioLogEntry & { _interval?: number })
+          | undefined;
+        if (lastSync?._interval !== undefined) {
+          setSyncIntervalMs(lastSync._interval);
+        }
+
+        setEvents((prev) => {
+          const next = [...prev, ...incoming];
+          return next.length > MAX_EVENTS ? next.slice(-MAX_EVENTS) : next;
+        });
+
+        setKindCounts({ ...kindCountsRef.current });
+      }
+      rafId = requestAnimationFrame(flush);
+    };
+
+    rafId = requestAnimationFrame(flush);
+    return () => cancelAnimationFrame(rafId);
+  }, [active]);
+
+  // Rolling seek rate — recompute every second
+  useEffect(() => {
+    if (!active) return;
+    const id = setInterval(() => {
+      const now = Date.now();
+      seekTimestamps.current = seekTimestamps.current.filter((t) => now - t < 5000);
+      setSeekRate(Math.round((seekTimestamps.current.length / 5) * 10) / 10);
+    }, 1000);
+    return () => clearInterval(id);
+  }, [active]);
+
+  return { events, clear, seekRate, syncIntervalMs, kindCounts };
+}

package/src/hooks/useCustomEventLog.ts

@@ -0,0 +1,39 @@
+'use client';
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { subscribeCustomEvents } from '../emitters/customEmitter';
+import type { CustomDebugEvent } from '../emitters/customEmitter';
+
+export interface CustomLogEntry extends CustomDebugEvent {
+  id: string;
+}
+
+const MAX_EVENTS = 300;
+
+/**
+ * Subscribes to custom channel events and maintains a ring-buffer per channel.
+ * Pass `channel` to filter — or undefined to receive all channels.
+ */
+export function useCustomEventLog(active: boolean, channel?: string) {
+  const [events, setEvents] = useState<CustomLogEntry[]>([]);
+  const counterRef = useRef(0);
+
+  const clear = useCallback(() => setEvents([]), []);
+
+  useEffect(() => {
+    if (!active) return;
+
+    const unsubscribe = subscribeCustomEvents((event) => {
+      if (channel && event.channel !== channel) return;
+      const entry: CustomLogEntry = { ...event, id: String(++counterRef.current) };
+      setEvents((prev) => {
+        const next = [...prev, entry];
+        return next.length > MAX_EVENTS ? next.slice(-MAX_EVENTS) : next;
+      });
+    });
+
+    return unsubscribe;
+  }, [active, channel]);
+
+  return { events, clear };
+}

package/src/hooks/useDebugShortcut.ts

@@ -0,0 +1,27 @@
+'use client';
+
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+import { useDebugStore } from '../store/debugStore';
+
+/**
+ * Registers a global keyboard shortcut to toggle the debug panel.
+ * Default: Cmd+D (meta+d) on Mac / Win+D on Windows.
+ *
+ * Guards:
+ * - In production: only fires if `isUnlocked === true`
+ */
+export function useDebugShortcut(): void {
+  const toggle = useDebugStore((s) => s.toggle);
+  const isUnlocked = useDebugStore((s) => s.isUnlocked);
+  const isDev = typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+
+  useHotkey(
+    'meta+d',
+    (e) => {
+      e.preventDefault();
+      if (!isDev && !isUnlocked) return;
+      toggle();
+    },
+    { preventDefault: true },
+  );
+}