@spearwolf/shadow-objects 0.32.0 → 0.34.0

package/src/utils/toMaybe.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/toMaybe.ts"],
-  "sourcesContent": ["import type {Maybe} from '../types.js';\n\nexport const toMaybe = <T = unknown>(value: T): Maybe<T> => value ?? undefined;"],
+  "sourcesContent": ["import type {Maybe} from '../types.js';\n\nexport const toMaybe = <T = unknown>(value: T): Maybe<T> => value ?? undefined;\n"],
   "mappings": "AAEO,MAAM,UAAU,CAAc,UAAuB,SAAS;",
   "names": []
 }

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

@@ -1 +1 @@
-{"version":3,"file":"toNamespace.d.ts","sourceRoot":"","sources":["../../../src/utils/toNamespace.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,WAAW,GAAI,YAAY,aAAa,KAAG,aAC6D,CAAC"}
+{"version":3,"file":"toNamespace.d.ts","sourceRoot":"","sources":["../../../src/utils/toNamespace.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,WAAW,eAAgB,aAAa,KAAG,aAC6D,CAAC"}

package/src/utils/toNamespace.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/toNamespace.ts"],
-  "sourcesContent": ["import {GlobalNS} from '../constants.js';\nimport type {NamespaceType} from '../types.js';\n\nexport const toNamespace = (namespace?: NamespaceType): NamespaceType =>\n  typeof namespace === 'string' ? namespace.trim() || GlobalNS : typeof namespace === 'symbol' ? namespace : GlobalNS;"],
+  "sourcesContent": ["import {GlobalNS} from '../constants.js';\nimport type {NamespaceType} from '../types.js';\n\nexport const toNamespace = (namespace?: NamespaceType): NamespaceType =>\n  typeof namespace === 'string' ? namespace.trim() || GlobalNS : typeof namespace === 'symbol' ? namespace : GlobalNS;\n"],
   "mappings": "AAAA,SAAQ,gBAAe;AAGhB,MAAM,cAAc,CAAC,cAC1B,OAAO,cAAc,WAAW,UAAU,KAAK,KAAK,WAAW,OAAO,cAAc,WAAW,YAAY;",
   "names": []
 }

package/src/utils/toUrlString.d.ts

@@ -1,2 +1,14 @@
+/**
+ * Turn a module url into the string a dynamic `import()` takes.
+ *
+ * A `URL` is handed back as its own string. A string is resolved against the base url of
+ * the realm -- `globalThis.location.href`, the document on the main thread and the worker
+ * script inside a worker -- so an absolute url and a `data:` url come back unchanged,
+ * while a relative path becomes absolute against the page or worker that asked for it.
+ *
+ * The realm therefore has to have a `location`, and every environment this library runs in
+ * has one: a document, a dedicated worker, a service worker. A bare Node process has none,
+ * and a string handed in there is refused with a `TypeError`.
+ */
 export declare const toUrlString: (url: URL | string) => string;
 //# sourceMappingURL=toUrlString.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"toUrlString.d.ts","sourceRoot":"","sources":["../../../src/utils/toUrlString.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,GAAI,KAAK,GAAG,GAAG,MAAM,KAAG,MAK/C,CAAC"}
+{"version":3,"file":"toUrlString.d.ts","sourceRoot":"","sources":["../../../src/utils/toUrlString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,QAAS,GAAG,GAAG,MAAM,KAAG,MAK/C,CAAC"}

package/src/utils/toUrlString.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/toUrlString.ts"],
-  "sourcesContent": ["export const toUrlString = (url: URL | string): string => {\n  if (typeof url === 'string') {\n    url = new URL(url, globalThis.location.href);\n  }\n  return url.toString();\n};"],
-  "mappings": "AAAO,MAAM,cAAc,CAAC,QAA8B;AACxD,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,IAAI,KAAK,WAAW,SAAS,IAAI;AAAA,EAC7C;AACA,SAAO,IAAI,SAAS;AACtB;",
+  "sourcesContent": ["/**\n * Turn a module url into the string a dynamic `import()` takes.\n *\n * A `URL` is handed back as its own string. A string is resolved against the base url of\n * the realm -- `globalThis.location.href`, the document on the main thread and the worker\n * script inside a worker -- so an absolute url and a `data:` url come back unchanged,\n * while a relative path becomes absolute against the page or worker that asked for it.\n *\n * The realm therefore has to have a `location`, and every environment this library runs in\n * has one: a document, a dedicated worker, a service worker. A bare Node process has none,\n * and a string handed in there is refused with a `TypeError`.\n */\nexport const toUrlString = (url: URL | string): string => {\n  if (typeof url === 'string') {\n    url = new URL(url, globalThis.location.href);\n  }\n  return url.toString();\n};\n"],
+  "mappings": "AAYO,MAAM,cAAc,CAAC,QAA8B;AACxD,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,IAAI,KAAK,WAAW,SAAS,IAAI;AAAA,EAC7C;AACA,SAAO,IAAI,SAAS;AACtB;",
   "names": []
 }

package/src/utils/waitForMessageOfType.d.ts

@@ -1,5 +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) => 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;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,gBAAc,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,kBAiC7G,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,17 +1,39 @@
-const waitForMessageOfType = (worker, type, timeout = 1e3, guard) => new Promise((resolve, reject) => {
+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;
+  }
   let timeoutId;
   let listener;
   const cleanup = () => {
     clearTimeout(timeoutId);
     worker.removeEventListener("message", listener);
+    signal?.removeEventListener("abort", onAbort);
   };
+  function onAbort() {
+    cleanup();
+    reject(signal.reason);
+  }
   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)) {
@@ -20,13 +42,16 @@ const waitForMessageOfType = (worker, type, timeout = 1e3, guard) => new Promise
         }
       } catch (error) {
         cleanup();
-        reject(error.toString());
+        reject(error);
       }
     }
   };
+  signal?.addEventListener("abort", onAbort, { once: true });
   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 */\nexport const waitForMessageOfType = (worker: Worker, type: string, timeout = 1000, guard?: (data: any) => boolean) =>\n  new Promise<void>((resolve, reject) => {\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    };\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.toString());\n        }\n      }\n    };\n\n    worker.addEventListener('message', listener);\n  });"],
-  "mappings": "AAGO,MAAM,uBAAuB,CAAC,QAAgB,MAAc,UAAU,KAAM,UACjF,IAAI,QAAc,CAAC,SAAS,WAAW;AACrC,MAAI;AAEJ,MAAI;AAEJ,QAAM,UAAU,MAAM;AACpB,iBAAa,SAAS;AACtB,WAAO,oBAAoB,WAAW,QAAQ;AAAA,EAChD;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,MAAM,SAAS,CAAC;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AAEA,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,21 +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;
-    changeProperty<T = unknown>(key: string, value: T, isEqual?: (a: T, b: T) => boolean): void;
+    /**
+     * @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;
@@ -26,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;IASrC,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM;IAS7B,WAAW,CAAC,KAAK,EAAE,MAAM;IAazB,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;IAcpF,cAAc,CAAC,GAAG,EAAE,MAAM;IAgB1B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,YAAY,EAAE;IAMvE,gBAAgB,CAAC,OAAO,EAAE,gBAAgB;IAW1C,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAAE,EAAE,UAAU,EAAE,gBAAgB;IAsC5E,UAAU,IAAI,WAAW;IAYzB,sBAAsB,IAAI,qBAAqB;IAiC/C,uBAAuB,IAAI,sBAAsB;IAOjD,mBAAmB,IAAI,gBAAgB;IAgBvC,qBAAqB,IAAI,kBAAkB;IAU3C,eAAe,IAAI,YAAY;IAU/B,wBAAwB,IAAI,iBAAiB;CAoB9C"}
+{"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"}