@blac/core 2.0.12 → 2.0.14

package/dist/plugin/BlacPlugin.d.ts

@@ -1,156 +1,126 @@
+import type { PathSet } from '@dirtytalk/structural';
 import type { HydrationStatus, StateContainer } from '../core/StateContainer';
-/**
- * Metadata information about a state container instance for debugging and inspection
- */
 export interface InstanceMetadata {
-    /** Unique instance identifier */
     id: string;
-    /** Name of the state container class */
     className: string;
-    /** Whether the instance has been disposed */
     isDisposed: boolean;
-    /** Display name for the instance */
     name: string;
-    /** When state last changed (milliseconds) */
-    lastStateChangeTimestamp: number;
-    /** Current state value */
     state: any;
-    /** Timestamp when instance was created (milliseconds) */
     createdAt: number;
-    /** Stack trace from when instance was created (for debugging) */
-    callstack?: string;
-    /** Stack trace showing where the instance was first created (e.g. which useBloc/ensure call) */
-    createdFrom?: string;
-    /** Previous state value */
     previousState?: any;
-    /** Current state value */
     currentState?: any;
-    /** Current hydration status */
     hydrationStatus: HydrationStatus;
-    /** Whether hydration completed successfully */
     isHydrated: boolean;
-    /** Hydration error, if present */
     hydrationError?: Error;
-    /** Whether state changed while hydration was pending */
     changedWhileHydrating: boolean;
+    /** Args passed at acquire time; keys instance identity. */
+    args?: unknown;
 }
 /**
- * Safe context API provided to plugins for accessing registry data
+ * 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 {
     /**
-     * Get metadata for a specific instance
-     */
-    getInstanceMetadata(instance: StateContainer<any>): InstanceMetadata;
-    /**
-     * Get current state from a container
+     * 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;
-    /**
-     * Get hydration status from a container
-     */
-    getHydrationStatus(instance: StateContainer<any>): HydrationStatus;
-    /**
-     * Mark a container as hydrating
-     */
-    startHydration(instance: StateContainer<any>): void;
-    /**
-     * Apply hydrated state if the container has not been mutated while hydrating
-     * @returns true when the state was applied
-     */
+    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;
-    /**
-     * Mark hydration as finished
-     */
-    finishHydration(instance: StateContainer<any>): void;
-    /**
-     * Mark hydration as failed
-     */
-    failHydration(instance: StateContainer<any>, error: Error): void;
-    /**
-     * Wait for hydration to settle
-     */
-    waitForHydration(instance: StateContainer<any>): Promise<void>;
-    /**
-     * Get all instances of a specific type
-     */
-    queryInstances<T extends StateContainer<any>>(typeClass: new (...args: any[]) => T): T[];
-    /**
-     * Get all registered state container types
-     */
-    getAllTypes(): Array<new (...args: any[]) => StateContainer<any>>;
-    /**
-     * Get registry statistics
-     */
+    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;
         typeBreakdown: Record<string, number>;
     };
-    /**
-     * Get all active reference IDs for an instance by its instanceId string.
-     * Useful for debugging which callers are holding an instance alive.
-     */
     getRefIds(instanceId: string): string[];
 }
 /**
- * Interface for plugins that extend BlaC functionality
+ * 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 {
-    /** Unique plugin identifier */
     readonly name: string;
-    /** Plugin version identifier */
     readonly version: string;
     /**
-     * Called when the plugin is installed (optional)
+     * Fires once when the plugin is installed. `ctx.container` is `undefined`
+     * here — `onInstall` is global to the plugin, not per-container.
      */
-    onInstall?(context: PluginContext): void;
+    onInstall?(ctx: PluginContext): void;
+    onUninstall?(): void;
     /**
-     * Called when the plugin is uninstalled
+     * Fires when a container is first created and acquired.
+     * `ctx.container` is the new container.
      */
-    onUninstall?(): void;
+    onCreated?(ctx: PluginContext): void;
     /**
-     * Called when a state container instance is created
+     * 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.
      */
-    onInstanceCreated?(instance: StateContainer<any>, context: PluginContext): void;
+    onStateChange?<S extends object = any>(ctx: PluginContext, prev: S, next: S, paths: PathSet): void;
     /**
-     * Called when state changes in a container instance
+     * Fires when a container is disposed.
+     * `ctx.container` is the disposed container (still queryable, but its
+     * `isDisposed` is `true` by the time this fires).
      */
-    onStateChanged?<S extends object = any>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;
+    onDestroyed?(ctx: PluginContext): void;
     /**
-     * Called when a state container instance is disposed
+     * Fires when a container's hydration status transitions.
      */
-    onInstanceDisposed?(instance: StateContainer<any>, context: PluginContext): void;
+    onHydrationChange?(ctx: PluginContext, status: HydrationStatus, previousStatus: HydrationStatus): void;
     /**
-     * Called when a reference is acquired on an instance
+     * @internal Devtools-only — fires when a named ref is acquired.
+     * Not part of the C2 event payload contract.
      */
-    onRefAcquired?(instance: StateContainer<any>, refId: string, context: PluginContext): void;
+    onRefAcquired?(ctx: PluginContext, refId: string): void;
     /**
-     * Called when a reference is released from an instance
+     * @internal Devtools-only — fires when a named ref is released.
+     * Not part of the C2 event payload contract.
      */
-    onRefReleased?(instance: StateContainer<any>, refId: string, context: PluginContext): void;
-}
-/**
- * Plugin interface variant that requires mandatory onInstall hook
- */
-export interface BlacPluginWithInit extends BlacPlugin {
+    onRefReleased?(ctx: PluginContext, refId: string): void;
     /**
-     * Required initialization hook called when plugin is installed
+     * @internal Devtools-only — fires when the merged per-consumer deps view
+     * for a container changes.
      */
-    onInstall(context: PluginContext): void;
+    onDepsChanged?(ctx: PluginContext, previousDeps: Readonly<Record<string, unknown>>, currentDeps: Readonly<Record<string, unknown>>): void;
+}
+export interface BlacPluginWithInit extends BlacPlugin {
+    onInstall(ctx: PluginContext): void;
 }
-/**
- * Configuration options for plugin installation
- */
 export interface PluginConfig {
-    /** Enable or disable the plugin */
     enabled?: boolean;
-    /** Environments where plugin runs */
     environment?: 'development' | 'production' | 'test' | 'all';
 }
-/**
- * Type guard to check if a plugin has a required onInstall hook
- * @param plugin - The plugin to check
- * @returns true if the plugin implements BlacPluginWithInit
- */
 export declare function hasInitHook(plugin: BlacPlugin): plugin is BlacPluginWithInit;

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
@@ -13,6 +31,13 @@ import type { BlacPlugin, PluginConfig } from './BlacPlugin';
 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
@@ -52,18 +77,55 @@ export declare class PluginManager {
      * Uninstall all plugins
      */
     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-mseeTqSA.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 { i as PluginManager, n as getPluginManager } from "./StateContainerRegistry-DOuGI-l5.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';