@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.
- package/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/resolve.d.ts +1 -1
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +192 -46
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/gate.js +69 -10
- package/dist/runtime/index.d.ts +1 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/policy-change.js +8 -2
- package/dist/runtime/policy-log.d.ts +5 -5
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/sdk/definition.d.ts +65 -6
- package/dist/sdk/definition.js +44 -0
- package/dist/sdk/registry.d.ts +17 -1
- package/dist/sdk/registry.js +39 -0
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/broadcast.d.ts +25 -15
- package/dist/signals/broadcast.js +209 -36
- package/dist/signals/collect.d.ts +137 -43
- package/dist/signals/collect.js +103 -36
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +51 -0
- package/dist/signals/counters.js +58 -0
- package/dist/signals/deployment-change.d.ts +28 -4
- package/dist/signals/deployment-change.js +57 -16
- package/dist/signals/deployment.d.ts +18 -5
- package/dist/signals/deployment.js +37 -11
- package/dist/signals/door.d.ts +34 -12
- package/dist/signals/door.js +37 -13
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +60 -0
- package/dist/signals/funnel.js +35 -20
- package/dist/signals/health.d.ts +201 -4
- package/dist/signals/health.js +214 -2
- package/dist/signals/index.d.ts +19 -0
- package/dist/signals/index.js +19 -0
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +112 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-reach-change.d.ts +10 -0
- package/dist/signals/library-reach-change.js +11 -3
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.js +2 -6
- package/dist/signals/memory.js +142 -1
- package/dist/signals/migrate.d.ts +6 -5
- package/dist/signals/migrate.js +150 -6
- package/dist/signals/notice.d.ts +88 -33
- package/dist/signals/notice.js +38 -16
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +25 -15
- package/dist/signals/parts.js +32 -73
- package/dist/signals/postgres.js +400 -26
- package/dist/signals/region.d.ts +1 -1
- package/dist/signals/retention.d.ts +43 -21
- package/dist/signals/retention.js +25 -8
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +127 -1
- package/dist/signals/rollup.js +211 -24
- package/dist/signals/schema.d.ts +640 -3
- package/dist/signals/schema.js +239 -3
- package/dist/signals/silences.d.ts +310 -11
- package/dist/signals/silences.js +243 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +125 -4
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +11 -0
- package/dist/store/index.js +11 -0
- package/dist/store/migrate.d.ts +26 -0
- package/dist/store/migrate.js +64 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres.d.ts +1 -0
- package/dist/store/postgres.js +1 -0
- package/dist/store/schema.d.ts +312 -0
- package/dist/store/schema.js +77 -0
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +32 -0
- package/dist/telemetry/memory.js +10 -1
- package/dist/telemetry/postgres.js +18 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +1 -0
- package/dist/testing/contracts.js +1 -0
- package/dist/testing/journal-contract.js +158 -5
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/tree/apply.js +13 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/package.json +39 -96
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- 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
|