@blac/core 2.1.0 → 2.1.1

package/dist/core/StateContainerRegistry.d.ts

@@ -1,41 +1,37 @@
 import type { HydrationStatus, StateContainer } from './StateContainer';
-import { type PluginManager } from '../plugin/PluginManager';
-import { InstanceReadonlyState, StateContainerConstructor, StateContainerInstance } from '../types/utilities';
+import { InstanceReadonlyState, StateContainerConstructor } from '../types/utilities';
+import { INSERT_INSTANCE } from './symbols';
 /**
- * Entry in the instance registry, tracking the instance and its named references
- * @template T - Instance type
+ * Entry in the instance registry.
+ * @typeParam T - Instance type
+ * @internal
  */
 export interface InstanceEntry<T = any> {
-    /** The state container instance */
     instance: T;
-    /** Map of active reference IDs to their acquire count (supports paired acquire/release) */
+    key: string;
+    /** 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>>;
-    /**
-     * `$blac.id` this entry is indexed under in `_byId`, captured at index time.
-     * Removal always keys off THIS stored id (never a fresh `$blac.id` read),
-     * so an id that changes later (e.g. `INIT_CONFIG` running after insertion)
-     * can never orphan the index.
-     */
-    id?: string;
+    sweepTimer?: ReturnType<typeof setTimeout>;
 }
 /**
  * Lifecycle events emitted by the registry
+ * @public
  */
-export type LifecycleEvent = 'created' | 'stateChanged' | 'disposed' | 'refAcquired' | 'refReleased' | 'depsChanged' | 'hydrationChanged';
+export type LifecycleEvent = 'created' | 'stateChanged' | 'disposed' | 'refAcquired' | 'refReleased' | 'depsChanged' | 'hydrationChanged' | 'activated' | 'deactivated';
 /**
  * Listener function type for each lifecycle event
- * @template E - The lifecycle event type
+ * @typeParam E - The lifecycle event type
+ * @public
  */
-export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ? (container: StateContainer<any, any, any>) => void : E extends 'stateChanged' ? (container: StateContainer<any, any, any>, previousState: any, currentState: any) => 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 : never;
+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
@@ -46,77 +42,47 @@ export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ?
  *   console.log('State changed:', prev, '->', next);
  * });
  * ```
+ *
+ * `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;
     /**
-     * Known storage key for each live instance, so disposal can delete its
-     * Map entry directly instead of scanning every entry for identity (P3).
+     * `depend()`-owner to the (Type, key) entries it resolved, per key because
+     * one handle resolves a different key per `args`.
      */
-    private readonly _keyByInstance;
-    /** Id index for O(1) `findEntryById` lookups (P6, used by devtools' `getRefIds`). */
-    private readonly _byId;
-    private readonly types;
-    private _registeredTypes;
+    private readonly _dependentEdges;
+    private readonly _entryByInstance;
+    /**
+     * Only for `PluginContext.getRefIds`: ids can collide across same-named
+     * classes, so nothing else may rely on it.
+     */
+    private readonly _entryById;
     private readonly listeners;
-    private _stateChangedListenerCount;
     get hasStateChangedListeners(): boolean;
     private _pendingStateChanges;
     private _autoRefIdCounter;
     constructor();
-    /**
-     * Registry-internal reaction to any instance's `disposed` lifecycle event.
-     * Prunes its Map entry, if this registry was tracking it (i.e. it was
-     * `acquire()`/`ensure()`'d, not a bare `new`), and always releases its
-     * dependent edges on whatever it `depend()`'d on.
-     */
+    /** Prune a tracked instance's entry and release its `depend()` edges. */
     private _handleDisposed;
+    /** The single dispose decision: no refs, no dependents, not keepAlive. */
+    private _isUnowned;
+    /** Ignores keepAlive: a keepAlive instance still deactivates. */
+    private _hasNoOwners;
     /**
-     * Remove the Map entry for `container`, if this registry is tracking it.
-     * O(1): looks up the entry's key via `_keyByInstance` instead of scanning
-     * every entry for identity. Keeps an identity guard so a recreated entry
-     * under the same key (a fresh instance under a reused/derived key) is
-     * never deleted by a stale container's disposal.
-     * @returns true if an entry was found and removed
+     * Idempotent, so every acquire/release path calls it. The events fire after
+     * the instance's own `onActivate`/`onDeactivate`.
      */
+    private _syncActivation;
+    private _recordDependentEdge;
+    /** @returns true if this registry tracked `container`. */
     private _pruneEntry;
-    /**
-     * Single removal point for the `_byId` index (P6). Every path that drops
-     * an `InstanceEntry` from the registry MUST route through this so the
-     * index can never leak a stale id -> entry mapping.
-     */
-    private _forgetEntry;
-    /**
-     * O(1) entry lookup by `$blac.id`, used by `PluginContext.getRefIds`
-     * instead of a nested scan over every type x every instance.
-     */
-    findEntryById(id: string): InstanceEntry | undefined;
-    /**
-     * Storage key `container` is CURRENTLY indexed under, or `undefined` if this
-     * registry never tracked it (bare `new`) or no longer does (disposed/pruned,
-     * or its key was taken over by a newer instance). Lets callers that hold only
-     * an instance address it without knowing the `args` it was acquired with.
-     */
-    keyOf(instance: StateContainerInstance): string | undefined;
-    /**
-     * Drop `Type` from `types` once its instances map is empty, so constructors
-     * (and anything keyed on them, e.g. a per-class PathInterner) aren't held
-     * alive forever. Deliberate consequence: `getStats()`/`getTypes()` no
-     * longer list types with zero live instances.
-     */
-    private _maybeDropType;
-    /**
-     * 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
@@ -127,61 +93,37 @@ export declare class StateContainerRegistry {
     /**
      * Get the instances Map for a specific class (public API for stats/debugging)
      */
-    getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
+    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
-     * @param options.canCreate - Whether to create new instance if not found (default: true)
-     * @param options.countRef - Whether to add a reference (default: true)
-     * @param options.refId - Named reference ID for debugging; auto-generated if omitted
-     * @param options.dependent - The `depend()`-owner resolving this instance, if any;
-     *   recorded so its dependent edge can be released on the owner's disposal.
-     * @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;
@@ -189,10 +131,17 @@ export declare class StateContainerRegistry {
         refId?: string;
         args?: unknown;
         dependent?: StateContainer<any, any, any>;
+        sweepIfUnowned?: boolean;
     }): InstanceType<T>;
     /**
-     * Borrow an existing instance without adding a ref (borrowing semantics).
-     * Tracks cross-bloc dependency for reactive updates.
+     * 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;
+    /**
+     * 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
@@ -202,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
@@ -218,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
@@ -234,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
@@ -245,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).
@@ -281,40 +211,29 @@ 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[];
+    /** Ref ids by `$blac.id`, for `PluginContext.getRefIds`. */
+    getRefIdsById(instanceId: string): string[];
     /**
      * Check if an instance exists.
      *
      * @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;
@@ -329,19 +248,21 @@ export declare class StateContainerRegistry {
     emit(event: 'refReleased', container: StateContainer<any, any, any>, refId: string): void;
     emit(event: 'depsChanged', container: StateContainer<any, any, any>, previousDeps: Readonly<Record<string, unknown>>, currentDeps: Readonly<Record<string, unknown>>): void;
     emit(event: 'hydrationChanged', container: StateContainer<any, any, any>, status: HydrationStatus, previousStatus: HydrationStatus): void;
+    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;
+    /**
+     * 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;
-/**
- * Get the global plugin manager
- */
-export declare function getPluginManager(): PluginManager;

package/dist/core/meta.d.ts

@@ -1,31 +1,35 @@
 /**
  * `$blac` meta namespace for `StateContainer`.
  *
- * ──────────────────────────────────────────────────────────────────────────
- * CONSTRAINT — NO ES `#private` FIELDS, ANYWHERE IN THIS FILE.
- *
- * `@blac/react`'s `buildTrackedProxy` invokes prototype getters with a
- * `Proxy(instance)` as the `this`-receiver. Accessing an ES `#private` field
- * through a proxy receiver throws (`#x` brand checks fail on the proxy). The
- * whole point of this meta object is to be proxy-safe: every getter/method
- * here closes over the *real* container instance captured at `createMeta`
- * time, NEVER over a `this`-receiver. Do not "modernize" the `_`-prefixed
- * TS-private reads below into `#private` access.
- * ──────────────────────────────────────────────────────────────────────────
+ * `BlacMeta` and `BlacHydration` are classes whose accessors live on the
+ * prototype and read the container through one `#private` back-reference, so
+ * a container allocates a single small object here instead of a literal with
+ * seven closures. Members are therefore not own-enumerable: `Object.keys` and
+ * `JSON.stringify` see an empty object. Read the fields by name.
  */
 import type { HydrationStatus } from './StateContainer';
 import type { StateContainerConstructor } from '../types/utilities';
+/**
+ * Non-enumerable brand carried on every `$blac` object. Used by the clobber
+ * guard in `StateContainer` to detect a subclass class-field shadowing the
+ * base's own `$blac` property, and by the meta tests. Intentionally NOT
+ * re-exported from the package barrel.
+ */
+export declare const META_BRAND: unique symbol;
 /**
  * Hydration sub-surface of {@link BlacMeta}. Exposes the container's
  * hydration state machine — the `begin`/`apply`/`finish`/`fail`/`wait`
  * methods and the `status`/`error`/`isHydrated`/`changedWhileHydrating`
  * getters — namespaced under `$blac`.
  */
-export interface BlacHydration<S extends object> {
-    readonly status: HydrationStatus;
-    readonly error: Error | undefined;
-    readonly isHydrated: boolean;
-    readonly changedWhileHydrating: boolean;
+export declare class BlacHydration<S extends object> {
+    #private;
+    /** @internal */
+    constructor(container: object);
+    get status(): HydrationStatus;
+    get error(): Error | undefined;
+    get isHydrated(): boolean;
+    get changedWhileHydrating(): boolean;
     begin(): void;
     apply(next: S): boolean;
     finish(): void;
@@ -38,36 +42,19 @@ export interface BlacHydration<S extends object> {
  * `createdAt`, `disposed`, `dependencies`, and the hydration methods) under one
  * namespace, keeping the generic names free for userland blocs.
  *
- * The object is allocated once per container, frozen, branded, and exposes
- * live getters that read the container's current `_`-private fields — values
- * are never snapshotted.
+ * Allocated once per container and frozen. Every accessor reads the
+ * container's current `_`-private fields live — values are never snapshotted.
  */
-export interface BlacMeta<S extends object = any> {
-    readonly name: string;
-    readonly id: string;
-    readonly debug: boolean;
-    readonly createdAt: number;
-    readonly disposed: boolean;
-    readonly dependencies: ReadonlyMap<StateContainerConstructor, string>;
-    readonly hydration: BlacHydration<S>;
+export declare class BlacMeta<S extends object = any> {
+    #private;
+    /** @internal Called from the `StateContainer` field initializer. */
+    constructor(container: object);
+    get name(): string;
+    get id(): string;
+    get debug(): boolean;
+    get createdAt(): number;
+    get disposed(): boolean;
+    get dependencies(): ReadonlyMap<StateContainerConstructor, string>;
+    /** Built on first access; identity-stable afterwards. */
+    get hydration(): BlacHydration<S>;
 }
-/**
- * Non-enumerable brand carried on every `$blac` object produced by
- * {@link createMeta}. Used by the clobber guard in `StateContainer` to detect
- * a subclass class-field shadowing the base's own `$blac` property, and by the
- * meta tests. Intentionally NOT re-exported from the package barrel.
- */
-export declare const META_BRAND: unique symbol;
-/**
- * Build the frozen, branded `$blac` meta object for a container.
- *
- * Called from a `StateContainer` field initializer (`$blac = createMeta(this)`).
- * Only the back-reference is captured at this point; every getter/method reads
- * the container's `_`-private fields lazily on access, so field-initializer
- * ordering relative to those private fields is irrelevant.
- *
- * The getters close over `container` (the real instance), never over a
- * `this`-receiver — this is what keeps `$blac` reads safe through
- * `buildTrackedProxy`.
- */
-export declare function createMeta<S extends object>(container: object): BlacMeta<S>;

package/dist/core/symbols.d.ts

@@ -1,6 +1,6 @@
 /**
  * @internal Apply one owner's (consumer's) deps slice to an instance.
- * Called by framework adapters (e.g. @blac/react useBloc) — not public API.
+ * Called by framework adapters (e.g. `@blac/react` useBloc) — not public API.
  */
 export declare const APPLY_DEPS: unique symbol;
 /**
@@ -24,3 +24,23 @@ export declare const ON_DISPOSE: unique symbol;
  * helpers are the sole callers, mirroring the `APPLY_DEPS` precedent.
  */
 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. Getters run with `this` bound to the
+ * real instance, so ES `#private` works in user blocs.
+ */
+export declare const WITH_TRACKED_STATE: unique symbol;
+/**
+ * @internal Drive the activation lifecycle from the registry's 0↔1 ownership
+ * transition. Owns the per-instance AbortController so `onActivate`'s signal
+ * aborts on the matching deactivation and on dispose.
+ *
+ * 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

@@ -1,35 +1,35 @@
 import type { EqualityFn } from '../config';
 /**
- * Configuration options for the @blac decorator.
- * Only one option can be specified at a time (union type).
+ * Configuration options for the `@blac` decorator. Any combination may be
+ * given at once.
  */
-export type BlacOptions = 
-/** Mark bloc to never be auto-disposed when ref count reaches 0 */
-{
-    keepAlive: true;
-}
-/** Exclude bloc from DevTools tracking (prevents infinite loops) */
- | {
-    excludeFromDevTools: true;
-}
-/**
- * Override the global equality check for this bloc.
- * Return `true` to skip the emit (states considered equal).
- * Applies to `emit`/`update` only — `patch` does not consult this fn; it
- * still skips structural no-ops on its own.
- */
- | {
-    equality: EqualityFn;
+export interface BlacOptions {
+    /**
+     * 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;
+    /**
+     * Override the global equality check for this bloc.
+     * Return `true` to skip the emit (states considered equal).
+     */
+    equality?: EqualityFn;
+    /**
+     * Override the default structural-hash identity key.
+     * The function receives `args` and returns the instance key string.
+     * Distinct return values → distinct instances; identical values → shared instance.
+     * Non-identity fields can be excluded so they don't fork new instances.
+     */
+    key?: (args: any) => string;
+    /**
+     * Explicit, minification-safe identity for this bloc class. Falls back to
+     * `constructor.name` when unset, which collides across classes once a
+     * minifier shortens class names.
+     */
+    name?: string;
 }
-/**
- * Override the default structural-hash identity key.
- * The function receives `args` and returns the instance key string.
- * Distinct return values → distinct instances; identical values → shared instance.
- * Non-identity fields can be excluded so they don't fork new instances.
- */
- | {
-    key: (args: any) => string;
-};
 /**
  * Decorator to configure StateContainer classes.
  *
@@ -40,6 +40,9 @@ export type BlacOptions =
  *
  * @blac({ excludeFromDevTools: true })
  * class InternalBloc extends Cubit<InternalState> {}
+ *
+ * @blac({ keepAlive: true, key: (args) => args.userId })
+ * class UserBloc extends Cubit<UserState> {}
  * ```
  *
  * @example Function syntax (no decorator support needed)

package/dist/{acquire-B1LYXSGj.js → ensure-Bi_yXk6f.js}

@@ -1,4 +1,4 @@
-import { t as getRegistry } from "./config-DXI3kzmA.js";
+import { i as getRegistry } from "./StateContainer-Bh2ipNYj.js";
 //#region src/registry/acquire.ts
 /**
 * Acquire an instance with ref tracking (ownership semantics). Instance
@@ -6,8 +6,8 @@ import { t as getRegistry } from "./config-DXI3kzmA.js";
 * a structural hash of `args`, or the default sentinel when there are none).
 *
 * @param BlocClass - The StateContainer class constructor
-* @param opts.args - Construction/identity args; derives the instance key
-* @param opts.refId - Named reference ID for debugging; auto-generated if omitted
+* @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();
@@ -30,6 +30,17 @@ function resolveInstanceKey(BlocClass, args) {
 	return getRegistry().resolveKey(BlocClass, void 0, args);
 }
 //#endregion
-export { resolveInstanceKey as n, acquire as t };
+//#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=acquire-B1LYXSGj.js.map
+//# sourceMappingURL=ensure-Bi_yXk6f.js.map