devtools-tracing 1.0.0

package/lib/front_end/core/sdk/SDKModel.ts

@@ -0,0 +1,65 @@
+// Copyright 2019 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Common from '../common/common.js';
+
+import type {Target} from './Target.js';
+
+export interface RegistrationInfo {
+  capabilities: number;
+  autostart: boolean;
+  early?: boolean;
+}
+
+const registeredModels = new Map<new (arg1: Target) => SDKModel, RegistrationInfo>();
+
+// TODO(crbug.com/1228674) Remove defaults for generic type parameters once
+//                         all event emitters and sinks have been migrated.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class SDKModel<Events = any> extends Common.ObjectWrapper.ObjectWrapper<Events> {
+  readonly #target: Target;
+
+  constructor(target: Target) {
+    super();
+    this.#target = target;
+  }
+
+  target(): Target {
+    return this.#target;
+  }
+
+  /**
+   * Override this method to perform tasks that are required to suspend the
+   * model and that still need other models in an unsuspended state.
+   */
+  async preSuspendModel(_reason?: string): Promise<void> {
+  }
+
+  async suspendModel(_reason?: string): Promise<void> {
+  }
+
+  async resumeModel(): Promise<void> {
+  }
+
+  /**
+   * Override this method to perform tasks that are required to after resuming
+   * the model and that require all models already in an unsuspended state.
+   */
+  async postResumeModel(): Promise<void> {
+  }
+
+  dispose(): void {
+  }
+
+  static register(modelClass: new(arg1: Target) => SDKModel, registrationInfo: RegistrationInfo): void {
+    if (registrationInfo.early && !registrationInfo.autostart) {
+      throw new Error(`Error registering model ${modelClass.name}: early models must be autostarted.`);
+    }
+    registeredModels.set(modelClass, registrationInfo);
+  }
+
+  static get registeredModels(): typeof registeredModels {
+    return registeredModels;
+  }
+}

package/lib/front_end/core/sdk/ScopeTreeCache.ts

@@ -0,0 +1,45 @@
+// Copyright 2023 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Formatter from '../../models/formatter/formatter.js';
+import * as TextUtils from '../../models/text_utils/text_utils.js';
+
+import type {Script} from './Script.js';
+
+type ScopeTreeNode = Formatter.FormatterWorkerPool.ScopeTreeNode;
+type Text = TextUtils.Text.Text;
+
+/** If a script failed to parse, we stash null in order to prevent unnecessary re-parsing */
+const scopeTrees = new WeakMap<Script, Promise<{scopeTree: ScopeTreeNode, text: Text}|null>>();
+
+/**
+ * Computes and caches the scope tree for `script`.
+ *
+ * We use {@link Script} as a key to uniquely identify scripts.
+ * {@link Script} boils down to "target" + "script ID". This
+ * duplicates work in case of identical script running on multiple targets
+ * (e.g. workers).
+ *
+ * We also return a {@link TextUtils.Text.Text} instance. The scope tree uses offsets
+ * and the text allows conversion from/to line/column numbers.
+ */
+export function scopeTreeForScript(script: Script): Promise<{scopeTree: ScopeTreeNode, text: Text}|null> {
+  let promise = scopeTrees.get(script);
+  if (promise === undefined) {
+    promise = script.requestContentData().then(content => {
+      if (TextUtils.ContentData.ContentData.isError(content)) {
+        return null;
+      }
+
+      const sourceType = script.isModule ? 'module' : 'script';
+      return Formatter.FormatterWorkerPool.formatterWorkerPool()
+          .javaScriptScopeTree(content.text, sourceType)
+          .then(scopeTree => scopeTree ? ({scopeTree, text: content.textObj}) : null)
+          .catch(() => null);
+    });
+    scopeTrees.set(script, promise);
+  }
+  // We intentionally return `null` here if the script already failed to parse once.
+  return promise;
+}

package/lib/front_end/core/sdk/ScreenCaptureModel.ts

@@ -0,0 +1,255 @@
+// Copyright 2017 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type * as ProtocolProxyApi from '../../generated/protocol-proxy-api.js';
+import type * as Protocol from '../../generated/protocol.js';
+
+import {OverlayModel} from './OverlayModel.js';
+import {SDKModel} from './SDKModel.js';
+import {Capability, type Target} from './Target.js';
+
+export const enum ScreenshotMode {
+  FROM_VIEWPORT = 'fromViewport',
+  FROM_CLIP = 'fromClip',
+  FULLPAGE = 'fullpage',
+}
+
+/**
+ * This structure holds a specific `startScreencast` request's parameters
+ * and its callbacks so that they can be re-started if needed.
+ **/
+interface ScreencastOperation {
+  id: number;
+  request: {
+    format: Protocol.Page.StartScreencastRequestFormat,
+    quality: number,
+    maxWidth: number|undefined,
+    maxHeight: number|undefined,
+    everyNthFrame: number|undefined,
+  };
+  callbacks: {
+    onScreencastFrame: ScreencastFrameCallback,
+    onScreencastVisibilityChanged: ScreencastVisibilityChangedCallback,
+  };
+}
+
+type ScreencastFrameCallback = ((arg0: Protocol.binary, arg1: Protocol.Page.ScreencastFrameMetadata) => void);
+type ScreencastVisibilityChangedCallback = ((arg0: boolean) => void);
+
+/**
+ * Manages concurrent screencast requests by queuing and prioritizing.
+ *
+ * When startScreencast is invoked:
+ * - If a screencast is currently active, the existing screencast's parameters and callbacks are
+ * saved in the #screencastOperations array.
+ * - The active screencast is then stopped.
+ * - A new screencast is initiated using the parameters and callbacks from the current startScreencast call.
+ *
+ * When stopScreencast is invoked:
+ * - The currently active screencast is stopped.
+ * - The #screencastOperations is checked for interrupted screencast operations.
+ * - If any operations are found, the latest one is started
+ * using its saved parameters and callbacks.
+ *
+ * This ensures that:
+ * - Only one screencast is active at a time.
+ * - Interrupted screencasts are resumed after the current screencast is stopped.
+ * This ensures animation previews, which use screencasting, don't disrupt ongoing remote debugging sessions. Without this mechanism, stopping a preview screencast would terminate the debugging screencast, freezing the ScreencastView.
+ **/
+export class ScreenCaptureModel extends SDKModel<void> implements ProtocolProxyApi.PageDispatcher {
+  readonly #agent: ProtocolProxyApi.PageApi;
+  #nextScreencastOperationId = 1;
+  #screencastOperations: ScreencastOperation[] = [];
+  constructor(target: Target) {
+    super(target);
+    this.#agent = target.pageAgent();
+    target.registerPageDispatcher(this);
+  }
+
+  async startScreencast(
+      format: Protocol.Page.StartScreencastRequestFormat, quality: number, maxWidth: number|undefined,
+      maxHeight: number|undefined, everyNthFrame: number|undefined, onFrame: ScreencastFrameCallback,
+      onVisibilityChanged: ScreencastVisibilityChangedCallback): Promise<number> {
+    const currentRequest = this.#screencastOperations.at(-1);
+    if (currentRequest) {
+      // If there already is a screencast operation in progress, we need to stop it now and handle the
+      // incoming request. Once that request is stopped, we'll return back to handling the stopped operation.
+      await this.#agent.invoke_stopScreencast();
+    }
+
+    const operation = {
+      id: this.#nextScreencastOperationId++,
+      request: {
+        format,
+        quality,
+        maxWidth,
+        maxHeight,
+        everyNthFrame,
+      },
+      callbacks: {
+        onScreencastFrame: onFrame,
+        onScreencastVisibilityChanged: onVisibilityChanged,
+      }
+    };
+    this.#screencastOperations.push(operation);
+    void this.#agent.invoke_startScreencast({format, quality, maxWidth, maxHeight, everyNthFrame});
+
+    return operation.id;
+  }
+
+  stopScreencast(id: number): void {
+    const operationToStop = this.#screencastOperations.pop();
+    if (!operationToStop) {
+      throw new Error('There is no screencast operation to stop.');
+    }
+
+    if (operationToStop.id !== id) {
+      throw new Error('Trying to stop a screencast operation that is not being served right now.');
+    }
+    void this.#agent.invoke_stopScreencast();
+
+    // The latest operation is concluded, let's return back to the previous request now, if it exists.
+    const nextOperation = this.#screencastOperations.at(-1);
+    if (nextOperation) {
+      void this.#agent.invoke_startScreencast({
+        format: nextOperation.request.format,
+        quality: nextOperation.request.quality,
+        maxWidth: nextOperation.request.maxWidth,
+        maxHeight: nextOperation.request.maxHeight,
+        everyNthFrame: nextOperation.request.everyNthFrame,
+      });
+    }
+  }
+
+  async captureScreenshot(
+      format: Protocol.Page.CaptureScreenshotRequestFormat, quality: number, mode: ScreenshotMode,
+      clip?: Protocol.Page.Viewport): Promise<string|null> {
+    const properties: Protocol.Page.CaptureScreenshotRequest = {
+      format,
+      quality,
+      fromSurface: true,
+    };
+    switch (mode) {
+      case ScreenshotMode.FROM_CLIP:
+        properties.captureBeyondViewport = true;
+        properties.clip = clip;
+        break;
+      case ScreenshotMode.FULLPAGE:
+        properties.captureBeyondViewport = true;
+        break;
+      case ScreenshotMode.FROM_VIEWPORT:
+        properties.captureBeyondViewport = false;
+        break;
+      default:
+        throw new Error('Unexpected or unspecified screnshotMode');
+    }
+
+    await OverlayModel.muteHighlight();
+    const result = await this.#agent.invoke_captureScreenshot(properties);
+    await OverlayModel.unmuteHighlight();
+    return result.data;
+  }
+
+  screencastFrame({data, metadata, sessionId}: Protocol.Page.ScreencastFrameEvent): void {
+    void this.#agent.invoke_screencastFrameAck({sessionId});
+
+    const currentRequest = this.#screencastOperations.at(-1);
+    if (currentRequest) {
+      currentRequest.callbacks.onScreencastFrame.call(null, data, metadata);
+    }
+  }
+
+  screencastVisibilityChanged({visible}: Protocol.Page.ScreencastVisibilityChangedEvent): void {
+    const currentRequest = this.#screencastOperations.at(-1);
+    if (currentRequest) {
+      currentRequest.callbacks.onScreencastVisibilityChanged.call(null, visible);
+    }
+  }
+
+  backForwardCacheNotUsed(_params: Protocol.Page.BackForwardCacheNotUsedEvent): void {
+  }
+
+  domContentEventFired(_params: Protocol.Page.DomContentEventFiredEvent): void {
+  }
+
+  loadEventFired(_params: Protocol.Page.LoadEventFiredEvent): void {
+  }
+
+  lifecycleEvent(_params: Protocol.Page.LifecycleEventEvent): void {
+  }
+
+  navigatedWithinDocument(_params: Protocol.Page.NavigatedWithinDocumentEvent): void {
+  }
+
+  frameAttached(_params: Protocol.Page.FrameAttachedEvent): void {
+  }
+
+  frameNavigated(_params: Protocol.Page.FrameNavigatedEvent): void {
+  }
+
+  documentOpened(_params: Protocol.Page.DocumentOpenedEvent): void {
+  }
+
+  frameDetached(_params: Protocol.Page.FrameDetachedEvent): void {
+  }
+
+  frameStartedLoading(_params: Protocol.Page.FrameStartedLoadingEvent): void {
+  }
+
+  frameStoppedLoading(_params: Protocol.Page.FrameStoppedLoadingEvent): void {
+  }
+
+  frameRequestedNavigation(_params: Protocol.Page.FrameRequestedNavigationEvent): void {
+  }
+
+  frameStartedNavigating(_params: Protocol.Page.FrameStartedNavigatingEvent): void {
+  }
+
+  frameSubtreeWillBeDetached(_params: Protocol.Page.FrameSubtreeWillBeDetachedEvent): void {
+  }
+
+  frameScheduledNavigation(_params: Protocol.Page.FrameScheduledNavigationEvent): void {
+  }
+
+  frameClearedScheduledNavigation(_params: Protocol.Page.FrameClearedScheduledNavigationEvent): void {
+  }
+
+  frameResized(): void {
+  }
+
+  javascriptDialogOpening(_params: Protocol.Page.JavascriptDialogOpeningEvent): void {
+  }
+
+  javascriptDialogClosed(_params: Protocol.Page.JavascriptDialogClosedEvent): void {
+  }
+
+  interstitialShown(): void {
+  }
+
+  interstitialHidden(): void {
+  }
+
+  windowOpen(_params: Protocol.Page.WindowOpenEvent): void {
+  }
+
+  fileChooserOpened(_params: Protocol.Page.FileChooserOpenedEvent): void {
+  }
+
+  compilationCacheProduced(_params: Protocol.Page.CompilationCacheProducedEvent): void {
+  }
+
+  downloadWillBegin(_params: Protocol.Page.DownloadWillBeginEvent): void {
+  }
+
+  downloadProgress(): void {
+  }
+
+  prefetchStatusUpdated(_params: Protocol.Preload.PrefetchStatusUpdatedEvent): void {
+  }
+
+  prerenderStatusUpdated(_params: Protocol.Preload.PrerenderStatusUpdatedEvent): void {
+  }
+}
+
+SDKModel.register(ScreenCaptureModel, {capabilities: Capability.SCREEN_CAPTURE, autostart: false});