mvc-kit 2.2.2 → 2.2.3

package/README.md

@@ -131,6 +131,7 @@ const todos = new Collection<Todo>();
 
 // CRUD (triggers re-renders)
 todos.add({ id: '1', text: 'Learn mvc-kit', done: false });
+todos.upsert({ id: '1', text: 'Updated', done: true }); // Add-or-replace by ID
 todos.update('1', { done: true });
 todos.remove('1');
 todos.reset([...]); // Replace all
@@ -401,13 +402,13 @@ class ChatViewModel extends ViewModel<{ messages: Message[] }> {
 
 ### `subscribeTo(source, listener)` (protected)
 
-Subscribe to a Subscribable and auto-unsubscribe on dispose. Available on ViewModel, Model, and Controller.
+Subscribe to a Subscribable and auto-unsubscribe on dispose. Available on ViewModel, Model, and Controller. Use for **imperative reactions** — for deriving values from collections, use getters instead (auto-tracking handles reactivity).
 
 ```typescript
-class UsersViewModel extends ViewModel<State> {
+class ChatViewModel extends ViewModel<State> {
   protected onInit() {
-    // Replaces: this.addCleanup(this.collection.subscribe(() => this.derive()))
-    this.subscribeTo(this.collection, () => this.derive());
+    // Imperative reaction: play sound on new messages
+    this.subscribeTo(this.messagesCollection, () => this.playNotificationSound());
   }
 }
 ```

package/agent-config/claude-code/agents/mvc-kit-architect.md

@@ -52,10 +52,9 @@ When asked to plan a feature:
 
 - State holds only source-of-truth values. Derived values are `get` accessors. Async status comes from `vm.async.methodName`.
 - One ViewModel per component via `useLocal`. No `useEffect` for data loading.
-- Collections are encapsulated by ViewModels. Components never import Collections.
+- Collections are encapsulated by ViewModels. Getters read from collections directly — auto-tracking handles reactivity. Components never import Collections.
 - Services are stateless, accept `AbortSignal`, throw `HttpError`.
-- `onInit()` handles data loading and subscription setup.
-- Use `subscribeTo()` for Collection subscriptions (auto-cleanup).
+- `onInit()` handles data loading. Use `subscribeTo()` only for imperative side effects, not for deriving values.
 - ViewModel section order: Private fields → Computed getters → Lifecycle → Actions → Setters.
 - Pass `this.disposeSignal` to every async call.
 

package/agent-config/claude-code/skills/guide/SKILL.md

@@ -29,7 +29,7 @@ You are assisting a developer using **mvc-kit**, a zero-dependency TypeScript-fi
 
 3. **Components are declarative.** Read `state.x` for raw values, `vm.x` for computed, `vm.async.x` for loading/error. Call `vm.method()` for actions.
 
-4. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()` and mirror data into state. Components never import Collections.
+4. **Collections are encapsulated.** ViewModel getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects. Components never import Collections.
 
 5. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels or Collections.
 

package/agent-config/claude-code/skills/guide/anti-patterns.md

@@ -9,16 +9,37 @@ Reject these patterns. Each entry shows the bad pattern and the correct alternat
 ```typescript
 // BAD
 interface State {
-  items: Item[];
   loading: boolean;
   error: string | null;
 }
 
 // GOOD — async tracking handles it
+// Read: vm.async.load.loading, vm.async.load.error
+```
+
+---
+
+## 1b. Mirroring Collection Data into State
+
+```typescript
+// BAD — subscribeTo + set() to mirror collection data
 interface State {
   items: Item[];
+  search: string;
+}
+protected onInit() {
+  this.subscribeTo(this.collection, () => {
+    this.set({ items: this.collection.items });
+  });
+}
+
+// GOOD — getter reads from collection directly, auto-tracked
+interface State {
+  search: string;
+}
+get items(): Item[] {
+  return this.collection.items as Item[];
 }
-// Read: vm.async.load.loading, vm.async.load.error
 ```
 
 ---
@@ -302,7 +323,25 @@ function UsersPage() {
 
 ---
 
-## 15. Missing disposeSignal on Async Calls
+## 15. Using reset() for Paginated/Incremental Loads
+
+```typescript
+// BAD — reset() destroys data other ViewModels depend on
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.reset(data); // wipes previous pages!
+}
+
+// GOOD — upsert() accumulates data, replacing stale items and adding new ones
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.upsert(...data);
+}
+```
+
+---
+
+## 16. Missing disposeSignal on Async Calls
 
 ```typescript
 // BAD — no cancellation on unmount

package/agent-config/claude-code/skills/guide/api-reference.md

@@ -108,10 +108,11 @@ Same as ViewModel: `onInit()`, `onSet()`, `onDispose()`, `disposeSignal`, `subsc
 Reactive typed array with CRUD and query methods. Items must have an `id: string` field.
 
 ### CRUD (triggers notifications)
-- `add(item: T): void`
+- `add(...items: T[]): void` — Append items. Skips existing IDs.
+- `upsert(...items: T[]): void` — Add-or-replace by ID. Existing replaced in-place; new appended. Ideal for paginated loads.
 - `update(id: string, partial: Partial<T>): void`
-- `remove(id: string): void`
-- `reset(items: T[]): void` — Replace all items.
+- `remove(...ids: string[]): void`
+- `reset(items: T[]): void` — Replace all items. Use for full loads; prefer `upsert()` for incremental.
 - `clear(): void`
 
 ### Query (pure, no notifications)

package/agent-config/claude-code/skills/guide/patterns.md

@@ -69,28 +69,27 @@ The setter changes state → React re-renders → getters recompute. No manual r
 
 ## Encapsulating Collections
 
-ViewModels subscribe internally. Components never see Collections.
+Getters read directly from collection members — auto-tracking handles reactivity. Components never see Collections.
 
 ```typescript
 class LocationsViewModel extends ViewModel<State> {
-  private collection = singleton(LocationsCollection);
+  collection = singleton(LocationsCollection);
   private service = singleton(LocationService);
 
+  // Getter reads from collection — auto-tracked
+  get items(): LocationState[] {
+    return this.collection.items as LocationState[];
+  }
+
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-
-    // Smart init: use cached data or fetch fresh
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    // Smart init: skip fetch if data already loaded
+    if (this.collection.length === 0) this.load();
   }
 }
 ```
 
+Use `subscribeTo()` only for imperative side effects (e.g. play a sound on new messages), not for deriving values.
+
 ---
 
 ## Async Methods — Happy Path Only
@@ -100,6 +99,12 @@ async load() {
   const data = await this.service.getAll(this.disposeSignal);
   this.collection.reset(data);
 }
+
+// For paginated/incremental loads, use upsert() to accumulate data:
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.upsert(...data);
+}
 ```
 
 No try/catch. No `set({ loading: true })`. No AbortError check. The framework handles it.
@@ -220,7 +225,7 @@ class UserService extends Service {
 class UsersCollection extends Collection<UserState> {}
 ```
 
-Thin subclass for singleton identity. No custom methods — query logic goes in ViewModel getters.
+Thin subclass for singleton identity. No custom methods — query logic goes in ViewModel getters. Use `reset()` for full loads, `upsert()` for paginated/incremental loads, and `add`/`update`/`remove` for granular mutations.
 
 ---
 

package/agent-config/claude-code/skills/review/checklist.md

@@ -13,7 +13,7 @@
 6. **Section order** — Must follow: Private fields → Computed getters → Lifecycle → Actions → Setters.
 7. **No two-step setters** — Setters should be one-liners (`this.set({ x })`). No manual refilter/rederive calls after `set()`.
 8. **Smart init pattern** — When subscribing to a Collection, check `collection.length > 0` before fetching.
-9. **Use `subscribeTo`** — Collection subscriptions must use `subscribeTo()` (auto-cleanup), not manual `subscribe()` + `addCleanup()`.
+9. **Getters read from collections** — Collection data should be accessed via getters, not mirrored into state with `subscribeTo()` + `set()`. Use `subscribeTo()` only for imperative side effects.
 10. **Use `collection.optimistic()`** — No manual snapshot/restore for optimistic updates.
 11. **Singleton resolution as property** — Dependencies resolved via `private service = singleton(MyService)`, not in `onInit()`.
 

package/agent-config/claude-code/skills/scaffold/SKILL.md

@@ -47,6 +47,6 @@ Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
 - Services are stateless, accept `AbortSignal`, throw `HttpError`.
 - Collections are thin subclasses — no custom methods.
 - Use `singleton()` for dependency resolution in ViewModels.
-- Use `subscribeTo()` for Collection subscriptions with smart init pattern.
+- Getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects.
 - Pass `this.disposeSignal` to every async call.
 - Test files use `teardownAll()` in `beforeEach`.

package/agent-config/claude-code/skills/scaffold/templates/collection.md

@@ -22,23 +22,16 @@ import { ViewModel, singleton } from 'mvc-kit';
 import { {{Name}}Collection } from '../collections/{{Name}}Collection';
 import type { {{Name}}Item } from '../collections/{{Name}}Collection';
 
-interface State {
-  items: {{Name}}Item[];
-}
+class {{Name}}ViewModel extends ViewModel<{ search: string }> {
+  collection = singleton({{Name}}Collection);
 
-class {{Name}}ViewModel extends ViewModel<State> {
-  private collection = singleton({{Name}}Collection);
+  // Getter reads from collection — auto-tracked
+  get items(): {{Name}}Item[] {
+    return this.collection.items as {{Name}}Item[];
+  }
 
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    if (this.collection.length === 0) this.load();
   }
 
   async load() {

package/agent-config/claude-code/skills/scaffold/templates/viewmodel.md

@@ -8,7 +8,6 @@ import { ViewModel, singleton } from 'mvc-kit';
 // import { {{Name}}Collection } from '../collections/{{Name}}Collection';
 
 interface {{Name}}State {
-  items: any[]; // TODO: Replace with your item type
   search: string;
 }
 
@@ -20,11 +19,18 @@ interface {{Name}}State {
 export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
   // --- Private fields ---
   // private service = singleton({{Name}}Service);
-  // private collection = singleton({{Name}}Collection);
+  // collection = singleton({{Name}}Collection);
 
   // --- Computed getters ---
+  // Getter reads from collection — auto-tracked
+  // get items(): any[] {
+  //   return this.collection.items;
+  // }
+
   get filtered(): any[] {
-    const { items, search } = this.state;
+    const { search } = this.state;
+    // TODO: read from this.items (collection getter) instead of hardcoded array
+    const items: any[] = [];
     if (!search) return items;
     const q = search.toLowerCase();
     return items.filter(item =>
@@ -33,7 +39,7 @@ export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
   }
 
   get total(): number {
-    return this.state.items.length;
+    return this.filtered.length;
   }
 
   get hasResults(): boolean {
@@ -42,17 +48,8 @@ export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
 
   // --- Lifecycle ---
   protected onInit() {
-    // Subscribe to collection and mirror data into state
-    // this.subscribeTo(this.collection, () => {
-    //   this.set({ items: this.collection.items });
-    // });
-
-    // Smart init: use cached data or fetch fresh
-    // if (this.collection.length > 0) {
-    //   this.set({ items: this.collection.items });
-    // } else {
-    //   this.load();
-    // }
+    // Smart init: skip fetch if data already loaded
+    // if (this.collection.length === 0) this.load();
 
     this.load();
   }
@@ -79,9 +76,8 @@ import { {{Name}}ViewModel } from './{{Name}}ViewModel';
 beforeEach(() => teardownAll());
 
 describe('{{Name}}ViewModel', () => {
-  function create(overrides: Partial<{ items: any[]; search: string }> = {}) {
+  function create(overrides: Partial<{ search: string }> = {}) {
     return new {{Name}}ViewModel({
-      items: [],
       search: '',
       ...overrides,
     });
@@ -89,7 +85,6 @@ describe('{{Name}}ViewModel', () => {
 
   test('initializes with default state', () => {
     const vm = create();
-    expect(vm.state.items).toEqual([]);
     expect(vm.state.search).toBe('');
     vm.dispose();
   });
@@ -100,29 +95,5 @@ describe('{{Name}}ViewModel', () => {
     expect(vm.state.search).toBe('test');
     vm.dispose();
   });
-
-  test('filtered getter applies search', () => {
-    const vm = create({
-      items: [
-        { id: '1', name: 'Alpha' },
-        { id: '2', name: 'Beta' },
-      ],
-    });
-
-    expect(vm.filtered).toHaveLength(2);
-
-    vm.setSearch('alpha');
-    expect(vm.filtered).toHaveLength(1);
-
-    vm.dispose();
-  });
-
-  test('total returns item count', () => {
-    const vm = create({
-      items: [{ id: '1' }, { id: '2' }, { id: '3' }],
-    });
-    expect(vm.total).toBe(3);
-    vm.dispose();
-  });
 });
 ```

package/agent-config/copilot/copilot-instructions.md

@@ -30,7 +30,7 @@ import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useE
 4. **One ViewModel per component** via `useLocal`. No `useEffect` for data loading — use `onInit()`.
 5. **No `useState`/`useMemo`/`useCallback`** — the ViewModel is the hook.
 6. **Components are declarative.** Read `state.x` for raw, `vm.x` for computed, `vm.async.x` for loading/error.
-7. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()`. Components never import Collections.
+7. **Collections are encapsulated.** ViewModel getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects. Components never import Collections.
 8. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels.
 9. **Pass `this.disposeSignal`** to every async call.
 10. **Lifecycle**: `construct → init() → use → dispose()`. Hooks auto-call `init()`.
@@ -39,35 +39,31 @@ import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useE
 
 ```typescript
 interface ItemState {
-  items: Item[];
   search: string;
 }
 
 class ItemsViewModel extends ViewModel<ItemState> {
   // --- Private fields ---
   private service = singleton(ItemService);
-  private collection = singleton(ItemsCollection);
+  collection = singleton(ItemsCollection);
 
   // --- Computed getters ---
+  get items(): Item[] {
+    return this.collection.items as Item[];
+  }
+
   get filtered(): Item[] {
-    const { items, search } = this.state;
-    if (!search) return items;
+    const { search } = this.state;
+    if (!search) return this.items;
     const q = search.toLowerCase();
-    return items.filter(i => i.name.toLowerCase().includes(q));
+    return this.items.filter(i => i.name.toLowerCase().includes(q));
   }
 
-  get total(): number { return this.state.items.length; }
+  get total(): number { return this.items.length; }
 
   // --- Lifecycle ---
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    if (this.collection.length === 0) this.load();
   }
 
   // --- Actions ---
@@ -87,7 +83,7 @@ class ItemsViewModel extends ViewModel<ItemState> {
 
 ```tsx
 function ItemsPage() {
-  const [state, vm] = useLocal(ItemsViewModel, { items: [], search: '' });
+  const [state, vm] = useLocal(ItemsViewModel, { search: '' });
   const { loading, error } = vm.async.load;
 
   return (
@@ -133,6 +129,7 @@ class UserService extends Service {
 ```typescript
 class UsersCollection extends Collection<UserState> {}
 // Thin subclass. Query logic in ViewModel getters.
+// Use reset() for full loads, upsert() for paginated/incremental loads.
 ```
 
 ## Model Pattern
@@ -222,6 +219,7 @@ test('example', () => {
 - Manual try/catch for standard loads → async tracking handles it
 - Two-step setters with refilter calls → getters auto-recompute
 - Manual optimistic snapshot/restore → use `collection.optimistic()`
+- `reset()` for paginated/incremental loads → use `upsert()` to accumulate data
 - `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
 
 ## Decision Framework

package/agent-config/cursor/cursorrules

@@ -30,7 +30,7 @@ import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useE
 4. **One ViewModel per component** via `useLocal`. No `useEffect` for data loading — use `onInit()`.
 5. **No `useState`/`useMemo`/`useCallback`** — the ViewModel is the hook.
 6. **Components are declarative.** Read `state.x` for raw, `vm.x` for computed, `vm.async.x` for loading/error.
-7. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()`. Components never import Collections.
+7. **Collections are encapsulated.** ViewModel getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects. Components never import Collections.
 8. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels.
 9. **Pass `this.disposeSignal`** to every async call.
 10. **Lifecycle**: `construct → init() → use → dispose()`. Hooks auto-call `init()`.
@@ -39,35 +39,31 @@ import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useE
 
 ```typescript
 interface ItemState {
-  items: Item[];
   search: string;
 }
 
 class ItemsViewModel extends ViewModel<ItemState> {
   // --- Private fields ---
   private service = singleton(ItemService);
-  private collection = singleton(ItemsCollection);
+  collection = singleton(ItemsCollection);
 
   // --- Computed getters ---
+  get items(): Item[] {
+    return this.collection.items as Item[];
+  }
+
   get filtered(): Item[] {
-    const { items, search } = this.state;
-    if (!search) return items;
+    const { search } = this.state;
+    if (!search) return this.items;
     const q = search.toLowerCase();
-    return items.filter(i => i.name.toLowerCase().includes(q));
+    return this.items.filter(i => i.name.toLowerCase().includes(q));
   }
 
-  get total(): number { return this.state.items.length; }
+  get total(): number { return this.items.length; }
 
   // --- Lifecycle ---
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    if (this.collection.length === 0) this.load();
   }
 
   // --- Actions ---
@@ -87,7 +83,7 @@ class ItemsViewModel extends ViewModel<ItemState> {
 
 ```tsx
 function ItemsPage() {
-  const [state, vm] = useLocal(ItemsViewModel, { items: [], search: '' });
+  const [state, vm] = useLocal(ItemsViewModel, { search: '' });
   const { loading, error } = vm.async.load;
 
   return (
@@ -133,6 +129,7 @@ class UserService extends Service {
 ```typescript
 class UsersCollection extends Collection<UserState> {}
 // Thin subclass. Query logic in ViewModel getters.
+// Use reset() for full loads, upsert() for paginated/incremental loads.
 ```
 
 ## Model Pattern
@@ -222,6 +219,7 @@ test('example', () => {
 - Manual try/catch for standard loads → async tracking handles it
 - Two-step setters with refilter calls → getters auto-recompute
 - Manual optimistic snapshot/restore → use `collection.optimistic()`
+- `reset()` for paginated/incremental loads → use `upsert()` to accumulate data
 - `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
 
 ## Decision Framework

package/dist/Channel.d.ts

@@ -1,4 +1,5 @@
 import type { Listener, Subscribable, Disposable, Initializable } from './types';
+/** Describes the current connection state of a Channel. */
 export interface ChannelStatus {
     readonly connected: boolean;
     readonly reconnecting: boolean;
@@ -6,10 +7,18 @@ export interface ChannelStatus {
     readonly error: string | null;
 }
 type Handler<T> = (payload: T) => void;
+/**
+ * Abstract persistent connection with automatic reconnection and exponential backoff.
+ * Subclass to implement WebSocket, SSE, or other transport protocols.
+ */
 export declare abstract class Channel<M extends Record<string, any>> implements Subscribable<ChannelStatus>, Initializable, Disposable {
+    /** Base delay (ms) for reconnection backoff. */
     static RECONNECT_BASE: number;
+    /** Maximum delay cap (ms) for reconnection backoff. */
     static RECONNECT_MAX: number;
+    /** Exponential backoff multiplier for reconnection delay. */
     static RECONNECT_FACTOR: number;
+    /** Maximum number of reconnection attempts before giving up. */
     static MAX_ATTEMPTS: number;
     private _status;
     private _connState;
@@ -21,25 +30,45 @@ export declare abstract class Channel<M extends Record<string, any>> implements
     private _connectAbort;
     private _reconnectTimer;
     private _cleanups;
+    /** Current connection status. */
     get state(): Readonly<ChannelStatus>;
+    /** Subscribes to connection status changes. Returns an unsubscribe function. */
     subscribe(listener: Listener<ChannelStatus>): () => void;
+    /** Whether this instance has been disposed. */
     get disposed(): boolean;
+    /** Whether init() has been called. */
     get initialized(): boolean;
+    /** AbortSignal that fires when this instance is disposed. Lazily created. */
     get disposeSignal(): AbortSignal;
+    /** Initializes the instance. Called automatically by React hooks after mount. */
     init(): void | Promise<void>;
+    /** Tears down the instance, releasing all subscriptions and resources. */
     dispose(): void;
+    /** Establishes the underlying connection. Called internally by connect(). @protected */
     protected abstract open(signal: AbortSignal): void | Promise<void>;
+    /** Tears down the underlying connection. Called internally by disconnect() and dispose(). @protected */
     protected abstract close(): void;
+    /** Initiates a connection with automatic reconnection on failure. */
     connect(): void;
+    /** Closes the connection and cancels any pending reconnection. */
     disconnect(): void;
+    /** Call from subclass when a message arrives from the transport. @protected */
     protected receive<K extends keyof M>(type: K, payload: M[K]): void;
+    /** Call from subclass when the transport connection drops unexpectedly. Triggers reconnection. @protected */
     protected disconnected(): void;
+    /** Subscribes to a specific message type. Returns an unsubscribe function. */
     on<K extends keyof M>(type: K, handler: Handler<M[K]>): () => void;
+    /** Subscribes to a message type, auto-removing the handler after the first invocation. */
     once<K extends keyof M>(type: K, handler: Handler<M[K]>): () => void;
+    /** Registers a cleanup function to be called on dispose. @protected */
     protected addCleanup(fn: () => void): void;
+    /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
     protected subscribeTo<T>(source: Subscribable<T>, listener: Listener<T>): () => void;
+    /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */
     protected onInit?(): void | Promise<void>;
+    /** Lifecycle hook called during dispose(). Override for custom teardown. @protected */
     protected onDispose?(): void;
+    /** Computes the reconnect backoff delay with jitter for the given attempt number. @protected */
     protected _calculateDelay(attempt: number): number;
     private _setStatus;
     private _attemptConnect;

package/dist/Channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Channel.d.ts","sourceRoot":"","sources":["../src/Channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Channel.d.ts","sourceRoot":"","sources":["../src/Channel.ts"],"names":[],"mappings":"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"}

package/dist/Collection.d.ts

@@ -18,14 +18,25 @@ export declare class Collection<T extends {
      * Alias for Subscribable compatibility.
      */
     get state(): readonly T[];
+    /** The raw readonly array of items. */
     get items(): readonly T[];
+    /** Number of items in the collection. */
     get length(): number;
+    /** Whether this instance has been disposed. */
     get disposed(): boolean;
+    /** AbortSignal that fires when this instance is disposed. Lazily created. */
     get disposeSignal(): AbortSignal;
     /**
-     * Add one or more items.
+     * Add one or more items. Items with existing IDs are silently skipped.
      */
     add(...items: T[]): void;
+    /**
+     * Add or replace items by ID. Existing items are replaced in-place
+     * (preserving array position); new items are appended. Deduplicates
+     * input — last occurrence wins. No-op if nothing changed (reference
+     * comparison).
+     */
+    upsert(...items: T[]): void;
     /**
      * Remove items by id(s).
      */
@@ -71,9 +82,13 @@ export declare class Collection<T extends {
      * Map items to new array.
      */
     map<U>(fn: (item: T) => U): readonly U[];
+    /** Subscribes to state changes. Returns an unsubscribe function. */
     subscribe(listener: CollectionListener<T>): () => void;
+    /** Tears down the instance, releasing all subscriptions and resources. */
     dispose(): void;
+    /** Registers a cleanup function to be called on dispose. @protected */
     protected addCleanup(fn: () => void): void;
+    /** Lifecycle hook called during dispose(). Override for custom teardown. @protected */
     protected onDispose?(): void;
     private notify;
     private rebuildIndex;

package/dist/Collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEtD,KAAK,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC,EAAE,CAAC;AACvC,KAAK,kBAAkB,CAAC,CAAC,IAAI,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1D;;GAEG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAE,YAAW,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACpG,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,gBAAgB,CAAgC;IACxD,OAAO,CAAC,SAAS,CAA+B;gBAEpC,YAAY,GAAE,CAAC,EAAO;IAKlC;;OAEG;IACH,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAExB;IAED,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAExB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,aAAa,IAAI,WAAW,CAK/B;IAID;;OAEG;IACH,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAmBxB;;OAEG;IACH,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI;IA0B/B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IA6B9C;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAYvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAgBb;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAsB5C;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS;IAI/B;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO;IAIzB;;OAEG;IACH,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS;IAIpD;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS,CAAC,EAAE;IAIrD;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC,EAAE;IAIvD;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,EAAE;IAMxC,SAAS,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAYtD,OAAO,IAAI,IAAI;IAgBf,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAO1C,SAAS,CAAC,SAAS,CAAC,IAAI,IAAI;IAE5B,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,YAAY;CAMrB"}
+{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEtD,KAAK,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC,EAAE,CAAC;AACvC,KAAK,kBAAkB,CAAC,CAAC,IAAI,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1D;;GAEG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAE,YAAW,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACpG,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,gBAAgB,CAAgC;IACxD,OAAO,CAAC,SAAS,CAA+B;gBAEpC,YAAY,GAAE,CAAC,EAAO;IAKlC;;OAEG;IACH,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAExB;IAED,uCAAuC;IACvC,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAExB;IAED,yCAAyC;IACzC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,+CAA+C;IAC/C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,6EAA6E;IAC7E,IAAI,aAAa,IAAI,WAAW,CAK/B;IAID;;OAEG;IACH,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IA6BxB;;;;;OAKG;IACH,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IA8C3B;;OAEG;IACH,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI;IA0B/B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IA6B9C;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAYvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAgBb;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAsB5C;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS;IAI/B;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO;IAIzB;;OAEG;IACH,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS;IAIpD;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS,CAAC,EAAE;IAIrD;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC,EAAE;IAIvD;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,EAAE;IAMxC,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAYtD,0EAA0E;IAC1E,OAAO,IAAI,IAAI;IAgBf,uEAAuE;IACvE,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAO1C,uFAAuF;IACvF,SAAS,CAAC,SAAS,CAAC,IAAI,IAAI;IAE5B,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,YAAY;CAMrB"}