@jam-overture/loom 0.1.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 (414) 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/audience/compose.d.ts +112 -0
  11. package/dist/audience/compose.js +134 -0
  12. package/dist/audience/memory.d.ts +14 -0
  13. package/dist/audience/memory.js +71 -0
  14. package/dist/audience/overlay-store.d.ts +343 -0
  15. package/dist/audience/overlay-store.js +217 -0
  16. package/dist/audience/rule.d.ts +121 -0
  17. package/dist/audience/rule.js +78 -0
  18. package/dist/cli/index.d.ts +3 -4
  19. package/dist/cli/index.js +3 -4
  20. package/dist/cli/templates.js +19 -0
  21. package/dist/data/adapter.d.ts +9 -1
  22. package/dist/data/adapter.js +2 -0
  23. package/dist/data/plan.js +0 -0
  24. package/dist/data/resolution.d.ts +23 -1
  25. package/dist/data/resolve.d.ts +31 -4
  26. package/dist/data/resolve.js +11 -3
  27. package/dist/ids.d.ts +10 -0
  28. package/dist/ids.js +11 -1
  29. package/dist/index.d.ts +1 -0
  30. package/dist/index.js +1 -0
  31. package/dist/interpretation/anthropic.d.ts +1 -1
  32. package/dist/interpretation/anthropic.js +2 -22
  33. package/dist/interpretation/client.d.ts +1 -1
  34. package/dist/interpretation/materialize.js +67 -22
  35. package/dist/interpretation/openai-compatible.d.ts +36 -0
  36. package/dist/interpretation/openai-compatible.js +79 -0
  37. package/dist/interpretation/status.d.ts +19 -0
  38. package/dist/interpretation/status.js +26 -0
  39. package/dist/live/index.d.ts +73 -0
  40. package/dist/live/index.js +73 -0
  41. package/dist/live/pages.d.ts +187 -0
  42. package/dist/live/pages.js +161 -0
  43. package/dist/live/pull.d.ts +147 -0
  44. package/dist/live/pull.js +398 -0
  45. package/dist/live/pulling.d.ts +79 -0
  46. package/dist/live/pulling.js +117 -0
  47. package/dist/live/window.d.ts +129 -0
  48. package/dist/live/window.js +132 -0
  49. package/dist/patch.d.ts +54 -0
  50. package/dist/patch.js +44 -0
  51. package/dist/project/closing.d.ts +51 -0
  52. package/dist/project/closing.js +53 -0
  53. package/dist/project/memory.d.ts +20 -0
  54. package/dist/project/memory.js +97 -0
  55. package/dist/project/project.d.ts +90 -0
  56. package/dist/project/project.js +91 -0
  57. package/dist/project/store.d.ts +135 -0
  58. package/dist/project/store.js +41 -0
  59. package/dist/registered.d.ts +64 -0
  60. package/dist/registered.js +118 -0
  61. package/dist/render/addressed.d.ts +35 -0
  62. package/dist/render/addressed.js +79 -0
  63. package/dist/render/behaviour-adjust.d.ts +11 -19
  64. package/dist/render/behaviour-adjust.js +75 -21
  65. package/dist/render/behaviour-present.d.ts +8 -0
  66. package/dist/render/behaviour-present.js +57 -6
  67. package/dist/render/behaviour.d.ts +98 -17
  68. package/dist/render/behaviour.js +91 -26
  69. package/dist/render/control-name.d.ts +68 -0
  70. package/dist/render/control-name.js +37 -0
  71. package/dist/render/diagnostics.d.ts +72 -0
  72. package/dist/render/diagnostics.js +7 -0
  73. package/dist/render/document-theme.d.ts +70 -0
  74. package/dist/render/document-theme.js +139 -0
  75. package/dist/render/editable.d.ts +15 -1
  76. package/dist/render/editable.js +13 -1
  77. package/dist/render/expected.d.ts +98 -0
  78. package/dist/render/expected.js +88 -0
  79. package/dist/render/index.d.ts +4 -0
  80. package/dist/render/index.js +4 -0
  81. package/dist/render/reads.d.ts +11 -0
  82. package/dist/render/reads.js +12 -1
  83. package/dist/render/render.d.ts +11 -0
  84. package/dist/render/render.js +294 -53
  85. package/dist/render/request.d.ts +8 -1
  86. package/dist/render/request.js +1 -0
  87. package/dist/render/slots.d.ts +52 -0
  88. package/dist/render/slots.js +24 -0
  89. package/dist/render/theme.d.ts +54 -1
  90. package/dist/render/theme.js +23 -1
  91. package/dist/render/unshown.d.ts +152 -0
  92. package/dist/render/unshown.js +80 -0
  93. package/dist/runtime/analysis.d.ts +94 -9
  94. package/dist/runtime/analysis.js +54 -9
  95. package/dist/runtime/assessment.d.ts +36 -2
  96. package/dist/runtime/assessment.js +27 -2
  97. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  98. package/dist/runtime/auto-apply-ceiling.js +66 -0
  99. package/dist/runtime/checks.d.ts +148 -0
  100. package/dist/runtime/checks.js +112 -0
  101. package/dist/runtime/disposition.d.ts +96 -0
  102. package/dist/runtime/disposition.js +46 -0
  103. package/dist/runtime/gate.js +91 -10
  104. package/dist/runtime/index.d.ts +4 -0
  105. package/dist/runtime/index.js +4 -0
  106. package/dist/runtime/irreversibility.d.ts +64 -0
  107. package/dist/runtime/irreversibility.js +45 -0
  108. package/dist/runtime/nesting.d.ts +13 -1
  109. package/dist/runtime/nesting.js +41 -24
  110. package/dist/runtime/pipeline.d.ts +43 -0
  111. package/dist/runtime/pipeline.js +10 -2
  112. package/dist/runtime/policy-change.d.ts +93 -0
  113. package/dist/runtime/policy-change.js +305 -0
  114. package/dist/runtime/policy-log.d.ts +406 -0
  115. package/dist/runtime/policy-log.js +285 -0
  116. package/dist/runtime/policy.d.ts +8 -6
  117. package/dist/runtime/policy.js +5 -2
  118. package/dist/runtime/repointing.js +0 -0
  119. package/dist/runtime/reversibility.d.ts +11 -9
  120. package/dist/runtime/stakes.d.ts +129 -1
  121. package/dist/runtime/stakes.js +240 -26
  122. package/dist/runtime/vocabulary.d.ts +164 -7
  123. package/dist/runtime/vocabulary.js +181 -8
  124. package/dist/sdk/audit.d.ts +174 -3
  125. package/dist/sdk/audit.js +176 -17
  126. package/dist/sdk/catalogue.d.ts +9 -1
  127. package/dist/sdk/conformance.d.ts +37 -3
  128. package/dist/sdk/conformance.js +25 -4
  129. package/dist/sdk/definition.d.ts +129 -5
  130. package/dist/sdk/definition.js +66 -0
  131. package/dist/sdk/registry.d.ts +45 -2
  132. package/dist/sdk/registry.js +102 -1
  133. package/dist/signals/acted.contract.d.ts +21 -0
  134. package/dist/signals/acted.contract.js +236 -0
  135. package/dist/signals/acted.d.ts +359 -0
  136. package/dist/signals/acted.js +135 -0
  137. package/dist/signals/action-change.d.ts +507 -0
  138. package/dist/signals/action-change.js +265 -0
  139. package/dist/signals/action.d.ts +331 -0
  140. package/dist/signals/action.js +182 -0
  141. package/dist/signals/agenda.d.ts +585 -0
  142. package/dist/signals/agenda.js +295 -0
  143. package/dist/signals/applied-window.contract.d.ts +23 -0
  144. package/dist/signals/applied-window.contract.js +160 -0
  145. package/dist/signals/arrivals.contract.d.ts +21 -0
  146. package/dist/signals/arrivals.contract.js +180 -0
  147. package/dist/signals/arrivals.d.ts +375 -0
  148. package/dist/signals/arrivals.js +254 -0
  149. package/dist/signals/arriving.d.ts +210 -0
  150. package/dist/signals/arriving.js +133 -0
  151. package/dist/signals/audiences.d.ts +528 -0
  152. package/dist/signals/audiences.js +255 -0
  153. package/dist/signals/broadcast.d.ts +33 -17
  154. package/dist/signals/broadcast.js +255 -32
  155. package/dist/signals/change.d.ts +378 -0
  156. package/dist/signals/change.js +327 -0
  157. package/dist/signals/collect.d.ts +169 -34
  158. package/dist/signals/collect.js +186 -38
  159. package/dist/signals/conversion.d.ts +348 -0
  160. package/dist/signals/conversion.js +235 -0
  161. package/dist/signals/copy-change.d.ts +553 -0
  162. package/dist/signals/copy-change.js +377 -0
  163. package/dist/signals/copy.d.ts +337 -0
  164. package/dist/signals/copy.js +211 -0
  165. package/dist/signals/correlated.contract.d.ts +24 -0
  166. package/dist/signals/correlated.contract.js +94 -0
  167. package/dist/signals/counters.d.ts +97 -0
  168. package/dist/signals/counters.js +160 -0
  169. package/dist/signals/deliver.d.ts +23 -4
  170. package/dist/signals/deliver.js +34 -6
  171. package/dist/signals/deployment-change.d.ts +395 -0
  172. package/dist/signals/deployment-change.js +309 -0
  173. package/dist/signals/deployment.d.ts +278 -0
  174. package/dist/signals/deployment.js +178 -0
  175. package/dist/signals/door.d.ts +114 -0
  176. package/dist/signals/door.js +77 -0
  177. package/dist/signals/expire.d.ts +192 -0
  178. package/dist/signals/expire.js +213 -0
  179. package/dist/signals/fold.d.ts +10 -0
  180. package/dist/signals/fold.js +5 -1
  181. package/dist/signals/form-action.d.ts +302 -0
  182. package/dist/signals/form-action.js +169 -0
  183. package/dist/signals/form-copy.d.ts +523 -0
  184. package/dist/signals/form-copy.js +346 -0
  185. package/dist/signals/forms.d.ts +247 -0
  186. package/dist/signals/forms.js +147 -0
  187. package/dist/signals/frontier.d.ts +268 -0
  188. package/dist/signals/frontier.js +145 -0
  189. package/dist/signals/funnel-change.d.ts +548 -0
  190. package/dist/signals/funnel-change.js +361 -0
  191. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  192. package/dist/signals/funnel-hours.contract.js +221 -0
  193. package/dist/signals/funnel-hours.d.ts +293 -0
  194. package/dist/signals/funnel-hours.js +99 -0
  195. package/dist/signals/funnel.d.ts +592 -0
  196. package/dist/signals/funnel.js +231 -0
  197. package/dist/signals/health.d.ts +694 -0
  198. package/dist/signals/health.js +573 -0
  199. package/dist/signals/index.d.ts +60 -0
  200. package/dist/signals/index.js +60 -0
  201. package/dist/signals/ingest.d.ts +56 -1
  202. package/dist/signals/ingest.js +91 -1
  203. package/dist/signals/inside.d.ts +190 -0
  204. package/dist/signals/inside.js +263 -0
  205. package/dist/signals/join.d.ts +56 -0
  206. package/dist/signals/join.js +60 -0
  207. package/dist/signals/journal.d.ts +123 -9
  208. package/dist/signals/kept.contract.d.ts +22 -0
  209. package/dist/signals/kept.contract.js +111 -0
  210. package/dist/signals/kinds.d.ts +8 -6
  211. package/dist/signals/kinds.js +14 -6
  212. package/dist/signals/library-action.d.ts +430 -0
  213. package/dist/signals/library-action.js +336 -0
  214. package/dist/signals/library-agenda-change.d.ts +324 -0
  215. package/dist/signals/library-agenda-change.js +199 -0
  216. package/dist/signals/library-agenda.d.ts +258 -0
  217. package/dist/signals/library-agenda.js +167 -0
  218. package/dist/signals/library-change.d.ts +477 -0
  219. package/dist/signals/library-change.js +335 -0
  220. package/dist/signals/library-copy-change.d.ts +498 -0
  221. package/dist/signals/library-copy-change.js +476 -0
  222. package/dist/signals/library-pace.d.ts +319 -0
  223. package/dist/signals/library-pace.js +305 -0
  224. package/dist/signals/library-reach-change.d.ts +646 -0
  225. package/dist/signals/library-reach-change.js +542 -0
  226. package/dist/signals/library-reach.d.ts +377 -0
  227. package/dist/signals/library-reach.js +227 -0
  228. package/dist/signals/library-senders-change.d.ts +457 -0
  229. package/dist/signals/library-senders-change.js +367 -0
  230. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  231. package/dist/signals/library-senders-reach-change.js +538 -0
  232. package/dist/signals/library-senders-reach.d.ts +340 -0
  233. package/dist/signals/library-senders-reach.js +252 -0
  234. package/dist/signals/library-senders.d.ts +271 -0
  235. package/dist/signals/library-senders.js +180 -0
  236. package/dist/signals/library-word-reach-change.d.ts +567 -0
  237. package/dist/signals/library-word-reach-change.js +564 -0
  238. package/dist/signals/library.d.ts +306 -0
  239. package/dist/signals/library.js +178 -0
  240. package/dist/signals/memory.d.ts +9 -0
  241. package/dist/signals/memory.js +246 -14
  242. package/dist/signals/migrate.d.ts +20 -4
  243. package/dist/signals/migrate.js +269 -8
  244. package/dist/signals/notice.d.ts +389 -0
  245. package/dist/signals/notice.js +250 -0
  246. package/dist/signals/pace-change.d.ts +501 -0
  247. package/dist/signals/pace-change.js +310 -0
  248. package/dist/signals/pace.d.ts +296 -0
  249. package/dist/signals/pace.js +291 -0
  250. package/dist/signals/page-views.d.ts +365 -0
  251. package/dist/signals/page-views.js +218 -0
  252. package/dist/signals/part-pace.d.ts +378 -0
  253. package/dist/signals/part-pace.js +333 -0
  254. package/dist/signals/parts.d.ts +354 -0
  255. package/dist/signals/parts.js +232 -0
  256. package/dist/signals/postgres.d.ts +16 -2
  257. package/dist/signals/postgres.js +753 -76
  258. package/dist/signals/progress.d.ts +212 -0
  259. package/dist/signals/progress.js +150 -0
  260. package/dist/signals/ratios.d.ts +108 -0
  261. package/dist/signals/ratios.js +40 -0
  262. package/dist/signals/reach.d.ts +309 -0
  263. package/dist/signals/reach.js +93 -0
  264. package/dist/signals/readable.d.ts +34 -0
  265. package/dist/signals/readable.js +34 -0
  266. package/dist/signals/readership.d.ts +381 -0
  267. package/dist/signals/readership.js +308 -0
  268. package/dist/signals/region-pages.d.ts +173 -0
  269. package/dist/signals/region-pages.js +62 -0
  270. package/dist/signals/region.d.ts +287 -0
  271. package/dist/signals/region.js +198 -0
  272. package/dist/signals/retention.d.ts +163 -0
  273. package/dist/signals/retention.js +75 -0
  274. package/dist/signals/rhythm.d.ts +302 -0
  275. package/dist/signals/rhythm.js +262 -0
  276. package/dist/signals/rollup.d.ts +194 -4
  277. package/dist/signals/rollup.js +0 -0
  278. package/dist/signals/schema.d.ts +1069 -1
  279. package/dist/signals/schema.js +393 -3
  280. package/dist/signals/signal.d.ts +237 -11
  281. package/dist/signals/signal.js +70 -10
  282. package/dist/signals/silence-census.d.ts +205 -0
  283. package/dist/signals/silence-census.js +87 -0
  284. package/dist/signals/silences.d.ts +1147 -0
  285. package/dist/signals/silences.js +996 -0
  286. package/dist/signals/subtrees.d.ts +123 -0
  287. package/dist/signals/subtrees.js +102 -0
  288. package/dist/signals/tally.d.ts +262 -12
  289. package/dist/signals/unread.d.ts +292 -0
  290. package/dist/signals/unread.js +137 -0
  291. package/dist/signals/window-agenda.d.ts +276 -0
  292. package/dist/signals/window-agenda.js +83 -0
  293. package/dist/signals/window-figures.d.ts +148 -0
  294. package/dist/signals/window-figures.js +42 -0
  295. package/dist/signals/window-funnels.d.ts +88 -0
  296. package/dist/signals/window-funnels.js +47 -0
  297. package/dist/signals/window.d.ts +866 -0
  298. package/dist/signals/window.js +693 -0
  299. package/dist/signals/words.d.ts +24 -0
  300. package/dist/signals/words.js +24 -0
  301. package/dist/store/cache.d.ts +101 -0
  302. package/dist/store/cache.js +149 -0
  303. package/dist/store/history.d.ts +82 -0
  304. package/dist/store/history.js +36 -0
  305. package/dist/store/index.d.ts +30 -0
  306. package/dist/store/index.js +30 -0
  307. package/dist/store/memory.d.ts +2 -1
  308. package/dist/store/memory.js +48 -12
  309. package/dist/store/migrate.d.ts +106 -0
  310. package/dist/store/migrate.js +323 -7
  311. package/dist/store/postgres-applications.d.ts +4 -0
  312. package/dist/store/postgres-applications.js +197 -0
  313. package/dist/store/postgres-audience.d.ts +14 -0
  314. package/dist/store/postgres-audience.js +272 -0
  315. package/dist/store/postgres-holds.d.ts +10 -1
  316. package/dist/store/postgres-holds.js +116 -101
  317. package/dist/store/postgres-policy-log.d.ts +14 -0
  318. package/dist/store/postgres-policy-log.js +240 -0
  319. package/dist/store/postgres-projects.d.ts +4 -0
  320. package/dist/store/postgres-projects.js +217 -0
  321. package/dist/store/postgres.d.ts +17 -1
  322. package/dist/store/postgres.js +60 -9
  323. package/dist/store/replay.d.ts +102 -1
  324. package/dist/store/replay.js +190 -19
  325. package/dist/store/reseed.d.ts +238 -0
  326. package/dist/store/reseed.js +308 -0
  327. package/dist/store/schema.d.ts +762 -2
  328. package/dist/store/schema.js +218 -5
  329. package/dist/store/source.d.ts +57 -1
  330. package/dist/store/source.js +65 -1
  331. package/dist/store/store.d.ts +29 -6
  332. package/dist/submit/resolve.d.ts +1 -1
  333. package/dist/submit/resolve.js +2 -1
  334. package/dist/telemetry/calibration.d.ts +25 -0
  335. package/dist/telemetry/calibration.js +27 -1
  336. package/dist/telemetry/event.d.ts +391 -33
  337. package/dist/telemetry/event.js +84 -20
  338. package/dist/telemetry/index.d.ts +2 -0
  339. package/dist/telemetry/index.js +2 -0
  340. package/dist/telemetry/journal.d.ts +104 -3
  341. package/dist/telemetry/journal.js +9 -0
  342. package/dist/telemetry/lookup.d.ts +27 -0
  343. package/dist/telemetry/lookup.js +18 -0
  344. package/dist/telemetry/memory.js +33 -1
  345. package/dist/telemetry/migrate.js +22 -1
  346. package/dist/telemetry/postgres.d.ts +10 -1
  347. package/dist/telemetry/postgres.js +188 -90
  348. package/dist/telemetry/remeasure.d.ts +78 -0
  349. package/dist/telemetry/remeasure.js +83 -0
  350. package/dist/telemetry/retention.d.ts +2 -2
  351. package/dist/telemetry/schema.d.ts +17 -0
  352. package/dist/telemetry/schema.js +27 -1
  353. package/dist/telemetry/sink.d.ts +2 -2
  354. package/dist/telemetry/window.d.ts +135 -0
  355. package/dist/telemetry/window.js +101 -0
  356. package/dist/testing/application-contract.d.ts +14 -0
  357. package/dist/testing/application-contract.js +270 -0
  358. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  359. package/dist/testing/audience-overlay-contract.js +354 -0
  360. package/dist/testing/contracts.d.ts +13 -7
  361. package/dist/testing/contracts.js +13 -7
  362. package/dist/testing/definitions.d.ts +78 -0
  363. package/dist/testing/definitions.js +134 -9
  364. package/dist/testing/doubles.d.ts +103 -0
  365. package/dist/testing/doubles.js +143 -0
  366. package/dist/testing/index.d.ts +2 -2
  367. package/dist/testing/index.js +2 -2
  368. package/dist/testing/journal-contract.js +297 -6
  369. package/dist/testing/model-contract.d.ts +110 -0
  370. package/dist/testing/model-contract.js +150 -0
  371. package/dist/testing/policy-log-contract.d.ts +26 -0
  372. package/dist/testing/policy-log-contract.js +344 -0
  373. package/dist/testing/project-contract.d.ts +14 -0
  374. package/dist/testing/project-contract.js +266 -0
  375. package/dist/testing/reader-signal-contract.d.ts +27 -2
  376. package/dist/testing/reader-signal-contract.js +475 -5
  377. package/dist/testing/store-contract.d.ts +7 -1
  378. package/dist/testing/store-contract.js +84 -3
  379. package/dist/theme/apply.d.ts +20 -1
  380. package/dist/theme/apply.js +5 -3
  381. package/dist/theme/contrast.d.ts +19 -14
  382. package/dist/theme/contrast.js +181 -17
  383. package/dist/theme/derive.d.ts +22 -0
  384. package/dist/theme/derive.js +54 -1
  385. package/dist/theme/library.js +1 -1
  386. package/dist/theme/measure.d.ts +34 -0
  387. package/dist/theme/measure.js +30 -1
  388. package/dist/theme/palettes.js +7 -7
  389. package/dist/theme/ramp.d.ts +64 -0
  390. package/dist/theme/ramp.js +114 -0
  391. package/dist/theme/registry.d.ts +9 -0
  392. package/dist/theme/registry.js +11 -1
  393. package/dist/theme/separation.d.ts +97 -3
  394. package/dist/theme/separation.js +75 -0
  395. package/dist/tree/apply.js +13 -0
  396. package/dist/tree/compare.d.ts +9 -0
  397. package/dist/tree/compare.js +18 -0
  398. package/dist/tree/mutation.d.ts +18 -0
  399. package/dist/tree/mutation.js +24 -12
  400. package/dist/tree/navigation.d.ts +5 -0
  401. package/dist/tree/navigation.js +32 -10
  402. package/dist/tree/outline.d.ts +7 -0
  403. package/dist/tree/outline.js +9 -5
  404. package/dist/write/computed.d.ts +60 -0
  405. package/dist/write/computed.js +61 -0
  406. package/dist/write/held.d.ts +59 -0
  407. package/dist/write/index.d.ts +5 -2
  408. package/dist/write/index.js +5 -2
  409. package/dist/write/reseed.d.ts +151 -0
  410. package/dist/write/reseed.js +184 -0
  411. package/dist/write/revert.js +2 -16
  412. package/package.json +25 -3
  413. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  414. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -17,7 +17,13 @@ import { sampleTree } from "./fixtures.js";
17
17
  * implementation — how it reports a connection failure, what it exposes beyond
18
18
  * the interface — stays in that implementation's own test file.
19
19
  */
20
- export const appendOf = (delta, proposal = "p_1") => ({
20
+ export const appendOf = (delta, proposal = "p_1",
21
+ /**
22
+ * When the runtime applied it. Defaulted, because almost every case here is
23
+ * about what a store does with a delta rather than when; named by the cases
24
+ * that are, which cannot be written at all if every append shares one stamp.
25
+ */
26
+ appliedAt = FIXED_INSTANT) => ({
21
27
  proposalId: proposal,
22
28
  delta,
23
29
  provenance: {
@@ -27,7 +33,7 @@ export const appendOf = (delta, proposal = "p_1") => ({
27
33
  confidence: 0.9,
28
34
  interpretedAt: FIXED_INSTANT,
29
35
  },
30
- appliedAt: FIXED_INSTANT,
36
+ appliedAt,
31
37
  });
32
38
  export const removalOf = (tree, nodeId, baseRevision = tree.revision) => ({
33
39
  deltaId: sequentialIdFactory("s").deltaId(),
@@ -197,7 +203,10 @@ export const describeTreeStoreContract = (name, makeStore) => {
197
203
  await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer)));
198
204
  expect((await store.list()).ok && (await store.list())).toEqual({
199
205
  ok: true,
200
- value: { trees: [{ treeId: tree.treeId, revision: 1 }], cursor: null },
206
+ value: {
207
+ trees: [{ treeId: tree.treeId, revision: 1, changedAt: FIXED_INSTANT }],
208
+ cursor: null,
209
+ },
201
210
  });
202
211
  });
203
212
  it("is empty with a null cursor when nothing is stored", async () => {
@@ -244,6 +253,78 @@ export const describeTreeStoreContract = (name, makeStore) => {
244
253
  const page = await store.list({ limit: 0 });
245
254
  expect(page.ok && page.value.trees).toHaveLength(1);
246
255
  });
256
+ /**
257
+ * The half of the listing's rejected recency ordering that shipped: the
258
+ * fact, not the order (0020, 0277). These five cases are what make it a
259
+ * fact rather than a convenience — the stamp has to be the log's own, and
260
+ * the absence has to mean one thing.
261
+ */
262
+ describe("when each page last changed", () => {
263
+ it("says nothing about a tree that has never been changed", async () => {
264
+ const store = await freshStore();
265
+ await store.create(treeNamed("a"));
266
+ const page = await store.list();
267
+ const listing = page.ok ? page.value.trees[0] : undefined;
268
+ expect(listing?.revision).toBe(0);
269
+ expect(listing && "changedAt" in listing).toBe(false);
270
+ });
271
+ it("reports the stamp the append was given, not the time of the read", async () => {
272
+ const { tree, ids } = sampleTree();
273
+ const store = await freshStore();
274
+ await store.create(tree);
275
+ await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer), "p_1", "2026-03-02T11:12:13.000Z"));
276
+ const page = await store.list();
277
+ expect(page.ok && page.value.trees[0]?.changedAt).toBe("2026-03-02T11:12:13.000Z");
278
+ });
279
+ it("moves to the newest entry's stamp as the log grows", async () => {
280
+ const { tree, ids } = sampleTree();
281
+ const store = await freshStore();
282
+ await store.create(tree);
283
+ await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer), "p_1", "2026-03-02T11:12:13.000Z"));
284
+ const first = await store.list();
285
+ expect(first.ok && first.value.trees[0]?.changedAt).toBe("2026-03-02T11:12:13.000Z");
286
+ await store.append(tree.treeId, appendOf(removalOf(tree, ids.header, 1), "p_2", "2026-09-09T07:00:00.000Z"));
287
+ const second = await store.list();
288
+ expect(second.ok && second.value.trees[0]?.revision).toBe(2);
289
+ expect(second.ok && second.value.trees[0]?.changedAt).toBe("2026-09-09T07:00:00.000Z");
290
+ });
291
+ /**
292
+ * The reading a surface is allowed to depend on, asserted rather than
293
+ * written down: a stamp is present exactly when there is an entry to
294
+ * take one from. A store that filled this with a creation time would
295
+ * pass every case above and fail this one.
296
+ */
297
+ it("carries a stamp for exactly the trees whose revision is above zero", async () => {
298
+ const { tree, ids } = sampleTree();
299
+ const store = await freshStore();
300
+ await store.create(tree);
301
+ await store.create(treeNamed("z"));
302
+ await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer)));
303
+ const page = await store.list();
304
+ const trees = page.ok ? page.value.trees : [];
305
+ expect(trees).toHaveLength(2);
306
+ for (const listing of trees) {
307
+ expect("changedAt" in listing).toBe(listing.revision > 0);
308
+ }
309
+ });
310
+ /**
311
+ * The listing and the log are two reads of one fact, so the one thing
312
+ * that must never happen is that they disagree. This compares the
313
+ * listing against what `revisions` says, rather than against a literal
314
+ * the test typed in — the same stamp, reached two ways.
315
+ */
316
+ it("agrees with the newest entry the log itself hands back", async () => {
317
+ const { tree, ids } = sampleTree();
318
+ const store = await freshStore();
319
+ await store.create(tree);
320
+ await store.append(tree.treeId, appendOf(removalOf(tree, ids.footer), "p_1", "2026-05-05T05:05:05.000Z"));
321
+ const page = await store.list();
322
+ const log = await store.revisions(tree.treeId, { direction: "older" });
323
+ const newest = log.ok ? log.value.revisions.at(-1) : undefined;
324
+ expect(newest?.appliedAt).toBeDefined();
325
+ expect(page.ok && page.value.trees[0]?.changedAt).toBe(newest?.appliedAt);
326
+ });
327
+ });
247
328
  });
248
329
  /**
249
330
  * The log is read a page at a time, from either end (0026). These are the
@@ -1,3 +1,4 @@
1
+ import { type RampMode } from "./ramp.js";
1
2
  import { type ResolvedTheme } from "./theme.js";
2
3
  /**
3
4
  * A resolved theme, flattened into CSS custom properties.
@@ -12,6 +13,24 @@ import { type ResolvedTheme } from "./theme.js";
12
13
  * the tree and touches no primitive. A theme change is one `configure` on the
13
14
  * root, and every node below re-reads through the cascade.
14
15
  */
16
+ /**
17
+ * Re-exported rather than published whole: a host selecting a mode needs to
18
+ * name it, and nothing outside this package needs `rampLength` itself.
19
+ */
20
+ export type { RampMode } from "./ramp.js";
15
21
  export type ThemeVariables = Readonly<Record<string, string>>;
16
- export declare const themeVariables: (theme: ResolvedTheme) => ThemeVariables;
22
+ export type ThemeVariableOptions = {
23
+ /**
24
+ * Whether the two ramps may read the width they are rendered at.
25
+ *
26
+ * `"fluid"` is the default and is what a page in a browser wants: a declared
27
+ * step is a maximum, reached at `48rem` and held above it, so a tree built
28
+ * for a laptop is legible on a phone without the tree knowing a phone exists
29
+ * (0283). `"fixed"` emits the pack's numbers as the plain pixel lengths they
30
+ * were before that record, for a medium with no cascade to substitute — see
31
+ * `ramp.ts` for why a `clamp()` is worse than a pixel there.
32
+ */
33
+ readonly ramp?: RampMode;
34
+ };
35
+ export declare const themeVariables: (theme: ResolvedTheme, options?: ThemeVariableOptions) => ThemeVariables;
17
36
  //# sourceMappingURL=apply.d.ts.map
@@ -1,7 +1,9 @@
1
1
  import { chromaValue, paletteMeasures } from "./measure.js";
2
+ import { rampLength } from "./ramp.js";
2
3
  import { PALETTE_SLOTS } from "./theme.js";
3
- export const themeVariables = (theme) => {
4
+ export const themeVariables = (theme, options = {}) => {
4
5
  const variables = {};
6
+ const ramp = options.ramp ?? "fluid";
5
7
  for (const slot of PALETTE_SLOTS) {
6
8
  const value = theme.palette.slots[slot];
7
9
  if (value !== undefined)
@@ -41,7 +43,7 @@ export const themeVariables = (theme) => {
41
43
  variables["--loom-heading-weight"] = String(theme.fontPack.headingWeight);
42
44
  variables["--loom-body-weight"] = String(theme.fontPack.bodyWeight);
43
45
  theme.fontPack.scaleRamp.forEach((step, index) => {
44
- variables[`--loom-scale-${index + 1}`] = `${step}px`;
46
+ variables[`--loom-scale-${index + 1}`] = rampLength(step, "type", ramp);
45
47
  });
46
48
  const { radii, spacingScale, motion, density } = theme.stylePreset;
47
49
  variables["--loom-radius-sm"] = `${radii.sm}px`;
@@ -49,7 +51,7 @@ export const themeVariables = (theme) => {
49
51
  variables["--loom-radius-lg"] = `${radii.lg}px`;
50
52
  variables["--loom-radius-full"] = `${radii.full}px`;
51
53
  spacingScale.forEach((step, index) => {
52
- variables[`--loom-spacing-${index + 1}`] = `${step}px`;
54
+ variables[`--loom-spacing-${index + 1}`] = rampLength(step, "space", ramp);
53
55
  });
54
56
  variables["--loom-motion-fast"] = `${motion.fast}ms`;
55
57
  variables["--loom-motion-medium"] = `${motion.medium}ms`;
@@ -83,20 +83,25 @@ export type TextPairing = {
83
83
  };
84
84
  export declare const PALETTE_TEXT_PAIRINGS: readonly TextPairing[];
85
85
  /**
86
- * The colour as three 0–255 channels, or nothing when it is a form this cannot
87
- * measure.
88
- *
89
- * `colourSchema` accepts more than hex — `rgb()`, `hsl()`, a named colour, and
90
- * eight-digit hex with an alpha. Only three- and six-digit hex are measured
91
- * here, and the rest answer `undefined` rather than a guess:
92
- *
93
- * - a named colour needs the CSS colour table, which is 148 entries of vocabulary
94
- * this module would then own
95
- * - `hsl()` and modern `rgb()` syntax are a parser, and a parser that is subtly
96
- * wrong reports a passing ratio for a failing pair, which is worse than
97
- * reporting nothing
98
- * - an alpha composites against whatever is behind it, so its contrast is not a
99
- * property of the two slots at all
86
+ * A colour's three 0–255 channels, unrounded, or nothing when the form cannot
87
+ * be measured.
88
+ *
89
+ * `colourSchema` accepts four shapes: hex of three to eight digits, `rgb()`,
90
+ * `hsl()`, and a bare word naming a CSS colour. Of those, **every form whose
91
+ * channels are arithmetic is read here**, and two are declined (0365):
92
+ *
93
+ * - **a named colour is vocabulary, not arithmetic.** It needs the CSS colour
94
+ * table — 148 entries this module would then own and keep — and no amount of
95
+ * care with the other forms supplies it.
96
+ * - **an alpha below 1 composites against whatever is behind it**, so its
97
+ * contrast is not a property of the two slots at all. A *fully opaque* alpha
98
+ * is a different case and is read: `#111827ff` composites to exactly
99
+ * `#111827`, so declining it reported nothing about a colour that was never
100
+ * in doubt.
101
+ *
102
+ * Channels are left unrounded. A browser quantises `hsl()` to eight bits per
103
+ * channel on its way into a pixel; nothing here draws anything, so rounding to
104
+ * match it would discard precision to imitate a step this never takes.
100
105
  *
101
106
  * Answering "I could not measure this" is the same move `not-probeable` makes in
102
107
  * the conformance probe: a check that cannot answer says so, rather than passing.
@@ -159,20 +159,179 @@ const channel = (value) => {
159
159
  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
160
160
  };
161
161
  /**
162
- * The colour as three 0–255 channels, or nothing when it is a form this cannot
163
- * measure.
162
+ * The alpha at which a colour composites to exactly itself.
164
163
  *
165
- * `colourSchema` accepts more than hex — `rgb()`, `hsl()`, a named colour, and
166
- * eight-digit hex with an alpha. Only three- and six-digit hex are measured
167
- * here, and the rest answer `undefined` rather than a guess:
164
+ * The whole of what an alpha costs this module: at `1` there is nothing behind
165
+ * the colour to mix in, so the pair's contrast is a property of the pair. Below
166
+ * it, it is not, and no parser can recover what was never stated.
167
+ */
168
+ const OPAQUE = 1;
169
+ /** The one set of colour functions `colourSchema` admits. */
170
+ const COLOUR_CALL = /^(rgba?|hsla?)\(([^()]*)\)$/i;
171
+ /** A CSS `<number>`, or nothing. Rejects `none`, `1px` and the empty string. */
172
+ const numberOf = (text) => {
173
+ if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(text))
174
+ return undefined;
175
+ const value = Number(text);
176
+ return Number.isFinite(value) ? value : undefined;
177
+ };
178
+ /** A CSS `<percentage>` as its own number, so `50%` is `50`. */
179
+ const percentageOf = (text) => text.endsWith("%") ? numberOf(text.slice(0, -1)) : undefined;
180
+ const clampTo = (high, value) => Math.min(high, Math.max(0, value));
181
+ /**
182
+ * How much of a degree each `<angle>` unit is worth.
168
183
  *
169
- * - a named colour needs the CSS colour table, which is 148 entries of vocabulary
170
- * this module would then own
171
- * - `hsl()` and modern `rgb()` syntax are a parser, and a parser that is subtly
172
- * wrong reports a passing ratio for a failing pair, which is worse than
173
- * reporting nothing
174
- * - an alpha composites against whatever is behind it, so its contrast is not a
175
- * property of the two slots at all
184
+ * All four of CSS's units rather than `deg` alone: a host writing `turn` is
185
+ * writing legal CSS that a browser paints correctly, and a measurement that
186
+ * declined it would be declining arithmetic it has in front of it.
187
+ */
188
+ const DEGREES_PER_UNIT = {
189
+ deg: 1,
190
+ grad: 360 / 400,
191
+ rad: 180 / Math.PI,
192
+ turn: 360,
193
+ };
194
+ const ANGLE = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(deg|grad|rad|turn)?$/i;
195
+ /** A hue in degrees, unwrapped. A bare number is degrees, as CSS says. */
196
+ const degreesOf = (text) => {
197
+ const angle = ANGLE.exec(text);
198
+ if (angle === null)
199
+ return undefined;
200
+ const [, value = "", unit] = angle;
201
+ const magnitude = numberOf(value);
202
+ const perUnit = unit === undefined ? 1 : DEGREES_PER_UNIT[unit.toLowerCase()];
203
+ return magnitude === undefined || perUnit === undefined ? undefined : magnitude * perUnit;
204
+ };
205
+ /**
206
+ * The alpha a colour carries, as 0–1. Absent is `1`; unreadable is `undefined`.
207
+ *
208
+ * The two outcomes are kept apart deliberately. An absent alpha is an opaque
209
+ * colour and measurable; an alpha nobody can parse means the string is not the
210
+ * colour it appears to be, and guessing it opaque would measure a colour the
211
+ * host did not write.
212
+ */
213
+ const alphaOf = (text) => {
214
+ if (text === undefined)
215
+ return OPAQUE;
216
+ const percentage = percentageOf(text);
217
+ if (percentage !== undefined)
218
+ return clampTo(1, percentage / 100);
219
+ const number = numberOf(text);
220
+ return number === undefined ? undefined : clampTo(1, number);
221
+ };
222
+ /**
223
+ * The arguments of `rgb()` or `hsl()`, in either syntax CSS publishes.
224
+ *
225
+ * Commas are the legacy form and take their alpha as a fourth argument; spaces
226
+ * are the modern form and take it after a solidus. The two are not mixable, and
227
+ * a string that mixes them is refused rather than half-read — `rgb(1, 2 3)` is
228
+ * not a colour, and the one thing worse than declining it is averaging it.
229
+ *
230
+ * **Nothing here checks for the mix**, and a planted mutation is why the check
231
+ * is not here: a comma-split part carrying a space fails `numberOf` and
232
+ * `percentageOf` downstream anyway, so a guard against it changed no outcome on
233
+ * any input. Chromium refuses the same strings, which is how each one is known
234
+ * to be refused rather than assumed.
235
+ */
236
+ const argumentsOf = (body) => {
237
+ const trimmed = body.trim();
238
+ if (trimmed === "")
239
+ return undefined;
240
+ if (trimmed.includes(",")) {
241
+ if (trimmed.includes("/"))
242
+ return undefined;
243
+ const parts = trimmed.split(",").map((part) => part.trim());
244
+ if (parts.length === 3)
245
+ return { components: parts, alpha: undefined };
246
+ return parts.length === 4 ? { components: parts.slice(0, 3), alpha: parts[3] } : undefined;
247
+ }
248
+ const [stated = "", alpha, ...extra] = trimmed.split("/").map((part) => part.trim());
249
+ if (extra.length > 0 || alpha === "")
250
+ return undefined;
251
+ const components = stated.split(/\s+/);
252
+ return components.length === 3 ? { components, alpha } : undefined;
253
+ };
254
+ /** One `rgb()` component: a number out of 255, or a percentage of it. */
255
+ const rgbChannel = (text) => {
256
+ const percentage = percentageOf(text);
257
+ if (percentage !== undefined)
258
+ return clampTo(255, (percentage / 100) * 255);
259
+ const number = numberOf(text);
260
+ return number === undefined ? undefined : clampTo(255, number);
261
+ };
262
+ const rgbChannelsOf = (components) => {
263
+ const [r, g, b] = components.map(rgbChannel);
264
+ return r === undefined || g === undefined || b === undefined ? undefined : [r, g, b];
265
+ };
266
+ /**
267
+ * `hsl()` to sRGB, by CSS Color 4's own reference arithmetic.
268
+ *
269
+ * Written as the specification writes it rather than as the shorter form with
270
+ * two branches, because this is the function the 20 August argument against
271
+ * reading `hsl()` was about — *a parser that is subtly wrong reports a passing
272
+ * ratio for a failing pair* — and a reader checking that claim should be able to
273
+ * lay this beside the specification line for line.
274
+ */
275
+ const hslChannelsOf = (components) => {
276
+ const [hue = "", saturation = "", lightness = ""] = components;
277
+ const degrees = degreesOf(hue);
278
+ const s = percentageOf(saturation) ?? numberOf(saturation);
279
+ const l = percentageOf(lightness) ?? numberOf(lightness);
280
+ if (degrees === undefined || s === undefined || l === undefined)
281
+ return undefined;
282
+ const h = ((degrees % 360) + 360) % 360;
283
+ const saturated = clampTo(1, s / 100);
284
+ const light = clampTo(1, l / 100);
285
+ const amount = saturated * Math.min(light, 1 - light);
286
+ const channelAt = (offset) => {
287
+ const k = (offset + h / 30) % 12;
288
+ return (light - amount * Math.max(-1, Math.min(k - 3, 9 - k, 1))) * 255;
289
+ };
290
+ return [channelAt(0), channelAt(8), channelAt(4)];
291
+ };
292
+ /**
293
+ * Hex of three, four, six or eight digits, declining an alpha below opaque.
294
+ *
295
+ * Five and seven digits are refused. `colourSchema`'s pattern admits them —
296
+ * `#[0-9a-fA-F]{3,8}` — and no browser does, so a palette carrying one is a
297
+ * typo that renders as nothing and must not be measured as though it rendered.
298
+ */
299
+ const hexChannelsOf = (colour) => {
300
+ const digits = /^#([0-9a-fA-F]+)$/.exec(colour)?.[1];
301
+ if (digits === undefined)
302
+ return undefined;
303
+ const pairs = digits.length === 3 || digits.length === 4
304
+ ? [...digits].map((digit) => `${digit}${digit}`)
305
+ : digits.length === 6 || digits.length === 8
306
+ ? Array.from({ length: digits.length / 2 }, (_, at) => digits.slice(at * 2, at * 2 + 2))
307
+ : undefined;
308
+ if (pairs === undefined)
309
+ return undefined;
310
+ const [r, g, b, alpha] = pairs.map((pair) => Number.parseInt(pair, 16));
311
+ if (r === undefined || g === undefined || b === undefined)
312
+ return undefined;
313
+ return alpha !== undefined && alpha !== 255 ? undefined : [r, g, b];
314
+ };
315
+ /**
316
+ * A colour's three 0–255 channels, unrounded, or nothing when the form cannot
317
+ * be measured.
318
+ *
319
+ * `colourSchema` accepts four shapes: hex of three to eight digits, `rgb()`,
320
+ * `hsl()`, and a bare word naming a CSS colour. Of those, **every form whose
321
+ * channels are arithmetic is read here**, and two are declined (0365):
322
+ *
323
+ * - **a named colour is vocabulary, not arithmetic.** It needs the CSS colour
324
+ * table — 148 entries this module would then own and keep — and no amount of
325
+ * care with the other forms supplies it.
326
+ * - **an alpha below 1 composites against whatever is behind it**, so its
327
+ * contrast is not a property of the two slots at all. A *fully opaque* alpha
328
+ * is a different case and is read: `#111827ff` composites to exactly
329
+ * `#111827`, so declining it reported nothing about a colour that was never
330
+ * in doubt.
331
+ *
332
+ * Channels are left unrounded. A browser quantises `hsl()` to eight bits per
333
+ * channel on its way into a pixel; nothing here draws anything, so rounding to
334
+ * match it would discard precision to imitate a step this never takes.
176
335
  *
177
336
  * Answering "I could not measure this" is the same move `not-probeable` makes in
178
337
  * the conformance probe: a check that cannot answer says so, rather than passing.
@@ -182,12 +341,17 @@ const channel = (value) => {
182
341
  * parsers would be two answers to "is this measurable".
183
342
  */
184
343
  export const channelsOf = (colour) => {
185
- const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(colour)?.[1];
186
- if (hex === undefined)
344
+ const call = COLOUR_CALL.exec(colour.trim());
345
+ if (call === null)
346
+ return hexChannelsOf(colour.trim());
347
+ const [, name = "", body = ""] = call;
348
+ const parts = argumentsOf(body);
349
+ if (parts === undefined)
187
350
  return undefined;
188
- const pairs = hex.length === 3 ? [...hex].map((digit) => `${digit}${digit}`) : [0, 2, 4].map((at) => hex.slice(at, at + 2));
189
- const [r, g, b] = pairs.map((pair) => Number.parseInt(pair, 16));
190
- return r === undefined || g === undefined || b === undefined ? undefined : [r, g, b];
351
+ const alpha = alphaOf(parts.alpha);
352
+ if (alpha === undefined || alpha < OPAQUE)
353
+ return undefined;
354
+ return name.toLowerCase().startsWith("rgb") ? rgbChannelsOf(parts.components) : hslChannelsOf(parts.components);
191
355
  };
192
356
  const luminance = ([r, g, b]) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
193
357
  /**
@@ -1,4 +1,5 @@
1
1
  import { type Palette } from "./theme.js";
2
+ export declare const MARK_SEPARATION_TARGET: number;
2
3
  export type PaletteMode = "light" | "dark";
3
4
  export type HueSpec = {
4
5
  /** 0–360. */
@@ -44,6 +45,27 @@ export declare const hslHex: (hue: number, saturation: number, lightness: number
44
45
  * boundary, which is far finer than the 1/255 the hex can express.
45
46
  */
46
47
  export declare const solveLightness: (hue: number, saturation: number, on: string, target: number, darkening: boolean) => string;
48
+ /**
49
+ * The lightness *nearest* `from` at this hue whose colour clears `target` ΔE
50
+ * against every one of `grounds`.
51
+ *
52
+ * Nearest rather than furthest, which is the opposite of `solveLightness` and
53
+ * for the mirror of its reason. An ink is dragged as far as the bar allows
54
+ * because a letterform has to be read; a line only has to be **found**, and a
55
+ * border pushed further than it needs to go stops being the subtle tier and
56
+ * becomes the default one. The tiers are a ramp and the gaps between them carry
57
+ * meaning (0204), so the search moves a line the least it can.
58
+ *
59
+ * Both directions are tried at each step and the darker one wins a tie, because
60
+ * on a light palette the grounds are above the border and moving down is the
61
+ * direction that gains separation from all three at once.
62
+ *
63
+ * Falls back to `from` when nothing within 40 points of lightness clears the
64
+ * target, which is a palette whose three grounds surround the tier — the
65
+ * derivation cannot fix that by moving one slot, and `auditMarkGroundings` is
66
+ * what says so.
67
+ */
68
+ export declare const solveMarkLightness: (hue: number, saturation: number, from: number, grounds: readonly string[], target: number) => string;
47
69
  /**
48
70
  * Derives a palette. Total: it always returns one, and `auditPalette` on the
49
71
  * result is the check that it worked — see `derivePaletteChecked` for the pair.
@@ -1,4 +1,5 @@
1
1
  import { auditPalette, contrastRatio, TEXT_CONTRAST_MINIMUM } from "./contrast.js";
2
+ import { colourDifference, JUST_NOTICEABLE_DIFFERENCE } from "./separation.js";
2
3
  import { paletteSchema } from "./theme.js";
3
4
  /**
4
5
  * Builds a palette that clears the bar, from three hues and a mode.
@@ -39,6 +40,18 @@ import { paletteSchema } from "./theme.js";
39
40
  /** How far above the AA bar a derived colour lands. */
40
41
  const MARGIN = 0.25;
41
42
  const TARGET = TEXT_CONTRAST_MINIMUM + MARGIN;
43
+ /**
44
+ * How far past the just-noticeable difference a derived line lands, in ΔE.
45
+ *
46
+ * The same reasoning as `MARGIN` and for the same reason it is not zero: a slot
47
+ * solved to exactly the floor drops under it the first time somebody nudges a
48
+ * background by a value. 2.3 is what `separation.ts` asserts, because it is the
49
+ * published threshold; 3.0 is what this aims at, because it is the one a later
50
+ * edit can afford to lose a little of. Written as the floor plus a margin rather
51
+ * than as 3, so moving the published threshold moves this with it.
52
+ */
53
+ const MARK_MARGIN = 0.7;
54
+ export const MARK_SEPARATION_TARGET = JUST_NOTICEABLE_DIFFERENCE + MARK_MARGIN;
42
55
  /** HSL to a six-digit hex, which is the only form `contrastRatio` measures. */
43
56
  export const hslHex = (hue, saturation, lightness) => {
44
57
  const a = (saturation / 100) * Math.min(lightness / 100, 1 - lightness / 100);
@@ -86,6 +99,37 @@ const DEFAULT_LEVELS = {
86
99
  light: [98, 100, 94],
87
100
  dark: [10, 14, 8],
88
101
  };
102
+ /**
103
+ * The lightness *nearest* `from` at this hue whose colour clears `target` ΔE
104
+ * against every one of `grounds`.
105
+ *
106
+ * Nearest rather than furthest, which is the opposite of `solveLightness` and
107
+ * for the mirror of its reason. An ink is dragged as far as the bar allows
108
+ * because a letterform has to be read; a line only has to be **found**, and a
109
+ * border pushed further than it needs to go stops being the subtle tier and
110
+ * becomes the default one. The tiers are a ramp and the gaps between them carry
111
+ * meaning (0204), so the search moves a line the least it can.
112
+ *
113
+ * Both directions are tried at each step and the darker one wins a tie, because
114
+ * on a light palette the grounds are above the border and moving down is the
115
+ * direction that gains separation from all three at once.
116
+ *
117
+ * Falls back to `from` when nothing within 40 points of lightness clears the
118
+ * target, which is a palette whose three grounds surround the tier — the
119
+ * derivation cannot fix that by moving one slot, and `auditMarkGroundings` is
120
+ * what says so.
121
+ */
122
+ export const solveMarkLightness = (hue, saturation, from, grounds, target) => {
123
+ const nearestGround = (candidate) => Math.min(...grounds.map((ground) => colourDifference(candidate, ground) ?? 0));
124
+ for (let step = 0; step <= 40; step += 0.125) {
125
+ for (const lightness of step === 0 ? [from] : [from - step, from + step]) {
126
+ const candidate = hslHex(hue, saturation, lightness);
127
+ if (lightness >= 0 && lightness <= 100 && nearestGround(candidate) >= target)
128
+ return candidate;
129
+ }
130
+ }
131
+ return hslHex(hue, saturation, from);
132
+ };
89
133
  /**
90
134
  * Derives a palette. Total: it always returns one, and `auditPalette` on the
91
135
  * result is the check that it worked — see `derivePaletteChecked` for the pair.
@@ -134,7 +178,16 @@ export const derivePalette = (spec) => {
134
178
  "brand-secondary-strong": hslHex(sh, Math.min(ss + 6, 100), ink ? 38 : 48),
135
179
  "border-default": hslHex(ch, cs + 4, ink ? 86 : 22),
136
180
  "border-strong": hslHex(ch, cs + 4, ink ? 12 : 90),
137
- "border-subtle": hslHex(ch, cs + 3, ink ? 92 : 17),
181
+ /**
182
+ * The one border tier that is solved rather than picked. At the default
183
+ * levels it lands two points of lightness from the muted well, which is
184
+ * under the just-noticeable difference — so eight of the palettes in
185
+ * `palettes.ts` shipped a card edge a reader could not find, and one of
186
+ * them drew it in the well's own colour. The other two tiers are 4 to 15
187
+ * and 74 to 98 from every ground at every hue this derives, so they are
188
+ * picked; if that ever stops being true, this is the function to reach for.
189
+ */
190
+ "border-subtle": solveMarkLightness(ch, cs + 3, ink ? 92 : 17, [bgCanvas, bgSurface, bgSurfaceMuted], MARK_SEPARATION_TARGET),
138
191
  "border-accent": hslHex(ah, Math.min(as, 70), ink ? 58 : 62),
139
192
  },
140
193
  });
@@ -37,7 +37,7 @@ export const editorialPalette = paletteSchema.parse({
37
37
  "brand-secondary-strong": "#34425a",
38
38
  "border-default": "#e5e5e5",
39
39
  "border-strong": "#0a0a0a",
40
- "border-subtle": "#efefe9",
40
+ "border-subtle": "#e8e8df",
41
41
  "border-accent": "#4a5b78",
42
42
  },
43
43
  });
@@ -115,6 +115,35 @@ export declare const slotChroma: (colour: string) => number | undefined;
115
115
  * pair that might be the wrong way round.
116
116
  */
117
117
  export declare const paletteScrim: (palette: Palette) => Scrim | undefined;
118
+ /**
119
+ * Which way round a palette is.
120
+ *
121
+ * Not a colour and not a threshold: the question `color-scheme` asks, which is
122
+ * whether text on this palette's own ground is light-on-dark or dark-on-light.
123
+ * A host that draws a frame standing in for the page needs the answer and has
124
+ * nowhere to get it — `themeStyle` hands over every variable a *primitive*
125
+ * reads, and being light or dark is the one fact the host needs about the
126
+ * palette rather than from it.
127
+ */
128
+ export type PaletteScheme = "light" | "dark";
129
+ /**
130
+ * Which way round the palette is, or `undefined` when either end of its
131
+ * body-copy pair is a colour `channelsOf` declines to read.
132
+ *
133
+ * **No threshold, deliberately.** A luminance ceiling would be a number this
134
+ * module had to defend, and the one it already has — `SCRIM_DARK_CEILING` — is
135
+ * about whether a wash can darken what is under it, which is a different
136
+ * question with a different answer. Comparing a palette's own ink to its own
137
+ * canvas needs no constant at all: whichever is lighter says which way round the
138
+ * palette is, and it says it for a host palette nobody here has seen.
139
+ *
140
+ * Measured across the twenty-one registered palettes the two groups are canvases
141
+ * at `L > 0.9` and `L < 0.02`, so nothing sits anywhere near a line that does not
142
+ * exist. `measure.test.ts` holds that, and holds this against `paletteScrim`'s
143
+ * reading of the same pair, because two functions comparing one pair of colours
144
+ * must not be able to disagree about it.
145
+ */
146
+ export declare const paletteScheme: (palette: Palette) => PaletteScheme | undefined;
118
147
  /** Everything measurable about one palette that its slots do not say. */
119
148
  export type PaletteMeasures = {
120
149
  readonly palette: ThemeId;
@@ -125,6 +154,11 @@ export type PaletteMeasures = {
125
154
  */
126
155
  readonly chroma: Readonly<Partial<Record<PaletteSlot, number>>>;
127
156
  readonly scrim: Scrim | undefined;
157
+ /**
158
+ * Which way round the palette is, and `undefined` on the same terms `scrim`
159
+ * is: a pair this cannot read is reported as unavailable rather than guessed.
160
+ */
161
+ readonly scheme: PaletteScheme | undefined;
128
162
  };
129
163
  /** Measures one palette. Refuses nothing, and reports what it could not measure by leaving it out. */
130
164
  export declare const paletteMeasures: (palette: Palette) => PaletteMeasures;
@@ -119,6 +119,30 @@ export const paletteScrim = (palette) => {
119
119
  darkens: luminance <= SCRIM_DARK_CEILING,
120
120
  };
121
121
  };
122
+ /**
123
+ * Which way round the palette is, or `undefined` when either end of its
124
+ * body-copy pair is a colour `channelsOf` declines to read.
125
+ *
126
+ * **No threshold, deliberately.** A luminance ceiling would be a number this
127
+ * module had to defend, and the one it already has — `SCRIM_DARK_CEILING` — is
128
+ * about whether a wash can darken what is under it, which is a different
129
+ * question with a different answer. Comparing a palette's own ink to its own
130
+ * canvas needs no constant at all: whichever is lighter says which way round the
131
+ * palette is, and it says it for a host palette nobody here has seen.
132
+ *
133
+ * Measured across the twenty-one registered palettes the two groups are canvases
134
+ * at `L > 0.9` and `L < 0.02`, so nothing sits anywhere near a line that does not
135
+ * exist. `measure.test.ts` holds that, and holds this against `paletteScrim`'s
136
+ * reading of the same pair, because two functions comparing one pair of colours
137
+ * must not be able to disagree about it.
138
+ */
139
+ export const paletteScheme = (palette) => {
140
+ const ink = relativeLuminance(palette.slots["fg-default"] ?? "");
141
+ const page = relativeLuminance(palette.slots["bg-canvas"] ?? "");
142
+ if (ink === undefined || page === undefined)
143
+ return undefined;
144
+ return ink > page ? "dark" : "light";
145
+ };
122
146
  /** Measures one palette. Refuses nothing, and reports what it could not measure by leaving it out. */
123
147
  export const paletteMeasures = (palette) => {
124
148
  const chroma = {};
@@ -127,7 +151,12 @@ export const paletteMeasures = (palette) => {
127
151
  if (measured !== undefined)
128
152
  chroma[slot] = measured;
129
153
  }
130
- return { palette: palette.id, chroma, scrim: paletteScrim(palette) };
154
+ return {
155
+ palette: palette.id,
156
+ chroma,
157
+ scrim: paletteScrim(palette),
158
+ scheme: paletteScheme(palette),
159
+ };
131
160
  };
132
161
  /**
133
162
  * The decimal places a chroma is emitted to.