@spearwolf/shadow-objects 0.33.0 → 0.34.0

package/src/view/ComponentChanges.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/view/ComponentChanges.ts"],
-  "sourcesContent": ["import {ChangeTrailPhase, ComponentChangeType, VoidToken} from '../constants.js';\nimport type {\n  IChangeToken,\n  IComponentChangeType,\n  IComponentEvent,\n  ICreateEntitiesChange,\n  IDestroyEntitiesChange,\n  IPropertiesChange,\n  ISendEvents,\n  ISetParentChange,\n  IUpdateOrderChange,\n} from '../types.js';\nimport {appendToEnd, removeFrom} from '../utils/array-utils.js';\n\nconst ROOT = '#root';\n\nexport class ComponentChanges {\n  readonly #uuid: string;\n\n  get uuid(): string {\n    return this.#uuid;\n  }\n\n  #serial = 0;\n\n  constructor(uuid: string) {\n    this.#uuid = uuid;\n  }\n\n  #isNew = true;\n  #createCount = 0;\n  #destroyCount = 0;\n\n  hasChanges(): boolean {\n    return this.#serial > 0;\n  }\n\n  get isNew(): boolean {\n    return this.#isNew;\n  }\n\n  get isCreated(): boolean {\n    return this.#createCount > 0 && this.#createCount > this.#destroyCount;\n  }\n\n  get isDestroyed(): boolean {\n    return this.#destroyCount > 0 && this.#destroyCount >= this.#createCount;\n  }\n\n  #token: string = VoidToken;\n  #parentUuid?: string;\n  #order: number = 0;\n  #autoDestructionOnParentRemoval = false;\n\n  #nextToken?: string;\n  #nextParentUuid?: string;\n  #nextOrder?: number;\n\n  create(token: string = VoidToken, parentUuid?: string, order: number = 0, autoDestructionOnParentRemoval = false) {\n    this.#serial++;\n    this.#createCount++;\n\n    this.#nextToken = token;\n    this.#nextParentUuid = parentUuid ?? ROOT;\n    this.#nextOrder = !order ? undefined : order;\n    this.#autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;\n  }\n\n  destroy() {\n    this.#destroyCount++;\n    this.#serial++;\n  }\n\n  clear() {\n    this.#serial = 0;\n\n    this.#isNew = false;\n\n    this.#nextToken = undefined;\n    this.#nextParentUuid = undefined;\n    this.#nextOrder = undefined;\n\n    this.#nextProperties.clear();\n    this.#propsChangeOrder.length = 0;\n\n    this.#events.length = 0;\n    this.#transferables.clear();\n  }\n\n  changeToken(token: string | undefined) {\n    // an absent token means the void token everywhere else, so normalize here too;\n    // otherwise `undefined` would mark the component dirty without ever emitting a change\n    token ??= VoidToken;\n\n    if (token === this.#token) {\n      // a component that has not been flushed yet still owes the trail its create-token:\n      // #token is only the last *written* token, so dropping #nextToken here would emit a\n      // CreateEntities change without any token at all\n      this.#nextToken = this.#isNew ? token : undefined;\n    } else {\n      this.#nextToken = token;\n      this.#serial++;\n    }\n  }\n\n  setParent(parentUuid?: string) {\n    if (parentUuid === this.#parentUuid) {\n      this.#nextParentUuid = undefined;\n    } else {\n      this.#nextParentUuid = parentUuid ?? ROOT;\n      this.#serial++;\n    }\n  }\n\n  changeOrder(order: number) {\n    if (order === this.#order) {\n      this.#nextOrder = undefined;\n    } else {\n      this.#nextOrder = order;\n      this.#serial++;\n    }\n  }\n\n  #properties: Map<string, unknown> = new Map();\n  #nextProperties: Map<string, unknown> = new Map();\n  #propsChangeOrder: string[] = []; // we use an Array here and not a Set, because we want to keep the change order\n\n  /**\n   * @returns `true` if the value differs from the last value written to a change trail\n   */\n  changeProperty<T = unknown>(key: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean {\n    const prevValue = this.#properties.get(key) as T;\n    const valueChanged = (isEqual == null && value !== prevValue) || (isEqual != null && !isEqual(value, prevValue));\n\n    if (valueChanged) {\n      this.#nextProperties.set(key, value);\n      appendToEnd(this.#propsChangeOrder, key);\n      this.#serial++;\n    } else {\n      this.#nextProperties.delete(key);\n      removeFrom(this.#propsChangeOrder, key);\n    }\n\n    return valueChanged;\n  }\n\n  removeProperty(key: string) {\n    const propExists = this.#properties.has(key);\n    if (this.#nextProperties.has(key)) {\n      this.#nextProperties.delete(key);\n      if (!propExists) {\n        removeFrom(this.#propsChangeOrder, key);\n      }\n    } else if (propExists) {\n      appendToEnd(this.#propsChangeOrder, key);\n      this.#serial++;\n    }\n  }\n\n  #events: IComponentEvent[] = [];\n  #transferables = new Set<Transferable>();\n\n  createEvent(type: string, data: unknown, transferables?: Transferable[]) {\n    this.#events.push({type, data});\n    for (const transferable of transferables ?? []) {\n      this.#transferables.add(transferable);\n    }\n    this.#serial++;\n  }\n\n  transferEventsTo(changes: ComponentChanges) {\n    if (this.#events.length > 0) {\n      changes.#events.push(...this.#events);\n      this.#events.length = 0;\n    }\n    if (this.#transferables.size > 0) {\n      changes.#transferables = new Set([...changes.#transferables, ...this.#transferables]);\n      this.#transferables.clear();\n    }\n  }\n\n  buildChangeTrail(trail: IComponentChangeType[], trailPhase: ChangeTrailPhase) {\n    const {isNew, isCreated, isDestroyed} = this;\n\n    if (isNew && isDestroyed) return;\n\n    switch (trailPhase) {\n      case ChangeTrailPhase.StructuralChanges:\n        if (isNew) {\n          trail.push(this.makeCreateEntityChange());\n        } else if (!isDestroyed) {\n          if (this.#nextParentUuid !== undefined && !(this.#nextParentUuid === ROOT && this.#parentUuid === undefined)) {\n            trail.push(this.makeSetParentChange());\n          } else if (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) {\n            trail.push(this.makeUpdateOrderChange());\n          }\n          if (this.#nextToken !== undefined && this.#nextToken !== this.#token) {\n            trail.push(this.makeChangeToken());\n          }\n        }\n        break;\n\n      case ChangeTrailPhase.ContentUpdates:\n        if (!isNew && isCreated && this.#propsChangeOrder.length > 0) {\n          trail.push(this.makeChangePropertyChange());\n        }\n        if (this.#events.length > 0) {\n          trail.push(this.makeEvents());\n        }\n        break;\n\n      case ChangeTrailPhase.Removal:\n        if (isDestroyed) {\n          trail.push(this.makeDestroyEntityChange());\n        }\n        break;\n    }\n  }\n\n  makeEvents(): ISendEvents {\n    const event: ISendEvents = {\n      type: ComponentChangeType.SendEvents,\n      uuid: this.#uuid,\n      events: this.#events.slice(0),\n    };\n    if (this.#transferables.size > 0) {\n      event.transferables = Array.from(this.#transferables);\n    }\n    return event;\n  }\n\n  makeCreateEntityChange(): ICreateEntitiesChange {\n    // never emit a create without a token: the kernel would register an entity that no\n    // shadow object can ever be looked up for\n    const token = this.#nextToken ?? this.#token;\n\n    const entry: ICreateEntitiesChange = {\n      type: ComponentChangeType.CreateEntities,\n      uuid: this.#uuid,\n      token,\n    };\n\n    this.#token = token;\n\n    if (this.#nextParentUuid !== undefined) {\n      const nextParentUuid = this.#nextParentUuid === ROOT ? undefined : this.#nextParentUuid;\n      this.#parentUuid = nextParentUuid;\n      if (nextParentUuid !== undefined) {\n        entry.parentUuid = nextParentUuid;\n      }\n    }\n\n    if (this.#nextProperties.size > 0) {\n      entry.properties = Array.from(this.#nextProperties.entries()).filter(([, value]) => value !== undefined);\n      for (const [key, value] of entry.properties) {\n        this.#properties.set(key, value);\n      }\n    }\n\n    if (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) {\n      entry.order = this.#order = this.#nextOrder;\n    }\n\n    if (this.#autoDestructionOnParentRemoval) {\n      entry.autoDestructionOnParentRemoval = true;\n    }\n\n    return entry;\n  }\n\n  makeDestroyEntityChange(): IDestroyEntitiesChange {\n    return {\n      type: ComponentChangeType.DestroyEntities,\n      uuid: this.#uuid,\n    };\n  }\n\n  makeSetParentChange(): ISetParentChange {\n    this.#parentUuid = this.#nextParentUuid === ROOT ? undefined : this.#nextParentUuid;\n\n    const entry: ISetParentChange = {\n      type: ComponentChangeType.SetParent,\n      uuid: this.#uuid,\n      parentUuid: this.#parentUuid,\n    };\n\n    if (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) {\n      entry.order = this.#order = this.#nextOrder;\n    }\n\n    return entry;\n  }\n\n  makeUpdateOrderChange(): IUpdateOrderChange {\n    this.#order = this.#nextOrder ?? 0;\n\n    return {\n      type: ComponentChangeType.UpdateOrder,\n      uuid: this.#uuid,\n      order: this.#order,\n    };\n  }\n\n  makeChangeToken(): IChangeToken {\n    this.#token = this.#nextToken ?? VoidToken;\n\n    return {\n      type: ComponentChangeType.ChangeToken,\n      uuid: this.#uuid,\n      token: this.#token,\n    };\n  }\n\n  makeChangePropertyChange(): IPropertiesChange {\n    const properties = this.#propsChangeOrder.map((key) => {\n      if (this.#nextProperties.has(key)) {\n        // set prop \u2014 an explicit `undefined` is a removal, exactly like removeProperty()\n        const nextValue = this.#nextProperties.get(key);\n        if (nextValue === undefined) {\n          this.#properties.delete(key);\n        } else {\n          this.#properties.set(key, nextValue);\n        }\n        return [key, nextValue] as [string, unknown];\n      } else {\n        // remove prop\n        this.#properties.delete(key);\n        return [key, undefined] as [string, unknown];\n      }\n    });\n\n    return {\n      type: ComponentChangeType.ChangeProperties,\n      uuid: this.#uuid,\n      properties,\n    };\n  }\n}"],
-  "mappings": "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",
+  "sourcesContent": ["import {ChangeTrailPhase, ComponentChangeType, VoidToken} from '../constants.js';\nimport type {\n  ComponentPropertiesType,\n  IChangeToken,\n  IComponentChangeType,\n  IComponentEvent,\n  ICreateEntitiesChange,\n  IDestroyEntitiesChange,\n  IPropertiesChange,\n  ISendEvents,\n  ISetParentChange,\n  IUpdateOrderChange,\n} from '../types.js';\nimport {appendToEnd, removeFrom} from '../utils/array-utils.js';\n\nconst ROOT = '#root';\n\n/**\n * The value a property carries in this bookkeeping when it is set without one \u2014 the third form\n * of {@link ComponentPropertiesType}, which travels as a one-element `[key]`. `undefined`\n * cannot say it: that is what a removal reads as, and the two have to stay apart all the way\n * to the entry.\n *\n * It never leaves the View Layer. A change trail runs through `structuredClone()` on its way\n * to a worker, and a symbol on that wire is a `DataCloneError` \u2014 so every method that builds\n * an entry turns it back into the one-element form, and the one reader outside this class,\n * `ComponentContext.transferPropertiesTo()`, tests for it before it hands a value on.\n */\nexport const PropertyWithoutValue = Symbol('shadow-objects/property-without-value');\n\n/**\n * Tracks one component's outstanding changes between two change trails as four written \u2194\n * pending pairs: `#token`/`#nextToken`, `#parentUuid`/`#nextParentUuid`, `#order`/`#nextOrder`\n * and `#properties`/`#nextProperties`. The `make*` methods read the pending half and leave it\n * where it is: a trail entry is a request, and until the Shadow Environment has applied it the\n * change is still owed. {@link ComponentChanges.commitChange} is what moves the line \u2014 it folds\n * one applied entry into the written half and releases exactly the pending values that entry\n * carried, so a value that changed again while the entry was on its way goes out with the next\n * trail instead of being lost.\n *\n * Whether anything is outstanding follows from those pairs rather than from a counter, which is\n * what lets a partly applied trail leave the rest of the component untouched.\n *\n * The create/destroy counts behind {@link ComponentChanges.isCreated} and {@link\n * ComponentChanges.isDestroyed} belong to the uuid, not to a `ViewComponent` instance. They\n * carry the rule `ComponentContext.addComponent` keeps: a uuid names one component of a\n * `ComponentContext` at a time, so a later component takes this bookkeeping over only once\n * its predecessor has counted its own `destroy()`. A count pair that outlives its component\n * therefore describes an entity, and the successor on that uuid continues the same entity\n * rather than starting a second.\n */\nexport class ComponentChanges {\n  readonly #uuid: string;\n\n  get uuid(): string {\n    return this.#uuid;\n  }\n\n  constructor(uuid: string) {\n    this.#uuid = uuid;\n  }\n\n  #isNew = true;\n  #createCount = 0;\n  #destroyCount = 0;\n\n  /**\n   * Whether this component owes the next change trail anything: a creation, a destruction, or a\n   * pending value in one of the four written \u2194 pending pairs.\n   */\n  hasChanges(): boolean {\n    return (\n      (this.#isNew && this.isCreated) ||\n      this.isDestroyed ||\n      (this.#nextToken !== undefined && this.#nextToken !== this.#token) ||\n      this.#hasPendingParent() ||\n      (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) ||\n      this.#propsChangeOrder.length > 0 ||\n      this.#events.length > 0\n    );\n  }\n\n  get isNew(): boolean {\n    return this.#isNew;\n  }\n\n  get isCreated(): boolean {\n    return this.#createCount > 0 && this.#createCount > this.#destroyCount;\n  }\n\n  get isDestroyed(): boolean {\n    return this.#destroyCount > 0 && this.#destroyCount >= this.#createCount;\n  }\n\n  #token: string = VoidToken;\n  #parentUuid?: string | undefined;\n  #order: number = 0;\n  #autoDestructionOnParentRemoval = false;\n\n  #nextToken?: string | undefined;\n  #nextParentUuid?: string | undefined;\n  #nextOrder?: number | undefined;\n\n  create(token: string = VoidToken, parentUuid?: string, order: number = 0, autoDestructionOnParentRemoval = false) {\n    this.#createCount++;\n\n    this.#nextToken = token;\n    this.#nextParentUuid = parentUuid ?? ROOT;\n    this.#nextOrder = !order ? undefined : order;\n    this.#autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;\n  }\n\n  destroy() {\n    this.#destroyCount++;\n  }\n\n  /**\n   * Whether the pending parent asks for something the confirmed one is not already. A pending\n   * value that has come back to the confirmed parent is a change that cancelled itself out.\n   */\n  #hasPendingParent(): boolean {\n    if (this.#nextParentUuid === undefined) return false;\n    return (this.#nextParentUuid === ROOT ? undefined : this.#nextParentUuid) !== this.#parentUuid;\n  }\n\n  /**\n   * Drop every pending value without writing any of them forward.\n   *\n   * This is the way out for a component whose bookkeeping is about to be replaced wholesale \u2014\n   * `ComponentContext.reCreateChanges` does exactly that. A trail that has gone out is\n   * settled with {@link ComponentChanges.commitChange} instead.\n   */\n  clear() {\n    this.#nextToken = undefined;\n    this.#nextParentUuid = undefined;\n    this.#nextOrder = undefined;\n\n    this.#nextProperties.clear();\n    this.#propsChangeOrder.length = 0;\n    this.#travellingProperties = undefined;\n\n    this.#events.length = 0;\n    this.#transferables.clear();\n  }\n\n  /**\n   * The three scalar pairs below all answer the same question the same way: is anything owed once\n   * the entry that is on its way out has landed?\n   *\n   * The written half alone cannot answer it. It is the last *confirmed* value and stays behind\n   * until the entry is committed, so a value the caller sets back to it while the entry travels\n   * would look like \"nothing to do\" \u2014 and the entry would then be the last word, leaving the\n   * Shadow Environment holding a value the view has already moved on from. So the pending half is\n   * only released where there is nothing in flight to contradict it; where there is, the new value\n   * takes the pending slot and the emitting side decides, against the written half it settles on.\n   */\n  changeToken(token: string | undefined) {\n    // an absent token means the void token everywhere else, so normalize here too;\n    // otherwise `undefined` would mark the component dirty without ever emitting a change\n    token ??= VoidToken;\n\n    // nothing pending and the confirmed token is the wanted one: nothing to queue. A component\n    // that has not been flushed yet is the exception \u2014 it still owes the trail its create-token,\n    // and dropping it here would emit a CreateEntities change without any token at all.\n    if (token === this.#token && this.#nextToken === undefined && !this.#isNew) return;\n\n    this.#nextToken = token;\n  }\n\n  setParent(parentUuid?: string) {\n    const nextParentUuid = parentUuid ?? ROOT;\n\n    if (nextParentUuid === (this.#parentUuid ?? ROOT) && this.#nextParentUuid === undefined) return;\n\n    this.#nextParentUuid = nextParentUuid;\n  }\n\n  changeOrder(order: number) {\n    if (order === this.#order && this.#nextOrder === undefined) return;\n\n    this.#nextOrder = order;\n  }\n\n  #properties: Map<string, unknown> = new Map();\n  #nextProperties: Map<string, unknown> = new Map();\n  /**\n   * The keys with a queued change, in the order their changes happened \u2014 the order an entry\n   * carries them in, and the reason this is a list and not a set.\n   *\n   * A set beside it would answer membership in one step, and per call it does win from about eight\n   * 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\n   * at 64. The distance is what decides against it. At the upper stop this repository can produce \u2014\n   * 64 keys, every one of them changed in every frame at 60 fps, so 3840 calls per second \u2014 that is\n   * 0.13 ms saved per second of animation. And membership is the smaller half: `removeFrom()` and\n   * `appendToEnd()` are an `indexOf` plus a `splice`, and the splice stays linear no matter what\n   * answers the membership. Numbers measured 2026-08-31 on node v25.9.0.\n   */\n  #propsChangeOrder: string[] = [];\n\n  /**\n   * The keys an entry on its way out carries, until that entry is settled. For those keys the\n   * written half is behind, and {@link ComponentChanges.changeProperty} must not cancel against it.\n   */\n  #travellingProperties?: Map<string, unknown> | undefined;\n\n  /**\n   * @returns `true` if the value differs from the last value this component asked for\n   */\n  changeProperty<T = unknown>(key: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean {\n    const equals = (a: T, b: T) =>\n      // a registered rule compares values, and the marker is not one -- handed to it, a rule\n      // would be asked about a property it never saw, and one that reaches into its arguments\n      // throws on a symbol. Where either side is the marker the only question left is whether\n      // it is still the same third form, and identity answers that.\n      (a as unknown) === PropertyWithoutValue || (b as unknown) === PropertyWithoutValue\n        ? (a as unknown) === (b as unknown)\n        : isEqual == null\n          ? a === b\n          : isEqual(a, b);\n\n    const isQueued = this.#propsChangeOrder.includes(key);\n    const isTravelling = this.#travellingProperties?.has(key) ?? false;\n\n    // the value this component last said the property should have: the pending half where\n    // something is queued, else what an entry on its way out carries, else the confirmed value.\n    // A key that is none of the three reads as `undefined`, and a registered rule decides that\n    // comparison too -- a rule that calls the value equal to `undefined` says there is nothing\n    // to send.\n    let prevValue: T;\n    if (isQueued) {\n      prevValue = this.#nextProperties.get(key) as T;\n    } else if (isTravelling) {\n      prevValue = this.#travellingProperties!.get(key) as T;\n    } else {\n      prevValue = this.#properties.get(key) as T;\n    }\n\n    const valueChanged = !equals(value, prevValue);\n\n    // The pending half is released only where the confirmed value is the wanted one and no entry\n    // carrying another one is on its way out -- such an entry would otherwise be the last word.\n    // The travelling test comes first because it decides the branch on its own, and a comparison\n    // rule can be expensive on a path that runs once per frame. Where nothing is queued the\n    // comparison above was already the one against the confirmed value, so it is reused.\n    const nothingToSend = !isTravelling && (isQueued ? equals(value, this.#properties.get(key) as T) : !valueChanged);\n\n    if (nothingToSend) {\n      this.#nextProperties.delete(key);\n      removeFrom(this.#propsChangeOrder, key);\n    } else {\n      this.#nextProperties.set(key, value);\n      appendToEnd(this.#propsChangeOrder, key);\n    }\n\n    return valueChanged;\n  }\n\n  /**\n   * Mark `key` as set without giving it a value: the next trail carries an entry that names\n   * only the key. A later {@link ComponentChanges.changeProperty} replaces it with a value,\n   * and {@link ComponentChanges.removeProperty} takes it away like any other property.\n   *\n   * @returns `true` if this differs from the last value this component asked for\n   */\n  setPropertyWithoutValue(key: string): boolean {\n    return this.changeProperty(key, PropertyWithoutValue as unknown);\n  }\n\n  removeProperty(key: string) {\n    const isQueued = this.#propsChangeOrder.includes(key);\n\n    this.#nextProperties.delete(key);\n\n    if (!this.#properties.has(key) && !this.#travellingProperties?.has(key)) {\n      // nothing confirmed and nothing travelling: there is nothing to remove\n      removeFrom(this.#propsChangeOrder, key);\n      return;\n    }\n\n    // a key that was already queued keeps the place it took: the entry carries the changes in\n    // the order they happened, and a removal is not a second change to the same key\n    if (!isQueued) {\n      appendToEnd(this.#propsChangeOrder, key);\n    }\n  }\n\n  /**\n   * The properties this component holds at this moment: the ones a change trail has already\n   * carried, overlaid with everything that has accrued since.\n   *\n   * The overlay is what makes the result the current state instead of the state of the last\n   * trail \u2014 `#properties` is only written forward while a trail is being built\n   * ({@link ComponentChanges.makeCreateEntityChange},\n   * {@link ComponentChanges.makeChangePropertyChange}). A key whose accrued value is `undefined`\n   * and a key queued for change without an accrued value are both removals, and neither appears\n   * in the result. A key that is set without a value stands in the result with\n   * {@link PropertyWithoutValue}.\n   */\n  getProperties(): Map<string, unknown> {\n    const properties = new Map(this.#properties);\n\n    for (const key of this.#propsChangeOrder) {\n      const value = this.#nextProperties.get(key);\n      if (value === undefined) {\n        properties.delete(key);\n      } else {\n        properties.set(key, value);\n      }\n    }\n\n    return properties;\n  }\n\n  #events: IComponentEvent[] = [];\n  #transferables = new Set<Transferable>();\n\n  createEvent(type: string, data: unknown, transferables?: Transferable[]) {\n    this.#events.push({type, data});\n    for (const transferable of transferables ?? []) {\n      this.#transferables.add(transferable);\n    }\n  }\n\n  transferEventsTo(changes: ComponentChanges) {\n    if (this.#events.length > 0) {\n      changes.#events.push(...this.#events);\n      this.#events.length = 0;\n    }\n    if (this.#transferables.size > 0) {\n      changes.#transferables = new Set([...changes.#transferables, ...this.#transferables]);\n      this.#transferables.clear();\n    }\n  }\n\n  buildChangeTrail(trail: IComponentChangeType[], trailPhase: ChangeTrailPhase) {\n    const {isNew, isCreated, isDestroyed} = this;\n\n    if (isNew && isDestroyed) return;\n\n    switch (trailPhase) {\n      case ChangeTrailPhase.StructuralChanges:\n        if (isNew) {\n          trail.push(this.makeCreateEntityChange());\n        } else if (!isDestroyed) {\n          if (this.#hasPendingParent()) {\n            trail.push(this.makeSetParentChange());\n          } else if (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) {\n            trail.push(this.makeUpdateOrderChange());\n          }\n          if (this.#nextToken !== undefined && this.#nextToken !== this.#token) {\n            trail.push(this.makeChangeToken());\n          }\n        }\n        break;\n\n      case ChangeTrailPhase.ContentUpdates:\n        if (!isNew && isCreated && this.#propsChangeOrder.length > 0) {\n          trail.push(this.makeChangePropertyChange());\n        }\n        if (this.#events.length > 0) {\n          trail.push(this.makeEvents());\n        }\n        break;\n\n      case ChangeTrailPhase.Removal:\n        if (isDestroyed) {\n          trail.push(this.makeDestroyEntityChange());\n        }\n        break;\n    }\n  }\n\n  makeEvents(): ISendEvents {\n    const event: ISendEvents = {\n      type: ComponentChangeType.SendEvents,\n      uuid: this.#uuid,\n      events: this.#events.slice(0),\n    };\n    if (this.#transferables.size > 0) {\n      event.transferables = Array.from(this.#transferables);\n    }\n    return event;\n  }\n\n  makeCreateEntityChange(): ICreateEntitiesChange {\n    // never emit a create without a token: the kernel would register an entity that no\n    // shadow object can ever be looked up for\n    const token = this.#nextToken ?? this.#token;\n\n    const entry: ICreateEntitiesChange = {\n      type: ComponentChangeType.CreateEntities,\n      uuid: this.#uuid,\n      token,\n    };\n\n    if (this.#nextParentUuid !== undefined && this.#nextParentUuid !== ROOT) {\n      entry.parentUuid = this.#nextParentUuid;\n    }\n\n    if (this.#nextProperties.size > 0) {\n      // a create carries only the keys that have a value or are set without one; where nothing\n      // is left, the field stays off the entry \u2014 an absent `properties` and an empty one say\n      // the same thing, and the shorter one is what travels. The note is taken either way: it\n      // records what this entry carries, and an entry with no property is travelling with none\n      const properties: ComponentPropertiesType = [];\n      for (const [key, value] of this.#nextProperties) {\n        if (value === PropertyWithoutValue) {\n          properties.push([key]);\n        } else if (value !== undefined) {\n          properties.push([key, value]);\n        }\n      }\n      this.#noteTravellingProperties(properties);\n      if (properties.length > 0) {\n        entry.properties = properties;\n      }\n    }\n\n    if (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) {\n      entry.order = this.#nextOrder;\n    }\n\n    if (this.#autoDestructionOnParentRemoval) {\n      entry.autoDestructionOnParentRemoval = true;\n    }\n\n    return entry;\n  }\n\n  makeDestroyEntityChange(): IDestroyEntitiesChange {\n    return {\n      type: ComponentChangeType.DestroyEntities,\n      uuid: this.#uuid,\n    };\n  }\n\n  makeSetParentChange(): ISetParentChange {\n    const entry: ISetParentChange = {\n      type: ComponentChangeType.SetParent,\n      uuid: this.#uuid,\n      parentUuid: this.#nextParentUuid === ROOT ? undefined : this.#nextParentUuid,\n    };\n\n    if (this.#nextOrder !== undefined && this.#nextOrder !== this.#order) {\n      entry.order = this.#nextOrder;\n    }\n\n    return entry;\n  }\n\n  makeUpdateOrderChange(): IUpdateOrderChange {\n    return {\n      type: ComponentChangeType.UpdateOrder,\n      uuid: this.#uuid,\n      order: this.#nextOrder ?? 0,\n    };\n  }\n\n  makeChangeToken(): IChangeToken {\n    return {\n      type: ComponentChangeType.ChangeToken,\n      uuid: this.#uuid,\n      token: this.#nextToken ?? VoidToken,\n    };\n  }\n\n  makeChangePropertyChange(): IPropertiesChange {\n    // a key without a pending value is a removal, and so is a pending value of `undefined` --\n    // `get()` answers the same for both, which is what the receiving side reads them as. A key\n    // set without a value is the third form and travels as the bare key\n    const properties: ComponentPropertiesType = this.#propsChangeOrder.map((key) => {\n      const value = this.#nextProperties.get(key);\n      return value === PropertyWithoutValue ? [key] : [key, value];\n    });\n\n    this.#noteTravellingProperties(properties);\n\n    return {\n      type: ComponentChangeType.ChangeProperties,\n      uuid: this.#uuid,\n      properties,\n    };\n  }\n\n  /**\n   * Records the keys of an entry that is going out, so a later change knows the written half\n   * is behind.\n   */\n  #noteTravellingProperties(properties: ComponentPropertiesType): void {\n    // the arity carries the meaning on the wire, the marker carries it in here\n    this.#travellingProperties = new Map(\n      properties.map((entry) => [entry[0], entry.length === 1 ? PropertyWithoutValue : entry[1]]),\n    );\n  }\n\n  /**\n   * Fold one trail entry into the written half of this component's bookkeeping: the values the\n   * entry carries become the values the next diff is taken against, and the pending half that\n   * produced them is released. Called once per entry the Shadow Environment has applied.\n   *\n   * A pending value is released only while it is still the value the entry carried. Between the\n   * build of a trail and its confirmation lies a round trip, and whatever changed in that window\n   * is owed to the Shadow Environment \u2014 releasing it here would leave the two sides holding\n   * different values with nothing left to correct them.\n   */\n  commitChange(entry: IComponentChangeType): void {\n    switch (entry.type) {\n      case ComponentChangeType.CreateEntities:\n        this.#commitToken(entry.token);\n        this.#commitParentUuid(entry.parentUuid);\n        this.#commitOrder(entry.order ?? this.#order);\n        this.#commitProperties(entry.properties);\n        // a create carries only the properties that have a value; a pending removal of a key the\n        // entity was never given has nothing left to ask for and is released along with it\n        for (const key of this.#propsChangeOrder.slice(0)) {\n          if (this.#nextProperties.get(key) === undefined && !this.#properties.has(key)) {\n            this.#nextProperties.delete(key);\n            removeFrom(this.#propsChangeOrder, key);\n          }\n        }\n        this.#travellingProperties = undefined;\n        this.#isNew = false;\n        break;\n\n      case ComponentChangeType.SetParent:\n        this.#commitParentUuid(entry.parentUuid);\n        this.#commitOrder(entry.order ?? this.#order);\n        break;\n\n      case ComponentChangeType.UpdateOrder:\n        this.#commitOrder(entry.order);\n        break;\n\n      case ComponentChangeType.ChangeToken:\n        this.#commitToken(entry.token);\n        break;\n\n      case ComponentChangeType.ChangeProperties:\n        this.#commitProperties(entry.properties);\n        this.#travellingProperties = undefined;\n        break;\n\n      case ComponentChangeType.SendEvents:\n        // the entry carries a snapshot taken while the trail was built; anything that arrived\n        // behind it is still waiting to go out\n        this.#events.splice(0, entry.events.length);\n        for (const transferable of entry.transferables ?? []) {\n          this.#transferables.delete(transferable);\n        }\n        break;\n\n      case ComponentChangeType.DestroyEntities:\n        // The entity behind this uuid is gone. Usually the component entry goes with it, but a\n        // uuid its holder has left is free again, and a component that took it over in the\n        // meantime keeps the entry alive. The written half describes an entity that no longer\n        // exists, so it is reset to what a component nobody knows yet looks like -- otherwise the\n        // successor would diff against it and ask for a change to something that is not there.\n        this.#token = VoidToken;\n        this.#parentUuid = undefined;\n        this.#order = 0;\n        this.#properties.clear();\n        this.#travellingProperties = undefined;\n        this.#isNew = true;\n        break;\n    }\n  }\n\n  #commitToken(token: string): void {\n    this.#token = token;\n    if (this.#nextToken === token) {\n      this.#nextToken = undefined;\n    }\n  }\n\n  #commitParentUuid(parentUuid: string | undefined): void {\n    this.#parentUuid = parentUuid;\n    if ((this.#nextParentUuid === ROOT ? undefined : this.#nextParentUuid) === parentUuid) {\n      this.#nextParentUuid = undefined;\n    }\n  }\n\n  #commitOrder(order: number): void {\n    this.#order = order;\n    if (this.#nextOrder === order) {\n      this.#nextOrder = undefined;\n    }\n  }\n\n  #commitProperties(properties: ComponentPropertiesType | undefined): void {\n    for (const entry of properties ?? []) {\n      const key = entry[0];\n      // an entry that names only the key is the third form and not a removal: the written\n      // half has to hold it, or the next diff reads the key as one that was never set\n      const value = entry.length === 1 ? PropertyWithoutValue : entry[1];\n\n      if (value === undefined) {\n        this.#properties.delete(key);\n      } else {\n        this.#properties.set(key, value);\n      }\n\n      if (this.#nextProperties.get(key) === value) {\n        this.#nextProperties.delete(key);\n        removeFrom(this.#propsChangeOrder, key);\n      }\n    }\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/src/view/ComponentContext.d.ts

@@ -1,7 +1,24 @@
 import type { ChangeTrailType, NamespaceType } from '../types.js';
+import { type ComponentState } from './ComponentMemory.js';
 import type { ViewComponent } from './ViewComponent.js';
 declare global {
-    var __shadowEntsContexts: Map<string | symbol, ComponentContext> | undefined;
+    var __shadowObjectsContexts: Map<string | symbol, ComponentContext> | undefined;
+}
+/**
+ * Thrown when a {@link ViewComponent} tries to join a {@link ComponentContext} that has
+ * already been disposed.
+ */
+export declare class ComponentContextDisposedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a {@link ViewComponent} tries to join a {@link ComponentContext} under a uuid
+ * another component of that {@link ComponentContext} is holding. A uuid names one component at a
+ * time; it becomes free again once its holder has left.
+ */
+export declare class ComponentUuidInUseError extends Error {
+    readonly uuid: string;
+    constructor(uuid: string);
 }
 /**
  * The {@link ComponentContext} represents the current real-time state of the _view components_.
@@ -19,18 +36,24 @@ declare global {
  *
  * A context is always associated with a namespace.
  * If no namespace is specified when creating a {@link ComponentContext}, the global namespace is used.
- * There is only one {@link ComponentContext} (a singleton) for each namespace.
- */
-/**
- * Thrown when a {@link ViewComponent} tries to join a {@link ComponentContext} that has
- * already been disposed.
+ * There is only one {@link ComponentContext} instance per namespace: the constructor returns the
+ * existing instance for an already-occupied namespace rather than building a second one, so
+ * {@link ComponentContext.get} is the way consumers are meant to reach it.
  */
-export declare class ComponentContextDisposedError extends Error {
-    constructor(message?: string);
-}
 export declare class ComponentContext {
     #private;
     static readonly ReRequestParentRoots = "re-request-parent-roots";
+    static readonly ReRequestParent = "re-request-parent";
+    /**
+     * 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.
+     */
+    static readonly ReRequestEntHost = "re-request-ent-host";
     static getContextsMap(): Map<NamespaceType, ComponentContext>;
     static get(namespace?: NamespaceType): ComponentContext;
     ns?: NamespaceType;
@@ -43,19 +66,47 @@ export declare class ComponentContext {
      * obtain a fresh context for the same namespace.
      */
     get isDisposed(): boolean;
+    /**
+     * 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: ViewComponent): void;
+    /**
+     * 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: ViewComponent): boolean;
     hasComponents(): boolean;
     isRootComponent(component: ViewComponent): boolean;
     destroyComponent(component: ViewComponent): void;
+    /**
+     * 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: ViewComponent): ViewComponent[];
-    removeFromParent(childUuid: string, parent: ViewComponent): void;
-    moveToRoot(childUuid: string): void;
+    removeFromParent(component: ViewComponent, parent: ViewComponent): void;
+    moveToRoot(component: ViewComponent): void;
     changeToken(component: ViewComponent, token?: string): void;
     isChildOf(child: ViewComponent, parent: ViewComponent): boolean;
     addToChildren(parent: ViewComponent, child: ViewComponent): void;
     /**
      * 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}
      */
@@ -64,7 +115,48 @@ export declare class ComponentContext {
      * @returns `true` if the value differs from the last value written to a change trail
      */
     setProperty<T = unknown>(component: ViewComponent, propKey: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean;
+    /**
+     * 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: ViewComponent, propKey: string): boolean;
     removeProperty(component: ViewComponent, propKey: string): void;
+    /**
+     * 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: ViewComponent, target: ComponentContext): void;
     changeOrder(component: ViewComponent): void;
     /**
      * @returns all view-components in breadth-first order
@@ -83,26 +175,124 @@ export declare class ComponentContext {
      */
     dispatchMessage(uuid: string, type: string, data?: unknown, traverseChildren?: boolean): void;
     /**
-     * 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(): void;
+    /**
+     * 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: ViewComponent): void;
+    /**
+     * 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: ViewComponent, data?: unknown): void;
     /**
      * 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?: boolean): ChangeTrailType;
+    buildChangeTrails(commit?: boolean): ChangeTrailType;
+    /**
+     * 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: number, changeTrail?: ChangeTrailType): void;
+    /**
+     * Whether the Component Memory holds a state for `uuid` — the state
+     * {@link ComponentContext.reCreateChanges} would rebuild that component from.
+     */
+    hasComponentState(uuid: string): boolean;
+    /**
+     * 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: string): ComponentState | undefined;
     /**
      * 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(): void;
     /**
-     * Remove all components without writing anything to a change trail. The context stays
-     * registered under its namespace and can be used again afterwards.
+     * 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
      */
@@ -116,7 +306,7 @@ export declare class ComponentContext {
      * produces empty change trails, and rejects any component that tries to join it. Calling
      * it more than once is a no-op.
      *
-     * A {@link ShadowEnv} bound to this context keeps its reference; destroy the environment
+     * A `ShadowEnv` bound to this context keeps its reference; destroy the environment
      * first if you want the namespace released on both sides.
      */
     dispose(): void;

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

@@ -1 +1 @@
-{"version":3,"file":"ComponentContext.d.ts","sourceRoot":"","sources":["../../../src/view/ComponentContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAwB,aAAa,EAAC,MAAM,aAAa,CAAC;AAKtF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAStD,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,oBAAoB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,CAAC;CAC9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,OAAO,SAA4C;CAIhE;AAED,qBAAa,gBAAgB;;IAC3B,MAAM,CAAC,QAAQ,CAAC,oBAAoB,6BAA6B;IAEjE,MAAM,CAAC,cAAc,IAAI,GAAG,CAAC,aAAa,EAAE,gBAAgB,CAAC;IAO7D,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,gBAAgB;IASvD,EAAE,CAAC,EAAE,aAAa,CAAC;gBAQP,SAAS,GAAE,aAAwB;IAU/C;;;;;;OAMG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,YAAY,CAAC,SAAS,EAAE,aAAa;IA+CrC,YAAY,CAAC,SAAS,EAAE,aAAa;IAIrC,aAAa;IAIb,eAAe,CAAC,SAAS,EAAE,aAAa;IAIxC,gBAAgB,CAAC,SAAS,EAAE,aAAa;IAWzC,WAAW,CAAC,SAAS,EAAE,aAAa,GAAG,aAAa,EAAE;IAItD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa;IAkBzD,UAAU,CAAC,SAAS,EAAE,MAAM;IAS5B,WAAW,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM;IAIpD,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa;IAQrD,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa;IAYzD;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM;IAkB1B;;OAEG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO;IAczH,cAAc,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;IAIxD,WAAW,CAAC,SAAS,EAAE,aAAa;IAmBpC;;OAEG;IACH,qBAAqB,IAAI,aAAa,EAAE;IAIxC;;OAEG;IACH,0BAA0B,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,YAAY,EAAE;IAIhH;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAmB;IAMtD;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAmB,EAAE,gBAAgB,UAAQ;IAI/F;;OAEG;IACH,4BAA4B;IAM5B;;;;;OAKG;IACH,iBAAiB,CAAC,YAAY,UAAO,GAAG,eAAe;IAmCvD;;;;;OAKG;IACH,eAAe;IA6Bf;;;;;OAKG;IACH,KAAK;IAiBL;;;;;;;;;;;OAWG;IACH,OAAO;CAyGR"}
+{"version":3,"file":"ComponentContext.d.ts","sourceRoot":"","sources":["../../../src/view/ComponentContext.ts"],"names":[],"mappings":"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"}