@blac/core 2.0.13 → 2.0.14

package/dist/management-jQGCvZNN.cjs

@@ -1,70 +1,70 @@
-const require_config = require("./config-D3jisfdj.cjs");
+const require_config = require('./config-D3jisfdj.cjs');
 //#region src/registry/queries.ts
 function hasInstance(BlocClass, instanceKey) {
-	return require_config.getRegistry().hasInstance(BlocClass, instanceKey);
+  return require_config.getRegistry().hasInstance(BlocClass, instanceKey);
 }
 function getRefCount(BlocClass, instanceKey) {
-	return require_config.getRegistry().getRefCount(BlocClass, instanceKey);
+  return require_config.getRegistry().getRefCount(BlocClass, instanceKey);
 }
 function getAll(BlocClass) {
-	return require_config.getRegistry().getAll(BlocClass);
+  return require_config.getRegistry().getAll(BlocClass);
 }
 function forEach(BlocClass, callback) {
-	require_config.getRegistry().forEach(BlocClass, callback);
+  require_config.getRegistry().forEach(BlocClass, callback);
 }
 //#endregion
 //#region src/registry/management.ts
 function clear(BlocClass) {
-	require_config.getRegistry().clear(BlocClass);
+  require_config.getRegistry().clear(BlocClass);
 }
 function clearAll() {
-	require_config.getRegistry().clearAll();
+  require_config.getRegistry().clearAll();
 }
 function register(BlocClass) {
-	require_config.getRegistry().register(BlocClass);
+  require_config.getRegistry().register(BlocClass);
 }
 //#endregion
-Object.defineProperty(exports, "clear", {
-	enumerable: true,
-	get: function() {
-		return clear;
-	}
+Object.defineProperty(exports, 'clear', {
+  enumerable: true,
+  get: function () {
+    return clear;
+  },
 });
-Object.defineProperty(exports, "clearAll", {
-	enumerable: true,
-	get: function() {
-		return clearAll;
-	}
+Object.defineProperty(exports, 'clearAll', {
+  enumerable: true,
+  get: function () {
+    return clearAll;
+  },
 });
-Object.defineProperty(exports, "forEach", {
-	enumerable: true,
-	get: function() {
-		return forEach;
-	}
+Object.defineProperty(exports, 'forEach', {
+  enumerable: true,
+  get: function () {
+    return forEach;
+  },
 });
-Object.defineProperty(exports, "getAll", {
-	enumerable: true,
-	get: function() {
-		return getAll;
-	}
+Object.defineProperty(exports, 'getAll', {
+  enumerable: true,
+  get: function () {
+    return getAll;
+  },
 });
-Object.defineProperty(exports, "getRefCount", {
-	enumerable: true,
-	get: function() {
-		return getRefCount;
-	}
+Object.defineProperty(exports, 'getRefCount', {
+  enumerable: true,
+  get: function () {
+    return getRefCount;
+  },
 });
-Object.defineProperty(exports, "hasInstance", {
-	enumerable: true,
-	get: function() {
-		return hasInstance;
-	}
+Object.defineProperty(exports, 'hasInstance', {
+  enumerable: true,
+  get: function () {
+    return hasInstance;
+  },
 });
-Object.defineProperty(exports, "register", {
-	enumerable: true,
-	get: function() {
-		return register;
-	}
+Object.defineProperty(exports, 'register', {
+  enumerable: true,
+  get: function () {
+    return register;
+  },
 });
 
-//# sourceMappingURL=management-jQGCvZNN.cjs.map
+//# sourceMappingURL=management-jQGCvZNN.cjs.map

package/dist/management-ry_KteFK.cjs

@@ -1,79 +1,79 @@
-const require_config = require("./config-CQH9fTY-.cjs");
+const require_config = require('./config-CQH9fTY-.cjs');
 //#region src/registry/queries.ts
 function hasInstance(BlocClass, instanceKey) {
-	return require_config.getRegistry().hasInstance(BlocClass, instanceKey);
+  return require_config.getRegistry().hasInstance(BlocClass, instanceKey);
 }
 function getRefCount(BlocClass, instanceKey) {
-	return require_config.getRegistry().getRefCount(BlocClass, instanceKey);
+  return require_config.getRegistry().getRefCount(BlocClass, instanceKey);
 }
 function getRefIds(BlocClass, instanceKey) {
-	return require_config.getRegistry().getRefIds(BlocClass, instanceKey);
+  return require_config.getRegistry().getRefIds(BlocClass, instanceKey);
 }
 function getAll(BlocClass) {
-	return require_config.getRegistry().getAll(BlocClass);
+  return require_config.getRegistry().getAll(BlocClass);
 }
 function forEach(BlocClass, callback) {
-	require_config.getRegistry().forEach(BlocClass, callback);
+  require_config.getRegistry().forEach(BlocClass, callback);
 }
 //#endregion
 //#region src/registry/management.ts
 function clear(BlocClass) {
-	require_config.getRegistry().clear(BlocClass);
+  require_config.getRegistry().clear(BlocClass);
 }
 function clearAll() {
-	require_config.getRegistry().clearAll();
+  require_config.getRegistry().clearAll();
 }
 function register(BlocClass) {
-	require_config.getRegistry().register(BlocClass);
+  require_config.getRegistry().register(BlocClass);
 }
 //#endregion
-Object.defineProperty(exports, "clear", {
-	enumerable: true,
-	get: function() {
-		return clear;
-	}
+Object.defineProperty(exports, 'clear', {
+  enumerable: true,
+  get: function () {
+    return clear;
+  },
 });
-Object.defineProperty(exports, "clearAll", {
-	enumerable: true,
-	get: function() {
-		return clearAll;
-	}
+Object.defineProperty(exports, 'clearAll', {
+  enumerable: true,
+  get: function () {
+    return clearAll;
+  },
 });
-Object.defineProperty(exports, "forEach", {
-	enumerable: true,
-	get: function() {
-		return forEach;
-	}
+Object.defineProperty(exports, 'forEach', {
+  enumerable: true,
+  get: function () {
+    return forEach;
+  },
 });
-Object.defineProperty(exports, "getAll", {
-	enumerable: true,
-	get: function() {
-		return getAll;
-	}
+Object.defineProperty(exports, 'getAll', {
+  enumerable: true,
+  get: function () {
+    return getAll;
+  },
 });
-Object.defineProperty(exports, "getRefCount", {
-	enumerable: true,
-	get: function() {
-		return getRefCount;
-	}
+Object.defineProperty(exports, 'getRefCount', {
+  enumerable: true,
+  get: function () {
+    return getRefCount;
+  },
 });
-Object.defineProperty(exports, "getRefIds", {
-	enumerable: true,
-	get: function() {
-		return getRefIds;
-	}
+Object.defineProperty(exports, 'getRefIds', {
+  enumerable: true,
+  get: function () {
+    return getRefIds;
+  },
 });
-Object.defineProperty(exports, "hasInstance", {
-	enumerable: true,
-	get: function() {
-		return hasInstance;
-	}
+Object.defineProperty(exports, 'hasInstance', {
+  enumerable: true,
+  get: function () {
+    return hasInstance;
+  },
 });
-Object.defineProperty(exports, "register", {
-	enumerable: true,
-	get: function() {
-		return register;
-	}
+Object.defineProperty(exports, 'register', {
+  enumerable: true,
+  get: function () {
+    return register;
+  },
 });
 
-//# sourceMappingURL=management-ry_KteFK.cjs.map
+//# sourceMappingURL=management-ry_KteFK.cjs.map

package/dist/plugin/BlacPlugin.d.ts

@@ -1,3 +1,4 @@
+import type { PathSet } from '@dirtytalk/structural';
 import type { HydrationStatus, StateContainer } from '../core/StateContainer';
 export interface InstanceMetadata {
     id: string;
@@ -12,18 +13,37 @@ export interface InstanceMetadata {
     isHydrated: boolean;
     hydrationError?: Error;
     changedWhileHydrating: boolean;
+    /** Args passed at acquire time; keys instance identity. */
+    args?: unknown;
 }
+/**
+ * Per-event context delivered to plugin hooks.
+ *
+ * Per Decision 6 (C2 migration): `PluginContext` is per-container — it
+ * identifies the bloc, not the event. Per-event data (e.g. the changed
+ * `PathSet`) is passed via dedicated method arguments, never via the
+ * context object.
+ *
+ * The `container` field is the focal bloc for the event. For `onInstall`
+ * (which fires once at install time, not bound to any container) the
+ * `container` field is `undefined`.
+ */
 export interface PluginContext {
-    getInstanceMetadata(instance: StateContainer<any>): InstanceMetadata;
+    /**
+     * The container this event is about. `undefined` only for `onInstall`,
+     * which fires once at plugin install time before any container is known.
+     */
+    container: StateContainer<any, any, any> | undefined;
+    getInstanceMetadata(instance: StateContainer<any, any, any>): InstanceMetadata;
     getState<S extends object = any>(instance: StateContainer<S>): S;
-    getHydrationStatus(instance: StateContainer<any>): HydrationStatus;
-    startHydration(instance: StateContainer<any>): void;
+    getHydrationStatus(instance: StateContainer<any, any, any>): HydrationStatus;
+    startHydration(instance: StateContainer<any, any, any>): void;
     applyHydratedState<S extends object = any>(instance: StateContainer<S>, state: S): boolean;
-    finishHydration(instance: StateContainer<any>): void;
-    failHydration(instance: StateContainer<any>, error: Error): void;
-    waitForHydration(instance: StateContainer<any>): Promise<void>;
-    queryInstances<T extends StateContainer<any>>(typeClass: new (...args: any[]) => T): T[];
-    getAllTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    finishHydration(instance: StateContainer<any, any, any>): void;
+    failHydration(instance: StateContainer<any, any, any>, error: Error): void;
+    waitForHydration(instance: StateContainer<any, any, any>): Promise<void>;
+    queryInstances<T extends StateContainer<any, any, any>>(typeClass: new (...args: any[]) => T): T[];
+    getAllTypes(): Array<new (...args: any[]) => StateContainer<any, any, any>>;
     getStats(): {
         registeredTypes: number;
         totalInstances: number;
@@ -31,19 +51,73 @@ export interface PluginContext {
     };
     getRefIds(instanceId: string): string[];
 }
+/**
+ * BlaC plugin hook surface.
+ *
+ * Per C2 (Decision 6), state-change events carry the `PathSet` of paths
+ * that changed in the flush. Lifecycle events (`onCreated`, `onDestroyed`)
+ * are not tied to a state change and so do not carry `paths`.
+ *
+ * Hook firing model:
+ * - `onCreated` fires synchronously when a container is first acquired.
+ * - `onStateChange` fires once per channel flush (microtask-coalesced).
+ *   `prev` is the state before the first emit of the flush; `next` is the
+ *   state at flush time; `paths` is the set of paths marked during the flush.
+ * - `onDestroyed` fires synchronously when a container is disposed (after
+ *   its system 'dispose' event).
+ *
+ * Legacy ref/deps hooks (`onRefAcquired`, `onRefReleased`, `onDepsChanged`)
+ * are retained for devtools-connect compatibility — they are orthogonal to
+ * the C2 event payload contract.
+ */
 export interface BlacPlugin {
     readonly name: string;
     readonly version: string;
-    onInstall?(context: PluginContext): void;
+    /**
+     * Fires once when the plugin is installed. `ctx.container` is `undefined`
+     * here — `onInstall` is global to the plugin, not per-container.
+     */
+    onInstall?(ctx: PluginContext): void;
     onUninstall?(): void;
-    onInstanceCreated?(instance: StateContainer<any>, context: PluginContext): void;
-    onStateChanged?<S extends object = any>(instance: StateContainer<S>, previousState: S, currentState: S, context: PluginContext): void;
-    onInstanceDisposed?(instance: StateContainer<any>, context: PluginContext): void;
-    onRefAcquired?(instance: StateContainer<any>, refId: string, context: PluginContext): void;
-    onRefReleased?(instance: StateContainer<any>, refId: string, context: PluginContext): void;
+    /**
+     * Fires when a container is first created and acquired.
+     * `ctx.container` is the new container.
+     */
+    onCreated?(ctx: PluginContext): void;
+    /**
+     * Fires once per channel flush with the changed `PathSet`.
+     * `paths` may be `ALL_PATHS` when the change spans every path.
+     * `prev`/`next` are the coalesced before/after states for the flush.
+     */
+    onStateChange?<S extends object = any>(ctx: PluginContext, prev: S, next: S, paths: PathSet): void;
+    /**
+     * Fires when a container is disposed.
+     * `ctx.container` is the disposed container (still queryable, but its
+     * `isDisposed` is `true` by the time this fires).
+     */
+    onDestroyed?(ctx: PluginContext): void;
+    /**
+     * Fires when a container's hydration status transitions.
+     */
+    onHydrationChange?(ctx: PluginContext, status: HydrationStatus, previousStatus: HydrationStatus): void;
+    /**
+     * @internal Devtools-only — fires when a named ref is acquired.
+     * Not part of the C2 event payload contract.
+     */
+    onRefAcquired?(ctx: PluginContext, refId: string): void;
+    /**
+     * @internal Devtools-only — fires when a named ref is released.
+     * Not part of the C2 event payload contract.
+     */
+    onRefReleased?(ctx: PluginContext, refId: string): void;
+    /**
+     * @internal Devtools-only — fires when the merged per-consumer deps view
+     * for a container changes.
+     */
+    onDepsChanged?(ctx: PluginContext, previousDeps: Readonly<Record<string, unknown>>, currentDeps: Readonly<Record<string, unknown>>): void;
 }
 export interface BlacPluginWithInit extends BlacPlugin {
-    onInstall(context: PluginContext): void;
+    onInstall(ctx: PluginContext): void;
 }
 export interface PluginConfig {
     enabled?: boolean;

package/dist/plugin/PluginManager.d.ts

@@ -2,7 +2,25 @@ import type { StateContainerRegistry } from '../core/StateContainerRegistry';
 import type { BlacPlugin, PluginConfig } from './BlacPlugin';
 /**
  * Manages plugin lifecycle for the BlaC state management system.
- * Plugins receive notifications about state container lifecycle events.
+ *
+ * The manager hooks into two surfaces:
+ *
+ * 1. **Registry lifecycle events** (`created`, `disposed`, `refAcquired`,
+ *    `refReleased`, `depsChanged`) — synchronous, fired by the registry.
+ *
+ * 2. **Per-container channel flushes** — microtask-coalesced. For each
+ *    container, the manager subscribes once at create-time with
+ *    `ALL_PATHS` interest and stashes `prevState`. On every flush it
+ *    captures the new state + the changed `PathSet` and dispatches
+ *    `onStateChange(ctx, prev, next, paths)` to every enabled plugin.
+ *
+ * The `ALL_PATHS` subscription cost: plugins counted as a consumer with
+ * `ALL_PATHS` interest will defeat the single-consumer-skip optimization
+ * in `StructuralContainer`. This is the intended trade-off — devtools /
+ * persist plugins genuinely want every change, and stateful plugins
+ * (logging) can decode `paths` via `container.interner.lookup(id)` to log
+ * only relevant fields. Plugins that want low overhead should remain
+ * uninstalled or environment-gated.
  *
  * @example
  * ```ts
@@ -14,6 +32,12 @@ export declare class PluginManager {
     private plugins;
     private registry;
     private lifecycleUnsubscribers;
+    /**
+     * Per-container channel-bridge bookkeeping. Subscribed at `created`,
+     * torn down at `disposed`. Holds the rolling `prevState` snapshot the
+     * manager hands plugins on each flush.
+     */
+    private containerBridges;
     /**
      * Create a new PluginManager
      * @param registry - The StateContainerRegistry to monitor for lifecycle events
@@ -55,17 +79,53 @@ export declare class PluginManager {
     clear(): void;
     destroy(): void;
     /**
-     * Setup lifecycle hooks to notify plugins
+     * Wire registry lifecycle events into plugin dispatch.
+     *
+     * `onStateChange` is NOT wired through `registry.on('stateChanged', …)` —
+     * that event lacks the `PathSet` payload. Instead, on each `created` we
+     * subscribe to the container's channel directly so we get
+     * `(paths)` and capture `(prev, next)` via the per-container snapshot.
      */
     private setupLifecycleHooks;
     /**
-     * Notify all plugins of a lifecycle event
+     * Subscribe to the container's channel with `ALL_PATHS` interest, so we
+     * fire on every flush. Capture `prev` from the snapshot taken on the
+     * previous flush (or at create-time for the first flush) and pass the
+     * channel's `paths` argument straight through to plugins.
+     *
+     * Per-container bookkeeping is stored in a `WeakMap` keyed by the
+     * container itself, so a disposed/GC'd container drops cleanly.
+     */
+    private attachStateBridge;
+    private detachStateBridge;
+    /**
+     * Channel-flush callback. Snapshots `next`, hands `(prev, next, paths)`
+     * to every enabled plugin's `onStateChange`, then updates `prevState`
+     * for the next flush.
+     *
+     * Note: `prev` is captured once and reused across plugins — every
+     * plugin sees the same `prev`/`next`/`paths` regardless of dispatch
+     * order, matching the "snapshot prev once per flush" invariant called
+     * out in the C2 spec pitfalls.
+     */
+    private dispatchStateChange;
+    /**
+     * Notify all plugins of a lifecycle event.
+     *
+     * Builds a fresh `PluginContext` per dispatch (instance becomes
+     * `ctx.container`), so plugins can reach the focal bloc through
+     * `ctx.container` per Decision 6.
      */
     private notifyPlugins;
     /**
-     * Create plugin context with safe API access
+     * Build a `PluginContext` for a given focal container. The context is
+     * cheap to build — its methods close over `this.registry` directly —
+     * so we create one per dispatch rather than caching per container.
+     * This sidesteps the lifetime question of "when do we evict a cached
+     * context?" and keeps `paths`-vs-`container` lifetimes cleanly
+     * separated per the C2 spec.
      */
-    private createPluginContext;
+    private buildContext;
     /**
      * Check if plugin should be enabled based on environment
      */

package/dist/plugins.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_StateContainerRegistry = require("./StateContainerRegistry-CX2CBOmv.cjs");
+const require_StateContainerRegistry = require("./StateContainerRegistry-B4yVMYbx.cjs");
 exports.PluginManager = require_StateContainerRegistry.PluginManager;
 exports.getPluginManager = require_StateContainerRegistry.getPluginManager;

package/dist/plugins.d.cts

@@ -10,8 +10,8 @@
  *
  * const myPlugin: BlacPlugin = {
  *   name: 'my-plugin',
- *   onInstanceCreated(context) {
- *     console.log('Instance created:', context.instance);
+ *   onCreated(context) {
+ *     console.log('Instance created:', context.container);
  *   },
  * };
  *

package/dist/plugins.d.ts

@@ -10,8 +10,8 @@
  *
  * const myPlugin: BlacPlugin = {
  *   name: 'my-plugin',
- *   onInstanceCreated(context) {
- *     console.log('Instance created:', context.instance);
+ *   onCreated(context) {
+ *     console.log('Instance created:', context.container);
  *   },
  * };
  *

package/dist/plugins.js

@@ -1,2 +1,2 @@
-import { n as getPluginManager, s as PluginManager } from "./StateContainerRegistry-BK57H92E.js";
+import { c as PluginManager, n as getPluginManager } from "./StateContainerRegistry-DmmzYa7S.js";
 export { PluginManager, getPluginManager };

package/dist/registry/acquire.d.ts

@@ -1,2 +1,9 @@
-import type { StateContainerConstructor } from '../types/utilities';
-export declare function acquire<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, refId?: string): InstanceType<T>;
+import type { ExtractArgs, StateContainerConstructor } from '../types/utilities';
+export declare function acquire<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, refId?: string, args?: ExtractArgs<T>): InstanceType<T>;
+/**
+ * Resolve the storage key an instance would be acquired under, given an
+ * (optional) explicit key and construction args. Callers that both acquire and
+ * release (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.
+ */
+export declare function resolveInstanceKey<T extends StateContainerConstructor>(BlocClass: T, instanceKey: string | undefined, args?: ExtractArgs<T>): string;

package/dist/registry/ensure.d.ts

@@ -1,2 +1,2 @@
-import type { StateContainerConstructor } from '../types/utilities';
-export declare function ensure<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string): InstanceType<T>;
+import type { ExtractArgs, StateContainerConstructor } from '../types/utilities';
+export declare function ensure<T extends StateContainerConstructor>(BlocClass: T, instanceKey?: string, args?: ExtractArgs<T>): InstanceType<T>;

package/dist/registry/index.d.ts

@@ -1,4 +1,4 @@
-export { acquire } from './acquire';
+export { acquire, resolveInstanceKey } from './acquire';
 export { borrow, borrowSafe } from './borrow';
 export { ensure } from './ensure';
 export { release } from './release';