@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,310 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { audienceScopeRead, comparedAudiencesOf, crossesAudiences, } from "./audiences.js";
3
+ import { ratioOf } from "./ratios.js";
4
+ import { paceStandingOf, readingPaceOf, READING_WORDS_PER_MINUTE, } from "./pace.js";
5
+ /** The closed set, for a surface that has to account for every absent figure. */
6
+ export const PACE_CHANGE_SILENCES = everyMemberOf()([
7
+ "different-trees",
8
+ "different-audiences",
9
+ "wordless",
10
+ "audiences-mixed",
11
+ "nothing-measured",
12
+ "dissolved",
13
+ ]);
14
+ /** One line per silence, for a surface saying why a figure is not there. */
15
+ export const describePaceChangeSilence = (silence) => {
16
+ switch (silence) {
17
+ case "different-trees":
18
+ return "the two readings are of different pages";
19
+ case "different-audiences":
20
+ return "the two readings are of different audiences, and so of different readers";
21
+ case "wordless":
22
+ return "neither revision says anything that takes time to read";
23
+ case "audiences-mixed":
24
+ return "one window holds two forms of the page and says which readers neither";
25
+ case "nothing-measured":
26
+ return "one of the two windows held no page views";
27
+ case "dissolved":
28
+ return "the change left no part of the page as it was, so there is nothing to compare";
29
+ }
30
+ };
31
+ /** The closed set, for a surface accounting for every part it was handed. */
32
+ export const PACE_MOVEMENTS = everyMemberOf()([
33
+ "eased",
34
+ "rushed",
35
+ "still-skimmed",
36
+ "held",
37
+ "unknown",
38
+ ]);
39
+ /** One line per movement, for a surface putting a part in front of a person. */
40
+ export const describePaceMovement = (movement) => {
41
+ switch (movement) {
42
+ case "eased":
43
+ return "readers had too little time for its words and now they have enough";
44
+ case "rushed":
45
+ return "readers had time enough for its words and now they do not";
46
+ case "still-skimmed":
47
+ return "readers had too little time for its words before and after";
48
+ case "held":
49
+ return "readers had time enough for its words before and after";
50
+ case "unknown":
51
+ return "one of the two windows cannot say whether there was time for it";
52
+ }
53
+ };
54
+ /** The closed set, for a surface accounting for every verdict that moved. */
55
+ export const PACE_CAUSES = everyMemberOf()([
56
+ "words",
57
+ "time",
58
+ "either",
59
+ "together",
60
+ "unknown",
61
+ ]);
62
+ /** One line per cause, for a surface saying what moved a verdict. */
63
+ export const describePaceCause = (cause) => {
64
+ switch (cause) {
65
+ case "words":
66
+ return "the words the change wrote would have moved it on their own";
67
+ case "time":
68
+ return "the time readers now spend would have moved it on its own";
69
+ case "either":
70
+ return "either would have moved it on its own";
71
+ case "together":
72
+ return "neither would have moved it alone and the two together did";
73
+ case "unknown":
74
+ return "some of the words are a floor, so the question cannot be answered";
75
+ }
76
+ };
77
+ const ZERO_BY_MOVEMENT = Object.freeze({
78
+ eased: 0,
79
+ rushed: 0,
80
+ "still-skimmed": 0,
81
+ held: 0,
82
+ unknown: 0,
83
+ });
84
+ const ZERO_BY_CAUSE = Object.freeze({
85
+ words: 0,
86
+ time: 0,
87
+ either: 0,
88
+ together: 0,
89
+ unknown: 0,
90
+ });
91
+ /**
92
+ * Whether a part is worth a row at all.
93
+ *
94
+ * `pace.ts`'s own distinction between *there are none* and *nobody said*
95
+ * (0122), applied to the pair: a part with no words in its subtree on either
96
+ * side and no floor on either side can never have a pace, so a row for it would
97
+ * say `unknown` for ever. A floored part is kept, because *this may ask for
98
+ * time nothing here can see* is not *this asks for none*.
99
+ */
100
+ const takesTime = (sides) => sides.some((part) => part.wordsWithin > 0 || part.floored);
101
+ /** Whether a verdict is one of the two that say readers had time enough. */
102
+ const hadTime = (standing) => standing === "paced" || standing === "lingered";
103
+ /**
104
+ * What happened between two verdicts.
105
+ *
106
+ * `unknown` first and on either side, because it is the one answer that is not
107
+ * about the part: a window with no view of it, or words that are a floor, cannot
108
+ * be read as readers having had time or not having had it (0230).
109
+ */
110
+ const movementOf = (was, now) => {
111
+ if (was === "unknown" || now === "unknown")
112
+ return "unknown";
113
+ if (was === "skimmed")
114
+ return now === "skimmed" ? "still-skimmed" : "eased";
115
+ return hadTime(now) ? "held" : "rushed";
116
+ };
117
+ /** One side's time against the other side's words, under either side's floor. */
118
+ const heldOf = (spentMs, needMs, floored) => {
119
+ const pace = spentMs === null || needMs === 0 ? null : spentMs / needMs;
120
+ return { pace, standing: paceStandingOf(pace, floored) };
121
+ };
122
+ /**
123
+ * Which side the verdict moved with, by sufficiency.
124
+ *
125
+ * Each counterfactual is asked the one question that matters — *does this carry
126
+ * today's verdict* — so the answer never depends on how much anything moved.
127
+ * `unknown` wherever a counterfactual has no verdict, because the alternative
128
+ * is reading a floor's silence as a no.
129
+ */
130
+ const causeOf = (now, ifWordsHeld, ifTimeHeld) => {
131
+ if (ifWordsHeld.standing === "unknown" || ifTimeHeld.standing === "unknown")
132
+ return "unknown";
133
+ const wordsSuffice = ifTimeHeld.standing === now;
134
+ const timeSuffice = ifWordsHeld.standing === now;
135
+ if (wordsSuffice && timeSuffice)
136
+ return "either";
137
+ if (wordsSuffice)
138
+ return "words";
139
+ return timeSuffice ? "time" : "together";
140
+ };
141
+ /** Every part of a pace reading, keyed by node. */
142
+ const partsOf = (pace) => {
143
+ const byNode = new Map();
144
+ for (const part of pace.parts)
145
+ byNode.set(part.nodeId, part);
146
+ return byNode;
147
+ };
148
+ /**
149
+ * The one with more words passed, `>` keeping the first in the later reading
150
+ * order on a tie.
151
+ */
152
+ const moreOf = (standing, next) => standing === null || next.now.wordsPassed > standing.now.wordsPassed ? next : standing;
153
+ /** Descending by the words readers were shown now, strictly, so equals keep their order. */
154
+ const byWordsPassed = (one, other) => other.now.wordsPassed - one.now.wordsPassed;
155
+ /**
156
+ * Whether a revision says anything that takes time to read.
157
+ *
158
+ * Over each part's **own** words rather than the root's subtree, because a part's
159
+ * own words partition the page exactly once (0235) and a tree whose root is not
160
+ * an element has no part at depth 0 to read a page total off. A floor anywhere
161
+ * counts as something said, for `takesTime`'s reason.
162
+ */
163
+ const saysAnything = (pace) => pace.parts.some((part) => part.words > 0 || part.floored);
164
+ /**
165
+ * Whether either side was read as neither of two forms.
166
+ *
167
+ * Taken off the two readings' own published scope rather than recomputed, which
168
+ * is what `audienceScopeRead` is for: five comparisons now ask this one question
169
+ * and a sixth spelling of it is how the rule comes to be agreed with by some of
170
+ * them (0293).
171
+ */
172
+ const unsplit = (was, now) => audienceScopeRead(was).reading === "mixed" || audienceScopeRead(now).reading === "mixed";
173
+ const silenceOf = (readings, compared, unsplitWindow) => {
174
+ if (!saysAnything(readings.was) && !saysAnything(readings.now))
175
+ return "wordless";
176
+ if (unsplitWindow)
177
+ return "audiences-mixed";
178
+ if (readings.was.views === 0 || readings.now.views === 0)
179
+ return "nothing-measured";
180
+ return compared.length === 0 ? "dissolved" : null;
181
+ };
182
+ /** A positive, finite option, or the fallback — `pace.ts`'s rule, applied per side. */
183
+ const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
184
+ /**
185
+ * What a change did to whether readers had time for what a page says.
186
+ *
187
+ * Handed two `PageReading`s rather than two `PagePace`s, for the reason
188
+ * `copyChangeOf` is handed two: one input per side cannot be a mismatched pair.
189
+ * Here it buys a second guarantee that matters more — **the two sides cannot
190
+ * have been costed at different rates**, which no caller holding two finished
191
+ * pace readings could be stopped from doing and which would make every ratio
192
+ * below a comparison of the rates. The two pace readings it derives are
193
+ * returned.
194
+ *
195
+ * The labels `was` and `now` are the caller's. Nothing here checks which
196
+ * reading is older, so a caller holding them backwards gets a comparison with
197
+ * every movement reversed rather than a refusal — the same bargain 0224 struck,
198
+ * for the same reason: *this week against last week* is the same question with
199
+ * the tree held still, and refusing one order would refuse that too.
200
+ */
201
+ export const paceChangeOf = (was, now, options = {}) => {
202
+ const inflation = {
203
+ was: positive(options.inflation?.was, 0),
204
+ now: positive(options.inflation?.now, 0),
205
+ };
206
+ /**
207
+ * One rate, resolved once and handed to both sides, which is the whole of
208
+ * what taking two readings rather than two paces buys.
209
+ */
210
+ const wordsPerMinute = positive(options.wordsPerMinute, READING_WORDS_PER_MINUTE);
211
+ const readings = {
212
+ was: readingPaceOf(was, { inflation: inflation.was, wordsPerMinute }),
213
+ now: readingPaceOf(now, { inflation: inflation.now, wordsPerMinute }),
214
+ };
215
+ const head = {
216
+ treeId: was.treeId,
217
+ revisions: { was: was.revision, now: now.revision },
218
+ audiences: comparedAudiencesOf(was, now),
219
+ readings,
220
+ wordsPerMinute,
221
+ inflation,
222
+ };
223
+ /** The two states in which neither half of the comparison stands. */
224
+ const refusing = (silence) => ({
225
+ ...head,
226
+ compared: [],
227
+ added: [],
228
+ removed: [],
229
+ movements: ZERO_BY_MOVEMENT,
230
+ causes: ZERO_BY_CAUSE,
231
+ whole: null,
232
+ mostEased: null,
233
+ mostRushed: null,
234
+ stillSkimmed: [],
235
+ need: null,
236
+ silence,
237
+ });
238
+ if (was.treeId !== now.treeId)
239
+ return refusing("different-trees");
240
+ if (crossesAudiences(was, now))
241
+ return refusing("different-audiences");
242
+ const earlier = partsOf(readings.was);
243
+ const later = partsOf(readings.now);
244
+ const compared = [];
245
+ const added = [];
246
+ const removed = [];
247
+ for (const [nodeId, part] of later) {
248
+ const before = earlier.get(nodeId);
249
+ if (before === undefined) {
250
+ if (takesTime([part]))
251
+ added.push(part);
252
+ continue;
253
+ }
254
+ if (!takesTime([before, part]))
255
+ continue;
256
+ const floored = before.floored || part.floored;
257
+ const ifWordsHeld = heldOf(part.spentMs, before.needMs, floored);
258
+ const ifTimeHeld = heldOf(before.spentMs, part.needMs, floored);
259
+ const movement = movementOf(before.standing, part.standing);
260
+ compared.push({
261
+ nodeId,
262
+ type: part.type,
263
+ role: part.role,
264
+ was: before,
265
+ now: part,
266
+ movement,
267
+ paceRatio: ratioOf(before.pace, part.pace),
268
+ timeRatio: ratioOf(before.spentMs, part.spentMs),
269
+ needRatio: ratioOf(before.needMs, part.needMs),
270
+ ifWordsHeld,
271
+ ifTimeHeld,
272
+ cause: movement === "eased" || movement === "rushed"
273
+ ? causeOf(part.standing, ifWordsHeld, ifTimeHeld)
274
+ : null,
275
+ });
276
+ }
277
+ for (const [nodeId, part] of earlier) {
278
+ if (later.has(nodeId))
279
+ continue;
280
+ if (takesTime([part]))
281
+ removed.push(part);
282
+ }
283
+ const movements = compared.reduce((counted, part) => ({ ...counted, [part.movement]: counted[part.movement] + 1 }), { ...ZERO_BY_MOVEMENT });
284
+ const causes = compared.reduce((counted, part) => part.cause === null ? counted : { ...counted, [part.cause]: counted[part.cause] + 1 }, { ...ZERO_BY_CAUSE });
285
+ const whole = compared.find((part) => part.now.depth === 0 && part.was.depth === 0) ?? null;
286
+ const ranked = (movement) => compared.reduce((standing, next) => next.movement === movement && next !== whole ? moreOf(standing, next) : standing, null);
287
+ return {
288
+ ...head,
289
+ compared,
290
+ added,
291
+ removed,
292
+ movements,
293
+ causes,
294
+ whole,
295
+ mostEased: ranked("eased"),
296
+ mostRushed: ranked("rushed"),
297
+ stillSkimmed: compared
298
+ .filter((part) => part.movement === "still-skimmed" && part !== whole)
299
+ .sort(byWordsPassed),
300
+ need: whole === null
301
+ ? null
302
+ : {
303
+ was: whole.was.needMs,
304
+ now: whole.now.needMs,
305
+ change: whole.now.needMs - whole.was.needMs,
306
+ },
307
+ silence: silenceOf(readings, compared, unsplit(was, now)),
308
+ };
309
+ };
310
+ //# sourceMappingURL=pace-change.js.map
@@ -0,0 +1,296 @@
1
+ import type { NodeId, TreeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { PrimitiveRole } from "../role.js";
4
+ import type { PageReading } from "./parts.js";
5
+ /**
6
+ * Whether a part was read or scrolled past.
7
+ *
8
+ * [`parts.ts`](parts.ts) answers *which parts came into view*, and it has
9
+ * always been careful to say only that: `read` there means **a row says this
10
+ * part was on a reader's screen**. A band a reader scrolled through at speed is
11
+ * `read` by that definition and was not read by any other, and a page of them
12
+ * reports as a page that was read from top to bottom. That is the
13
+ * plausible-false-number failure this subsystem keeps finding in new places —
14
+ * the figure is the right shape, it is on the screen, and nobody can tell it is
15
+ * wrong.
16
+ *
17
+ * The missing half was already in the rows. A tally carries `dwellMs` beside
18
+ * `reached`, and since [0223](../../decisions/0223-a-prop-is-copy-when-a-reader-could-quote-it.md)
19
+ * the tree carries the words a part says. **Time on screen against the time its
20
+ * words take to read** is the question, and both sides of it are already held:
21
+ * nothing is added to a payload, a browser, a column, a store or the
22
+ * vocabulary. It is the fifth thing taken out of the server-side join of
23
+ * [0212](../../decisions/0212-what-a-reader-signal-means-is-joined-to-the-tree-when-it-is-read.md)
24
+ * rather than collected.
25
+ *
26
+ * ## A verdict in one direction only
27
+ *
28
+ * Three things bias the comparison, and all three bias it the same way.
29
+ *
30
+ * - **Dwell is time on screen, not time reading.** `READABLE_VISIBLE_FRACTION`
31
+ * says half of an element showing is enough ([0218](../../decisions/0218-what-a-counter-means-is-published-and-the-browser-pays-for-the-number-and-not-its-name.md)),
32
+ * so a part sits accumulating dwell while a reader reads its neighbour, and
33
+ * an ancestor accumulates dwell for the whole time any of its children was up.
34
+ * - **A word count can be a floor.** A type that declares no `copy` has words
35
+ * nothing can see (0122), and a declared prop holding something other than a
36
+ * string is a word owed and not given. Either way the part says *at least*
37
+ * this much.
38
+ * - **The reader count is generous.** `reached` is a distinct view count summed
39
+ * across rollup windows (0147), so a reader who straddled a boundary is two,
40
+ * and the mean time per reader is short by that much. This is the one of the
41
+ * three that is measured rather than argued, and {@link PaceOptions.inflation}
42
+ * is where a deployment hands the measurement in (0219).
43
+ *
44
+ * So the time a reader is credited with is generous, the words they had to get
45
+ * through are a floor, and **`skimmed` is the only verdict that survives all
46
+ * three**: it says the time on screen was short *even after* every doubt has
47
+ * been resolved in the page's favour. `paced` and `lingered` are the weaker
48
+ * claims, and where the words are a floor they are not made at all — the part
49
+ * goes back to `unknown`, with {@link PaceSilence} saying why.
50
+ *
51
+ * That asymmetry is the whole design and it is deliberate. *Readers are not
52
+ * reading this* is worth being sure of. *Readers read this* is a thing nobody
53
+ * acts on.
54
+ *
55
+ * ## Nesting, and the sums that are therefore missing
56
+ *
57
+ * A part is judged against its own subtree's words, because the words on screen
58
+ * while a band was up are the band's and its children's. So figures nest: a
59
+ * band and the paragraph inside it are both here, and the paragraph's words are
60
+ * in the band's count. Nothing on a page total adds them, and there is no
61
+ * page-wide word figure at all — one reader who scrolled past a band scrolled
62
+ * past everything in it, and a sum would charge them for it once per level.
63
+ *
64
+ * Pure, linear in the parts, and reaches no store, clock or DOM — it adds
65
+ * nothing to the broadcaster's import graph.
66
+ */
67
+ /**
68
+ * The rate a page's words are costed at, in words per minute.
69
+ *
70
+ * Published for the reason the readable fractions are (0218): a number that
71
+ * decides what a counter **means** should be quotable by the page explaining
72
+ * it, rather than retyped beside the noun it qualifies. 240 is the middle of
73
+ * the range usually reported for adult silent reading of ordinary prose, and it
74
+ * is a costing rate rather than a claim about any reader — the verdicts are
75
+ * built to survive being wrong about it by a wide margin in either direction.
76
+ *
77
+ * **Unlike the readable fractions, this one may be overridden**, and the
78
+ * difference is which side of the wire it lives on. Those two are applied in a
79
+ * browser and are baked into every counter already written. This is applied
80
+ * when the rows are read (0212), so a deployment that changes it reinterprets
81
+ * its whole history and invalidates nothing. What it may change is the rate,
82
+ * which is a fact about its own text and its own language that the framework
83
+ * cannot know; the thresholds below are the framework's statement of how much
84
+ * margin a claim needs, and are not a dial.
85
+ */
86
+ export declare const READING_WORDS_PER_MINUTE = 240;
87
+ /**
88
+ * Below this much of the time its words take, a part was not read.
89
+ *
90
+ * Half. Low enough that the verdict holds through all three biases above, which
91
+ * is what makes it the claim worth putting on a screen.
92
+ */
93
+ export declare const SKIMMED_BELOW = 0.5;
94
+ /**
95
+ * Above this much, readers stayed longer than the words account for.
96
+ *
97
+ * A weak signal by construction, because dwell counts a part that was merely up
98
+ * while something else was being read. It is a question — *is this where people
99
+ * get stuck, or is it just the tall thing at the bottom of the page* — and not
100
+ * an answer.
101
+ */
102
+ export declare const LINGERED_ABOVE = 3;
103
+ /** What the time readers spent says about the words a part puts in front of them. */
104
+ export type PaceStanding =
105
+ /**
106
+ * Readers had less than {@link SKIMMED_BELOW} of the time the words take.
107
+ *
108
+ * The one verdict here that is safe against every bias in the module
109
+ * documentation, and the one a screen should lead with.
110
+ */
111
+ "skimmed"
112
+ /** Time enough for the words, and not conspicuously more. */
113
+ | "paced"
114
+ /** More than {@link LINGERED_ABOVE} times the time the words take. */
115
+ | "lingered"
116
+ /** Nothing can be said, and {@link PacedPart.silence} says which nothing. */
117
+ | "unknown";
118
+ export declare const PACE_STANDINGS: readonly PaceStanding[];
119
+ /** Why a part has no pace. */
120
+ export type PaceSilence =
121
+ /**
122
+ * No view reported it coming into view, so there is no time to divide and no
123
+ * reader to divide it between.
124
+ *
125
+ * On a window with no views at all, this is every part — which is the same
126
+ * refusal `parts.ts` makes one level down, arrived at rather than special-cased.
127
+ */
128
+ "unreached"
129
+ /**
130
+ * Its words are a floor, and the verdict that floor would support is not the
131
+ * safe one.
132
+ *
133
+ * Some type in its subtree declares no `copy`, or declared a prop holding
134
+ * something that is not a string. `skimmed` is still reported where it is
135
+ * reached, because more words only make a part more skimmed; anything else
136
+ * would be a claim resting on words nobody counted.
137
+ */
138
+ | "unreadable"
139
+ /**
140
+ * It says nothing, as far as anything can tell: no words, and nothing
141
+ * undeclared either.
142
+ *
143
+ * A spacer, a rule, an image with no caption. There is no time its words take,
144
+ * so there is no ratio — and this is kept apart from `unreadable` because
145
+ * *there are none* and *nobody said* are different answers (0122).
146
+ */
147
+ | "wordless";
148
+ export declare const PACE_SILENCES: readonly PaceSilence[];
149
+ /** One line per standing, for a surface putting the reading in front of a person. */
150
+ export declare const describePaceStanding: (standing: PaceStanding) => string;
151
+ /** One line per silence, for the same surface. */
152
+ export declare const describePaceSilence: (silence: PaceSilence) => string;
153
+ /** One part, with the time its readers had against the time its words take. */
154
+ export type PacedPart = {
155
+ readonly nodeId: NodeId;
156
+ readonly type: PrimitiveType;
157
+ /** What part it plays (0114), or `null` where its type declared none. */
158
+ readonly role: PrimitiveRole | null;
159
+ /** 0 at the root. */
160
+ readonly depth: number;
161
+ /** null at the root. */
162
+ readonly parentId: NodeId | null;
163
+ /** Distinct page views that reported it coming into view; `0` where no row named it. */
164
+ readonly readers: number;
165
+ /** The words this part says itself, counted. Its own, never its subtree's. */
166
+ readonly words: number;
167
+ /**
168
+ * The words of this part and everything under it.
169
+ *
170
+ * The denominator, because the text on screen while a band was up is the
171
+ * band's and its children's. Nests, and is therefore never added across parts.
172
+ */
173
+ readonly wordsWithin: number;
174
+ /**
175
+ * Whether {@link wordsWithin} is a floor rather than a count.
176
+ *
177
+ * True when anything in the subtree declared no `copy`, or declared a prop
178
+ * holding something other than a string.
179
+ */
180
+ readonly floored: boolean;
181
+ /** Time on screen, summed across every view in the window. */
182
+ readonly dwellMs: number;
183
+ /**
184
+ * The same time per reader, after {@link PaceOptions.inflation}.
185
+ *
186
+ * `null` where nobody reached it. Generous by the two biases nothing measures:
187
+ * dwell counts a part that was merely up, and an ancestor's dwell covers its
188
+ * children's reading.
189
+ */
190
+ readonly spentMs: number | null;
191
+ /** What {@link wordsWithin} takes at the costing rate. `0` where it says nothing. */
192
+ readonly needMs: number;
193
+ /**
194
+ * Time spent for every unit of time the words take. `1` is exactly enough.
195
+ *
196
+ * `null` where there is nothing to divide: no reader, or no words.
197
+ */
198
+ readonly pace: number | null;
199
+ readonly standing: PaceStanding;
200
+ /** Why there is no verdict, and `null` where there is one. */
201
+ readonly silence: PaceSilence | null;
202
+ /**
203
+ * Readers times the words they were shown here — the ranking key, and a
204
+ * magnitude rather than a census.
205
+ *
206
+ * Nests like {@link wordsWithin} does, so it ranks and is never summed.
207
+ */
208
+ readonly wordsPassed: number;
209
+ };
210
+ export type PagePace = {
211
+ readonly treeId: TreeId;
212
+ readonly revision: number;
213
+ /** The page's view floor, carried through from the reading unchanged. */
214
+ readonly views: number;
215
+ /** Every element part of the revision, in reading order. */
216
+ readonly parts: readonly PacedPart[];
217
+ readonly standings: Readonly<Record<PaceStanding, number>>;
218
+ /** Why the parts with no verdict have none. Counts only the silent ones. */
219
+ readonly silences: Readonly<Record<PaceSilence, number>>;
220
+ /**
221
+ * The root, judged against the whole page.
222
+ *
223
+ * *Readers spend a third of the time this page's words take* is a true
224
+ * sentence and the one a reader screen opens with — and it is kept out of
225
+ * {@link mostSkimmed} because the page contains every part, so by words passed
226
+ * it would win every ranking it was entered in.
227
+ *
228
+ * `null` where the revision's root is not an element, which is the one tree
229
+ * shape with no part at depth 0.
230
+ */
231
+ readonly whole: PacedPart | null;
232
+ /**
233
+ * The part of the page most words went unread in: most words passed, then
234
+ * first in reading order.
235
+ *
236
+ * By words passed rather than by the lowest pace, for the same reason a stop
237
+ * is ranked by the readers it loses (0221): a caption two readers hurried
238
+ * past is a worse ratio and a smaller problem than a band four hundred of
239
+ * them did.
240
+ */
241
+ readonly mostSkimmed: PacedPart | null;
242
+ /** The inflation that was applied; `0` when none was given. */
243
+ readonly inflation: number;
244
+ /** The costing rate that was applied, which is the default unless one was given. */
245
+ readonly wordsPerMinute: number;
246
+ };
247
+ export type PaceOptions = {
248
+ /**
249
+ * How generous the reader counts are, as `drift ÷ opened` off the page-view
250
+ * rows (0219).
251
+ *
252
+ * `reached` over-counts by the page views that straddled a rollup window, so
253
+ * the mean time per reader is short by the same proportion — and short means
254
+ * **more parts called skimmed than should be**, which is the one direction
255
+ * this module's safe verdict cannot afford to be wrong in. A deployment that
256
+ * has the measurement hands it over and the correction is applied; one that
257
+ * does not gets the uncorrected figure and the bias stated here.
258
+ *
259
+ * Absent, zero, negative or not finite are all *no correction*: a negative
260
+ * inflation is not a thing a rollup can produce, and silently trusting one
261
+ * would widen the claim rather than narrow it.
262
+ */
263
+ readonly inflation?: number;
264
+ /**
265
+ * The costing rate, where {@link READING_WORDS_PER_MINUTE} is wrong for this
266
+ * deployment's text.
267
+ *
268
+ * Zero, negative or not finite are refused the same way, and the published
269
+ * default applies.
270
+ */
271
+ readonly wordsPerMinute?: number;
272
+ };
273
+ /**
274
+ * The verdict, which is the asymmetry of the module documentation written once.
275
+ *
276
+ * `skimmed` is reached before the floor is consulted, because words nobody
277
+ * counted can only make a part more skimmed than it already reads. Everything
278
+ * after that point is a claim the floor could overturn.
279
+ *
280
+ * **Published** because a comparison of two windows asks it of a pace neither
281
+ * window reported — the pace a part would have had if the change had not
282
+ * touched its words ([`pace-change.ts`](pace-change.ts)) — and a second
283
+ * spelling of this rule is the thing this subsystem has already been bitten by
284
+ * twice: two counter keys that agreed until they did not, and two word counts
285
+ * that agreed until one of them learned about slots.
286
+ */
287
+ export declare const paceStandingOf: (pace: number | null, floored: boolean) => PaceStanding;
288
+ /**
289
+ * Whether readers had time to read what each part of a page says.
290
+ *
291
+ * Handed the output of `pageReadingOf`, because the words, the counters and the
292
+ * reading order are all already joined there and deriving them a second time is
293
+ * how two screens come to disagree.
294
+ */
295
+ export declare const readingPaceOf: (reading: PageReading, options?: PaceOptions) => PagePace;
296
+ //# sourceMappingURL=pace.d.ts.map