mvc-kit 2.12.4 → 2.13.0

package/dist/ViewModel.js

@@ -1,583 +1,535 @@
-import { EventBus } from "./EventBus.js";
 import { walkPrototypeChain } from "./walkPrototypeChain.js";
+import { EventBus } from "./EventBus.js";
 import { wrapAsyncMethods } from "./wrapAsyncMethods.js";
 import { resolveDraftUpdater } from "./produceDraft.js";
-const __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
+//#region src/ViewModel.ts
+var __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
 function freeze(obj) {
-  return __DEV__ ? Object.freeze(obj) : obj;
+	return __DEV__ ? Object.freeze(obj) : obj;
 }
-const classMembers = /* @__PURE__ */ new WeakMap();
+var classMembers = /* @__PURE__ */ new WeakMap();
 function getClassMemberInfo(instance, stopPrototype, reservedKeys, lifecycleHooks) {
-  const ctor = instance.constructor;
-  let info = classMembers.get(ctor);
-  if (info) return info;
-  const getters = [];
-  const methods = [];
-  const found = [];
-  const processedGetters = /* @__PURE__ */ new Set();
-  const processedMethods = /* @__PURE__ */ new Set();
-  walkPrototypeChain(instance, stopPrototype, (key, desc) => {
-    if (reservedKeys.includes(key)) {
-      found.push(key);
-    }
-    if (desc.get && !processedGetters.has(key)) {
-      processedGetters.add(key);
-      getters.push({ key, get: desc.get });
-    }
-    if (!desc.get && !desc.set && typeof desc.value === "function" && !key.startsWith("_") && !lifecycleHooks.has(key) && !processedMethods.has(key)) {
-      processedMethods.add(key);
-      methods.push({ key, fn: desc.value });
-    }
-  });
-  info = { getters, methods, reservedKeys: found };
-  classMembers.set(ctor, info);
-  return info;
+	const ctor = instance.constructor;
+	let info = classMembers.get(ctor);
+	if (info) return info;
+	const getters = [];
+	const methods = [];
+	const found = [];
+	const processedGetters = /* @__PURE__ */ new Set();
+	const processedMethods = /* @__PURE__ */ new Set();
+	walkPrototypeChain(instance, stopPrototype, (key, desc) => {
+		if (reservedKeys.includes(key)) found.push(key);
+		if (desc.get && !processedGetters.has(key)) {
+			processedGetters.add(key);
+			getters.push({
+				key,
+				get: desc.get
+			});
+		}
+		if (!desc.get && !desc.set && typeof desc.value === "function" && !key.startsWith("_") && !lifecycleHooks.has(key) && !processedMethods.has(key)) {
+			processedMethods.add(key);
+			methods.push({
+				key,
+				fn: desc.value
+			});
+		}
+	});
+	info = {
+		getters,
+		methods,
+		reservedKeys: found
+	};
+	classMembers.set(ctor, info);
+	return info;
 }
-let _activeStateTracking = null;
-let _activeSourceTracking = null;
+var _activeStateTracking = null;
+var _activeSourceTracking = null;
 function isAutoTrackable(value) {
-  return value !== null && typeof value === "object" && typeof value.subscribe === "function";
-}
-const DEFAULT_TASK_STATE = Object.freeze({ loading: false, error: null, errorCode: null });
-const RESERVED_ASYNC_KEYS = ["async", "subscribeAsync"];
-const LIFECYCLE_HOOKS = /* @__PURE__ */ new Set(["onInit", "onSet", "onDispose"]);
-class ViewModel {
-  _state;
-  _initialState;
-  _disposed = false;
-  _initialized = false;
-  _listeners = /* @__PURE__ */ new Set();
-  _abortController = null;
-  _cleanups = null;
-  _subscriptionCleanups = null;
-  _eventBus = null;
-  // ── Reactive derived state (RFC 1) ─────────────────────────────
-  _revision = 0;
-  _trackedSources = /* @__PURE__ */ new Map();
-  // ── Async tracking (RFC 2) ──────────────────────────────────────
-  // Lazily allocated on first async method wrap to keep construction fast.
-  _asyncStates = null;
-  _asyncSnapshots = null;
-  _asyncListeners = null;
-  _asyncProxy = null;
-  _activeOps = null;
-  /** DEV-only timeout (ms) for detecting ghost async operations after dispose. */
-  static GHOST_TIMEOUT = 3e3;
-  constructor(...args) {
-    const initialState = args[0] ?? {};
-    this._state = freeze({ ...initialState });
-    this._initialState = this._state;
-    this._guardAndBind();
-  }
-  /** 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() {
-    if (!this._abortController) {
-      this._abortController = new AbortController();
-    }
-    return this._abortController.signal;
-  }
-  /** Lazily-created typed EventBus for emitting and subscribing to events. */
-  get events() {
-    if (!this._eventBus) {
-      this._eventBus = new EventBus();
-    }
-    return this._eventBus;
-  }
-  /** Initializes the instance. Called automatically by React hooks after mount. */
-  init() {
-    if (this._initialized || this._disposed) return;
-    this._initialized = true;
-    this._trackSubscribables();
-    this._installStateProxy();
-    this._processMembers();
-    return this.onInit?.();
-  }
-  /**
-   * Merges partial state into current state. If no values actually
-   * changed by reference, this is a no-op.
-   *
-   * Triggers React re-render via listener notification. Called when:
-   *   - User code calls set() to update source state
-   *
-   * NOT called for subscribable member notifications — those use
-   * a separate notification path (see _trackSubscribables).
-   */
-  set(partialOrUpdater) {
-    if (this._disposed) return;
-    if (__DEV__ && _activeStateTracking) {
-      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."
-      );
-      return;
-    }
-    let partial;
-    if (typeof partialOrUpdater === "function") {
-      const result = resolveDraftUpdater(this._state, partialOrUpdater);
-      if (!result) return;
-      partial = result;
-    } else {
-      partial = partialOrUpdater;
-    }
-    let hasChanges = false;
-    const current = this._state;
-    for (const key in partial) {
-      if (partial[key] !== current[key]) {
-        hasChanges = true;
-        break;
-      }
-    }
-    if (!hasChanges) {
-      return;
-    }
-    const prev = this._state;
-    const next = freeze({ ...prev, ...partial });
-    this._state = next;
-    this._revision++;
-    this.onSet?.(prev, next);
-    for (const listener of this._listeners) {
-      listener(next, prev);
-    }
-  }
-  /**
-   * Emits a typed event via the internal EventBus.
-   * Safe to call during dispose cleanup callbacks.
-   * @protected
-   */
-  emit(event, payload) {
-    if (this._eventBus?.disposed ?? this._disposed) return;
-    this.events.emit(event, payload);
-  }
-  /** Subscribes to state changes. Returns an unsubscribe function. */
-  subscribe(listener) {
-    if (this._disposed) {
-      return () => {
-      };
-    }
-    this._listeners.add(listener);
-    return () => {
-      this._listeners.delete(listener);
-    };
-  }
-  /** Tears down the instance, releasing all subscriptions and resources. */
-  dispose() {
-    if (this._disposed) {
-      return;
-    }
-    this._disposed = true;
-    this._teardownSubscriptions();
-    this._abortController?.abort();
-    if (this._cleanups) {
-      for (const fn of this._cleanups) fn();
-      this._cleanups = null;
-    }
-    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(newState) {
-    if (this._disposed) return;
-    this._abortController?.abort();
-    this._abortController = null;
-    this._teardownSubscriptions();
-    this._state = newState ? freeze({ ...newState }) : this._initialState;
-    this._revision++;
-    this._asyncStates?.clear();
-    this._asyncSnapshots?.clear();
-    this._notifyAsync();
-    this._trackSubscribables();
-    for (const listener of this._listeners) {
-      listener(this._state, this._state);
-    }
-    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(fn) {
-    if (!this._cleanups) {
-      this._cleanups = [];
-    }
-    this._cleanups.push(fn);
-  }
-  /** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
-  subscribeTo(source, listener) {
-    const unsubscribe = source.subscribe(listener);
-    if (!this._subscriptionCleanups) this._subscriptionCleanups = [];
-    this._subscriptionCleanups.push(unsubscribe);
-    return unsubscribe;
-  }
-  /** Subscribes to a typed event on a Channel or EventBus with automatic cleanup on dispose and reset. @protected */
-  listenTo(source, event, handler) {
-    const unsubscribe = source.on(event, handler);
-    if (!this._subscriptionCleanups) this._subscriptionCleanups = [];
-    this._subscriptionCleanups.push(unsubscribe);
-    return unsubscribe;
-  }
-  /** Pipes a Channel event into a Collection via upsert. Calls channel.init() and registers auto-cleanup on dispose and reset. @protected */
-  pipeChannel(channel, type, target) {
-    channel.init();
-    return this.listenTo(channel, type, (payload) => {
-      target.upsert(payload);
-    });
-  }
-  // ── Async tracking API ──────────────────────────────────────────
-  /** Proxy providing `TaskState` (loading, error, errorCode) per async method. */
-  get async() {
-    if (!this._asyncProxy) {
-      const self = this;
-      this._asyncProxy = new Proxy({}, {
-        get(_, prop) {
-          return self._asyncSnapshots?.get(prop) ?? DEFAULT_TASK_STATE;
-        },
-        has(_, prop) {
-          return self._asyncSnapshots?.has(prop) ?? false;
-        },
-        ownKeys() {
-          return self._asyncSnapshots ? Array.from(self._asyncSnapshots.keys()) : [];
-        },
-        getOwnPropertyDescriptor(_, prop) {
-          if (self._asyncSnapshots?.has(prop)) {
-            return { configurable: true, enumerable: true, value: self._asyncSnapshots.get(prop) };
-          }
-          return void 0;
-        }
-      });
-    }
-    return this._asyncProxy;
-  }
-  /** Subscribes to async state changes. Used for React integration. */
-  subscribeAsync(listener) {
-    if (this._disposed) return () => {
-    };
-    if (!this._asyncListeners) this._asyncListeners = /* @__PURE__ */ new Set();
-    this._asyncListeners.add(listener);
-    return () => {
-      this._asyncListeners.delete(listener);
-    };
-  }
-  _notifyAsync() {
-    if (!this._asyncListeners) return;
-    for (const listener of this._asyncListeners) {
-      listener();
-    }
-  }
-  // ── Async tracking internals ────────────────────────────────────
-  _teardownSubscriptions() {
-    for (const tracked of this._trackedSources.values()) tracked.unsubscribe();
-    this._trackedSources.clear();
-    if (this._subscriptionCleanups) {
-      for (const fn of this._subscriptionCleanups) fn();
-      this._subscriptionCleanups = null;
-    }
-  }
-  /**
-   * Guards reserved keys and auto-binds subclass methods in a single pass
-   * using the cached class metadata from getClassMemberInfo.
-   */
-  _guardAndBind() {
-    const info = getClassMemberInfo(this, ViewModel.prototype, RESERVED_ASYNC_KEYS, LIFECYCLE_HOOKS);
-    if (info.reservedKeys.length > 0) {
-      throw new Error(
-        `[mvc-kit] "${info.reservedKeys[0]}" is a reserved property on ViewModel and cannot be overridden.`
-      );
-    }
-    for (let i = 0; i < info.methods.length; i++) {
-      this[info.methods[i].key] = info.methods[i].fn.bind(this);
-    }
-  }
-  // ── Member processing (merged getter memoization + async method wrapping) ──
-  /**
-   * Uses cached class metadata to memoize getters (RFC 1) and delegates
-   * async method wrapping to the shared wrapAsyncMethods helper (RFC 2).
-   * Class metadata is computed once per class via getClassMemberInfo() and reused
-   * across all instances — avoids repeated prototype walks.
-   */
-  _processMembers() {
-    const info = getClassMemberInfo(this, ViewModel.prototype, RESERVED_ASYNC_KEYS, LIFECYCLE_HOOKS);
-    for (let i = 0; i < info.getters.length; i++) {
-      this._wrapGetter(info.getters[i].key, info.getters[i].get);
-    }
-    if (__DEV__) {
-      for (const key of RESERVED_ASYNC_KEYS) {
-        if (Object.getOwnPropertyDescriptor(this, key)?.value !== void 0) {
-          throw new Error(
-            `[mvc-kit] "${key}" is a reserved property on ViewModel and cannot be overridden.`
-          );
-        }
-      }
-    }
-    if (info.methods.length === 0) return;
-    if (!this._asyncStates) this._asyncStates = /* @__PURE__ */ new Map();
-    if (!this._asyncSnapshots) this._asyncSnapshots = /* @__PURE__ */ new Map();
-    if (!this._asyncListeners) this._asyncListeners = /* @__PURE__ */ new Set();
-    if (__DEV__) {
-      this._activeOps = /* @__PURE__ */ new Map();
-    }
-    wrapAsyncMethods({
-      instance: this,
-      stopPrototype: ViewModel.prototype,
-      reservedKeys: RESERVED_ASYNC_KEYS,
-      lifecycleHooks: LIFECYCLE_HOOKS,
-      isDisposed: () => this._disposed,
-      isInitialized: () => this._initialized,
-      asyncStates: this._asyncStates,
-      asyncSnapshots: this._asyncSnapshots,
-      asyncListeners: this._asyncListeners,
-      notifyAsync: () => this._notifyAsync(),
-      addCleanup: (fn) => this.addCleanup(fn),
-      ghostTimeout: this.constructor.GHOST_TIMEOUT,
-      className: "ViewModel",
-      activeOps: this._activeOps,
-      methods: info.methods
-    });
-  }
-  // ── Auto-tracking internals ────────────────────────────────────
-  /**
-   * Installs a context-sensitive state getter on the instance.
-   *
-   * During getter tracking (_activeStateTracking is active): returns a Proxy
-   * that records which state properties are accessed. The Proxy is created
-   * lazily on first tracking access to keep init() fast.
-   *
-   * Otherwise: returns the frozen state object directly. This is critical
-   * for React's useSyncExternalStore — it needs a changing reference to
-   * detect state updates and trigger re-renders.
-   */
-  _installStateProxy() {
-    let stateProxy = null;
-    Object.defineProperty(this, "state", {
-      get: () => {
-        if (_activeStateTracking) {
-          if (!stateProxy) {
-            stateProxy = new Proxy({}, {
-              get: (_, prop) => {
-                _activeStateTracking?.add(prop);
-                return this._state[prop];
-              },
-              ownKeys: () => Reflect.ownKeys(this._state),
-              getOwnPropertyDescriptor: (_, prop) => Reflect.getOwnPropertyDescriptor(this._state, prop),
-              set: () => {
-                throw new Error("Cannot mutate state directly. Use set() instead.");
-              },
-              has: (_, prop) => prop in this._state
-            });
-          }
-          return stateProxy;
-        }
-        return this._state;
-      },
-      configurable: true,
-      enumerable: true
-    });
-  }
-  /**
-   * Scans own instance properties for Subscribable objects and sets up
-   * automatic dependency tracking for each one found.
-   *
-   * For each subscribable member:
-   *   1. Subscribe to it. On notification: bump its tracked revision
-   *      AND the VM's global revision, then force a new state reference
-   *      and notify listeners so React re-renders.
-   *   2. Replace the instance property with a getter that participates
-   *      in dependency tracking.
-   *   3. Register unsubscribe in the dispose chain.
-   *
-   * Called during init(), AFTER all subclass property initializers
-   * have run (they execute during the constructor, before init()).
-   */
-  _trackSubscribables() {
-    for (const key of Object.getOwnPropertyNames(this)) {
-      const value = this[key];
-      if (!isAutoTrackable(value)) continue;
-      let tracked;
-      const onSourceNotify = () => {
-        if (this._disposed) return;
-        tracked.revision++;
-        this._revision++;
-        for (const listener of this._listeners) {
-          listener(this._state, this._state);
-        }
-      };
-      const unsubState = value.subscribe(onSourceNotify);
-      const unsubAsync = typeof value.subscribeAsync === "function" ? value.subscribeAsync(onSourceNotify) : void 0;
-      tracked = {
-        source: value,
-        revision: 0,
-        unsubscribe: unsubAsync ? () => {
-          unsubState();
-          unsubAsync();
-        } : unsubState
-      };
-      this._trackedSources.set(key, tracked);
-      Object.defineProperty(this, key, {
-        get: () => {
-          _activeSourceTracking?.set(key, tracked);
-          return value;
-        },
-        configurable: true,
-        enumerable: false
-      });
-    }
-  }
-  /**
-   * Bubbles cached dependency records to the active parent tracking context.
-   * Called from Tier 1/Tier 2 cache hits during nested getter composition
-   * so the parent getter records the full transitive dependency set.
-   * Extracted to keep the getter closure small for V8 inlining.
-   */
-  _bubbleDeps(stateDepKeys, sourceDepKeys) {
-    const st = _activeStateTracking;
-    if (stateDepKeys) {
-      for (let i = 0; i < stateDepKeys.length; i++) st.add(stateDepKeys[i]);
-    }
-    if (sourceDepKeys) {
-      const srt = _activeSourceTracking;
-      for (let i = 0; i < sourceDepKeys.length; i++) {
-        const ts = this._trackedSources.get(sourceDepKeys[i]);
-        if (ts) srt.set(sourceDepKeys[i], ts);
-      }
-    }
-  }
-  /**
-   * Replaces a single prototype getter with a memoized version on this
-   * instance. The memoized getter tracks both state dependencies and
-   * subscribable member dependencies, caching its result and
-   * revalidating through a three-tier strategy:
-   *
-   *   Tier 1 (fast):   revision unchanged → return cached (1 int compare)
-   *   Tier 2 (medium): revision changed but this getter's deps didn't → return cached
-   *   Tier 3 (slow):   at least one dep changed → full recompute with tracking
-   */
-  _wrapGetter(key, original) {
-    let cached;
-    let validatedAtRevision = -1;
-    let stateDepKeys;
-    let stateDepValues;
-    let sourceDepKeys;
-    let sourceDepRevisions;
-    let trackingSet;
-    let trackingMap;
-    Object.defineProperty(this, key, {
-      get: () => {
-        if (validatedAtRevision === this._revision) {
-          if (_activeStateTracking) this._bubbleDeps(stateDepKeys, sourceDepKeys);
-          return cached;
-        }
-        if (this._disposed) return cached;
-        if (stateDepKeys !== void 0) {
-          let fresh = true;
-          const state = this._state;
-          for (let i = 0; i < stateDepKeys.length; i++) {
-            if (state[stateDepKeys[i]] !== stateDepValues[i]) {
-              fresh = false;
-              break;
-            }
-          }
-          if (fresh && sourceDepKeys !== void 0 && sourceDepKeys.length > 0) {
-            for (let i = 0; i < sourceDepKeys.length; i++) {
-              const ts = this._trackedSources.get(sourceDepKeys[i]);
-              if (ts && ts.revision !== sourceDepRevisions[i]) {
-                fresh = false;
-                break;
-              }
-            }
-          }
-          if (fresh) {
-            if (_activeStateTracking) this._bubbleDeps(stateDepKeys, sourceDepKeys);
-            validatedAtRevision = this._revision;
-            return cached;
-          }
-        }
-        const parentStateTracking = _activeStateTracking;
-        const parentSourceTracking = _activeSourceTracking;
-        if (trackingSet) {
-          trackingSet.clear();
-        } else {
-          trackingSet = /* @__PURE__ */ new Set();
-        }
-        if (trackingMap) {
-          trackingMap.clear();
-        } else {
-          trackingMap = /* @__PURE__ */ new Map();
-        }
-        _activeStateTracking = trackingSet;
-        _activeSourceTracking = trackingMap;
-        try {
-          cached = original.call(this);
-        } catch (e) {
-          _activeStateTracking = parentStateTracking;
-          _activeSourceTracking = parentSourceTracking;
-          throw e;
-        }
-        _activeStateTracking = parentStateTracking;
-        _activeSourceTracking = parentSourceTracking;
-        if (parentStateTracking) {
-          for (const d of trackingSet) parentStateTracking.add(d);
-        }
-        if (parentSourceTracking) {
-          for (const [k, v] of trackingMap) {
-            parentSourceTracking.set(k, v);
-          }
-        }
-        const depCount = trackingSet.size;
-        if (!stateDepKeys || stateDepKeys.length !== depCount) {
-          stateDepKeys = new Array(depCount);
-          stateDepValues = new Array(depCount);
-        }
-        {
-          let i = 0;
-          const state = this._state;
-          for (const d of trackingSet) {
-            stateDepKeys[i] = d;
-            stateDepValues[i] = state[d];
-            i++;
-          }
-        }
-        const sourceCount = trackingMap.size;
-        if (sourceCount > 0) {
-          if (!sourceDepKeys || sourceDepKeys.length !== sourceCount) {
-            sourceDepKeys = new Array(sourceCount);
-            sourceDepRevisions = new Array(sourceCount);
-          }
-          let i = 0;
-          for (const [memberKey, tracked] of trackingMap) {
-            sourceDepKeys[i] = memberKey;
-            sourceDepRevisions[i] = tracked.revision;
-            i++;
-          }
-        } else {
-          sourceDepKeys = void 0;
-          sourceDepRevisions = void 0;
-        }
-        validatedAtRevision = this._revision;
-        return cached;
-      },
-      configurable: true,
-      enumerable: true
-    });
-  }
+	return value !== null && typeof value === "object" && typeof value.subscribe === "function";
 }
-export {
-  ViewModel,
-  walkPrototypeChain
+var DEFAULT_TASK_STATE = Object.freeze({
+	loading: false,
+	error: null,
+	errorCode: null
+});
+var RESERVED_ASYNC_KEYS = ["async", "subscribeAsync"];
+var LIFECYCLE_HOOKS = new Set([
+	"onInit",
+	"onSet",
+	"onDispose"
+]);
+/**
+* Reactive state container with computed getters, automatic async tracking, and typed events.
+* Subclass and define state shape, getters, and action methods. Use with `useLocal` in React.
+*/
+var ViewModel = class ViewModel {
+	_state;
+	_initialState;
+	_disposed = false;
+	_initialized = false;
+	_listeners = /* @__PURE__ */ new Set();
+	_abortController = null;
+	_cleanups = null;
+	_subscriptionCleanups = null;
+	_eventBus = null;
+	_revision = 0;
+	_trackedSources = /* @__PURE__ */ new Map();
+	_asyncStates = null;
+	_asyncSnapshots = null;
+	_asyncListeners = null;
+	_asyncProxy = null;
+	_activeOps = null;
+	/** DEV-only timeout (ms) for detecting ghost async operations after dispose. */
+	static GHOST_TIMEOUT = 3e3;
+	constructor(...args) {
+		this._state = freeze({ ...args[0] ?? {} });
+		this._initialState = this._state;
+		this._guardAndBind();
+	}
+	/** 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() {
+		if (!this._abortController) this._abortController = new AbortController();
+		return this._abortController.signal;
+	}
+	/** Lazily-created typed EventBus for emitting and subscribing to events. */
+	get events() {
+		if (!this._eventBus) this._eventBus = new EventBus();
+		return this._eventBus;
+	}
+	/** Initializes the instance. Called automatically by React hooks after mount. */
+	init() {
+		if (this._initialized || this._disposed) return;
+		this._initialized = true;
+		this._trackSubscribables();
+		this._installStateProxy();
+		this._processMembers();
+		return this.onInit?.();
+	}
+	/**
+	* Merges partial state into current state. If no values actually
+	* changed by reference, this is a no-op.
+	*
+	* Triggers React re-render via listener notification. Called when:
+	*   - User code calls set() to update source state
+	*
+	* NOT called for subscribable member notifications — those use
+	* a separate notification path (see _trackSubscribables).
+	*/
+	set(partialOrUpdater) {
+		if (this._disposed) return;
+		if (__DEV__ && _activeStateTracking) {
+			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.");
+			return;
+		}
+		let partial;
+		if (typeof partialOrUpdater === "function") {
+			const result = resolveDraftUpdater(this._state, partialOrUpdater);
+			if (!result) return;
+			partial = result;
+		} else partial = partialOrUpdater;
+		let hasChanges = false;
+		const current = this._state;
+		for (const key in partial) if (partial[key] !== current[key]) {
+			hasChanges = true;
+			break;
+		}
+		if (!hasChanges) return;
+		const prev = this._state;
+		const next = freeze({
+			...prev,
+			...partial
+		});
+		this._state = next;
+		this._revision++;
+		this.onSet?.(prev, next);
+		for (const listener of this._listeners) listener(next, prev);
+	}
+	/**
+	* Emits a typed event via the internal EventBus.
+	* Safe to call during dispose cleanup callbacks.
+	* @protected
+	*/
+	emit(event, payload) {
+		if (this._eventBus?.disposed ?? this._disposed) return;
+		this.events.emit(event, payload);
+	}
+	/** Subscribes to state changes. Returns an unsubscribe function. */
+	subscribe(listener) {
+		if (this._disposed) return () => {};
+		this._listeners.add(listener);
+		return () => {
+			this._listeners.delete(listener);
+		};
+	}
+	/** Tears down the instance, releasing all subscriptions and resources. */
+	dispose() {
+		if (this._disposed) return;
+		this._disposed = true;
+		this._teardownSubscriptions();
+		this._abortController?.abort();
+		if (this._cleanups) {
+			for (const fn of this._cleanups) fn();
+			this._cleanups = null;
+		}
+		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(newState) {
+		if (this._disposed) return;
+		this._abortController?.abort();
+		this._abortController = null;
+		this._teardownSubscriptions();
+		this._state = newState ? freeze({ ...newState }) : this._initialState;
+		this._revision++;
+		this._asyncStates?.clear();
+		this._asyncSnapshots?.clear();
+		this._notifyAsync();
+		this._trackSubscribables();
+		for (const listener of this._listeners) listener(this._state, this._state);
+		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(fn) {
+		if (!this._cleanups) this._cleanups = [];
+		this._cleanups.push(fn);
+	}
+	/** Subscribes to an external Subscribable with automatic cleanup on dispose. @protected */
+	subscribeTo(source, listener) {
+		const unsubscribe = source.subscribe(listener);
+		if (!this._subscriptionCleanups) this._subscriptionCleanups = [];
+		this._subscriptionCleanups.push(unsubscribe);
+		return unsubscribe;
+	}
+	/** Subscribes to a typed event on a Channel or EventBus with automatic cleanup on dispose and reset. @protected */
+	listenTo(source, event, handler) {
+		const unsubscribe = source.on(event, handler);
+		if (!this._subscriptionCleanups) this._subscriptionCleanups = [];
+		this._subscriptionCleanups.push(unsubscribe);
+		return unsubscribe;
+	}
+	/** Pipes a Channel event into a Collection via upsert. Calls channel.init() and registers auto-cleanup on dispose and reset. @protected */
+	pipeChannel(channel, type, target) {
+		channel.init();
+		return this.listenTo(channel, type, (payload) => {
+			target.upsert(payload);
+		});
+	}
+	/** Proxy providing `TaskState` (loading, error, errorCode) per async method. */
+	get async() {
+		if (!this._asyncProxy) {
+			const self = this;
+			this._asyncProxy = new Proxy({}, {
+				get(_, prop) {
+					return self._asyncSnapshots?.get(prop) ?? DEFAULT_TASK_STATE;
+				},
+				has(_, prop) {
+					return self._asyncSnapshots?.has(prop) ?? false;
+				},
+				ownKeys() {
+					return self._asyncSnapshots ? Array.from(self._asyncSnapshots.keys()) : [];
+				},
+				getOwnPropertyDescriptor(_, prop) {
+					if (self._asyncSnapshots?.has(prop)) return {
+						configurable: true,
+						enumerable: true,
+						value: self._asyncSnapshots.get(prop)
+					};
+				}
+			});
+		}
+		return this._asyncProxy;
+	}
+	/** Subscribes to async state changes. Used for React integration. */
+	subscribeAsync(listener) {
+		if (this._disposed) return () => {};
+		if (!this._asyncListeners) this._asyncListeners = /* @__PURE__ */ new Set();
+		this._asyncListeners.add(listener);
+		return () => {
+			this._asyncListeners.delete(listener);
+		};
+	}
+	_notifyAsync() {
+		if (!this._asyncListeners) return;
+		for (const listener of this._asyncListeners) listener();
+	}
+	_teardownSubscriptions() {
+		for (const tracked of this._trackedSources.values()) tracked.unsubscribe();
+		this._trackedSources.clear();
+		if (this._subscriptionCleanups) {
+			for (const fn of this._subscriptionCleanups) fn();
+			this._subscriptionCleanups = null;
+		}
+	}
+	/**
+	* Guards reserved keys and auto-binds subclass methods in a single pass
+	* using the cached class metadata from getClassMemberInfo.
+	*/
+	_guardAndBind() {
+		const info = getClassMemberInfo(this, ViewModel.prototype, RESERVED_ASYNC_KEYS, LIFECYCLE_HOOKS);
+		if (info.reservedKeys.length > 0) throw new Error(`[mvc-kit] "${info.reservedKeys[0]}" is a reserved property on ViewModel and cannot be overridden.`);
+		for (let i = 0; i < info.methods.length; i++) this[info.methods[i].key] = info.methods[i].fn.bind(this);
+	}
+	/**
+	* Uses cached class metadata to memoize getters (RFC 1) and delegates
+	* async method wrapping to the shared wrapAsyncMethods helper (RFC 2).
+	* Class metadata is computed once per class via getClassMemberInfo() and reused
+	* across all instances — avoids repeated prototype walks.
+	*/
+	_processMembers() {
+		const info = getClassMemberInfo(this, ViewModel.prototype, RESERVED_ASYNC_KEYS, LIFECYCLE_HOOKS);
+		for (let i = 0; i < info.getters.length; i++) this._wrapGetter(info.getters[i].key, info.getters[i].get);
+		if (__DEV__) {
+			for (const key of RESERVED_ASYNC_KEYS) if (Object.getOwnPropertyDescriptor(this, key)?.value !== void 0) throw new Error(`[mvc-kit] "${key}" is a reserved property on ViewModel and cannot be overridden.`);
+		}
+		if (info.methods.length === 0) return;
+		if (!this._asyncStates) this._asyncStates = /* @__PURE__ */ new Map();
+		if (!this._asyncSnapshots) this._asyncSnapshots = /* @__PURE__ */ new Map();
+		if (!this._asyncListeners) this._asyncListeners = /* @__PURE__ */ new Set();
+		if (__DEV__) this._activeOps = /* @__PURE__ */ new Map();
+		wrapAsyncMethods({
+			instance: this,
+			stopPrototype: ViewModel.prototype,
+			reservedKeys: RESERVED_ASYNC_KEYS,
+			lifecycleHooks: LIFECYCLE_HOOKS,
+			isDisposed: () => this._disposed,
+			isInitialized: () => this._initialized,
+			asyncStates: this._asyncStates,
+			asyncSnapshots: this._asyncSnapshots,
+			asyncListeners: this._asyncListeners,
+			notifyAsync: () => this._notifyAsync(),
+			addCleanup: (fn) => this.addCleanup(fn),
+			ghostTimeout: this.constructor.GHOST_TIMEOUT,
+			className: "ViewModel",
+			activeOps: this._activeOps,
+			methods: info.methods
+		});
+	}
+	/**
+	* Installs a context-sensitive state getter on the instance.
+	*
+	* During getter tracking (_activeStateTracking is active): returns a Proxy
+	* that records which state properties are accessed. The Proxy is created
+	* lazily on first tracking access to keep init() fast.
+	*
+	* Otherwise: returns the frozen state object directly. This is critical
+	* for React's useSyncExternalStore — it needs a changing reference to
+	* detect state updates and trigger re-renders.
+	*/
+	_installStateProxy() {
+		let stateProxy = null;
+		Object.defineProperty(this, "state", {
+			get: () => {
+				if (_activeStateTracking) {
+					if (!stateProxy) stateProxy = new Proxy({}, {
+						get: (_, prop) => {
+							_activeStateTracking?.add(prop);
+							return this._state[prop];
+						},
+						ownKeys: () => Reflect.ownKeys(this._state),
+						getOwnPropertyDescriptor: (_, prop) => Reflect.getOwnPropertyDescriptor(this._state, prop),
+						set: () => {
+							throw new Error("Cannot mutate state directly. Use set() instead.");
+						},
+						has: (_, prop) => prop in this._state
+					});
+					return stateProxy;
+				}
+				return this._state;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
+	/**
+	* Scans own instance properties for Subscribable objects and sets up
+	* automatic dependency tracking for each one found.
+	*
+	* For each subscribable member:
+	*   1. Subscribe to it. On notification: bump its tracked revision
+	*      AND the VM's global revision, then force a new state reference
+	*      and notify listeners so React re-renders.
+	*   2. Replace the instance property with a getter that participates
+	*      in dependency tracking.
+	*   3. Register unsubscribe in the dispose chain.
+	*
+	* Called during init(), AFTER all subclass property initializers
+	* have run (they execute during the constructor, before init()).
+	*/
+	_trackSubscribables() {
+		for (const key of Object.getOwnPropertyNames(this)) {
+			const value = this[key];
+			if (!isAutoTrackable(value)) continue;
+			let tracked;
+			const onSourceNotify = () => {
+				if (this._disposed) return;
+				tracked.revision++;
+				this._revision++;
+				for (const listener of this._listeners) listener(this._state, this._state);
+			};
+			const unsubState = value.subscribe(onSourceNotify);
+			const unsubAsync = typeof value.subscribeAsync === "function" ? value.subscribeAsync(onSourceNotify) : void 0;
+			tracked = {
+				source: value,
+				revision: 0,
+				unsubscribe: unsubAsync ? () => {
+					unsubState();
+					unsubAsync();
+				} : unsubState
+			};
+			this._trackedSources.set(key, tracked);
+			Object.defineProperty(this, key, {
+				get: () => {
+					_activeSourceTracking?.set(key, tracked);
+					return value;
+				},
+				configurable: true,
+				enumerable: false
+			});
+		}
+	}
+	/**
+	* Bubbles cached dependency records to the active parent tracking context.
+	* Called from Tier 1/Tier 2 cache hits during nested getter composition
+	* so the parent getter records the full transitive dependency set.
+	* Extracted to keep the getter closure small for V8 inlining.
+	*/
+	_bubbleDeps(stateDepKeys, sourceDepKeys) {
+		const st = _activeStateTracking;
+		if (stateDepKeys) for (let i = 0; i < stateDepKeys.length; i++) st.add(stateDepKeys[i]);
+		if (sourceDepKeys) {
+			const srt = _activeSourceTracking;
+			for (let i = 0; i < sourceDepKeys.length; i++) {
+				const ts = this._trackedSources.get(sourceDepKeys[i]);
+				if (ts) srt.set(sourceDepKeys[i], ts);
+			}
+		}
+	}
+	/**
+	* Replaces a single prototype getter with a memoized version on this
+	* instance. The memoized getter tracks both state dependencies and
+	* subscribable member dependencies, caching its result and
+	* revalidating through a three-tier strategy:
+	*
+	*   Tier 1 (fast):   revision unchanged → return cached (1 int compare)
+	*   Tier 2 (medium): revision changed but this getter's deps didn't → return cached
+	*   Tier 3 (slow):   at least one dep changed → full recompute with tracking
+	*/
+	_wrapGetter(key, original) {
+		let cached;
+		let validatedAtRevision = -1;
+		let stateDepKeys;
+		let stateDepValues;
+		let sourceDepKeys;
+		let sourceDepRevisions;
+		let trackingSet;
+		let trackingMap;
+		Object.defineProperty(this, key, {
+			get: () => {
+				if (validatedAtRevision === this._revision) {
+					if (_activeStateTracking) this._bubbleDeps(stateDepKeys, sourceDepKeys);
+					return cached;
+				}
+				if (this._disposed) return cached;
+				if (stateDepKeys !== void 0) {
+					let fresh = true;
+					const state = this._state;
+					for (let i = 0; i < stateDepKeys.length; i++) if (state[stateDepKeys[i]] !== stateDepValues[i]) {
+						fresh = false;
+						break;
+					}
+					if (fresh && sourceDepKeys !== void 0 && sourceDepKeys.length > 0) for (let i = 0; i < sourceDepKeys.length; i++) {
+						const ts = this._trackedSources.get(sourceDepKeys[i]);
+						if (ts && ts.revision !== sourceDepRevisions[i]) {
+							fresh = false;
+							break;
+						}
+					}
+					if (fresh) {
+						if (_activeStateTracking) this._bubbleDeps(stateDepKeys, sourceDepKeys);
+						validatedAtRevision = this._revision;
+						return cached;
+					}
+				}
+				const parentStateTracking = _activeStateTracking;
+				const parentSourceTracking = _activeSourceTracking;
+				if (trackingSet) trackingSet.clear();
+				else trackingSet = /* @__PURE__ */ new Set();
+				if (trackingMap) trackingMap.clear();
+				else trackingMap = /* @__PURE__ */ new Map();
+				_activeStateTracking = trackingSet;
+				_activeSourceTracking = trackingMap;
+				try {
+					cached = original.call(this);
+				} catch (e) {
+					_activeStateTracking = parentStateTracking;
+					_activeSourceTracking = parentSourceTracking;
+					throw e;
+				}
+				_activeStateTracking = parentStateTracking;
+				_activeSourceTracking = parentSourceTracking;
+				if (parentStateTracking) for (const d of trackingSet) parentStateTracking.add(d);
+				if (parentSourceTracking) for (const [k, v] of trackingMap) parentSourceTracking.set(k, v);
+				const depCount = trackingSet.size;
+				if (!stateDepKeys || stateDepKeys.length !== depCount) {
+					stateDepKeys = new Array(depCount);
+					stateDepValues = new Array(depCount);
+				}
+				{
+					let i = 0;
+					const state = this._state;
+					for (const d of trackingSet) {
+						stateDepKeys[i] = d;
+						stateDepValues[i] = state[d];
+						i++;
+					}
+				}
+				const sourceCount = trackingMap.size;
+				if (sourceCount > 0) {
+					if (!sourceDepKeys || sourceDepKeys.length !== sourceCount) {
+						sourceDepKeys = new Array(sourceCount);
+						sourceDepRevisions = new Array(sourceCount);
+					}
+					let i = 0;
+					for (const [memberKey, tracked] of trackingMap) {
+						sourceDepKeys[i] = memberKey;
+						sourceDepRevisions[i] = tracked.revision;
+						i++;
+					}
+				} else {
+					sourceDepKeys = void 0;
+					sourceDepRevisions = void 0;
+				}
+				validatedAtRevision = this._revision;
+				return cached;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
 };
-//# sourceMappingURL=ViewModel.js.map
+//#endregion
+export { ViewModel };
+
+//# sourceMappingURL=ViewModel.js.map