webext-active-tab 0.0.0

package/distribution/on-active-tab.d.ts

@@ -0,0 +1,25 @@
+type TabId = number;
+type Origin = string;
+export type ActiveTab = {
+    id: TabId;
+    origin: Origin;
+};
+/**
+ * The list is not guaranteed to be up to date. The activeTab permission might be lost before it's detected.
+ */
+export declare const possiblyActiveTabs: Map<number, string>;
+declare function startActiveTabTracking(): void;
+declare function stopActiveTabTracking(): void;
+export declare const PRIVATE: {
+    startActiveTabTracking: typeof startActiveTabTracking;
+    stopActiveTabTracking: typeof stopActiveTabTracking;
+};
+export declare const onActiveTab: {
+    addListener(callback: (tab: ActiveTab) => void): void;
+    removeListener: (callback: import("simple-event-target").SimpleEventListener<ActiveTab>) => void;
+};
+export declare const onActiveTabLost: {
+    addListener(callback: (tabId: TabId) => void): void;
+    removeListener: (callback: import("simple-event-target").SimpleEventListener<number>) => void;
+};
+export {};

package/distribution/on-active-tab.js

@@ -0,0 +1,87 @@
+import { isScriptableUrl } from 'webext-content-scripts';
+import { isBackground } from 'webext-detect';
+import SimpleEventTarget from 'simple-event-target';
+if (!isBackground()) {
+    throw new Error('This module is only allowed in a background script');
+}
+if (!chrome.runtime.getManifest().permissions?.includes('activeTab')) {
+    throw new Error('The manifest should include the `activeTab` permission for `webext-active-tab` to work');
+}
+const activation = new SimpleEventTarget();
+const deactivation = new SimpleEventTarget();
+const browserAction = chrome.action ?? chrome.browserAction;
+// TODO: use https://github.com/fregante/webext-storage/issues/5
+/**
+ * The list is not guaranteed to be up to date. The activeTab permission might be lost before it's detected.
+ */
+export const possiblyActiveTabs = new Map();
+async function addIfScriptable({ url, id }) {
+    if (id && url
+        // Skip if it already exists. A previous change of origin already cleared this
+        && !possiblyActiveTabs.has(id)
+        // ActiveTab doesn't make sense on non-scriptable URLs as they generally don't have scriptable frames
+        && isScriptableUrl(url)
+    // Note: Do not filter by `isContentScriptRegistered`; `active-tab` also applies to random `executeScript` calls
+    ) {
+        const { origin } = new URL(url);
+        console.debug('activeTab:', id, 'added', { origin });
+        possiblyActiveTabs.set(id, origin);
+        activation.emit({ id, origin });
+    }
+    else {
+        console.debug('activeTab:', id, 'not added', { origin });
+    }
+}
+function dropIfOriginChanged(tabId, { url }) {
+    if (url && possiblyActiveTabs.has(tabId)) {
+        const { origin } = new URL(url);
+        if (possiblyActiveTabs.get(tabId) !== origin) {
+            console.debug('activeTab:', tabId, 'removed because origin changed from', possiblyActiveTabs.get(tabId), 'to', origin);
+            possiblyActiveTabs.delete(tabId);
+        }
+    }
+}
+function altListener(_, tab) {
+    if (tab) {
+        void addIfScriptable(tab);
+    }
+}
+function drop(tabId) {
+    console.debug('activeTab:', tabId, 'removed');
+    possiblyActiveTabs.delete(tabId);
+    deactivation.emit(tabId);
+}
+// https://developer.chrome.com/docs/extensions/mv3/manifest/activeTab/#invoking-activeTab
+function startActiveTabTracking() {
+    browserAction?.onClicked.addListener(addIfScriptable);
+    chrome.contextMenus?.onClicked.addListener(altListener);
+    chrome.commands?.onCommand.addListener(altListener);
+    chrome.tabs.onUpdated.addListener(dropIfOriginChanged);
+    chrome.tabs.onRemoved.addListener(drop);
+}
+function stopActiveTabTracking() {
+    browserAction?.onClicked.removeListener(addIfScriptable);
+    chrome.contextMenus?.onClicked.removeListener(altListener);
+    chrome.commands?.onCommand.removeListener(altListener);
+    chrome.tabs.onUpdated.removeListener(dropIfOriginChanged);
+    chrome.tabs.onRemoved.removeListener(drop);
+    possiblyActiveTabs.clear();
+}
+export const PRIVATE = {
+    startActiveTabTracking,
+    stopActiveTabTracking,
+};
+export const onActiveTab = {
+    addListener(callback) {
+        startActiveTabTracking();
+        activation.subscribe(callback);
+    },
+    removeListener: activation.unsubscribe.bind(activation),
+};
+export const onActiveTabLost = {
+    addListener(callback) {
+        startActiveTabTracking();
+        deactivation.subscribe(callback);
+    },
+    removeListener: deactivation.unsubscribe.bind(deactivation),
+};

package/distribution/register-active-tab-scripts.d.ts

@@ -0,0 +1,8 @@
+import { type RunAt } from 'webext-content-scripts';
+export type ActiveTabContentScript = {
+    css?: string[];
+    js?: string[];
+    matchAboutBlank?: boolean;
+    runAt?: RunAt;
+};
+export default function registerActiveTabScripts(...newScripts: ActiveTabContentScript[]): void;

package/distribution/register-active-tab-scripts.js

@@ -0,0 +1,44 @@
+import { injectContentScript } from 'webext-content-scripts';
+import { onActiveTab, possiblyActiveTabs } from './on-active-tab.js';
+const gotNavigation = typeof chrome === 'object' && 'webNavigation' in chrome;
+const scripts = [];
+async function injectAllFrames({ id: tabId, origin: url }) {
+    if (tabId === undefined) {
+        return;
+    }
+    if (!gotNavigation) {
+        // Without it, we only inject it into the top frame
+        return injectOneFrame({ frameId: 0, url, tabId });
+    }
+    const frames = await chrome.webNavigation.getAllFrames({ tabId });
+    // .map() needed for async loop
+    void frames?.map(async ({ frameId, url }) => injectOneFrame({ frameId, url, tabId }));
+}
+async function injectOneFrame({ tabId, frameId, url }) {
+    const { origin } = new URL(url);
+    // Check origin because the request might be for a frame; cross-origin frames do not receive activeTab
+    if (possiblyActiveTabs.get(tabId) === origin) {
+        console.debug('activeTab: will inject', { tabId, frameId, url });
+        await injectContentScript({ tabId, frameId }, scripts);
+    }
+    else {
+        console.debug('activeTab: won’t inject', { tabId, frameId, url }, { activeTab: possiblyActiveTabs.get(tabId) ?? 'no' });
+    }
+}
+async function tabListener(tabId, { status }, { url }) {
+    // Only status updates are relevant
+    // No URL = no permission
+    if (status === 'loading' && url) {
+        await injectOneFrame({ tabId, url, frameId: 0 });
+    }
+}
+export default function registerActiveTabScripts(...newScripts) {
+    scripts.push(...newScripts);
+    onActiveTab.addListener(injectAllFrames);
+    if (gotNavigation) {
+        chrome.webNavigation.onCommitted.addListener(injectOneFrame);
+    }
+    else {
+        chrome.tabs.onUpdated.addListener(tabListener);
+    }
+}

package/distribution/register.d.ts

@@ -0,0 +1 @@
+export {};

package/distribution/register.js

@@ -0,0 +1,2 @@
+import register from './scripts.js';
+register();

package/distribution/scripts.d.ts

@@ -0,0 +1 @@
+export default function register(): void;

package/distribution/scripts.js

@@ -0,0 +1,47 @@
+import { injectContentScript } from 'webext-content-scripts';
+import { addActiveTabListener, possiblyActiveTabs } from './tracker.js';
+import { isContentScriptRegistered } from './utils.js';
+const gotNavigation = typeof chrome === 'object' && 'webNavigation' in chrome;
+const scripts = chrome.runtime.getManifest().content_scripts;
+async function injectToTabUnlessRegistered({ id: tabId, origin }) {
+    if (tabId === undefined) {
+        return;
+    }
+    const frames = gotNavigation
+        // Only with `webNavigation` we can inject into the frames
+        ? await chrome.webNavigation.getAllFrames({ tabId })
+        // Without it, we only inject it into the top frame
+        : [{ frameId: 0, url: origin }];
+    // .map() needed for async loop
+    void frames?.map(async ({ frameId, url }) => injectIfActive({ frameId, url, tabId }));
+}
+async function injectIfActive({ tabId, frameId, url }) {
+    const { origin } = new URL(url);
+    if (
+    // Check origin because the request might be for a frame; cross-origin frames do not receive activeTab
+    possiblyActiveTabs.get(tabId) === origin
+        // Don't inject if already registered
+        && !(await isContentScriptRegistered(url))) {
+        console.debug('activeTab: will inject', { tabId, frameId, url });
+        await injectContentScript({ tabId, frameId }, scripts);
+    }
+    else {
+        console.debug('activeTab: won’t inject', { tabId, frameId, url }, { activeTab: possiblyActiveTabs.get(tabId) ?? 'no' });
+    }
+}
+async function tabListener(tabId, { status }, { url }) {
+    // Only status updates are relevant
+    // No URL = no permission
+    if (status === 'loading' && url) {
+        await injectIfActive({ tabId, url, frameId: 0 });
+    }
+}
+export default function register() {
+    addActiveTabListener(injectToTabUnlessRegistered);
+    if (gotNavigation) {
+        chrome.webNavigation.onCommitted.addListener(injectIfActive);
+    }
+    else {
+        chrome.tabs.onUpdated.addListener(tabListener);
+    }
+}

package/distribution/tracker.d.ts

@@ -0,0 +1,11 @@
+type TabId = number;
+type Origin = string;
+export type ActiveTab = {
+    id: TabId;
+    origin: Origin;
+};
+export declare const possiblyActiveTabs: Map<number, string>;
+export declare function startActiveTabTracking(): void;
+export declare function stopActiveTabTracking(): void;
+export declare function addActiveTabListener(callback: (tab: ActiveTab) => void): void;
+export {};

package/distribution/tracker.js

@@ -0,0 +1,65 @@
+import { isScriptableUrl } from 'webext-content-scripts';
+import { isBackground } from 'webext-detect';
+import SimpleEventTarget from 'simple-event-target';
+if (!isBackground()) {
+    throw new Error('This module is only allowed in a background script');
+}
+const newActiveTabs = new SimpleEventTarget();
+const browserAction = chrome.action ?? chrome.browserAction;
+// TODO: use webext-storage
+export const possiblyActiveTabs = new Map();
+async function addIfScriptable({ url, id }) {
+    if (id && url
+        // Skip if it already exists. A previous change of origin already cleared this
+        && !possiblyActiveTabs.has(id)
+        // ActiveTab doesn't make sense on non-scriptable URLs as they generally don't have scriptable frames
+        && isScriptableUrl(url)
+    // Note: Do not filter by `isContentScriptRegistered`; `active-tab` also applies to random `executeScript` calls
+    ) {
+        const { origin } = new URL(url);
+        console.debug('activeTab:', id, 'added', { origin });
+        possiblyActiveTabs.set(id, origin);
+        newActiveTabs.emit({ id, origin });
+    }
+    else {
+        console.debug('activeTab:', id, 'not added', { origin });
+    }
+}
+function dropIfOriginChanged(tabId, { url }) {
+    if (url && possiblyActiveTabs.has(tabId)) {
+        const { origin } = new URL(url);
+        if (possiblyActiveTabs.get(tabId) !== origin) {
+            console.debug('activeTab:', tabId, 'removed because origin changed from', possiblyActiveTabs.get(tabId), 'to', origin);
+            possiblyActiveTabs.delete(tabId);
+        }
+    }
+}
+function altListener(_, tab) {
+    if (tab) {
+        void addIfScriptable(tab);
+    }
+}
+function drop(tabId) {
+    console.debug('activeTab:', tabId, 'removed');
+    possiblyActiveTabs.delete(tabId);
+}
+// https://developer.chrome.com/docs/extensions/mv3/manifest/activeTab/#invoking-activeTab
+export function startActiveTabTracking() {
+    browserAction?.onClicked.addListener(addIfScriptable);
+    chrome.contextMenus?.onClicked.addListener(altListener);
+    chrome.commands?.onCommand.addListener(altListener);
+    chrome.tabs.onUpdated.addListener(dropIfOriginChanged);
+    chrome.tabs.onRemoved.addListener(drop);
+}
+export function stopActiveTabTracking() {
+    browserAction?.onClicked.removeListener(addIfScriptable);
+    chrome.contextMenus?.onClicked.removeListener(altListener);
+    chrome.commands?.onCommand.removeListener(altListener);
+    chrome.tabs.onUpdated.removeListener(dropIfOriginChanged);
+    chrome.tabs.onRemoved.removeListener(drop);
+    possiblyActiveTabs.clear();
+}
+export function addActiveTabListener(callback) {
+    startActiveTabTracking();
+    newActiveTabs.listen(callback);
+}

package/distribution/utils.d.ts

@@ -0,0 +1,7 @@
+export declare function isContentScriptStaticallyRegistered(url: string): boolean;
+export declare function isContentScriptDynamicallyRegistered(url: string): Promise<boolean>;
+/**
+Checks whether a URL will have the content scripts automatically injected.
+It returns a promise that resolves with string indicating the type of injection ('static' or 'dynamic') or `false` if it won't be injected on the specified URL.
+*/
+export declare function isContentScriptRegistered(url: string): Promise<'static' | 'dynamic' | false>;

package/distribution/utils.js

@@ -0,0 +1,30 @@
+import { queryAdditionalPermissions } from 'webext-permissions';
+import { patternToRegex } from 'webext-patterns';
+export function isContentScriptStaticallyRegistered(url) {
+    return Boolean(chrome.runtime
+        .getManifest()
+        .content_scripts
+        ?.flatMap(script => script.matches)
+        .some(pattern => patternToRegex(pattern).test(url)));
+}
+export async function isContentScriptDynamicallyRegistered(url) {
+    // Injected by `webext-active-tab`
+    const { origins } = await queryAdditionalPermissions({
+        strictOrigins: false,
+    });
+    // Do not replace the 2 calls above with `permissions.getAll` because it might also include hosts that are permitted by the manifest but have no content script registered
+    return patternToRegex(...origins).test(url);
+}
+/**
+Checks whether a URL will have the content scripts automatically injected.
+It returns a promise that resolves with string indicating the type of injection ('static' or 'dynamic') or `false` if it won't be injected on the specified URL.
+*/
+export async function isContentScriptRegistered(url) {
+    if (isContentScriptStaticallyRegistered(url)) {
+        return 'static';
+    }
+    if (await isContentScriptDynamicallyRegistered(url)) {
+        return 'dynamic';
+    }
+    return false;
+}

package/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Federico Brigante <me@fregante.com> (https://fregante.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,102 @@
+{
+	"name": "webext-active-tab",
+	"version": "0.0.0",
+	"description": "WebExtension module: Automatically registers your `content_scripts` on domains added via `permission.request` or on `activeTab`",
+	"keywords": [
+		"contentscript",
+		"register",
+		"injection",
+		"permissions",
+		"request",
+		"optional_permissions",
+		"host_permissions",
+		"manifest",
+		"new hosts",
+		"chrome",
+		"firefox",
+		"browser",
+		"activetab",
+		"extension"
+	],
+	"repository": "fregante/webext-active-tab",
+	"funding": "https://github.com/sponsors/fregante",
+	"license": "MIT",
+	"author": "Federico Brigante <me@fregante.com> (https://fregante.com)",
+	"type": "module",
+	"exports": {
+		"./on-active-tabs": {
+			"types": "./distribution/on-active-tabs.d.ts",
+			"default": "./distribution/on-active-tabs.js"
+		},
+		"./register-active-tab-scripts": {
+			"types": "./distribution/register-active-tab-scripts.d.ts",
+			"default": "./distribution/register-active-tab-scripts.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"demo:build": "parcel build --no-cache",
+		"demo:watch": "parcel watch --no-cache --no-hmr",
+		"prepack": "tsc --sourceMap false",
+		"lint": "xo",
+		"fix": "xo --fix",
+		"test": "run-p lint build demo:build",
+		"watch": "tsc --watch"
+	},
+	"xo": {
+		"envs": [
+			"browser",
+			"webextensions"
+		],
+		"rules": {
+			"no-implicit-globals": "off",
+			"@typescript-eslint/prefer-nullish-coalescing": "off",
+			"@typescript-eslint/no-implicit-any-catch": "off",
+			"@typescript-eslint/naming-convention": "off",
+			"import/extensions": "off",
+			"import/no-unassigned-import": "off",
+			"unicorn/prefer-top-level-await": "off",
+			"unicorn/prefer-node-protocol": "off",
+			"n/file-extension-in-import": "off"
+		}
+	},
+	"dependencies": {
+		"simple-event-target": "^2.0.0",
+		"webext-content-scripts": "^2.7.2",
+		"webext-detect": "^5.3.2"
+	},
+	"devDependencies": {
+		"@parcel/config-webextension": "^2.13.3",
+		"@sindresorhus/tsconfig": "^7.0.0",
+		"@types/chrome": "^0.0.300",
+		"npm-run-all2": "^7.0.2",
+		"parcel": "^2.13.3",
+		"typescript": "^5.7.3",
+		"xo": "^0.60.0"
+	},
+	"@parcel/resolver-default": {
+		"packageExports": true
+	},
+	"targets": {
+		"main": false,
+		"module": false,
+		"demo": {
+			"source": "./demo-extension/manifest.json",
+			"distDir": "./dist",
+			"sourceMap": {
+				"inline": true
+			},
+			"optimize": false
+		}
+	},
+	"webExt": {
+		"sourceDir": "dist",
+		"run": {
+			"startUrl": [
+				"https://extra-ephiframe.vercel.app/Inject-via-context-menu-please",
+				"https://extra-ephiframe.vercel.app/Inject-via-context-menu-please?iframe=https://ephiframe.vercel.app/Static-inner",
+				"chrome://extensions/"
+			]
+		}
+	}
+}

package/readme.md

@@ -0,0 +1,36 @@
+# webext-active-tab [![npm version](https://img.shields.io/npm/v/webext-active-tab.svg)](https://www.npmjs.com/package/webext-active-tab)
+
+> WebExtension module: Track `activeTab` permission; automatically inject content scripts
+
+The main use case is to ship your extension without `host_permissions` and have the user invoke the extension on click on any website.
+
+Alternatively, consider using [webext-permission-toggle](https://github.com/fregante/webext-permission-toggle) and [webext-dynamic-content-scripts](https://github.com/fregante/webext-dynamic-content-scripts) to permanently receive access to certain hosts and automatically register content scripts on it.
+
+## Install
+
+```sh
+npm install webext-active-tab
+```
+
+## Usage
+
+This package exports various utilities, just import what you need.
+
+- [on-active-tab](./source/on-active-tab.md) - Watch when tabs receive `activeTab`
+- [register-active-tab-scripts](./source/register-active-tab-scripts.md) - Automatically inject scripts into tabs with `activeTab`
+
+> [!NOTE]
+> Firefox has some limitations:
+> - `activeTab` seems to be lost after a reload
+> - further `contextMenu` clicks receive a moz-extension URL rather than the current page’s URL
+
+## Related
+
+- [webext-dynamic-content-scripts](https://github.com/fregante/webext-dynamic-content-scripts) - Automatically registers your `content_scripts` on domains added via `permission.request`.
+- [webext-events](https://github.com/fregante/webext-events) - High-level events and utilities for events in Web Extensions
+- [Awesome-WebExtensions](https://github.com/fregante/Awesome-WebExtensions) - A curated list of awesome resources for WebExtensions development.
+- [More…](https://github.com/fregante/webext-fun)
+
+## License
+
+MIT © [Federico Brigante](https://fregante.com)