@blac/core 2.0.19 → 2.0.21

package/dist/core/StateContainerRegistry.d.ts

@@ -1,27 +1,35 @@
 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. */
     args?: unknown;
+    /** Memoized structuralKey(args) for the dev arg-mismatch warning. */
+    argsKey?: string;
+    /** `depend()`-owners currently holding this instance (see `acquire`'s `dependent` option). */
+    dependents?: Set<StateContainer<any, any, 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.
@@ -35,16 +43,80 @@ 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 instance to its entry, so `_pruneEntry` is O(1). */
+    private readonly _entryByInstance;
+    /** Reverse lookup from `$blac.id` to its entry, for `PluginContext.getRefIds`. */
+    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.
+     * 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.
+     */
+    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
+     */
+    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 _releaseDependent;
     /**
      * Register a type for lifecycle event tracking
      * @param constructor - The StateContainer class constructor
@@ -60,7 +132,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
@@ -79,7 +151,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
@@ -108,10 +180,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 - 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?: {
@@ -119,7 +194,20 @@ export declare class StateContainerRegistry {
         countRef?: boolean;
         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.
@@ -211,6 +299,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.
      *
@@ -259,19 +354,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,17 +1,11 @@
 /**
  * `$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.
- * ──────────────────────────────────────────────────────────────────────────
+ * Getters/methods here close over the *real* container instance captured at
+ * `createMeta` time rather than reading a `this`-receiver. `buildTrackedProxy`
+ * no longer uses a `this`-Proxy (getters run with `this` = the real instance),
+ * so ES `#private` is safe here now; the closure style is kept because it also
+ * keeps this own, frozen property independent of the proxy entirely.
  */
 import type { HydrationStatus } from './StateContainer';
 import type { StateContainerConstructor } from '../types/utilities';

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;
 /**
@@ -8,6 +8,12 @@ export declare const APPLY_DEPS: unique symbol;
  * Called by framework adapters — not public API.
  */
 export declare const REMOVE_DEPS_OWNER: unique symbol;
+/**
+ * @internal Subscribe to this specific instance's own disposal, bypassing
+ * the global registry `'disposed'` event. Called by `watch()` — not public
+ * API.
+ */
+export declare const ON_DISPOSE: unique symbol;
 /**
  * @internal Symbol-keyed configuration entry point on `StateContainer`.
  * Writes the instance's identity fields (`_name`/`_debug`/`_instanceId`),
@@ -18,3 +24,20 @@ export declare const REMOVE_DEPS_OWNER: 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)