@paulirish/trace_engine 0.0.67-beta.0 → 0.0.67-beta.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 (147) hide show
  1. package/README.md +60 -22
  2. package/core/common/ParsedURL.d.ts +8 -0
  3. package/core/common/Settings.d.ts +2 -0
  4. package/core/host/Platform.d.ts +5 -0
  5. package/core/host/UserMetricsEnums.d.ts +8 -3
  6. package/core/platform/StringUtilities.d.ts +21 -0
  7. package/core/root/ExperimentNames.d.ts +2 -1
  8. package/core/root/Runtime.d.ts +4 -2
  9. package/core/sdk/CSSModel.d.ts +5 -0
  10. package/core/sdk/CSSPropertyParser.d.ts +0 -5
  11. package/core/sdk/DOMModel.d.ts +8 -4
  12. package/core/sdk/DebuggerModel.d.ts +37 -4
  13. package/core/sdk/NetworkRequest.d.ts +30 -2
  14. package/core/sdk/ResourceTreeModel.d.ts +3 -1
  15. package/core/sdk/RuntimeModel.d.ts +1 -0
  16. package/core/sdk/SDKSettings.d.ts +1 -0
  17. package/core/sdk/SourceMap.d.ts +20 -6
  18. package/core/sdk/SourceMapFunctionRanges.d.ts +3 -6
  19. package/core/sdk/SourceMapScopesInfo.d.ts +98 -23
  20. package/core/text_utils/Markdown.d.ts +13 -0
  21. package/core/text_utils/text_utils.d.ts +2 -1
  22. package/entrypoints/formatter_actions/formatter_actions.d.ts +17 -0
  23. package/generated/protocol-mapping.d.ts +64 -9
  24. package/generated/protocol-proxy-api.d.ts +58 -7
  25. package/generated/protocol.d.ts +93 -30
  26. package/index.d.ts +2 -0
  27. package/locales/af.json +129 -126
  28. package/locales/am.json +128 -125
  29. package/locales/ar.json +130 -127
  30. package/locales/as.json +130 -127
  31. package/locales/az.json +130 -127
  32. package/locales/be.json +128 -125
  33. package/locales/bg.json +130 -127
  34. package/locales/bn.json +130 -127
  35. package/locales/bs.json +130 -127
  36. package/locales/ca.json +130 -127
  37. package/locales/cs.json +128 -125
  38. package/locales/cy.json +130 -127
  39. package/locales/da.json +129 -126
  40. package/locales/de.json +130 -127
  41. package/locales/el.json +130 -127
  42. package/locales/en-GB.json +130 -127
  43. package/locales/en-US.json +1058 -0
  44. package/locales/es-419.json +129 -126
  45. package/locales/es.json +130 -127
  46. package/locales/et.json +95 -92
  47. package/locales/eu.json +130 -127
  48. package/locales/fa.json +130 -127
  49. package/locales/fi.json +129 -126
  50. package/locales/fil.json +130 -127
  51. package/locales/fr-CA.json +130 -127
  52. package/locales/fr.json +130 -127
  53. package/locales/gl.json +130 -127
  54. package/locales/gu.json +130 -127
  55. package/locales/he.json +130 -127
  56. package/locales/hi.json +130 -127
  57. package/locales/hr.json +128 -125
  58. package/locales/hu.json +90 -87
  59. package/locales/hy.json +127 -124
  60. package/locales/id.json +130 -127
  61. package/locales/is.json +129 -126
  62. package/locales/it.json +130 -127
  63. package/locales/ja.json +130 -127
  64. package/locales/ka.json +129 -126
  65. package/locales/kk.json +38 -35
  66. package/locales/km.json +130 -127
  67. package/locales/kn.json +130 -127
  68. package/locales/ko.json +22 -19
  69. package/locales/ky.json +130 -127
  70. package/locales/lo.json +130 -127
  71. package/locales/lt.json +130 -127
  72. package/locales/lv.json +66 -63
  73. package/locales/mk.json +130 -127
  74. package/locales/ml.json +129 -126
  75. package/locales/mn.json +129 -126
  76. package/locales/mr.json +130 -127
  77. package/locales/ms.json +130 -127
  78. package/locales/my.json +130 -127
  79. package/locales/ne.json +128 -125
  80. package/locales/nl.json +129 -126
  81. package/locales/no.json +130 -127
  82. package/locales/or.json +130 -127
  83. package/locales/pa.json +130 -127
  84. package/locales/pl.json +130 -127
  85. package/locales/pt-PT.json +129 -126
  86. package/locales/pt.json +130 -127
  87. package/locales/ro.json +129 -126
  88. package/locales/ru.json +50 -47
  89. package/locales/si.json +130 -127
  90. package/locales/sk.json +130 -127
  91. package/locales/sl.json +130 -127
  92. package/locales/sq.json +129 -126
  93. package/locales/sr-Latn.json +130 -127
  94. package/locales/sr.json +130 -127
  95. package/locales/sv.json +130 -127
  96. package/locales/sw.json +130 -127
  97. package/locales/ta.json +129 -126
  98. package/locales/te.json +130 -127
  99. package/locales/th.json +92 -89
  100. package/locales/tr.json +129 -126
  101. package/locales/uk.json +128 -125
  102. package/locales/ur.json +130 -127
  103. package/locales/uz.json +126 -123
  104. package/locales/vi.json +130 -127
  105. package/locales/zh-HK.json +130 -127
  106. package/locales/zh-TW.json +130 -127
  107. package/locales/zh.json +130 -127
  108. package/locales/zu.json +129 -126
  109. package/models/emulation/DeviceModeModel.d.ts +1 -0
  110. package/models/formatter/FormatterWorkerPool.d.ts +2 -2
  111. package/models/formatter/ScriptFormatter.d.ts +2 -2
  112. package/models/trace/extras/StackTraceForEvent.d.ts +1 -1
  113. package/models/trace/handlers/AnimationFramesHandler.d.ts +1 -1
  114. package/models/trace/handlers/AsyncJSCallsHandler.d.ts +2 -2
  115. package/models/trace/handlers/ImagePaintingHandler.d.ts +2 -2
  116. package/models/trace/handlers/InitiatorsHandler.d.ts +2 -2
  117. package/models/trace/handlers/LayerTreeHandler.d.ts +1 -1
  118. package/models/trace/handlers/NetworkRequestsHandler.d.ts +1 -1
  119. package/models/trace/handlers/PageLoadMetricsHandler.d.ts +1 -1
  120. package/models/trace/handlers/ScriptsHandler.d.ts +1 -1
  121. package/models/trace/handlers/WarningsHandler.d.ts +1 -1
  122. package/models/trace/helpers/SamplesIntegrator.d.ts +3 -1
  123. package/models/trace/helpers/Trace.d.ts +2 -0
  124. package/models/trace/insights/CLSCulprits.d.ts +1 -1
  125. package/models/trace/insights/DuplicatedJavaScript.d.ts +1 -1
  126. package/models/trace/insights/ImageDelivery.d.ts +1 -0
  127. package/models/trace/lantern/core/NetworkAnalyzer.d.ts +1 -0
  128. package/models/trace/lantern/graph/CPUNode.d.ts +4 -2
  129. package/models/trace/lantern/simulation/TCPConnection.d.ts +4 -4
  130. package/models/trace/lantern/types/Lantern.d.ts +15 -0
  131. package/models/trace/trace.js +21 -4
  132. package/models/trace/types/Overlays.d.ts +4 -3
  133. package/models/trace/types/TraceEvents.d.ts +184 -124
  134. package/package.json +14 -4
  135. package/third_party/marked/marked.d.ts +2 -0
  136. package/third_party/marked/package/lib/marked.esm.d.ts +760 -0
  137. package/third_party/source-map-scopes-codec/package/src/builder/builder.d.ts +4 -1
  138. package/third_party/source-map-scopes-codec/package/src/builder/safe_builder.d.ts +3 -1
  139. package/third_party/source-map-scopes-codec/package/src/codec.d.ts +6 -5
  140. package/third_party/source-map-scopes-codec/package/src/decode/decode.d.ts +2 -0
  141. package/third_party/source-map-scopes-codec/package/src/encode/encoder.d.ts +4 -1
  142. package/third_party/source-map-scopes-codec/package/src/scopes.d.ts +4 -3
  143. package/third_party/source-map-scopes-codec/package/src/vlq.d.ts +1 -1
  144. package/models/trace/lantern/lantern.js +0 -8
  145. package/models/trace/types/Timing.js +0 -8
  146. package/models/trace/types/TraceEvents.js +0 -189
  147. package/models/trace/types/types.js +0 -8
package/README.md CHANGED
@@ -8,46 +8,84 @@ But the breakages should be obvious exceptions or type failures.
8
8
  ## API quickstart
9
9
 
10
10
  ```js
11
- import * as TraceModel from '@paulirish/trace_engine';
11
+ import * as Trace from '@paulirish/trace_engine';
12
12
 
13
- const engine = TraceModel.Processor.TraceProcessor.createWithAllHandlers();
13
+ const model = Trace.TraceModel.Model.createWithAllHandlers();
14
+ await model.parse(traceEvents);
14
15
 
15
- await engine.parse(traceEvents);
16
- console.log(engine.data) // TraceParseData
16
+ const parsedTrace = model.parsedTrace();
17
+ console.log(parsedTrace.data); // Handlers data (Meta, Screenshots, LayoutShifts, etc.)
18
+ console.log(parsedTrace.insights); // Insight models
17
19
  ```
18
20
 
19
- See the included `analyze-trace.mjs` for a runnable invocation.
21
+ See the included `analyze-trace.mjs` for a runnable CLI script.
20
22
 
21
- ### Types & Submodule Imports
23
+ ### Imports & TypeScript Types
22
24
 
23
- All `models/trace/**` submodules exported by `trace.ts` (including `models/trace/types/TraceEvents.js`, `models/trace/lantern/lantern.js`, `models/trace/insights/*.js`, and `models/trace/extras/ThirdParties.js`) have both `.d.ts` declarations and runtime `.js` ESM proxies:
25
+ All runtime values and types are imported directly from the root package entrypoint (`@paulirish/trace_engine`):
24
26
 
25
- @type {import('@paulirish/trace_engine').Types.Events.Event[]}
26
- @type {import('@paulirish/trace_engine').Handlers.Types.HandlerData}
27
+ ```js
28
+ import * as TraceEngine from '@paulirish/trace_engine';
29
+ // Or via named imports:
30
+ import {Types, Lantern, Insights, Processor, Handlers, Helpers, Extras} from '@paulirish/trace_engine';
31
+
32
+ // Enums & Event Types
33
+ const {Phase, Name} = Types.Events;
34
+ const {Milli, Micro} = Types.Timing;
35
+
36
+ // Lantern
37
+ const {Graph, Simulation} = Lantern;
38
+
39
+ // Insights
40
+ const {UIStrings} = Insights.Models.ImageDelivery;
41
+ ```
42
+
43
+ TypeScript declarations (`.d.ts`) mirror DevTools' own types through the root namespace:
44
+
45
+ ```ts
46
+ import type {Types, Insights, Lantern} from '@paulirish/trace_engine';
47
+
48
+ type TraceEvent = Types.Events.Event;
49
+ type SyntheticNetworkRequest = Types.Events.SyntheticNetworkRequest;
50
+ type InsightSet = Insights.Types.InsightSet;
51
+ ```
52
+
53
+ #### Migrating from Legacy Deep Subpaths
54
+
55
+ Older versions of `@paulirish/trace_engine` exposed individual files inside `models/trace/...`. These deep paths are deprecated in favor of the canonical root exports:
56
+
57
+ | Old Deep Path | Canonical Import (`@paulirish/trace_engine`) |
58
+ | :--- | :--- |
59
+ | `.../models/trace/lantern/lantern.js` | `import { Lantern } from '@paulirish/trace_engine';` |
60
+ | `.../models/trace/types/types.js` | `import { Types } from '@paulirish/trace_engine';` |
61
+ | `.../models/trace/types/TraceEvents.js` | `import { Types } from '@paulirish/trace_engine'; const { Events } = Types;` |
62
+ | `.../models/trace/types/Timing.js` | `import { Types } from '@paulirish/trace_engine'; const { Timing } = Types;` |
63
+ | `.../models/trace/insights/<Insight>.js` | `import { Insights } from '@paulirish/trace_engine'; const { UIStrings } = Insights.Models.<Insight>;` |
64
+ | `.../models/trace/extras/ThirdParties.js` | `import { Extras } from '@paulirish/trace_engine'; const { ThirdParties } = Extras;` |
27
65
 
28
66
  ## Maintainer cheatsheet
29
67
 
30
- `@paulirish/trace_engine` wraps the pre-bundled `DevTools.TraceEngine` shipped in `chrome-devtools-mcp` and emits the exact matching `.d.ts` declarations from `devtools-frontend` (using the commit SHA recorded in `chrome-devtools-mcp/build/src/third_party/bundled-packages.json`).
68
+ `@paulirish/trace_engine` wraps the pre-bundled `DevTools.TraceEngine` shipped in `chrome-devtools-mcp` and emits matching `.d.ts` declarations and locales from `devtools-frontend` (using the commit SHA recorded in `chrome-devtools-mcp/build/src/third_party/bundled-packages.json`).
31
69
 
32
- - `scripts/build.ts` automatically pins the exact `chrome-devtools-mcp` version in `package.json` so runtime code and `.d.ts` declarations never drift.
33
- - Exported `const enum`s under `models/trace` (such as `Types.Events.Name`, `Types.Events.Phase`, `Handlers.Threads.ThreadType`, etc.) are materialized as runtime enum objects so plain JS and `--experimental-strip-types` consumers can reference them at runtime. (`const enum`s in other internal DevTools modules remain type-only.)
34
- - Importing `@paulirish/trace_engine` initializes the `DevToolsLocale` singleton to `'en-US'` if it has not already been initialized in the current process.
70
+ - `models/trace/trace.js` is a static runtime wrapper that initializes `DevToolsLocale` ('en-US') and intercepts `LocalizedStringSet.prototype.getLocalizedString` so calls from `models/trace/` return `{i18nId, values, formattedDefault}` for Lighthouse's multi-locale pipeline.
71
+ - Exported `const enum`s under `models/trace` (such as `Types.Events.Phase`, `Handlers.Threads.ThreadType`, etc.) are materialized at runtime in `models/trace/trace.js` until [CL 8539952](https://chromium-review.git.corp.google.com/c/devtools/devtools-frontend/+/8539952) lands upstream in `devtools-frontend`.
72
+ - `scripts/build.ts` extracts `front_end/` via `git archive` from the local `devtools-frontend` checkout at the exact SHA and runs `tsc --emitDeclarationOnly` in ~2 seconds.
35
73
 
36
74
  ```sh
37
75
  cd $HOME/code/trace_engine
38
76
 
39
- # Update chrome-devtools-mcp to latest, regenerate .d.ts & wrapper, and run tests + type-check
40
- npm i chrome-devtools-mcp@latest
77
+ # 1. Update chrome-devtools-mcp to latest (exact version)
78
+ npm i chrome-devtools-mcp@latest --save-exact
79
+
80
+ # 2. Re-emit .d.ts declarations and locales (~2s)
41
81
  npm run build
42
- npm test
43
82
 
44
- # Bump version and dry-run publish
45
- npm version patch
46
- npm publish --access public --dry-run
83
+ # 3. Run test suite and type check
84
+ npm test
47
85
 
48
- # Auth and publish
49
- npm whoami --registry https://registry.npmjs.org/ || npm login --registry https://registry.npmjs.org/
50
- npm publish --access public --registry https://registry.npmjs.org/
86
+ # 4. Bump version and publish (use --tag beta for testing)
87
+ npm version prerelease --preid=beta # e.g. 0.0.67-beta.0
88
+ npm publish --tag beta
51
89
  ```
52
90
 
53
91
  ## High level architecture
@@ -4,6 +4,14 @@ import * as Platform from '../platform/platform.js';
4
4
  */
5
5
  export declare function normalizePath(path: string): string;
6
6
  export declare function schemeIs(url: Platform.DevToolsPath.UrlString | URL, scheme: string): boolean;
7
+ /**
8
+ * Returns true if the URL uses an unprivileged web-safe scheme (or is a `blob:`/`filesystem:` URL wrapping one).
9
+ */
10
+ export declare function hasWebSafeScheme(url: Platform.DevToolsPath.UrlString | URL | string): boolean;
11
+ /**
12
+ * Returns true if the URL uses a privileged scheme (or is a `blob:`/`filesystem:` URL wrapping one).
13
+ */
14
+ export declare function isPrivilegedScheme(url: Platform.DevToolsPath.UrlString | URL | string): boolean;
7
15
  /**
8
16
  * File paths in DevTools that are represented either as unencoded absolute or relative paths, or encoded paths, or URLs.
9
17
  * @example
@@ -106,6 +106,8 @@ export declare class Settings {
106
106
  */
107
107
  moduleSetting<T = any>(settingName: string): Setting<T>;
108
108
  settingForTest(settingName: string): Setting<unknown>;
109
+ /** The event target shared by all settings. Change listeners are registered with the setting name as event type. */
110
+ get eventTargetForTest(): ObjectWrapper<GenericEvents>;
109
111
  /**
110
112
  * Get setting via key, and create a new setting if the requested setting does not exist.
111
113
  * @param key kebab-case string ID
@@ -9,3 +9,8 @@ export declare function isWin(): boolean;
9
9
  export declare function setPlatformForTests(platform: string): void;
10
10
  export declare function fontFamily(): string;
11
11
  export declare function setFontFamilyForTests(family: string): void;
12
+ export declare function setLocationForTest(url: string | undefined): void;
13
+ export declare function isRemoteDevtoolsFrontend(): boolean;
14
+ export declare function isCustomDevtoolsFrontend(): boolean;
15
+ export declare function setIsRemoteDevtoolsFrontendForTest(isRemote: boolean | undefined): void;
16
+ export declare function setIsCustomDevtoolsFrontendForTest(isCustom: boolean | undefined): void;
@@ -475,7 +475,8 @@ export declare enum DevtoolsExperiments {
475
475
  'durable-messages' = 110,
476
476
  'jpeg-xl' = 111,
477
477
  'plus-button' = 112,
478
- MAX_VALUE = 113
478
+ 'source-map-scopes-in-sources-panel' = 113,
479
+ MAX_VALUE = 114
479
480
  }
480
481
  /** Update DevToolsIssuesPanelIssueExpanded from tools/metrics/histograms/enums.xml if new enum is added. **/
481
482
  export declare enum IssueExpanded {
@@ -597,8 +598,12 @@ export declare enum IssueCreated {
597
598
  'CorsIssue::LocalNetworkAccessPermissionDenied' = 111,
598
599
  'SRIMessageSignatureIssue::ValidationFailedIntegrityMismatch' = 112,
599
600
  'ElementAccessibilityIssue::InteractiveContentSummaryDescendant' = 113,
600
- 'CorsIssue::InvalidLocalNetworkAccess' = 114,
601
- MAX_VALUE = 115
601
+ 'GenericIssue::AutofillAndManualTextPolicyControlledFeaturesInfo' = 114,
602
+ 'GenericIssue::AutofillPolicyControlledFeatureInfo' = 115,
603
+ 'GenericIssue::ManualTextPolicyControlledFeatureInfo' = 116,
604
+ 'GenericIssue::GeolocationPromptWithoutUserGesture' = 117,
605
+ 'CorsIssue::InvalidLocalNetworkAccess' = 118,
606
+ MAX_VALUE = 119
602
607
  }
603
608
  export declare enum DeveloperResourceLoaded {
604
609
  LOAD_THROUGH_PAGE_VIA_TARGET = 0,
@@ -104,3 +104,24 @@ export declare const stringifyWithPrecision: (s: number, precision?: number) =>
104
104
  * Somewhat efficiently concatenates 2 base64 encoded strings.
105
105
  */
106
106
  export declare const concatBase64: (lhs: string, rhs: string) => string;
107
+ /**
108
+ * Formats and escapes `value` so it can be safely written as a single CSV cell.
109
+ *
110
+ * This handles two separate layers of escaping:
111
+ * 1. Spreadsheet formula escaping (CWE-1236 & viewer fidelity):
112
+ * RFC 4180 double-quoting (`"=1+1"` or `"- Loading..."`) only groups text
113
+ * into a single CSV column; spreadsheet apps strip the outer `"` and still
114
+ * evaluate cells starting with `=`, `+`, `-`, or `@` as formulas (often
115
+ * resulting in `#NAME?` errors or unintended formula execution). Prefixing
116
+ * the value with a single quote (`'`) tells spreadsheet apps to treat the
117
+ * cell as literal text (and they hide the leading `'` when displaying it).
118
+ * - Example without commas: `=SUM(A1:A2)` -> `'=SUM(A1:A2)`
119
+ * 2. RFC 4180 structural CSV quoting:
120
+ * If the cell also contains commas (`,`), double quotes (`"`), or newlines,
121
+ * it is wrapped in `"..."` (with inner `"` doubled to `""`) so CSV parsers
122
+ * do not split the cell across columns or rows.
123
+ * - Example with commas: `=SUM(1,2)` -> `"'=SUM(1,2)"`
124
+ * - Example starting with a literal quote: `"=SUM(1,2)"` -> `"""=SUM(1,2)"""`
125
+ * (not treated as a formula since the first character is `"`, not `=`).
126
+ */
127
+ export declare const escapeCsvCell: (value: string) => string;
@@ -4,5 +4,6 @@ export declare enum ExperimentName {
4
4
  INSTRUMENTATION_BREAKPOINTS = "instrumentation-breakpoints",
5
5
  DURABLE_MESSAGES = "durable-messages",
6
6
  JPEG_XL = "jpeg-xl",
7
- PLUS_BUTTON = "plus-button"
7
+ PLUS_BUTTON = "plus-button",
8
+ SOURCE_MAP_SCOPES_IN_SOURCES_PANEL = "source-map-scopes-in-sources-panel"
8
9
  }
@@ -54,13 +54,11 @@ export declare class ExperimentsSupport {
54
54
  readonly feedbackLink?: Platform.DevToolsPath.UrlString;
55
55
  }): Experiment;
56
56
  isEnabled(experimentName: ExperimentName): boolean;
57
- getValueFromStorage(experimentName: ExperimentName): boolean | undefined;
58
57
  setEnabled(experimentName: ExperimentName, enabled: boolean): void;
59
58
  enableForTest(experimentName: ExperimentName): void;
60
59
  disableForTest(experimentName: ExperimentName): void;
61
60
  isEnabledForTest(experimentName: ExperimentName): boolean;
62
61
  clearForTest(): void;
63
- removeAllExperimentsFromLocalStorage(): void;
64
62
  }
65
63
  export declare class Experiment {
66
64
  #private;
@@ -264,6 +262,9 @@ interface DevToolsMobileSafeAreaEmulation {
264
262
  interface DevToolsNetworkBackendLinking {
265
263
  enabled: boolean;
266
264
  }
265
+ interface DevToolsAiNaturalLanguageInterface {
266
+ enabled: boolean;
267
+ }
267
268
  /**
268
269
  * The host configuration that we expect from the DevTools back-end.
269
270
  *
@@ -294,6 +295,7 @@ export type HostConfig = Platform.TypeScriptUtilities.RecursivePartial<{
294
295
  devToolsAiCodeGeneration: HostConfigAiCodeGeneration;
295
296
  devToolsAiCodeCompletionStyles: HostConfigAiCodeCompletionStyles;
296
297
  devToolsVeLogging: HostConfigVeLogging;
298
+ devToolsAiNaturalLanguageInterface: DevToolsAiNaturalLanguageInterface;
297
299
  /**
298
300
  * OffTheRecord here indicates that the user's profile is either incognito,
299
301
  * or guest mode, rather than a "normal" profile.
@@ -26,6 +26,7 @@ export interface LayoutProperties {
26
26
  isContents?: boolean;
27
27
  containerType?: string;
28
28
  hasScroll: boolean;
29
+ isAnchorPositioned?: boolean;
29
30
  }
30
31
  export declare class CSSModel extends SDKModel<EventTypes> {
31
32
  #private;
@@ -67,6 +68,8 @@ export declare class CSSModel extends SDKModel<EventTypes> {
67
68
  allStyleSheets(): CSSStyleSheetHeader[];
68
69
  getInlineStyles(nodeId: Protocol.DOM.NodeId): Promise<InlineStyleResult | null>;
69
70
  forceStartingStyle(node: DOMNode, forced: boolean): boolean;
71
+ forcePositionTryOption(node: DOMNode, index?: number): boolean;
72
+ forcedPositionTryOption(node: DOMNode): number | undefined;
70
73
  forcePseudoState(node: DOMNode, pseudoClass: string, enable: boolean): boolean;
71
74
  pseudoState(node: DOMNode): string[] | null;
72
75
  setMediaText(styleSheetId: Protocol.DOM.StyleSheetId, range: TextUtils.TextRange.TextRange, newMediaText: string): Promise<boolean>;
@@ -115,6 +118,7 @@ export declare enum Events {
115
118
  MediaQueryResultChanged = "MediaQueryResultChanged",
116
119
  ModelWasEnabled = "ModelWasEnabled",
117
120
  ModelDisposed = "ModelDisposed",
121
+ PositionTryOptionForced = "PositionTryOptionForced",
118
122
  PseudoStateForced = "PseudoStateForced",
119
123
  StartingStylesStateForced = "StartingStylesStateForced",
120
124
  StyleSheetAdded = "StyleSheetAdded",
@@ -139,6 +143,7 @@ export interface EventTypes {
139
143
  [Events.MediaQueryResultChanged]: void;
140
144
  [Events.ModelWasEnabled]: void;
141
145
  [Events.ModelDisposed]: CSSModel;
146
+ [Events.PositionTryOptionForced]: DOMNode;
142
147
  [Events.PseudoStateForced]: PseudoStateForcedEvent;
143
148
  [Events.StartingStylesStateForced]: DOMNode;
144
149
  [Events.StyleSheetAdded]: CSSStyleSheetHeader;
@@ -101,11 +101,6 @@ export declare class ComputedText {
101
101
  * ignored for the spacing requirement.
102
102
  **/
103
103
  export declare function requiresSpace(a: string, b: string): boolean;
104
- export declare function requiresSpace(a: Array<{
105
- textContent?: string | null;
106
- }>, b: Array<{
107
- textContent?: string | null;
108
- }>): boolean;
109
104
  export declare namespace ASTUtils {
110
105
  function siblings(node: CodeMirror.SyntaxNode | null): CodeMirror.SyntaxNode[];
111
106
  function children(node: CodeMirror.SyntaxNode | null): CodeMirror.SyntaxNode[];
@@ -246,20 +246,21 @@ export declare class DOMDocument extends DOMNode {
246
246
  #private;
247
247
  body: DOMNode | null;
248
248
  documentElement: DOMNode | null;
249
- constructor(domModel: DOMModel, payload: Protocol.DOM.Node);
249
+ constructor(domModel: DOMModel, payload: Protocol.DOM.Node, frameId?: Protocol.Page.FrameId | null);
250
250
  get documentURL(): Platform.DevToolsPath.UrlString;
251
251
  get baseURL(): Platform.DevToolsPath.UrlString;
252
+ frameId(): Protocol.Page.FrameId | null;
252
253
  /**
253
254
  * Returns the security origin of this document.
254
255
  *
255
- * The security origin is derived from the document URL and is recomputed
256
+ * The security origin is resolved from the document's frame and is recomputed
256
257
  * when the document navigates to a new URL via `setDocumentURL`.
257
258
  */
258
259
  securityOrigin(): SecurityOrigin;
259
260
  /**
260
- * Updates the document and base URLs, and recomputes the document's security origin.
261
+ * Updates the document and base URLs, and updates the document's security origin.
261
262
  */
262
- setDocumentURL(url: Platform.DevToolsPath.UrlString): void;
263
+ setDocumentURL(url: Platform.DevToolsPath.UrlString, securityOrigin?: SecurityOrigin | null): void;
263
264
  }
264
265
  export declare class AdoptedStyleSheet {
265
266
  readonly id: Protocol.DOM.StyleSheetId;
@@ -412,6 +413,9 @@ export declare class DOMNodeSnapshot extends DOMNode {
412
413
  setAsInspectedNode(): Promise<void>;
413
414
  }
414
415
  export declare class DOMDocumentSnapshot extends DOMDocument {
416
+ #private;
417
+ constructor(domModel: DOMModel, payload: Protocol.DOM.Node, frameId: Protocol.Page.FrameId | null | undefined, securityOrigin: SecurityOrigin);
418
+ securityOrigin(): SecurityOrigin;
415
419
  init(_doc: DOMDocument | null, _isInShadowTree: boolean, _payload: Protocol.DOM.Node, _retainedNodes?: Set<Protocol.DOM.BackendNodeId> | undefined): void;
416
420
  setNodeName(_name: string, _callback?: ((arg0: string | null, arg1: DOMNode | null) => void) | undefined): void;
417
421
  setNodeValue(_value: string, _callback?: ((arg0: string | null) => void) | undefined): void;
@@ -16,6 +16,30 @@ export declare const enum StepMode {
16
16
  STEP_OUT = "StepOut",
17
17
  STEP_OVER = "StepOver"
18
18
  }
19
+ /**
20
+ * A CDP step command. `ranges` is passed as `skipList` to stepInto/stepOver, and ignored for stepOut. `enterRanges` is
21
+ * passed as `enterRanges` to stepOver: functions within them are entered as if by stepInto.
22
+ */
23
+ export interface AutoStep {
24
+ readonly command: StepMode;
25
+ readonly ranges: readonly LocationRange[];
26
+ readonly enterRanges?: readonly LocationRange[];
27
+ }
28
+ /**
29
+ * The step the user requested. It lives until a pause is presented to the user, or the user resumes or pauses, and
30
+ * allows the before-paused callback to continue the step automatically.
31
+ */
32
+ export interface StepContext {
33
+ readonly mode: StepMode;
34
+ /** The call frames of the pause in which the user requested the step. */
35
+ readonly callFrames: readonly CallFrame[];
36
+ }
37
+ /** Computes the CDP step command for a user-requested step. */
38
+ export type ComputeAutoStepCallback = (mode: StepMode, callFrames: readonly CallFrame[]) => Promise<AutoStep>;
39
+ /**
40
+ * Invoked for every pause before it's presented. Returns null to present the pause, or the step to issue instead.
41
+ */
42
+ export type BeforePausedCallback = (details: DebuggerPausedDetails, context: StepContext | null) => Promise<AutoStep | null>;
19
43
  export declare const WASM_SYMBOLS_PRIORITY: Protocol.Debugger.DebugSymbolsType[];
20
44
  export declare const skipAllPausesSettingDescriptor: Common.Settings.SettingDescriptor<boolean>;
21
45
  export declare class DebuggerModel extends SDKModel<EventTypes> {
@@ -44,8 +68,7 @@ export declare class DebuggerModel extends SDKModel<EventTypes> {
44
68
  private pauseOnExceptionStateChanged;
45
69
  private asyncStackTracesStateChanged;
46
70
  private breakpointsActiveChanged;
47
- setComputeAutoStepRangesCallback(callback: ((arg0: StepMode, arg1: CallFrame) => Promise<LocationRange[]>) | null): void;
48
- private computeAutoStepSkipList;
71
+ setComputeAutoStepCallback(callback: ComputeAutoStepCallback | null): void;
49
72
  stepInto(): Promise<void>;
50
73
  stepOver(): Promise<void>;
51
74
  stepOut(): Promise<void>;
@@ -71,9 +94,12 @@ export declare class DebuggerModel extends SDKModel<EventTypes> {
71
94
  scriptsForExecutionContext(executionContext: ExecutionContext): Script[];
72
95
  get callFrames(): CallFrame[] | null;
73
96
  debuggerPausedDetails(): DebuggerPausedDetails | null;
97
+ /**
98
+ * @returns null if the pause was presented, or the step to issue instead, as decided by the before-paused callback.
99
+ */
74
100
  private setDebuggerPausedDetails;
75
101
  private resetDebuggerPausedDetails;
76
- setBeforePausedCallback(callback: ((arg0: DebuggerPausedDetails, autoSteppingContext: Location | null) => Promise<boolean>) | null): void;
102
+ setBeforePausedCallback(callback: BeforePausedCallback | null): void;
77
103
  setEvaluateOnCallFrameCallback(callback: ((arg0: CallFrame, arg1: EvaluationOptions) => Promise<EvaluationResult | null>) | null): void;
78
104
  setSynchronizeBreakpointsCallback(callback: ((script: Script) => Promise<void>) | null): void;
79
105
  pausedScript(callFrames: Protocol.Debugger.CallFrame[], reason: Protocol.Debugger.PausedEventReason, auxData: Object | undefined, breakpointIds: string[], asyncStackTrace?: Protocol.Runtime.StackTrace, asyncStackTraceId?: Protocol.Runtime.StackTraceId): Promise<void>;
@@ -229,7 +255,14 @@ export declare class Scope implements ScopeChainEntry {
229
255
  object(): RemoteObject;
230
256
  description(): string;
231
257
  icon(): undefined;
232
- empty(): boolean;
258
+ /**
259
+ * Present iff V8 has no variable values to show for this scope, either because the scope
260
+ * declares no variables or because all of them are unavailable (e.g. optimized out).
261
+ *
262
+ * Such scopes are retained in {@link CallFrame.scopeChain} so they can be addressed via
263
+ * `scopeNumber` in `Debugger.evaluateOnCallFrame` and matched against source map scopes.
264
+ */
265
+ emptyReason(): Protocol.Debugger.ScopeEmptyReason | undefined;
233
266
  extraProperties(): RemoteObjectProperty[];
234
267
  }
235
268
  export declare class DebuggerPausedDetails {
@@ -21,10 +21,20 @@ export declare class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<E
21
21
  responseReceivedPromise?: Promise<void>;
22
22
  responseReceivedPromiseResolve?: () => void;
23
23
  directSocketInfo?: DirectSocketInfo;
24
- constructor(requestId: string, backendRequestId: Protocol.Network.RequestId | undefined, url: Platform.DevToolsPath.UrlString, documentURL: Platform.DevToolsPath.UrlString, frameId: Protocol.Page.FrameId | null, loaderId: Protocol.Network.LoaderId | null, initiator: Protocol.Network.Initiator | null, hasUserGesture?: boolean, console?: Common.Console.Console);
24
+ constructor(requestId: string, backendRequestId: Protocol.Network.RequestId | undefined, url: Platform.DevToolsPath.UrlString, documentURL: Platform.DevToolsPath.UrlString, frameId: Protocol.Page.FrameId | null, loaderId: Protocol.Network.LoaderId | null, initiator: Protocol.Network.Initiator | null, hasUserGesture?: boolean, console?: Common.Console.Console, isImportedHar?: boolean);
25
25
  static create(backendRequestId: Protocol.Network.RequestId, url: Platform.DevToolsPath.UrlString, documentURL: Platform.DevToolsPath.UrlString, frameId: Protocol.Page.FrameId | null, loaderId: Protocol.Network.LoaderId | null, initiator: Protocol.Network.Initiator | null, hasUserGesture?: boolean, console?: Common.Console.Console): NetworkRequest;
26
26
  static createForSocket(backendRequestId: Protocol.Network.RequestId, requestURL: Platform.DevToolsPath.UrlString, initiator?: Protocol.Network.Initiator, console?: Common.Console.Console): NetworkRequest;
27
27
  static createWithoutBackendRequest(requestId: string, url: Platform.DevToolsPath.UrlString, documentURL: Platform.DevToolsPath.UrlString, initiator: Protocol.Network.Initiator | null, console?: Common.Console.Console): NetworkRequest;
28
+ /**
29
+ * Creates a network request representing an entry imported from a HAR file.
30
+ *
31
+ * Use this instead of {@link createWithoutBackendRequest} when importing HAR logs
32
+ * (or testing HAR-imported traffic) so that the request is marked as HAR-imported
33
+ * at construction time and its security origins ({@link requestURLSecurityOrigin}
34
+ * and {@link initiatorSecurityOrigin}) resolve to isolated `imported-har://`
35
+ * virtual origins rather than colliding with live web origins.
36
+ */
37
+ static createForImportedHar(requestId: string, url: Platform.DevToolsPath.UrlString, documentURL: Platform.DevToolsPath.UrlString, initiator: Protocol.Network.Initiator | null, console?: Common.Console.Console): NetworkRequest;
28
38
  identityCompare(other: NetworkRequest): number;
29
39
  requestId(): string;
30
40
  backendRequestId(): Protocol.Network.RequestId | undefined;
@@ -39,6 +49,9 @@ export declare class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<E
39
49
  * (`imported-har://${authority}`) to ensure recorded network traffic never collides with
40
50
  * live web origins.
41
51
  *
52
+ * The result is cached, so repeated calls return the same instance until the URL changes.
53
+ * This keeps opaque origins (such as `data:` URLs) same-origin with themselves.
54
+ *
42
55
  * @see {@link initiatorSecurityOrigin} to obtain the origin of the document that initiated the request.
43
56
  */
44
57
  requestURLSecurityOrigin(): SecurityOrigin;
@@ -56,6 +69,9 @@ export declare class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<E
56
69
  * For imported HAR files, the origin is mapped to an isolated virtual domain
57
70
  * (`imported-har://${authority}`) matching the imported initiating document.
58
71
  *
72
+ * The result is cached, so repeated calls return the same instance. This keeps opaque
73
+ * origins same-origin with themselves.
74
+ *
59
75
  * @see {@link requestURLSecurityOrigin} to obtain the origin of the target resource URL being requested.
60
76
  */
61
77
  initiatorSecurityOrigin(): SecurityOrigin;
@@ -209,7 +225,6 @@ export declare class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<E
209
225
  wasIntercepted(): boolean;
210
226
  setWasIntercepted(wasIntercepted: boolean): void;
211
227
  isImportedHar(): boolean;
212
- setIsImportedHar(isImportedHar: boolean): void;
213
228
  setEarlyHintsHeaders(headers: NameValue[]): void;
214
229
  get responseCookies(): Cookie[];
215
230
  set responseCookies(responseCookies: Cookie[]);
@@ -238,6 +253,19 @@ export declare class NetworkRequest extends Common.ObjectWrapper.ObjectWrapper<E
238
253
  private parseMultipartFormDataParameters;
239
254
  private computeHeaderValue;
240
255
  requestContentData(): Promise<TextUtils.ContentData.ContentDataOrError>;
256
+ /**
257
+ * Returns the response body without waiting for the request to finish loading.
258
+ *
259
+ * `requestContentData()` waits for `FINISHED_LOADING` when the request has no
260
+ * content data provider. Some requests never finish: Chrome does not send
261
+ * `loadingFinished` for a `Cache-Control: no-store` fetch() whose body the page
262
+ * never reads, and synthetic requests without a provider are never finished at all.
263
+ * Callers that must not block, such as AI context building, use this method instead.
264
+ *
265
+ * Requests with a content data provider (Local Overrides, Cache Storage, HAR
266
+ * imports) resolve even when they have not finished.
267
+ */
268
+ requestContentDataIfAvailable(): Promise<TextUtils.ContentData.ContentDataOrError>;
241
269
  setContentDataProvider(dataProvider: () => Promise<TextUtils.ContentData.ContentDataOrError>): void;
242
270
  requestStreamingContent(): Promise<TextUtils.StreamingContentData.StreamingContentDataOrError>;
243
271
  contentURL(): Platform.DevToolsPath.UrlString;
@@ -42,6 +42,7 @@ export declare class ResourceTreeModel extends SDKModel<EventTypes> {
42
42
  primaryPageChanged(frame: ResourceTreeFrame, type: PrimaryPageChangeType): void;
43
43
  documentOpened(framePayload: Protocol.Page.Frame): void;
44
44
  navigatedWithinDocument(frameId: Protocol.Page.FrameId, url: string): void;
45
+ frameStoppedLoading(frameId: Protocol.Page.FrameId): void;
45
46
  frameDetached(frameId: Protocol.Page.FrameId, isSwap: boolean): void;
46
47
  private onRequestFinished;
47
48
  private onRequestUpdateDropped;
@@ -221,6 +222,7 @@ export declare class ResourceTreeFrame {
221
222
  highlight(): Promise<void>;
222
223
  getPermissionsPolicyState(): Promise<Protocol.Page.PermissionsPolicyFeatureState[] | null>;
223
224
  getOriginTrials(): Promise<Protocol.Page.OriginTrial[]>;
225
+ getSpellCheckCustomDictionary(): Promise<string[]>;
224
226
  setCreationStackTrace(creationStackTraceData: {
225
227
  creationStackTrace: Protocol.Runtime.StackTrace | null;
226
228
  creationStackTraceTarget: Target;
@@ -241,7 +243,7 @@ export declare class PageDispatcher implements ProtocolProxyApi.PageDispatcher {
241
243
  frameDetached({ frameId, reason }: Protocol.Page.FrameDetachedEvent): void;
242
244
  frameSubtreeWillBeDetached(_params: Protocol.Page.FrameSubtreeWillBeDetachedEvent): void;
243
245
  frameStartedLoading({}: Protocol.Page.FrameStartedLoadingEvent): void;
244
- frameStoppedLoading({}: Protocol.Page.FrameStoppedLoadingEvent): void;
246
+ frameStoppedLoading({ frameId }: Protocol.Page.FrameStoppedLoadingEvent): void;
245
247
  frameRequestedNavigation({}: Protocol.Page.FrameRequestedNavigationEvent): void;
246
248
  frameScheduledNavigation({}: Protocol.Page.FrameScheduledNavigationEvent): void;
247
249
  frameClearedScheduledNavigation({}: Protocol.Page.FrameClearedScheduledNavigationEvent): void;
@@ -10,6 +10,7 @@ export declare class RuntimeModel extends SDKModel<EventTypes> {
10
10
  #private;
11
11
  readonly agent: ProtocolProxyApi.RuntimeApi;
12
12
  constructor(target: Target);
13
+ dispose(): void;
13
14
  static isSideEffectFailure(response: Protocol.Runtime.EvaluateResponse | EvaluationResult): boolean;
14
15
  debuggerModel(): DebuggerModel;
15
16
  heapProfilerModel(): HeapProfilerModel;
@@ -51,3 +51,4 @@ export declare const consoleUserActivationEvalSettingDescriptor: Common.Settings
51
51
  export declare const monitoringXHREnabledSettingDescriptor: Common.Settings.SettingDescriptor<boolean>;
52
52
  export declare const disablePausedStateOverlaySettingDescriptor: Common.Settings.SettingDescriptor<boolean>;
53
53
  export declare const preserveNetworkLogSettingDescriptor: Common.Settings.SettingDescriptor<boolean>;
54
+ export declare const textEditorIndentSettingDescriptor: Common.Settings.SettingDescriptor<string>;
@@ -2,10 +2,10 @@ import * as ScopesCodec from '../../third_party/source-map-scopes-codec/source-m
2
2
  import * as Common from '../common/common.js';
3
3
  import * as Platform from '../platform/platform.js';
4
4
  import * as TextUtils from '../text_utils/text_utils.js';
5
- import type { CallFrame, ScopeChainEntry } from './DebuggerModel.js';
5
+ import type { CallFrame, Location, ScopeChainEntry } from './DebuggerModel.js';
6
6
  import type { Script } from './Script.js';
7
7
  import { type NamedFunctionRange } from './SourceMapFunctionRanges.js';
8
- import { type TranslatedFrame } from './SourceMapScopesInfo.js';
8
+ import { type PositionRange, type RawFrameTranslation } from './SourceMapScopesInfo.js';
9
9
  /**
10
10
  * Type of the base source map JSON object, which contains the sources and the mappings at the very least, plus
11
11
  * some additional fields.
@@ -22,7 +22,8 @@ export interface SourceMapV3Object {
22
22
  sourcesContent?: Array<string | null>;
23
23
  names?: string[];
24
24
  ignoreList?: number[];
25
- scopes?: string;
25
+ scopes?: Array<string | null>;
26
+ ranges?: string[];
26
27
  rangeMappings?: string;
27
28
  debugId?: string;
28
29
  x_google_linecount?: number;
@@ -106,6 +107,11 @@ export declare class SourceMap {
106
107
  sourceURLs(): Platform.DevToolsPath.UrlString[];
107
108
  embeddedContentByURL(sourceURL: Platform.DevToolsPath.UrlString): string | null;
108
109
  hasScopeInfo(): boolean;
110
+ /**
111
+ * True iff the scopes come from the source map itself (encoded `scopes`), not from the AST fallback or from an
112
+ * extension.
113
+ */
114
+ hasEncodedScopeInfo(): boolean;
109
115
  waitForScopeInfo(): Promise<void>;
110
116
  findEntry(lineNumber: number, columnNumber: number): SourceMapEntry | null;
111
117
  /** Returns the entry at the given position but only if an entry exists for that exact position */
@@ -162,14 +168,22 @@ export declare class SourceMap {
162
168
  */
163
169
  compatibleForURL(sourceURL: Platform.DevToolsPath.UrlString, other: SourceMap): boolean;
164
170
  resolveScopeChain(frame: CallFrame): ScopeChainEntry[] | null;
171
+ resolveMappedVariablesAtPosition(location: Location, ignoreInnerBlockScopes?: boolean): Array<Map<string, string | null>> | null;
165
172
  findOriginalFunctionName(position: ScopesCodec.Position): string | null;
166
173
  findOriginalFunctionScope(position: ScopesCodec.Position): {
167
174
  scope: ScopesCodec.OriginalScope;
168
175
  url?: Platform.DevToolsPath.UrlString;
169
176
  } | null;
170
- isOutlinedFrame(generatedLine: number, generatedColumn: number): boolean;
171
- hasInlinedFrames(generatedLine: number, generatedColumn: number): boolean;
172
- translateCallSite(generatedLine: number, generatedColumn: number): TranslatedFrame[];
177
+ /** See {@link SourceMapScopesInfo.translateRawFrame}. `null` if no scopes information is available. */
178
+ translateRawFrame(generatedLine: number, generatedColumn: number): RawFrameTranslation | null;
179
+ /** See {@link SourceMapScopesInfo.inlinedFunctionRange}. `null` without encoded scopes. */
180
+ inlinedFunctionRange(generatedLine: number, generatedColumn: number): PositionRange | null;
181
+ /** See {@link SourceMapScopesInfo.inlinedCalleeRanges}. Empty without encoded scopes. */
182
+ inlinedCalleeRanges(generatedLine: number, generatedColumn: number): PositionRange[];
183
+ /** See {@link SourceMapScopesInfo.outlinedFunctionRanges}. Empty without encoded scopes. */
184
+ outlinedFunctionRanges(generatedLine: number, generatedColumn: number): PositionRange[];
185
+ /** See {@link SourceMapScopesInfo.artificialFunctionRanges}. Empty without encoded scopes. */
186
+ artificialFunctionRanges(): PositionRange[];
173
187
  }
174
188
  export declare class TokenIterator {
175
189
  #private;
@@ -5,19 +5,16 @@ export interface NamedFunctionRange {
5
5
  name: string;
6
6
  }
7
7
  /**
8
- * Turns a list of {@link NamedFunctionRange}s into a single {@link OriginalScope} tree nested
9
- * according to the start/end position. Each range is turned into a OriginalScope with the `isStackFrame`
8
+ * Turns a list of {@link NamedFunctionRange}s into a list of {@link OriginalScope} trees nested
9
+ * according to the start/end position. Each range is turned into an OriginalScope with the `isStackFrame`
10
10
  * bit set to denote it as a function and a generic "Function" label.
11
11
  *
12
- * We nest all these function scopes underneath a single global scope that always starts at (0, 0) and
13
- * reaches to the largest end position.
14
- *
15
12
  * `ranges` can be unsorted but will be sorted in-place.
16
13
  *
17
14
  * @throws if the ranges are not nested properly. Concretely: start < end for each range, and no
18
15
  * "straddling" (i.e. partially overlapping ranges).
19
16
  */
20
- export declare function buildOriginalScopes(ranges: NamedFunctionRange[]): ScopesCodec.OriginalScope;
17
+ export declare function buildOriginalScopes(ranges: NamedFunctionRange[]): ScopesCodec.OriginalScope[];
21
18
  /**
22
19
  * Implements decoding of the pasta source map specification.
23
20
  *