@spearwolf/shadow-objects 0.34.0 → 0.35.0

package/src/testing/TestEntity.js

@@ -0,0 +1,135 @@
+import { emit } from "@spearwolf/eventize";
+import { value } from "@spearwolf/signalize";
+import { getDisplayName } from "../in-the-dark/displayName.js";
+const toPropertyEntries = (props) => Object.entries(props).map(([key, val]) => [key, val]);
+class TestEntityImpl {
+  #testKernel;
+  // The token the Kernel no longer answers for, once this Entity is destroyed. A handle stays
+  // readable after its Entity is gone -- a test asserts on what it held, and a getter that threw
+  // would turn that assertion into a crash.
+  #lastKnownToken;
+  constructor(testKernel, uuid, token) {
+    this.#testKernel = testKernel;
+    this.uuid = uuid;
+    this.#lastKnownToken = token;
+  }
+  get #kernel() {
+    return this.#testKernel.kernel;
+  }
+  get entity() {
+    return this.#kernel.getEntity(this.uuid);
+  }
+  get token() {
+    const current = this.#kernel.tokenOf(this.uuid);
+    if (current !== void 0) {
+      this.#lastKnownToken = current;
+    }
+    return this.#lastKnownToken;
+  }
+  /**
+   * A view onto the test kernel's own log, the way `token` and `entity` are views onto the Kernel.
+   * The handle stores nothing: a message is recorded for a uuid whether or not a handle for it
+   * existed at the time, so a handle built later answers for everything that Entity already sent.
+   */
+  get viewMessages() {
+    return this.#testKernel.viewMessagesOf(this.uuid);
+  }
+  createChild(token, props, options) {
+    return this.#testKernel.createEntity(token, props, { ...options, parent: this });
+  }
+  /**
+   * Writes through the Kernel rather than through `Entity.setProperties()`: `changeProperties()`
+   * re-resolves the constructor set afterwards, which is how a property route -- `token@prop` in a
+   * module's `routes` -- puts a Shadow Object on an Entity or takes it off again.
+   */
+  setProps(props) {
+    this.#kernel.changeProperties(this.uuid, toPropertyEntries(props));
+  }
+  /** A property set to `undefined` is a removal; see `ComponentPropertiesType` in `src/types.ts`. */
+  removeProps(...names) {
+    this.#kernel.changeProperties(
+      this.uuid,
+      names.map((name) => [name, void 0])
+    );
+  }
+  readProp(name) {
+    return this.entity.getProperty(name);
+  }
+  /**
+   * The effective value of an Entity Context, the one `useContext()` reads. It arrives a microtask
+   * after a provider wrote it -- `Entity` runs every context value through a `MicrotaskCollector` --
+   * so a test reads it after `settle()`.
+   */
+  readContext(name) {
+    return value(this.entity.useContext(name));
+  }
+  setToken(token) {
+    this.#kernel.changeToken(this.uuid, token);
+  }
+  setParent(parent, order) {
+    this.#kernel.setParent(this.uuid, parent?.uuid, order);
+  }
+  /**
+   * Delivery is synchronous, the way `Kernel.dispatchEventsToEntity()` is: a View event carries no
+   * structure, so nothing has to settle before a Shadow Object hears it.
+   */
+  sendViewEvent(type, data) {
+    this.#kernel.dispatchEventsToEntity(this.uuid, [{ type, data }]);
+  }
+  /**
+   * Emits on the Entity's own event bus. Every Shadow Object of this Entity is attached there as an
+   * eventize listener object, so a method named like the event is what receives it.
+   */
+  emit(eventName, ...args) {
+    emit(this.entity, eventName, ...args);
+  }
+  shadowObjects() {
+    return this.#kernel.findShadowObjects(this.uuid);
+  }
+  /**
+   * The one Shadow Object on this Entity that came out of `constructa`.
+   *
+   * Two rules in order, because one does not cover both constructor shapes, and because the second
+   * one is not exact. A class instance answers `instanceof` -- the `@ShadowObject` decorator wraps
+   * the class in a subclass, which still does -- and so does an object from a function constructor
+   * that returns nothing. Identity is asked first and, where anything answers it, alone.
+   *
+   * A function constructor that returns an object answers nothing: `new fn()` hands back that
+   * object, and it carries none of `fn`'s prototype. Only there does the display name decide, and
+   * only then, because a name is not an identity. `findShadowObjects()` and
+   * `describeShadowObjects()` walk the same bookkeeping in the same order, so the two lists line up
+   * index by index.
+   */
+  shadowObjectOf(constructa) {
+    const displayName = getDisplayName(constructa);
+    const instances = this.shadowObjects();
+    let matches = instances.filter((instance) => instance instanceof constructa);
+    if (matches.length === 0) {
+      const descriptions = this.describe();
+      matches = instances.filter((_, index) => descriptions[index]?.displayName === displayName);
+    }
+    if (matches.length === 0) {
+      throw new Error(`no shadow object built from "${displayName}" on entity ${this.uuid}`);
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `${matches.length} shadow objects built from "${displayName}" on entity ${this.uuid}; use shadowObjects() and pick one`
+      );
+    }
+    return matches[0];
+  }
+  describe() {
+    return this.#kernel.describeShadowObjects(this.uuid);
+  }
+  clearViewMessages() {
+    this.#testKernel.clearViewMessagesOf(this.uuid);
+  }
+  destroy() {
+    this.#kernel.destroyEntity(this.uuid);
+  }
+}
+export {
+  TestEntityImpl,
+  toPropertyEntries
+};
+//# sourceMappingURL=TestEntity.js.map

package/src/testing/TestEntity.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/testing/TestEntity.ts"],
+  "sourcesContent": ["import {emit} from '@spearwolf/eventize';\nimport {value} from '@spearwolf/signalize';\nimport {getDisplayName} from '../in-the-dark/displayName.js';\nimport type {Entity} from '../in-the-dark/Entity.js';\nimport type {Kernel} from '../in-the-dark/Kernel.js';\nimport type {ComponentPropertiesType, ShadowObjectConstructor, ShadowObjectDescription, ShadowObjectType} from '../types.js';\nimport type {\n  AnyShadowObjectConstructor,\n  CreateEntityOptions,\n  ShadowObjectInstance,\n  TestEntity,\n  ViewMessageRecord,\n} from './types.js';\n\n/** What a `TestEntityImpl` needs from the test kernel that owns it. */\nexport interface TestKernelInternals {\n  readonly kernel: Kernel;\n  createEntity(token: string, props?: Record<string, unknown>, options?: CreateEntityOptions): TestEntity;\n  /** What the test kernel recorded for a uuid. The log is its own, so a handle never holds one. */\n  viewMessagesOf(uuid: string): readonly ViewMessageRecord[];\n  clearViewMessagesOf(uuid: string): void;\n}\n\n/**\n * Properties as a Kernel call wants them. `Object.entries()` drops symbol keys, which is right:\n * an Entity property is string-keyed. A value of `undefined` is a removal, which is what\n * `types.ts` says about a `ComponentPropertiesType` entry and what `removeProps()` relies on.\n */\nexport const toPropertyEntries = (props: Record<string, unknown>): ComponentPropertiesType =>\n  Object.entries(props).map(([key, val]) => [key, val] as [string, unknown]);\n\nexport class TestEntityImpl implements TestEntity {\n  readonly uuid: string;\n\n  readonly #testKernel: TestKernelInternals;\n\n  // The token the Kernel no longer answers for, once this Entity is destroyed. A handle stays\n  // readable after its Entity is gone -- a test asserts on what it held, and a getter that threw\n  // would turn that assertion into a crash.\n  #lastKnownToken: string;\n\n  constructor(testKernel: TestKernelInternals, uuid: string, token: string) {\n    this.#testKernel = testKernel;\n    this.uuid = uuid;\n    this.#lastKnownToken = token;\n  }\n\n  get #kernel(): Kernel {\n    return this.#testKernel.kernel;\n  }\n\n  get entity(): Entity {\n    return this.#kernel.getEntity(this.uuid);\n  }\n\n  get token(): string {\n    const current = this.#kernel.tokenOf(this.uuid);\n    if (current !== undefined) {\n      this.#lastKnownToken = current;\n    }\n    return this.#lastKnownToken;\n  }\n\n  /**\n   * A view onto the test kernel's own log, the way `token` and `entity` are views onto the Kernel.\n   * The handle stores nothing: a message is recorded for a uuid whether or not a handle for it\n   * existed at the time, so a handle built later answers for everything that Entity already sent.\n   */\n  get viewMessages(): readonly ViewMessageRecord[] {\n    return this.#testKernel.viewMessagesOf(this.uuid);\n  }\n\n  createChild(token: string, props?: Record<string, unknown>, options?: Omit<CreateEntityOptions, 'parent'>): TestEntity {\n    return this.#testKernel.createEntity(token, props, {...options, parent: this});\n  }\n\n  /**\n   * Writes through the Kernel rather than through `Entity.setProperties()`: `changeProperties()`\n   * re-resolves the constructor set afterwards, which is how a property route -- `token@prop` in a\n   * module's `routes` -- puts a Shadow Object on an Entity or takes it off again.\n   */\n  setProps(props: Record<string, unknown>): void {\n    this.#kernel.changeProperties(this.uuid, toPropertyEntries(props));\n  }\n\n  /** A property set to `undefined` is a removal; see `ComponentPropertiesType` in `src/types.ts`. */\n  removeProps(...names: string[]): void {\n    this.#kernel.changeProperties(\n      this.uuid,\n      names.map((name) => [name, undefined] as [string, unknown]),\n    );\n  }\n\n  readProp<T = unknown>(name: string): T | undefined {\n    return this.entity.getProperty<T | undefined>(name);\n  }\n\n  /**\n   * The effective value of an Entity Context, the one `useContext()` reads. It arrives a microtask\n   * after a provider wrote it -- `Entity` runs every context value through a `MicrotaskCollector` --\n   * so a test reads it after `settle()`.\n   */\n  readContext<T = unknown>(name: string | symbol): T | undefined {\n    return value(this.entity.useContext<T | undefined>(name));\n  }\n\n  setToken(token: string): void {\n    this.#kernel.changeToken(this.uuid, token);\n  }\n\n  setParent(parent: TestEntity | undefined, order?: number): void {\n    this.#kernel.setParent(this.uuid, parent?.uuid, order);\n  }\n\n  /**\n   * Delivery is synchronous, the way `Kernel.dispatchEventsToEntity()` is: a View event carries no\n   * structure, so nothing has to settle before a Shadow Object hears it.\n   */\n  sendViewEvent(type: string, data?: unknown): void {\n    this.#kernel.dispatchEventsToEntity(this.uuid, [{type, data}]);\n  }\n\n  /**\n   * Emits on the Entity's own event bus. Every Shadow Object of this Entity is attached there as an\n   * eventize listener object, so a method named like the event is what receives it.\n   */\n  emit(eventName: string | symbol, ...args: unknown[]): void {\n    emit(this.entity, eventName, ...args);\n  }\n\n  shadowObjects(): ShadowObjectType[] {\n    return this.#kernel.findShadowObjects(this.uuid);\n  }\n\n  /**\n   * The one Shadow Object on this Entity that came out of `constructa`.\n   *\n   * Two rules in order, because one does not cover both constructor shapes, and because the second\n   * one is not exact. A class instance answers `instanceof` -- the `@ShadowObject` decorator wraps\n   * the class in a subclass, which still does -- and so does an object from a function constructor\n   * that returns nothing. Identity is asked first and, where anything answers it, alone.\n   *\n   * A function constructor that returns an object answers nothing: `new fn()` hands back that\n   * object, and it carries none of `fn`'s prototype. Only there does the display name decide, and\n   * only then, because a name is not an identity. `findShadowObjects()` and\n   * `describeShadowObjects()` walk the same bookkeeping in the same order, so the two lists line up\n   * index by index.\n   */\n  shadowObjectOf<C extends AnyShadowObjectConstructor>(constructa: C): ShadowObjectInstance<C> {\n    const displayName = getDisplayName(constructa as ShadowObjectConstructor);\n    const instances = this.shadowObjects();\n\n    let matches = instances.filter((instance) => instance instanceof (constructa as unknown as new (...args: any[]) => object));\n\n    // The display name is the fallback, never a second rule beside identity. Two constructors are\n    // free to carry one display name, and an `||` between the two would then count the other one's\n    // Shadow Object as a match and report an ambiguity that is not there. Identity, where it\n    // answers at all, is exact.\n    //\n    // What no rule separates is two *function* constructors of one name on one Entity: neither\n    // leaves a prototype behind, so nothing tells their objects apart. The throw below names that\n    // for what it is and points at `shadowObjects()`.\n    if (matches.length === 0) {\n      const descriptions = this.describe();\n      matches = instances.filter((_, index) => descriptions[index]?.displayName === displayName);\n    }\n\n    if (matches.length === 0) {\n      throw new Error(`no shadow object built from \"${displayName}\" on entity ${this.uuid}`);\n    }\n    if (matches.length > 1) {\n      throw new Error(\n        `${matches.length} shadow objects built from \"${displayName}\" on entity ${this.uuid}; use shadowObjects() and pick one`,\n      );\n    }\n\n    return matches[0] as ShadowObjectInstance<C>;\n  }\n\n  describe(): ShadowObjectDescription[] {\n    return this.#kernel.describeShadowObjects(this.uuid);\n  }\n\n  clearViewMessages(): void {\n    this.#testKernel.clearViewMessagesOf(this.uuid);\n  }\n\n  destroy(): void {\n    this.#kernel.destroyEntity(this.uuid);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/src/testing/createTestKernel.d.ts

@@ -0,0 +1,11 @@
+import type { TestKernel, TestKernelOptions } from './types.js';
+/**
+ * A Kernel for a unit test: its own Registry, object-shaped properties, recorded View messages,
+ * recorded Kernel errors, and a `settle()` that drains the microtask cascade.
+ *
+ * Everything runs on the real Kernel. There is no DOM, no ShadowEnv and no worker in it, and no
+ * `structuredClone` between the test and the Shadow Object -- a value handed in as a property or a
+ * context arrives by identity, a DOM node and a WebGL handle included.
+ */
+export declare function createTestKernel(options?: TestKernelOptions): TestKernel;
+//# sourceMappingURL=createTestKernel.d.ts.map

package/src/testing/createTestKernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTestKernel.d.ts","sourceRoot":"","sources":["../../../src/testing/createTestKernel.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAKV,UAAU,EACV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AA0KpB;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAE5E"}

package/src/testing/createTestKernel.js

@@ -0,0 +1,132 @@
+import { on } from "@spearwolf/eventize";
+import { MessageToView } from "../constants.js";
+import { importModule as importShadowObjectsModule } from "../in-the-dark/importModule.js";
+import { Kernel } from "../in-the-dark/Kernel.js";
+import { Registry } from "../in-the-dark/Registry.js";
+import { generateUUID } from "../utils/generateUUID.js";
+import { recordKernelErrors } from "./recordKernelErrors.js";
+import { settle } from "./settle.js";
+import { TestEntityImpl, toPropertyEntries } from "./TestEntity.js";
+const NoViewMessages = Object.freeze([]);
+class TestKernelImpl {
+  #handles = /* @__PURE__ */ new Map();
+  // The recording lives here rather than on the handles, because a message is dispatched for a uuid
+  // long before anything asks for its handle: a Shadow Object that calls `entity.kernel.createEntity()`
+  // makes one, and a handle built afterwards has to answer for what that Entity already sent.
+  #viewMessages = /* @__PURE__ */ new Map();
+  #importedModules = /* @__PURE__ */ new Set();
+  #recorder;
+  #unsubscribeMessageToView;
+  // Only a Registry this test kernel made is a Registry it may empty. One the caller handed in is
+  // the caller's, default or not, and clearing it would take the rest of the suite's definitions.
+  #ownsRegistry;
+  #failOnKernelErrors;
+  #disposed = false;
+  constructor(options) {
+    this.#ownsRegistry = options.registry === void 0;
+    this.#failOnKernelErrors = options.failOnKernelErrors ?? true;
+    this.registry = options.registry ?? new Registry();
+    this.kernel = new Kernel(this.registry);
+    this.#recorder = recordKernelErrors(this.kernel.logger, options.echoKernelErrors ?? false);
+    this.#unsubscribeMessageToView = on(this.kernel, MessageToView, (message) => {
+      const record = {
+        type: message.type,
+        data: message.data,
+        ...message.traverseChildren !== void 0 ? { traverseChildren: message.traverseChildren } : {}
+      };
+      const recorded = this.#viewMessages.get(message.uuid);
+      if (recorded === void 0) {
+        this.#viewMessages.set(message.uuid, [record]);
+      } else {
+        recorded.push(record);
+      }
+    });
+  }
+  get errors() {
+    return this.#recorder.records;
+  }
+  define(token, constructa) {
+    this.registry.define(token, constructa);
+  }
+  route(token, targets) {
+    this.registry.appendRoute(token, targets);
+  }
+  async importModule(module) {
+    await importShadowObjectsModule(this.kernel, module, this.#importedModules);
+  }
+  createEntity(token, props, options) {
+    const uuid = options?.uuid ?? generateUUID();
+    const previous = this.#handles.get(uuid);
+    const handle = new TestEntityImpl(this, uuid, token);
+    this.#handles.set(uuid, handle);
+    try {
+      this.kernel.createEntity(
+        uuid,
+        token,
+        options?.parent?.uuid,
+        options?.order ?? 0,
+        props ? toPropertyEntries(props) : void 0,
+        options?.autoDestructionOnParentRemoval ?? false
+      );
+    } catch (error) {
+      if (previous === void 0) {
+        this.#handles.delete(uuid);
+      } else {
+        this.#handles.set(uuid, previous);
+      }
+      throw error;
+    }
+    return handle;
+  }
+  entity(uuid) {
+    const known = this.#handles.get(uuid);
+    if (known !== void 0) return known;
+    const token = this.kernel.tokenOf(uuid);
+    if (token === void 0) return void 0;
+    const handle = new TestEntityImpl(this, uuid, token);
+    this.#handles.set(uuid, handle);
+    return handle;
+  }
+  /** What was recorded for a uuid, whether or not a handle for it existed at the time. @internal */
+  viewMessagesOf(uuid) {
+    return this.#viewMessages.get(uuid) ?? NoViewMessages;
+  }
+  /** Empties one uuid's recorded list, and no other's. @internal */
+  clearViewMessagesOf(uuid) {
+    this.#viewMessages.delete(uuid);
+  }
+  settle() {
+    return settle();
+  }
+  clearErrors() {
+    this.#recorder.clear();
+  }
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.kernel.destroy();
+    this.#unsubscribeMessageToView();
+    if (this.#ownsRegistry) {
+      this.registry.clear();
+    }
+    const errors = this.#recorder.records.filter((record) => record.level === "error");
+    this.#recorder.unhook();
+    this.#handles.clear();
+    this.#viewMessages.clear();
+    this.#importedModules.clear();
+    if (this.#failOnKernelErrors && errors.length > 0) {
+      const first = errors[0];
+      throw new Error(
+        `the kernel reported ${errors.length} error(s) that this test did not acknowledge. The first one was: ${first.args.map((arg) => String(arg)).join(" ")}. Assert on testKernel.errors and call clearErrors(), or pass {failOnKernelErrors: false}.`,
+        ...first.error !== void 0 ? [{ cause: first.error }] : []
+      );
+    }
+  }
+}
+function createTestKernel(options = {}) {
+  return new TestKernelImpl(options);
+}
+export {
+  createTestKernel
+};
+//# sourceMappingURL=createTestKernel.js.map

package/src/testing/createTestKernel.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/testing/createTestKernel.ts"],
+  "sourcesContent": ["import {on} from '@spearwolf/eventize';\nimport {MessageToView} from '../constants.js';\nimport {importModule as importShadowObjectsModule} from '../in-the-dark/importModule.js';\nimport {Kernel, type MessageToViewEvent} from '../in-the-dark/Kernel.js';\nimport {Registry} from '../in-the-dark/Registry.js';\nimport type {ShadowObjectConstructor, ShadowObjectsModule} from '../types.js';\nimport {generateUUID} from '../utils/generateUUID.js';\nimport {type KernelErrorRecorder, recordKernelErrors} from './recordKernelErrors.js';\nimport {settle} from './settle.js';\nimport {TestEntityImpl, type TestKernelInternals, toPropertyEntries} from './TestEntity.js';\nimport type {\n  AnyShadowObjectConstructor,\n  CreateEntityOptions,\n  KernelErrorRecord,\n  TestEntity,\n  TestKernel,\n  TestKernelOptions,\n  ViewMessageRecord,\n} from './types.js';\n\n/** What `viewMessagesOf()` answers for a uuid nothing was ever recorded for. */\nconst NoViewMessages: readonly ViewMessageRecord[] = Object.freeze([]);\n\nclass TestKernelImpl implements TestKernel, TestKernelInternals {\n  readonly kernel: Kernel;\n  readonly registry: Registry;\n\n  readonly #handles = new Map<string, TestEntityImpl>();\n\n  // The recording lives here rather than on the handles, because a message is dispatched for a uuid\n  // long before anything asks for its handle: a Shadow Object that calls `entity.kernel.createEntity()`\n  // makes one, and a handle built afterwards has to answer for what that Entity already sent.\n  readonly #viewMessages = new Map<string, ViewMessageRecord[]>();\n\n  readonly #importedModules = new Set<ShadowObjectsModule>();\n  readonly #recorder: KernelErrorRecorder;\n  readonly #unsubscribeMessageToView: () => void;\n  // Only a Registry this test kernel made is a Registry it may empty. One the caller handed in is\n  // the caller's, default or not, and clearing it would take the rest of the suite's definitions.\n  readonly #ownsRegistry: boolean;\n  readonly #failOnKernelErrors: boolean;\n\n  #disposed = false;\n\n  constructor(options: TestKernelOptions) {\n    this.#ownsRegistry = options.registry === undefined;\n    this.#failOnKernelErrors = options.failOnKernelErrors ?? true;\n    this.registry = options.registry ?? new Registry();\n    this.kernel = new Kernel(this.registry);\n    this.#recorder = recordKernelErrors(this.kernel.logger, options.echoKernelErrors ?? false);\n\n    // Nothing clones the payload on the way here, unlike `LocalShadowObjectEnv`, which runs it\n    // through `structuredClone`. A test asserts on the object the Shadow Object sent.\n    //\n    // `traverseChildren` is recorded rather than acted on: the flag is an instruction to the View\n    // layer, and there is no View layer here. The spread is conditional because\n    // `exactOptionalPropertyTypes` forbids writing `undefined` into an optional field.\n    this.#unsubscribeMessageToView = on(this.kernel, MessageToView, (message: MessageToViewEvent) => {\n      const record: ViewMessageRecord = {\n        type: message.type,\n        data: message.data,\n        ...(message.traverseChildren !== undefined ? {traverseChildren: message.traverseChildren} : {}),\n      };\n\n      const recorded = this.#viewMessages.get(message.uuid);\n      if (recorded === undefined) {\n        this.#viewMessages.set(message.uuid, [record]);\n      } else {\n        recorded.push(record);\n      }\n    });\n  }\n\n  get errors(): readonly KernelErrorRecord[] {\n    return this.#recorder.records;\n  }\n\n  define(token: string, constructa: AnyShadowObjectConstructor): void {\n    this.registry.define(token, constructa as ShadowObjectConstructor);\n  }\n\n  route(token: string, targets: string[]): void {\n    this.registry.appendRoute(token, targets);\n  }\n\n  async importModule(module: ShadowObjectsModule): Promise<void> {\n    await importShadowObjectsModule(this.kernel, module, this.#importedModules);\n  }\n\n  createEntity(token: string, props?: Record<string, unknown>, options?: CreateEntityOptions): TestEntity {\n    const uuid = options?.uuid ?? generateUUID();\n\n    // The handle goes in before the Kernel call, because a Shadow Object constructor may ask this\n    // facade for its own handle, and the one it gets has to be the one this call hands back.\n    const previous = this.#handles.get(uuid);\n    const handle = new TestEntityImpl(this, uuid, token);\n    this.#handles.set(uuid, handle);\n\n    try {\n      this.kernel.createEntity(\n        uuid,\n        token,\n        options?.parent?.uuid,\n        options?.order ?? 0,\n        props ? toPropertyEntries(props) : undefined,\n        options?.autoDestructionOnParentRemoval ?? false,\n      );\n    } catch (error) {\n      // Restore rather than delete. `options.uuid` may name a uuid this facade already held a handle\n      // for -- the Kernel refuses that creation with an `EntityUuidInUseError` -- and deleting would\n      // evict a handle the caller still holds, leaving every later message for that uuid on the\n      // replacement this failed call put in.\n      if (previous === undefined) {\n        this.#handles.delete(uuid);\n      } else {\n        this.#handles.set(uuid, previous);\n      }\n      throw error;\n    }\n\n    return handle;\n  }\n\n  entity(uuid: string): TestEntity | undefined {\n    const known = this.#handles.get(uuid);\n    if (known !== undefined) return known;\n\n    const token = this.kernel.tokenOf(uuid);\n    if (token === undefined) return undefined;\n\n    const handle = new TestEntityImpl(this, uuid, token);\n    this.#handles.set(uuid, handle);\n    return handle;\n  }\n\n  /** What was recorded for a uuid, whether or not a handle for it existed at the time. @internal */\n  viewMessagesOf(uuid: string): readonly ViewMessageRecord[] {\n    return this.#viewMessages.get(uuid) ?? NoViewMessages;\n  }\n\n  /** Empties one uuid's recorded list, and no other's. @internal */\n  clearViewMessagesOf(uuid: string): void {\n    this.#viewMessages.delete(uuid);\n  }\n\n  settle(): Promise<void> {\n    return settle();\n  }\n\n  clearErrors(): void {\n    this.#recorder.clear();\n  }\n\n  dispose(): void {\n    if (this.#disposed) return;\n    this.#disposed = true;\n\n    this.kernel.destroy();\n    this.#unsubscribeMessageToView();\n\n    if (this.#ownsRegistry) {\n      this.registry.clear();\n    }\n\n    // Read before the unhook, because unhooking does not clear the records but a later read has no\n    // reason to reach the recorder again.\n    const errors = this.#recorder.records.filter((record) => record.level === 'error');\n\n    this.#recorder.unhook();\n    this.#handles.clear();\n    this.#viewMessages.clear();\n    this.#importedModules.clear();\n\n    // Only `error`. A warning is recorded and readable, and never fails a run: `importModule()`\n    // warns about a module two `extends` chains have in common, which is a shape of the module\n    // graph and not a mistake.\n    if (this.#failOnKernelErrors && errors.length > 0) {\n      const first = errors[0]!;\n      throw new Error(\n        `the kernel reported ${errors.length} error(s) that this test did not acknowledge. ` +\n          `The first one was: ${first.args.map((arg) => String(arg)).join(' ')}. ` +\n          'Assert on testKernel.errors and call clearErrors(), or pass {failOnKernelErrors: false}.',\n        ...(first.error !== undefined ? [{cause: first.error}] : []),\n      );\n    }\n  }\n}\n\n/**\n * A Kernel for a unit test: its own Registry, object-shaped properties, recorded View messages,\n * recorded Kernel errors, and a `settle()` that drains the microtask cascade.\n *\n * Everything runs on the real Kernel. There is no DOM, no ShadowEnv and no worker in it, and no\n * `structuredClone` between the test and the Shadow Object -- a value handed in as a property or a\n * context arrives by identity, a DOM node and a WebGL handle included.\n */\nexport function createTestKernel(options: TestKernelOptions = {}): TestKernel {\n  return new TestKernelImpl(options);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/src/testing/mountShadowObject.d.ts

@@ -0,0 +1,21 @@
+import type { AnyShadowObjectConstructor, MountedShadowObject, MountOptions } from './types.js';
+/**
+ * Mounts one Shadow Object on one Entity and hands back everything a test asserts on.
+ *
+ * Asynchronous because the framework is. `contexts` are provided by a synthetic parent Entity, and a
+ * context value reaches a reader a microtask after it was written.
+ *
+ * Two settles, and they buy different things. `settle()` drains the whole microtask cascade, so the
+ * second one alone already carries every context value down to every effect. The first is what a
+ * constructor gets: it lets the parent's own context signal settle before the object under test is
+ * built, so a `useParentContext()` read inside the constructor body answers with the value instead
+ * of `undefined` -- that reader is a direct link to the parent and does not pass the Entity's
+ * collector.
+ *
+ * What neither settle can do is hand a context value to a constructor through `useContext()`. That
+ * reader does pass the collector, and the value behind it lands after the constructor has returned,
+ * in a mounted test as much as in a running application. A context is read inside an effect or a
+ * memo.
+ */
+export declare function mountShadowObject<C extends AnyShadowObjectConstructor>(constructa: C, options?: MountOptions): Promise<MountedShadowObject<C>>;
+//# sourceMappingURL=mountShadowObject.d.ts.map

package/src/testing/mountShadowObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountShadowObject.d.ts","sourceRoot":"","sources":["../../../src/testing/mountShadowObject.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,0BAA0B,EAC1B,mBAAmB,EACnB,YAAY,EAIb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,0BAA0B,EAC1E,UAAU,EAAE,CAAC,EACb,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAwBjC"}

package/src/testing/mountShadowObject.js

@@ -0,0 +1,72 @@
+import { generateUUID } from "../utils/generateUUID.js";
+import { createTestKernel } from "./createTestKernel.js";
+async function mountShadowObject(constructa, options = {}) {
+  const testKernel = createTestKernel({
+    ...options.registry !== void 0 ? { registry: options.registry } : {},
+    ...options.failOnKernelErrors !== void 0 ? { failOnKernelErrors: options.failOnKernelErrors } : {},
+    ...options.echoKernelErrors !== void 0 ? { echoKernelErrors: options.echoKernelErrors } : {}
+  });
+  try {
+    return await mount(testKernel, constructa, options);
+  } catch (error) {
+    try {
+      testKernel.dispose();
+    } catch {
+    }
+    throw error;
+  }
+}
+async function mount(testKernel, constructa, options) {
+  const token = options.token ?? `mounted-shadow-object-${generateUUID()}`;
+  testKernel.define(token, constructa);
+  let parent;
+  const providedContexts = options.contexts ?? {};
+  const contextNames = Reflect.ownKeys(providedContexts);
+  if (contextNames.length > 0) {
+    const providerToken = `mounted-context-provider-${generateUUID()}`;
+    testKernel.define(providerToken, function MountedContextProvider({ provideContext }) {
+      for (const name of contextNames) {
+        provideContext(name, providedContexts[name]);
+      }
+    });
+    parent = testKernel.createEntity(providerToken);
+    await testKernel.settle();
+  }
+  const ent = testKernel.createEntity(token, options.props, parent !== void 0 ? { parent } : {});
+  await testKernel.settle();
+  const instance = ent.shadowObjectOf(constructa);
+  return {
+    get uuid() {
+      return ent.uuid;
+    },
+    get token() {
+      return ent.token;
+    },
+    get entity() {
+      return ent.entity;
+    },
+    get viewMessages() {
+      return ent.viewMessages;
+    },
+    instance,
+    testKernel,
+    setProps: (props) => ent.setProps(props),
+    removeProps: (...names) => ent.removeProps(...names),
+    readProp: (name) => ent.readProp(name),
+    readContext: (name) => ent.readContext(name),
+    setToken: (nextToken) => ent.setToken(nextToken),
+    setParent: (nextParent, order) => ent.setParent(nextParent, order),
+    sendViewEvent: (type, data) => ent.sendViewEvent(type, data),
+    emit: (eventName, ...args) => ent.emit(eventName, ...args),
+    shadowObjects: () => ent.shadowObjects(),
+    shadowObjectOf: (other) => ent.shadowObjectOf(other),
+    describe: () => ent.describe(),
+    clearViewMessages: () => ent.clearViewMessages(),
+    settle: () => testKernel.settle(),
+    dispose: () => testKernel.dispose()
+  };
+}
+export {
+  mountShadowObject
+};
+//# sourceMappingURL=mountShadowObject.js.map

package/src/testing/mountShadowObject.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/testing/mountShadowObject.ts"],
+  "sourcesContent": ["import type {ShadowObjectCreationAPI} from '../types.js';\nimport {generateUUID} from '../utils/generateUUID.js';\nimport {createTestKernel} from './createTestKernel.js';\nimport type {\n  AnyShadowObjectConstructor,\n  MountedShadowObject,\n  MountOptions,\n  ShadowObjectInstance,\n  TestEntity,\n  TestKernel,\n} from './types.js';\n\n/**\n * Mounts one Shadow Object on one Entity and hands back everything a test asserts on.\n *\n * Asynchronous because the framework is. `contexts` are provided by a synthetic parent Entity, and a\n * context value reaches a reader a microtask after it was written.\n *\n * Two settles, and they buy different things. `settle()` drains the whole microtask cascade, so the\n * second one alone already carries every context value down to every effect. The first is what a\n * constructor gets: it lets the parent's own context signal settle before the object under test is\n * built, so a `useParentContext()` read inside the constructor body answers with the value instead\n * of `undefined` -- that reader is a direct link to the parent and does not pass the Entity's\n * collector.\n *\n * What neither settle can do is hand a context value to a constructor through `useContext()`. That\n * reader does pass the collector, and the value behind it lands after the constructor has returned,\n * in a mounted test as much as in a running application. A context is read inside an effect or a\n * memo.\n */\nexport async function mountShadowObject<C extends AnyShadowObjectConstructor>(\n  constructa: C,\n  options: MountOptions = {},\n): Promise<MountedShadowObject<C>> {\n  const testKernel = createTestKernel({\n    ...(options.registry !== undefined ? {registry: options.registry} : {}),\n    ...(options.failOnKernelErrors !== undefined ? {failOnKernelErrors: options.failOnKernelErrors} : {}),\n    ...(options.echoKernelErrors !== undefined ? {echoKernelErrors: options.echoKernelErrors} : {}),\n  });\n\n  // Everything from here on can throw -- a Shadow Object constructor propagates through\n  // `createEntity()`, and `shadowObjectOf()` throws when nothing matched. The test kernel is\n  // unreachable on that path, because the caller is handed an error rather than a mount, so it is\n  // torn down here or never. With `{registry: Registry.get()}` \"never\" would leave the generated\n  // token and the synthetic provider's token in the process-wide Registry for the rest of the run.\n  try {\n    return await mount(testKernel, constructa, options);\n  } catch (error) {\n    try {\n      testKernel.dispose();\n    } catch {\n      // `dispose()` throws over an unacknowledged Kernel error -- and a failed mount is exactly the\n      // situation that records one. That error must not take the place of the one the caller is\n      // waiting for: the original says why the mount failed, and it is the one that gets through.\n    }\n    throw error;\n  }\n}\n\n/** The body of the mount, split out so the caller above has one place to put the teardown guard. */\nasync function mount<C extends AnyShadowObjectConstructor>(\n  testKernel: TestKernel,\n  constructa: C,\n  options: MountOptions,\n): Promise<MountedShadowObject<C>> {\n  const token = options.token ?? `mounted-shadow-object-${generateUUID()}`;\n  testKernel.define(token, constructa);\n\n  let parent: TestEntity | undefined;\n\n  // Hoisted rather than read off `options` inside the closure: a narrowing done out here does not\n  // survive into a function body, and the alternative is a non-null assertion per read.\n  const providedContexts: Record<string | symbol, unknown> = options.contexts ?? {};\n  const contextNames = Reflect.ownKeys(providedContexts);\n\n  if (contextNames.length > 0) {\n    const providerToken = `mounted-context-provider-${generateUUID()}`;\n    // A function as a context value is read by `provideContext()` as a signal reader rather than as\n    // the value. That is `provideContext()`'s contract; the documentation names it next to this.\n    testKernel.define(providerToken, function MountedContextProvider({provideContext}: ShadowObjectCreationAPI) {\n      for (const name of contextNames) {\n        provideContext(name, providedContexts[name]);\n      }\n    });\n    parent = testKernel.createEntity(providerToken);\n    await testKernel.settle();\n  }\n\n  const ent = testKernel.createEntity(token, options.props, parent !== undefined ? {parent} : {});\n\n  await testKernel.settle();\n\n  const instance = ent.shadowObjectOf(constructa);\n\n  // Written out rather than delegated through a prototype: `TestEntityImpl` keeps its state in\n  // private fields, which are branded per instance, so a method reached through `Object.create()`\n  // would throw on the first field access.\n  return {\n    get uuid() {\n      return ent.uuid;\n    },\n    get token() {\n      return ent.token;\n    },\n    get entity() {\n      return ent.entity;\n    },\n    get viewMessages() {\n      return ent.viewMessages;\n    },\n    instance: instance as ShadowObjectInstance<C>,\n    testKernel,\n    setProps: (props) => ent.setProps(props),\n    removeProps: (...names) => ent.removeProps(...names),\n    readProp: <T>(name: string) => ent.readProp<T>(name),\n    readContext: <T>(name: string | symbol) => ent.readContext<T>(name),\n    setToken: (nextToken) => ent.setToken(nextToken),\n    setParent: (nextParent, order) => ent.setParent(nextParent, order),\n    sendViewEvent: (type, data) => ent.sendViewEvent(type, data),\n    emit: (eventName, ...args) => ent.emit(eventName, ...args),\n    shadowObjects: () => ent.shadowObjects(),\n    shadowObjectOf: <C2 extends AnyShadowObjectConstructor>(other: C2) => ent.shadowObjectOf(other),\n    describe: () => ent.describe(),\n    clearViewMessages: () => ent.clearViewMessages(),\n    settle: () => testKernel.settle(),\n    dispose: () => testKernel.dispose(),\n  };\n}\n"],
+  "mappings": "AACA,SAAQ,oBAAmB;AAC3B,SAAQ,wBAAuB;AA4B/B,eAAsB,kBACpB,YACA,UAAwB,CAAC,GACQ;AACjC,QAAM,aAAa,iBAAiB;AAAA,IAClC,GAAI,QAAQ,aAAa,SAAY,EAAC,UAAU,QAAQ,SAAQ,IAAI,CAAC;AAAA,IACrE,GAAI,QAAQ,uBAAuB,SAAY,EAAC,oBAAoB,QAAQ,mBAAkB,IAAI,CAAC;AAAA,IACnG,GAAI,QAAQ,qBAAqB,SAAY,EAAC,kBAAkB,QAAQ,iBAAgB,IAAI,CAAC;AAAA,EAC/F,CAAC;AAOD,MAAI;AACF,WAAO,MAAM,MAAM,YAAY,YAAY,OAAO;AAAA,EACpD,SAAS,OAAO;AACd,QAAI;AACF,iBAAW,QAAQ;AAAA,IACrB,QAAQ;AAAA,IAIR;AACA,UAAM;AAAA,EACR;AACF;AAGA,eAAe,MACb,YACA,YACA,SACiC;AACjC,QAAM,QAAQ,QAAQ,SAAS,yBAAyB,aAAa,CAAC;AACtE,aAAW,OAAO,OAAO,UAAU;AAEnC,MAAI;AAIJ,QAAM,mBAAqD,QAAQ,YAAY,CAAC;AAChF,QAAM,eAAe,QAAQ,QAAQ,gBAAgB;AAErD,MAAI,aAAa,SAAS,GAAG;AAC3B,UAAM,gBAAgB,4BAA4B,aAAa,CAAC;AAGhE,eAAW,OAAO,eAAe,SAAS,uBAAuB,EAAC,eAAc,GAA4B;AAC1G,iBAAW,QAAQ,cAAc;AAC/B,uBAAe,MAAM,iBAAiB,IAAI,CAAC;AAAA,MAC7C;AAAA,IACF,CAAC;AACD,aAAS,WAAW,aAAa,aAAa;AAC9C,UAAM,WAAW,OAAO;AAAA,EAC1B;AAEA,QAAM,MAAM,WAAW,aAAa,OAAO,QAAQ,OAAO,WAAW,SAAY,EAAC,OAAM,IAAI,CAAC,CAAC;AAE9F,QAAM,WAAW,OAAO;AAExB,QAAM,WAAW,IAAI,eAAe,UAAU;AAK9C,SAAO;AAAA,IACL,IAAI,OAAO;AACT,aAAO,IAAI;AAAA,IACb;AAAA,IACA,IAAI,QAAQ;AACV,aAAO,IAAI;AAAA,IACb;AAAA,IACA,IAAI,SAAS;AACX,aAAO,IAAI;AAAA,IACb;AAAA,IACA,IAAI,eAAe;AACjB,aAAO,IAAI;AAAA,IACb;AAAA,IACA;AAAA,IACA;AAAA,IACA,UAAU,CAAC,UAAU,IAAI,SAAS,KAAK;AAAA,IACvC,aAAa,IAAI,UAAU,IAAI,YAAY,GAAG,KAAK;AAAA,IACnD,UAAU,CAAI,SAAiB,IAAI,SAAY,IAAI;AAAA,IACnD,aAAa,CAAI,SAA0B,IAAI,YAAe,IAAI;AAAA,IAClE,UAAU,CAAC,cAAc,IAAI,SAAS,SAAS;AAAA,IAC/C,WAAW,CAAC,YAAY,UAAU,IAAI,UAAU,YAAY,KAAK;AAAA,IACjE,eAAe,CAAC,MAAM,SAAS,IAAI,cAAc,MAAM,IAAI;AAAA,IAC3D,MAAM,CAAC,cAAc,SAAS,IAAI,KAAK,WAAW,GAAG,IAAI;AAAA,IACzD,eAAe,MAAM,IAAI,cAAc;AAAA,IACvC,gBAAgB,CAAwC,UAAc,IAAI,eAAe,KAAK;AAAA,IAC9F,UAAU,MAAM,IAAI,SAAS;AAAA,IAC7B,mBAAmB,MAAM,IAAI,kBAAkB;AAAA,IAC/C,QAAQ,MAAM,WAAW,OAAO;AAAA,IAChC,SAAS,MAAM,WAAW,QAAQ;AAAA,EACpC;AACF;",
+  "names": []
+}

package/src/testing/recordKernelErrors.d.ts

@@ -0,0 +1,21 @@
+import type { ConsoleLogger } from '../utils/ConsoleLogger.js';
+import type { KernelErrorRecord } from './types.js';
+export interface KernelErrorRecorder {
+    readonly records: readonly KernelErrorRecord[];
+    clear(): void;
+    unhook(): void;
+}
+/**
+ * Records what a Kernel reports through its logger, and keeps it off the console.
+ *
+ * The Kernel answers a failing teardown by reporting it and carrying on -- `runGuarded()` hands
+ * nothing back to a caller, because on that path there is no caller left to decide anything. A test
+ * therefore has no way to see a Shadow Object whose `onDestroy` threw, unless it watches the logger.
+ *
+ * `error` and `warn` live on `ConsoleLogger.prototype`, so writing them here shadows them with own
+ * properties and `unhook()` deletes those again. `warn` is recorded even though the real method is
+ * gated behind `ConsoleLogger.isWarn`, which is off outside a loopback host: a test wants the report
+ * whatever the host it runs on happens to be.
+ */
+export declare function recordKernelErrors(logger: ConsoleLogger, echo?: boolean): KernelErrorRecorder;
+//# sourceMappingURL=recordKernelErrors.d.ts.map

package/src/testing/recordKernelErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordKernelErrors.d.ts","sourceRoot":"","sources":["../../../src/testing/recordKernelErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,UAAQ,GAAG,mBAAmB,CAwC3F"}

package/src/testing/recordKernelErrors.js

@@ -0,0 +1,39 @@
+function recordKernelErrors(logger, echo = false) {
+  const records = [];
+  const originals = {
+    error: logger.error,
+    warn: logger.warn
+  };
+  const wasOwn = {
+    error: Object.hasOwn(logger, "error"),
+    warn: Object.hasOwn(logger, "warn")
+  };
+  const record = (level) => (...args) => {
+    const last = args.length > 0 ? args[args.length - 1] : void 0;
+    records.push({ level, args, ...last instanceof Error ? { error: last } : {} });
+    if (echo) {
+      originals[level].apply(logger, args);
+    }
+  };
+  logger.error = record("error");
+  logger.warn = record("warn");
+  return {
+    records,
+    clear() {
+      records.length = 0;
+    },
+    unhook() {
+      for (const level of ["error", "warn"]) {
+        if (wasOwn[level]) {
+          logger[level] = originals[level];
+        } else {
+          delete logger[level];
+        }
+      }
+    }
+  };
+}
+export {
+  recordKernelErrors
+};
+//# sourceMappingURL=recordKernelErrors.js.map

package/src/testing/recordKernelErrors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/testing/recordKernelErrors.ts"],
+  "sourcesContent": ["import type {ConsoleLogger} from '../utils/ConsoleLogger.js';\nimport type {KernelErrorRecord} from './types.js';\n\nexport interface KernelErrorRecorder {\n  readonly records: readonly KernelErrorRecord[];\n  clear(): void;\n  unhook(): void;\n}\n\n/**\n * Records what a Kernel reports through its logger, and keeps it off the console.\n *\n * The Kernel answers a failing teardown by reporting it and carrying on -- `runGuarded()` hands\n * nothing back to a caller, because on that path there is no caller left to decide anything. A test\n * therefore has no way to see a Shadow Object whose `onDestroy` threw, unless it watches the logger.\n *\n * `error` and `warn` live on `ConsoleLogger.prototype`, so writing them here shadows them with own\n * properties and `unhook()` deletes those again. `warn` is recorded even though the real method is\n * gated behind `ConsoleLogger.isWarn`, which is off outside a loopback host: a test wants the report\n * whatever the host it runs on happens to be.\n */\nexport function recordKernelErrors(logger: ConsoleLogger, echo = false): KernelErrorRecorder {\n  const records: KernelErrorRecord[] = [];\n\n  const originals: Record<'error' | 'warn', (...args: any[]) => void> = {\n    error: logger.error,\n    warn: logger.warn,\n  };\n  const wasOwn: Record<'error' | 'warn', boolean> = {\n    error: Object.hasOwn(logger, 'error'),\n    warn: Object.hasOwn(logger, 'warn'),\n  };\n\n  const record =\n    (level: 'error' | 'warn') =>\n    (...args: any[]) => {\n      const last = args.length > 0 ? args[args.length - 1] : undefined;\n      records.push({level, args, ...(last instanceof Error ? {error: last} : {})});\n      if (echo) {\n        originals[level].apply(logger, args);\n      }\n    };\n\n  logger.error = record('error');\n  logger.warn = record('warn');\n\n  return {\n    records,\n    clear() {\n      records.length = 0;\n    },\n    unhook() {\n      for (const level of ['error', 'warn'] as const) {\n        if (wasOwn[level]) {\n          logger[level] = originals[level];\n        } else {\n          delete (logger as Partial<ConsoleLogger>)[level];\n        }\n      }\n    },\n  };\n}\n"],
+  "mappings": "AAqBO,SAAS,mBAAmB,QAAuB,OAAO,OAA4B;AAC3F,QAAM,UAA+B,CAAC;AAEtC,QAAM,YAAgE;AAAA,IACpE,OAAO,OAAO;AAAA,IACd,MAAM,OAAO;AAAA,EACf;AACA,QAAM,SAA4C;AAAA,IAChD,OAAO,OAAO,OAAO,QAAQ,OAAO;AAAA,IACpC,MAAM,OAAO,OAAO,QAAQ,MAAM;AAAA,EACpC;AAEA,QAAM,SACJ,CAAC,UACD,IAAI,SAAgB;AAClB,UAAM,OAAO,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC,IAAI;AACvD,YAAQ,KAAK,EAAC,OAAO,MAAM,GAAI,gBAAgB,QAAQ,EAAC,OAAO,KAAI,IAAI,CAAC,EAAE,CAAC;AAC3E,QAAI,MAAM;AACR,gBAAU,KAAK,EAAE,MAAM,QAAQ,IAAI;AAAA,IACrC;AAAA,EACF;AAEF,SAAO,QAAQ,OAAO,OAAO;AAC7B,SAAO,OAAO,OAAO,MAAM;AAE3B,SAAO;AAAA,IACL;AAAA,IACA,QAAQ;AACN,cAAQ,SAAS;AAAA,IACnB;AAAA,IACA,SAAS;AACP,iBAAW,SAAS,CAAC,SAAS,MAAM,GAAY;AAC9C,YAAI,OAAO,KAAK,GAAG;AACjB,iBAAO,KAAK,IAAI,UAAU,KAAK;AAAA,QACjC,OAAO;AACL,iBAAQ,OAAkC,KAAK;AAAA,QACjD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

package/src/testing/settle.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Waits until the microtask queue is empty, including everything it grows while it is drained.
+ *
+ * A single `await Promise.resolve()` clears one generation of microtasks and lies about the rest,
+ * and the Kernel produces more than one: `dispatchMessageToView()` queues a microtask of its own,
+ * and the `MicrotaskCollector` behind the Entity Contexts is documented to accept writes from
+ * inside its own delivery, which schedules the next round. A macrotask hop waits for all of them.
+ *
+ * `MessageChannel` rather than `setTimeout`, because a test that installs fake timers is a test
+ * that has frozen `setTimeout`, and a `settle()` that never resolves under fake timers is an
+ * afternoon of debugging per consumer. A message port is not a timer. The `setTimeout` fallback
+ * covers a realm that has no `MessageChannel`.
+ */
+export declare function settle(): Promise<void>;
+//# sourceMappingURL=settle.d.ts.map

package/src/testing/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../../src/testing/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAetC"}

package/src/testing/settle.js

@@ -0,0 +1,19 @@
+function settle() {
+  return new Promise((resolve) => {
+    if (typeof MessageChannel === "function") {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = () => {
+        channel.port1.close();
+        channel.port2.close();
+        resolve();
+      };
+      channel.port2.postMessage(void 0);
+    } else {
+      setTimeout(resolve, 0);
+    }
+  });
+}
+export {
+  settle
+};
+//# sourceMappingURL=settle.js.map

package/src/testing/settle.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/testing/settle.ts"],
+  "sourcesContent": ["/**\n * Waits until the microtask queue is empty, including everything it grows while it is drained.\n *\n * A single `await Promise.resolve()` clears one generation of microtasks and lies about the rest,\n * and the Kernel produces more than one: `dispatchMessageToView()` queues a microtask of its own,\n * and the `MicrotaskCollector` behind the Entity Contexts is documented to accept writes from\n * inside its own delivery, which schedules the next round. A macrotask hop waits for all of them.\n *\n * `MessageChannel` rather than `setTimeout`, because a test that installs fake timers is a test\n * that has frozen `setTimeout`, and a `settle()` that never resolves under fake timers is an\n * afternoon of debugging per consumer. A message port is not a timer. The `setTimeout` fallback\n * covers a realm that has no `MessageChannel`.\n */\nexport function settle(): Promise<void> {\n  return new Promise<void>((resolve) => {\n    if (typeof MessageChannel === 'function') {\n      const channel = new MessageChannel();\n      // Assigning `onmessage` starts the port; no explicit `start()` is needed.\n      channel.port1.onmessage = () => {\n        channel.port1.close();\n        channel.port2.close();\n        resolve();\n      };\n      channel.port2.postMessage(undefined);\n    } else {\n      setTimeout(resolve, 0);\n    }\n  });\n}\n"],
+  "mappings": "AAaO,SAAS,SAAwB;AACtC,SAAO,IAAI,QAAc,CAAC,YAAY;AACpC,QAAI,OAAO,mBAAmB,YAAY;AACxC,YAAM,UAAU,IAAI,eAAe;AAEnC,cAAQ,MAAM,YAAY,MAAM;AAC9B,gBAAQ,MAAM,MAAM;AACpB,gBAAQ,MAAM,MAAM;AACpB,gBAAQ;AAAA,MACV;AACA,cAAQ,MAAM,YAAY,MAAS;AAAA,IACrC,OAAO;AACL,iBAAW,SAAS,CAAC;AAAA,IACvB;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}