@djangocfg/debuger 2.1.219

package/src/panels/LogsPanel.tsx

@@ -0,0 +1,267 @@
+'use client';
+
+import React, { useState, useCallback, useEffect, useRef } from 'react';
+import {
+  useDebugLogStore,
+  useDebugFilteredLogs,
+  useDebugLogCount,
+  useDebugErrorCount,
+  type LogLevel,
+  type LogEntry,
+} from '../logger';
+import {
+  Button,
+  CopyButton,
+  Badge,
+  Input,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import { LazyJsonTree } from '@djangocfg/ui-tools';
+import { useVirtualizer, type VirtualItem } from '@tanstack/react-virtual';
+import {
+  Bug, Trash2, Download, ChevronDown, ChevronUp,
+  AlertCircle, Info, AlertTriangle, CheckCircle, Search,
+} from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const ROW_ESTIMATE_PX = 32;
+const OVERSCAN = 5;
+
+const LOG_LEVEL_CONFIG: Record<LogLevel, { icon: React.ElementType; color: string }> = {
+  debug:   { icon: Bug,           color: 'text-muted-foreground' },
+  info:    { icon: Info,          color: 'text-blue-500' },
+  warn:    { icon: AlertTriangle, color: 'text-yellow-500' },
+  error:   { icon: AlertCircle,  color: 'text-red-500' },
+  success: { icon: CheckCircle,  color: 'text-green-500' },
+};
+
+const LOG_LEVELS = Object.keys(LOG_LEVEL_CONFIG) as LogLevel[];
+
+// ============================================================================
+// LogEntryRow
+// ============================================================================
+
+interface LogEntryRowProps {
+  entry: LogEntry;
+  expanded: boolean;
+  onToggle: () => void;
+}
+
+function LogEntryRow({ entry, expanded, onToggle }: LogEntryRowProps) {
+  const config = LOG_LEVEL_CONFIG[entry.level];
+  const Icon = config.icon;
+  const pad = (n: number, len = 2) => String(n).padStart(len, '0');
+  const d = entry.timestamp;
+  const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+  const hasData = entry.data && Object.keys(entry.data).length > 0;
+  const hasStack = !!entry.stack;
+  const isExpandable = hasData || hasStack;
+
+  return (
+    <div className="border-b border-border/50 last:border-0">
+      <button
+        type="button"
+        onClick={isExpandable ? onToggle : undefined}
+        disabled={!isExpandable}
+        className={cn(
+          'flex w-full items-start gap-2 px-3 py-1.5 text-left text-xs',
+          isExpandable ? 'hover:bg-muted/50 cursor-pointer' : 'cursor-default'
+        )}
+      >
+        <Icon className={cn('h-3.5 w-3.5 mt-0.5 shrink-0', config.color)} />
+        <span className="text-muted-foreground font-mono shrink-0">{time}</span>
+        <Badge variant="outline" className="shrink-0 text-[10px] px-1 py-0">{entry.component}</Badge>
+        <span className="flex-1 truncate">{entry.message}</span>
+        {isExpandable && (
+          <span className="shrink-0 text-muted-foreground">
+            {expanded ? <ChevronUp className="h-3 w-3" /> : <ChevronDown className="h-3 w-3" />}
+          </span>
+        )}
+      </button>
+      {expanded && isExpandable && (
+        <div className="px-3 pb-2 pl-8">
+          {hasData && <div className="mt-1"><LazyJsonTree data={entry.data} mode="compact" /></div>}
+          {hasStack && (
+            <pre className="mt-2 text-[10px] text-red-400 whitespace-pre-wrap font-mono bg-red-950/20 p-2 rounded">
+              {entry.stack}
+            </pre>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ============================================================================
+// LogsPanel
+// ============================================================================
+
+export function LogsPanel({ isActive }: { isActive: boolean }) {
+  const [expandedLogs, setExpandedLogs] = useState<Set<string>>(new Set());
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedLevels, setSelectedLevels] = useState<Set<LogLevel>>(
+    new Set(['debug', 'info', 'warn', 'error', 'success'])
+  );
+  const [componentFilter, setComponentFilter] = useState('');
+
+  const logs = useDebugFilteredLogs();
+  const logCount = useDebugLogCount();
+  const errorCount = useDebugErrorCount();
+  const clearLogs = useDebugLogStore((s) => s.clearLogs);
+  const setFilter = useDebugLogStore((s) => s.setFilter);
+  const exportLogs = useDebugLogStore((s) => s.exportLogs);
+
+  // Virtualizer
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: logs.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => ROW_ESTIMATE_PX,
+    overscan: OVERSCAN,
+  });
+
+  useEffect(() => {
+    if (!isActive) return;
+    setFilter({
+      levels: Array.from(selectedLevels),
+      component: componentFilter || undefined,
+      search: searchQuery || undefined,
+    });
+  }, [isActive, selectedLevels, componentFilter, searchQuery, setFilter]);
+
+  const handleToggleExpand = useCallback((id: string) => {
+    setExpandedLogs((prev) => {
+      const next = new Set(prev);
+      next.has(id) ? next.delete(id) : next.add(id);
+      return next;
+    });
+  }, []);
+
+  const handleToggleLevel = useCallback((level: LogLevel) => {
+    setSelectedLevels((prev) => {
+      const next = new Set(prev);
+      next.has(level) ? next.delete(level) : next.add(level);
+      return next;
+    });
+  }, []);
+
+  const handleExport = useCallback(() => {
+    const json = exportLogs();
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `debug-logs-${new Date().toISOString().slice(0, 19).replace(/:/g, '-')}.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }, [exportLogs]);
+
+  const handleClear = useCallback(() => {
+    clearLogs();
+    setExpandedLogs(new Set());
+  }, [clearLogs]);
+
+  const logsJson = exportLogs();
+  const virtualItems = virtualizer.getVirtualItems();
+  const totalSize = virtualizer.getTotalSize();
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Stats */}
+      <div className="flex items-center gap-2 border-b border-border px-3 py-1.5 shrink-0">
+        <Badge variant="secondary" className="text-[10px]">{logCount} logs</Badge>
+        {errorCount > 0 && <Badge variant="destructive" className="text-[10px]">{errorCount} errors</Badge>}
+      </div>
+
+      {/* Filters */}
+      <div className="flex flex-wrap items-center gap-2 border-b border-border px-3 py-2 shrink-0">
+        <div className="relative flex-1 min-w-[140px]">
+          <Search className="absolute left-2 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            placeholder="Search..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="h-7 pl-7 text-xs"
+          />
+        </div>
+        <Input
+          placeholder="Component..."
+          value={componentFilter}
+          onChange={(e) => setComponentFilter(e.target.value)}
+          className="h-7 w-24 text-xs"
+        />
+        <div className="flex items-center gap-0.5">
+          {LOG_LEVELS.map((level) => {
+            const { icon: Icon, color } = LOG_LEVEL_CONFIG[level];
+            const active = selectedLevels.has(level);
+            return (
+              <Tooltip key={level}>
+                <TooltipTrigger asChild>
+                  <Button variant={active ? 'secondary' : 'ghost'} size="icon" className="h-6 w-6" onClick={() => handleToggleLevel(level)}>
+                    <Icon className={cn('h-3.5 w-3.5', active && color)} />
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent>{level}</TooltipContent>
+              </Tooltip>
+            );
+          })}
+        </div>
+        <div className="flex items-center gap-0.5 ml-auto">
+          <CopyButton value={logsJson} size="icon" className="h-6 w-6" />
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleExport}>
+                <Download className="h-3.5 w-3.5" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Export JSON</TooltipContent>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleClear}>
+                <Trash2 className="h-3.5 w-3.5" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Clear</TooltipContent>
+          </Tooltip>
+        </div>
+      </div>
+
+      {/* Virtualized log list */}
+      <div ref={scrollRef} className="flex-1 overflow-auto">
+        {logs.length === 0 ? (
+          <div className="flex flex-col items-center justify-center py-10 text-muted-foreground">
+            <Bug className="h-8 w-8 mb-2 opacity-40" />
+            <p className="text-sm">No logs yet</p>
+          </div>
+        ) : (
+          <div style={{ height: `${totalSize}px`, position: 'relative' }}>
+            {virtualItems.map((vItem: VirtualItem) => {
+              const entry = logs[vItem.index];
+              return (
+                <div
+                  key={entry.id}
+                  data-index={vItem.index}
+                  ref={virtualizer.measureElement}
+                  style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${vItem.start}px)` }}
+                >
+                  <LogEntryRow
+                    entry={entry}
+                    expanded={expandedLogs.has(entry.id)}
+                    onToggle={() => handleToggleExpand(entry.id)}
+                  />
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/panels/StorePanel.tsx

@@ -0,0 +1,71 @@
+'use client';
+
+import React from 'react';
+import { ScrollArea } from '@djangocfg/ui-core/components';
+import { LazyJsonTree } from '@djangocfg/ui-tools';
+import { Database } from 'lucide-react';
+import { useStoreSnapshot } from '../hooks/useStoreSnapshot';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StorePanelProps {
+  /** Display label shown above the JSON tree */
+  label: string;
+  /**
+   * Getter for the store state slice to display.
+   * Use `() => useMyStore.getState()` — stable function ref is not required,
+   * the hook handles stabilization internally.
+   */
+  getState: () => Record<string, unknown>;
+  /**
+   * Poll interval in ms. Default 200ms.
+   * Use higher values for stores that update very frequently.
+   */
+  intervalMs?: number;
+  /** Only polls when active (panel tab is visible) */
+  isActive: boolean;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * Generic Zustand store viewer for the debug panel.
+ *
+ * Uses polling (not reactive subscription) to read external store state.
+ * This avoids Zustand v5 infinite loop issues and prevents the debug panel
+ * from re-rendering on every store change.
+ *
+ * @example — in consuming app's custom tab:
+ * import { StorePanel } from '@org/debuger';
+ * import { useTimelineStore } from '@stores/timelineStore';
+ *
+ * <StorePanel
+ *   label="Timeline Store"
+ *   getState={() => useTimelineStore.getState()}
+ *   isActive={isActive}
+ * />
+ */
+export function StorePanel({ label, getState, intervalMs = 200, isActive }: StorePanelProps) {
+  const snapshot = useStoreSnapshot(getState, intervalMs, isActive);
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="flex items-center gap-2 border-b border-border px-3 py-2 shrink-0">
+        <Database className="h-3.5 w-3.5 text-muted-foreground" />
+        <span className="text-xs font-medium text-muted-foreground">{label}</span>
+        <span className="ml-auto text-[10px] text-muted-foreground/60">
+          polling {intervalMs}ms
+        </span>
+      </div>
+      <ScrollArea className="flex-1">
+        <div className="p-2">
+          <LazyJsonTree data={snapshot} mode="full" />
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}

package/src/store/debugStore.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import { create } from 'zustand';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DebugTab = 'logs' | 'audio' | 'pipeline' | 'custom';
+
+export interface DebugStore {
+  isOpen: boolean;
+  tab: DebugTab;
+  isUnlocked: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  setTab: (t: DebugTab) => void;
+  unlock: (key: string) => boolean;
+}
+
+// ============================================================================
+// Store
+// ============================================================================
+
+export const useDebugStore = create<DebugStore>((set) => ({
+  isOpen: false,
+  tab: 'logs',
+  isUnlocked: false,
+
+  open: () => set({ isOpen: true }),
+  close: () => set({ isOpen: false }),
+  toggle: () => set((s) => ({ isOpen: !s.isOpen })),
+  setTab: (tab) => set({ tab }),
+
+  unlock: (_key) => {
+    // Any non-empty value unlocks — no secret key required
+    const valid = true;
+    if (valid) set({ isUnlocked: true });
+    return valid;
+  },
+}));

package/src/styles/index.css

@@ -0,0 +1,5 @@
+/**
+ * Tailwind v4 Source Detection for Debuger Package
+ * Add this import to your app's globals.css to enable Tailwind class scanning.
+ */
+@source "../**/*.{ts,tsx}";