@blac/core 2.0.20 → 2.1.0

package/dist/constants.d.ts

@@ -11,10 +11,6 @@ export declare const BLAC_DEFAULTS: {
      * Default instance key for shared instances
      */
     readonly DEFAULT_INSTANCE_KEY: "default";
-    /**
-     * Maximum getter nesting depth (prevents infinite recursion)
-     */
-    readonly MAX_GETTER_DEPTH: 10;
 };
 /**
  * Static property names for StateContainer classes
@@ -42,15 +38,8 @@ export declare const BLAC_STATIC_PROPS: {
      * non-identity fields (e.g., `readonly` flags) while still keying by id.
      */
     readonly KEY: "key";
-};
-/**
- * ID generation patterns and constants
- */
-export declare const BLAC_ID_PATTERNS: {
-    /**
-     * Length of generated ID portion (9 characters from base36)
-     */
-    readonly ID_LENGTH: 9;
+    /** Mark a bloc as always per-mount: `static isolated = true`. */
+    readonly ISOLATED: "isolated";
 };
 /**
  * Standard error message prefix

package/dist/core/StateContainer.d.ts

@@ -1,4 +1,5 @@
 import { StructuralContainer, type DeepPartial, type StructuralContainerOptions } from '@dirtytalk/structural';
+import { type EventToken } from '../events';
 import type { ExtractArgs, ExtractState, StateContainerConstructor } from '../types/utilities';
 import { APPLY_DEPS, INIT_CONFIG, ON_DISPOSE, REMOVE_DEPS_OWNER } from './symbols';
 import { type BlacMeta } from './meta';
@@ -127,6 +128,7 @@ export declare abstract class StateContainer<S extends object = any, Args = void
     private _emitRateWarned;
     private readonly _systemEventHandlers;
     private _dependencies;
+    private _depEdges;
     private _pendingChange;
     private _bridgeUnsub;
     private _registry;
@@ -162,6 +164,15 @@ export declare abstract class StateContainer<S extends object = any, Args = void
      */
     protected depend<T extends StateContainerConstructor>(Type: T, defaultArgs?: ExtractArgs<T>): DepHandle<T>;
     constructor(initialState: S, options?: StructuralContainerOptions);
+    /**
+     * @internal Subscribe the channel bridge that turns flushes into
+     * 'stateChanged' system events. Interest is ALL_PATHS so we wake on every
+     * flush. Coalesced via `_pendingChange`: if no emit happened (e.g. a no-op
+     * patch), the bridge sees null and skips. Lazy: only subscribed while at
+     * least one 'stateChanged' handler exists.
+     */
+    private _subscribeBridge;
+    private _hasStateChangedHandlers;
     /**
      * Called once after construction with the args passed at acquire time, before the first
      * state snapshot is read by any consumer. Override to seed args-derived state (via
@@ -204,6 +215,16 @@ export declare abstract class StateContainer<S extends object = any, Args = void
     private resolveHydration;
     private rejectHydration;
     protected onSystemEvent: <E extends SystemEvent>(event: E, handler: SystemEventHandler<S, E>) => (() => void);
+    /**
+     * Subscribe to a cross-cutting application event for this container's
+     * lifetime. The subscription is torn down automatically on `dispose()` — no
+     * manual `off` in consumer code (requirements AC3).
+     *
+     * Uses THIS container's registry (`_registry`, captured at construction), not
+     * the ambient one, so a container always listens on the bus of the registry it
+     * belongs to.
+     */
+    protected on: <P>(token: EventToken<P>, handler: (payload: P) => void) => (() => void);
     private emitSystemEvent;
     /**
      * Dev-only soft circuit breaker. Counts real state changes in a rolling 1s

package/dist/core/StateContainerRegistry.d.ts

@@ -1,6 +1,6 @@
 import type { HydrationStatus, StateContainer } from './StateContainer';
 import { type PluginManager } from '../plugin/PluginManager';
-import { InstanceReadonlyState, StateContainerConstructor } from '../types/utilities';
+import { InstanceReadonlyState, StateContainerConstructor, StateContainerInstance } from '../types/utilities';
 /**
  * Entry in the instance registry, tracking the instance and its named references
  * @template T - Instance type
@@ -16,6 +16,13 @@ export interface InstanceEntry<T = any> {
     argsKey?: string;
     /** `depend()`-owners currently holding this instance (see `acquire`'s `dependent` option). */
     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;
 }
 /**
  * Lifecycle events emitted by the registry
@@ -42,8 +49,15 @@ export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ?
  */
 export declare class StateContainerRegistry {
     private readonly instancesByConstructor;
+    /**
+     * Known storage key for each live instance, so disposal can delete its
+     * Map entry directly instead of scanning every entry for identity (P3).
+     */
+    private readonly _keyByInstance;
+    /** Id index for O(1) `findEntryById` lookups (P6, used by devtools' `getRefIds`). */
+    private readonly _byId;
     private readonly types;
-    private readonly registeredTypeNames;
+    private _registeredTypes;
     private readonly listeners;
     private _stateChangedListenerCount;
     get hasStateChangedListeners(): boolean;
@@ -52,16 +66,45 @@ export declare class StateContainerRegistry {
     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.
+     * 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.
      */
     private _handleDisposed;
     /**
      * 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
      */
     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

package/dist/debug.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_StateContainerRegistry = require("./StateContainerRegistry-CS18y4au.cjs");
-const require_config = require("./config-DWUq7zEQ.cjs");
-const require_management = require("./management-QWLpbXlW.cjs");
+const require_StateContainerRegistry = require("./StateContainerRegistry-G81GcCRm.cjs");
+const require_config = require("./config-C1T6Jw7n.cjs");
+const require_management = require("./management-hkY13log.cjs");
 exports.forEach = require_management.forEach;
 exports.getAll = require_management.getAll;
 exports.getRefCount = require_management.getRefCount;

package/dist/debug.js

@@ -1,4 +1,4 @@
-import { r as globalRegistry } from "./StateContainerRegistry-D8nu7Z0T.js";
-import { n as getStats, r as setRegistry, t as getRegistry } from "./config-DXI3kzmA.js";
-import { a as getAll, c as hasInstance, i as forEach, o as getRefCount, r as register, s as getRefIds } from "./management-C-WGcwPD.js";
+import { r as globalRegistry } from "./StateContainerRegistry-DWOzx7Gd.js";
+import { n as getStats, r as setRegistry, t as getRegistry } from "./config-D2A8ZYRM.js";
+import { a as getAll, c as hasInstance, i as forEach, o as getRefCount, r as register, s as getRefIds } from "./management-8x1OVMi6.js";
 export { forEach, getAll, getRefCount, getRefIds, getRegistry, getStats, globalRegistry, hasInstance, register, setRegistry };

package/dist/decorators/blac.d.ts

@@ -15,6 +15,8 @@ export type BlacOptions =
 /**
  * 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;