@types/chrome 0.1.25 → 0.1.27

chrome/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for chrome (https://developer.chrome.com/
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/chrome.
 
 ### Additional Details
- * Last updated: Mon, 27 Oct 2025 18:40:39 GMT
+ * Last updated: Mon, 27 Oct 2025 20:34:59 GMT
  * Dependencies: [@types/filesystem](https://npmjs.com/package/@types/filesystem), [@types/har-format](https://npmjs.com/package/@types/har-format)
 
 # Credits

chrome/index.d.ts

@@ -11869,7 +11869,7 @@ declare namespace chrome {
      * Permissions: "topSites"
      */
     export namespace topSites {
-        /** An object encapsulating a most visited URL, such as the URLs on the new tab page. */
+        /** An object encapsulating a most visited URL, such as the default shortcuts on the new tab page. */
         export interface MostVisitedURL {
             /** The most visited URL. */
             url: string;
@@ -11877,14 +11877,13 @@ declare namespace chrome {
             title: string;
         }
 
-        /** Gets a list of top sites. */
-        export function get(callback: (data: MostVisitedURL[]) => void): void;
-
         /**
          * Gets a list of top sites.
-         * @return The `get` method provides its result via callback or returned as a `Promise` (MV3 only).
+         *
+         * Can return its result via Promise in Manifest V3 or later since Chrome 96.
          */
         export function get(): Promise<MostVisitedURL[]>;
+        export function get(callback: (data: MostVisitedURL[]) => void): void;
     }
 
     ////////////////////
@@ -12471,27 +12470,35 @@ declare namespace chrome {
      * @since Chrome 43
      */
     export namespace wallpaper {
+        /**
+         * The supported wallpaper layouts.
+         * @since Chrome 44
+         */
+        export enum WallpaperLayout {
+            STRETCH = "STRETCH",
+            CENTER = "CENTER",
+            CENTER_CROPPED = "CENTER_CROPPED",
+        }
+
         export interface WallpaperDetails {
-            /** Optional. The jpeg or png encoded wallpaper image. */
+            /** The jpeg or png encoded wallpaper image as an ArrayBuffer. */
             data?: ArrayBuffer | undefined;
-            /** Optional. The URL of the wallpaper to be set. */
+            /** The URL of the wallpaper to be set (can be relative). */
             url?: string | undefined;
-            /**
-             * The supported wallpaper layouts.
-             * One of: "STRETCH", "CENTER", or "CENTER_CROPPED"
-             */
-            layout: "STRETCH" | "CENTER" | "CENTER_CROPPED";
+            /** The supported wallpaper layouts. */
+            layout: `${WallpaperLayout}`;
             /** The file name of the saved wallpaper. */
             filename: string;
-            /** Optional. True if a 128x60 thumbnail should be generated. */
+            /** True if a 128x60 thumbnail should be generated. Layout and ratio are not supported yet. */
             thumbnail?: boolean | undefined;
         }
 
         /**
          * Sets wallpaper to the image at url or wallpaperData with the specified layout
-         * @param callback
-         * Optional parameter thumbnail: The jpeg encoded wallpaper thumbnail. It is generated by resizing the wallpaper to 128x60.
+         *
+         * Can return its result via Promise in Manifest V3 or later since Chrome 96.
          */
+        export function setWallpaper(details: WallpaperDetails): Promise<ArrayBuffer | undefined>;
         export function setWallpaper(details: WallpaperDetails, callback: (thumbnail?: ArrayBuffer) => void): void;
     }
 
@@ -14442,133 +14449,165 @@ declare namespace chrome {
      * @since Chrome 120, MV3
      */
     export namespace userScripts {
-        /**
-         * Execution environment for a user script.
-         */
-        export type ExecutionWorld = "MAIN" | "USER_SCRIPT";
+        /** The JavaScript world for a user script to execute within. */
+        export enum ExecutionWorld {
+            /** Specifies the execution environment of the DOM, which is the execution environment shared with the host page's JavaScript. */
+            MAIN = "MAIN",
+            /** Specifies the execution environment that is specific to user scripts and is exempt from the page's CSP. */
+            USER_SCRIPT = "USER_SCRIPT",
+        }
 
         /** @since Chrome 135 */
-        export interface InjectionResult {
-            /** The document associated with the injection. */
-            documentId: string;
-            /** The error, if any. `error` and `result` are mutually exclusive. */
-            error?: string;
-            /** The frame associated with the injection. */
-            frameId: number;
-            /** The result of the script execution. */
-            result: any;
-        }
+        export type InjectionResult<T = unknown> =
+            & {
+                /** The document associated with the injection. */
+                documentId: string;
+                /** The frame associated with the injection. */
+                frameId: number;
+            }
+            & (
+                | {
+                    /** The error, if any */
+                    error?: never;
+                    /** The result of the script execution. */
+                    result: T;
+                }
+                | {
+                    /** The error, if any */
+                    error: string;
+                    /** The result of the script execution. */
+                    result?: never;
+                }
+            );
 
         export interface WorldProperties {
             /** Specifies the world csp. The default is the `ISOLATED` world csp. */
-            csp?: string;
-            /** Specifies whether messaging APIs are exposed. The default is false.*/
-            messaging?: boolean;
+            csp?: string | undefined;
+            /** Specifies whether messaging APIs are exposed. The default is `false`.*/
+            messaging?: boolean | undefined;
             /**
              * Specifies the ID of the specific user script world to update. If not provided, updates the properties of the default user script world. Values with leading underscores (`_`) are reserved.
              * @since Chrome 133
              */
-            worldId?: string;
+            worldId?: string | undefined;
         }
 
         export interface UserScriptFilter {
-            ids?: string[];
+            /** {@link getScripts} only returns scripts with the IDs specified in this list. */
+            ids?: string[] | undefined;
         }
 
-        /** @since Chrome 135 */
-        export interface InjectionTarget {
-            /** Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if `frameIds` is specified. */
-            allFrames?: boolean;
-            /** The IDs of specific documentIds to inject into. This must not be set if `frameIds` is set. */
-            documentIds?: string[];
-            /** The IDs of specific frames to inject into. */
-            frameIds?: number[];
-            /** The ID of the tab into which to inject. */
-            tabId: number;
-        }
+        // /** @since Chrome 135 */
+        export type InjectionTarget =
+            & {
+                /** The ID of the tab into which to inject. */
+                tabId: number;
+            }
+            & (
+                | {
+                    /** Whether the script should inject into all frames within the tab. Defaults to false. */
+                    allFrames?: boolean | undefined;
+                    /** The IDs of specific documentIds to inject into. */
+                    documentIds?: never;
+                    /** The IDs of specific frames to inject into. */
+                    frameIds?: never;
+                }
+                | {
+                    /** Whether the script should inject into all frames within the tab. Defaults to false. */
+                    allFrames?: false | undefined;
+                    /** The IDs of specific documentIds to inject into. */
+                    documentIds?: never;
+                    /** The IDs of specific frames to inject into. */
+                    frameIds: number[] | undefined;
+                }
+                | {
+                    /** Whether the script should inject into all frames within the tab. Defaults to false. */
+                    allFrames?: false | undefined;
+                    /** The IDs of specific documentIds to inject into. */
+                    documentIds?: string[] | undefined;
+                    /** The IDs of specific frames to inject into. */
+                    frameIds?: never;
+                }
+            );
 
         export interface RegisteredUserScript {
             /** If true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched. */
-            allFrames?: boolean;
+            allFrames?: boolean | undefined;
             /** Specifies wildcard patterns for pages this user script will NOT be injected into. */
-            excludeGlobs?: string[];
+            excludeGlobs?: string[] | undefined;
             /**Excludes pages that this user script would otherwise be injected into. See Match Patterns for more details on the syntax of these strings. */
-            excludeMatches?: string[];
+            excludeMatches?: string[] | undefined;
             /** The ID of the user script specified in the API call. This property must not start with a '_' as it's reserved as a prefix for generated script IDs. */
             id: string;
             /** Specifies wildcard patterns for pages this user script will be injected into. */
-            includeGlobs?: string[];
+            includeGlobs?: string[] | undefined;
             /** The list of ScriptSource objects defining sources of scripts to be injected into matching pages. This property must be specified for {@link register}, and when specified it must be a non-empty array.*/
             js: ScriptSource[];
-            /** Specifies which pages this user script will be injected into. See Match Patterns for more details on the syntax of these strings. This property must be specified for ${ref:register}. */
-            matches?: string[];
-            /** Specifies when JavaScript files are injected into the web page. The preferred and default value is document_idle */
-            runAt?: extensionTypes.RunAt;
+            /** Specifies which pages this user script will be injected into. See Match Patterns for more details on the syntax of these strings. This property must be specified for {@link register}. */
+            matches?: string[] | undefined;
+            /** Specifies when JavaScript files are injected into the web page. The preferred and default value is `document_idle` */
+            runAt?: extensionTypes.RunAt | undefined;
             /** The JavaScript execution environment to run the script in. The default is `USER_SCRIPT` */
-            world?: ExecutionWorld;
+            world?: `${ExecutionWorld}` | undefined;
             /**
              * Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid if `world` is omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are reserved.
              * @since Chrome 133
              */
-            worldId?: string;
+            worldId?: string | undefined;
         }
 
         /** @since Chrome 135 */
         export interface UserScriptInjection {
             /** Whether the injection should be triggered in the target as soon as possible. Note that this is not a guarantee that injection will occur prior to page load, as the page may have already loaded by the time the script reaches the target. */
-            injectImmediately?: boolean;
+            injectImmediately?: boolean | undefined;
             /** The list of ScriptSource objects defining sources of scripts to be injected into the target. */
-            js: ScriptSource[];
+            js: [ScriptSource, ...ScriptSource[]];
             /** Details specifying the target into which to inject the script. */
             target: InjectionTarget;
             /** The JavaScript "world" to run the script in. The default is `USER_SCRIPT`. */
-            world?: ExecutionWorld;
+            world?: `${ExecutionWorld}` | undefined;
             /** Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid if `world` is omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are reserved. */
-            worldId?: string;
+            worldId?: string | undefined;
         }
 
-        /**
-         * Properties for a script source.
-         */
-        export interface ScriptSource {
-            /** A string containing the JavaScript code to inject. Exactly one of file or code must be specified. */
-            code?: string;
-            /** The path of the JavaScript file to inject relative to the extension's root directory. Exactly one of file or code must be specified. */
-            file?: string;
-        }
+        export type ScriptSource = {
+            /** A string containing the JavaScript code to inject. */
+            code: string;
+            /** The path of the JavaScript file to inject relative to the extension's root directory. */
+            file?: undefined;
+        } | {
+            /** A string containing the JavaScript code to inject. */
+            code?: undefined;
+            /** The path of the JavaScript file to inject relative to the extension's root directory. */
+            file: string;
+        };
 
         /**
          * Configures the `USER_SCRIPT` execution environment.
          *
-         * @param properties - Contains the user script world configuration.
-         * @returns A Promise that resolves with the same type that is passed to the callback.
+         * Can return its result via Promise.
+         * @param properties Contains the user script world configuration.
          */
         export function configureWorld(properties: WorldProperties): Promise<void>;
-        /**
-         * Configures the `USER_SCRIPT` execution environment.
-         *
-         * @param properties - Contains the user script world configuration.
-         * @param callback - Callback function to be executed after configuring the world.
-         */
         export function configureWorld(properties: WorldProperties, callback: () => void): void;
 
         /**
          * Returns all dynamically-registered user scripts for this extension.
          *
-         * @param filter - If specified, this method returns only the user scripts that match it.
-         * @returns A Promise that resolves with the same type that is passed to the callback.
+         * Can return its result via Promise.
+         * @param filter If specified, this method returns only the user scripts that match it.
          */
         export function getScripts(filter?: UserScriptFilter): Promise<RegisteredUserScript[]>;
-        /**
-         * Returns all dynamically-registered user scripts for this extension.
-         *
-         * @param filter - If specified, this method returns only the user scripts that match it.
-         * @param callback - Callback function to be executed after getting user scripts.
-         */
-        export function getScripts(filter: UserScriptFilter, callback: (scripts: RegisteredUserScript[]) => void): void;
+        export function getScripts(callback: (scripts: RegisteredUserScript[]) => void): void;
+        export function getScripts(
+            filter: UserScriptFilter | undefined,
+            callback: (scripts: RegisteredUserScript[]) => void,
+        ): void;
 
         /**
          * Retrieves all registered world configurations.
+         *
+         * Can return its result via Promise.
          * @since Chrome 133
          */
         export function getWorldConfigurations(): Promise<WorldProperties[]>;
@@ -14576,24 +14615,23 @@ declare namespace chrome {
 
         /**
          * Injects a script into a target context. By default, the script will be run at `document_idle`, or immediately if the page has already loaded. If the `injectImmediately` property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value.
+         *
+         * Can return its result via Promise.
          * @since Chrome 135
          */
-        export function execute(injection: UserScriptInjection): Promise<InjectionResult[]>;
-        export function execute(injection: UserScriptInjection, callback: (result: InjectionResult[]) => void): void;
+        export function execute<T>(injection: UserScriptInjection): Promise<InjectionResult<T>[]>;
+        export function execute<T>(
+            injection: UserScriptInjection,
+            callback: (result: InjectionResult<T>[]) => void,
+        ): void;
 
         /**
          * Registers one or more user scripts for this extension.
          *
+         * Can return its result via Promise.
          * @param scripts - Contains a list of user scripts to be registered.
-         * @returns A Promise that resolves with the same type that is passed to the callback.
          */
         export function register(scripts: RegisteredUserScript[]): Promise<void>;
-        /**
-         * Registers one or more user scripts for this extension.
-         *
-         * @param scripts - Contains a list of user scripts to be registered.
-         * @param callback - Callback function to be executed after registering user scripts.
-         */
         export function register(scripts: RegisteredUserScript[], callback: () => void): void;
 
         /**
@@ -14601,41 +14639,26 @@ declare namespace chrome {
          * @param worldId The ID of the user script world to reset. If omitted, resets the default world's configuration.
          */
         export function resetWorldConfiguration(worldId?: string): Promise<void>;
-        export function resetWorldConfiguration(worldId: string, callback: () => void): void;
         export function resetWorldConfiguration(callback: () => void): void;
+        export function resetWorldConfiguration(worldId: string | undefined, callback: () => void): void;
 
         /**
          * Unregisters all dynamically-registered user scripts for this extension.
          *
-         * @param filter - If specified, this method unregisters only the user scripts that match it.
-         * @returns A Promise that resolves with the same type that is passed to the callback.
+         * Can return its result via Promise.
+         * @param filter If specified, this method unregisters only the user scripts that match it.
          */
         export function unregister(filter?: UserScriptFilter): Promise<void>;
-        /**
-         * Unregisters all dynamically-registered user scripts for this extension.
-         *
-         * @param filter - If specified, this method unregisters only the user scripts that match it.
-         * @param callback - Callback function to be executed after unregistering user scripts.
-         */
-        export function unregister(filter: UserScriptFilter, callback: () => void): void;
+        export function unregister(callback: () => void): void;
+        export function unregister(filter: UserScriptFilter | undefined, callback: () => void): void;
 
         /**
          * Updates one or more user scripts for this extension.
          *
-         * @param scripts - Contains a list of user scripts to be updated. A property is only updated for the existing script
-         *                  if it is specified in this object. If there are errors during script parsing/file validation, or if
-         *                  the IDs specified do not correspond to a fully registered script, then no scripts are updated.
-         * @returns A Promise that resolves with the same type that is passed to the callback.
+         * Can return its result via Promise.
+         * @param scripts Contains a list of user scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated.
          */
         export function update(scripts: RegisteredUserScript[]): Promise<void>;
-        /**
-         * Updates one or more user scripts for this extension.
-         *
-         * @param scripts - Contains a list of user scripts to be updated. A property is only updated for the existing script
-         *                  if it is specified in this object. If there are errors during script parsing/file validation, or if
-         *                  the IDs specified do not correspond to a fully registered script, then no scripts are updated.
-         * @param callback - Callback function to be executed after updating user scripts.
-         */
         export function update(scripts: RegisteredUserScript[], callback: () => void): void;
     }
 }

chrome/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/chrome",
-    "version": "0.1.25",
+    "version": "0.1.27",
     "description": "TypeScript definitions for chrome",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/chrome",
     "license": "MIT",
@@ -94,6 +94,6 @@
         "@types/har-format": "*"
     },
     "peerDependencies": {},
-    "typesPublisherContentHash": "d216a6c8c00a765cff5c13cda2f955a491576cb4cf67da012fc054017600a879",
+    "typesPublisherContentHash": "855bc18cd67fbe7ca35c8d69bffa87a3a938f61821b97032b7fc5ef9613bd1ce",
     "typeScriptVersion": "5.2"
 }