@blac/core 2.0.20 → 2.0.22

package/dist/core/StateContainerRegistry.d.ts

@@ -1,13 +1,15 @@
 import type { HydrationStatus, StateContainer } from './StateContainer';
-import { type PluginManager } from '../plugin/PluginManager';
 import { InstanceReadonlyState, StateContainerConstructor } from '../types/utilities';
 /**
  * Entry in the instance registry, tracking the instance and its named references
- * @template T - Instance type
+ * @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) */
     refs: Map<string, number>;
     /** The args used when this entry was first created; used for dev-warn on arg mismatch. */
@@ -19,13 +21,15 @@ export interface InstanceEntry<T = any> {
 }
 /**
  * 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.
@@ -39,13 +43,33 @@ export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ?
  *   console.log('State changed:', prev, '->', next);
  * });
  * ```
+ *
+ * `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.
  */
 export declare class StateContainerRegistry {
     private readonly instancesByConstructor;
     private readonly types;
-    private readonly registeredTypeNames;
+    /**
+     * `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.
+     */
+    private readonly _dependentEdges;
+    /**
+     * 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.
+     */
+    private readonly _entryById;
     private readonly listeners;
-    private _stateChangedListenerCount;
+    /**
+     * 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;
@@ -57,6 +81,35 @@ export declare class StateContainerRegistry {
      * release its dependent edges on whatever it `depend()`'d on.
      */
     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.
+     */
+    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.
+     */
+    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.
+     */
+    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
@@ -84,7 +137,7 @@ 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
@@ -103,7 +156,7 @@ export declare class StateContainerRegistry {
      * 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.
+     * explicit key \> `static key(args)` \> structural hash of args \> default sentinel.
      *
      * @param Type - The StateContainer class constructor
      * @param instanceKey - Explicit key, or undefined to derive from args
@@ -132,12 +185,13 @@ export declare class StateContainerRegistry {
      *   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.
+     * @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
      */
     acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
@@ -146,7 +200,19 @@ export declare class StateContainerRegistry {
         refId?: string;
         args?: unknown;
         dependent?: StateContainer<any, any, any>;
+        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`.
+     */
+    private _scheduleSweep;
     /**
      * Borrow an existing instance without adding a ref (borrowing semantics).
      * Tracks cross-bloc dependency for reactive updates.
@@ -238,6 +304,13 @@ 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)
+     */
+    getRefIdsById(instanceId: string): string[];
     /**
      * Check if an instance exists.
      *
@@ -286,19 +359,27 @@ 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.
      * @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.
+     */
     private flushStateChanged;
 }
 /**
  * Global default registry instance
+ * @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,20 @@ 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.
+ *
+ * Replaces the old `this`-Proxy receiver: getters now 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;

package/dist/decorators/blac.d.ts

@@ -1,33 +1,32 @@
 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).
- */
- | {
-    equality: EqualityFn;
+export interface 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).
+     */
+    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.
  *
@@ -38,6 +37,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)