Add Live Component Debugger with real-time event streaming#66
Merged
MarcosBrendonDePaula merged 15 commits intomainfrom Feb 22, 2026
Merged
Add Live Component Debugger with real-time event streaming#66MarcosBrendonDePaula merged 15 commits intomainfrom
MarcosBrendonDePaula merged 15 commits intomainfrom
Conversation
Adds a visual debugger that connects via WebSocket to monitor all Live Component activity in real-time. Captures state changes, action calls, room events, connections, and errors — all organized per component. Server-side: - LiveDebugger.ts: event bus singleton with circular buffer, component snapshots, and debug client management (auto-enabled in development) - Debug WebSocket endpoint at /api/live/debug/ws for real-time streaming - HTTP endpoints for snapshot, events, component state, and toggle - Instrumented LiveComponent (setState, proxy, executeAction, rooms) and ComponentRegistry (mount, unmount, connections) with debug events Client-side: - useLiveDebugger hook: connects to debug WS, manages event stream, component tracking, filtering, pause/resume - LiveDebuggerPanel: full-page UI with component sidebar, event timeline with expandable JSON, state inspector, type filtering, and search - Accessible at /debugger route https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
The LiveDebugger module uses process.env which doesn't exist in the browser. Instead of importing it directly in types.ts (which is shared between server and client), use an injectable pattern: define a lightweight interface in types.ts and inject the real instance from ComponentRegistry at server startup. https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
Replace the full-page /debugger route with an in-page floating overlay
component that shows debug data directly on the page being developed.
LiveDebugger overlay:
- Collapsible bar at the bottom of the screen (click to expand)
- Component sidebar with live stats (state changes, actions, errors)
- Event feed with expandable JSON, color-coded by type
- State inspector tab showing current component state
- Pause/resume, clear, auto-scroll controls
debugLabel option:
- Developers can set a custom label for each component instance:
Live.use(LiveCounter, { debugLabel: 'Header Counter' })
- The label flows from client -> mount payload -> server -> debugger
- Shown prominently in the debugger instead of the UUID component ID
- Component class name shown as subtitle when label is set
https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
The $field() helper internally calls the setValue action to sync form field values to the server, but LiveForm didn't include it in its publicActions whitelist, causing "Action 'setValue' is not callable". https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
Major UX improvements: - Floating draggable window instead of fixed bottom bar that blocked clicks - Resizable from bottom-right corner - Keyboard shortcut Ctrl+Shift+D to toggle open/close - Event type filter chips grouped by category (Lifecycle, State, Actions, Rooms, WS, Errors) with live counts - Search bar to filter events by content - Auto-scroll with manual scroll detection and "scroll to bottom" button - Minimized state is a small badge showing component count (not a full bar) - Badge shows error indicator when errors are present https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
Clicking a component in the sidebar no longer forces the tab back to 'events' — it stays on whichever tab (events/state) was already active. https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
New "Rooms" tab shows: - Active rooms with member count - Components in each room with stats - Recent room activity feed (JOIN, LEAVE, EMIT events) Rooms are derived from component snapshots in real-time. https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
The old viewer truncated nested data at depth 2 (showing {...4} for
objects), making it impossible to inspect deep structures like chat
messages or room state.
New tree viewer:
- Click arrows to expand/collapse any object or array
- Top-level state auto-expands, nested nodes start collapsed
- Inline preview of collapsed nodes (e.g. { id: "tech", name: "..." })
- Shows item/key counts when expanded
- No depth limit - drill as deep as needed
- Strings display up to 120 chars before truncating
https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
Clicking to collapse/expand JSON nodes inside an event's detail area was bubbling up and toggling the parent event row closed. https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
Server side: - registerDebugClient() now checks _enabled flag - If disabled, sends DEBUG_DISABLED message and closes the WebSocket - Welcome message includes enabled status Client side: - Hook tracks serverDisabled state - Stops auto-reconnect loop when server reports disabled - LiveDebugger renders nothing (null) when server is disabled - New force prop to override and show debugger anyway Flow: - Development: auto-enabled, debugger works normally - Production: server rejects debug WS, client renders nothing, no reconnect loop, zero resource usage - Production + DEBUG_LIVE=true: server accepts, debugger works https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
DEBUG_LIVE now takes priority over NODE_ENV when explicitly set: - DEBUG_LIVE=true -> enabled (any environment) - DEBUG_LIVE=false -> disabled (any environment) - Not set -> enabled in development, disabled otherwise https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
…aw env vars LiveDebugger now reads `debugLive` from `appRuntimeConfig` (config/system/runtime.config.ts) instead of parsing process.env directly. The config defaults to true in development, false otherwise, and can be overridden via the DEBUG_LIVE env var. https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
…e, word wrap Adds a configuration panel to both the floating debugger widget (new Settings tab with gear icon) and the full-page debugger panel (collapsible settings drawer). Settings include: - Font size (XS/SM/MD/LG) for adjusting text readability - Max events buffer size (100/300/500/1000) - Show/hide timestamps toggle - Compact mode for denser event display - Word wrap toggle for long data values - Reset to defaults button All settings persist to localStorage and are shared between both debugger views. https://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a comprehensive debugging system for Live Components that provides real-time visibility into component lifecycle, state changes, actions, and room events. Includes server-side event capture, WebSocket streaming, and client-side UI components for inspection.
Key Changes
Server-side debugger (
core/server/live/LiveDebugger.ts): Event bus that captures and tracks:Client hook (
core/client/hooks/useLiveDebugger.ts): React hook that:UI Components:
core/client/components/LiveDebugger.tsx: Compact floating panel with tabs for events and state inspectionapp/client/src/live/LiveDebuggerPanel.tsx: Full-featured debugger panel with detailed event timeline, component list, state inspector, and advanced filteringWebSocket routes (
core/server/live/websocket-plugin.ts):/api/live/debug/ws: WebSocket endpoint for streaming debug events/api/live/debug/snapshot: REST endpoint for current component state/api/live/debug/events: REST endpoint for event history with filteringIntegration: Debugger is auto-enabled in development mode and injected into
LiveComponentclass viaComponentRegistryto track all instrumented eventsNotable Implementation Details
debugLabelfor easier identificationDEBUG_LIVE=trueenvironment variable is sethttps://claude.ai/code/session_01UjPuBmfmnczYxAXNVTYdKW