@jam-overture/loom 0.1.0 → 0.2.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 (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -0,0 +1,255 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ /** Sorted so a split is in the same order whatever order the rows arrived in. */
3
+ const sorted = (audiences) => [...audiences].sort((one, other) => one.localeCompare(other));
4
+ /**
5
+ * The audiences a window names, deduplicated and in a stable order.
6
+ *
7
+ * Rows naming none are not an audience and are not counted as one. A window of
8
+ * them answers `[]`, which is *nothing here says* rather than *one audience* —
9
+ * the distinction `MaybeAudienceScoped` exists for.
10
+ */
11
+ export const audiencesIn = (rows) => {
12
+ const found = new Set();
13
+ for (const row of rows) {
14
+ if (row.audienceId !== undefined)
15
+ found.add(row.audienceId);
16
+ }
17
+ return sorted(found);
18
+ };
19
+ /**
20
+ * Which of the three a window and an asking come to.
21
+ *
22
+ * The census is deduplicated and sorted here, so a caller may hand in the rows
23
+ * of two windows concatenated — a reading of funnel rows is of the populations
24
+ * its own rows name **and** of the populations the page reading it was taken
25
+ * against named, and either alone can be the ambiguous one.
26
+ *
27
+ * An audience asked for always wins, including over a window that names it
28
+ * nowhere: a caller asking for one population and being handed none is holding
29
+ * an empty reading, which is what it asked for and not an ambiguity.
30
+ */
31
+ export const audienceScopeOf = (audiences, asked) => {
32
+ const named = sorted(new Set(audiences));
33
+ if (asked !== undefined)
34
+ return { reading: "one", audienceId: asked, audiences: named };
35
+ if (named.length === 1 && named[0] !== undefined)
36
+ return { reading: "one", audienceId: named[0], audiences: named };
37
+ if (named.length === 0)
38
+ return { reading: "unlabelled", audienceId: null, audiences: [] };
39
+ return { reading: "mixed", audienceId: null, audiences: named };
40
+ };
41
+ /**
42
+ * The scope a reading already recorded, read back off it.
43
+ *
44
+ * What a **second** reading needs: a comparison holding two sides against each
45
+ * other has to know that a side was read as neither population before it can
46
+ * say what moved between them, and a reading that published only its audience
47
+ * and its census leaves that as a subtraction for every caller to make the same
48
+ * way. One of them making it differently is this module's whole subject.
49
+ */
50
+ export const audienceScopeRead = (reading) => audienceScopeOf(reading.audiences, reading.audienceId ?? undefined);
51
+ /**
52
+ * The rows of one audience, and nothing else.
53
+ *
54
+ * A row naming no audience is not in any audience's window. A caller holding
55
+ * such rows is holding something no store produced, and silently folding them
56
+ * into whichever audience was asked for would be this module inventing the
57
+ * fact it exists to keep.
58
+ */
59
+ export const forAudience = (audience, rows) => rows.filter((row) => row.audienceId === audience);
60
+ /**
61
+ * A window a deployment read, split into the populations it actually holds.
62
+ *
63
+ * Exhaustive and lossless: every row is in exactly one window, each window's
64
+ * rows keep the order they arrived in, and the windows themselves are in a
65
+ * stable order so two reads of one store produce the same list. A deployment
66
+ * serving one form of every page gets one window, which is what it has always
67
+ * had.
68
+ */
69
+ export const byAudience = (rows) => {
70
+ const windows = new Map();
71
+ for (const row of rows) {
72
+ const held = windows.get(row.audienceId);
73
+ if (held === undefined)
74
+ windows.set(row.audienceId, [row]);
75
+ else
76
+ held.push(row);
77
+ }
78
+ return sorted(windows.keys()).map((audience) => ({
79
+ audience,
80
+ rows: windows.get(audience) ?? [],
81
+ }));
82
+ };
83
+ /**
84
+ * What makes two readings one page: the tree, the revision and the audience.
85
+ *
86
+ * The one place that decides what a duplicate is. Five readings refuse to count
87
+ * a page twice — the health of a collection, the order over a deployment's
88
+ * pages, and the three censuses of a library — and before this they refused on
89
+ * a tree and a revision, which two audiences of one page share. So a deployment
90
+ * that began serving a second form had that form's reading dropped as a repeat
91
+ * of the first, and the number it was dropped out of went on looking right
92
+ * (0158: a count that has been added cannot be unadded, and one that was never
93
+ * added cannot be noticed).
94
+ *
95
+ * A reading naming no audience keys as itself, so a window of rows that never
96
+ * carried the column behaves exactly as it did.
97
+ */
98
+ export const readingKeyOf = (reading) => `${reading.treeId}\u0000${reading.revision}\u0000${reading.audienceId ?? ""}`;
99
+ /** The form a reading is of, with an absent audience normalised to the `null` it means. */
100
+ export const formOf = (reading) => ({
101
+ treeId: reading.treeId,
102
+ audienceId: reading.audienceId ?? null,
103
+ });
104
+ /**
105
+ * What makes two readings one page in one form, which is what a comparison
106
+ * pairs on.
107
+ *
108
+ * The second of this module's two keys, published for the reason the first is:
109
+ * every comparison in this subsystem decides, in its own loop, whether two
110
+ * readings handed in are one page to be paired or one page handed in twice, and
111
+ * **a tree alone is not that page**. Two forms of it (0263) share a tree, so a
112
+ * comparison keyed by the tree drops the second form as a duplicate where the
113
+ * two sit at one revision and gates **both** out as ambiguous where they do
114
+ * not — which is 0158-permanent in the first case and silent in both.
115
+ */
116
+ export const formKeyOf = (form) => `${form.treeId}\u0000${form.audienceId ?? ""}`;
117
+ /** Sorted so a list of forms reads the same whatever order they arrived in. */
118
+ export const inFormOrder = (one, other) => formKeyOf(one).localeCompare(formKeyOf(other));
119
+ /**
120
+ * The two populations a comparison was handed, published once rather than
121
+ * spelled on each comparison.
122
+ *
123
+ * Carried whether or not the pair was refused, because a `null` on either side
124
+ * is the whole of why a mismatched pair can go unrefused: it is what a surface
125
+ * reads to say *this comparison spans a window that named no audience* rather
126
+ * than being told nothing at all.
127
+ */
128
+ export const comparedAudiencesOf = (was, now) => ({ was: was.audienceId ?? null, now: now.audienceId ?? null });
129
+ /**
130
+ * Whether two sides of a comparison prove they are of two populations.
131
+ *
132
+ * The one place that decides it, for the reason {@link readingKeyOf} is one
133
+ * place: ten comparisons here take their pair from a caller, nine of them
134
+ * refuse a pair of different trees, and a pair of different audiences is the
135
+ * same kind of error with none of the same visibility. Two trees are two pages and every figure comes back absurd; two
136
+ * forms of one page (0263) compare cleanly and the arithmetic is right. What is
137
+ * wrong is the sentence on top of it — *this is what your change did* — when
138
+ * the readership was varied by construction and the tree may not have changed
139
+ * at all.
140
+ *
141
+ * **False where either side names none, and that is not an oversight.** A row
142
+ * written before the column existed (0284) names no audience, so a pair of such
143
+ * a window and an `aud_pro` one is either an honest before-and-after across the
144
+ * migration or a cross-population comparison, and nothing in the counters tells
145
+ * them apart. Refusing both would withhold every comparison spanning the day a
146
+ * deployment upgraded, which is the comparison it most wants; refusing neither
147
+ * would publish a cross-population movement as a change. So the rule refuses
148
+ * what is provable and {@link comparedAudiencesOf} makes the rest visible.
149
+ */
150
+ export const crossesAudiences = (was, now) => {
151
+ const pair = comparedAudiencesOf(was, now);
152
+ return pair.was !== null && pair.now !== null && pair.was !== pair.now;
153
+ };
154
+ /**
155
+ * The audiences a set of forms names, deduplicated and in a stable order.
156
+ *
157
+ * The form-level counterpart of {@link audiencesIn}, which answers the same
158
+ * question over rows. A form whose `audienceId` is `null` is not an audience
159
+ * and is not counted as one, so a window of forms that never carried the
160
+ * column answers `[]` — *nothing here says* rather than *one audience*.
161
+ */
162
+ export const audiencesOf = (forms) => {
163
+ const found = new Set();
164
+ for (const form of forms) {
165
+ if (form.audienceId !== null)
166
+ found.add(form.audienceId);
167
+ }
168
+ return sorted(found);
169
+ };
170
+ /**
171
+ * The pages behind a set of forms, which two forms of one page share.
172
+ *
173
+ * A page is one base tree plus the deltas an audience earns (0263), so the
174
+ * tree is the page and the form is the page as one audience meets it. A window
175
+ * of four forms over three trees is three pages, one of them served twice.
176
+ */
177
+ export const pagesOf = (forms) => {
178
+ const pages = new Set();
179
+ for (const form of forms)
180
+ pages.add(form.treeId);
181
+ return pages;
182
+ };
183
+ /** The closed set, in the order {@link formPairOf} reaches them. */
184
+ export const FORM_PAIR_REFUSALS = everyMemberOf()([
185
+ "different-pages",
186
+ "unsplit",
187
+ "unattributed",
188
+ "one-population",
189
+ "different-revisions",
190
+ ]);
191
+ /** One line per refusal, for a surface saying why there is no pair. */
192
+ export const describeFormPairRefusal = (refusal) => {
193
+ switch (refusal) {
194
+ case "different-pages":
195
+ return "the two readings are of different pages";
196
+ case "unsplit":
197
+ return "one of the two windows holds two forms of the page and says which readers neither";
198
+ case "unattributed":
199
+ return "one of the two windows names no audience, so it is of no form in particular";
200
+ case "one-population":
201
+ return "both readings are of one audience, so there is no second form to compare";
202
+ case "different-revisions":
203
+ return "the two readings are of two revisions, so they are not two forms of one page";
204
+ }
205
+ };
206
+ /**
207
+ * Settle two readings into two forms of one page, or say why they are not.
208
+ *
209
+ * **Neither side is earlier, so the order of the arguments does not reach the
210
+ * answer.** `changeOf` takes `was` and `now` and does not check which is older:
211
+ * a caller holding them backwards gets every sign reversed, which is the
212
+ * bargain 0224 struck so that *this week against last week* comes out of the
213
+ * same function. Here that bargain would be a bug rather than a trade, because
214
+ * there is no fact of the matter about which of two populations comes first.
215
+ * Two deployments asking one question would get two answers, and a screen built
216
+ * on one of them would read the direction of every figure backwards without
217
+ * anything saying so.
218
+ *
219
+ * So the two sides are put in the order of their audience ids **before anything
220
+ * is read off either**, and `one` is the lower of the two names rather than the
221
+ * first argument. A pair with a name missing on either side has no order to
222
+ * take and keeps the arguments' own, which is all the two refusals that have no
223
+ * second population need.
224
+ */
225
+ export const formPairOf = (one, other) => {
226
+ const [first, second] = one.audienceId !== null &&
227
+ other.audienceId !== null &&
228
+ other.audienceId.localeCompare(one.audienceId) < 0
229
+ ? [other, one]
230
+ : [one, other];
231
+ const refusing = (refusal) => ({
232
+ pairing: "refused",
233
+ one: first,
234
+ other: second,
235
+ refusal,
236
+ });
237
+ if (first.treeId !== second.treeId)
238
+ return refusing("different-pages");
239
+ const scopes = { one: audienceScopeRead(first), other: audienceScopeRead(second) };
240
+ if (scopes.one.reading === "mixed" || scopes.other.reading === "mixed")
241
+ return refusing("unsplit");
242
+ if (scopes.one.audienceId === null || scopes.other.audienceId === null)
243
+ return refusing("unattributed");
244
+ if (scopes.one.audienceId === scopes.other.audienceId)
245
+ return refusing("one-population");
246
+ if (first.revision !== second.revision)
247
+ return refusing("different-revisions");
248
+ return {
249
+ pairing: "paired",
250
+ one: first,
251
+ other: second,
252
+ audiences: { one: scopes.one.audienceId, other: scopes.other.audienceId },
253
+ };
254
+ };
255
+ //# sourceMappingURL=audiences.js.map
@@ -28,7 +28,13 @@ import { type RandomBytes } from "./view.js";
28
28
  * the control rather than the band. The addressed elements above it go on the
29
29
  * signal as `within`, read off the walk this was already doing — because which
30
30
  * region a node sat in is a fact about the page at the moment of the press, and
31
- * nothing downstream can recover it afterwards.
31
+ * nothing downstream can recover it afterwards. A `completed` carries the same
32
+ * walk, for the same reason and more sharply: *which band converted* is the
33
+ * question a deployment opens the portal to ask.
34
+ *
35
+ * **A completion is a form the browser let go.** Nothing else on the page is a
36
+ * finish a reader can be said to have reached, and nothing else is observable
37
+ * without asking the network how it went (0211).
32
38
  *
33
39
  * **It keeps up with a page that changes.** Nodes that arrive after it started
34
40
  * are watched and nodes that leave stop counting, so a band behind a Suspense
@@ -49,7 +55,7 @@ import { type RandomBytes } from "./view.js";
49
55
  * a broadcaster in a browser bundle is exactly the host who needs a `send`. One
50
56
  * import line for the two things that are always used together.
51
57
  */
52
- export { DEFAULT_READER_SIGNAL_PATH, deliverReaderSignals, type DeliverOptions, type PostBatch, type SendBeacon, } from "./deliver.js";
58
+ export { BATCH_CONTENT_TYPE, DEFAULT_READER_SIGNAL_PATH, deliverReaderSignals, type DeliverOptions, type PostBatch, type SendBeacon, } from "./deliver.js";
53
59
  export declare const READER_SIGNALS_EVENT = "loom:signals";
54
60
  /** Something that reports elements coming into and out of view. The browser's `IntersectionObserver` unless a host passes its own. */
55
61
  export type VisibilityObserver = {
@@ -4,6 +4,7 @@ import { LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM
4
4
  import { err, ok } from "../result.js";
5
5
  import { createSignalLedger } from "./ledger.js";
6
6
  import { READER_SIGNAL_KINDS } from "./kinds.js";
7
+ import { READABLE_VIEWPORT_FRACTION, READABLE_VISIBLE_FRACTION } from "./readable.js";
7
8
  import { mintViewKey } from "./view.js";
8
9
  /**
9
10
  * Broadcasting reader signals from a rendered Loom page.
@@ -32,7 +33,13 @@ import { mintViewKey } from "./view.js";
32
33
  * the control rather than the band. The addressed elements above it go on the
33
34
  * signal as `within`, read off the walk this was already doing — because which
34
35
  * region a node sat in is a fact about the page at the moment of the press, and
35
- * nothing downstream can recover it afterwards.
36
+ * nothing downstream can recover it afterwards. A `completed` carries the same
37
+ * walk, for the same reason and more sharply: *which band converted* is the
38
+ * question a deployment opens the portal to ask.
39
+ *
40
+ * **A completion is a form the browser let go.** Nothing else on the page is a
41
+ * finish a reader can be said to have reached, and nothing else is observable
42
+ * without asking the network how it went (0211).
36
43
  *
37
44
  * **It keeps up with a page that changes.** Nodes that arrive after it started
38
45
  * are watched and nodes that leave stop counting, so a band behind a Suspense
@@ -53,7 +60,7 @@ import { mintViewKey } from "./view.js";
53
60
  * a broadcaster in a browser bundle is exactly the host who needs a `send`. One
54
61
  * import line for the two things that are always used together.
55
62
  */
56
- export { DEFAULT_READER_SIGNAL_PATH, deliverReaderSignals, } from "./deliver.js";
63
+ export { BATCH_CONTENT_TYPE, DEFAULT_READER_SIGNAL_PATH, deliverReaderSignals, } from "./deliver.js";
57
64
  export const READER_SIGNALS_EVENT = "loom:signals";
58
65
  /**
59
66
  * What a reader can aim at, as HTML defines it. `summary` is left out on
@@ -87,17 +94,16 @@ const selectionOf = (kinds, types) => {
87
94
  };
88
95
  const DEFAULT_FLUSH_MS = 5000;
89
96
  /**
90
- * On screen means a reader could be reading it: at least half of the element is
91
- * visible, or it fills at least 30% of the viewport. The second clause is not
92
- * optional — the visible fraction of an element taller than the window can never
93
- * reach one half, so a long section judged by the first alone is never viewed.
97
+ * On screen means a reader could be reading it: at least
98
+ * {@link READABLE_VISIBLE_FRACTION} of the element is visible, **or** it fills
99
+ * at least {@link READABLE_VIEWPORT_FRACTION} of the viewport.
94
100
  */
95
101
  const isReadable = (entry) => {
96
102
  if (!entry.isIntersecting)
97
103
  return false;
98
104
  const viewport = entry.rootBounds?.height ?? globalThis.innerHeight ?? 0;
99
- const fills = viewport > 0 && entry.intersectionRect.height / viewport >= 0.3;
100
- return entry.intersectionRatio >= 0.5 || fills;
105
+ const fills = viewport > 0 && entry.intersectionRect.height / viewport >= READABLE_VIEWPORT_FRACTION;
106
+ return entry.intersectionRatio >= READABLE_VISIBLE_FRACTION || fills;
101
107
  };
102
108
  const intersectionVisibility = (onChange) => {
103
109
  const observer = new IntersectionObserver((entries) => onChange(entries.map((entry) => ({ target: entry.target, visible: isReadable(entry) }))), { threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1] });
@@ -203,6 +209,16 @@ export const broadcastReaderSignals = (root, options = {}) => {
203
209
  * describes even by accident.
204
210
  */
205
211
  const view = mintViewKey(options.random);
212
+ /**
213
+ * Whether the opening delivery of this page view has gone.
214
+ *
215
+ * One batch of a view carries `first` and the rest do not, which is how an
216
+ * intake counts a reader arriving exactly once — without it, the only
217
+ * countable unit is the delivery, and a reader who stays ten minutes is a
218
+ * hundred of them. A new broadcast mints a new view key and gets a new
219
+ * opening, which is what a client-side navigation needs.
220
+ */
221
+ let opened = false;
206
222
  const ledger = createSignalLedger(document.visibilityState === "hidden");
207
223
  let stopped = false;
208
224
  const walks = options.within ?? true;
@@ -239,8 +255,10 @@ export const broadcastReaderSignals = (root, options = {}) => {
239
255
  revision: page.value.revision,
240
256
  sentAt: now(),
241
257
  view,
258
+ ...(opened ? {} : { first: true }),
242
259
  signals,
243
260
  };
261
+ opened = true;
244
262
  root.dispatchEvent(new CustomEvent(READER_SIGNALS_EVENT, { detail: batch, bubbles: true }));
245
263
  deliverSafely(options.send, batch);
246
264
  };
@@ -374,6 +392,36 @@ export const broadcastReaderSignals = (root, options = {}) => {
374
392
  ...within,
375
393
  }))(details);
376
394
  };
395
+ /**
396
+ * A form inside the page was submitted, which is the one completion a page
397
+ * can witness on its own.
398
+ *
399
+ * **Captured rather than delegated**, like `toggle` and unlike `click`: a
400
+ * handler inside the page may call `stopPropagation`, and a submission the
401
+ * broadcaster never heard is a conversion nobody counted. The press on the
402
+ * submit control is a separate fact and is still reported as `activated`
403
+ * against the control — two kinds about two nodes, not one action counted
404
+ * twice.
405
+ *
406
+ * **`preventDefault` is read once the dispatch is over, never during it.**
407
+ * Any listener may cancel a submit, and whether this one runs before or after
408
+ * theirs is registration order — React attaches its own at a root container
409
+ * which may be this very element. A microtask queued here runs after dispatch
410
+ * has finished, so what it reads is the final answer rather than whichever
411
+ * one happened to be true halfway through. The instant is taken at the event,
412
+ * not in the microtask, because the event is when the reader finished.
413
+ */
414
+ const onSubmit = (event) => {
415
+ const form = event.target;
416
+ if (!(form instanceof HTMLFormElement) || !root.contains(form))
417
+ return;
418
+ const at = now();
419
+ queueMicrotask(() => {
420
+ if (stopped || event.defaultPrevented)
421
+ return;
422
+ record("completed", (address, within) => ({ kind: "completed", ...address, at, ...within }))(form);
423
+ });
424
+ };
377
425
  const disclosures = new MutationObserver((mutations) => {
378
426
  for (const mutation of mutations) {
379
427
  if (!(mutation.target instanceof Element))
@@ -421,6 +469,7 @@ export const broadcastReaderSignals = (root, options = {}) => {
421
469
  const onPageHide = () => flush();
422
470
  root.addEventListener("click", onClick);
423
471
  root.addEventListener("toggle", onToggle, true);
472
+ root.addEventListener("submit", onSubmit, true);
424
473
  disclosures.observe(root, {
425
474
  attributes: true,
426
475
  attributeFilter: [DISCLOSED_ATTRIBUTE],
@@ -443,6 +492,7 @@ export const broadcastReaderSignals = (root, options = {}) => {
443
492
  arrivals?.disconnect();
444
493
  root.removeEventListener("click", onClick);
445
494
  root.removeEventListener("toggle", onToggle, true);
495
+ root.removeEventListener("submit", onSubmit, true);
446
496
  document.removeEventListener("visibilitychange", onVisibility);
447
497
  document.defaultView?.removeEventListener("pagehide", onPageHide);
448
498
  };