@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
package/dist/sdk/audit.js CHANGED
@@ -1,4 +1,5 @@
1
- import { describeProbeFailures, probeConfigurations, probeEditableDecoration, probePlacement, probeStates, probeSubmissionPlacement, } from "./conformance.js";
1
+ import { namesRead } from "../render/reads.js";
2
+ import { describeProbeFailures, probeConfigurationsFrom, probeEditableDecoration, probePlacement, probeStates, probeSubmissionPlacement, } from "./conformance.js";
2
3
  const unplacedIn = (placement) => placement.outcome === "probed" ? placement.unplacedSlots : [];
3
4
  const unplacedBehavioursIn = (placement) => placement.outcome === "probed" ? placement.unplacedBehaviours : [];
4
5
  /**
@@ -7,25 +8,140 @@ const unplacedBehavioursIn = (placement) => placement.outcome === "probed" ? pla
7
8
  * same failures as one that answered despite some of them; only `not-callable`
8
9
  * has none, because nothing was called.
9
10
  */
10
- const throwingIn = (type, placement) => {
11
- const failures = placement.outcome === "probed" ? placement.threw : placement.failures;
11
+ const throwingIn = (primitive, placement) => {
12
+ const threw = placement.outcome === "probed" ? placement.threw : placement.failures;
13
+ const failures = threw.filter((failure) => accepts(primitive.validate(failure.props)));
12
14
  if (failures.length === 0)
13
15
  return [];
14
- return [{ type, failures, everyConfiguration: placement.outcome === "not-probeable" }];
16
+ return [{ type: primitive.type, failures, everyConfiguration: placement.outcome === "not-probeable" }];
15
17
  };
16
18
  const NO_ANSWERS = Object.freeze([]);
19
+ const EMPTY_PROPS = Object.freeze([{}]);
20
+ /**
21
+ * A props bag as a key, for telling two bases apart.
22
+ *
23
+ * Top-level keys sorted, so a caller writing the same bag in another order does
24
+ * not get it probed twice; nested values are compared as written, which is as
25
+ * far as this needs to go — the cost of missing a duplicate is one extra call.
26
+ */
27
+ const keyOf = (props) => JSON.stringify(Object.keys(props).sort().map((name) => [name, props[name]]));
28
+ /**
29
+ * The empty bag first, then whatever the caller supplied for this type, with
30
+ * duplicates dropped.
31
+ *
32
+ * The empty bag stays even when props were supplied: for most primitives it is
33
+ * the configuration the schema accepts, and for the rest it is the one the
34
+ * audit reports as refused — dropping it would hide the fact that this
35
+ * primitive cannot be probed without help. Deduplicating is what makes handing
36
+ * over a bag the probe already had change nothing at all.
37
+ */
38
+ const basesFor = (supplied) => {
39
+ if (supplied === undefined)
40
+ return EMPTY_PROPS;
41
+ const seen = new Set(EMPTY_PROPS.map(keyOf));
42
+ const bases = [...EMPTY_PROPS];
43
+ for (const base of supplied) {
44
+ const key = keyOf(base);
45
+ if (seen.has(key))
46
+ continue;
47
+ seen.add(key);
48
+ bases.push(base);
49
+ }
50
+ return bases;
51
+ };
52
+ /**
53
+ * Whether this primitive's own validator accepts these props.
54
+ *
55
+ * `undeclared` counts as accepted, because it means the registration carries no
56
+ * schema for the type and nothing refused anything — the same reading
57
+ * `render.ts` gives it.
58
+ */
59
+ const accepts = (verdict) => verdict.outcome !== "invalid";
60
+ const refusedIn = (primitive, configurations) => configurations.flatMap((props) => {
61
+ const verdict = primitive.validate(props);
62
+ return verdict.outcome === "invalid" ? [{ props, issues: verdict.issues }] : [];
63
+ });
64
+ const requiredPropsOf = (primitive) => (primitive.declaredProps ?? []).filter((prop) => prop.required).map((prop) => prop.name);
65
+ /**
66
+ * The entry for a primitive the probe never reached, as nought or one.
67
+ *
68
+ * The test is `not-probeable` **and** nothing accepted having answered, so a
69
+ * class component stays where 0012 put it: `not-callable` means nothing was
70
+ * called under any bag, accepted or not, and handing it props would not change
71
+ * that.
72
+ */
73
+ const unconfigured = (primitive, verdict, configurations, supplied) => {
74
+ if (verdict.outcome !== "not-probeable" || verdict.cause !== "threw")
75
+ return [];
76
+ const refused = refusedIn(primitive, configurations);
77
+ if (refused.length === 0 || refused.length < configurations.length)
78
+ return [];
79
+ return [
80
+ {
81
+ type: primitive.type,
82
+ required: [...requiredPropsOf(primitive)].sort(),
83
+ reason: supplied === undefined ? "no-props" : "props-not-accepted",
84
+ refused,
85
+ },
86
+ ];
87
+ };
88
+ /**
89
+ * Whether one probed state answers something this primitive will look for.
90
+ *
91
+ * `Object.hasOwn` rather than a truthiness test on the read, because a name
92
+ * answered with a failure is still a name answered: the state reaches the
93
+ * primitive's did-not-answer branch *having been asked*, which is a state the
94
+ * probe was told about and is not what this list reports.
95
+ */
96
+ const answersAName = (answer, reads) => namesRead(reads, answer.props ?? {}).some((name) => Object.hasOwn(answer.data, name));
97
+ /**
98
+ * One registration and the answers this call held for it, as nought or one entry.
99
+ *
100
+ * Derived from the registration and the options alone — no probe outcome reaches
101
+ * here — because the claim is that the audit was not told something, and a probe
102
+ * result cannot make that true or false.
103
+ *
104
+ * An empty `reads` is not a bound primitive and reports nothing, the way an
105
+ * empty `frames` does: there is no answer anybody could have handed it.
106
+ */
107
+ const unansweredReader = (type, reads, answers) => {
108
+ if (reads === undefined || reads.length === 0)
109
+ return [];
110
+ if (answers.length === 0)
111
+ return [{ type, reads, reason: "no-answers" }];
112
+ if (answers.some((answer) => answersAName(answer, reads)))
113
+ return [];
114
+ return [{ type, reads, reason: "names-not-answered" }];
115
+ };
17
116
  export const auditRegistry = (registry, options = {}) => {
18
- const audits = registry.primitives.map((primitive) => {
19
- const configurations = probeStates(probeConfigurations(primitive.choices), options.answers?.get(primitive.type) ?? NO_ANSWERS);
117
+ /**
118
+ * One pass, holding the registration beside its audit. What the probe was
119
+ * handed is needed again afterwards — to ask the primitive's own validator
120
+ * whether a configuration that threw was one it accepts — and a second lookup
121
+ * by type would be a second chance to get the pairing wrong.
122
+ */
123
+ const probed = registry.primitives.map((primitive) => {
124
+ const supplied = options.props?.get(primitive.type);
125
+ const states = probeStates(probeConfigurationsFrom(basesFor(supplied), primitive.choices), options.answers?.get(primitive.type) ?? NO_ANSWERS);
126
+ const configurations = states.map((state) => state.props);
20
127
  return {
21
- type: primitive.type,
22
- verdict: probeEditableDecoration(primitive.component, primitive.text, configurations, primitive.frames),
23
- placement: probePlacement(primitive.component, primitive.slots, primitive.text, configurations, primitive.behaviours, primitive.frames),
24
- submission: probeSubmissionPlacement(primitive.component, primitive.text, configurations, primitive.frames),
25
- declaresSubmits: primitive.submits,
26
- framesProps: primitive.frames,
128
+ primitive,
129
+ supplied,
130
+ configurations,
131
+ audit: {
132
+ type: primitive.type,
133
+ verdict: probeEditableDecoration(primitive.component, primitive.text, states, primitive.frames),
134
+ placement: probePlacement(primitive.component, primitive.slots, primitive.text, states, primitive.behaviours, primitive.frames),
135
+ submission: probeSubmissionPlacement(primitive.component, primitive.text, states, primitive.frames),
136
+ declaresSubmits: primitive.submits,
137
+ framesProps: primitive.frames,
138
+ refusedConfigurations: refusedIn(primitive, configurations),
139
+ },
27
140
  };
28
141
  });
142
+ const audits = probed.map((entry) => entry.audit);
143
+ const notConfigured = probed.flatMap((entry) => unconfigured(entry.primitive, entry.audit.verdict, entry.configurations, entry.supplied));
144
+ const unreached = new Set(notConfigured.map((entry) => entry.type));
29
145
  const places = (audit) => audit.submission.outcome === "places";
30
146
  return {
31
147
  audits,
@@ -44,17 +160,21 @@ export const auditRegistry = (registry, options = {}) => {
44
160
  .filter((audit) => audit.declaresSubmits && audit.submission.outcome === "not-placed")
45
161
  .map((audit) => audit.type),
46
162
  notDecorated: audits.filter((audit) => audit.verdict.outcome === "not-decorated").map((audit) => audit.type),
47
- notProbeable: audits.filter((audit) => audit.verdict.outcome === "not-probeable").map((audit) => audit.type),
163
+ notProbeable: audits
164
+ .filter((audit) => audit.verdict.outcome === "not-probeable" && !unreached.has(audit.type))
165
+ .map((audit) => audit.type),
166
+ notConfigured,
48
167
  unplacedSlots: audits
49
168
  .filter((audit) => unplacedIn(audit.placement).length > 0)
50
169
  .map((audit) => ({ type: audit.type, slots: unplacedIn(audit.placement) })),
51
170
  unplacedBehaviours: audits
52
171
  .filter((audit) => unplacedBehavioursIn(audit.placement).length > 0)
53
172
  .map((audit) => ({ type: audit.type, behaviours: unplacedBehavioursIn(audit.placement) })),
173
+ notAnswered: registry.primitives.flatMap((primitive) => unansweredReader(primitive.type, primitive.reads, options.answers?.get(primitive.type) ?? NO_ANSWERS)),
54
174
  leaves: audits
55
175
  .filter((audit) => audit.placement.outcome === "probed" && !audit.placement.rendersChildren)
56
176
  .map((audit) => audit.type),
57
- throwsOnDeclaredProps: audits.flatMap((audit) => throwingIn(audit.type, audit.placement)),
177
+ throwsOnDeclaredProps: probed.flatMap((entry) => throwingIn(entry.primitive, entry.audit.placement)),
58
178
  };
59
179
  };
60
180
  /**
@@ -121,8 +241,47 @@ const describeSubmission = (entry) => {
121
241
  }
122
242
  return entry.declaresSubmits ? "; declares `submits` and places no address" : "";
123
243
  };
244
+ const describeDeclaration = (declaration) => typeof declaration === "string"
245
+ ? `\`${declaration}\``
246
+ : `whatever its \`${declaration.fromProp}\` prop says, or \`${declaration.default}\` where it says nothing`;
247
+ /**
248
+ * Said only when there is something to say, and said before the answers clause
249
+ * because it is the stronger of the two: an unanswered binding makes the
250
+ * clauses above describe one branch of a primitive, and no accepted
251
+ * configuration at all makes them describe a call no tree could make (0267).
252
+ */
253
+ const describeConfiguration = (unconfigured) => {
254
+ if (unconfigured === undefined)
255
+ return "";
256
+ const requires = unconfigured.required.length === 0
257
+ ? "requires props"
258
+ : `requires \`${unconfigured.required.join("`, `")}\``;
259
+ const handed = unconfigured.reason === "no-props"
260
+ ? "was handed none"
261
+ : "was handed none its schema accepts";
262
+ return `; ${requires} and ${handed}, so nothing above is a claim about this component`;
263
+ };
264
+ /**
265
+ * Said only when there is something to say, like `describeSubmission`, and said
266
+ * last because it is the one clause that is not an observation. The clauses
267
+ * before it may be describing this primitive's unanswered branch, and a reader
268
+ * fixing something needs to know that before believing them.
269
+ */
270
+ const describeAnswers = (unanswered) => {
271
+ if (unanswered === undefined)
272
+ return "";
273
+ const reads = unanswered.reads.map(describeDeclaration).join(", ");
274
+ const cause = unanswered.reason === "no-answers"
275
+ ? "was probed with no answer"
276
+ : "was handed no answer under a name it reads";
277
+ return `; reads ${reads} and ${cause}, so what it draws only when answered was never probed`;
278
+ };
124
279
  /** One line per primitive, for a CLI or a failing test's message. */
125
- export const describeRegistryAudit = (audit) => audit.audits
126
- .map((entry) => `${entry.type}: ${describeVerdict(entry.verdict)}; ${describePlacement(entry.placement)}${describeSubmission(entry)}`)
127
- .join("\n");
280
+ export const describeRegistryAudit = (audit) => {
281
+ const unanswered = new Map(audit.notAnswered.map((entry) => [entry.type, entry]));
282
+ const unconfigured = new Map(audit.notConfigured.map((entry) => [entry.type, entry]));
283
+ return audit.audits
284
+ .map((entry) => `${entry.type}: ${describeVerdict(entry.verdict)}; ${describePlacement(entry.placement)}${describeSubmission(entry)}${describeConfiguration(unconfigured.get(entry.type))}${describeAnswers(unanswered.get(entry.type))}`)
285
+ .join("\n");
286
+ };
128
287
  //# sourceMappingURL=audit.js.map
@@ -23,8 +23,16 @@ import type { PrimitiveRegistry } from "./registry.js";
23
23
  * `export type *` never carried them and `sdk.catalogueFields` is `undefined`.
24
24
  * Naming the three types the catalogue is made of says the true thing in a way
25
25
  * the generator reads correctly.
26
+ *
27
+ * `ClosedChoice` is the fourth and is not part of the catalogue — it is
28
+ * deliberately left out of one (`catalogue.ts` says why). It is here because
29
+ * two published signatures hold one: `PrimitiveEntry.choices` and
30
+ * `probeConfigurations`, so a host could pass one and read one and had no way
31
+ * to write the type of a function that takes one. `CataloguedProp` is the same
32
+ * kind of small projection and was already exported, which is what made the
33
+ * omission an oversight rather than a decision.
26
34
  */
27
- export type { CataloguedPrimitive, CataloguedProp, PrimitiveCatalogue } from "../catalogue.js";
35
+ export type { CataloguedPrimitive, CataloguedProp, ClosedChoice, PrimitiveCatalogue, } from "../catalogue.js";
28
36
  /**
29
37
  * The registry, projected into the catalogue other components read.
30
38
  *
@@ -30,7 +30,15 @@ import { type PaletteSlot } from "../theme/theme.js";
30
30
  * `registry.ts` never calls a primitive. Enforcement is the host's call, which
31
31
  * is why the verdict is a value.
32
32
  */
33
- /** A configuration the schema accepts that the component threw on. */
33
+ /**
34
+ * A configuration the probe built that the component threw on.
35
+ *
36
+ * Built *from* the schema, which is not the same as accepted *by* it: the
37
+ * default configuration is `{}`, and a primitive with a required prop refuses
38
+ * that (0267). Whether a failure here is a fault of the component is
39
+ * `auditRegistry`'s partition, because the validator it needs lives on the
40
+ * registration rather than in this module.
41
+ */
34
42
  export type ProbeFailure = {
35
43
  readonly props: JsonObject;
36
44
  readonly reason: string;
@@ -133,6 +141,27 @@ export type ProbeAnswers = {
133
141
  * that way, and a primitive that were would be one nobody can read.
134
142
  */
135
143
  export declare const probeConfigurations: (choices: readonly ClosedChoice[]) => readonly JsonObject[];
144
+ /**
145
+ * The same, from props a caller supplied rather than from nothing (0267).
146
+ *
147
+ * `probeConfigurations` starts from `{}`, which is a props bag the schema of any
148
+ * primitive with a required prop refuses — thirty-two of the hundred and seven
149
+ * starter primitives, where it is every configuration the probe builds. Those
150
+ * primitives answer anyway, because handing React a missing prop renders
151
+ * nothing; the first one to *read* a required prop throws, and a throw under a
152
+ * bag no valid tree can carry is not a fault of the component.
153
+ *
154
+ * A base is **supplied, not derived**, for the reason `ProbeAnswers` is: a
155
+ * required `z.string().min(1)` has no value the probe can read off the schema,
156
+ * and one it invented would make everything downstream a function of the guess.
157
+ * Whoever registered the primitive knows a bag it accepts.
158
+ *
159
+ * Each base is varied by each closed choice in turn — the sum again, not the
160
+ * product — so a caller who hands one bag gets that bag and that bag under
161
+ * every value its schema closes over, which is what 0075 asks for and what `{}`
162
+ * could not deliver for a primitive that requires anything.
163
+ */
164
+ export declare const probeConfigurationsFrom: (bases: readonly JsonObject[], choices: readonly ClosedChoice[]) => readonly JsonObject[];
136
165
  /**
137
166
  * The states a primitive is probed in: what its schema closes over, then what
138
167
  * its registrant declared it can be answered with (0185).
@@ -213,8 +242,13 @@ export type PlacementVerdict = {
213
242
  /**
214
243
  * Configurations built from the primitive's own schema that it threw on.
215
244
  * Never a reason to distrust the verdict — the configurations that
216
- * answered still answered — and always a fault: a component that throws
217
- * on a value its schema accepts is one a valid tree can crash a page with.
245
+ * answered still answered.
246
+ *
247
+ * A fault for every one of them its schema **accepts**, which is the
248
+ * partition `auditRegistry` makes and this module cannot: a component that
249
+ * throws on a value its schema accepts is one a valid tree can crash a
250
+ * page with, and one that throws on the empty bag it requires props
251
+ * against is a component nobody has handed props to yet (0267).
218
252
  */
219
253
  readonly threw: readonly ProbeFailure[];
220
254
  } | NotProbeable;
@@ -89,10 +89,31 @@ const namesIn = (data) => {
89
89
  * particular values together is not found. Nothing in the library is shaped
90
90
  * that way, and a primitive that were would be one nobody can read.
91
91
  */
92
- export const probeConfigurations = (choices) => [
93
- {},
94
- ...choices.flatMap(({ name, options }) => options.map((option) => ({ [name]: option }))),
95
- ];
92
+ export const probeConfigurations = (choices) => probeConfigurationsFrom([{}], choices);
93
+ /**
94
+ * The same, from props a caller supplied rather than from nothing (0267).
95
+ *
96
+ * `probeConfigurations` starts from `{}`, which is a props bag the schema of any
97
+ * primitive with a required prop refuses — thirty-two of the hundred and seven
98
+ * starter primitives, where it is every configuration the probe builds. Those
99
+ * primitives answer anyway, because handing React a missing prop renders
100
+ * nothing; the first one to *read* a required prop throws, and a throw under a
101
+ * bag no valid tree can carry is not a fault of the component.
102
+ *
103
+ * A base is **supplied, not derived**, for the reason `ProbeAnswers` is: a
104
+ * required `z.string().min(1)` has no value the probe can read off the schema,
105
+ * and one it invented would make everything downstream a function of the guess.
106
+ * Whoever registered the primitive knows a bag it accepts.
107
+ *
108
+ * Each base is varied by each closed choice in turn — the sum again, not the
109
+ * product — so a caller who hands one bag gets that bag and that bag under
110
+ * every value its schema closes over, which is what 0075 asks for and what `{}`
111
+ * could not deliver for a primitive that requires anything.
112
+ */
113
+ export const probeConfigurationsFrom = (bases, choices) => bases.flatMap((base) => [
114
+ base,
115
+ ...choices.flatMap(({ name, options }) => options.map((option) => ({ ...base, [name]: option }))),
116
+ ]);
96
117
  /**
97
118
  * The states a primitive is probed in: what its schema closes over, then what
98
119
  * its registrant declared it can be answered with (0185).
@@ -6,6 +6,7 @@ import type { BehaviourName } from "../render/behaviour.js";
6
6
  import type { LoomPrimitive } from "../render/primitive.js";
7
7
  import type { PropsVerdict } from "../render/props.js";
8
8
  import type { BindingDeclaration } from "../render/reads.js";
9
+ import type { UnshownDeclaration } from "../render/unshown.js";
9
10
  import { type PrimitiveText } from "../render/text.js";
10
11
  import type { PrimitiveRole } from "../role.js";
11
12
  /**
@@ -54,6 +55,10 @@ import type { PrimitiveRole } from "../role.js";
54
55
  * primitive never reads (0181). Each entry is a fixed name or the name a prop
55
56
  * gives (0184). Optional, and the second declaration where leaving it out and
56
57
  * declaring it empty differ.
58
+ * - `unshown` — its own reading of the answers it was given, so the walk can say
59
+ * that eleven of twelve rows arrived and were not drawn (0206). The only
60
+ * declaration here that is a function, because how many rows survived a shape
61
+ * is not data about a primitive. Optional, and read at render time.
57
62
  */
58
63
  export type PrimitiveDefinition<TProps extends JsonObjectView = JsonObject, TText extends string = never, TBehaviour extends BehaviourName = never> = {
59
64
  readonly type: string;
@@ -115,6 +120,28 @@ export type PrimitiveDefinition<TProps extends JsonObjectView = JsonObject, TTex
115
120
  * `interactive` or the Gate will let one sit inside an anchor.
116
121
  */
117
122
  readonly behaviours?: readonly TBehaviour[];
123
+ /**
124
+ * The prop each control takes its name from — `{ present: "label" }` on a
125
+ * dialog whose trigger carries the page's own call to action.
126
+ *
127
+ * Optional, and absent for almost every primitive that takes a control at all.
128
+ * A control's name is normally a string this primitive declares, which is what
129
+ * makes *Copy* the same word on every code panel in a deployment and lets one
130
+ * dictionary translate all of them. This is the exception for the control whose
131
+ * words are **content**: a trigger that opens a dialog says *Watch the demo*,
132
+ * the next one says *Book a call*, and neither is a fact about the primitive or
133
+ * a thing a translator should hold.
134
+ *
135
+ * Three checks follow, and the first two are the registry's. The behaviour must
136
+ * be one this primitive declared, and the prop must be one its schema declares
137
+ * — the same drift `frames` and `interactive` are checked against, failing the
138
+ * same silent way: a prop renamed and a declaration left pointing at nothing
139
+ * would quietly go back to the declared string for ever. The third is not a
140
+ * check but a property: the declared text is still required, so the control has
141
+ * a name in every language before any node is written, and a node that fills
142
+ * the prop with nothing gets it.
143
+ */
144
+ readonly names?: Readonly<Partial<Record<TBehaviour, string>>>;
118
145
  /**
119
146
  * What part this primitive plays — `"heading"` on anything a reader takes as
120
147
  * the title of what follows, whatever it is called. Optional, and absent on
@@ -181,6 +208,32 @@ export type PrimitiveDefinition<TProps extends JsonObjectView = JsonObject, TTex
181
208
  * so a declaration cannot go on naming a prop that was renamed away.
182
209
  */
183
210
  readonly reads?: readonly BindingDeclaration[];
211
+ /**
212
+ * What this primitive made of each answer it was given: the rows it found and
213
+ * the rows it placed. The walk reports the ones where those differ.
214
+ *
215
+ * The one way a binding can be wrong that nothing outside the component can
216
+ * see. A source can answer perfectly, under a name the primitive reads, with
217
+ * rows the primitive then declines one at a time — because a row's shape is
218
+ * the primitive's own, and eleven of twelve failing it is the author's problem
219
+ * and nobody else's. The reader is told without a count (0175); this is how
220
+ * the author is told with one (0206).
221
+ *
222
+ * A function, where everything above is data, and that is the honest shape
223
+ * rather than a shortcut. `reads` is a list of names, and a name is data —
224
+ * which is why it has a `fromProp` form instead of a callback (0184). A count
225
+ * of rows that survived a schema is not data about a primitive; it is the
226
+ * primitive reading an answer, and the primitive already contains that code,
227
+ * because it had to decide what to skip in order to skip it. Declare the
228
+ * function the component calls and the two cannot disagree.
229
+ *
230
+ * Pure, synchronous, and handed exactly what the component is handed of the
231
+ * same two things. It may not throw and may not return a reading that cannot
232
+ * describe an answer; both are caught and reported as
233
+ * `unshown-unreadable` against the primitive rather than allowed to cost the
234
+ * page, because rendering is total.
235
+ */
236
+ readonly unshown?: UnshownDeclaration;
184
237
  readonly component: LoomPrimitive<TProps, TText, TBehaviour>;
185
238
  };
186
239
  /**
@@ -212,6 +265,12 @@ export type PrimitiveEntry = {
212
265
  readonly frames: readonly string[];
213
266
  /** Declared behaviour names, still raw: the registry is what checks them. */
214
267
  readonly behaviours: readonly string[];
268
+ /**
269
+ * Which prop names which control, still raw: the registry is what checks that
270
+ * both halves of each pair exist. Empty for the primitive that named none,
271
+ * which is almost all of them.
272
+ */
273
+ readonly names: Readonly<Record<string, string>>;
215
274
  /**
216
275
  * The declared role, still raw: the registry is what checks it, for the same
217
276
  * reason it checks a behaviour name. `undefined` for the primitive that plays
@@ -230,6 +289,12 @@ export type PrimitiveEntry = {
230
289
  * two mean different things here and all the way out to the render walk.
231
290
  */
232
291
  readonly reads: readonly BindingDeclaration[] | undefined;
292
+ /**
293
+ * The declared reading of this node's answers, or `undefined` where the author
294
+ * has not said. Nothing to check at registration — there are no names in it
295
+ * and no props it could name — so it is carried straight through.
296
+ */
297
+ readonly unshown: UnshownDeclaration | undefined;
233
298
  readonly validate: (props: JsonObject) => PropsVerdict;
234
299
  };
235
300
  /**
@@ -15,6 +15,26 @@ const freezeText = (text) => {
15
15
  copy[key] = value;
16
16
  return Object.freeze(copy);
17
17
  };
18
+ /**
19
+ * The raw declaration for a primitive that named no control. Null-prototype for
20
+ * the reason `NO_TEXT` gives: a lookup under `constructor` must answer nothing.
21
+ */
22
+ const NO_NAMES = Object.freeze(Object.create(null));
23
+ /**
24
+ * Declared control names, copied and frozen for `freezeText`'s reason: the
25
+ * caller keeps the literal it passed, and an entry sharing it is one mutation
26
+ * away from a rendered page's buttons changing under it.
27
+ */
28
+ const freezeNames = (names) => {
29
+ if (!names)
30
+ return NO_NAMES;
31
+ const copy = Object.create(null);
32
+ for (const [behaviour, prop] of Object.entries(names)) {
33
+ if (prop !== undefined)
34
+ copy[behaviour] = prop;
35
+ }
36
+ return Object.freeze(copy);
37
+ };
18
38
  const toIssue = (issue) => ({
19
39
  path: issue.path.length === 0 ? "props" : issue.path.map(String).join("."),
20
40
  message: issue.message,
@@ -45,9 +65,11 @@ export const definePrimitive = (definition) => ({
45
65
  submits: definition.submits ?? false,
46
66
  frames: definition.frames ?? [],
47
67
  behaviours: definition.behaviours ?? [],
68
+ names: freezeNames(definition.names),
48
69
  role: definition.role,
49
70
  copy: definition.copy,
50
71
  reads: definition.reads,
72
+ unshown: definition.unshown,
51
73
  /**
52
74
  * The one narrowing cast in the SDK, and the invariant that makes it sound:
53
75
  * a registry hands the renderer this component and the validator built from
@@ -3,12 +3,14 @@ import type { InteractiveWhen } from "../interactivity.js";
3
3
  import type { JsonObject } from "../json.js";
4
4
  import { type PrimitiveType, type SlotName } from "../primitive-type.js";
5
5
  import { type Result } from "../result.js";
6
- import { type BehaviourName, type BehaviourResolver } from "../render/behaviour.js";
6
+ import { type BehaviourName, type BehaviourResolver, type ControlNameProps } from "../render/behaviour.js";
7
7
  import type { FrameResolver } from "../render/frame.js";
8
8
  import type { BindingDeclaration, BindingReader } from "../render/reads.js";
9
+ import type { UnshownDeclaration, UnshownReader } from "../render/unshown.js";
9
10
  import type { LoomPrimitive, PrimitiveResolver } from "../render/primitive.js";
10
11
  import type { PropsValidator, PropsVerdict } from "../render/props.js";
11
12
  import { type PrimitiveText, type TextResolver } from "../render/text.js";
13
+ import type { SlotPlacer } from "../render/slots.js";
12
14
  import { type PrimitiveRole } from "../role.js";
13
15
  import type { CopyDeclarations } from "./copy.js";
14
16
  import type { PrimitiveEntry } from "./definition.js";
@@ -53,6 +55,13 @@ export type RegisteredPrimitive = {
53
55
  readonly frames: readonly string[];
54
56
  /** The controls it takes from the runtime's vocabulary. Empty for most. */
55
57
  readonly behaviours: readonly BehaviourName[];
58
+ /**
59
+ * The prop each of those controls is named by, where its author said so
60
+ * (0234). Empty for almost every primitive that takes a control at all: a
61
+ * control's name is normally a string the primitive declared, and this is the
62
+ * exception for the trigger whose words are the page's.
63
+ */
64
+ readonly names: ControlNameProps;
56
65
  /** What part it plays (0114). `undefined` for most, which play none. */
57
66
  readonly role: PrimitiveRole | undefined;
58
67
  /**
@@ -68,6 +77,14 @@ export type RegisteredPrimitive = {
68
77
  * walk reports under the first and stays quiet under the second.
69
78
  */
70
79
  readonly reads: readonly BindingDeclaration<BindingName>[] | undefined;
80
+ /**
81
+ * Its own reading of the answers it was given (0206). `undefined` where the
82
+ * author has not said, which here is the same answer as declaring one that
83
+ * reports nothing — unlike `copy` and `reads`, because there is no emptiness
84
+ * to distinguish: a reading is made per answer at render time, and a primitive
85
+ * that has said nothing about its answers is reported on by nothing.
86
+ */
87
+ readonly unshown: UnshownDeclaration | undefined;
71
88
  readonly validate: (props: JsonObject) => PropsVerdict;
72
89
  };
73
90
  export type RegistryError = {
@@ -115,6 +132,16 @@ export type RegistryError = {
115
132
  readonly type: string;
116
133
  readonly behaviour: string;
117
134
  readonly requires: string;
135
+ } | {
136
+ readonly code: "undeclared-named-behaviour";
137
+ readonly type: string;
138
+ readonly behaviour: string;
139
+ readonly prop: string;
140
+ } | {
141
+ readonly code: "undeclared-control-name-prop";
142
+ readonly type: string;
143
+ readonly behaviour: string;
144
+ readonly prop: string;
118
145
  } | {
119
146
  readonly code: "unknown-role";
120
147
  readonly type: string;
@@ -131,7 +158,7 @@ export type RegistryError = {
131
158
  readonly code: "duplicate-primitive-type";
132
159
  readonly type: string;
133
160
  };
134
- export type PrimitiveRegistry = PrimitiveResolver & PropsValidator & TextResolver & BehaviourResolver & FrameResolver & BindingReader & CopyDeclarations & {
161
+ export type PrimitiveRegistry = PrimitiveResolver & PropsValidator & TextResolver & BehaviourResolver & FrameResolver & BindingReader & SlotPlacer & UnshownReader & CopyDeclarations & {
135
162
  /** In registration order, so a catalogue and an audit read predictably. */
136
163
  readonly primitives: readonly RegisteredPrimitive[];
137
164
  /**