@crimsonsunset/jsg-logger 1.6.0 → 1.7.2

package/devtools/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/docs/devtools-roadmap.md

@@ -128,10 +128,13 @@
 - [ ] **Bulk Actions** - Select multiple components for batch operations
 - [ ] **Preset Configurations** - Save/load common debug configurations
 
-### **Phase 4: Data & Persistence** 🎯 FUTURE
+### **Phase 4: State Management & Persistence** 🎯 FUTURE
+- [ ] **Zustand Integration** - Centralized state management for DevTools UI
+- [ ] **Floating Button Position** - Persist position across reloads (first Zustand feature)
+- [ ] **Panel Open/Closed State** - Remember panel state across page reloads
+- [ ] **Display Settings** - Persist display toggles and preferences
+- [ ] **Component Filter States** - Remember component level selections
 - [ ] **Configuration Export/Import** - Save panel settings to JSON
-- [ ] **Session Persistence** - Remember panel state across page reloads
-- [ ] **Local Storage** - Persist component preferences per site
 - [ ] **Configuration Sharing** - Export/import debug configurations
 - [ ] **Preset Templates** - Common configurations for different scenarios
 

package/docs/next-session.md

@@ -14,12 +14,74 @@
 
 ---
 
-**Date:** October 25, 2025  
-**Session Goal:** 🎯 **Critical CLI Tool Fixes** - Resolve environment detection and custom component blockers  
-**Status:** ✅ **COMPLETE** - v1.5.0 shipped with all critical fixes
+**Date:** October 28, 2025  
+**Session Goal:** 🎨 **Phase 7.1: Display Controls Panel** - Real-time preview with display toggles  
+**Status:** ✅ **COMPLETE** - All display controls implemented and working
 
 ## 🎉 MAJOR ACCOMPLISHMENTS THIS SESSION
 
+### ✅ Phase 7.1 Display Controls Complete (October 28, 2025) 🎨→✅
+- **📊 Live Preview in Sticky Header** - Real-time log preview that updates instantly
+  - Shows sample log with all elements (timestamp, emoji, component, level, message, JSON, stack trace)
+  - Updates immediately as controls are toggled
+  - Stays visible while scrolling through other controls
+  - Professional monospace styling matching console output
+- **⏱️ Timestamp Mode Control** - Button group with 4 modes
+  - Absolute: `22:15:30.1` (milliseconds precision)
+  - Readable: `10:15 PM` (12-hour format)
+  - Relative: `2s ago` (time since)
+  - Off: Hidden (no timestamp)
+  - Active button highlighted with primary appearance
+- **🎛️ 6 Display Toggle Switches** - Granular control over log elements
+  - Emoji: Show/hide level emoji (🌐, 🚨, etc.)
+  - Component: Show/hide [COMPONENT-NAME] tags
+  - Level Name: Show/hide level text (INFO, DEBUG, etc.)
+  - Message: Always on (disabled - can't hide messages)
+  - JSON Data: Show/hide context data trees
+  - Stack Trace: Show/hide error stack traces
+- **✅ Bulk Operations** - Quick control actions
+  - All On: Enable all display options
+  - All Off: Disable all (except message)
+  - Reset: Restore default settings
+- **🏗️ Clean Architecture** - Simplified layout with no sections
+  - Removed all subheadings and dividers
+  - Everything in one sticky container
+  - Only Component Filters and Global Controls scroll
+  - Single divider at the bottom of scrolling content
+- **🔧 API Integration** - Full logger.controls integration
+  - `getDisplayConfig()` loads initial state
+  - `getTimestampMode()` loads timestamp setting
+  - `setDisplayOption()` applies changes to console
+  - `setTimestampMode()` updates timestamp format
+  - State managed via parent component callback
+
+### **Technical Implementation**
+- **DisplayControls.jsx** (~350 lines)
+  - Exported LogPreview component for header use
+  - State management with `onStateChange` callback
+  - Timestamp button group (replaced SegmentedControl)
+  - 6 toggle switches in 2-column grid
+  - Bulk control buttons
+- **PanelContainer.jsx** (updated)
+  - LogPreview and DisplayControls in sticky header
+  - State management for preview rendering
+  - Single scrolling content area
+  - Clean layout with one border at bottom
+- **ComponentFilters.jsx** (simplified)
+  - Removed "🎚️ Log Levels" heading
+  - Reduced spacing for compact layout
+- **GlobalControls.jsx** (simplified)
+  - Removed "🌐 Global Controls" heading
+  - Cleaner integration with overall layout
+
+### **Real-World Impact**
+Phase 7.1 completes the foundation for comprehensive DevTools UI:
+- **Before**: Only basic component filtering, missing 80% of logger capabilities
+- **After**: Display controls expose all visual formatting options with live preview
+- **Next**: Phase 7.2 will add component management (emoji/color pickers, bulk operations)
+
+## 🎉 PREVIOUS SESSION ACCOMPLISHMENTS
+
 ### ✅ Critical CLI Tool Fixes Complete (October 25, 2025) 🚨→✅
 - **🎨 CLI Context Data Display Fixed** - Replaced pino-colada with custom formatter
   - Context data now renders as indented tree in terminal

package/docs/roadmap.md

@@ -20,10 +20,10 @@
 ---
 
 ## 🎯 Current Status
-**Last Updated:** August 21, 2025  
-**Current Phase:** DevTools Phase 2 - Evergreen UI Migration 🔧 **IN PROGRESS**  
-**Status:** 🎨 **UI COMPLETE, DEBUGGING API INTEGRATION** - Professional DevTools UI built, fixing logger compatibility  
-**Next Phase:** Complete DevTools Phase 2, then Phase 10 DX Enhancements
+**Last Updated:** October 28, 2025  
+**Current Phase:** DevTools UI Enhancement (Phase 3-7) 🚀 **ACTIVE DEVELOPMENT**  
+**Status:** 🎨 **PHASE 7.1 COMPLETE** - Display Controls with live preview implemented  
+**Next Phase:** Phase 7.2 Component Management → Log Viewer → Advanced Config → Statistics → UI Polish
 
 ### Progress Overview
 - ✅ **COMPLETED:** Multi-environment logger with smart detection
@@ -38,6 +38,8 @@
 - ✅ **COMPLETED:** Documentation structure (LICENSE, CHANGELOG, CONTRIBUTING)
 - ✅ **COMPLETED:** Phase 8 API Enhancement - v1.1.0 with zero-boilerplate integration
 - ✅ **COMPLETED:** Phase 9 Genericization - v1.2.0 with zero legacy references
+- ✅ **COMPLETED:** Phase 6 DevTools Foundation - Working panel with Evergreen UI integration
+- 🚀 **IN PROGRESS:** Phase 7 DevTools UI Enhancement - Comprehensive feature expansion
 
 ### Key Achievements
 - **🚀 BREAKTHROUGH:** Custom browser logger achieving perfect visual formatting
@@ -47,6 +49,8 @@
 - **📚 Documentation:** Comprehensive README with examples
 - **✨ PROJECT SIMPLIFICATION:** Phase 8 - 82% boilerplate reduction with v1.1.0 API enhancements
 - **🎯 FULL GENERICIZATION:** Phase 9 - 100% generic logger, zero legacy dependencies
+- **🎛️ DEVTOOLS FOUNDATION:** Phase 6 - Working panel with Evergreen UI integration and runtime injection
+- **📊 COMPREHENSIVE PLANNING:** Phase 7 - Identified and architected solution for exposing 80% of missing library capabilities
 
 ---
 
@@ -105,19 +109,153 @@
 - [x] docs/ folder structure
 - [x] Roadmap and session tracking
 
-### **Phase 6: DevTools Panel Implementation** 🎯 FUTURE
-- [ ] **DevTools Panel Architecture** - Runtime-injected browser widget
-- [ ] **UI Components** - Preact-based filtering controls
-- [ ] **Panel Integration** - Floating button + collapsible sidebar
-- [ ] **Filter Controls** - Component toggles using existing logger.controls API
-- [ ] **State Persistence** - IndexedDB for panel preferences
-- [ ] **Real-time Filtering** - Forward console filtering without log display
+### **Phase 6: DevTools Panel Implementation** ✅ COMPLETE
+- [x] **DevTools Panel Architecture** - Runtime-injected browser widget
+- [x] **UI Components** - Preact-based filtering controls
+- [x] **Panel Integration** - Floating button + collapsible sidebar
+- [x] **Filter Controls** - Component toggles using existing logger.controls API
+- [x] **State Persistence** - IndexedDB for panel preferences
+- [x] **Real-time Filtering** - Forward console filtering without log display
+
+### **Phase 7: DevTools UI Enhancement (Phase 2)** 🚀 ACTIVE
+- [x] **Display Controls Panel** - 7 toggle switches for display options with real-time preview ✅ COMPLETE
+- [ ] **Enhanced Component Management** - Emoji/color pickers, add/remove components, bulk operations 🎯 NEXT
+- [ ] **Integrated Log Viewer** - Real-time filtering, search, export capabilities within DevTools
+- [ ] **Advanced Configuration** - Timestamp controls, environment settings, config import/export
+- [ ] **Statistics Dashboard** - Analytics, charts, performance monitoring, visual trends
+- [ ] **UI Architecture Polish** - Tabbed interface, responsive design, professional theming
+
+### **Phase 8: Advanced DevTools Features** 🎯 FUTURE
+- [ ] **File Override Management** - Visual interface for file-specific logging rules
+- [ ] **Performance Monitoring** - Real-time performance metrics and optimization suggestions
+- [ ] **Export Utilities** - Advanced log export formats (JSON, CSV, filtered datasets)
+- [ ] **Integration Guides** - Framework-specific examples and DevTools integration patterns
 
-### **Phase 7: Optional Ecosystem Enhancements** 🎯 FUTURE  
-- [ ] **Performance Monitoring** - Log performance metrics
-- [ ] **Export Utilities** - Save logs to file formats
-- [ ] **Integration Guides** - Framework-specific examples
-- [ ] **Restore pino-pretty Support** - Add back full pino-pretty formatter with proper browser/Node.js environment detection to avoid bundling conflicts
+---
+
+## 🎛️ **Phase 7: DevTools UI Enhancement - Detailed Implementation Plan**
+
+*This section outlines the comprehensive expansion of DevTools UI to expose JSG Logger's full capabilities.*
+
+### **🎯 Gap Analysis Results**
+
+**Current UI Coverage:** ~20% of JSG Logger capabilities  
+**Missing Features:** 80% of sophisticated library functionality not exposed in UI
+
+**Critical Missing Categories:**
+1. **File Override Management** - Visual interface for powerful file-specific logging rules
+2. **Display Controls** - 7 individual display option toggles with real-time preview
+3. **Component Management** - Emoji/color customization, add/remove components, bulk operations
+4. **Log Viewer** - Integrated log viewing with filtering, search, and export
+5. **Advanced Configuration** - Timestamp controls, environment settings, config management
+6. **Statistics Dashboard** - Analytics, trends, performance monitoring with visualizations
+7. **UI Architecture** - Professional tabbed interface with responsive design and state persistence
+
+### **🚀 Implementation Phases**
+
+#### **Phase 7.1: Display Controls Panel** ✅ COMPLETE (October 28, 2025)
+**Implemented Components:**
+- `devtools/src/components/DisplayControls.jsx` (created - 350 lines)
+- `devtools/src/components/PanelContainer.jsx` (updated - sticky header integration)
+- `devtools/src/components/ComponentFilters.jsx` (simplified - removed heading)
+- `devtools/src/components/GlobalControls.jsx` (simplified - removed heading)
+
+**Features Delivered:**
+- ✅ Live preview in sticky header with real-time updates
+- ✅ Timestamp mode selector (4 buttons: Absolute, Readable, Relative, Off)
+- ✅ 6 toggle switches (emoji, component, level, message-disabled, JSON data, stack trace)
+- ✅ Bulk operations (All On, All Off, Reset)
+- ✅ Clean architecture with single sticky container
+- ✅ Full API integration with logger.controls
+- ✅ State management via parent callback (onStateChange)
+
+#### **Phase 7.2: Enhanced Component Management** 🎯 NEXT
+**Target Components:**
+- `devtools/src/components/ComponentManager.jsx` (new)
+- `devtools/src/components/ComponentEditor.jsx` (new)
+- `devtools/src/components/ComponentFilters.jsx` (update)
+
+**Features:**
+- Component customization modal with emoji picker
+- Color picker for component themes and styling
+- Add/remove custom components with validation
+- Bulk component operations (select all, reset all, apply level to multiple)
+- Component import/export functionality
+- Component usage statistics and recommendations
+
+#### **Phase 7.3: Integrated Log Viewer** 🎯 FUTURE
+**Target Components:**
+- `devtools/src/components/LogViewer.jsx` (new)
+- `devtools/src/components/LogEntry.jsx` (new)
+- `devtools/src/components/LogFilters.jsx` (new)
+
+**Features:**
+- Virtualized scrolling log viewer for performance with large datasets
+- Real-time log filtering by component, level, and custom criteria
+- Advanced search functionality with regex support
+- Log export features (JSON, CSV, plain text, filtered datasets)
+- Log entry expansion showing full context data and metadata
+- Integration with `logger.logStore` API for efficient data access
+
+#### **Phase 7.4: Advanced Configuration Interface** 🎯 FUTURE
+**Target Components:**
+- `devtools/src/components/AdvancedConfig.jsx` (new)
+- `devtools/src/components/TimestampControls.jsx` (new)
+- `devtools/src/components/ConfigManager.jsx` (new)
+
+**Features:**
+- Timestamp mode selector with 4 modes and live preview
+- Environment override controls with detection status
+- Configuration import/export with validation and diff viewing
+- Performance monitoring dashboard with metrics and recommendations
+- System information panel showing environment details and capabilities
+
+#### **Phase 7.5: Statistics & Monitoring Dashboard** 🎯 FUTURE
+**Target Components:**
+- `devtools/src/components/StatsDashboard.jsx` (new)
+- `devtools/src/components/ComponentChart.jsx` (new)
+- `devtools/src/components/PerformanceMonitor.jsx` (new)
+
+**Features:**
+- Enhanced statistics dashboard with interactive charts and graphs
+- Component activity trends and usage patterns visualization
+- Time-based analytics with historical data and trend analysis
+- Performance metrics monitoring with optimization suggestions
+- Real-time monitoring widgets with configurable alerts and thresholds
+
+#### **Phase 7.6: UI Architecture & Professional Polish** 🎯 FUTURE
+**Target Components:**
+- `devtools/src/components/TabbedInterface.jsx` (new)
+- `devtools/src/components/PanelContainer.jsx` (major redesign)
+- `devtools/src/styles/` (new directory)
+
+**Features:**
+- Tabbed interface for organizing all panels with intuitive navigation
+- Responsive design adapting to different screen sizes and orientations
+- Consistent theming across all components with dark/light mode support
+- Smooth animations and transitions for professional user experience
+- Keyboard shortcuts for common actions and navigation
+- Panel state persistence using localStorage with user preferences
+
+### **🎯 Success Criteria**
+
+#### **Functionality Goals**
+- ✅ **Complete API Coverage** - UI exposes 95%+ of JSG Logger's runtime capabilities
+- ✅ **Superior Console Alternative** - Better UX than native browser console
+- ✅ **Integrated Workflow** - All debugging needs met within single interface
+- ✅ **Professional Quality** - Matches or exceeds native DevTools UI standards
+
+#### **User Experience Goals**
+- ✅ **Intuitive Navigation** - Users can find any feature within 2 clicks
+- ✅ **Immediate Feedback** - All changes reflected in real-time
+- ✅ **State Persistence** - User preferences and panel states survive page reloads
+- ✅ **Performance** - UI remains responsive with 1000+ log entries and 50+ components
+
+#### **Technical Goals**
+- ✅ **Zero Bundle Impact** - All features load on-demand via dynamic imports
+- ✅ **Responsive Design** - Works seamlessly from 1024px to 4K displays
+- ✅ **Accessibility** - Full keyboard navigation and screen reader support
+- ✅ **Browser Compatibility** - Works in Chrome, Firefox, Safari, and Edge
 
 ---
 
@@ -342,7 +480,24 @@ Console filtering updates
 
 ## 📈 Recent Progress
 
-### August 21, 2025 - DevTools Phase 2: Evergreen UI Migration Major Progress 🎨
+### October 28, 2025 - Phase 7.1 Display Controls Complete 🎨
+- ✅ **Live Preview in Sticky Header** - Real-time log preview updates instantly as controls change
+- ✅ **Timestamp Mode Control** - 4-button group (Absolute, Readable, Relative, Off)
+- ✅ **6 Display Toggles** - Emoji, Component, Level, Message (disabled), JSON Data, Stack Trace
+- ✅ **Bulk Operations** - All On, All Off, Reset buttons for quick control
+- ✅ **Clean Architecture** - Removed all subheadings/dividers, single sticky container
+- ✅ **API Integration** - Full logger.controls integration for display options and timestamp mode
+- 🔧 **Fixed SegmentedControl Issue** - Replaced with button group (not in Evergreen UI v7)
+- 📦 **Component Updates** - DisplayControls.jsx created, PanelContainer/ComponentFilters/GlobalControls simplified
+
+### October 27, 2025 - DevTools UI Enhancement Planning & Architecture 🎛️
+- ✅ **Gap Analysis Complete** - Identified JSG Logger exposes only ~20% of capabilities in current DevTools UI
+- ✅ **Feature Prioritization** - Mapped 7 critical missing feature categories with implementation priorities
+- ✅ **Architecture Planning** - Designed comprehensive UI enhancement covering display controls, component management, log viewer, advanced config, statistics, and UI polish
+- 🎯 **Phase 7 Expansion** - Redefined DevTools development as comprehensive UI enhancement rather than simple panel addition
+- 📋 **Roadmap Updated** - Updated implementation phases to reflect new DevTools focus and priorities
+
+### August 21, 2025 - DevTools Phase 2: Evergreen UI Migration Complete ✅
 - ✅ **Professional UI Architecture** - Complete Preact + Evergreen UI DevTools application
 - ✅ **Separate DevTools Package** - Independent development environment in `devtools/` directory  
 - ✅ **Custom Theme System** - Professional dark theme with JSG Logger branding colors
@@ -715,6 +870,8 @@ if (this.loggers.core) {
 ### **Phase 10: Developer Experience Enhancements** 🎯 FUTURE  
 **Goal**: Make JSG Logger deployment effortless for new projects with zero friction onboarding
 
+*Note: This phase moved to lower priority as DevTools UI enhancement takes precedence based on gap analysis revealing only 20% of library capabilities currently exposed in UI.*
+
 **Current State Analysis:**
 - ✅ **Easy to use**: `JSGLogger.getInstance({ configPath: './logger-config.json' })`
 - ✅ **Auto-discovery**: Missing components created automatically

package/examples/advanced-config.json

@@ -105,6 +105,9 @@
       }
     }
   },
+  "devtools": {
+    "enabled": false
+  },
   "fileOverrides": {
     "src/api/auth.js": { 
       "level": "trace",

package/formatters/browser-formatter.js

@@ -57,7 +57,7 @@ export const createBrowserFormatter = (componentName, logStore = null) => {
 
                 // 3. Component name
                 if (displayConfig.component) {
-                    const componentName = component.name.toUpperCase().replace(/([a-z])([A-Z])/g, '$1-$2');
+                    const componentName = component.name;  // Already formatted by configManager
                     logParts.push(`%c[${componentName}]`);
                     logStyles.push(`color: ${component.color}; font-weight: bold;`);
                 }

package/formatters/cli-formatter.js

@@ -3,7 +3,8 @@
  * Custom formatter with context data display
  */
 
-import { COMPONENT_SCHEME, LEVEL_SCHEME } from '../config/component-schemes.js';
+import { LEVEL_SCHEME } from '../config/component-schemes.js';
+import { configManager } from '../config/config-manager.js';
 
 /**
  * Format a value for display in context tree
@@ -36,9 +37,9 @@ export const createCLIFormatter = () => {
       try {
         const log = JSON.parse(chunk);
         
-        // Get component info
-        const component = COMPONENT_SCHEME[log.name] || COMPONENT_SCHEME['core'];
-        const componentName = component.name.toUpperCase().replace(/([a-z])([A-Z])/g, '$1-$2');
+        // Get component info from configManager (supports custom components)
+        const component = configManager.getComponentConfig(log.name);
+        const componentName = component.name;
         
         // Get level info  
         const level = LEVEL_SCHEME[log.level] || LEVEL_SCHEME[30];

package/index.d.ts

@@ -0,0 +1,192 @@
+/**
+ * TypeScript definitions for @crimsonsunset/jsg-logger
+ */
+
+export interface LoggerInstance {
+  info: (message: string, data?: any) => void;
+  debug: (message: string, data?: any) => void;
+  warn: (message: string, data?: any) => void;
+  error: (message: string, data?: any) => void;
+  fatal: (message: string, data?: any) => void;
+  trace: (message: string, data?: any) => void;
+  [key: string]: any;
+}
+
+export interface LoggerComponents {
+  /**
+   * Component loggers - factory functions that ALWAYS return LoggerInstance
+   * Components return no-op logger if not initialized or unavailable
+   * Safe to call without null checks: components.reactComponents?.().info(...)
+   */
+  reactComponents?: () => LoggerInstance;
+  astroComponents?: () => LoggerInstance;
+  astroBuild?: () => LoggerInstance;
+  astroIntegration?: () => LoggerInstance;
+  contentProcessing?: () => LoggerInstance;
+  textUtils?: () => LoggerInstance;
+  dateUtils?: () => LoggerInstance;
+  pages?: () => LoggerInstance;
+  config?: () => LoggerInstance;
+  seo?: () => LoggerInstance;
+  performance?: () => LoggerInstance;
+  devServer?: () => LoggerInstance;
+  webComponents?: () => LoggerInstance;
+  core?: () => LoggerInstance;
+  api?: () => LoggerInstance;
+  ui?: () => LoggerInstance;
+  database?: () => LoggerInstance;
+  test?: () => LoggerInstance;
+  preact?: () => LoggerInstance;
+  auth?: () => LoggerInstance;
+  analytics?: () => LoggerInstance;
+  websocket?: () => LoggerInstance;
+  notification?: () => LoggerInstance;
+  router?: () => LoggerInstance;
+  cache?: () => LoggerInstance;
+  /**
+   * Dynamic component access - always returns a logger factory
+   * The factory function always returns LoggerInstance (no-op if unavailable)
+   */
+  [key: string]: (() => LoggerInstance) | undefined;
+}
+
+export interface JSGLoggerConfig {
+  configPath?: string;
+  config?: Record<string, any>;
+  devtools?: {
+    enabled?: boolean;
+  };
+  [key: string]: any;
+}
+
+export interface LoggerControls {
+  setLevel?: (component: string, level: string) => void;
+  getLevel?: (component: string) => string | undefined;
+  listComponents?: () => string[];
+  enableDebugMode?: () => void;
+  enableTraceMode?: () => void;
+  addFileOverride?: (filePath: string, overrideConfig: Record<string, any>) => void;
+  removeFileOverride?: (filePath: string) => void;
+  listFileOverrides?: () => string[];
+  setTimestampMode?: (mode: string) => void;
+  getTimestampMode?: () => string;
+  getTimestampModes?: () => string[];
+  setDisplayOption?: (option: string, enabled: boolean) => void;
+  getDisplayConfig?: () => Record<string, boolean>;
+  toggleDisplayOption?: (option: string) => void;
+  getStats?: () => any;
+  subscribe?: (callback: Function) => void;
+  clearLogs?: () => void;
+  getConfigSummary?: () => any;
+  setComponentLevel?: (component: string, level: string) => void;
+  getComponentLevel?: (component: string) => string | undefined;
+  enableDevPanel?: () => Promise<any>;
+  disableDevPanel?: () => boolean;
+  refresh?: () => void;
+  reset?: () => void;
+  [key: string]: any;
+}
+
+export interface LoggerConfig {
+  environment?: string;
+  components?: Record<string, any>;
+  summary?: any;
+}
+
+export interface LoggerInstanceType {
+  /**
+   * Direct access to component loggers
+   */
+  [componentName: string]: LoggerInstance | any;
+
+  /**
+   * Auto-discovery convenience getters (factory functions)
+   */
+  components?: LoggerComponents;
+
+  /**
+   * Get a specific component logger - always returns a logger instance
+   * Returns no-op logger if component unavailable or logger not initialized
+   * Always available - never undefined
+   */
+  getComponent: (componentName: string) => LoggerInstance;
+
+  /**
+   * Create a logger for a specific component
+   */
+  createLogger?: (componentName: string) => LoggerInstance;
+
+  /**
+   * Configuration and debugging info
+   */
+  config?: LoggerConfig;
+
+  /**
+   * Configuration manager instance
+   */
+  configManager?: any;
+
+  /**
+   * Log store instance
+   */
+  logStore?: any;
+
+  /**
+   * Enhanced runtime controls
+   */
+  controls?: LoggerControls;
+
+  /**
+   * Get singleton instance (async)
+   */
+  getInstance?: (config?: JSGLoggerConfig) => Promise<LoggerInstanceType> | LoggerInstanceType;
+
+  /**
+   * Get singleton instance (sync)
+   */
+  getInstanceSync?: (config?: JSGLoggerConfig) => LoggerInstanceType;
+
+  /**
+   * Static performance logging utility
+   */
+  logPerformance?: (label: string, startTime: number, component?: string) => Promise<number>;
+}
+
+export interface JSGLogger {
+  /**
+   * Get singleton instance with auto-initialization
+   * @param config - Initialization options (only used on first call)
+   * @returns Enhanced logger exports with controls API
+   * 
+   * Note: Returns Promise if initialization is needed, sync value if already initialized.
+   * Use `await` to handle both cases safely.
+   * 
+   * @example
+   * ```ts
+   * const logger = await JSGLogger.getInstance({ configPath: 'logger-config.json' });
+   * logger.components?.reactComponents?.().info('Hello');
+   * ```
+   */
+  getInstance(config?: JSGLoggerConfig): Promise<LoggerInstanceType> | LoggerInstanceType;
+
+  /**
+   * Get singleton instance synchronously (for environments without async support)
+   * @param config - Initialization options (only used on first call)
+   * @returns Enhanced logger exports with controls API
+   */
+  getInstanceSync(config?: JSGLoggerConfig): LoggerInstanceType;
+
+  /**
+   * Static performance logging utility
+   * @param label - Performance label
+   * @param startTime - Start time from performance.now()
+   * @param component - Optional component name (defaults to 'performance')
+   * @returns Duration in milliseconds
+   */
+  logPerformance(label: string, startTime: number, component?: string): Promise<number>;
+}
+
+declare const JSGLogger: JSGLogger;
+export default JSGLogger;
+export { JSGLogger };
+