@spearwolf/shadow-objects 0.32.0 → 0.34.0

package/src/view/ComponentContext.js

@@ -1,17 +1,82 @@
 import { ChangeTrailPhase, ContextLost, GlobalNS } from "../constants.js";
-import { removeFrom } from "../utils/array-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 { ComponentChanges } from "./ComponentChanges.js";
+import { ComponentChanges, PropertyWithoutValue } from "./ComponentChanges.js";
 import { ComponentMemory } from "./ComponentMemory.js";
+class OrderedUuids {
+  #uuids = [];
+  #members = /* @__PURE__ */ new Set();
+  /** The uuids in their order. Read-only: every write goes through this class. */
+  get uuids() {
+    return this.#uuids;
+  }
+  get size() {
+    return this.#uuids.length;
+  }
+  has(uuid) {
+    return this.#members.has(uuid);
+  }
+  push(uuid) {
+    this.#uuids.push(uuid);
+    this.#members.add(uuid);
+  }
+  insertAt(index, uuid) {
+    this.#uuids.splice(index, 0, uuid);
+    this.#members.add(uuid);
+  }
+  /** @returns whether the uuid was in the list */
+  delete(uuid) {
+    if (!this.#members.delete(uuid)) return false;
+    const idx = this.#uuids.indexOf(uuid);
+    if (idx !== -1) {
+      this.#uuids.splice(idx, 1);
+    }
+    return true;
+  }
+  clear() {
+    this.#uuids.length = 0;
+    this.#members.clear();
+  }
+}
+class ComponentContextDisposedError extends Error {
+  constructor(message = "the component context has been disposed") {
+    super(message);
+    this.name = "ComponentContextDisposedError";
+  }
+}
+class ComponentUuidInUseError extends Error {
+  constructor(uuid) {
+    super(`the view component cannot join the component context because the uuid ${uuid} is already held by another component`);
+    this.name = "ComponentUuidInUseError";
+    this.uuid = uuid;
+  }
+}
 class ComponentContext {
   static {
     this.ReRequestParentRoots = "re-request-parent-roots";
   }
+  static {
+    this.ReRequestParent = "re-request-parent";
+  }
+  static {
+    /**
+     * Ask the element behind a component to let the properties hanging on it look for their host
+     * again.
+     *
+     * A context knows nothing about `<shae-prop>` — a property has no view component and cannot be
+     * addressed here. The signal still belongs next to the two above: it travels the same broadcast
+     * channel to the same receivers, and the element on the other end is the one that can reach the
+     * properties below it.
+     */
+    this.ReRequestEntHost = "re-request-ent-host";
+  }
   static getContextsMap() {
-    if (globalThis.__shadowEntsContexts == null) {
-      globalThis.__shadowEntsContexts = /* @__PURE__ */ new Map();
+    if (globalThis.__shadowObjectsContexts == null) {
+      globalThis.__shadowObjectsContexts = /* @__PURE__ */ new Map();
     }
-    return globalThis.__shadowEntsContexts;
+    return globalThis.__shadowObjectsContexts;
   }
   static get(namespace) {
     const ns = toNamespace(namespace);
@@ -22,9 +87,63 @@ class ComponentContext {
     return new ComponentContext(ns);
   }
   #components = /* @__PURE__ */ new Map();
-  #rootComponents = [];
-  // we use an Array here and not a Set, because we want to keep the insertion order
+  // the entity tree is walked in this order, so the roots are a list and not a set
+  #rootComponents = new OrderedUuids();
+  #isDisposed = false;
+  // which instances name this ComponentContext, and the one place that can say so. #components holds one
+  // entry per uuid, and an entry outlives the departure of its component until the next change
+  // trail — so a uuid standing in that map is no statement about anyone still being a member
+  #componentInstances = /* @__PURE__ */ new Set();
+  /**
+   * The entry `component` owns, and nothing else.
+   *
+   * An entry outlives the departure of its component until the next change trail, so a later
+   * component can take the uuid over while the entry is still standing. A lookup by uuid alone
+   * would then hand back the entry of a namesake, and every write that followed would land on a
+   * live component that was never named. Each method that is given an instance asks through here,
+   * so that it acts on that instance or on nothing.
+   */
+  #entryOf(component) {
+    const entry = this.#components.get(component.uuid);
+    return entry !== void 0 && entry.component === component ? entry : void 0;
+  }
   #componentMemory = new ComponentMemory();
+  #logger = new ConsoleLogger("ComponentContext");
+  /**
+   * The change trail this context built last, as long as nobody has settled it yet.
+   * `owners[i]` is the bookkeeping that produced `entries[i]`; `retiring` are the components the
+   * build read as spent, which is a verdict of the build and not of the commit — a component
+   * destroyed while the trail travels owes its destruction to the *next* trail, and dropping its
+   * entry here would leave the entity standing with nothing left to take it down.
+   */
+  #uncommittedTrail;
+  /** The components a build reads as spent: destroyed, or created and dropped without ever going out. */
+  #retiringComponents(participants) {
+    return participants.filter((changes) => changes.isDestroyed || changes.isNew && !changes.isCreated);
+  }
+  /**
+   * Carry out the verdict the build took, for the components whose every entry is settled.
+   *
+   * A component that has been claimed again since the build stays: a uuid its holder has left is
+   * free, and the entry now belongs to whoever took it over.
+   */
+  #retireComponents(retiring, stillPending) {
+    for (const changes of retiring) {
+      if (stillPending?.has(changes)) continue;
+      if (changes.isCreated) continue;
+      this.#deleteComponent(changes.uuid, changes);
+    }
+  }
+  /**
+   * Release the record of the built trail and drop the components it retired, without folding
+   * anything into their bookkeeping.
+   */
+  #retireBuiltTrail() {
+    const uncommitted = this.#uncommittedTrail;
+    if (uncommitted == null) return;
+    this.#uncommittedTrail = void 0;
+    this.#retireComponents(uncommitted.retiring);
+  }
   constructor(namespace = GlobalNS) {
     const ns = toNamespace(namespace);
     const ctxMap = ComponentContext.getContextsMap();
@@ -34,16 +153,48 @@ class ComponentContext {
     this.ns = ns;
     ctxMap.set(ns, this);
   }
+  /**
+   * Whether this context has been torn down by {@link ComponentContext.dispose}.
+   *
+   * A disposed context holds no components, produces empty change trails and no longer
+   * occupies its namespace. It cannot be revived; use {@link ComponentContext.get} to
+   * obtain a fresh context for the same namespace.
+   */
+  get isDisposed() {
+    return this.#isDisposed;
+  }
+  /**
+   * Take a component in: it becomes a member of this {@link ComponentContext} and a
+   * `CreateEntities` change is written for its uuid.
+   *
+   * Called by the {@link ViewComponent#context} setter, and by nothing else.
+   *
+   * @throws {ComponentContextDisposedError} if this {@link ComponentContext} has been disposed
+   * @throws {ComponentUuidInUseError} if another member of this {@link ComponentContext} holds
+   *   `component.uuid`
+   */
   addComponent(component) {
-    let viewInstance;
-    if (this.#components.has(component.uuid)) {
-      viewInstance = this.#components.get(component.uuid);
+    if (this.#isDisposed) {
+      throw new ComponentContextDisposedError(
+        `the view component ${component.uuid} cannot join the component context because it has been disposed`
+      );
+    }
+    let viewInstance = this.#components.get(component.uuid);
+    if (viewInstance) {
+      if (viewInstance.component !== component) {
+        if (this.#componentInstances.has(viewInstance.component)) {
+          throw new ComponentUuidInUseError(component.uuid);
+        }
+        for (const childUuid of [...viewInstance.children.uuids]) {
+          this.#components.get(childUuid)?.component.removeFromParent();
+        }
+      }
       viewInstance.component = component;
-      viewInstance.children = [];
+      viewInstance.children.clear();
     } else {
       viewInstance = {
         component,
-        children: [],
+        children: new OrderedUuids(),
         changes: new ComponentChanges(component.uuid),
         propIsEqual: void 0
       };
@@ -61,80 +212,127 @@ class ComponentContext {
     } else {
       this.#appendToOrdered(component, this.#rootComponents);
     }
+    this.#componentInstances.add(component);
     this.#viewInstances = void 0;
   }
+  /**
+   * Whether `component` is a member of this {@link ComponentContext} right now.
+   *
+   * This is the question about the instance, and the only one this class answers about
+   * membership. A component that has left gets `false`, even while its entry is still standing —
+   * {@link ComponentContext.hasComponents} is what counts entries.
+   */
   hasComponent(component) {
-    return this.#components.has(component.uuid);
+    return this.#componentInstances.has(component);
   }
   hasComponents() {
     return this.#components.size > 0;
   }
   isRootComponent(component) {
-    return this.#rootComponents.includes(component.uuid);
+    return this.#entryOf(component) !== void 0 && this.#rootComponents.has(component.uuid);
   }
   destroyComponent(component) {
-    if (this.hasComponent(component)) {
-      const entry = this.#components.get(component.uuid);
-      entry.children.slice(0).forEach((childUuid) => this.#components.get(childUuid)?.component.removeFromParent());
+    this.#componentInstances.delete(component);
+    const entry = this.#entryOf(component);
+    if (entry !== void 0 && !entry.changes.isDestroyed) {
+      for (const childUuid of [...entry.children.uuids]) {
+        this.#components.get(childUuid)?.component.removeFromParent();
+      }
       entry.changes.destroy();
       this.#viewInstances = void 0;
     }
+    if (component.context === this) {
+      component.destroy();
+    }
   }
+  /**
+   * The children of `component`, in sort order — a fresh array each call, and an empty one for
+   * an instance that does not own its entry.
+   *
+   * Uuids without a matching view instance are skipped instead of dereferenced: `addToChildren()`
+   * writes a uuid into a children list without the parent link of the child following along, so
+   * `#deleteComponent()` has no list to take that uuid out of and the entry behind it goes while
+   * the list keeps naming it. `#appendToOrdered()` and `#traverseLevelOrderBFS()` read a children
+   * list the same way.
+   */
   getChildren(component) {
-    return this.#components.get(component.uuid)?.children.map((uuid) => this.#components.get(uuid).component) ?? [];
-  }
-  removeFromParent(childUuid, parent) {
-    if (this.hasComponent(parent)) {
-      const childEntry = this.#components.get(childUuid);
-      const parentEntry = this.#components.get(parent.uuid);
-      const childIdx = parentEntry.children.indexOf(childUuid);
-      if (childIdx !== -1) {
-        parentEntry.children.splice(childIdx, 1);
-        childEntry.changes.setParent(void 0);
+    const children = this.#entryOf(component)?.children;
+    if (children === void 0) return [];
+    const result = [];
+    for (const uuid of children.uuids) {
+      const entry = this.#components.get(uuid);
+      if (entry !== void 0) {
+        result.push(entry.component);
       }
-      this.#appendToOrdered(childEntry.component, this.#rootComponents);
-      this.#viewInstances = void 0;
     }
+    return result;
   }
-  moveToRoot(childUuid) {
-    const childEntry = this.#components.get(childUuid);
-    if (childEntry) {
-      childEntry.changes?.setParent(void 0);
+  removeFromParent(component, parent) {
+    const parentEntry = this.#entryOf(parent);
+    if (parentEntry === void 0) return;
+    const childEntry = this.#entryOf(component);
+    if (childEntry === void 0) return;
+    if (parentEntry.children.delete(component.uuid)) {
+      childEntry.changes.setParent(void 0);
       this.#appendToOrdered(childEntry.component, this.#rootComponents);
+      this.#viewInstances = void 0;
     }
+  }
+  moveToRoot(component) {
+    const childEntry = this.#entryOf(component);
+    if (childEntry === void 0) return;
+    const parentEntry = component.parent ? this.#entryOf(component.parent) : void 0;
+    parentEntry?.children.delete(component.uuid);
+    childEntry.changes.setParent(void 0);
+    this.#appendToOrdered(childEntry.component, this.#rootComponents);
     this.#viewInstances = void 0;
   }
   changeToken(component, token) {
-    this.#components.get(component.uuid)?.changes.changeToken(token);
+    this.#entryOf(component)?.changes.changeToken(token);
   }
   isChildOf(child, parent) {
-    if (this.hasComponent(parent)) {
-      const entry = this.#components.get(parent.uuid);
-      return entry.children.includes(child.uuid);
-    }
-    return false;
+    const parentEntry = this.#entryOf(parent);
+    return parentEntry !== void 0 && this.#entryOf(child) !== void 0 && parentEntry.children.has(child.uuid);
   }
   addToChildren(parent, child) {
-    const entry = this.#components.get(parent.uuid);
+    const entry = this.#entryOf(parent);
     if (entry) {
+      const childEntry = this.#entryOf(child);
+      if (childEntry === void 0) return;
       this.#appendToOrdered(child, entry.children);
-      this.#components.get(child.uuid)?.changes.setParent(parent.uuid);
-      removeFrom(this.#rootComponents, child.uuid);
+      childEntry.changes.setParent(parent.uuid);
+      this.#rootComponents.delete(child.uuid);
       this.#viewInstances = void 0;
     } else {
-      throw new Error(`the view component ${parent.uuid} cannot have a child added to it because the component do not exist!`);
+      throw new Error(`the view component ${parent.uuid} cannot have a child added to it because this context does not hold it`);
     }
   }
+  /**
+   * Destroy a component and all its descendants without writing anything to a change trail.
+   * Each of them is detached from this context and reports {@link ViewComponent#isDestroyed}.
+   *
+   * @see {@link ComponentContext.clear}
+   */
   removeSubTree(uuid) {
+    this.#removeSubTree(uuid, /* @__PURE__ */ new Set());
+  }
+  #removeSubTree(uuid, visited) {
+    if (visited.has(uuid)) return;
+    visited.add(uuid);
     const entry = this.#components.get(uuid);
     if (entry) {
-      entry.children.slice(0).forEach((childUuid) => this.removeSubTree(childUuid));
-      this.destroyComponent(entry.component);
+      for (const childUuid of [...entry.children.uuids]) {
+        this.#removeSubTree(childUuid, visited);
+      }
       this.#deleteComponent(uuid);
+      this.destroyComponent(entry.component);
     }
   }
+  /**
+   * @returns `true` if the value differs from the last value written to a change trail
+   */
   setProperty(component, propKey, value, isEqual) {
-    const vi = this.#components.get(component.uuid);
+    const vi = this.#entryOf(component);
     if (vi != null) {
       if (isEqual != null) {
         vi.propIsEqual ??= /* @__PURE__ */ new Map();
@@ -146,19 +344,89 @@ class ComponentContext {
     }
     return false;
   }
+  /**
+   * Mark `propKey` on `component` as set without giving it a value: the change trail carries
+   * an entry that names only the key, and the entity behind it reads the property as
+   * `undefined` with the key in place. {@link ComponentContext.setProperty} with `undefined`
+   * is the other thing — a removal.
+   *
+   * An equality rule registered for the key is forgotten, the way it is for a
+   * {@link ComponentContext.setProperty} that comes without one: there is no value here for a
+   * rule to compare.
+   *
+   * @returns `true` when this differs from the last value written to a change trail, and
+   *   `false` for an instance that does not own its entry
+   */
+  setPropertyWithoutValue(component, propKey) {
+    const vi = this.#entryOf(component);
+    if (vi != null) {
+      vi.propIsEqual?.delete(propKey);
+      return vi.changes.setPropertyWithoutValue(propKey);
+    }
+    return false;
+  }
   removeProperty(component, propKey) {
-    this.#components.get(component.uuid)?.changes.removeProperty(propKey);
+    this.#entryOf(component)?.changes.removeProperty(propKey);
+  }
+  /**
+   * Hand the properties of `component` over to the context it has just joined.
+   *
+   * Called by the {@link ViewComponent#context} setter, and by nothing else. It reads the state
+   * this context still holds for the component: leaving a context destroys it, but the entry
+   * survives until the next {@link ComponentContext.buildChangeTrails}, so the properties are
+   * still there to be read once the join has happened.
+   *
+   * The equality function travels with each property, because it is a rule about the key and not
+   * about the value — the same key means the same notion of "unchanged" wherever it lives. It does
+   * not get to decide about the arrival, though: the target holds nothing for the key yet, so it
+   * would be asked whether the value equals `undefined`, and a function that says yes would drop
+   * the property instead of carrying it over. The value is therefore written first and the rule
+   * registered after it — the other way round, the write would delete the entry it just made,
+   * because {@link ComponentContext.setProperty} keeps only what its caller passes.
+   *
+   * What the registered rule is for: {@link ComponentContext.reCreateChanges} is its one reader,
+   * and it compares with it when it rebuilds a component from the memory. A later
+   * {@link ComponentContext.setProperty} does not consult it — it uses its own argument, or none.
+   *
+   * A property that is set without a value goes over as one: handing it on as the value
+   * `undefined` would have the target read it as a removal, and the key would not arrive.
+   *
+   * Built like {@link ComponentChanges.transferEventsTo}, with one difference: the properties are
+   * copied, not moved. What stays behind goes down with the entity in this context.
+   */
+  transferPropertiesTo(component, target) {
+    const vi = this.#entryOf(component);
+    if (vi === void 0) return;
+    for (const [key, value] of vi.changes.getProperties()) {
+      if (value === PropertyWithoutValue) {
+        target.setPropertyWithoutValue(component, key);
+      } else {
+        target.setProperty(component, key, value);
+      }
+      const isEqual = vi.propIsEqual?.get(key);
+      if (isEqual != null) {
+        target.#registerPropIsEqual(component, key, isEqual);
+      }
+    }
+  }
+  #registerPropIsEqual(component, propKey, isEqual) {
+    const vi = this.#entryOf(component);
+    if (vi === void 0) return;
+    vi.propIsEqual ??= /* @__PURE__ */ new Map();
+    vi.propIsEqual.set(propKey, isEqual);
   }
   changeOrder(component) {
-    if (component.parent) {
-      const parentEntry = this.#components.get(component.parent.uuid);
-      removeFrom(parentEntry.children, component.uuid);
+    const entry = this.#entryOf(component);
+    if (entry === void 0) return;
+    const parentEntry = component.parent ? this.#entryOf(component.parent) : void 0;
+    if (parentEntry !== void 0) {
+      parentEntry.children.delete(component.uuid);
       this.#appendToOrdered(component, parentEntry.children);
-    } else {
-      removeFrom(this.#rootComponents, component.uuid);
+    } else if (component.parent == null) {
+      this.#rootComponents.delete(component.uuid);
       this.#appendToOrdered(component, this.#rootComponents);
     }
-    this.#components.get(component.uuid)?.changes.changeOrder(component.order);
+    entry.changes.changeOrder(component.order);
     this.#viewInstances = void 0;
   }
   /**
@@ -171,7 +439,7 @@ class ComponentContext {
    * Dispatch an event to the shadow objects linked to the view component
    */
   dispatchShadowObjectsEvent(component, type, data, transferables) {
-    this.#components.get(component.uuid)?.changes.createEvent(type, data, transferables);
+    this.#entryOf(component)?.changes.createEvent(type, data, transferables);
   }
   /**
    * Dispatch an event to all view components
@@ -188,56 +456,258 @@ class ComponentContext {
     this.#components.get(uuid)?.component.dispatchEvent(type, data, traverseChildren);
   }
   /**
-   * Inform all root components that they should re-request their parents
+   * Inform all root components that they should re-request their parents.
+   *
+   * Every root is asked, because there is nothing here to ask about: the message carries no
+   * sender, so this side cannot narrow the set down at all. The receiver is the one that can:
+   * it re-asks the element tree, and whoever answers first wins.
+   *
+   * Delivery is immediate: the round is over by the time the call returns. Two paths inside the
+   * library end here — {@link ComponentContext.dispatchReRequestParentSiblings} for a component
+   * without a parent, whose candidate set is the roots, and the delivery of a collected round for
+   * that same set. What does not come this way is an entity that has just arrived: it hands its
+   * round to the collector below. The method is public because running a round at a moment of
+   * one's own choosing is what it is for.
    */
   dispatchReRequestParentRoots() {
-    for (const uuid of this.#rootComponents) {
+    for (const uuid of [...this.#rootComponents.uuids]) {
       this.dispatchMessage(uuid, ComponentContext.ReRequestParentRoots);
     }
   }
+  /**
+   * Inform the children of `component` that they should re-request their parents.
+   *
+   * The receivers are the components hanging on `component` right now, and every one of them has
+   * to let go: the message carries no sender and needs no filter, because there is nothing here to
+   * decide. {@link ComponentContext.ReRequestParentRoots} is the signal for it — it means "drop
+   * your parent and ask again", which is what the roots happen to be asked for most often, not
+   * what it says.
+   */
+  dispatchReRequestParentChildren(component) {
+    for (const child of this.getChildren(component)) {
+      this.dispatchMessage(child.uuid, ComponentContext.ReRequestParentRoots);
+    }
+  }
+  /**
+   * Inform the siblings of `component` that they should re-request their parents.
+   *
+   * This narrows the candidate set for one specific question: which components could have bound
+   * to an ancestor further away than they should have, because `component` was not yet answering
+   * when they asked? Such a component sits below `component` in the element tree and shares its
+   * parent — any entity in between would have answered first. As long as `component` has no
+   * parent of its own, the roots are that same set.
+   *
+   * The signal alone does not decide anything: the receiver re-asks, and whoever answers first
+   * wins. Which components exist as candidates is what this method knows; whether one of them
+   * really sits below `component` is settled on the receiving side, which is where the element
+   * tree is visible — `data` is what carries the sender's identity there.
+   *
+   * The two signals differ in the order they work in, and that decides more than it looks like:
+   * {@link ComponentContext.ReRequestParentRoots} releases the parent before asking, so a
+   * component that gets the same answer back re-joins its parent's children at the end;
+   * {@link ComponentContext.ReRequestParent} asks first and releases only where nobody answers,
+   * which leaves every component that is already bound where it stands, order included.
+   *
+   * Delivery is immediate, and nothing inside the library calls it: like
+   * {@link ComponentContext.dispatchReRequestParentRoots} it is public so that a round can be run
+   * at a moment of one's own choosing.
+   */
+  dispatchReRequestParentSiblings(component, data = void 0) {
+    const parent = component.parent;
+    if (parent == null) {
+      this.dispatchReRequestParentRoots();
+      return;
+    }
+    for (const child of this.getChildren(parent)) {
+      if (child !== component) {
+        this.dispatchMessage(child.uuid, ComponentContext.ReRequestParent, data);
+      }
+    }
+  }
+  /**
+   * The peers waiting for a round: sender by sender in arrival order, each with the data the
+   * round it asks for would carry.
+   */
+  #peerReRequests = new MicrotaskCollector((pending) => this.#deliverPeerReRequests(pending));
+  /**
+   * Take a peer re-request from `sender` — an entity that has just become one and may be the new
+   * closest ancestor for entities that bound while it was not yet answering.
+   *
+   * Everything that arrives in the same task shares one round. Alone, each arrival is a broadcast
+   * over the whole candidate set: the root channel carries no sender and has to ask every root,
+   * the sibling channel asks every child of one parent. n entities coming up together then cost
+   * n(n+1)/2 messages, and each message is a full ancestor request through the DOM — for 600 roots
+   * in one namespace that is 180 300 messages and some 257 ms on top of a build that takes 42 ms
+   * with the channel switched off. One round per task costs 600 messages and 2 ms on top. The
+   * point where a round per arrival costs more than a frame lies at about 145 roots in one
+   * namespace; one round per task stays clear of it over the whole measured range, up to 600.
+   *
+   * Numbers measured 2026-08-22 in Chromium via Playwright 1.62.1 — a snapshot, not a guarantee;
+   * the size series is in `packages/shadow-objects/docs/guides.md`, under "How Many Entities Fit
+   * in One Namespace".
+   *
+   * @param data travels with the round as long as `sender` is the only one in it — see
+   *   {@link ComponentContext.dispatchReRequestParentSiblings} for what a receiver does with it.
+   *
+   * @internal
+   */
+  collectPeerReRequest(sender, data = void 0) {
+    this.#peerReRequests.add(sender, data);
+  }
+  /** Run the collected rounds, one per candidate set. */
+  #deliverPeerReRequests(pending) {
+    const rounds = /* @__PURE__ */ new Map();
+    for (const [sender, data] of pending) {
+      if (!this.#componentInstances.has(sender)) continue;
+      const key = sender.parent ?? null;
+      const round = rounds.get(key);
+      if (round === void 0) {
+        rounds.set(key, { data });
+      } else {
+        round.data = void 0;
+      }
+    }
+    for (const [parent, round] of rounds) {
+      runGuarded(
+        this.#logger,
+        () => {
+          if (parent == null) {
+            this.dispatchReRequestParentRoots();
+          } else {
+            for (const child of this.getChildren(parent)) {
+              this.dispatchMessage(child.uuid, ComponentContext.ReRequestParent, round.data);
+            }
+          }
+        },
+        "a peer re-request round could not be delivered:",
+        parent?.uuid ?? "roots"
+      );
+    }
+  }
   /**
    * Create the component change trails at this point in time.
    * The next call will only return the differences from the previous call.
    *
+   * @param commit whether the trail counts as applied the moment it is built. Pass `false` when
+   *   the trail still has to travel to a Shadow Environment that may refuse it, and settle it
+   *   afterwards with {@link ComponentContext.commitChangeTrail}.
+   *
+   * @see {@link ComponentContext.commitChangeTrail}
    * @see {@link ComponentContext.reCreateChanges}
    */
-  buildChangeTrails(clearChanges = true) {
-    const trails = [];
-    if (!this.hasComponents()) return trails;
-    const pathOfChanges = this.#buildPathOfChanges();
-    for (const changes of pathOfChanges) {
-      changes.buildChangeTrail(trails, ChangeTrailPhase.StructuralChanges);
-    }
-    for (const changes of pathOfChanges) {
-      changes.buildChangeTrail(trails, ChangeTrailPhase.ContentUpdates);
-    }
-    for (const changes of pathOfChanges) {
-      changes.buildChangeTrail(trails, ChangeTrailPhase.Removal);
-      if (changes.isDestroyed || changes.isNew && !changes.isCreated) {
-        this.#deleteComponent(changes.uuid);
+  buildChangeTrails(commit = true) {
+    this.#peerReRequests.flush();
+    if (this.#uncommittedTrail != null) {
+      this.#logger.debug("committing an open change trail because a second one is being built", this.#uncommittedTrail.entries);
+      this.commitChangeTrail(this.#uncommittedTrail.entries.length);
+    }
+    const entries = [];
+    const owners = [];
+    const participants = this.hasComponents() ? this.#buildPathOfChanges() : [];
+    const build = (changes, phase) => {
+      const before = entries.length;
+      changes.buildChangeTrail(entries, phase);
+      for (let i = before; i < entries.length; i++) {
+        owners[i] = changes;
       }
-      if (clearChanges) changes.clear();
+    };
+    for (const changes of participants) build(changes, ChangeTrailPhase.StructuralChanges);
+    for (const changes of participants) build(changes, ChangeTrailPhase.ContentUpdates);
+    for (const changes of participants) build(changes, ChangeTrailPhase.Removal);
+    this.#uncommittedTrail = { entries, owners, retiring: this.#retiringComponents(participants) };
+    if (commit) this.commitChangeTrail(entries.length);
+    return entries;
+  }
+  /**
+   * Fold the first `appliedCount` entries of the change trail this context built last into the
+   * state the next trail is diffed against, and write them to the Component Memory. Every entry
+   * behind that line stays pending and goes out again with the next trail.
+   *
+   * A component is retired -- its entry dropped -- only where the build read it as spent and every
+   * entry it contributed is settled. One component can hold a creation and an event in the same
+   * trail, and a creation sent twice is refused by the Shadow Environment, which already holds an
+   * entity behind that uuid.
+   *
+   * @param appliedCount how many entries the Shadow Environment applied, counted from the front.
+   *   Clamped to the length of the trail.
+   * @param changeTrail the trail this call settles. Given, the call is ignored unless it is the
+   *   very trail this context built last -- a cycle that lost its trail to a later build must not
+   *   draw a line through that later trail.
+   */
+  commitChangeTrail(appliedCount, changeTrail) {
+    const uncommitted = this.#uncommittedTrail;
+    if (uncommitted == null) return;
+    if (changeTrail != null && changeTrail !== uncommitted.entries) return;
+    const { entries, owners, retiring } = uncommitted;
+    const count = Math.min(Math.max(appliedCount, 0), entries.length);
+    this.#uncommittedTrail = void 0;
+    const stillPending = new Set(owners.slice(count));
+    for (let i = 0; i < count; i++) {
+      owners[i].commitChange(entries[i]);
     }
-    this.#componentMemory.write(trails);
-    return trails;
+    this.#componentMemory.write(count === entries.length ? entries : entries.slice(0, count));
+    this.#retireComponents(retiring, stillPending);
+  }
+  /**
+   * Whether the Component Memory holds a state for `uuid` — the state
+   * {@link ComponentContext.reCreateChanges} would rebuild that component from.
+   */
+  hasComponentState(uuid) {
+    return this.#componentMemory.hasComponentState(uuid);
+  }
+  /**
+   * The state the Component Memory holds for `uuid`, or `undefined` where it holds none.
+   *
+   * A snapshot, not the record: the property list of the record is rewritten in place as
+   * trails come in, so a caller holding on to it would be reading a moving value — or
+   * writing one. What it is a snapshot of is the memory at the moment of the call, and the
+   * memory moves under several hands: {@link ComponentContext.commitChangeTrail} folds a
+   * settled trail into it, {@link ComponentContext.buildChangeTrails} does the same for the
+   * trail it builds unless it is told not to commit, {@link ComponentContext.reCreateChanges}
+   * writes the trail it builds and empties the memory afterwards, and
+   * {@link ComponentContext.clear} empties it outright. A snapshot taken before any of those
+   * describes a state that is over; take it again to see the current one.
+   *
+   * This is the window a test or a diagnosis needs, and the one that leaves the context as it
+   * found it — reading the same thing out of {@link ComponentContext.reCreateChanges} costs a
+   * rebuild of every component in the namespace.
+   */
+  getComponentState(uuid) {
+    const state = this.#componentMemory.getComponentState(uuid);
+    if (state === void 0) return void 0;
+    return {
+      ...state,
+      properties: state.properties?.map((entry) => entry.length === 1 ? [entry[0]] : [entry[0], entry[1]])
+    };
   }
   /**
    * Resets the internal component change states so that all view components are regenerated with the next change trail.
    * The outstanding events are taken over.
    *
+   * The trail this produces belongs to a Shadow Environment that holds none of these uuids -- a
+   * fresh proxy. One whose Kernel still holds them refuses the first re-created creation it reads,
+   * and every cycle that follows, because a uuid names one entity at a time.
+   *
    * @see {@link ComponentContext.buildChangeTrails}
    */
   reCreateChanges() {
     if (this.#componentMemory.isEmpty()) return;
-    this.buildChangeTrails(false);
+    const trails = this.buildChangeTrails(false);
+    this.#componentMemory.write(trails);
+    this.#retireBuiltTrail();
     for (const [uuid, cMem] of this.#componentMemory) {
       const c = this.#components.get(uuid);
       if (c) {
         const changes = new ComponentChanges(uuid);
         changes.create(cMem.token, cMem.parentUuid, cMem.order, cMem.autoDestructionOnParentRemoval);
         if (cMem.properties) {
-          for (const [key, value] of cMem.properties) {
-            changes.changeProperty(key, value, c.propIsEqual?.get(key));
+          for (const entry of cMem.properties) {
+            const key = entry[0];
+            if (entry.length === 1) {
+              changes.setPropertyWithoutValue(key);
+            } else {
+              changes.changeProperty(key, entry[1], c.propIsEqual?.get(key));
+            }
           }
         }
         c.changes.transferEventsTo(changes);
@@ -248,86 +718,149 @@ class ComponentContext {
     this.#componentMemory.clear();
     this.broadcastEvent(ContextLost);
   }
+  /**
+   * Remove all components without writing anything to a change trail. Every
+   * {@link ViewComponent} this context holds is destroyed, so each of them reports
+   * {@link ViewComponent#isDestroyed} and holds no context afterwards. The context itself stays
+   * registered under its namespace and can be used again — assigning it to a component takes
+   * that component back in under the same uuid.
+   *
+   * @see {@link ComponentContext.dispose} for the final teardown
+   */
   clear() {
     this.#viewInstances = void 0;
     this.#componentMemory.clear();
-    this.#rootComponents.slice(0).forEach((uuid) => this.removeSubTree(uuid));
-    if (this.#rootComponents.length !== 0) {
+    this.#uncommittedTrail = void 0;
+    for (const component of Array.from(this.#componentInstances)) {
+      component.destroy();
+    }
+    this.#componentInstances.clear();
+    for (const uuid of [...this.#rootComponents.uuids]) {
+      this.removeSubTree(uuid);
+    }
+    if (this.#rootComponents.size !== 0) {
       throw new Error("component-context panic: #rootComponents is not empty!");
     }
     if (this.#components.size !== 0) {
       throw new Error("component-context panic: #components is not empty!");
     }
   }
-  #deleteComponent(uuid) {
-    if (this.#components.has(uuid)) {
-      this.#components.delete(uuid);
-      removeFrom(this.#rootComponents, uuid);
-      this.#viewInstances = void 0;
+  /**
+   * Tear the context down for good: every {@link ViewComponent} it holds is destroyed, the
+   * component memory is dropped, and the namespace is released so that
+   * {@link ComponentContext.get} creates a fresh context for it.
+   *
+   * Unlike {@link ComponentContext.clear} this is final. The context holds no components,
+   * produces empty change trails, and rejects any component that tries to join it. Calling
+   * it more than once is a no-op.
+   *
+   * A `ShadowEnv` bound to this context keeps its reference; destroy the environment
+   * first if you want the namespace released on both sides.
+   */
+  dispose() {
+    if (this.#isDisposed) return;
+    this.clear();
+    this.#isDisposed = true;
+    const ctxMap = ComponentContext.getContextsMap();
+    if (this.ns != null && ctxMap.get(this.ns) === this) {
+      ctxMap.delete(this.ns);
     }
   }
+  /**
+   * Drop the component entry behind `uuid`, and with it the uuid's place in every children list.
+   *
+   * @param expectedChanges the bookkeeping that asked for the deletion. A round trip lies between
+   *   the build of a change trail and its commit, and an entry that a different bookkeeping stands
+   *   behind by then belongs to a component that joined in the meantime.
+   */
+  #deleteComponent(uuid, expectedChanges) {
+    const entry = this.#components.get(uuid);
+    if (entry === void 0) return;
+    if (expectedChanges !== void 0 && entry.changes !== expectedChanges) return;
+    const parentUuid = entry.component.parent?.uuid;
+    if (parentUuid !== void 0) {
+      const parentEntry = this.#components.get(parentUuid);
+      if (parentEntry !== void 0) {
+        parentEntry.children.delete(uuid);
+      }
+    }
+    this.#components.delete(uuid);
+    this.#rootComponents.delete(uuid);
+    this.#viewInstances = void 0;
+  }
   #buildPathOfChanges() {
     return this.#traverseLevelOrderBFS().filter((vi) => vi.changes.hasChanges()).map((vi) => vi.changes);
   }
+  /**
+   * Insert a component into an ordered list of uuids.
+   *
+   * The list is kept sorted by ascending {@link ViewComponent#order}. Components sharing
+   * the same order value keep their insertion order, so the new component is placed after
+   * all components with an equal order.
+   *
+   * Uuids without a matching view instance are skipped instead of dereferenced, so a
+   * partially torn down list can never turn a reordering into an exception.
+   *
+   * Two questions decide what one insertion costs, and a list that carries nothing but its uuids
+   * has to be walked for both: once to see whether the uuid already stands in it, once to find the
+   * place it sorts into. Filling such a list with n components costs n(n+1)/2 steps. `OrderedUuids`
+   * answers the membership in one step, and the shortcut below answers the place in one more for
+   * every component that sorts at or after the last member; a component that sorts ahead of it
+   * still walks the list. Building n roots one after another, all on the default order, that is
+   * 1.01 ms for 600 and 2.03 ms for 1200, against 4.44 ms and 16.04 ms for the walked list.
+   * Numbers measured 2026-08-31 on node v25.9.0, on the context alone with no DOM around
+   * it -- a snapshot, not a guarantee. The parent-resolution series in
+   * `packages/shadow-objects/docs/guides.md` was measured in a browser and covers a different question.
+   */
   #appendToOrdered(component, childUuids) {
-    if (childUuids.length === 0) {
-      childUuids.push(component.uuid);
-      return;
-    }
-    if (childUuids.includes(component.uuid)) {
+    if (childUuids.has(component.uuid)) {
       return;
     }
-    const len = childUuids.length;
-    const childComponents = new Array(len);
-    childComponents[0] = this.#components.get(childUuids[0]).component;
-    if (component.order < childComponents[0].order) {
-      childUuids.unshift(component.uuid);
-      return;
-    }
-    if (len === 1) {
+    const { order } = component;
+    const last = childUuids.size > 0 ? this.#components.get(childUuids.uuids[childUuids.size - 1])?.component : void 0;
+    if (last !== void 0 && order >= last.order) {
       childUuids.push(component.uuid);
       return;
     }
-    const lastIdx = len - 1;
-    childComponents[lastIdx] = this.#components.get(childUuids[lastIdx]).component;
-    if (component.order >= childComponents[lastIdx].order) {
-      childUuids.push(component.uuid);
-      return;
-    }
-    if (len === 2) {
-      childUuids.splice(1, 0, component.uuid);
-      return;
-    }
-    for (let i = lastIdx - 1; i >= 1; i--) {
-      childComponents[i] = this.#components.get(childUuids[i]).component;
-      if (component.order >= childComponents[i].order) {
-        childUuids.splice(i + 1, 0, component.uuid);
+    for (let i = 0; i < childUuids.size; i++) {
+      const other = this.#components.get(childUuids.uuids[i])?.component;
+      if (other !== void 0 && order < other.order) {
+        childUuids.insertAt(i, component.uuid);
         return;
       }
     }
+    childUuids.push(component.uuid);
   }
   #viewInstances;
   #traverseLevelOrderBFS() {
     if (this.#viewInstances) return this.#viewInstances;
     const lvl = /* @__PURE__ */ new Map();
+    const visited = /* @__PURE__ */ new Set();
     const traverse = (uuid, depth) => {
+      if (visited.has(uuid)) return;
+      visited.add(uuid);
       const viewInstance = this.#components.get(uuid);
       if (viewInstance == null) return;
-      if (lvl.has(depth)) {
-        lvl.get(depth).push(viewInstance);
+      const atDepth = lvl.get(depth);
+      if (atDepth) {
+        atDepth.push(viewInstance);
       } else {
         lvl.set(depth, [viewInstance]);
       }
-      for (const childUuid of viewInstance.children) {
+      for (const childUuid of viewInstance.children.uuids) {
         traverse(childUuid, depth + 1);
       }
     };
-    this.#rootComponents.forEach((uuid) => traverse(uuid, 0));
+    for (const uuid of this.#rootComponents.uuids) {
+      traverse(uuid, 0);
+    }
     this.#viewInstances = Array.from(lvl.entries()).sort((a, b) => a[0] - b[0]).flatMap(([, vi]) => vi);
     return this.#viewInstances;
   }
 }
 export {
-  ComponentContext
+  ComponentContext,
+  ComponentContextDisposedError,
+  ComponentUuidInUseError
 };
 //# sourceMappingURL=ComponentContext.js.map