@spearwolf/shadow-objects 0.33.0 → 0.34.0

package/src/view/ViewComponent.d.ts

@@ -1,6 +1,31 @@
 import { ComponentContext } from './ComponentContext.js';
+interface ViewComponentOptions {
+    parent?: ViewComponent | undefined;
+    order?: number | undefined;
+    context?: ComponentContext | undefined;
+    uuid?: string | undefined;
+    autoDestructionOnParentRemoval?: boolean | undefined;
+}
 export declare class ViewComponent {
     #private;
+    /**
+     * The last thing a component says before {@link ViewComponent#destroy} takes every subscription
+     * off it. An integration that put something on the instance — event subscriptions, an own
+     * `dispatchEvent` — hears it here and can set that up again on the same component; a context
+     * that takes the component back in (`vc.context = ctx`) revives it under the same uuid.
+     *
+     * It goes out directly on the component rather than through {@link ViewComponent#dispatchEvent},
+     * so an own `dispatchEvent` an integration installed does not see it and cannot carry it further.
+     * Leaving a context says nothing: `vc.context = null` detaches the component and keeps everything
+     * on it.
+     *
+     * A listener that throws is reported through `console.warn` and costs neither the listeners
+     * behind it their turn nor the component the rest of its teardown.
+     *
+     * Not to be confused with the `Destroyed` exported at the top level of the package: that one is
+     * `'destroyed'` and belongs to the worker channel, this one is `'view-component-destroyed'`.
+     */
+    static readonly Destroyed = "view-component-destroyed";
     get uuid(): string;
     get token(): string | undefined;
     set token(token: string | undefined);
@@ -8,19 +33,31 @@ export declare class ViewComponent {
     set parent(parent: ViewComponent | null | undefined);
     get context(): ComponentContext | undefined;
     /**
-     * @throws {ComponentContextDisposedError} if the new context has been disposed. The component
-     *   keeps its current context in that case: leaving the old one is only worth it if the new
-     *   one can actually be joined.
+     * @throws {ComponentContextDisposedError} if the new {@link ComponentContext} has been disposed.
+     *   The component keeps its current one in that case: leaving the old one is only worth it if
+     *   the new one can actually be joined.
+     * @throws {ComponentUuidInUseError} if another component of the new {@link ComponentContext}
+     *   holds this component's uuid. A uuid names one component of a {@link ComponentContext} at a
+     *   time, and it is free again once its holder has left. This one is thrown after the old
+     *   {@link ComponentContext} has been left, so the component holds none afterwards — assign one
+     *   again to take it back in.
      */
     set context(context: ComponentContext | null | undefined);
     /**
      * A destroyed component is detached from its {@link ComponentContext}: it no longer appears
      * in any change trail and no longer has a corresponding entity.
      *
-     * Every mutation that only concerns the component itself (`token`, `order`, properties, events,
-     * `removeFromParent`, `destroy`) is silently ignored while destroyed. Operations that would tie
-     * a second, live component to it (`addChild`, the `parent` setter) throw instead, because
-     * ignoring them would leave the caller with a wrong picture of the entity tree.
+     * Every mutation that only concerns the component itself (`token`, `order`, properties,
+     * `removeFromParent`) is silently ignored while destroyed. Operations that would tie a second,
+     * live component to it (`addChild`, the `parent` setter) throw instead, because ignoring them
+     * would leave the caller with a wrong picture of the entity tree.
+     * {@link ViewComponent#destroy} finds nothing left to detach and still takes off whatever lies
+     * on the component at that moment.
+     *
+     * Assigning `null` or `undefined` to {@link ViewComponent#context} reports the same state: it
+     * detaches the component without silencing it, so {@link ViewComponent#dispatchEvent} reaches
+     * every listener on it. After a {@link ViewComponent#destroy} it reaches those registered since.
+     * Children are not traversed either way.
      *
      * Assigning a {@link ViewComponent#context} revives the component under the same uuid.
      */
@@ -40,13 +77,18 @@ export declare class ViewComponent {
      * parent is destroyed, so they remain reachable.
      */
     get autoDestructionOnParentRemoval(): boolean;
-    constructor(token: string, options?: {
-        parent?: ViewComponent;
-        order?: number;
-        context?: ComponentContext;
-        uuid?: string;
-        autoDestructionOnParentRemoval?: boolean;
-    });
+    /**
+     * Create a component: `new ViewComponent(token, parent)` hangs it under another component, and
+     * `new ViewComponent(token, options)` takes `parent`, `order`, `context`, `uuid` and
+     * `autoDestructionOnParentRemoval` as an object.
+     *
+     * A {@link ViewComponent} given in place of the options object is read as the parent and as
+     * nothing else — `uuid`, `order` and `context` come from their usual sources, never from it.
+     *
+     * A component created without a `token` carries {@link VoidToken} (`'#void'`).
+     */
+    constructor(token?: string, parent?: ViewComponent);
+    constructor(token?: string, options?: ViewComponentOptions);
     isChildOf(parent: ViewComponent): boolean;
     removeFromParent(): void;
     addChild(child: ViewComponent): void;
@@ -55,9 +97,31 @@ export declare class ViewComponent {
      *   A destroyed component always returns `false`.
      */
     setProperty<T = unknown>(name: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean;
+    /**
+     * Mark a property as set without giving it a value. The entity holds the key and reads it as
+     * `undefined`; {@link ViewComponent.setProperty} with `undefined` removes it instead.
+     *
+     * @returns `true` if this differs from the last value written to the change trail.
+     *   A destroyed component always returns `false`.
+     */
+    setPropertyWithoutValue(name: string): boolean;
     removeProperty(name: string): void;
     dispatchShadowObjectsEvent(type: string, data: unknown, transferables?: Transferable[]): void;
     dispatchEvent(type: string, data: unknown, traverseChildren: boolean): void;
+    /**
+     * End the component: it leaves its {@link ComponentContext} and goes silent. Every `on()` and
+     * `once()` subscription made on it is removed, and a `dispatchEvent` an integration installed on
+     * the instance is dropped with them. A promise from `onceAsync()` is not reached and settles
+     * only when the event it waits for arrives.
+     *
+     * Calling it more than once is safe. Each call takes off what is on the component at that
+     * moment — a subscription made afterwards is heard again.
+     *
+     * {@link ViewComponent.Destroyed} goes out on the component right before the subscriptions come
+     * off, so whoever holds something on it hears it. A listener that wants its subscription back
+     * does not set it up inside the handler — that one would come off with the rest.
+     */
     destroy(): void;
 }
+export {};
 //# sourceMappingURL=ViewComponent.d.ts.map

package/src/view/ViewComponent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ViewComponent.d.ts","sourceRoot":"","sources":["../../../src/view/ViewComponent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC;AAsBtF,qBAAa,aAAa;;IAWxB,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,IAIQ,MAAM,GAAG,SAAS,CAFlC;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAKlC;IAED,IAAI,MAAM,IAAI,aAAa,GAAG,SAAS,CAEtC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAMlD;IAED,IAAI,OAAO,IAAI,gBAAgB,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACH,IAAI,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAyBvD;IAED;;;;;;;;;;OAUG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAMzC;IAED;;;;;;OAMG;IACH,IAAI,8BAA8B,IAAI,OAAO,CAE5C;gBAGC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,aAAa,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,8BAA8B,CAAC,EAAE,OAAO,CAAC;KAC1C;IAwBH,SAAS,CAAC,MAAM,EAAE,aAAa;IAI/B,gBAAgB;IAShB,QAAQ,CAAC,KAAK,EAAE,aAAa;IAuB7B;;;OAGG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO;IAI5F,cAAc,CAAC,IAAI,EAAE,MAAM;IAI3B,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,YAAY,EAAE;IAItF,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO;IAUpE,OAAO;CAKR"}
+{"version":3,"file":"ViewComponent.d.ts","sourceRoot":"","sources":["../../../src/view/ViewComponent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC;AA4BtF,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,8BAA8B,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtD;AAED,qBAAa,aAAa;;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,QAAQ,CAAC,SAAS,8BAA8B;IAYvD,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,IAIQ,MAAM,GAAG,SAAS,CAFlC;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAKlC;IAED,IAAI,MAAM,IAAI,aAAa,GAAG,SAAS,CAEtC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAMlD;IAED,IAAI,OAAO,IAAI,gBAAgB,GAAG,SAAS,CAE1C;IAED;;;;;;;;;OASG;IACH,IAAI,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAqCvD;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAMzC;IAED;;;;;;OAMG;IACH,IAAI,8BAA8B,IAAI,OAAO,CAE5C;IAOD;;;;;;;;;OASG;IACH,YAAY,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,EAAE;IACpD,YAAY,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,EAAE;IAwB5D,SAAS,CAAC,MAAM,EAAE,aAAa,WAE9B;IAED,gBAAgB,SAOf;IAED,QAAQ,CAAC,KAAK,EAAE,aAAa,QAqB5B;IAED;;;OAGG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAE3F;IAED;;;;;;OAMG;IACH,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;IAED,cAAc,CAAC,IAAI,EAAE,MAAM,QAE1B;IAED,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,YAAY,EAAE,QAErF;IAED,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,QAcnE;IAiBD;;;;;;;;;;;;OAYG;IACH,OAAO,SAiBN;CACF"}

package/src/view/ViewComponent.js

@@ -1,4 +1,4 @@
-import { emit, eventize } from "@spearwolf/eventize";
+import { emitSafe, eventize, off } from "@spearwolf/eventize";
 import { VoidToken } from "../constants.js";
 import { generateUUID } from "../utils/generateUUID.js";
 import { ComponentContext, ComponentContextDisposedError } from "./ComponentContext.js";
@@ -15,8 +15,31 @@ function assertUsableAsParent(parent, childContext) {
   if (parent.context !== childContext) {
     throw new ViewComponentError("cannot add a child from another context");
   }
+  if (!childContext.hasComponent(parent)) {
+    throw new ViewComponentError("cannot add a child to a view component its context does not hold");
+  }
 }
 class ViewComponent {
+  static {
+    /**
+     * The last thing a component says before {@link ViewComponent#destroy} takes every subscription
+     * off it. An integration that put something on the instance — event subscriptions, an own
+     * `dispatchEvent` — hears it here and can set that up again on the same component; a context
+     * that takes the component back in (`vc.context = ctx`) revives it under the same uuid.
+     *
+     * It goes out directly on the component rather than through {@link ViewComponent#dispatchEvent},
+     * so an own `dispatchEvent` an integration installed does not see it and cannot carry it further.
+     * Leaving a context says nothing: `vc.context = null` detaches the component and keeps everything
+     * on it.
+     *
+     * A listener that throws is reported through `console.warn` and costs neither the listeners
+     * behind it their turn nor the component the rest of its teardown.
+     *
+     * Not to be confused with the `Destroyed` exported at the top level of the package: that one is
+     * `'destroyed'` and belongs to the worker channel, this one is `'view-component-destroyed'`.
+     */
+    this.Destroyed = "view-component-destroyed";
+  }
   #uuid;
   #token;
   #context;
@@ -49,9 +72,14 @@ class ViewComponent {
     return this.#context;
   }
   /**
-   * @throws {ComponentContextDisposedError} if the new context has been disposed. The component
-   *   keeps its current context in that case: leaving the old one is only worth it if the new
-   *   one can actually be joined.
+   * @throws {ComponentContextDisposedError} if the new {@link ComponentContext} has been disposed.
+   *   The component keeps its current one in that case: leaving the old one is only worth it if
+   *   the new one can actually be joined.
+   * @throws {ComponentUuidInUseError} if another component of the new {@link ComponentContext}
+   *   holds this component's uuid. A uuid names one component of a {@link ComponentContext} at a
+   *   time, and it is free again once its holder has left. This one is thrown after the old
+   *   {@link ComponentContext} has been left, so the component holds none afterwards — assign one
+   *   again to take it back in.
    */
   set context(context) {
     const next = context ?? void 0;
@@ -61,8 +89,9 @@ class ViewComponent {
         `the view component ${this.#uuid} cannot join the component context because it has been disposed`
       );
     }
+    const previousContext = this.#context;
     if (this.#context) {
-      this.destroy();
+      this.#leaveContext();
     }
     this.#context = next;
     try {
@@ -71,15 +100,25 @@ class ViewComponent {
       this.#context = void 0;
       throw error;
     }
+    if (next != null && previousContext != null) {
+      previousContext.transferPropertiesTo(this, next);
+    }
   }
   /**
    * A destroyed component is detached from its {@link ComponentContext}: it no longer appears
    * in any change trail and no longer has a corresponding entity.
    *
-   * Every mutation that only concerns the component itself (`token`, `order`, properties, events,
-   * `removeFromParent`, `destroy`) is silently ignored while destroyed. Operations that would tie
-   * a second, live component to it (`addChild`, the `parent` setter) throw instead, because
-   * ignoring them would leave the caller with a wrong picture of the entity tree.
+   * Every mutation that only concerns the component itself (`token`, `order`, properties,
+   * `removeFromParent`) is silently ignored while destroyed. Operations that would tie a second,
+   * live component to it (`addChild`, the `parent` setter) throw instead, because ignoring them
+   * would leave the caller with a wrong picture of the entity tree.
+   * {@link ViewComponent#destroy} finds nothing left to detach and still takes off whatever lies
+   * on the component at that moment.
+   *
+   * Assigning `null` or `undefined` to {@link ViewComponent#context} reports the same state: it
+   * detaches the component without silencing it, so {@link ViewComponent#dispatchEvent} reaches
+   * every listener on it. After a {@link ViewComponent#destroy} it reaches those registered since.
+   * Children are not traversed either way.
    *
    * Assigning a {@link ViewComponent#context} revives the component under the same uuid.
    */
@@ -132,10 +171,10 @@ class ViewComponent {
   }
   removeFromParent() {
     if (this.#parent) {
-      this.#context?.removeFromParent(this.uuid, this.#parent);
+      this.#context?.removeFromParent(this, this.#parent);
       this.#parent = void 0;
     } else {
-      this.#context?.moveToRoot(this.uuid);
+      this.#context?.moveToRoot(this);
     }
   }
   addChild(child) {
@@ -163,6 +202,16 @@ class ViewComponent {
   setProperty(name, value, isEqual) {
     return this.#context?.setProperty(this, name, value, isEqual) ?? false;
   }
+  /**
+   * Mark a property as set without giving it a value. The entity holds the key and reads it as
+   * `undefined`; {@link ViewComponent.setProperty} with `undefined` removes it instead.
+   *
+   * @returns `true` if this differs from the last value written to the change trail.
+   *   A destroyed component always returns `false`.
+   */
+  setPropertyWithoutValue(name) {
+    return this.#context?.setPropertyWithoutValue(this, name) ?? false;
+  }
   removeProperty(name) {
     this.#context?.removeProperty(this, name);
   }
@@ -170,17 +219,44 @@ class ViewComponent {
     this.#context?.dispatchShadowObjectsEvent(this, type, data, transferables);
   }
   dispatchEvent(type, data, traverseChildren) {
-    emit(this, type, data);
+    emitSafe(this, type, data);
     if (traverseChildren) {
       for (const child of this.#context?.getChildren(this) ?? []) {
         child.dispatchEvent(type, data, traverseChildren);
       }
     }
   }
-  destroy() {
+  /**
+   * Leave the context without ending the component. What a consumer put on the instance — event
+   * subscriptions, an own `dispatchEvent` — belongs to the component and not to its membership in
+   * a context, so a component that is taken back in keeps answering with all of it.
+   */
+  #leaveContext() {
     this.removeFromParent();
-    this.#context?.destroyComponent(this);
+    const context = this.#context;
     this.#context = void 0;
+    context?.destroyComponent(this);
+  }
+  /**
+   * End the component: it leaves its {@link ComponentContext} and goes silent. Every `on()` and
+   * `once()` subscription made on it is removed, and a `dispatchEvent` an integration installed on
+   * the instance is dropped with them. A promise from `onceAsync()` is not reached and settles
+   * only when the event it waits for arrives.
+   *
+   * Calling it more than once is safe. Each call takes off what is on the component at that
+   * moment — a subscription made afterwards is heard again.
+   *
+   * {@link ViewComponent.Destroyed} goes out on the component right before the subscriptions come
+   * off, so whoever holds something on it hears it. A listener that wants its subscription back
+   * does not set it up inside the handler — that one would come off with the rest.
+   */
+  destroy() {
+    this.#leaveContext();
+    if (Object.hasOwn(this, "dispatchEvent")) {
+      delete this.dispatchEvent;
+    }
+    emitSafe(this, ViewComponent.Destroyed);
+    off(this);
   }
 }
 export {

package/src/view/ViewComponent.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/ViewComponent.ts"],
-  "sourcesContent": ["import {emit, eventize} from '@spearwolf/eventize';\nimport {VoidToken} from '../constants.js';\nimport {generateUUID} from '../utils/generateUUID.js';\nimport {ComponentContext, ComponentContextDisposedError} from './ComponentContext.js';\n\nclass ViewComponentError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ViewComponentError';\n  }\n}\n\n/**\n * Guards every path that attaches a child to a parent: the constructor, {@link ViewComponent#addChild}\n * and the `parent` setter all funnel through here so that they fail with the same message.\n */\nfunction assertUsableAsParent(parent: ViewComponent, childContext: ComponentContext | undefined) {\n  if (parent.context == null) {\n    throw new ViewComponentError('cannot add a child to a destroyed view component');\n  }\n  if (parent.context !== childContext) {\n    throw new ViewComponentError('cannot add a child from another context');\n  }\n}\n\nexport class ViewComponent {\n  readonly #uuid: string;\n\n  #token: string;\n\n  #context?: ComponentContext;\n\n  #parent?: ViewComponent;\n  #order = 0;\n  readonly #autoDestructionOnParentRemoval: boolean;\n\n  get uuid() {\n    return this.#uuid;\n  }\n\n  get token() {\n    return this.#token;\n  }\n\n  set token(token: string | undefined) {\n    token ??= VoidToken;\n    if (token === this.#token) return;\n    this.#token = token;\n    this.#context?.changeToken(this, token);\n  }\n\n  get parent(): ViewComponent | undefined {\n    return this.#parent;\n  }\n\n  set parent(parent: ViewComponent | null | undefined) {\n    if (parent) {\n      parent.addChild(this);\n    } else {\n      this.removeFromParent();\n    }\n  }\n\n  get context(): ComponentContext | undefined {\n    return this.#context;\n  }\n\n  /**\n   * @throws {ComponentContextDisposedError} if the new context has been disposed. The component\n   *   keeps its current context in that case: leaving the old one is only worth it if the new\n   *   one can actually be joined.\n   */\n  set context(context: ComponentContext | null | undefined) {\n    const next = context ?? undefined;\n    if (this.#context === next) return;\n\n    // checked before the teardown below, so a rejected join costs the component nothing\n    if (next?.isDisposed) {\n      throw new ComponentContextDisposedError(\n        `the view component ${this.#uuid} cannot join the component context because it has been disposed`,\n      );\n    }\n\n    if (this.#context) {\n      this.destroy();\n    }\n\n    this.#context = next;\n\n    try {\n      next?.addComponent(this);\n    } catch (error) {\n      // a failed join must not leave a destroyed component pointing at a context that never\n      // took it in \u2014 every later mutation would silently go nowhere while `isDestroyed` lies\n      this.#context = undefined;\n      throw error;\n    }\n  }\n\n  /**\n   * A destroyed component is detached from its {@link ComponentContext}: it no longer appears\n   * in any change trail and no longer has a corresponding entity.\n   *\n   * Every mutation that only concerns the component itself (`token`, `order`, properties, events,\n   * `removeFromParent`, `destroy`) is silently ignored while destroyed. Operations that would tie\n   * a second, live component to it (`addChild`, the `parent` setter) throw instead, because\n   * ignoring them would leave the caller with a wrong picture of the entity tree.\n   *\n   * Assigning a {@link ViewComponent#context} revives the component under the same uuid.\n   */\n  get isDestroyed(): boolean {\n    return this.#context == null;\n  }\n\n  /**\n   * The order property sets the order to lay out a component in a children array of the parent component.\n   *\n   * Items in a children array are sorted by ascending order value and then by their insertion order.\n   */\n  get order(): number {\n    return this.#order;\n  }\n\n  set order(order: number | null | undefined) {\n    const prevOrder = this.#order;\n    this.#order = order ?? 0;\n    if (prevOrder !== this.#order) {\n      this.#context?.changeOrder(this);\n    }\n  }\n\n  /**\n   * Whether the corresponding entity should be destroyed when its parent entity is destroyed.\n   *\n   * Set via the constructor option of the same name; immutable after creation.\n   * Children that opt out (the default) are promoted to root entities when their\n   * parent is destroyed, so they remain reachable.\n   */\n  get autoDestructionOnParentRemoval(): boolean {\n    return this.#autoDestructionOnParentRemoval;\n  }\n\n  constructor(\n    token: string,\n    options?: {\n      parent?: ViewComponent;\n      order?: number;\n      context?: ComponentContext;\n      uuid?: string;\n      autoDestructionOnParentRemoval?: boolean;\n    },\n  ) {\n    eventize(this);\n\n    if (options instanceof ViewComponent) {\n      options = {parent: options};\n    }\n\n    this.#uuid = options?.uuid ?? generateUUID();\n\n    this.#token = token ?? VoidToken;\n    this.#order = options?.order ?? 0;\n    this.#parent = options?.parent;\n    this.#autoDestructionOnParentRemoval = options?.autoDestructionOnParentRemoval ?? false;\n\n    const ctx = options?.context ?? ComponentContext.get();\n\n    if (this.#parent) {\n      assertUsableAsParent(this.#parent, ctx);\n    }\n\n    this.context = ctx;\n  }\n\n  isChildOf(parent: ViewComponent) {\n    return this.#parent === parent;\n  }\n\n  removeFromParent() {\n    if (this.#parent) {\n      this.#context?.removeFromParent(this.uuid, this.#parent);\n      this.#parent = undefined;\n    } else {\n      this.#context?.moveToRoot(this.uuid);\n    }\n  }\n\n  addChild(child: ViewComponent) {\n    if (child.#context == null) {\n      throw new ViewComponentError('cannot add a destroyed view component as a child');\n    }\n\n    assertUsableAsParent(this, child.#context);\n\n    // walking up via #parent is safe: the entity tree is kept acyclic by exactly this guard\n    for (let ancestor: ViewComponent | undefined = this; ancestor != null; ancestor = ancestor.#parent) {\n      if (ancestor === child) {\n        throw new ViewComponentError(\n          'cannot add the component itself or one of its ancestors as a child: this would create a cycle',\n        );\n      }\n    }\n\n    if (!child.isChildOf(this)) {\n      child.removeFromParent();\n      child.#parent = this;\n      this.#context!.addToChildren(this, child);\n    }\n  }\n\n  /**\n   * @returns `true` if the value differs from the last one written to the change trail.\n   *   A destroyed component always returns `false`.\n   */\n  setProperty<T = unknown>(name: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean {\n    return this.#context?.setProperty(this, name, value, isEqual) ?? false;\n  }\n\n  removeProperty(name: string) {\n    this.#context?.removeProperty(this, name);\n  }\n\n  dispatchShadowObjectsEvent(type: string, data: unknown, transferables?: Transferable[]) {\n    this.#context?.dispatchShadowObjectsEvent(this, type, data, transferables);\n  }\n\n  dispatchEvent(type: string, data: unknown, traverseChildren: boolean) {\n    emit(this as ViewComponent, type, data);\n\n    if (traverseChildren) {\n      for (const child of this.#context?.getChildren(this) ?? []) {\n        child.dispatchEvent(type, data, traverseChildren);\n      }\n    }\n  }\n\n  destroy() {\n    this.removeFromParent();\n    this.#context?.destroyComponent(this);\n    this.#context = undefined;\n  }\n}"],
-  "mappings": "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",
+  "sourcesContent": ["import {emitSafe, eventize, off} from '@spearwolf/eventize';\nimport {VoidToken} from '../constants.js';\nimport {generateUUID} from '../utils/generateUUID.js';\nimport {ComponentContext, ComponentContextDisposedError} from './ComponentContext.js';\n\nclass ViewComponentError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ViewComponentError';\n  }\n}\n\n/**\n * Guards every path that attaches a child to a parent: the constructor, {@link ViewComponent#addChild}\n * and the `parent` setter all funnel through here so that they fail with the same message.\n */\nfunction assertUsableAsParent(parent: ViewComponent, childContext: ComponentContext | undefined) {\n  if (parent.context == null) {\n    throw new ViewComponentError('cannot add a child to a destroyed view component');\n  }\n  if (parent.context !== childContext) {\n    throw new ViewComponentError('cannot add a child from another context');\n  }\n  // the two checks above ask the instance which context it names; this one asks the context\n  // whether it holds the instance. Both have to agree before a child is hung on the parent \u2014 a\n  // parent the context does not hold would take the child into a children list nobody reads\n  if (!childContext.hasComponent(parent)) {\n    throw new ViewComponentError('cannot add a child to a view component its context does not hold');\n  }\n}\n\ninterface ViewComponentOptions {\n  parent?: ViewComponent | undefined;\n  order?: number | undefined;\n  context?: ComponentContext | undefined;\n  uuid?: string | undefined;\n  autoDestructionOnParentRemoval?: boolean | undefined;\n}\n\nexport class ViewComponent {\n  /**\n   * The last thing a component says before {@link ViewComponent#destroy} takes every subscription\n   * off it. An integration that put something on the instance \u2014 event subscriptions, an own\n   * `dispatchEvent` \u2014 hears it here and can set that up again on the same component; a context\n   * that takes the component back in (`vc.context = ctx`) revives it under the same uuid.\n   *\n   * It goes out directly on the component rather than through {@link ViewComponent#dispatchEvent},\n   * so an own `dispatchEvent` an integration installed does not see it and cannot carry it further.\n   * Leaving a context says nothing: `vc.context = null` detaches the component and keeps everything\n   * on it.\n   *\n   * A listener that throws is reported through `console.warn` and costs neither the listeners\n   * behind it their turn nor the component the rest of its teardown.\n   *\n   * Not to be confused with the `Destroyed` exported at the top level of the package: that one is\n   * `'destroyed'` and belongs to the worker channel, this one is `'view-component-destroyed'`.\n   */\n  static readonly Destroyed = 'view-component-destroyed';\n\n  readonly #uuid: string;\n\n  #token: string;\n\n  #context?: ComponentContext | undefined;\n\n  #parent?: ViewComponent | undefined;\n  #order = 0;\n  readonly #autoDestructionOnParentRemoval: boolean;\n\n  get uuid() {\n    return this.#uuid;\n  }\n\n  get token() {\n    return this.#token;\n  }\n\n  set token(token: string | undefined) {\n    token ??= VoidToken;\n    if (token === this.#token) return;\n    this.#token = token;\n    this.#context?.changeToken(this, token);\n  }\n\n  get parent(): ViewComponent | undefined {\n    return this.#parent;\n  }\n\n  set parent(parent: ViewComponent | null | undefined) {\n    if (parent) {\n      parent.addChild(this);\n    } else {\n      this.removeFromParent();\n    }\n  }\n\n  get context(): ComponentContext | undefined {\n    return this.#context;\n  }\n\n  /**\n   * @throws {ComponentContextDisposedError} if the new {@link ComponentContext} has been disposed.\n   *   The component keeps its current one in that case: leaving the old one is only worth it if\n   *   the new one can actually be joined.\n   * @throws {ComponentUuidInUseError} if another component of the new {@link ComponentContext}\n   *   holds this component's uuid. A uuid names one component of a {@link ComponentContext} at a\n   *   time, and it is free again once its holder has left. This one is thrown after the old\n   *   {@link ComponentContext} has been left, so the component holds none afterwards \u2014 assign one\n   *   again to take it back in.\n   */\n  set context(context: ComponentContext | null | undefined) {\n    const next = context ?? undefined;\n    if (this.#context === next) return;\n\n    // checked before the teardown below, so a rejected join costs the component nothing\n    if (next?.isDisposed) {\n      throw new ComponentContextDisposedError(\n        `the view component ${this.#uuid} cannot join the component context because it has been disposed`,\n      );\n    }\n\n    const previousContext = this.#context;\n\n    if (this.#context) {\n      // leaving, not ending: an element that leaves the document hands its context back and takes\n      // the same component in again when it returns, so the subscriptions on it have to survive\n      this.#leaveContext();\n    }\n\n    this.#context = next;\n\n    try {\n      next?.addComponent(this);\n    } catch (error) {\n      // a failed join must not leave a destroyed component pointing at a context that never\n      // took it in \u2014 every later mutation would silently go nowhere while `isDestroyed` lies\n      this.#context = undefined;\n      throw error;\n    }\n\n    // after the join, not before it: `addComponent` is what creates the ComponentChanges the\n    // properties are written into, so they end up in the same CreateEntities change as the token\n    // and the parent rather than in a separate one behind it. A move to no context carries\n    // nothing \u2014 there is no receiver for it\n    if (next != null && previousContext != null) {\n      previousContext.transferPropertiesTo(this, next);\n    }\n  }\n\n  /**\n   * A destroyed component is detached from its {@link ComponentContext}: it no longer appears\n   * in any change trail and no longer has a corresponding entity.\n   *\n   * Every mutation that only concerns the component itself (`token`, `order`, properties,\n   * `removeFromParent`) is silently ignored while destroyed. Operations that would tie a second,\n   * live component to it (`addChild`, the `parent` setter) throw instead, because ignoring them\n   * would leave the caller with a wrong picture of the entity tree.\n   * {@link ViewComponent#destroy} finds nothing left to detach and still takes off whatever lies\n   * on the component at that moment.\n   *\n   * Assigning `null` or `undefined` to {@link ViewComponent#context} reports the same state: it\n   * detaches the component without silencing it, so {@link ViewComponent#dispatchEvent} reaches\n   * every listener on it. After a {@link ViewComponent#destroy} it reaches those registered since.\n   * Children are not traversed either way.\n   *\n   * Assigning a {@link ViewComponent#context} revives the component under the same uuid.\n   */\n  get isDestroyed(): boolean {\n    return this.#context == null;\n  }\n\n  /**\n   * The order property sets the order to lay out a component in a children array of the parent component.\n   *\n   * Items in a children array are sorted by ascending order value and then by their insertion order.\n   */\n  get order(): number {\n    return this.#order;\n  }\n\n  set order(order: number | null | undefined) {\n    const prevOrder = this.#order;\n    this.#order = order ?? 0;\n    if (prevOrder !== this.#order) {\n      this.#context?.changeOrder(this);\n    }\n  }\n\n  /**\n   * Whether the corresponding entity should be destroyed when its parent entity is destroyed.\n   *\n   * Set via the constructor option of the same name; immutable after creation.\n   * Children that opt out (the default) are promoted to root entities when their\n   * parent is destroyed, so they remain reachable.\n   */\n  get autoDestructionOnParentRemoval(): boolean {\n    return this.#autoDestructionOnParentRemoval;\n  }\n\n  // the parent form is declared first on purpose: ViewComponent has a member for every optional\n  // member of the options type, so without it the compiler resolves `new ViewComponent(t, parent)`\n  // structurally against the options object and reads `uuid`, `order` and `context` off the parent\n  // \u2014 a meaning the body does not have. An object literal is assignable to neither ViewComponent\n  // (private fields) nor the first overload, and lands on the second one\n  /**\n   * Create a component: `new ViewComponent(token, parent)` hangs it under another component, and\n   * `new ViewComponent(token, options)` takes `parent`, `order`, `context`, `uuid` and\n   * `autoDestructionOnParentRemoval` as an object.\n   *\n   * A {@link ViewComponent} given in place of the options object is read as the parent and as\n   * nothing else \u2014 `uuid`, `order` and `context` come from their usual sources, never from it.\n   *\n   * A component created without a `token` carries {@link VoidToken} (`'#void'`).\n   */\n  constructor(token?: string, parent?: ViewComponent);\n  constructor(token?: string, options?: ViewComponentOptions);\n  constructor(token?: string, options?: ViewComponent | ViewComponentOptions) {\n    eventize(this);\n\n    if (options instanceof ViewComponent) {\n      options = {parent: options};\n    }\n\n    this.#uuid = options?.uuid ?? generateUUID();\n\n    this.#token = token ?? VoidToken;\n    this.#order = options?.order ?? 0;\n    this.#parent = options?.parent;\n    this.#autoDestructionOnParentRemoval = options?.autoDestructionOnParentRemoval ?? false;\n\n    const ctx = options?.context ?? ComponentContext.get();\n\n    if (this.#parent) {\n      assertUsableAsParent(this.#parent, ctx);\n    }\n\n    this.context = ctx;\n  }\n\n  isChildOf(parent: ViewComponent) {\n    return this.#parent === parent;\n  }\n\n  removeFromParent() {\n    if (this.#parent) {\n      this.#context?.removeFromParent(this, this.#parent);\n      this.#parent = undefined;\n    } else {\n      this.#context?.moveToRoot(this);\n    }\n  }\n\n  addChild(child: ViewComponent) {\n    if (child.#context == null) {\n      throw new ViewComponentError('cannot add a destroyed view component as a child');\n    }\n\n    assertUsableAsParent(this, child.#context);\n\n    // walking up via #parent is safe: the entity tree is kept acyclic by exactly this guard\n    for (let ancestor: ViewComponent | undefined = this; ancestor != null; ancestor = ancestor.#parent) {\n      if (ancestor === child) {\n        throw new ViewComponentError(\n          'cannot add the component itself or one of its ancestors as a child: this would create a cycle',\n        );\n      }\n    }\n\n    if (!child.isChildOf(this)) {\n      child.removeFromParent();\n      child.#parent = this;\n      this.#context!.addToChildren(this, child);\n    }\n  }\n\n  /**\n   * @returns `true` if the value differs from the last one written to the change trail.\n   *   A destroyed component always returns `false`.\n   */\n  setProperty<T = unknown>(name: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean {\n    return this.#context?.setProperty(this, name, value, isEqual) ?? false;\n  }\n\n  /**\n   * Mark a property as set without giving it a value. The entity holds the key and reads it as\n   * `undefined`; {@link ViewComponent.setProperty} with `undefined` removes it instead.\n   *\n   * @returns `true` if this differs from the last value written to the change trail.\n   *   A destroyed component always returns `false`.\n   */\n  setPropertyWithoutValue(name: string): boolean {\n    return this.#context?.setPropertyWithoutValue(this, name) ?? false;\n  }\n\n  removeProperty(name: string) {\n    this.#context?.removeProperty(this, name);\n  }\n\n  dispatchShadowObjectsEvent(type: string, data: unknown, transferables?: Transferable[]) {\n    this.#context?.dispatchShadowObjectsEvent(this, type, data, transferables);\n  }\n\n  dispatchEvent(type: string, data: unknown, traverseChildren: boolean) {\n    // `emitSafe()`: this is the delivery path of everything the shadow environment sends to the\n    // view, and it is a fan-out twice over -- over the listeners of one component, and, with\n    // `traverseChildren`, over a whole subtree. Under the plain dispatch one listener that throws\n    // would end the delivery and cut off every component below it, and the error would leave\n    // through the message channel that has no caller left to catch it. A failure is reported\n    // through `console.warn` and costs only itself.\n    emitSafe(this as ViewComponent, type, data);\n\n    if (traverseChildren) {\n      for (const child of this.#context?.getChildren(this) ?? []) {\n        child.dispatchEvent(type, data, traverseChildren);\n      }\n    }\n  }\n\n  /**\n   * Leave the context without ending the component. What a consumer put on the instance \u2014 event\n   * subscriptions, an own `dispatchEvent` \u2014 belongs to the component and not to its membership in\n   * a context, so a component that is taken back in keeps answering with all of it.\n   */\n  #leaveContext() {\n    this.removeFromParent();\n\n    // the context pointer goes first: destroyComponent() detaches every component that still\n    // names the context, and would call destroy() on it otherwise\n    const context = this.#context;\n    this.#context = undefined;\n    context?.destroyComponent(this);\n  }\n\n  /**\n   * End the component: it leaves its {@link ComponentContext} and goes silent. Every `on()` and\n   * `once()` subscription made on it is removed, and a `dispatchEvent` an integration installed on\n   * the instance is dropped with them. A promise from `onceAsync()` is not reached and settles\n   * only when the event it waits for arrives.\n   *\n   * Calling it more than once is safe. Each call takes off what is on the component at that\n   * moment \u2014 a subscription made afterwards is heard again.\n   *\n   * {@link ViewComponent.Destroyed} goes out on the component right before the subscriptions come\n   * off, so whoever holds something on it hears it. A listener that wants its subscription back\n   * does not set it up inside the handler \u2014 that one would come off with the rest.\n   */\n  destroy() {\n    this.#leaveContext();\n\n    // an integration may shadow `dispatchEvent` on the instance; dropping the own property\n    // uncovers the method on the prototype again, it does not remove it\n    if (Object.hasOwn(this, 'dispatchEvent')) {\n      delete (this as {dispatchEvent?: ViewComponent['dispatchEvent']}).dispatchEvent;\n    }\n\n    // last, and before the subscriptions come off: the component is in its final shape by now, and\n    // whoever hears this still hears it. Guarded, because the line below is the point of the whole\n    // method: under the plain dispatch a listener that throws would leave through `destroy()` and\n    // take the `off()` with it, and the component would end its life holding every subscription it\n    // was supposed to be rid of.\n    emitSafe(this as ViewComponent, ViewComponent.Destroyed);\n\n    off(this);\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/src/view/cloneChangeTrail.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/cloneChangeTrail.ts"],
-  "sourcesContent": ["import type {ChangeTrailType} from '../types.js';\n\nexport function cloneChangeTrail(trails: ChangeTrailType): ChangeTrailType {\n  return trails.map((trail) => {\n    if (trail.transferables && trail.transferables.length > 0) {\n      const {transferables, ...data} = trail;\n      return structuredClone(data, {transfer: transferables as any});\n    } else {\n      return structuredClone(trail);\n    }\n  });\n}"],
-  "mappings": "AAEO,SAAS,iBAAiB,QAA0C;AACzE,SAAO,OAAO,IAAI,CAAC,UAAU;AAC3B,QAAI,MAAM,iBAAiB,MAAM,cAAc,SAAS,GAAG;AACzD,YAAM,EAAC,eAAe,GAAG,KAAI,IAAI;AACjC,aAAO,gBAAgB,MAAM,EAAC,UAAU,cAAoB,CAAC;AAAA,IAC/D,OAAO;AACL,aAAO,gBAAgB,KAAK;AAAA,IAC9B;AAAA,EACF,CAAC;AACH;",
+  "sourcesContent": ["import type {ChangeTrailType} from '../types.js';\n\nexport function cloneChangeTrail(trails: ChangeTrailType): ChangeTrailType {\n  return trails.map((trail) => {\n    if (trail.transferables && trail.transferables.length > 0) {\n      const {transferables, ...data} = trail;\n      return structuredClone(data, {transfer: transferables});\n    } else {\n      return structuredClone(trail);\n    }\n  });\n}\n"],
+  "mappings": "AAEO,SAAS,iBAAiB,QAA0C;AACzE,SAAO,OAAO,IAAI,CAAC,UAAU;AAC3B,QAAI,MAAM,iBAAiB,MAAM,cAAc,SAAS,GAAG;AACzD,YAAM,EAAC,eAAe,GAAG,KAAI,IAAI;AACjC,aAAO,gBAAgB,MAAM,EAAC,UAAU,cAAa,CAAC;AAAA,IACxD,OAAO;AACL,aAAO,gBAAgB,KAAK;AAAA,IAC9B;AAAA,EACF,CAAC;AACH;",
   "names": []
 }

package/src/worker/MessageRouter.d.ts

@@ -1,10 +1,24 @@
 import { Kernel, type MessageToViewEvent } from '../in-the-dark/Kernel.js';
+import { ConsoleLogger } from '../utils/ConsoleLogger.js';
+/**
+ * A payload this side can read is an object: every branch below takes a `type` off it and
+ * then reads further fields. `null`, `undefined`, a number or a string come from someone who
+ * does not speak this protocol, and reading through them takes the whole worker down over one
+ * message. Deliberately a plain boolean rather than a type predicate: `event.data` is `any` on
+ * both call sites, and narrowing it would only cost the branches below the payload types they
+ * already have.
+ */
+export declare const isReadableMessageData: (data: unknown) => boolean;
 export interface MessageRouterOptions {
     kernel?: Kernel;
     postMessage?: typeof self.postMessage;
 }
 export declare class MessageRouter {
     #private;
+    /** The logger this router reports through. */
+    get logger(): ConsoleLogger;
+    /** Whether this router has been torn down. Once it is, every message that reaches it is discarded. */
+    get isDestroyed(): boolean;
     kernel: Kernel;
     postMessage: typeof self.postMessage;
     constructor(options?: MessageRouterOptions);

package/src/worker/MessageRouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MessageRouter.d.ts","sourceRoot":"","sources":["../../../src/worker/MessageRouter.ts"],"names":[],"mappings":"AAYA,OAAO,EAAC,MAAM,EAAE,KAAK,kBAAkB,EAAC,MAAM,0BAA0B,CAAC;AAQzE,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,IAAI,CAAC,WAAW,CAAC;CACvC;AAED,qBAAa,aAAa;;IAGxB,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW,EAAE,OAAO,IAAI,CAAC,WAAW,CAAC;gBAEzB,OAAO,CAAC,EAAE,oBAAoB;IAQ1C,KAAK,CAAC,KAAK,EAAE,YAAY;IAmBzB,eAAe,CAAC,KAAK,EAAE,kBAAkB;CA+C1C"}
+{"version":3,"file":"MessageRouter.d.ts","sourceRoot":"","sources":["../../../src/worker/MessageRouter.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,MAAM,EAAE,KAAK,kBAAkB,EAAC,MAAM,0BAA0B,CAAC;AAEzE,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAgBxD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,SAAU,OAAO,KAAG,OAAoD,CAAC;AA2B3G,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,IAAI,CAAC,WAAW,CAAC;CACvC;AAED,qBAAa,aAAa;;IAcxB,8CAA8C;IAC9C,IAAI,MAAM,IAAI,aAAa,CAE1B;IAID,sGAAsG;IACtG,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW,EAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IAErC,YAAY,OAAO,CAAC,EAAE,oBAAoB,EAMzC;IAED,KAAK,CAAC,KAAK,EAAE,YAAY,QAiCxB;IAED,eAAe,CAAC,KAAK,EAAE,kBAAkB,QAIxC;CAyFF"}

package/src/worker/MessageRouter.js

@@ -1,4 +1,5 @@
 import { off, on } from "@spearwolf/eventize";
+import { ChangeTrailRefusedError } from "../ChangeTrailRefusedError.js";
 import {
   AppliedChangeTrail,
   ChangeTrail,
@@ -9,34 +10,71 @@ import {
   MessageToView,
   ShadowObjectsExport
 } from "../constants.js";
-import { importModule } from "../in-the-dark/importModule.js";
+import { importModule, missingShadowObjectsExportMessage } from "../in-the-dark/importModule.js";
 import { Kernel } from "../in-the-dark/Kernel.js";
+import { ConsoleLogger } from "../utils/ConsoleLogger.js";
 import { toUrlString } from "../utils/toUrlString.js";
+const isReadableMessageData = (data) => typeof data === "object" && data !== null;
+const describeError = (error) => {
+  try {
+    return error instanceof Error ? { error: error.message || String(error), errorName: error.name } : { error: String(error) || "unknown error" };
+  } catch {
+    return { error: "an error that cannot be described" };
+  }
+};
 class MessageRouter {
   #importedModules = /* @__PURE__ */ new Set();
+  /**
+   * Built in the field initializer rather than on first read, the way the lazy getter
+   * `WorkerRuntime.logger` has to be: a `MessageRouter` is only ever built from
+   * `WorkerRuntime.onmessage`, and only past the branch that answers the `CONSOLE_LOGGER`
+   * configuration message and returns -- so by the time this initializer runs, that configuration
+   * has already been installed. The `Kernel` this router holds builds its own logger the same way,
+   * in its own field initializer, on the same guarantee; which of the two is built first is not
+   * something either one depends on.
+   */
+  #logger = new ConsoleLogger("MessageRouter");
+  /** The logger this router reports through. */
+  get logger() {
+    return this.#logger;
+  }
+  #isDestroyed = false;
+  /** Whether this router has been torn down. Once it is, every message that reaches it is discarded. */
+  get isDestroyed() {
+    return this.#isDestroyed;
+  }
   constructor(options) {
     this.kernel = options?.kernel ?? new Kernel();
     this.postMessage = options?.postMessage ?? self.postMessage.bind(self);
     on(this.kernel, MessageToView, "onMessageToView", this);
   }
   route(event) {
-    switch (event.data.type) {
+    const data = event.data;
+    if (!isReadableMessageData(data)) {
+      this.logger.debug("discarding a message it cannot read", data);
+      return;
+    }
+    if (this.#isDestroyed) {
+      this.logger.debug("discarding a message that arrived after the teardown", data.type);
+      return;
+    }
+    switch (data.type) {
       case Configure:
-        this.#configure(event.data);
+        this.#configure(data);
         break;
       case ChangeTrail:
-        this.#onChangeTrail(event.data);
+        this.#onChangeTrail(data);
         break;
       case Destroy:
-        this.#onDestroy(event.data);
+        this.#onDestroy(data);
         break;
       default:
-        console.warn("[MessageRouter] unknown message", event.data.type ?? event.data);
+        this.logger.warn("unknown message", data.type ?? data);
     }
   }
   onMessageToView(event) {
     const { transferables: transfer, ...data } = event;
-    this.postMessage({ type: MessageToView, data }, { transfer });
+    this.postMessage({ type: MessageToView, data }, { transfer: transfer ?? [] });
   }
   async #configure(data) {
     const url = data.importModule;
@@ -46,6 +84,10 @@ class MessageRouter {
         /* @vite-ignore */
         toUrlString(url)
       );
+      if (this.#isDestroyed) {
+        this.logger.debug("discarding a module that arrived after the teardown", url);
+        return;
+      }
       if (module[ShadowObjectsExport]) {
         await importModule(this.kernel, module[ShadowObjectsExport], this.#importedModules);
         this.postMessage({ type: ImportedModule, url });
@@ -53,33 +95,51 @@ class MessageRouter {
         this.postMessage({
           type: ImportedModule,
           url,
-          error: `module has no "${ShadowObjectsExport}" export`
+          error: missingShadowObjectsExportMessage
         });
       }
     } catch (error) {
-      console.error("[MessageRouter] failed to import module", error);
-      this.postMessage({ type: ImportedModule, url, error: `${error}` });
+      this.logger.error("failed to import module", error);
+      this.postMessage({ type: ImportedModule, url, ...describeError(error) });
     }
   }
   #onChangeTrail(data) {
     try {
       this.kernel.run(data);
     } catch (error) {
-      console.error("[MessageRouter] failed to apply change trail", error);
-      this.postMessage({ type: AppliedChangeTrail, serial: data.serial, error: `${error}` });
+      this.logger.error("failed to apply change trail", error);
+      if (data.serial != null) {
+        const refusal = error instanceof ChangeTrailRefusedError ? error : void 0;
+        this.postMessage({
+          type: AppliedChangeTrail,
+          serial: data.serial,
+          // what the entry threw, not the refusal wrapped around it: the number travels in a
+          // field of its own, so the reason stays the reason
+          ...describeError(refusal?.cause ?? error),
+          ...refusal ? { appliedCount: refusal.appliedCount } : {}
+        });
+      }
+      return;
     }
-    if (data.serial) {
+    if (data.serial != null) {
       this.postMessage({ type: AppliedChangeTrail, serial: data.serial });
     }
   }
   #onDestroy(data) {
-    console.debug("[MessageRouter] on destroy", data);
+    this.logger.debug("on destroy", data);
+    this.#isDestroyed = true;
     off(this.kernel, this);
+    try {
+      this.kernel.destroy();
+    } catch (error) {
+      this.logger.error("failed to tear the kernel down", error);
+    }
     this.#importedModules.clear();
     this.postMessage({ type: Destroyed });
   }
 }
 export {
-  MessageRouter
+  MessageRouter,
+  isReadableMessageData
 };
 //# sourceMappingURL=MessageRouter.js.map