@blac/core 2.0.16 → 2.0.18

package/dist/core/Cubit.d.ts

@@ -4,13 +4,13 @@ import { StateContainer } from './StateContainer';
  * public mutation surface. Today it adds nothing structurally beyond
  * `StateContainer` — both are inherited from the underlying
  * `StructuralContainer<S>`. Kept as a real class (not a type alias) because
- * downstream code does `instance instanceof Cubit` checks (see A2 audit).
+ * downstream code does `instance instanceof Cubit` checks.
  *
  * The class body is intentionally empty: a no-op `emit` override would
  * still go through `applyState`, and `patch` is inherited from
- * `StructuralContainer` (path-diffed, microtask-flushed). If a caller
- * needs the old "skip if no real change" patch semantics, they can wrap
- * `patch` themselves or call `emit` after a manual equality check.
+ * `StructuralContainer` (path-diffed, microtask-flushed). A caller that
+ * wants "skip if no real change" patch semantics can wrap `patch`
+ * themselves or call `emit` after a manual equality check.
  */
 export declare abstract class Cubit<S extends object = any, Args = void, Deps extends object = Record<string, never>> extends StateContainer<S, Args, Deps> {
 }

package/dist/core/StateContainer.d.ts

@@ -1,6 +1,43 @@
 import { StructuralContainer, type DeepPartial, type StructuralContainerOptions } from '@dirtytalk/structural';
-import type { ExtractArgs, StateContainerConstructor } from '../types/utilities';
-import { APPLY_DEPS, EMIT, REMOVE_DEPS_OWNER } from './symbols';
+import type { ExtractArgs, ExtractState, StateContainerConstructor } from '../types/utilities';
+import { APPLY_DEPS, INIT_CONFIG, REMOVE_DEPS_OWNER } from './symbols';
+import { type BlacMeta } from './meta';
+/**
+ * Brand symbol carried (non-enumerable) on every handle returned by
+ * `depend()`. Framework adapters (`@blac/react`) use this to detect handles
+ * inside a tracked-proxy and swap in a session-bound wrapper.
+ *
+ * @internal — exported for `@blac/react`; not part of the public API.
+ */
+export declare const DEP_BRAND: unique symbol;
+/**
+ * Per-access options for a {@link DepHandle}. `args` resolves the specific dep
+ * instance for this call; omit it to fall back to the default args passed to
+ * `depend()`. Args resolve at call time so they can derive from current state.
+ */
+export interface DepAccessOptions<T extends StateContainerConstructor> {
+    args?: ExtractArgs<T>;
+}
+/**
+ * Branded handle returned by `StateContainer.depend()`. Two intention-revealing
+ * accessors, no callable surface:
+ *
+ * - `handle.track(options?)` — base impl: returns `[instance.state, instance]`
+ *   live with no subscription. The React layer replaces `.track()` per-consumer
+ *   so that cross-bloc state changes trigger re-renders of the reading component.
+ * - `handle.untracked(options?)` — returns the live dep instance with no
+ *   tracking. Use for imperative calls (`.untracked().doThing()`) and one-off
+ *   state reads that should not subscribe the reader.
+ * - `handle[DEP_BRAND]` — carries `{ Type, defaultArgs }` for framework use.
+ */
+export interface DepHandle<T extends StateContainerConstructor> {
+    track(options?: DepAccessOptions<T>): [ExtractState<T>, InstanceType<T>];
+    untracked(options?: DepAccessOptions<T>): InstanceType<T>;
+    readonly [DEP_BRAND]: {
+        Type: T;
+        defaultArgs?: ExtractArgs<T>;
+    };
+}
 export interface StateContainerConfig {
     name?: string;
     debug?: boolean;
@@ -9,7 +46,6 @@ export interface StateContainerConfig {
     args?: unknown;
 }
 export type HydrationStatus = 'idle' | 'hydrating' | 'hydrated' | 'error';
-type StateListener<S> = (state: S) => void;
 export type SystemEvent = 'stateChanged' | 'dispose' | 'hydrationChanged';
 export interface SystemEventPayloads<S> {
     stateChanged: {
@@ -36,19 +72,15 @@ type SystemEventHandler<S, E extends SystemEvent> = (payload: SystemEventPayload
  *   - per-class `PathInterner`
  *
  * StateContainer layers on:
- *   - identity (`name`, `instanceId`, `createdAt`, `debug`)
- *   - lifecycle (`dispose`, `isDisposed`, `onSystemEvent`)
- *   - hydration (`beginHydration` / `applyHydratedState` / `finishHydration` / `failHydration` / `waitForHydration`)
- *   - cross-bloc deps (`depend()`, `dependencies` getter)
+ *   - identity / lifecycle / hydration (exposed via `$blac: BlacMeta`)
+ *   - cross-bloc deps (`depend()`, `$blac.dependencies`)
  *   - per-consumer deps slices (`APPLY_DEPS` / `REMOVE_DEPS_OWNER` / `onDepsChanged`)
  *   - registry integration (config-driven equality, emit-rate circuit breaker)
  *
  * Subscribers can attach via:
- *   - `subscribe(listener)` — legacy state listener (back-compat); fires on
- *     every flush with the latest state.
  *   - `onSystemEvent('stateChanged' | 'dispose' | 'hydrationChanged', cb)` —
  *     coarse lifecycle events.
- *   - `this.channel.subscribe(interest, cb)` — path-scoped (new code).
+ *   - `this.channel.subscribe(interest, cb)` — path-scoped.
  */
 export declare abstract class StateContainer<S extends object = any, Args = void, Deps extends object = Record<string, never>> extends StructuralContainer<S> {
     static __excludeFromDevTools: boolean;
@@ -87,31 +119,42 @@ export declare abstract class StateContainer<S extends object = any, Args = void
     private _emitWindowStart;
     private _emitCount;
     private _emitRateWarned;
-    private readonly _listeners;
     private readonly _systemEventHandlers;
     private _dependencies;
     private _pendingChange;
     private _bridgeUnsub;
     private _registry;
     private _equalityFn;
-    name: string;
-    debug: boolean;
-    instanceId: string;
-    createdAt: number;
-    get dependencies(): ReadonlyMap<StateContainerConstructor, string>;
+    private _name;
+    private _debug;
+    private _instanceId;
+    private _createdAt;
+    /**
+     * Reserved meta namespace: identity (`name`/`id`/`debug`/`createdAt`),
+     * lifecycle (`disposed`/`dependencies`), and the `hydration` sub-surface.
+     * Own, frozen, branded data property — `buildTrackedProxy` only intercepts
+     * prototype getters, so this own property and its closure-based getters are
+     * proxy-safe. See {@link createMeta}.
+     */
+    readonly $blac: BlacMeta<S>;
     get args(): Args | undefined;
     /**
-     * Declare a cross-bloc dependency. Returns a getter so callers write
-     * `this.user()` lazily — the dep is resolved against the registry on each
-     * call, which keeps the surface immune to dep-instance churn.
+     * Declare a cross-bloc dependency. Returns a branded handle with two
+     * accessors — the dep instance is resolved against the registry on each call,
+     * which keeps the surface immune to dep-instance churn:
+     *
+     * - `handle.track(options?)` — reactive read. Returns `[state, instance]`.
+     *   Inside a getter reached through the React proxy this subscribes the
+     *   reading component to the dep's changes (base impl: live, no subscription).
+     * - `handle.untracked(options?)` — returns the live instance with no tracking,
+     *   for imperative method calls and one-off reads.
      *
-     * Note: this does NOT auto-resubscribe to the dep's channel. Consumers that
-     * need reactive updates from a dep should subscribe explicitly (typically
-     * via the framework adapter / `useBloc`'s tracker). A naive auto-bridge
-     * here would cycle on mutual deps; the channel's same-tick coalescing
-     * limits the blast radius but a true mutual cycle is still a user bug.
+     * `defaultArgs` resolves the dep instance when an accessor is called without
+     * its own `args`; per-call `options.args` overrides it and can derive from
+     * current state. This does NOT auto-resubscribe outside the React proxy;
+     * non-React consumers needing updates should subscribe explicitly.
      */
-    protected depend<T extends StateContainerConstructor>(Type: T, args?: ExtractArgs<T>): () => InstanceType<T>;
+    protected depend<T extends StateContainerConstructor>(Type: T, defaultArgs?: ExtractArgs<T>): DepHandle<T>;
     constructor(initialState: S, options?: StructuralContainerOptions);
     /**
      * Called once after construction with the args passed at acquire time, before the first
@@ -119,43 +162,37 @@ export declare abstract class StateContainer<S extends object = any, Args = void
      * this.emit(...)) or kick off loads.
      */
     protected init(_args: Args): void;
-    initConfig(config: StateContainerConfig): void;
-    get isDisposed(): boolean;
-    get hydrationStatus(): HydrationStatus;
-    get hydrationError(): Error | undefined;
-    get isHydrated(): boolean;
-    get changedWhileHydrating(): boolean;
-    subscribe(listener: StateListener<S>): () => void;
+    /**
+     * @internal Framework-only configuration entry point (registry + testing
+     * helpers). Writes the `_`-private identity fields directly, resolves
+     * per-class equality, emits the registry `created` event, and runs `init()`
+     * once. See {@link INIT_CONFIG}.
+     */
+    [INIT_CONFIG](config: StateContainerConfig): void;
     dispose(): void;
     emit(next: S): void;
     /**
      * Override of `StructuralContainer.patch` that routes through the
      * StateContainer concerns: disposed guard, dev-only emit-rate check,
-     * `_changedWhileHydrating` flag, pending-change capture (so legacy
-     * listeners and `stateChanged` system events see the merged prev/next),
-     * and the registry-level `stateChanged` notification. We still call
+     * `_changedWhileHydrating` flag, pending-change capture (so `stateChanged`
+     * system events see the merged prev/next), and the registry-level
+     * `stateChanged` notification. We still call
      * `super.patch` so path-marking semantics (the whole point of patch) are
      * preserved.
      */
     patch(partial: DeepPartial<S>): void;
-    /**
-     * @internal @deprecated Symbol-keyed alias for `emit`. Kept only so legacy
-     * in-package tests that index with `[EMIT]` typecheck/run unchanged. C5
-     * removes this along with the `EMIT` symbol.
-     */
-    protected [EMIT](next: S): void;
     private applyState;
     /**
      * Called by the channel-bridge subscriber on each flush. Drains the
-     * pending change (if any) into legacy listeners and the 'stateChanged'
-     * system event. No pending change == flush from a no-op patch == skip.
+     * pending change (if any) into the 'stateChanged' system event.
+     * No pending change == flush from a no-op patch == skip.
      */
     private _drainPending;
-    beginHydration(): void;
-    applyHydratedState(next: S): boolean;
-    finishHydration(): void;
-    failHydration(error: Error): void;
-    waitForHydration(): Promise<void>;
+    private _beginHydration;
+    private _applyHydratedState;
+    private _finishHydration;
+    private _failHydration;
+    private _waitForHydration;
     private setHydrationStatus;
     private ensureHydrationPromise;
     private resolveHydration;

package/dist/core/StateContainerRegistry.d.ts

@@ -105,7 +105,7 @@ export declare class StateContainerRegistry {
      * You must call `release()` with the same refId when done.
      *
      * @internal Internal key tier. Public callers use the args-based `acquire`
-     *   wrapper; `useBloc`/`compat`/`watch` address a pre-resolved key here.
+     *   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
@@ -114,7 +114,7 @@ export declare class StateContainerRegistry {
      * @param options.refId - Named reference ID for debugging; auto-generated if omitted
      * @returns The state container instance
      */
-    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string | undefined, options?: {
+    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
         canCreate?: boolean;
         countRef?: boolean;
         refId?: string;
@@ -162,7 +162,7 @@ export declare class StateContainerRegistry {
      * @param args - Construction args; used for keying when no explicit key is given
      * @returns The state container instance
      */
-    ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string | undefined, args?: unknown): InstanceType<T>;
+    ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, args?: unknown): InstanceType<T>;
     /**
      * Release a reference to an instance.
      * Removes the ref and disposes when refs is empty (unless keepAlive).

package/dist/core/meta.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `$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.
+ * ──────────────────────────────────────────────────────────────────────────
+ */
+import type { HydrationStatus } from './StateContainer';
+import type { StateContainerConstructor } from '../types/utilities';
+/**
+ * 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;
+    begin(): void;
+    apply(next: S): boolean;
+    finish(): void;
+    fail(error: Error): void;
+    wait(): Promise<void>;
+}
+/**
+ * The reserved `$blac` instance member on every `StateContainer`. Gathers the
+ * container's identity/lifecycle/hydration surface (`name`, `id`, `debug`,
+ * `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.
+ */
+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>;
+}
+/**
+ * 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,27 +1,20 @@
-/**
- * @internal @deprecated Symbol-keyed mutation entry point on `StateContainer`.
- *
- * Per A2 audit (`plans/blac-core-migration/_audit.md`), this symbol has zero
- * external consumers — only in-package tests still reference it. C0 keeps it
- * as a thin alias for `emit()` so the existing test files typecheck and run
- * unchanged; C5 will port those tests to use `emit()` directly and delete
- * this symbol along with its `[EMIT]` method on `StateContainer`.
- *
- * Do not add new uses of this symbol.
- */
-export declare const EMIT: unique symbol;
 /**
  * @internal Apply one owner's (consumer's) deps slice to an instance.
  * Called by framework adapters (e.g. @blac/react useBloc) — not public API.
- *
- * Kept until D0 ports `useBloc` off the legacy adapter surface. See A2 audit
- * (`plans/blac-core-migration/_audit.md`) for the consumer list.
  */
 export declare const APPLY_DEPS: unique symbol;
 /**
  * @internal Withdraw one owner's entire deps slice (consumer unmounted).
  * Called by framework adapters — not public API.
- *
- * Kept until D0 ports `useBloc`. See A2 audit for the consumer list.
  */
 export declare const REMOVE_DEPS_OWNER: unique symbol;
+/**
+ * @internal Symbol-keyed configuration entry point on `StateContainer`.
+ * Writes the instance's identity fields (`_name`/`_debug`/`_instanceId`),
+ * resolves per-class equality, emits the registry `created` event, and runs
+ * `init()` once.
+ *
+ * Framework-only — the registry (`StateContainerRegistry.ensure`) and testing
+ * helpers are the sole callers, mirroring the `APPLY_DEPS` precedent.
+ */
+export declare const INIT_CONFIG: unique symbol;

package/dist/debug.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_StateContainerRegistry = require("./StateContainerRegistry-FWKzPfS-.cjs");
-const require_config = require("./config-DVMnlHLv.cjs");
-const require_management = require("./management-GcnNJjnm.cjs");
+const require_StateContainerRegistry = require("./StateContainerRegistry-CSNm2Ws5.cjs");
+const require_config = require("./config-C7Ktkjh2.cjs");
+const require_management = require("./management-14vsHr4t.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-B_ViBLvJ.js";
-import { n as getStats, r as setRegistry, t as getRegistry } from "./config-8pyOC5gv.js";
-import { a as getAll, c as hasInstance, i as forEach, o as getRefCount, r as register, s as getRefIds } from "./management-7jLjVHJd.js";
+import { r as globalRegistry } from "./StateContainerRegistry-CvBOhAT2.js";
+import { n as getStats, r as setRegistry, t as getRegistry } from "./config-buwpT7l3.js";
+import { a as getAll, c as hasInstance, i as forEach, o as getRefCount, r as register, s as getRefIds } from "./management-BvUAjril.js";
 export { forEach, getAll, getRefCount, getRefIds, getRegistry, getStats, globalRegistry, hasInstance, register, setRegistry };