create-fluxstack 1.13.0 → 1.15.0

package/LLMD/resources/live-components.md

@@ -1,12 +1,17 @@
 # Live Components
 
-**Version:** 1.13.0 | **Updated:** 2025-02-09
+**Version:** 1.14.0 | **Updated:** 2025-02-27
 
 ## Quick Facts
 
 - Server-side state management with WebSocket sync
 - **Direct state access** - `this.count++` auto-syncs (v1.13.0)
-- Automatic state persistence and re-hydration
+- **Lifecycle hooks** - `onMount()` / `onDestroy()` for proper initialization and cleanup (v1.14.0)
+- **HMR persistence** - `static persistent` + `this.$persistent` survives hot reloads (v1.14.0)
+- **Singleton components** - `static singleton = true` for shared server-side instances (v1.14.0)
+- **Mandatory `publicActions`** - Only whitelisted methods are callable from client (secure by default)
+- **Helpful error messages** - Forgotten `publicActions` entries show exactly what to fix (v1.14.0)
+- Automatic state persistence and re-hydration (with anti-replay nonces)
 - Room-based event system for multi-user sync
 - Type-safe client-server communication (FluxStackWebSocket)
 - Built-in connection management and recovery
@@ -25,7 +30,8 @@ import type { CounterDemo as _Client } from '@client/src/live/CounterDemo'
 
 export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
   static componentName = 'LiveCounter'
-  static logging = ['lifecycle', 'messages'] as const  // Per-component logging (optional)
+  static publicActions = ['increment', 'decrement', 'reset'] as const  // 🔒 REQUIRED
+  // static logging = ['lifecycle', 'messages'] as const  // Console logging (optional, prefer DEBUG_LIVE)
   static defaultState = {
     count: 0
   }
@@ -51,11 +57,19 @@ export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState>
 }
 ```
 
+### Key Changes in v1.14.0
+
+1. **Lifecycle hooks** - `onMount()` (async) and `onDestroy()` (sync) replace constructor/destroy workarounds
+2. **HMR persistence** - `static persistent` + `this.$persistent` for data that survives hot module reloads
+3. **Singleton components** - `static singleton = true` for shared state across all connected clients
+4. **Better publicActions errors** - Clear message when a method exists but is missing from `publicActions`
+
 ### Key Changes in v1.13.0
 
 1. **Direct state access** - `this.count++` instead of `this.state.count++`
 2. **declare keyword** - TypeScript hint for dynamic properties
 3. **Cleaner code** - No need to prefix with `this.state.`
+4. **Mandatory `publicActions`** - Components without it deny ALL remote actions (secure by default)
 
 ### Key Changes in v1.12.0
 
@@ -72,6 +86,7 @@ import { LiveComponent, type FluxStackWebSocket } from '@core/types/types'
 
 export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
   static componentName = 'LiveCounter'
+  static publicActions = ['increment'] as const  // 🔒 REQUIRED
   static defaultState = {
     count: 0,
     lastUpdatedBy: null as string | null,
@@ -107,27 +122,207 @@ export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState>
 }
 ```
 
-## Lifecycle Methods
+## Lifecycle Hooks (v1.14.0)
+
+Full lifecycle hook system — no more constructor workarounds:
 
 ```typescript
 export class MyComponent extends LiveComponent<typeof MyComponent.defaultState> {
   static componentName = 'MyComponent'
+  static publicActions = ['doWork'] as const
+  static defaultState = { users: [] as string[], ready: false, currentRoom: '' }
+
+  private _pollTimer?: NodeJS.Timeout
+
+  // 1️⃣ Called when WebSocket connection is established (before onMount)
+  protected onConnect() {
+    console.log('WebSocket connected for this component')
+  }
+
+  // 2️⃣ Called AFTER component is fully mounted (rooms, auth, injections ready)
+  // Can be async!
+  protected async onMount() {
+    this.$room.join()
+    this.$room.on('user:joined', (user) => {
+      this.state.users = [...this.state.users, user]
+    })
+    const data = await fetchInitialData(this.$auth.user?.id)
+    this.state.ready = true
+    this._pollTimer = setInterval(() => this.poll(), 5000)
+  }
+
+  // Called after state is restored from localStorage (rehydration)
+  protected onRehydrate(previousState: typeof MyComponent.defaultState) {
+    if (!previousState.ready) {
+      this.state.ready = false // Re-validate stale state
+    }
+  }
+
+  // Called after any state mutation (proxy or setState)
+  protected onStateChange(changes: Partial<typeof MyComponent.defaultState>) {
+    if ('users' in changes) {
+      console.log(`User count: ${this.state.users.length}`)
+    }
+  }
+
+  // Called when joining a room
+  protected onRoomJoin(roomId: string) {
+    this.state.currentRoom = roomId
+  }
+
+  // Called when leaving a room
+  protected onRoomLeave(roomId: string) {
+    if (this.state.currentRoom === roomId) this.state.currentRoom = ''
+  }
+
+  // Called before each action — return false to cancel
+  protected onAction(action: string, payload: any) {
+    console.log(`[${this.id}] ${action}`, payload)
+    // return false  // ← would cancel the action
+  }
+
+  // Called when WebSocket drops (NOT on intentional unmount)
+  protected onDisconnect() {
+    console.log('Connection lost — saving recovery data')
+  }
+
+  // Called BEFORE internal cleanup (sync only)
+  protected onDestroy() {
+    clearInterval(this._pollTimer)
+  }
+
+  async doWork() { /* ... */ }
+  private poll() { /* ... */ }
+}
+```
+
+### Lifecycle Order
+
+```
+WebSocket connects
+  └→ onConnect()
+       └→ onMount()          ← async, rooms/auth ready
+            └→ [component active]
+                 ├→ onAction(action, payload)  ← before each action (return false to cancel)
+                 ├→ onStateChange(changes)     ← after each state mutation
+                 ├→ onRoomJoin(roomId)         ← when joining a room
+                 └→ onRoomLeave(roomId)        ← when leaving a room
+
+Connection drops:
+  └→ onDisconnect()          ← only on unexpected disconnect
+       └→ onDestroy()        ← sync, before internal cleanup
+
+Rehydration (reconnect with saved state):
+  └→ onConnect()
+       └→ onRehydrate(previousState)
+            └→ onMount()
+```
+
+### Rules
+
+| Hook | Async? | When |
+|------|--------|------|
+| `onConnect()` | No | WebSocket established, before mount |
+| `onMount()` | **Yes** | After all setup (rooms, auth, DI) |
+| `onRehydrate(prevState)` | No | After state restored from localStorage |
+| `onStateChange(changes)` | No | After every state mutation |
+| `onRoomJoin(roomId)` | No | After `$room.join()` |
+| `onRoomLeave(roomId)` | No | After `$room.leave()` |
+| `onAction(action, payload)` | **Yes** | Before action execution (return `false` to cancel) |
+| `onDisconnect()` | No | Connection lost (NOT intentional unmount) |
+| `onDestroy()` | No | Before internal cleanup |
+
+- All hooks are optional — override only what you need
+- All hook errors are caught and logged — they never break the system
+- Constructor is still needed ONLY for `this.onRoomEvent()` subscriptions
+- All hooks are in BLOCKED_ACTIONS — clients cannot call them remotely
+
+## HMR Persistence (v1.14.0)
+
+Data in `static persistent` survives Hot Module Replacement reloads via `globalThis`:
+
+```typescript
+export class LiveMigration extends LiveComponent<typeof LiveMigration.defaultState> {
+  static componentName = 'LiveMigration'
+  static publicActions = ['runMigration'] as const
+  static defaultState = { status: 'idle', lastResult: '' }
+
+  // Define shape and defaults for persistent data
+  static persistent = {
+    cache: {} as Record<string, any>,
+    runCount: 0
+  }
+
+  protected onMount() {
+    this.$persistent.runCount++
+    console.log(`Mount #${this.$persistent.runCount}`) // Survives HMR!
+  }
+
+  async runMigration(payload: { key: string }) {
+    // Check HMR-safe cache
+    if (this.$persistent.cache[payload.key]) {
+      return { cached: true, result: this.$persistent.cache[payload.key] }
+    }
+
+    const result = await expensiveComputation(payload.key)
+    this.$persistent.cache[payload.key] = result
+    this.state.lastResult = result
+    return { cached: false, result }
+  }
+}
+```
+
+**Key facts:**
+- `this.$persistent` reads from `globalThis.__fluxstack_persistent_{ComponentName}`
+- Each component class has its own namespace
+- Defaults come from `static persistent` — initialized once, then persisted
+- Not sent to client — server-only
+- `$persistent` is in BLOCKED_ACTIONS (can't be called from client)
+
+## Singleton Components (v1.14.0)
+
+When `static singleton = true`, only ONE server-side instance exists. All clients share the same state:
+
+```typescript
+export class LiveDashboard extends LiveComponent<typeof LiveDashboard.defaultState> {
+  static componentName = 'LiveDashboard'
+  static singleton = true  // All clients share this instance
+  static publicActions = ['refresh', 'addAlert'] as const
   static defaultState = {
-    // Define state here
+    visitors: 0,
+    alerts: [] as string[],
+    lastRefresh: ''
   }
 
-  // Constructor ONLY needed if:
-  // - Subscribing to room events
-  // - Custom initialization logic
-  // Otherwise, omit it entirely!
+  protected async onMount() {
+    this.state.visitors++
+    this.state.lastRefresh = new Date().toISOString()
+  }
 
-  destroy() {
-    // Cleanup subscriptions, timers, etc.
-    super.destroy()
+  async refresh() {
+    const data = await fetchDashboardData()
+    this.setState(data) // Broadcasts to ALL connected clients
+    return { success: true }
+  }
+
+  async addAlert(payload: { message: string }) {
+    this.state.alerts = [...this.state.alerts, payload.message]
+    // All clients see the new alert instantly
+    return { success: true }
   }
 }
 ```
 
+**How it works:**
+- First client to mount creates the singleton instance
+- Subsequent clients join the existing instance and receive current state
+- `emit` / `setState` / `this.state.x = y` broadcast to ALL connected WebSockets
+- When a client disconnects, it's removed from the singleton's connections
+- When the LAST client disconnects, the singleton is destroyed
+- Stats visible at `/api/live/stats` (shows singleton connection counts)
+
+**Use cases:** Shared dashboards, global migration state, admin panels, live counters
+
 ## State Management
 
 ### Reactive State Proxy (How It Works)
@@ -186,16 +381,86 @@ this.setState(prev => ({
 
 ### setValue (Generic Action)
 
-Built-in action to set any state key from the client:
+Built-in action to set any state key from the client. **Must be explicitly included in `publicActions` to be callable:**
 
 ```typescript
-// Client can call this without defining a custom action
+// Server: opt-in to setValue
+static publicActions = ['increment', 'setValue'] as const  // Must include 'setValue'
+
+// Client can then call:
 await component.setValue({ key: 'count', value: 42 })
 ```
 
+> **Security note:** `setValue` is powerful - it allows the client to set any state key. Only add it to `publicActions` if you trust the client to modify any state field.
+
+### $private — Server-Only State
+
+`$private` is a key-value store that lives **exclusively on the server**. It is NEVER synchronized with the client — no `STATE_UPDATE`, no `STATE_DELTA`, not included in `getSerializableState()`.
+
+Use it for sensitive data like tokens, API keys, internal IDs, or any server-side bookkeeping:
+
+```typescript
+export class Chat extends LiveComponent<typeof Chat.defaultState> {
+  static componentName = 'Chat'
+  static publicActions = ['connect', 'sendMessage'] as const
+  static defaultState = { messages: [] as string[] }
+
+  async connect(payload: { token: string }) {
+    // 🔒 Stays on server — never sent to client
+    this.$private.token = payload.token
+    this.$private.apiKey = await getApiKey()
+
+    // ✅ Only UI data goes to state (synced with client)
+    this.state.messages = await fetchMessages(this.$private.token)
+    return { success: true }
+  }
+
+  async sendMessage(payload: { text: string }) {
+    // Use $private data for server-side logic
+    await postToAPI(this.$private.apiKey, payload.text)
+    this.state.messages = [...this.state.messages, payload.text]
+    return { success: true }
+  }
+}
+```
+
+#### Typed $private (optional)
+
+Pass a second generic to get full autocomplete and type checking:
+
+```typescript
+interface ChatPrivate {
+  token: string
+  apiKey: string
+  retryCount: number
+}
+
+export class Chat extends LiveComponent<typeof Chat.defaultState, ChatPrivate> {
+  static componentName = 'Chat'
+  static publicActions = ['connect'] as const
+  static defaultState = { messages: [] as string[] }
+
+  async connect(payload: { token: string }) {
+    this.$private.token = payload.token     // ✅ autocomplete
+    this.$private.retryCount = 0            // ✅ must be number
+    this.$private.tokkken = 'x'             // ❌ TypeScript error (typo)
+  }
+}
+```
+
+The second generic defaults to `Record<string, any>`, so existing components work without changes.
+
+**Key facts:**
+- Starts as an empty `{}` — no static default needed
+- Mutations do NOT trigger any WebSocket messages
+- Cleared automatically on `destroy()`
+- Lost on rehydration (re-populate in your action handlers)
+- Blocked from remote access (`$private` and `_privateState` are in BLOCKED_ACTIONS)
+- Optional `TPrivate` generic for full type safety
+
 ### getSerializableState
 
-Get current state for serialization:
+Get current state for serialization (does NOT include `$private`):
 
 ```typescript
 const currentState = this.getSerializableState()
@@ -260,11 +525,13 @@ const counter = Live.use(LiveCounter, {
 
 ## Actions
 
-Actions are methods called from the client:
+Actions are methods callable from the client. **Only methods listed in `publicActions` can be called remotely.** Components without `publicActions` deny ALL remote actions.
 
 ```typescript
 // Server-side
 export class LiveForm extends LiveComponent<FormState> {
+  static publicActions = ['submit', 'validate'] as const  // 🔒 REQUIRED
+
   async submit() {
     const { name, email } = this.state
     
@@ -429,10 +696,11 @@ On reconnect, components restore previous state:
 
 1. Client stores signed state in localStorage
 2. On reconnect, sends signed state to server
-3. Server validates signature
+3. Server validates signature (HMAC-SHA256) and **anti-replay nonce**
 4. Component re-hydrated with previous state
+5. State expires after 24 hours (configurable)
 
-No manual code needed - automatic.
+No manual code needed - automatic. Each signed state includes a cryptographic nonce that is consumed on validation, preventing replay attacks.
 
 ## Multi-User Synchronization
 
@@ -530,8 +798,9 @@ app/client/src/live/
 
 Each server file contains:
 - `static componentName` - Component identifier
+- `static publicActions` - **REQUIRED** whitelist of client-callable methods
 - `static defaultState` - Initial state object
-- `static logging` - Per-component log control (optional, see [Live Logging](./live-logging.md))
+- `static logging` - Per-component console log control (optional, prefer `DEBUG_LIVE=true` for debug panel — see [Live Logging](./live-logging.md))
 - Component class extending `LiveComponent`
 - Client link via `import type { Demo as _Client }`
 
@@ -583,21 +852,29 @@ export class MyComponent extends LiveComponent<State> {
 
 **ALWAYS:**
 - Define `static componentName` matching class name
+- Define `static publicActions` listing ALL client-callable methods (MANDATORY)
 - Define `static defaultState` inside the class
 - Use `typeof ClassName.defaultState` for type parameter
 - Use `declare` for each state property (TypeScript type hint)
-- Call `super.destroy()` in destroy method if overriding
+- Use `onMount()` for async initialization (rooms, auth, data fetching)
+- Use `onDestroy()` for cleanup (timers, connections) — sync only
 - Use `emitRoomEventWithState` for state changes in rooms
 - Handle errors in actions (throw Error)
 - Add client link: `import type { Demo as _Client } from '@client/...'`
+- Use `$persistent` for data that should survive HMR reloads
+- Use `static singleton = true` for shared cross-client state
 
 **NEVER:**
+- Omit `static publicActions` (component will deny ALL remote actions)
 - Export separate `defaultState` constant (use static)
 - Create constructor just to call super() (not needed)
 - Forget `static componentName` (breaks minification)
+- Override `destroy()` directly — use `onDestroy()` instead (v1.14.0)
 - Emit room events without subscribing first
 - Store non-serializable data in state
-- Use reserved names for state properties (id, state, ws, room, userId, $room, $rooms, broadcastToRoom, roomType)
+- Use reserved names for state properties (id, state, ws, room, userId, $room, $rooms, $private, $persistent, broadcastToRoom, roomType)
+- Include `setValue` in `publicActions` unless you trust clients to modify any state key
+- Store sensitive data (tokens, API keys, secrets) in `state` — use `$private` instead
 
 **STATE UPDATES (v1.13.0) — all auto-sync via Proxy:**
 ```typescript
@@ -636,6 +913,8 @@ import { liveUploadDefaultState, type LiveUploadState } from '@app/shared'
 export const defaultState: LiveUploadState = liveUploadDefaultState
 
 export class LiveUpload extends LiveComponent<LiveUploadState> {
+  static componentName = 'LiveUpload'
+  static publicActions = ['startUpload', 'updateProgress', 'completeUpload', 'failUpload', 'reset'] as const
   static defaultState = defaultState
 
   constructor(initialState: Partial<typeof defaultState>, ws: any, options?: { room?: string; userId?: string }) {

package/LLMD/resources/live-logging.md

@@ -1,56 +1,100 @@
 # Live Logging
 
-**Version:** 1.12.0 | **Updated:** 2025-02-12
+**Version:** 1.12.1 | **Updated:** 2025-02-22
 
 ## Quick Facts
 
 - Per-component logging control — silent by default
-- Opt-in via `static logging` property on LiveComponent subclasses
+- Two output channels: **console** (`LIVE_LOGGING`) and **debug panel** (`DEBUG_LIVE`)
+- Both off by default — opt-in only
 - 6 categories: `lifecycle`, `messages`, `state`, `performance`, `rooms`, `websocket`
-- Global (non-component) logs controlled by `LIVE_LOGGING` env var
 - `console.error` always visible regardless of config
+- All `liveLog`/`liveWarn` calls are forwarded to the Live Debugger as `LOG` events when `DEBUG_LIVE=true`
 
-## Usage
+## Two Logging Channels
 
-### Enable Logging on a Component
+| Channel | Env Var | Default | Purpose |
+|---------|---------|---------|---------|
+| **Console** | `LIVE_LOGGING` | `false` | Server terminal output |
+| **Debug Panel** | `DEBUG_LIVE` | `false` | Live Debugger WebSocket stream |
+
+The debug panel receives **all** `liveLog`/`liveWarn` calls as `LOG` events (with `category`, `level`, `message`, and `details`) regardless of the `LIVE_LOGGING` console setting. This keeps the console clean while making everything visible in the debug panel.
+
+### Recommended Workflow
+
+- **Normal development**: both off — clean console, no debug overhead
+- **Debugging live components**: `DEBUG_LIVE=true` — open the debug panel at `/api/live/debug/ws`
+- **Quick console debugging**: `LIVE_LOGGING=lifecycle,state` — targeted categories to console
+- **Per-component debugging**: `static logging = true` on the specific component class
+
+## Console Logging
+
+### Per-Component (static logging)
 
 ```typescript
-// app/server/live/LiveCounter.ts
-export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
-  static componentName = 'LiveCounter'
+// app/server/live/LiveChat.ts
+export class LiveChat extends LiveComponent<typeof LiveChat.defaultState> {
+  static componentName = 'LiveChat'
 
-  // ✅ All categories
+  // ✅ All categories to console
   static logging = true
 
   // ✅ Specific categories only
-  static logging = ['lifecycle', 'messages', 'state', 'rooms'] as const
+  static logging = ['lifecycle', 'rooms'] as const
 
   // ✅ Silent (default — omit property or set false)
-  // static logging = false
+  // No static logging needed
 }
 ```
 
-### Global Logs (Non-Component)
+### Global (LIVE_LOGGING env var)
 
-Logs not tied to a specific component (room cleanup, key rotation, etc.) are controlled by the `LIVE_LOGGING` env var:
+Logs not tied to a specific component (connection cleanup, key rotation, etc.):
 
 ```bash
 # .env
-LIVE_LOGGING=true                  # All global logs
+LIVE_LOGGING=true                  # All global logs to console
 LIVE_LOGGING=lifecycle,rooms       # Specific categories only
 # (unset or 'false')              # Silent (default)
 ```
 
+## Debug Panel (DEBUG_LIVE)
+
+When `DEBUG_LIVE=true`, all `liveLog`/`liveWarn` calls emit `LOG` events to the Live Debugger, regardless of `LIVE_LOGGING` or `static logging` settings.
+
+```bash
+# .env
+DEBUG_LIVE=true   # Enable debug panel events
+```
+
+Each `LOG` event contains:
+
+```typescript
+{
+  type: 'LOG',
+  componentId: string | null,
+  componentName: null,
+  data: {
+    category: 'lifecycle' | 'messages' | 'state' | 'performance' | 'rooms' | 'websocket',
+    level: 'info' | 'warn',
+    message: string,
+    details?: unknown   // Extra args passed to liveLog/liveWarn
+  }
+}
+```
+
+The debug panel also receives all other debug events (`COMPONENT_MOUNT`, `STATE_CHANGE`, `ACTION_CALL`, etc.) — see [Live Components](./live-components.md) for the full event list.
+
 ## Categories
 
 | Category | What It Logs |
 |----------|-------------|
 | `lifecycle` | Mount, unmount, rehydration, recovery, migration |
-| `messages` | Received/sent WebSocket messages, file uploads |
+| `messages` | Received/sent WebSocket messages, file uploads, queue operations |
 | `state` | Signing, backup, compression, encryption, validation |
 | `performance` | Monitoring init, alerts, optimization suggestions |
 | `rooms` | Room create/join/leave, emit, broadcast |
-| `websocket` | Connection open/close, auth |
+| `websocket` | Connection open/close/cleanup, pool management, auth |
 
 ## Type Definition
 
@@ -69,12 +113,12 @@ static logging = ['lifecycle', 'messages'] as const
 
 ## API (Framework Internal)
 
-These functions are used by the framework — app developers only need `static logging`:
+These functions are used by the framework — app developers only need `static logging` or env vars:
 
 ```typescript
 import { liveLog, liveWarn, registerComponentLogging, unregisterComponentLogging } from '@core/server/live'
 
-// Log gated by component config
+// Log gated by component config (console) + always forwarded to debug panel
 liveLog('lifecycle', componentId, '🚀 Mounted component')
 liveLog('rooms', componentId, `📡 Joined room '${roomId}'`)
 
@@ -89,70 +133,88 @@ unregisterComponentLogging(componentId)
 ## How It Works
 
 1. **Mount**: `ComponentRegistry` reads `static logging` from the class and calls `registerComponentLogging(componentId, config)`
-2. **Runtime**: All `liveLog()`/`liveWarn()` calls check the registry before emitting
+2. **Runtime**: All `liveLog()`/`liveWarn()` calls:
+   - Forward to the Live Debugger as `LOG` events (when `DEBUG_LIVE=true`)
+   - Check the registry before emitting to console (when `LIVE_LOGGING` or `static logging` is active)
 3. **Unmount**: `unregisterComponentLogging(componentId)` removes the entry
 4. **Global logs**: Fall back to `LIVE_LOGGING` env var when `componentId` is `null`
 
 ## Examples
 
-### Debug a Specific Component
+### Debug via Panel (Recommended)
+
+```bash
+# .env
+DEBUG_LIVE=true
+# No LIVE_LOGGING needed — console stays clean
+```
+
+Open the debug panel WebSocket at `/api/live/debug/ws` to see all events in real-time.
+
+### Debug a Specific Component (Console)
 
 ```typescript
-// Only this component will show logs
+// Only this component will show console logs
 export class LiveChat extends LiveComponent<typeof LiveChat.defaultState> {
   static componentName = 'LiveChat'
-  static logging = true  // See everything for this component
+  static logging = true  // See everything for this component in console
 }
 
-// All other components remain silent
+// All other components remain silent in console
 export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
   static componentName = 'LiveCounter'
-  // No static logging → silent
+  // No static logging → silent in console
 }
 ```
 
-### Monitor Only Room Activity
+### Monitor Only Room Activity (Console)
 
 ```typescript
 export class LiveChat extends LiveComponent<typeof LiveChat.defaultState> {
   static componentName = 'LiveChat'
-  static logging = ['rooms'] as const  // Only room events
+  static logging = ['rooms'] as const  // Only room events in console
 }
 ```
 
 ### Production: Silent Everywhere
 
 ```bash
-# .env (no LIVE_LOGGING set)
-# All components without static logging → silent
-# Components with static logging still log (remove for production)
+# .env (no LIVE_LOGGING, no DEBUG_LIVE)
+# Console: silent
+# Debug panel: disabled
 ```
 
 ## Files Reference
 
 | File | Purpose |
 |------|---------|
-| `core/server/live/LiveLogger.ts` | Logger implementation, registry, shouldLog logic |
-| `core/server/live/ComponentRegistry.ts` | Reads `static logging` on mount/unmount |
+| `core/server/live/LiveLogger.ts` | Logger implementation, registry, shouldLog logic, debugger forwarding |
+| `core/server/live/LiveDebugger.ts` | Debug event bus, `LOG` event type, debug client management |
+| `core/server/live/ComponentRegistry.ts` | Reads `static logging` on mount/unmount, uses `liveLog` |
 | `core/server/live/websocket-plugin.ts` | Uses `liveLog` for WebSocket events |
+| `core/server/live/WebSocketConnectionManager.ts` | Uses `liveLog`/`liveWarn` for connection pool management |
+| `core/server/live/FileUploadManager.ts` | Uses `liveLog`/`liveWarn` for upload operations |
 | `core/server/live/StateSignature.ts` | Uses `liveLog`/`liveWarn` for state operations |
 | `core/server/live/LiveRoomManager.ts` | Uses `liveLog` for room lifecycle |
 | `core/server/live/LiveComponentPerformanceMonitor.ts` | Uses `liveLog`/`liveWarn` for perf |
+| `config/system/runtime.config.ts` | `DEBUG_LIVE` env var config |
 | `core/types/types.ts` | `LiveComponent` base class with `static logging` property |
 
 ## Critical Rules
 
 **ALWAYS:**
 - Use `as const` on logging arrays for type safety
-- Keep components silent by default in production
+- Keep components silent by default (no `static logging`)
+- Use `DEBUG_LIVE=true` for debugging instead of `static logging` on components
 - Use specific categories instead of `true` when possible
 
 **NEVER:**
 - Use `console.log` directly in Live Component code — use `liveLog()`
 - Forget that `console.error` is always visible (not gated)
+- Enable `LIVE_LOGGING` or `DEBUG_LIVE` in production
 
 ## Related
 
 - [Live Components](./live-components.md) - Base component system
 - [Live Rooms](./live-rooms.md) - Room system (logged under `rooms` category)
-- [Environment Variables](../config/environment-vars.md) - `LIVE_LOGGING` reference
+- [Environment Variables](../config/environment-vars.md) - `LIVE_LOGGING` and `DEBUG_LIVE` reference