@spearwolf/shadow-objects 0.33.0 → 0.34.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@spearwolf/shadow-objects",
   "description": "a reactive entity-component framework that feels at home in the shadows",
   "homepage": "https://github.com/spearwolf/shadow-objects/",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "author": {
     "name": "Wolfger Schramm",
     "email": "wolfger@spearwolf.de",
@@ -54,6 +54,10 @@
     "./ConsoleLogger.js": {
       "import": "./src/utils/ConsoleLogger.js",
       "types": "./src/utils/ConsoleLogger.d.ts"
+    },
+    "./FrameLoop.js": {
+      "import": "./src/utils/FrameLoop.js",
+      "types": "./src/utils/FrameLoop.d.ts"
     }
   },
   "sideEffects": [
@@ -69,7 +73,7 @@
     "src/shae-worker.js"
   ],
   "dependencies": {
-    "@spearwolf/eventize": "^5.0.0",
-    "@spearwolf/signalize": "^0.30.0"
+    "@spearwolf/eventize": "^6.2.0",
+    "@spearwolf/signalize": "^1.0.0"
   }
 }

package/src/ChangeTrailRefusedError.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The reason a Shadow Environment refuses a change trail it could only apply in part.
+ *
+ * A change trail is applied entry by entry and the first throw ends the run, so what the Kernel
+ * holds afterwards is always a prefix of the trail: the entries in `[0, appliedCount)` are
+ * applied, the entry at `appliedCount` is the one that threw, and everything behind it was never
+ * attempted. That single number is therefore the whole answer to "how far did it get" — the view
+ * side folds the prefix into its bookkeeping and sends the rest again with the next trail.
+ *
+ * `cause` carries what the entry actually threw. Across a worker boundary that is a
+ * `WorkerReportedError` carrying the wording and the name of the throw; the class of the original
+ * error and the fields it added do not cross the boundary.
+ *
+ * A refusal for a reason that says nothing about how far the Kernel got — a confirmation window
+ * that ran out, a worker that died, a proxy of someone else's making — is not one of these. The
+ * view reads such a reason as "the whole trail may well have been applied", which is the safe
+ * direction: a creation the Kernel already holds an entity for is refused, and the same trail
+ * comes back to the same refusal for as long as the view keeps sending it.
+ */
+export declare class ChangeTrailRefusedError extends Error {
+    /** how many entries of the change trail the Kernel applied before it stopped */
+    readonly appliedCount: number;
+    /** how many entries the change trail carried */
+    readonly entryCount: number;
+    constructor(appliedCount: number, entryCount: number, options?: ErrorOptions);
+}
+//# sourceMappingURL=ChangeTrailRefusedError.d.ts.map

package/src/ChangeTrailRefusedError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeTrailRefusedError.d.ts","sourceRoot":"","sources":["../../src/ChangeTrailRefusedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAK3E;CACF"}

package/src/ChangeTrailRefusedError.js

@@ -0,0 +1,12 @@
+class ChangeTrailRefusedError extends Error {
+  constructor(appliedCount, entryCount, options) {
+    super(`the kernel applied ${appliedCount} of ${entryCount} change trail entries`, options);
+    this.name = "ChangeTrailRefusedError";
+    this.appliedCount = appliedCount;
+    this.entryCount = entryCount;
+  }
+}
+export {
+  ChangeTrailRefusedError
+};
+//# sourceMappingURL=ChangeTrailRefusedError.js.map

package/src/ChangeTrailRefusedError.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ChangeTrailRefusedError.ts"],
+  "sourcesContent": ["/**\n * The reason a Shadow Environment refuses a change trail it could only apply in part.\n *\n * A change trail is applied entry by entry and the first throw ends the run, so what the Kernel\n * holds afterwards is always a prefix of the trail: the entries in `[0, appliedCount)` are\n * applied, the entry at `appliedCount` is the one that threw, and everything behind it was never\n * attempted. That single number is therefore the whole answer to \"how far did it get\" \u2014 the view\n * side folds the prefix into its bookkeeping and sends the rest again with the next trail.\n *\n * `cause` carries what the entry actually threw. Across a worker boundary that is a\n * `WorkerReportedError` carrying the wording and the name of the throw; the class of the original\n * error and the fields it added do not cross the boundary.\n *\n * A refusal for a reason that says nothing about how far the Kernel got \u2014 a confirmation window\n * that ran out, a worker that died, a proxy of someone else's making \u2014 is not one of these. The\n * view reads such a reason as \"the whole trail may well have been applied\", which is the safe\n * direction: a creation the Kernel already holds an entity for is refused, and the same trail\n * comes back to the same refusal for as long as the view keeps sending it.\n */\nexport class ChangeTrailRefusedError extends Error {\n  /** how many entries of the change trail the Kernel applied before it stopped */\n  readonly appliedCount: number;\n\n  /** how many entries the change trail carried */\n  readonly entryCount: number;\n\n  constructor(appliedCount: number, entryCount: number, options?: ErrorOptions) {\n    super(`the kernel applied ${appliedCount} of ${entryCount} change trail entries`, options);\n    this.name = 'ChangeTrailRefusedError';\n    this.appliedCount = appliedCount;\n    this.entryCount = entryCount;\n  }\n}\n"],
+  "mappings": "AAmBO,MAAM,gCAAgC,MAAM;AAAA,EAOjD,YAAY,cAAsB,YAAoB,SAAwB;AAC5E,UAAM,sBAAsB,YAAY,OAAO,UAAU,yBAAyB,OAAO;AACzF,SAAK,OAAO;AACZ,SAAK,eAAe;AACpB,SAAK,aAAa;AAAA,EACpB;AACF;",
+  "names": []
+}

package/src/EntityUuidInUseError.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown when the Kernel is asked to create an entity under a uuid it already holds an entity for.
+ *
+ * A uuid names one entity at a time. The entity behind it keeps its shadow objects, its signals,
+ * its contexts, its token and its properties; the creation that was refused leaves nothing of
+ * itself anywhere, because the guard stands ahead of every write it would make.
+ *
+ * The uuid is free again once `Kernel.destroyEntity()` has been through: whoever wants an entity
+ * built anew under the same uuid destroys the one that stands first.
+ *
+ * In a change trail this is the reason underneath a `ChangeTrailRefusedError`: the trail is
+ * refused at that entry, and `appliedCount` names the prefix the Kernel did apply.
+ */
+export declare class EntityUuidInUseError extends Error {
+    /** the uuid the kernel already holds an entity for */
+    readonly uuid: string;
+    constructor(uuid: string);
+}
+//# sourceMappingURL=EntityUuidInUseError.d.ts.map

package/src/EntityUuidInUseError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityUuidInUseError.d.ts","sourceRoot":"","sources":["../../src/EntityUuidInUseError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAIvB;CACF"}

package/src/EntityUuidInUseError.js

@@ -0,0 +1,11 @@
+class EntityUuidInUseError extends Error {
+  constructor(uuid) {
+    super(`the kernel cannot create an entity because the uuid ${uuid} is already held by another entity`);
+    this.name = "EntityUuidInUseError";
+    this.uuid = uuid;
+  }
+}
+export {
+  EntityUuidInUseError
+};
+//# sourceMappingURL=EntityUuidInUseError.js.map

package/src/EntityUuidInUseError.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/EntityUuidInUseError.ts"],
+  "sourcesContent": ["/**\n * Thrown when the Kernel is asked to create an entity under a uuid it already holds an entity for.\n *\n * A uuid names one entity at a time. The entity behind it keeps its shadow objects, its signals,\n * its contexts, its token and its properties; the creation that was refused leaves nothing of\n * itself anywhere, because the guard stands ahead of every write it would make.\n *\n * The uuid is free again once `Kernel.destroyEntity()` has been through: whoever wants an entity\n * built anew under the same uuid destroys the one that stands first.\n *\n * In a change trail this is the reason underneath a `ChangeTrailRefusedError`: the trail is\n * refused at that entry, and `appliedCount` names the prefix the Kernel did apply.\n */\nexport class EntityUuidInUseError extends Error {\n  /** the uuid the kernel already holds an entity for */\n  readonly uuid: string;\n\n  constructor(uuid: string) {\n    super(`the kernel cannot create an entity because the uuid ${uuid} is already held by another entity`);\n    this.name = 'EntityUuidInUseError';\n    this.uuid = uuid;\n  }\n}\n"],
+  "mappings": "AAaO,MAAM,6BAA6B,MAAM;AAAA,EAI9C,YAAY,MAAc;AACxB,UAAM,uDAAuD,IAAI,oCAAoC;AACrG,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;",
+  "names": []
+}

package/src/WorkerTimeoutError.d.ts

@@ -0,0 +1,25 @@
+import type { WorkerReplyType } from './constants.js';
+/**
+ * The reason a reply from the worker did not arrive in time.
+ *
+ * Four replies of a `RemoteWorkerEnv` have a deadline, and `messageType` names the one that stayed
+ * out: the `Loaded` greeting of the load handshake, the `ImportedModule` answer to an
+ * `importScript()`, the `AppliedChangeTrail` confirmation of a change trail sent with
+ * `waitForConfirmation`, and the `Destroyed` receipt of a teardown.
+ *
+ * `timeout` carries the number of milliseconds that were waited, so a diagnosis knows which of the
+ * four values was in force without reaching for the `timeouts` of the `RemoteWorkerEnv`.
+ *
+ * The error says nothing about what the worker did with the request. A confirmation window that
+ * ran out leaves a Shadow Environment that may well have applied the whole change trail, which is
+ * why `ShadowEnv` books it as applied; `ChangeTrailRefusedError` is the only refusal that names a
+ * number.
+ */
+export declare class WorkerTimeoutError extends Error {
+    /** the type of the message that did not arrive */
+    readonly messageType: WorkerReplyType;
+    /** how many milliseconds were waited for it */
+    readonly timeout: number;
+    constructor(messageType: WorkerReplyType, timeout: number);
+}
+//# sourceMappingURL=WorkerTimeoutError.d.ts.map

package/src/WorkerTimeoutError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerTimeoutError.d.ts","sourceRoot":"","sources":["../../src/WorkerTimeoutError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IAEtC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,YAAY,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAKxD;CACF"}

package/src/WorkerTimeoutError.js

@@ -0,0 +1,12 @@
+class WorkerTimeoutError extends Error {
+  constructor(messageType, timeout) {
+    super(`no ${messageType} message arrived from the worker within ${timeout}ms`);
+    this.name = "WorkerTimeoutError";
+    this.messageType = messageType;
+    this.timeout = timeout;
+  }
+}
+export {
+  WorkerTimeoutError
+};
+//# sourceMappingURL=WorkerTimeoutError.js.map

package/src/WorkerTimeoutError.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/WorkerTimeoutError.ts"],
+  "sourcesContent": ["import type {WorkerReplyType} from './constants.js';\n\n/**\n * The reason a reply from the worker did not arrive in time.\n *\n * Four replies of a `RemoteWorkerEnv` have a deadline, and `messageType` names the one that stayed\n * out: the `Loaded` greeting of the load handshake, the `ImportedModule` answer to an\n * `importScript()`, the `AppliedChangeTrail` confirmation of a change trail sent with\n * `waitForConfirmation`, and the `Destroyed` receipt of a teardown.\n *\n * `timeout` carries the number of milliseconds that were waited, so a diagnosis knows which of the\n * four values was in force without reaching for the `timeouts` of the `RemoteWorkerEnv`.\n *\n * The error says nothing about what the worker did with the request. A confirmation window that\n * ran out leaves a Shadow Environment that may well have applied the whole change trail, which is\n * why `ShadowEnv` books it as applied; `ChangeTrailRefusedError` is the only refusal that names a\n * number.\n */\nexport class WorkerTimeoutError extends Error {\n  /** the type of the message that did not arrive */\n  readonly messageType: WorkerReplyType;\n\n  /** how many milliseconds were waited for it */\n  readonly timeout: number;\n\n  constructor(messageType: WorkerReplyType, timeout: number) {\n    super(`no ${messageType} message arrived from the worker within ${timeout}ms`);\n    this.name = 'WorkerTimeoutError';\n    this.messageType = messageType;\n    this.timeout = timeout;\n  }\n}\n"],
+  "mappings": "AAkBO,MAAM,2BAA2B,MAAM;AAAA,EAO5C,YAAY,aAA8B,SAAiB;AACzD,UAAM,MAAM,WAAW,2CAA2C,OAAO,IAAI;AAC7E,SAAK,OAAO;AACZ,SAAK,cAAc;AACnB,SAAK,UAAU;AAAA,EACjB;AACF;",
+  "names": []
+}

package/src/bundle.d.ts

@@ -2,6 +2,6 @@ import './shae-ent.js';
 import './shae-prop.js';
 import './shae-worker.js';
 declare global {
-    var SHADOW_ENTS_BUNDLE_LOADED: boolean;
+    var SHADOW_OBJECTS_BUNDLE_LOADED: boolean;
 }
 //# sourceMappingURL=bundle.d.ts.map

package/src/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,yBAAyB,EAAE,OAAO,CAAC;CACxC"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,4BAA4B,EAAE,OAAO,CAAC;CAC3C"}

package/src/bundle.js

@@ -1,5 +1,5 @@
 import "./shae-ent.js";
 import "./shae-prop.js";
 import "./shae-worker.js";
-globalThis.SHADOW_ENTS_BUNDLE_LOADED = true;
+globalThis.SHADOW_OBJECTS_BUNDLE_LOADED = true;
 //# sourceMappingURL=bundle.js.map

package/src/bundle.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/bundle.ts"],
-  "sourcesContent": ["import './shae-ent.js';\nimport './shae-prop.js';\nimport './shae-worker.js';\n\ndeclare global {\n  // eslint-disable-next-line no-var\n  var SHADOW_ENTS_BUNDLE_LOADED: boolean;\n}\n\nglobalThis.SHADOW_ENTS_BUNDLE_LOADED = true;"],
-  "mappings": "AAAA,OAAO;AACP,OAAO;AACP,OAAO;AAOP,WAAW,4BAA4B;",
+  "sourcesContent": ["import './shae-ent.js';\nimport './shae-prop.js';\nimport './shae-worker.js';\n\ndeclare global {\n  var SHADOW_OBJECTS_BUNDLE_LOADED: boolean;\n}\n\nglobalThis.SHADOW_OBJECTS_BUNDLE_LOADED = true;\n"],
+  "mappings": "AAAA,OAAO;AACP,OAAO;AACP,OAAO;AAMP,WAAW,+BAA+B;",
   "names": []
 }

package/src/constants.d.ts

@@ -1,4 +1,4 @@
-import type { NamespaceType } from './types.ts';
+import type { NamespaceType } from './types.js';
 export declare enum ChangeTrailPhase {
     StructuralChanges = 1,
     ContentUpdates = 2,
@@ -16,7 +16,7 @@ export declare enum ComponentChangeType {
 export declare const GlobalNS: NamespaceType;
 export declare const VoidToken = "#void";
 /**
- * The event is dispatched by {@link ComponentContext.reCreateChanges} and forwarded to all {@link ViewComponent}.
+ * The event is dispatched by `ComponentContext.reCreateChanges` and forwarded to all `ViewComponent`.
  * The event itself has no other data.
  */
 export declare const ContextLost = "contextLost";
@@ -27,6 +27,13 @@ export declare const Loaded = "loaded";
 export declare const AppliedChangeTrail = "appliedChangeTrail";
 export declare const ImportedModule = "importedModule";
 export declare const Destroyed = "destroyed";
+/**
+ * The four replies a `RemoteWorkerEnv` waits for, each behind a deadline of its own: the `Loaded`
+ * greeting of the load handshake, the `ImportedModule` answer to an `importScript()`, the
+ * `AppliedChangeTrail` confirmation of a change trail sent with `waitForConfirmation`, and the
+ * `Destroyed` receipt of a teardown. A `switch` over the four is exhaustive.
+ */
+export type WorkerReplyType = typeof Loaded | typeof AppliedChangeTrail | typeof ImportedModule | typeof Destroyed;
 /**
  * The `messageToView` event is fired when the kernel receives a message from an entity (to its view component counterpart)
  */

package/src/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAE9C,oBAAY,gBAAgB;IAC1B,iBAAiB,IAAI;IACrB,cAAc,IAAA;IACd,OAAO,IAAA;CACR;AAED,oBAAY,mBAAmB;IAC7B,cAAc,IAAI;IAClB,eAAe,IAAA;IACf,SAAS,IAAA;IACT,WAAW,IAAA;IACX,gBAAgB,IAAA;IAChB,WAAW,IAAA;IACX,UAAU,IAAA;CACX;AAED,eAAO,MAAM,QAAQ,EAAE,aAAgD,CAAC;AAExE,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AACvC,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAC5C,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,eAAO,MAAM,mBAAmB,kBAAkB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAE9C,oBAAY,gBAAgB;IAC1B,iBAAiB,IAAI;IACrB,cAAc,IAAA;IACd,OAAO,IAAA;CACR;AAED,oBAAY,mBAAmB;IAC7B,cAAc,IAAI;IAClB,eAAe,IAAA;IACf,SAAS,IAAA;IACT,WAAW,IAAA;IACX,gBAAgB,IAAA;IAChB,WAAW,IAAA;IACX,UAAU,IAAA;CACX;AAED,eAAO,MAAM,QAAQ,EAAE,aAAmD,CAAC;AAE3E,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,MAAM,GAAG,OAAO,kBAAkB,GAAG,OAAO,cAAc,GAAG,OAAO,SAAS,CAAC;AAEnH;;GAEG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AACvC,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAC5C,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,eAAO,MAAM,mBAAmB,kBAAkB,CAAC"}

package/src/constants.js

@@ -14,7 +14,7 @@ var ComponentChangeType = /* @__PURE__ */ ((ComponentChangeType2) => {
   ComponentChangeType2[ComponentChangeType2["SendEvents"] = 7] = "SendEvents";
   return ComponentChangeType2;
 })(ComponentChangeType || {});
-const GlobalNS = /* @__PURE__ */ Symbol.for("ShadowEntsGlobalNS");
+const GlobalNS = /* @__PURE__ */ Symbol.for("ShadowObjectsGlobalNS");
 const VoidToken = "#void";
 const ContextLost = "contextLost";
 const Configure = "configure";

package/src/constants.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/constants.ts"],
-  "sourcesContent": ["import type {NamespaceType} from './types.ts';\n\nexport enum ChangeTrailPhase {\n  StructuralChanges = 1,\n  ContentUpdates,\n  Removal,\n}\n\nexport enum ComponentChangeType {\n  CreateEntities = 1,\n  DestroyEntities,\n  SetParent,\n  UpdateOrder,\n  ChangeProperties,\n  ChangeToken,\n  SendEvents,\n}\n\nexport const GlobalNS: NamespaceType = Symbol.for('ShadowEntsGlobalNS');\n\nexport const VoidToken = '#void';\n\n/**\n * The event is dispatched by {@link ComponentContext.reCreateChanges} and forwarded to all {@link ViewComponent}.\n * The event itself has no other data.\n */\nexport const ContextLost = 'contextLost';\n\nexport const Configure = 'configure';\nexport const ChangeTrail = 'changeTrail';\nexport const Destroy = 'destroy';\n\nexport const Loaded = 'loaded';\nexport const AppliedChangeTrail = 'appliedChangeTrail';\nexport const ImportedModule = 'importedModule';\nexport const Destroyed = 'destroyed';\n\n/**\n * The `messageToView` event is fired when the kernel receives a message from an entity (to its view component counterpart)\n */\nexport const MessageToView = 'messageToView';\n\nexport const WorkerLoadTimeout = 60000;\nexport const WorkerConfigureTimeout = 60000;\nexport const WorkerChangeTrailTimeout = 5000;\nexport const WorkerDestroyTimeout = 5000;\n\nexport const ShadowObjectsExport = 'shadowObjects';"],
-  "mappings": "AAEO,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,oCAAA,uBAAoB,KAApB;AACA,EAAAA,oCAAA;AACA,EAAAA,oCAAA;AAHU,SAAAA;AAAA,GAAA;AAML,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,0CAAA,oBAAiB,KAAjB;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AAPU,SAAAA;AAAA,GAAA;AAUL,MAAM,WAA0B,uBAAO,IAAI,oBAAoB;AAE/D,MAAM,YAAY;AAMlB,MAAM,cAAc;AAEpB,MAAM,YAAY;AAClB,MAAM,cAAc;AACpB,MAAM,UAAU;AAEhB,MAAM,SAAS;AACf,MAAM,qBAAqB;AAC3B,MAAM,iBAAiB;AACvB,MAAM,YAAY;AAKlB,MAAM,gBAAgB;AAEtB,MAAM,oBAAoB;AAC1B,MAAM,yBAAyB;AAC/B,MAAM,2BAA2B;AACjC,MAAM,uBAAuB;AAE7B,MAAM,sBAAsB;",
+  "sourcesContent": ["import type {NamespaceType} from './types.js';\n\nexport enum ChangeTrailPhase {\n  StructuralChanges = 1,\n  ContentUpdates,\n  Removal,\n}\n\nexport enum ComponentChangeType {\n  CreateEntities = 1,\n  DestroyEntities,\n  SetParent,\n  UpdateOrder,\n  ChangeProperties,\n  ChangeToken,\n  SendEvents,\n}\n\nexport const GlobalNS: NamespaceType = Symbol.for('ShadowObjectsGlobalNS');\n\nexport const VoidToken = '#void';\n\n/**\n * The event is dispatched by `ComponentContext.reCreateChanges` and forwarded to all `ViewComponent`.\n * The event itself has no other data.\n */\nexport const ContextLost = 'contextLost';\n\nexport const Configure = 'configure';\nexport const ChangeTrail = 'changeTrail';\nexport const Destroy = 'destroy';\n\nexport const Loaded = 'loaded';\nexport const AppliedChangeTrail = 'appliedChangeTrail';\nexport const ImportedModule = 'importedModule';\nexport const Destroyed = 'destroyed';\n\n/**\n * The four replies a `RemoteWorkerEnv` waits for, each behind a deadline of its own: the `Loaded`\n * greeting of the load handshake, the `ImportedModule` answer to an `importScript()`, the\n * `AppliedChangeTrail` confirmation of a change trail sent with `waitForConfirmation`, and the\n * `Destroyed` receipt of a teardown. A `switch` over the four is exhaustive.\n */\nexport type WorkerReplyType = typeof Loaded | typeof AppliedChangeTrail | typeof ImportedModule | typeof Destroyed;\n\n/**\n * The `messageToView` event is fired when the kernel receives a message from an entity (to its view component counterpart)\n */\nexport const MessageToView = 'messageToView';\n\nexport const WorkerLoadTimeout = 60000;\nexport const WorkerConfigureTimeout = 60000;\nexport const WorkerChangeTrailTimeout = 5000;\nexport const WorkerDestroyTimeout = 5000;\n\nexport const ShadowObjectsExport = 'shadowObjects';\n"],
+  "mappings": "AAEO,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,oCAAA,uBAAoB,KAApB;AACA,EAAAA,oCAAA;AACA,EAAAA,oCAAA;AAHU,SAAAA;AAAA,GAAA;AAML,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,0CAAA,oBAAiB,KAAjB;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AACA,EAAAA,0CAAA;AAPU,SAAAA;AAAA,GAAA;AAUL,MAAM,WAA0B,uBAAO,IAAI,uBAAuB;AAElE,MAAM,YAAY;AAMlB,MAAM,cAAc;AAEpB,MAAM,YAAY;AAClB,MAAM,cAAc;AACpB,MAAM,UAAU;AAEhB,MAAM,SAAS;AACf,MAAM,qBAAqB;AAC3B,MAAM,iBAAiB;AACvB,MAAM,YAAY;AAalB,MAAM,gBAAgB;AAEtB,MAAM,oBAAoB;AAC1B,MAAM,yBAAyB;AAC/B,MAAM,2BAA2B;AACjC,MAAM,uBAAuB;AAE7B,MAAM,sBAAsB;",
   "names": ["ChangeTrailPhase", "ComponentChangeType"]
 }

package/src/create-worker.bundle.d.ts

@@ -1,3 +1,3 @@
-declare const _default: () => any;
 export default _default;
+declare function _default(): any;
 //# sourceMappingURL=create-worker.bundle.d.ts.map

package/src/create-worker.bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-worker.bundle.d.ts","sourceRoot":"","sources":["../../src/create-worker.bundle.ts"],"names":[],"mappings":";AAQA,wBAAkC"}
+{"version":3,"file":"create-worker.bundle.d.ts","sourceRoot":"","sources":["../../src/create-worker.bundle.ts"],"names":[],"mappings":""}

package/src/create-worker.bundle.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/create-worker.bundle.ts"],
-  "sourcesContent": ["// @ts-ignore\nimport Worker from './bundle.worker.js';\n\n// This module is converted to __inline__ worker code using the esbuild-plugin-inline-worker plugin.\n// It is done in the `bundle.mjs` build script.\n//\n// `worker/WorkerRuntime.ts` => `shadow-objects.worker.js` => `bundle.worker.js`\n\nexport default () => new Worker();"],
+  "sourcesContent": ["// @ts-ignore\nimport Worker from './bundle.worker.js';\n\n// This module is converted to __inline__ worker code using the esbuild-plugin-inline-worker plugin.\n// It is done in the `bundle.mjs` build script.\n//\n// `worker/WorkerRuntime.ts` => `shadow-objects.worker.js` => `bundle.worker.js`\n\nexport default () => new Worker();\n"],
   "mappings": "AACA,OAAO,YAAY;AAOnB,IAAO,+BAAQ,MAAM,IAAI,OAAO;",
   "names": []
 }

package/src/create-worker.d.ts

@@ -1,3 +1,3 @@
-declare const _default: () => Worker;
 export default _default;
+declare function _default(): Worker;
 //# sourceMappingURL=create-worker.d.ts.map

package/src/create-worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-worker.d.ts","sourceRoot":"","sources":["../../src/create-worker.ts"],"names":[],"mappings":";AAAA,wBAA0G"}
+{"version":3,"file":"create-worker.d.ts","sourceRoot":"","sources":["../../src/create-worker.ts"],"names":[],"mappings":""}

package/src/create-worker.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/create-worker.ts"],
-  "sourcesContent": ["export default () => new Worker(new URL('./shadow-objects.worker.js', import.meta.url), {type: 'module'});"],
+  "sourcesContent": ["export default () => new Worker(new URL('./shadow-objects.worker.js', import.meta.url), {type: 'module'});\n"],
   "mappings": "AAAA,IAAO,wBAAQ,MAAM,IAAI,OAAO,IAAI,IAAI,8BAA8B,YAAY,GAAG,GAAG,EAAC,MAAM,SAAQ,CAAC;",
   "names": []
 }

package/src/elements/ShaeElement.d.ts

@@ -1,13 +1,81 @@
 import { Signal } from '@spearwolf/signalize';
-import type { NamespaceType } from '../types.ts';
-export declare class ShaeElement extends HTMLElement {
+import type { NamespaceType } from '../types.js';
+import { ShaeLifecycleElement } from './ShaeLifecycleElement.js';
+/**
+ * The base of the custom elements that pick an environment through their `ns` attribute.
+ *
+ * What it adds to {@link ShaeLifecycleElement} is the namespace: the `ns` attribute, the signal
+ * behind it, the reflection back onto the attribute, and the two ways to hand an environment on to
+ * the next sync. When such an element starts listening and when it lets go is the base's answer,
+ * and it is the same answer `<shae-prop>` gets, which shares that base without this layer.
+ */
+export declare class ShaeElement extends ShaeLifecycleElement {
+    #private;
     static observedAttributes: string[];
     readonly isShaeElement = true;
     readonly ns$: Signal<NamespaceType>;
     get ns(): NamespaceType;
     set ns(ns: NamespaceType);
     constructor();
+    /**
+     * Take the namespace subscription up, and catch up on what changed while nothing was listening.
+     * The namespace half of {@link ShaeLifecycleElement.restore}.
+     *
+     * The catch-up is the half that is easy to leave out and expensive to miss. A released element
+     * still takes writes — the signals are alive — but nothing carries them onto the attributes, so
+     * the two drift apart. Writing the signal's value back here settles that before anything reads an
+     * attribute again: without it, the attribute read on the way in would push the *old* value back
+     * into the signal and the write would be lost without a word. At the first connect the same
+     * write is what carries the normalisation of the constructor's attribute read onto the attribute.
+     */
+    protected restore(): void;
+    /**
+     * Writes an attribute back from a signal, or holds the write until the element first connects.
+     *
+     * A write is parked whenever it happens before the element has connected once — `restore()`'s
+     * own writes on the very first connect are one source, carrying every reflecting signal out to
+     * its attribute, including whatever the constructor's attribute read normalised; any other
+     * write that lands ahead of that first connect is parked the same way. `restore()`'s call sits
+     * in front of the gate on purpose: a `setAttribute` from inside it would re-enter
+     * `attributeChangedCallback` while the subscriptions are still being set up, and running the
+     * writes a few lines further on, once the element is whole, is cheaper than making every
+     * subscription survive being read halfway through. A later write for the same attribute
+     * replaces the parked one — only the value the signal ends up with is worth writing.
+     *
+     * What is written back on connect is what the signals already carry, so the
+     * `attributeChangedCallback` it triggers sets each signal to the value it is already on. For a
+     * signal holding a scalar that is no change and reaches no handler at all; for one holding a
+     * fresh object on every read — `forward-custom-events` builds a new `Set` per read — the write
+     * counts as a change by identity and the reflecting handler runs once more, where the guard on
+     * the attribute value it already wrote stops the second write. Either way the attribute ends up
+     * on the value the signal carries.
+     */
+    protected reflectAttribute(name: string, write: () => void): void;
+    connectedCallback(): void;
+    /**
+     * Release the namespace reflection. The namespace half of {@link ShaeLifecycleElement.teardown}.
+     *
+     * `#pendingReflections` is left alone on purpose: it holds every write parked before the
+     * element's first connect, and that connect is what drains it — a `destroy()` reached first
+     * leaves the map standing for whichever connect comes next.
+     */
+    protected teardown(): void;
     attributeChangedCallback(name: string): void;
+    /**
+     * Hand the environment of this element's namespace on to the next `sync()` — the unconfirmed
+     * path.
+     *
+     * Over a worker it learns nothing of a confirmation the Shadow Environment refused, and no
+     * `syncfailed` event follows. Whoever needs to know switches `auto-sync` off and runs
+     * `syncWait()` from their own loop.
+     */
     syncShadowObjects(): void;
+    /**
+     * Sync the environment of `ns` instead of the one this element sits in right now.
+     *
+     * For the moment an element changes namespaces: the environment it leaves has a change trail
+     * waiting for it, and `this.ns` no longer points at it.
+     */
+    protected syncShadowObjectsOf(ns: NamespaceType): void;
 }
 //# sourceMappingURL=ShaeElement.d.ts.map

package/src/elements/ShaeElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaeElement.d.ts","sourceRoot":"","sources":["../../../src/elements/ShaeElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AA2B/C,qBAAa,WAAY,SAAQ,WAAW;IAC1C,MAAM,CAAC,kBAAkB,WAAa;IAEtC,QAAQ,CAAC,aAAa,QAAQ;IAE9B,QAAQ,CAAC,GAAG,wBAAyC;IAErD,IAAI,EAAE,IAAI,aAAa,CAEtB;IAED,IAAI,EAAE,CAAC,EAAE,EAAE,aAAa,EAMvB;;IAkBD,wBAAwB,CAAC,IAAI,EAAE,MAAM;IAMrC,iBAAiB;CAGlB"}
+{"version":3,"file":"ShaeElement.d.ts","sourceRoot":"","sources":["../../../src/elements/ShaeElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAErE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAQ/C,OAAO,EAAC,oBAAoB,EAAC,MAAM,2BAA2B,CAAC;AA0B/D;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,oBAAoB;;IACnD,MAAM,CAAC,kBAAkB,WAAa;IAEtC,QAAQ,CAAC,aAAa,QAAQ;IAE9B,QAAQ,CAAC,GAAG,wBAAyC;IAErD,IAAI,EAAE,IAAI,aAAa,CAEtB;IAED,IAAI,EAAE,CAAC,EAAE,EAAE,aAAa,EAMvB;IAWD,cAQC;IAyBD;;;;;;;;;;OAUG;IACH,UAAmB,OAAO,IAAI,IAAI,CAKjC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAOhE;IAEQ,iBAAiB,SAwBzB;IAED;;;;;;OAMG;IACH,UAAmB,QAAQ,IAAI,IAAI,CAKlC;IAED,wBAAwB,CAAC,IAAI,EAAE,MAAM,QAIpC;IAED;;;;;;;OAOG;IACH,iBAAiB,SAEhB;IAED;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,EAAE,EAAE,aAAa,QAE9C;CACF"}

package/src/elements/ShaeElement.js

@@ -1,41 +1,32 @@
-import { createSignal, Signal } from "@spearwolf/signalize";
+import { createSignal, hibernate, Signal } from "@spearwolf/signalize";
 import { GlobalNS } from "../constants.js";
 import { readNamespaceAttribute } from "../utils/attr-utils.js";
+import { ConsoleLogger } from "../utils/ConsoleLogger.js";
+import { MicrotaskCollector } from "../utils/MicrotaskCollector.js";
+import { runGuarded } from "../utils/runGuarded.js";
 import { toNamespace } from "../utils/toNamespace.js";
 import { ShadowEnv } from "../view/ShadowEnv.js";
 import { ATTR_NS } from "./constants.js";
+import { ShaeLifecycleElement } from "./ShaeLifecycleElement.js";
 const updateNamespace = (el, ns) => {
   ns.set(readNamespaceAttribute(el));
 };
-const SyncNamespaces = /* @__PURE__ */ new Set();
-let nextSyncIsScheduled = false;
-const syncShadowObjects = (ns) => {
-  SyncNamespaces.add(ns);
-  if (!nextSyncIsScheduled) {
-    nextSyncIsScheduled = true;
-    queueMicrotask(() => {
-      nextSyncIsScheduled = false;
-      for (const ns2 of SyncNamespaces) {
-        ShadowEnv.get(ns2)?.sync();
-      }
-      SyncNamespaces.clear();
-    });
+const logger = new ConsoleLogger("ShaeElement");
+const syncCollector = new MicrotaskCollector((namespaces) => {
+  for (const ns of namespaces.keys()) {
+    runGuarded(logger, () => ShadowEnv.get(ns)?.sync(), "a namespace could not be synced:", ns);
   }
+});
+const collectForSync = (ns) => {
+  syncCollector.add(ns);
 };
-class ShaeElement extends HTMLElement {
+class ShaeElement extends ShaeLifecycleElement {
   constructor() {
     super();
     this.isShaeElement = true;
     this.ns$ = createSignal(GlobalNS);
-    this.ns$.onChange((ns) => {
-      if (typeof ns === "string" && ns.length > 0) {
-        if (this.getAttribute(ATTR_NS) !== ns) {
-          this.setAttribute(ATTR_NS, ns);
-        }
-      } else {
-        this.removeAttribute(ATTR_NS);
-      }
-    });
+    /** Whether this element has been in a tree at least once. */
+    this.#wasConnected = false;
     updateNamespace(this, this.ns$);
   }
   static {
@@ -51,13 +42,126 @@ class ShaeElement extends HTMLElement {
       this.ns$.set(toNamespace(ns));
     }
   }
+  #wasConnected;
+  /** Attribute writes that came in before the first connect, the latest one per attribute. */
+  #pendingReflections;
+  /** Takes the namespace reflection off again. */
+  #nsReflection;
+  /**
+   * Take up everything this element listens to.
+   *
+   * Private rather than overridable, and called from {@link ShaeElement.restore} alone: a subclass
+   * extends the pair `restore()`/`teardown()`, which is where its own signals are there to be
+   * subscribed to.
+   */
+  #subscribe() {
+    this.#nsReflection = this.ns$.onChange((ns) => this.#reflectNamespace(ns));
+  }
+  #reflectNamespace(ns) {
+    this.reflectAttribute(ATTR_NS, () => {
+      if (typeof ns === "string" && ns.length > 0) {
+        if (this.getAttribute(ATTR_NS) !== ns) {
+          this.setAttribute(ATTR_NS, ns);
+        }
+      } else {
+        this.removeAttribute(ATTR_NS);
+      }
+    });
+  }
+  /**
+   * Take the namespace subscription up, and catch up on what changed while nothing was listening.
+   * The namespace half of {@link ShaeLifecycleElement.restore}.
+   *
+   * The catch-up is the half that is easy to leave out and expensive to miss. A released element
+   * still takes writes — the signals are alive — but nothing carries them onto the attributes, so
+   * the two drift apart. Writing the signal's value back here settles that before anything reads an
+   * attribute again: without it, the attribute read on the way in would push the *old* value back
+   * into the signal and the write would be lost without a word. At the first connect the same
+   * write is what carries the normalisation of the constructor's attribute read onto the attribute.
+   */
+  restore() {
+    super.restore();
+    this.#subscribe();
+    this.#reflectNamespace(this.ns$.value);
+  }
+  /**
+   * Writes an attribute back from a signal, or holds the write until the element first connects.
+   *
+   * A write is parked whenever it happens before the element has connected once — `restore()`'s
+   * own writes on the very first connect are one source, carrying every reflecting signal out to
+   * its attribute, including whatever the constructor's attribute read normalised; any other
+   * write that lands ahead of that first connect is parked the same way. `restore()`'s call sits
+   * in front of the gate on purpose: a `setAttribute` from inside it would re-enter
+   * `attributeChangedCallback` while the subscriptions are still being set up, and running the
+   * writes a few lines further on, once the element is whole, is cheaper than making every
+   * subscription survive being read halfway through. A later write for the same attribute
+   * replaces the parked one — only the value the signal ends up with is worth writing.
+   *
+   * What is written back on connect is what the signals already carry, so the
+   * `attributeChangedCallback` it triggers sets each signal to the value it is already on. For a
+   * signal holding a scalar that is no change and reaches no handler at all; for one holding a
+   * fresh object on every read — `forward-custom-events` builds a new `Set` per read — the write
+   * counts as a change by identity and the reflecting handler runs once more, where the guard on
+   * the attribute value it already wrote stops the second write. Either way the attribute ends up
+   * on the value the signal carries.
+   */
+  reflectAttribute(name, write) {
+    if (this.#wasConnected) {
+      write();
+    } else {
+      this.#pendingReflections ??= /* @__PURE__ */ new Map();
+      this.#pendingReflections.set(name, write);
+    }
+  }
+  connectedCallback() {
+    hibernate(() => {
+      super.connectedCallback();
+      this.#wasConnected = true;
+      const pending = this.#pendingReflections;
+      this.#pendingReflections = void 0;
+      if (pending) {
+        for (const write of pending.values()) {
+          write();
+        }
+      }
+    });
+  }
+  /**
+   * Release the namespace reflection. The namespace half of {@link ShaeLifecycleElement.teardown}.
+   *
+   * `#pendingReflections` is left alone on purpose: it holds every write parked before the
+   * element's first connect, and that connect is what drains it — a `destroy()` reached first
+   * leaves the map standing for whichever connect comes next.
+   */
+  teardown() {
+    this.#nsReflection?.();
+    this.#nsReflection = void 0;
+    super.teardown();
+  }
   attributeChangedCallback(name) {
     if (name === ATTR_NS) {
       updateNamespace(this, this.ns$);
     }
   }
+  /**
+   * Hand the environment of this element's namespace on to the next `sync()` — the unconfirmed
+   * path.
+   *
+   * Over a worker it learns nothing of a confirmation the Shadow Environment refused, and no
+   * `syncfailed` event follows. Whoever needs to know switches `auto-sync` off and runs
+   * `syncWait()` from their own loop.
+   */
   syncShadowObjects() {
-    syncShadowObjects(this.ns);
+    collectForSync(this.ns);
+  }
+  /**
+   * Sync the environment of `ns` instead of the one this element sits in right now.
+   *
+   * For the moment an element changes namespaces: the environment it leaves has a change trail
+   * waiting for it, and `this.ns` no longer points at it.
+   */
+  syncShadowObjectsOf(ns) {
+    collectForSync(ns);
   }
 }
 export {