@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/utils/waitForMessageOfType.d.ts

@@ -1,9 +1,20 @@
+import type { WorkerReplyType } from '../constants.js';
+/**
+ * The largest delay a timer actually keeps. `setTimeout()` truncates its delay into a signed
+ * 32-bit field, so a larger number comes back out as some other, shorter one: a millisecond
+ * past this bound already fires at once. Whatever it lands on, it is not the wait that was
+ * asked for, and nothing says so.
+ */
+export declare const MaxWorkerTimeout = 2147483647;
+export declare const isTimeout: (value: unknown) => value is number;
 /**
  * Wait for a message of a specific type or reject after a timeout.
  *
+ * A deadline that runs out rejects with a `WorkerTimeoutError`.
+ *
  * A `signal` rejects the promise the moment it is aborted, with the abort reason,
  * so that a caller does not sit out the timeout waiting for a reply that can no
  * longer arrive.
  */
-export declare const waitForMessageOfType: (worker: Worker, type: string, timeout?: number, guard?: (data: any) => boolean, signal?: AbortSignal) => Promise<void>;
+export declare const waitForMessageOfType: <T = unknown>(worker: Worker, type: WorkerReplyType, timeout?: number, guard?: (data: T) => boolean, signal?: AbortSignal) => Promise<void>;
 //# sourceMappingURL=waitForMessageOfType.d.ts.map

package/src/utils/waitForMessageOfType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"waitForMessageOfType.d.ts","sourceRoot":"","sources":["../../../src/utils/waitForMessageOfType.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,gBAAc,EACd,QAAQ,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAC9B,SAAS,WAAW,kBAiDlB,CAAC"}
+{"version":3,"file":"waitForMessageOfType.d.ts","sourceRoot":"","sources":["../../../src/utils/waitForMessageOfType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iBAAiB,CAAC;AAIrD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,aAAgB,CAAC;AAE9C,eAAO,MAAM,SAAS,UAAW,OAAO,KAAG,KAAK,IAAI,MAC2C,CAAC;AAEhG;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,GAAG,OAAO,UACtC,MAAM,QACR,eAAe,4BAEb,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,WACnB,WAAW,kBA6DlB,CAAC"}

package/src/utils/waitForMessageOfType.js

@@ -1,4 +1,16 @@
+import { WorkerTimeoutError } from "../WorkerTimeoutError.js";
+import { isReadableMessageData } from "../worker/MessageRouter.js";
+const MaxWorkerTimeout = 2147483647;
+const isTimeout = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 && value <= MaxWorkerTimeout;
 const waitForMessageOfType = (worker, type, timeout = 1e3, guard, signal) => new Promise((resolve, reject) => {
+  if (timeout !== 0 && timeout !== Infinity && !isTimeout(timeout)) {
+    reject(
+      new TypeError(
+        `cannot wait for a ${type} message: expected a timeout of 1 to ${MaxWorkerTimeout} milliseconds, or 0 or Infinity for no deadline, got ${String(timeout)}`
+      )
+    );
+    return;
+  }
   if (signal?.aborted) {
     reject(signal.reason);
     return;
@@ -17,10 +29,11 @@ const waitForMessageOfType = (worker, type, timeout = 1e3, guard, signal) => new
   if (timeout !== 0 && timeout !== Infinity) {
     timeoutId = setTimeout(() => {
       cleanup();
-      reject(new Error(`Timeout waiting for message of type: ${type}`));
+      reject(new WorkerTimeoutError(type, timeout));
     }, timeout);
   }
   listener = (event) => {
+    if (!isReadableMessageData(event.data)) return;
     if (event.data.type === type) {
       try {
         if (!guard || guard(event.data)) {
@@ -37,6 +50,8 @@ const waitForMessageOfType = (worker, type, timeout = 1e3, guard, signal) => new
   worker.addEventListener("message", listener);
 });
 export {
+  MaxWorkerTimeout,
+  isTimeout,
   waitForMessageOfType
 };
 //# sourceMappingURL=waitForMessageOfType.js.map

package/src/utils/waitForMessageOfType.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/waitForMessageOfType.ts"],
-  "sourcesContent": ["/**\n * Wait for a message of a specific type or reject after a timeout.\n *\n * A `signal` rejects the promise the moment it is aborted, with the abort reason,\n * so that a caller does not sit out the timeout waiting for a reply that can no\n * longer arrive.\n */\nexport const waitForMessageOfType = (\n  worker: Worker,\n  type: string,\n  timeout = 1000,\n  guard?: (data: any) => boolean,\n  signal?: AbortSignal,\n) =>\n  new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(signal.reason);\n      return;\n    }\n\n    let timeoutId: number;\n    // eslint-disable-next-line prefer-const\n    let listener: (event: MessageEvent) => void;\n\n    const cleanup = () => {\n      clearTimeout(timeoutId);\n      worker.removeEventListener('message', listener);\n      signal?.removeEventListener('abort', onAbort);\n    };\n\n    // a function declaration, so that `cleanup` may reference it above its own definition;\n    // it only ever runs when a signal was passed in, since that is the only case where it gets registered below\n    function onAbort() {\n      cleanup();\n      reject(signal!.reason);\n    }\n\n    if (timeout !== 0 && timeout !== Infinity) {\n      timeoutId = setTimeout(() => {\n        cleanup();\n        reject(new Error(`Timeout waiting for message of type: ${type}`));\n      }, timeout) as any;\n    }\n\n    listener = (event) => {\n      if (event.data.type === type) {\n        try {\n          if (!guard || guard(event.data)) {\n            cleanup();\n            resolve();\n          }\n        } catch (error) {\n          cleanup();\n          reject(error);\n        }\n      }\n    };\n\n    signal?.addEventListener('abort', onAbort, {once: true});\n\n    worker.addEventListener('message', listener);\n  });"],
-  "mappings": "AAOO,MAAM,uBAAuB,CAClC,QACA,MACA,UAAU,KACV,OACA,WAEA,IAAI,QAAc,CAAC,SAAS,WAAW;AACrC,MAAI,QAAQ,SAAS;AACnB,WAAO,OAAO,MAAM;AACpB;AAAA,EACF;AAEA,MAAI;AAEJ,MAAI;AAEJ,QAAM,UAAU,MAAM;AACpB,iBAAa,SAAS;AACtB,WAAO,oBAAoB,WAAW,QAAQ;AAC9C,YAAQ,oBAAoB,SAAS,OAAO;AAAA,EAC9C;AAIA,WAAS,UAAU;AACjB,YAAQ;AACR,WAAO,OAAQ,MAAM;AAAA,EACvB;AAEA,MAAI,YAAY,KAAK,YAAY,UAAU;AACzC,gBAAY,WAAW,MAAM;AAC3B,cAAQ;AACR,aAAO,IAAI,MAAM,wCAAwC,IAAI,EAAE,CAAC;AAAA,IAClE,GAAG,OAAO;AAAA,EACZ;AAEA,aAAW,CAAC,UAAU;AACpB,QAAI,MAAM,KAAK,SAAS,MAAM;AAC5B,UAAI;AACF,YAAI,CAAC,SAAS,MAAM,MAAM,IAAI,GAAG;AAC/B,kBAAQ;AACR,kBAAQ;AAAA,QACV;AAAA,MACF,SAAS,OAAO;AACd,gBAAQ;AACR,eAAO,KAAK;AAAA,MACd;AAAA,IACF;AAAA,EACF;AAEA,UAAQ,iBAAiB,SAAS,SAAS,EAAC,MAAM,KAAI,CAAC;AAEvD,SAAO,iBAAiB,WAAW,QAAQ;AAC7C,CAAC;",
+  "sourcesContent": ["import type {WorkerReplyType} from '../constants.js';\nimport {WorkerTimeoutError} from '../WorkerTimeoutError.js';\nimport {isReadableMessageData} from '../worker/MessageRouter.js';\n\n/**\n * The largest delay a timer actually keeps. `setTimeout()` truncates its delay into a signed\n * 32-bit field, so a larger number comes back out as some other, shorter one: a millisecond\n * past this bound already fires at once. Whatever it lands on, it is not the wait that was\n * asked for, and nothing says so.\n */\nexport const MaxWorkerTimeout = 2_147_483_647;\n\nexport const isTimeout = (value: unknown): value is number =>\n  typeof value === 'number' && Number.isFinite(value) && value > 0 && value <= MaxWorkerTimeout;\n\n/**\n * Wait for a message of a specific type or reject after a timeout.\n *\n * A deadline that runs out rejects with a `WorkerTimeoutError`.\n *\n * A `signal` rejects the promise the moment it is aborted, with the abort reason,\n * so that a caller does not sit out the timeout waiting for a reply that can no\n * longer arrive.\n */\nexport const waitForMessageOfType = <T = unknown>(\n  worker: Worker,\n  type: WorkerReplyType,\n  timeout = 1000,\n  guard?: (data: T) => boolean,\n  signal?: AbortSignal,\n) =>\n  new Promise<void>((resolve, reject) => {\n    if (timeout !== 0 && timeout !== Infinity && !isTimeout(timeout)) {\n      reject(\n        new TypeError(\n          `cannot wait for a ${type} message: expected a timeout of 1 to ${MaxWorkerTimeout} milliseconds, or 0 or Infinity for no deadline, got ${String(timeout)}`,\n        ),\n      );\n      return;\n    }\n\n    if (signal?.aborted) {\n      reject(signal.reason);\n      return;\n    }\n\n    let timeoutId: ReturnType<typeof setTimeout>;\n    let listener: (event: MessageEvent) => void;\n\n    const cleanup = () => {\n      clearTimeout(timeoutId);\n      worker.removeEventListener('message', listener);\n      signal?.removeEventListener('abort', onAbort);\n    };\n\n    // a function declaration, so that `cleanup` may reference it above its own definition;\n    // it only ever runs when a signal was passed in, since that is the only case where it gets registered below\n    function onAbort() {\n      cleanup();\n      reject(signal!.reason);\n    }\n\n    if (timeout !== 0 && timeout !== Infinity) {\n      timeoutId = setTimeout(() => {\n        cleanup();\n        reject(new WorkerTimeoutError(type, timeout));\n      }, timeout);\n    }\n\n    listener = (event) => {\n      // three readers listen on this channel and answer the same way: a payload that is not\n      // an object carries no `type` to route on, and reading through it takes down whoever\n      // reads it -- here, into the listener of every request still waiting\n      if (!isReadableMessageData(event.data)) return;\n      if (event.data.type === type) {\n        try {\n          if (!guard || guard(event.data)) {\n            cleanup();\n            resolve();\n          }\n        } catch (error) {\n          cleanup();\n          reject(error);\n        }\n      }\n    };\n\n    signal?.addEventListener('abort', onAbort, {once: true});\n\n    worker.addEventListener('message', listener);\n  });\n"],
+  "mappings": "AACA,SAAQ,0BAAyB;AACjC,SAAQ,6BAA4B;AAQ7B,MAAM,mBAAmB;AAEzB,MAAM,YAAY,CAAC,UACxB,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,KAAK,QAAQ,KAAK,SAAS;AAWxE,MAAM,uBAAuB,CAClC,QACA,MACA,UAAU,KACV,OACA,WAEA,IAAI,QAAc,CAAC,SAAS,WAAW;AACrC,MAAI,YAAY,KAAK,YAAY,YAAY,CAAC,UAAU,OAAO,GAAG;AAChE;AAAA,MACE,IAAI;AAAA,QACF,qBAAqB,IAAI,wCAAwC,gBAAgB,wDAAwD,OAAO,OAAO,CAAC;AAAA,MAC1J;AAAA,IACF;AACA;AAAA,EACF;AAEA,MAAI,QAAQ,SAAS;AACnB,WAAO,OAAO,MAAM;AACpB;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AAEJ,QAAM,UAAU,MAAM;AACpB,iBAAa,SAAS;AACtB,WAAO,oBAAoB,WAAW,QAAQ;AAC9C,YAAQ,oBAAoB,SAAS,OAAO;AAAA,EAC9C;AAIA,WAAS,UAAU;AACjB,YAAQ;AACR,WAAO,OAAQ,MAAM;AAAA,EACvB;AAEA,MAAI,YAAY,KAAK,YAAY,UAAU;AACzC,gBAAY,WAAW,MAAM;AAC3B,cAAQ;AACR,aAAO,IAAI,mBAAmB,MAAM,OAAO,CAAC;AAAA,IAC9C,GAAG,OAAO;AAAA,EACZ;AAEA,aAAW,CAAC,UAAU;AAIpB,QAAI,CAAC,sBAAsB,MAAM,IAAI,EAAG;AACxC,QAAI,MAAM,KAAK,SAAS,MAAM;AAC5B,UAAI;AACF,YAAI,CAAC,SAAS,MAAM,MAAM,IAAI,GAAG;AAC/B,kBAAQ;AACR,kBAAQ;AAAA,QACV;AAAA,MACF,SAAS,OAAO;AACd,gBAAQ;AACR,eAAO,KAAK;AAAA,MACd;AAAA,IACF;AAAA,EACF;AAEA,UAAQ,iBAAiB,SAAS,SAAS,EAAC,MAAM,KAAI,CAAC;AAEvD,SAAO,iBAAiB,WAAW,QAAQ;AAC7C,CAAC;",
   "names": []
 }

package/src/view/ComponentChanges.d.ts

@@ -1,24 +1,100 @@
 import { ChangeTrailPhase } from '../constants.js';
 import type { IChangeToken, IComponentChangeType, ICreateEntitiesChange, IDestroyEntitiesChange, IPropertiesChange, ISendEvents, ISetParentChange, IUpdateOrderChange } from '../types.js';
+/**
+ * The value a property carries in this bookkeeping when it is set without one — the third form
+ * of {@link ComponentPropertiesType}, which travels as a one-element `[key]`. `undefined`
+ * cannot say it: that is what a removal reads as, and the two have to stay apart all the way
+ * to the entry.
+ *
+ * It never leaves the View Layer. A change trail runs through `structuredClone()` on its way
+ * to a worker, and a symbol on that wire is a `DataCloneError` — so every method that builds
+ * an entry turns it back into the one-element form, and the one reader outside this class,
+ * `ComponentContext.transferPropertiesTo()`, tests for it before it hands a value on.
+ */
+export declare const PropertyWithoutValue: unique symbol;
+/**
+ * Tracks one component's outstanding changes between two change trails as four written ↔
+ * pending pairs: `#token`/`#nextToken`, `#parentUuid`/`#nextParentUuid`, `#order`/`#nextOrder`
+ * and `#properties`/`#nextProperties`. The `make*` methods read the pending half and leave it
+ * where it is: a trail entry is a request, and until the Shadow Environment has applied it the
+ * change is still owed. {@link ComponentChanges.commitChange} is what moves the line — it folds
+ * one applied entry into the written half and releases exactly the pending values that entry
+ * carried, so a value that changed again while the entry was on its way goes out with the next
+ * trail instead of being lost.
+ *
+ * Whether anything is outstanding follows from those pairs rather than from a counter, which is
+ * what lets a partly applied trail leave the rest of the component untouched.
+ *
+ * The create/destroy counts behind {@link ComponentChanges.isCreated} and {@link
+ * ComponentChanges.isDestroyed} belong to the uuid, not to a `ViewComponent` instance. They
+ * carry the rule `ComponentContext.addComponent` keeps: a uuid names one component of a
+ * `ComponentContext` at a time, so a later component takes this bookkeeping over only once
+ * its predecessor has counted its own `destroy()`. A count pair that outlives its component
+ * therefore describes an entity, and the successor on that uuid continues the same entity
+ * rather than starting a second.
+ */
 export declare class ComponentChanges {
     #private;
     get uuid(): string;
     constructor(uuid: string);
+    /**
+     * Whether this component owes the next change trail anything: a creation, a destruction, or a
+     * pending value in one of the four written ↔ pending pairs.
+     */
     hasChanges(): boolean;
     get isNew(): boolean;
     get isCreated(): boolean;
     get isDestroyed(): boolean;
     create(token?: string, parentUuid?: string, order?: number, autoDestructionOnParentRemoval?: boolean): void;
     destroy(): void;
+    /**
+     * Drop every pending value without writing any of them forward.
+     *
+     * This is the way out for a component whose bookkeeping is about to be replaced wholesale —
+     * `ComponentContext.reCreateChanges` does exactly that. A trail that has gone out is
+     * settled with {@link ComponentChanges.commitChange} instead.
+     */
     clear(): void;
+    /**
+     * The three scalar pairs below all answer the same question the same way: is anything owed once
+     * the entry that is on its way out has landed?
+     *
+     * The written half alone cannot answer it. It is the last *confirmed* value and stays behind
+     * until the entry is committed, so a value the caller sets back to it while the entry travels
+     * would look like "nothing to do" — and the entry would then be the last word, leaving the
+     * Shadow Environment holding a value the view has already moved on from. So the pending half is
+     * only released where there is nothing in flight to contradict it; where there is, the new value
+     * takes the pending slot and the emitting side decides, against the written half it settles on.
+     */
     changeToken(token: string | undefined): void;
     setParent(parentUuid?: string): void;
     changeOrder(order: number): void;
     /**
-     * @returns `true` if the value differs from the last value written to a change trail
+     * @returns `true` if the value differs from the last value this component asked for
      */
     changeProperty<T = unknown>(key: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean;
+    /**
+     * Mark `key` as set without giving it a value: the next trail carries an entry that names
+     * only the key. A later {@link ComponentChanges.changeProperty} replaces it with a value,
+     * and {@link ComponentChanges.removeProperty} takes it away like any other property.
+     *
+     * @returns `true` if this differs from the last value this component asked for
+     */
+    setPropertyWithoutValue(key: string): boolean;
     removeProperty(key: string): void;
+    /**
+     * The properties this component holds at this moment: the ones a change trail has already
+     * carried, overlaid with everything that has accrued since.
+     *
+     * The overlay is what makes the result the current state instead of the state of the last
+     * trail — `#properties` is only written forward while a trail is being built
+     * ({@link ComponentChanges.makeCreateEntityChange},
+     * {@link ComponentChanges.makeChangePropertyChange}). A key whose accrued value is `undefined`
+     * and a key queued for change without an accrued value are both removals, and neither appears
+     * in the result. A key that is set without a value stands in the result with
+     * {@link PropertyWithoutValue}.
+     */
+    getProperties(): Map<string, unknown>;
     createEvent(type: string, data: unknown, transferables?: Transferable[]): void;
     transferEventsTo(changes: ComponentChanges): void;
     buildChangeTrail(trail: IComponentChangeType[], trailPhase: ChangeTrailPhase): void;
@@ -29,5 +105,16 @@ export declare class ComponentChanges {
     makeUpdateOrderChange(): IUpdateOrderChange;
     makeChangeToken(): IChangeToken;
     makeChangePropertyChange(): IPropertiesChange;
+    /**
+     * Fold one trail entry into the written half of this component's bookkeeping: the values the
+     * entry carries become the values the next diff is taken against, and the pending half that
+     * produced them is released. Called once per entry the Shadow Environment has applied.
+     *
+     * A pending value is released only while it is still the value the entry carried. Between the
+     * build of a trail and its confirmation lies a round trip, and whatever changed in that window
+     * is owed to the Shadow Environment — releasing it here would leave the two sides holding
+     * different values with nothing left to correct them.
+     */
+    commitChange(entry: IComponentChangeType): void;
 }
 //# sourceMappingURL=ComponentChanges.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ComponentChanges.d.ts","sourceRoot":"","sources":["../../../src/view/ComponentChanges.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,gBAAgB,EAAiC,MAAM,iBAAiB,CAAC;AACjF,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EAEpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAKrB,qBAAa,gBAAgB;;IAG3B,IAAI,IAAI,IAAI,MAAM,CAEjB;gBAIW,IAAI,EAAE,MAAM;IAQxB,UAAU,IAAI,OAAO;IAIrB,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAWD,MAAM,CAAC,KAAK,GAAE,MAAkB,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,EAAE,8BAA8B,UAAQ;IAUhH,OAAO;IAKP,KAAK;IAgBL,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;IAgBrC,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM;IAS7B,WAAW,CAAC,KAAK,EAAE,MAAM;IAazB;;OAEG;IACH,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO;IAgB9F,cAAc,CAAC,GAAG,EAAE,MAAM;IAgB1B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,YAAY,EAAE;IAQvE,gBAAgB,CAAC,OAAO,EAAE,gBAAgB;IAW1C,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAAE,EAAE,UAAU,EAAE,gBAAgB;IAsC5E,UAAU,IAAI,WAAW;IAYzB,sBAAsB,IAAI,qBAAqB;IAuC/C,uBAAuB,IAAI,sBAAsB;IAOjD,mBAAmB,IAAI,gBAAgB;IAgBvC,qBAAqB,IAAI,kBAAkB;IAU3C,eAAe,IAAI,YAAY;IAU/B,wBAAwB,IAAI,iBAAiB;CAwB9C"}
+{"version":3,"file":"ComponentChanges.d.ts","sourceRoot":"","sources":["../../../src/view/ComponentChanges.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,gBAAgB,EAAiC,MAAM,iBAAiB,CAAC;AACjF,OAAO,KAAK,EAEV,YAAY,EACZ,oBAAoB,EAEpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAkD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB;;IAG3B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,YAAY,IAAI,EAAE,MAAM,EAEvB;IAMD;;;OAGG;IACH,UAAU,IAAI,OAAO,CAUpB;IAED,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAWD,MAAM,CAAC,KAAK,GAAE,MAAkB,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,EAAE,8BAA8B,UAAQ,QAO/G;IAED,OAAO,SAEN;IAWD;;;;;;OAMG;IACH,KAAK,SAWJ;IAED;;;;;;;;;;OAUG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,QAWpC;IAED,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,QAM5B;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,QAIxB;IAwBD;;OAEG;IACH,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CA+C7F;IAED;;;;;;OAMG;IACH,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE5C;IAED,cAAc,CAAC,GAAG,EAAE,MAAM,QAgBzB;IAED;;;;;;;;;;;OAWG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAapC;IAKD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,YAAY,EAAE,QAKtE;IAED,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,QASzC;IAED,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAAE,EAAE,UAAU,EAAE,gBAAgB,QAoC3E;IAED,UAAU,IAAI,WAAW,CAUxB;IAED,sBAAsB,IAAI,qBAAqB,CA2C9C;IAED,uBAAuB,IAAI,sBAAsB,CAKhD;IAED,mBAAmB,IAAI,gBAAgB,CAYtC;IAED,qBAAqB,IAAI,kBAAkB,CAM1C;IAED,eAAe,IAAI,YAAY,CAM9B;IAED,wBAAwB,IAAI,iBAAiB,CAgB5C;IAaD;;;;;;;;;OASG;IACH,YAAY,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CA4D9C;CA0CF"}

package/src/view/ComponentChanges.js

@@ -1,20 +1,24 @@
 import { ChangeTrailPhase, ComponentChangeType, VoidToken } from "../constants.js";
 import { appendToEnd, removeFrom } from "../utils/array-utils.js";
 const ROOT = "#root";
+const PropertyWithoutValue = /* @__PURE__ */ Symbol("shadow-objects/property-without-value");
 class ComponentChanges {
   #uuid;
   get uuid() {
     return this.#uuid;
   }
-  #serial = 0;
   constructor(uuid) {
     this.#uuid = uuid;
   }
   #isNew = true;
   #createCount = 0;
   #destroyCount = 0;
+  /**
+   * Whether this component owes the next change trail anything: a creation, a destruction, or a
+   * pending value in one of the four written ↔ pending pairs.
+   */
   hasChanges() {
-    return this.#serial > 0;
+    return this.#isNew && this.isCreated || this.isDestroyed || this.#nextToken !== void 0 && this.#nextToken !== this.#token || this.#hasPendingParent() || this.#nextOrder !== void 0 && this.#nextOrder !== this.#order || this.#propsChangeOrder.length > 0 || this.#events.length > 0;
   }
   get isNew() {
     return this.#isNew;
@@ -33,7 +37,6 @@ class ComponentChanges {
   #nextParentUuid;
   #nextOrder;
   create(token = VoidToken, parentUuid, order = 0, autoDestructionOnParentRemoval = false) {
-    this.#serial++;
     this.#createCount++;
     this.#nextToken = token;
     this.#nextParentUuid = parentUuid ?? ROOT;
@@ -42,76 +45,154 @@ class ComponentChanges {
   }
   destroy() {
     this.#destroyCount++;
-    this.#serial++;
   }
+  /**
+   * Whether the pending parent asks for something the confirmed one is not already. A pending
+   * value that has come back to the confirmed parent is a change that cancelled itself out.
+   */
+  #hasPendingParent() {
+    if (this.#nextParentUuid === void 0) return false;
+    return (this.#nextParentUuid === ROOT ? void 0 : this.#nextParentUuid) !== this.#parentUuid;
+  }
+  /**
+   * Drop every pending value without writing any of them forward.
+   *
+   * This is the way out for a component whose bookkeeping is about to be replaced wholesale —
+   * `ComponentContext.reCreateChanges` does exactly that. A trail that has gone out is
+   * settled with {@link ComponentChanges.commitChange} instead.
+   */
   clear() {
-    this.#serial = 0;
-    this.#isNew = false;
     this.#nextToken = void 0;
     this.#nextParentUuid = void 0;
     this.#nextOrder = void 0;
     this.#nextProperties.clear();
     this.#propsChangeOrder.length = 0;
+    this.#travellingProperties = void 0;
     this.#events.length = 0;
     this.#transferables.clear();
   }
+  /**
+   * The three scalar pairs below all answer the same question the same way: is anything owed once
+   * the entry that is on its way out has landed?
+   *
+   * The written half alone cannot answer it. It is the last *confirmed* value and stays behind
+   * until the entry is committed, so a value the caller sets back to it while the entry travels
+   * would look like "nothing to do" — and the entry would then be the last word, leaving the
+   * Shadow Environment holding a value the view has already moved on from. So the pending half is
+   * only released where there is nothing in flight to contradict it; where there is, the new value
+   * takes the pending slot and the emitting side decides, against the written half it settles on.
+   */
   changeToken(token) {
     token ??= VoidToken;
-    if (token === this.#token) {
-      this.#nextToken = this.#isNew ? token : void 0;
-    } else {
-      this.#nextToken = token;
-      this.#serial++;
-    }
+    if (token === this.#token && this.#nextToken === void 0 && !this.#isNew) return;
+    this.#nextToken = token;
   }
   setParent(parentUuid) {
-    if (parentUuid === this.#parentUuid) {
-      this.#nextParentUuid = void 0;
-    } else {
-      this.#nextParentUuid = parentUuid ?? ROOT;
-      this.#serial++;
-    }
+    const nextParentUuid = parentUuid ?? ROOT;
+    if (nextParentUuid === (this.#parentUuid ?? ROOT) && this.#nextParentUuid === void 0) return;
+    this.#nextParentUuid = nextParentUuid;
   }
   changeOrder(order) {
-    if (order === this.#order) {
-      this.#nextOrder = void 0;
-    } else {
-      this.#nextOrder = order;
-      this.#serial++;
-    }
+    if (order === this.#order && this.#nextOrder === void 0) return;
+    this.#nextOrder = order;
   }
   #properties = /* @__PURE__ */ new Map();
   #nextProperties = /* @__PURE__ */ new Map();
+  /**
+   * The keys with a queued change, in the order their changes happened — the order an entry
+   * carries them in, and the reason this is a list and not a set.
+   *
+   * A set beside it would answer membership in one step, and per call it does win from about eight
+   * keys on: 8.0 ns for the set against 10.7 ns for the list at eight keys, 10.4 ns against 43.9 ns
+   * at 64. The distance is what decides against it. At the upper stop this repository can produce —
+   * 64 keys, every one of them changed in every frame at 60 fps, so 3840 calls per second — that is
+   * 0.13 ms saved per second of animation. And membership is the smaller half: `removeFrom()` and
+   * `appendToEnd()` are an `indexOf` plus a `splice`, and the splice stays linear no matter what
+   * answers the membership. Numbers measured 2026-08-31 on node v25.9.0.
+   */
   #propsChangeOrder = [];
-  // we use an Array here and not a Set, because we want to keep the change order
   /**
-   * @returns `true` if the value differs from the last value written to a change trail
+   * The keys an entry on its way out carries, until that entry is settled. For those keys the
+   * written half is behind, and {@link ComponentChanges.changeProperty} must not cancel against it.
+   */
+  #travellingProperties;
+  /**
+   * @returns `true` if the value differs from the last value this component asked for
    */
   changeProperty(key, value, isEqual) {
-    const prevValue = this.#properties.get(key);
-    const valueChanged = isEqual == null && value !== prevValue || isEqual != null && !isEqual(value, prevValue);
-    if (valueChanged) {
-      this.#nextProperties.set(key, value);
-      appendToEnd(this.#propsChangeOrder, key);
-      this.#serial++;
+    const equals = (a, b) => (
+      // a registered rule compares values, and the marker is not one -- handed to it, a rule
+      // would be asked about a property it never saw, and one that reaches into its arguments
+      // throws on a symbol. Where either side is the marker the only question left is whether
+      // it is still the same third form, and identity answers that.
+      a === PropertyWithoutValue || b === PropertyWithoutValue ? a === b : isEqual == null ? a === b : isEqual(a, b)
+    );
+    const isQueued = this.#propsChangeOrder.includes(key);
+    const isTravelling = this.#travellingProperties?.has(key) ?? false;
+    let prevValue;
+    if (isQueued) {
+      prevValue = this.#nextProperties.get(key);
+    } else if (isTravelling) {
+      prevValue = this.#travellingProperties.get(key);
     } else {
+      prevValue = this.#properties.get(key);
+    }
+    const valueChanged = !equals(value, prevValue);
+    const nothingToSend = !isTravelling && (isQueued ? equals(value, this.#properties.get(key)) : !valueChanged);
+    if (nothingToSend) {
       this.#nextProperties.delete(key);
       removeFrom(this.#propsChangeOrder, key);
+    } else {
+      this.#nextProperties.set(key, value);
+      appendToEnd(this.#propsChangeOrder, key);
     }
     return valueChanged;
   }
+  /**
+   * Mark `key` as set without giving it a value: the next trail carries an entry that names
+   * only the key. A later {@link ComponentChanges.changeProperty} replaces it with a value,
+   * and {@link ComponentChanges.removeProperty} takes it away like any other property.
+   *
+   * @returns `true` if this differs from the last value this component asked for
+   */
+  setPropertyWithoutValue(key) {
+    return this.changeProperty(key, PropertyWithoutValue);
+  }
   removeProperty(key) {
-    const propExists = this.#properties.has(key);
-    if (this.#nextProperties.has(key)) {
-      this.#nextProperties.delete(key);
-      if (!propExists) {
-        removeFrom(this.#propsChangeOrder, key);
-      }
-    } else if (propExists) {
+    const isQueued = this.#propsChangeOrder.includes(key);
+    this.#nextProperties.delete(key);
+    if (!this.#properties.has(key) && !this.#travellingProperties?.has(key)) {
+      removeFrom(this.#propsChangeOrder, key);
+      return;
+    }
+    if (!isQueued) {
       appendToEnd(this.#propsChangeOrder, key);
-      this.#serial++;
     }
   }
+  /**
+   * The properties this component holds at this moment: the ones a change trail has already
+   * carried, overlaid with everything that has accrued since.
+   *
+   * The overlay is what makes the result the current state instead of the state of the last
+   * trail — `#properties` is only written forward while a trail is being built
+   * ({@link ComponentChanges.makeCreateEntityChange},
+   * {@link ComponentChanges.makeChangePropertyChange}). A key whose accrued value is `undefined`
+   * and a key queued for change without an accrued value are both removals, and neither appears
+   * in the result. A key that is set without a value stands in the result with
+   * {@link PropertyWithoutValue}.
+   */
+  getProperties() {
+    const properties = new Map(this.#properties);
+    for (const key of this.#propsChangeOrder) {
+      const value = this.#nextProperties.get(key);
+      if (value === void 0) {
+        properties.delete(key);
+      } else {
+        properties.set(key, value);
+      }
+    }
+    return properties;
+  }
   #events = [];
   #transferables = /* @__PURE__ */ new Set();
   createEvent(type, data, transferables) {
@@ -119,7 +200,6 @@ class ComponentChanges {
     for (const transferable of transferables ?? []) {
       this.#transferables.add(transferable);
     }
-    this.#serial++;
   }
   transferEventsTo(changes) {
     if (this.#events.length > 0) {
@@ -139,7 +219,7 @@ class ComponentChanges {
         if (isNew) {
           trail.push(this.makeCreateEntityChange());
         } else if (!isDestroyed) {
-          if (this.#nextParentUuid !== void 0 && !(this.#nextParentUuid === ROOT && this.#parentUuid === void 0)) {
+          if (this.#hasPendingParent()) {
             trail.push(this.makeSetParentChange());
           } else if (this.#nextOrder !== void 0 && this.#nextOrder !== this.#order) {
             trail.push(this.makeUpdateOrderChange());
@@ -182,22 +262,25 @@ class ComponentChanges {
       uuid: this.#uuid,
       token
     };
-    this.#token = token;
-    if (this.#nextParentUuid !== void 0) {
-      const nextParentUuid = this.#nextParentUuid === ROOT ? void 0 : this.#nextParentUuid;
-      this.#parentUuid = nextParentUuid;
-      if (nextParentUuid !== void 0) {
-        entry.parentUuid = nextParentUuid;
-      }
+    if (this.#nextParentUuid !== void 0 && this.#nextParentUuid !== ROOT) {
+      entry.parentUuid = this.#nextParentUuid;
     }
     if (this.#nextProperties.size > 0) {
-      entry.properties = Array.from(this.#nextProperties.entries()).filter(([, value]) => value !== void 0);
-      for (const [key, value] of entry.properties) {
-        this.#properties.set(key, value);
+      const properties = [];
+      for (const [key, value] of this.#nextProperties) {
+        if (value === PropertyWithoutValue) {
+          properties.push([key]);
+        } else if (value !== void 0) {
+          properties.push([key, value]);
+        }
+      }
+      this.#noteTravellingProperties(properties);
+      if (properties.length > 0) {
+        entry.properties = properties;
       }
     }
     if (this.#nextOrder !== void 0 && this.#nextOrder !== this.#order) {
-      entry.order = this.#order = this.#nextOrder;
+      entry.order = this.#nextOrder;
     }
     if (this.#autoDestructionOnParentRemoval) {
       entry.autoDestructionOnParentRemoval = true;
@@ -211,56 +294,143 @@ class ComponentChanges {
     };
   }
   makeSetParentChange() {
-    this.#parentUuid = this.#nextParentUuid === ROOT ? void 0 : this.#nextParentUuid;
     const entry = {
       type: ComponentChangeType.SetParent,
       uuid: this.#uuid,
-      parentUuid: this.#parentUuid
+      parentUuid: this.#nextParentUuid === ROOT ? void 0 : this.#nextParentUuid
     };
     if (this.#nextOrder !== void 0 && this.#nextOrder !== this.#order) {
-      entry.order = this.#order = this.#nextOrder;
+      entry.order = this.#nextOrder;
     }
     return entry;
   }
   makeUpdateOrderChange() {
-    this.#order = this.#nextOrder ?? 0;
     return {
       type: ComponentChangeType.UpdateOrder,
       uuid: this.#uuid,
-      order: this.#order
+      order: this.#nextOrder ?? 0
     };
   }
   makeChangeToken() {
-    this.#token = this.#nextToken ?? VoidToken;
     return {
       type: ComponentChangeType.ChangeToken,
       uuid: this.#uuid,
-      token: this.#token
+      token: this.#nextToken ?? VoidToken
     };
   }
   makeChangePropertyChange() {
     const properties = this.#propsChangeOrder.map((key) => {
-      if (this.#nextProperties.has(key)) {
-        const nextValue = this.#nextProperties.get(key);
-        if (nextValue === void 0) {
-          this.#properties.delete(key);
-        } else {
-          this.#properties.set(key, nextValue);
-        }
-        return [key, nextValue];
-      } else {
-        this.#properties.delete(key);
-        return [key, void 0];
-      }
+      const value = this.#nextProperties.get(key);
+      return value === PropertyWithoutValue ? [key] : [key, value];
     });
+    this.#noteTravellingProperties(properties);
     return {
       type: ComponentChangeType.ChangeProperties,
       uuid: this.#uuid,
       properties
     };
   }
+  /**
+   * Records the keys of an entry that is going out, so a later change knows the written half
+   * is behind.
+   */
+  #noteTravellingProperties(properties) {
+    this.#travellingProperties = new Map(
+      properties.map((entry) => [entry[0], entry.length === 1 ? PropertyWithoutValue : entry[1]])
+    );
+  }
+  /**
+   * Fold one trail entry into the written half of this component's bookkeeping: the values the
+   * entry carries become the values the next diff is taken against, and the pending half that
+   * produced them is released. Called once per entry the Shadow Environment has applied.
+   *
+   * A pending value is released only while it is still the value the entry carried. Between the
+   * build of a trail and its confirmation lies a round trip, and whatever changed in that window
+   * is owed to the Shadow Environment — releasing it here would leave the two sides holding
+   * different values with nothing left to correct them.
+   */
+  commitChange(entry) {
+    switch (entry.type) {
+      case ComponentChangeType.CreateEntities:
+        this.#commitToken(entry.token);
+        this.#commitParentUuid(entry.parentUuid);
+        this.#commitOrder(entry.order ?? this.#order);
+        this.#commitProperties(entry.properties);
+        for (const key of this.#propsChangeOrder.slice(0)) {
+          if (this.#nextProperties.get(key) === void 0 && !this.#properties.has(key)) {
+            this.#nextProperties.delete(key);
+            removeFrom(this.#propsChangeOrder, key);
+          }
+        }
+        this.#travellingProperties = void 0;
+        this.#isNew = false;
+        break;
+      case ComponentChangeType.SetParent:
+        this.#commitParentUuid(entry.parentUuid);
+        this.#commitOrder(entry.order ?? this.#order);
+        break;
+      case ComponentChangeType.UpdateOrder:
+        this.#commitOrder(entry.order);
+        break;
+      case ComponentChangeType.ChangeToken:
+        this.#commitToken(entry.token);
+        break;
+      case ComponentChangeType.ChangeProperties:
+        this.#commitProperties(entry.properties);
+        this.#travellingProperties = void 0;
+        break;
+      case ComponentChangeType.SendEvents:
+        this.#events.splice(0, entry.events.length);
+        for (const transferable of entry.transferables ?? []) {
+          this.#transferables.delete(transferable);
+        }
+        break;
+      case ComponentChangeType.DestroyEntities:
+        this.#token = VoidToken;
+        this.#parentUuid = void 0;
+        this.#order = 0;
+        this.#properties.clear();
+        this.#travellingProperties = void 0;
+        this.#isNew = true;
+        break;
+    }
+  }
+  #commitToken(token) {
+    this.#token = token;
+    if (this.#nextToken === token) {
+      this.#nextToken = void 0;
+    }
+  }
+  #commitParentUuid(parentUuid) {
+    this.#parentUuid = parentUuid;
+    if ((this.#nextParentUuid === ROOT ? void 0 : this.#nextParentUuid) === parentUuid) {
+      this.#nextParentUuid = void 0;
+    }
+  }
+  #commitOrder(order) {
+    this.#order = order;
+    if (this.#nextOrder === order) {
+      this.#nextOrder = void 0;
+    }
+  }
+  #commitProperties(properties) {
+    for (const entry of properties ?? []) {
+      const key = entry[0];
+      const value = entry.length === 1 ? PropertyWithoutValue : entry[1];
+      if (value === void 0) {
+        this.#properties.delete(key);
+      } else {
+        this.#properties.set(key, value);
+      }
+      if (this.#nextProperties.get(key) === value) {
+        this.#nextProperties.delete(key);
+        removeFrom(this.#propsChangeOrder, key);
+      }
+    }
+  }
 }
 export {
-  ComponentChanges
+  ComponentChanges,
+  PropertyWithoutValue
 };
 //# sourceMappingURL=ComponentChanges.js.map