Add lifecycle hooks, HMR persistence, and singleton components

[MarcosBrendonDePaula]

Summary

This PR introduces a comprehensive DX enhancement to LiveComponent with lifecycle hooks, HMR-safe persistent state, singleton component support, and improved error messages for missing publicActions entries.

Key Changes

1. Lifecycle Hooks (v1.14.0)

• onConnect() - Called when WebSocket connection is established (before mount)
• onMount() - Called after component is fully mounted; supports async initialization
• onDisconnect() - Called when connection drops unexpectedly (before destroy)
• onDestroy() - Called before internal cleanup; replaces constructor workarounds
• onStateChange(changes) - Called after any state mutation (proxy or setState)
• onRoomJoin(roomId) / onRoomLeave(roomId) - Called when joining/leaving rooms
• onRehydrate(previousState) - Called after state is restored from localStorage
• onAction(action, payload) - Called before action execution; can return false to cancel

All hooks are optional, error-safe (caught and logged), and blocked from client execution.

2. HMR Persistence (static persistent + $persistent)

• Define shape and defaults via static persistent = { ... }
• Access via this.$persistent at runtime
• Data stored in globalThis and survives hot module reloads
• Useful for caches, counters, and expensive computations that should persist across HMR

3. Singleton Components (static singleton = true)

• Only one server-side instance exists for the component
• All clients share the same state
• State updates broadcast to every connected client via emit override
• ComponentRegistry tracks singleton instances and connections
• New clients joining a singleton receive current state and are added to broadcast list

4. Better publicActions Error Messages

• When a method exists but is missing from publicActions, error message now includes:
  • The action name
  • The component name
  • Suggestion to add it to publicActions
• Generic error for methods that don't exist at all

5. Security: BLOCKED_ACTIONS Expansion

• All lifecycle hooks (onMount, onDestroy, onConnect, onDisconnect, onStateChange, onRoomJoin, onRoomLeave, onRehydrate, onAction) are blocked from client execution
• $persistent property is blocked
• _setEmitOverride() internal method is blocked

Implementation Details

ComponentRegistry Changes

• Added singletons Map to track singleton instances and their connected clients
• mountComponent() now checks for singleton flag and returns existing instance if found
• New clients joining a singleton are added to the broadcast connections map
• Emit override injected into singleton instances to broadcast to all connections
• Lifecycle hooks (onConnect, onMount, onRehydrate) called at appropriate points
• New ensureWsData() helper method to initialize WebSocket data structure

LiveComponent Changes

• Added $persistent getter that reads/writes to globalThis.__fluxstack_persistent_${componentName}
• Added _setEmitOverride() method for singleton broadcast support
• All lifecycle hook methods added as protected (optional) methods
• State proxy now calls onStateChange() after mutations
• Room join/leave methods call onRoomJoin() / onRoomLeave() hooks
• executeAction() calls onAction() before execution and respects false return value

Test Coverage

• 870 lines of comprehensive tests covering all new features
• Tests for lifecycle order, async onMount, HMR persistence across instances
• Singleton broadcast behavior with multiple connections
• Error message validation for missing publicActions
• Security tests ensuring hooks cannot be called from client
• Edge cases: errors in hooks don't break system, unchanged state doesn't trigger onStateChange

Breaking Changes

None. All changes are additive and backward compatible.

Documentation

Updated LLMD/resources/live-components.md with:

• Lifecycle hook reference with examples
• Lifecycle order diagram
• HMR persistence guide with cache example
• Singleton component pattern documentation

https://claude.ai/code/session_01V12t1cDiYmAvDsMJsYaLys