mvc-kit 2.2.2 → 2.2.3

package/dist/mvc-kit.js

@@ -1,6 +1,6 @@
-import { E as y } from "./singleton-C8_FRbA7.js";
-import { h as N, s as V, t as B, a as L } from "./singleton-C8_FRbA7.js";
-class w extends Error {
+import { E as w } from "./singleton-CaEXSbYg.js";
+import { h as N, s as V, t as B, a as L } from "./singleton-CaEXSbYg.js";
+class y extends Error {
   constructor(t, e) {
     super(e ?? `HTTP ${t}`), this.status = t, this.name = "HttpError";
   }
@@ -19,7 +19,7 @@ function O(n) {
     code: "abort",
     message: "Request was aborted",
     original: n
-  } : n instanceof w ? {
+  } : n instanceof y ? {
     code: C(n.status),
     message: n.message,
     status: n.status,
@@ -47,7 +47,7 @@ function O(n) {
     original: n
   };
 }
-const _ = typeof __MVC_KIT_DEV__ < "u" && __MVC_KIT_DEV__;
+const u = typeof __MVC_KIT_DEV__ < "u" && __MVC_KIT_DEV__;
 function E(n) {
   return n !== null && typeof n == "object" && typeof n.subscribe == "function";
 }
@@ -55,8 +55,8 @@ function g(n, t, e) {
   let s = Object.getPrototypeOf(n);
   for (; s && s !== t; ) {
     const i = Object.getOwnPropertyDescriptors(s);
-    for (const [o, a] of Object.entries(i))
-      o !== "constructor" && e(o, a, s);
+    for (const [r, c] of Object.entries(i))
+      r !== "constructor" && e(r, c, s);
     s = Object.getPrototypeOf(s);
   }
 }
@@ -82,25 +82,32 @@ class b {
   _asyncListeners = /* @__PURE__ */ new Set();
   _asyncProxy = null;
   _activeOps = null;
+  /** DEV-only timeout (ms) for detecting ghost async operations after dispose. */
   static GHOST_TIMEOUT = 3e3;
   constructor(t) {
     this._state = Object.freeze({ ...t }), this._initialState = this._state, this._guardReservedKeys();
   }
+  /** Current frozen state object. */
   get state() {
     return this._state;
   }
+  /** Whether this instance has been disposed. */
   get disposed() {
     return this._disposed;
   }
+  /** Whether init() has been called. */
   get initialized() {
     return this._initialized;
   }
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
   get disposeSignal() {
     return this._abortController || (this._abortController = new AbortController()), this._abortController.signal;
   }
+  /** Lazily-created typed EventBus for emitting and subscribing to events. */
   get events() {
-    return this._eventBus || (this._eventBus = new y()), this._eventBus;
+    return this._eventBus || (this._eventBus = new w()), this._eventBus;
   }
+  /** Initializes the instance. Called automatically by React hooks after mount. */
   init() {
     if (!(this._initialized || this._disposed))
       return this._initialized = !0, this._trackSubscribables(), this._installStateProxy(), this._memoizeGetters(), this._wrapMethods(), this.onInit?.();
@@ -117,7 +124,7 @@ class b {
    */
   set(t) {
     if (this._disposed) return;
-    if (_ && this._stateTracking) {
+    if (u && this._stateTracking) {
       console.error(
         "[mvc-kit] set() called inside a getter. Getters must be pure — they read state and return a value. They must never call set(), which would cause an infinite render loop. Move this logic to an action method."
       );
@@ -125,23 +132,30 @@ class b {
     }
     const e = typeof t == "function" ? t(this._state) : t;
     if (!Object.keys(e).some(
-      (c) => e[c] !== this._state[c]
+      (a) => e[a] !== this._state[a]
     ))
       return;
-    const o = this._state, a = Object.freeze({ ...o, ...e });
-    this._state = a, this._revision++, this.onSet?.(o, a);
-    for (const c of this._listeners)
-      c(a, o);
+    const r = this._state, c = Object.freeze({ ...r, ...e });
+    this._state = c, this._revision++, this.onSet?.(r, c);
+    for (const a of this._listeners)
+      a(c, r);
   }
+  /**
+   * Emits a typed event via the internal EventBus.
+   * Safe to call during dispose cleanup callbacks.
+   * @protected
+   */
   emit(t, e) {
     (this._eventBus?.disposed ?? this._disposed) || this.events.emit(t, e);
   }
+  /** Subscribes to state changes. Returns an unsubscribe function. */
   subscribe(t) {
     return this._disposed ? () => {
     } : (this._listeners.add(t), () => {
       this._listeners.delete(t);
     });
   }
+  /** Tears down the instance, releasing all subscriptions and resources. */
   dispose() {
     if (!this._disposed) {
       if (this._disposed = !0, this._teardownSubscriptions(), this._abortController?.abort(), this._cleanups) {
@@ -151,6 +165,10 @@ class b {
       this._eventBus?.dispose(), this.onDispose?.(), this._listeners.clear();
     }
   }
+  /**
+   * Resets state to initial values (or provided state), aborts in-flight work,
+   * clears async tracking, and re-runs onInit().
+   */
   reset(t) {
     if (!this._disposed) {
       this._abortController?.abort(), this._abortController = null, this._teardownSubscriptions(), this._state = t ? Object.freeze({ ...t }) : this._initialState, this._revision++, this._asyncStates.clear(), this._asyncSnapshots.clear(), this._notifyAsync(), this._trackSubscribables();
@@ -159,14 +177,22 @@ class b {
       return this.onInit?.();
     }
   }
+  /**
+   * Registers a cleanup function to be called on dispose. Used internally for things like method wrapper
+   * cleanup and event bus disposal, but can also be used by subclasses for custom cleanup logic.
+   * @param fn
+   * @protected
+   */
   addCleanup(t) {
     this._cleanups || (this._cleanups = []), this._cleanups.push(t);
   }
+  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
   subscribeTo(t, e) {
     const s = t.subscribe(e);
     return this._subscriptionCleanups || (this._subscriptionCleanups = []), this._subscriptionCleanups.push(s), s;
   }
   // ── Async tracking API ──────────────────────────────────────────
+  /** Proxy providing `TaskState` (loading, error, errorCode) per async method. */
   get async() {
     if (!this._asyncProxy) {
       const t = this;
@@ -188,6 +214,7 @@ class b {
     }
     return this._asyncProxy;
   }
+  /** Subscribes to async state changes. Used by `useAsync` for React integration. */
   subscribeAsync(t) {
     return this._disposed ? () => {
     } : (this._asyncListeners.add(t), () => {
@@ -221,78 +248,78 @@ class b {
           `[mvc-kit] "${i}" is a reserved property on ViewModel and cannot be overridden.`
         );
     const t = this, e = /* @__PURE__ */ new Set(), s = [];
-    _ && (this._activeOps = /* @__PURE__ */ new Map()), g(this, b.prototype, (i, o) => {
-      if (o.get || o.set || typeof o.value != "function" || i.startsWith("_") || z.has(i) || e.has(i)) return;
+    u && (this._activeOps = /* @__PURE__ */ new Map()), g(this, b.prototype, (i, r) => {
+      if (r.get || r.set || typeof r.value != "function" || i.startsWith("_") || z.has(i) || e.has(i)) return;
       e.add(i);
-      const a = o.value;
-      let c = !1;
-      const d = function(...f) {
+      const c = r.value;
+      let a = !1;
+      const l = function(...f) {
         if (t._disposed) {
-          _ && console.warn(`[mvc-kit] "${i}" called after dispose — ignored.`);
+          u && console.warn(`[mvc-kit] "${i}" called after dispose — ignored.`);
           return;
         }
-        _ && !t._initialized && console.warn(
+        u && !t._initialized && console.warn(
           `[mvc-kit] "${i}" called before init(). Async tracking is active only after init().`
         );
-        let h;
+        let _;
         try {
-          h = a.apply(t, f);
-        } catch (l) {
-          throw l;
+          _ = c.apply(t, f);
+        } catch (h) {
+          throw h;
         }
-        if (!h || typeof h.then != "function")
-          return c || (c = !0, t._asyncStates.delete(i), t._asyncSnapshots.delete(i), t[i] = a.bind(t)), h;
-        let r = t._asyncStates.get(i);
-        return r || (r = { loading: !1, error: null, errorCode: null, count: 0 }, t._asyncStates.set(i, r)), r.count++, r.loading = !0, r.error = null, r.errorCode = null, t._asyncSnapshots.set(i, Object.freeze({ loading: !0, error: null, errorCode: null })), t._notifyAsync(), _ && t._activeOps && t._activeOps.set(i, (t._activeOps.get(i) ?? 0) + 1), h.then(
-          (l) => {
-            if (t._disposed) return l;
-            if (r.count--, r.loading = r.count > 0, t._asyncSnapshots.set(
+        if (!_ || typeof _.then != "function")
+          return a || (a = !0, t._asyncStates.delete(i), t._asyncSnapshots.delete(i), t[i] = c.bind(t)), _;
+        let o = t._asyncStates.get(i);
+        return o || (o = { loading: !1, error: null, errorCode: null, count: 0 }, t._asyncStates.set(i, o)), o.count++, o.loading = !0, o.error = null, o.errorCode = null, t._asyncSnapshots.set(i, Object.freeze({ loading: !0, error: null, errorCode: null })), t._notifyAsync(), u && t._activeOps && t._activeOps.set(i, (t._activeOps.get(i) ?? 0) + 1), _.then(
+          (h) => {
+            if (t._disposed) return h;
+            if (o.count--, o.loading = o.count > 0, t._asyncSnapshots.set(
               i,
-              Object.freeze({ loading: r.loading, error: r.error, errorCode: r.errorCode })
-            ), t._notifyAsync(), _ && t._activeOps) {
-              const u = (t._activeOps.get(i) ?? 1) - 1;
-              u <= 0 ? t._activeOps.delete(i) : t._activeOps.set(i, u);
+              Object.freeze({ loading: o.loading, error: o.error, errorCode: o.errorCode })
+            ), t._notifyAsync(), u && t._activeOps) {
+              const d = (t._activeOps.get(i) ?? 1) - 1;
+              d <= 0 ? t._activeOps.delete(i) : t._activeOps.set(i, d);
             }
-            return l;
+            return h;
           },
-          (l) => {
-            if (v(l)) {
-              if (t._disposed || (r.count--, r.loading = r.count > 0, t._asyncSnapshots.set(
+          (h) => {
+            if (v(h)) {
+              if (t._disposed || (o.count--, o.loading = o.count > 0, t._asyncSnapshots.set(
                 i,
-                Object.freeze({ loading: r.loading, error: r.error, errorCode: r.errorCode })
-              ), t._notifyAsync()), _ && t._activeOps) {
+                Object.freeze({ loading: o.loading, error: o.error, errorCode: o.errorCode })
+              ), t._notifyAsync()), u && t._activeOps) {
                 const p = (t._activeOps.get(i) ?? 1) - 1;
                 p <= 0 ? t._activeOps.delete(i) : t._activeOps.set(i, p);
               }
               return;
             }
             if (t._disposed) return;
-            r.count--, r.loading = r.count > 0;
-            const u = O(l);
-            if (r.error = u.message, r.errorCode = u.code, t._asyncSnapshots.set(
+            o.count--, o.loading = o.count > 0;
+            const d = O(h);
+            if (o.error = d.message, o.errorCode = d.code, t._asyncSnapshots.set(
               i,
-              Object.freeze({ loading: r.loading, error: u.message, errorCode: u.code })
-            ), t._notifyAsync(), _ && t._activeOps) {
+              Object.freeze({ loading: o.loading, error: d.message, errorCode: d.code })
+            ), t._notifyAsync(), u && t._activeOps) {
               const p = (t._activeOps.get(i) ?? 1) - 1;
               p <= 0 ? t._activeOps.delete(i) : t._activeOps.set(i, p);
             }
-            throw l;
+            throw h;
           }
         );
       };
-      s.push(i), t[i] = d;
+      s.push(i), t[i] = l;
     }), s.length > 0 && this.addCleanup(() => {
-      const i = _ && t._activeOps ? new Map(t._activeOps) : null;
-      for (const o of s)
-        _ ? t[o] = () => {
-          console.warn(`[mvc-kit] "${o}" called after dispose — ignored.`);
-        } : t[o] = () => {
+      const i = u && t._activeOps ? new Map(t._activeOps) : null;
+      for (const r of s)
+        u ? t[r] = () => {
+          console.warn(`[mvc-kit] "${r}" called after dispose — ignored.`);
+        } : t[r] = () => {
         };
-      t._asyncListeners.clear(), t._asyncStates.clear(), t._asyncSnapshots.clear(), _ && i && i.size > 0 && t._scheduleGhostCheck(i);
+      t._asyncListeners.clear(), t._asyncStates.clear(), t._asyncSnapshots.clear(), u && i && i.size > 0 && t._scheduleGhostCheck(i);
     });
   }
   _scheduleGhostCheck(t) {
-    _ && setTimeout(() => {
+    u && setTimeout(() => {
       for (const [e, s] of t)
         console.warn(
           `[mvc-kit] Ghost async operation detected: "${e}" had ${s} pending call(s) when the ViewModel was disposed. Consider using disposeSignal to cancel in-flight work.`
@@ -388,49 +415,49 @@ class b {
    *   Tier 3 (slow):   at least one dep changed → full recompute with tracking
    */
   _wrapGetter(t, e) {
-    let s, i = -1, o, a, c;
+    let s, i = -1, r, c, a;
     Object.defineProperty(this, t, {
       get: () => {
         if (this._disposed || i === this._revision)
           return s;
-        if (o && a) {
-          let r = !0;
-          for (const [l, u] of a)
-            if (this._state[l] !== u) {
-              r = !1;
+        if (r && c) {
+          let o = !0;
+          for (const [h, d] of c)
+            if (this._state[h] !== d) {
+              o = !1;
               break;
             }
-          if (r && c)
-            for (const [l, u] of c) {
-              const p = this._trackedSources.get(l);
-              if (p && p.revision !== u) {
-                r = !1;
+          if (o && a)
+            for (const [h, d] of a) {
+              const p = this._trackedSources.get(h);
+              if (p && p.revision !== d) {
+                o = !1;
                 break;
               }
             }
-          if (r)
+          if (o)
             return i = this._revision, s;
         }
-        const d = this._stateTracking, f = this._sourceTracking;
+        const l = this._stateTracking, f = this._sourceTracking;
         this._stateTracking = /* @__PURE__ */ new Set(), this._sourceTracking = /* @__PURE__ */ new Map();
         try {
           s = e.call(this);
-        } catch (r) {
-          throw this._stateTracking = d, this._sourceTracking = f, r;
+        } catch (o) {
+          throw this._stateTracking = l, this._sourceTracking = f, o;
         }
-        o = this._stateTracking;
-        const h = this._sourceTracking;
-        if (this._stateTracking = d, this._sourceTracking = f, d)
-          for (const r of o) d.add(r);
+        r = this._stateTracking;
+        const _ = this._sourceTracking;
+        if (this._stateTracking = l, this._sourceTracking = f, l)
+          for (const o of r) l.add(o);
         if (f)
-          for (const [r, l] of h)
-            f.set(r, l);
-        a = /* @__PURE__ */ new Map();
-        for (const r of o)
-          a.set(r, this._state[r]);
+          for (const [o, h] of _)
+            f.set(o, h);
         c = /* @__PURE__ */ new Map();
-        for (const [r, l] of h)
-          c.set(r, l.revision);
+        for (const o of r)
+          c.set(o, this._state[o]);
+        a = /* @__PURE__ */ new Map();
+        for (const [o, h] of _)
+          a.set(o, h.revision);
         return i = this._revision, s;
       },
       configurable: !0,
@@ -450,6 +477,7 @@ class M {
     const e = Object.freeze({ ...t });
     this._state = e, this._committed = e;
   }
+  /** Current frozen state object. */
   get state() {
     return this._state;
   }
@@ -477,31 +505,39 @@ class M {
   get valid() {
     return Object.keys(this.errors).length === 0;
   }
+  /** Whether this instance has been disposed. */
   get disposed() {
     return this._disposed;
   }
+  /** Whether init() has been called. */
   get initialized() {
     return this._initialized;
   }
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
   get disposeSignal() {
     return this._abortController || (this._abortController = new AbortController()), this._abortController.signal;
   }
+  /** Initializes the instance. Called automatically by React hooks after mount. */
   init() {
     if (!(this._initialized || this._disposed))
       return this._initialized = !0, this.onInit?.();
   }
+  /**
+   * Merges partial state with validation. No-op if no values changed by reference.
+   * @protected
+   */
   set(t) {
     if (this._disposed)
       throw new Error("Cannot set state on disposed Model");
     const e = typeof t == "function" ? t(this._state) : t;
     if (!Object.keys(e).some(
-      (c) => e[c] !== this._state[c]
+      (a) => e[a] !== this._state[a]
     ))
       return;
-    const o = this._state, a = Object.freeze({ ...o, ...e });
-    this._state = a, this.onSet?.(o, a);
-    for (const c of this._listeners)
-      c(a, o);
+    const r = this._state, c = Object.freeze({ ...r, ...e });
+    this._state = c, this.onSet?.(r, c);
+    for (const a of this._listeners)
+      a(c, r);
   }
   /**
    * Mark current state as the new baseline (not dirty).
@@ -524,12 +560,14 @@ class M {
     for (const e of this._listeners)
       e(this._state, t);
   }
+  /** Subscribes to state changes. Returns an unsubscribe function. */
   subscribe(t) {
     return this._disposed ? () => {
     } : (this._listeners.add(t), () => {
       this._listeners.delete(t);
     });
   }
+  /** Tears down the instance, releasing all subscriptions and resources. */
   dispose() {
     if (!this._disposed) {
       if (this._disposed = !0, this._abortController?.abort(), this._cleanups) {
@@ -546,9 +584,11 @@ class M {
   validate(t) {
     return {};
   }
+  /** Registers a cleanup function to be called on dispose. @protected */
   addCleanup(t) {
     this._cleanups || (this._cleanups = []), this._cleanups.push(t);
   }
+  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
   subscribeTo(t, e) {
     const s = t.subscribe(e);
     return this.addCleanup(s), s;
@@ -557,8 +597,8 @@ class M {
     const s = Object.keys(t), i = Object.keys(e);
     if (s.length !== i.length)
       return !1;
-    for (const o of s)
-      if (t[o] !== e[o])
+    for (const r of s)
+      if (t[r] !== e[r])
         return !1;
     return !0;
   }
@@ -579,32 +619,71 @@ class x {
   get state() {
     return this._items;
   }
+  /** The raw readonly array of items. */
   get items() {
     return this._items;
   }
+  /** Number of items in the collection. */
   get length() {
     return this._items.length;
   }
+  /** Whether this instance has been disposed. */
   get disposed() {
     return this._disposed;
   }
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
   get disposeSignal() {
     return this._abortController || (this._abortController = new AbortController()), this._abortController.signal;
   }
   // ── CRUD Methods (notify listeners) ──
   /**
-   * Add one or more items.
+   * Add one or more items. Items with existing IDs are silently skipped.
    */
   add(...t) {
     if (this._disposed)
       throw new Error("Cannot add to disposed Collection");
     if (t.length === 0)
       return;
-    const e = this._items;
-    this._items = Object.freeze([...e, ...t]);
-    for (const s of t)
-      this._index.set(s.id, s);
-    this.notify(e);
+    const e = /* @__PURE__ */ new Set(), s = [];
+    for (const r of t)
+      !this._index.has(r.id) && !e.has(r.id) && (s.push(r), e.add(r.id));
+    if (s.length === 0) return;
+    const i = this._items;
+    this._items = Object.freeze([...i, ...s]);
+    for (const r of s)
+      this._index.set(r.id, r);
+    this.notify(i);
+  }
+  /**
+   * Add or replace items by ID. Existing items are replaced in-place
+   * (preserving array position); new items are appended. Deduplicates
+   * input — last occurrence wins. No-op if nothing changed (reference
+   * comparison).
+   */
+  upsert(...t) {
+    if (this._disposed)
+      throw new Error("Cannot upsert on disposed Collection");
+    if (t.length === 0) return;
+    const e = /* @__PURE__ */ new Map();
+    for (const a of t)
+      e.set(a.id, a);
+    const s = this._items;
+    let i = !1;
+    const r = /* @__PURE__ */ new Set(), c = [];
+    for (const a of s)
+      if (e.has(a.id)) {
+        const l = e.get(a.id);
+        l !== a && (i = !0), c.push(l), r.add(a.id);
+      } else
+        c.push(a);
+    for (const [a, l] of e)
+      r.has(a) || (c.push(l), i = !0);
+    if (i) {
+      this._items = Object.freeze(c);
+      for (const [a, l] of e)
+        this._index.set(a, l);
+      this.notify(s);
+    }
   }
   /**
    * Remove items by id(s).
@@ -614,13 +693,13 @@ class x {
       throw new Error("Cannot remove from disposed Collection");
     if (t.length === 0)
       return;
-    const e = new Set(t), s = this._items.filter((o) => !e.has(o.id));
+    const e = new Set(t), s = this._items.filter((r) => !e.has(r.id));
     if (s.length === this._items.length)
       return;
     const i = this._items;
     this._items = Object.freeze(s);
-    for (const o of t)
-      this._index.delete(o);
+    for (const r of t)
+      this._index.delete(r);
     this.notify(i);
   }
   /**
@@ -629,14 +708,14 @@ class x {
   update(t, e) {
     if (this._disposed)
       throw new Error("Cannot update disposed Collection");
-    const s = this._items.findIndex((h) => h.id === t);
+    const s = this._items.findIndex((_) => _.id === t);
     if (s === -1)
       return;
-    const i = this._items[s], o = { ...i, ...e, id: t };
-    if (!Object.keys(e).some((h) => e[h] !== i[h]))
+    const i = this._items[s], r = { ...i, ...e, id: t };
+    if (!Object.keys(e).some((_) => e[_] !== i[_]))
       return;
-    const d = this._items, f = [...d];
-    f[s] = o, this._items = Object.freeze(f), this._index.set(t, o), this.notify(d);
+    const l = this._items, f = [...l];
+    f[s] = r, this._items = Object.freeze(f), this._index.set(t, r), this.notify(l);
   }
   /**
    * Replace all items.
@@ -713,12 +792,14 @@ class x {
     return this._items.map(t);
   }
   // ── Subscribable interface ──
+  /** Subscribes to state changes. Returns an unsubscribe function. */
   subscribe(t) {
     return this._disposed ? () => {
     } : (this._listeners.add(t), () => {
       this._listeners.delete(t);
     });
   }
+  /** Tears down the instance, releasing all subscriptions and resources. */
   dispose() {
     if (!this._disposed) {
       if (this._disposed = !0, this._abortController?.abort(), this._cleanups) {
@@ -728,6 +809,7 @@ class x {
       this.onDispose?.(), this._listeners.clear(), this._index.clear();
     }
   }
+  /** Registers a cleanup function to be called on dispose. @protected */
   addCleanup(t) {
     this._cleanups || (this._cleanups = []), this._cleanups.push(t);
   }
@@ -746,19 +828,24 @@ class D {
   _initialized = !1;
   _abortController = null;
   _cleanups = null;
+  /** Whether this instance has been disposed. */
   get disposed() {
     return this._disposed;
   }
+  /** Whether init() has been called. */
   get initialized() {
     return this._initialized;
   }
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
   get disposeSignal() {
     return this._abortController || (this._abortController = new AbortController()), this._abortController.signal;
   }
+  /** Initializes the instance. Called automatically by React hooks after mount. */
   init() {
     if (!(this._initialized || this._disposed))
       return this._initialized = !0, this.onInit?.();
   }
+  /** Tears down the instance, releasing all subscriptions and resources. */
   dispose() {
     if (!this._disposed) {
       if (this._disposed = !0, this._abortController?.abort(), this._cleanups) {
@@ -768,32 +855,39 @@ class D {
       this.onDispose?.();
     }
   }
+  /** Registers a cleanup function to be called on dispose. @protected */
   addCleanup(t) {
     this._cleanups || (this._cleanups = []), this._cleanups.push(t);
   }
+  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
   subscribeTo(t, e) {
     const s = t.subscribe(e);
     return this.addCleanup(s), s;
   }
 }
-class P {
+class I {
   _disposed = !1;
   _initialized = !1;
   _abortController = null;
   _cleanups = null;
+  /** Whether this instance has been disposed. */
   get disposed() {
     return this._disposed;
   }
+  /** Whether init() has been called. */
   get initialized() {
     return this._initialized;
   }
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
   get disposeSignal() {
     return this._abortController || (this._abortController = new AbortController()), this._abortController.signal;
   }
+  /** Initializes the instance. Called automatically by React hooks after mount. */
   init() {
     if (!(this._initialized || this._disposed))
       return this._initialized = !0, this.onInit?.();
   }
+  /** Tears down the instance, releasing all subscriptions and resources. */
   dispose() {
     if (!this._disposed) {
       if (this._disposed = !0, this._abortController?.abort(), this._cleanups) {
@@ -803,6 +897,7 @@ class P {
       this.onDispose?.();
     }
   }
+  /** Registers a cleanup function to be called on dispose. @protected */
   addCleanup(t) {
     this._cleanups || (this._cleanups = []), this._cleanups.push(t);
   }
@@ -813,11 +908,15 @@ const m = typeof __MVC_KIT_DEV__ < "u" && __MVC_KIT_DEV__, k = Object.freeze({
   attempt: 0,
   error: null
 });
-class I {
+class P {
   // Static config (subclass overrides)
+  /** Base delay (ms) for reconnection backoff. */
   static RECONNECT_BASE = 1e3;
+  /** Maximum delay cap (ms) for reconnection backoff. */
   static RECONNECT_MAX = 3e4;
+  /** Exponential backoff multiplier for reconnection delay. */
   static RECONNECT_FACTOR = 2;
+  /** Maximum number of reconnection attempts before giving up. */
   static MAX_ATTEMPTS = 1 / 0;
   // ── Internal state ──────────────────────────────────────────────
   _status = k;
@@ -831,9 +930,11 @@ class I {
   _reconnectTimer = null;
   _cleanups = null;
   // ── Subscribable<ChannelStatus> ─────────────────────────────────
+  /** Current connection status. */
   get state() {
     return this._status;
   }
+  /** Subscribes to connection status changes. Returns an unsubscribe function. */
   subscribe(t) {
     return this._disposed ? () => {
     } : (this._listeners.add(t), () => {
@@ -841,19 +942,24 @@ class I {
     });
   }
   // ── Disposable / Initializable ──────────────────────────────────
+  /** Whether this instance has been disposed. */
   get disposed() {
     return this._disposed;
   }
+  /** Whether init() has been called. */
   get initialized() {
     return this._initialized;
   }
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
   get disposeSignal() {
     return this._abortController || (this._abortController = new AbortController()), this._abortController.signal;
   }
+  /** Initializes the instance. Called automatically by React hooks after mount. */
   init() {
     if (!(this._initialized || this._disposed))
       return this._initialized = !0, this.onInit?.();
   }
+  /** Tears down the instance, releasing all subscriptions and resources. */
   dispose() {
     if (!this._disposed) {
       this._disposed = !0, this._connState = 4, this._reconnectTimer !== null && (clearTimeout(this._reconnectTimer), this._reconnectTimer = null), this._connectAbort?.abort(), this._connectAbort = null, this._abortController?.abort();
@@ -869,6 +975,7 @@ class I {
     }
   }
   // ── Connection control ──────────────────────────────────────────
+  /** Initiates a connection with automatic reconnection on failure. */
   connect() {
     if (this._disposed) {
       m && console.warn("[mvc-kit] connect() called after dispose — ignored.");
@@ -876,6 +983,7 @@ class I {
     }
     m && !this._initialized && console.warn("[mvc-kit] connect() called before init()."), !(this._connState === 1 || this._connState === 2) && (this._reconnectTimer !== null && (clearTimeout(this._reconnectTimer), this._reconnectTimer = null), this._attemptConnect(0));
   }
+  /** Closes the connection and cancels any pending reconnection. */
   disconnect() {
     if (!this._disposed) {
       if (this._reconnectTimer !== null && (clearTimeout(this._reconnectTimer), this._reconnectTimer = null), this._connectAbort?.abort(), this._connectAbort = null, this._connState === 2 || this._connState === 1) {
@@ -890,6 +998,7 @@ class I {
     }
   }
   // ── Subclass signals ────────────────────────────────────────────
+  /** Call from subclass when a message arrives from the transport. @protected */
   receive(t, e) {
     if (this._disposed) {
       m && console.warn(`[mvc-kit] receive("${String(t)}") called after dispose — ignored.`);
@@ -900,10 +1009,12 @@ class I {
       for (const i of s)
         i(e);
   }
+  /** Call from subclass when the transport connection drops unexpectedly. Triggers reconnection. @protected */
   disconnected() {
     this._disposed || this._connState !== 2 && this._connState !== 1 || (this._connectAbort?.abort(), this._connectAbort = null, this._connState = 3, this._scheduleReconnect(1));
   }
   // ── Consumer API ────────────────────────────────────────────────
+  /** Subscribes to a specific message type. Returns an unsubscribe function. */
   on(t, e) {
     if (this._disposed) return () => {
     };
@@ -912,6 +1023,7 @@ class I {
       s.delete(e);
     };
   }
+  /** Subscribes to a message type, auto-removing the handler after the first invocation. */
   once(t, e) {
     const s = this.on(t, (i) => {
       s(), e(i);
@@ -919,14 +1031,17 @@ class I {
     return s;
   }
   // ── Infrastructure ──────────────────────────────────────────────
+  /** Registers a cleanup function to be called on dispose. @protected */
   addCleanup(t) {
     this._cleanups || (this._cleanups = []), this._cleanups.push(t);
   }
+  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
   subscribeTo(t, e) {
     const s = t.subscribe(e);
     return this.addCleanup(s), s;
   }
   // ── Backoff ─────────────────────────────────────────────────────
+  /** Computes the reconnect backoff delay with jitter for the given attempt number. @protected */
   _calculateDelay(t) {
     const e = this.constructor, s = Math.min(
       e.RECONNECT_BASE * Math.pow(e.RECONNECT_FACTOR, t),
@@ -994,20 +1109,20 @@ class I {
       attempt: t,
       error: i
     });
-    const o = this._calculateDelay(t - 1);
+    const r = this._calculateDelay(t - 1);
     this._reconnectTimer = setTimeout(() => {
       this._reconnectTimer = null, this._attemptConnect(t);
-    }, o);
+    }, r);
   }
 }
 export {
-  I as Channel,
+  P as Channel,
   x as Collection,
   D as Controller,
-  y as EventBus,
-  w as HttpError,
+  w as EventBus,
+  y as HttpError,
   M as Model,
-  P as Service,
+  I as Service,
   b as ViewModel,
   O as classifyError,
   N as hasSingleton,