@zeix/cause-effect 0.17.0 → 0.17.1

package/.ai-context.md

@@ -9,10 +9,11 @@ Cause & Effect is a modern reactive state management library for JavaScript/Type
 ### Signal Types
 - **Signal**: Base interface with `.get()` method for value access
 - **State**: Mutable signals for primitive values (numbers, strings, booleans)
+- **Ref**: Signal wrappers for external objects that change outside the reactive system (DOM elements, Map, Set, Date, third-party objects)
+- **Computed**: Read-only derived signals with automatic memoization, reducer capabilities and async handling
 - **Store**: Mutable signals for objects with individually reactive properties
 - **List**: Mutable signals for arrays with individually reactive items
-- **Collection**: Read-only derived arrays with item-level memoization and async support
-- **Computed**: Read-only derived signals with automatic memoization, reducer capabilities and asyc handling
+- **Collection**: Interface for reactive array-like collections (implemented by DerivedCollection)
 - **Effect**: Side effect handlers that react to signal changes
 
 ### Key Principles
@@ -29,9 +30,10 @@ cause-effect/
 ├── src/
 │   ├── classes/
 │   │   ├── state.ts       # Mutable state signals (State)
+│   │   ├── ref.ts         # Signal wrapper for external objects (Ref)
 │   │   ├── store.ts       # Object stores with reactive properties
 │   │   ├── list.ts        # Array stores with stable keys (List)
-│   │   ├── collection.ts  # Read-only derived arrays (Collection)
+│   │   ├── collection.ts  # Collection interface and DerivedCollection
 │   │   └── computed.ts    # Computed/derived signals (Memo and Task)
 |   ├── signal.ts      # Base signal types and utilities
 │   ├── effect.ts      # Effect system (createEffect)
@@ -55,6 +57,10 @@ const count = new State(42)
 const name = new State('Alice')
 const actions = new State<'increment' | 'decrement' | 'reset'>('reset')
 
+// Ref signals for external objects
+const elementRef = new Ref(document.getElementById('status'))
+const cacheRef = new Ref(new Map([['key', 'value']]))
+
 // Store signals for objects  
 const user = createStore({ name: 'Alice', age: 30 })
 
@@ -181,15 +187,19 @@ const firstTodo = todoList.byKey('task1')
 firstTodo?.completed.set(true) // Mark completed
 
 // Collections for read-only derived data
-const completedTodos = new Collection(todoList, todo => 
+const completedTodos = new DerivedCollection(todoList, todo => 
   todo.completed ? { ...todo, status: 'done' } : null
 ).filter(Boolean) // Remove null values
 
 // Async collections for enhanced data
-const todoWithDetails = new Collection(todoList, async (todo, abort) => {
+const todoWithDetails = new DerivedCollection(todoList, async (todo, abort) => {
   const response = await fetch(`/todos/${todo.id}/details`, { signal: abort })
   return { ...todo, details: await response.json() }
 })
+
+// Element collections for DOM reactivity
+const buttons = createElementCollection(document.body, 'button')
+const inputs = createElementCollection(form, 'input[type="text"]')
 ```
 
 ### Derived State
@@ -265,6 +275,10 @@ const processedItems = items.deriveCollection(item => ({
 const finalResults = processedItems.deriveCollection(item => 
   item.processed ? { summary: `${item.name} at ${item.timestamp}` } : null
 ).filter(Boolean)
+
+// Ref signal manual notifications
+elementRef.notify() // Notify when DOM element changes externally
+cacheRef.notify()   // Notify when Map/Set changes externally
 ```
 
 ## Build and Development

package/.cursorrules

@@ -6,9 +6,11 @@ TypeScript/JavaScript reactive state management library using signals pattern
 ## Core Concepts
 - Signals: Base reactive primitives with .get() method
 - State: new State() for primitives/simple values  
+- Ref: new Ref() for external objects (DOM, Map, Set) requiring manual .notify()
 - Computed: new Memo() for derived/memoized values and new Task() for asynchronous computations
 - Store: createStore() for objects with reactive properties
 - List: new List() for arrays with stable keys and reactive items
+- Collection: Interface for reactive collections (DerivedCollection, ElementCollection)
 - Effects: createEffect() for side effects
 
 ## Code Style
@@ -31,9 +33,12 @@ TypeScript/JavaScript reactive state management library using signals pattern
 
 ## File Structure
 - src/signal.ts - Base signal types
-- src/state.ts - Mutable state signals  
-- src/store.ts - Object stores
-- src/computed.ts - Computed signals
+- src/classes/state.ts - Mutable state signals
+- src/classes/ref.ts - Signal wrappers for external objects
+- src/classes/store.ts - Object stores
+- src/classes/list.ts - Array stores with stable keys
+- src/classes/collection.ts - Collection interface and DerivedCollection
+- src/classes/computed.ts - Computed signals
 - src/effect.ts - Effect system
 - src/system.ts - Core reactivity (watchers, batching)
 - index.ts - Main exports

package/.github/copilot-instructions.md

@@ -8,18 +8,20 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 
 - **Signals**: Base reactive primitives with `.get()` method
 - **State**: Mutable signals for primitive values (`new State()`)
+- **Ref**: Signal wrappers for external objects that change outside reactive system (`new Ref()`)
 - **Computed**: Derived read-only signals with memoization, reducer capabilities and async support (`new Memo()`, `new Task()`)
 - **Store**: Mutable signals for objects with reactive properties (`createStore()`)
 - **List**: Mutable signals for arrays with stable keys and reactive entries (`new List()`)
-- **Collection**: Read-only derived arrays with item-level memoization and async support (`new Collection()`)
+- **Collection**: Interface for reactive collections (implemented by `DerivedCollection`)
 - **Effects**: Side effect handlers that react to signal changes (`createEffect()`)
 
 ## Key Files Structure
 
 - `src/classes/state.ts` - Mutable state signals
+- `src/classes/ref.ts` - Signal wrappers for external objects (DOM, Map, Set, etc.)
 - `src/classes/store.ts` - Object stores with reactive properties
 - `src/classes/list.ts` - Array stores with stable keys and reactive items
-- `src/classes/collection.ts` - Read-only derived arrays with memoization
+- `src/classes/collection.ts` - Collection interface and DerivedCollection implementation
 - `src/classes/computed.ts` - Computed/derived signals
 - `src/signal.ts` - Base signal types and utilities
 - `src/effect.ts` - Effect system
@@ -77,6 +79,10 @@ const count = new State(42)
 const name = new State('Alice')
 const actions = new State<'increment' | 'decrement'>('increment')
 
+// Ref for external objects
+const elementRef = new Ref(document.getElementById('status'))
+const cacheRef = new Ref(new Map())
+
 // Store for objects
 const user = createStore({ name: 'Alice', age: 30 })
 
@@ -145,7 +151,6 @@ function isSignal<T extends {}>(value: unknown): value is Signal<T>
 const items = new List(['a', 'b', 'c'])
 
 // String prefix keys
-// Lists with stable keys
 const items = new List(['apple', 'banana'], 'fruit')
 // Creates keys: 'fruit0', 'fruit1'
 
@@ -156,7 +161,7 @@ const users = new List([
 ], user => user.id) // Uses user.id as stable key
 
 // Collections derived from lists
-const userProfiles = new Collection(users, user => ({
+const userProfiles = new DerivedCollection(users, user => ({
   ...user,
   displayName: `${user.name} (ID: ${user.id})`
 }))

package/CLAUDE.md

@@ -6,21 +6,20 @@ Cause & Effect is a reactive state management library that implements the signal
 
 ### Core Philosophy
 - **Granular Reactivity**: Changes propagate only to dependent computations, minimizing unnecessary work
-- **Explicit Dependencies**: No hidden subscriptions or magic - dependencies are tracked through `.get()` calls
-- **Functional Design**: Immutable by default, with pure functions and predictable state updates
-- **Type Safety First**: Comprehensive TypeScript support with strict generic constraints
+- **Explicit Dependencies**: Dependencies are tracked through `.get()` calls, no hidden subscriptions
+- **Type Safety First**: Comprehensive TypeScript support with strict generic constraints (`T extends {}`)
 - **Performance Conscious**: Minimal overhead through efficient dependency tracking and batching
 
 ## Mental Model for Understanding the System
 
 Think of signals as **observable cells** in a spreadsheet:
-- **State signals** are like input cells where you can directly enter values
-- **Computed signals** are like formula cells that automatically recalculate when their dependencies change
-- **Store signals** are like structured data tables where individual columns (properties) are reactive
-- **List signals** with stable keys are like tables with persistent row IDs that survive sorting and reordering
-- **Effects** are like event handlers that trigger side effects when cells change
-
-The key insight is that the system tracks which cells (signals) are read during computation, creating an automatic dependency graph that ensures minimal and correct updates.
+- **State signals** are input cells for primitive values and objects
+- **Ref signals** are cells that reference external objects (DOM, Map, Set) requiring manual notification
+- **Computed signals** are formula cells that automatically recalculate when dependencies change
+- **Store signals** are structured tables where individual columns (properties) are reactive
+- **List signals** are tables with stable row IDs that survive sorting and reordering
+- **Collection signals** are read-only derived tables with item-level memoization
+- **Effects** are event handlers that trigger side effects when cells change
 
 ## Architectural Deep Dive
 
@@ -45,72 +44,52 @@ interface MutableSignal<T extends {}> extends Signal<T> {
   update(fn: (current: T) => T): void
 }
 
-// Collection signals are read-only derived arrays
-interface Collection<T extends {}, U extends {}> extends Signal<T[]> {
-  at(index: number): Computed<T> | undefined
-  byKey(key: string): Computed<T> | undefined
-  deriveCollection<R extends {}>(callback: CollectionCallback<R, T>): Collection<R, T>
+// Collection interface - implemented by various collection types
+interface Collection<T extends {}> {
+  get(): T[]
+  at(index: number): Signal<T> | undefined
+  byKey(key: string): Signal<T> | undefined
+  deriveCollection<R extends {}>(callback: CollectionCallback<R, T>): Collection<R>
 }
 ```
 
 The generic constraint `T extends {}` is crucial - it excludes `null` and `undefined` at the type level, preventing common runtime errors and making the API more predictable.
 
-### Collection Signal Deep Dive
-
-Collection signals provide read-only derived array transformations with automatic memoization:
-
-1. **Source Dependency**: Collections derive from Lists or other Collections
-2. **Item-level Memoization**: Each item transformation is individually memoized
-3. **Async Support**: Supports Promise-based transformations with cancellation
-4. **Stable Keys**: Maintains the same stable key system as source Lists
-5. **Chainable**: Collections can derive from other Collections for data pipelines
-
-Key implementation details:
-- Individual items are Computed signals, not mutable signals
-- Automatically handles source List changes (add, remove, sort)
-- Supports both sync and async transformation callbacks
-- Lazy evaluation - transformations only run when accessed
-- Smart watcher management - only creates watchers when change listeners are active
-- Order preservation through internal `#order` array synchronized with source
+### Collection Architecture
 
-Collection Architecture:
-- **BaseCollection**: Core implementation with signal management and event handling
-- **Computed Creation**: Each source item gets its own computed signal with transformation callback
-- **Source Synchronization**: Listens to source events and maintains parallel structure
-- **Memory Efficiency**: Automatically cleans up computed signals when source items are removed
+Collections are an interface implemented by different reactive array types:
 
-### Store Signal Deep Dive
+**DerivedCollection**: Read-only transformations of Lists or other Collections
+- Item-level memoization with Computed signals
+- Async support with automatic cancellation
+- Chainable for data pipelines
 
-Store signals are the most complex part of the system. They transform plain objects or arrays into reactive data structures:
+**ElementCollection**: DOM element collections with MutationObserver
+- Uses Ref signals for elements that change externally
+- Watches attributes and childList mutations
+- Stable keys for persistent element identity
 
-1. **Property Proxification**: Each property becomes its own signal
-2. **Nested Reactivity**: Objects within objects recursively become stores
-3. **Array Support**: Arrays get special treatment with length tracking and efficient sorting
-4. **Dynamic Properties**: Runtime addition/removal of properties with proper reactivity
+Key patterns:
+- Collections return arrays of values via `.get()`
+- Individual items accessed as signals via `.at()` and `.byKey()`
+- All collections support `.deriveCollection()` for chaining
 
-Key implementation details:
-- Uses Proxy to intercept property access
-- Maintains internal signal instances for each property
-- Supports change notifications for fine-grained updates
-- Handles edge cases like symbol properties and prototype chain
-- For lists: maintains stable keys that persist through sorting, splicing, and reordering
-- Provides specialized methods: `byKey()`, `keyAt()`, `indexOfKey()`, `splice()` for array manipulation
+### Store and List Architecture
 
-### MutableComposite Architecture
+**Store signals** (`createStore`): Transform objects into reactive data structures
+- Each property becomes its own signal via Proxy
+- Built on `Composite` class for signal management
+- Dynamic property addition/removal with proper reactivity
 
-Both Store and List signals are built on top of `MutableComposite`, which provides the common reactive property management:
+**List signals** (`new List`): Arrays with stable keys and reactive items
+- Maintains stable keys that survive sorting and reordering
+- Built on `Composite` class for consistent signal management
+- Provides `byKey()`, `keyAt()`, `indexOfKey()` for key-based access
 
-1. **Signal Management**: Maintains a `Map<string, MutableSignal>` of property signals
-2. **Change Detection**: Uses `diff()` to detect actual changes before triggering updates
-3. **Event System**: Emits granular notifications for add/change/remove operations
-4. **Validation**: Enforces type constraints and prevents invalid mutations
-5. **Performance**: Only creates signals when properties are first accessed or added
-
-Key implementation details:
-- Lazy signal creation for better memory usage
-- Efficient batch updates through change detection
-- Support for both object and array data structures
-- Automatic cleanup when properties are removed
+**Composite Architecture**: Shared foundation for Store and List
+- `Map<string, Signal>` for property/item signals
+- Event system for granular add/change/remove notifications
+- Lazy signal creation and automatic cleanup
 
 ### Computed Signal Memoization Strategy
 
@@ -134,51 +113,41 @@ Computed signals implement smart memoization:
 ```typescript
 const count = new State(0)
 const theme = new State<'light' | 'dark'>('light')
-const user = new State<User>({ id: 1, name: 'John Doe', email: 'john@example.com' }) // Replace entire user object
+```
+
+**Ref Signals (`new Ref`)**:
+- External objects that change outside the reactive system
+- DOM elements, Map, Set, Date objects, third-party APIs
+- Requires manual `.notify()` when external object changes
+
+```typescript
+const elementRef = new Ref(document.getElementById('status'))
+const cacheRef = new Ref(new Map())
+// When external change occurs: cacheRef.notify()
 ```
 
 **Store Signals (`createStore`)**:
 - Objects where individual properties change independently
-- Nested data structures
-- Form state where fields update individually
-- Configuration objects with multiple settings
 
 ```typescript
-const form = createStore({
-  email: '',
-  password: '',
-  errors: { email: null, password: null }
-})
-// form.email.set('user@example.com') // Only email subscribers react
+const user = createStore({ name: 'Alice', email: 'alice@example.com' })
+user.name.set('Bob') // Only name subscribers react
 ```
 
 **List Signals (`new List`)**:
-
-```ts
-// Lists with stable keys
+```typescript
 const todoList = new List([
-  { id: 'task1', text: 'Learn signals' },
-  { id: 'task2', text: 'Build app' }
-], todo => todo.id) // Use todo.id as stable key
-
-// Access by stable key instead of index
-const firstTodo = todoList.byKey('task1')
-firstTodo?.text.set('Learn signals deeply')
-
-// Sort while maintaining stable references
-todoList.sort((a, b) => a.text.localeCompare(b.text))
+  { id: 'task1', text: 'Learn signals' }
+], todo => todo.id)
+const firstTodo = todoList.byKey('task1') // Access by stable key
 ```
 
-**Collection Signals (`new Collection`)**:
-
-```ts
-// Read-only derived arrays with memoization
-const completedTodos = new Collection(todoList, todo => 
+**Collection Signals (`new DerivedCollection`)**:
+```typescript
+const completedTodos = new DerivedCollection(todoList, todo => 
   todo.completed ? { ...todo, status: 'done' } : null
 )
-
-// Async transformations with cancellation
-const todoDetails = new Collection(todoList, async (todo, abort) => {
+const todoDetails = new DerivedCollection(todoList, async (todo, abort) => {
   const response = await fetch(`/todos/${todo.id}`, { signal: abort })
   return { ...todo, details: await response.json() }
 })
@@ -245,19 +214,13 @@ The library provides several layers of error handling:
 4. **Helper Functions**: `resolve()` and `match()` for ergonomic error handling
 
 ```typescript
-// Robust async data fetching with error handling
+// Error handling with resolve() and match()
 const apiData = new Task(async (prev, abort) => {
-  try {
-    const response = await fetch('/api/data', { signal: abort })
-    if (!response.ok) throw new Error(`HTTP ${response.status}`)
-    return response.json()
-  } catch (error) {
-    if (abort.aborted) return prev // Cancelled, not an error
-    throw error // Real error
-  }
+  const response = await fetch('/api/data', { signal: abort })
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+  return response.json()
 })
 
-// Pattern matching for comprehensive state handling
 createEffect(() => {
   match(resolve({ apiData }), {
     ok: ({ apiData }) => updateUI(apiData),
@@ -267,199 +230,70 @@ createEffect(() => {
 })
 ```
 
-### Performance Optimization Techniques
-
-1. **Batching Updates**: Use `batchSignalWrites()` for multiple synchronous updates
-2. **Selective Dependencies**: Structure computed signals to minimize dependencies
-3. **Cleanup Management**: Properly dispose of effects to prevent memory leaks
-4. **Shallow vs Deep Equality**: Use appropriate comparison strategies
+### Performance Optimization
 
+**Batching**: Use `batchSignalWrites()` for multiple updates
 ```typescript
-// Create a user store
-const user = createStore<{ id: number, name: string, email: string, age?: number }>({
-	id: 1,
-	name: 'John Doe',
-	email: 'john@example.com'
-})
-
-// Batch multiple updates to prevent intermediate states
 batchSignalWrites(() => {
-  user.name.set('Alice Doe')
-  user.age.set(30)
+  user.name.set('Alice')
   user.email.set('alice@example.com')
-}) // Only triggers effects once at the end
-
-// Optimize computed dependencies
-const userDisplay = new Memo(() => {
-  const { name, email } = user.get() // Gets entire object, will rerun also if age changes
-  return `${name} <${email}>`
-})
-
-// Better: more granular dependencies
-const userDisplay = new Memo(() => {
-  return `${user.name.get()} <${user.email.get()}>` // Only depends on name/email
-})
+}) // Single effect trigger
 ```
 
-## Integration Patterns
-
-### Framework Integration
-The library is framework-agnostic but integrates well with:
-- **React**: Use effects to trigger re-renders
-- **Vue**: Integrate with Vue's reactivity system
-- **Svelte**: Use effects to update Svelte stores
-- **Vanilla JS**: Direct DOM manipulation in effects
-
-### Testing Strategies
-- **Unit Testing**: Test signal logic in isolation
-- **Integration Testing**: Test effect chains and async operations
-- **Mock Testing**: Mock external dependencies in computed signals
-- **Property Testing**: Use random inputs to verify invariants
-
-### Debugging Techniques
-- Use `resolve()` to inspect multiple signal states at once
-- Add logging effects for debugging reactivity chains
-- Use AbortSignal inspection for async operation debugging
-- Leverage TypeScript for compile-time dependency analysis
+**Granular Dependencies**: Structure computed signals to minimize dependencies
+```typescript
+// Bad: depends on entire user object
+const display = new Memo(() => user.get().name + user.get().email)
+// Good: only depends on specific properties  
+const display = new Memo(() => user.name.get() + user.email.get())
+```
 
-## Common Pitfalls and How to Avoid Them
+## Common Pitfalls
 
 1. **Infinite Loops**: Don't update signals within their own computed callbacks
-2. **Stale Closures**: Be careful with captured values in async operations
-3. **Memory Leaks**: Always clean up effects when components unmount
-4. **Over-reactivity**: Structure data to minimize unnecessary updates
-5. **Async Race Conditions**: Trust the automatic cancellation, don't fight it
+2. **Memory Leaks**: Clean up effects when components unmount  
+3. **Over-reactivity**: Structure data to minimize unnecessary updates
+4. **Async Race Conditions**: Trust automatic cancellation with AbortSignal
 
-## Advanced Use Cases
+## Advanced Patterns
 
-### Building Reactive Data Structures
+### Event Bus with Type Safety
 ```typescript
-// Reactive list with computed properties
-const todos = new List<Todo[]>([])
-const completedCount = new Memo(() => 
-  todos.get().filter(todo => todo.completed).length
-)
-const remainingCount = new Memo(() => 
-  todos.get().length - completedCount.get()
-)
-```
-
-### Reactive State Machines
-```typescript
-const state = new State<'idle' | 'loading' | 'success' | 'error'>('idle')
-const canRetry = () => state.get() === 'error'
-const isLoading = () => state.get() === 'loading'
-```
-
-### Cross-Component Communication
-```typescript
-// Component ownership pattern: The component that emits events owns the store
-// Component B (the emitter) declares the shape of events it will emit upfront
-type EventBusSchema = {
+type Events = {
   userLogin: { userId: number; timestamp: number }
   userLogout: { userId: number }
-  userUpdate: { userId: number; profile: { name: string } }
 }
 
-// Initialize the event bus with proper typing
-const eventBus = createStore<EventBusSchema>({
+const eventBus = createStore<Events>({
   userLogin: UNSET,
-  userLogout: UNSET,
-  userUpdate: UNSET,
+  userLogout: UNSET
 })
 
-// Type-safe emit function
-const emit = <K extends keyof EventBusSchema>(
-  event: K,
-  data: EventBusSchema[K],
-) => {
+const emit = <K extends keyof Events>(event: K, data: Events[K]) => {
   eventBus[event].set(data)
 }
 
-// Type-safe on function with proper callback typing
-const on = <K extends keyof EventBusSchema>(
-  event: K,
-  callback: (data: EventBusSchema[K]) => void,
-) =>
+const on = <K extends keyof Events>(event: K, callback: (data: Events[K]) => void) =>
   createEffect(() => {
     const data = eventBus[event].get()
     if (data !== UNSET) callback(data)
   })
-
-// Usage example:
-// Component A listens for user events
-on('userLogin', (data) => {
-  console.log('User logged in:', data) // data is properly typed
-})
-
-// Component B emits user events
-eventBus.userLogin.set({ userId: 123, timestamp: Date.now() })
 ```
 
-### Reactive Data Processing Pipelines
-
+### Data Processing Pipelines
 ```typescript
-// Build complex data processing with Collections
-const rawData = new List([
-  { id: 1, value: 10, category: 'A' },
-  { id: 2, value: 20, category: 'B' },
-  { id: 3, value: 15, category: 'A' }
-])
-
-// Multi-step transformation pipeline
-const processedData = rawData
+const rawData = new List([{ id: 1, value: 10 }])
+const processed = rawData
   .deriveCollection(item => ({ ...item, doubled: item.value * 2 }))
-  .deriveCollection(item => ({ ...item, category: item.category.toLowerCase() }))
-
-const categoryTotals = new Collection(processedData, async (item, abort) => {
-  // Simulate async processing
-  await new Promise(resolve => setTimeout(resolve, 100))
-  return { category: item.category, contribution: item.doubled }
-})
-
-// Aggregation can be done with computed signals
-const totals = new Memo(() => {
-  const items = categoryTotals.get()
-  return items.reduce((acc, item) => {
-    acc[item.category] = (acc[item.category] || 0) + item.contribution
-    return acc
-  }, {} as Record<string, number>)
-})
+  .deriveCollection(item => ({ ...item, formatted: `$${item.doubled}` }))
 ```
 
-### Stable Keys for Persistent Item Identity
+### Stable List Keys
 ```typescript
-// Managing a list of items where order matters but identity persists
 const playlist = new List([
-  { id: 'track1', title: 'Song A', duration: 180 },
-  { id: 'track2', title: 'Song B', duration: 210 }
+  { id: 'track1', title: 'Song A' }
 ], track => track.id)
 
-// Get persistent reference to a specific track
-const firstTrackSignal = playlist.byKey('track1')
-const firstTrack = firstTrackSignal?.get()
-
-// Reorder playlist while maintaining references
+const firstTrack = playlist.byKey('track1') // Persists through sorting
 playlist.sort((a, b) => a.title.localeCompare(b.title))
-// firstTrackSignal still points to the same track!
-
-// Insert new track at specific position
-playlist.splice(1, 0, { id: 'track3', title: 'Song C', duration: 195 })
-
-// Find current position of a track by its stable key
-const track1Position = playlist.indexOfKey('track1')
-const keyAtPosition2 = playlist.keyAt(2)
 ```
-
-**Component ownership principle**: The component that emits events should own and initialize the event store. This creates clear boundaries and prevents coupling issues.
-
-**Why this pattern?**: By having the owning component (Component B) initialize all known events with `UNSET`, we get:
-1. **Fine-grained reactivity**: Each `on()` call establishes a direct dependency on the specific event signal
-2. **Full type safety**: Event names and data shapes are constrained at compile time
-3. **Simple logic**: No conditional updates, no store-wide watching in `on()`
-4. **Clear ownership**: Component B declares its event contract upfront with a schema
-5. **Better performance**: Only the specific event listeners trigger, not all listeners
-6. **Explicit dependencies**: Effects track exactly which events they care about
-7. **IntelliSense support**: IDEs can provide autocomplete for event names and data structures
-
-This context should help you understand not just what the code does, but why it's structured this way and how to use it effectively in real-world applications.