@spearwolf/shadow-objects 0.32.0 → 0.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (213) hide show
  1. package/CHANGELOG.md +333 -10
  2. package/README.md +100 -20
  3. package/bundle.js +5 -54
  4. package/package.json +7 -3
  5. package/src/ChangeTrailRefusedError.d.ts +27 -0
  6. package/src/ChangeTrailRefusedError.d.ts.map +1 -0
  7. package/src/ChangeTrailRefusedError.js +12 -0
  8. package/src/ChangeTrailRefusedError.js.map +7 -0
  9. package/src/EntityUuidInUseError.d.ts +19 -0
  10. package/src/EntityUuidInUseError.d.ts.map +1 -0
  11. package/src/EntityUuidInUseError.js +11 -0
  12. package/src/EntityUuidInUseError.js.map +7 -0
  13. package/src/WorkerTimeoutError.d.ts +25 -0
  14. package/src/WorkerTimeoutError.d.ts.map +1 -0
  15. package/src/WorkerTimeoutError.js +12 -0
  16. package/src/WorkerTimeoutError.js.map +7 -0
  17. package/src/bundle.d.ts +1 -1
  18. package/src/bundle.d.ts.map +1 -1
  19. package/src/bundle.js +1 -1
  20. package/src/bundle.js.map +2 -2
  21. package/src/constants.d.ts +9 -2
  22. package/src/constants.d.ts.map +1 -1
  23. package/src/constants.js +1 -1
  24. package/src/constants.js.map +2 -2
  25. package/src/create-worker.bundle.d.ts +1 -1
  26. package/src/create-worker.bundle.d.ts.map +1 -1
  27. package/src/create-worker.bundle.js.map +1 -1
  28. package/src/create-worker.d.ts +1 -1
  29. package/src/create-worker.d.ts.map +1 -1
  30. package/src/create-worker.js.map +1 -1
  31. package/src/elements/ShaeElement.d.ts +70 -2
  32. package/src/elements/ShaeElement.d.ts.map +1 -1
  33. package/src/elements/ShaeElement.js +129 -25
  34. package/src/elements/ShaeElement.js.map +3 -3
  35. package/src/elements/ShaeEntElement.d.ts +43 -5
  36. package/src/elements/ShaeEntElement.d.ts.map +1 -1
  37. package/src/elements/ShaeEntElement.js +399 -170
  38. package/src/elements/ShaeEntElement.js.map +2 -2
  39. package/src/elements/ShaeLifecycleElement.d.ts +71 -0
  40. package/src/elements/ShaeLifecycleElement.d.ts.map +1 -0
  41. package/src/elements/ShaeLifecycleElement.js +83 -0
  42. package/src/elements/ShaeLifecycleElement.js.map +7 -0
  43. package/src/elements/ShaePropElement.d.ts +57 -7
  44. package/src/elements/ShaePropElement.d.ts.map +1 -1
  45. package/src/elements/ShaePropElement.js +241 -220
  46. package/src/elements/ShaePropElement.js.map +2 -2
  47. package/src/elements/ShaeWorkerElement.d.ts +49 -5
  48. package/src/elements/ShaeWorkerElement.d.ts.map +1 -1
  49. package/src/elements/ShaeWorkerElement.js +230 -74
  50. package/src/elements/ShaeWorkerElement.js.map +2 -2
  51. package/src/elements/constants.d.ts +6 -0
  52. package/src/elements/constants.d.ts.map +1 -1
  53. package/src/elements/constants.js +12 -0
  54. package/src/elements/constants.js.map +2 -2
  55. package/src/elements/deferredTeardown.d.ts +24 -0
  56. package/src/elements/deferredTeardown.d.ts.map +1 -0
  57. package/src/elements/deferredTeardown.js +30 -0
  58. package/src/elements/deferredTeardown.js.map +7 -0
  59. package/src/elements/displayContentsRule.d.ts +25 -0
  60. package/src/elements/displayContentsRule.d.ts.map +1 -0
  61. package/src/elements/displayContentsRule.js +37 -0
  62. package/src/elements/displayContentsRule.js.map +7 -0
  63. package/src/elements/events.d.ts +10 -7
  64. package/src/elements/events.d.ts.map +1 -1
  65. package/src/elements/forwardCustomEvents.d.ts +19 -0
  66. package/src/elements/forwardCustomEvents.d.ts.map +1 -0
  67. package/src/elements/forwardCustomEvents.js +47 -0
  68. package/src/elements/forwardCustomEvents.js.map +7 -0
  69. package/src/elements/hostedSlots.d.ts +36 -0
  70. package/src/elements/hostedSlots.d.ts.map +1 -0
  71. package/src/elements/hostedSlots.js +118 -0
  72. package/src/elements/hostedSlots.js.map +7 -0
  73. package/src/elements/parentRemoval.d.ts +18 -0
  74. package/src/elements/parentRemoval.d.ts.map +1 -0
  75. package/src/elements/parentRemoval.js +60 -0
  76. package/src/elements/parentRemoval.js.map +7 -0
  77. package/src/elements/propValueConverters.d.ts +3 -0
  78. package/src/elements/propValueConverters.d.ts.map +1 -0
  79. package/src/elements/propValueConverters.js +54 -0
  80. package/src/elements/propValueConverters.js.map +7 -0
  81. package/src/elements/requestEntAncestor.d.ts +32 -0
  82. package/src/elements/requestEntAncestor.d.ts.map +1 -0
  83. package/src/elements/requestEntAncestor.js +16 -0
  84. package/src/elements/requestEntAncestor.js.map +7 -0
  85. package/src/elements.js.map +1 -1
  86. package/src/in-the-dark/Entity.d.ts +113 -3
  87. package/src/in-the-dark/Entity.d.ts.map +1 -1
  88. package/src/in-the-dark/Entity.js +292 -63
  89. package/src/in-the-dark/Entity.js.map +3 -3
  90. package/src/in-the-dark/Kernel.d.ts +81 -17
  91. package/src/in-the-dark/Kernel.d.ts.map +1 -1
  92. package/src/in-the-dark/Kernel.js +449 -392
  93. package/src/in-the-dark/Kernel.js.map +3 -3
  94. package/src/in-the-dark/Registry.d.ts +1 -1
  95. package/src/in-the-dark/Registry.d.ts.map +1 -1
  96. package/src/in-the-dark/Registry.js +99 -26
  97. package/src/in-the-dark/Registry.js.map +2 -2
  98. package/src/in-the-dark/ShadowObject.d.ts +1 -1
  99. package/src/in-the-dark/ShadowObject.d.ts.map +1 -1
  100. package/src/in-the-dark/ShadowObject.js +3 -2
  101. package/src/in-the-dark/ShadowObject.js.map +2 -2
  102. package/src/in-the-dark/ShadowObjectCreationScope.d.ts +126 -0
  103. package/src/in-the-dark/ShadowObjectCreationScope.d.ts.map +1 -0
  104. package/src/in-the-dark/ShadowObjectCreationScope.js +596 -0
  105. package/src/in-the-dark/ShadowObjectCreationScope.js.map +7 -0
  106. package/src/in-the-dark/SignalsPath.d.ts.map +1 -1
  107. package/src/in-the-dark/SignalsPath.js +2 -2
  108. package/src/in-the-dark/SignalsPath.js.map +2 -2
  109. package/src/in-the-dark/events.js.map +1 -1
  110. package/src/in-the-dark/importModule.d.ts +7 -0
  111. package/src/in-the-dark/importModule.d.ts.map +1 -1
  112. package/src/in-the-dark/importModule.js +8 -5
  113. package/src/in-the-dark/importModule.js.map +2 -2
  114. package/src/index.d.ts +7 -1
  115. package/src/index.d.ts.map +1 -1
  116. package/src/index.js +5 -1
  117. package/src/index.js.map +2 -2
  118. package/src/shadow-objects.d.ts +2 -0
  119. package/src/shadow-objects.d.ts.map +1 -1
  120. package/src/shadow-objects.js +2 -0
  121. package/src/shadow-objects.js.map +2 -2
  122. package/src/shadow-objects.worker.js +0 -1
  123. package/src/shadow-objects.worker.js.map +2 -2
  124. package/src/shae-ent.js.map +1 -1
  125. package/src/shae-prop.js +2 -2
  126. package/src/shae-prop.js.map +2 -2
  127. package/src/shae-worker.js.map +1 -1
  128. package/src/types.d.ts +39 -8
  129. package/src/types.d.ts.map +1 -1
  130. package/src/utils/ConsoleLogger.d.ts +45 -10
  131. package/src/utils/ConsoleLogger.d.ts.map +1 -1
  132. package/src/utils/ConsoleLogger.js +54 -28
  133. package/src/utils/ConsoleLogger.js.map +2 -2
  134. package/src/utils/FrameLoop.d.ts +42 -3
  135. package/src/utils/FrameLoop.d.ts.map +1 -1
  136. package/src/utils/FrameLoop.js +71 -12
  137. package/src/utils/FrameLoop.js.map +2 -2
  138. package/src/utils/MicrotaskCollector.d.ts +45 -0
  139. package/src/utils/MicrotaskCollector.d.ts.map +1 -0
  140. package/src/utils/MicrotaskCollector.js +33 -0
  141. package/src/utils/MicrotaskCollector.js.map +7 -0
  142. package/src/utils/MicrotaskGate.d.ts +17 -0
  143. package/src/utils/MicrotaskGate.d.ts.map +1 -0
  144. package/src/utils/MicrotaskGate.js +20 -0
  145. package/src/utils/MicrotaskGate.js.map +7 -0
  146. package/src/utils/array-utils.js.map +1 -1
  147. package/src/utils/attr-utils.d.ts +6 -0
  148. package/src/utils/attr-utils.d.ts.map +1 -1
  149. package/src/utils/attr-utils.js +4 -2
  150. package/src/utils/attr-utils.js.map +2 -2
  151. package/src/utils/constants.js.map +1 -1
  152. package/src/utils/generateUUID.d.ts +12 -1
  153. package/src/utils/generateUUID.d.ts.map +1 -1
  154. package/src/utils/generateUUID.js +31 -266
  155. package/src/utils/generateUUID.js.map +2 -2
  156. package/src/utils/props-utils.d.ts +3 -2
  157. package/src/utils/props-utils.d.ts.map +1 -1
  158. package/src/utils/props-utils.js +13 -24
  159. package/src/utils/props-utils.js.map +2 -2
  160. package/src/utils/runGuarded.d.ts +27 -0
  161. package/src/utils/runGuarded.d.ts.map +1 -0
  162. package/src/utils/runGuarded.js +11 -0
  163. package/src/utils/runGuarded.js.map +7 -0
  164. package/src/utils/toMaybe.d.ts.map +1 -1
  165. package/src/utils/toMaybe.js.map +1 -1
  166. package/src/utils/toNamespace.d.ts.map +1 -1
  167. package/src/utils/toNamespace.js.map +1 -1
  168. package/src/utils/toUrlString.d.ts +12 -0
  169. package/src/utils/toUrlString.d.ts.map +1 -1
  170. package/src/utils/toUrlString.js.map +2 -2
  171. package/src/utils/waitForMessageOfType.d.ts +16 -1
  172. package/src/utils/waitForMessageOfType.d.ts.map +1 -1
  173. package/src/utils/waitForMessageOfType.js +28 -3
  174. package/src/utils/waitForMessageOfType.js.map +2 -2
  175. package/src/view/ComponentChanges.d.ts +91 -1
  176. package/src/view/ComponentChanges.d.ts.map +1 -1
  177. package/src/view/ComponentChanges.js +253 -69
  178. package/src/view/ComponentChanges.js.map +2 -2
  179. package/src/view/ComponentContext.d.ts +239 -7
  180. package/src/view/ComponentContext.d.ts.map +1 -1
  181. package/src/view/ComponentContext.js +648 -115
  182. package/src/view/ComponentContext.js.map +2 -2
  183. package/src/view/ComponentMemory.d.ts +3 -3
  184. package/src/view/ComponentMemory.d.ts.map +1 -1
  185. package/src/view/ComponentMemory.js +3 -1
  186. package/src/view/ComponentMemory.js.map +2 -2
  187. package/src/view/IShadowObjectEnvProxy.d.ts +33 -1
  188. package/src/view/IShadowObjectEnvProxy.d.ts.map +1 -1
  189. package/src/view/LocalShadowObjectEnv.d.ts +2 -2
  190. package/src/view/LocalShadowObjectEnv.d.ts.map +1 -1
  191. package/src/view/LocalShadowObjectEnv.js +18 -11
  192. package/src/view/LocalShadowObjectEnv.js.map +2 -2
  193. package/src/view/RemoteWorkerEnv.d.ts +129 -3
  194. package/src/view/RemoteWorkerEnv.d.ts.map +1 -1
  195. package/src/view/RemoteWorkerEnv.js +290 -60
  196. package/src/view/RemoteWorkerEnv.js.map +2 -2
  197. package/src/view/ShadowEnv.d.ts +73 -2
  198. package/src/view/ShadowEnv.d.ts.map +1 -1
  199. package/src/view/ShadowEnv.js +301 -64
  200. package/src/view/ShadowEnv.js.map +2 -2
  201. package/src/view/ViewComponent.d.ts +93 -8
  202. package/src/view/ViewComponent.d.ts.map +1 -1
  203. package/src/view/ViewComponent.js +148 -28
  204. package/src/view/ViewComponent.js.map +2 -2
  205. package/src/view/cloneChangeTrail.js.map +2 -2
  206. package/src/worker/MessageRouter.d.ts +14 -0
  207. package/src/worker/MessageRouter.d.ts.map +1 -1
  208. package/src/worker/MessageRouter.js +80 -18
  209. package/src/worker/MessageRouter.js.map +2 -2
  210. package/src/worker/WorkerRuntime.d.ts +22 -1
  211. package/src/worker/WorkerRuntime.d.ts.map +1 -1
  212. package/src/worker/WorkerRuntime.js +60 -8
  213. package/src/worker/WorkerRuntime.js.map +2 -2
@@ -1,7 +1,24 @@
1
1
  import type { ChangeTrailType, NamespaceType } from '../types.js';
2
+ import { type ComponentState } from './ComponentMemory.js';
2
3
  import type { ViewComponent } from './ViewComponent.js';
3
4
  declare global {
4
- var __shadowEntsContexts: Map<string | symbol, ComponentContext> | undefined;
5
+ var __shadowObjectsContexts: Map<string | symbol, ComponentContext> | undefined;
6
+ }
7
+ /**
8
+ * Thrown when a {@link ViewComponent} tries to join a {@link ComponentContext} that has
9
+ * already been disposed.
10
+ */
11
+ export declare class ComponentContextDisposedError extends Error {
12
+ constructor(message?: string);
13
+ }
14
+ /**
15
+ * Thrown when a {@link ViewComponent} tries to join a {@link ComponentContext} under a uuid
16
+ * another component of that {@link ComponentContext} is holding. A uuid names one component at a
17
+ * time; it becomes free again once its holder has left.
18
+ */
19
+ export declare class ComponentUuidInUseError extends Error {
20
+ readonly uuid: string;
21
+ constructor(uuid: string);
5
22
  }
6
23
  /**
7
24
  * The {@link ComponentContext} represents the current real-time state of the _view components_.
@@ -19,29 +36,127 @@ declare global {
19
36
  *
20
37
  * A context is always associated with a namespace.
21
38
  * If no namespace is specified when creating a {@link ComponentContext}, the global namespace is used.
22
- * There is only one {@link ComponentContext} (a singleton) for each namespace.
39
+ * There is only one {@link ComponentContext} instance per namespace: the constructor returns the
40
+ * existing instance for an already-occupied namespace rather than building a second one, so
41
+ * {@link ComponentContext.get} is the way consumers are meant to reach it.
23
42
  */
24
43
  export declare class ComponentContext {
25
44
  #private;
26
45
  static readonly ReRequestParentRoots = "re-request-parent-roots";
46
+ static readonly ReRequestParent = "re-request-parent";
47
+ /**
48
+ * Ask the element behind a component to let the properties hanging on it look for their host
49
+ * again.
50
+ *
51
+ * A context knows nothing about `<shae-prop>` — a property has no view component and cannot be
52
+ * addressed here. The signal still belongs next to the two above: it travels the same broadcast
53
+ * channel to the same receivers, and the element on the other end is the one that can reach the
54
+ * properties below it.
55
+ */
56
+ static readonly ReRequestEntHost = "re-request-ent-host";
27
57
  static getContextsMap(): Map<NamespaceType, ComponentContext>;
28
58
  static get(namespace?: NamespaceType): ComponentContext;
29
59
  ns?: NamespaceType;
30
60
  constructor(namespace?: NamespaceType);
61
+ /**
62
+ * Whether this context has been torn down by {@link ComponentContext.dispose}.
63
+ *
64
+ * A disposed context holds no components, produces empty change trails and no longer
65
+ * occupies its namespace. It cannot be revived; use {@link ComponentContext.get} to
66
+ * obtain a fresh context for the same namespace.
67
+ */
68
+ get isDisposed(): boolean;
69
+ /**
70
+ * Take a component in: it becomes a member of this {@link ComponentContext} and a
71
+ * `CreateEntities` change is written for its uuid.
72
+ *
73
+ * Called by the {@link ViewComponent#context} setter, and by nothing else.
74
+ *
75
+ * @throws {ComponentContextDisposedError} if this {@link ComponentContext} has been disposed
76
+ * @throws {ComponentUuidInUseError} if another member of this {@link ComponentContext} holds
77
+ * `component.uuid`
78
+ */
31
79
  addComponent(component: ViewComponent): void;
80
+ /**
81
+ * Whether `component` is a member of this {@link ComponentContext} right now.
82
+ *
83
+ * This is the question about the instance, and the only one this class answers about
84
+ * membership. A component that has left gets `false`, even while its entry is still standing —
85
+ * {@link ComponentContext.hasComponents} is what counts entries.
86
+ */
32
87
  hasComponent(component: ViewComponent): boolean;
33
88
  hasComponents(): boolean;
34
89
  isRootComponent(component: ViewComponent): boolean;
35
90
  destroyComponent(component: ViewComponent): void;
91
+ /**
92
+ * The children of `component`, in sort order — a fresh array each call, and an empty one for
93
+ * an instance that does not own its entry.
94
+ *
95
+ * Uuids without a matching view instance are skipped instead of dereferenced: `addToChildren()`
96
+ * writes a uuid into a children list without the parent link of the child following along, so
97
+ * `#deleteComponent()` has no list to take that uuid out of and the entry behind it goes while
98
+ * the list keeps naming it. `#appendToOrdered()` and `#traverseLevelOrderBFS()` read a children
99
+ * list the same way.
100
+ */
36
101
  getChildren(component: ViewComponent): ViewComponent[];
37
- removeFromParent(childUuid: string, parent: ViewComponent): void;
38
- moveToRoot(childUuid: string): void;
102
+ removeFromParent(component: ViewComponent, parent: ViewComponent): void;
103
+ moveToRoot(component: ViewComponent): void;
39
104
  changeToken(component: ViewComponent, token?: string): void;
40
105
  isChildOf(child: ViewComponent, parent: ViewComponent): boolean;
41
106
  addToChildren(parent: ViewComponent, child: ViewComponent): void;
107
+ /**
108
+ * Destroy a component and all its descendants without writing anything to a change trail.
109
+ * Each of them is detached from this context and reports {@link ViewComponent#isDestroyed}.
110
+ *
111
+ * @see {@link ComponentContext.clear}
112
+ */
42
113
  removeSubTree(uuid: string): void;
43
- setProperty<T = unknown>(component: ViewComponent, propKey: string, value: T, isEqual?: (a: T, b: T) => boolean): false | void;
114
+ /**
115
+ * @returns `true` if the value differs from the last value written to a change trail
116
+ */
117
+ setProperty<T = unknown>(component: ViewComponent, propKey: string, value: T, isEqual?: (a: T, b: T) => boolean): boolean;
118
+ /**
119
+ * Mark `propKey` on `component` as set without giving it a value: the change trail carries
120
+ * an entry that names only the key, and the entity behind it reads the property as
121
+ * `undefined` with the key in place. {@link ComponentContext.setProperty} with `undefined`
122
+ * is the other thing — a removal.
123
+ *
124
+ * An equality rule registered for the key is forgotten, the way it is for a
125
+ * {@link ComponentContext.setProperty} that comes without one: there is no value here for a
126
+ * rule to compare.
127
+ *
128
+ * @returns `true` when this differs from the last value written to a change trail, and
129
+ * `false` for an instance that does not own its entry
130
+ */
131
+ setPropertyWithoutValue(component: ViewComponent, propKey: string): boolean;
44
132
  removeProperty(component: ViewComponent, propKey: string): void;
133
+ /**
134
+ * Hand the properties of `component` over to the context it has just joined.
135
+ *
136
+ * Called by the {@link ViewComponent#context} setter, and by nothing else. It reads the state
137
+ * this context still holds for the component: leaving a context destroys it, but the entry
138
+ * survives until the next {@link ComponentContext.buildChangeTrails}, so the properties are
139
+ * still there to be read once the join has happened.
140
+ *
141
+ * The equality function travels with each property, because it is a rule about the key and not
142
+ * about the value — the same key means the same notion of "unchanged" wherever it lives. It does
143
+ * not get to decide about the arrival, though: the target holds nothing for the key yet, so it
144
+ * would be asked whether the value equals `undefined`, and a function that says yes would drop
145
+ * the property instead of carrying it over. The value is therefore written first and the rule
146
+ * registered after it — the other way round, the write would delete the entry it just made,
147
+ * because {@link ComponentContext.setProperty} keeps only what its caller passes.
148
+ *
149
+ * What the registered rule is for: {@link ComponentContext.reCreateChanges} is its one reader,
150
+ * and it compares with it when it rebuilds a component from the memory. A later
151
+ * {@link ComponentContext.setProperty} does not consult it — it uses its own argument, or none.
152
+ *
153
+ * A property that is set without a value goes over as one: handing it on as the value
154
+ * `undefined` would have the target read it as a removal, and the key would not arrive.
155
+ *
156
+ * Built like {@link ComponentChanges.transferEventsTo}, with one difference: the properties are
157
+ * copied, not moved. What stays behind goes down with the entity in this context.
158
+ */
159
+ transferPropertiesTo(component: ViewComponent, target: ComponentContext): void;
45
160
  changeOrder(component: ViewComponent): void;
46
161
  /**
47
162
  * @returns all view-components in breadth-first order
@@ -60,23 +175,140 @@ export declare class ComponentContext {
60
175
  */
61
176
  dispatchMessage(uuid: string, type: string, data?: unknown, traverseChildren?: boolean): void;
62
177
  /**
63
- * Inform all root components that they should re-request their parents
178
+ * Inform all root components that they should re-request their parents.
179
+ *
180
+ * Every root is asked, because there is nothing here to ask about: the message carries no
181
+ * sender, so this side cannot narrow the set down at all. The receiver is the one that can:
182
+ * it re-asks the element tree, and whoever answers first wins.
183
+ *
184
+ * Delivery is immediate: the round is over by the time the call returns. Two paths inside the
185
+ * library end here — {@link ComponentContext.dispatchReRequestParentSiblings} for a component
186
+ * without a parent, whose candidate set is the roots, and the delivery of a collected round for
187
+ * that same set. What does not come this way is an entity that has just arrived: it hands its
188
+ * round to the collector below. The method is public because running a round at a moment of
189
+ * one's own choosing is what it is for.
64
190
  */
65
191
  dispatchReRequestParentRoots(): void;
192
+ /**
193
+ * Inform the children of `component` that they should re-request their parents.
194
+ *
195
+ * The receivers are the components hanging on `component` right now, and every one of them has
196
+ * to let go: the message carries no sender and needs no filter, because there is nothing here to
197
+ * decide. {@link ComponentContext.ReRequestParentRoots} is the signal for it — it means "drop
198
+ * your parent and ask again", which is what the roots happen to be asked for most often, not
199
+ * what it says.
200
+ */
201
+ dispatchReRequestParentChildren(component: ViewComponent): void;
202
+ /**
203
+ * Inform the siblings of `component` that they should re-request their parents.
204
+ *
205
+ * This narrows the candidate set for one specific question: which components could have bound
206
+ * to an ancestor further away than they should have, because `component` was not yet answering
207
+ * when they asked? Such a component sits below `component` in the element tree and shares its
208
+ * parent — any entity in between would have answered first. As long as `component` has no
209
+ * parent of its own, the roots are that same set.
210
+ *
211
+ * The signal alone does not decide anything: the receiver re-asks, and whoever answers first
212
+ * wins. Which components exist as candidates is what this method knows; whether one of them
213
+ * really sits below `component` is settled on the receiving side, which is where the element
214
+ * tree is visible — `data` is what carries the sender's identity there.
215
+ *
216
+ * The two signals differ in the order they work in, and that decides more than it looks like:
217
+ * {@link ComponentContext.ReRequestParentRoots} releases the parent before asking, so a
218
+ * component that gets the same answer back re-joins its parent's children at the end;
219
+ * {@link ComponentContext.ReRequestParent} asks first and releases only where nobody answers,
220
+ * which leaves every component that is already bound where it stands, order included.
221
+ *
222
+ * Delivery is immediate, and nothing inside the library calls it: like
223
+ * {@link ComponentContext.dispatchReRequestParentRoots} it is public so that a round can be run
224
+ * at a moment of one's own choosing.
225
+ */
226
+ dispatchReRequestParentSiblings(component: ViewComponent, data?: unknown): void;
66
227
  /**
67
228
  * Create the component change trails at this point in time.
68
229
  * The next call will only return the differences from the previous call.
69
230
  *
231
+ * @param commit whether the trail counts as applied the moment it is built. Pass `false` when
232
+ * the trail still has to travel to a Shadow Environment that may refuse it, and settle it
233
+ * afterwards with {@link ComponentContext.commitChangeTrail}.
234
+ *
235
+ * @see {@link ComponentContext.commitChangeTrail}
70
236
  * @see {@link ComponentContext.reCreateChanges}
71
237
  */
72
- buildChangeTrails(clearChanges?: boolean): ChangeTrailType;
238
+ buildChangeTrails(commit?: boolean): ChangeTrailType;
239
+ /**
240
+ * Fold the first `appliedCount` entries of the change trail this context built last into the
241
+ * state the next trail is diffed against, and write them to the Component Memory. Every entry
242
+ * behind that line stays pending and goes out again with the next trail.
243
+ *
244
+ * A component is retired -- its entry dropped -- only where the build read it as spent and every
245
+ * entry it contributed is settled. One component can hold a creation and an event in the same
246
+ * trail, and a creation sent twice is refused by the Shadow Environment, which already holds an
247
+ * entity behind that uuid.
248
+ *
249
+ * @param appliedCount how many entries the Shadow Environment applied, counted from the front.
250
+ * Clamped to the length of the trail.
251
+ * @param changeTrail the trail this call settles. Given, the call is ignored unless it is the
252
+ * very trail this context built last -- a cycle that lost its trail to a later build must not
253
+ * draw a line through that later trail.
254
+ */
255
+ commitChangeTrail(appliedCount: number, changeTrail?: ChangeTrailType): void;
256
+ /**
257
+ * Whether the Component Memory holds a state for `uuid` — the state
258
+ * {@link ComponentContext.reCreateChanges} would rebuild that component from.
259
+ */
260
+ hasComponentState(uuid: string): boolean;
261
+ /**
262
+ * The state the Component Memory holds for `uuid`, or `undefined` where it holds none.
263
+ *
264
+ * A snapshot, not the record: the property list of the record is rewritten in place as
265
+ * trails come in, so a caller holding on to it would be reading a moving value — or
266
+ * writing one. What it is a snapshot of is the memory at the moment of the call, and the
267
+ * memory moves under several hands: {@link ComponentContext.commitChangeTrail} folds a
268
+ * settled trail into it, {@link ComponentContext.buildChangeTrails} does the same for the
269
+ * trail it builds unless it is told not to commit, {@link ComponentContext.reCreateChanges}
270
+ * writes the trail it builds and empties the memory afterwards, and
271
+ * {@link ComponentContext.clear} empties it outright. A snapshot taken before any of those
272
+ * describes a state that is over; take it again to see the current one.
273
+ *
274
+ * This is the window a test or a diagnosis needs, and the one that leaves the context as it
275
+ * found it — reading the same thing out of {@link ComponentContext.reCreateChanges} costs a
276
+ * rebuild of every component in the namespace.
277
+ */
278
+ getComponentState(uuid: string): ComponentState | undefined;
73
279
  /**
74
280
  * Resets the internal component change states so that all view components are regenerated with the next change trail.
75
281
  * The outstanding events are taken over.
76
282
  *
283
+ * The trail this produces belongs to a Shadow Environment that holds none of these uuids -- a
284
+ * fresh proxy. One whose Kernel still holds them refuses the first re-created creation it reads,
285
+ * and every cycle that follows, because a uuid names one entity at a time.
286
+ *
77
287
  * @see {@link ComponentContext.buildChangeTrails}
78
288
  */
79
289
  reCreateChanges(): void;
290
+ /**
291
+ * Remove all components without writing anything to a change trail. Every
292
+ * {@link ViewComponent} this context holds is destroyed, so each of them reports
293
+ * {@link ViewComponent#isDestroyed} and holds no context afterwards. The context itself stays
294
+ * registered under its namespace and can be used again — assigning it to a component takes
295
+ * that component back in under the same uuid.
296
+ *
297
+ * @see {@link ComponentContext.dispose} for the final teardown
298
+ */
80
299
  clear(): void;
300
+ /**
301
+ * Tear the context down for good: every {@link ViewComponent} it holds is destroyed, the
302
+ * component memory is dropped, and the namespace is released so that
303
+ * {@link ComponentContext.get} creates a fresh context for it.
304
+ *
305
+ * Unlike {@link ComponentContext.clear} this is final. The context holds no components,
306
+ * produces empty change trails, and rejects any component that tries to join it. Calling
307
+ * it more than once is a no-op.
308
+ *
309
+ * A `ShadowEnv` bound to this context keeps its reference; destroy the environment
310
+ * first if you want the namespace released on both sides.
311
+ */
312
+ dispose(): void;
81
313
  }
82
314
  //# sourceMappingURL=ComponentContext.d.ts.map
@@ -1 +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,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;gBAOP,SAAS,GAAE,aAAwB;IAU/C,YAAY,CAAC,SAAS,EAAE,aAAa;IAkCrC,YAAY,CAAC,SAAS,EAAE,aAAa;IAIrC,aAAa;IAIb,eAAe,CAAC,SAAS,EAAE,aAAa;IAIxC,gBAAgB,CAAC,SAAS,EAAE,aAAa;IASzC,WAAW,CAAC,SAAS,EAAE,aAAa,GAAG,aAAa,EAAE;IAItD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa;IAczD,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,aAAa,CAAC,IAAI,EAAE,MAAM;IAS1B,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;IAc/G,cAAc,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;IAIxD,WAAW,CAAC,SAAS,EAAE,aAAa;IAapC;;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,KAAK;CA2GN"}
1
+ {"version":3,"file":"ComponentContext.d.ts","sourceRoot":"","sources":["../../../src/view/ComponentContext.ts"],"names":[],"mappings":"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"}