@blac/core 2.0.22 → 2.1.1

package/dist/core/StateContainerRegistry.d.ts

@@ -1,23 +1,22 @@
 import type { HydrationStatus, StateContainer } from './StateContainer';
 import { InstanceReadonlyState, StateContainerConstructor } from '../types/utilities';
+import { INSERT_INSTANCE } from './symbols';
 /**
- * Entry in the instance registry, tracking the instance and its named references
+ * Entry in the instance registry.
  * @typeParam T - Instance type
  * @internal
  */
 export interface InstanceEntry<T = any> {
-    /** The state container instance */
     instance: T;
-    /** The key this entry is stored under in its constructor's instances Map. */
     key: string;
-    /** Map of active reference IDs to their acquire count (supports paired acquire/release) */
+    /** refId to acquire count. */
     refs: Map<string, number>;
-    /** The args used when this entry was first created; used for dev-warn on arg mismatch. */
+    /** Args from creation, for the dev arg-mismatch warning. */
     args?: unknown;
-    /** Memoized structuralKey(args) for the dev arg-mismatch warning. */
     argsKey?: string;
-    /** `depend()`-owners currently holding this instance (see `acquire`'s `dependent` option). */
+    /** `depend()`-owners holding this instance. */
     dependents?: Set<StateContainer<any, any, any>>;
+    sweepTimer?: ReturnType<typeof setTimeout>;
 }
 /**
  * Lifecycle events emitted by the registry
@@ -31,8 +30,8 @@ export type LifecycleEvent = 'created' | 'stateChanged' | 'disposed' | 'refAcqui
  */
 export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ? (container: StateContainer<any, any, any>) => void : E extends 'stateChanged' ? (container: StateContainer<any, any, any>, previousState: Readonly<Record<string, unknown>>, currentState: Readonly<Record<string, unknown>>) => void : E extends 'disposed' ? (container: StateContainer<any, any, any>) => void : E extends 'refAcquired' ? (container: StateContainer<any, any, any>, refId: string) => void : E extends 'refReleased' ? (container: StateContainer<any, any, any>, refId: string) => void : E extends 'depsChanged' ? (container: StateContainer<any, any, any>, previousDeps: Readonly<Record<string, unknown>>, currentDeps: Readonly<Record<string, unknown>>) => void : E extends 'hydrationChanged' ? (container: StateContainer<any, any, any>, status: HydrationStatus, previousStatus: HydrationStatus) => void : E extends 'activated' ? (container: StateContainer<any, any, any>, signal: AbortSignal) => void : E extends 'deactivated' ? (container: StateContainer<any, any, any>) => void : never;
 /**
- * Central registry for managing StateContainer instances.
- * Handles instance lifecycle, named ref tracking, and lifecycle event emission.
+ * Owns StateContainer instances: creation, ref tracking, disposal and
+ * lifecycle events.
  *
  * @example
  * ```ts
@@ -44,89 +43,46 @@ export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ?
  * });
  * ```
  *
- * `stateChanged` fires once per emit (microtask-deferred but uncoalesced), so
- * listeners see every intermediate transition. Plugins' `onStateChange` fires
- * once per channel flush with coalesced `prev`/`next` and a `PathSet`. Pick
- * the transition log for devtools/time-travel, the plugin hook for
- * change-driven work.
+ * `stateChanged` fires once per emit (microtask-deferred, not coalesced).
+ * Plugins' `onStateChange` fires once per channel flush with coalesced
+ * `prev`/`next` and a `PathSet`.
  */
 export declare class StateContainerRegistry {
     private readonly instancesByConstructor;
     private readonly types;
     /**
-     * `depend()`-owner to the (Type, key) entries it has resolved. Keyed per
-     * resolved key because one handle resolves a different key per `args`.
-     * Weak so a bare `new`'d owner that is never disposed cannot pin the map.
+     * `depend()`-owner to the (Type, key) entries it resolved, per key because
+     * one handle resolves a different key per `args`.
      */
     private readonly _dependentEdges;
+    private readonly _entryByInstance;
     /**
-     * Reverse lookup from `$blac.id` to its entry, for `PluginContext.getRefIds`
-     * and the O(1) prune on dispose. Ids are `<name>:<key>`, so an entry is
-     * matched by instance identity as well.
+     * Only for `PluginContext.getRefIds`: ids can collide across same-named
+     * classes, so nothing else may rely on it.
      */
     private readonly _entryById;
     private readonly listeners;
-    /**
-     * Derived from the listener Set, never a parallel counter: `on()` with the
-     * same function twice adds once, so a counter cannot stay in step.
-     */
     get hasStateChangedListeners(): boolean;
     private _pendingStateChanges;
     private _autoRefIdCounter;
     constructor();
-    /**
-     * Registry-internal reaction to any instance's `disposed` lifecycle event.
-     * If the disposing container is itself tracked in this registry (i.e. it
-     * was `acquire()`/`ensure()`'d, not a bare `new`), prune its Map entry and
-     * release its dependent edges on whatever it `depend()`'d on.
-     */
+    /** Prune a tracked instance's entry and release its `depend()` edges. */
     private _handleDisposed;
-    /**
-     * An entry may be disposed only when nothing owns it: no public refs, no
-     * `depend()` dependents, and not keepAlive. Every dispose decision goes
-     * through here so `release()` and `_releaseDependent` cannot disagree.
-     */
+    /** The single dispose decision: no refs, no dependents, not keepAlive. */
     private _isUnowned;
-    /**
-     * Pure ownership: refs plus `depend()` dependents, with no keepAlive term.
-     * `_isUnowned` is "may be disposed"; this is "nothing is using it", which is
-     * what the activation lifecycle keys off — a keepAlive instance still
-     * deactivates when its last owner goes.
-     */
+    /** Ignores keepAlive: a keepAlive instance still deactivates. */
     private _hasNoOwners;
     /**
-     * Single funnel for the 0↔1 ownership transition. `SET_ACTIVE` is idempotent,
-     * so every acquire/release path can call this unconditionally rather than
-     * each computing the edge itself. Emits `activated`/`deactivated` for
-     * plugins to observe the same transition `onActivate`/`onDeactivate` expose
-     * to bloc authors — after `SET_ACTIVE` has already run the instance's own
-     * hook, so plugins always see a container that has finished reacting.
+     * Idempotent, so every acquire/release path calls it. The events fire after
+     * the instance's own `onActivate`/`onDeactivate`.
      */
     private _syncActivation;
-    /**
-     * Record that `dependent` resolved `Type` at `key`, so the edge can be
-     * released on the owner's disposal. Keyed per resolved key, not per type:
-     * one `depend()` handle resolves a distinct key for every `args` it is
-     * called with, and all of them must be swept.
-     */
     private _recordDependentEdge;
-    /**
-     * Remove the Map entry for `container`, if this registry is tracking it.
-     * @returns true if an entry was found and removed
-     */
+    /** @returns true if this registry tracked `container`. */
     private _pruneEntry;
-    /**
-     * Drop `dependent`'s edge on the `Type`/`key` entry (a `depend()`-resolved
-     * instance). When that leaves the entry with no dependents AND no public
-     * refs AND it isn't keepAlive, dispose it — this recurses into the same
-     * `disposed` listener, so dep-of-dep chains unwind naturally.
-     */
+    private _indexEntry;
+    /** Disposing here recurses through `disposed`, unwinding dep chains. */
     private _releaseDependent;
-    /**
-     * Register a type for lifecycle event tracking
-     * @param constructor - The StateContainer class constructor
-     */
-    registerType<T extends StateContainerConstructor>(constructor: T): void;
     /**
      * Register a StateContainer class with configuration
      * @param constructor - The StateContainer class constructor
@@ -139,60 +95,35 @@ export declare class StateContainerRegistry {
      */
     getInstancesMap<T extends StateContainerConstructor>(Type: T): ReadonlyMap<string, InstanceEntry>;
     /**
-     * Directly insert an instance entry into the registry without going through
-     * acquire/release. Creates the internal WeakMap bucket for the constructor if
-     * it does not exist yet. Replaces any existing entry for the same key.
-     *
-     * The provided instance is NOT configured or disposed here — callers are
-     * responsible for any initConfig / dispose calls. Intended for testing
-     * helpers that create stubs outside the normal acquisition path.
+     * Insert an entry, replacing the one at `instanceKey`. The instance is not
+     * configured here.
      *
      * @internal Used by testing helpers only.
      */
-    insertInstance<T extends StateContainerConstructor>(Type: T, instanceKey: string, instance: InstanceType<T>, refs?: Map<string, number>): void;
+    [INSERT_INSTANCE]<T extends StateContainerConstructor>(Type: T, instanceKey: string, instance: InstanceType<T>, refs?: Map<string, number>): void;
     /**
-     * Resolve the storage key for an instance. This is the single source of truth
-     * for keying — `acquire` and `release` MUST agree, otherwise a ref taken under
-     * an args-derived key is never dropped (instance leaks).
-     *
-     * Resolution order (explicit beats derived):
-     * explicit key \> `static key(args)` \> structural hash of args \> default sentinel.
+     * The single source of keying, so `acquire` and `release` agree: explicit
+     * key \> `static key(args)` \> structural hash of args \> default key.
      *
      * @param Type - The StateContainer class constructor
      * @param instanceKey - Explicit key, or undefined to derive from args
      * @param args - Construction args used for structural/`static key` derivation
      */
     resolveKey<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey: string | undefined, args: unknown): string;
-    /**
-     * Circuit breaker for runaway instance creation. Throws when a single
-     * constructor would exceed `maxInstancesPerType` live instances — almost
-     * always an unstable instance key (e.g. a new object/array passed as `args`
-     * every render, or a missing `static key`) leaking an instance per render.
-     */
     private assertInstanceLimit;
-    /**
-     * Circuit breaker for runaway reference growth. Throws when one instance
-     * accumulates more than `maxRefsPerInstance` distinct live refs — almost
-     * always consumer cleanup (e.g. `useBloc`'s unmount `release`) never firing.
-     */
     private assertRefLimit;
     /**
-     * Acquire an instance with ref tracking (ownership semantics).
-     * Creates a new instance if one doesn't exist, or returns existing and adds a ref.
-     * You must call `release()` with the same refId when done.
+     * Get or create an instance and add a ref; `release()` it with the same
+     * refId.
      *
      * @internal Internal key tier. Public callers use the args-based `acquire`
      *   wrapper; `useBloc` and `watch` address a pre-resolved key here.
      * @param Type - The StateContainer class constructor
      * @param instanceKey - Pre-resolved instance key (defaults to 'default')
-     * @param options - Acquisition options: `canCreate` (create when absent,
-     *   default true), `countRef` (add a reference, default true), `refId`
-     *   (named reference for debugging, auto-generated when omitted),
-     *   `dependent` — the `depend()`-owner resolving this instance, recorded so
-     *   its dependent edge is released on the owner's disposal — and
-     *   `sweepIfUnowned`, for callers that create speculatively and claim
-     *   ownership later (see {@link _scheduleSweep}).
-     * @returns The state container instance
+     * @param options - `canCreate` and `countRef` default to true; `refId` is
+     *   auto-generated when omitted; `dependent` is the `depend()`-owner, whose
+     *   edge is released on its disposal; `sweepIfUnowned` is for speculative
+     *   creates (see `_scheduleSweep`).
      */
     acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
         canCreate?: boolean;
@@ -203,19 +134,14 @@ export declare class StateContainerRegistry {
         sweepIfUnowned?: boolean;
     }): InstanceType<T>;
     /**
-     * Speculative creates (`useBloc`'s render-time create) leak forever when the
-     * render is discarded or never commits — SSR has no commit at all, so nothing
-     * ever claims ownership. Sweep at the end of the microtask unless the entry
-     * gained an owner or is keepAlive.
-     *
-     * Opt-in, not automatic: a bare `ensure()` hands the instance to a caller
-     * that legitimately holds it without a ref, and sweeping those would make
-     * `ensure` unusable across an `await`.
+     * Dispose a speculative create (a render that never commits, SSR) that is
+     * still unowned after `unownedSweepDelayMs`. The delay must outlast a
+     * time-sliced render; a repeat speculative acquire restarts it. Opt-in, so a
+     * bare `ensure()` stays usable across an `await`.
      */
     private _scheduleSweep;
     /**
-     * Borrow an existing instance without adding a ref (borrowing semantics).
-     * Tracks cross-bloc dependency for reactive updates.
+     * Get an existing instance without adding a ref.
      *
      * @internal Internal key tier; public callers use the args-based `borrow`.
      * @param Type - The StateContainer class constructor
@@ -225,8 +151,7 @@ export declare class StateContainerRegistry {
      */
     borrow<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
-     * Safely borrow an existing instance (borrowing semantics with error handling).
-     * Returns discriminated union for type-safe conditional access.
+     * Like `borrow`, but returns the error instead of throwing.
      *
      * @internal Internal key tier; public callers use the args-based `borrowSafe`.
      * @param Type - The StateContainer class constructor
@@ -241,12 +166,7 @@ export declare class StateContainerRegistry {
         instance: InstanceType<T>;
     };
     /**
-     * Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
-     * Gets existing instance OR creates it if it doesn't exist, without adding a ref.
-     * Tracks cross-bloc dependency for reactive updates.
-     *
-     * Use this in bloc-to-bloc communication when you need to ensure an instance exists
-     * but don't want to claim ownership (no ref added).
+     * Get or create an instance without adding a ref.
      *
      * @internal Internal key tier; public callers use the args-based `ensure`.
      * @param Type - The StateContainer class constructor
@@ -257,9 +177,8 @@ export declare class StateContainerRegistry {
      */
     ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, args?: unknown): InstanceType<T>;
     /**
-     * Release a reference to an instance.
-     * Removes the ref and disposes when refs is empty (unless keepAlive).
-     * Releasing an already-removed refId is a no-op (idempotent).
+     * Remove a ref and dispose the instance once nothing owns it. Releasing a
+     * ref that isn't held is a no-op.
      *
      * @internal Internal key tier; public callers use the args-based `release`.
      * @param Type - The StateContainer class constructor
@@ -268,23 +187,11 @@ export declare class StateContainerRegistry {
      * @param refId - The specific ref to remove; removes one arbitrary ref if omitted
      */
     release<T extends StateContainerConstructor>(Type: T, instanceKey?: string, forceDispose?: boolean, refId?: string): void;
-    /**
-     * Get all instances of a specific type.
-     * @param Type - The StateContainer class constructor
-     * @returns Array of all instances
-     */
+    /** Live instances of `Type`. */
     getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
-    /**
-     * Safely iterate over all instances of a type.
-     * Skips disposed instances and catches callback errors.
-     * @param Type - The StateContainer class constructor
-     * @param callback - Function to call for each instance
-     */
+    /** Iterate live instances of `Type`; callback errors are logged. */
     forEach<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
-    /**
-     * Clear all instances of a specific type (disposes them).
-     * @param Type - The StateContainer class constructor
-     */
+    /** Dispose all instances of `Type`. */
     clear<T extends StateContainerConstructor>(Type: T): void;
     /**
      * Get reference count for an instance (number of active refs).
@@ -304,12 +211,7 @@ export declare class StateContainerRegistry {
      * @returns Array of ref ID strings (empty if instance doesn't exist)
      */
     getRefIds<T extends StateContainerConstructor>(Type: T, instanceKey?: string): string[];
-    /**
-     * Get all active reference IDs for an instance by its `$blac.id`, without
-     * needing the owning Type. Used by `PluginContext.getRefIds`.
-     * @param instanceId - The instance's `$blac.id`
-     * @returns Array of ref ID strings (empty if instance doesn't exist)
-     */
+    /** Ref ids by `$blac.id`, for `PluginContext.getRefIds`. */
     getRefIdsById(instanceId: string): string[];
     /**
      * Check if an instance exists.
@@ -317,34 +219,21 @@ export declare class StateContainerRegistry {
      * @internal Internal key tier; public callers use the args-based `hasInstance`.
      * @param Type - The StateContainer class constructor
      * @param instanceKey - Pre-resolved instance key (defaults to 'default')
-     * @returns true if instance exists
+     * @returns true if a live (not disposed) instance exists
      */
     hasInstance<T extends StateContainerConstructor>(Type: T, instanceKey?: string): boolean;
-    /**
-     * Clear all instances from all types (for testing)
-     *
-     * Iterates all registered types and clears their instances.
-     * Also clears type tracking to reset the registry state.
-     */
+    /** Dispose every instance and forget all types (for testing). */
     clearAll(): void;
-    /**
-     * Get registry statistics for debugging.
-     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
-     */
+    /** Instance counts, for debugging. */
     getStats(): {
         registeredTypes: number;
         totalInstances: number;
         typeBreakdown: Record<string, number>;
     };
-    /**
-     * Get all registered types (for plugin system).
-     * @returns Array of all registered StateContainer class constructors
-     */
+    /** All registered types (for plugins). */
     getTypes(): StateContainerConstructor[];
     /**
-     * Subscribe to lifecycle events
-     * @param event - The lifecycle event to listen for
-     * @param listener - The listener function to call when the event occurs
+     * Subscribe to a lifecycle event.
      * @returns Unsubscribe function
      */
     on<E extends LifecycleEvent>(event: E, listener: LifecycleListener<E>): () => void;
@@ -362,24 +251,18 @@ export declare class StateContainerRegistry {
     emit(event: 'activated', container: StateContainer<any, any, any>, signal: AbortSignal): void;
     emit(event: 'deactivated', container: StateContainer<any, any, any>): void;
     /**
-     * Schedule a deferred stateChanged notification via microtask.
-     * Skips entirely when no stateChanged listeners are registered.
+     * Queue a microtask-deferred `stateChanged`.
      * @internal - Called by StateContainer.applyState
      */
     notifyStateChanged(container: StateContainer<any, any, any>, previousState: any, newState: any): void;
     /**
-     * Deliver one event per emit, in order — deliberately NOT coalesced.
-     *
-     * This is a transition log: devtools, time-travel debugging and perf
-     * monitoring need every intermediate `prev`/`next`, which coalescing would
-     * destroy. The plugin `onStateChange` bridge is the coalesced, `PathSet`-
-     * carrying lane (see `PluginManager.setupLifecycleHooks`); the two differ on
-     * purpose, so a listener picks the lane that matches what it needs.
+     * One event per emit, deliberately not coalesced: devtools and time-travel
+     * need every intermediate transition. Plugins get the coalesced lane.
      */
     private flushStateChanged;
 }
 /**
- * Global default registry instance
+ * The global default registry.
  * @public
  */
 export declare const globalRegistry: StateContainerRegistry;

package/dist/core/symbols.d.ts

@@ -27,10 +27,8 @@ export declare const INIT_CONFIG: unique symbol;
 /**
  * @internal Run `fn` with `state` temporarily reporting a render's tracking
  * proxy, so getters record the paths they read. Called by `@blac/react`'s
- * `buildTrackedProxy` — not public API.
- *
- * Replaces the old `this`-Proxy receiver: getters now run with `this` bound to
- * the real instance, so ES `#private` works in user blocs.
+ * `buildTrackedProxy` — not public API. Getters run with `this` bound to the
+ * real instance, so ES `#private` works in user blocs.
  */
 export declare const WITH_TRACKED_STATE: unique symbol;
 /**
@@ -41,3 +39,8 @@ export declare const WITH_TRACKED_STATE: unique symbol;
  * Framework-only — `StateContainerRegistry` is the sole caller.
  */
 export declare const SET_ACTIVE: unique symbol;
+/**
+ * @internal Insert an instance entry directly, bypassing acquire/release.
+ * Called by the testing helpers — not public API.
+ */
+export declare const INSERT_INSTANCE: unique symbol;

package/dist/decorators/blac.d.ts

@@ -4,8 +4,11 @@ import type { EqualityFn } from '../config';
  * given at once.
  */
 export interface BlacOptions {
-    /** Mark bloc to never be auto-disposed when ref count reaches 0 */
-    keepAlive?: true;
+    /**
+     * Keep the bloc alive when its ref count reaches 0. `false` turns off a
+     * `keepAlive` inherited from a base class.
+     */
+    keepAlive?: boolean;
     /** Exclude bloc from DevTools tracking (prevents infinite loops) */
     excludeFromDevTools?: true;
     /**

package/dist/ensure-Bi_yXk6f.js

@@ -0,0 +1,46 @@
+import { i as getRegistry } from "./StateContainer-Bh2ipNYj.js";
+//#region src/registry/acquire.ts
+/**
+* Acquire an instance with ref tracking (ownership semantics). Instance
+* identity is derived purely from `args` (via the class's `static key(args)`,
+* a structural hash of `args`, or the default sentinel when there are none).
+*
+* @param BlocClass - The StateContainer class constructor
+* @param opts - `args` derives the instance key; `refId` names the reference
+*   for debugging and is auto-generated when omitted.
+*/
+function acquire(BlocClass, opts) {
+	const registry = getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.acquire(BlocClass, key, {
+		canCreate: true,
+		countRef: true,
+		refId: opts?.refId,
+		args: opts?.args
+	});
+}
+/**
+* Resolve the storage key an instance would be acquired under, given its
+* construction `args`. This is the canonical key-computation path. Callers that
+* both acquire and release against the `@internal` registry tier (e.g.
+* `@blac/react` `useBloc`) must use this once and pass the same resolved key to
+* both, so the ref is dropped under the key it was taken.
+*/
+function resolveInstanceKey(BlocClass, args) {
+	return getRegistry().resolveKey(BlocClass, void 0, args);
+}
+//#endregion
+//#region src/registry/ensure.ts
+/**
+* Ensure an instance exists without taking ownership (no ref added). Instance
+* identity is derived purely from `args`, matching `acquire`.
+*/
+function ensure(BlocClass, opts) {
+	const registry = getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.ensure(BlocClass, key, opts?.args);
+}
+//#endregion
+export { acquire as n, resolveInstanceKey as r, ensure as t };
+
+//# sourceMappingURL=ensure-Bi_yXk6f.js.map

package/dist/ensure-Bi_yXk6f.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-Bi_yXk6f.js","names":[],"sources":["../src/registry/acquire.ts","../src/registry/ensure.ts"],"sourcesContent":["import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Acquire an instance with ref tracking (ownership semantics). Instance\n * identity is derived purely from `args` (via the class's `static key(args)`,\n * a structural hash of `args`, or the default sentinel when there are none).\n *\n * @param BlocClass - The StateContainer class constructor\n * @param opts - `args` derives the instance key; `refId` names the reference\n *   for debugging and is auto-generated when omitted.\n */\nexport function acquire<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T>; refId?: string },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.acquire(BlocClass, key, {\n    canCreate: true,\n    countRef: true,\n    refId: opts?.refId,\n    args: opts?.args,\n  });\n}\n\n/**\n * Resolve the storage key an instance would be acquired under, given its\n * construction `args`. This is the canonical key-computation path. Callers that\n * both acquire and release against the `@internal` registry tier (e.g.\n * `@blac/react` `useBloc`) must use this once and pass the same resolved key to\n * both, so the ref is dropped under the key it was taken.\n */\nexport function resolveInstanceKey<T extends StateContainerConstructor>(\n  BlocClass: T,\n  args?: ExtractArgs<T>,\n): string {\n  return getRegistry().resolveKey(BlocClass, undefined, args);\n}\n","import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Ensure an instance exists without taking ownership (no ref added). Instance\n * identity is derived purely from `args`, matching `acquire`.\n */\nexport function ensure<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T> },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.ensure(BlocClass, key, opts?.args);\n}\n"],"mappings":";;;;;;;;;;;AAeA,SAAgB,QACd,WACA,MACiB;CACjB,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,QAAQ,WAAW,KAAK;EACtC,WAAW;EACX,UAAU;EACV,OAAO,MAAM;EACb,MAAM,MAAM;CACd,CAAC;AACH;;;;;;;;AASA,SAAgB,mBACd,WACA,MACQ;CACR,OAAO,YAAY,EAAE,WAAW,WAAW,KAAA,GAAW,IAAI;AAC5D;;;;;;;AC/BA,SAAgB,OACd,WACA,MACiB;CACjB,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,OAAO,WAAW,KAAK,MAAM,IAAI;AACnD"}

package/dist/ensure-Bx41d-il.cjs

@@ -0,0 +1,63 @@
+const require_StateContainer = require("./StateContainer-ClzwKnQZ.cjs");
+//#region src/registry/acquire.ts
+/**
+* Acquire an instance with ref tracking (ownership semantics). Instance
+* identity is derived purely from `args` (via the class's `static key(args)`,
+* a structural hash of `args`, or the default sentinel when there are none).
+*
+* @param BlocClass - The StateContainer class constructor
+* @param opts - `args` derives the instance key; `refId` names the reference
+*   for debugging and is auto-generated when omitted.
+*/
+function acquire(BlocClass, opts) {
+	const registry = require_StateContainer.getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.acquire(BlocClass, key, {
+		canCreate: true,
+		countRef: true,
+		refId: opts?.refId,
+		args: opts?.args
+	});
+}
+/**
+* Resolve the storage key an instance would be acquired under, given its
+* construction `args`. This is the canonical key-computation path. Callers that
+* both acquire and release against the `@internal` registry tier (e.g.
+* `@blac/react` `useBloc`) must use this once and pass the same resolved key to
+* both, so the ref is dropped under the key it was taken.
+*/
+function resolveInstanceKey(BlocClass, args) {
+	return require_StateContainer.getRegistry().resolveKey(BlocClass, void 0, args);
+}
+//#endregion
+//#region src/registry/ensure.ts
+/**
+* Ensure an instance exists without taking ownership (no ref added). Instance
+* identity is derived purely from `args`, matching `acquire`.
+*/
+function ensure(BlocClass, opts) {
+	const registry = require_StateContainer.getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.ensure(BlocClass, key, opts?.args);
+}
+//#endregion
+Object.defineProperty(exports, "acquire", {
+	enumerable: true,
+	get: function() {
+		return acquire;
+	}
+});
+Object.defineProperty(exports, "ensure", {
+	enumerable: true,
+	get: function() {
+		return ensure;
+	}
+});
+Object.defineProperty(exports, "resolveInstanceKey", {
+	enumerable: true,
+	get: function() {
+		return resolveInstanceKey;
+	}
+});
+
+//# sourceMappingURL=ensure-Bx41d-il.cjs.map

package/dist/ensure-Bx41d-il.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-Bx41d-il.cjs","names":["getRegistry","getRegistry"],"sources":["../src/registry/acquire.ts","../src/registry/ensure.ts"],"sourcesContent":["import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Acquire an instance with ref tracking (ownership semantics). Instance\n * identity is derived purely from `args` (via the class's `static key(args)`,\n * a structural hash of `args`, or the default sentinel when there are none).\n *\n * @param BlocClass - The StateContainer class constructor\n * @param opts - `args` derives the instance key; `refId` names the reference\n *   for debugging and is auto-generated when omitted.\n */\nexport function acquire<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T>; refId?: string },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.acquire(BlocClass, key, {\n    canCreate: true,\n    countRef: true,\n    refId: opts?.refId,\n    args: opts?.args,\n  });\n}\n\n/**\n * Resolve the storage key an instance would be acquired under, given its\n * construction `args`. This is the canonical key-computation path. Callers that\n * both acquire and release against the `@internal` registry tier (e.g.\n * `@blac/react` `useBloc`) must use this once and pass the same resolved key to\n * both, so the ref is dropped under the key it was taken.\n */\nexport function resolveInstanceKey<T extends StateContainerConstructor>(\n  BlocClass: T,\n  args?: ExtractArgs<T>,\n): string {\n  return getRegistry().resolveKey(BlocClass, undefined, args);\n}\n","import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Ensure an instance exists without taking ownership (no ref added). Instance\n * identity is derived purely from `args`, matching `acquire`.\n */\nexport function ensure<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T> },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.ensure(BlocClass, key, opts?.args);\n}\n"],"mappings":";;;;;;;;;;;AAeA,SAAgB,QACd,WACA,MACiB;CACjB,MAAM,WAAWA,uBAAAA,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,QAAQ,WAAW,KAAK;EACtC,WAAW;EACX,UAAU;EACV,OAAO,MAAM;EACb,MAAM,MAAM;CACd,CAAC;AACH;;;;;;;;AASA,SAAgB,mBACd,WACA,MACQ;CACR,OAAOA,uBAAAA,YAAY,EAAE,WAAW,WAAW,KAAA,GAAW,IAAI;AAC5D;;;;;;;AC/BA,SAAgB,OACd,WACA,MACiB;CACjB,MAAM,WAAWC,uBAAAA,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,OAAO,WAAW,KAAK,MAAM,IAAI;AACnD"}

package/dist/ensure-C7UQ_mKM.js

@@ -0,0 +1,46 @@
+import { i as getRegistry } from "./StateContainer-B_7UHc3I.js";
+//#region src/registry/acquire.ts
+/**
+* Acquire an instance with ref tracking (ownership semantics). Instance
+* identity is derived purely from `args` (via the class's `static key(args)`,
+* a structural hash of `args`, or the default sentinel when there are none).
+*
+* @param BlocClass - The StateContainer class constructor
+* @param opts - `args` derives the instance key; `refId` names the reference
+*   for debugging and is auto-generated when omitted.
+*/
+function acquire(BlocClass, opts) {
+	const registry = getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.acquire(BlocClass, key, {
+		canCreate: true,
+		countRef: true,
+		refId: opts?.refId,
+		args: opts?.args
+	});
+}
+/**
+* Resolve the storage key an instance would be acquired under, given its
+* construction `args`. This is the canonical key-computation path. Callers that
+* both acquire and release against the `@internal` registry tier (e.g.
+* `@blac/react` `useBloc`) must use this once and pass the same resolved key to
+* both, so the ref is dropped under the key it was taken.
+*/
+function resolveInstanceKey(BlocClass, args) {
+	return getRegistry().resolveKey(BlocClass, void 0, args);
+}
+//#endregion
+//#region src/registry/ensure.ts
+/**
+* Ensure an instance exists without taking ownership (no ref added). Instance
+* identity is derived purely from `args`, matching `acquire`.
+*/
+function ensure(BlocClass, opts) {
+	const registry = getRegistry();
+	const key = registry.resolveKey(BlocClass, void 0, opts?.args);
+	return registry.ensure(BlocClass, key, opts?.args);
+}
+//#endregion
+export { acquire as n, resolveInstanceKey as r, ensure as t };
+
+//# sourceMappingURL=ensure-C7UQ_mKM.js.map

package/dist/ensure-C7UQ_mKM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-C7UQ_mKM.js","names":[],"sources":["../src/registry/acquire.ts","../src/registry/ensure.ts"],"sourcesContent":["import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Acquire an instance with ref tracking (ownership semantics). Instance\n * identity is derived purely from `args` (via the class's `static key(args)`,\n * a structural hash of `args`, or the default sentinel when there are none).\n *\n * @param BlocClass - The StateContainer class constructor\n * @param opts - `args` derives the instance key; `refId` names the reference\n *   for debugging and is auto-generated when omitted.\n */\nexport function acquire<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T>; refId?: string },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.acquire(BlocClass, key, {\n    canCreate: true,\n    countRef: true,\n    refId: opts?.refId,\n    args: opts?.args,\n  });\n}\n\n/**\n * Resolve the storage key an instance would be acquired under, given its\n * construction `args`. This is the canonical key-computation path. Callers that\n * both acquire and release against the `@internal` registry tier (e.g.\n * `@blac/react` `useBloc`) must use this once and pass the same resolved key to\n * both, so the ref is dropped under the key it was taken.\n */\nexport function resolveInstanceKey<T extends StateContainerConstructor>(\n  BlocClass: T,\n  args?: ExtractArgs<T>,\n): string {\n  return getRegistry().resolveKey(BlocClass, undefined, args);\n}\n","import { getRegistry } from './config';\nimport type {\n  ExtractArgs,\n  StateContainerConstructor,\n} from '../types/utilities';\n\n/**\n * Ensure an instance exists without taking ownership (no ref added). Instance\n * identity is derived purely from `args`, matching `acquire`.\n */\nexport function ensure<T extends StateContainerConstructor>(\n  BlocClass: T,\n  opts?: { args?: ExtractArgs<T> },\n): InstanceType<T> {\n  const registry = getRegistry();\n  const key = registry.resolveKey(BlocClass, undefined, opts?.args);\n  return registry.ensure(BlocClass, key, opts?.args);\n}\n"],"mappings":";;;;;;;;;;;AAeA,SAAgB,QACd,WACA,MACiB;CACjB,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,QAAQ,WAAW,KAAK;EACtC,WAAW;EACX,UAAU;EACV,OAAO,MAAM;EACb,MAAM,MAAM;CACd,CAAC;AACH;;;;;;;;AASA,SAAgB,mBACd,WACA,MACQ;CACR,OAAO,YAAY,EAAE,WAAW,WAAW,KAAA,GAAW,IAAI;AAC5D;;;;;;;AC/BA,SAAgB,OACd,WACA,MACiB;CACjB,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,SAAS,WAAW,WAAW,KAAA,GAAW,MAAM,IAAI;CAChE,OAAO,SAAS,OAAO,WAAW,KAAK,MAAM,IAAI;AACnD"}