@speedkit/cli 4.51.0-run-control.1 → 4.51.0-run-control.2

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 (93) hide show
  1. package/README.md +81 -29
  2. package/dist/build-info.json +3 -3
  3. package/dist/commands/diff.d.ts +1 -0
  4. package/dist/commands/login.d.ts +3 -0
  5. package/dist/commands/login.js +14 -3
  6. package/dist/commands/onboarding/browser/emulate.d.ts +12 -0
  7. package/dist/commands/onboarding/browser/emulate.js +3 -0
  8. package/dist/commands/onboarding/browser/navigate.d.ts +8 -0
  9. package/dist/commands/onboarding/browser/navigate.js +2 -1
  10. package/dist/commands/onboarding/cache/prewarm.js +1 -1
  11. package/dist/commands/onboarding/debug/arm.d.ts +6 -0
  12. package/dist/commands/onboarding/debug/arm.js +2 -1
  13. package/dist/commands/onboarding/files/rebuild.d.ts +6 -6
  14. package/dist/commands/onboarding/logs.js +3 -2
  15. package/dist/commands/onboarding/status.js +2 -2
  16. package/dist/commands/onboarding/stop.d.ts +13 -0
  17. package/dist/commands/onboarding/stop.js +17 -0
  18. package/dist/commands/onboarding.d.ts +1 -1
  19. package/dist/commands/onboarding.js +1 -1
  20. package/dist/services/diff/diff-service-build-context.d.ts +4 -0
  21. package/dist/services/diff/diff-service-build-context.js +5 -0
  22. package/dist/services/diff/diff-service-factory.js +17 -5
  23. package/dist/services/diff/run-runtime-config.d.ts +33 -0
  24. package/dist/services/diff/run-runtime-config.js +74 -0
  25. package/dist/services/diff/spec/run-runtime-config.spec.d.ts +1 -0
  26. package/dist/services/diff/spec/run-runtime-config.spec.js +87 -0
  27. package/dist/services/onboarding/browse/browse-service.d.ts +13 -1
  28. package/dist/services/onboarding/browse/browse-service.js +40 -7
  29. package/dist/services/onboarding/browser/answer-dialogs.d.ts +12 -0
  30. package/dist/services/onboarding/browser/answer-dialogs.js +25 -0
  31. package/dist/services/onboarding/browser/emulate-device.d.ts +12 -1
  32. package/dist/services/onboarding/browser/emulate-device.js +33 -6
  33. package/dist/services/onboarding/browser/launch-browser.d.ts +2 -1
  34. package/dist/services/onboarding/browser/launch-browser.js +3 -1
  35. package/dist/services/onboarding/control/browser-session.d.ts +26 -12
  36. package/dist/services/onboarding/control/browser-session.js +118 -91
  37. package/dist/services/onboarding/control/control-protocol.d.ts +39 -1
  38. package/dist/services/onboarding/control/control-protocol.js +0 -11
  39. package/dist/services/onboarding/control/control-server.d.ts +8 -0
  40. package/dist/services/onboarding/control/control-server.js +22 -2
  41. package/dist/services/onboarding/control/debug-session.d.ts +30 -1
  42. package/dist/services/onboarding/control/debug-session.js +106 -10
  43. package/dist/services/onboarding/control/navigate-wait.d.ts +33 -0
  44. package/dist/services/onboarding/control/navigate-wait.js +56 -0
  45. package/dist/services/onboarding/control/service-worker-tracker.js +1 -0
  46. package/dist/services/onboarding/control/watch.js +9 -1
  47. package/dist/services/onboarding/fetch-event-handler.js +9 -0
  48. package/dist/services/onboarding/inject/inject-service.js +1 -1
  49. package/dist/services/onboarding/onboarding-model.js +2 -1
  50. package/dist/services/onboarding/onboarding-service-build-context.js +1 -1
  51. package/dist/services/onboarding/onboarding-service-factory.js +20 -7
  52. package/dist/services/onboarding/onboarding-service.js +1 -1
  53. package/dist/services/onboarding/spec/browser/answer-dialogs.spec.d.ts +1 -0
  54. package/dist/services/onboarding/spec/browser/answer-dialogs.spec.js +66 -0
  55. package/dist/services/onboarding/spec/control/browser-session.spec.js +127 -2
  56. package/dist/services/onboarding/spec/control/control-server.spec.js +33 -0
  57. package/dist/services/onboarding/spec/control/debug-session.spec.js +58 -0
  58. package/dist/services/onboarding/spec/control/navigate-wait.spec.d.ts +1 -0
  59. package/dist/services/onboarding/spec/control/navigate-wait.spec.js +47 -0
  60. package/dist/services/onboarding/spec/control/watch.spec.js +15 -0
  61. package/dist/services/onboarding/spec/fetch-event-handler.spec.js +17 -0
  62. package/dist/services/onboarding/spec/onboarding-model.spec.js +2 -3
  63. package/dist/services/onboarding/spec/onboarding-service-factory.spec.js +24 -1
  64. package/dist/services/onboarding/spec/virtual-orestes-app/virtual-orestes-app.spec.d.ts +1 -0
  65. package/dist/services/onboarding/spec/virtual-orestes-app/virtual-orestes-app.spec.js +65 -0
  66. package/dist/services/onboarding/virtual-orestes-app/index.d.ts +4 -0
  67. package/dist/services/onboarding/virtual-orestes-app/index.js +31 -0
  68. package/dist/services/origin-request/runtime-config-source.d.ts +6 -0
  69. package/dist/services/origin-request/runtime-config-source.js +6 -0
  70. package/dist/services/run-control/browser/run-browser-contexts.d.ts +16 -0
  71. package/dist/services/run-control/browser/run-browser-contexts.js +14 -1
  72. package/dist/services/run-control/browser/run-browser-service.d.ts +5 -1
  73. package/dist/services/run-control/browser/run-browser-service.js +16 -9
  74. package/dist/services/run-control/debug/run-debug-contexts.d.ts +5 -0
  75. package/dist/services/run-control/debug/run-debug-contexts.js +3 -0
  76. package/dist/services/run-control/debug/run-debug-service.d.ts +1 -0
  77. package/dist/services/run-control/debug/run-debug-service.js +3 -0
  78. package/dist/services/run-control/files/run-files-contexts.d.ts +5 -5
  79. package/dist/services/run-control/inject/run-inject-contexts.js +7 -1
  80. package/dist/services/run-control/inject/run-inject-service.d.ts +2 -2
  81. package/dist/services/run-control/inject/run-inject-service.js +32 -8
  82. package/dist/services/run-control/probe/run-probe-service.js +1 -0
  83. package/dist/services/run-control/session/run-session-service.d.ts +8 -1
  84. package/dist/services/run-control/session/run-session-service.js +58 -2
  85. package/dist/services/run-control/spec/cache/run-cache-service.spec.js +1 -1
  86. package/dist/services/run-control/spec/inject/run-inject-service.spec.js +27 -0
  87. package/dist/services/run-control/spec/session/run-session-service.spec.js +49 -0
  88. package/dist/services/run-log/request-log.d.ts +3 -1
  89. package/dist/services/run-registry/run-registry.d.ts +7 -2
  90. package/dist/services/run-registry/run-registry.js +26 -5
  91. package/dist/services/run-registry/spec/run-registry.spec.js +17 -0
  92. package/oclif.manifest.json +281 -181
  93. package/package.json +1 -1
@@ -1,6 +1,7 @@
1
1
  import { Browser, Page } from "puppeteer";
2
2
  import { BrowserActionData, BrowserResetScope, BrowserStateData, PageThreadState, BrowserClickData, BrowserEmulateData, CdpData, EmulatedDevice, TabInfo, EmulationState } from "./control-protocol.js";
3
3
  import { DebugSession, DebugTransport } from "./debug-session.js";
4
+ import { NavigateWaitPoint } from "./navigate-wait.js";
4
5
  import { NavwalkBrowser, RawDocumentHit } from "./navwalk.js";
5
6
  import { ViewportBrowser } from "./viewport.js";
6
7
  import { PreloadRegistry, PreloadTransport } from "./preload-registry.js";
@@ -11,6 +12,9 @@ export interface EmulationRequest {
11
12
  width?: number;
12
13
  height?: number;
13
14
  dpr?: number;
15
+ /** Replaces the preset's user agent, without client hints: Safari sends none. */
16
+ userAgent?: string;
17
+ touch?: boolean;
14
18
  reload?: boolean;
15
19
  }
16
20
  /** What `click` clicks: a CSS selector, or a control's visible text. */
@@ -185,7 +189,7 @@ export interface BrowserController extends PageEvaluator {
185
189
  state(): Promise<BrowserStateData>;
186
190
  reset(scope: BrowserResetScope): Promise<BrowserActionData>;
187
191
  reinstallServiceWorker(): Promise<BrowserActionData>;
188
- navigate(url: string): Promise<BrowserActionData>;
192
+ navigate(url: string, wait?: NavigateWaitPoint, waitMs?: number): Promise<BrowserActionData>;
189
193
  /** Open DevTools for the page on the Speed Kit panel. */
190
194
  showPanel(): Promise<BrowserActionData>;
191
195
  /** Present the page as a device until switched off, workers included. */
@@ -257,7 +261,8 @@ export declare class BrowserSession implements BrowserController, PreloadTranspo
257
261
  * open: an override lasts as long as the session that set it.
258
262
  */
259
263
  private workers;
260
- private onWorkerCreated?;
264
+ /** The browser-wide auto-attach that overrides every service worker as it starts. */
265
+ private workerAttach?;
261
266
  /** One session per other tab a caller has asked about, made on demand. */
262
267
  private readonly tabSessions;
263
268
  /**
@@ -430,23 +435,27 @@ export declare class BrowserSession implements BrowserController, PreloadTranspo
430
435
  * Chrome's next update check.
431
436
  */
432
437
  private serveWorkerAs;
433
- /** Override the user agent on every service worker, and on each one that appears. */
438
+ /**
439
+ * Override the user agent and its client hints on every service worker, and
440
+ * on each one that starts later, before its first line runs: a stopped worker
441
+ * has no target, and the next fetch starts it fresh.
442
+ */
434
443
  private emulateWorkers;
435
444
  private overrideWorker;
436
445
  /**
437
- * What each of the app's service workers says its user agent is, read in
438
- * the worker, once the page's worker is active.
446
+ * What the worker in charge of the page says its user agent is, read in the
447
+ * worker, once one is active.
439
448
  *
440
- * Listed fresh rather than from the sessions made earlier: the worker that
441
- * ends up active may have started since. Only workers on the app's origins —
442
- * the devtools extension runs one too, and counting it was noise.
449
+ * Only that one: it decides the device. A run collects stale registrations,
450
+ * and asking each of them, one stopped worker after the other, ran past the
451
+ * op's budget. An empty list means no worker is in charge yet.
443
452
  */
444
453
  private workerUserAgents;
445
454
  /**
446
- * The script url of the worker in charge of the page, waiting briefly for
447
- * one to activate after a reinstall. Null when none did in time.
455
+ * The version of the worker in charge of the page, waiting briefly for one
456
+ * to activate after a reinstall. Null when none did in time.
448
457
  */
449
- private activeWorkerScript;
458
+ private activeWorker;
450
459
  private forgetWorkers;
451
460
  /**
452
461
  * Load the page again, as a navigation: a document already loaded was laid
@@ -497,7 +506,12 @@ export declare class BrowserSession implements BrowserController, PreloadTranspo
497
506
  * A relative url resolves against the page's current origin, which is where
498
507
  * the caller is looking.
499
508
  */
500
- navigate(url: string): Promise<BrowserActionData>;
509
+ navigate(url: string, wait?: NavigateWaitPoint, waitMs?: number): Promise<BrowserActionData>;
510
+ /**
511
+ * Looks at the page until `point`'s mark lands, or until it cannot land any more, or until
512
+ * `deadline`. Never pauses the page.
513
+ */
514
+ private waitForMark;
501
515
  /**
502
516
  * Bring the devtools extension's panel to the front, opening DevTools for
503
517
  * the page if it is closed.
@@ -1,5 +1,7 @@
1
1
  import { DebugSession } from "./debug-session.js";
2
+ import { WAIT_MARKS, WAIT_PROBE, decideWait, } from "./navigate-wait.js";
2
3
  import { deviceEmulation } from "../../browser-fetch/device-emulation.js";
4
+ import { onEveryTarget } from "../browser/emulate-device.js";
3
5
  import { PreloadRegistry } from "./preload-registry.js";
4
6
  import { PanelNotFoundError, showDevtoolsPanel, } from "../browser/extension/devtools-panel.js";
5
7
  /** Long enough for a real expression, short enough that a stall is reported. */
@@ -170,7 +172,8 @@ export class BrowserSession {
170
172
  * open: an override lasts as long as the session that set it.
171
173
  */
172
174
  workers = [];
173
- onWorkerCreated;
175
+ /** The browser-wide auto-attach that overrides every service worker as it starts. */
176
+ workerAttach;
174
177
  /** One session per other tab a caller has asked about, made on demand. */
175
178
  tabSessions = new Map();
176
179
  /**
@@ -516,17 +519,21 @@ export class BrowserSession {
516
519
  height: request.height ?? preset.height,
517
520
  dpr: request.dpr ?? preset.dpr,
518
521
  mobile: preset.mobile,
519
- touch: preset.touch,
520
- userAgent: device.userAgent ?? null,
522
+ touch: request.touch ?? preset.touch,
523
+ userAgent: request.userAgent ?? device.userAgent ?? null,
521
524
  since: new Date().toISOString(),
522
525
  };
523
526
  // The session first: making one re-applies whatever emulation is set, and
524
527
  // setting it before would apply this one twice.
525
528
  const session = await this.cdpSession();
526
- this.emulation = { state, metadata: device.metadata };
529
+ this.emulation = {
530
+ state,
531
+ metadata: request.userAgent ? undefined : device.metadata,
532
+ };
527
533
  await this.applyEmulation(session);
528
- await this.serveWorkerAs(state.userAgent);
534
+ // Before the reinstall, so the worker it starts is held until it is overridden.
529
535
  await this.emulateWorkers();
536
+ await this.serveWorkerAs(state.userAgent);
530
537
  const reloaded = await this.reloadUnder(request);
531
538
  // The worker that ends up active is not always the one the reinstall
532
539
  // produced: a short-lived registration can come first, and the run's own
@@ -832,112 +839,89 @@ export class BrowserSession {
832
839
  context.setWorkerUserAgent(userAgent);
833
840
  await context.reinstall();
834
841
  }
835
- /** Override the user agent on every service worker, and on each one that appears. */
842
+ /**
843
+ * Override the user agent and its client hints on every service worker, and
844
+ * on each one that starts later, before its first line runs: a stopped worker
845
+ * has no target, and the next fetch starts it fresh.
846
+ */
836
847
  async emulateWorkers() {
837
848
  const browser = this.browser;
838
- if (!browser) {
839
- return;
840
- }
841
849
  this.forgetWorkers();
842
- for (const target of browser.targets()) {
843
- await this.overrideWorker(target);
850
+ if (!browser || !this.emulation?.state.userAgent) {
851
+ return;
844
852
  }
845
- // A worker that is stopped has no target, and the next fetch starts it
846
- // fresh — without the override. So the override follows new workers too.
847
- this.onWorkerCreated = (target) => {
848
- void this.overrideWorker(target);
849
- };
850
- browser.on("targetcreated", this.onWorkerCreated);
853
+ this.workerAttach = await bounded(onEveryTarget(browser, (session, targetInfo) => this.overrideWorker(session, targetInfo), [{ type: "service_worker" }]), "Target.setAutoAttach", this.cdpAnswerMs);
851
854
  }
852
- async overrideWorker(target) {
855
+ async overrideWorker(session, { url, targetId }) {
853
856
  const emulation = this.emulation;
854
- if (!emulation?.state.userAgent || target.type() !== "service_worker") {
857
+ if (!emulation?.state.userAgent) {
855
858
  return;
856
859
  }
857
- try {
858
- const session = await bounded(target.createCDPSession(), "Target.attachToTarget", this.cdpAnswerMs);
859
- await bounded(session.send("Network.setUserAgentOverride", {
860
- userAgent: emulation.state.userAgent,
861
- ...(emulation.metadata
862
- ? { userAgentMetadata: emulation.metadata }
863
- : {}),
864
- }), "Network.setUserAgentOverride", this.cdpAnswerMs);
865
- this.workers.push({ session, url: target.url() });
866
- }
867
- catch {
868
- // A worker that went away between listing and attaching has nothing to
869
- // override; `workerUserAgents` reports what is actually there.
870
- }
860
+ this.workers.push({ session, url, targetId });
861
+ await bounded(session.send("Network.setUserAgentOverride", {
862
+ userAgent: emulation.state.userAgent,
863
+ ...(emulation.metadata
864
+ ? { userAgentMetadata: emulation.metadata }
865
+ : {}),
866
+ }), "Network.setUserAgentOverride", this.cdpAnswerMs);
871
867
  }
872
868
  /**
873
- * What each of the app's service workers says its user agent is, read in
874
- * the worker, once the page's worker is active.
869
+ * What the worker in charge of the page says its user agent is, read in the
870
+ * worker, once one is active.
875
871
  *
876
- * Listed fresh rather than from the sessions made earlier: the worker that
877
- * ends up active may have started since. Only workers on the app's origins —
878
- * the devtools extension runs one too, and counting it was noise.
872
+ * Only that one: it decides the device. A run collects stale registrations,
873
+ * and asking each of them, one stopped worker after the other, ran past the
874
+ * op's budget. An empty list means no worker is in charge yet.
879
875
  */
880
876
  async workerUserAgents(settle) {
881
- const context = this.require();
882
877
  const wanted = this.emulation?.state.userAgent ?? null;
883
- const origins = new Set([context.origin, ...context.origins].map((origin) => {
884
- try {
885
- return new URL(normalise(origin)).origin;
886
- }
887
- catch {
888
- return origin;
889
- }
890
- }));
891
- const active = await this.activeWorkerScript(settle ? WORKER_SETTLE_MS : 0);
892
- const targets = (this.browser?.targets() ?? []).filter((target) => {
893
- if (target.type() !== "service_worker") {
894
- return false;
895
- }
896
- try {
897
- return origins.has(new URL(target.url()).origin);
898
- }
899
- catch {
900
- return false;
901
- }
902
- });
903
- const answers = [];
904
- for (const target of targets) {
905
- const known = this.workers.find((worker) => worker.url === target.url() && !worker.session.detached);
906
- const session = known?.session ??
907
- (await bounded(target.createCDPSession(), "Target.attachToTarget", this.cdpAnswerMs).catch(() => undefined));
908
- if (!session) {
909
- continue;
910
- }
911
- if (!known) {
912
- this.workers.push({ session, url: target.url() });
913
- }
914
- const userAgent = await bounded(session.send("Runtime.evaluate", {
878
+ const active = await this.activeWorker(settle ? WORKER_SETTLE_MS : 0);
879
+ if (!active) {
880
+ return [];
881
+ }
882
+ const known = this.workers.find((worker) => !worker.session.detached &&
883
+ (active.targetId
884
+ ? worker.targetId === active.targetId
885
+ : worker.url === active.scriptURL));
886
+ const target = known
887
+ ? undefined
888
+ : (this.browser?.targets() ?? []).find((one) => one.type() === "service_worker" && one.url() === active.scriptURL);
889
+ const session = known?.session ??
890
+ (target &&
891
+ (await bounded(target.createCDPSession(), "Target.attachToTarget", this.cdpAnswerMs).catch(() => undefined)));
892
+ if (session && !known) {
893
+ this.workers.push({ session, url: active.scriptURL });
894
+ }
895
+ const userAgent = session
896
+ ? await bounded(session.send("Runtime.evaluate", {
915
897
  expression: "navigator.userAgent",
916
898
  returnByValue: true,
917
899
  }), "Runtime.evaluate", this.cdpAnswerMs)
918
- .then((result) => String(result.result?.value ?? "") || null)
919
- .catch(() => null);
920
- answers.push({
921
- url: target.url(),
900
+ .then((result) => String(result.result?.value ??
901
+ "") || null)
902
+ .catch(() => null)
903
+ : null;
904
+ return [
905
+ {
906
+ url: active.scriptURL,
922
907
  userAgent,
923
908
  emulated: wanted !== null && userAgent === wanted,
924
- active: active !== null && target.url() === active,
925
- });
926
- }
927
- return answers;
909
+ active: true,
910
+ },
911
+ ];
928
912
  }
929
913
  /**
930
- * The script url of the worker in charge of the page, waiting briefly for
931
- * one to activate after a reinstall. Null when none did in time.
914
+ * The version of the worker in charge of the page, waiting briefly for one
915
+ * to activate after a reinstall. Null when none did in time.
932
916
  */
933
- async activeWorkerScript(waitMs) {
917
+ async activeWorker(waitMs) {
934
918
  const context = this.require();
935
919
  const deadline = Date.now() + waitMs;
936
920
  for (;;) {
937
921
  const state = context.serviceWorkers.state(this.url());
938
922
  const version = state.versions.find((one) => one.versionId === state.activeVersionId);
939
923
  if (version) {
940
- return version.scriptURL;
924
+ return version;
941
925
  }
942
926
  if (Date.now() > deadline) {
943
927
  return null;
@@ -946,10 +930,8 @@ export class BrowserSession {
946
930
  }
947
931
  }
948
932
  forgetWorkers() {
949
- if (this.onWorkerCreated) {
950
- this.browser?.off("targetcreated", this.onWorkerCreated);
951
- this.onWorkerCreated = undefined;
952
- }
933
+ void this.workerAttach?.detach().catch(() => undefined);
934
+ this.workerAttach = undefined;
953
935
  for (const { session } of this.workers) {
954
936
  void session.detach().catch(() => undefined);
955
937
  }
@@ -1095,7 +1077,8 @@ export class BrowserSession {
1095
1077
  * A relative url resolves against the page's current origin, which is where
1096
1078
  * the caller is looking.
1097
1079
  */
1098
- async navigate(url) {
1080
+ async navigate(url, wait = "load", waitMs = NAVIGATION_TIMEOUT_MS) {
1081
+ const started = Date.now();
1099
1082
  // The page's origin when the app covers it, the run's own otherwise. A
1100
1083
  // login flow regularly leaves the tab on an identity provider, and a
1101
1084
  // relative url resolved against that is refused as off-app — when what
@@ -1117,9 +1100,13 @@ export class BrowserSession {
1117
1100
  // socket's patience used to surface as CONTROL_TIMEOUT on a page that had
1118
1101
  // in fact moved — an error about something that worked. Bounded here and
1119
1102
  // reported as what it is.
1103
+ // A wait for a mark needs the new document only, not its load event.
1120
1104
  let loaded = true;
1121
1105
  try {
1122
- await this.page.goto(target.href, { timeout: NAVIGATION_TIMEOUT_MS });
1106
+ await this.page.goto(target.href, {
1107
+ timeout: waitMs,
1108
+ waitUntil: wait === "load" ? "load" : "domcontentloaded",
1109
+ });
1123
1110
  }
1124
1111
  catch (error) {
1125
1112
  if (!isTimeout(error)) {
@@ -1127,14 +1114,54 @@ export class BrowserSession {
1127
1114
  }
1128
1115
  loaded = false;
1129
1116
  }
1117
+ const point = wait === "load"
1118
+ ? undefined
1119
+ : await this.waitForMark(wait, started + waitMs);
1130
1120
  return {
1131
1121
  url: this.url(),
1132
- did: loaded
1122
+ did: (loaded || point
1133
1123
  ? `navigated to ${target.href}`
1134
- : `navigated to ${target.href}, which had not finished loading after ${NAVIGATION_TIMEOUT_MS}ms — the page did move, so read from it as usual`,
1124
+ : `navigated to ${target.href}, which had not finished loading after ${waitMs}ms — the page did move, so read from it as usual`) +
1125
+ (point
1126
+ ? point.reached
1127
+ ? `; ${point.point} (${point.mark}) at ${point.atMs}ms`
1128
+ : `; ${point.point} ${point.reason}`
1129
+ : ""),
1135
1130
  origin: target.origin,
1131
+ ...(point ? { wait: point } : {}),
1136
1132
  };
1137
1133
  }
1134
+ /**
1135
+ * Looks at the page until `point`'s mark lands, or until it cannot land any more, or until
1136
+ * `deadline`. Never pauses the page.
1137
+ */
1138
+ async waitForMark(point, deadline) {
1139
+ let loadedAt;
1140
+ let probe;
1141
+ for (;;) {
1142
+ probe = await this.call("Runtime.evaluate", { expression: WAIT_PROBE, returnByValue: true }, Math.max(500, Math.min(2000, deadline - Date.now())))
1143
+ .then(({ result }) => JSON.parse(result?.value ?? "null"))
1144
+ .catch(() => undefined);
1145
+ if (probe) {
1146
+ if (probe.readyState === "complete")
1147
+ loadedAt ??= Date.now();
1148
+ const decided = decideWait(point, probe, loadedAt === undefined ? undefined : Date.now() - loadedAt);
1149
+ if (decided)
1150
+ return decided;
1151
+ }
1152
+ if (Date.now() >= deadline) {
1153
+ return {
1154
+ point,
1155
+ mark: WAIT_MARKS[point],
1156
+ reached: false,
1157
+ reason: probe
1158
+ ? `not reached: timed out (document ${probe.readyState}, responseSource ${probe.responseSource ?? "none"})`
1159
+ : "not reached: timed out, and the page did not answer",
1160
+ };
1161
+ }
1162
+ await new Promise((resolve) => setTimeout(resolve, 100));
1163
+ }
1164
+ }
1138
1165
  /**
1139
1166
  * Bring the devtools extension's panel to the front, opening DevTools for
1140
1167
  * the page if it is closed.
@@ -1,3 +1,4 @@
1
+ import type { NavigateWaitData, NavigateWaitPoint } from "./navigate-wait.js";
1
2
  /**
2
3
  * The seam between a live `sk onboarding` run and anything outside it.
3
4
  *
@@ -9,6 +10,7 @@
9
10
  * line, an id to match them. The clients are short-lived `sk onboarding <tool>`
10
11
  * commands, and anything richer would be machinery they never use.
11
12
  */
13
+ import type { OriginRequestConfig } from "../../origin-request/index.js";
12
14
  /** Bumped whenever a change would make an older peer misread a message. */
13
15
  export declare const CONTROL_PROTOCOL_VERSION = 1;
14
16
  /** Filename inside the run directory. Unix socket, mode 0600. */
@@ -132,6 +134,9 @@ type ControlRequestBody = {
132
134
  } | {
133
135
  id: string;
134
136
  op: "files.validate";
137
+ } | {
138
+ id: string;
139
+ op: "config.runtime";
135
140
  } | {
136
141
  id: string;
137
142
  op: "browser.state";
@@ -151,6 +156,10 @@ type ControlRequestBody = {
151
156
  id: string;
152
157
  op: "browser.navigate";
153
158
  url: string;
159
+ /** Where to return: the load event (the default), or a lifecycle mark. */
160
+ wait?: NavigateWaitPoint;
161
+ /** The bound on the navigation and the wait together. */
162
+ waitMs?: number;
154
163
  } | {
155
164
  id: string;
156
165
  op: "browser.panel";
@@ -163,6 +172,10 @@ type ControlRequestBody = {
163
172
  width?: number;
164
173
  height?: number;
165
174
  dpr?: number;
175
+ /** Overrides the preset's user agent; sent without client hints. */
176
+ userAgent?: string;
177
+ /** Overrides the preset's touch. */
178
+ touch?: boolean;
166
179
  /**
167
180
  * Load the page again under the emulation. Default true: a document
168
181
  * already loaded was laid out, detected and served as the old device.
@@ -246,6 +259,8 @@ type ControlRequestBody = {
246
259
  bps?: number[];
247
260
  /** What to do once armed, so one call is the whole setup. */
248
261
  then?: DebugThen;
262
+ /** BP1 and BP3 pause where change detection compares, with `window.__skCD`. */
263
+ compared?: boolean;
249
264
  } | {
250
265
  id: string;
251
266
  op: "debug.disarm";
@@ -520,6 +535,8 @@ export interface DebugPause {
520
535
  columnNumber?: number;
521
536
  };
522
537
  state: DebugPausedState;
538
+ /** Under `arm --compared`: what `window.__skCD` holds, or why it is missing. */
539
+ compared?: Record<string, unknown>;
523
540
  at: string;
524
541
  }
525
542
  /**
@@ -582,6 +599,8 @@ export interface DebugStatusData {
582
599
  changeDetectionSkipped: string | null;
583
600
  }
584
601
  export interface DebugAwaitData extends DebugStatusData {
602
+ /** Never null here: an answer to "did it pause" says yes or no. */
603
+ paused: boolean;
585
604
  fired: boolean;
586
605
  timedOut: boolean;
587
606
  waitedMs: number;
@@ -641,6 +660,8 @@ export interface WatchData {
641
660
  console: WatchMessage[];
642
661
  exceptions: WatchMessage[];
643
662
  truncated: boolean;
663
+ /** What changed the request, stated only when something did. */
664
+ notes: string[];
644
665
  }
645
666
  /** One argument a recipe takes. */
646
667
  export interface InjectRecipeParam {
@@ -849,6 +870,14 @@ export type ControlResponse<T = unknown> = {
849
870
  * silent source of confident wrong conclusions.
850
871
  */
851
872
  export type Generation = number;
873
+ /**
874
+ * The runtime config the run loaded, for `sk diff` to follow the run.
875
+ * It holds basic-auth passwords, so it travels over this socket only.
876
+ */
877
+ export interface RuntimeConfigData {
878
+ /** Null when the run could not load one and uses the built-in defaults. */
879
+ config: OriginRequestConfig | null;
880
+ }
852
881
  export interface HelloData {
853
882
  /** Cross-checked against meta.json: a socket that answers is not proof. */
854
883
  pid: number;
@@ -904,8 +933,13 @@ export interface CacheGetData extends CacheEntry {
904
933
  export interface CachePrewarmEntry extends CacheEntry {
905
934
  bodyPath: string;
906
935
  bodySha: string;
907
- /** False when it was already cached and this call left it alone. */
936
+ /** True when this call fetched the origin and built it. */
908
937
  built: boolean;
938
+ /**
939
+ * True when it was cached before this call, by an earlier request, prewarm
940
+ * or config-change rebuild, and this call left it alone. Not a failure.
941
+ */
942
+ alreadyCached: boolean;
909
943
  }
910
944
  /** A variation that could not be built, and why. Never fails the whole call. */
911
945
  export interface CachePrewarmFailure {
@@ -1129,6 +1163,8 @@ export interface ServiceWorkerVersionInfo {
1129
1163
  /** installing, installed, activating, activated, redundant. */
1130
1164
  status: string;
1131
1165
  runningStatus: string;
1166
+ /** The CDP target of the running worker; absent while it is stopped. */
1167
+ targetId?: string;
1132
1168
  /** Set when the run decided this version was the deployed one taking over. */
1133
1169
  foreign?: boolean;
1134
1170
  }
@@ -1332,6 +1368,8 @@ export interface BrowserActionData {
1332
1368
  * did not name it could describe clearing a cache that is still there.
1333
1369
  */
1334
1370
  origin?: string;
1371
+ /** `browser navigate --wait <bpN>`: the point, and when it was reached or why not. */
1372
+ wait?: NavigateWaitData;
1335
1373
  }
1336
1374
  export declare const CONTROL_ERRORS: {
1337
1375
  /** The peer speaks a version this run does not. */
@@ -1,14 +1,3 @@
1
- /**
2
- * The seam between a live `sk onboarding` run and anything outside it.
3
- *
4
- * Both sides import this file. Same package, same build — so "keep these in
5
- * lockstep" is a compiler guarantee rather than a comment, which is the one
6
- * thing an IPC layer has to get right and the thing hand-kept copies never do.
7
- *
8
- * Deliberately small: newline-delimited JSON, one request and one answer per
9
- * line, an id to match them. The clients are short-lived `sk onboarding <tool>`
10
- * commands, and anything richer would be machinery they never use.
11
- */
12
1
  /** Bumped whenever a change would make an older peer misread a message. */
13
2
  export const CONTROL_PROTOCOL_VERSION = 1;
14
3
  /** Filename inside the run directory. Unix socket, mode 0600. */
@@ -1,4 +1,5 @@
1
1
  import { CliServiceInterface } from "../../cli/index.js";
2
+ import type { OriginRequestConfig } from "../../origin-request/index.js";
2
3
  import { FileListInterface } from "../../integration-api/index.js";
3
4
  import { Cache } from "../request-cache/cache.js";
4
5
  import { TodoCollector } from "../todo-collector.js";
@@ -55,6 +56,11 @@ export interface ControlServerCollaborators {
55
56
  rebuild?: (target: RebuildTarget) => Promise<RebuildStep[]>;
56
57
  /** Re-runs the config and mandatory-file validators against what is loaded. */
57
58
  validate?: () => ValidationProblem[];
59
+ /**
60
+ * The runtime config the run loaded, or undefined when it loaded none.
61
+ * Absent on a run that loads no runtime config at all, such as browse mode.
62
+ */
63
+ runtimeConfig?: () => OriginRequestConfig | undefined;
58
64
  }
59
65
  /**
60
66
  * Serves the control protocol on a unix socket inside the run directory.
@@ -174,6 +180,8 @@ export declare class ControlServer {
174
180
  private refreshCache;
175
181
  private listCacheErrors;
176
182
  private rebuildFiles;
183
+ /** Never logged: the config carries the origin's basic-auth passwords. */
184
+ private readRuntimeConfig;
177
185
  private validateFiles;
178
186
  /**
179
187
  * Why a url came back the way it did.
@@ -494,6 +494,15 @@ export class ControlServer {
494
494
  });
495
495
  return;
496
496
  }
497
+ case "config.runtime": {
498
+ this.reply(socket, {
499
+ id: request.id,
500
+ status: "ok",
501
+ generation: this.generation,
502
+ data: this.readRuntimeConfig(),
503
+ });
504
+ return;
505
+ }
497
506
  case "response.explain": {
498
507
  this.reply(socket, {
499
508
  id: request.id,
@@ -634,7 +643,7 @@ export class ControlServer {
634
643
  return;
635
644
  }
636
645
  case "debug.arm": {
637
- const data = await (await this.browser(request)).debug.arm(request.bps, request.then);
646
+ const data = await (await this.browser(request)).debug.arm(request.bps, request.then, request.compared);
638
647
  this.collaborators.cli.writeWarning(`an agent armed BP${data.armed.join(", BP")} on this run — the page will pause at the Speed Kit lifecycle marks until it is disarmed`);
639
648
  this.reply(socket, {
640
649
  id: request.id,
@@ -1084,6 +1093,7 @@ export class ControlServer {
1084
1093
  bodySha: entry.sha,
1085
1094
  bodyPath: entry.path,
1086
1095
  built: !before.has(key),
1096
+ alreadyCached: before.has(key),
1087
1097
  });
1088
1098
  }
1089
1099
  if (entries.length === 0 && failed.length > 0) {
@@ -1239,6 +1249,16 @@ export class ControlServer {
1239
1249
  reinstallsServiceWorker: steps.some((step) => step.target === "install"),
1240
1250
  };
1241
1251
  }
1252
+ /** Never logged: the config carries the origin's basic-auth passwords. */
1253
+ readRuntimeConfig() {
1254
+ const runtimeConfig = this.collaborators.runtimeConfig;
1255
+ if (!runtimeConfig) {
1256
+ throw new ControlHandlerError(CONTROL_ERRORS.handlerFailed, {
1257
+ message: "this run loads no runtime config",
1258
+ });
1259
+ }
1260
+ return { config: runtimeConfig() ?? null };
1261
+ }
1242
1262
  validateFiles() {
1243
1263
  const validate = this.collaborators.validate;
1244
1264
  if (!validate) {
@@ -1475,7 +1495,7 @@ export class ControlServer {
1475
1495
  return browser.showPanel();
1476
1496
  }
1477
1497
  default: {
1478
- return browser.navigate(request.url);
1498
+ return browser.navigate(request.url, request.wait, request.waitMs);
1479
1499
  }
1480
1500
  }
1481
1501
  }