lighthouse 9.6.7 → 10.0.0

package/types/internal/test.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license Copyright 2022 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+declare global {
+  var expect: import('expect').Expect;
+  type Mock<T, Y> = import('jest-mock').Mock<T, Y>;
+}
+
+declare module 'expect' {
+  interface Matchers<R extends void | Promise<void>, T={}> {
+    /**
+     * This ensures that a value matches the most recent snapshot with property matchers.
+     * Check out [the Snapshot Testing guide](http://facebook.github.io/jest/docs/snapshot-testing.html) for more information.
+     */
+    // tslint:disable-next-line: no-unnecessary-generics
+    toMatchSnapshot<U extends { [P in keyof T]: any }>(propertyMatchers: Partial<U>, snapshotName?: string): R;
+    /**
+     * This ensures that a value matches the most recent snapshot.
+     * Check out [the Snapshot Testing guide](http://facebook.github.io/jest/docs/snapshot-testing.html) for more information.
+     */
+    toMatchSnapshot(snapshotName?: string): R;
+    /**
+     * This ensures that a value matches the most recent snapshot with property matchers.
+     * Instead of writing the snapshot value to a .snap file, it will be written into the source code automatically.
+     * Check out [the Snapshot Testing guide](http://facebook.github.io/jest/docs/snapshot-testing.html) for more information.
+     */
+    // tslint:disable-next-line: no-unnecessary-generics
+    toMatchInlineSnapshot<U extends { [P in keyof T]: any }>(propertyMatchers: Partial<U>, snapshot?: string): R;
+
+    // The following are custom matchers defined in expect-setup.js
+
+    /**
+     * Jest's `toBeCloseTo()` exposed as an asymmetric matcher. This allows
+     * approximate numeric testing within matchers like `toMatchObject()`.
+     * The default for `numDigits` is 2.
+     */
+    toBeApproximately(expected: number, numDigits?: number): R;
+    /**
+     * Asserts that an inspectable promise created by makePromiseInspectable is currently resolved or rejected.
+     * This is useful for situations where we want to test that we are actually waiting for a particular event.
+     */
+    toBeDone: (failureMessage?: string) => R;
+    /**
+     * Asserts that an i18n string (using en-US) matches an expected pattern.
+     */
+    toBeDisplayString: (pattern: RegExp | string) => R;
+  }
+}
+
+export {};

package/types/lh.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license Copyright 2023 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {ArbitraryEqualityMap as ArbitraryEqualityMap_} from '../core/lib/arbitrary-equality-map.js';
+import * as Artifacts_ from './artifacts.js';
+import Audit_ from './audit.js';
+import Budget_ from './lhr/budget.js';
+import Config_ from './config.js';
+import {Protocol as _Crdp} from 'devtools-protocol/types/protocol.js';
+import {ProtocolMapping as _CrdpMappings} from 'devtools-protocol/types/protocol-mapping.js';
+import * as Externs from './externs.js';
+import Gatherer_ from './gatherer.js';
+import * as I18n from './lhr/i18n.js';
+import {LighthouseError as LighthouseError_} from '../core/lib/lh-error.js';
+import LHResult from './lhr/lhr.js';
+import FlowResult_ from './lhr/flow-result.js';
+import Protocol_ from './protocol.js';
+import * as Settings from './lhr/settings.js';
+import Treemap_ from './lhr/treemap.js';
+import UserFlow_ from './user-flow.js';
+import Puppeteer_ from './puppeteer.js';
+import Util_ from './utility-types.js';
+
+// Construct hierarchy of global types under the LH namespace.
+export type ArbitraryEqualityMap = ArbitraryEqualityMap_;
+export type NavigationRequestor = string | (() => Promise<void> | void);
+
+export import Util = Util_;
+
+export import Puppeteer = Puppeteer_;
+
+// artifacts.d.ts
+export import Artifacts = Artifacts_.Artifacts;
+export import BaseArtifacts = Artifacts_.BaseArtifacts;
+export import FRArtifacts = Artifacts_.FRArtifacts;
+export import FRBaseArtifacts = Artifacts_.FRBaseArtifacts;
+export import GathererArtifacts = Artifacts_.GathererArtifacts;
+export import DevtoolsLog = Artifacts_.DevtoolsLog;
+export import Trace = Artifacts_.Trace;
+export import TraceCpuProfile = Artifacts_.TraceCpuProfile;
+export import TraceEvent = Artifacts_.TraceEvent;
+
+export import Audit = Audit_;
+export import Budget = Budget_;
+export import Config = Config_;
+export import Crdp = _Crdp;
+export import CrdpEvents = _CrdpMappings.Events;
+export import CrdpCommands = _CrdpMappings.Commands;
+
+export import UserFlow = UserFlow_;
+
+// externs.d.ts
+export import Flags = Externs.Flags;
+export import CliFlags = Externs.CliFlags;
+export import RunnerResult = Externs.RunnerResult;
+export import DevToolsJsonTarget = Externs.DevToolsJsonTarget;
+
+export import Gatherer = Gatherer_;
+export import LighthouseError = LighthouseError_;
+export import Result = LHResult;
+export import FlowResult = FlowResult_;
+
+// lhr/i18n.d.ts
+export import IcuMessage = I18n.IcuMessage;
+export import RawIcu = I18n.RawIcu;
+export import FormattedIcu = I18n.FormattedIcu;
+
+export import Protocol = Protocol_;
+
+// lhr/settings.d.ts
+export import Locale = Settings.Locale;
+export import ThrottlingSettings = Settings.ThrottlingSettings;
+export import ScreenEmulationSettings = Settings.ScreenEmulationSettings;
+export import SharedFlagsSettings = Settings.SharedFlagsSettings;
+export import OutputMode = Settings.OutputMode;
+export import PrecomputedLanternData = Settings.PrecomputedLanternData;
+
+export import Treemap = Treemap_;

package/types/lh.js

@@ -0,0 +1,13 @@
+
+/**
+ * @license Copyright 2023 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+/**
+ * @fileoverview Typescript does not allow us to import an entire module via JSDOC so we need to import type modules via regular imports.
+ * This empty module will be served to any JS file that needs to import our global type module.
+ */
+
+export {};

package/types/lhr/audit-details.d.ts

@@ -4,8 +4,8 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {IcuMessage} from './i18n';
-import Treemap from './treemap';
+import {IcuMessage} from './i18n.js';
+import Treemap from './treemap.js';
 
 type Details =
   Details.CriticalRequestChain |
@@ -15,7 +15,6 @@ type Details =
   Details.List |
   Details.Opportunity |
   Details.Screenshot |
-  Details.FullPageScreenshot |
   Details.Table;
 
 // Details namespace.
@@ -67,7 +66,7 @@ declare module Details {
     type: 'opportunity';
     overallSavingsMs: number;
     overallSavingsBytes?: number;
-    headings: OpportunityColumnHeading[];
+    headings: TableColumnHeading[];
     items: OpportunityItem[];
     debugData?: DebugData;
   }
@@ -79,22 +78,6 @@ declare module Details {
     data: string;
   }
 
-  /**
-   * A screenshot of the entire page, including width and height information,
-   * and the locations of interesting nodes.
-   * Used by element screenshots renderer.
-   */
-  interface FullPageScreenshot {
-    type: 'full-page-screenshot';
-    screenshot: {
-      /** Base64 image data URL. */
-      data: string;
-      width: number;
-      height: number;
-    };
-    nodes: Record<string, Rect>;
-  }
-
   interface Rect {
     width: number;
     height: number;
@@ -141,9 +124,6 @@ declare module Details {
   /** Possible types of values found within table items. */
   type ItemValue = string | number | boolean | DebugData | NodeValue | SourceLocationValue | LinkValue | UrlValue | CodeValue | NumericValue | IcuMessage | TableSubItems;
 
-  // TODO: drop TableColumnHeading, rename OpportunityColumnHeading to TableColumnHeading and
-  // use that for all table-like audit details.
-
   interface TableColumnHeading {
     /**
      * The name of the property within items being described.
@@ -153,18 +133,18 @@ declare module Details {
      */
     key: string|null;
     /** Readable text label of the field. */
-    text: IcuMessage | string;
+    label: IcuMessage | string;
     /**
      * The data format of the column of values being described. Usually
      * those values will be primitives rendered as this type, but the values
      * could also be objects with their own type to override this field.
      */
-    itemType: ItemValueType;
+    valueType: ItemValueType;
     /**
      * Optional - defines an inner table of values that correspond to this column.
      * Key is required - if other properties are not provided, the value for the heading is used.
      */
-    subItemsHeading?: {key: string, itemType?: ItemValueType, displayUnit?: string, granularity?: number};
+    subItemsHeading?: {key: string, valueType?: ItemValueType, displayUnit?: string, granularity?: number};
 
     displayUnit?: string;
     granularity?: number;
@@ -176,33 +156,6 @@ declare module Details {
     [p: string]: undefined | ItemValue;
   }
 
-  interface OpportunityColumnHeading {
-    /**
-     * The name of the property within items being described.
-     * If null, subItemsHeading must be defined, and the first table row in this column for
-     * every item will be empty.
-     * See legacy-javascript for an example.
-     */
-    key: string|null;
-    /** Readable text label of the field. */
-    label: IcuMessage | string;
-    /**
-     * The data format of the column of values being described. Usually
-     * those values will be primitives rendered as this type, but the values
-     * could also be objects with their own type to override this field.
-     */
-    valueType: ItemValueType;
-    /**
-     * Optional - defines an inner table of values that correspond to this column.
-     * Key is required - if other properties are not provided, the value for the heading is used.
-     */
-    subItemsHeading?: {key: string, valueType?: ItemValueType, displayUnit?: string, granularity?: number};
-
-    // NOTE: not used by opportunity details, but used in the renderer until table/opportunity unification.
-    displayUnit?: string;
-    granularity?: number;
-  }
-
   /** A more specific table element used for `opportunity` tables. */
   interface OpportunityItem extends TableItem {
     url: string;

package/types/lhr/audit-result.d.ts

@@ -4,8 +4,8 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {FormattedIcu} from './i18n';
-import AuditDetails from './audit-details';
+import {FormattedIcu} from './i18n.js';
+import AuditDetails from './audit-details.js';
 
 interface ScoreDisplayModes {
   /** Scores of 0-1 (map to displayed scores of 0-100). */

package/types/lhr/flow-result.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license Copyright 2021 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import Result from './lhr.js';
+
+declare module FlowResult {
+  interface Step {
+    /** Lighthouse report for this flow step. */
+    lhr: Result;
+    /** Display name of this flow step. */
+    name: string;
+  }
+}
+
+/**
+ * The full output of a Lighthouse flow. Includes a series of Lighthouse runs.
+ */
+interface FlowResult {
+  /** Ordered list of flow steps, each corresponding to a navigation, timespan, or snapshot. */
+  steps: FlowResult.Step[];
+  /** Display name of this user flow. */
+  name: string;
+}
+
+export default FlowResult;

package/types/lhr/lhr.d.ts

@@ -4,8 +4,9 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {Result as AuditResult} from './audit-result';
-import {ConfigSettings} from './settings';
+import {Result as AuditResult} from './audit-result.js';
+import AuditDetails from './audit-details.js';
+import {ConfigSettings} from './settings.js';
 
 /**
  * The full output of a Lighthouse run.
@@ -13,10 +14,17 @@ import {ConfigSettings} from './settings';
 interface Result {
   /** Gather mode used to collect artifacts for this result. */
   gatherMode: Result.GatherMode;
-  /** The URL that was supplied to Lighthouse and initially navigated to. */
-  requestedUrl: string;
-  /** The post-redirects URL that Lighthouse loaded. */
-  finalUrl: string;
+  /** The URL that Lighthouse initially navigated to. Will be `undefined` in timespan/snapshot. */
+  requestedUrl?: string;
+  /** URL of the last document request during a Lighthouse navigation. Will be `undefined` in timespan/snapshot. */
+  mainDocumentUrl?: string;
+  /**
+   * For historical reasons, this will always be the same as `mainDocumentUrl`.
+   * @deprecated
+   */
+  finalUrl?: string;
+  /** The URL displayed on the page after Lighthouse finishes. */
+  finalDisplayedUrl: string;
   /** The ISO-8601 timestamp of when the results were generated. */
   fetchTime: string;
   /** The version of Lighthouse with which these results were generated. */
@@ -48,6 +56,10 @@ interface Result {
   };
   /** An array containing the result of all stack packs. */
   stackPacks?: Result.StackPack[];
+  /** All the origins encountered during this Lighthouse run, and information about what web property (aka "entity") they belong to. Won't be present for snapshot mode. */
+  entities?: Result.Entities;
+  /** Screenshot taken of the full page, with node rects referencing audit results. If there was an error with collection, this is null. If disabled via the disableFullPageScreenshot setting, this is undefined. */
+  fullPageScreenshot?: Result.FullPageScreenshot | null;
 }
 
 // Result namespace
@@ -59,6 +71,8 @@ declare module Result {
     networkUserAgent: string;
     /** The benchmark index number that indicates rough device class. */
     benchmarkIndex: number;
+    /** Many benchmark indexes. */
+    benchmarkIndexes?: number[];
     /** The version of libraries with which these results were generated. Ex: axe-core. */
     credits?: Record<string, string|undefined>,
   }
@@ -129,6 +143,39 @@ declare module Result {
     descriptions: Record<string, string>;
   }
 
+  interface FullPageScreenshot {
+    screenshot: {
+      /** Base64 image data URL. */
+      data: string;
+      width: number;
+      height: number;
+    };
+    nodes: Record<string, AuditDetails.Rect>;
+  }
+
+  /**
+   * Entity classification for the run, for resolving URLs/items to entities in report.
+   */
+  interface Entities extends Array<LhrEntity> {}
+
+  /**
+   * An entity that's either recognized by third-party-web or made up by Lighthouse.
+   */
+  interface LhrEntity {
+    /** Name of the entity. Maps to third-party-web unique name for recognized entities and a root domain name for the unrecognized. */
+    name: string;
+    /** Homepage URL for a recognized entity, if available in third-party-web. */
+    homepage?: string;
+    /** Category name that the entity belongs to, if available. */
+    category?: string;
+    /** Is this entity the first party? */
+    isFirstParty?: boolean;
+    /** Is this entity recognized by third-party-web? */
+    isUnrecognized?: boolean;
+    /** List of origin strings that belong to this entity found in network records. */
+    origins: Array<string>;
+  }
+
   /**
    * Info about an `LH.IcuMessage` value that was localized to a string when
    * included in the LHR. Value is either a

package/types/lhr/settings.d.ts

@@ -4,7 +4,7 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import Budget from './budget';
+import Budget from './budget.js';
 
 export type Locale = 'en-US'|'en'|'en-AU'|'en-GB'|'en-IE'|'en-SG'|'en-ZA'|'en-IN'|'ar-XB'|'ar'|'bg'|'ca'|'cs'|'da'|'de'|'el'|'en-XA'|'en-XL'|'es'|'es-419'|'es-AR'|'es-BO'|'es-BR'|'es-BZ'|'es-CL'|'es-CO'|'es-CR'|'es-CU'|'es-DO'|'es-EC'|'es-GT'|'es-HN'|'es-MX'|'es-NI'|'es-PA'|'es-PE'|'es-PR'|'es-PY'|'es-SV'|'es-US'|'es-UY'|'es-VE'|'fi'|'fil'|'fr'|'he'|'hi'|'hr'|'hu'|'gsw'|'id'|'in'|'it'|'iw'|'ja'|'ko'|'lt'|'lv'|'mo'|'nl'|'nb'|'no'|'pl'|'pt'|'pt-PT'|'ro'|'ru'|'sk'|'sl'|'sr'|'sr-Latn'|'sv'|'ta'|'te'|'th'|'tl'|'tr'|'uk'|'vi'|'zh'|'zh-HK'|'zh-TW';
 
@@ -71,6 +71,10 @@ export type ScreenEmulationSettings = {
   disableStorageReset?: boolean;
   /** Flag indicating that Lighthouse should pause after page load to wait for the user's permission to continue the audit. */
   debugNavigation?: boolean;
+  /** If set to true, will skip the initial navigation to about:blank. This option is ignored when using the legacy navigation runner. */
+  skipAboutBlank?: boolean;
+  /** If set to true, gatherers should avoid any behavior that may be destructive to the page state. (e.g. extra navigations, resizing the viewport) */
+  usePassiveGathering?: boolean;
 
   /** How Lighthouse should interpret this run in regards to scoring performance metrics and skipping mobile-only tests in desktop. Must be set even if throttling/emulation is being applied outside of Lighthouse. */
   formFactor?: 'mobile'|'desktop';
@@ -97,6 +101,19 @@ export type ScreenEmulationSettings = {
   precomputedLanternData?: PrecomputedLanternData | null;
   /** The budget.json object for LightWallet. */
   budgets?: Array<Budget> | null;
+
+  /** The number of milliseconds to wait after FCP until the page should be considered loaded. */
+  pauseAfterFcpMs?: number;
+  /** The number of milliseconds to wait after the load event until the page should be considered loaded. */
+  pauseAfterLoadMs?: number;
+  /** The number of milliseconds to wait between high priority network requests or 3 simulataneous requests before the page should be considered loaded. */
+  networkQuietThresholdMs?: number;
+  /** The number of milliseconds to wait between long tasks until the page should be considered loaded. */
+  cpuQuietThresholdMs?: number;
+  /** The URL to use for the "blank" neutral page in between navigations. Defaults to `about:blank`. */
+  blankPage?: string;
+  /** Disables collection of the full page screenshot, which can be rather large and possibly leave the page in an undesirable state. */
+  disableFullPageScreenshot?: boolean;
 }
 
 export interface ConfigSettings extends Required<SharedFlagsSettings> {

package/types/lhr/treemap.d.ts

@@ -4,14 +4,15 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {Result as AuditResult} from './audit-result';
-import {Locale} from './settings';
+import {Result as AuditResult} from './audit-result.js';
+import {Locale} from './settings.js';
 
 declare module Treemap {
   interface Options {
     lhr: {
-      requestedUrl: string;
-      finalUrl: string;
+      mainDocumentUrl?: string;
+      finalUrl?: string;
+      finalDisplayedUrl: string;
       audits: {
         'script-treemap-data': AuditResult;
       };

package/types/lhr/tsconfig.json

@@ -1,8 +1,6 @@
 {
   "extends": "../../tsconfig-base.json",
   "compilerOptions": {
-    "outDir": "../../.tmp/tsbuildinfo/types/lhr",
-
     // We only need the base JS definitions, no DOM, etc.
     "lib": ["esnext"],
     // Don't include any types from node_modules/.

package/types/protocol.d.ts

@@ -4,7 +4,29 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
+import {ProtocolMapping as CrdpMappings} from 'devtools-protocol/types/protocol-mapping.js';
+
+type CrdpEvents = CrdpMappings.Events;
+type CrdpCommands = CrdpMappings.Commands;
+
 declare module Protocol {
+  /**
+   * An intermediate type, used to create a record of all possible Crdp raw event
+   * messages, keyed on method. e.g. {
+   *   'Domain.method1Name': {method: 'Domain.method1Name', params: EventPayload1},
+   *   'Domain.method2Name': {method: 'Domain.method2Name', params: EventPayload2},
+   * }
+   */
+  type RawEventMessageRecord = {
+    [K in keyof CrdpEvents]: {
+      method: K,
+      // Drop [] for `undefined` (so a JS value is valid).
+      params: CrdpEvents[K] extends [] ? undefined: CrdpEvents[K][number]
+      // If sessionId is not set, it means the event was from the root target.
+      sessionId?: string;
+    };
+  }
+
   /**
    * Union of raw (over the wire) message format of all possible Crdp events,
    * of the form `{method: 'Domain.event', params: eventPayload}`.
@@ -16,7 +38,7 @@ declare module Protocol {
    */
   type RawCommandMessage = {
     id: number;
-    result: LH.CrdpCommands[keyof LH.CrdpCommands]['returnType'];
+    result: CrdpCommands[keyof CrdpCommands]['returnType'];
     error: {
       code: number,
       message: string
@@ -36,7 +58,7 @@ declare module Protocol {
    * serve as the arguments to event listener callbacks.
    * Inspired by work from https://github.com/bterlson/strict-event-emitter-types.
    */
-  type StrictEventEmitter<TEventRecord extends Record<keyof TEventRecord, any[]>> = {
+  type StrictEventEmitter<TEventRecord extends Record<keyof TEventRecord, unknown[]>> = {
     on<E extends keyof TEventRecord>(event: E, listener: (...args: TEventRecord[E]) => void): void;
 
     off<E extends keyof TEventRecord>(event: E, listener: Function): void;
@@ -50,24 +72,16 @@ declare module Protocol {
     once<E extends keyof TEventRecord>(event: E, listener: (...args: TEventRecord[E]) => void): void;
 
     emit<E extends keyof TEventRecord>(event: E, ...request: TEventRecord[E]): void;
+
+    listenerCount<E extends keyof TEventRecord>(event: E): number;
   }
-}
 
-/**
- * An intermediate type, used to create a record of all possible Crdp raw event
- * messages, keyed on method. e.g. {
- *   'Domain.method1Name': {method: 'Domain.method1Name', params: EventPayload1},
- *   'Domain.method2Name': {method: 'Domain.method2Name', params: EventPayload2},
- * }
- */
-type RawEventMessageRecord = {
-  [K in keyof LH.CrdpEvents]: {
-    method: K,
-    // Drop [] for `undefined` (so a JS value is valid).
-    params: LH.CrdpEvents[K] extends [] ? undefined: LH.CrdpEvents[K][number]
-    // If sessionId is not set, it means the event was from the root target.
-    sessionId?: string;
-  };
+  /**
+   * A constructable StrictEventEmitter.
+   */
+  interface StrictEventEmitterClass<TEventRecord extends Record<keyof TEventRecord, unknown[]>> {
+    new(): StrictEventEmitter<TEventRecord>;
+  }
 }
 
 export default Protocol;

package/types/puppeteer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright 2022 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import * as puppeteerCore from 'puppeteer-core';
+
+/**
+ * @fileoverview Lighthouse should be compatible with puppeteer and puppeteer-core even though the types can be slightly different between the two packages.
+ * Anytime we want to use a Puppeteer type within Lighthouse, we should pull the union type from here rather than one of the packages directly.
+ */
+
+type IfNotAny<T> = [T & 0] extends [1] ? never : T;
+
+declare module Puppeteer {
+  // @ts-ignore Puppeteer is an optional dependency. `IfNotAny` will handle the `any` type if it's not installed.
+  export type Browser = puppeteerCore.Browser | IfNotAny<import('puppeteer').Browser>;
+  // @ts-ignore Puppeteer is an optional dependency. `IfNotAny` will handle the `any` type if it's not installed.
+  export type Page = puppeteerCore.Page | IfNotAny<import('puppeteer').Page>;
+  // @ts-ignore Puppeteer is an optional dependency. `IfNotAny` will handle the `any` type if it's not installed.
+  export type CDPSession = puppeteerCore.CDPSession | IfNotAny<import('puppeteer').CDPSession>;
+  // @ts-ignore Puppeteer is an optional dependency. `IfNotAny` will handle the `any` type if it's not installed.
+  export type Connection = puppeteerCore.Connection | IfNotAny<import('puppeteer').Connection>;
+}
+
+export default Puppeteer;

package/types/user-flow.d.ts

@@ -1,4 +1,13 @@
-import {UserFlow as UserFlow_} from '../lighthouse-core/fraggle-rock/user-flow';
+/**
+ * @license Copyright 2022 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {UserFlow as UserFlow_} from '../core/user-flow.js';
+import Config from './config.js';
+import {Flags} from './externs.js';
+import {Artifacts} from './artifacts.js';
 
 declare module UserFlow {
   export interface FlowArtifacts {
@@ -6,14 +15,26 @@ declare module UserFlow {
     name?: string;
   }
 
+  export interface Options {
+    /** Config to use for each flow step. */
+    config?: Config;
+    /** Base flags to use for each flow step. Step specific flags will override these flags. */
+    flags?: Flags;
+    /** Display name for this user flow. */
+    name?: string;
+  }
+
+  export interface StepFlags extends Flags {
+    /** Display name for this flow step. */
+    name?: string;
+  }
+
   export interface GatherStep {
-    artifacts: LH.Artifacts;
-    name: string;
-    config?: LH.Config.Json;
-    configContext?: LH.Config.FRContext;
+    artifacts: Artifacts;
+    flags?: StepFlags;
   }
 }
 
-type UserFlow = typeof UserFlow_;
+type UserFlow = InstanceType<typeof UserFlow_>;
 
 export default UserFlow;