mvc-kit 2.9.0 → 2.10.0

package/dist/Pending.js

@@ -0,0 +1,301 @@
+import { classifyError, isAbortError } from "./errors.js";
+import { bindPublicMethods } from "./bindPublicMethods.js";
+const __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
+class Pending {
+  // ── Static config (Channel pattern — override via subclass) ──
+  /** Maximum number of retry attempts before marking as failed. */
+  static MAX_RETRIES = 5;
+  /** Base delay (ms) for retry backoff. */
+  static RETRY_BASE = 1e3;
+  /** Maximum delay cap (ms) for retry backoff. */
+  static RETRY_MAX = 3e4;
+  /** Exponential backoff multiplier for retry delay. */
+  static RETRY_FACTOR = 2;
+  // ── Private state ──
+  _operations = /* @__PURE__ */ new Map();
+  _snapshots = /* @__PURE__ */ new Map();
+  _listeners = /* @__PURE__ */ new Set();
+  _disposed = false;
+  _entriesCache = null;
+  constructor() {
+    bindPublicMethods(this);
+  }
+  // ── Readable state (reactive — auto-tracked by ViewModel getters) ──
+  /** Get the frozen status snapshot for an operation by ID, or null if not found. */
+  getStatus(id) {
+    return this._snapshots.get(id) ?? null;
+  }
+  /** Whether an operation exists for the given ID. */
+  has(id) {
+    return this._operations.has(id);
+  }
+  /** Number of operations (all statuses). */
+  get count() {
+    return this._operations.size;
+  }
+  /** Whether any operations are in-flight (active or retrying). */
+  get hasPending() {
+    for (const op of this._operations.values()) {
+      if (op.status !== "failed") return true;
+    }
+    return false;
+  }
+  /** Whether any operations are in a failed state. */
+  get hasFailed() {
+    for (const op of this._operations.values()) {
+      if (op.status === "failed") return true;
+    }
+    return false;
+  }
+  /** Number of operations in a failed state. */
+  get failedCount() {
+    let n = 0;
+    for (const op of this._operations.values()) {
+      if (op.status === "failed") n++;
+    }
+    return n;
+  }
+  /** All operations as a frozen array of entries (id + snapshot). Cached until next mutation. */
+  get entries() {
+    if (this._entriesCache === null) {
+      const result = [];
+      for (const [id, snapshot] of this._snapshots) {
+        result.push(Object.freeze({ ...snapshot, id }));
+      }
+      this._entriesCache = Object.freeze(result);
+    }
+    return this._entriesCache;
+  }
+  // ── Core API ──
+  /**
+   * Enqueue an operation for the given ID. Fire-and-forget (synchronous return).
+   * If the same ID already has a pending operation, it is superseded (aborted).
+   */
+  enqueue(id, operation, execute, meta) {
+    if (this._disposed) {
+      if (__DEV__) {
+        console.warn("[mvc-kit] Pending.enqueue() called after dispose — ignored.");
+      }
+      return;
+    }
+    const existing = this._operations.get(id);
+    if (existing) {
+      existing.abortController.abort();
+      if (existing.retryTimer !== null) {
+        clearTimeout(existing.retryTimer);
+      }
+    }
+    const op = {
+      id,
+      operation,
+      execute,
+      status: "active",
+      attempts: 0,
+      error: null,
+      errorCode: null,
+      nextRetryAt: null,
+      createdAt: Date.now(),
+      abortController: new AbortController(),
+      retryTimer: null,
+      meta: meta ?? null
+    };
+    this._operations.set(id, op);
+    this._snapshot(op);
+    this._notify();
+    queueMicrotask(() => this._process(id));
+  }
+  // ── Controls ──
+  /** Retry a failed operation. No-op if the operation is not in 'failed' status. */
+  retry(id) {
+    if (this._disposed) {
+      if (__DEV__) {
+        console.warn("[mvc-kit] Pending.retry() called after dispose — ignored.");
+      }
+      return;
+    }
+    const op = this._operations.get(id);
+    if (!op || op.status !== "failed") return;
+    op.attempts = 0;
+    op.error = null;
+    op.errorCode = null;
+    op.nextRetryAt = null;
+    op.abortController = new AbortController();
+    this._process(id);
+  }
+  /** Retry all failed operations. */
+  retryAll() {
+    if (this._disposed) {
+      if (__DEV__) {
+        console.warn("[mvc-kit] Pending.retryAll() called after dispose — ignored.");
+      }
+      return;
+    }
+    const failedIds = [];
+    for (const op of this._operations.values()) {
+      if (op.status === "failed") failedIds.push(op.id);
+    }
+    for (const id of failedIds) {
+      this.retry(id);
+    }
+  }
+  /** Cancel an in-flight operation by ID. Aborts the signal, clears timers, and removes it. */
+  cancel(id) {
+    const op = this._operations.get(id);
+    if (!op) return;
+    op.abortController.abort();
+    if (op.retryTimer !== null) {
+      clearTimeout(op.retryTimer);
+    }
+    this._operations.delete(id);
+    this._snapshots.delete(id);
+    this._notify();
+  }
+  /** Cancel all operations. */
+  cancelAll() {
+    for (const op of this._operations.values()) {
+      op.abortController.abort();
+      if (op.retryTimer !== null) {
+        clearTimeout(op.retryTimer);
+      }
+    }
+    this._operations.clear();
+    this._snapshots.clear();
+    if (this._listeners.size > 0) this._notify();
+  }
+  /** Remove a failed operation without retrying. No-op if the operation is not in 'failed' status. */
+  dismiss(id) {
+    const op = this._operations.get(id);
+    if (!op || op.status !== "failed") return;
+    this._operations.delete(id);
+    this._snapshots.delete(id);
+    this._notify();
+  }
+  /** Remove all failed operations without retrying. */
+  dismissAll() {
+    const failedIds = [];
+    for (const op of this._operations.values()) {
+      if (op.status === "failed") failedIds.push(op.id);
+    }
+    if (failedIds.length === 0) return;
+    for (const id of failedIds) {
+      this._operations.delete(id);
+      this._snapshots.delete(id);
+    }
+    this._notify();
+  }
+  // ── Hooks (overridable in subclass) ──
+  /**
+   * Determines whether an error is retryable. Override in a subclass to customize.
+   * Default: retries on network, timeout, and server_error codes.
+   * @protected
+   */
+  isRetryable(error) {
+    const code = classifyError(error).code;
+    return code === "network" || code === "timeout" || code === "server_error";
+  }
+  // ── Subscribable interface (duck-typed — auto-tracked by ViewModel) ──
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  subscribe(cb) {
+    this._listeners.add(cb);
+    return () => {
+      this._listeners.delete(cb);
+    };
+  }
+  // ── Lifecycle ──
+  /** Whether this instance has been disposed. */
+  get disposed() {
+    return this._disposed;
+  }
+  /** Dispose: cancels all operations, clears listeners. */
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = true;
+    this.cancelAll();
+    this._listeners.clear();
+  }
+  // ── Internals ──
+  _snapshot(op) {
+    const ctor = this.constructor;
+    this._snapshots.set(op.id, Object.freeze({
+      status: op.status,
+      operation: op.operation,
+      attempts: op.attempts,
+      maxRetries: ctor.MAX_RETRIES,
+      error: op.error,
+      errorCode: op.errorCode,
+      nextRetryAt: op.nextRetryAt,
+      createdAt: op.createdAt,
+      meta: op.meta
+    }));
+  }
+  _notify() {
+    this._entriesCache = null;
+    for (const cb of this._listeners) cb();
+  }
+  _process(id) {
+    const op = this._operations.get(id);
+    if (!op || this._disposed) return;
+    op.status = "active";
+    op.attempts++;
+    op.error = null;
+    op.errorCode = null;
+    op.nextRetryAt = null;
+    this._snapshot(op);
+    this._notify();
+    op.execute(op.abortController.signal).then(
+      () => {
+        if (this._operations.get(id) !== op) return;
+        const operation = op.operation;
+        this._operations.delete(id);
+        this._snapshots.delete(id);
+        this._notify();
+        this.onConfirmed?.(id, operation);
+      },
+      (error) => {
+        if (this._operations.get(id) !== op) return;
+        if (isAbortError(error)) {
+          this._operations.delete(id);
+          this._snapshots.delete(id);
+          this._notify();
+          return;
+        }
+        const ctor = this.constructor;
+        const classified = classifyError(error);
+        if (this.isRetryable(error) && op.attempts < ctor.MAX_RETRIES) {
+          op.status = "retrying";
+          const delay = this._calculateDelay(op.attempts - 1);
+          op.nextRetryAt = Date.now() + delay;
+          op.error = classified.message;
+          op.errorCode = classified.code;
+          this._snapshot(op);
+          this._notify();
+          op.retryTimer = setTimeout(() => {
+            op.retryTimer = null;
+            this._process(id);
+          }, delay);
+        } else {
+          op.status = "failed";
+          op.error = classified.message;
+          op.errorCode = classified.code;
+          op.nextRetryAt = null;
+          this._snapshot(op);
+          this._notify();
+          this.onFailed?.(id, op.operation, error);
+        }
+      }
+    );
+  }
+  /** Computes retry backoff delay with jitter (Channel formula). @private */
+  _calculateDelay(attempt) {
+    const ctor = this.constructor;
+    const capped = Math.min(
+      ctor.RETRY_BASE * Math.pow(ctor.RETRY_FACTOR, attempt),
+      ctor.RETRY_MAX
+    );
+    return Math.random() * capped;
+  }
+}
+export {
+  Pending
+};
+//# sourceMappingURL=Pending.js.map

package/dist/Pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pending.js","sources":["../src/Pending.ts"],"sourcesContent":["import { classifyError, isAbortError } from './errors';\nimport type { AppError } from './errors';\nimport { bindPublicMethods } from './bindPublicMethods';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// ── Types ─────────────────────────────────────────────────────────\n\n/** Frozen snapshot of a single pending operation's state. */\nexport interface PendingOperation<Meta = unknown> {\n  readonly status: 'active' | 'retrying' | 'failed';\n  readonly operation: string;\n  readonly attempts: number;\n  readonly maxRetries: number;\n  readonly error: string | null;\n  readonly errorCode: AppError['code'] | null;\n  readonly nextRetryAt: number | null;\n  readonly createdAt: number;\n  readonly meta: Meta | null;\n}\n\n/** A PendingOperation snapshot paired with its key, for iteration. */\nexport interface PendingEntry<K extends string | number, Meta = unknown>\n  extends PendingOperation<Meta> {\n  readonly id: K;\n}\n\n/** Mutable internal state for a pending operation. */\ninterface InternalOp<K, Meta> {\n  id: K;\n  operation: string;\n  execute: (signal: AbortSignal) => Promise<void>;\n  status: PendingOperation['status'];\n  attempts: number;\n  error: string | null;\n  errorCode: AppError['code'] | null;\n  nextRetryAt: number | null;\n  createdAt: number;\n  abortController: AbortController;\n  retryTimer: ReturnType<typeof setTimeout> | null;\n  meta: Meta | null;\n}\n\n// ── Pending ───────────────────────────────────────────────────────\n\n/**\n * Per-item operation queue with retry and status tracking.\n * Tracks operations by key with exponential backoff retry on transient errors.\n * Subscribable — auto-tracked when used as a ViewModel/Resource property.\n */\nexport class Pending<K extends string | number = string | number, Meta = unknown> {\n  // ── Static config (Channel pattern — override via subclass) ──\n\n  /** Maximum number of retry attempts before marking as failed. */\n  static MAX_RETRIES = 5;\n  /** Base delay (ms) for retry backoff. */\n  static RETRY_BASE = 1000;\n  /** Maximum delay cap (ms) for retry backoff. */\n  static RETRY_MAX = 30000;\n  /** Exponential backoff multiplier for retry delay. */\n  static RETRY_FACTOR = 2;\n\n  // ── Private state ──\n\n  private _operations = new Map<K, InternalOp<K, Meta>>();\n  private _snapshots = new Map<K, PendingOperation<Meta>>();\n  private _listeners = new Set<() => void>();\n  private _disposed = false;\n  private _entriesCache: readonly PendingEntry<K, Meta>[] | null = null;\n\n  constructor() {\n    bindPublicMethods(this);\n  }\n\n  // ── Readable state (reactive — auto-tracked by ViewModel getters) ──\n\n  /** Get the frozen status snapshot for an operation by ID, or null if not found. */\n  getStatus(id: K): PendingOperation<Meta> | null {\n    return this._snapshots.get(id) ?? null;\n  }\n\n  /** Whether an operation exists for the given ID. */\n  has(id: K): boolean {\n    return this._operations.has(id);\n  }\n\n  /** Number of operations (all statuses). */\n  get count(): number {\n    return this._operations.size;\n  }\n\n  /** Whether any operations are in-flight (active or retrying). */\n  get hasPending(): boolean {\n    for (const op of this._operations.values()) {\n      if (op.status !== 'failed') return true;\n    }\n    return false;\n  }\n\n  /** Whether any operations are in a failed state. */\n  get hasFailed(): boolean {\n    for (const op of this._operations.values()) {\n      if (op.status === 'failed') return true;\n    }\n    return false;\n  }\n\n  /** Number of operations in a failed state. */\n  get failedCount(): number {\n    let n = 0;\n    for (const op of this._operations.values()) {\n      if (op.status === 'failed') n++;\n    }\n    return n;\n  }\n\n  /** All operations as a frozen array of entries (id + snapshot). Cached until next mutation. */\n  get entries(): readonly PendingEntry<K, Meta>[] {\n    if (this._entriesCache === null) {\n      const result: PendingEntry<K, Meta>[] = [];\n      for (const [id, snapshot] of this._snapshots) {\n        result.push(Object.freeze({ ...snapshot, id }));\n      }\n      this._entriesCache = Object.freeze(result) as readonly PendingEntry<K, Meta>[];\n    }\n    return this._entriesCache;\n  }\n\n  // ── Core API ──\n\n  /**\n   * Enqueue an operation for the given ID. Fire-and-forget (synchronous return).\n   * If the same ID already has a pending operation, it is superseded (aborted).\n   */\n  enqueue(id: K, operation: string, execute: (signal: AbortSignal) => Promise<void>, meta?: Meta): void {\n    if (this._disposed) {\n      if (__DEV__) {\n        console.warn('[mvc-kit] Pending.enqueue() called after dispose — ignored.');\n      }\n      return;\n    }\n\n    // Supersede existing operation for this ID\n    const existing = this._operations.get(id);\n    if (existing) {\n      existing.abortController.abort();\n      if (existing.retryTimer !== null) {\n        clearTimeout(existing.retryTimer);\n      }\n    }\n\n    const op: InternalOp<K, Meta> = {\n      id,\n      operation,\n      execute,\n      status: 'active',\n      attempts: 0,\n      error: null,\n      errorCode: null,\n      nextRetryAt: null,\n      createdAt: Date.now(),\n      abortController: new AbortController(),\n      retryTimer: null,\n      meta: meta ?? null,\n    };\n\n    this._operations.set(id, op);\n    this._snapshot(op);\n    this._notify();\n\n    // Schedule processing via microtask (allows batching multiple enqueues)\n    queueMicrotask(() => this._process(id));\n  }\n\n  // ── Controls ──\n\n  /** Retry a failed operation. No-op if the operation is not in 'failed' status. */\n  retry(id: K): void {\n    if (this._disposed) {\n      if (__DEV__) {\n        console.warn('[mvc-kit] Pending.retry() called after dispose — ignored.');\n      }\n      return;\n    }\n\n    const op = this._operations.get(id);\n    if (!op || op.status !== 'failed') return;\n\n    op.attempts = 0;\n    op.error = null;\n    op.errorCode = null;\n    op.nextRetryAt = null;\n    op.abortController = new AbortController();\n    this._process(id);\n  }\n\n  /** Retry all failed operations. */\n  retryAll(): void {\n    if (this._disposed) {\n      if (__DEV__) {\n        console.warn('[mvc-kit] Pending.retryAll() called after dispose — ignored.');\n      }\n      return;\n    }\n\n    const failedIds: K[] = [];\n    for (const op of this._operations.values()) {\n      if (op.status === 'failed') failedIds.push(op.id);\n    }\n    for (const id of failedIds) {\n      this.retry(id);\n    }\n  }\n\n  /** Cancel an in-flight operation by ID. Aborts the signal, clears timers, and removes it. */\n  cancel(id: K): void {\n    const op = this._operations.get(id);\n    if (!op) return;\n\n    op.abortController.abort();\n    if (op.retryTimer !== null) {\n      clearTimeout(op.retryTimer);\n    }\n    this._operations.delete(id);\n    this._snapshots.delete(id);\n    this._notify();\n  }\n\n  /** Cancel all operations. */\n  cancelAll(): void {\n    for (const op of this._operations.values()) {\n      op.abortController.abort();\n      if (op.retryTimer !== null) {\n        clearTimeout(op.retryTimer);\n      }\n    }\n    this._operations.clear();\n    this._snapshots.clear();\n    if (this._listeners.size > 0) this._notify();\n  }\n\n  /** Remove a failed operation without retrying. No-op if the operation is not in 'failed' status. */\n  dismiss(id: K): void {\n    const op = this._operations.get(id);\n    if (!op || op.status !== 'failed') return;\n\n    this._operations.delete(id);\n    this._snapshots.delete(id);\n    this._notify();\n  }\n\n  /** Remove all failed operations without retrying. */\n  dismissAll(): void {\n    const failedIds: K[] = [];\n    for (const op of this._operations.values()) {\n      if (op.status === 'failed') failedIds.push(op.id);\n    }\n    if (failedIds.length === 0) return;\n    for (const id of failedIds) {\n      this._operations.delete(id);\n      this._snapshots.delete(id);\n    }\n    this._notify();\n  }\n\n  // ── Hooks (overridable in subclass) ──\n\n  /**\n   * Determines whether an error is retryable. Override in a subclass to customize.\n   * Default: retries on network, timeout, and server_error codes.\n   * @protected\n   */\n  protected isRetryable(error: unknown): boolean {\n    const code = classifyError(error).code;\n    return code === 'network' || code === 'timeout' || code === 'server_error';\n  }\n\n  /** Called when an operation succeeds. Override in a subclass for side effects. @protected */\n  protected onConfirmed?(id: K, operation: string): void;\n  /** Called when an operation fails permanently. Override in a subclass for side effects. @protected */\n  protected onFailed?(id: K, operation: string, error: unknown): void;\n\n  // ── Subscribable interface (duck-typed — auto-tracked by ViewModel) ──\n\n  /** Subscribe to state changes. Returns an unsubscribe function. */\n  subscribe(cb: () => void): () => void {\n    this._listeners.add(cb);\n    return () => { this._listeners.delete(cb); };\n  }\n\n  // ── Lifecycle ──\n\n  /** Whether this instance has been disposed. */\n  get disposed(): boolean {\n    return this._disposed;\n  }\n\n  /** Dispose: cancels all operations, clears listeners. */\n  dispose(): void {\n    if (this._disposed) return;\n    this._disposed = true;\n    this.cancelAll();\n    this._listeners.clear();\n  }\n\n  // ── Internals ──\n\n  private _snapshot(op: InternalOp<K, Meta>): void {\n    const ctor = this.constructor as typeof Pending;\n    this._snapshots.set(op.id, Object.freeze({\n      status: op.status,\n      operation: op.operation,\n      attempts: op.attempts,\n      maxRetries: ctor.MAX_RETRIES,\n      error: op.error,\n      errorCode: op.errorCode,\n      nextRetryAt: op.nextRetryAt,\n      createdAt: op.createdAt,\n      meta: op.meta,\n    }));\n  }\n\n  private _notify(): void {\n    this._entriesCache = null;\n    for (const cb of this._listeners) cb();\n  }\n\n  private _process(id: K): void {\n    const op = this._operations.get(id);\n    if (!op || this._disposed) return;\n\n    // Set active status\n    op.status = 'active';\n    op.attempts++;\n    op.error = null;\n    op.errorCode = null;\n    op.nextRetryAt = null;\n    this._snapshot(op);\n    this._notify();\n\n    op.execute(op.abortController.signal).then(\n      () => {\n        // Identity check: ignore if this op was superseded or cancelled\n        if (this._operations.get(id) !== op) return;\n        const operation = op.operation;\n        this._operations.delete(id);\n        this._snapshots.delete(id);\n        this._notify();\n        this.onConfirmed?.(id, operation);\n      },\n      (error: unknown) => {\n        // Identity check: ignore if this op was superseded or cancelled\n        if (this._operations.get(id) !== op) return;\n\n        // AbortError — remove silently (cancel or supersede)\n        if (isAbortError(error)) {\n          this._operations.delete(id);\n          this._snapshots.delete(id);\n          this._notify();\n          return;\n        }\n\n        const ctor = this.constructor as typeof Pending;\n        const classified = classifyError(error);\n\n        // Check if retryable and under max retries\n        if (this.isRetryable(error) && op.attempts < ctor.MAX_RETRIES) {\n          op.status = 'retrying';\n          const delay = this._calculateDelay(op.attempts - 1);\n          op.nextRetryAt = Date.now() + delay;\n          op.error = classified.message;\n          op.errorCode = classified.code;\n          this._snapshot(op);\n          this._notify();\n\n          op.retryTimer = setTimeout(() => {\n            op.retryTimer = null;\n            this._process(id);\n          }, delay);\n        } else {\n          // Non-retryable or max retries exceeded\n          op.status = 'failed';\n          op.error = classified.message;\n          op.errorCode = classified.code;\n          op.nextRetryAt = null;\n          this._snapshot(op);\n          this._notify();\n          this.onFailed?.(id, op.operation, error);\n        }\n      },\n    );\n  }\n\n  /** Computes retry backoff delay with jitter (Channel formula). @private */\n  private _calculateDelay(attempt: number): number {\n    const ctor = this.constructor as typeof Pending;\n    const capped = Math.min(\n      ctor.RETRY_BASE * Math.pow(ctor.RETRY_FACTOR, attempt),\n      ctor.RETRY_MAX,\n    );\n    return Math.random() * capped;\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/PersistentCollection.cjs

@@ -5,7 +5,7 @@ const __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
 const _registeredKeys = __DEV__ ? /* @__PURE__ */ new Map() : null;
 class PersistentCollection extends Collection.Collection {
   /** Debounce delay in ms for storage writes. 0 = immediate. */
-  static WRITE_DELAY = 100;
+  static WRITE_DELAY = 0;
   // ── Serialization hooks ──
   /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */
   serialize(items) {

package/dist/PersistentCollection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"PersistentCollection.cjs","sources":["../src/PersistentCollection.ts"],"sourcesContent":["import { Collection } from './Collection';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// Track storageKey uniqueness in DEV\nconst _registeredKeys: Map<string, string> | null = __DEV__ ? new Map() : null;\n\n/**\n * Abstract base for Collections that persist to external storage.\n * Tracks deltas per mutation and flushes via debounced writes.\n * Subclasses implement the storage-specific `persist*` methods.\n */\nexport abstract class PersistentCollection<\n  T extends { id: string | number },\n> extends Collection<T> {\n  /** Debounce delay in ms for storage writes. 0 = immediate. */\n  static WRITE_DELAY = 100;\n\n  /** Unique key identifying this collection in storage. */\n  protected abstract readonly storageKey: string;\n\n  // ── Abstract persistence methods ──\n\n  /** Retrieve a single item by id from storage. @protected */\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  /** Retrieve all items from storage. @protected */\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items in storage. @protected */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  /** Remove items by their ids from storage. @protected */\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  /** Remove all items from storage. @protected */\n  protected abstract persistClear(): void | Promise<void>;\n\n  // ── Serialization hooks ──\n\n  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */\n  protected serialize(items: T[]): string {\n    return JSON.stringify(items);\n  }\n\n  /** Deserialize a string back to items. Used by string-based adapters. */\n  protected deserialize(raw: string): T[] {\n    return JSON.parse(raw);\n  }\n\n  // ── Error hook ──\n\n  /** Called when a storage operation fails. Override for custom error handling. */\n  protected onPersistError?(error: unknown): void;\n\n  // ── Internal state ──\n\n  private _hydrated = false;\n  private _hydrating = false;\n  // Suppresses the self-subscriber during reset/clear overrides,\n  // which queue deltas manually instead of relying on diff.\n  private _suppressSubscriber = false;\n  private _persistenceReady = false;\n  private _preHydrationWarned = false;\n  private _pendingWrites = new Map<T['id'], T>();\n  private _pendingRemoves = new Set<T['id']>();\n  private _diffMap = new Map<T['id'], T>();\n  private _pendingClear = false;\n  private _flushTimer: ReturnType<typeof setTimeout> | null = null;\n\n  constructor(initialItems: T[] = []) {\n    super(initialItems);\n\n    // Self-subscribe to detect mutations via diff.\n    // storageKey may not be available yet (class field initializers run after super()),\n    // but that's fine — the subscriber only fires on mutations, not during construction.\n    const unsub = this.subscribe((current, prev) => {\n      if (this._hydrating || this._suppressSubscriber) return;\n      this._ensurePersistenceReady();\n      this._diffAndQueue(current, prev);\n      this._scheduleSave();\n    });\n    this.addCleanup(unsub);\n  }\n\n  /**\n   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract\n   * field that isn't available during the parent constructor chain.\n   */\n  private _ensurePersistenceReady(): void {\n    if (this._persistenceReady) return;\n    this._persistenceReady = true;\n\n    if (__DEV__ && _registeredKeys) {\n      const className = this.constructor.name;\n      const existing = _registeredKeys.get(this.storageKey);\n      if (existing && existing !== className) {\n        console.warn(\n          `[mvc-kit] Duplicate storageKey \"${this.storageKey}\" used by \"${className}\" ` +\n            `and \"${existing}\". Each PersistentCollection should have a unique storageKey.`,\n        );\n      }\n      _registeredKeys.set(this.storageKey, className);\n    }\n  }\n\n  // ── Public API ──\n\n  /** Whether storage data has been loaded. */\n  get hydrated(): boolean {\n    return this._hydrated;\n  }\n\n  /**\n   * Load data from storage into the collection. Idempotent — subsequent calls return current items.\n   * Returns the items after hydration.\n   */\n  async hydrate(): Promise<T[]> {\n    if (this._hydrated) return this.items;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = await this.persistGetAll();\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n      return this.items;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n      return this.items;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Synchronous hydration for sync adapters (e.g., WebStorage).\n   * Call from the **leaf class** constructor (after field initializers have run).\n   */\n  protected _hydrateSync(): void {\n    if (this._hydrated) return;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = this.persistGetAll();\n      if (stored instanceof Promise) {\n        throw new Error('[mvc-kit] _hydrateSync called with async persistGetAll');\n      }\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Clear all data from storage AND from the in-memory collection.\n   */\n  clearStorage(): void | Promise<void> {\n    this._ensurePersistenceReady();\n\n    // Clear pending queues — we're wiping everything\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._pendingClear = false;\n    this._cancelSave();\n\n    // Clear in-memory\n    if (this.length > 0) {\n      super.clear();\n    }\n\n    try {\n      const result = this.persistClear();\n      if (result instanceof Promise) {\n        return result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  // ── Overrides for clear/reset tracking ──\n\n  reset(items: T[]): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    for (const item of items) {\n      this._pendingWrites.set(item.id, item);\n    }\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.reset(items);\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.clear();\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  // ── Override items getter for DEV pre-hydration warning ──\n\n  get items(): T[] {\n    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {\n      this._preHydrationWarned = true;\n      console.warn(\n        `[mvc-kit] Accessing items on \"${this.constructor.name}\" before hydrate() has been called. ` +\n          `Data may be incomplete. Call hydrate() first.`,\n      );\n    }\n    return super.items;\n  }\n\n  get state(): T[] {\n    return this.items;\n  }\n\n  // ── Dispose ──\n\n  dispose(): void {\n    if (this.disposed) return;\n\n    // Flush any pending saves before disposing\n    this._cancelSave();\n    if (this._hasPending()) {\n      try {\n        const result = this._flush();\n        if (result instanceof Promise) {\n          result.catch((err) => this._handlePersistError(err));\n        }\n      } catch (err) {\n        this._handlePersistError(err);\n      }\n    }\n\n    // DEV: unregister storageKey\n    if (__DEV__ && _registeredKeys && this._persistenceReady) {\n      _registeredKeys.delete(this.storageKey);\n    }\n\n    super.dispose();\n  }\n\n  // ── Private: delta tracking ──\n\n  private _diffAndQueue(current: readonly T[], prev: readonly T[]): void {\n    const prevMap = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\n    for (const item of current) {\n      const prevItem = prevMap.get(item.id);\n      if (!prevItem || prevItem !== item) {\n        this._pendingWrites.set(item.id, item);\n        this._pendingRemoves.delete(item.id);\n      }\n      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\n  }\n\n  private _hasPending(): boolean {\n    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;\n  }\n\n  // ── Private: debounce + flush ──\n\n  private _scheduleSave(): void {\n    this._cancelSave();\n    const delay = (this.constructor as typeof PersistentCollection).WRITE_DELAY;\n    if (delay <= 0) {\n      this._doFlush();\n      return;\n    }\n    this._flushTimer = setTimeout(() => this._doFlush(), delay);\n  }\n\n  private _cancelSave(): void {\n    if (this._flushTimer !== null) {\n      clearTimeout(this._flushTimer);\n      this._flushTimer = null;\n    }\n  }\n\n  private _doFlush(): void {\n    if (!this._hasPending()) return;\n    try {\n      const result = this._flush();\n      if (result instanceof Promise) {\n        result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  private _flush(): void | Promise<void> {\n    const doClear = this._pendingClear;\n    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;\n    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;\n\n    // Clear queues\n    this._pendingClear = false;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n\n    if (doClear) {\n      const clearResult = this.persistClear();\n      if (clearResult instanceof Promise) {\n        return clearResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n      if (writes) {\n        return this.persistSet(writes);\n      }\n      return;\n    }\n\n    // Non-clear: removes then writes\n    if (removes) {\n      const removeResult = this.persistRemove(removes);\n      if (removeResult instanceof Promise) {\n        return removeResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n    }\n    if (writes) {\n      return this.persistSet(writes);\n    }\n  }\n\n  // ── Private: error handling ──\n\n  private _handlePersistError(err: unknown): void {\n    if (this.onPersistError) {\n      this.onPersistError(err);\n      return;\n    }\n    if (__DEV__) {\n      console.warn('[mvc-kit] Storage error:', err);\n    }\n  }\n}\n"],"names":["Collection"],"mappings":"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"}
+{"version":3,"file":"PersistentCollection.cjs","sources":["../src/PersistentCollection.ts"],"sourcesContent":["import { Collection } from './Collection';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// Track storageKey uniqueness in DEV\nconst _registeredKeys: Map<string, string> | null = __DEV__ ? new Map() : null;\n\n/**\n * Abstract base for Collections that persist to external storage.\n * Tracks deltas per mutation and flushes via debounced writes.\n * Subclasses implement the storage-specific `persist*` methods.\n */\nexport abstract class PersistentCollection<\n  T extends { id: string | number },\n> extends Collection<T> {\n  /** Debounce delay in ms for storage writes. 0 = immediate. */\n  static WRITE_DELAY = 0;\n\n  /** Unique key identifying this collection in storage. */\n  protected abstract readonly storageKey: string;\n\n  // ── Abstract persistence methods ──\n\n  /** Retrieve a single item by id from storage. @protected */\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  /** Retrieve all items from storage. @protected */\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items in storage. @protected */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  /** Remove items by their ids from storage. @protected */\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  /** Remove all items from storage. @protected */\n  protected abstract persistClear(): void | Promise<void>;\n\n  // ── Serialization hooks ──\n\n  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */\n  protected serialize(items: T[]): string {\n    return JSON.stringify(items);\n  }\n\n  /** Deserialize a string back to items. Used by string-based adapters. */\n  protected deserialize(raw: string): T[] {\n    return JSON.parse(raw);\n  }\n\n  // ── Error hook ──\n\n  /** Called when a storage operation fails. Override for custom error handling. */\n  protected onPersistError?(error: unknown): void;\n\n  // ── Internal state ──\n\n  private _hydrated = false;\n  private _hydrating = false;\n  // Suppresses the self-subscriber during reset/clear overrides,\n  // which queue deltas manually instead of relying on diff.\n  private _suppressSubscriber = false;\n  private _persistenceReady = false;\n  private _preHydrationWarned = false;\n  private _pendingWrites = new Map<T['id'], T>();\n  private _pendingRemoves = new Set<T['id']>();\n  private _diffMap = new Map<T['id'], T>();\n  private _pendingClear = false;\n  private _flushTimer: ReturnType<typeof setTimeout> | null = null;\n\n  constructor(initialItems: T[] = []) {\n    super(initialItems);\n\n    // Self-subscribe to detect mutations via diff.\n    // storageKey may not be available yet (class field initializers run after super()),\n    // but that's fine — the subscriber only fires on mutations, not during construction.\n    const unsub = this.subscribe((current, prev) => {\n      if (this._hydrating || this._suppressSubscriber) return;\n      this._ensurePersistenceReady();\n      this._diffAndQueue(current, prev);\n      this._scheduleSave();\n    });\n    this.addCleanup(unsub);\n  }\n\n  /**\n   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract\n   * field that isn't available during the parent constructor chain.\n   */\n  private _ensurePersistenceReady(): void {\n    if (this._persistenceReady) return;\n    this._persistenceReady = true;\n\n    if (__DEV__ && _registeredKeys) {\n      const className = this.constructor.name;\n      const existing = _registeredKeys.get(this.storageKey);\n      if (existing && existing !== className) {\n        console.warn(\n          `[mvc-kit] Duplicate storageKey \"${this.storageKey}\" used by \"${className}\" ` +\n            `and \"${existing}\". Each PersistentCollection should have a unique storageKey.`,\n        );\n      }\n      _registeredKeys.set(this.storageKey, className);\n    }\n  }\n\n  // ── Public API ──\n\n  /** Whether storage data has been loaded. */\n  get hydrated(): boolean {\n    return this._hydrated;\n  }\n\n  /**\n   * Load data from storage into the collection. Idempotent — subsequent calls return current items.\n   * Returns the items after hydration.\n   */\n  async hydrate(): Promise<T[]> {\n    if (this._hydrated) return this.items;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = await this.persistGetAll();\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n      return this.items;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n      return this.items;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Synchronous hydration for sync adapters (e.g., WebStorage).\n   * Call from the **leaf class** constructor (after field initializers have run).\n   */\n  protected _hydrateSync(): void {\n    if (this._hydrated) return;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = this.persistGetAll();\n      if (stored instanceof Promise) {\n        throw new Error('[mvc-kit] _hydrateSync called with async persistGetAll');\n      }\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Clear all data from storage AND from the in-memory collection.\n   */\n  clearStorage(): void | Promise<void> {\n    this._ensurePersistenceReady();\n\n    // Clear pending queues — we're wiping everything\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._pendingClear = false;\n    this._cancelSave();\n\n    // Clear in-memory\n    if (this.length > 0) {\n      super.clear();\n    }\n\n    try {\n      const result = this.persistClear();\n      if (result instanceof Promise) {\n        return result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  // ── Overrides for clear/reset tracking ──\n\n  reset(items: T[]): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    for (const item of items) {\n      this._pendingWrites.set(item.id, item);\n    }\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.reset(items);\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.clear();\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  // ── Override items getter for DEV pre-hydration warning ──\n\n  get items(): T[] {\n    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {\n      this._preHydrationWarned = true;\n      console.warn(\n        `[mvc-kit] Accessing items on \"${this.constructor.name}\" before hydrate() has been called. ` +\n          `Data may be incomplete. Call hydrate() first.`,\n      );\n    }\n    return super.items;\n  }\n\n  get state(): T[] {\n    return this.items;\n  }\n\n  // ── Dispose ──\n\n  dispose(): void {\n    if (this.disposed) return;\n\n    // Flush any pending saves before disposing\n    this._cancelSave();\n    if (this._hasPending()) {\n      try {\n        const result = this._flush();\n        if (result instanceof Promise) {\n          result.catch((err) => this._handlePersistError(err));\n        }\n      } catch (err) {\n        this._handlePersistError(err);\n      }\n    }\n\n    // DEV: unregister storageKey\n    if (__DEV__ && _registeredKeys && this._persistenceReady) {\n      _registeredKeys.delete(this.storageKey);\n    }\n\n    super.dispose();\n  }\n\n  // ── Private: delta tracking ──\n\n  private _diffAndQueue(current: readonly T[], prev: readonly T[]): void {\n    const prevMap = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\n    for (const item of current) {\n      const prevItem = prevMap.get(item.id);\n      if (!prevItem || prevItem !== item) {\n        this._pendingWrites.set(item.id, item);\n        this._pendingRemoves.delete(item.id);\n      }\n      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\n  }\n\n  private _hasPending(): boolean {\n    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;\n  }\n\n  // ── Private: debounce + flush ──\n\n  private _scheduleSave(): void {\n    this._cancelSave();\n    const delay = (this.constructor as typeof PersistentCollection).WRITE_DELAY;\n    if (delay <= 0) {\n      this._doFlush();\n      return;\n    }\n    this._flushTimer = setTimeout(() => this._doFlush(), delay);\n  }\n\n  private _cancelSave(): void {\n    if (this._flushTimer !== null) {\n      clearTimeout(this._flushTimer);\n      this._flushTimer = null;\n    }\n  }\n\n  private _doFlush(): void {\n    if (!this._hasPending()) return;\n    try {\n      const result = this._flush();\n      if (result instanceof Promise) {\n        result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  private _flush(): void | Promise<void> {\n    const doClear = this._pendingClear;\n    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;\n    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;\n\n    // Clear queues\n    this._pendingClear = false;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n\n    if (doClear) {\n      const clearResult = this.persistClear();\n      if (clearResult instanceof Promise) {\n        return clearResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n      if (writes) {\n        return this.persistSet(writes);\n      }\n      return;\n    }\n\n    // Non-clear: removes then writes\n    if (removes) {\n      const removeResult = this.persistRemove(removes);\n      if (removeResult instanceof Promise) {\n        return removeResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n    }\n    if (writes) {\n      return this.persistSet(writes);\n    }\n  }\n\n  // ── Private: error handling ──\n\n  private _handlePersistError(err: unknown): void {\n    if (this.onPersistError) {\n      this.onPersistError(err);\n      return;\n    }\n    if (__DEV__) {\n      console.warn('[mvc-kit] Storage error:', err);\n    }\n  }\n}\n"],"names":["Collection"],"mappings":"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"}

package/dist/PersistentCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PersistentCollection.d.ts","sourceRoot":"","sources":["../src/PersistentCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C;;;;GAIG;AACH,8BAAsB,oBAAoB,CACxC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CACjC,SAAQ,UAAU,CAAC,CAAC,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,WAAW,SAAO;IAEzB,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAI/C,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,kDAAkD;IAClD,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACtD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IACtE,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,iGAAiG;IACjG,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,MAAM;IAIvC,yEAAyE;IACzE,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE;IAMvC,iFAAiF;IACjF,SAAS,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI/C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAA8C;gBAErD,YAAY,GAAE,CAAC,EAAO;IAelC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAmB/B,4CAA4C;IAC5C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAqB7B;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAsB9B;;OAEG;IACH,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BpC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAiBvB,KAAK,IAAI,IAAI;IAgBb,IAAI,KAAK,IAAI,CAAC,EAAE,CASf;IAED,IAAI,KAAK,IAAI,CAAC,EAAE,CAEf;IAID,OAAO,IAAI,IAAI;IA0Bf,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,MAAM;IAuCd,OAAO,CAAC,mBAAmB;CAS5B"}
+{"version":3,"file":"PersistentCollection.d.ts","sourceRoot":"","sources":["../src/PersistentCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C;;;;GAIG;AACH,8BAAsB,oBAAoB,CACxC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CACjC,SAAQ,UAAU,CAAC,CAAC,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,WAAW,SAAK;IAEvB,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAI/C,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,kDAAkD;IAClD,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACtD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IACtE,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,iGAAiG;IACjG,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,MAAM;IAIvC,yEAAyE;IACzE,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE;IAMvC,iFAAiF;IACjF,SAAS,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI/C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAA8C;gBAErD,YAAY,GAAE,CAAC,EAAO;IAelC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAmB/B,4CAA4C;IAC5C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAqB7B;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAsB9B;;OAEG;IACH,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BpC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAiBvB,KAAK,IAAI,IAAI;IAgBb,IAAI,KAAK,IAAI,CAAC,EAAE,CASf;IAED,IAAI,KAAK,IAAI,CAAC,EAAE,CAEf;IAID,OAAO,IAAI,IAAI;IA0Bf,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,MAAM;IAuCd,OAAO,CAAC,mBAAmB;CAS5B"}

package/dist/PersistentCollection.js

@@ -3,7 +3,7 @@ const __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
 const _registeredKeys = __DEV__ ? /* @__PURE__ */ new Map() : null;
 class PersistentCollection extends Collection {
   /** Debounce delay in ms for storage writes. 0 = immediate. */
-  static WRITE_DELAY = 100;
+  static WRITE_DELAY = 0;
   // ── Serialization hooks ──
   /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */
   serialize(items) {

package/dist/PersistentCollection.js.map

@@ -1 +1 @@
-{"version":3,"file":"PersistentCollection.js","sources":["../src/PersistentCollection.ts"],"sourcesContent":["import { Collection } from './Collection';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// Track storageKey uniqueness in DEV\nconst _registeredKeys: Map<string, string> | null = __DEV__ ? new Map() : null;\n\n/**\n * Abstract base for Collections that persist to external storage.\n * Tracks deltas per mutation and flushes via debounced writes.\n * Subclasses implement the storage-specific `persist*` methods.\n */\nexport abstract class PersistentCollection<\n  T extends { id: string | number },\n> extends Collection<T> {\n  /** Debounce delay in ms for storage writes. 0 = immediate. */\n  static WRITE_DELAY = 100;\n\n  /** Unique key identifying this collection in storage. */\n  protected abstract readonly storageKey: string;\n\n  // ── Abstract persistence methods ──\n\n  /** Retrieve a single item by id from storage. @protected */\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  /** Retrieve all items from storage. @protected */\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items in storage. @protected */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  /** Remove items by their ids from storage. @protected */\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  /** Remove all items from storage. @protected */\n  protected abstract persistClear(): void | Promise<void>;\n\n  // ── Serialization hooks ──\n\n  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */\n  protected serialize(items: T[]): string {\n    return JSON.stringify(items);\n  }\n\n  /** Deserialize a string back to items. Used by string-based adapters. */\n  protected deserialize(raw: string): T[] {\n    return JSON.parse(raw);\n  }\n\n  // ── Error hook ──\n\n  /** Called when a storage operation fails. Override for custom error handling. */\n  protected onPersistError?(error: unknown): void;\n\n  // ── Internal state ──\n\n  private _hydrated = false;\n  private _hydrating = false;\n  // Suppresses the self-subscriber during reset/clear overrides,\n  // which queue deltas manually instead of relying on diff.\n  private _suppressSubscriber = false;\n  private _persistenceReady = false;\n  private _preHydrationWarned = false;\n  private _pendingWrites = new Map<T['id'], T>();\n  private _pendingRemoves = new Set<T['id']>();\n  private _diffMap = new Map<T['id'], T>();\n  private _pendingClear = false;\n  private _flushTimer: ReturnType<typeof setTimeout> | null = null;\n\n  constructor(initialItems: T[] = []) {\n    super(initialItems);\n\n    // Self-subscribe to detect mutations via diff.\n    // storageKey may not be available yet (class field initializers run after super()),\n    // but that's fine — the subscriber only fires on mutations, not during construction.\n    const unsub = this.subscribe((current, prev) => {\n      if (this._hydrating || this._suppressSubscriber) return;\n      this._ensurePersistenceReady();\n      this._diffAndQueue(current, prev);\n      this._scheduleSave();\n    });\n    this.addCleanup(unsub);\n  }\n\n  /**\n   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract\n   * field that isn't available during the parent constructor chain.\n   */\n  private _ensurePersistenceReady(): void {\n    if (this._persistenceReady) return;\n    this._persistenceReady = true;\n\n    if (__DEV__ && _registeredKeys) {\n      const className = this.constructor.name;\n      const existing = _registeredKeys.get(this.storageKey);\n      if (existing && existing !== className) {\n        console.warn(\n          `[mvc-kit] Duplicate storageKey \"${this.storageKey}\" used by \"${className}\" ` +\n            `and \"${existing}\". Each PersistentCollection should have a unique storageKey.`,\n        );\n      }\n      _registeredKeys.set(this.storageKey, className);\n    }\n  }\n\n  // ── Public API ──\n\n  /** Whether storage data has been loaded. */\n  get hydrated(): boolean {\n    return this._hydrated;\n  }\n\n  /**\n   * Load data from storage into the collection. Idempotent — subsequent calls return current items.\n   * Returns the items after hydration.\n   */\n  async hydrate(): Promise<T[]> {\n    if (this._hydrated) return this.items;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = await this.persistGetAll();\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n      return this.items;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n      return this.items;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Synchronous hydration for sync adapters (e.g., WebStorage).\n   * Call from the **leaf class** constructor (after field initializers have run).\n   */\n  protected _hydrateSync(): void {\n    if (this._hydrated) return;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = this.persistGetAll();\n      if (stored instanceof Promise) {\n        throw new Error('[mvc-kit] _hydrateSync called with async persistGetAll');\n      }\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Clear all data from storage AND from the in-memory collection.\n   */\n  clearStorage(): void | Promise<void> {\n    this._ensurePersistenceReady();\n\n    // Clear pending queues — we're wiping everything\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._pendingClear = false;\n    this._cancelSave();\n\n    // Clear in-memory\n    if (this.length > 0) {\n      super.clear();\n    }\n\n    try {\n      const result = this.persistClear();\n      if (result instanceof Promise) {\n        return result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  // ── Overrides for clear/reset tracking ──\n\n  reset(items: T[]): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    for (const item of items) {\n      this._pendingWrites.set(item.id, item);\n    }\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.reset(items);\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.clear();\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  // ── Override items getter for DEV pre-hydration warning ──\n\n  get items(): T[] {\n    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {\n      this._preHydrationWarned = true;\n      console.warn(\n        `[mvc-kit] Accessing items on \"${this.constructor.name}\" before hydrate() has been called. ` +\n          `Data may be incomplete. Call hydrate() first.`,\n      );\n    }\n    return super.items;\n  }\n\n  get state(): T[] {\n    return this.items;\n  }\n\n  // ── Dispose ──\n\n  dispose(): void {\n    if (this.disposed) return;\n\n    // Flush any pending saves before disposing\n    this._cancelSave();\n    if (this._hasPending()) {\n      try {\n        const result = this._flush();\n        if (result instanceof Promise) {\n          result.catch((err) => this._handlePersistError(err));\n        }\n      } catch (err) {\n        this._handlePersistError(err);\n      }\n    }\n\n    // DEV: unregister storageKey\n    if (__DEV__ && _registeredKeys && this._persistenceReady) {\n      _registeredKeys.delete(this.storageKey);\n    }\n\n    super.dispose();\n  }\n\n  // ── Private: delta tracking ──\n\n  private _diffAndQueue(current: readonly T[], prev: readonly T[]): void {\n    const prevMap = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\n    for (const item of current) {\n      const prevItem = prevMap.get(item.id);\n      if (!prevItem || prevItem !== item) {\n        this._pendingWrites.set(item.id, item);\n        this._pendingRemoves.delete(item.id);\n      }\n      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\n  }\n\n  private _hasPending(): boolean {\n    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;\n  }\n\n  // ── Private: debounce + flush ──\n\n  private _scheduleSave(): void {\n    this._cancelSave();\n    const delay = (this.constructor as typeof PersistentCollection).WRITE_DELAY;\n    if (delay <= 0) {\n      this._doFlush();\n      return;\n    }\n    this._flushTimer = setTimeout(() => this._doFlush(), delay);\n  }\n\n  private _cancelSave(): void {\n    if (this._flushTimer !== null) {\n      clearTimeout(this._flushTimer);\n      this._flushTimer = null;\n    }\n  }\n\n  private _doFlush(): void {\n    if (!this._hasPending()) return;\n    try {\n      const result = this._flush();\n      if (result instanceof Promise) {\n        result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  private _flush(): void | Promise<void> {\n    const doClear = this._pendingClear;\n    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;\n    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;\n\n    // Clear queues\n    this._pendingClear = false;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n\n    if (doClear) {\n      const clearResult = this.persistClear();\n      if (clearResult instanceof Promise) {\n        return clearResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n      if (writes) {\n        return this.persistSet(writes);\n      }\n      return;\n    }\n\n    // Non-clear: removes then writes\n    if (removes) {\n      const removeResult = this.persistRemove(removes);\n      if (removeResult instanceof Promise) {\n        return removeResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n    }\n    if (writes) {\n      return this.persistSet(writes);\n    }\n  }\n\n  // ── Private: error handling ──\n\n  private _handlePersistError(err: unknown): void {\n    if (this.onPersistError) {\n      this.onPersistError(err);\n      return;\n    }\n    if (__DEV__) {\n      console.warn('[mvc-kit] Storage error:', err);\n    }\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"PersistentCollection.js","sources":["../src/PersistentCollection.ts"],"sourcesContent":["import { Collection } from './Collection';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// Track storageKey uniqueness in DEV\nconst _registeredKeys: Map<string, string> | null = __DEV__ ? new Map() : null;\n\n/**\n * Abstract base for Collections that persist to external storage.\n * Tracks deltas per mutation and flushes via debounced writes.\n * Subclasses implement the storage-specific `persist*` methods.\n */\nexport abstract class PersistentCollection<\n  T extends { id: string | number },\n> extends Collection<T> {\n  /** Debounce delay in ms for storage writes. 0 = immediate. */\n  static WRITE_DELAY = 0;\n\n  /** Unique key identifying this collection in storage. */\n  protected abstract readonly storageKey: string;\n\n  // ── Abstract persistence methods ──\n\n  /** Retrieve a single item by id from storage. @protected */\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  /** Retrieve all items from storage. @protected */\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items in storage. @protected */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  /** Remove items by their ids from storage. @protected */\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  /** Remove all items from storage. @protected */\n  protected abstract persistClear(): void | Promise<void>;\n\n  // ── Serialization hooks ──\n\n  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */\n  protected serialize(items: T[]): string {\n    return JSON.stringify(items);\n  }\n\n  /** Deserialize a string back to items. Used by string-based adapters. */\n  protected deserialize(raw: string): T[] {\n    return JSON.parse(raw);\n  }\n\n  // ── Error hook ──\n\n  /** Called when a storage operation fails. Override for custom error handling. */\n  protected onPersistError?(error: unknown): void;\n\n  // ── Internal state ──\n\n  private _hydrated = false;\n  private _hydrating = false;\n  // Suppresses the self-subscriber during reset/clear overrides,\n  // which queue deltas manually instead of relying on diff.\n  private _suppressSubscriber = false;\n  private _persistenceReady = false;\n  private _preHydrationWarned = false;\n  private _pendingWrites = new Map<T['id'], T>();\n  private _pendingRemoves = new Set<T['id']>();\n  private _diffMap = new Map<T['id'], T>();\n  private _pendingClear = false;\n  private _flushTimer: ReturnType<typeof setTimeout> | null = null;\n\n  constructor(initialItems: T[] = []) {\n    super(initialItems);\n\n    // Self-subscribe to detect mutations via diff.\n    // storageKey may not be available yet (class field initializers run after super()),\n    // but that's fine — the subscriber only fires on mutations, not during construction.\n    const unsub = this.subscribe((current, prev) => {\n      if (this._hydrating || this._suppressSubscriber) return;\n      this._ensurePersistenceReady();\n      this._diffAndQueue(current, prev);\n      this._scheduleSave();\n    });\n    this.addCleanup(unsub);\n  }\n\n  /**\n   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract\n   * field that isn't available during the parent constructor chain.\n   */\n  private _ensurePersistenceReady(): void {\n    if (this._persistenceReady) return;\n    this._persistenceReady = true;\n\n    if (__DEV__ && _registeredKeys) {\n      const className = this.constructor.name;\n      const existing = _registeredKeys.get(this.storageKey);\n      if (existing && existing !== className) {\n        console.warn(\n          `[mvc-kit] Duplicate storageKey \"${this.storageKey}\" used by \"${className}\" ` +\n            `and \"${existing}\". Each PersistentCollection should have a unique storageKey.`,\n        );\n      }\n      _registeredKeys.set(this.storageKey, className);\n    }\n  }\n\n  // ── Public API ──\n\n  /** Whether storage data has been loaded. */\n  get hydrated(): boolean {\n    return this._hydrated;\n  }\n\n  /**\n   * Load data from storage into the collection. Idempotent — subsequent calls return current items.\n   * Returns the items after hydration.\n   */\n  async hydrate(): Promise<T[]> {\n    if (this._hydrated) return this.items;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = await this.persistGetAll();\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n      return this.items;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n      return this.items;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Synchronous hydration for sync adapters (e.g., WebStorage).\n   * Call from the **leaf class** constructor (after field initializers have run).\n   */\n  protected _hydrateSync(): void {\n    if (this._hydrated) return;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = this.persistGetAll();\n      if (stored instanceof Promise) {\n        throw new Error('[mvc-kit] _hydrateSync called with async persistGetAll');\n      }\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Clear all data from storage AND from the in-memory collection.\n   */\n  clearStorage(): void | Promise<void> {\n    this._ensurePersistenceReady();\n\n    // Clear pending queues — we're wiping everything\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._pendingClear = false;\n    this._cancelSave();\n\n    // Clear in-memory\n    if (this.length > 0) {\n      super.clear();\n    }\n\n    try {\n      const result = this.persistClear();\n      if (result instanceof Promise) {\n        return result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  // ── Overrides for clear/reset tracking ──\n\n  reset(items: T[]): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    for (const item of items) {\n      this._pendingWrites.set(item.id, item);\n    }\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.reset(items);\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.clear();\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  // ── Override items getter for DEV pre-hydration warning ──\n\n  get items(): T[] {\n    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {\n      this._preHydrationWarned = true;\n      console.warn(\n        `[mvc-kit] Accessing items on \"${this.constructor.name}\" before hydrate() has been called. ` +\n          `Data may be incomplete. Call hydrate() first.`,\n      );\n    }\n    return super.items;\n  }\n\n  get state(): T[] {\n    return this.items;\n  }\n\n  // ── Dispose ──\n\n  dispose(): void {\n    if (this.disposed) return;\n\n    // Flush any pending saves before disposing\n    this._cancelSave();\n    if (this._hasPending()) {\n      try {\n        const result = this._flush();\n        if (result instanceof Promise) {\n          result.catch((err) => this._handlePersistError(err));\n        }\n      } catch (err) {\n        this._handlePersistError(err);\n      }\n    }\n\n    // DEV: unregister storageKey\n    if (__DEV__ && _registeredKeys && this._persistenceReady) {\n      _registeredKeys.delete(this.storageKey);\n    }\n\n    super.dispose();\n  }\n\n  // ── Private: delta tracking ──\n\n  private _diffAndQueue(current: readonly T[], prev: readonly T[]): void {\n    const prevMap = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\n    for (const item of current) {\n      const prevItem = prevMap.get(item.id);\n      if (!prevItem || prevItem !== item) {\n        this._pendingWrites.set(item.id, item);\n        this._pendingRemoves.delete(item.id);\n      }\n      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\n  }\n\n  private _hasPending(): boolean {\n    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;\n  }\n\n  // ── Private: debounce + flush ──\n\n  private _scheduleSave(): void {\n    this._cancelSave();\n    const delay = (this.constructor as typeof PersistentCollection).WRITE_DELAY;\n    if (delay <= 0) {\n      this._doFlush();\n      return;\n    }\n    this._flushTimer = setTimeout(() => this._doFlush(), delay);\n  }\n\n  private _cancelSave(): void {\n    if (this._flushTimer !== null) {\n      clearTimeout(this._flushTimer);\n      this._flushTimer = null;\n    }\n  }\n\n  private _doFlush(): void {\n    if (!this._hasPending()) return;\n    try {\n      const result = this._flush();\n      if (result instanceof Promise) {\n        result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  private _flush(): void | Promise<void> {\n    const doClear = this._pendingClear;\n    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;\n    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;\n\n    // Clear queues\n    this._pendingClear = false;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n\n    if (doClear) {\n      const clearResult = this.persistClear();\n      if (clearResult instanceof Promise) {\n        return clearResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n      if (writes) {\n        return this.persistSet(writes);\n      }\n      return;\n    }\n\n    // Non-clear: removes then writes\n    if (removes) {\n      const removeResult = this.persistRemove(removes);\n      if (removeResult instanceof Promise) {\n        return removeResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n    }\n    if (writes) {\n      return this.persistSet(writes);\n    }\n  }\n\n  // ── Private: error handling ──\n\n  private _handlePersistError(err: unknown): void {\n    if (this.onPersistError) {\n      this.onPersistError(err);\n      return;\n    }\n    if (__DEV__) {\n      console.warn('[mvc-kit] Storage error:', err);\n    }\n  }\n}\n"],"names":[],"mappings":";AAEA,MAAM,UAAU,OAAO,oBAAoB,eAAe;AAG1D,MAAM,kBAA8C,UAAU,oBAAI,IAAA,IAAQ;AAOnE,MAAe,6BAEZ,WAAc;AAAA;AAAA,EAEtB,OAAO,cAAc;AAAA;AAAA;AAAA,EAqBX,UAAU,OAAoB;AACtC,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B;AAAA;AAAA,EAGU,YAAY,KAAkB;AACtC,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB;AAAA;AAAA,EASQ,YAAY;AAAA,EACZ,aAAa;AAAA;AAAA;AAAA,EAGb,sBAAsB;AAAA,EACtB,oBAAoB;AAAA,EACpB,sBAAsB;AAAA,EACtB,qCAAqB,IAAA;AAAA,EACrB,sCAAsB,IAAA;AAAA,EACtB,+BAAe,IAAA;AAAA,EACf,gBAAgB;AAAA,EAChB,cAAoD;AAAA,EAE5D,YAAY,eAAoB,IAAI;AAClC,UAAM,YAAY;AAKlB,UAAM,QAAQ,KAAK,UAAU,CAAC,SAAS,SAAS;AAC9C,UAAI,KAAK,cAAc,KAAK,oBAAqB;AACjD,WAAK,wBAAA;AACL,WAAK,cAAc,SAAS,IAAI;AAChC,WAAK,cAAA;AAAA,IACP,CAAC;AACD,SAAK,WAAW,KAAK;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMQ,0BAAgC;AACtC,QAAI,KAAK,kBAAmB;AAC5B,SAAK,oBAAoB;AAEzB,QAAI,WAAW,iBAAiB;AAC9B,YAAM,YAAY,KAAK,YAAY;AACnC,YAAM,WAAW,gBAAgB,IAAI,KAAK,UAAU;AACpD,UAAI,YAAY,aAAa,WAAW;AACtC,gBAAQ;AAAA,UACN,mCAAmC,KAAK,UAAU,cAAc,SAAS,UAC/D,QAAQ;AAAA,QAAA;AAAA,MAEtB;AACA,sBAAgB,IAAI,KAAK,YAAY,SAAS;AAAA,IAChD;AAAA,EACF;AAAA;AAAA;AAAA,EAKA,IAAI,WAAoB;AACtB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,UAAwB;AAC5B,QAAI,KAAK,UAAW,QAAO,KAAK;AAChC,SAAK,wBAAA;AAEL,SAAK,aAAa;AAClB,QAAI;AACF,YAAM,SAAS,MAAM,KAAK,cAAA;AAC1B,UAAI,OAAO,SAAS,GAAG;AACrB,cAAM,MAAM,MAAM;AAAA,MACpB;AACA,WAAK,YAAY;AACjB,aAAO,KAAK;AAAA,IACd,SAAS,KAAK;AACZ,WAAK,oBAAoB,GAAG;AAC5B,WAAK,YAAY;AACjB,aAAO,KAAK;AAAA,IACd,UAAA;AACE,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMU,eAAqB;AAC7B,QAAI,KAAK,UAAW;AACpB,SAAK,wBAAA;AAEL,SAAK,aAAa;AAClB,QAAI;AACF,YAAM,SAAS,KAAK,cAAA;AACpB,UAAI,kBAAkB,SAAS;AAC7B,cAAM,IAAI,MAAM,wDAAwD;AAAA,MAC1E;AACA,UAAI,OAAO,SAAS,GAAG;AACrB,cAAM,MAAM,MAAM;AAAA,MACpB;AACA,WAAK,YAAY;AAAA,IACnB,SAAS,KAAK;AACZ,WAAK,oBAAoB,GAAG;AAC5B,WAAK,YAAY;AAAA,IACnB,UAAA;AACE,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,eAAqC;AACnC,SAAK,wBAAA;AAGL,SAAK,eAAe,MAAA;AACpB,SAAK,gBAAgB,MAAA;AACrB,SAAK,gBAAgB;AACrB,SAAK,YAAA;AAGL,QAAI,KAAK,SAAS,GAAG;AACnB,YAAM,MAAA;AAAA,IACR;AAEA,QAAI;AACF,YAAM,SAAS,KAAK,aAAA;AACpB,UAAI,kBAAkB,SAAS;AAC7B,eAAO,OAAO,MAAM,CAAC,QAAQ,KAAK,oBAAoB,GAAG,CAAC;AAAA,MAC5D;AAAA,IACF,SAAS,KAAK;AACZ,WAAK,oBAAoB,GAAG;AAAA,IAC9B;AAAA,EACF;AAAA;AAAA,EAIA,MAAM,OAAkB;AACtB,SAAK,gBAAgB;AACrB,SAAK,eAAe,MAAA;AACpB,SAAK,gBAAgB,MAAA;AACrB,eAAW,QAAQ,OAAO;AACxB,WAAK,eAAe,IAAI,KAAK,IAAI,IAAI;AAAA,IACvC;AAEA,SAAK,sBAAsB;AAC3B,QAAI;AACF,YAAM,MAAM,KAAK;AAAA,IACnB,UAAA;AACE,WAAK,sBAAsB;AAAA,IAC7B;AACA,SAAK,cAAA;AAAA,EACP;AAAA,EAEA,QAAc;AACZ,SAAK,gBAAgB;AACrB,SAAK,eAAe,MAAA;AACpB,SAAK,gBAAgB,MAAA;AAErB,SAAK,sBAAsB;AAC3B,QAAI;AACF,YAAM,MAAA;AAAA,IACR,UAAA;AACE,WAAK,sBAAsB;AAAA,IAC7B;AACA,SAAK,cAAA;AAAA,EACP;AAAA;AAAA,EAIA,IAAI,QAAa;AACf,QAAI,WAAW,CAAC,KAAK,aAAa,CAAC,KAAK,cAAc,CAAC,KAAK,qBAAqB;AAC/E,WAAK,sBAAsB;AAC3B,cAAQ;AAAA,QACN,iCAAiC,KAAK,YAAY,IAAI;AAAA,MAAA;AAAA,IAG1D;AACA,WAAO,MAAM;AAAA,EACf;AAAA,EAEA,IAAI,QAAa;AACf,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAIA,UAAgB;AACd,QAAI,KAAK,SAAU;AAGnB,SAAK,YAAA;AACL,QAAI,KAAK,eAAe;AACtB,UAAI;AACF,cAAM,SAAS,KAAK,OAAA;AACpB,YAAI,kBAAkB,SAAS;AAC7B,iBAAO,MAAM,CAAC,QAAQ,KAAK,oBAAoB,GAAG,CAAC;AAAA,QACrD;AAAA,MACF,SAAS,KAAK;AACZ,aAAK,oBAAoB,GAAG;AAAA,MAC9B;AAAA,IACF;AAGA,QAAI,WAAW,mBAAmB,KAAK,mBAAmB;AACxD,sBAAgB,OAAO,KAAK,UAAU;AAAA,IACxC;AAEA,UAAM,QAAA;AAAA,EACR;AAAA;AAAA,EAIQ,cAAc,SAAuB,MAA0B;AACrE,UAAM,UAAU,KAAK;AACrB,YAAQ,MAAA;AACR,eAAW,QAAQ,MAAM;AACvB,cAAQ,IAAI,KAAK,IAAI,IAAI;AAAA,IAC3B;AAGA,eAAW,QAAQ,SAAS;AAC1B,YAAM,WAAW,QAAQ,IAAI,KAAK,EAAE;AACpC,UAAI,CAAC,YAAY,aAAa,MAAM;AAClC,aAAK,eAAe,IAAI,KAAK,IAAI,IAAI;AACrC,aAAK,gBAAgB,OAAO,KAAK,EAAE;AAAA,MACrC;AACA,cAAQ,OAAO,KAAK,EAAE;AAAA,IACxB;AAGA,eAAW,CAAC,EAAE,KAAK,SAAS;AAC1B,WAAK,gBAAgB,IAAI,EAAE;AAC3B,WAAK,eAAe,OAAO,EAAE;AAAA,IAC/B;AAEA,YAAQ,MAAA;AAAA,EACV;AAAA,EAEQ,cAAuB;AAC7B,WAAO,KAAK,iBAAiB,KAAK,eAAe,OAAO,KAAK,KAAK,gBAAgB,OAAO;AAAA,EAC3F;AAAA;AAAA,EAIQ,gBAAsB;AAC5B,SAAK,YAAA;AACL,UAAM,QAAS,KAAK,YAA4C;AAChE,QAAI,SAAS,GAAG;AACd,WAAK,SAAA;AACL;AAAA,IACF;AACA,SAAK,cAAc,WAAW,MAAM,KAAK,SAAA,GAAY,KAAK;AAAA,EAC5D;AAAA,EAEQ,cAAoB;AAC1B,QAAI,KAAK,gBAAgB,MAAM;AAC7B,mBAAa,KAAK,WAAW;AAC7B,WAAK,cAAc;AAAA,IACrB;AAAA,EACF;AAAA,EAEQ,WAAiB;AACvB,QAAI,CAAC,KAAK,cAAe;AACzB,QAAI;AACF,YAAM,SAAS,KAAK,OAAA;AACpB,UAAI,kBAAkB,SAAS;AAC7B,eAAO,MAAM,CAAC,QAAQ,KAAK,oBAAoB,GAAG,CAAC;AAAA,MACrD;AAAA,IACF,SAAS,KAAK;AACZ,WAAK,oBAAoB,GAAG;AAAA,IAC9B;AAAA,EACF;AAAA,EAEQ,SAA+B;AACrC,UAAM,UAAU,KAAK;AACrB,UAAM,SAAS,KAAK,eAAe,OAAO,IAAI,CAAC,GAAG,KAAK,eAAe,OAAA,CAAQ,IAAI;AAClF,UAAM,UAAU,KAAK,gBAAgB,OAAO,IAAI,CAAC,GAAG,KAAK,eAAe,IAAI;AAG5E,SAAK,gBAAgB;AACrB,SAAK,eAAe,MAAA;AACpB,SAAK,gBAAgB,MAAA;AAErB,QAAI,SAAS;AACX,YAAM,cAAc,KAAK,aAAA;AACzB,UAAI,uBAAuB,SAAS;AAClC,eAAO,YAAY,KAAK,MAAM;AAC5B,cAAI,OAAQ,QAAO,KAAK,WAAW,MAAM;AAAA,QAC3C,CAAC;AAAA,MACH;AACA,UAAI,QAAQ;AACV,eAAO,KAAK,WAAW,MAAM;AAAA,MAC/B;AACA;AAAA,IACF;AAGA,QAAI,SAAS;AACX,YAAM,eAAe,KAAK,cAAc,OAAO;AAC/C,UAAI,wBAAwB,SAAS;AACnC,eAAO,aAAa,KAAK,MAAM;AAC7B,cAAI,OAAQ,QAAO,KAAK,WAAW,MAAM;AAAA,QAC3C,CAAC;AAAA,MACH;AAAA,IACF;AACA,QAAI,QAAQ;AACV,aAAO,KAAK,WAAW,MAAM;AAAA,IAC/B;AAAA,EACF;AAAA;AAAA,EAIQ,oBAAoB,KAAoB;AAC9C,QAAI,KAAK,gBAAgB;AACvB,WAAK,eAAe,GAAG;AACvB;AAAA,IACF;AACA,QAAI,SAAS;AACX,cAAQ,KAAK,4BAA4B,GAAG;AAAA,IAC9C;AAAA,EACF;AACF;"}

package/dist/Selection.cjs

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const bindPublicMethods = require("./bindPublicMethods.cjs");
 class Selection {
   _selected = /* @__PURE__ */ new Set();
   _listeners = /* @__PURE__ */ new Set();
   _readonlyView = this._selected;
+  constructor() {
+    bindPublicMethods.bindPublicMethods(this);
+  }
   // ── Readable state ──
   /** Read-only view of currently selected keys. */
   get selected() {

package/dist/Selection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"Selection.cjs","sources":["../src/Selection.ts"],"sourcesContent":["/**\n * Key-based selection set with toggle and select-all support.\n * Tracks which items are selected by their key (id).\n * Subscribable — auto-tracked when used as a ViewModel property.\n */\nexport class Selection<K extends string | number = string | number> {\n  private _selected: Set<K> = new Set();\n  private _listeners = new Set<() => void>();\n  private _readonlyView: ReadonlySet<K> = this._selected;\n\n  // ── Readable state ──\n\n  /** Read-only view of currently selected keys. */\n  get selected(): ReadonlySet<K> {\n    return this._readonlyView;\n  }\n\n  /** Number of currently selected items. */\n  get count(): number {\n    return this._selected.size;\n  }\n\n  /** Whether any items are currently selected. */\n  get hasSelection(): boolean {\n    return this._selected.size > 0;\n  }\n\n  // ── Query ──\n\n  /** Check whether a specific key is selected. */\n  isSelected(key: K): boolean {\n    return this._selected.has(key);\n  }\n\n  // ── Actions ──\n\n  /** Toggle a key's selection state (select if unselected, deselect if selected). */\n  toggle(key: K): void {\n    if (this._selected.has(key)) {\n      this._selected.delete(key);\n    } else {\n      this._selected.add(key);\n    }\n    this._publish();\n  }\n\n  /** Add one or more keys to the selection. */\n  select(...keys: K[]): void {\n    let changed = false;\n    for (const key of keys) {\n      if (!this._selected.has(key)) {\n        this._selected.add(key);\n        changed = true;\n      }\n    }\n    if (changed) this._publish();\n  }\n\n  /** Remove one or more keys from the selection. */\n  deselect(...keys: K[]): void {\n    let changed = false;\n    for (const key of keys) {\n      if (this._selected.has(key)) {\n        this._selected.delete(key);\n        changed = true;\n      }\n    }\n    if (changed) this._publish();\n  }\n\n  /** If all selected → deselect all, else select all. */\n  toggleAll(allKeys: K[]): void {\n    const allSelected = allKeys.length > 0 && allKeys.every(k => this._selected.has(k));\n    if (allSelected) {\n      this._selected.clear();\n    } else {\n      for (const key of allKeys) this._selected.add(key);\n    }\n    this._publish();\n  }\n\n  /** Replace the entire selection atomically. Single notification. */\n  set(...keys: K[]): void {\n    // Check if anything actually changed\n    if (keys.length === this._selected.size && keys.every(k => this._selected.has(k))) return;\n    this._selected.clear();\n    for (const key of keys) this._selected.add(key);\n    this._publish();\n  }\n\n  /** Remove all items from the selection. */\n  clear(): void {\n    if (this._selected.size === 0) return;\n    this._selected.clear();\n    this._publish();\n  }\n\n  // ── Utility ──\n\n  /** Filter an array to only items whose key is in the selection. */\n  selectedFrom<T>(items: T[], keyOf: (item: T) => K): T[] {\n    return items.filter(item => this._selected.has(keyOf(item)));\n  }\n\n  // ── Subscribable interface ──\n\n  /** Subscribe to selection changes. Returns an unsubscribe function. */\n  subscribe(cb: () => void): () => void {\n    this._listeners.add(cb);\n    return () => { this._listeners.delete(cb); };\n  }\n\n  private _publish(): void {\n    // Replace readonlyView so reference equality changes (needed for React)\n    this._readonlyView = new Set(this._selected);\n    for (const cb of this._listeners) cb();\n  }\n}\n"],"names":[],"mappings":";;AAKO,MAAM,UAAuD;AAAA,EAC1D,gCAAwB,IAAA;AAAA,EACxB,iCAAiB,IAAA;AAAA,EACjB,gBAAgC,KAAK;AAAA;AAAA;AAAA,EAK7C,IAAI,WAA2B;AAC7B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAgB;AAClB,WAAO,KAAK,UAAU;AAAA,EACxB;AAAA;AAAA,EAGA,IAAI,eAAwB;AAC1B,WAAO,KAAK,UAAU,OAAO;AAAA,EAC/B;AAAA;AAAA;AAAA,EAKA,WAAW,KAAiB;AAC1B,WAAO,KAAK,UAAU,IAAI,GAAG;AAAA,EAC/B;AAAA;AAAA;AAAA,EAKA,OAAO,KAAc;AACnB,QAAI,KAAK,UAAU,IAAI,GAAG,GAAG;AAC3B,WAAK,UAAU,OAAO,GAAG;AAAA,IAC3B,OAAO;AACL,WAAK,UAAU,IAAI,GAAG;AAAA,IACxB;AACA,SAAK,SAAA;AAAA,EACP;AAAA;AAAA,EAGA,UAAU,MAAiB;AACzB,QAAI,UAAU;AACd,eAAW,OAAO,MAAM;AACtB,UAAI,CAAC,KAAK,UAAU,IAAI,GAAG,GAAG;AAC5B,aAAK,UAAU,IAAI,GAAG;AACtB,kBAAU;AAAA,MACZ;AAAA,IACF;AACA,QAAI,cAAc,SAAA;AAAA,EACpB;AAAA;AAAA,EAGA,YAAY,MAAiB;AAC3B,QAAI,UAAU;AACd,eAAW,OAAO,MAAM;AACtB,UAAI,KAAK,UAAU,IAAI,GAAG,GAAG;AAC3B,aAAK,UAAU,OAAO,GAAG;AACzB,kBAAU;AAAA,MACZ;AAAA,IACF;AACA,QAAI,cAAc,SAAA;AAAA,EACpB;AAAA;AAAA,EAGA,UAAU,SAAoB;AAC5B,UAAM,cAAc,QAAQ,SAAS,KAAK,QAAQ,MAAM,CAAA,MAAK,KAAK,UAAU,IAAI,CAAC,CAAC;AAClF,QAAI,aAAa;AACf,WAAK,UAAU,MAAA;AAAA,IACjB,OAAO;AACL,iBAAW,OAAO,QAAS,MAAK,UAAU,IAAI,GAAG;AAAA,IACnD;AACA,SAAK,SAAA;AAAA,EACP;AAAA;AAAA,EAGA,OAAO,MAAiB;AAEtB,QAAI,KAAK,WAAW,KAAK,UAAU,QAAQ,KAAK,MAAM,CAAA,MAAK,KAAK,UAAU,IAAI,CAAC,CAAC,EAAG;AACnF,SAAK,UAAU,MAAA;AACf,eAAW,OAAO,KAAM,MAAK,UAAU,IAAI,GAAG;AAC9C,SAAK,SAAA;AAAA,EACP;AAAA;AAAA,EAGA,QAAc;AACZ,QAAI,KAAK,UAAU,SAAS,EAAG;AAC/B,SAAK,UAAU,MAAA;AACf,SAAK,SAAA;AAAA,EACP;AAAA;AAAA;AAAA,EAKA,aAAgB,OAAY,OAA4B;AACtD,WAAO,MAAM,OAAO,CAAA,SAAQ,KAAK,UAAU,IAAI,MAAM,IAAI,CAAC,CAAC;AAAA,EAC7D;AAAA;AAAA;AAAA,EAKA,UAAU,IAA4B;AACpC,SAAK,WAAW,IAAI,EAAE;AACtB,WAAO,MAAM;AAAE,WAAK,WAAW,OAAO,EAAE;AAAA,IAAG;AAAA,EAC7C;AAAA,EAEQ,WAAiB;AAEvB,SAAK,gBAAgB,IAAI,IAAI,KAAK,SAAS;AAC3C,eAAW,MAAM,KAAK,WAAY,IAAA;AAAA,EACpC;AACF;;"}
+{"version":3,"file":"Selection.cjs","sources":["../src/Selection.ts"],"sourcesContent":["import { bindPublicMethods } from './bindPublicMethods';\n\n/**\n * Key-based selection set with toggle and select-all support.\n * Tracks which items are selected by their key (id).\n * Subscribable — auto-tracked when used as a ViewModel property.\n */\nexport class Selection<K extends string | number = string | number> {\n  private _selected: Set<K> = new Set();\n  private _listeners = new Set<() => void>();\n  private _readonlyView: ReadonlySet<K> = this._selected;\n\n  constructor() {\n    bindPublicMethods(this);\n  }\n\n  // ── Readable state ──\n\n  /** Read-only view of currently selected keys. */\n  get selected(): ReadonlySet<K> {\n    return this._readonlyView;\n  }\n\n  /** Number of currently selected items. */\n  get count(): number {\n    return this._selected.size;\n  }\n\n  /** Whether any items are currently selected. */\n  get hasSelection(): boolean {\n    return this._selected.size > 0;\n  }\n\n  // ── Query ──\n\n  /** Check whether a specific key is selected. */\n  isSelected(key: K): boolean {\n    return this._selected.has(key);\n  }\n\n  // ── Actions ──\n\n  /** Toggle a key's selection state (select if unselected, deselect if selected). */\n  toggle(key: K): void {\n    if (this._selected.has(key)) {\n      this._selected.delete(key);\n    } else {\n      this._selected.add(key);\n    }\n    this._publish();\n  }\n\n  /** Add one or more keys to the selection. */\n  select(...keys: K[]): void {\n    let changed = false;\n    for (const key of keys) {\n      if (!this._selected.has(key)) {\n        this._selected.add(key);\n        changed = true;\n      }\n    }\n    if (changed) this._publish();\n  }\n\n  /** Remove one or more keys from the selection. */\n  deselect(...keys: K[]): void {\n    let changed = false;\n    for (const key of keys) {\n      if (this._selected.has(key)) {\n        this._selected.delete(key);\n        changed = true;\n      }\n    }\n    if (changed) this._publish();\n  }\n\n  /** If all selected → deselect all, else select all. */\n  toggleAll(allKeys: K[]): void {\n    const allSelected = allKeys.length > 0 && allKeys.every(k => this._selected.has(k));\n    if (allSelected) {\n      this._selected.clear();\n    } else {\n      for (const key of allKeys) this._selected.add(key);\n    }\n    this._publish();\n  }\n\n  /** Replace the entire selection atomically. Single notification. */\n  set(...keys: K[]): void {\n    // Check if anything actually changed\n    if (keys.length === this._selected.size && keys.every(k => this._selected.has(k))) return;\n    this._selected.clear();\n    for (const key of keys) this._selected.add(key);\n    this._publish();\n  }\n\n  /** Remove all items from the selection. */\n  clear(): void {\n    if (this._selected.size === 0) return;\n    this._selected.clear();\n    this._publish();\n  }\n\n  // ── Utility ──\n\n  /** Filter an array to only items whose key is in the selection. */\n  selectedFrom<T>(items: T[], keyOf: (item: T) => K): T[] {\n    return items.filter(item => this._selected.has(keyOf(item)));\n  }\n\n  // ── Subscribable interface ──\n\n  /** Subscribe to selection changes. Returns an unsubscribe function. */\n  subscribe(cb: () => void): () => void {\n    this._listeners.add(cb);\n    return () => { this._listeners.delete(cb); };\n  }\n\n  private _publish(): void {\n    // Replace readonlyView so reference equality changes (needed for React)\n    this._readonlyView = new Set(this._selected);\n    for (const cb of this._listeners) cb();\n  }\n}\n"],"names":["bindPublicMethods"],"mappings":";;;AAOO,MAAM,UAAuD;AAAA,EAC1D,gCAAwB,IAAA;AAAA,EACxB,iCAAiB,IAAA;AAAA,EACjB,gBAAgC,KAAK;AAAA,EAE7C,cAAc;AACZA,sBAAAA,kBAAkB,IAAI;AAAA,EACxB;AAAA;AAAA;AAAA,EAKA,IAAI,WAA2B;AAC7B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAgB;AAClB,WAAO,KAAK,UAAU;AAAA,EACxB;AAAA;AAAA,EAGA,IAAI,eAAwB;AAC1B,WAAO,KAAK,UAAU,OAAO;AAAA,EAC/B;AAAA;AAAA;AAAA,EAKA,WAAW,KAAiB;AAC1B,WAAO,KAAK,UAAU,IAAI,GAAG;AAAA,EAC/B;AAAA;AAAA;AAAA,EAKA,OAAO,KAAc;AACnB,QAAI,KAAK,UAAU,IAAI,GAAG,GAAG;AAC3B,WAAK,UAAU,OAAO,GAAG;AAAA,IAC3B,OAAO;AACL,WAAK,UAAU,IAAI,GAAG;AAAA,IACxB;AACA,SAAK,SAAA;AAAA,EACP;AAAA;AAAA,EAGA,UAAU,MAAiB;AACzB,QAAI,UAAU;AACd,eAAW,OAAO,MAAM;AACtB,UAAI,CAAC,KAAK,UAAU,IAAI,GAAG,GAAG;AAC5B,aAAK,UAAU,IAAI,GAAG;AACtB,kBAAU;AAAA,MACZ;AAAA,IACF;AACA,QAAI,cAAc,SAAA;AAAA,EACpB;AAAA;AAAA,EAGA,YAAY,MAAiB;AAC3B,QAAI,UAAU;AACd,eAAW,OAAO,MAAM;AACtB,UAAI,KAAK,UAAU,IAAI,GAAG,GAAG;AAC3B,aAAK,UAAU,OAAO,GAAG;AACzB,kBAAU;AAAA,MACZ;AAAA,IACF;AACA,QAAI,cAAc,SAAA;AAAA,EACpB;AAAA;AAAA,EAGA,UAAU,SAAoB;AAC5B,UAAM,cAAc,QAAQ,SAAS,KAAK,QAAQ,MAAM,CAAA,MAAK,KAAK,UAAU,IAAI,CAAC,CAAC;AAClF,QAAI,aAAa;AACf,WAAK,UAAU,MAAA;AAAA,IACjB,OAAO;AACL,iBAAW,OAAO,QAAS,MAAK,UAAU,IAAI,GAAG;AAAA,IACnD;AACA,SAAK,SAAA;AAAA,EACP;AAAA;AAAA,EAGA,OAAO,MAAiB;AAEtB,QAAI,KAAK,WAAW,KAAK,UAAU,QAAQ,KAAK,MAAM,CAAA,MAAK,KAAK,UAAU,IAAI,CAAC,CAAC,EAAG;AACnF,SAAK,UAAU,MAAA;AACf,eAAW,OAAO,KAAM,MAAK,UAAU,IAAI,GAAG;AAC9C,SAAK,SAAA;AAAA,EACP;AAAA;AAAA,EAGA,QAAc;AACZ,QAAI,KAAK,UAAU,SAAS,EAAG;AAC/B,SAAK,UAAU,MAAA;AACf,SAAK,SAAA;AAAA,EACP;AAAA;AAAA;AAAA,EAKA,aAAgB,OAAY,OAA4B;AACtD,WAAO,MAAM,OAAO,CAAA,SAAQ,KAAK,UAAU,IAAI,MAAM,IAAI,CAAC,CAAC;AAAA,EAC7D;AAAA;AAAA;AAAA,EAKA,UAAU,IAA4B;AACpC,SAAK,WAAW,IAAI,EAAE;AACtB,WAAO,MAAM;AAAE,WAAK,WAAW,OAAO,EAAE;AAAA,IAAG;AAAA,EAC7C;AAAA,EAEQ,WAAiB;AAEvB,SAAK,gBAAgB,IAAI,IAAI,KAAK,SAAS;AAC3C,eAAW,MAAM,KAAK,WAAY,IAAA;AAAA,EACpC;AACF;;"}

package/dist/Selection.d.ts

@@ -7,6 +7,7 @@ export declare class Selection<K extends string | number = string | number> {
     private _selected;
     private _listeners;
     private _readonlyView;
+    constructor();
     /** Read-only view of currently selected keys. */
     get selected(): ReadonlySet<K>;
     /** Number of currently selected items. */

package/dist/Selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Selection.d.ts","sourceRoot":"","sources":["../src/Selection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM;IAChE,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,aAAa,CAAkC;IAIvD,iDAAiD;IACjD,IAAI,QAAQ,IAAI,WAAW,CAAC,CAAC,CAAC,CAE7B;IAED,0CAA0C;IAC1C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,gDAAgD;IAChD,IAAI,YAAY,IAAI,OAAO,CAE1B;IAID,gDAAgD;IAChD,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAM3B,mFAAmF;IACnF,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IASpB,6CAA6C;IAC7C,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAW1B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAW5B,uDAAuD;IACvD,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI;IAU7B,oEAAoE;IACpE,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAQvB,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAQb,mEAAmE;IACnE,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IAMvD,uEAAuE;IACvE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,OAAO,CAAC,QAAQ;CAKjB"}
+{"version":3,"file":"Selection.d.ts","sourceRoot":"","sources":["../src/Selection.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM;IAChE,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,aAAa,CAAkC;;IAQvD,iDAAiD;IACjD,IAAI,QAAQ,IAAI,WAAW,CAAC,CAAC,CAAC,CAE7B;IAED,0CAA0C;IAC1C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,gDAAgD;IAChD,IAAI,YAAY,IAAI,OAAO,CAE1B;IAID,gDAAgD;IAChD,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAM3B,mFAAmF;IACnF,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IASpB,6CAA6C;IAC7C,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAW1B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAW5B,uDAAuD;IACvD,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI;IAU7B,oEAAoE;IACpE,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAQvB,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAQb,mEAAmE;IACnE,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IAMvD,uEAAuE;IACvE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/Selection.js

@@ -1,7 +1,11 @@
+import { bindPublicMethods } from "./bindPublicMethods.js";
 class Selection {
   _selected = /* @__PURE__ */ new Set();
   _listeners = /* @__PURE__ */ new Set();
   _readonlyView = this._selected;
+  constructor() {
+    bindPublicMethods(this);
+  }
   // ── Readable state ──
   /** Read-only view of currently selected keys. */
   get selected() {