chrome-devtools-frontend 1.0.1626840 → 1.0.1629211

package/front_end/panels/emulation/DeviceModeView.ts

@@ -124,7 +124,7 @@ export class DeviceModeView extends UI.Widget.VBox {
 
   private createUI(): void {
     this.toolbar = new DeviceModeToolbar(this.model, this.showMediaInspectorSetting, this.showRulersSetting);
-    this.contentElement.appendChild(this.toolbar.element());
+    this.toolbar.show(this.contentElement);
     this.contentClip = this.contentElement.createChild('div', 'device-mode-content-clip vbox');
     this.responsivePresetsContainer = this.contentClip.createChild('div', 'device-mode-presets-container');
     this.responsivePresetsContainer.setAttribute('jslog', `${VisualLogging.responsivePresets()}`);
@@ -358,7 +358,7 @@ export class DeviceModeView extends UI.Widget.VBox {
       this.cachedScale = this.model.scale();
     }
 
-    this.toolbar.update();
+    this.toolbar.requestUpdate();
     this.loadImage(this.screenImage, this.model.screenImage());
     this.loadImage(this.outlineImage, this.model.outlineImage());
     this.mediaInspector.setAxisTransform(this.model.scale());

package/front_end/panels/profiler/HeapSnapshotGridNodes.ts

@@ -269,11 +269,13 @@ export class HeapSnapshotGridNode extends
       const value = this.data[columnId];
       const percentColumn = columnId + '-percent';
       const percent = this.data[percentColumn];
+      const tooltipColumn = `${columnId}-tooltip`;
+      const tooltip = this.data[tooltipColumn];
       if (percent) {
         render(
             html`
           <div class="profile-multiple-values">
-            <span aria-hidden="true">${value}</span>
+            <span aria-hidden="true" title=${Directives.ifDefined(tooltip)}>${value}</span>
             <span class="percent-column" aria-hidden="true">${percent}</span>
           </div>`,
             cell);
@@ -283,7 +285,7 @@ export class HeapSnapshotGridNode extends
         render(
             html`
           <div>
-            <span>${value}</span>
+            <span title=${Directives.ifDefined(tooltip)}>${value}</span>
           </div>`,
             cell);
       }
@@ -560,6 +562,8 @@ export abstract class HeapSnapshotGenericObjectNode extends HeapSnapshotGridNode
       retainedSize: i18n.ByteUtilities.formatBytesToKb(this.retainedSize),
       'shallowSize-percent': this.toPercentString(shallowSizePercent),
       'retainedSize-percent': this.toPercentString(retainedSizePercent),
+      'shallowSize-tooltip': i18n.ByteUtilities.bytesToString(this.shallowSize),
+      'retainedSize-tooltip': i18n.ByteUtilities.bytesToString(this.retainedSize),
     };
   }
 
@@ -580,8 +584,7 @@ export abstract class HeapSnapshotGenericObjectNode extends HeapSnapshotGridNode
   }
 
   override createCell(columnId: string): HTMLElement {
-    const cell = columnId !== 'object' ? this.createValueCell(columnId) : this.createObjectCell();
-    return cell;
+    return columnId !== 'object' ? this.createValueCell(columnId) : this.createObjectCell();
   }
 
   createObjectCell(): HTMLElement {
@@ -1132,6 +1135,8 @@ export class HeapSnapshotConstructorNode extends HeapSnapshotGridNode {
       retainedSize: i18n.ByteUtilities.formatBytesToKb(this.retainedSize),
       'shallowSize-percent': this.toPercentString(shallowSizePercent),
       'retainedSize-percent': this.toPercentString(retainedSizePercent),
+      'shallowSize-tooltip': i18n.ByteUtilities.bytesToString(this.shallowSize),
+      'retainedSize-tooltip': i18n.ByteUtilities.bytesToString(this.retainedSize),
     };
   }
 

package/front_end/panels/profiler/ProfilesPanel.ts

@@ -37,6 +37,7 @@ import {createIcon} from '../../ui/kit/kit.js';
 // eslint-disable-next-line @devtools/es-modules-import
 import objectValueStyles from '../../ui/legacy/components/object_ui/objectValue.css.js';
 import * as UI from '../../ui/legacy/legacy.js';
+import {render} from '../../ui/lit/lit.js';
 import * as VisualLogging from '../../ui/visual_logging/visual_logging.js';
 
 import {
@@ -473,7 +474,12 @@ export class ProfilesPanel extends UI.Panel.PanelWithSidebar implements DataDisp
     this.profileViewToolbar.removeToolbarItems();
 
     void (view as unknown as UI.View.View).toolbarItems().then(items => {
-      items.map(item => this.profileViewToolbar.appendToolbarItem(item));
+      if (Array.isArray(items)) {
+        items.map(item => this.profileViewToolbar.appendToolbarItem(item));
+      } else {
+        // eslint-disable-next-line @devtools/no-lit-render-outside-of-view
+        render(items, this.profileViewToolbar);
+      }
     });
 
     return view;

package/front_end/panels/sources/AiCodeCompletionPlugin.ts

@@ -23,7 +23,7 @@ export class AiCodeCompletionPlugin extends Plugin {
   #aiCodeCompletionDisclaimer?: PanelCommon.AiCodeCompletionDisclaimer;
   #aiCodeCompletionDisclaimerContainer = document.createElement('div');
   #aiCodeCompletionDisclaimerToolbarItem = new UI.Toolbar.ToolbarItem(this.#aiCodeCompletionDisclaimerContainer);
-  #aiCodeCompletionCitationsToolbar?: PanelCommon.AiCodeCompletionSummaryToolbar;
+  #aiCodeCompletionCitationsToolbar?: PanelCommon.AiCodeCompletionSummaryToolbar.AiCodeCompletionSummaryToolbar;
   #aiCodeCompletionCitationsToolbarContainer = document.createElement('div');
   #aiCodeCompletionCitationsToolbarAttached = false;
   aiCodeCompletionConfig: TextEditor.AiCodeCompletionProvider.AiCodeCompletionConfig;
@@ -113,11 +113,12 @@ export class AiCodeCompletionPlugin extends Plugin {
     if (this.#aiCodeCompletionCitationsToolbar) {
       return;
     }
-    this.#aiCodeCompletionCitationsToolbar = new PanelCommon.AiCodeCompletionSummaryToolbar({
-      citationsTooltipId: CITATIONS_TOOLTIP_ID,
-      hasTopBorder: true,
-      panel: AiCodeCompletion.AiCodeCompletion.ContextFlavor.SOURCES
-    });
+    this.#aiCodeCompletionCitationsToolbar =
+        new PanelCommon.AiCodeCompletionSummaryToolbar.AiCodeCompletionSummaryToolbar({
+          citationsTooltipId: CITATIONS_TOOLTIP_ID,
+          hasTopBorder: true,
+          panel: AiCodeCompletion.AiCodeCompletion.ContextFlavor.SOURCES
+        });
     this.#aiCodeCompletionCitationsToolbar.show(this.#aiCodeCompletionCitationsToolbarContainer, undefined, true);
   }
 

package/front_end/panels/sources/WatchExpressionsSidebarPane.ts

@@ -49,7 +49,7 @@ import * as ObjectUI from '../../ui/legacy/components/object_ui/object_ui.js';
 import objectValueStyles from '../../ui/legacy/components/object_ui/objectValue.css.js';
 import * as Components from '../../ui/legacy/components/utils/utils.js';
 import * as UI from '../../ui/legacy/legacy.js';
-import {Directives, html, render} from '../../ui/lit/lit.js';
+import {Directives, html, render, type TemplateResult} from '../../ui/lit/lit.js';
 import * as VisualLogging from '../../ui/visual_logging/visual_logging.js';
 
 import {UISourceCodeFrame} from './UISourceCodeFrame.js';
@@ -179,8 +179,6 @@ export class WatchExpressionsSidebarPane extends UI.Widget.VBox implements UI.Ac
                                                                            UI.Toolbar.ItemsProvider {
   #watchExpressions: WatchExpression[];
   #watchExpressionsSetting: Common.Settings.Setting<string[]>;
-  private readonly addButton: UI.Toolbar.ToolbarButton;
-  private readonly refreshButton: UI.Toolbar.ToolbarButton;
   private readonly linkifier: Components.Linkifier.Linkifier;
   #view: View;
   #expandControllers = new Map<string, ObjectUI.ObjectPropertiesSection.ObjectTreeExpansionTracker>();
@@ -192,17 +190,6 @@ export class WatchExpressionsSidebarPane extends UI.Widget.VBox implements UI.Ac
     this.#watchExpressionsSetting =
         Common.Settings.Settings.instance().createLocalSetting<string[]>('watch-expressions', []);
 
-    this.addButton = new UI.Toolbar.ToolbarButton(
-        i18nString(UIStrings.addWatchExpression), 'plus', undefined, 'add-watch-expression');
-    this.addButton.setSize(Buttons.Button.Size.SMALL);
-    this.addButton.addEventListener(UI.Toolbar.ToolbarButton.Events.CLICK, _event => {
-      void this.addButtonClicked();
-    });
-    this.refreshButton = new UI.Toolbar.ToolbarButton(
-        i18nString(UIStrings.refreshWatchExpressions), 'refresh', undefined, 'refresh-watch-expressions');
-    this.refreshButton.setSize(Buttons.Button.Size.SMALL);
-    this.refreshButton.addEventListener(UI.Toolbar.ToolbarButton.Events.CLICK, this.#refreshExpressions, this);
-
     UI.Context.Context.instance().addFlavorChangeListener(
         SDK.RuntimeModel.ExecutionContext, this.#refreshExpressions, this);
     UI.Context.Context.instance().addFlavorChangeListener(
@@ -223,8 +210,27 @@ export class WatchExpressionsSidebarPane extends UI.Widget.VBox implements UI.Ac
     return this.#watchExpressions;
   }
 
-  toolbarItems(): UI.Toolbar.ToolbarItem[] {
-    return [this.addButton, this.refreshButton];
+  toolbarItems(): TemplateResult {
+    // clang-format off
+    return html`
+      <devtools-button .data=${{
+          variant: Buttons.Button.Variant.TOOLBAR,
+          iconName: 'plus',
+          size: Buttons.Button.Size.SMALL,
+          title: i18nString(UIStrings.addWatchExpression),
+          jslogContext: 'add-watch-expression',
+        } as Buttons.Button.ButtonData}
+        @click=${(e: Event) => this.addButtonClicked(e)}></devtools-button>
+      <devtools-button .data=${{
+          variant: Buttons.Button.Variant.TOOLBAR,
+          iconName: 'refresh',
+          size: Buttons.Button.Size.SMALL,
+          title: i18nString(UIStrings.refreshWatchExpressions),
+          jslogContext: 'refresh-watch-expressions',
+        } as Buttons.Button.ButtonData}
+        @click=${(e: Event) => this.refreshButtonClicked(e)}></devtools-button>
+    `;
+    // clang-format on
   }
 
   private saveExpressions(): void {
@@ -239,7 +245,8 @@ export class WatchExpressionsSidebarPane extends UI.Widget.VBox implements UI.Ac
     this.#watchExpressionsSetting.set(toSave);
   }
 
-  private async addButtonClicked(): Promise<void> {
+  private async addButtonClicked(event?: Event): Promise<void> {
+    event?.consume(true);
     await UI.ViewManager.ViewManager.instance().showView('sources.watch');
     const watchExpression = this.createWatchExpression(null);
     this.requestUpdate();
@@ -250,6 +257,11 @@ export class WatchExpressionsSidebarPane extends UI.Widget.VBox implements UI.Ac
     watchExpression.startEditing();
   }
 
+  private refreshButtonClicked(event: Event): void {
+    event.consume(true);
+    this.#refreshExpressions();
+  }
+
   #refreshExpressions(): void {
     this.linkifier.reset();
     for (const expression of this.#watchExpressions) {
@@ -407,7 +419,6 @@ export class WatchExpression extends Common.ObjectWrapper.ObjectWrapper<EventTyp
   get result(): SDK.RemoteObject.RemoteObject|null {
     return this.#result ?? null;
   }
-
   get updateComplete(): Promise<void> {
     return this.#updateComplete;
   }

package/front_end/panels/sources/sources-meta.ts

@@ -1076,6 +1076,13 @@ UI.ActionRegistration.registerActionExtension({
         UI.ActionRegistration.KeybindSet.VS_CODE,
       ],
     },
+    {
+      shortcut: 'Alt+g',
+      keybindSets: [
+        UI.ActionRegistration.KeybindSet.DEVTOOLS_DEFAULT,
+        UI.ActionRegistration.KeybindSet.VS_CODE,
+      ],
+    },
   ],
 });
 

package/front_end/panels/timeline/TimelineController.ts

@@ -5,7 +5,6 @@
 import * as Common from '../../core/common/common.js';
 import * as i18n from '../../core/i18n/i18n.js';
 import type * as Platform from '../../core/platform/platform.js';
-import * as Root from '../../core/root/root.js';
 import * as SDK from '../../core/sdk/sdk.js';
 import type * as Protocol from '../../generated/protocol.js';
 import * as CrUXManager from '../../models/crux-manager/crux-manager.js';
@@ -254,7 +253,7 @@ export class TimelineController implements Tracing.TracingManager.TracingManager
     if (options.enableJSSampling) {
       categoriesArray.push(disabledByDefault('v8.cpu_profiler'));
     }
-    if (Root.Runtime.experiments.isEnabled(Root.ExperimentNames.ExperimentName.TIMELINE_INVALIDATION_TRACKING)) {
+    if (Common.Settings.Settings.instance().moduleSetting('timeline-invalidation-tracking').get() as boolean) {
       categoriesArray.push(disabledByDefault('devtools.timeline.invalidationTracking'));
     }
     if (options.capturePictures) {

package/front_end/panels/timeline/TimelinePanel.ts

@@ -740,7 +740,7 @@ export class TimelinePanel extends Common.ObjectWrapper.eventMixin<EventTypes, t
   #instantiateNewModel(): Trace.TraceModel.Model {
     const config = Trace.Types.Configuration.defaults();
     config.showAllEvents = Common.Settings.Settings.instance().moduleSetting('timeline-show-all-events').get();
-    config.debugMode = Root.Runtime.experiments.isEnabled(Root.ExperimentNames.ExperimentName.TIMELINE_DEBUG_MODE);
+    config.debugMode = Common.Settings.Settings.instance().moduleSetting('timeline-debug-mode').get() as boolean;
 
     const traceEngineModel = Trace.TraceModel.Model.createWithAllHandlers(config);
 

package/front_end/panels/timeline/TimelineUIUtils.ts

@@ -497,16 +497,8 @@ type TimeRangeCategoryStats = Record<string, number>;
 const {SamplesIntegrator} = Trace.Helpers.SamplesIntegrator;
 
 export class TimelineUIUtils {
-  /**
-   * use getGetDebugModeEnabled() to query this variable.
-   */
-  static debugModeEnabled: boolean|undefined = undefined;
   static getGetDebugModeEnabled(): boolean {
-    if (TimelineUIUtils.debugModeEnabled === undefined) {
-      TimelineUIUtils.debugModeEnabled =
-          Root.Runtime.experiments.isEnabled(Root.ExperimentNames.ExperimentName.TIMELINE_DEBUG_MODE);
-    }
-    return TimelineUIUtils.debugModeEnabled;
+    return Common.Settings.Settings.instance().moduleSetting('timeline-debug-mode').get() as boolean;
   }
   static frameDisplayName(frame: Protocol.Runtime.CallFrame): string {
     const maybeResolvedData = SourceMapsResolver.SourceMapsResolver.resolvedCodeLocationForCallFrame(frame);
@@ -1527,7 +1519,7 @@ export class TimelineUIUtils {
       await TimelineUIUtils.generateCauses(event, contentHelper, parsedTrace);
     }
 
-    if (Root.Runtime.experiments.isEnabled(Root.ExperimentNames.ExperimentName.TIMELINE_DEBUG_MODE)) {
+    if (TimelineUIUtils.getGetDebugModeEnabled()) {
       TimelineUIUtils.renderEventJson(event, contentHelper);
     }
 

package/front_end/panels/timeline/timeline-meta.ts

@@ -66,6 +66,14 @@ const UIStrings = {
    * @description Title of a setting under the Performance category in Settings
    */
   timelineShowAllEvents: 'Show all events',
+  /**
+   * @description Title of a setting under the Performance category in Settings
+   */
+  timelineDebugMode: 'Timeline debug mode (trace event details, etc.)',
+  /**
+   * @description Title of a setting under the Performance category in Settings
+   */
+  timelineInvalidationTracking: 'Invalidation tracking',
 } as const;
 const str_ = i18n.i18n.registerUIStrings('panels/timeline/timeline-meta.ts', UIStrings);
 const i18nLazyString = i18n.i18n.getLazilyComputedLocalizedString.bind(undefined, str_);
@@ -327,6 +335,24 @@ Common.Settings.registerSettingExtension({
   defaultValue: false,
 });
 
+Common.Settings.registerSettingExtension({
+  category: Common.Settings.SettingCategory.PERFORMANCE,
+  storageType: Common.Settings.SettingStorageType.SYNCED,
+  title: i18nLazyString(UIStrings.timelineDebugMode),
+  settingName: 'timeline-debug-mode',
+  settingType: Common.Settings.SettingType.BOOLEAN,
+  defaultValue: false,
+});
+
+Common.Settings.registerSettingExtension({
+  category: Common.Settings.SettingCategory.PERFORMANCE,
+  storageType: Common.Settings.SettingStorageType.SYNCED,
+  title: i18nLazyString(UIStrings.timelineInvalidationTracking),
+  settingName: 'timeline-invalidation-tracking',
+  settingType: Common.Settings.SettingType.BOOLEAN,
+  defaultValue: false,
+});
+
 // IMPORTANT: if you are updating this, you should also update the setting in
 // js_timeline-meta.
 Common.Settings.registerSettingExtension({

package/front_end/third_party/acorn/README.chromium

@@ -13,5 +13,5 @@ Description:
 A tiny, fast JavaScript parser written in JavaScript.
 
 ```bash
-wget -qO- https://registry.npmjs.org/acorn/-/acorn-8.10.0.tgz | tar xzf -
+wget -qO- https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz | tar xzf -
 ```

package/front_end/third_party/acorn/acorn.ts

@@ -7,7 +7,7 @@ import * as acorn from './package/dist/acorn.mjs';
 import type * as ESTree from './estree-legacy.js';
 export {ESTree};
 
-export { type Comment, defaultOptions, getLineInfo, isNewLine, lineBreak, lineBreakG, Node, SourceLocation, Token, tokTypes, tokContexts} from './package/dist/acorn.mjs';
+export { type Comment, defaultOptions, getLineInfo, Node, SourceLocation, Token, tokTypes} from './package/dist/acorn.mjs';
 
 export const Parser = acorn.Parser;
 export const tokenizer = acorn.Parser.tokenizer.bind(acorn.Parser);

package/front_end/third_party/acorn/package/CHANGELOG.md

@@ -1,3 +1,131 @@
+## 8.16.0 (2026-02-19)
+
+### New features
+
+The `sourceType` option can now be set to `"commonjs"` to have the parser treat the top level scope as a function scope.
+
+Add support for Unicode 17.
+
+### Bug fixes
+
+Don't recognize `await using` as contextual keywords when followed directly by a backslash.
+
+Fix an issue where the parser would allow `return` statements in `static` blocks when `allowReturnOutsideFunction` was enabled.
+
+Properly reject `using` declarations that appear directly in `switch` or `for` head scopes.
+
+Fix some corner case issues in the recognition of `using` syntax.
+
+## 8.15.0 (2025-06-08)
+
+### New features
+
+Support `using` and `await using` syntax.
+
+The `AnyNode` type is now defined in such a way that plugins can extend it.
+
+### Bug fixes
+
+Fix an issue where the `bigint` property of literal nodes for non-decimal bigints had the wrong format.
+
+The `acorn` CLI tool no longer crashes when emitting a tree that contains a bigint.
+
+## 8.14.1 (2025-03-05)
+
+### Bug fixes
+
+Fix an issue where `await` expressions in class field initializers were inappropriately allowed.
+
+Properly allow await inside an async arrow function inside a class field initializer.
+
+Mention the source file name in syntax error messages when given.
+
+Properly add an empty `attributes` property to every form of `ExportNamedDeclaration`.
+
+## 8.14.0 (2024-10-27)
+
+### New features
+
+Support ES2025 import attributes.
+
+Support ES2025 RegExp modifiers.
+
+### Bug fixes
+
+Support some missing Unicode properties.
+
+## 8.13.0 (2024-10-16)
+
+### New features
+
+Upgrade to Unicode 16.0.
+
+## 8.12.1 (2024-07-03)
+
+### Bug fixes
+
+Fix a regression that caused Acorn to no longer run on Node versions <8.10.
+
+## 8.12.0 (2024-06-14)
+
+### New features
+
+Support ES2025 duplicate capture group names in regular expressions.
+
+### Bug fixes
+
+Include `VariableDeclarator` in the `AnyNode` type so that walker objects can refer to it without getting a type error.
+
+Properly raise a parse error for invalid `for`/`of` statements using `async` as binding name.
+
+Properly recognize \"use strict\" when preceded by a string with an escaped newline.
+
+Mark the `Parser` constructor as protected, not private, so plugins can extend it without type errors.
+
+Fix a bug where some invalid `delete` expressions were let through when the operand was parenthesized and `preserveParens` was enabled.
+
+Properly normalize line endings in raw strings of invalid template tokens.
+
+Properly track line numbers for escaped newlines in strings.
+
+Fix a bug that broke line number accounting after a template literal with invalid escape sequences.
+
+## 8.11.3 (2023-12-29)
+
+### Bug fixes
+
+Add `Function` and `Class` to the `AggregateType` type, so that they can be used in walkers without raising a type error.
+
+Make sure `onToken` get an `import` keyword token when parsing `import.meta`.
+
+Fix a bug where `.loc.start` could be undefined for `new.target` `meta` nodes.
+
+## 8.11.2 (2023-10-27)
+
+### Bug fixes
+
+Fix a bug that caused regular expressions after colon tokens to not be properly tokenized in some circumstances.
+
+## 8.11.1 (2023-10-26)
+
+### Bug fixes
+
+Fix a regression where `onToken` would receive 'name' tokens for 'new' keyword tokens.
+
+## 8.11.0 (2023-10-26)
+
+### Bug fixes
+
+Fix an issue where tokenizing (without parsing) an object literal with a property named `class` or `function` could, in some circumstance, put the tokenizer into an invalid state.
+
+Fix an issue where a slash after a call to a propery named the same as some keywords would be tokenized as a regular expression.
+
+### New features
+
+Upgrade to Unicode 15.1.
+
+Use a set of new, much more precise, TypeScript types.
+
 ## 8.10.0 (2023-07-05)
 
 ### New features

package/front_end/third_party/acorn/package/README.md

@@ -9,9 +9,7 @@ Acorn is open source software released under an
 
 You are welcome to
 [report bugs](https://github.com/acornjs/acorn/issues) or create pull
-requests on [github](https://github.com/acornjs/acorn). For questions
-and discussion, please use the
-[Tern discussion forum](https://discuss.ternjs.net).
+requests on [github](https://github.com/acornjs/acorn).
 
 ## Installation
 
@@ -28,6 +26,24 @@ git clone https://github.com/acornjs/acorn.git
 cd acorn
 npm install
 ```
+## Importing acorn
+
+ESM as well as CommonJS is supported for all 3: `acorn`, `acorn-walk` and `acorn-loose`.
+
+ESM example for `acorn`:
+
+```js
+import * as acorn from "acorn"
+```
+
+CommonJS example for `acorn`:
+
+```js
+let acorn = require("acorn")
+```
+
+ESM is preferred, as it allows better editor auto-completions by offering TypeScript support.
+For this reason, following examples will use ESM imports.
 
 ## Interface
 
@@ -38,8 +54,8 @@ syntax tree object as specified by the [ESTree
 spec](https://github.com/estree/estree).
 
 ```javascript
-let acorn = require("acorn");
-console.log(acorn.parse("1 + 1", {ecmaVersion: 2020}));
+import * as acorn from "acorn"
+console.log(acorn.parse("1 + 1", {ecmaVersion: 2020}))
 ```
 
 When encountering a syntax error, the parser will raise a
@@ -52,23 +68,23 @@ Options are provided by in a second argument, which should be an
 object containing any of these fields (only `ecmaVersion` is
 required):
 
-- **ecmaVersion**: Indicates the ECMAScript version to parse. Must be
-  either 3, 5, 6 (or 2015), 7 (2016), 8 (2017), 9 (2018), 10 (2019),
-  11 (2020), 12 (2021), 13 (2022), 14 (2023), or `"latest"` (the
-  latest the library supports). This influences support for strict
-  mode, the set of reserved words, and support for new syntax
-  features.
+- **ecmaVersion**: Indicates the ECMAScript version to parse. Can be a
+  number, either in year (`2022`) or plain version number (`6`) form,
+  or `"latest"` (the latest the library supports). This influences
+  support for strict mode, the set of reserved words, and support for
+  new syntax features.
 
   **NOTE**: Only 'stage 4' (finalized) ECMAScript features are being
   implemented by Acorn. Other proposed new features must be
   implemented through plugins.
 
 - **sourceType**: Indicate the mode the code should be parsed in. Can be
-  either `"script"` or `"module"`. This influences global strict mode
+  either `"script"`, `"module"` or `"commonjs"`. This influences global strict mode
   and parsing of `import` and `export` declarations.
 
   **NOTE**: If set to `"module"`, then static `import` / `export` syntax
-  will be valid, even if `ecmaVersion` is less than 6.
+  will be valid, even if `ecmaVersion` is less than 6. If set to `"commonjs"`,
+  it is the same as `"script"` except that the top-level scope behaves like a function.
 
 - **onInsertedSemicolon**: If given a callback, that callback will be
   called whenever a missing semicolon is inserted by the parser. The
@@ -100,7 +116,7 @@ required):
   for `ecmaVersion` 2022 and later, `false` for lower versions.
   Setting this option to `true` allows to have top-level `await`
   expressions. They are still not allowed in non-`async` functions,
-  though.
+  though. Setting this option to `true` is not allowed when `sourceType: "commonjs"`.
 
 - **allowSuperOutsideMethod**: By default, `super` outside a method
   raises an error. Set this to `true` to accept such code.
@@ -204,6 +220,13 @@ option is enabled). When the token's type is `tokTypes.eof`, you
 should stop calling the method, since it will keep returning that same
 token forever.
 
+Note that tokenizing JavaScript without parsing it is, in modern
+versions of the language, not really possible due to the way syntax is
+overloaded in ways that can only be disambiguated by the parse
+context. This package applies a bunch of heuristics to try and do a
+reasonable job, but you are advised to use `parse` with the `onToken`
+option instead of this.
+
 In ES6 environment, returned result can be used as any other
 protocol-compliant iterable:
 
@@ -213,7 +236,7 @@ for (let token of acorn.tokenizer(str)) {
 }
 
 // transform code to array of tokens:
-var tokens = [...acorn.tokenizer(str)];
+var tokens = [...acorn.tokenizer(str)]
 ```
 
 **tokTypes** holds an object mapping names to the token type objects
@@ -234,10 +257,10 @@ on the extended version of the class. To extend a parser with plugins,
 you can use its static `extend` method.
 
 ```javascript
-var acorn = require("acorn");
-var jsx = require("acorn-jsx");
-var JSXParser = acorn.Parser.extend(jsx());
-JSXParser.parse("foo(<bar/>)", {ecmaVersion: 2020});
+var acorn = require("acorn")
+var jsx = require("acorn-jsx")
+var JSXParser = acorn.Parser.extend(jsx())
+JSXParser.parse("foo(<bar/>)", {ecmaVersion: 2020})
 ```
 
 The `extend` method takes any number of plugin values, and returns a