@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
@@ -0,0 +1,333 @@
1
+ import { readingKeyOf } from "./audiences.js";
2
+ import { atDoorScale, doorOf } from "./door.js";
3
+ import { paceStandingOf, readingPaceOf, READING_WORDS_PER_MINUTE, } from "./pace.js";
4
+ import { pageViewsFor } from "./page-views.js";
5
+ /**
6
+ * Whether the readers who reach **one part** have time for what it says, across
7
+ * every page it stands on.
8
+ *
9
+ * A goal is a kind of signal on a part
10
+ * ([0350](../../decisions/0350-a-project-sets-goals-from-signals-already-collected-and-one-of-them-is-primary.md)):
11
+ * one node id, counted on the pages a project named or on every page that has
12
+ * it. Every figure a goal has is therefore keyed on a part across pages — and
13
+ * **the one a screen has been waiting for since 8 November is how long readers
14
+ * stay on it**, which `docs/portal.md` records twice as *waiting on time on a
15
+ * part being counted per reader*.
16
+ *
17
+ * The time was already in the rows. A tally carries `dwellMs` beside `reached`
18
+ * for every part of every revision, and [`pace.ts`](pace.ts) has divided the
19
+ * two for a part of **one** page since it landed. What was unaskable is the
20
+ * same question of a part that stands on nine pages: a goal's part has nine
21
+ * rows, nine word counts and nine doors, and nothing added them up. So this is
22
+ * the join, and it is the **twenty-third** thing taken out of what this
23
+ * subsystem already knows rather than collected: no payload field, no counter,
24
+ * no column, no byte on any wire and nothing in a browser.
25
+ *
26
+ * ## It is `library-pace.ts`' arithmetic keyed on a node instead of a kind
27
+ *
28
+ * [`library-pace.ts`](library-pace.ts) answers the same question of a *kind* of
29
+ * part (0325) and this one shares its terms exactly, deliberately and by
30
+ * reading its published pieces rather than by respelling them: a pooled
31
+ * quotient of two reader-millisecond sums, `dwellMs` added as the rows hold it
32
+ * and `readers × wordsWithin × msPerWord` as the denominator, each page's
33
+ * readers put on its **own** door's scale before two pages are added (0250),
34
+ * the verdict taken by {@link paceStandingOf} so that a floor can hold up
35
+ * anything but `skimmed`, and a page the door cannot scale kept rather than
36
+ * refused, because the missing correction only ever moves a pace towards the
37
+ * safe verdict.
38
+ *
39
+ * **A goal's part is not a kind of part**, which is why this is a reading and
40
+ * not a row of that one. A kind pools every placement of a type; a goal names
41
+ * one node, and the type row a screen could have read instead holds the
42
+ * forty-nine other sections of the deployment. Nothing in the library readings
43
+ * can narrow to a node, and a surface narrowing one by hand would be dividing
44
+ * two columns with none of the five rules above applied to them.
45
+ *
46
+ * ## Nothing nests, and that is the whole of what this reading does not need
47
+ *
48
+ * A kind's pace carries a nesting rule, because a stack inside a stack would
49
+ * put one page's words into one row twice. **A node id stands at most once in a
50
+ * revision**, so there is nothing here for an outer placement to stand for: one
51
+ * reading contributes one placement or none, every term is a sum over distinct
52
+ * pages, and the only way a page can enter twice is a caller handing the same
53
+ * reading in twice — which is what {@link PartPace.duplicated} counts and the
54
+ * one error that would be permanent if it were let through (0158).
55
+ *
56
+ * ## Which page it is skimmed on is the same rows, kept rather than summed away
57
+ *
58
+ * The pooled quotient is one number about nine pages, and `standings` says *and
59
+ * skimmed on two of them* without saying which two. The per-page rows were
60
+ * always there — the loop reads each page's own pace, its own words and its own
61
+ * door, and threw them away — so publishing them costs an array and no further
62
+ * arithmetic
63
+ * ([0390](../../decisions/0390-a-parts-pages-are-a-second-order-ranked-on-the-reading-time-its-readers-did-not-have.md)).
64
+ *
65
+ * The decision in it is the **order**, and it is this subsystem's ordinary one:
66
+ * the pages are ranked on the reading time their readers did not have, a
67
+ * magnitude in reader-milliseconds, rather than on the pace, a rate. A page one
68
+ * reader hurried past has the worst rate in the deployment and is not the page
69
+ * to go to (0250, 0377).
70
+ *
71
+ * ## The silences are a kind's four, as values
72
+ *
73
+ * {@link KindPaceSilence} unchanged, and reused rather than respelled for the
74
+ * reason `library-pace.ts` reuses a census's two (0256): *it stands nowhere*,
75
+ * *nowhere it stands was read*, *its words could not be counted* and *it says
76
+ * nothing that takes time* are the same four states of the same quotient, and a
77
+ * twenty-third silence vocabulary naming them again would give a screen two
78
+ * names for one state and two mappings to keep in step. What is part-shaped is
79
+ * the **sentence**, which {@link describePartPaceSilence} says; the meaning a
80
+ * window publishes is `meaningOfKindPaceSilence` and stays one function.
81
+ *
82
+ * Pure. It reaches no store, no clock and no DOM, it is linear in the parts of
83
+ * the readings times the rows handed in, and nothing in it survives into a
84
+ * browser bundle.
85
+ */
86
+ /** One line per silence, for a surface saying why one part has no pace. */
87
+ export const describePartPaceSilence = (silence) => {
88
+ switch (silence) {
89
+ case "unread":
90
+ return "nothing reported a view of this part on any page it stands on";
91
+ case "unplaced":
92
+ return "none of the pages read holds this part";
93
+ case "unreadable":
94
+ return "some of its words could not be counted, so only a skim could be claimed of it";
95
+ case "wordless":
96
+ return "it says nothing that takes time to read";
97
+ }
98
+ };
99
+ const NO_STANDINGS = Object.freeze({
100
+ skimmed: 0,
101
+ paced: 0,
102
+ lingered: 0,
103
+ unknown: 0,
104
+ });
105
+ const NO_SILENCES = Object.freeze({
106
+ unreached: 0,
107
+ unreadable: 0,
108
+ wordless: 0,
109
+ });
110
+ /**
111
+ * Tree id, then newest revision first, which is the order the page-view rows
112
+ * are read in — and the last key of every list this module publishes, so two
113
+ * pages that cost the same do not reorder on a refresh.
114
+ */
115
+ const byRevision = (one, other) => one.treeId.localeCompare(other.treeId) || other.revision - one.revision;
116
+ /**
117
+ * Most reading time missing, then the lower pace, then by page (0390).
118
+ *
119
+ * Both keys are the row's own, and the second is only ever reached by pages
120
+ * whose readers had time enough — `shortMs` is nought exactly where `pace` is
121
+ * at least `1`, so the tie-break ranks the pages nearest to being short.
122
+ */
123
+ const byTimeMissing = (one, other) => other.shortMs - one.shortMs || one.pace - other.pace || byRevision(one, other);
124
+ const MS_PER_MINUTE = 60_000;
125
+ /** A positive, finite option, or the fallback. Everything else is refused. */
126
+ const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
127
+ /**
128
+ * The silence, with the reasons tried in the order they have to be tried in.
129
+ *
130
+ * *It stands nowhere* before *nowhere was read*, because the second is true of
131
+ * the first by accident. Then the part-level reasons in the order a page's own
132
+ * reading reaches them: a floor before silence, because *nobody counted them*
133
+ * outranks *there are none*.
134
+ */
135
+ const silenceOf = (placements, counted, silences, standing) => {
136
+ if (placements === 0)
137
+ return "unplaced";
138
+ if (counted === 0) {
139
+ if (silences.unreadable > 0)
140
+ return "unreadable";
141
+ if (silences.wordless > 0)
142
+ return "wordless";
143
+ return "unread";
144
+ }
145
+ return standing === "unknown" ? "unreadable" : null;
146
+ };
147
+ /**
148
+ * Whether the readers who reach one part have time for what it says.
149
+ *
150
+ * Takes the node, the readings of the pages it is counted on, and the whole
151
+ * window of page-view rows a deployment holds — each page's own row is picked
152
+ * out of them by the published matching rule (`pageViewsFor`) rather than by a
153
+ * hand-written copy of it, because the pairing is the part of every join here
154
+ * that fails quietly when it is got wrong.
155
+ *
156
+ * **Which readings are handed in is the caller's answer to *which pages*.** A
157
+ * goal naming pages hands in those pages' readings; a goal naming none hands in
158
+ * every page it can read, and a reading with no row for the node contributes
159
+ * nothing but a count. Narrowing here rather than inside would have made this
160
+ * function hold the goal vocabulary, which is the portal's and not this
161
+ * subsystem's (0350).
162
+ *
163
+ * There is **no `inflation` option**, for the reason `libraryPaceOf` has none:
164
+ * one scalar over nine pages with nine straddle rates would be a correction
165
+ * nobody measured, so each page's own is read off its own door row.
166
+ *
167
+ * Linear in the parts of the readings times the rows.
168
+ */
169
+ export const partPaceOf = (nodeId, readings, rows, options = {}) => {
170
+ const wordsPerMinute = positive(options.wordsPerMinute, READING_WORDS_PER_MINUTE);
171
+ const msPerWord = MS_PER_MINUTE / wordsPerMinute;
172
+ const seen = new Set();
173
+ const trees = new Set();
174
+ const bearing = new Set();
175
+ const unscaledPages = [];
176
+ const disagreed = new Set();
177
+ const standings = { ...NO_STANDINGS };
178
+ const silences = { ...NO_SILENCES };
179
+ const ranked = [];
180
+ const unranked = [];
181
+ let type = null;
182
+ let role = null;
183
+ let placements = 0;
184
+ let counted = 0;
185
+ let floored = 0;
186
+ let whole = 0;
187
+ let readers = 0;
188
+ let dwellMs = 0;
189
+ let needMs = 0;
190
+ let unscaled = 0;
191
+ let duplicated = 0;
192
+ let duplicatedRows = 0;
193
+ for (const reading of readings) {
194
+ const key = readingKeyOf(reading);
195
+ if (seen.has(key)) {
196
+ duplicated += 1;
197
+ continue;
198
+ }
199
+ seen.add(key);
200
+ const found = pageViewsFor(reading, rows);
201
+ duplicatedRows += found.duplicated;
202
+ const door = doorOf(found.measured);
203
+ /**
204
+ * Each page's own straddle rate, off its own door (0250). A page the door
205
+ * cannot scale gets no correction, which leaves its pace low rather than
206
+ * high.
207
+ */
208
+ const paced = readingPaceOf(reading, {
209
+ inflation: found.measured?.inflation ?? 0,
210
+ wordsPerMinute,
211
+ });
212
+ const part = paced.parts.find((candidate) => candidate.nodeId === nodeId);
213
+ if (part === undefined)
214
+ continue;
215
+ placements += 1;
216
+ if (placements === 1) {
217
+ type = part.type;
218
+ role = part.role;
219
+ }
220
+ else if (part.type !== type) {
221
+ disagreed.add(part.type);
222
+ }
223
+ standings[part.standing] += 1;
224
+ const scaled = door.silence === null ? atDoorScale(part.readers, door) : part.readers;
225
+ /**
226
+ * What this page is, before it is known whether it has figures — the half
227
+ * of a row that both lists carry, and the half that is the same question
228
+ * either way.
229
+ *
230
+ * `standing` is the page's **own** reading's verdict and never one
231
+ * re-derived from the row's `pace` below. The two quotients agree
232
+ * mathematically and need not agree in their last float place, and
233
+ * `standings` counts this one — so a breakdown of *skimmed on two of them*
234
+ * that recomputed the verdict could name three pages or one (0390).
235
+ */
236
+ const where = {
237
+ treeId: reading.treeId,
238
+ revision: reading.revision,
239
+ audienceId: reading.audienceId,
240
+ readers: scaled,
241
+ dwellMs: part.dwellMs,
242
+ wordsWithin: part.wordsWithin,
243
+ floored: part.floored,
244
+ whole: part.depth === 0,
245
+ unscaled: door.silence,
246
+ standing: part.standing,
247
+ };
248
+ if (part.pace === null) {
249
+ /**
250
+ * A part with no pace always carries the reason it has none, because
251
+ * `pace.ts` fills the silence for every standing of `unknown` and a part
252
+ * with no pace is always one. The fallback is the type system's and not a
253
+ * state.
254
+ */
255
+ const silence = part.silence ?? "unreached";
256
+ silences[silence] += 1;
257
+ unranked.push({ ...where, needMs: null, spentMs: null, shortMs: null, pace: null, silence });
258
+ continue;
259
+ }
260
+ /**
261
+ * The page's own terms, in the reader-milliseconds the sums are in — never
262
+ * `PacedPart.needMs`, which is one reader's. Taking the row's figures off
263
+ * the same two products the sums are made of is what makes the breakdown
264
+ * add up to the figure above it, which is the only thing tying the two
265
+ * together.
266
+ */
267
+ const placeNeedMs = scaled * part.wordsWithin * msPerWord;
268
+ counted += 1;
269
+ trees.add(reading.treeId);
270
+ bearing.add(key);
271
+ floored += part.floored ? 1 : 0;
272
+ whole += part.depth === 0 ? 1 : 0;
273
+ readers += scaled;
274
+ dwellMs += part.dwellMs;
275
+ needMs += placeNeedMs;
276
+ ranked.push({
277
+ ...where,
278
+ needMs: placeNeedMs,
279
+ spentMs: part.dwellMs / scaled,
280
+ shortMs: Math.max(0, placeNeedMs - part.dwellMs),
281
+ pace: part.dwellMs / placeNeedMs,
282
+ silence: null,
283
+ });
284
+ if (door.silence !== null) {
285
+ unscaled += scaled;
286
+ unscaledPages.push({
287
+ treeId: reading.treeId,
288
+ revision: reading.revision,
289
+ silence: door.silence,
290
+ });
291
+ }
292
+ }
293
+ /**
294
+ * A counted placement always has a reader and a word of its own, so a part
295
+ * with one has a denominator: `needMs` is nought exactly when `counted` is.
296
+ */
297
+ const pace = counted === 0 ? null : dwellMs / needMs;
298
+ const order = [...ranked].sort(byTimeMissing);
299
+ const standing = paceStandingOf(pace, floored > 0);
300
+ const silence = silenceOf(placements, counted, silences, standing);
301
+ const measured = silence === null;
302
+ return {
303
+ nodeId,
304
+ type,
305
+ role,
306
+ typeDisagreed: [...disagreed].sort((one, other) => one.localeCompare(other)),
307
+ placements,
308
+ counted,
309
+ silences: { ...silences },
310
+ standings: { ...standings },
311
+ pages: bearing.size,
312
+ trees: trees.size,
313
+ floored,
314
+ whole,
315
+ readers: measured ? readers : null,
316
+ dwellMs,
317
+ needMs: measured ? needMs : null,
318
+ spentMs: measured ? dwellMs / readers : null,
319
+ shortMs: measured ? Math.max(0, needMs - dwellMs) : null,
320
+ pace: measured ? pace : null,
321
+ standing,
322
+ silence,
323
+ unscaled,
324
+ unscaledPages: [...unscaledPages].sort(byRevision),
325
+ duplicated,
326
+ duplicatedRows,
327
+ ranked: order,
328
+ unranked: [...unranked].sort(byRevision),
329
+ worst: order[0] ?? null,
330
+ wordsPerMinute,
331
+ };
332
+ };
333
+ //# sourceMappingURL=part-pace.js.map
@@ -2,9 +2,10 @@ import type { AudienceId } from "../audience/audience.js";
2
2
  import type { NodeId, TreeId } from "../ids.js";
3
3
  import type { PrimitiveType } from "../primitive-type.js";
4
4
  import { type PrimitiveRole } from "../role.js";
5
- import { type CopyDeclarations, type NodeCopy } from "../sdk/copy.js";
5
+ import type { CopyDeclarations, NodeCopy } from "../sdk/copy.js";
6
6
  import type { LoomTree } from "../tree/tree.js";
7
7
  import { type MaybeAudienceScoped } from "./audiences.js";
8
+ import { type RoleDeclarations } from "./join.js";
8
9
  import type { ReaderTally } from "./rollup.js";
9
10
  /**
10
11
  * What a counter is about, joined on the server from what the page already
@@ -132,19 +133,7 @@ export declare const PART_STANDINGS: readonly PartStanding[];
132
133
  export declare const spokenFor: (standing: PartStanding) => boolean;
133
134
  /** One line per standing, for a surface putting the reading in front of a person. */
134
135
  export declare const describePartStanding: (standing: PartStanding) => string;
135
- /**
136
- * Which types declared each role, as a registry answers it.
137
- *
138
- * The same shape as `CopyDeclarations` and for the same reason (0122): a
139
- * registry built by the SDK satisfies it, and so does a two-line double in a
140
- * test. The inverse — a type's role — is what this module needs and is not what
141
- * 0114 exposes, because a role is a question asked of the vocabulary rather than
142
- * of a component. The vocabulary is closed and exported, so the inversion is a
143
- * walk of `PRIMITIVE_ROLES` rather than a method on the registry.
144
- */
145
- export type RoleDeclarations = {
146
- readonly typesWithRole: (role: PrimitiveRole) => readonly PrimitiveType[];
147
- };
136
+ export type { RoleDeclarations } from "./join.js";
148
137
  /** Everything the join asks of a deployment. A `PrimitiveRegistry` satisfies it. */
149
138
  export type PartDeclarations = CopyDeclarations & RoleDeclarations;
150
139
  /**
@@ -162,8 +151,29 @@ export type PartReading = {
162
151
  readonly role: PrimitiveRole | null;
163
152
  /** 0 at the root. */
164
153
  readonly depth: number;
165
- /** null at the root. */
154
+ /**
155
+ * The **tree** parent, which may be a node that is in no part's list, and
156
+ * `null` at the root.
157
+ *
158
+ * A slot is a node with children and is never a part, so an element handed
159
+ * into a slot has a slot's id here — an id that appears nowhere in
160
+ * {@link PageReading.parts}. Kept because three readings and the published
161
+ * reference carry it and it is the right answer to the question it asks, which
162
+ * is *where is this node in the tree*. {@link PartReading.withinId} is the
163
+ * answer to the other one.
164
+ */
166
165
  readonly parentId: NodeId | null;
166
+ /**
167
+ * The nearest **addressed** ancestor — the part this part sits inside — and
168
+ * `null` at the outermost part.
169
+ *
170
+ * What a surface drawing the page's shape must key on, and what `within`
171
+ * names on the wire (0167): slots between two elements are passed through, so
172
+ * every id here is one this list has a row for. The same field, by the same
173
+ * rule, as `InsidePart.withinId` (0368) — one page has one containment, and
174
+ * two readings of it must not disagree about what contains what.
175
+ */
176
+ readonly withinId: NodeId | null;
167
177
  readonly standing: PartStanding;
168
178
  /**
169
179
  * The counters, or `undefined` where no signal in the window named it.
@@ -1,8 +1,8 @@
1
1
  import { everyMemberOf } from "../closed-set.js";
2
2
  import { PRIMITIVE_ROLES } from "../role.js";
3
- import { copyIn } from "../sdk/copy.js";
4
3
  import { outlineTree } from "../tree/outline.js";
5
4
  import { audienceScopeOf, audiencesIn } from "./audiences.js";
5
+ import { ownCopy, rolesByType } from "./join.js";
6
6
  export const PART_STANDINGS = everyMemberOf()([
7
7
  "read",
8
8
  "skipped",
@@ -46,63 +46,6 @@ const NO_STANDINGS = Object.freeze({
46
46
  skipped: 0,
47
47
  unknown: 0,
48
48
  });
49
- /**
50
- * A type's role, inverted from the vocabulary once per reading.
51
- *
52
- * Linear in the vocabulary rather than per part: the alternative is asking
53
- * `typesWithRole` for every part, which is a registry call and a list scan per
54
- * node on a page that may have thousands.
55
- */
56
- const rolesByType = (declarations) => {
57
- const byType = new Map();
58
- for (const role of PRIMITIVE_ROLES) {
59
- for (const type of declarations.typesWithRole(role)) {
60
- /**
61
- * First declaration wins, and it cannot legitimately happen twice: a
62
- * definition carries one `role`. A registry that answered the same type
63
- * for two roles is wrong about something this reading cannot fix, and
64
- * picking the earlier keeps the answer stable rather than dependent on
65
- * the vocabulary's order.
66
- */
67
- if (!byType.has(type))
68
- byType.set(type, role);
69
- }
70
- }
71
- return byType;
72
- };
73
- /**
74
- * The children that are not parts in their own right, which is what a node
75
- * contributes itself.
76
- *
77
- * Text is kept and an element is dropped, because every element is a part of
78
- * this reading and would otherwise be counted at two depths. **A slot is kept
79
- * and pruned the same way**, because a slot is not an element and so is never a
80
- * part: text handed into one belongs to the nearest element above it, and a slot
81
- * treated as an element would lose those words to a node this reading never
82
- * reports. The words of a page are partitioned across its parts exactly once,
83
- * and that sentence is only true with this clause in it.
84
- */
85
- const ownChildren = (children) => children.flatMap((child) => {
86
- switch (child.kind) {
87
- case "element":
88
- return [];
89
- case "text":
90
- return [child];
91
- case "slot":
92
- return [{ ...child, children: ownChildren(child.children) }];
93
- }
94
- });
95
- /**
96
- * What a part says on its own, read with `copyIn` against a node stripped of
97
- * everything that is a part in its own right.
98
- *
99
- * `copyIn` walks a subtree, which is right for its callers and wrong here — a
100
- * root would carry every word on the page and so would every band on the way
101
- * down. Rather than reimplement its rules about blank strings, non-string values
102
- * and what counts as declared, this hands it the node with only the children
103
- * that are nobody else's, which is exactly the part's own contribution.
104
- */
105
- const ownCopy = (node, declarations) => copyIn({ ...node, children: ownChildren(node.children) }, declarations);
106
49
  const standingOf = (counters, views) => {
107
50
  if (counters !== undefined && counters.reached > 0)
108
51
  return "read";
@@ -219,30 +162,46 @@ export const pageReadingOf = (tree, tallies, declarations, audience) => {
219
162
  }
220
163
  const views = [...byNode.values()].reduce((most, tally) => Math.max(most, tally.views), 0);
221
164
  const roles = rolesByType(declarations);
222
- const parts = outlineTree(tree.root).flatMap((entry) => {
165
+ /**
166
+ * The stack of elements still open at this point in the pre-order walk, whose
167
+ * top is the part the current node sits inside. Carried down the walk rather
168
+ * than looked up per part: a part's own ancestors are never re-walked, so the
169
+ * pass stays linear in the nodes whatever the shape of the page (rule 4). An
170
+ * entry whose depth is not below the top has closed it, which is the only
171
+ * comparison this needs.
172
+ */
173
+ const open = [];
174
+ const parts = [];
175
+ for (const entry of outlineTree(tree.root)) {
176
+ while (open.length > 0 && (open.at(-1)?.depth ?? 0) >= entry.depth)
177
+ open.pop();
223
178
  const { node } = entry;
224
179
  /**
225
180
  * Elements only, and that is the whole universe rather than a narrowing: a
226
181
  * text or slot node carries no identity attributes, so no signal can ever
227
182
  * name one. A text node's words are read as its parent's (`ownCopy`), so
228
183
  * nothing in the tree goes unaccounted for.
184
+ *
185
+ * A slot is passed over here and never pushed, which is what makes
186
+ * {@link PartReading.withinId} the nearest *addressed* ancestor rather than
187
+ * the tree parent.
229
188
  */
230
189
  if (node.kind !== "element")
231
- return [];
190
+ continue;
232
191
  const counters = byNode.get(node.id);
233
- return [
234
- {
235
- nodeId: node.id,
236
- type: node.type,
237
- role: roles.get(node.type) ?? null,
238
- depth: entry.depth,
239
- parentId: entry.parentId,
240
- standing: standingOf(counters, views),
241
- counters,
242
- copy: ownCopy(node, declarations),
243
- },
244
- ];
245
- });
192
+ parts.push({
193
+ nodeId: node.id,
194
+ type: node.type,
195
+ role: roles.get(node.type) ?? null,
196
+ depth: entry.depth,
197
+ parentId: entry.parentId,
198
+ withinId: open.at(-1)?.nodeId ?? null,
199
+ standing: standingOf(counters, views),
200
+ counters,
201
+ copy: ownCopy(node, declarations),
202
+ });
203
+ open.push({ nodeId: node.id, depth: entry.depth });
204
+ }
246
205
  const addressed = new Set(parts.map((part) => part.nodeId));
247
206
  return {
248
207
  treeId: tree.treeId,