@blac/core 2.1.0 → 2.1.1

package/dist/testing.cjs

@@ -1,8 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_StateContainerRegistry = require("./StateContainerRegistry-G81GcCRm.cjs");
-const require_ensure = require("./ensure-r1C_7K6_.cjs");
-const require_config = require("./config-C1T6Jw7n.cjs");
-const require_acquire = require("./acquire-CkgLJ8WL.cjs");
+const require_StateContainerRegistry = require("./StateContainerRegistry-DjQQtlCW.cjs");
+const require_StateContainer = require("./StateContainer-BUyuxKb3.cjs");
+const require_ensure = require("./ensure-DBnuRJ0R.cjs");
 //#region src/testing.ts
 /** Synthetic owner id used by test helpers for pre-wired deps. */
 const TESTING_DEPS_OWNER = "testing-deps";
@@ -10,39 +9,42 @@ function createTestRegistry() {
 	return new require_StateContainerRegistry.StateContainerRegistry();
 }
 function withTestRegistry(fn) {
-	const previous = require_config.getRegistry();
+	const previous = require_StateContainer.getRegistry();
 	const testRegistry = createTestRegistry();
-	require_config.setRegistry(testRegistry);
+	require_StateContainer.setRegistry(testRegistry);
 	try {
 		const result = fn(testRegistry);
 		if (result instanceof Promise) return result.then((value) => {
-			require_config.setRegistry(previous);
+			require_StateContainer.setRegistry(previous);
 			return value;
 		}, (error) => {
-			require_config.setRegistry(previous);
+			require_StateContainer.setRegistry(previous);
 			throw error;
 		});
-		require_config.setRegistry(previous);
+		require_StateContainer.setRegistry(previous);
 		return result;
 	} catch (error) {
-		require_config.setRegistry(previous);
+		require_StateContainer.setRegistry(previous);
 		throw error;
 	}
 }
 function blacTestSetup() {
 	let savedRegistry;
+	let testRegistry;
 	beforeEach(() => {
-		savedRegistry = require_config.getRegistry();
-		require_config.setRegistry(new require_StateContainerRegistry.StateContainerRegistry());
+		savedRegistry = require_StateContainer.getRegistry();
+		testRegistry = createTestRegistry();
+		require_StateContainer.setRegistry(testRegistry);
 	});
 	afterEach(() => {
-		require_config.setRegistry(savedRegistry);
+		testRegistry.clearAll();
+		require_StateContainer.setRegistry(savedRegistry);
 	});
 }
 function registerOverride(BlocClass, instance, args) {
-	const registry = require_config.getRegistry();
-	const key = require_acquire.resolveInstanceKey(BlocClass, args);
-	registry.insertInstance(BlocClass, key, instance, new Map([["testing-override", 1]]));
+	const registry = require_StateContainer.getRegistry();
+	const key = require_ensure.resolveInstanceKey(BlocClass, args);
+	registry[require_StateContainerRegistry.INSERT_INSTANCE](BlocClass, key, instance, new Map([["testing-override", 1]]));
 }
 function overrideEnsure(BlocClass, instance, fn, args) {
 	return withTestRegistry(() => {
@@ -52,14 +54,8 @@ function overrideEnsure(BlocClass, instance, fn, args) {
 }
 function createCubitStub(BlocClass, options) {
 	const instance = new BlocClass();
-	if (options?.args != null) instance[require_StateContainerRegistry.INIT_CONFIG]({ args: options.args });
-	if (options?.state != null) {
-		if (instance instanceof require_ensure.Cubit) {
-			const currentState = instance.state;
-			if (typeof currentState === "object" && currentState !== null && typeof options.state === "object" && options.state !== null) instance.patch(options.state);
-			else instance.emit(options.state);
-		}
-	}
+	instance[require_StateContainerRegistry.INIT_CONFIG]({ args: options?.args });
+	if (options?.state != null) applyState(instance, options.state);
 	if (options?.methods) {
 		for (const [key, impl] of Object.entries(options.methods)) if (typeof impl === "function") instance[key] = impl;
 	}
@@ -68,31 +64,35 @@ function createCubitStub(BlocClass, options) {
 }
 function withBlocState(BlocClass, state, args) {
 	const instance = require_ensure.ensure(BlocClass, { args });
-	if (instance instanceof require_ensure.Cubit) {
-		const currentState = instance.state;
-		if (typeof currentState === "object" && currentState !== null && typeof state === "object" && state !== null) instance.patch(state);
-		else instance.emit(state);
-	}
+	applyState(instance, state);
 	return instance;
 }
+function applyState(instance, state) {
+	const target = instance;
+	if (typeof target.state === "object" && target.state !== null && typeof state === "object" && state !== null) target.patch(state);
+	else target.emit(state);
+}
 function withBlocMethod(BlocClass, methodName, impl, args) {
 	const instance = require_ensure.ensure(BlocClass, { args });
 	instance[methodName] = impl;
 	return instance;
 }
 /**
-* Drain pending microtasks so any channel-flushed effects (channel
-* subscribers, `onSystemEvent('stateChanged')` handlers, plugin hooks) run
-* before the next assertion.
-*
-* The default `MicrotaskScheduler` coalesces emits within a tick; tests
-* that emit and then assert on subscriber side-effects need `await flush()`
-* between the two.
+* Drain pending microtasks so channel-flushed effects (subscribers,
+* `onSystemEvent('stateChanged')` handlers, plugin hooks) run before the
+* next assertion. A subscriber can emit again, so this keeps draining until
+* a round passes with no new state change.
 */
 async function flush() {
-	await Promise.resolve();
-	await Promise.resolve();
+	for (let i = 0; i < MAX_FLUSH_ROUNDS; i++) {
+		const before = require_StateContainer.getStateChangeCount();
+		await Promise.resolve();
+		await Promise.resolve();
+		if (require_StateContainer.getStateChangeCount() === before) return;
+	}
+	throw new Error(`[blac] flush(): state was still changing after ${MAX_FLUSH_ROUNDS} rounds`);
 }
+const MAX_FLUSH_ROUNDS = 100;
 //#endregion
 exports.blacTestSetup = blacTestSetup;
 exports.createCubitStub = createCubitStub;

package/dist/testing.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"testing.cjs","names":["StateContainerRegistry","getRegistry","resolveInstanceKey","INIT_CONFIG","Cubit","APPLY_DEPS","ensure"],"sources":["../src/testing.ts"],"sourcesContent":["import { Cubit } from './core/Cubit';\nimport { StateContainerRegistry } from './core/StateContainerRegistry';\nimport { APPLY_DEPS, INIT_CONFIG } from './core/symbols';\nimport { ensure, getRegistry, setRegistry } from './registry';\nimport { resolveInstanceKey } from './registry/acquire';\nimport type {\n  ExtractArgs,\n  ExtractDeps,\n  ExtractState,\n  StateContainerConstructor,\n} from './types/utilities';\n\n/** Synthetic owner id used by test helpers for pre-wired deps. */\nconst TESTING_DEPS_OWNER = 'testing-deps';\n\ndeclare const beforeEach: (fn: () => void) => void;\ndeclare const afterEach: (fn: () => void) => void;\n\n// --- createTestRegistry + withTestRegistry ---\n\nexport function createTestRegistry(): StateContainerRegistry {\n  return new StateContainerRegistry();\n}\n\nexport function withTestRegistry<T>(\n  fn: (registry: StateContainerRegistry) => T,\n): T {\n  const previous = getRegistry();\n  const testRegistry = createTestRegistry();\n  setRegistry(testRegistry);\n  try {\n    const result = fn(testRegistry);\n    if (result instanceof Promise) {\n      return result.then(\n        (value) => {\n          setRegistry(previous);\n          return value;\n        },\n        (error) => {\n          setRegistry(previous);\n          throw error;\n        },\n      ) as T;\n    }\n    setRegistry(previous);\n    return result;\n  } catch (error) {\n    setRegistry(previous);\n    throw error;\n  }\n}\n\n// --- blacTestSetup ---\n\nexport function blacTestSetup(): void {\n  let savedRegistry: StateContainerRegistry;\n  beforeEach(() => {\n    savedRegistry = getRegistry();\n    setRegistry(new StateContainerRegistry());\n  });\n  afterEach(() => {\n    setRegistry(savedRegistry);\n  });\n}\n\n// --- registerOverride + overrideEnsure ---\n\nexport function registerOverride<T extends StateContainerConstructor>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  args?: ExtractArgs<T>,\n): void {\n  const registry = getRegistry();\n  const key = resolveInstanceKey(BlocClass, args);\n  registry.insertInstance(\n    BlocClass,\n    key,\n    instance,\n    new Map([['testing-override', 1]]),\n  );\n}\n\nexport function overrideEnsure<T extends StateContainerConstructor, R>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  fn: () => R,\n  args?: ExtractArgs<T>,\n): R {\n  return withTestRegistry(() => {\n    registerOverride(BlocClass, instance, args);\n    return fn();\n  });\n}\n\n// --- createCubitStub ---\n\ntype MethodKeys<T> = {\n  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;\n}[keyof T];\n\nexport interface CubitStubOptions<T extends StateContainerConstructor> {\n  state?: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>;\n  methods?: Partial<\n    Record<MethodKeys<InstanceType<T>>, (...args: any[]) => any>\n  >;\n  /**\n   * Args to pass to init(). If the bloc's Args type is not void, supplying\n   * args here causes initConfig({ args }) to be called so init() runs.\n   */\n  args?: ExtractArgs<T> extends void ? never : ExtractArgs<T>;\n  /**\n   * Deps slice to pre-wire via the core [APPLY_DEPS] path (synthetic owner\n   * \"testing-deps\"), so onDepsChanged fires during tests.\n   */\n  deps?: Partial<ExtractDeps<T>>;\n}\n\nexport function createCubitStub<T extends StateContainerConstructor>(\n  BlocClass: T,\n  options?: CubitStubOptions<T>,\n): InstanceType<T> {\n  const instance = new BlocClass() as InstanceType<T>;\n\n  // Run init() if args are supplied — goes through the same initConfig path\n  // that the registry uses, so lifecycle hooks fire correctly.\n  if (options?.args != null) {\n    instance[INIT_CONFIG]({ args: options.args });\n  }\n\n  if (options?.state != null) {\n    if (instance instanceof Cubit) {\n      const currentState = instance.state;\n      if (\n        typeof currentState === 'object' &&\n        currentState !== null &&\n        typeof options.state === 'object' &&\n        options.state !== null\n      ) {\n        instance.patch(options.state as any);\n      } else {\n        instance.emit(options.state as any);\n      }\n    }\n  }\n  if (options?.methods) {\n    for (const [key, impl] of Object.entries(options.methods)) {\n      if (typeof impl === 'function') {\n        (instance as any)[key] = impl;\n      }\n    }\n  }\n\n  // Pre-wire deps via the core merge path so onDepsChanged fires in tests.\n  if (options?.deps != null) {\n    (instance as any)[APPLY_DEPS](TESTING_DEPS_OWNER, options.deps);\n  }\n\n  return instance;\n}\n\n// --- withBlocState ---\n\nexport function withBlocState<T extends StateContainerConstructor>(\n  BlocClass: T,\n  state: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  if (instance instanceof Cubit) {\n    const currentState = instance.state;\n    if (\n      typeof currentState === 'object' &&\n      currentState !== null &&\n      typeof state === 'object' &&\n      state !== null\n    ) {\n      instance.patch(state as any);\n    } else {\n      instance.emit(state as any);\n    }\n  }\n  return instance;\n}\n\n// --- withBlocMethod ---\n\nexport function withBlocMethod<T extends StateContainerConstructor>(\n  BlocClass: T,\n  methodName: keyof InstanceType<T>,\n  impl: (...args: any[]) => any,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  (instance as any)[methodName] = impl;\n  return instance;\n}\n\n// --- flush ---\n\n/**\n * Drain pending microtasks so any channel-flushed effects (channel\n * subscribers, `onSystemEvent('stateChanged')` handlers, plugin hooks) run\n * before the next assertion.\n *\n * The default `MicrotaskScheduler` coalesces emits within a tick; tests\n * that emit and then assert on subscriber side-effects need `await flush()`\n * between the two.\n */\nexport async function flush(): Promise<void> {\n  // queueMicrotask wins the race against the channel's own queued flush —\n  // we resolve after the channel has drained its current pending flush.\n  await Promise.resolve();\n  await Promise.resolve();\n}\n"],"mappings":";;;;;;;AAaA,MAAM,qBAAqB;AAO3B,SAAgB,qBAA6C;CAC3D,OAAO,IAAIA,+BAAAA,uBAAuB;AACpC;AAEA,SAAgB,iBACd,IACG;CACH,MAAM,WAAWC,eAAAA,YAAY;CAC7B,MAAM,eAAe,mBAAmB;CACxC,eAAA,YAAY,YAAY;CACxB,IAAI;EACF,MAAM,SAAS,GAAG,YAAY;EAC9B,IAAI,kBAAkB,SACpB,OAAO,OAAO,MACX,UAAU;GACT,eAAA,YAAY,QAAQ;GACpB,OAAO;EACT,IACC,UAAU;GACT,eAAA,YAAY,QAAQ;GACpB,MAAM;EACR,CACF;EAEF,eAAA,YAAY,QAAQ;EACpB,OAAO;CACT,SAAS,OAAO;EACd,eAAA,YAAY,QAAQ;EACpB,MAAM;CACR;AACF;AAIA,SAAgB,gBAAsB;CACpC,IAAI;CACJ,iBAAiB;EACf,gBAAgBA,eAAAA,YAAY;EAC5B,eAAA,YAAY,IAAID,+BAAAA,uBAAuB,CAAC;CAC1C,CAAC;CACD,gBAAgB;EACd,eAAA,YAAY,aAAa;CAC3B,CAAC;AACH;AAIA,SAAgB,iBACd,WACA,UACA,MACM;CACN,MAAM,WAAWC,eAAAA,YAAY;CAC7B,MAAM,MAAMC,gBAAAA,mBAAmB,WAAW,IAAI;CAC9C,SAAS,eACP,WACA,KACA,UACA,IAAI,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CACnC;AACF;AAEA,SAAgB,eACd,WACA,UACA,IACA,MACG;CACH,OAAO,uBAAuB;EAC5B,iBAAiB,WAAW,UAAU,IAAI;EAC1C,OAAO,GAAG;CACZ,CAAC;AACH;AA2BA,SAAgB,gBACd,WACA,SACiB;CACjB,MAAM,WAAW,IAAI,UAAU;CAI/B,IAAI,SAAS,QAAQ,MACnB,SAASC,+BAAAA,aAAa,EAAE,MAAM,QAAQ,KAAK,CAAC;CAG9C,IAAI,SAAS,SAAS;MAChB,oBAAoBC,eAAAA,OAAO;GAC7B,MAAM,eAAe,SAAS;GAC9B,IACE,OAAO,iBAAiB,YACxB,iBAAiB,QACjB,OAAO,QAAQ,UAAU,YACzB,QAAQ,UAAU,MAElB,SAAS,MAAM,QAAQ,KAAY;QAEnC,SAAS,KAAK,QAAQ,KAAY;EAEtC;;CAEF,IAAI,SAAS;OACN,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,QAAQ,OAAO,GACtD,IAAI,OAAO,SAAS,YAClB,SAAkB,OAAO;CAAA;CAM/B,IAAI,SAAS,QAAQ,MACnB,SAAkBC,+BAAAA,YAAY,oBAAoB,QAAQ,IAAI;CAGhE,OAAO;AACT;AAIA,SAAgB,cACd,WACA,OAGA,MACiB;CACjB,MAAM,WAAWC,eAAAA,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,IAAI,oBAAoBF,eAAAA,OAAO;EAC7B,MAAM,eAAe,SAAS;EAC9B,IACE,OAAO,iBAAiB,YACxB,iBAAiB,QACjB,OAAO,UAAU,YACjB,UAAU,MAEV,SAAS,MAAM,KAAY;OAE3B,SAAS,KAAK,KAAY;CAE9B;CACA,OAAO;AACT;AAIA,SAAgB,eACd,WACA,YACA,MACA,MACiB;CACjB,MAAM,WAAWE,eAAAA,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,SAAkB,cAAc;CAChC,OAAO;AACT;;;;;;;;;;AAaA,eAAsB,QAAuB;CAG3C,MAAM,QAAQ,QAAQ;CACtB,MAAM,QAAQ,QAAQ;AACxB"}
+{"version":3,"file":"testing.cjs","names":["StateContainerRegistry","getRegistry","resolveInstanceKey","INSERT_INSTANCE","INIT_CONFIG","APPLY_DEPS","ensure","getStateChangeCount"],"sources":["../src/testing.ts"],"sourcesContent":["import type { Cubit } from './core/Cubit';\nimport { getStateChangeCount } from './core/StateContainer';\nimport { StateContainerRegistry } from './core/StateContainerRegistry';\nimport { APPLY_DEPS, INIT_CONFIG, INSERT_INSTANCE } from './core/symbols';\nimport { ensure, getRegistry, setRegistry } from './registry';\nimport { resolveInstanceKey } from './registry/acquire';\nimport type {\n  ExtractArgs,\n  ExtractDeps,\n  ExtractState,\n  StateContainerConstructor,\n} from './types/utilities';\n\n/** Synthetic owner id used by test helpers for pre-wired deps. */\nconst TESTING_DEPS_OWNER = 'testing-deps';\n\ndeclare const beforeEach: (fn: () => void) => void;\ndeclare const afterEach: (fn: () => void) => void;\n\nexport function createTestRegistry(): StateContainerRegistry {\n  return new StateContainerRegistry();\n}\n\nexport function withTestRegistry<T>(\n  fn: (registry: StateContainerRegistry) => T,\n): T {\n  const previous = getRegistry();\n  const testRegistry = createTestRegistry();\n  setRegistry(testRegistry);\n  try {\n    const result = fn(testRegistry);\n    if (result instanceof Promise) {\n      return result.then(\n        (value) => {\n          setRegistry(previous);\n          return value;\n        },\n        (error) => {\n          setRegistry(previous);\n          throw error;\n        },\n      ) as T;\n    }\n    setRegistry(previous);\n    return result;\n  } catch (error) {\n    setRegistry(previous);\n    throw error;\n  }\n}\n\nexport function blacTestSetup(): void {\n  let savedRegistry: StateContainerRegistry;\n  let testRegistry: StateContainerRegistry;\n  beforeEach(() => {\n    savedRegistry = getRegistry();\n    testRegistry = createTestRegistry();\n    setRegistry(testRegistry);\n  });\n  afterEach(() => {\n    testRegistry.clearAll();\n    setRegistry(savedRegistry);\n  });\n}\n\nexport function registerOverride<T extends StateContainerConstructor>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  args?: ExtractArgs<T>,\n): void {\n  const registry = getRegistry();\n  const key = resolveInstanceKey(BlocClass, args);\n  registry[INSERT_INSTANCE](\n    BlocClass,\n    key,\n    instance,\n    new Map([['testing-override', 1]]),\n  );\n}\n\nexport function overrideEnsure<T extends StateContainerConstructor, R>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  fn: () => R,\n  args?: ExtractArgs<T>,\n): R {\n  return withTestRegistry(() => {\n    registerOverride(BlocClass, instance, args);\n    return fn();\n  });\n}\n\ntype MethodKeys<T> = {\n  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;\n}[keyof T];\n\nexport interface CubitStubOptions<T extends StateContainerConstructor> {\n  state?: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>;\n  methods?: Partial<\n    Record<MethodKeys<InstanceType<T>>, (...args: any[]) => any>\n  >;\n  /** Args passed to init(). */\n  args?: ExtractArgs<T> extends void ? never : ExtractArgs<T>;\n  /**\n   * Deps slice to pre-wire via the core [APPLY_DEPS] path (synthetic owner\n   * \"testing-deps\"), so onDepsChanged fires during tests.\n   */\n  deps?: Partial<ExtractDeps<T>>;\n}\n\nexport function createCubitStub<T extends StateContainerConstructor>(\n  BlocClass: T,\n  options?: CubitStubOptions<T>,\n): InstanceType<T> {\n  const instance = new BlocClass() as InstanceType<T>;\n  instance[INIT_CONFIG]({ args: options?.args });\n\n  if (options?.state != null) {\n    applyState(instance, options.state);\n  }\n  if (options?.methods) {\n    for (const [key, impl] of Object.entries(options.methods)) {\n      if (typeof impl === 'function') {\n        (instance as any)[key] = impl;\n      }\n    }\n  }\n\n  // Pre-wire deps via the core merge path so onDepsChanged fires in tests.\n  if (options?.deps != null) {\n    (instance as any)[APPLY_DEPS](TESTING_DEPS_OWNER, options.deps);\n  }\n\n  return instance;\n}\n\nexport function withBlocState<T extends StateContainerConstructor>(\n  BlocClass: T,\n  state: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  applyState(instance, state);\n  return instance;\n}\n\n// emit/patch are protected on StateContainer; Cubit only makes them public.\nfunction applyState(instance: object, state: unknown): void {\n  const target = instance as Cubit<any>;\n  if (\n    typeof target.state === 'object' &&\n    target.state !== null &&\n    typeof state === 'object' &&\n    state !== null\n  ) {\n    target.patch(state);\n  } else {\n    target.emit(state as any);\n  }\n}\n\nexport function withBlocMethod<T extends StateContainerConstructor>(\n  BlocClass: T,\n  methodName: keyof InstanceType<T>,\n  impl: (...args: any[]) => any,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  (instance as any)[methodName] = impl;\n  return instance;\n}\n\n/**\n * Drain pending microtasks so channel-flushed effects (subscribers,\n * `onSystemEvent('stateChanged')` handlers, plugin hooks) run before the\n * next assertion. A subscriber can emit again, so this keeps draining until\n * a round passes with no new state change.\n */\nexport async function flush(): Promise<void> {\n  for (let i = 0; i < MAX_FLUSH_ROUNDS; i++) {\n    const before = getStateChangeCount();\n    // The second tick lets microtasks queued by the drain itself (registry\n    // `stateChanged` delivery) run too.\n    await Promise.resolve();\n    await Promise.resolve();\n    if (getStateChangeCount() === before) return;\n  }\n  throw new Error(\n    `[blac] flush(): state was still changing after ${MAX_FLUSH_ROUNDS} rounds`,\n  );\n}\n\nconst MAX_FLUSH_ROUNDS = 100;\n"],"mappings":";;;;;;AAcA,MAAM,qBAAqB;AAK3B,SAAgB,qBAA6C;CAC3D,OAAO,IAAIA,+BAAAA,uBAAuB;AACpC;AAEA,SAAgB,iBACd,IACG;CACH,MAAM,WAAWC,uBAAAA,YAAY;CAC7B,MAAM,eAAe,mBAAmB;CACxC,uBAAA,YAAY,YAAY;CACxB,IAAI;EACF,MAAM,SAAS,GAAG,YAAY;EAC9B,IAAI,kBAAkB,SACpB,OAAO,OAAO,MACX,UAAU;GACT,uBAAA,YAAY,QAAQ;GACpB,OAAO;EACT,IACC,UAAU;GACT,uBAAA,YAAY,QAAQ;GACpB,MAAM;EACR,CACF;EAEF,uBAAA,YAAY,QAAQ;EACpB,OAAO;CACT,SAAS,OAAO;EACd,uBAAA,YAAY,QAAQ;EACpB,MAAM;CACR;AACF;AAEA,SAAgB,gBAAsB;CACpC,IAAI;CACJ,IAAI;CACJ,iBAAiB;EACf,gBAAgBA,uBAAAA,YAAY;EAC5B,eAAe,mBAAmB;EAClC,uBAAA,YAAY,YAAY;CAC1B,CAAC;CACD,gBAAgB;EACd,aAAa,SAAS;EACtB,uBAAA,YAAY,aAAa;CAC3B,CAAC;AACH;AAEA,SAAgB,iBACd,WACA,UACA,MACM;CACN,MAAM,WAAWA,uBAAAA,YAAY;CAC7B,MAAM,MAAMC,eAAAA,mBAAmB,WAAW,IAAI;CAC9C,SAASC,+BAAAA,iBACP,WACA,KACA,UACA,IAAI,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CACnC;AACF;AAEA,SAAgB,eACd,WACA,UACA,IACA,MACG;CACH,OAAO,uBAAuB;EAC5B,iBAAiB,WAAW,UAAU,IAAI;EAC1C,OAAO,GAAG;CACZ,CAAC;AACH;AAsBA,SAAgB,gBACd,WACA,SACiB;CACjB,MAAM,WAAW,IAAI,UAAU;CAC/B,SAASC,+BAAAA,aAAa,EAAE,MAAM,SAAS,KAAK,CAAC;CAE7C,IAAI,SAAS,SAAS,MACpB,WAAW,UAAU,QAAQ,KAAK;CAEpC,IAAI,SAAS;OACN,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,QAAQ,OAAO,GACtD,IAAI,OAAO,SAAS,YAClB,SAAkB,OAAO;CAAA;CAM/B,IAAI,SAAS,QAAQ,MACnB,SAAkBC,+BAAAA,YAAY,oBAAoB,QAAQ,IAAI;CAGhE,OAAO;AACT;AAEA,SAAgB,cACd,WACA,OAGA,MACiB;CACjB,MAAM,WAAWC,eAAAA,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,WAAW,UAAU,KAAK;CAC1B,OAAO;AACT;AAGA,SAAS,WAAW,UAAkB,OAAsB;CAC1D,MAAM,SAAS;CACf,IACE,OAAO,OAAO,UAAU,YACxB,OAAO,UAAU,QACjB,OAAO,UAAU,YACjB,UAAU,MAEV,OAAO,MAAM,KAAK;MAElB,OAAO,KAAK,KAAY;AAE5B;AAEA,SAAgB,eACd,WACA,YACA,MACA,MACiB;CACjB,MAAM,WAAWA,eAAAA,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,SAAkB,cAAc;CAChC,OAAO;AACT;;;;;;;AAQA,eAAsB,QAAuB;CAC3C,KAAK,IAAI,IAAI,GAAG,IAAI,kBAAkB,KAAK;EACzC,MAAM,SAASC,uBAAAA,oBAAoB;EAGnC,MAAM,QAAQ,QAAQ;EACtB,MAAM,QAAQ,QAAQ;EACtB,IAAIA,uBAAAA,oBAAoB,MAAM,QAAQ;CACxC;CACA,MAAM,IAAI,MACR,kDAAkD,iBAAiB,QACrE;AACF;AAEA,MAAM,mBAAmB"}

package/dist/testing.d.cts

@@ -11,10 +11,7 @@ type MethodKeys<T> = {
 export interface CubitStubOptions<T extends StateContainerConstructor> {
     state?: ExtractState<T> extends Record<string, any> ? Partial<ExtractState<T>> : ExtractState<T>;
     methods?: Partial<Record<MethodKeys<InstanceType<T>>, (...args: any[]) => any>>;
-    /**
-     * Args to pass to init(). If the bloc's Args type is not void, supplying
-     * args here causes initConfig({ args }) to be called so init() runs.
-     */
+    /** Args passed to init(). */
     args?: ExtractArgs<T> extends void ? never : ExtractArgs<T>;
     /**
      * Deps slice to pre-wire via the core [APPLY_DEPS] path (synthetic owner
@@ -26,13 +23,10 @@ export declare function createCubitStub<T extends StateContainerConstructor>(Blo
 export declare function withBlocState<T extends StateContainerConstructor>(BlocClass: T, state: ExtractState<T> extends Record<string, any> ? Partial<ExtractState<T>> : ExtractState<T>, args?: ExtractArgs<T>): InstanceType<T>;
 export declare function withBlocMethod<T extends StateContainerConstructor>(BlocClass: T, methodName: keyof InstanceType<T>, impl: (...args: any[]) => any, args?: ExtractArgs<T>): InstanceType<T>;
 /**
- * Drain pending microtasks so any channel-flushed effects (channel
- * subscribers, `onSystemEvent('stateChanged')` handlers, plugin hooks) run
- * before the next assertion.
- *
- * The default `MicrotaskScheduler` coalesces emits within a tick; tests
- * that emit and then assert on subscriber side-effects need `await flush()`
- * between the two.
+ * Drain pending microtasks so channel-flushed effects (subscribers,
+ * `onSystemEvent('stateChanged')` handlers, plugin hooks) run before the
+ * next assertion. A subscriber can emit again, so this keeps draining until
+ * a round passes with no new state change.
  */
 export declare function flush(): Promise<void>;
 export {};

package/dist/testing.d.ts

@@ -11,10 +11,7 @@ type MethodKeys<T> = {
 export interface CubitStubOptions<T extends StateContainerConstructor> {
     state?: ExtractState<T> extends Record<string, any> ? Partial<ExtractState<T>> : ExtractState<T>;
     methods?: Partial<Record<MethodKeys<InstanceType<T>>, (...args: any[]) => any>>;
-    /**
-     * Args to pass to init(). If the bloc's Args type is not void, supplying
-     * args here causes initConfig({ args }) to be called so init() runs.
-     */
+    /** Args passed to init(). */
     args?: ExtractArgs<T> extends void ? never : ExtractArgs<T>;
     /**
      * Deps slice to pre-wire via the core [APPLY_DEPS] path (synthetic owner
@@ -26,13 +23,10 @@ export declare function createCubitStub<T extends StateContainerConstructor>(Blo
 export declare function withBlocState<T extends StateContainerConstructor>(BlocClass: T, state: ExtractState<T> extends Record<string, any> ? Partial<ExtractState<T>> : ExtractState<T>, args?: ExtractArgs<T>): InstanceType<T>;
 export declare function withBlocMethod<T extends StateContainerConstructor>(BlocClass: T, methodName: keyof InstanceType<T>, impl: (...args: any[]) => any, args?: ExtractArgs<T>): InstanceType<T>;
 /**
- * Drain pending microtasks so any channel-flushed effects (channel
- * subscribers, `onSystemEvent('stateChanged')` handlers, plugin hooks) run
- * before the next assertion.
- *
- * The default `MicrotaskScheduler` coalesces emits within a tick; tests
- * that emit and then assert on subscriber side-effects need `await flush()`
- * between the two.
+ * Drain pending microtasks so channel-flushed effects (subscribers,
+ * `onSystemEvent('stateChanged')` handlers, plugin hooks) run before the
+ * next assertion. A subscriber can emit again, so this keeps draining until
+ * a round passes with no new state change.
  */
 export declare function flush(): Promise<void>;
 export {};

package/dist/testing.js

@@ -1,7 +1,6 @@
-import { a as INIT_CONFIG, i as APPLY_DEPS, t as StateContainerRegistry } from "./StateContainerRegistry-DWOzx7Gd.js";
-import { n as Cubit, t as ensure } from "./ensure-11-asM1e.js";
-import { r as setRegistry, t as getRegistry } from "./config-D2A8ZYRM.js";
-import { n as resolveInstanceKey } from "./acquire-CU0u8BMn.js";
+import { a as INSERT_INSTANCE, i as INIT_CONFIG, r as APPLY_DEPS, t as StateContainerRegistry } from "./StateContainerRegistry-gQbEutkN.js";
+import { i as getRegistry, o as setRegistry, r as getStateChangeCount } from "./StateContainer-Bh2ipNYj.js";
+import { r as resolveInstanceKey, t as ensure } from "./ensure-Bi_yXk6f.js";
 //#region src/testing.ts
 /** Synthetic owner id used by test helpers for pre-wired deps. */
 const TESTING_DEPS_OWNER = "testing-deps";
@@ -30,18 +29,21 @@ function withTestRegistry(fn) {
 }
 function blacTestSetup() {
 	let savedRegistry;
+	let testRegistry;
 	beforeEach(() => {
 		savedRegistry = getRegistry();
-		setRegistry(new StateContainerRegistry());
+		testRegistry = createTestRegistry();
+		setRegistry(testRegistry);
 	});
 	afterEach(() => {
+		testRegistry.clearAll();
 		setRegistry(savedRegistry);
 	});
 }
 function registerOverride(BlocClass, instance, args) {
 	const registry = getRegistry();
 	const key = resolveInstanceKey(BlocClass, args);
-	registry.insertInstance(BlocClass, key, instance, new Map([["testing-override", 1]]));
+	registry[INSERT_INSTANCE](BlocClass, key, instance, new Map([["testing-override", 1]]));
 }
 function overrideEnsure(BlocClass, instance, fn, args) {
 	return withTestRegistry(() => {
@@ -51,14 +53,8 @@ function overrideEnsure(BlocClass, instance, fn, args) {
 }
 function createCubitStub(BlocClass, options) {
 	const instance = new BlocClass();
-	if (options?.args != null) instance[INIT_CONFIG]({ args: options.args });
-	if (options?.state != null) {
-		if (instance instanceof Cubit) {
-			const currentState = instance.state;
-			if (typeof currentState === "object" && currentState !== null && typeof options.state === "object" && options.state !== null) instance.patch(options.state);
-			else instance.emit(options.state);
-		}
-	}
+	instance[INIT_CONFIG]({ args: options?.args });
+	if (options?.state != null) applyState(instance, options.state);
 	if (options?.methods) {
 		for (const [key, impl] of Object.entries(options.methods)) if (typeof impl === "function") instance[key] = impl;
 	}
@@ -67,31 +63,35 @@ function createCubitStub(BlocClass, options) {
 }
 function withBlocState(BlocClass, state, args) {
 	const instance = ensure(BlocClass, { args });
-	if (instance instanceof Cubit) {
-		const currentState = instance.state;
-		if (typeof currentState === "object" && currentState !== null && typeof state === "object" && state !== null) instance.patch(state);
-		else instance.emit(state);
-	}
+	applyState(instance, state);
 	return instance;
 }
+function applyState(instance, state) {
+	const target = instance;
+	if (typeof target.state === "object" && target.state !== null && typeof state === "object" && state !== null) target.patch(state);
+	else target.emit(state);
+}
 function withBlocMethod(BlocClass, methodName, impl, args) {
 	const instance = ensure(BlocClass, { args });
 	instance[methodName] = impl;
 	return instance;
 }
 /**
-* Drain pending microtasks so any channel-flushed effects (channel
-* subscribers, `onSystemEvent('stateChanged')` handlers, plugin hooks) run
-* before the next assertion.
-*
-* The default `MicrotaskScheduler` coalesces emits within a tick; tests
-* that emit and then assert on subscriber side-effects need `await flush()`
-* between the two.
+* Drain pending microtasks so channel-flushed effects (subscribers,
+* `onSystemEvent('stateChanged')` handlers, plugin hooks) run before the
+* next assertion. A subscriber can emit again, so this keeps draining until
+* a round passes with no new state change.
 */
 async function flush() {
-	await Promise.resolve();
-	await Promise.resolve();
+	for (let i = 0; i < MAX_FLUSH_ROUNDS; i++) {
+		const before = getStateChangeCount();
+		await Promise.resolve();
+		await Promise.resolve();
+		if (getStateChangeCount() === before) return;
+	}
+	throw new Error(`[blac] flush(): state was still changing after ${MAX_FLUSH_ROUNDS} rounds`);
 }
+const MAX_FLUSH_ROUNDS = 100;
 //#endregion
 export { blacTestSetup, createCubitStub, createTestRegistry, flush, overrideEnsure, registerOverride, withBlocMethod, withBlocState, withTestRegistry };
 

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import { Cubit } from './core/Cubit';\nimport { StateContainerRegistry } from './core/StateContainerRegistry';\nimport { APPLY_DEPS, INIT_CONFIG } from './core/symbols';\nimport { ensure, getRegistry, setRegistry } from './registry';\nimport { resolveInstanceKey } from './registry/acquire';\nimport type {\n  ExtractArgs,\n  ExtractDeps,\n  ExtractState,\n  StateContainerConstructor,\n} from './types/utilities';\n\n/** Synthetic owner id used by test helpers for pre-wired deps. */\nconst TESTING_DEPS_OWNER = 'testing-deps';\n\ndeclare const beforeEach: (fn: () => void) => void;\ndeclare const afterEach: (fn: () => void) => void;\n\n// --- createTestRegistry + withTestRegistry ---\n\nexport function createTestRegistry(): StateContainerRegistry {\n  return new StateContainerRegistry();\n}\n\nexport function withTestRegistry<T>(\n  fn: (registry: StateContainerRegistry) => T,\n): T {\n  const previous = getRegistry();\n  const testRegistry = createTestRegistry();\n  setRegistry(testRegistry);\n  try {\n    const result = fn(testRegistry);\n    if (result instanceof Promise) {\n      return result.then(\n        (value) => {\n          setRegistry(previous);\n          return value;\n        },\n        (error) => {\n          setRegistry(previous);\n          throw error;\n        },\n      ) as T;\n    }\n    setRegistry(previous);\n    return result;\n  } catch (error) {\n    setRegistry(previous);\n    throw error;\n  }\n}\n\n// --- blacTestSetup ---\n\nexport function blacTestSetup(): void {\n  let savedRegistry: StateContainerRegistry;\n  beforeEach(() => {\n    savedRegistry = getRegistry();\n    setRegistry(new StateContainerRegistry());\n  });\n  afterEach(() => {\n    setRegistry(savedRegistry);\n  });\n}\n\n// --- registerOverride + overrideEnsure ---\n\nexport function registerOverride<T extends StateContainerConstructor>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  args?: ExtractArgs<T>,\n): void {\n  const registry = getRegistry();\n  const key = resolveInstanceKey(BlocClass, args);\n  registry.insertInstance(\n    BlocClass,\n    key,\n    instance,\n    new Map([['testing-override', 1]]),\n  );\n}\n\nexport function overrideEnsure<T extends StateContainerConstructor, R>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  fn: () => R,\n  args?: ExtractArgs<T>,\n): R {\n  return withTestRegistry(() => {\n    registerOverride(BlocClass, instance, args);\n    return fn();\n  });\n}\n\n// --- createCubitStub ---\n\ntype MethodKeys<T> = {\n  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;\n}[keyof T];\n\nexport interface CubitStubOptions<T extends StateContainerConstructor> {\n  state?: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>;\n  methods?: Partial<\n    Record<MethodKeys<InstanceType<T>>, (...args: any[]) => any>\n  >;\n  /**\n   * Args to pass to init(). If the bloc's Args type is not void, supplying\n   * args here causes initConfig({ args }) to be called so init() runs.\n   */\n  args?: ExtractArgs<T> extends void ? never : ExtractArgs<T>;\n  /**\n   * Deps slice to pre-wire via the core [APPLY_DEPS] path (synthetic owner\n   * \"testing-deps\"), so onDepsChanged fires during tests.\n   */\n  deps?: Partial<ExtractDeps<T>>;\n}\n\nexport function createCubitStub<T extends StateContainerConstructor>(\n  BlocClass: T,\n  options?: CubitStubOptions<T>,\n): InstanceType<T> {\n  const instance = new BlocClass() as InstanceType<T>;\n\n  // Run init() if args are supplied — goes through the same initConfig path\n  // that the registry uses, so lifecycle hooks fire correctly.\n  if (options?.args != null) {\n    instance[INIT_CONFIG]({ args: options.args });\n  }\n\n  if (options?.state != null) {\n    if (instance instanceof Cubit) {\n      const currentState = instance.state;\n      if (\n        typeof currentState === 'object' &&\n        currentState !== null &&\n        typeof options.state === 'object' &&\n        options.state !== null\n      ) {\n        instance.patch(options.state as any);\n      } else {\n        instance.emit(options.state as any);\n      }\n    }\n  }\n  if (options?.methods) {\n    for (const [key, impl] of Object.entries(options.methods)) {\n      if (typeof impl === 'function') {\n        (instance as any)[key] = impl;\n      }\n    }\n  }\n\n  // Pre-wire deps via the core merge path so onDepsChanged fires in tests.\n  if (options?.deps != null) {\n    (instance as any)[APPLY_DEPS](TESTING_DEPS_OWNER, options.deps);\n  }\n\n  return instance;\n}\n\n// --- withBlocState ---\n\nexport function withBlocState<T extends StateContainerConstructor>(\n  BlocClass: T,\n  state: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  if (instance instanceof Cubit) {\n    const currentState = instance.state;\n    if (\n      typeof currentState === 'object' &&\n      currentState !== null &&\n      typeof state === 'object' &&\n      state !== null\n    ) {\n      instance.patch(state as any);\n    } else {\n      instance.emit(state as any);\n    }\n  }\n  return instance;\n}\n\n// --- withBlocMethod ---\n\nexport function withBlocMethod<T extends StateContainerConstructor>(\n  BlocClass: T,\n  methodName: keyof InstanceType<T>,\n  impl: (...args: any[]) => any,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  (instance as any)[methodName] = impl;\n  return instance;\n}\n\n// --- flush ---\n\n/**\n * Drain pending microtasks so any channel-flushed effects (channel\n * subscribers, `onSystemEvent('stateChanged')` handlers, plugin hooks) run\n * before the next assertion.\n *\n * The default `MicrotaskScheduler` coalesces emits within a tick; tests\n * that emit and then assert on subscriber side-effects need `await flush()`\n * between the two.\n */\nexport async function flush(): Promise<void> {\n  // queueMicrotask wins the race against the channel's own queued flush —\n  // we resolve after the channel has drained its current pending flush.\n  await Promise.resolve();\n  await Promise.resolve();\n}\n"],"mappings":";;;;;;AAaA,MAAM,qBAAqB;AAO3B,SAAgB,qBAA6C;CAC3D,OAAO,IAAI,uBAAuB;AACpC;AAEA,SAAgB,iBACd,IACG;CACH,MAAM,WAAW,YAAY;CAC7B,MAAM,eAAe,mBAAmB;CACxC,YAAY,YAAY;CACxB,IAAI;EACF,MAAM,SAAS,GAAG,YAAY;EAC9B,IAAI,kBAAkB,SACpB,OAAO,OAAO,MACX,UAAU;GACT,YAAY,QAAQ;GACpB,OAAO;EACT,IACC,UAAU;GACT,YAAY,QAAQ;GACpB,MAAM;EACR,CACF;EAEF,YAAY,QAAQ;EACpB,OAAO;CACT,SAAS,OAAO;EACd,YAAY,QAAQ;EACpB,MAAM;CACR;AACF;AAIA,SAAgB,gBAAsB;CACpC,IAAI;CACJ,iBAAiB;EACf,gBAAgB,YAAY;EAC5B,YAAY,IAAI,uBAAuB,CAAC;CAC1C,CAAC;CACD,gBAAgB;EACd,YAAY,aAAa;CAC3B,CAAC;AACH;AAIA,SAAgB,iBACd,WACA,UACA,MACM;CACN,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,mBAAmB,WAAW,IAAI;CAC9C,SAAS,eACP,WACA,KACA,UACA,IAAI,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CACnC;AACF;AAEA,SAAgB,eACd,WACA,UACA,IACA,MACG;CACH,OAAO,uBAAuB;EAC5B,iBAAiB,WAAW,UAAU,IAAI;EAC1C,OAAO,GAAG;CACZ,CAAC;AACH;AA2BA,SAAgB,gBACd,WACA,SACiB;CACjB,MAAM,WAAW,IAAI,UAAU;CAI/B,IAAI,SAAS,QAAQ,MACnB,SAAS,aAAa,EAAE,MAAM,QAAQ,KAAK,CAAC;CAG9C,IAAI,SAAS,SAAS;MAChB,oBAAoB,OAAO;GAC7B,MAAM,eAAe,SAAS;GAC9B,IACE,OAAO,iBAAiB,YACxB,iBAAiB,QACjB,OAAO,QAAQ,UAAU,YACzB,QAAQ,UAAU,MAElB,SAAS,MAAM,QAAQ,KAAY;QAEnC,SAAS,KAAK,QAAQ,KAAY;EAEtC;;CAEF,IAAI,SAAS;OACN,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,QAAQ,OAAO,GACtD,IAAI,OAAO,SAAS,YAClB,SAAkB,OAAO;CAAA;CAM/B,IAAI,SAAS,QAAQ,MACnB,SAAkB,YAAY,oBAAoB,QAAQ,IAAI;CAGhE,OAAO;AACT;AAIA,SAAgB,cACd,WACA,OAGA,MACiB;CACjB,MAAM,WAAW,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,IAAI,oBAAoB,OAAO;EAC7B,MAAM,eAAe,SAAS;EAC9B,IACE,OAAO,iBAAiB,YACxB,iBAAiB,QACjB,OAAO,UAAU,YACjB,UAAU,MAEV,SAAS,MAAM,KAAY;OAE3B,SAAS,KAAK,KAAY;CAE9B;CACA,OAAO;AACT;AAIA,SAAgB,eACd,WACA,YACA,MACA,MACiB;CACjB,MAAM,WAAW,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,SAAkB,cAAc;CAChC,OAAO;AACT;;;;;;;;;;AAaA,eAAsB,QAAuB;CAG3C,MAAM,QAAQ,QAAQ;CACtB,MAAM,QAAQ,QAAQ;AACxB"}
+{"version":3,"file":"testing.js","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import type { Cubit } from './core/Cubit';\nimport { getStateChangeCount } from './core/StateContainer';\nimport { StateContainerRegistry } from './core/StateContainerRegistry';\nimport { APPLY_DEPS, INIT_CONFIG, INSERT_INSTANCE } from './core/symbols';\nimport { ensure, getRegistry, setRegistry } from './registry';\nimport { resolveInstanceKey } from './registry/acquire';\nimport type {\n  ExtractArgs,\n  ExtractDeps,\n  ExtractState,\n  StateContainerConstructor,\n} from './types/utilities';\n\n/** Synthetic owner id used by test helpers for pre-wired deps. */\nconst TESTING_DEPS_OWNER = 'testing-deps';\n\ndeclare const beforeEach: (fn: () => void) => void;\ndeclare const afterEach: (fn: () => void) => void;\n\nexport function createTestRegistry(): StateContainerRegistry {\n  return new StateContainerRegistry();\n}\n\nexport function withTestRegistry<T>(\n  fn: (registry: StateContainerRegistry) => T,\n): T {\n  const previous = getRegistry();\n  const testRegistry = createTestRegistry();\n  setRegistry(testRegistry);\n  try {\n    const result = fn(testRegistry);\n    if (result instanceof Promise) {\n      return result.then(\n        (value) => {\n          setRegistry(previous);\n          return value;\n        },\n        (error) => {\n          setRegistry(previous);\n          throw error;\n        },\n      ) as T;\n    }\n    setRegistry(previous);\n    return result;\n  } catch (error) {\n    setRegistry(previous);\n    throw error;\n  }\n}\n\nexport function blacTestSetup(): void {\n  let savedRegistry: StateContainerRegistry;\n  let testRegistry: StateContainerRegistry;\n  beforeEach(() => {\n    savedRegistry = getRegistry();\n    testRegistry = createTestRegistry();\n    setRegistry(testRegistry);\n  });\n  afterEach(() => {\n    testRegistry.clearAll();\n    setRegistry(savedRegistry);\n  });\n}\n\nexport function registerOverride<T extends StateContainerConstructor>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  args?: ExtractArgs<T>,\n): void {\n  const registry = getRegistry();\n  const key = resolveInstanceKey(BlocClass, args);\n  registry[INSERT_INSTANCE](\n    BlocClass,\n    key,\n    instance,\n    new Map([['testing-override', 1]]),\n  );\n}\n\nexport function overrideEnsure<T extends StateContainerConstructor, R>(\n  BlocClass: T,\n  instance: InstanceType<T>,\n  fn: () => R,\n  args?: ExtractArgs<T>,\n): R {\n  return withTestRegistry(() => {\n    registerOverride(BlocClass, instance, args);\n    return fn();\n  });\n}\n\ntype MethodKeys<T> = {\n  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;\n}[keyof T];\n\nexport interface CubitStubOptions<T extends StateContainerConstructor> {\n  state?: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>;\n  methods?: Partial<\n    Record<MethodKeys<InstanceType<T>>, (...args: any[]) => any>\n  >;\n  /** Args passed to init(). */\n  args?: ExtractArgs<T> extends void ? never : ExtractArgs<T>;\n  /**\n   * Deps slice to pre-wire via the core [APPLY_DEPS] path (synthetic owner\n   * \"testing-deps\"), so onDepsChanged fires during tests.\n   */\n  deps?: Partial<ExtractDeps<T>>;\n}\n\nexport function createCubitStub<T extends StateContainerConstructor>(\n  BlocClass: T,\n  options?: CubitStubOptions<T>,\n): InstanceType<T> {\n  const instance = new BlocClass() as InstanceType<T>;\n  instance[INIT_CONFIG]({ args: options?.args });\n\n  if (options?.state != null) {\n    applyState(instance, options.state);\n  }\n  if (options?.methods) {\n    for (const [key, impl] of Object.entries(options.methods)) {\n      if (typeof impl === 'function') {\n        (instance as any)[key] = impl;\n      }\n    }\n  }\n\n  // Pre-wire deps via the core merge path so onDepsChanged fires in tests.\n  if (options?.deps != null) {\n    (instance as any)[APPLY_DEPS](TESTING_DEPS_OWNER, options.deps);\n  }\n\n  return instance;\n}\n\nexport function withBlocState<T extends StateContainerConstructor>(\n  BlocClass: T,\n  state: ExtractState<T> extends Record<string, any>\n    ? Partial<ExtractState<T>>\n    : ExtractState<T>,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  applyState(instance, state);\n  return instance;\n}\n\n// emit/patch are protected on StateContainer; Cubit only makes them public.\nfunction applyState(instance: object, state: unknown): void {\n  const target = instance as Cubit<any>;\n  if (\n    typeof target.state === 'object' &&\n    target.state !== null &&\n    typeof state === 'object' &&\n    state !== null\n  ) {\n    target.patch(state);\n  } else {\n    target.emit(state as any);\n  }\n}\n\nexport function withBlocMethod<T extends StateContainerConstructor>(\n  BlocClass: T,\n  methodName: keyof InstanceType<T>,\n  impl: (...args: any[]) => any,\n  args?: ExtractArgs<T>,\n): InstanceType<T> {\n  const instance = ensure(BlocClass, { args });\n  (instance as any)[methodName] = impl;\n  return instance;\n}\n\n/**\n * Drain pending microtasks so channel-flushed effects (subscribers,\n * `onSystemEvent('stateChanged')` handlers, plugin hooks) run before the\n * next assertion. A subscriber can emit again, so this keeps draining until\n * a round passes with no new state change.\n */\nexport async function flush(): Promise<void> {\n  for (let i = 0; i < MAX_FLUSH_ROUNDS; i++) {\n    const before = getStateChangeCount();\n    // The second tick lets microtasks queued by the drain itself (registry\n    // `stateChanged` delivery) run too.\n    await Promise.resolve();\n    await Promise.resolve();\n    if (getStateChangeCount() === before) return;\n  }\n  throw new Error(\n    `[blac] flush(): state was still changing after ${MAX_FLUSH_ROUNDS} rounds`,\n  );\n}\n\nconst MAX_FLUSH_ROUNDS = 100;\n"],"mappings":";;;;;AAcA,MAAM,qBAAqB;AAK3B,SAAgB,qBAA6C;CAC3D,OAAO,IAAI,uBAAuB;AACpC;AAEA,SAAgB,iBACd,IACG;CACH,MAAM,WAAW,YAAY;CAC7B,MAAM,eAAe,mBAAmB;CACxC,YAAY,YAAY;CACxB,IAAI;EACF,MAAM,SAAS,GAAG,YAAY;EAC9B,IAAI,kBAAkB,SACpB,OAAO,OAAO,MACX,UAAU;GACT,YAAY,QAAQ;GACpB,OAAO;EACT,IACC,UAAU;GACT,YAAY,QAAQ;GACpB,MAAM;EACR,CACF;EAEF,YAAY,QAAQ;EACpB,OAAO;CACT,SAAS,OAAO;EACd,YAAY,QAAQ;EACpB,MAAM;CACR;AACF;AAEA,SAAgB,gBAAsB;CACpC,IAAI;CACJ,IAAI;CACJ,iBAAiB;EACf,gBAAgB,YAAY;EAC5B,eAAe,mBAAmB;EAClC,YAAY,YAAY;CAC1B,CAAC;CACD,gBAAgB;EACd,aAAa,SAAS;EACtB,YAAY,aAAa;CAC3B,CAAC;AACH;AAEA,SAAgB,iBACd,WACA,UACA,MACM;CACN,MAAM,WAAW,YAAY;CAC7B,MAAM,MAAM,mBAAmB,WAAW,IAAI;CAC9C,SAAS,iBACP,WACA,KACA,UACA,IAAI,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CACnC;AACF;AAEA,SAAgB,eACd,WACA,UACA,IACA,MACG;CACH,OAAO,uBAAuB;EAC5B,iBAAiB,WAAW,UAAU,IAAI;EAC1C,OAAO,GAAG;CACZ,CAAC;AACH;AAsBA,SAAgB,gBACd,WACA,SACiB;CACjB,MAAM,WAAW,IAAI,UAAU;CAC/B,SAAS,aAAa,EAAE,MAAM,SAAS,KAAK,CAAC;CAE7C,IAAI,SAAS,SAAS,MACpB,WAAW,UAAU,QAAQ,KAAK;CAEpC,IAAI,SAAS;OACN,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,QAAQ,OAAO,GACtD,IAAI,OAAO,SAAS,YAClB,SAAkB,OAAO;CAAA;CAM/B,IAAI,SAAS,QAAQ,MACnB,SAAkB,YAAY,oBAAoB,QAAQ,IAAI;CAGhE,OAAO;AACT;AAEA,SAAgB,cACd,WACA,OAGA,MACiB;CACjB,MAAM,WAAW,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,WAAW,UAAU,KAAK;CAC1B,OAAO;AACT;AAGA,SAAS,WAAW,UAAkB,OAAsB;CAC1D,MAAM,SAAS;CACf,IACE,OAAO,OAAO,UAAU,YACxB,OAAO,UAAU,QACjB,OAAO,UAAU,YACjB,UAAU,MAEV,OAAO,MAAM,KAAK;MAElB,OAAO,KAAK,KAAY;AAE5B;AAEA,SAAgB,eACd,WACA,YACA,MACA,MACiB;CACjB,MAAM,WAAW,OAAO,WAAW,EAAE,KAAK,CAAC;CAC3C,SAAkB,cAAc;CAChC,OAAO;AACT;;;;;;;AAQA,eAAsB,QAAuB;CAC3C,KAAK,IAAI,IAAI,GAAG,IAAI,kBAAkB,KAAK;EACzC,MAAM,SAAS,oBAAoB;EAGnC,MAAM,QAAQ,QAAQ;EACtB,MAAM,QAAQ,QAAQ;EACtB,IAAI,oBAAoB,MAAM,QAAQ;CACxC;CACA,MAAM,IAAI,MACR,kDAAkD,iBAAiB,QACrE;AACF;AAEA,MAAM,mBAAmB"}

package/dist/types/branded.d.ts

@@ -1,26 +1,19 @@
 declare const brand: unique symbol;
 /**
- * Utility type for creating branded/nominal types.
- * Prevents accidental type confusion between similar primitive types.
- * @template T - The base type
- * @template B - The brand identifier
+ * Nominal type helper, preventing accidental confusion between similar
+ * primitive types.
+ * @typeParam T - The base type
+ * @typeParam B - The brand identifier
  */
 export type Brand<T, B> = T & {
     [brand]: B;
 };
 /**
  * Branded string type for type-safe IDs.
- * @template B - The brand identifier
+ * @typeParam B - The brand identifier
  */
 export type BrandedId<B> = Brand<string, B>;
-/**
- * Branded string type for state container instance IDs
- */
+/** Branded string type for state container instance IDs. */
 export type InstanceId = Brand<string, 'InstanceId'>;
-/**
- * Create a branded InstanceId from a string
- * @param id - The string ID to brand
- * @returns Branded InstanceId
- */
 export declare function instanceId(id: string): InstanceId;
 export {};

package/dist/types/utilities.d.ts

@@ -1,51 +1,60 @@
 import type { StateContainer } from '../core/StateContainer';
 /**
- * Extract the state type from a StateContainer
- * @template T - The StateContainer type
+ * Recursively mark all properties readonly. The mirror of
+ * `DeepPartial` in `@dirtytalk/structural`, and carves out the same
+ * built-ins for the same reason.
+ *
+ * - Arrays become `ReadonlyArray`, recursing into the element type.
+ * - `Map`/`Set` become their `Readonly` counterparts so their contents are
+ *   frozen too, rather than only the binding.
+ * - `Date | RegExp` are kept as-is; mapping over them would freeze their
+ *   prototype methods instead of their (inaccessible) internal state.
+ * - Primitives and functions pass through unchanged.
+ *
+ * @typeParam T - The type to deeply freeze
+ * @public
  */
-export type ExtractState<T> = T extends StateContainerConstructor<infer S> ? Readonly<S> : never;
+export type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends ReadonlySet<infer U> ? ReadonlySet<DeepReadonly<U>> : T extends Date | RegExp ? T : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * Extract the state type from a StateContainer, deeply readonly.
+ *
+ * State is owned by the container: consumers read it and mutate only through
+ * `emit`/`patch`, so nested writes are a compile error rather than a silent
+ * desync from the change-tracking channel.
+ *
+ * @typeParam T - The StateContainer type
+ */
+export type ExtractState<T> = T extends StateContainerConstructor<infer S> ? DeepReadonly<S> : never;
 export type ExtractStateMutable<T> = T extends StateContainerConstructor<infer S> ? S : never;
 /**
  * Constructor type for StateContainer classes
- * @template S - State type managed by the container
+ * @typeParam S - State type managed by the container
  */
-export type StateContainerConstructor<S extends object = any> = new (...args: any[]) => StateContainer<S, any, any>;
+export type StateContainerConstructor<S extends object = any> = new () => StateContainer<S, any, any>;
 /**
  * Extract the args type (serializable construction/identity data) from a
  * StateContainer subclass.
- * @template T - The StateContainer constructor type
+ * @typeParam T - The StateContainer constructor type
  */
 export type ExtractArgs<T> = T extends new () => StateContainer<any, infer A, any> ? A : void;
 /**
  * Extract the deps type (injected non-serializable handles) from a
  * StateContainer subclass.
- * @template T - The StateContainer constructor type
+ * @typeParam T - The StateContainer constructor type
  */
 export type ExtractDeps<T> = T extends new () => StateContainer<any, any, infer D> ? D : Record<string, never>;
-export type InstanceReadonlyState<T extends StateContainerConstructor = any> = Omit<InstanceType<T>, 'state'> & {
-    state: ExtractState<T>;
-};
-export type InstanceState<T extends StateContainerConstructor = any> = Omit<InstanceType<T>, 'state'> & {
-    state: ExtractStateMutable<T>;
-};
-export type StateContainerInstance<S extends object = any> = Omit<StateContainer<S, any, any>, 'state'> & {
-    state: Readonly<S>;
-};
-/**
- * Extract constructor argument types from a class
- * @template T - The class type
- */
-export type ExtractConstructorArgs<T> = T extends new (...args: infer P) => any ? P : never[];
-/**
- * Extract instance type from an abstract class constructor
- * @template T - The abstract class constructor type
- */
-export type BlocInstanceType<T extends abstract new (...args: any) => any> = T extends abstract new (...args: any) => infer R ? R : any;
 /**
- * Constructor type for StateContainer classes.
- * Used for type-safe hook parameters.
- * @template TBloc - The StateContainer instance type
+ * Narrow a container instance's `state` without erasing the class. A plain
+ * intersection keeps private members, `this` types and symbol keys, so the
+ * result stays assignable to `StateContainer`; `state` is getter-only at the
+ * source, so no `readonly` modifier is needed here.
+ * @public
  */
-export type BlocConstructor<S extends object = any, T extends new (...args: any[]) => StateContainer<S, any, any> = new (...args: any[]) => StateContainer<S, any, any>> = (new (...args: any[]) => InstanceType<T>) & {
-    keepAlive?: boolean;
+export type WithState<I, S> = I & {
+    state: S;
 };
+export type InstanceReadonlyState<T extends StateContainerConstructor = StateContainerConstructor> = WithState<InstanceType<T>, ExtractState<T>>;
+export type InstanceState<T extends StateContainerConstructor = StateContainerConstructor> = WithState<InstanceType<T>, ExtractStateMutable<T>>;
+export type StateContainerInstance<S extends object = any> = WithState<StateContainer<S, any, any>, Readonly<S>>;

package/dist/utils/idGenerator.d.ts

@@ -1,21 +1,14 @@
 /**
- * Centralized ID Generation
+ * Build an instance id: `${prefix}:${affix}` when an affix is given (the
+ * registry passes the instance key), otherwise `${prefix}:${timestamp}_${random}`.
  *
- * Provides consistent, collision-resistant ID generation for all BlaC subsystems.
- * Uses timestamp + counter + random suffix for uniqueness.
- */
-/**
- * Generate simple ID with timestamp and random (no counter tracking)
- *
- * Format: `${prefix}:${timestamp}_${random}`
- *
- * @param prefix - Prefix for the ID
- * @returns Branded ID string
+ * Ids are not unique: same-named classes share an id for the same affix, and
+ * the lazy `$blac.id` of an unregistered instance is always `${prefix}:main`.
  *
  * @example
  * ```ts
- * const id = generateSimpleId('CounterBloc');
- * // Returns: "CounterBloc:1698765432100_a3k9d7f2q"
+ * generateSimpleId('CounterBloc', 'default'); // "CounterBloc:default"
+ * generateSimpleId('CounterBloc'); // "CounterBloc:1698765432100_a3k9d7f2q"
  * ```
  */
 export declare function generateSimpleId(prefix: string, affix?: string): string;

package/dist/utils/static-props.d.ts

@@ -1,47 +1,40 @@
-/**
- * Utility functions for accessing static properties on StateContainer classes
- */
 import type { EqualityFn } from '../config';
 import { StateContainerConstructor } from '../types/utilities';
 /**
- * Get a static property from a class constructor
- * Type-safe helper that avoids (Type as any) casts
- *
- * @param Type - The class constructor
- * @param propName - The property name to access
- * @param defaultValue - Optional default value if property is undefined
- * @returns The property value or default
+ * Get a static property from a class constructor, walking the prototype
+ * chain so subclasses inherit the value unless they define their own.
+ */
+export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string): V | undefined;
+/**
+ * Get a static property declared directly on `Type`, ignoring the prototype
+ * chain, so subclasses never inherit a base class's value.
  */
-export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string, defaultValue?: V): V | undefined;
+export declare function getOwnStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string): V | undefined;
 /**
- * Check if a class is marked as keepAlive.
- * KeepAlive classes are never auto-disposed when ref count reaches 0.
- * @param Type - The class constructor to check
- * @returns true if the class has `static keepAlive = true`
+ * Whether a class is marked `keepAlive` (never auto-disposed at ref count 0).
+ * Inherited: a subclass keeps a base class's `keepAlive` unless overridden.
  */
 export declare function isKeepAliveClass<T extends StateContainerConstructor>(Type: T): boolean;
 /**
- * Check if a class should be excluded from DevTools.
- * Used to prevent infinite loops when DevTools tracks itself.
- * @param Type - The class constructor to check
- * @returns true if the class has `static __excludeFromDevTools = true`
+ * Whether a class is excluded from DevTools (avoids DevTools tracking itself
+ * into an infinite loop). Inherited unless overridden by a subclass.
  */
 export declare function isExcludedFromDevTools<T extends StateContainerConstructor>(Type: T): boolean;
 /**
  * Get the per-class equality function set via `@blac({ equality })`, if any.
- * @param Type - The class constructor to check
- * @returns the equality function or `undefined`
+ * Inherited: a subclass keeps a base class's equality fn unless overridden.
  */
 export declare function getClassEquality<T extends StateContainerConstructor>(Type: T): EqualityFn | undefined;
 /**
- * Get the per-class key function set via `@blac({ key })` or `static key = …`, if any.
- * Used by the registry to derive a stable instance key from `args`.
- * @param Type - The class constructor to check
- * @returns the key function or `undefined`
+ * Get a class's minification-safe identity name (`static blacName`), falling
+ * back to `Type.name`. Own only: a subclass never inherits a base class's
+ * explicit `blacName`, since that would collapse two distinct blocs onto one
+ * identity.
  */
-export declare function getClassKey(Type: unknown): ((args: any) => string) | undefined;
+export declare function getBlacName<T extends StateContainerConstructor>(Type: T): string;
 /**
- * Check if a class is marked as always-per-mount.
- * @returns true if the class has `static isolated = true`
+ * Get the per-class key function set via `@blac({ key })` or `static key = …`.
+ * Own only: a subclass never inherits a base class's `key`, since a
+ * different `Args` shape would derive the wrong instance key.
  */
-export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
+export declare function getClassKey(Type: unknown): ((args: any) => string) | undefined;