@blac/core 2.0.17 → 2.0.18

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

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-DJQqLrli.cjs");
-const require_config = require("./config-sCPKPYxZ.cjs");
-const require_management = require("./management-DAV9sN-k.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-B1GYx9Xo.js";
-import { n as getStats, r as setRegistry, t as getRegistry } from "./config-Dk1FxfXj.js";
-import { a as getAll, c as hasInstance, i as forEach, o as getRefCount, r as register, s as getRefIds } from "./management-444tdCBG.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 };