@drupflare/spool 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +444 -18
  2. package/dist/cdn/client.js +1 -1
  3. package/dist/cdn/manifest.json +7 -7
  4. package/dist/cdn/spool-sw.js +1 -1
  5. package/dist/client/activity.d.ts +37 -0
  6. package/dist/client/activity.js +114 -0
  7. package/dist/client/entry.js +2 -1
  8. package/dist/client/index.d.ts +1 -0
  9. package/dist/client/index.js +1 -0
  10. package/dist/media/embeds.d.ts +60 -0
  11. package/dist/media/embeds.js +135 -0
  12. package/dist/media/headers.d.ts +13 -0
  13. package/dist/media/headers.js +44 -0
  14. package/dist/media/html.d.ts +27 -0
  15. package/dist/media/html.js +93 -0
  16. package/dist/media/image.d.ts +222 -0
  17. package/dist/media/image.js +413 -0
  18. package/dist/media/index.d.ts +6 -0
  19. package/dist/media/index.js +6 -0
  20. package/dist/media/lazy.d.ts +26 -0
  21. package/dist/media/lazy.js +74 -0
  22. package/dist/media/responsive.d.ts +45 -0
  23. package/dist/media/responsive.js +98 -0
  24. package/dist/media/video.d.ts +30 -0
  25. package/dist/media/video.js +75 -0
  26. package/dist/protocol/envelope.d.ts +2 -0
  27. package/dist/protocol/envelope.js +12 -2
  28. package/dist/protocol/errors.d.ts +1 -1
  29. package/dist/protocol/hash.d.ts +2 -0
  30. package/dist/protocol/hash.js +8 -0
  31. package/dist/protocol/index.d.ts +4 -0
  32. package/dist/protocol/index.js +4 -0
  33. package/dist/protocol/inline.d.ts +14 -0
  34. package/dist/protocol/inline.js +43 -0
  35. package/dist/protocol/navigation.d.ts +81 -0
  36. package/dist/protocol/navigation.js +249 -0
  37. package/dist/protocol/normalise.d.ts +4 -3
  38. package/dist/protocol/normalise.js +6 -4
  39. package/dist/protocol/provision.d.ts +6 -1
  40. package/dist/protocol/provision.js +15 -5
  41. package/dist/protocol/query.d.ts +80 -0
  42. package/dist/protocol/query.js +153 -0
  43. package/dist/protocol/route.d.ts +80 -4
  44. package/dist/protocol/route.js +63 -0
  45. package/dist/proxy/bases.d.ts +53 -0
  46. package/dist/proxy/bases.js +76 -0
  47. package/dist/proxy/dictionary.d.ts +58 -0
  48. package/dist/proxy/dictionary.js +197 -0
  49. package/dist/proxy/index.d.ts +2 -0
  50. package/dist/proxy/index.js +2 -0
  51. package/dist/proxy/proxy.d.ts +47 -0
  52. package/dist/proxy/proxy.js +140 -15
  53. package/dist/report/capacity.d.ts +59 -0
  54. package/dist/report/capacity.js +76 -0
  55. package/dist/report/channels.d.ts +60 -0
  56. package/dist/report/channels.js +65 -0
  57. package/dist/report/derive.d.ts +2 -0
  58. package/dist/report/derive.js +6 -2
  59. package/dist/report/index.d.ts +4 -0
  60. package/dist/report/index.js +4 -0
  61. package/dist/report/institution.d.ts +97 -0
  62. package/dist/report/institution.js +79 -0
  63. package/dist/report/ledger.d.ts +197 -0
  64. package/dist/report/ledger.js +308 -0
  65. package/dist/report/measurement.d.ts +1 -1
  66. package/dist/report/measurement.js +7 -1
  67. package/dist/report/traffic.d.ts +11 -2
  68. package/dist/report/traffic.js +13 -3
  69. package/dist/server/embedded.d.ts +3 -3
  70. package/dist/server/embedded.js +3 -3
  71. package/dist/server/index.d.ts +1 -0
  72. package/dist/server/index.js +1 -0
  73. package/dist/server/spool.d.ts +20 -0
  74. package/dist/server/spool.js +62 -9
  75. package/dist/sw/render.d.ts +3 -1
  76. package/dist/sw/render.js +14 -1
  77. package/dist/sw/replica.d.ts +2 -0
  78. package/dist/sw/replica.js +6 -0
  79. package/dist/sw/router.js +2 -2
  80. package/dist/sw/runtime.js +104 -9
  81. package/dist/trim/tokens.d.ts +4 -0
  82. package/dist/trim/tokens.js +1 -1
  83. package/package.json +10 -4
@@ -0,0 +1,30 @@
1
+ import type { MediaSignals } from './headers.js';
2
+ /**
3
+ * What `spoolProxy({ video })` does to `<video>` start tags. `preload` is the value to set, or
4
+ * `false` to leave the attribute alone. `autoplay: 'defer'` removes the `autoplay` attribute, marks
5
+ * the tag `data-spool-autoplay`, adds `controls` so a visitor can start the video, and sets
6
+ * `preload` to `none` unless the option is `metadata`. With `'keep'` the `autoplay` attribute stays,
7
+ * and a video that autoplays loads its file whatever `preload` says. `when` limits the rewrite to a
8
+ * visitor who sent `Save-Data: on` (`save-data`) or who also has an `ECT` of `slow-2g`, `2g` or
9
+ * `3g` (`slow`). Defaults: `preload: 'none'`, `autoplay: 'keep'`, `when: 'always'`.
10
+ */
11
+ export type VideoOptions = {
12
+ preload?: 'none' | 'metadata' | false;
13
+ autoplay?: 'keep' | 'defer';
14
+ when?: 'always' | 'save-data' | 'slow';
15
+ };
16
+ /** `VideoOptions` with every default applied */
17
+ export type ResolvedVideoOptions = Required<VideoOptions>;
18
+ /** applies the defaults to `options` and refuses an unknown value with `ProtocolError('bad-route')` */
19
+ export declare function resolveVideoOptions(options?: VideoOptions): ResolvedVideoOptions;
20
+ /**
21
+ * Rewrites the `<video>` start tags of `html` as `options` ask and says how many tags changed.
22
+ * It reads tags with `tagsOf` and skips a tag inside an HTML comment, a tag that never closes, and
23
+ * every element that is not `<video>`. A tag that already says what the options ask for is not
24
+ * counted. Everything outside the edited start tags stays byte for byte, and the edits are ASCII,
25
+ * so a page in another charset read one byte per character comes back the same way.
26
+ */
27
+ export declare function rewriteVideo(html: string, options: VideoOptions, signals: MediaSignals): {
28
+ html: string;
29
+ rewritten: number;
30
+ };
@@ -0,0 +1,75 @@
1
+ import { ProtocolError } from '../protocol/errors.js';
2
+ import { appendAttributes, applyEdits, find, setValue, tagsNamed } from './html.js';
3
+ /** applies the defaults to `options` and refuses an unknown value with `ProtocolError('bad-route')` */
4
+ export function resolveVideoOptions(options = {}) {
5
+ const resolved = {
6
+ preload: options.preload ?? 'none',
7
+ autoplay: options.autoplay ?? 'keep',
8
+ when: options.when ?? 'always'
9
+ };
10
+ if (![false, 'none', 'metadata'].includes(resolved.preload)) {
11
+ throw new ProtocolError('bad-route', `video preload must be 'none', 'metadata' or false`);
12
+ }
13
+ if (!['keep', 'defer'].includes(resolved.autoplay)) {
14
+ throw new ProtocolError('bad-route', `video autoplay must be 'keep' or 'defer'`);
15
+ }
16
+ if (!['always', 'save-data', 'slow'].includes(resolved.when)) {
17
+ throw new ProtocolError('bad-route', `video when must be 'always', 'save-data' or 'slow'`);
18
+ }
19
+ return resolved;
20
+ }
21
+ function editsFor(html, tag, options) {
22
+ const edits = [];
23
+ const autoplay = find(tag, 'autoplay');
24
+ const defer = options.autoplay === 'defer' && autoplay !== undefined;
25
+ const target = defer ? (options.preload === 'metadata' ? 'metadata' : 'none') : options.preload;
26
+ const added = [];
27
+ if (defer) {
28
+ if (find(tag, 'data-spool-autoplay')) {
29
+ let from = autoplay.start;
30
+ while (from > tag.start && /\s/.test(html[from - 1]))
31
+ from--;
32
+ edits.push({ at: from, to: autoplay.end, text: '' });
33
+ }
34
+ else {
35
+ edits.push({ at: autoplay.start, to: autoplay.end, text: 'data-spool-autoplay' });
36
+ }
37
+ if (!find(tag, 'controls'))
38
+ added.push('controls');
39
+ }
40
+ if (target !== false) {
41
+ const preload = find(tag, 'preload');
42
+ if (!preload)
43
+ added.push(`preload="${target}"`);
44
+ else if (preload.value.trim().toLowerCase() !== target) {
45
+ edits.push(setValue(html, preload, target));
46
+ }
47
+ }
48
+ if (added.length > 0)
49
+ edits.push(appendAttributes(html, tag, added));
50
+ return edits;
51
+ }
52
+ /**
53
+ * Rewrites the `<video>` start tags of `html` as `options` ask and says how many tags changed.
54
+ * It reads tags with `tagsOf` and skips a tag inside an HTML comment, a tag that never closes, and
55
+ * every element that is not `<video>`. A tag that already says what the options ask for is not
56
+ * counted. Everything outside the edited start tags stays byte for byte, and the edits are ASCII,
57
+ * so a page in another charset read one byte per character comes back the same way.
58
+ */
59
+ export function rewriteVideo(html, options, signals) {
60
+ const resolved = resolveVideoOptions(options);
61
+ const applies = resolved.when === 'always' ||
62
+ (resolved.when === 'save-data' ? signals.saveData : signals.slow || signals.saveData);
63
+ if (!applies)
64
+ return { html, rewritten: 0 };
65
+ const edits = [];
66
+ let rewritten = 0;
67
+ for (const tag of tagsNamed(html, 'video')) {
68
+ const tagEdits = editsFor(html, tag, resolved);
69
+ if (tagEdits.length === 0)
70
+ continue;
71
+ rewritten++;
72
+ edits.push(...tagEdits);
73
+ }
74
+ return { html: applyEdits(html, edits), rewritten };
75
+ }
@@ -19,6 +19,8 @@ export type EnvelopeArtifact = {
19
19
  deps: string[];
20
20
  /** the vector cursor the artifact reflects */
21
21
  version: number;
22
+ /** base64url SHA-256 of the artifact's shell as the page body carries it, minus the client tag */
23
+ hash?: string;
22
24
  };
23
25
  /** every spool header of a response, decoded; an absent header is an absent field */
24
26
  export type Envelope = {
@@ -14,6 +14,7 @@ export const HEADERS = {
14
14
  /** `Spool-Clear` token that wipes everything the worker holds */
15
15
  export const CLEAR_ALL = '*';
16
16
  const PARTITION = /^[A-Za-z0-9_-]{1,128}$/;
17
+ const HASH = /^[A-Za-z0-9_-]{43}$/;
17
18
  function bad(message) {
18
19
  throw new ProtocolError('bad-header', message);
19
20
  }
@@ -43,12 +44,18 @@ export function encodeEnvelope(envelope) {
43
44
  };
44
45
  const { artifact, invalidate, clear, vector, seen, partition } = envelope;
45
46
  if (artifact) {
46
- out[HEADERS.artifact] = [
47
+ const fields = [
47
48
  `id=${encodeURIComponent(artifact.id)}`,
48
49
  `scope=${artifact.scope}`,
49
50
  `deps=${artifact.deps.map(encodeURIComponent).join(',')}`,
50
51
  `v=${artifact.version}`
51
- ].join('; ');
52
+ ];
53
+ if (artifact.hash !== undefined) {
54
+ if (!HASH.test(artifact.hash))
55
+ return bad('hash must be a base64url token');
56
+ fields.push(`h=${artifact.hash}`);
57
+ }
58
+ out[HEADERS.artifact] = fields.join('; ');
52
59
  }
53
60
  const changed = Object.entries(invalidate ?? {});
54
61
  if (changed.length > 0) {
@@ -130,6 +137,9 @@ export function decodeEnvelope(headers) {
130
137
  deps: list(fields.get('deps') ?? '').map((d) => decode(d, 'Spool-Artifact deps')),
131
138
  version: integer(version, 'Spool-Artifact v')
132
139
  };
140
+ const hash = fields.get('h');
141
+ if (hash !== undefined && HASH.test(hash))
142
+ out.artifact.hash = hash;
133
143
  }
134
144
  const invalidate = headers.get(HEADERS.invalidate);
135
145
  if (invalidate !== null) {
@@ -1,5 +1,5 @@
1
1
  /** why a protocol value was refused */
2
- export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | 'bad-beacon' | 'bad-template' | 'bad-manifest';
2
+ export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | 'bad-beacon' | 'bad-template' | 'bad-manifest' | 'bad-nav';
3
3
  /** thrown for malformed protocol input; `code` names the family so callers can map it to a status */
4
4
  export declare class ProtocolError extends Error {
5
5
  readonly code: ProtocolErrorCode;
@@ -0,0 +1,2 @@
1
+ /** base64url SHA-256 of the UTF-8 bytes of `text`, without padding */
2
+ export declare function shellHash(text: string): Promise<string>;
@@ -0,0 +1,8 @@
1
+ /** base64url SHA-256 of the UTF-8 bytes of `text`, without padding */
2
+ export async function shellHash(text) {
3
+ const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)));
4
+ let binary = '';
5
+ for (const byte of digest)
6
+ binary += String.fromCharCode(byte);
7
+ return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
8
+ }
@@ -6,10 +6,14 @@ export * from './config.js';
6
6
  export * from './envelope.js';
7
7
  export * from './errors.js';
8
8
  export * from './graph.js';
9
+ export * from './hash.js';
10
+ export * from './inline.js';
9
11
  export * from './manifest.js';
12
+ export * from './navigation.js';
10
13
  export * from './normalise.js';
11
14
  export * from './pattern.js';
12
15
  export * from './provision.js';
16
+ export * from './query.js';
13
17
  export * from './route.js';
14
18
  export * from './sync.js';
15
19
  export * from './tag.js';
@@ -6,10 +6,14 @@ export * from './config.js';
6
6
  export * from './envelope.js';
7
7
  export * from './errors.js';
8
8
  export * from './graph.js';
9
+ export * from './hash.js';
10
+ export * from './inline.js';
9
11
  export * from './manifest.js';
12
+ export * from './navigation.js';
10
13
  export * from './normalise.js';
11
14
  export * from './pattern.js';
12
15
  export * from './provision.js';
16
+ export * from './query.js';
13
17
  export * from './route.js';
14
18
  export * from './sync.js';
15
19
  export * from './tag.js';
@@ -0,0 +1,14 @@
1
+ /** the opening tag of the element that carries a page's own artifact */
2
+ export declare const INLINE_OPEN = "<script type=\"application/spool+json\" data-spool-artifact>";
3
+ /** `json` with every character that could end or confuse a script element written as a `\u` escape */
4
+ export declare function escapeInline(json: string): string;
5
+ /** the script element that carries `text`, which must already be escaped */
6
+ export declare function inlineElement(text: string): string;
7
+ /**
8
+ * `html` with the element placed before the last `</body>`, or at the end when the page has none.
9
+ */
10
+ export declare function placeInline(html: string, element: string): string;
11
+ /** the text of the last inline element in `html`, or null when there is none */
12
+ export declare function readInline(html: string): string | null;
13
+ /** `html` without any inline element, which is data and no part of the page */
14
+ export declare function stripInline(html: string): string;
@@ -0,0 +1,43 @@
1
+ /** the opening tag of the element that carries a page's own artifact */
2
+ export const INLINE_OPEN = '<script type="application/spool+json" data-spool-artifact>';
3
+ const INLINE_CLOSE = '</script>';
4
+ const UNSAFE = new RegExp(`[<>&${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
5
+ /** `json` with every character that could end or confuse a script element written as a `\u` escape */
6
+ export function escapeInline(json) {
7
+ return json.replace(UNSAFE, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
8
+ }
9
+ /** the script element that carries `text`, which must already be escaped */
10
+ export function inlineElement(text) {
11
+ return `${INLINE_OPEN}${text}${INLINE_CLOSE}`;
12
+ }
13
+ /**
14
+ * `html` with the element placed before the last `</body>`, or at the end when the page has none.
15
+ */
16
+ export function placeInline(html, element) {
17
+ let at = -1;
18
+ for (const match of html.matchAll(/<\/body\s*>/gi))
19
+ at = match.index;
20
+ return at < 0 ? html + element : html.slice(0, at) + element + html.slice(at);
21
+ }
22
+ /** the text of the last inline element in `html`, or null when there is none */
23
+ export function readInline(html) {
24
+ const open = html.lastIndexOf(INLINE_OPEN);
25
+ if (open < 0)
26
+ return null;
27
+ const from = open + INLINE_OPEN.length;
28
+ const close = html.indexOf(INLINE_CLOSE, from);
29
+ return close < 0 ? null : html.slice(from, close);
30
+ }
31
+ /** `html` without any inline element, which is data and no part of the page */
32
+ export function stripInline(html) {
33
+ let out = '';
34
+ let at = 0;
35
+ for (;;) {
36
+ const open = html.indexOf(INLINE_OPEN, at);
37
+ const close = open < 0 ? -1 : html.indexOf(INLINE_CLOSE, open + INLINE_OPEN.length);
38
+ if (close < 0)
39
+ return out + html.slice(at);
40
+ out += html.slice(at, open);
41
+ at = close + INLINE_CLOSE.length;
42
+ }
43
+ }
@@ -0,0 +1,81 @@
1
+ /** how the model reads its history; every field is optional */
2
+ export type NavOptions = {
3
+ /** 1 predicts from the last route pattern; 2 uses the last two and backs off to 1 */
4
+ order?: 1 | 2;
5
+ /** observations until a count has lost half its weight; `Infinity` turns decay off */
6
+ halfLife?: number;
7
+ /** pseudo-observations that pull each row toward its prior */
8
+ alpha?: number;
9
+ /** the two-pattern row weighs n / (n + backoff) against the one-pattern row, n being its observations */
10
+ backoff?: number;
11
+ /** counts per one-pattern context, as a population or a public corpus would give them */
12
+ prior?: Record<string, Record<string, number>>;
13
+ /** contexts kept in each table */
14
+ maxContexts?: number;
15
+ /** next routes kept per context */
16
+ maxNext?: number;
17
+ };
18
+ /** a route with its probability and the effective observations behind its context */
19
+ export type NavPrediction = {
20
+ /** the predicted next route pattern */
21
+ route: string;
22
+ /** probability that this route comes next, from 0 to 1 */
23
+ p: number;
24
+ /** effective observations behind the context */
25
+ weight: number;
26
+ };
27
+ /** a row as JSON: its context, its last tick, then each next route with its count and tick */
28
+ export type RowEntry = [
29
+ ctx: string[],
30
+ t: number,
31
+ next: Array<[route: string, n: number, t: number]>
32
+ ];
33
+ /** the model as JSON; `one` holds one-pattern contexts, `two` two-pattern contexts */
34
+ export type NavSnapshot = {
35
+ /** format version; always 1 */
36
+ v: 1;
37
+ /** observations the model had seen when it was saved */
38
+ t: number;
39
+ /** rows for one-route contexts */
40
+ one: RowEntry[];
41
+ /** rows for two-route contexts */
42
+ two: RowEntry[];
43
+ };
44
+ /**
45
+ * Predicts the next route pattern from the ones before it. Counts decay by half every `halfLife`
46
+ * observations, and a route the model has never seen (in counts or prior) is never predicted.
47
+ */
48
+ export declare class NavModel {
49
+ #private;
50
+ constructor(options?: NavOptions);
51
+ /** records that `route` came after `context`, newest route last; an empty context is a no-op */
52
+ observe(context: readonly string[], route: string): void;
53
+ /** the likely next routes, most probable first; routes with no probability are left out */
54
+ predict(context: readonly string[]): NavPrediction[];
55
+ /** the model as a snapshot that fromJSON restores */
56
+ toJSON(): NavSnapshot;
57
+ /** restores a model from toJSON output; throws bad-nav on a malformed snapshot */
58
+ static fromJSON(snapshot: unknown, options?: NavOptions): NavModel;
59
+ }
60
+ /** a Wilson score lower bound for a proportion `p` over `weight` effective observations */
61
+ export declare function lowerBound(p: number, weight: number, z?: number): number;
62
+ /** joules: `avoided` is what a hit keeps off the wire, the rest is what it costs */
63
+ export type NetInput = {
64
+ /** probability the candidate is used, from 0 to 1 */
65
+ p: number;
66
+ /** effective observations behind p */
67
+ weight: number;
68
+ /** joules a hit keeps off the wire */
69
+ avoided: number;
70
+ /** joules to provision the candidate, paid whether or not it is used */
71
+ provision: number;
72
+ /** joules to render the candidate, paid whether or not it is used; default 0 */
73
+ render?: number;
74
+ /** joules to keep the candidate current, paid whether or not it is used; default 0 */
75
+ maintain?: number;
76
+ /** joules of model work the decision costs, paid whether or not it is used; default 0 */
77
+ model?: number;
78
+ };
79
+ /** expected joules of acting on a candidate, with its probability taken at the lower bound */
80
+ export declare function expectedNet(input: NetInput, z?: number): number;
81
+ export declare function shouldAct(input: NetInput, z?: number): boolean;
@@ -0,0 +1,249 @@
1
+ import { ProtocolError } from './errors.js';
2
+ const SNAPSHOT_KEYS = ['v', 't', 'one', 'two'];
3
+ const round3 = (x) => Math.round(x * 1000) / 1000;
4
+ const keyOf = (ctx) => JSON.stringify(ctx);
5
+ function range(ok, name) {
6
+ if (!ok)
7
+ throw new RangeError(`nav option ${name} is out of range`);
8
+ }
9
+ function refuse(what) {
10
+ throw new ProtocolError('bad-nav', `nav snapshot ${what}`);
11
+ }
12
+ function isRecord(v) {
13
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
14
+ }
15
+ function isRoute(v) {
16
+ return typeof v === 'string' && v.length > 0;
17
+ }
18
+ function isTick(v, max) {
19
+ return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 && v <= max;
20
+ }
21
+ function entryOf(row) {
22
+ const next = [...row.next].map(([route, c]) => [route, c.n, c.t]);
23
+ return [[...row.ctx], row.t, next];
24
+ }
25
+ function dropOldest(table) {
26
+ let oldest = '';
27
+ let oldestT = Infinity;
28
+ for (const [key, row] of table) {
29
+ if (row.t < oldestT) {
30
+ oldest = key;
31
+ oldestT = row.t;
32
+ }
33
+ }
34
+ table.delete(oldest);
35
+ }
36
+ function restore(table, entries, size, tick) {
37
+ for (const item of entries) {
38
+ if (!Array.isArray(item) || item.length !== 3)
39
+ refuse('has a malformed row');
40
+ const [ctx, t, next] = item;
41
+ if (!Array.isArray(ctx) || ctx.length !== size || !ctx.every(isRoute)) {
42
+ refuse('has a malformed context');
43
+ }
44
+ if (!isTick(t, tick) || t === 0)
45
+ refuse('has a row touched outside the model');
46
+ if (!Array.isArray(next))
47
+ refuse('has a malformed row');
48
+ const key = keyOf(ctx);
49
+ if (table.has(key))
50
+ refuse('repeats a context');
51
+ const row = { ctx, t, next: new Map() };
52
+ for (const pair of next) {
53
+ if (!Array.isArray(pair) || pair.length !== 3)
54
+ refuse('has a malformed route');
55
+ const [route, n, touch] = pair;
56
+ if (!isRoute(route) || row.next.has(route))
57
+ refuse('has a malformed route');
58
+ if (typeof n !== 'number')
59
+ refuse('has a count that is not a number');
60
+ if (n < 0)
61
+ refuse('has a negative count');
62
+ if (!isTick(touch, tick) || touch === 0)
63
+ refuse('has a route touched outside the model');
64
+ row.next.set(route, { n, t: touch });
65
+ }
66
+ table.set(key, row);
67
+ }
68
+ }
69
+ /**
70
+ * Predicts the next route pattern from the ones before it. Counts decay by half every `halfLife`
71
+ * observations, and a route the model has never seen (in counts or prior) is never predicted.
72
+ */
73
+ export class NavModel {
74
+ #order;
75
+ #halfLife;
76
+ #alpha;
77
+ #backoff;
78
+ #prior;
79
+ #maxContexts;
80
+ #maxNext;
81
+ #one = new Map();
82
+ #two = new Map();
83
+ #tick = 0;
84
+ constructor(options = {}) {
85
+ const order = options.order ?? 1;
86
+ const halfLife = options.halfLife ?? 200;
87
+ const alpha = options.alpha ?? 1;
88
+ const backoff = options.backoff ?? 5;
89
+ const prior = options.prior ?? {};
90
+ const maxContexts = options.maxContexts ?? 64;
91
+ const maxNext = options.maxNext ?? 16;
92
+ range(order === 1 || order === 2, 'order');
93
+ range(halfLife > 0, 'halfLife');
94
+ range(alpha >= 0 && Number.isFinite(alpha), 'alpha');
95
+ range(backoff >= 0 && Number.isFinite(backoff), 'backoff');
96
+ range(Number.isSafeInteger(maxContexts) && maxContexts >= 1, 'maxContexts');
97
+ range(Number.isSafeInteger(maxNext) && maxNext >= 1, 'maxNext');
98
+ for (const row of Object.values(prior)) {
99
+ for (const n of Object.values(row))
100
+ range(n >= 0 && Number.isFinite(n), 'prior');
101
+ }
102
+ this.#order = order;
103
+ this.#halfLife = halfLife;
104
+ this.#alpha = alpha;
105
+ this.#backoff = backoff;
106
+ this.#prior = prior;
107
+ this.#maxContexts = maxContexts;
108
+ this.#maxNext = maxNext;
109
+ }
110
+ /** records that `route` came after `context`, newest route last; an empty context is a no-op */
111
+ observe(context, route) {
112
+ if (context.length === 0)
113
+ return;
114
+ this.#tick += 1;
115
+ this.#touch(this.#one, context.slice(-1), route);
116
+ if (this.#order === 2 && context.length >= 2) {
117
+ this.#touch(this.#two, context.slice(-2), route);
118
+ }
119
+ }
120
+ /** the likely next routes, most probable first; routes with no probability are left out */
121
+ predict(context) {
122
+ if (context.length === 0)
123
+ return [];
124
+ const last = context[context.length - 1] ?? '';
125
+ const one = this.#one.get(keyOf(context.slice(-1)));
126
+ const two = this.#order === 2 && context.length >= 2
127
+ ? this.#two.get(keyOf(context.slice(-2)))
128
+ : undefined;
129
+ const prior = Object.hasOwn(this.#prior, last) ? this.#prior[last] : undefined;
130
+ const p1 = this.#distribution(one, prior);
131
+ // the prior's counts are evidence about the mean, so they count toward the weight
132
+ const priorMass = prior ? Object.values(prior).reduce((sum, n) => sum + n, 0) : 0;
133
+ const w1 = (one ? this.#rowWeight(one) : 0) + priorMass;
134
+ const p2 = this.#distribution(two);
135
+ const w2 = two ? this.#rowWeight(two) : 0;
136
+ const lambda = w2 === 0 ? 0 : w2 / (w2 + this.#backoff);
137
+ const weight = lambda * w2 + (1 - lambda) * w1;
138
+ const out = [];
139
+ for (const route of new Set([...p1.keys(), ...p2.keys()])) {
140
+ const p = lambda * (p2.get(route) ?? 0) + (1 - lambda) * (p1.get(route) ?? 0);
141
+ if (p > 0)
142
+ out.push({ route, p, weight });
143
+ }
144
+ return out.sort((a, b) => b.p - a.p || (a.route < b.route ? -1 : a.route > b.route ? 1 : 0));
145
+ }
146
+ /** the model as a snapshot that fromJSON restores */
147
+ toJSON() {
148
+ return {
149
+ v: 1,
150
+ t: this.#tick,
151
+ one: [...this.#one.values()].map(entryOf),
152
+ two: [...this.#two.values()].map(entryOf)
153
+ };
154
+ }
155
+ /** restores a model from toJSON output; throws bad-nav on a malformed snapshot */
156
+ static fromJSON(snapshot, options) {
157
+ if (!isRecord(snapshot))
158
+ refuse('is not an object');
159
+ if (snapshot.v !== 1)
160
+ refuse('has an unknown version');
161
+ if (Object.keys(snapshot).some((key) => !SNAPSHOT_KEYS.includes(key))) {
162
+ refuse('has an unknown field');
163
+ }
164
+ const { t, one, two } = snapshot;
165
+ if (!isTick(t, Number.MAX_SAFE_INTEGER))
166
+ refuse('has a bad tick');
167
+ if (!Array.isArray(one) || !Array.isArray(two))
168
+ refuse('has a table that is not a list');
169
+ const model = new NavModel(options);
170
+ if (model.#order === 1 && two.length > 0)
171
+ refuse('has two-pattern contexts for order 1');
172
+ model.#tick = t;
173
+ restore(model.#one, one, 1, t);
174
+ restore(model.#two, two, 2, t);
175
+ return model;
176
+ }
177
+ #touch(table, ctx, route) {
178
+ const key = keyOf(ctx);
179
+ let row = table.get(key);
180
+ if (!row) {
181
+ if (table.size >= this.#maxContexts)
182
+ dropOldest(table);
183
+ row = { ctx, t: this.#tick, next: new Map() };
184
+ table.set(key, row);
185
+ }
186
+ row.t = this.#tick;
187
+ const prev = row.next.get(route);
188
+ row.next.set(route, { n: round3((prev ? this.#weigh(prev) : 0) + 1), t: this.#tick });
189
+ if (row.next.size > this.#maxNext)
190
+ this.#dropWeakest(row.next);
191
+ }
192
+ #dropWeakest(next) {
193
+ let weakest = '';
194
+ let weakestW = Infinity;
195
+ for (const [route, count] of next) {
196
+ const w = this.#weigh(count);
197
+ if (w < weakestW || (w === weakestW && route < weakest)) {
198
+ weakest = route;
199
+ weakestW = w;
200
+ }
201
+ }
202
+ next.delete(weakest);
203
+ }
204
+ #weigh(count) {
205
+ return count.n * 0.5 ** ((this.#tick - count.t) / this.#halfLife);
206
+ }
207
+ #rowWeight(row) {
208
+ let total = 0;
209
+ for (const count of row.next.values())
210
+ total += this.#weigh(count);
211
+ return total;
212
+ }
213
+ #distribution(row, prior) {
214
+ const out = new Map();
215
+ const denom = (row ? this.#rowWeight(row) : 0) + this.#alpha;
216
+ if (denom <= 0)
217
+ return out;
218
+ const priorTotal = prior ? Object.values(prior).reduce((sum, n) => sum + n, 0) : 0;
219
+ const routes = new Set([...(row?.next.keys() ?? []), ...Object.keys(prior ?? {})]);
220
+ for (const route of routes) {
221
+ const count = row?.next.get(route);
222
+ const shared = prior && Object.hasOwn(prior, route) ? (prior[route] ?? 0) : 0;
223
+ const share = priorTotal > 0 ? shared / priorTotal : 0;
224
+ out.set(route, ((count ? this.#weigh(count) : 0) + this.#alpha * share) / denom);
225
+ }
226
+ return out;
227
+ }
228
+ }
229
+ /** a Wilson score lower bound for a proportion `p` over `weight` effective observations */
230
+ export function lowerBound(p, weight, z = 1.28) {
231
+ if (!(p >= 0 && p <= 1) || !(weight > 0) || !Number.isFinite(weight))
232
+ return 0;
233
+ const z2 = z * z;
234
+ const centre = p + z2 / (2 * weight);
235
+ const margin = z * Math.sqrt((p * (1 - p)) / weight + z2 / (4 * weight * weight));
236
+ const bound = (centre - margin) / (1 + z2 / weight);
237
+ return Math.min(p, Math.max(0, bound));
238
+ }
239
+ /** expected joules of acting on a candidate, with its probability taken at the lower bound */
240
+ export function expectedNet(input, z) {
241
+ return (lowerBound(input.p, input.weight, z) * input.avoided -
242
+ input.provision -
243
+ (input.render ?? 0) -
244
+ (input.maintain ?? 0) -
245
+ (input.model ?? 0));
246
+ }
247
+ export function shouldAct(input, z) {
248
+ return expectedNet(input, z) > 0;
249
+ }
@@ -3,9 +3,10 @@ export type NormaliseOptions = {
3
3
  ignore?: readonly RegExp[];
4
4
  };
5
5
  /**
6
- * Reduces markup to what two renders of the same page must share: comments removed, runs of
7
- * whitespace collapsed to one space, whitespace between tags dropped, and every `ignore` match
8
- * blanked (a per-render nonce, say). It does not reorder attributes or fix tag soup.
6
+ * Reduces markup to what two renders of the same page must share: comments and the inline
7
+ * artifact element removed, runs of whitespace collapsed to one space, whitespace between tags
8
+ * dropped, and every `ignore` match blanked (a per-render nonce, say). It does not reorder
9
+ * attributes or fix tag soup.
9
10
  */
10
11
  export declare function normalise(html: string, options?: NormaliseOptions): string;
11
12
  /** the verdict of {@link equivalent}; a mismatch names where the two first differ */
@@ -1,11 +1,13 @@
1
+ import { stripInline } from './inline.js';
1
2
  const IGNORED = '\u0000';
2
3
  /**
3
- * Reduces markup to what two renders of the same page must share: comments removed, runs of
4
- * whitespace collapsed to one space, whitespace between tags dropped, and every `ignore` match
5
- * blanked (a per-render nonce, say). It does not reorder attributes or fix tag soup.
4
+ * Reduces markup to what two renders of the same page must share: comments and the inline
5
+ * artifact element removed, runs of whitespace collapsed to one space, whitespace between tags
6
+ * dropped, and every `ignore` match blanked (a per-render nonce, say). It does not reorder
7
+ * attributes or fix tag soup.
6
8
  */
7
9
  export function normalise(html, options = {}) {
8
- let out = html.replace(/<!--[\s\S]*?-->/g, '');
10
+ let out = stripInline(html).replace(/<!--[\s\S]*?-->/g, '');
9
11
  for (const pattern of options.ignore ?? []) {
10
12
  const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
11
13
  out = out.replace(new RegExp(pattern.source, flags), IGNORED);
@@ -78,6 +78,8 @@ export type EntryCandidate = {
78
78
  path: string;
79
79
  /** the predicted share of devices that will open the page, 0 to 1 */
80
80
  p: number;
81
+ /** the observations behind `p`; with a `z` it lowers `p` to a confidence bound, so a share seen once does not count as one seen a thousand times */
82
+ weight?: number;
81
83
  /** compressed bytes of the entry */
82
84
  entryBytes: number;
83
85
  /** bytes of the document the entry replaces */
@@ -87,10 +89,13 @@ export type EntryCandidate = {
87
89
  * The candidates worth shipping: those whose `p` is at least their break-even, best expected net
88
90
  * first, kept while their entry bytes fit under `capBytes`. A candidate that does not fit is
89
91
  * skipped and a smaller one may still go. A path is chosen once. A candidate with a `p` outside 0
90
- * to 1 or a negative or non-finite size is never chosen.
92
+ * to 1 or a negative or non-finite size is never chosen. With `z` above 0, a candidate that has a
93
+ * `weight` is judged on the lower confidence bound of its `p` (the Wilson bound at `z`), and the
94
+ * order follows the net at that bound; one with no `weight` keeps its `p`.
91
95
  */
92
96
  export declare function chooseEntries(candidates: readonly EntryCandidate[], options: {
93
97
  capBytes: number;
98
+ z?: number;
94
99
  }): EntryCandidate[];
95
100
  /**
96
101
  * P_reuse from aggregate telemetry: the share of a route's views that found a stored copy, pulled