@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
@@ -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`;
@@ -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.
@@ -56,7 +56,7 @@ export const paperPalette = paletteSchema.parse({
56
56
  "brand-secondary-strong": "#ac7515",
57
57
  "border-default": "#e7dbcf",
58
58
  "border-strong": "#291f14",
59
- "border-subtle": "#f1ebe4",
59
+ "border-subtle": "#efe8e0",
60
60
  "border-accent": "#d67551",
61
61
  },
62
62
  });
@@ -104,7 +104,7 @@ export const sagePalette = paletteSchema.parse({
104
104
  "brand-secondary-strong": "#56952d",
105
105
  "border-default": "#d5e2d5",
106
106
  "border-strong": "#192419",
107
- "border-subtle": "#e7eee7",
107
+ "border-subtle": "#e4ece4",
108
108
  "border-accent": "#5ccc90",
109
109
  },
110
110
  });
@@ -176,7 +176,7 @@ export const citrusPalette = paletteSchema.parse({
176
176
  "brand-secondary-strong": "#b6830c",
177
177
  "border-default": "#e9e6ce",
178
178
  "border-strong": "#2a2813",
179
- "border-subtle": "#f2f1e3",
179
+ "border-subtle": "#f0efde",
180
180
  "border-accent": "#b4d058",
181
181
  },
182
182
  });
@@ -224,7 +224,7 @@ export const graphitePalette = paletteSchema.parse({
224
224
  "brand-secondary-strong": "#675b5b",
225
225
  "border-default": "#dddada",
226
226
  "border-strong": "#201d1d",
227
- "border-subtle": "#ebeaea",
227
+ "border-subtle": "#e8e6e6",
228
228
  "border-accent": "#949494",
229
229
  },
230
230
  });
@@ -248,7 +248,7 @@ export const clayPalette = paletteSchema.parse({
248
248
  "brand-secondary-strong": "#348d6a",
249
249
  "border-default": "#e6ddd1",
250
250
  "border-strong": "#282015",
251
- "border-subtle": "#f1ece5",
251
+ "border-subtle": "#ebe4db",
252
252
  "border-accent": "#d27356",
253
253
  },
254
254
  });
@@ -272,7 +272,7 @@ export const linenPalette = paletteSchema.parse({
272
272
  "brand-secondary-strong": "#32708f",
273
273
  "border-default": "#e5dfd1",
274
274
  "border-strong": "#272216",
275
- "border-subtle": "#f0ede5",
275
+ "border-subtle": "#eae6da",
276
276
  "border-accent": "#b49274",
277
277
  },
278
278
  });
@@ -416,7 +416,7 @@ export const duskPalette = paletteSchema.parse({
416
416
  "brand-secondary-strong": "#752acb",
417
417
  "border-default": "#2d2c44",
418
418
  "border-strong": "#e1e0eb",
419
- "border-subtle": "#232234",
419
+ "border-subtle": "#252437",
420
420
  "border-accent": "#de5e73",
421
421
  },
422
422
  });
@@ -0,0 +1,64 @@
1
+ /**
2
+ * A ramp step as a CSS length, and the width at which it is what the pack said.
3
+ *
4
+ * A font pack declares eight type sizes and a style preset eight spacing steps,
5
+ * both as plain numbers, and `apply.ts` mounted them as pixels. That is the
6
+ * whole of why a page built in Loom did not fit a phone: `--loom-scale-8` was
7
+ * 72px at every width, so a hero headline on a 390px screen was given three
8
+ * characters a line, and `--loom-spacing-4` plus `--loom-spacing-6` took 35% of
9
+ * that screen in gutter before a word was set. Filed by `Loom marketing` on
10
+ * 13 October against the one surface built entirely in the framework — measured
11
+ * there, because the only instrument that sees it is a camera.
12
+ *
13
+ * **A tree cannot fix it and must not be able to.** There is no prop, no theme
14
+ * and no node that means *smaller on a phone*, and there is not going to be
15
+ * one: a render is a pure function of one node
16
+ * ([0008](../../decisions/0008-the-renderer-is-a-total-pure-projection.md)), so
17
+ * a primitive handed a viewport would make the same tree a different page. The
18
+ * surface's own stylesheet cannot fix it either — a second source of truth for
19
+ * type and spacing is exactly what the re-theme guarantee
20
+ * ([0049](../../decisions/0049-a-theme-is-three-ids-in-the-tree.md)) cannot
21
+ * have.
22
+ *
23
+ * So the width is read where this repository already reads it: in CSS.
24
+ * [0079](../../decisions/0079-a-layout-css-alone-can-express-belongs-in-the-stylesheet.md)
25
+ * drew that line for `loom.mosaic` and drew it in the right place — *no
26
+ * viewport in the render function*, and a rule in a stylesheet is not in the
27
+ * render function. A `clamp()` is the same bargain one step earlier: the markup
28
+ * is unchanged, nothing is interpolated, `themeVariables` is as pure as it was
29
+ * — the same theme yields the same strings — and the browser rather than the
30
+ * render function is what knows how wide the page is.
31
+ *
32
+ * ## What a declared number now means
33
+ *
34
+ * **A maximum, reached at `48rem` and held above it.** Below that a step is
35
+ * compressed toward the largest value its quantity can hold on a phone, and a
36
+ * step already that small is emitted as the plain pixel length it always was.
37
+ * The consequence worth stating is the one that is easy to miss: **nothing
38
+ * changes at or above 768px.** A reader on a laptop sees the ramp the pack
39
+ * declared, to the pixel.
40
+ */
41
+ /** Which ramp a step belongs to. They differ only in what a phone can hold. */
42
+ export type RampKind = "type" | "space";
43
+ /**
44
+ * Whether the emitted length may read the width.
45
+ *
46
+ * `"fixed"` is for a medium with no cascade and no viewport — an image renderer
47
+ * or an email body, which `inline-variables.ts` substitutes values into. A
48
+ * `clamp()` in container units is not a literal length: it is strictly worse
49
+ * there than the pixel it replaced, because nothing in that medium resolves it.
50
+ * A caller asking for literals gets the pack's declared numbers.
51
+ */
52
+ export type RampMode = "fluid" | "fixed";
53
+ /**
54
+ * One ramp step, as the length `apply.ts` mounts.
55
+ *
56
+ * The preferred value is `cqi` rather than `vw` for the reason `loom.heading`
57
+ * learned in the same place: with no ancestor declaring containment `cqi` is
58
+ * the small viewport width, so a step on the open page behaves as it always
59
+ * did, and a step inside a `loom.card` or one half of a `loom.split` is held to
60
+ * the column it is actually in because those declare the containment for it to
61
+ * read.
62
+ */
63
+ export declare const rampLength: (step: number, kind: RampKind, mode: RampMode) => string;
64
+ //# sourceMappingURL=ramp.d.ts.map
@@ -0,0 +1,114 @@
1
+ /**
2
+ * A ramp step as a CSS length, and the width at which it is what the pack said.
3
+ *
4
+ * A font pack declares eight type sizes and a style preset eight spacing steps,
5
+ * both as plain numbers, and `apply.ts` mounted them as pixels. That is the
6
+ * whole of why a page built in Loom did not fit a phone: `--loom-scale-8` was
7
+ * 72px at every width, so a hero headline on a 390px screen was given three
8
+ * characters a line, and `--loom-spacing-4` plus `--loom-spacing-6` took 35% of
9
+ * that screen in gutter before a word was set. Filed by `Loom marketing` on
10
+ * 13 October against the one surface built entirely in the framework — measured
11
+ * there, because the only instrument that sees it is a camera.
12
+ *
13
+ * **A tree cannot fix it and must not be able to.** There is no prop, no theme
14
+ * and no node that means *smaller on a phone*, and there is not going to be
15
+ * one: a render is a pure function of one node
16
+ * ([0008](../../decisions/0008-the-renderer-is-a-total-pure-projection.md)), so
17
+ * a primitive handed a viewport would make the same tree a different page. The
18
+ * surface's own stylesheet cannot fix it either — a second source of truth for
19
+ * type and spacing is exactly what the re-theme guarantee
20
+ * ([0049](../../decisions/0049-a-theme-is-three-ids-in-the-tree.md)) cannot
21
+ * have.
22
+ *
23
+ * So the width is read where this repository already reads it: in CSS.
24
+ * [0079](../../decisions/0079-a-layout-css-alone-can-express-belongs-in-the-stylesheet.md)
25
+ * drew that line for `loom.mosaic` and drew it in the right place — *no
26
+ * viewport in the render function*, and a rule in a stylesheet is not in the
27
+ * render function. A `clamp()` is the same bargain one step earlier: the markup
28
+ * is unchanged, nothing is interpolated, `themeVariables` is as pure as it was
29
+ * — the same theme yields the same strings — and the browser rather than the
30
+ * render function is what knows how wide the page is.
31
+ *
32
+ * ## What a declared number now means
33
+ *
34
+ * **A maximum, reached at `48rem` and held above it.** Below that a step is
35
+ * compressed toward the largest value its quantity can hold on a phone, and a
36
+ * step already that small is emitted as the plain pixel length it always was.
37
+ * The consequence worth stating is the one that is easy to miss: **nothing
38
+ * changes at or above 768px.** A reader on a laptop sees the ramp the pack
39
+ * declared, to the pixel.
40
+ */
41
+ /**
42
+ * The width at which a ramp is exactly what its pack declared.
43
+ *
44
+ * `48rem` is the library's one width and 0079 set the bar for a second high on
45
+ * purpose. This is not a second one — a `clamp()` has no breakpoint in it, and
46
+ * naming the width the library already switches `loom.mosaic` on is the whole
47
+ * reason to prefer this number to a better-looking one.
48
+ */
49
+ const FULL_WIDTH_PX = 768;
50
+ /**
51
+ * How much of the distance between the hold and the declared number survives on
52
+ * a narrow screen.
53
+ *
54
+ * **It is not a taste.** `loom.primitives` capped `loom.heading`'s top step at
55
+ * `11cqi` on 20 August, found by measuring which words lost their last letter
56
+ * in a 390px screen. `0.46` is the ratio that reproduces that cap from the
57
+ * pack's own number — a 72px step floors at 42.84px where `11cqi` is 42.90px —
58
+ * so the figure a lane arrived at by photographing one pack is now derived for
59
+ * every step of every pack, including the ones nothing has photographed.
60
+ */
61
+ const COMPRESSION = 0.46;
62
+ /**
63
+ * The value each ramp is compressed toward, and the reason the two differ.
64
+ *
65
+ * Type holds at 18px because step 3 is body copy in every registered pack and
66
+ * step 4 is 17–20: a ramp that shrank those would be trading a headline that
67
+ * does not fit for paragraphs nobody can read. Space holds at 8px because
68
+ * whitespace has no legibility floor — only a floor at which a gap stops
69
+ * reading as one — and a phone wants less of it, not a little less.
70
+ */
71
+ const HOLD_PX = { type: 18, space: 8 };
72
+ /**
73
+ * Two decimal places, rounded **up**.
74
+ *
75
+ * Up rather than to nearest, and the preferred value is why. A coefficient
76
+ * rounded down reaches the declared size a little *after* `48rem` rather than
77
+ * at it — `20px` resolved to 19.97 at 768 before this was `ceil`, which is the
78
+ * one property the whole construction promises and the kind of defect only
79
+ * arithmetic over every registered pack finds. On a floor a hundredth of a
80
+ * pixel is beneath anything a reader or a camera can see.
81
+ */
82
+ const round = (value) => Math.ceil(value * 100) / 100;
83
+ /**
84
+ * The smallest this step is ever rendered.
85
+ *
86
+ * Monotone in `step` by construction — the identity at or below the hold, and
87
+ * affine with a positive slope above it — which is what keeps a ramp a ramp. A
88
+ * narrow screen reorders nothing: if the declared steps ascend, so do these,
89
+ * and so does every width between the two bounds.
90
+ */
91
+ const rampFloor = (step, kind) => {
92
+ const hold = HOLD_PX[kind];
93
+ return step <= hold ? step : hold + (step - hold) * COMPRESSION;
94
+ };
95
+ /**
96
+ * One ramp step, as the length `apply.ts` mounts.
97
+ *
98
+ * The preferred value is `cqi` rather than `vw` for the reason `loom.heading`
99
+ * learned in the same place: with no ancestor declaring containment `cqi` is
100
+ * the small viewport width, so a step on the open page behaves as it always
101
+ * did, and a step inside a `loom.card` or one half of a `loom.split` is held to
102
+ * the column it is actually in because those declare the containment for it to
103
+ * read.
104
+ */
105
+ export const rampLength = (step, kind, mode) => {
106
+ if (mode === "fixed")
107
+ return `${step}px`;
108
+ const floor = round(rampFloor(step, kind));
109
+ /** A step a phone already holds is the plain length it has always been. */
110
+ if (floor >= step)
111
+ return `${step}px`;
112
+ return `clamp(${floor}px, ${round((step / FULL_WIDTH_PX) * 100)}cqi, ${step}px)`;
113
+ };
114
+ //# sourceMappingURL=ramp.js.map
@@ -24,6 +24,15 @@ export type ThemeError = {
24
24
  readonly code: "malformed-selection";
25
25
  readonly detail: string;
26
26
  };
27
+ /**
28
+ * Why a theme did not resolve, and what could have.
29
+ *
30
+ * `available` holds every registered id and this prints the few nearest the one
31
+ * that was asked for, because the sentence lands in a log line whose length is
32
+ * not the deployment's to set. A caller that wants the whole list has it on the
33
+ * error, and a caller that wants it with names and descriptions has
34
+ * `catalogue()`.
35
+ */
27
36
  export declare const describeThemeError: (error: ThemeError) => string;
28
37
  export type ThemeCatalogueEntry = {
29
38
  readonly id: string;