@speedkit/cli 4.47.0 → 4.49.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 (39) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +103 -1
  3. package/dist/commands/onboarding.d.ts +2 -0
  4. package/dist/commands/onboarding.js +1 -0
  5. package/dist/commands/revalidate/jobs.d.ts +16 -0
  6. package/dist/commands/revalidate/jobs.js +80 -0
  7. package/dist/commands/revalidate/start.d.ts +15 -0
  8. package/dist/commands/revalidate/start.js +25 -0
  9. package/dist/commands/revalidate/unblock.d.ts +12 -0
  10. package/dist/commands/revalidate/unblock.js +13 -0
  11. package/dist/commands/revalidate/wait.d.ts +12 -0
  12. package/dist/commands/revalidate/wait.js +13 -0
  13. package/dist/services/browser-fetch/device-emulation.d.ts +16 -3
  14. package/dist/services/browser-fetch/device-emulation.js +32 -17
  15. package/dist/services/browser-fetch/spec/device-emulation.spec.js +20 -0
  16. package/dist/services/onboarding/browser/emulate-device.d.ts +13 -0
  17. package/dist/services/onboarding/browser/emulate-device.js +50 -0
  18. package/dist/services/onboarding/browser/launch-browser.js +7 -2
  19. package/dist/services/onboarding/onboarding-model.d.ts +27 -6
  20. package/dist/services/onboarding/onboarding-model.js +88 -15
  21. package/dist/services/onboarding/onboarding-service-build-context.d.ts +7 -0
  22. package/dist/services/onboarding/onboarding-service-build-context.js +12 -0
  23. package/dist/services/onboarding/onboarding-service-factory.d.ts +7 -0
  24. package/dist/services/onboarding/onboarding-service-factory.js +34 -1
  25. package/dist/services/onboarding/spec/onboarding-model.spec.js +93 -2
  26. package/dist/services/onboarding/spec/onboarding-service-build-context.spec.js +16 -1
  27. package/dist/services/revalidate/index.d.ts +1 -0
  28. package/dist/services/revalidate/index.js +1 -0
  29. package/dist/services/revalidate/revalidate-factory.d.ts +1 -1
  30. package/dist/services/revalidate/revalidate-jobs-build-context.d.ts +56 -0
  31. package/dist/services/revalidate/revalidate-jobs-build-context.js +69 -0
  32. package/dist/services/revalidate/revalidate-model.d.ts +30 -0
  33. package/dist/services/revalidate/revalidate-model.js +22 -0
  34. package/dist/services/revalidate/revalidate-service.d.ts +29 -1
  35. package/dist/services/revalidate/revalidate-service.js +89 -1
  36. package/dist/services/revalidate/spec/revalidate-jobs.spec.d.ts +1 -0
  37. package/dist/services/revalidate/spec/revalidate-jobs.spec.js +130 -0
  38. package/oclif.manifest.json +187 -1
  39. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,26 @@
1
+ # [4.49.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.48.0...v4.49.0) (2026-10-26)
2
+
3
+
4
+ ### Features
5
+
6
+ * **onboarding:** emulate a whole device with --device mobile|tablet|desktop ([7f978e7](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/7f978e7aaf356952825c185e3e13f29f74dba26f))
7
+ * **onboarding:** implement mobileMode ([64aed4f](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/64aed4fc6059db54c084fb1e8459038bf574acc6))
8
+ * **onboarding:** take the --device presets from Speed Kit RUM ([aad8b6d](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/aad8b6d890d31622417710b500ead09e83f719d3))
9
+
10
+ # [4.48.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.47.0...v4.48.0) (2026-10-19)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * **revalidate:** advise the content comparison, and name each job's reason ([c9849bd](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c9849bdc5d99abd4f2d27e8fbfe0e82d22509e26))
16
+
17
+
18
+ ### Features
19
+
20
+ * **revalidate:** list, inspect and resume revalidation jobs ([a11638a](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/a11638a8c3d48d6c137f4b2d7d3f913a47fe64da))
21
+ * **revalidate:** start only the deployment jobs that block the HTML ([c066946](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c0669461837f5a4686f03705507557f1dfc41bb2))
22
+ * **revalidate:** wait until the jobs end ([8762abb](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/8762abb2ad7815a7a6821618e972d70bdfc9154d))
23
+
1
24
  # [4.47.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.46.0...v4.47.0) (2026-10-16)
2
25
 
3
26
 
package/README.md CHANGED
@@ -95,6 +95,10 @@ By either...
95
95
  * [`sk query parameter CUSTOMERPATH`](#sk-query-parameter-customerpath)
96
96
  * [`sk query prewarm CUSTOMERPATH`](#sk-query-prewarm-customerpath)
97
97
  * [`sk revalidate APP`](#sk-revalidate-app)
98
+ * [`sk revalidate jobs APP [REVID]`](#sk-revalidate-jobs-app-revid)
99
+ * [`sk revalidate start APP REVID`](#sk-revalidate-start-app-revid)
100
+ * [`sk revalidate unblock APP`](#sk-revalidate-unblock-app)
101
+ * [`sk revalidate wait APP`](#sk-revalidate-wait-app)
98
102
  * [`sk wpt-launcher URLS TESTID`](#sk-wpt-launcher-urls-testid)
99
103
 
100
104
  ## `sk auto-prewarm CUSTOMERPATH`
@@ -780,7 +784,8 @@ Start a local dev environment for building and testing the Speed Kit configurati
780
784
  ```
781
785
  USAGE
782
786
  $ sk onboarding [CUSTOMERPATH] [-c <value>] [-t] [-d <value>] [-p] [--debugPort <value>] [-v] [-s]
783
- [--headless] [--app <value> [--inject [<installationId>] | --browse]] [--browserFetch]
787
+ [--headless] [-m | --device mobile|tablet|desktop] [--app <value> [--inject [<installationId>] | --browse]]
788
+ [--browserFetch]
784
789
 
785
790
  ARGUMENTS
786
791
  [CUSTOMERPATH] The customer config path (optional with --browse and --inject)
@@ -788,6 +793,7 @@ ARGUMENTS
788
793
  FLAGS
789
794
  -c, --configName=<value> [default: production] The costumer config name
790
795
  -d, --domain=<value> Startup domain (optional)
796
+ -m, --mobile Same as --device mobile
791
797
  -p, --debuggingPort Enable remote debugging port (disables speculation rules/prerendering)
792
798
  -s, --ignoreContentSecurityPolicy Removes header/meta "content-security-policy" for origin-responses
793
799
  -t, --useTestConfig Override app with configured testApp
@@ -802,6 +808,9 @@ FLAGS
802
808
  otherwise detected and rerouted on its own.
803
809
  --debugPort=<value> [default: 9222] Chrome remote debugging port (only used with -p/--headless). Use
804
810
  distinct ports to run multiple onboarding processes at once.
811
+ --device=<option> Emulate a device in every page and Service Worker: user agent, client hints,
812
+ viewport, pointer and touch. Without it, Chrome runs as it launches.
813
+ <options: mobile|tablet|desktop>
805
814
  --headless Run Chrome in headless mode (for CI environments). Implicitly enables remote
806
815
  debugging port.
807
816
  --inject=[<installationId>] Inject a deployed Speed Kit installation into the site, for a customer that has not
@@ -821,6 +830,8 @@ EXAMPLES
821
830
 
822
831
  $ sk onboarding customers/decathlon.de --browse -p
823
832
 
833
+ $ sk onboarding customers/decathlon.de -p --device tablet
834
+
824
835
  $ sk onboarding customers/decathlon.de --inject
825
836
 
826
837
  $ sk onboarding customers/decathlon.de --inject <installationId>
@@ -1084,6 +1095,97 @@ EXAMPLES
1084
1095
  $ sk revalidate example-shop --prefix https://www.example.com/en/ --dryRun
1085
1096
  ```
1086
1097
 
1098
+ ## `sk revalidate jobs APP [REVID]`
1099
+
1100
+ List the revalidation jobs of an app that have not ended, or show one in full. In a terminal, it asks which job to show or to start.
1101
+
1102
+ ```
1103
+ USAGE
1104
+ $ sk revalidate jobs APP [REVID] [--state CREATED|SCHEDULED|DEFERRED|RUNNING|FINISHED|ERROR|CANCELLED...]
1105
+
1106
+ ARGUMENTS
1107
+ APP The customer app name
1108
+ [REVID] Show this job in full instead of the list.
1109
+
1110
+ FLAGS
1111
+ --state=<option>... [default: CREATED,SCHEDULED,DEFERRED,RUNNING] List the jobs in these states. Repeatable. The
1112
+ default is every state of a job that has not ended.
1113
+ <options: CREATED|SCHEDULED|DEFERRED|RUNNING|FINISHED|ERROR|CANCELLED>
1114
+
1115
+ DESCRIPTION
1116
+ List the revalidation jobs of an app that have not ended, or show one in full. In a terminal, it asks which job to
1117
+ show or to start.
1118
+
1119
+ EXAMPLES
1120
+ $ sk revalidate jobs example-shop
1121
+
1122
+ $ sk revalidate jobs example-shop --state SCHEDULED --state CANCELLED
1123
+
1124
+ $ sk revalidate jobs example-shop <revId>
1125
+ ```
1126
+
1127
+ ## `sk revalidate start APP REVID`
1128
+
1129
+ Start a scheduled revalidation job now instead of after its wait.
1130
+
1131
+ ```
1132
+ USAGE
1133
+ $ sk revalidate start APP REVID [--wait]
1134
+
1135
+ ARGUMENTS
1136
+ APP The customer app name
1137
+ REVID The scheduled job to start now.
1138
+
1139
+ FLAGS
1140
+ --wait Wait until the job ends.
1141
+
1142
+ DESCRIPTION
1143
+ Start a scheduled revalidation job now instead of after its wait.
1144
+
1145
+ EXAMPLES
1146
+ $ sk revalidate start example-shop <revId>
1147
+
1148
+ $ sk revalidate start example-shop <revId> --wait
1149
+ ```
1150
+
1151
+ ## `sk revalidate unblock APP`
1152
+
1153
+ Start the scheduled deployment jobs of an app until none blocks the HTML. A scheduled deployment job makes Speed Kit answer 306 and serve from origin. Use it while the app runs at 0%: above 0%, let the jobs run on their own schedule and use `sk revalidate wait`.
1154
+
1155
+ ```
1156
+ USAGE
1157
+ $ sk revalidate unblock APP
1158
+
1159
+ ARGUMENTS
1160
+ APP The customer app name
1161
+
1162
+ DESCRIPTION
1163
+ Start the scheduled deployment jobs of an app until none blocks the HTML. A scheduled deployment job makes Speed Kit
1164
+ answer 306 and serve from origin. Use it while the app runs at 0%: above 0%, let the jobs run on their own schedule
1165
+ and use `sk revalidate wait`.
1166
+
1167
+ EXAMPLES
1168
+ $ sk revalidate unblock example-shop
1169
+ ```
1170
+
1171
+ ## `sk revalidate wait APP`
1172
+
1173
+ Wait until no deployment job of an app blocks the HTML. It starts nothing.
1174
+
1175
+ ```
1176
+ USAGE
1177
+ $ sk revalidate wait APP
1178
+
1179
+ ARGUMENTS
1180
+ APP The customer app name
1181
+
1182
+ DESCRIPTION
1183
+ Wait until no deployment job of an app blocks the HTML. It starts nothing.
1184
+
1185
+ EXAMPLES
1186
+ $ sk revalidate wait example-shop
1187
+ ```
1188
+
1087
1189
  ## `sk wpt-launcher URLS TESTID`
1088
1190
 
1089
1191
  Analyze the performance impact that Speed Kit has compared to the original version.
@@ -16,6 +16,8 @@ export default class Onboarding extends SkCommand<OnboardingServiceBuildContext>
16
16
  verboseLevel: import("@oclif/core/interfaces").BooleanFlag<boolean>;
17
17
  ignoreContentSecurityPolicy: import("@oclif/core/interfaces").BooleanFlag<boolean>;
18
18
  headless: import("@oclif/core/interfaces").BooleanFlag<boolean>;
19
+ device: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
20
+ mobile: import("@oclif/core/interfaces").BooleanFlag<boolean>;
19
21
  browse: import("@oclif/core/interfaces").BooleanFlag<boolean>;
20
22
  inject: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
21
23
  app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
@@ -10,6 +10,7 @@ export default class Onboarding extends SkCommand {
10
10
  `$ sk onboarding customers/decathlon.de -c production -d www.decathlon.de`,
11
11
  `$ sk onboarding --browse -d www.decathlon.de --headless --debugPort 9290`,
12
12
  `$ sk onboarding customers/decathlon.de --browse -p`,
13
+ `$ sk onboarding customers/decathlon.de -p --device tablet`,
13
14
  `$ sk onboarding customers/decathlon.de --inject`,
14
15
  `$ sk onboarding customers/decathlon.de --inject <installationId>`,
15
16
  ];
@@ -0,0 +1,16 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateJobsBuildContext } from "../../services/revalidate/index.js";
3
+ export default class RevalidateJobs extends SkCommand<RevalidateJobsBuildContext> {
4
+ static description: string;
5
+ static buildContext: typeof RevalidateJobsBuildContext;
6
+ static args: {
7
+ app: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
8
+ revId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
9
+ };
10
+ static flags: {
11
+ state: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
12
+ };
13
+ static examples: string[];
14
+ run(): Promise<void>;
15
+ private printList;
16
+ }
@@ -0,0 +1,80 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateFactory, RevalidateJobsBuildContext, } from "../../services/revalidate/index.js";
3
+ const DONE = "__done__";
4
+ export default class RevalidateJobs extends SkCommand {
5
+ static description = "List the revalidation jobs of an app that have not ended, or show one in full. In a terminal, it asks which job to show or to start.";
6
+ static buildContext = RevalidateJobsBuildContext;
7
+ static args = RevalidateJobsBuildContext.args;
8
+ static flags = RevalidateJobsBuildContext.flags;
9
+ static examples = [
10
+ "$ sk revalidate jobs example-shop",
11
+ "$ sk revalidate jobs example-shop --state SCHEDULED --state CANCELLED",
12
+ "$ sk revalidate jobs example-shop <revId>",
13
+ ];
14
+ async run() {
15
+ const { args, flags } = await this.parse(RevalidateJobs);
16
+ const cli = this.environment.cli;
17
+ const service = new RevalidateFactory(this.context).getService();
18
+ const states = flags["state"];
19
+ if (args.revId) {
20
+ this.log(JSON.stringify(await service.job(args.revId), null, 2));
21
+ return;
22
+ }
23
+ let jobs = await service.list(states);
24
+ this.printList(jobs, states);
25
+ if (cli.nonInteractive || jobs.length === 0) {
26
+ return;
27
+ }
28
+ for (;;) {
29
+ const revId = await cli.select("Which job?", [
30
+ ...jobs.map((job) => ({ name: line(job), value: job.revId })),
31
+ { name: "Done", value: DONE },
32
+ ]);
33
+ if (revId === DONE)
34
+ return;
35
+ const job = jobs.find((candidate) => candidate.revId === revId);
36
+ const action = await cli.select("What should happen?", [
37
+ { name: "Show details", value: "show" },
38
+ ...(job?.state === "SCHEDULED"
39
+ ? [{ name: "Start it now", value: "start" }]
40
+ : []),
41
+ { name: "Back", value: "back" },
42
+ ]);
43
+ if (action === "show") {
44
+ this.log(JSON.stringify(await service.job(revId), null, 2));
45
+ }
46
+ else if (action === "start") {
47
+ await service.resume(revId);
48
+ this.log(`started ${revId}`);
49
+ jobs = await service.list(states);
50
+ this.printList(jobs, states);
51
+ if (jobs.length === 0)
52
+ return;
53
+ }
54
+ }
55
+ }
56
+ printList(jobs, states) {
57
+ if (jobs.length === 0) {
58
+ this.log(`no job in ${states.join(", ")}`);
59
+ return;
60
+ }
61
+ for (const job of jobs)
62
+ this.log(line(job));
63
+ }
64
+ }
65
+ /** One job on one line: what it is, when it runs, and why it started. */
66
+ function line(job) {
67
+ const runs = job.state === "SCHEDULED" && job.scheduledAt && job.scheduleIn
68
+ ? ` runs ${new Date(Date.parse(job.scheduledAt) + job.scheduleIn).toISOString().slice(11, 19)}Z`
69
+ : "";
70
+ return [
71
+ job.revId,
72
+ job.state,
73
+ job.type ?? "",
74
+ job.triggeredBy ?? "",
75
+ `${job.startedAt?.slice(0, 19) ?? ""}${runs}`,
76
+ job.reason ?? "",
77
+ ]
78
+ .filter(Boolean)
79
+ .join(" ");
80
+ }
@@ -0,0 +1,15 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateStartBuildContext } from "../../services/revalidate/index.js";
3
+ export default class RevalidateStart extends SkCommand<RevalidateStartBuildContext> {
4
+ static description: string;
5
+ static buildContext: typeof RevalidateStartBuildContext;
6
+ static args: {
7
+ app: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
8
+ revId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
9
+ };
10
+ static flags: {
11
+ wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
12
+ };
13
+ static examples: string[];
14
+ run(): Promise<void>;
15
+ }
@@ -0,0 +1,25 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateFactory, RevalidateStartBuildContext, } from "../../services/revalidate/index.js";
3
+ export default class RevalidateStart extends SkCommand {
4
+ static description = "Start a scheduled revalidation job now instead of after its wait.";
5
+ static buildContext = RevalidateStartBuildContext;
6
+ static args = RevalidateStartBuildContext.args;
7
+ static flags = RevalidateStartBuildContext.flags;
8
+ static examples = [
9
+ "$ sk revalidate start example-shop <revId>",
10
+ "$ sk revalidate start example-shop <revId> --wait",
11
+ ];
12
+ async run() {
13
+ const { args, flags } = await this.parse(RevalidateStart);
14
+ const service = new RevalidateFactory(this.context).getService();
15
+ await service.resume(args.revId);
16
+ this.log(`started ${args.revId}`);
17
+ if (!flags["wait"])
18
+ return;
19
+ // A detected deployment that follows replaces the job, so CANCELLED is a normal end.
20
+ const job = await service.waitFor(args.revId);
21
+ this.log(`ended as ${job.state}, refreshed ${job.refreshedCount ?? 0}`);
22
+ if (job.state === "ERROR")
23
+ this.error(`the job failed: ${job.error}`);
24
+ }
25
+ }
@@ -0,0 +1,12 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateAppBuildContext } from "../../services/revalidate/index.js";
3
+ export default class RevalidateUnblock extends SkCommand<RevalidateAppBuildContext> {
4
+ static description: string;
5
+ static buildContext: typeof RevalidateAppBuildContext;
6
+ static args: {
7
+ app: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
8
+ };
9
+ static flags: {};
10
+ static examples: string[];
11
+ run(): Promise<void>;
12
+ }
@@ -0,0 +1,13 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateAppBuildContext, RevalidateFactory, } from "../../services/revalidate/index.js";
3
+ export default class RevalidateUnblock extends SkCommand {
4
+ static description = "Start the scheduled deployment jobs of an app until none blocks the HTML. A scheduled deployment job makes Speed Kit answer 306 and serve from origin. Use it while the app runs at 0%: above 0%, let the jobs run on their own schedule and use `sk revalidate wait`.";
5
+ static buildContext = RevalidateAppBuildContext;
6
+ static args = RevalidateAppBuildContext.args;
7
+ static flags = RevalidateAppBuildContext.flags;
8
+ static examples = ["$ sk revalidate unblock example-shop"];
9
+ async run() {
10
+ await new RevalidateFactory(this.context).getService().settleDeployments();
11
+ this.log("no deployment job blocks the HTML");
12
+ }
13
+ }
@@ -0,0 +1,12 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateAppBuildContext } from "../../services/revalidate/index.js";
3
+ export default class RevalidateWait extends SkCommand<RevalidateAppBuildContext> {
4
+ static description: string;
5
+ static buildContext: typeof RevalidateAppBuildContext;
6
+ static args: {
7
+ app: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
8
+ };
9
+ static flags: {};
10
+ static examples: string[];
11
+ run(): Promise<void>;
12
+ }
@@ -0,0 +1,13 @@
1
+ import { SkCommand } from "../../base/sk-command.js";
2
+ import { RevalidateAppBuildContext, RevalidateFactory, } from "../../services/revalidate/index.js";
3
+ export default class RevalidateWait extends SkCommand {
4
+ static description = "Wait until no deployment job of an app blocks the HTML. It starts nothing.";
5
+ static buildContext = RevalidateAppBuildContext;
6
+ static args = RevalidateAppBuildContext.args;
7
+ static flags = RevalidateAppBuildContext.flags;
8
+ static examples = ["$ sk revalidate wait example-shop"];
9
+ async run() {
10
+ await new RevalidateFactory(this.context).getService().waitForDeployments();
11
+ this.log("no deployment job blocks the HTML");
12
+ }
13
+ }
@@ -1,6 +1,7 @@
1
1
  import { Protocol, Viewport } from "puppeteer";
2
- /** The devices the browser fetcher can present, one per Speed Kit device variation. */
3
- export type FetchDevice = "desktop" | "mobile" | "tablet";
2
+ /** The devices the browser fetcher and `sk onboarding --device` can present, one per Speed Kit device variation. */
3
+ export declare const FETCH_DEVICES: readonly ["mobile", "tablet", "desktop"];
4
+ export type FetchDevice = (typeof FETCH_DEVICES)[number];
4
5
  /** Everything a page needs to look like one device, as `openPage` applies it. */
5
6
  export interface DeviceEmulation {
6
7
  readonly device: FetchDevice;
@@ -14,6 +15,16 @@ export interface DeviceEmulation {
14
15
  /** Null leaves the window's own viewport in place, which is what a desktop fetch wants. */
15
16
  readonly viewport: Viewport | null;
16
17
  }
18
+ /**
19
+ * The most common Chrome screen per device in Speed Kit RUM, in CSS px (physical px / DPR).
20
+ * Source: `rum.pi`, all apps, real page impressions with browser Chrome, snapshot of 2026-10-25.
21
+ * Refresh the values from the same query.
22
+ *
23
+ * - mobile: 1080x2340 @2.8125, the top Android Chrome phone screen (15.8%).
24
+ * - tablet: 1920x1200 @1.5, the top Android Chrome tablet screen (16.6% landscape, 16.4% portrait).
25
+ * - desktop: 1920x1080 @1, the top Chrome desktop screen (21%).
26
+ */
27
+ export declare const DEVICE_VIEWPORTS: Record<FetchDevice, Viewport>;
17
28
  /** True for one of the user agents the Asset API sends for a device variation. */
18
29
  export declare function isSpeedKitUserAgent(userAgent?: string): boolean;
19
30
  /**
@@ -42,5 +53,7 @@ export declare function deviceForUserAgent(userAgent?: string): FetchDevice | un
42
53
  *
43
54
  * @param browserVersionString - `browser.version()`, e.g. `Chrome/146.0.7680.165`.
44
55
  * @param device - The device to present.
56
+ * @param platform - Node platform of the desktop user agent. The fetcher keeps the host's, so its
57
+ * fingerprint matches; `sk onboarding --device desktop` presents Windows.
45
58
  */
46
- export declare function deviceEmulation(browserVersionString: string, device: FetchDevice): DeviceEmulation;
59
+ export declare function deviceEmulation(browserVersionString: string, device: FetchDevice, platform?: string): DeviceEmulation;
@@ -1,5 +1,7 @@
1
1
  import { buildHeadedUserAgent, chromeMajorVersion, } from "../onboarding/browser/executable/headed-user-agent.js";
2
2
  import { DEFAULT_USER_AGENT, MOBILE_USER_AGENT, TABLET_USER_AGENT, } from "../origin-request/asset-variations.js";
3
+ /** The devices the browser fetcher and `sk onboarding --device` can present, one per Speed Kit device variation. */
4
+ export const FETCH_DEVICES = ["mobile", "tablet", "desktop"];
3
5
  /**
4
6
  * Android's frozen platform token. Chrome's UA reduction pins every Android build to
5
7
  * `Android 10; K` regardless of the device, so this is the literal string real Chrome sends —
@@ -30,28 +32,38 @@ const DEFAULT_DESKTOP_PLATFORM = { platform: "Linux", version: "" };
30
32
  */
31
33
  const GREASE_BRAND = { brand: "Not=A?Brand", version: "24" };
32
34
  /**
33
- * Viewports for the emulated devices. Deliberately not puppeteer's `KnownDevices`: those carry a
34
- * frozen user agent each, and the frozen strings are stale enough to be a signal on their own —
35
- * `Galaxy Tab S4` still says `Chrome/70`, `iPad Pro 11` pairs `CPU OS 12_2` with `Version/15.4`.
36
- * Only the metrics are taken from a real device (a Pixel-class phone and a 11" tablet).
35
+ * The most common Chrome screen per device in Speed Kit RUM, in CSS px (physical px / DPR).
36
+ * Source: `rum.pi`, all apps, real page impressions with browser Chrome, snapshot of 2026-10-25.
37
+ * Refresh the values from the same query.
38
+ *
39
+ * - mobile: 1080x2340 @2.8125, the top Android Chrome phone screen (15.8%).
40
+ * - tablet: 1920x1200 @1.5, the top Android Chrome tablet screen (16.6% landscape, 16.4% portrait).
41
+ * - desktop: 1920x1080 @1, the top Chrome desktop screen (21%).
37
42
  */
38
- const VIEWPORTS = {
39
- desktop: null,
43
+ export const DEVICE_VIEWPORTS = {
40
44
  mobile: {
41
- width: 412,
42
- height: 915,
43
- deviceScaleFactor: 2.625,
45
+ width: 384,
46
+ height: 832,
47
+ deviceScaleFactor: 2.8125,
44
48
  isMobile: true,
45
49
  hasTouch: true,
46
50
  isLandscape: false,
47
51
  },
48
52
  tablet: {
49
- width: 834,
50
- height: 1112,
51
- deviceScaleFactor: 2,
53
+ width: 1280,
54
+ height: 800,
55
+ deviceScaleFactor: 1.5,
52
56
  isMobile: true,
53
57
  hasTouch: true,
54
- isLandscape: false,
58
+ isLandscape: true,
59
+ },
60
+ desktop: {
61
+ width: 1920,
62
+ height: 1080,
63
+ deviceScaleFactor: 1,
64
+ isMobile: false,
65
+ hasTouch: false,
66
+ isLandscape: true,
55
67
  },
56
68
  };
57
69
  /** The device each of the server's default variation user agents stands for. */
@@ -104,17 +116,20 @@ export function deviceForUserAgent(userAgent) {
104
116
  *
105
117
  * @param browserVersionString - `browser.version()`, e.g. `Chrome/146.0.7680.165`.
106
118
  * @param device - The device to present.
119
+ * @param platform - Node platform of the desktop user agent. The fetcher keeps the host's, so its
120
+ * fingerprint matches; `sk onboarding --device desktop` presents Windows.
107
121
  */
108
- export function deviceEmulation(browserVersionString, device) {
109
- const viewport = VIEWPORTS[device];
122
+ export function deviceEmulation(browserVersionString, device, platform = process.platform) {
123
+ // A desktop fetch keeps the window's own viewport, from the launch's `defaultViewport: null`.
124
+ const viewport = device === "desktop" ? null : DEVICE_VIEWPORTS[device];
110
125
  const major = chromeMajorVersion(browserVersionString);
111
126
  if (!major)
112
127
  return { device, viewport };
113
128
  if (device === "desktop") {
114
129
  return {
115
130
  device,
116
- userAgent: buildHeadedUserAgent(browserVersionString),
117
- metadata: desktopMetadata(major),
131
+ userAgent: buildHeadedUserAgent(browserVersionString, platform),
132
+ metadata: desktopMetadata(major, platform),
118
133
  viewport,
119
134
  };
120
135
  }
@@ -56,6 +56,26 @@ describe("deviceEmulation", () => {
56
56
  expect(emulation.userAgent).to.equal("Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36");
57
57
  expect(emulation.viewport?.width).to.be.greaterThan(deviceEmulation(CHROME_VERSION, "mobile").viewport?.width ?? 0);
58
58
  });
59
+ it("takes the most common Chrome phone and tablet screens of RUM", () => {
60
+ expect(deviceEmulation(CHROME_VERSION, "mobile").viewport).to.deep.include({
61
+ width: 384,
62
+ height: 832,
63
+ deviceScaleFactor: 2.8125,
64
+ isLandscape: false,
65
+ });
66
+ expect(deviceEmulation(CHROME_VERSION, "tablet").viewport).to.deep.include({
67
+ width: 1280,
68
+ height: 800,
69
+ deviceScaleFactor: 1.5,
70
+ isLandscape: true,
71
+ });
72
+ });
73
+ it("presents the desktop on the given platform", () => {
74
+ const emulation = deviceEmulation(CHROME_VERSION, "desktop", "win32");
75
+ expect(emulation.userAgent).to.equal("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36");
76
+ expect(emulation.metadata?.platform).to.equal("Windows");
77
+ expect(emulation.viewport).to.equal(null);
78
+ });
59
79
  it("sends client hints that agree with the Android user agent", () => {
60
80
  const mobile = deviceEmulation(CHROME_VERSION, "mobile").metadata;
61
81
  const tablet = deviceEmulation(CHROME_VERSION, "tablet").metadata;
@@ -0,0 +1,13 @@
1
+ import { Browser } from "puppeteer";
2
+ import { BrowserContext } from "../onboarding-model.js";
3
+ /**
4
+ * Emulates the device of `--device` on every page and Service Worker of `browser`: the ones open
5
+ * now, and every one opened later, by the CLI or by an external CDP client.
6
+ *
7
+ * A browser-wide auto-attach holds each new target until its overrides are in, so the first request
8
+ * of a page or worker already carries them. Each override is sent once, when the target appears. A
9
+ * client that overrides the metrics afterwards keeps its own values.
10
+ *
11
+ * The overrides live as long as this session, which lives as long as the browser connection.
12
+ */
13
+ export declare function emulateDevice(browser: Browser, browserContext: BrowserContext): Promise<void>;
@@ -0,0 +1,50 @@
1
+ import { safe } from "../../../helpers/safe.js";
2
+ /**
3
+ * Emulates the device of `--device` on every page and Service Worker of `browser`: the ones open
4
+ * now, and every one opened later, by the CLI or by an external CDP client.
5
+ *
6
+ * A browser-wide auto-attach holds each new target until its overrides are in, so the first request
7
+ * of a page or worker already carries them. Each override is sent once, when the target appears. A
8
+ * client that overrides the metrics afterwards keeps its own values.
9
+ *
10
+ * The overrides live as long as this session, which lives as long as the browser connection.
11
+ */
12
+ export async function emulateDevice(browser, browserContext) {
13
+ const session = await browser.target().createCDPSession();
14
+ session.on("Target.attachedToTarget", (event) => {
15
+ const target = session.connection()?.session(event.sessionId);
16
+ if (target)
17
+ void emulateTarget(target, event, browserContext);
18
+ });
19
+ await session.send("Target.setAutoAttach", {
20
+ autoAttach: true,
21
+ waitForDebuggerOnStart: true,
22
+ flatten: true,
23
+ });
24
+ }
25
+ async function emulateTarget(session, { targetInfo, waitingForDebugger }, browserContext) {
26
+ // Not the DevTools window that `devtools: true` docks next to a headed page.
27
+ const isPage = targetInfo.type === "page" && !targetInfo.url.startsWith("devtools:");
28
+ const { userAgent, metadata } = browserContext.emulation;
29
+ // The client hints: the `--user-agent` launch flag changes only the string, so Chrome would still
30
+ // send the host's `Sec-CH-UA-Platform` and `Sec-CH-UA-Mobile`.
31
+ if (userAgent && (isPage || targetInfo.type === "service_worker")) {
32
+ await safe(session.send("Network.setUserAgentOverride", {
33
+ userAgent,
34
+ userAgentMetadata: metadata,
35
+ }));
36
+ }
37
+ if (isPage) {
38
+ await safe(session.send("Emulation.setDeviceMetricsOverride", browserContext.getDeviceMetricsOverride()));
39
+ const touch = browserContext.getTouchEmulation();
40
+ await safe(session.send("Emulation.setTouchEmulationEnabled", touch));
41
+ // Without it a mouse click never reaches a touch-only handler in headed mode.
42
+ await safe(session.send("Emulation.setEmitTouchEventsForMouse", {
43
+ enabled: touch.enabled,
44
+ configuration: "mobile",
45
+ }));
46
+ }
47
+ if (waitingForDebugger) {
48
+ await safe(session.send("Runtime.runIfWaitingForDebugger"));
49
+ }
50
+ }
@@ -1,7 +1,12 @@
1
1
  import puppeteerExtra from "puppeteer-extra";
2
+ import { emulateDevice } from "./emulate-device.js";
2
3
  /** Launches the onboarding Chrome. Onboarding and browse mode share it, so their hardening cannot drift. */
3
- export function launchBrowser(browserContext) {
4
- return puppeteerExtra.default.launch(browserContext.getPuppeteerLaunchOptions());
4
+ export async function launchBrowser(browserContext) {
5
+ const browser = await puppeteerExtra.default.launch(browserContext.getPuppeteerLaunchOptions());
6
+ if (browserContext.emulation) {
7
+ await emulateDevice(browser, browserContext);
8
+ }
9
+ return browser;
5
10
  }
6
11
  /**
7
12
  * Starts from a clean state for `origin`: no service worker, no cookies, no stored data, no