@blac/core 2.1.0 → 2.1.2

package/dist/StateContainerRegistry-vWgsD-RP.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateContainerRegistry-vWgsD-RP.js","names":[],"sources":["../src/config.ts","../src/constants.ts","../src/utils/static-props.ts","../src/utils/structural-key.ts","../src/core/symbols.ts","../src/core/StateContainerRegistry.ts"],"sourcesContent":["/**\n * Global configuration for `@blac/core`\n */\n\nexport type EqualityFn = <S>(prev: S, next: S) => boolean;\n\nexport interface BlacConfig {\n  /**\n   * Equality check used by `StateContainer.applyState` to skip emits when\n   * `prev` and `next` are structurally equal. Default: `shallowEqualState`.\n   *\n   * Return `true` to skip the emit (states considered equal).\n   */\n  equality: EqualityFn;\n\n  /**\n   * Circuit breaker: maximum number of live instances allowed under a single\n   * bloc constructor before `acquire` throws. Guards against runaway instance\n   * creation — typically an unstable/args-derived key churning out instances\n   * that are never disposed (a memory leak that eventually freezes the app).\n   *\n   * Default: `1000`. Set to `Infinity` (or any non-positive value) to disable.\n   */\n  maxInstancesPerType: number;\n\n  /**\n   * Circuit breaker: maximum number of distinct live references (consumers)\n   * allowed on a single instance before `acquire` throws. Guards against the\n   * other leak shape — consumer cleanup (e.g. `useBloc` unmount `release`)\n   * never firing, so refs accumulate without bound on one instance.\n   *\n   * Default: `1000`. Set to `Infinity` (or any non-positive value) to disable.\n   */\n  maxRefsPerInstance: number;\n\n  /**\n   * Dev-only soft circuit breaker: if a single instance emits more than this\n   * many *real* state changes within a rolling one-second window, log a single\n   * `console.warn`. This is the \"frozen app\" smell — almost always a tight loop\n   * (RAF/animation, or an effect that emits on every commit) pushing\n   * high-frequency data through bloc state, which then saturates subscribers,\n   * plugins (logging/devtools), and the main thread.\n   *\n   * Heuristic by nature — warns, never throws, since high-frequency state can\n   * occasionally be legitimate. No-op in production. Default: `100`. Set to\n   * `Infinity` (or any non-positive value) to disable.\n   */\n  maxEmitsPerSecond: number;\n}\n\n/**\n * Default equality: shallow per-key `Object.is` comparison.\n * Falls through to `false` for primitives/null so reference-only state still\n * behaves correctly.\n */\nexport const shallowEqualState: EqualityFn = (prev, next) => {\n  if (Object.is(prev, next)) return true;\n  if (typeof prev !== 'object' || prev === null) return false;\n  if (typeof next !== 'object' || next === null) return false;\n\n  const prevKeys = Object.keys(prev as object);\n  if (prevKeys.length !== Object.keys(next as object).length) return false;\n\n  for (let i = 0; i < prevKeys.length; i++) {\n    const key = prevKeys[i];\n    if (\n      !Object.is(\n        (prev as Record<string, unknown>)[key],\n        (next as Record<string, unknown>)[key],\n      )\n    ) {\n      return false;\n    }\n  }\n  return true;\n};\n\nconst defaultConfig: BlacConfig = {\n  equality: shallowEqualState,\n  maxInstancesPerType: 100000,\n  maxRefsPerInstance: 100000,\n  maxEmitsPerSecond: 1000,\n};\n\nlet globalConfig: BlacConfig = { ...defaultConfig };\n\n/**\n * Configure global defaults for `@blac/core`.\n *\n * @example\n * ```ts\n * import { configureBlac, shallowEqualState } from '@blac/core';\n *\n * // Swap in a deep-equality check for all blocs\n * configureBlac({ equality: myDeepEqual });\n * ```\n */\nexport function configureBlac(config: Partial<BlacConfig>): void {\n  globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get the current global configuration.\n * @internal\n */\nexport function getBlacConfig(): BlacConfig {\n  return globalConfig;\n}\n\n/**\n * Reset configuration to defaults (useful for testing).\n * @internal\n */\nexport function resetBlacConfig(): void {\n  globalConfig = { ...defaultConfig };\n}\n","/**\n * Default configuration constants for BlaC\n *\n * Centralized location for all magic numbers and default values.\n */\n\n/**\n * Static property names for StateContainer classes\n * Used for feature flags and configuration on bloc classes\n */\nexport const BLAC_STATIC_PROPS = {\n  /**\n   * Mark a bloc to never be auto-disposed (kept alive permanently)\n   */\n  KEEP_ALIVE: 'keepAlive',\n\n  /**\n   * Exclude a bloc from DevTools reporting (prevents infinite loops)\n   */\n  EXCLUDE_FROM_DEVTOOLS: '__excludeFromDevTools',\n\n  /**\n   * Per-class equality function used to short-circuit `emit`/`patch` when the\n   * new state is structurally equal to the previous state. Falls back to the\n   * global `configureBlac({ equality })` value when unset.\n   */\n  EQUALITY: '__equality',\n\n  /**\n   * Per-class key function: `static key = (args) => string`.\n   * When set, the registry calls `Type.key(args)` to derive the instance key\n   * instead of using a structural hash of `args`. Allows blocs to ignore\n   * non-identity fields (e.g., `readonly` flags) while still keying by id.\n   */\n  KEY: 'key',\n\n  /**\n   * Explicit, minification-safe identity for a bloc class: `static blacName = '...'`.\n   * When unset, identity falls back to `constructor.name`.\n   */\n  BLAC_NAME: 'blacName',\n} as const;\n\n/**\n * Standard error message prefix\n */\nexport const BLAC_ERROR_PREFIX = '[BlaC]' as const;\n\n/**\n * True outside production builds.\n *\n * Reads `process.env.NODE_ENV` defensively: plain ESM in the browser, Deno and\n * some test runners have no `process` binding, where a bare read throws.\n * Bundlers that define `process.env.NODE_ENV` still constant-fold this.\n */\nexport const IS_DEV: boolean =\n  typeof process === 'undefined' || process.env?.NODE_ENV !== 'production';\n","/**\n * Utility functions for accessing static properties on StateContainer classes\n */\n\nimport { BLAC_STATIC_PROPS } from '../constants';\nimport type { EqualityFn } from '../config';\nimport { StateContainerConstructor } from '../types/utilities';\n\n/**\n * Get a static property from a class constructor, walking the prototype\n * chain so subclasses inherit the value unless they define their own.\n * Type-safe helper that avoids (Type as any) casts\n *\n * @param Type - The class constructor\n * @param propName - The property name to access\n * @param defaultValue - Optional default value if property is undefined\n * @returns The property value or default\n */\nexport function getStaticProp<\n  V,\n  T extends StateContainerConstructor = StateContainerConstructor,\n>(Type: T, propName: string, defaultValue?: V): V | undefined {\n  return (Type as any)[propName] ?? defaultValue;\n}\n\n/**\n * Get a static property declared directly on `Type`, ignoring the prototype\n * chain, so subclasses never inherit a base class's value.\n *\n * @param Type - The class constructor\n * @param propName - The property name to access\n * @returns The own property value or `undefined`\n */\nexport function getOwnStaticProp<\n  V,\n  T extends StateContainerConstructor = StateContainerConstructor,\n>(Type: T, propName: string): V | undefined {\n  return Object.hasOwn(Type, propName) ? (Type as any)[propName] : undefined;\n}\n\n/**\n * Check if a class is marked as keepAlive.\n * KeepAlive classes are never auto-disposed when ref count reaches 0.\n * Inherited: a subclass keeps a base class's `keepAlive` unless overridden.\n * @param Type - The class constructor to check\n * @returns true if the class has `static keepAlive = true`\n */\nexport function isKeepAliveClass<T extends StateContainerConstructor>(\n  Type: T,\n): boolean {\n  return getStaticProp<boolean>(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;\n}\n\n/**\n * Check if a class should be excluded from DevTools.\n * Used to prevent infinite loops when DevTools tracks itself.\n * Inherited: a subclass keeps a base class's exclusion unless overridden.\n * @param Type - The class constructor to check\n * @returns true if the class has `static __excludeFromDevTools = true`\n */\nexport function isExcludedFromDevTools<T extends StateContainerConstructor>(\n  Type: T,\n): boolean {\n  return (\n    getStaticProp<boolean>(Type, BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS) ===\n    true\n  );\n}\n\n/**\n * Get the per-class equality function set via `@blac({ equality })`, if any.\n * Inherited: a subclass keeps a base class's equality fn unless overridden.\n * @param Type - The class constructor to check\n * @returns the equality function or `undefined`\n */\nexport function getClassEquality<T extends StateContainerConstructor>(\n  Type: T,\n): EqualityFn | undefined {\n  const fn = getStaticProp<EqualityFn>(Type, BLAC_STATIC_PROPS.EQUALITY);\n  return typeof fn === 'function' ? fn : undefined;\n}\n\n/**\n * Get a class's minification-safe identity name.\n * Own only: a subclass never inherits a base class's explicit `blacName`,\n * since that would collapse two distinct blocs onto one identity.\n * Falls back to `Type.name` (the runtime `constructor.name`) when unset.\n * @param Type - The class constructor to check\n * @returns the explicit `static blacName` or `Type.name`\n */\nexport function getBlacName<T extends StateContainerConstructor>(\n  Type: T,\n): string {\n  return (\n    getOwnStaticProp<string>(Type, BLAC_STATIC_PROPS.BLAC_NAME) ?? Type.name\n  );\n}\n\n/**\n * Get the per-class key function set via `@blac({ key })` or `static key = …`, if any.\n * Used by the registry to derive a stable instance key from `args`.\n * Own only: a subclass never inherits a base class's `key`, since a\n * different `Args` shape would derive the wrong instance key.\n * @param Type - The class constructor to check\n * @returns the key function or `undefined`\n */\nexport function getClassKey(\n  Type: unknown,\n): ((args: any) => string) | undefined {\n  const fn = getOwnStaticProp<(args: any) => string>(\n    Type as StateContainerConstructor,\n    BLAC_STATIC_PROPS.KEY,\n  );\n  return typeof fn === 'function' ? fn : undefined;\n}\n","/**\n * Deterministic, order-independent hash of serializable args.\n * Sorts object keys so {a,b} === {b,a}.\n * Throws (dev) if it encounters a function or non-plain object — those belong in `deps`.\n */\n\nexport const DEFAULT_STRUCTURAL_KEY = 'default';\n\n/**\n * Produce a stable string key for serializable args.\n * - `undefined` / `void` args → `'default'` sentinel (no-args blocs stay on the default key).\n * - Object keys are sorted for order-independence.\n * - Arrays keep their insertion order.\n * - Functions throw — they must be passed via `deps`, not `args`.\n * - Object args are memoized by identity; callers on hot paths (`resolveKey`,\n *   `depend`) re-resolve the same args object on every call.\n */\nconst keyCache = new WeakMap<object, string>();\n\nexport function structuralKey(args: unknown): string {\n  if (args === undefined || args === null) {\n    return DEFAULT_STRUCTURAL_KEY;\n  }\n\n  if (typeof args === 'object') {\n    const cached = keyCache.get(args);\n    if (cached !== undefined) return cached;\n    const key = serialize(args);\n    keyCache.set(args, key);\n    return key;\n  }\n\n  return serialize(args);\n}\n\nfunction serialize(args: unknown): string {\n  return JSON.stringify(args, function (_k, v) {\n    if (typeof v === 'function') {\n      throw new Error(\n        `[blac] args must be serializable; put refs/callbacks in \\`deps\\` ` +\n          `(found a function at key \"${_k || '(root)'}\")`,\n      );\n    }\n    if (v && typeof v === 'object' && !Array.isArray(v)) {\n      return Object.keys(v)\n        .sort()\n        .reduce(\n          (o, k) => {\n            (o as any)[k] = (v as any)[k];\n            return o;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return v;\n  });\n}\n","/**\n * @internal Apply one owner's (consumer's) deps slice to an instance.\n * Called by framework adapters (e.g. `@blac/react` useBloc) — not public API.\n */\nexport const APPLY_DEPS = Symbol('blac.applyDeps');\n\n/**\n * @internal Withdraw one owner's entire deps slice (consumer unmounted).\n * Called by framework adapters — not public API.\n */\nexport const REMOVE_DEPS_OWNER = Symbol('blac.removeDepsOwner');\n\n/**\n * @internal Subscribe to this specific instance's own disposal, bypassing\n * the global registry `'disposed'` event. Called by `watch()` — not public\n * API.\n */\nexport const ON_DISPOSE = Symbol('blac.onDispose');\n\n/**\n * @internal Symbol-keyed configuration entry point on `StateContainer`.\n * Writes the instance's identity fields (`_name`/`_debug`/`_instanceId`),\n * resolves per-class equality, emits the registry `created` event, and runs\n * `init()` once.\n *\n * Framework-only — the registry (`StateContainerRegistry.ensure`) and testing\n * helpers are the sole callers, mirroring the `APPLY_DEPS` precedent.\n */\nexport const INIT_CONFIG = Symbol('blac.initConfig');\n\n/**\n * @internal Run `fn` with `state` temporarily reporting a render's tracking\n * proxy, so getters record the paths they read. Called by `@blac/react`'s\n * `buildTrackedProxy` — not public API.\n *\n * Replaces the old `this`-Proxy receiver: getters now run with `this` bound to\n * the real instance, so ES `#private` works in user blocs.\n */\nexport const WITH_TRACKED_STATE = Symbol('blac.withTrackedState');\n\n/**\n * @internal Drive the activation lifecycle from the registry's 0↔1 ownership\n * transition. Owns the per-instance AbortController so `onActivate`'s signal\n * aborts on the matching deactivation and on dispose.\n *\n * Framework-only — `StateContainerRegistry` is the sole caller.\n */\nexport const SET_ACTIVE = Symbol('blac.setActive');\n","import type {\n  HydrationStatus,\n  StateContainer,\n  StateContainerConfig,\n} from './StateContainer';\nimport { BLAC_ERROR_PREFIX, IS_DEV } from '../constants';\nimport { getBlacConfig } from '../config';\nimport {\n  isKeepAliveClass,\n  getClassKey,\n  getBlacName,\n} from '../utils/static-props';\nimport { structuralKey, DEFAULT_STRUCTURAL_KEY } from '../utils/structural-key';\nimport {\n  InstanceReadonlyState,\n  StateContainerConstructor,\n} from '../types/utilities';\nimport { INIT_CONFIG, SET_ACTIVE } from './symbols';\n\n/**\n * Entry in the instance registry, tracking the instance and its named references\n * @typeParam T - Instance type\n * @internal\n */\nexport interface InstanceEntry<T = any> {\n  /** The state container instance */\n  instance: T;\n  /** The key this entry is stored under in its constructor's instances Map. */\n  key: string;\n  /** Map of active reference IDs to their acquire count (supports paired acquire/release) */\n  refs: Map<string, number>;\n  /** The args used when this entry was first created; used for dev-warn on arg mismatch. */\n  args?: unknown;\n  /** Memoized structuralKey(args) for the dev arg-mismatch warning. */\n  argsKey?: string;\n  /** `depend()`-owners currently holding this instance (see `acquire`'s `dependent` option). */\n  dependents?: Set<StateContainer<any, any, any>>;\n}\n\n/** Shared, read-only Map returned by `getInstancesMap` for unregistered types. */\nconst EMPTY_INSTANCES_MAP: ReadonlyMap<string, InstanceEntry> = new Map();\n\n/**\n * Lifecycle events emitted by the registry\n * @public\n */\nexport type LifecycleEvent =\n  | 'created'\n  | 'stateChanged'\n  | 'disposed'\n  | 'refAcquired'\n  | 'refReleased'\n  | 'depsChanged'\n  | 'hydrationChanged'\n  | 'activated'\n  | 'deactivated';\n\n/**\n * Listener function type for each lifecycle event\n * @typeParam E - The lifecycle event type\n * @public\n */\nexport type LifecycleListener<E extends LifecycleEvent> = E extends 'created'\n  ? (container: StateContainer<any, any, any>) => void\n  : E extends 'stateChanged'\n    ? (\n        container: StateContainer<any, any, any>,\n        previousState: Readonly<Record<string, unknown>>,\n        currentState: Readonly<Record<string, unknown>>,\n      ) => void\n    : E extends 'disposed'\n      ? (container: StateContainer<any, any, any>) => void\n      : E extends 'refAcquired'\n        ? (container: StateContainer<any, any, any>, refId: string) => void\n        : E extends 'refReleased'\n          ? (container: StateContainer<any, any, any>, refId: string) => void\n          : E extends 'depsChanged'\n            ? (\n                container: StateContainer<any, any, any>,\n                previousDeps: Readonly<Record<string, unknown>>,\n                currentDeps: Readonly<Record<string, unknown>>,\n              ) => void\n            : E extends 'hydrationChanged'\n              ? (\n                  container: StateContainer<any, any, any>,\n                  status: HydrationStatus,\n                  previousStatus: HydrationStatus,\n                ) => void\n              : E extends 'activated'\n                ? (\n                    container: StateContainer<any, any, any>,\n                    signal: AbortSignal,\n                  ) => void\n                : E extends 'deactivated'\n                  ? (container: StateContainer<any, any, any>) => void\n                  : never;\n\n/**\n * Central registry for managing StateContainer instances.\n * Handles instance lifecycle, named ref tracking, and lifecycle event emission.\n *\n * @example\n * ```ts\n * const registry = new StateContainerRegistry();\n * const instance = registry.acquire(MyBloc);  // ownership, must release\n * const other = registry.ensure(OtherBloc);   // no ownership, bloc-to-bloc\n * registry.on('stateChanged', (container, prev, next) => {\n *   console.log('State changed:', prev, '->', next);\n * });\n * ```\n *\n * `stateChanged` fires once per emit (microtask-deferred but uncoalesced), so\n * listeners see every intermediate transition. Plugins' `onStateChange` fires\n * once per channel flush with coalesced `prev`/`next` and a `PathSet`. Pick\n * the transition log for devtools/time-travel, the plugin hook for\n * change-driven work.\n */\nexport class StateContainerRegistry {\n  private readonly instancesByConstructor = new WeakMap<\n    StateContainerConstructor,\n    Map<string, InstanceEntry>\n  >();\n\n  private readonly types = new Set<StateContainerConstructor>();\n\n  /**\n   * `depend()`-owner to the (Type, key) entries it has resolved. Keyed per\n   * resolved key because one handle resolves a different key per `args`.\n   * Weak so a bare `new`'d owner that is never disposed cannot pin the map.\n   */\n  private readonly _dependentEdges = new WeakMap<\n    StateContainer<any, any, any>,\n    Map<StateContainerConstructor, Set<string>>\n  >();\n\n  /** Reverse lookup from instance to its entry, so `_pruneEntry` is O(1). */\n  private readonly _entryByInstance = new WeakMap<\n    StateContainer<any, any, any>,\n    InstanceEntry\n  >();\n\n  /** Reverse lookup from `$blac.id` to its entry, for `PluginContext.getRefIds`. */\n  private readonly _entryById = new Map<string, InstanceEntry>();\n\n  private readonly listeners = new Map<\n    LifecycleEvent,\n    Set<(...args: any[]) => void>\n  >();\n\n  private _stateChangedListenerCount = 0;\n  get hasStateChangedListeners(): boolean {\n    return this._stateChangedListenerCount > 0;\n  }\n  private _pendingStateChanges: Array<\n    [StateContainer<any, any, any>, any, any]\n  > | null = null;\n\n  private _autoRefIdCounter = 0;\n\n  constructor() {\n    // Self-prune on direct dispose (bypassing release()) and sweep any\n    // depend()-owner edges this instance held, so orphaned dependencies\n    // (created via `ensure`, which never adds a public ref) don't leak.\n    this.on('disposed', (container) => this._handleDisposed(container));\n  }\n\n  /**\n   * Registry-internal reaction to any instance's `disposed` lifecycle event.\n   * If the disposing container is itself tracked in this registry (i.e. it\n   * was `acquire()`/`ensure()`'d, not a bare `new`), prune its Map entry and\n   * release its dependent edges on whatever it `depend()`'d on.\n   */\n  private _handleDisposed(container: StateContainer<any, any, any>): void {\n    const Type = container.constructor as StateContainerConstructor;\n    const found = this._pruneEntry(Type, container);\n    if (!found) return;\n    const edges = this._dependentEdges.get(container);\n    if (!edges) return;\n    this._dependentEdges.delete(container);\n    for (const [DepType, keys] of edges) {\n      for (const depKey of keys) {\n        this._releaseDependent(DepType, depKey, container);\n      }\n    }\n  }\n\n  /**\n   * An entry may be disposed only when nothing owns it: no public refs, no\n   * `depend()` dependents, and not keepAlive. Every dispose decision goes\n   * through here so `release()` and `_releaseDependent` cannot disagree.\n   */\n  private _isUnowned(\n    Type: StateContainerConstructor,\n    entry: InstanceEntry,\n  ): boolean {\n    return this._hasNoOwners(entry) && !isKeepAliveClass(Type);\n  }\n\n  /**\n   * Pure ownership: refs plus `depend()` dependents, with no keepAlive term.\n   * `_isUnowned` is \"may be disposed\"; this is \"nothing is using it\", which is\n   * what the activation lifecycle keys off — a keepAlive instance still\n   * deactivates when its last owner goes.\n   */\n  private _hasNoOwners(entry: InstanceEntry): boolean {\n    return (\n      entry.refs.size === 0 &&\n      (entry.dependents === undefined || entry.dependents.size === 0)\n    );\n  }\n\n  /**\n   * Single funnel for the 0↔1 ownership transition. `SET_ACTIVE` is idempotent,\n   * so every acquire/release path can call this unconditionally rather than\n   * each computing the edge itself. Emits `activated`/`deactivated` for\n   * plugins to observe the same transition `onActivate`/`onDeactivate` expose\n   * to bloc authors — after `SET_ACTIVE` has already run the instance's own\n   * hook, so plugins always see a container that has finished reacting.\n   */\n  private _syncActivation(entry: InstanceEntry): void {\n    const transition = entry.instance[SET_ACTIVE](!this._hasNoOwners(entry));\n    if (transition === 'none') return;\n    if (transition === 'deactivated') {\n      this.emit('deactivated', entry.instance);\n    } else {\n      this.emit('activated', entry.instance, transition.signal);\n    }\n  }\n\n  /**\n   * Record that `dependent` resolved `Type` at `key`, so the edge can be\n   * released on the owner's disposal. Keyed per resolved key, not per type:\n   * one `depend()` handle resolves a distinct key for every `args` it is\n   * called with, and all of them must be swept.\n   */\n  private _recordDependentEdge(\n    dependent: StateContainer<any, any, any>,\n    Type: StateContainerConstructor,\n    key: string,\n  ): void {\n    let byType = this._dependentEdges.get(dependent);\n    if (!byType) this._dependentEdges.set(dependent, (byType = new Map()));\n    let keys = byType.get(Type);\n    if (!keys) byType.set(Type, (keys = new Set()));\n    keys.add(key);\n  }\n\n  /**\n   * Remove the Map entry for `container`, if this registry is tracking it.\n   * @returns true if an entry was found and removed\n   */\n  private _pruneEntry(\n    Type: StateContainerConstructor,\n    container: StateContainer<any, any, any>,\n  ): boolean {\n    const entry = this._entryByInstance.get(container);\n    if (!entry) return false;\n    this.instancesByConstructor.get(Type)?.delete(entry.key);\n    this._entryById.delete(container.$blac.id);\n    return true;\n  }\n\n  /**\n   * Drop `dependent`'s edge on the `Type`/`key` entry (a `depend()`-resolved\n   * instance). When that leaves the entry with no dependents AND no public\n   * refs AND it isn't keepAlive, dispose it — this recurses into the same\n   * `disposed` listener, so dep-of-dep chains unwind naturally.\n   */\n  private _releaseDependent(\n    Type: StateContainerConstructor,\n    key: string,\n    dependent: StateContainer<any, any, any>,\n  ): void {\n    const instances = this.instancesByConstructor.get(Type);\n    const entry = instances?.get(key);\n    if (!entry) return;\n    entry.dependents?.delete(dependent);\n    if (this._isUnowned(Type, entry)) {\n      if (!entry.instance.$blac.disposed) entry.instance.dispose();\n      return;\n    }\n    this._syncActivation(entry);\n  }\n\n  /**\n   * Register a type for lifecycle event tracking\n   * @param constructor - The StateContainer class constructor\n   */\n  registerType<T extends StateContainerConstructor>(constructor: T): void {\n    this.types.add(constructor);\n  }\n\n  /**\n   * Register a StateContainer class with configuration\n   * @param constructor - The StateContainer class constructor\n   * @throws Error if type is already registered\n   */\n  register<T extends StateContainerConstructor>(constructor: T): void {\n    if (this.types.has(constructor)) {\n      throw new Error(\n        `${BLAC_ERROR_PREFIX} Type \"${getBlacName(constructor)}\" is already registered`,\n      );\n    }\n\n    this.registerType(constructor);\n  }\n\n  private ensureInstancesMap<T extends StateContainerConstructor>(\n    Type: T,\n  ): Map<string, InstanceEntry> {\n    let instances = this.instancesByConstructor.get(Type);\n    if (!instances) {\n      instances = new Map<string, InstanceEntry>();\n      this.instancesByConstructor.set(Type, instances);\n    }\n    return instances;\n  }\n\n  /**\n   * Get the instances Map for a specific class (public API for stats/debugging)\n   */\n  getInstancesMap<T extends StateContainerConstructor>(\n    Type: T,\n  ): ReadonlyMap<string, InstanceEntry> {\n    return this.instancesByConstructor.get(Type) || EMPTY_INSTANCES_MAP;\n  }\n\n  /**\n   * Directly insert an instance entry into the registry without going through\n   * acquire/release. Creates the internal WeakMap bucket for the constructor if\n   * it does not exist yet. Replaces any existing entry for the same key.\n   *\n   * The provided instance is NOT configured or disposed here — callers are\n   * responsible for any initConfig / dispose calls. Intended for testing\n   * helpers that create stubs outside the normal acquisition path.\n   *\n   * @internal Used by testing helpers only.\n   */\n  insertInstance<T extends StateContainerConstructor>(\n    Type: T,\n    instanceKey: string,\n    instance: InstanceType<T>,\n    refs: Map<string, number> = new Map(),\n  ): void {\n    const instances = this.ensureInstancesMap(Type);\n    const existingEntry = instances.get(instanceKey);\n    if (\n      existingEntry &&\n      existingEntry.instance !== instance &&\n      !existingEntry.instance.$blac.disposed\n    ) {\n      existingEntry.instance.dispose();\n    }\n    const entry: InstanceEntry = { instance, key: instanceKey, refs };\n    instances.set(instanceKey, entry);\n    this._entryByInstance.set(instance, entry);\n    this._entryById.set(instance.$blac.id, entry);\n  }\n\n  /**\n   * Resolve the storage key for an instance. This is the single source of truth\n   * for keying — `acquire` and `release` MUST agree, otherwise a ref taken under\n   * an args-derived key is never dropped (instance leaks).\n   *\n   * Resolution order (explicit beats derived):\n   * explicit key \\> `static key(args)` \\> structural hash of args \\> default sentinel.\n   *\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Explicit key, or undefined to derive from args\n   * @param args - Construction args used for structural/`static key` derivation\n   */\n  resolveKey<T extends StateContainerConstructor = StateContainerConstructor>(\n    Type: T,\n    instanceKey: string | undefined,\n    args: unknown,\n  ): string {\n    if (instanceKey !== undefined) {\n      return instanceKey;\n    }\n    const keyFn = getClassKey(Type);\n    if (keyFn) {\n      return keyFn(args);\n    }\n    if (args !== undefined) {\n      return structuralKey(args);\n    }\n    return DEFAULT_STRUCTURAL_KEY;\n  }\n\n  /**\n   * Circuit breaker for runaway instance creation. Throws when a single\n   * constructor would exceed `maxInstancesPerType` live instances — almost\n   * always an unstable instance key (e.g. a new object/array passed as `args`\n   * every render, or a missing `static key`) leaking an instance per render.\n   */\n  private assertInstanceLimit(\n    Type: StateContainerConstructor,\n    currentCount: number,\n  ): void {\n    const limit = getBlacConfig().maxInstancesPerType;\n    if (limit > 0 && currentCount >= limit) {\n      throw new Error(\n        `${BLAC_ERROR_PREFIX} ${Type.name} exceeded the maximum of ${limit} live instances. ` +\n          `This usually means the instance key is unstable — e.g. \\`args\\` that ` +\n          `change identity every render, or a missing \\`static key\\` — so a new ` +\n          `instance is created and never disposed (memory leak). Stabilize the key, ` +\n          `add a \\`static key(args)\\`, or raise \\`configureBlac({ maxInstancesPerType })\\`.`,\n      );\n    }\n  }\n\n  /**\n   * Circuit breaker for runaway reference growth. Throws when one instance\n   * accumulates more than `maxRefsPerInstance` distinct live refs — almost\n   * always consumer cleanup (e.g. `useBloc`'s unmount `release`) never firing.\n   */\n  private assertRefLimit(\n    Type: StateContainerConstructor,\n    resolvedKey: string,\n    refCount: number,\n  ): void {\n    const limit = getBlacConfig().maxRefsPerInstance;\n    if (limit > 0 && refCount > limit) {\n      throw new Error(\n        `${BLAC_ERROR_PREFIX} ${Type.name} instance \"${resolvedKey}\" exceeded the maximum of ${limit} live references. ` +\n          `This usually means references are acquired without a matching release ` +\n          `(e.g. a consumer that never unmounts/cleans up), leaking refs that keep ` +\n          `the instance alive forever. Ensure every acquire is paired with a release, ` +\n          `or raise \\`configureBlac({ maxRefsPerInstance })\\`.`,\n      );\n    }\n  }\n\n  /**\n   * Acquire an instance with ref tracking (ownership semantics).\n   * Creates a new instance if one doesn't exist, or returns existing and adds a ref.\n   * You must call `release()` with the same refId when done.\n   *\n   * @internal Internal key tier. Public callers use the args-based `acquire`\n   *   wrapper; `useBloc` and `watch` address a pre-resolved key here.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @param options - Acquisition options: `canCreate` (create when absent,\n   *   default true), `countRef` (add a reference, default true), `refId`\n   *   (named reference for debugging, auto-generated when omitted),\n   *   `dependent` — the `depend()`-owner resolving this instance, recorded so\n   *   its dependent edge is released on the owner's disposal — and\n   *   `sweepIfUnowned`, for callers that create speculatively and claim\n   *   ownership later (see {@link _scheduleSweep}).\n   * @returns The state container instance\n   */\n  acquire<T extends StateContainerConstructor = StateContainerConstructor>(\n    Type: T,\n    instanceKey?: string,\n    options: {\n      canCreate?: boolean;\n      countRef?: boolean;\n      refId?: string;\n      args?: unknown;\n      dependent?: StateContainer<any, any, any>;\n      sweepIfUnowned?: boolean;\n    } = {},\n  ): InstanceType<T> {\n    const { canCreate = true, countRef = true } = options;\n    const args = options.args;\n\n    const resolvedKey = this.resolveKey(Type, instanceKey, args);\n\n    const config: StateContainerConfig = {\n      instanceId: resolvedKey,\n      args,\n    };\n\n    const instances = this.ensureInstancesMap(Type);\n    let entry = instances.get(resolvedKey);\n\n    // Detect stale disposed entries (disposed directly, not through release)\n    if (entry?.instance.$blac.disposed) {\n      instances.delete(resolvedKey);\n      entry = undefined;\n    }\n\n    if (entry) {\n      // Dev-warn when the same key is reused with structurally different args.\n      if (IS_DEV && args !== undefined && entry.args !== undefined) {\n        const incomingKey = structuralKey(args);\n        const storedKey = (entry.argsKey ??= structuralKey(entry.args));\n        if (incomingKey !== storedKey) {\n          console.warn(\n            `${BLAC_ERROR_PREFIX} ${Type.name} instance key \"${resolvedKey}\" was acquired with different args. ` +\n              `Existing args: ${storedKey}, new args: ${incomingKey}. ` +\n              `The existing instance will be reused. If distinct args should produce distinct instances, ` +\n              `either remove the explicit instanceKey or provide a \\`static key\\` function that reflects the difference.`,\n          );\n        }\n      }\n\n      if (countRef) {\n        const refId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;\n        entry.refs.set(refId, (entry.refs.get(refId) ?? 0) + 1);\n        this.assertRefLimit(Type, resolvedKey, entry.refs.size);\n        this.emit('refAcquired', entry.instance, refId);\n      }\n\n      if (options.dependent) {\n        (entry.dependents ??= new Set()).add(options.dependent);\n        this._recordDependentEdge(options.dependent, Type, resolvedKey);\n      }\n\n      this._syncActivation(entry);\n\n      return entry.instance;\n    }\n\n    if (!canCreate) {\n      throw new Error(\n        `${BLAC_ERROR_PREFIX} ${Type.name} instance \"${resolvedKey}\" not found and creation is disabled.`,\n      );\n    }\n\n    // Circuit breaker: refuse to create when this type already holds too many\n    // live instances — a runaway key (unstable/args-derived) never disposing.\n    this.assertInstanceLimit(Type, instances.size);\n\n    // Create new shared instance\n    const instance = new Type() as InstanceType<T>;\n    instance[INIT_CONFIG](config);\n    const initialRefs = new Map<string, number>();\n    let initialRefId: string | undefined;\n    if (countRef) {\n      initialRefId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;\n      initialRefs.set(initialRefId, 1);\n    }\n    const newEntry: InstanceEntry = {\n      instance,\n      key: resolvedKey,\n      refs: initialRefs,\n      args,\n    };\n    if (options.dependent) {\n      (newEntry.dependents ??= new Set()).add(options.dependent);\n      this._recordDependentEdge(options.dependent, Type, resolvedKey);\n    }\n    instances.set(resolvedKey, newEntry);\n    this._entryByInstance.set(instance, newEntry);\n    this._entryById.set(instance.$blac.id, newEntry);\n\n    // Register type for lifecycle coordination\n    this.registerType(Type);\n\n    if (initialRefId) {\n      this.emit('refAcquired', instance, initialRefId);\n    }\n\n    this._syncActivation(newEntry);\n\n    if (options.sweepIfUnowned && this._hasNoOwners(newEntry)) {\n      this._scheduleSweep(Type, newEntry);\n    }\n\n    return instance;\n  }\n\n  /**\n   * Speculative creates (`useBloc`'s render-time create) leak forever when the\n   * render is discarded or never commits — SSR has no commit at all, so nothing\n   * ever claims ownership. Sweep at the end of the microtask unless the entry\n   * gained an owner or is keepAlive.\n   *\n   * Opt-in, not automatic: a bare `ensure()` hands the instance to a caller\n   * that legitimately holds it without a ref, and sweeping those would make\n   * `ensure` unusable across an `await`.\n   */\n  private _scheduleSweep(\n    Type: StateContainerConstructor,\n    entry: InstanceEntry,\n  ): void {\n    queueMicrotask(() => {\n      const instances = this.instancesByConstructor.get(Type);\n      if (instances?.get(entry.key) !== entry) return;\n      if (entry.instance.$blac.disposed) return;\n      if (!this._isUnowned(Type, entry)) return;\n      entry.instance.dispose();\n      instances.delete(entry.key);\n    });\n  }\n\n  /**\n   * Borrow an existing instance without adding a ref (borrowing semantics).\n   * Tracks cross-bloc dependency for reactive updates.\n   *\n   * @internal Internal key tier; public callers use the args-based `borrow`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @returns The state container instance\n   * @throws Error if instance doesn't exist\n   */\n  borrow<T extends StateContainerConstructor = StateContainerConstructor>(\n    Type: T,\n    instanceKey: string = DEFAULT_STRUCTURAL_KEY,\n  ): InstanceType<T> {\n    return this.acquire(Type, instanceKey, {\n      canCreate: false,\n      countRef: false,\n    });\n  }\n\n  /**\n   * Safely borrow an existing instance (borrowing semantics with error handling).\n   * Returns discriminated union for type-safe conditional access.\n   *\n   * @internal Internal key tier; public callers use the args-based `borrowSafe`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @returns Discriminated union with either the instance or an error\n   */\n  borrowSafe<T extends StateContainerConstructor = StateContainerConstructor>(\n    Type: T,\n    instanceKey: string = DEFAULT_STRUCTURAL_KEY,\n  ):\n    | { error: Error; instance: null }\n    | { error: null; instance: InstanceType<T> } {\n    try {\n      const instance = this.borrow(Type, instanceKey);\n      return { error: null, instance };\n    } catch (error: any) {\n      return { error, instance: null };\n    }\n  }\n\n  /**\n   * Ensure an instance exists without taking ownership (for bloc-to-bloc communication).\n   * Gets existing instance OR creates it if it doesn't exist, without adding a ref.\n   * Tracks cross-bloc dependency for reactive updates.\n   *\n   * Use this in bloc-to-bloc communication when you need to ensure an instance exists\n   * but don't want to claim ownership (no ref added).\n   *\n   * @internal Internal key tier; public callers use the args-based `ensure`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key, or undefined to derive from `args`\n   *   (`static key(args)` / structural hash), matching `acquire`.\n   * @param args - Construction args; used for keying when no explicit key is given\n   * @returns The state container instance\n   */\n  ensure<T extends StateContainerConstructor = StateContainerConstructor>(\n    Type: T,\n    instanceKey?: string,\n    args?: unknown,\n  ): InstanceType<T> {\n    return this.acquire(Type, instanceKey, {\n      canCreate: true,\n      countRef: false,\n      args,\n    });\n  }\n\n  /**\n   * Release a reference to an instance.\n   * Removes the ref and disposes when refs is empty (unless keepAlive).\n   * Releasing an already-removed refId is a no-op (idempotent).\n   *\n   * @internal Internal key tier; public callers use the args-based `release`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @param forceDispose - Force immediate disposal regardless of refs\n   * @param refId - The specific ref to remove; removes one arbitrary ref if omitted\n   */\n  release<T extends StateContainerConstructor>(\n    Type: T,\n    instanceKey: string = DEFAULT_STRUCTURAL_KEY,\n    forceDispose = false,\n    refId?: string,\n  ): void {\n    const instances = this.ensureInstancesMap(Type);\n    const entry = instances.get(instanceKey);\n\n    if (!entry) return;\n\n    // Force dispose immediately\n    if (forceDispose) {\n      if (!entry.instance.$blac.disposed) {\n        entry.instance.dispose();\n      }\n      instances.delete(instanceKey);\n      return;\n    }\n\n    // Decrement the named ref's count; when no refId is given, drop one\n    // arbitrary ref so an unscoped release still frees a reference.\n    let releasedRefId: string | undefined;\n    if (refId !== undefined) {\n      const count = entry.refs.get(refId) ?? 0;\n      if (count <= 1) {\n        entry.refs.delete(refId);\n      } else {\n        entry.refs.set(refId, count - 1);\n      }\n      releasedRefId = refId;\n    } else {\n      const firstKey = entry.refs.keys().next().value;\n      if (firstKey !== undefined) {\n        const count = entry.refs.get(firstKey) ?? 0;\n        if (count <= 1) {\n          entry.refs.delete(firstKey);\n        } else {\n          entry.refs.set(firstKey, count - 1);\n        }\n        releasedRefId = firstKey;\n      }\n    }\n\n    if (releasedRefId) {\n      this.emit('refReleased', entry.instance, releasedRefId);\n    }\n\n    // Auto-dispose only when nothing owns the entry. A `depend()`-owner that\n    // is still alive keeps its dependency, even once the last public ref goes.\n    // Dispose is checked first so a disposing entry never also fires\n    // `onDeactivate` — dispose is the single teardown path for that case.\n    if (this._isUnowned(Type, entry)) {\n      if (!entry.instance.$blac.disposed) {\n        entry.instance.dispose();\n      }\n      instances.delete(instanceKey);\n      return;\n    }\n\n    this._syncActivation(entry);\n  }\n\n  /**\n   * Get all instances of a specific type.\n   * @param Type - The StateContainer class constructor\n   * @returns Array of all instances\n   */\n  getAll<T extends StateContainerConstructor>(\n    Type: T,\n  ): InstanceReadonlyState<T>[] {\n    const instances = this.ensureInstancesMap(Type);\n    const result: InstanceReadonlyState<T>[] = [];\n    for (const entry of instances.values()) {\n      if (!entry.instance.$blac.disposed) {\n        result.push(entry.instance);\n      }\n    }\n    return result;\n  }\n\n  /**\n   * Safely iterate over all instances of a type.\n   * Skips disposed instances and catches callback errors.\n   * @param Type - The StateContainer class constructor\n   * @param callback - Function to call for each instance\n   */\n  forEach<T extends StateContainerConstructor>(\n    Type: T,\n    callback: (instance: InstanceReadonlyState<T>) => void,\n  ): void {\n    const instances = this.ensureInstancesMap(Type);\n    for (const entry of instances.values()) {\n      const instance = entry.instance;\n      if (!instance.$blac.disposed) {\n        try {\n          callback(instance);\n        } catch (error) {\n          console.error(\n            `${BLAC_ERROR_PREFIX} forEach callback error for ${Type.name}:`,\n            error,\n          );\n        }\n      }\n    }\n  }\n\n  /**\n   * Clear all instances of a specific type (disposes them).\n   * @param Type - The StateContainer class constructor\n   */\n  clear<T extends StateContainerConstructor>(Type: T): void {\n    const instances = this.ensureInstancesMap(Type);\n    // Dispose all instances\n    for (const entry of instances.values()) {\n      if (!entry.instance.$blac.disposed) {\n        entry.instance.dispose();\n      }\n    }\n    // Clear the Map\n    instances.clear();\n  }\n\n  /**\n   * Get reference count for an instance (number of active refs).\n   *\n   * @internal Internal key tier; public callers use the args-based `getRefCount`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @returns Current ref count (0 if instance doesn't exist)\n   */\n  getRefCount<T extends StateContainerConstructor>(\n    Type: T,\n    instanceKey: string = DEFAULT_STRUCTURAL_KEY,\n  ): number {\n    const instances = this.ensureInstancesMap(Type);\n    const entry = instances.get(instanceKey);\n    return entry?.refs.size ?? 0;\n  }\n\n  /**\n   * Get all active reference IDs for an instance.\n   *\n   * @internal Internal key tier; public callers use the args-based `getRefIds`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @returns Array of ref ID strings (empty if instance doesn't exist)\n   */\n  getRefIds<T extends StateContainerConstructor>(\n    Type: T,\n    instanceKey: string = DEFAULT_STRUCTURAL_KEY,\n  ): string[] {\n    const instances = this.instancesByConstructor.get(Type);\n    if (!instances) return [];\n    const entry = instances.get(instanceKey);\n    return entry ? Array.from(entry.refs.keys()) : [];\n  }\n\n  /**\n   * Get all active reference IDs for an instance by its `$blac.id`, without\n   * needing the owning Type. Used by `PluginContext.getRefIds`.\n   * @param instanceId - The instance's `$blac.id`\n   * @returns Array of ref ID strings (empty if instance doesn't exist)\n   */\n  getRefIdsById(instanceId: string): string[] {\n    const entry = this._entryById.get(instanceId);\n    return entry ? Array.from(entry.refs.keys()) : [];\n  }\n\n  /**\n   * Check if an instance exists.\n   *\n   * @internal Internal key tier; public callers use the args-based `hasInstance`.\n   * @param Type - The StateContainer class constructor\n   * @param instanceKey - Pre-resolved instance key (defaults to 'default')\n   * @returns true if instance exists\n   */\n  hasInstance<T extends StateContainerConstructor>(\n    Type: T,\n    instanceKey: string = DEFAULT_STRUCTURAL_KEY,\n  ): boolean {\n    const instances = this.ensureInstancesMap(Type);\n    return instances.has(instanceKey);\n  }\n\n  /**\n   * Clear all instances from all types (for testing)\n   *\n   * Iterates all registered types and clears their instances.\n   * Also clears type tracking to reset the registry state.\n   */\n  clearAll(): void {\n    // Step 1: Clear instances from each type (while we still have the types list)\n    for (const Type of this.types) {\n      this.clear(Type);\n    }\n    // Step 2: Now clear type tracking (resets registry state for tests)\n    this.types.clear();\n  }\n\n  /**\n   * Get registry statistics for debugging.\n   * @returns Object with registeredTypes, totalInstances, and typeBreakdown\n   */\n  getStats(): {\n    registeredTypes: number;\n    totalInstances: number;\n    typeBreakdown: Record<string, number>;\n  } {\n    const typeBreakdown: Record<string, number> = {};\n    let totalInstances = 0;\n\n    // Collect stats from each registered type\n    for (const Type of this.types) {\n      const typeName = Type.name;\n      const instances = this.getInstancesMap(Type);\n      const count = instances.size;\n\n      typeBreakdown[typeName] = count;\n      totalInstances += count;\n    }\n\n    return {\n      registeredTypes: this.types.size,\n      totalInstances,\n      typeBreakdown,\n    };\n  }\n\n  /**\n   * Get all registered types (for plugin system).\n   * @returns Array of all registered StateContainer class constructors\n   */\n  getTypes(): StateContainerConstructor[] {\n    return Array.from(this.types);\n  }\n\n  /**\n   * Subscribe to lifecycle events\n   * @param event - The lifecycle event to listen for\n   * @param listener - The listener function to call when the event occurs\n   * @returns Unsubscribe function\n   */\n  on<E extends LifecycleEvent>(\n    event: E,\n    listener: LifecycleListener<E>,\n  ): () => void {\n    let instance = this.listeners.get(event);\n    if (!instance) {\n      instance = new Set();\n      this.listeners.set(event, instance);\n    }\n\n    instance.add(listener as (...args: any[]) => void);\n\n    if (event === 'stateChanged') {\n      this._stateChangedListenerCount++;\n    }\n\n    // Return unsubscribe function\n    return () => {\n      const deleted = this.listeners\n        .get(event)\n        ?.delete(listener as (...args: any[]) => void);\n      if (deleted && event === 'stateChanged') {\n        this._stateChangedListenerCount--;\n      }\n    };\n  }\n\n  /**\n   * Emit lifecycle event to all listeners\n   * @internal - Called by StateContainer lifecycle methods\n   */\n  emit(event: 'created', container: StateContainer<any, any, any>): void;\n  emit(event: 'disposed', container: StateContainer<any, any, any>): void;\n  emit(\n    event: 'stateChanged',\n    container: StateContainer<any, any, any>,\n    previousState: any,\n    currentState: any,\n  ): void;\n  emit(\n    event: 'refAcquired',\n    container: StateContainer<any, any, any>,\n    refId: string,\n  ): void;\n  emit(\n    event: 'refReleased',\n    container: StateContainer<any, any, any>,\n    refId: string,\n  ): void;\n  emit(\n    event: 'depsChanged',\n    container: StateContainer<any, any, any>,\n    previousDeps: Readonly<Record<string, unknown>>,\n    currentDeps: Readonly<Record<string, unknown>>,\n  ): void;\n  emit(\n    event: 'hydrationChanged',\n    container: StateContainer<any, any, any>,\n    status: HydrationStatus,\n    previousStatus: HydrationStatus,\n  ): void;\n  emit(\n    event: 'activated',\n    container: StateContainer<any, any, any>,\n    signal: AbortSignal,\n  ): void;\n  emit(event: 'deactivated', container: StateContainer<any, any, any>): void;\n  emit(event: LifecycleEvent, ...args: any[]): void {\n    const listeners = this.listeners.get(event);\n    if (!listeners || listeners.size === 0) return; // Zero overhead when no listeners\n\n    for (const listener of listeners) {\n      try {\n        listener(...args);\n      } catch (error) {\n        console.error(\n          `${BLAC_ERROR_PREFIX} Listener error for '${event}':`,\n          error,\n        );\n      }\n    }\n  }\n\n  /**\n   * Schedule a deferred stateChanged notification via microtask.\n   * Skips entirely when no stateChanged listeners are registered.\n   * @internal - Called by StateContainer.applyState\n   */\n  notifyStateChanged(\n    container: StateContainer<any, any, any>,\n    previousState: any,\n    newState: any,\n  ): void {\n    if (this._stateChangedListenerCount === 0) return;\n\n    if (!this._pendingStateChanges) {\n      this._pendingStateChanges = [];\n      queueMicrotask(() => this.flushStateChanged());\n    }\n    this._pendingStateChanges.push([container, previousState, newState]);\n  }\n\n  /**\n   * Deliver one event per emit, in order — deliberately NOT coalesced.\n   *\n   * This is a transition log: devtools, time-travel debugging and perf\n   * monitoring need every intermediate `prev`/`next`, which coalescing would\n   * destroy. The plugin `onStateChange` bridge is the coalesced, `PathSet`-\n   * carrying lane (see `PluginManager.setupLifecycleHooks`); the two differ on\n   * purpose, so a listener picks the lane that matches what it needs.\n   */\n  private flushStateChanged(): void {\n    const pending = this._pendingStateChanges;\n    this._pendingStateChanges = null;\n    if (!pending) return;\n\n    for (const [container, prev, next] of pending) {\n      this.emit('stateChanged', container, prev, next);\n    }\n  }\n}\n\n/**\n * Global default registry instance\n * @public\n */\nexport const globalRegistry = new StateContainerRegistry();\n"],"mappings":";;;;;;AAuDA,MAAa,qBAAiC,MAAM,SAAS;CAC3D,IAAI,OAAO,GAAG,MAAM,IAAI,GAAG,OAAO;CAClC,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM,OAAO;CACtD,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM,OAAO;CAEtD,MAAM,WAAW,OAAO,KAAK,IAAc;CAC3C,IAAI,SAAS,WAAW,OAAO,KAAK,IAAc,EAAE,QAAQ,OAAO;CAEnE,KAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;EACxC,MAAM,MAAM,SAAS;EACrB,IACE,CAAC,OAAO,GACL,KAAiC,MACjC,KAAiC,IACpC,GAEA,OAAO;CAEX;CACA,OAAO;AACT;AAEA,MAAM,gBAA4B;CAChC,UAAU;CACV,qBAAqB;CACrB,oBAAoB;CACpB,mBAAmB;AACrB;AAEA,IAAI,eAA2B,EAAE,GAAG,cAAc;;;;;;;;;;;;AAalD,SAAgB,cAAc,QAAmC;CAC/D,eAAe;EAAE,GAAG;EAAc,GAAG;CAAO;AAC9C;;;;;AAMA,SAAgB,gBAA4B;CAC1C,OAAO;AACT;;;;;AAMA,SAAgB,kBAAwB;CACtC,eAAe,EAAE,GAAG,cAAc;AACpC;;;;;;;;;;;;ACzGA,MAAa,oBAAoB;;;;CAI/B,YAAY;;;;CAKZ,uBAAuB;;;;;;CAOvB,UAAU;;;;;;;CAQV,KAAK;;;;;CAML,WAAW;AACb;;;;AAKA,MAAa,oBAAoB;;;;;;;;AASjC,MAAa,SACX,OAAO,YAAY,eAAe,QAAQ,KAAK,aAAa;;;;;;;;;;;;;;;;ACtC9D,SAAgB,cAGd,MAAS,UAAkB,cAAiC;CAC5D,OAAQ,KAAa,aAAa;AACpC;;;;;;;;;AAUA,SAAgB,iBAGd,MAAS,UAAiC;CAC1C,OAAO,OAAO,OAAO,MAAM,QAAQ,IAAK,KAAa,YAAY,KAAA;AACnE;;;;;;;;AASA,SAAgB,iBACd,MACS;CACT,OAAO,cAAuB,MAAM,kBAAkB,UAAU,MAAM;AACxE;;;;;;;;AASA,SAAgB,uBACd,MACS;CACT,OACE,cAAuB,MAAM,kBAAkB,qBAAqB,MACpE;AAEJ;;;;;;;AAQA,SAAgB,iBACd,MACwB;CACxB,MAAM,KAAK,cAA0B,MAAM,kBAAkB,QAAQ;CACrE,OAAO,OAAO,OAAO,aAAa,KAAK,KAAA;AACzC;;;;;;;;;AAUA,SAAgB,YACd,MACQ;CACR,OACE,iBAAyB,MAAM,kBAAkB,SAAS,KAAK,KAAK;AAExE;;;;;;;;;AAUA,SAAgB,YACd,MACqC;CACrC,MAAM,KAAK,iBACT,MACA,kBAAkB,GACpB;CACA,OAAO,OAAO,OAAO,aAAa,KAAK,KAAA;AACzC;;;;;;;;AC5GA,MAAa,yBAAyB;;;;;;;;;;AAWtC,MAAM,2BAAW,IAAI,QAAwB;AAE7C,SAAgB,cAAc,MAAuB;CACnD,IAAI,SAAS,KAAA,KAAa,SAAS,MACjC,OAAO;CAGT,IAAI,OAAO,SAAS,UAAU;EAC5B,MAAM,SAAS,SAAS,IAAI,IAAI;EAChC,IAAI,WAAW,KAAA,GAAW,OAAO;EACjC,MAAM,MAAM,UAAU,IAAI;EAC1B,SAAS,IAAI,MAAM,GAAG;EACtB,OAAO;CACT;CAEA,OAAO,UAAU,IAAI;AACvB;AAEA,SAAS,UAAU,MAAuB;CACxC,OAAO,KAAK,UAAU,MAAM,SAAU,IAAI,GAAG;EAC3C,IAAI,OAAO,MAAM,YACf,MAAM,IAAI,MACR,8FAC+B,MAAM,SAAS,GAChD;EAEF,IAAI,KAAK,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC,GAChD,OAAO,OAAO,KAAK,CAAC,EACjB,KAAK,EACL,QACE,GAAG,MAAM;GACR,EAAW,KAAM,EAAU;GAC3B,OAAO;EACT,GACA,CAAC,CACH;EAEJ,OAAO;CACT,CAAC;AACH;;;;;;;ACpDA,MAAa,aAAa,OAAO,gBAAgB;;;;;AAMjD,MAAa,oBAAoB,OAAO,sBAAsB;;;;;;AAO9D,MAAa,aAAa,OAAO,gBAAgB;;;;;;;;;;AAWjD,MAAa,cAAc,OAAO,iBAAiB;;;;;;;;;AAUnD,MAAa,qBAAqB,OAAO,uBAAuB;;;;;;;;AAShE,MAAa,aAAa,OAAO,gBAAgB;;;;ACPjD,MAAM,sCAA0D,IAAI,IAAI;;;;;;;;;;;;;;;;;;;;;AA6ExE,IAAa,yBAAb,MAAoC;CAiClC,IAAI,2BAAoC;EACtC,OAAO,KAAK,6BAA6B;CAC3C;CAOA,cAAc;gDAzC4B,IAAI,QAG5C;+BAEuB,IAAI,IAA+B;yCAOzB,IAAI,QAGrC;0CAGkC,IAAI,QAGtC;oCAG4B,IAAI,IAA2B;mCAEhC,IAAI,IAG/B;oCAEmC;8BAM1B;2BAEiB;EAM1B,KAAK,GAAG,aAAa,cAAc,KAAK,gBAAgB,SAAS,CAAC;CACpE;;;;;;;CAQA,gBAAwB,WAAgD;EACtE,MAAM,OAAO,UAAU;EAEvB,IAAI,CADU,KAAK,YAAY,MAAM,SAC5B,GAAG;EACZ,MAAM,QAAQ,KAAK,gBAAgB,IAAI,SAAS;EAChD,IAAI,CAAC,OAAO;EACZ,KAAK,gBAAgB,OAAO,SAAS;EACrC,KAAK,MAAM,CAAC,SAAS,SAAS,OAC5B,KAAK,MAAM,UAAU,MACnB,KAAK,kBAAkB,SAAS,QAAQ,SAAS;CAGvD;;;;;;CAOA,WACE,MACA,OACS;EACT,OAAO,KAAK,aAAa,KAAK,KAAK,CAAC,iBAAiB,IAAI;CAC3D;;;;;;;CAQA,aAAqB,OAA+B;EAClD,OACE,MAAM,KAAK,SAAS,MACnB,MAAM,eAAe,KAAA,KAAa,MAAM,WAAW,SAAS;CAEjE;;;;;;;;;CAUA,gBAAwB,OAA4B;EAClD,MAAM,aAAa,MAAM,SAAS,YAAY,CAAC,KAAK,aAAa,KAAK,CAAC;EACvE,IAAI,eAAe,QAAQ;EAC3B,IAAI,eAAe,eACjB,KAAK,KAAK,eAAe,MAAM,QAAQ;OAEvC,KAAK,KAAK,aAAa,MAAM,UAAU,WAAW,MAAM;CAE5D;;;;;;;CAQA,qBACE,WACA,MACA,KACM;EACN,IAAI,SAAS,KAAK,gBAAgB,IAAI,SAAS;EAC/C,IAAI,CAAC,QAAQ,KAAK,gBAAgB,IAAI,WAAY,yBAAS,IAAI,IAAI,CAAE;EACrE,IAAI,OAAO,OAAO,IAAI,IAAI;EAC1B,IAAI,CAAC,MAAM,OAAO,IAAI,MAAO,uBAAO,IAAI,IAAI,CAAE;EAC9C,KAAK,IAAI,GAAG;CACd;;;;;CAMA,YACE,MACA,WACS;EACT,MAAM,QAAQ,KAAK,iBAAiB,IAAI,SAAS;EACjD,IAAI,CAAC,OAAO,OAAO;EACnB,KAAK,uBAAuB,IAAI,IAAI,GAAG,OAAO,MAAM,GAAG;EACvD,KAAK,WAAW,OAAO,UAAU,MAAM,EAAE;EACzC,OAAO;CACT;;;;;;;CAQA,kBACE,MACA,KACA,WACM;EAEN,MAAM,QADY,KAAK,uBAAuB,IAAI,IAC5B,GAAG,IAAI,GAAG;EAChC,IAAI,CAAC,OAAO;EACZ,MAAM,YAAY,OAAO,SAAS;EAClC,IAAI,KAAK,WAAW,MAAM,KAAK,GAAG;GAChC,IAAI,CAAC,MAAM,SAAS,MAAM,UAAU,MAAM,SAAS,QAAQ;GAC3D;EACF;EACA,KAAK,gBAAgB,KAAK;CAC5B;;;;;CAMA,aAAkD,aAAsB;EACtE,KAAK,MAAM,IAAI,WAAW;CAC5B;;;;;;CAOA,SAA8C,aAAsB;EAClE,IAAI,KAAK,MAAM,IAAI,WAAW,GAC5B,MAAM,IAAI,MACR,GAAG,kBAAkB,SAAS,YAAY,WAAW,EAAE,wBACzD;EAGF,KAAK,aAAa,WAAW;CAC/B;CAEA,mBACE,MAC4B;EAC5B,IAAI,YAAY,KAAK,uBAAuB,IAAI,IAAI;EACpD,IAAI,CAAC,WAAW;GACd,4BAAY,IAAI,IAA2B;GAC3C,KAAK,uBAAuB,IAAI,MAAM,SAAS;EACjD;EACA,OAAO;CACT;;;;CAKA,gBACE,MACoC;EACpC,OAAO,KAAK,uBAAuB,IAAI,IAAI,KAAK;CAClD;;;;;;;;;;;;CAaA,eACE,MACA,aACA,UACA,uBAA4B,IAAI,IAAI,GAC9B;EACN,MAAM,YAAY,KAAK,mBAAmB,IAAI;EAC9C,MAAM,gBAAgB,UAAU,IAAI,WAAW;EAC/C,IACE,iBACA,cAAc,aAAa,YAC3B,CAAC,cAAc,SAAS,MAAM,UAE9B,cAAc,SAAS,QAAQ;EAEjC,MAAM,QAAuB;GAAE;GAAU,KAAK;GAAa;EAAK;EAChE,UAAU,IAAI,aAAa,KAAK;EAChC,KAAK,iBAAiB,IAAI,UAAU,KAAK;EACzC,KAAK,WAAW,IAAI,SAAS,MAAM,IAAI,KAAK;CAC9C;;;;;;;;;;;;;CAcA,WACE,MACA,aACA,MACQ;EACR,IAAI,gBAAgB,KAAA,GAClB,OAAO;EAET,MAAM,QAAQ,YAAY,IAAI;EAC9B,IAAI,OACF,OAAO,MAAM,IAAI;EAEnB,IAAI,SAAS,KAAA,GACX,OAAO,cAAc,IAAI;EAE3B,OAAO;CACT;;;;;;;CAQA,oBACE,MACA,cACM;EACN,MAAM,QAAQ,cAAc,EAAE;EAC9B,IAAI,QAAQ,KAAK,gBAAgB,OAC/B,MAAM,IAAI,MACR,GAAG,kBAAkB,GAAG,KAAK,KAAK,2BAA2B,MAAM,qTAKrE;CAEJ;;;;;;CAOA,eACE,MACA,aACA,UACM;EACN,MAAM,QAAQ,cAAc,EAAE;EAC9B,IAAI,QAAQ,KAAK,WAAW,OAC1B,MAAM,IAAI,MACR,GAAG,kBAAkB,GAAG,KAAK,KAAK,aAAa,YAAY,4BAA4B,MAAM,+RAK/F;CAEJ;;;;;;;;;;;;;;;;;;;CAoBA,QACE,MACA,aACA,UAOI,CAAC,GACY;EACjB,MAAM,EAAE,YAAY,MAAM,WAAW,SAAS;EAC9C,MAAM,OAAO,QAAQ;EAErB,MAAM,cAAc,KAAK,WAAW,MAAM,aAAa,IAAI;EAE3D,MAAM,SAA+B;GACnC,YAAY;GACZ;EACF;EAEA,MAAM,YAAY,KAAK,mBAAmB,IAAI;EAC9C,IAAI,QAAQ,UAAU,IAAI,WAAW;EAGrC,IAAI,OAAO,SAAS,MAAM,UAAU;GAClC,UAAU,OAAO,WAAW;GAC5B,QAAQ,KAAA;EACV;EAEA,IAAI,OAAO;GAET,IAAI,UAAU,SAAS,KAAA,KAAa,MAAM,SAAS,KAAA,GAAW;IAC5D,MAAM,cAAc,cAAc,IAAI;IACtC,MAAM,YAAa,MAAM,YAAY,cAAc,MAAM,IAAI;IAC7D,IAAI,gBAAgB,WAClB,QAAQ,KACN,GAAG,kBAAkB,GAAG,KAAK,KAAK,iBAAiB,YAAY,qDAC3C,UAAU,cAAc,YAAY,sMAG1D;GAEJ;GAEA,IAAI,UAAU;IACZ,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C,MAAM,KAAK,IAAI,QAAQ,MAAM,KAAK,IAAI,KAAK,KAAK,KAAK,CAAC;IACtD,KAAK,eAAe,MAAM,aAAa,MAAM,KAAK,IAAI;IACtD,KAAK,KAAK,eAAe,MAAM,UAAU,KAAK;GAChD;GAEA,IAAI,QAAQ,WAAW;IACrB,CAAC,MAAM,+BAAe,IAAI,IAAI,GAAG,IAAI,QAAQ,SAAS;IACtD,KAAK,qBAAqB,QAAQ,WAAW,MAAM,WAAW;GAChE;GAEA,KAAK,gBAAgB,KAAK;GAE1B,OAAO,MAAM;EACf;EAEA,IAAI,CAAC,WACH,MAAM,IAAI,MACR,GAAG,kBAAkB,GAAG,KAAK,KAAK,aAAa,YAAY,sCAC7D;EAKF,KAAK,oBAAoB,MAAM,UAAU,IAAI;EAG7C,MAAM,WAAW,IAAI,KAAK;EAC1B,SAAS,aAAa,MAAM;EAC5B,MAAM,8BAAc,IAAI,IAAoB;EAC5C,IAAI;EACJ,IAAI,UAAU;GACZ,eAAe,QAAQ,SAAS,SAAS,KAAK;GAC9C,YAAY,IAAI,cAAc,CAAC;EACjC;EACA,MAAM,WAA0B;GAC9B;GACA,KAAK;GACL,MAAM;GACN;EACF;EACA,IAAI,QAAQ,WAAW;GACrB,CAAC,SAAS,+BAAe,IAAI,IAAI,GAAG,IAAI,QAAQ,SAAS;GACzD,KAAK,qBAAqB,QAAQ,WAAW,MAAM,WAAW;EAChE;EACA,UAAU,IAAI,aAAa,QAAQ;EACnC,KAAK,iBAAiB,IAAI,UAAU,QAAQ;EAC5C,KAAK,WAAW,IAAI,SAAS,MAAM,IAAI,QAAQ;EAG/C,KAAK,aAAa,IAAI;EAEtB,IAAI,cACF,KAAK,KAAK,eAAe,UAAU,YAAY;EAGjD,KAAK,gBAAgB,QAAQ;EAE7B,IAAI,QAAQ,kBAAkB,KAAK,aAAa,QAAQ,GACtD,KAAK,eAAe,MAAM,QAAQ;EAGpC,OAAO;CACT;;;;;;;;;;;CAYA,eACE,MACA,OACM;EACN,qBAAqB;GACnB,MAAM,YAAY,KAAK,uBAAuB,IAAI,IAAI;GACtD,IAAI,WAAW,IAAI,MAAM,GAAG,MAAM,OAAO;GACzC,IAAI,MAAM,SAAS,MAAM,UAAU;GACnC,IAAI,CAAC,KAAK,WAAW,MAAM,KAAK,GAAG;GACnC,MAAM,SAAS,QAAQ;GACvB,UAAU,OAAO,MAAM,GAAG;EAC5B,CAAC;CACH;;;;;;;;;;;CAYA,OACE,MACA,cAAsB,wBACL;EACjB,OAAO,KAAK,QAAQ,MAAM,aAAa;GACrC,WAAW;GACX,UAAU;EACZ,CAAC;CACH;;;;;;;;;;CAWA,WACE,MACA,cAAsB,wBAGuB;EAC7C,IAAI;GAEF,OAAO;IAAE,OAAO;IAAM,UADL,KAAK,OAAO,MAAM,WACN;GAAE;EACjC,SAAS,OAAY;GACnB,OAAO;IAAE;IAAO,UAAU;GAAK;EACjC;CACF;;;;;;;;;;;;;;;;CAiBA,OACE,MACA,aACA,MACiB;EACjB,OAAO,KAAK,QAAQ,MAAM,aAAa;GACrC,WAAW;GACX,UAAU;GACV;EACF,CAAC;CACH;;;;;;;;;;;;CAaA,QACE,MACA,cAAsB,wBACtB,eAAe,OACf,OACM;EACN,MAAM,YAAY,KAAK,mBAAmB,IAAI;EAC9C,MAAM,QAAQ,UAAU,IAAI,WAAW;EAEvC,IAAI,CAAC,OAAO;EAGZ,IAAI,cAAc;GAChB,IAAI,CAAC,MAAM,SAAS,MAAM,UACxB,MAAM,SAAS,QAAQ;GAEzB,UAAU,OAAO,WAAW;GAC5B;EACF;EAIA,IAAI;EACJ,IAAI,UAAU,KAAA,GAAW;GACvB,MAAM,QAAQ,MAAM,KAAK,IAAI,KAAK,KAAK;GACvC,IAAI,SAAS,GACX,MAAM,KAAK,OAAO,KAAK;QAEvB,MAAM,KAAK,IAAI,OAAO,QAAQ,CAAC;GAEjC,gBAAgB;EAClB,OAAO;GACL,MAAM,WAAW,MAAM,KAAK,KAAK,EAAE,KAAK,EAAE;GAC1C,IAAI,aAAa,KAAA,GAAW;IAC1B,MAAM,QAAQ,MAAM,KAAK,IAAI,QAAQ,KAAK;IAC1C,IAAI,SAAS,GACX,MAAM,KAAK,OAAO,QAAQ;SAE1B,MAAM,KAAK,IAAI,UAAU,QAAQ,CAAC;IAEpC,gBAAgB;GAClB;EACF;EAEA,IAAI,eACF,KAAK,KAAK,eAAe,MAAM,UAAU,aAAa;EAOxD,IAAI,KAAK,WAAW,MAAM,KAAK,GAAG;GAChC,IAAI,CAAC,MAAM,SAAS,MAAM,UACxB,MAAM,SAAS,QAAQ;GAEzB,UAAU,OAAO,WAAW;GAC5B;EACF;EAEA,KAAK,gBAAgB,KAAK;CAC5B;;;;;;CAOA,OACE,MAC4B;EAC5B,MAAM,YAAY,KAAK,mBAAmB,IAAI;EAC9C,MAAM,SAAqC,CAAC;EAC5C,KAAK,MAAM,SAAS,UAAU,OAAO,GACnC,IAAI,CAAC,MAAM,SAAS,MAAM,UACxB,OAAO,KAAK,MAAM,QAAQ;EAG9B,OAAO;CACT;;;;;;;CAQA,QACE,MACA,UACM;EACN,MAAM,YAAY,KAAK,mBAAmB,IAAI;EAC9C,KAAK,MAAM,SAAS,UAAU,OAAO,GAAG;GACtC,MAAM,WAAW,MAAM;GACvB,IAAI,CAAC,SAAS,MAAM,UAClB,IAAI;IACF,SAAS,QAAQ;GACnB,SAAS,OAAO;IACd,QAAQ,MACN,GAAG,kBAAkB,8BAA8B,KAAK,KAAK,IAC7D,KACF;GACF;EAEJ;CACF;;;;;CAMA,MAA2C,MAAe;EACxD,MAAM,YAAY,KAAK,mBAAmB,IAAI;EAE9C,KAAK,MAAM,SAAS,UAAU,OAAO,GACnC,IAAI,CAAC,MAAM,SAAS,MAAM,UACxB,MAAM,SAAS,QAAQ;EAI3B,UAAU,MAAM;CAClB;;;;;;;;;CAUA,YACE,MACA,cAAsB,wBACd;EAGR,OAFkB,KAAK,mBAAmB,IACpB,EAAE,IAAI,WACjB,GAAG,KAAK,QAAQ;CAC7B;;;;;;;;;CAUA,UACE,MACA,cAAsB,wBACZ;EACV,MAAM,YAAY,KAAK,uBAAuB,IAAI,IAAI;EACtD,IAAI,CAAC,WAAW,OAAO,CAAC;EACxB,MAAM,QAAQ,UAAU,IAAI,WAAW;EACvC,OAAO,QAAQ,MAAM,KAAK,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC;CAClD;;;;;;;CAQA,cAAc,YAA8B;EAC1C,MAAM,QAAQ,KAAK,WAAW,IAAI,UAAU;EAC5C,OAAO,QAAQ,MAAM,KAAK,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC;CAClD;;;;;;;;;CAUA,YACE,MACA,cAAsB,wBACb;EAET,OADkB,KAAK,mBAAmB,IAC3B,EAAE,IAAI,WAAW;CAClC;;;;;;;CAQA,WAAiB;EAEf,KAAK,MAAM,QAAQ,KAAK,OACtB,KAAK,MAAM,IAAI;EAGjB,KAAK,MAAM,MAAM;CACnB;;;;;CAMA,WAIE;EACA,MAAM,gBAAwC,CAAC;EAC/C,IAAI,iBAAiB;EAGrB,KAAK,MAAM,QAAQ,KAAK,OAAO;GAC7B,MAAM,WAAW,KAAK;GAEtB,MAAM,QADY,KAAK,gBAAgB,IACjB,EAAE;GAExB,cAAc,YAAY;GAC1B,kBAAkB;EACpB;EAEA,OAAO;GACL,iBAAiB,KAAK,MAAM;GAC5B;GACA;EACF;CACF;;;;;CAMA,WAAwC;EACtC,OAAO,MAAM,KAAK,KAAK,KAAK;CAC9B;;;;;;;CAQA,GACE,OACA,UACY;EACZ,IAAI,WAAW,KAAK,UAAU,IAAI,KAAK;EACvC,IAAI,CAAC,UAAU;GACb,2BAAW,IAAI,IAAI;GACnB,KAAK,UAAU,IAAI,OAAO,QAAQ;EACpC;EAEA,SAAS,IAAI,QAAoC;EAEjD,IAAI,UAAU,gBACZ,KAAK;EAIP,aAAa;GAIX,IAHgB,KAAK,UAClB,IAAI,KAAK,GACR,OAAO,QAAoC,KAChC,UAAU,gBACvB,KAAK;EAET;CACF;CA0CA,KAAK,OAAuB,GAAG,MAAmB;EAChD,MAAM,YAAY,KAAK,UAAU,IAAI,KAAK;EAC1C,IAAI,CAAC,aAAa,UAAU,SAAS,GAAG;EAExC,KAAK,MAAM,YAAY,WACrB,IAAI;GACF,SAAS,GAAG,IAAI;EAClB,SAAS,OAAO;GACd,QAAQ,MACN,GAAG,kBAAkB,uBAAuB,MAAM,KAClD,KACF;EACF;CAEJ;;;;;;CAOA,mBACE,WACA,eACA,UACM;EACN,IAAI,KAAK,+BAA+B,GAAG;EAE3C,IAAI,CAAC,KAAK,sBAAsB;GAC9B,KAAK,uBAAuB,CAAC;GAC7B,qBAAqB,KAAK,kBAAkB,CAAC;EAC/C;EACA,KAAK,qBAAqB,KAAK;GAAC;GAAW;GAAe;EAAQ,CAAC;CACrE;;;;;;;;;;CAWA,oBAAkC;EAChC,MAAM,UAAU,KAAK;EACrB,KAAK,uBAAuB;EAC5B,IAAI,CAAC,SAAS;EAEd,KAAK,MAAM,CAAC,WAAW,MAAM,SAAS,SACpC,KAAK,KAAK,gBAAgB,WAAW,MAAM,IAAI;CAEnD;AACF;;;;;AAMA,MAAa,iBAAiB,IAAI,uBAAuB"}

package/dist/config.d.cts

@@ -1,6 +1,3 @@
-/**
- * Global configuration for @blac/core
- */
 export type EqualityFn = <S>(prev: S, next: S) => boolean;
 export interface BlacConfig {
     /**
@@ -8,10 +5,6 @@ export interface BlacConfig {
      * `prev` and `next` are structurally equal. Default: `shallowEqualState`.
      *
      * Return `true` to skip the emit (states considered equal).
-     *
-     * Applies to `emit`/`update` only — `patch` does not consult this fn; it
-     * relies on its own per-key `Object.is` pre-check plus structural no-op
-     * detection to skip redundant notifications.
      */
     equality: EqualityFn;
     /**
@@ -45,6 +38,13 @@ export interface BlacConfig {
      * `Infinity` (or any non-positive value) to disable.
      */
     maxEmitsPerSecond: number;
+    /**
+     * How long an instance created speculatively during a render stays alive
+     * without an owner before it is disposed. Covers renders that never commit
+     * (SSR, discarded or suspended renders) while giving a time-sliced render
+     * time to commit. Default: `5000`.
+     */
+    unownedSweepDelayMs: number;
 }
 /**
  * Default equality: shallow per-key `Object.is` comparison.
@@ -53,7 +53,7 @@ export interface BlacConfig {
  */
 export declare const shallowEqualState: EqualityFn;
 /**
- * Configure global defaults for @blac/core.
+ * Configure global defaults for `@blac/core`.
  *
  * @example
  * ```ts

package/dist/config.d.ts

@@ -1,6 +1,3 @@
-/**
- * Global configuration for @blac/core
- */
 export type EqualityFn = <S>(prev: S, next: S) => boolean;
 export interface BlacConfig {
     /**
@@ -8,10 +5,6 @@ export interface BlacConfig {
      * `prev` and `next` are structurally equal. Default: `shallowEqualState`.
      *
      * Return `true` to skip the emit (states considered equal).
-     *
-     * Applies to `emit`/`update` only — `patch` does not consult this fn; it
-     * relies on its own per-key `Object.is` pre-check plus structural no-op
-     * detection to skip redundant notifications.
      */
     equality: EqualityFn;
     /**
@@ -45,6 +38,13 @@ export interface BlacConfig {
      * `Infinity` (or any non-positive value) to disable.
      */
     maxEmitsPerSecond: number;
+    /**
+     * How long an instance created speculatively during a render stays alive
+     * without an owner before it is disposed. Covers renders that never commit
+     * (SSR, discarded or suspended renders) while giving a time-sliced render
+     * time to commit. Default: `5000`.
+     */
+    unownedSweepDelayMs: number;
 }
 /**
  * Default equality: shallow per-key `Object.is` comparison.
@@ -53,7 +53,7 @@ export interface BlacConfig {
  */
 export declare const shallowEqualState: EqualityFn;
 /**
- * Configure global defaults for @blac/core.
+ * Configure global defaults for `@blac/core`.
  *
  * @example
  * ```ts

package/dist/constants.d.cts

@@ -1,29 +1,10 @@
-/**
- * Default configuration constants for BlaC
- *
- * Centralized location for all magic numbers and default values.
- */
-/**
- * Default configuration constants for BlaC
- */
-export declare const BLAC_DEFAULTS: {
-    /**
-     * Default instance key for shared instances
-     */
-    readonly DEFAULT_INSTANCE_KEY: "default";
-};
-/**
- * Static property names for StateContainer classes
- * Used for feature flags and configuration on bloc classes
- */
+/** Static property names used for feature flags and configuration on bloc classes. */
 export declare const BLAC_STATIC_PROPS: {
-    /**
-     * Mark a bloc to never be auto-disposed (kept alive permanently)
-     */
+    /** Mark a bloc to never be auto-disposed (kept alive permanently). */
     readonly KEEP_ALIVE: "keepAlive";
-    /**
-     * Exclude a bloc from DevTools reporting (prevents infinite loops)
-     */
+    /** Give each React `useBloc` mount its own private instance. */
+    readonly ISOLATED: "isolated";
+    /** Exclude a bloc from DevTools reporting (prevents infinite loops). */
     readonly EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools";
     /**
      * Per-class equality function used to short-circuit `emit`/`patch` when the
@@ -38,10 +19,21 @@ export declare const BLAC_STATIC_PROPS: {
      * non-identity fields (e.g., `readonly` flags) while still keying by id.
      */
     readonly KEY: "key";
-    /** Mark a bloc as always per-mount: `static isolated = true`. */
-    readonly ISOLATED: "isolated";
+    /**
+     * Explicit, minification-safe identity for a bloc class: `static blacName = '...'`.
+     * When unset, identity falls back to `constructor.name`.
+     */
+    readonly BLAC_NAME: "blacName";
 };
+export declare const BLAC_ERROR_PREFIX: "[BlaC]";
+export declare function readNodeEnv(): string | undefined;
 /**
- * Standard error message prefix
+ * True only when `process.env.NODE_ENV` is defined and not `'production'`.
+ *
+ * Dev-only checks (emit-rate breaker, deps collision scan, args-mismatch key)
+ * cost real work per emit/acquire, so an environment that says nothing about
+ * its mode — plain ESM in the browser, Deno, a bundle without a `process`
+ * shim — is treated as production. Bundlers that define `process.env.NODE_ENV`
+ * still constant-fold the read.
  */
-export declare const BLAC_ERROR_PREFIX: "[BlaC]";
+export declare const IS_DEV: boolean;

package/dist/constants.d.ts

@@ -1,29 +1,10 @@
-/**
- * Default configuration constants for BlaC
- *
- * Centralized location for all magic numbers and default values.
- */
-/**
- * Default configuration constants for BlaC
- */
-export declare const BLAC_DEFAULTS: {
-    /**
-     * Default instance key for shared instances
-     */
-    readonly DEFAULT_INSTANCE_KEY: "default";
-};
-/**
- * Static property names for StateContainer classes
- * Used for feature flags and configuration on bloc classes
- */
+/** Static property names used for feature flags and configuration on bloc classes. */
 export declare const BLAC_STATIC_PROPS: {
-    /**
-     * Mark a bloc to never be auto-disposed (kept alive permanently)
-     */
+    /** Mark a bloc to never be auto-disposed (kept alive permanently). */
     readonly KEEP_ALIVE: "keepAlive";
-    /**
-     * Exclude a bloc from DevTools reporting (prevents infinite loops)
-     */
+    /** Give each React `useBloc` mount its own private instance. */
+    readonly ISOLATED: "isolated";
+    /** Exclude a bloc from DevTools reporting (prevents infinite loops). */
     readonly EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools";
     /**
      * Per-class equality function used to short-circuit `emit`/`patch` when the
@@ -38,10 +19,21 @@ export declare const BLAC_STATIC_PROPS: {
      * non-identity fields (e.g., `readonly` flags) while still keying by id.
      */
     readonly KEY: "key";
-    /** Mark a bloc as always per-mount: `static isolated = true`. */
-    readonly ISOLATED: "isolated";
+    /**
+     * Explicit, minification-safe identity for a bloc class: `static blacName = '...'`.
+     * When unset, identity falls back to `constructor.name`.
+     */
+    readonly BLAC_NAME: "blacName";
 };
+export declare const BLAC_ERROR_PREFIX: "[BlaC]";
+export declare function readNodeEnv(): string | undefined;
 /**
- * Standard error message prefix
+ * True only when `process.env.NODE_ENV` is defined and not `'production'`.
+ *
+ * Dev-only checks (emit-rate breaker, deps collision scan, args-mismatch key)
+ * cost real work per emit/acquire, so an environment that says nothing about
+ * its mode — plain ESM in the browser, Deno, a bundle without a `process`
+ * shim — is treated as production. Bundlers that define `process.env.NODE_ENV`
+ * still constant-fold the read.
  */
-export declare const BLAC_ERROR_PREFIX: "[BlaC]";
+export declare const IS_DEV: boolean;

package/dist/core/Cubit.d.ts

@@ -1,16 +1,20 @@
 import { StateContainer } from './StateContainer';
+import type { DeepPartial } from '@dirtytalk/structural';
 /**
- * `Cubit<S>` is a `StateContainer<S>` with `emit` / `patch` exposed as
- * public mutation surface. Today it adds nothing structurally beyond
- * `StateContainer` — both are inherited from the underlying
- * `StructuralContainer<S>`. Kept as a real class (not a type alias) because
- * downstream code does `instance instanceof Cubit` checks.
+ * `Cubit<S>` is a `StateContainer<S>` that exposes mutation publicly.
  *
- * The class body is intentionally empty: a no-op `emit` override would
- * still go through `applyState`, and `patch` is inherited from
- * `StructuralContainer` (path-diffed, microtask-flushed). A caller that
- * wants "skip if no real change" patch semantics can wrap `patch`
- * themselves or call `emit` after a manual equality check.
+ * That is the whole difference, and it is a real one: on `StateContainer`
+ * `emit` / `patch` / `update` are `protected`, so a container mutates itself
+ * from its own methods and callers go through the API it chooses to publish.
+ * `Cubit` re-declares the three as `public` for the cases where a caller
+ * legitimately drives state from outside — test helpers, devtools
+ * time-travel, benchmarks.
+ *
+ * Reach for `StateContainer` when business logic should live in the class,
+ * and `Cubit` when the caller owns the transitions.
  */
 export declare abstract class Cubit<S extends object = any, Args = void, Deps extends object = Record<string, never>> extends StateContainer<S, Args, Deps> {
+    emit(next: S): void;
+    patch(partial: DeepPartial<S>): void;
+    update(fn: (state: S) => S): void;
 }

package/dist/core/StateContainer.d.ts

@@ -1,14 +1,14 @@
 import { StructuralContainer, type DeepPartial, type StructuralContainerOptions } from '@dirtytalk/structural';
-import { type EventToken } from '../events';
+import type { StateContainerRegistry } from './StateContainerRegistry';
 import type { ExtractArgs, ExtractState, StateContainerConstructor } from '../types/utilities';
-import { APPLY_DEPS, INIT_CONFIG, ON_DISPOSE, REMOVE_DEPS_OWNER } from './symbols';
-import { type BlacMeta } from './meta';
+import { APPLY_DEPS, INIT_CONFIG, ON_ACTIVATED, ON_DISPOSE, REMOVE_DEPS_OWNER, SET_ACTIVE, WITH_TRACKED_STATE } from './symbols';
+import { BlacMeta } from './meta';
 /**
  * Brand symbol carried (non-enumerable) on every handle returned by
  * `depend()`. Framework adapters (`@blac/react`) use this to detect handles
  * inside a tracked-proxy and swap in a session-bound wrapper.
  *
- * @internal — exported for `@blac/react`; not part of the public API.
+ * @internal — exported from `@blac/core/internal` for `@blac/react`.
  */
 export declare const DEP_BRAND: unique symbol;
 /**
@@ -45,6 +45,13 @@ export interface StateContainerConfig {
     instanceId?: string;
     /** Args passed at acquire time; forwarded to init(). */
     args?: unknown;
+    /**
+     * The registry that created this instance. Lifecycle events, deps and
+     * `depend()` route here instead of the module-global, which is what makes a
+     * scoped registry isolating.
+     * @internal
+     */
+    registry?: StateContainerRegistry;
 }
 export type HydrationStatus = 'idle' | 'hydrating' | 'hydrated' | 'error';
 export type SystemEvent = 'stateChanged' | 'dispose' | 'hydrationChanged';
@@ -62,26 +69,15 @@ export interface SystemEventPayloads<S> {
     };
 }
 type SystemEventHandler<S, E extends SystemEvent> = (payload: SystemEventPayloads<S>[E]) => void;
+/** @internal */
+export declare function getStateChangeCount(): number;
 /**
- * BlaC's lifecycle/identity/dependency layer on top of `StructuralContainer`.
- *
- * StructuralContainer provides:
- *   - `state` getter
- *   - `emit` / `patch` / `update` (path-tracked, microtask-flushed)
- *   - `channel` (the underlying `DirtyChannel`)
- *   - `registerConsumerPaths` / `unregisterConsumer` (for fine-grained consumers)
- *   - per-class `PathInterner`
- *
- * StateContainer layers on:
- *   - identity / lifecycle / hydration (exposed via `$blac: BlacMeta`)
- *   - cross-bloc deps (`depend()`, `$blac.dependencies`)
- *   - per-consumer deps slices (`APPLY_DEPS` / `REMOVE_DEPS_OWNER` / `onDepsChanged`)
- *   - registry integration (config-driven equality, emit-rate circuit breaker)
- *
- * Subscribers can attach via:
- *   - `onSystemEvent('stateChanged' | 'dispose' | 'hydrationChanged', cb)` —
- *     coarse lifecycle events.
- *   - `this.channel.subscribe(interest, cb)` — path-scoped.
+ * BlaC's lifecycle/identity/dependency layer on top of `StructuralContainer`
+ * (which provides `state`, `emit`/`patch`/`update`, and `channel`).
+ * StateContainer adds identity/lifecycle/hydration (`$blac: BlacMeta`),
+ * cross-bloc deps (`depend()`), per-consumer deps slices, and registry
+ * integration. Subscribe via `onSystemEvent(...)` for coarse lifecycle
+ * events or `this.channel.subscribe(...)` for path-scoped ones.
  */
 export declare abstract class StateContainer<S extends object = any, Args = void, Deps extends object = Record<string, never>> extends StructuralContainer<S> {
     static __excludeFromDevTools: boolean;
@@ -111,6 +107,25 @@ export declare abstract class StateContainer<S extends object = any, Args = void
      * filtering the global registry `'disposed'` event.
      */
     [ON_DISPOSE](handler: () => void): () => void;
+    /**
+     * @internal Run `handler` on every activation, and now if already active.
+     * Backs `onActivated()`.
+     */
+    [ON_ACTIVATED](handler: (signal: AbortSignal) => void): () => void;
+    /**
+     * @internal Drive the 0↔1 ownership transition. Idempotent: repeated calls
+     * with the same value are no-ops, so the registry can call it from every
+     * acquire/release without tracking edges itself.
+     *
+     * Returns which real transition (if any) just happened, so the registry can
+     * emit the matching `activated`/`deactivated` plugin event without exposing
+     * `_activation` itself — `'none'` for an idempotent no-op call.
+     */
+    [SET_ACTIVE](active: boolean): {
+        kind: 'activated';
+        signal: AbortSignal;
+    } | 'deactivated' | 'none';
+    private _abortActivation;
     private reconcileDeps;
     protected onDepsChanged(_next: Readonly<Deps>, _prev: Readonly<Deps>): void;
     private _disposed;
@@ -123,28 +138,47 @@ export declare abstract class StateContainer<S extends object = any, Args = void
     private _hydrationPromiseSettled;
     private _config;
     private _initCalled;
+    private _activation;
+    private _activationHandlers;
     private _emitWindowStart;
     private _emitCount;
     private _emitRateWarned;
-    private readonly _systemEventHandlers;
+    private _systemEventHandlers;
     private _dependencies;
-    private _depEdges;
     private _pendingChange;
     private _bridgeUnsub;
     private _registry;
     private _equalityFn;
     private _name;
     private _debug;
-    private _instanceId;
+    private _instanceId?;
     private _createdAt;
     /**
      * Reserved meta namespace: identity (`name`/`id`/`debug`/`createdAt`),
      * lifecycle (`disposed`/`dependencies`), and the `hydration` sub-surface.
      * Own, frozen, branded data property — `buildTrackedProxy` only intercepts
-     * prototype getters, so this own property and its closure-based getters are
-     * proxy-safe. See {@link createMeta}.
+     * prototype getters of the container, so this own property is proxy-safe.
+     * Its members are prototype accessors over the container (non-enumerable).
      */
     readonly $blac: BlacMeta<S>;
+    /**
+     * Both set only for the duration of a `[WITH_TRACKED_STATE]` call. TS-private
+     * so they stay out of the public surface.
+     */
+    private _stateOverride;
+    private _depHandleHook;
+    get state(): S;
+    /**
+     * @internal Run `fn` (with `this` = this instance, so a prototype getter can
+     * be passed directly) while `state` reports `tracked` and dep handles read
+     * off `this` route through `onDepHandle`. Restored in `finally`, and
+     * nestable — getters reading other getters stay in tracked context.
+     *
+     * The dep hook lives here rather than in the adapter's proxy because getters
+     * now run with `this` = the real instance (so ES `#private` works), which
+     * means a `this.someDep` read never passes through the proxy's trap.
+     */
+    [WITH_TRACKED_STATE]<R>(tracked: S, fn: () => R, onDepHandle?: (handle: object) => unknown): R;
     get args(): Args | undefined;
     /**
      * Declare a cross-bloc dependency. Returns a branded handle with two
@@ -164,41 +198,43 @@ export declare abstract class StateContainer<S extends object = any, Args = void
      */
     protected depend<T extends StateContainerConstructor>(Type: T, defaultArgs?: ExtractArgs<T>): DepHandle<T>;
     constructor(initialState: S, options?: StructuralContainerOptions);
-    /**
-     * @internal Subscribe the channel bridge that turns flushes into
-     * 'stateChanged' system events. Interest is ALL_PATHS so we wake on every
-     * flush. Coalesced via `_pendingChange`: if no emit happened (e.g. a no-op
-     * patch), the bridge sees null and skips. Lazy: only subscribed while at
-     * least one 'stateChanged' handler exists.
-     */
-    private _subscribeBridge;
-    private _hasStateChangedHandlers;
     /**
      * Called once after construction with the args passed at acquire time, before the first
      * state snapshot is read by any consumer. Override to seed args-derived state (via
      * this.emit(...)) or kick off loads.
      */
     protected init(_args: Args): void;
+    /**
+     * Called when this instance goes from unowned to owned (first ref or first
+     * `depend()` dependent). Override to start work that should only run while
+     * something is actually using the instance — fetches, timers, listeners.
+     *
+     * `signal` aborts on the matching `onDeactivate` and on dispose, so
+     * async work started here can be cancelled without extra bookkeeping.
+     *
+     * Runs before the first `useBlocDeps` slice is applied, so `this.deps` is
+     * empty on first activation — use `onDepsChanged` for deps-driven work.
+     */
+    protected onActivate(_signal: AbortSignal): void;
+    /**
+     * Called when this instance goes from owned back to unowned while surviving
+     * in the registry (i.e. `keepAlive`). A disposed instance does NOT get this
+     * callback — `dispose()` is the teardown path for that case.
+     */
+    protected onDeactivate(): void;
     /**
      * @internal Framework-only configuration entry point (registry + testing
-     * helpers). Writes the `_`-private identity fields directly, resolves
-     * per-class equality, emits the registry `created` event, and runs `init()`
-     * once. See {@link INIT_CONFIG}.
+     * helpers). Writes the `_`-private identity fields directly, emits the
+     * registry `created` event, and runs `init()` once. See `INIT_CONFIG`.
      */
     [INIT_CONFIG](config: StateContainerConfig): void;
     dispose(): void;
-    emit(next: S): void;
-    /**
-     * Override of `StructuralContainer.patch` that routes through the
-     * StateContainer concerns: disposed guard, dev-only emit-rate check,
-     * `_changedWhileHydrating` flag, pending-change capture (so `stateChanged`
-     * system events see the merged prev/next), and the registry-level
-     * `stateChanged` notification. We still call
-     * `super.patch` so path-marking semantics (the whole point of patch) are
-     * preserved.
-     */
-    patch(partial: DeepPartial<S>): void;
+    protected emit(next: S): void;
+    /** @see emit for the StateContainer concerns layered onto `super.patch`. */
+    protected patch(partial: DeepPartial<S>): void;
     private applyState;
+    /** Bookkeeping shared by every real state change (`emit`, `patch`, hydration). */
+    private _recordChange;
     /**
      * Called by the channel-bridge subscriber on each flush. Drains the
      * pending change (if any) into the 'stateChanged' system event.
@@ -206,6 +242,7 @@ export declare abstract class StateContainer<S extends object = any, Args = void
      */
     private _drainPending;
     private _beginHydration;
+    private _warnDisposedMutation;
     private _applyHydratedState;
     private _finishHydration;
     private _failHydration;
@@ -214,17 +251,7 @@ export declare abstract class StateContainer<S extends object = any, Args = void
     private ensureHydrationPromise;
     private resolveHydration;
     private rejectHydration;
-    protected onSystemEvent: <E extends SystemEvent>(event: E, handler: SystemEventHandler<S, E>) => (() => void);
-    /**
-     * Subscribe to a cross-cutting application event for this container's
-     * lifetime. The subscription is torn down automatically on `dispose()` — no
-     * manual `off` in consumer code (requirements AC3).
-     *
-     * Uses THIS container's registry (`_registry`, captured at construction), not
-     * the ambient one, so a container always listens on the bus of the registry it
-     * belongs to.
-     */
-    protected on: <P>(token: EventToken<P>, handler: (payload: P) => void) => (() => void);
+    protected onSystemEvent<E extends SystemEvent>(event: E, handler: SystemEventHandler<S, E>): () => void;
     private emitSystemEvent;
     /**
      * Dev-only soft circuit breaker. Counts real state changes in a rolling 1s