@jam-overture/loom 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,117 @@
1
+ /**
2
+ * The loop that keeps a customer's server current: pull, hold, wait, pull
3
+ * again.
4
+ *
5
+ * This is the one stateful thing in the pull — a server holds its live pages
6
+ * and a timer, and both belong to the process rather than to a request. It is a
7
+ * closure and not a class because there is nothing to inherit and nothing to
8
+ * override: the two functions a host calls are reading what is held and
9
+ * stopping.
10
+ *
11
+ * **A reader waits on it once per server, and only for the first answer**
12
+ * ([0364](../../decisions/0364-a-new-server-waits-for-its-first-pull-before-it-serves-and-never-waits-again.md)).
13
+ * The first pull is made at once rather than after an interval, and a render
14
+ * that asks `ready()` before it has settled waits for it — so the first reader
15
+ * on a new server gets the live page rather than the page as built and then a
16
+ * different one on the next request. A pull that fails answers at once, and
17
+ * the wait gives up after `DEFAULT_FIRST_WAIT_MS` only when Loom says nothing
18
+ * at all; either way the page as built is served and the pull carries on.
19
+ *
20
+ * After the first answer nothing waits again: the next pull is scheduled only
21
+ * when the last has settled, so a slow Loom stretches the interval instead of
22
+ * stacking requests behind it, and a render reads whatever is held.
23
+ */
24
+ import { ceilingOf } from "../deadline.js";
25
+ import { NO_LIVE_PAGES } from "./pages.js";
26
+ import { pullLivePages, withPullOutcome } from "./pull.js";
27
+ /** A minute, which is a change live within a minute of somebody accepting it. */
28
+ export const DEFAULT_PULL_INTERVAL_MS = 60_000;
29
+ /**
30
+ * How long a render waits for a new server's first answer, when Loom says
31
+ * nothing at all.
32
+ *
33
+ * It is not a guess at how long Loom takes: a refusal or a failed connection
34
+ * ends the wait at once. It is the bound on a hang, which nothing else can tell
35
+ * apart from slowness, and it is set long enough that only a Loom that is down
36
+ * reaches it. The portal waits as long for its own store.
37
+ */
38
+ export const DEFAULT_FIRST_WAIT_MS = 5_000;
39
+ const scheduleWithTimeout = (run, afterMs) => {
40
+ const handle = setTimeout(run, afterMs);
41
+ /*
42
+ * A pending pull must not be the reason a process will not exit: a server
43
+ * shutting down between pulls would otherwise wait out the interval. Guarded
44
+ * because `unref` is Node's and not the web's.
45
+ */
46
+ if (typeof handle === "object" && typeof handle.unref === "function")
47
+ handle.unref();
48
+ return () => clearTimeout(handle);
49
+ };
50
+ export const startPullingLivePages = (options) => {
51
+ const interval = ceilingOf(options.intervalMs, DEFAULT_PULL_INTERVAL_MS);
52
+ const firstWait = ceilingOf(options.firstWaitMs, DEFAULT_FIRST_WAIT_MS);
53
+ const schedule = options.schedule ?? scheduleWithTimeout;
54
+ const now = options.now ?? Date.now;
55
+ let held = NO_LIVE_PAGES;
56
+ let inFlight;
57
+ let cancel;
58
+ let stopped = false;
59
+ let waited;
60
+ const announce = (outcome) => {
61
+ try {
62
+ options.onOutcome?.(outcome, held);
63
+ }
64
+ catch {
65
+ /*
66
+ * A host's logger throwing must not end the loop: the pages would then go
67
+ * stale for ever over a mistake in a sentence about them.
68
+ */
69
+ }
70
+ };
71
+ const once = async () => {
72
+ const outcome = await pullLivePages(options, held);
73
+ held = withPullOutcome(held, outcome, now());
74
+ announce(outcome);
75
+ return outcome;
76
+ };
77
+ const pull = () => {
78
+ if (inFlight !== undefined)
79
+ return inFlight;
80
+ const running = once().finally(() => {
81
+ inFlight = undefined;
82
+ });
83
+ inFlight = running;
84
+ return running;
85
+ };
86
+ const loop = () => {
87
+ const running = pull();
88
+ void running.finally(() => {
89
+ if (!stopped)
90
+ cancel = schedule(() => void loop(), interval);
91
+ });
92
+ return running;
93
+ };
94
+ const first = loop();
95
+ /*
96
+ * Started by the first render that asks rather than at boot, so the bound is
97
+ * on how long a reader waits and not on how long the process has been up.
98
+ */
99
+ const firstSettled = () => (waited ??= new Promise((resolve) => {
100
+ const giveUp = schedule(resolve, firstWait);
101
+ void first.finally(() => {
102
+ giveUp();
103
+ resolve();
104
+ });
105
+ }));
106
+ return {
107
+ ready: () => firstSettled().then(() => held),
108
+ held: () => held,
109
+ pullNow: pull,
110
+ stop: () => {
111
+ stopped = true;
112
+ cancel?.();
113
+ cancel = undefined;
114
+ },
115
+ };
116
+ };
117
+ //# sourceMappingURL=pulling.js.map
@@ -0,0 +1,129 @@
1
+ /**
2
+ * The pin a reader carries, and the version of a page it asks for.
3
+ *
4
+ * A reader's first page view under a window pins them to the project's live
5
+ * pages as they stood at that moment, and every page they read until the window
6
+ * runs out is drawn as it stood then (0383 clause 2). This is the whole of that
7
+ * in the customer's server: a number read out of a request's `Cookie` header, a
8
+ * version chosen against what the last pull held, and the `Set-Cookie` value a
9
+ * reader with no pin is given.
10
+ *
11
+ * **Nothing here reaches Loom, and nothing here is a reader id.** The pin is
12
+ * the number the project's live pages stood at when the reader first arrived,
13
+ * so every reader who arrived between the same two changes carries the same
14
+ * value (0383 clause 3). It goes on no signal and no pull (0146, 0262): the
15
+ * door is asked for the project's pages, never for this reader's.
16
+ *
17
+ * **A pin the server cannot resolve reads the newest live page**, and a server
18
+ * holding nothing renders the page as built (0383 clause 5). Every refusal in
19
+ * this file is that sentence — freshness is what fails, never the page.
20
+ */
21
+ import type { TreeId } from "../ids.js";
22
+ import type { LoomTree } from "../tree/tree.js";
23
+ /**
24
+ * One version of a page a pin can still be served.
25
+ *
26
+ * `until` is the number the change that replaced this version became live at,
27
+ * so this version is what a pin *below* that number asks for.
28
+ */
29
+ export type HeldVersion = {
30
+ readonly until: number;
31
+ readonly tree: LoomTree;
32
+ };
33
+ /**
34
+ * How long this project holds its readers, and what a pin needs to be
35
+ * resolved — the door's `window`, as the pull read it.
36
+ *
37
+ * **The numbers are milliseconds** (when each state of the pages was made), so
38
+ * they only ever increase and they do not go up by one. Everything here
39
+ * compares them and nothing counts them.
40
+ */
41
+ export type ReadersHeld = {
42
+ /** How long a reader keeps the pages they first saw. */
43
+ readonly ms: number;
44
+ /** The number below which a pin reads the newest pages: a snapshot or a revert raised it. */
45
+ readonly floor: number;
46
+ /** What the pages stand at now, which is what a new reader is pinned to. */
47
+ readonly number: number;
48
+ /** Each page's versions a pin can still be served, by the page's own id. */
49
+ readonly held: ReadonlyMap<TreeId, readonly HeldVersion[]>;
50
+ };
51
+ export type LiveWindow = {
52
+ readonly ms: 0;
53
+ } | ReadersHeld;
54
+ /**
55
+ * Readers are not held: every page view reads the newest live page, no cookie
56
+ * is set, and nothing is kept on a reader's device.
57
+ *
58
+ * This is the default a project has until somebody chooses otherwise (0383
59
+ * clause 1), what a server holds before its first pull, and what a door from
60
+ * before the window answers.
61
+ */
62
+ export declare const WINDOW_OFF: LiveWindow;
63
+ /** The cookie the pin is kept in, first-party, on the customer's own domain. */
64
+ export declare const PIN_COOKIE = "loom_pin";
65
+ /**
66
+ * The pin in a request's `Cookie` header, or `undefined` for a reader who has
67
+ * no usable one.
68
+ *
69
+ * **This asks one question and it is a syntactic one: is there a whole number
70
+ * under our name?** Whether that number can be resolved against the window the
71
+ * last pull brought is `livePageOf`'s question, and the two are deliberately
72
+ * apart — a pin from before the floor is a reader who *has* a pin and must not
73
+ * be given a new one (0383 clause 3), while a cookie holding something that is
74
+ * not a number is a reader who has none and gets one. Answering both here would
75
+ * make those one answer, and they are opposite acts.
76
+ *
77
+ * A header carrying our name twice is read as its first value. A browser sends
78
+ * one for a cookie set at `Path=/`, and two would have no single reading.
79
+ *
80
+ * **Only a value this file could have written is read**: digits, no sign, no
81
+ * point, no exponent, no leading zero. `Number` would read `1e3` as 1,000 and
82
+ * an empty string as `0` — and `0` is a pin below every floor rather than the
83
+ * absence of one, which is the difference between serving this reader the
84
+ * newest page and giving them a pin they never had. A cookie under our name
85
+ * holding anything else was not set by `pinCookieFor`, so its reader has no pin
86
+ * and gets one.
87
+ */
88
+ export declare const pinIn: (cookies: string | null | undefined) => number | undefined;
89
+ /**
90
+ * The version of this page to draw for a reader carrying this pin, or
91
+ * `undefined` where the pin asks for the newest live page.
92
+ *
93
+ * The four pins that read the newest are the four 0383 clause 5 names: no
94
+ * window set, a pin below the floor (so a snapshot from the site or an accepted
95
+ * revert has overtaken it — clause 4), a pin above the number the pages stand
96
+ * at, and a page this pin was never held a version of.
97
+ *
98
+ * **The version served is the one with the earliest `until` after the pin**,
99
+ * rather than the first in the list. The door answers them oldest first and
100
+ * both readings agree on an ordered list; reading the order would make a
101
+ * reader's page depend on it, and the cost of a list that arrived out of order
102
+ * is a reader served a *newer* page than they were pinned to, which is the one
103
+ * flip this record exists to remove.
104
+ */
105
+ export declare const heldVersionFor: (window: LiveWindow, page: TreeId, pin: number | undefined) => LoomTree | undefined;
106
+ /**
107
+ * The `Set-Cookie` value for this reader, or `undefined` to set none.
108
+ *
109
+ * **A reader who has a pin is never given another one** (0383 clause 3). A
110
+ * cookie renewed on every visit would hold a daily reader on one version for
111
+ * ever, so the expiry is set once, at first sight, and never extended. Nothing
112
+ * is set while the window is *Off*, which is every project that has not chosen
113
+ * one.
114
+ *
115
+ * **The expiry is `Max-Age` and there is no clock in this function.** Both are
116
+ * one choice: `Max-Age` is counted from when the reader's browser receives the
117
+ * response, which is first sight exactly, so the window cannot be lengthened or
118
+ * shortened by the server's clock drifting from the reader's — which is what
119
+ * `Expires` is compared against. It also makes this a pure function of what the
120
+ * last pull brought, with no `now` to be wrong about.
121
+ *
122
+ * A window under a second rounds to no cookie rather than to `Max-Age=0`: both
123
+ * hold the reader for no time at all, and a cookie that is dead on arrival is
124
+ * a thing somebody has to explain.
125
+ */
126
+ export declare const pinCookieFor: (held: {
127
+ readonly window: LiveWindow;
128
+ }, pin: number | undefined) => string | undefined;
129
+ //# sourceMappingURL=window.d.ts.map
@@ -0,0 +1,132 @@
1
+ /**
2
+ * The pin a reader carries, and the version of a page it asks for.
3
+ *
4
+ * A reader's first page view under a window pins them to the project's live
5
+ * pages as they stood at that moment, and every page they read until the window
6
+ * runs out is drawn as it stood then (0383 clause 2). This is the whole of that
7
+ * in the customer's server: a number read out of a request's `Cookie` header, a
8
+ * version chosen against what the last pull held, and the `Set-Cookie` value a
9
+ * reader with no pin is given.
10
+ *
11
+ * **Nothing here reaches Loom, and nothing here is a reader id.** The pin is
12
+ * the number the project's live pages stood at when the reader first arrived,
13
+ * so every reader who arrived between the same two changes carries the same
14
+ * value (0383 clause 3). It goes on no signal and no pull (0146, 0262): the
15
+ * door is asked for the project's pages, never for this reader's.
16
+ *
17
+ * **A pin the server cannot resolve reads the newest live page**, and a server
18
+ * holding nothing renders the page as built (0383 clause 5). Every refusal in
19
+ * this file is that sentence — freshness is what fails, never the page.
20
+ */
21
+ /**
22
+ * Whether this project holds its readers at all.
23
+ *
24
+ * A predicate rather than `window.ms === 0` at each use: `ms` is a length on
25
+ * one side of the union and the literal `0` on the other, so a comparison does
26
+ * not narrow it and every reader of this file would have to know that.
27
+ */
28
+ const holdsReaders = (window) => window.ms !== 0;
29
+ /**
30
+ * Readers are not held: every page view reads the newest live page, no cookie
31
+ * is set, and nothing is kept on a reader's device.
32
+ *
33
+ * This is the default a project has until somebody chooses otherwise (0383
34
+ * clause 1), what a server holds before its first pull, and what a door from
35
+ * before the window answers.
36
+ */
37
+ export const WINDOW_OFF = { ms: 0 };
38
+ /** The cookie the pin is kept in, first-party, on the customer's own domain. */
39
+ export const PIN_COOKIE = "loom_pin";
40
+ /** The one spelling of a pin: what `pinCookieFor` writes, and nothing else. */
41
+ const DECIMAL = /^(?:0|[1-9][0-9]*)$/;
42
+ /**
43
+ * The pin in a request's `Cookie` header, or `undefined` for a reader who has
44
+ * no usable one.
45
+ *
46
+ * **This asks one question and it is a syntactic one: is there a whole number
47
+ * under our name?** Whether that number can be resolved against the window the
48
+ * last pull brought is `livePageOf`'s question, and the two are deliberately
49
+ * apart — a pin from before the floor is a reader who *has* a pin and must not
50
+ * be given a new one (0383 clause 3), while a cookie holding something that is
51
+ * not a number is a reader who has none and gets one. Answering both here would
52
+ * make those one answer, and they are opposite acts.
53
+ *
54
+ * A header carrying our name twice is read as its first value. A browser sends
55
+ * one for a cookie set at `Path=/`, and two would have no single reading.
56
+ *
57
+ * **Only a value this file could have written is read**: digits, no sign, no
58
+ * point, no exponent, no leading zero. `Number` would read `1e3` as 1,000 and
59
+ * an empty string as `0` — and `0` is a pin below every floor rather than the
60
+ * absence of one, which is the difference between serving this reader the
61
+ * newest page and giving them a pin they never had. A cookie under our name
62
+ * holding anything else was not set by `pinCookieFor`, so its reader has no pin
63
+ * and gets one.
64
+ */
65
+ export const pinIn = (cookies) => {
66
+ if (cookies === undefined || cookies === null)
67
+ return undefined;
68
+ const value = cookies
69
+ .split(";")
70
+ .map((pair) => pair.trim())
71
+ .find((pair) => pair.startsWith(`${PIN_COOKIE}=`))
72
+ ?.slice(PIN_COOKIE.length + 1);
73
+ if (value === undefined || !DECIMAL.test(value))
74
+ return undefined;
75
+ const pin = Number(value);
76
+ return Number.isSafeInteger(pin) ? pin : undefined;
77
+ };
78
+ /**
79
+ * The version of this page to draw for a reader carrying this pin, or
80
+ * `undefined` where the pin asks for the newest live page.
81
+ *
82
+ * The four pins that read the newest are the four 0383 clause 5 names: no
83
+ * window set, a pin below the floor (so a snapshot from the site or an accepted
84
+ * revert has overtaken it — clause 4), a pin above the number the pages stand
85
+ * at, and a page this pin was never held a version of.
86
+ *
87
+ * **The version served is the one with the earliest `until` after the pin**,
88
+ * rather than the first in the list. The door answers them oldest first and
89
+ * both readings agree on an ordered list; reading the order would make a
90
+ * reader's page depend on it, and the cost of a list that arrived out of order
91
+ * is a reader served a *newer* page than they were pinned to, which is the one
92
+ * flip this record exists to remove.
93
+ */
94
+ export const heldVersionFor = (window, page, pin) => {
95
+ if (pin === undefined || !holdsReaders(window))
96
+ return undefined;
97
+ if (!Number.isSafeInteger(pin) || pin < window.floor || pin > window.number)
98
+ return undefined;
99
+ return (window.held.get(page) ?? [])
100
+ .filter((version) => version.until > pin)
101
+ .reduce((earliest, version) => earliest === undefined || version.until < earliest.until ? version : earliest, undefined)?.tree;
102
+ };
103
+ /**
104
+ * The `Set-Cookie` value for this reader, or `undefined` to set none.
105
+ *
106
+ * **A reader who has a pin is never given another one** (0383 clause 3). A
107
+ * cookie renewed on every visit would hold a daily reader on one version for
108
+ * ever, so the expiry is set once, at first sight, and never extended. Nothing
109
+ * is set while the window is *Off*, which is every project that has not chosen
110
+ * one.
111
+ *
112
+ * **The expiry is `Max-Age` and there is no clock in this function.** Both are
113
+ * one choice: `Max-Age` is counted from when the reader's browser receives the
114
+ * response, which is first sight exactly, so the window cannot be lengthened or
115
+ * shortened by the server's clock drifting from the reader's — which is what
116
+ * `Expires` is compared against. It also makes this a pure function of what the
117
+ * last pull brought, with no `now` to be wrong about.
118
+ *
119
+ * A window under a second rounds to no cookie rather than to `Max-Age=0`: both
120
+ * hold the reader for no time at all, and a cookie that is dead on arrival is
121
+ * a thing somebody has to explain.
122
+ */
123
+ export const pinCookieFor = (held, pin) => {
124
+ const { window } = held;
125
+ if (pin !== undefined || !holdsReaders(window))
126
+ return undefined;
127
+ const seconds = Math.floor(window.ms / 1000);
128
+ return seconds < 1
129
+ ? undefined
130
+ : `${PIN_COOKIE}=${window.number}; Max-Age=${seconds}; Path=/; HttpOnly; Secure; SameSite=Lax`;
131
+ };
132
+ //# sourceMappingURL=window.js.map
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The root of an addressed page within `scope`, or `undefined` if there is none.
3
+ *
4
+ * The root is the one element carrying the tree it belongs to, so this is the
5
+ * element a reader-signal broadcast asks for. A host passes `document` on a
6
+ * page it serves whole, or the container it rendered a tree into when the page
7
+ * holds other things as well.
8
+ *
9
+ * **The scope counts as its own answer.** `querySelector` searches descendants
10
+ * only, so a host holding the root element and asking this for the root would
11
+ * be told there is none — the one answer that is never useful. Including the
12
+ * scope makes the function idempotent instead: feeding it its own result
13
+ * returns that result.
14
+ *
15
+ * **The first in document order when a scope holds more than one tree**, which
16
+ * is `querySelector`'s own rule rather than a new one. A host rendering two
17
+ * trees knows where it put them and should ask within each; a host that does
18
+ * not know would not be helped by a different choice here.
19
+ *
20
+ * `undefined` rather than `null` because *there is no addressed page here* is
21
+ * the absence of an answer rather than an answer, and because a caller reaching
22
+ * through an optional ref otherwise has two empty values to test for on the way
23
+ * out where one will do.
24
+ *
25
+ * The saving is on the way **out** and not on the way in: `scope` is
26
+ * `ParentNode`, so a caller guards its ref and then asks —
27
+ * `container === null ? undefined : addressedRootIn(container)`, which is what
28
+ * `reader-signals-live.tsx` writes. An earlier version of this note showed
29
+ * `addressedRootIn(frame.current)`, which does not typecheck. The narrow
30
+ * parameter is the honest type for a function whose contract is *somewhere to
31
+ * look*.
32
+ */
33
+ export declare const addressedRootIn: (scope: ParentNode) => Element | undefined;
34
+ export { LOOM_AUDIENCE_ATTRIBUTE, LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE, } from "./editable.js";
35
+ //# sourceMappingURL=addressed.d.ts.map
@@ -0,0 +1,79 @@
1
+ import { LOOM_TREE_ATTRIBUTE } from "./editable.js";
2
+ /**
3
+ * The names a render writes onto a published page, and how to find the page.
4
+ *
5
+ * `addressed: true` stamps a node's identity onto the markup of a live page:
6
+ * node id and type on each decorated element, tree id and revision on the root
7
+ * (0136). Those four names are the whole of the contract between a render and
8
+ * anything that reads a published page afterwards — a broadcaster gathering
9
+ * reader signals, a portal authoring an intent from the DOM, a script bringing
10
+ * a named node into view.
11
+ *
12
+ * **This module exists so that reading them costs a browser nothing.** The
13
+ * names were published only through `@jam-overture/loom/react`, which carries
14
+ * the render seam and every primitive's registration, so a browser bundle that
15
+ * imported one string from there carried all of it. That is the mistake the
16
+ * broadcaster's own entry point was split out to stop and the one `disclosed.ts`
17
+ * was pulled out of `behaviour.ts` to avoid (0136), and it is invisible in a
18
+ * diff: one import line, every test green.
19
+ *
20
+ * So the choice a host faced was a heavy import or a hand-written
21
+ * `"[data-loom-tree]"`, and the hosts that ship a browser bundle wrote the
22
+ * literal. Measured in this repository on 5 November: the spelling written out
23
+ * by hand in four files, the constant imported from the heavy door in two more,
24
+ * one of which is a client component that reaches it for a single string.
25
+ *
26
+ * Nothing here loads a package, which `addressed.weight.test.ts` holds it to by
27
+ * walking what it imports rather than by trusting this paragraph.
28
+ *
29
+ * **Reading, not writing.** `editableAttributes` builds the attributes and
30
+ * stays on the render seam, where the tree types it needs already are. A host
31
+ * does not write these names; the renderer does.
32
+ */
33
+ /**
34
+ * By node type rather than `instanceof Element`, which is false for an element
35
+ * from another realm — an iframe's document has an `Element` of its own, and a
36
+ * page inspecting a frame it rendered is a host this door is for. A node type
37
+ * is a number the DOM agrees on across realms, so the test does not have to
38
+ * know which one it is in.
39
+ */
40
+ const isElement = (node) => node.nodeType === 1;
41
+ /**
42
+ * The root of an addressed page within `scope`, or `undefined` if there is none.
43
+ *
44
+ * The root is the one element carrying the tree it belongs to, so this is the
45
+ * element a reader-signal broadcast asks for. A host passes `document` on a
46
+ * page it serves whole, or the container it rendered a tree into when the page
47
+ * holds other things as well.
48
+ *
49
+ * **The scope counts as its own answer.** `querySelector` searches descendants
50
+ * only, so a host holding the root element and asking this for the root would
51
+ * be told there is none — the one answer that is never useful. Including the
52
+ * scope makes the function idempotent instead: feeding it its own result
53
+ * returns that result.
54
+ *
55
+ * **The first in document order when a scope holds more than one tree**, which
56
+ * is `querySelector`'s own rule rather than a new one. A host rendering two
57
+ * trees knows where it put them and should ask within each; a host that does
58
+ * not know would not be helped by a different choice here.
59
+ *
60
+ * `undefined` rather than `null` because *there is no addressed page here* is
61
+ * the absence of an answer rather than an answer, and because a caller reaching
62
+ * through an optional ref otherwise has two empty values to test for on the way
63
+ * out where one will do.
64
+ *
65
+ * The saving is on the way **out** and not on the way in: `scope` is
66
+ * `ParentNode`, so a caller guards its ref and then asks —
67
+ * `container === null ? undefined : addressedRootIn(container)`, which is what
68
+ * `reader-signals-live.tsx` writes. An earlier version of this note showed
69
+ * `addressedRootIn(frame.current)`, which does not typecheck. The narrow
70
+ * parameter is the honest type for a function whose contract is *somewhere to
71
+ * look*.
72
+ */
73
+ export const addressedRootIn = (scope) => {
74
+ if (isElement(scope) && scope.hasAttribute(LOOM_TREE_ATTRIBUTE))
75
+ return scope;
76
+ return scope.querySelector(`[${LOOM_TREE_ATTRIBUTE}]`) ?? undefined;
77
+ };
78
+ export { LOOM_AUDIENCE_ATTRIBUTE, LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE, } from "./editable.js";
79
+ //# sourceMappingURL=addressed.js.map
@@ -0,0 +1,70 @@
1
+ import type { RampMode } from "../theme/apply.js";
2
+ import type { ResolvedTheme } from "../theme/theme.js";
3
+ /**
4
+ * A resolved theme as the `:root` rule a host puts on its own document.
5
+ *
6
+ * Every variable `themeStyle` mounts, and then the ground — `background-color`,
7
+ * `color` and `color-scheme` — so one rule answers both the page's palette and
8
+ * the furniture around it. `:root` **is** the document element, which is what
9
+ * makes the ground reach the overscroll area past the end of a short page; the
10
+ * same declarations on a wrapper inside the document leave the browser's own
11
+ * white there, invisible under a light palette and not under the next one.
12
+ *
13
+ * Takes a `ResolvedTheme` rather than a `ThemeResolution`, the bargain
14
+ * `themeStyle` and `themeGround` both make: there is no fallback theme (0049),
15
+ * so *the tree names no theme* is the host's question about its own document and
16
+ * not one the runtime can answer by handing back a rule.
17
+ *
18
+ * **The ground may be absent and the rule is still returned.** A palette whose
19
+ * body-copy pair cannot be read gets no ground rather than a guessed one, and
20
+ * `ThemeGround` already documents what follows: whatever `color-scheme` the
21
+ * host's own stylesheet sets stands. The variables are unaffected by that and
22
+ * are the half a host cannot write for itself, so withholding the rule over it
23
+ * would cost a page its whole palette to avoid mis-stating one declaration of
24
+ * it. Every registered palette resolves both ends.
25
+ *
26
+ * Nothing is restated here: both halves are derived from the one resolved theme
27
+ * by the two functions a surface uses, so only the serialisation is this
28
+ * function's own and a re-theme has no second source of truth to miss.
29
+ */
30
+ export declare const themeDocumentCss: (theme: ResolvedTheme, ramp?: RampMode) => string;
31
+ /**
32
+ * The ground alone, as the same `:root` rule — for a host whose page is already
33
+ * a tree to its edges.
34
+ *
35
+ * `themeDocumentCss` above answers a host that has no tree: the
36
+ * application shell draws its own frame, mounts nothing, and needs every
37
+ * variable as well as the ground. A *surface* is the other host, and it is not
38
+ * the same host. `(marketing)` composes a tree whose root primitive already
39
+ * mounts every `--loom-*` below it, so the variables in the document rule are
40
+ * read by nothing inside the page — they are a second copy of a mounting that
41
+ * already happened, in the one place no primitive looks. What that page actually
42
+ * needs from the document is the three declarations a tree cannot reach:
43
+ * `background-color`, `color` and `color-scheme`, on the element the scrollbar
44
+ * and the overscroll canvas belong to.
45
+ *
46
+ * `Loom marketing` measured the duplicate at 1,976 bytes on `/?theme=bold` and
47
+ * filed the shape rather than hand-writing the shorter rule, which was the right
48
+ * call twice over: a three-declaration rule written in a surface is a copy of a
49
+ * decision the palette owns, kept where the palette cannot reach it, and that is
50
+ * the hazard [`themeGround`](./theme.ts) and the docblock above both exist to
51
+ * refuse. The answer is to publish the half, not to let a caller rebuild it.
52
+ *
53
+ * **A second export rather than a flag on the first**, because the two differ in
54
+ * their inputs and not only in their output. `ramp` decides how the variables
55
+ * are written and has nothing to say about the ground, so a flag would leave a
56
+ * parameter that is read on one setting and silently ignored on the other —
57
+ * and a caller passing both would have written something that cannot be true.
58
+ * Two functions, one private serialiser, and neither has an argument it
59
+ * disregards.
60
+ *
61
+ * **`undefined` when the palette has no ground**, which mirrors `themeGround`
62
+ * exactly and for its reason: a palette whose body-copy pair cannot be read gets
63
+ * no ground rather than a guessed one. `themeDocumentCss` still returns its rule
64
+ * in that case because the variables are the half the host cannot write for
65
+ * itself and they are unaffected. Here there is no other half, so a rule would
66
+ * be an empty block — and *nothing to say* is a state a caller should have to
67
+ * answer rather than render. Every registered palette resolves both ends.
68
+ */
69
+ export declare const themeGroundCss: (theme: ResolvedTheme) => string | undefined;
70
+ //# sourceMappingURL=document-theme.d.ts.map