@jam-overture/loom 0.2.0 → 0.3.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 (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -159,20 +159,179 @@ const channel = (value) => {
159
159
  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
160
160
  };
161
161
  /**
162
- * The colour as three 0–255 channels, or nothing when it is a form this cannot
163
- * measure.
162
+ * The alpha at which a colour composites to exactly itself.
164
163
  *
165
- * `colourSchema` accepts more than hex — `rgb()`, `hsl()`, a named colour, and
166
- * eight-digit hex with an alpha. Only three- and six-digit hex are measured
167
- * here, and the rest answer `undefined` rather than a guess:
164
+ * The whole of what an alpha costs this module: at `1` there is nothing behind
165
+ * the colour to mix in, so the pair's contrast is a property of the pair. Below
166
+ * it, it is not, and no parser can recover what was never stated.
167
+ */
168
+ const OPAQUE = 1;
169
+ /** The one set of colour functions `colourSchema` admits. */
170
+ const COLOUR_CALL = /^(rgba?|hsla?)\(([^()]*)\)$/i;
171
+ /** A CSS `<number>`, or nothing. Rejects `none`, `1px` and the empty string. */
172
+ const numberOf = (text) => {
173
+ if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(text))
174
+ return undefined;
175
+ const value = Number(text);
176
+ return Number.isFinite(value) ? value : undefined;
177
+ };
178
+ /** A CSS `<percentage>` as its own number, so `50%` is `50`. */
179
+ const percentageOf = (text) => text.endsWith("%") ? numberOf(text.slice(0, -1)) : undefined;
180
+ const clampTo = (high, value) => Math.min(high, Math.max(0, value));
181
+ /**
182
+ * How much of a degree each `<angle>` unit is worth.
168
183
  *
169
- * - a named colour needs the CSS colour table, which is 148 entries of vocabulary
170
- * this module would then own
171
- * - `hsl()` and modern `rgb()` syntax are a parser, and a parser that is subtly
172
- * wrong reports a passing ratio for a failing pair, which is worse than
173
- * reporting nothing
174
- * - an alpha composites against whatever is behind it, so its contrast is not a
175
- * property of the two slots at all
184
+ * All four of CSS's units rather than `deg` alone: a host writing `turn` is
185
+ * writing legal CSS that a browser paints correctly, and a measurement that
186
+ * declined it would be declining arithmetic it has in front of it.
187
+ */
188
+ const DEGREES_PER_UNIT = {
189
+ deg: 1,
190
+ grad: 360 / 400,
191
+ rad: 180 / Math.PI,
192
+ turn: 360,
193
+ };
194
+ const ANGLE = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(deg|grad|rad|turn)?$/i;
195
+ /** A hue in degrees, unwrapped. A bare number is degrees, as CSS says. */
196
+ const degreesOf = (text) => {
197
+ const angle = ANGLE.exec(text);
198
+ if (angle === null)
199
+ return undefined;
200
+ const [, value = "", unit] = angle;
201
+ const magnitude = numberOf(value);
202
+ const perUnit = unit === undefined ? 1 : DEGREES_PER_UNIT[unit.toLowerCase()];
203
+ return magnitude === undefined || perUnit === undefined ? undefined : magnitude * perUnit;
204
+ };
205
+ /**
206
+ * The alpha a colour carries, as 0–1. Absent is `1`; unreadable is `undefined`.
207
+ *
208
+ * The two outcomes are kept apart deliberately. An absent alpha is an opaque
209
+ * colour and measurable; an alpha nobody can parse means the string is not the
210
+ * colour it appears to be, and guessing it opaque would measure a colour the
211
+ * host did not write.
212
+ */
213
+ const alphaOf = (text) => {
214
+ if (text === undefined)
215
+ return OPAQUE;
216
+ const percentage = percentageOf(text);
217
+ if (percentage !== undefined)
218
+ return clampTo(1, percentage / 100);
219
+ const number = numberOf(text);
220
+ return number === undefined ? undefined : clampTo(1, number);
221
+ };
222
+ /**
223
+ * The arguments of `rgb()` or `hsl()`, in either syntax CSS publishes.
224
+ *
225
+ * Commas are the legacy form and take their alpha as a fourth argument; spaces
226
+ * are the modern form and take it after a solidus. The two are not mixable, and
227
+ * a string that mixes them is refused rather than half-read — `rgb(1, 2 3)` is
228
+ * not a colour, and the one thing worse than declining it is averaging it.
229
+ *
230
+ * **Nothing here checks for the mix**, and a planted mutation is why the check
231
+ * is not here: a comma-split part carrying a space fails `numberOf` and
232
+ * `percentageOf` downstream anyway, so a guard against it changed no outcome on
233
+ * any input. Chromium refuses the same strings, which is how each one is known
234
+ * to be refused rather than assumed.
235
+ */
236
+ const argumentsOf = (body) => {
237
+ const trimmed = body.trim();
238
+ if (trimmed === "")
239
+ return undefined;
240
+ if (trimmed.includes(",")) {
241
+ if (trimmed.includes("/"))
242
+ return undefined;
243
+ const parts = trimmed.split(",").map((part) => part.trim());
244
+ if (parts.length === 3)
245
+ return { components: parts, alpha: undefined };
246
+ return parts.length === 4 ? { components: parts.slice(0, 3), alpha: parts[3] } : undefined;
247
+ }
248
+ const [stated = "", alpha, ...extra] = trimmed.split("/").map((part) => part.trim());
249
+ if (extra.length > 0 || alpha === "")
250
+ return undefined;
251
+ const components = stated.split(/\s+/);
252
+ return components.length === 3 ? { components, alpha } : undefined;
253
+ };
254
+ /** One `rgb()` component: a number out of 255, or a percentage of it. */
255
+ const rgbChannel = (text) => {
256
+ const percentage = percentageOf(text);
257
+ if (percentage !== undefined)
258
+ return clampTo(255, (percentage / 100) * 255);
259
+ const number = numberOf(text);
260
+ return number === undefined ? undefined : clampTo(255, number);
261
+ };
262
+ const rgbChannelsOf = (components) => {
263
+ const [r, g, b] = components.map(rgbChannel);
264
+ return r === undefined || g === undefined || b === undefined ? undefined : [r, g, b];
265
+ };
266
+ /**
267
+ * `hsl()` to sRGB, by CSS Color 4's own reference arithmetic.
268
+ *
269
+ * Written as the specification writes it rather than as the shorter form with
270
+ * two branches, because this is the function the 20 August argument against
271
+ * reading `hsl()` was about — *a parser that is subtly wrong reports a passing
272
+ * ratio for a failing pair* — and a reader checking that claim should be able to
273
+ * lay this beside the specification line for line.
274
+ */
275
+ const hslChannelsOf = (components) => {
276
+ const [hue = "", saturation = "", lightness = ""] = components;
277
+ const degrees = degreesOf(hue);
278
+ const s = percentageOf(saturation) ?? numberOf(saturation);
279
+ const l = percentageOf(lightness) ?? numberOf(lightness);
280
+ if (degrees === undefined || s === undefined || l === undefined)
281
+ return undefined;
282
+ const h = ((degrees % 360) + 360) % 360;
283
+ const saturated = clampTo(1, s / 100);
284
+ const light = clampTo(1, l / 100);
285
+ const amount = saturated * Math.min(light, 1 - light);
286
+ const channelAt = (offset) => {
287
+ const k = (offset + h / 30) % 12;
288
+ return (light - amount * Math.max(-1, Math.min(k - 3, 9 - k, 1))) * 255;
289
+ };
290
+ return [channelAt(0), channelAt(8), channelAt(4)];
291
+ };
292
+ /**
293
+ * Hex of three, four, six or eight digits, declining an alpha below opaque.
294
+ *
295
+ * Five and seven digits are refused. `colourSchema`'s pattern admits them —
296
+ * `#[0-9a-fA-F]{3,8}` — and no browser does, so a palette carrying one is a
297
+ * typo that renders as nothing and must not be measured as though it rendered.
298
+ */
299
+ const hexChannelsOf = (colour) => {
300
+ const digits = /^#([0-9a-fA-F]+)$/.exec(colour)?.[1];
301
+ if (digits === undefined)
302
+ return undefined;
303
+ const pairs = digits.length === 3 || digits.length === 4
304
+ ? [...digits].map((digit) => `${digit}${digit}`)
305
+ : digits.length === 6 || digits.length === 8
306
+ ? Array.from({ length: digits.length / 2 }, (_, at) => digits.slice(at * 2, at * 2 + 2))
307
+ : undefined;
308
+ if (pairs === undefined)
309
+ return undefined;
310
+ const [r, g, b, alpha] = pairs.map((pair) => Number.parseInt(pair, 16));
311
+ if (r === undefined || g === undefined || b === undefined)
312
+ return undefined;
313
+ return alpha !== undefined && alpha !== 255 ? undefined : [r, g, b];
314
+ };
315
+ /**
316
+ * A colour's three 0–255 channels, unrounded, or nothing when the form cannot
317
+ * be measured.
318
+ *
319
+ * `colourSchema` accepts four shapes: hex of three to eight digits, `rgb()`,
320
+ * `hsl()`, and a bare word naming a CSS colour. Of those, **every form whose
321
+ * channels are arithmetic is read here**, and two are declined (0365):
322
+ *
323
+ * - **a named colour is vocabulary, not arithmetic.** It needs the CSS colour
324
+ * table — 148 entries this module would then own and keep — and no amount of
325
+ * care with the other forms supplies it.
326
+ * - **an alpha below 1 composites against whatever is behind it**, so its
327
+ * contrast is not a property of the two slots at all. A *fully opaque* alpha
328
+ * is a different case and is read: `#111827ff` composites to exactly
329
+ * `#111827`, so declining it reported nothing about a colour that was never
330
+ * in doubt.
331
+ *
332
+ * Channels are left unrounded. A browser quantises `hsl()` to eight bits per
333
+ * channel on its way into a pixel; nothing here draws anything, so rounding to
334
+ * match it would discard precision to imitate a step this never takes.
176
335
  *
177
336
  * Answering "I could not measure this" is the same move `not-probeable` makes in
178
337
  * the conformance probe: a check that cannot answer says so, rather than passing.
@@ -182,12 +341,17 @@ const channel = (value) => {
182
341
  * parsers would be two answers to "is this measurable".
183
342
  */
184
343
  export const channelsOf = (colour) => {
185
- const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(colour)?.[1];
186
- if (hex === undefined)
344
+ const call = COLOUR_CALL.exec(colour.trim());
345
+ if (call === null)
346
+ return hexChannelsOf(colour.trim());
347
+ const [, name = "", body = ""] = call;
348
+ const parts = argumentsOf(body);
349
+ if (parts === undefined)
187
350
  return undefined;
188
- const pairs = hex.length === 3 ? [...hex].map((digit) => `${digit}${digit}`) : [0, 2, 4].map((at) => hex.slice(at, at + 2));
189
- const [r, g, b] = pairs.map((pair) => Number.parseInt(pair, 16));
190
- return r === undefined || g === undefined || b === undefined ? undefined : [r, g, b];
351
+ const alpha = alphaOf(parts.alpha);
352
+ if (alpha === undefined || alpha < OPAQUE)
353
+ return undefined;
354
+ return name.toLowerCase().startsWith("rgb") ? rgbChannelsOf(parts.components) : hslChannelsOf(parts.components);
191
355
  };
192
356
  const luminance = ([r, g, b]) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
193
357
  /**
@@ -5,6 +5,19 @@ import { detachNode, insertChild, replaceNode } from "./mutation.js";
5
5
  import { collectNodeIds, duplicateNodeIds, isDescendantOf, walkTree } from "./navigation.js";
6
6
  import { withRoot } from "./tree.js";
7
7
  const withRetired = (applied, retired) => mapResult(applied, (root) => ({ root, retired }));
8
+ /**
9
+ * **This is where the only structural invariant a tree has is enforced, and
10
+ * that it is the only one is the part worth writing down.**
11
+ * `validateTreeInvariants` checks unique ids and nothing else, so anything that
12
+ * composes operations from two sources — a composition per audience (0359,
13
+ * 0376), a merge of two proposals, anything that replays two logs — does not
14
+ * need a defensive check over what it produced: the second `insert` of an id
15
+ * the tree already holds fails here, long before there is a tree to invalidate.
16
+ *
17
+ * Written here because a run that reaches for that check reaches for it out of a
18
+ * fear this answers, and the answer took a planted mutation to settle. The
19
+ * fear, and the removal, are recorded in `audience/compose.ts`.
20
+ */
8
21
  const rejectIdCollisions = (root, incoming) => {
9
22
  const [internalDuplicate] = duplicateNodeIds(incoming);
10
23
  if (internalDuplicate)
@@ -6,8 +6,26 @@ import { type LoomNode } from "./node.js";
6
6
  * Structural edits on an immutable tree. Each returns a new root; nodes off the
7
7
  * edited path keep their identity, so a renderer can rely on reference equality
8
8
  * to skip untouched subtrees.
9
+ *
10
+ * **Nothing here recurses into the tree, and nothing rebuilds a list of
11
+ * children one child at a time**, for the same reason the reads in
12
+ * `navigation.ts` do not (0372, 0373): a page's shape is data, and an edit that
13
+ * spends a call frame per level or copies the accumulated siblings per sibling
14
+ * stops answering at a shape a page is allowed to have.
9
15
  */
10
16
  export type NodeTransform = (node: LoomNode) => Result<LoomNode, TreeError>;
17
+ /**
18
+ * The addressed node, transformed, and every ancestor rebuilt around it.
19
+ *
20
+ * It descends by the **path** rather than by a search. `nodePath` names the
21
+ * chain from the root to the node in one walk, so the rebuild touches one node
22
+ * per level and asks nothing: no `containsNode` per level, no frame per level.
23
+ *
24
+ * Where a tree holds the same id twice — which `duplicateNodeIds` exists to
25
+ * find and no valid tree has — the node this edits is the first in tree order,
26
+ * because that is the one `nodePath` addresses. The search this replaced edited
27
+ * every copy.
28
+ */
11
29
  export declare const replaceNode: (root: LoomNode, nodeId: NodeId, transform: NodeTransform) => Result<LoomNode, TreeError>;
12
30
  export declare const insertChild: (root: LoomNode, parentId: NodeId, index: number, node: LoomNode) => Result<LoomNode, TreeError>;
13
31
  export type DetachedTree = {
@@ -1,21 +1,33 @@
1
- import { err, mapResult, ok, reduceResult } from "../result.js";
2
- import { containsNode, findNode, findParent } from "./navigation.js";
1
+ import { err, flatMapResult, mapResult, ok } from "../result.js";
2
+ import { findNode, findParent, nodePath } from "./navigation.js";
3
3
  import { isContainerNode, withChildren, } from "./node.js";
4
4
  const requireContainer = (node) => isContainerNode(node)
5
5
  ? ok(node)
6
6
  : err({ code: "not-a-container", nodeId: node.id, nodeKind: node.kind });
7
+ /** One child swapped for its rebuilt self, by reference, in one pass. */
8
+ const withChildSwapped = (parent, previous, next) => mapResult(requireContainer(parent), (container) => withChildren(container, container.children.map((child) => (child === previous ? next : child))));
9
+ /**
10
+ * The addressed node, transformed, and every ancestor rebuilt around it.
11
+ *
12
+ * It descends by the **path** rather than by a search. `nodePath` names the
13
+ * chain from the root to the node in one walk, so the rebuild touches one node
14
+ * per level and asks nothing: no `containsNode` per level, no frame per level.
15
+ *
16
+ * Where a tree holds the same id twice — which `duplicateNodeIds` exists to
17
+ * find and no valid tree has — the node this edits is the first in tree order,
18
+ * because that is the one `nodePath` addresses. The search this replaced edited
19
+ * every copy.
20
+ */
7
21
  export const replaceNode = (root, nodeId, transform) => {
8
- if (!containsNode(root, nodeId))
22
+ const path = nodePath(root, nodeId);
23
+ const [target, ...ancestorsNearestFirst] = path ? [...path].reverse() : [];
24
+ if (!target)
9
25
  return err({ code: "node-not-found", nodeId });
10
- const rebuild = (node) => {
11
- if (node.id === nodeId)
12
- return transform(node);
13
- if (!isContainerNode(node) || !containsNode(node, nodeId))
14
- return ok(node);
15
- const rebuiltChildren = reduceResult(node.children, [], (accumulated, child) => mapResult(rebuild(child), (next) => [...accumulated, next]));
16
- return mapResult(rebuiltChildren, (children) => withChildren(node, children));
17
- };
18
- return rebuild(root);
26
+ const rebuilt = ancestorsNearestFirst.reduce((carried, ancestor) => flatMapResult(carried, (below) => mapResult(withChildSwapped(ancestor, below.was, below.now), (next) => ({
27
+ was: ancestor,
28
+ now: next,
29
+ }))), mapResult(transform(target), (now) => ({ was: target, now })));
30
+ return mapResult(rebuilt, (top) => top.now);
19
31
  };
20
32
  export const insertChild = (root, parentId, index, node) => {
21
33
  const parent = findNode(root, parentId);
@@ -4,6 +4,11 @@ import { type LoomNode } from "./node.js";
4
4
  * Read-only traversal. Every function here takes a root and derives a view;
5
5
  * nothing caches, because a cache would be a second source of truth about a
6
6
  * structure that changes on every accepted delta.
7
+ *
8
+ * **Nothing here recurses into the tree**, which is a correctness requirement
9
+ * rather than a preference (0372): a page's depth is data, so a walk that
10
+ * spends a call frame per level stops answering at a depth a tree is allowed to
11
+ * reach. Every walk below carries an explicit stack and is linear in nodes.
7
12
  */
8
13
  export declare function walkTree(root: LoomNode): Generator<LoomNode>;
9
14
  export declare const collectNodeIds: (root: LoomNode) => readonly NodeId[];
@@ -3,11 +3,19 @@ import { childrenOf } from "./node.js";
3
3
  * Read-only traversal. Every function here takes a root and derives a view;
4
4
  * nothing caches, because a cache would be a second source of truth about a
5
5
  * structure that changes on every accepted delta.
6
+ *
7
+ * **Nothing here recurses into the tree**, which is a correctness requirement
8
+ * rather than a preference (0372): a page's depth is data, so a walk that
9
+ * spends a call frame per level stops answering at a depth a tree is allowed to
10
+ * reach. Every walk below carries an explicit stack and is linear in nodes.
6
11
  */
7
12
  export function* walkTree(root) {
8
- yield root;
9
- for (const child of childrenOf(root))
10
- yield* walkTree(child);
13
+ const pending = [root];
14
+ for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
15
+ yield node;
16
+ for (const child of [...childrenOf(node)].reverse())
17
+ pending.push(child);
18
+ }
11
19
  }
12
20
  export const collectNodeIds = (root) => Array.from(walkTree(root), (node) => node.id);
13
21
  export const findNode = (root, nodeId) => {
@@ -25,18 +33,26 @@ export const findParent = (root, nodeId) => {
25
33
  }
26
34
  return null;
27
35
  };
36
+ const chainTo = (descent) => {
37
+ const chain = [];
38
+ for (let step = descent; step !== null; step = step.from) {
39
+ chain.push(step.node);
40
+ }
41
+ return chain.reverse();
42
+ };
28
43
  /**
29
44
  * The chain of nodes from the root down to and including `nodeId`, or null when
30
45
  * the node is absent. Paths are derived on demand and never persisted — the id
31
46
  * is the stable address, the path is the current position.
32
47
  */
33
48
  export const nodePath = (root, nodeId) => {
34
- if (root.id === nodeId)
35
- return [root];
36
- for (const child of childrenOf(root)) {
37
- const childPath = nodePath(child, nodeId);
38
- if (childPath)
39
- return [root, ...childPath];
49
+ const pending = [{ node: root, from: null }];
50
+ for (let descent = pending.pop(); descent !== undefined; descent = pending.pop()) {
51
+ if (descent.node.id === nodeId)
52
+ return chainTo(descent);
53
+ for (const child of [...childrenOf(descent.node)].reverse()) {
54
+ pending.push({ node: child, from: descent });
55
+ }
40
56
  }
41
57
  return null;
42
58
  };
@@ -46,7 +62,13 @@ export const isDescendantOf = (root, ancestorId, nodeId) => {
46
62
  const ancestor = findNode(root, ancestorId);
47
63
  if (!ancestor)
48
64
  return false;
49
- return childrenOf(ancestor).some((child) => child.id === nodeId || isDescendantOf(child, child.id, nodeId));
65
+ const beneath = walkTree(ancestor);
66
+ beneath.next(); // a node is not its own descendant, and the walk yields it first
67
+ for (const node of beneath) {
68
+ if (node.id === nodeId)
69
+ return true;
70
+ }
71
+ return false;
50
72
  };
51
73
  /**
52
74
  * What a node says: every text node under it, in tree order, concatenated.
@@ -13,6 +13,13 @@ import { type LoomNode } from "./node.js";
13
13
  * `index` is the position among the parent's children, which is the same number
14
14
  * an `insert` or a `move` names — an outline row is therefore enough to address
15
15
  * a position, not only a node.
16
+ *
17
+ * The walk carries an **explicit stack** and is not recursive, which is a
18
+ * correctness requirement rather than a preference (0372). A recursive
19
+ * generator delegating with `yield*` passes every value back up through each
20
+ * delegating frame, so a node at depth *d* costs *d*, the walk costs the sum of
21
+ * the depths rather than the number of nodes, and past about two thousand deep
22
+ * it does not return at all.
16
23
  */
17
24
  export type OutlineEntry = {
18
25
  readonly node: LoomNode;
@@ -1,10 +1,14 @@
1
1
  import { childrenOf } from "./node.js";
2
- function* walkOutline(node, depth, parentId, index) {
3
- yield { node, depth, parentId, index };
4
- for (const [childIndex, child] of childrenOf(node).entries()) {
5
- yield* walkOutline(child, depth + 1, node.id, childIndex);
2
+ function* walkOutline(root) {
3
+ const pending = [{ node: root, depth: 0, parentId: null, index: 0 }];
4
+ for (let entry = pending.pop(); entry !== undefined; entry = pending.pop()) {
5
+ yield entry;
6
+ const nested = Array.from(childrenOf(entry.node).entries()).reverse();
7
+ for (const [index, child] of nested) {
8
+ pending.push({ node: child, depth: entry.depth + 1, parentId: entry.node.id, index });
9
+ }
6
10
  }
7
11
  }
8
12
  /** Pre-order, so a row is always preceded by the row it is nested inside. */
9
- export const outlineTree = (root) => Array.from(walkOutline(root, 0, null, 0));
13
+ export const outlineTree = (root) => Array.from(walkOutline(root));
10
14
  //# sourceMappingURL=outline.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jam-overture/loom",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Loom — an AI-powered adaptive UI runtime",
5
5
  "license": "MIT",
6
6
  "author": "jam-overture",
@@ -36,17 +36,17 @@
36
36
  "types": "./dist/interpretation/anthropic.d.ts",
37
37
  "default": "./dist/interpretation/anthropic.js"
38
38
  },
39
+ "./openai-compatible": {
40
+ "types": "./dist/interpretation/openai-compatible.d.ts",
41
+ "default": "./dist/interpretation/openai-compatible.js"
42
+ },
39
43
  "./react": {
40
44
  "types": "./dist/render/index.d.ts",
41
45
  "default": "./dist/render/index.js"
42
46
  },
43
- "./primitives": {
44
- "types": "./dist/primitives/index.d.ts",
45
- "default": "./dist/primitives/index.js"
46
- },
47
- "./primitives/compositions": {
48
- "types": "./dist/primitives/compositions/index.d.ts",
49
- "default": "./dist/primitives/compositions/index.js"
47
+ "./addressed": {
48
+ "types": "./dist/render/addressed.d.ts",
49
+ "default": "./dist/render/addressed.js"
50
50
  },
51
51
  "./sdk": {
52
52
  "types": "./dist/sdk/index.d.ts",
@@ -68,6 +68,10 @@
68
68
  "types": "./dist/store/postgres.d.ts",
69
69
  "default": "./dist/store/postgres.js"
70
70
  },
71
+ "./live": {
72
+ "types": "./dist/live/index.d.ts",
73
+ "default": "./dist/live/index.js"
74
+ },
71
75
  "./signals": {
72
76
  "types": "./dist/signals/index.d.ts",
73
77
  "default": "./dist/signals/index.js"
@@ -100,29 +104,6 @@
100
104
  "bin": {
101
105
  "loom": "./dist/cli/main.js"
102
106
  },
103
- "scripts": {
104
- "loom": "tsx src/cli/main.ts",
105
- "typecheck": "tsc --noEmit",
106
- "test": "vitest run",
107
- "test:watch": "vitest",
108
- "test:coverage": "vitest run --coverage",
109
- "prepare": "git config merge.ours.driver true || true",
110
- "verify": "pnpm build && pnpm typecheck && pnpm test && pnpm findings:check && pnpm reports:check && pnpm --filter @loom/app verify && pnpm prerender:check",
111
- "findings:check": "tsx tools/findings/main.ts",
112
- "build": "tsc -p tsconfig.build.json",
113
- "clean": "rm -rf dist apps/loom/.next",
114
- "decisions:index": "tsx tools/decisions/build-index.ts",
115
- "prerender:check": "tsx tools/prerender/main.ts",
116
- "queue": "tsx tools/queue/main.ts",
117
- "package:primitives": "tsx tools/package/main.ts",
118
- "shoot": "tsx tools/screenshot/shoot.ts",
119
- "specimen": "tsx tools/specimen/main.ts",
120
- "prepack": "pnpm build",
121
- "reports:check": "tsx tools/reports/main.ts",
122
- "reports:shrink": "tsx tools/reports/shrink.ts",
123
- "portal:account": "pnpm --filter @loom/app portal:account",
124
- "signals:key": "pnpm --filter @loom/app signals:key"
125
- },
126
107
  "dependencies": {
127
108
  "zod": "^3.24.1"
128
109
  },
@@ -164,7 +145,6 @@
164
145
  "typescript": "^5.7.3",
165
146
  "vitest": "^3.0.5"
166
147
  },
167
- "packageManager": "pnpm@10.31.0",
168
148
  "types": "./dist/index.d.ts",
169
149
  "files": [
170
150
  "dist",
@@ -172,68 +152,31 @@
172
152
  "!dist/**/*.map"
173
153
  ],
174
154
  "publishConfig": {
175
- "access": "public",
176
- "exports": {
177
- ".": {
178
- "types": "./dist/index.d.ts",
179
- "default": "./dist/index.js"
180
- },
181
- "./anthropic": {
182
- "types": "./dist/interpretation/anthropic.d.ts",
183
- "default": "./dist/interpretation/anthropic.js"
184
- },
185
- "./react": {
186
- "types": "./dist/render/index.d.ts",
187
- "default": "./dist/render/index.js"
188
- },
189
- "./sdk": {
190
- "types": "./dist/sdk/index.d.ts",
191
- "default": "./dist/sdk/index.js"
192
- },
193
- "./cli": {
194
- "types": "./dist/cli/index.d.ts",
195
- "default": "./dist/cli/index.js"
196
- },
197
- "./store": {
198
- "types": "./dist/store/index.d.ts",
199
- "default": "./dist/store/index.js"
200
- },
201
- "./write": {
202
- "types": "./dist/write/index.d.ts",
203
- "default": "./dist/write/index.js"
204
- },
205
- "./postgres": {
206
- "types": "./dist/store/postgres.d.ts",
207
- "default": "./dist/store/postgres.js"
208
- },
209
- "./signals": {
210
- "types": "./dist/signals/index.d.ts",
211
- "default": "./dist/signals/index.js"
212
- },
213
- "./signals/broadcast": {
214
- "types": "./dist/signals/broadcast.d.ts",
215
- "default": "./dist/signals/broadcast.js"
216
- },
217
- "./signals/postgres": {
218
- "types": "./dist/signals/postgres.d.ts",
219
- "default": "./dist/signals/postgres.js"
220
- },
221
- "./telemetry": {
222
- "types": "./dist/telemetry/index.d.ts",
223
- "default": "./dist/telemetry/index.js"
224
- },
225
- "./telemetry/postgres": {
226
- "types": "./dist/telemetry/postgres.d.ts",
227
- "default": "./dist/telemetry/postgres.js"
228
- },
229
- "./testing": {
230
- "types": "./dist/testing/index.d.ts",
231
- "default": "./dist/testing/index.js"
232
- },
233
- "./testing/contracts": {
234
- "types": "./dist/testing/contracts.d.ts",
235
- "default": "./dist/testing/contracts.js"
236
- }
237
- }
155
+ "access": "public"
156
+ },
157
+ "scripts": {
158
+ "loom": "tsx src/cli/main.ts",
159
+ "typecheck": "tsc --noEmit",
160
+ "test": "vitest run",
161
+ "test:watch": "vitest",
162
+ "test:coverage": "vitest run --coverage",
163
+ "verify": "pnpm build && pnpm typecheck && pnpm test && pnpm findings:check && pnpm reports:check && pnpm --filter @loom/app verify && pnpm prerender:check",
164
+ "findings:check": "tsx tools/findings/main.ts",
165
+ "fences": "tsx tools/sources/fences/generate.ts",
166
+ "build": "tsc -p tsconfig.build.json",
167
+ "clean": "rm -rf dist apps/loom/.next",
168
+ "decisions:index": "tsx tools/decisions/build-index.ts",
169
+ "prerender:check": "tsx tools/prerender/main.ts",
170
+ "queue": "tsx tools/queue/main.ts",
171
+ "package:primitives": "tsx tools/package/main.ts",
172
+ "shoot": "tsx tools/screenshot/shoot.ts",
173
+ "weigh": "tsx tools/weigh/main.ts",
174
+ "posted": "tsx tools/posted/main.ts",
175
+ "specimen": "tsx tools/specimen/main.ts",
176
+ "reports:check": "tsx tools/reports/main.ts",
177
+ "reports:shrink": "tsx tools/reports/shrink.ts",
178
+ "portal:account": "pnpm --filter @loom/app portal:account",
179
+ "signals:key": "pnpm --filter @loom/app signals:key",
180
+ "simulate": "pnpm --filter @loom/app simulate"
238
181
  }
239
- }
182
+ }