@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,197 @@
1
+ import { type Spread } from './derive.js';
2
+ import type { Row } from './measurement.js';
3
+ /** one lever of the ledger: the bytes it saves on each page of a corpus, in page order */
4
+ export type Lever = {
5
+ id: string;
6
+ /** where the lever stands: `default` is on once its parent option is set, `option` needs its own option, `max` is not built or needs a condition the corpus does not show */
7
+ status: 'default' | 'option' | 'max';
8
+ corpus: 'crawl' | 'trim';
9
+ /** the site of each page, in the same order as `bytes` */
10
+ sites: string[];
11
+ bytes: number[];
12
+ };
13
+ /** what a lever saves across a corpus, in bytes */
14
+ export type LeverStats = {
15
+ pages: number;
16
+ withSaving: number;
17
+ medianPage: number;
18
+ /** the median over the pages that save anything, or null when none do */
19
+ medianEligible: number | null;
20
+ /** the median over sites of each site's mean per page */
21
+ medianSite: number;
22
+ mean: number;
23
+ };
24
+ export type CrawlImageRow = {
25
+ kind: 'image';
26
+ site: string;
27
+ profile: string;
28
+ page: string;
29
+ bytes: number;
30
+ format: string;
31
+ arms: {
32
+ native?: {
33
+ bytes: number;
34
+ };
35
+ ceiling?: {
36
+ bytes: number;
37
+ } | null;
38
+ resized?: {
39
+ bytes: number;
40
+ } | null;
41
+ lossless?: {
42
+ bytes: number;
43
+ } | null;
44
+ } | null;
45
+ };
46
+ export type CrawlPageRow = {
47
+ kind: 'page';
48
+ site: string;
49
+ profile: string;
50
+ variant: 'original' | 'lazy';
51
+ page: string;
52
+ ok: true | string;
53
+ imageBytesLoad: number;
54
+ imageBytesScroll: number;
55
+ videoBytes: number;
56
+ videoTags: Array<{
57
+ autoplay: boolean;
58
+ }>;
59
+ iframes: Array<{
60
+ host: string;
61
+ bytes: number;
62
+ }>;
63
+ lcp: {
64
+ tag: string | null;
65
+ loading: string | null;
66
+ } | null;
67
+ };
68
+ export type CrawlEmbedRow = {
69
+ kind: 'embed';
70
+ provider: 'youtube' | 'vimeo';
71
+ arm: 'iframe' | 'facade';
72
+ bytes: number;
73
+ docBytes: number;
74
+ };
75
+ /** the bytes a WebP of each image saves: `native` is the file at its own size, `ceiling` the width ceiling, `resized` the rendered width */
76
+ export declare function imageSavings(rows: readonly CrawlImageRow[]): {
77
+ format: number;
78
+ resize: number;
79
+ lossless: number;
80
+ };
81
+ /** the levers of the image-crawl corpus: the first views of the desktop profile, one entry per page */
82
+ export declare function crawlLevers(rows: readonly Row[]): Lever[];
83
+ /** bytes of image data a visit that never scrolls does not load when `loading="lazy"` is on, by page */
84
+ export declare function lazyUnscrolled(rows: readonly Row[], profile?: string): {
85
+ pairs: number;
86
+ sites: string[];
87
+ bytes: number[];
88
+ baseLoad: number[];
89
+ lazyLoad: number[];
90
+ lcpImagePages: number;
91
+ lcpLazyPages: number;
92
+ };
93
+ /** the levers of the trim corpus: the first views of internal pages of the Drupal sites */
94
+ export declare function trimLevers(trimmed: readonly Row[], crawl: readonly Row[]): Lever[];
95
+ /** {@link LeverStats} of a lever's per-page bytes, or null for an empty corpus */
96
+ export declare function leverStats(sites: readonly string[], bytes: readonly number[]): LeverStats | null;
97
+ /** the bytes of several levers added page by page; the levers must come from one corpus and one page order */
98
+ export declare function addLevers(levers: readonly Lever[]): {
99
+ sites: string[];
100
+ bytes: number[];
101
+ } | null;
102
+ /** the dictionary choices the `dictionary-size` rig measures; see that rig for what each one is */
103
+ export declare const DICTIONARY_ARMS: readonly ["oracle", "browser", "serverVisit", "serverHeld", "serverOut"];
104
+ /** one of {@link DICTIONARY_ARMS} */
105
+ export type DictionaryArm = (typeof DICTIONARY_ARMS)[number];
106
+ /** what one dictionary choice saves against brotli 11 alone, with a file that gains nothing served plain */
107
+ export type DictionaryStat = {
108
+ /** the median over sites of the share of that site's brotli 11 bytes saved */
109
+ medianSite: number;
110
+ /** the same share over every file of every site */
111
+ pooled: number;
112
+ /** internal pages */
113
+ pages: number;
114
+ /** the median bytes saved on an internal page's first view */
115
+ medianPageBytes: number;
116
+ /** internal pages whose new files save more than 5% of their brotli 11 bytes */
117
+ pagesOver5: number;
118
+ };
119
+ /**
120
+ * The savings of each dictionary choice in a `dictionary-size` reading, for `dcz` (zstd) and `dcb`
121
+ * (brotli). A file the choice gives no dictionary, or whose delta is not smaller than brotli 11,
122
+ * saves nothing.
123
+ */
124
+ export declare function dictionaryArms(rows: readonly Record<string, unknown>[]): {
125
+ sites: number;
126
+ files: number;
127
+ br11Bytes: number;
128
+ arms: Record<"oracle" | "browser" | "serverVisit" | "serverHeld" | "serverOut", {
129
+ zstd: DictionaryStat;
130
+ br: DictionaryStat;
131
+ }>;
132
+ };
133
+ /** the windows of one arm that a derivation keeps and drops, and why */
134
+ export type WindowCount = {
135
+ kept: number;
136
+ /** other containers used more than the limit of CPU per second */
137
+ dropped: number;
138
+ /** the window belongs to a round whose idle windows disagree (idle-activity only) */
139
+ idleControl: number;
140
+ };
141
+ /** kept and dropped windows per arm under the contamination limit; a row with no length (a probe) is not a window */
142
+ export declare function windowCounts(rows: readonly Row[], limit?: number): Record<string, WindowCount>;
143
+ /** the idle windows of a round may differ by this factor, largest over smallest, before the round is dropped */
144
+ export declare const IDLE_AGREEMENT = 1.25;
145
+ /** one arm of an idle-activity reading, after the drops */
146
+ export type ActivityArm = {
147
+ windows: number;
148
+ /** package watts over the kept windows */
149
+ watts: Spread;
150
+ /** watts above the idle windows of the same round */
151
+ extraWatts: Spread;
152
+ };
153
+ /**
154
+ * Package watts per arm of an idle-activity reading. A window is dropped when other containers used
155
+ * more than `limit` ms of CPU per second. The rig cannot see a host process or a container that
156
+ * stopped inside a window, so the three idle windows of each round also act as a control: when the
157
+ * largest of them is over {@link IDLE_AGREEMENT} times the smallest, the whole round is dropped. An
158
+ * arm with no kept window is null.
159
+ */
160
+ export declare function activityFigures(rows: readonly Row[], limit?: number): {
161
+ idleWatts: Spread | null;
162
+ noisyRounds: number[];
163
+ counts: Record<string, WindowCount>;
164
+ arms: Record<string, ActivityArm | null>;
165
+ };
166
+ /** a page with a pause hook, the same page without it, and the quiet page of the same setup */
167
+ export type ActivityPair = {
168
+ plain: string;
169
+ hook: string;
170
+ quiet: string;
171
+ };
172
+ /** the two pairs the rig measures: a loop off screen in a visible page, and a poll in a hidden tab */
173
+ export declare const ACTIVITY_PAIRS: readonly ActivityPair[];
174
+ /** what a pause hook did for one pair, in watts */
175
+ export type ActivityGain = {
176
+ pair: ActivityPair;
177
+ /** the same page without the hook less with it, over the arm medians; the range sets each page's extreme against the other's opposite */
178
+ saved: {
179
+ median: number;
180
+ min: number;
181
+ max: number;
182
+ };
183
+ /** what the page with the hook still draws above the quiet page */
184
+ residual: number;
185
+ };
186
+ /**
187
+ * Per pair, the watts a hook removes from the page it is on (the gain), and the watts that page
188
+ * still draws above a quiet one (the residual). A pair with an arm that has no kept window is left
189
+ * out. The quiet arm is not the baseline of the gain: a quiet page is where a perfect hook would end.
190
+ */
191
+ export declare function activityGains(arms: Readonly<Record<string, {
192
+ extraWatts: Spread;
193
+ } | null | undefined>>, pairs?: readonly ActivityPair[]): ActivityGain[];
194
+ /** attributional joules for `bytes` (the same SWD v4 rate as the headline, no origin term: these are the same requests with fewer bytes) */
195
+ export declare const ledgerJoules: (bytes: number) => number;
196
+ /** megawatt-hours a year when `perView` joules are saved on a share of `views` views */
197
+ export declare const ledgerMWh: (perView: number, views: number, share: number) => number;
@@ -0,0 +1,308 @@
1
+ import { CONTAMINATION_MS_PER_S, isContaminated, median, quantile, spread } from './derive.js';
2
+ import { attributionalJoules } from './model.js';
3
+ const EMBED_HOSTS = {
4
+ 'www.youtube.com': 'youtube',
5
+ 'youtube.com': 'youtube',
6
+ 'www.youtube-nocookie.com': 'youtube',
7
+ 'youtube-nocookie.com': 'youtube',
8
+ 'player.vimeo.com': 'vimeo'
9
+ };
10
+ /** the bytes a WebP of each image saves: `native` is the file at its own size, `ceiling` the width ceiling, `resized` the rendered width */
11
+ export function imageSavings(rows) {
12
+ let format = 0;
13
+ let resize = 0;
14
+ let lossless = 0;
15
+ for (const row of rows) {
16
+ const arms = row.arms;
17
+ if (!arms?.native)
18
+ continue;
19
+ const ceiling = arms.ceiling?.bytes ?? arms.native.bytes;
20
+ const base = Math.min(row.bytes, ceiling);
21
+ format += row.bytes - base;
22
+ resize += base - Math.min(base, arms.resized?.bytes ?? base);
23
+ if (arms.lossless)
24
+ lossless += Math.max(0, base - arms.lossless.bytes);
25
+ }
26
+ return { format, resize, lossless };
27
+ }
28
+ /** the levers of the image-crawl corpus: the first views of the desktop profile, one entry per page */
29
+ export function crawlLevers(rows) {
30
+ const all = rows;
31
+ const pages = all.filter((r) => r.kind === 'page' &&
32
+ r.profile === 'desktop' &&
33
+ r.variant === 'original' &&
34
+ r.ok === true);
35
+ const images = all.filter((r) => r.kind === 'image' && r.profile === 'desktop');
36
+ const embeds = all.filter((r) => r.kind === 'embed');
37
+ const facade = (provider) => {
38
+ const row = embeds.find((e) => e.provider === provider && e.arm === 'facade');
39
+ return row ? row.bytes + row.docBytes : 0;
40
+ };
41
+ const key = (r) => `${r.site}|${r.page}`;
42
+ const byPage = new Map();
43
+ for (const image of images)
44
+ byPage.set(key(image), [...(byPage.get(key(image)) ?? []), image]);
45
+ const sites = pages.map((p) => p.site);
46
+ const per = (f) => pages.map(f);
47
+ const embedSaved = (page) => page.iframes.reduce((sum, frame) => {
48
+ const provider = EMBED_HOSTS[frame.host];
49
+ return provider ? sum + Math.max(0, frame.bytes - facade(provider)) : sum;
50
+ }, 0);
51
+ const idle = (page) => page.videoTags.length > 0 && page.videoTags.every((t) => !t.autoplay);
52
+ return [
53
+ {
54
+ id: 'images-format',
55
+ status: 'default',
56
+ corpus: 'crawl',
57
+ sites,
58
+ bytes: per((p) => imageSavings(byPage.get(key(p)) ?? []).format)
59
+ },
60
+ {
61
+ id: 'images-resize',
62
+ status: 'default',
63
+ corpus: 'crawl',
64
+ sites,
65
+ bytes: per((p) => imageSavings(byPage.get(key(p)) ?? []).resize)
66
+ },
67
+ {
68
+ id: 'video-preload',
69
+ status: 'default',
70
+ corpus: 'crawl',
71
+ sites,
72
+ bytes: per((p) => (idle(p) ? p.videoBytes : 0))
73
+ },
74
+ {
75
+ id: 'video-defer',
76
+ status: 'option',
77
+ corpus: 'crawl',
78
+ sites,
79
+ bytes: per((p) => (idle(p) ? 0 : p.videoBytes))
80
+ },
81
+ { id: 'embeds', status: 'option', corpus: 'crawl', sites, bytes: per(embedSaved) }
82
+ ];
83
+ }
84
+ /** bytes of image data a visit that never scrolls does not load when `loading="lazy"` is on, by page */
85
+ export function lazyUnscrolled(rows, profile = 'desktop') {
86
+ const pages = rows.filter((r) => r.kind === 'page' && r.profile === profile && r.ok === true);
87
+ const original = new Map(pages.filter((p) => p.variant === 'original').map((p) => [`${p.site}|${p.page}`, p]));
88
+ const pairs = pages
89
+ .filter((p) => p.variant === 'lazy')
90
+ .flatMap((lazy) => {
91
+ const base = original.get(`${lazy.site}|${lazy.page}`);
92
+ return base ? [{ base, lazy }] : [];
93
+ });
94
+ const lcpImages = pairs.filter((p) => p.lazy.lcp?.tag === 'IMG');
95
+ return {
96
+ pairs: pairs.length,
97
+ sites: pairs.map((p) => p.base.site),
98
+ bytes: pairs.map((p) => Math.max(0, p.base.imageBytesLoad - p.lazy.imageBytesLoad)),
99
+ baseLoad: pairs.map((p) => p.base.imageBytesLoad),
100
+ lazyLoad: pairs.map((p) => p.lazy.imageBytesLoad),
101
+ lcpImagePages: lcpImages.length,
102
+ lcpLazyPages: lcpImages.filter((p) => p.lazy.lcp?.loading === 'lazy' && p.base.lcp?.loading !== 'lazy').length
103
+ };
104
+ }
105
+ /** the levers of the trim corpus: the first views of internal pages of the Drupal sites */
106
+ export function trimLevers(trimmed, crawl) {
107
+ const trimSites = trimmed;
108
+ const aggSites = crawl;
109
+ const internal = (sites) => sites.flatMap((s) => s.pages.filter((p) => p.kind === 'internal').map((p) => ({ site: s.site, page: p })));
110
+ const css = internal(trimSites);
111
+ const agg = internal(aggSites).filter((x) => x.page.ok === true && x.page.newAgg);
112
+ return [
113
+ {
114
+ id: 'css-trim',
115
+ status: 'option',
116
+ corpus: 'trim',
117
+ sites: css.map((x) => x.site),
118
+ bytes: css.map((x) => x.page.saved.br5Saved)
119
+ },
120
+ {
121
+ id: 'aggregate-dictionary',
122
+ status: 'max',
123
+ corpus: 'trim',
124
+ sites: agg.map((x) => x.site),
125
+ bytes: agg.map((x) => {
126
+ const a = x.page.newAgg;
127
+ return a.zstdAlone > 0 ? a.transfer * Math.max(0, 1 - a.zstdDict / a.zstdAlone) : 0;
128
+ })
129
+ }
130
+ ];
131
+ }
132
+ /** {@link LeverStats} of a lever's per-page bytes, or null for an empty corpus */
133
+ export function leverStats(sites, bytes) {
134
+ if (bytes.length === 0)
135
+ return null;
136
+ const saving = bytes.filter((b) => b > 0);
137
+ const perSite = new Map();
138
+ bytes.forEach((b, i) => perSite.set(sites[i], [...(perSite.get(sites[i]) ?? []), b]));
139
+ const mean = (xs) => xs.reduce((s, x) => s + x, 0) / xs.length;
140
+ return {
141
+ pages: bytes.length,
142
+ withSaving: saving.length,
143
+ medianPage: quantile(bytes, 0.5),
144
+ medianEligible: saving.length > 0 ? quantile(saving, 0.5) : null,
145
+ medianSite: median([...perSite.values()].map(mean)),
146
+ mean: mean(bytes)
147
+ };
148
+ }
149
+ /** the bytes of several levers added page by page; the levers must come from one corpus and one page order */
150
+ export function addLevers(levers) {
151
+ const first = levers[0];
152
+ if (!first)
153
+ return null;
154
+ return {
155
+ sites: first.sites,
156
+ bytes: first.bytes.map((_, i) => levers.reduce((sum, l) => sum + (l.bytes[i] ?? 0), 0))
157
+ };
158
+ }
159
+ /** the dictionary choices the `dictionary-size` rig measures; see that rig for what each one is */
160
+ export const DICTIONARY_ARMS = [
161
+ 'oracle',
162
+ 'browser',
163
+ 'serverVisit',
164
+ 'serverHeld',
165
+ 'serverOut'
166
+ ];
167
+ /**
168
+ * The savings of each dictionary choice in a `dictionary-size` reading, for `dcz` (zstd) and `dcb`
169
+ * (brotli). A file the choice gives no dictionary, or whose delta is not smaller than brotli 11,
170
+ * saves nothing.
171
+ */
172
+ export function dictionaryArms(rows) {
173
+ const files = rows.filter((r) => r.kind === 'file');
174
+ const stat = (arm, codec) => {
175
+ const saved = (f) => {
176
+ const size = f[arm]?.[codec];
177
+ return size == null ? 0 : Math.max(0, f.br11 - size);
178
+ };
179
+ const share = (group) => {
180
+ const plain = group.reduce((s, f) => s + f.br11, 0);
181
+ return plain > 0 ? group.reduce((s, f) => s + saved(f), 0) / plain : 0;
182
+ };
183
+ const bySite = new Map();
184
+ const byPage = new Map();
185
+ for (const f of files) {
186
+ bySite.set(f.site, [...(bySite.get(f.site) ?? []), f]);
187
+ if (f.pageKind === 'internal') {
188
+ const key = `${f.site}|${f.page}`;
189
+ byPage.set(key, [...(byPage.get(key) ?? []), f]);
190
+ }
191
+ }
192
+ const pages = [...byPage.values()];
193
+ return {
194
+ medianSite: median([...bySite.values()].map(share)),
195
+ pooled: share(files),
196
+ pages: pages.length,
197
+ medianPageBytes: median(pages.map((p) => p.reduce((s, f) => s + saved(f), 0))),
198
+ pagesOver5: pages.filter((p) => share(p) > 0.05).length
199
+ };
200
+ };
201
+ const arms = {};
202
+ for (const arm of DICTIONARY_ARMS)
203
+ arms[arm] = { zstd: stat(arm, 'zstd'), br: stat(arm, 'br') };
204
+ return {
205
+ sites: new Set(files.map((f) => f.site)).size,
206
+ files: files.length,
207
+ br11Bytes: files.reduce((s, f) => s + f.br11, 0),
208
+ arms
209
+ };
210
+ }
211
+ const windowSeconds = (row) => row.elapsedMs / 1000;
212
+ const timed = (rows) => rows.filter((r) => typeof r.elapsedMs === 'number' && r.elapsedMs > 0);
213
+ const tally = (counts, arm) => (counts[String(arm)] ??= { kept: 0, dropped: 0, idleControl: 0 });
214
+ /** kept and dropped windows per arm under the contamination limit; a row with no length (a probe) is not a window */
215
+ export function windowCounts(rows, limit = CONTAMINATION_MS_PER_S) {
216
+ const counts = {};
217
+ for (const row of timed(rows)) {
218
+ tally(counts, row.arm)[isContaminated(row, limit) ? 'dropped' : 'kept']++;
219
+ }
220
+ return counts;
221
+ }
222
+ /** the idle windows of a round may differ by this factor, largest over smallest, before the round is dropped */
223
+ export const IDLE_AGREEMENT = 1.25;
224
+ /**
225
+ * Package watts per arm of an idle-activity reading. A window is dropped when other containers used
226
+ * more than `limit` ms of CPU per second. The rig cannot see a host process or a container that
227
+ * stopped inside a window, so the three idle windows of each round also act as a control: when the
228
+ * largest of them is over {@link IDLE_AGREEMENT} times the smallest, the whole round is dropped. An
229
+ * arm with no kept window is null.
230
+ */
231
+ export function activityFigures(rows, limit = CONTAMINATION_MS_PER_S) {
232
+ const counts = {};
233
+ const watts = (row) => row.pkgJ / windowSeconds(row);
234
+ const calm = timed(rows).filter((row) => {
235
+ const contaminated = isContaminated(row, limit);
236
+ if (contaminated)
237
+ tally(counts, row.arm).dropped++;
238
+ return !contaminated;
239
+ });
240
+ const idleByRound = new Map();
241
+ for (const row of calm) {
242
+ if (row.arm === 'idle') {
243
+ idleByRound.set(row.round, [
244
+ ...(idleByRound.get(row.round) ?? []),
245
+ watts(row)
246
+ ]);
247
+ }
248
+ }
249
+ const noisy = [...idleByRound]
250
+ .filter(([, w]) => w.length > 1 && Math.max(...w) > IDLE_AGREEMENT * Math.min(...w))
251
+ .map(([round]) => round);
252
+ const kept = calm.filter((row) => {
253
+ const drop = noisy.includes(row.round);
254
+ tally(counts, row.arm)[drop ? 'idleControl' : 'kept']++;
255
+ return !drop;
256
+ });
257
+ const idleRound = new Map([...idleByRound].filter(([round]) => !noisy.includes(round)).map(([r, w]) => [r, median(w)]));
258
+ const idleWatts = idleRound.size > 0 ? spread([...idleRound.values()]) : null;
259
+ const arms = {};
260
+ for (const name of new Set(timed(rows).map((row) => String(row.arm)))) {
261
+ if (name === 'idle')
262
+ continue;
263
+ const mine = kept.filter((row) => row.arm === name && idleRound.has(row.round));
264
+ arms[name] =
265
+ mine.length === 0
266
+ ? null
267
+ : {
268
+ windows: mine.length,
269
+ watts: spread(mine.map(watts)),
270
+ extraWatts: spread(mine.map((row) => watts(row) - idleRound.get(row.round)))
271
+ };
272
+ }
273
+ return { idleWatts, noisyRounds: noisy.sort((a, b) => a - b), counts, arms };
274
+ }
275
+ /** the two pairs the rig measures: a loop off screen in a visible page, and a poll in a hidden tab */
276
+ export const ACTIVITY_PAIRS = [
277
+ { plain: 'raf-off-plain', hook: 'raf-off-hook', quiet: 'quiet' },
278
+ { plain: 'poll-hidden-plain', hook: 'poll-hidden-hook', quiet: 'quiet-hidden' }
279
+ ];
280
+ /**
281
+ * Per pair, the watts a hook removes from the page it is on (the gain), and the watts that page
282
+ * still draws above a quiet one (the residual). A pair with an arm that has no kept window is left
283
+ * out. The quiet arm is not the baseline of the gain: a quiet page is where a perfect hook would end.
284
+ */
285
+ export function activityGains(arms, pairs = ACTIVITY_PAIRS) {
286
+ return pairs.flatMap((pair) => {
287
+ const plain = arms[pair.plain]?.extraWatts;
288
+ const hook = arms[pair.hook]?.extraWatts;
289
+ const quiet = arms[pair.quiet]?.extraWatts;
290
+ if (!plain || !hook || !quiet)
291
+ return [];
292
+ return [
293
+ {
294
+ pair,
295
+ saved: {
296
+ median: plain.median - hook.median,
297
+ min: plain.min - hook.max,
298
+ max: plain.max - hook.min
299
+ },
300
+ residual: hook.median - quiet.median
301
+ }
302
+ ];
303
+ });
304
+ }
305
+ /** attributional joules for `bytes` (the same SWD v4 rate as the headline, no origin term: these are the same requests with fewer bytes) */
306
+ export const ledgerJoules = (bytes) => attributionalJoules(bytes);
307
+ /** megawatt-hours a year when `perView` joules are saved on a share of `views` views */
308
+ export const ledgerMWh = (perView, views, share) => (perView * views * share) / 3.6e9;
@@ -1,6 +1,6 @@
1
1
  import type { Layer } from './inputs.js';
2
2
  /** the rigs that write to `measurements/<rig>/`, one folder each */
3
- export declare const RIGS: readonly ["repeat-nav", "on-wire", "zero-network", "device-cpu", "rapl", "iphone", "payload", "trim"];
3
+ export declare const RIGS: readonly ["repeat-nav", "on-wire", "zero-network", "device-cpu", "rapl", "iphone", "payload", "trim", "link-assets", "image-crawl", "dictionary-size", "nav-replay", "first-payload", "embed-markup"];
4
4
  /** one of {@link RIGS} */
5
5
  export type Rig = (typeof RIGS)[number];
6
6
  /** the format version {@link parseMeasurement} reads */
@@ -7,7 +7,13 @@ export const RIGS = [
7
7
  'rapl',
8
8
  'iphone',
9
9
  'payload',
10
- 'trim'
10
+ 'trim',
11
+ 'link-assets',
12
+ 'image-crawl',
13
+ 'dictionary-size',
14
+ 'nav-replay',
15
+ 'first-payload',
16
+ 'embed-markup'
11
17
  ];
12
18
  /** the format version {@link parseMeasurement} reads */
13
19
  export const MEASUREMENT_SCHEMA = 1;
@@ -136,5 +136,14 @@ export type Transitions = {
136
136
  };
137
137
  /** counts per `(from, route)` pair and per `from`; a view with no `from` counts in neither */
138
138
  export declare function transitions(views: readonly TimedView[]): Transitions;
139
- /** the share of views from `from` that went to each route, in route order; empty when none came from it */
140
- export declare function nextShare(views: readonly TimedView[], from: string): Record<string, number>;
139
+ /**
140
+ * The share of views from `from` that went to each route, in route order; empty when none came from
141
+ * it. With `first`, only a first view of the route counts toward its share, over every view from
142
+ * `from`. A catalogue entry saves only a first view, so that share is the one to rank entries by:
143
+ * the share over all views counts returning visits and, in a replay of 989,818 public visitors,
144
+ * ran 1.5 to 7 times the observed chance of a first view in the bins that decide an entry
145
+ * (`measurements/nav-replay`).
146
+ */
147
+ export declare function nextShare(views: readonly TimedView[], from: string, options?: {
148
+ first?: boolean;
149
+ }): Record<string, number>;
@@ -214,9 +214,19 @@ export function transitions(views) {
214
214
  const sorted = [...pairs.values()].sort((a, b) => a.from === b.from ? (a.route < b.route ? -1 : 1) : a.from < b.from ? -1 : 1);
215
215
  return { pairs: sorted, byFrom };
216
216
  }
217
- /** the share of views from `from` that went to each route, in route order; empty when none came from it */
218
- export function nextShare(views, from) {
219
- const { pairs, byFrom } = transitions(views);
217
+ /** a view of a page the device did not hold: a network view of a cold route, or a catalogue entry's first open */
218
+ const isFirstView = (view) => view.reason === 'cold' || view.reason === 'catalogue';
219
+ /**
220
+ * The share of views from `from` that went to each route, in route order; empty when none came from
221
+ * it. With `first`, only a first view of the route counts toward its share, over every view from
222
+ * `from`. A catalogue entry saves only a first view, so that share is the one to rank entries by:
223
+ * the share over all views counts returning visits and, in a replay of 989,818 public visitors,
224
+ * ran 1.5 to 7 times the observed chance of a first view in the bins that decide an entry
225
+ * (`measurements/nav-replay`).
226
+ */
227
+ export function nextShare(views, from, options = {}) {
228
+ const { byFrom } = transitions(views);
229
+ const { pairs } = options.first ? transitions(views.filter(isFirstView)) : transitions(views);
220
230
  const total = byFrom[from];
221
231
  const out = {};
222
232
  if (!total)