@midra/webext 0.0.0-stage → 0.0.1

package/dist/index.js

@@ -0,0 +1,738 @@
+//#region src/paths.ts
+const LINKED_TAB_ID_NAME = "_webext_linked_tab_id";
+const POPOUT_NAME = "_webext_popout";
+const ambiguousRelativePath = /^(?:\/|[^/]*:)/;
+function isExtensionUrl(url, extensionUrl) {
+	return url.protocol === extensionUrl.protocol && url.host === extensionUrl.host;
+}
+/** 外部URLを拒否し、拡張ルートを基準にページのURLを解決する。 */
+function resolveExtensionPath(path, extensionUrl) {
+	if (typeof path !== "string" || !path.trim()) throw new TypeError("A non-empty extension page path is required");
+	const target = new URL(path, extensionUrl);
+	if (!isExtensionUrl(target, extensionUrl)) throw new TypeError("Path must point to a page in this extension");
+	return target;
+}
+function normalizeExtensionPath(path, extensionUrl) {
+	const target = resolveExtensionPath(path, extensionUrl);
+	const relativePath = target.pathname.slice(1);
+	return `${ambiguousRelativePath.test(relativePath) ? `.${target.pathname}` : relativePath}${target.search}${target.hash}`;
+}
+//#endregion
+//#region src/context.ts
+function detectContext(api, url, extensionPage, extensionUrl) {
+	if (typeof ServiceWorkerGlobalScope !== "undefined" && globalThis instanceof ServiceWorkerGlobalScope) return "background";
+	if (typeof window !== "undefined" && api.extension?.getBackgroundPage?.() === window) return "background";
+	if (url && !extensionPage) return "content-script";
+	if (!extensionPage) return null;
+	const manifest = api.runtime.getManifest();
+	const matches = (path) => !!path && url?.pathname === new URL(path, extensionUrl).pathname;
+	if (matches(manifest.action?.default_popup)) return "popup";
+	if (matches(manifest.side_panel?.default_path ?? manifest.sidebar_action?.default_panel)) return "sidepanel";
+	return null;
+}
+function createContext(api, extensionUrl, options) {
+	const href = options.url ?? globalThis.location?.href;
+	const url = href ? new URL(href) : void 0;
+	const extensionPage = !!url && isExtensionUrl(url, extensionUrl);
+	const rawTabId = extensionPage ? url?.searchParams.get(LINKED_TAB_ID_NAME) : null;
+	const parsed = rawTabId?.trim() ? Number(rawTabId) : NaN;
+	const linkedTabId = Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+	return Object.freeze({
+		LINKED_TAB_ID_NAME,
+		browser: options.browser ?? (extensionUrl.protocol === "moz-extension:" ? "firefox" : extensionUrl.protocol === "chrome-extension:" ? "chrome" : "unknown"),
+		type: options.context === void 0 ? detectContext(api, url, extensionPage, extensionUrl) : options.context,
+		linkedTabId,
+		isPopout: extensionPage && (url?.searchParams.get("_webext_popout") === "1" || linkedTabId !== null)
+	});
+}
+//#endregion
+//#region src/facade.ts
+/** グローバルAPIを変更せず、ネイティブメソッドの呼び出し元を維持する。 */
+function facade(native, extra) {
+	const target = Object.assign(Object.create(null), extra);
+	const bound = /* @__PURE__ */ new Map();
+	return new Proxy(target, {
+		get(target, key, receiver) {
+			if (Object.hasOwn(target, key)) return Reflect.get(target, key, receiver);
+			const value = Reflect.get(native, key, native);
+			if (typeof value !== "function") return value;
+			let entry = bound.get(key);
+			if (!entry || entry.original !== value) {
+				entry = {
+					original: value,
+					value: value.bind(native)
+				};
+				bound.set(key, entry);
+			}
+			return entry.value;
+		},
+		has(target, key) {
+			return Reflect.has(target, key) || Reflect.has(native, key);
+		},
+		ownKeys(target) {
+			return [.../* @__PURE__ */ new Set([...Reflect.ownKeys(native), ...Reflect.ownKeys(target)])];
+		},
+		getOwnPropertyDescriptor(target, key) {
+			return Reflect.getOwnPropertyDescriptor(target, key) ?? (Reflect.has(native, key) ? {
+				configurable: true,
+				enumerable: true,
+				get: () => Reflect.get(native, key, native)
+			} : void 0);
+		}
+	});
+}
+/** 初回のアクセスまで初期化を遅延し、初期化後と同じプロパティ参照を提供する。 */
+function lazyFacade(initialize) {
+	let instance;
+	const getInstance = () => instance ??= initialize();
+	return new Proxy({}, {
+		get(_target, key) {
+			return Reflect.get(getInstance(), key);
+		},
+		set(_target, key, value) {
+			return Reflect.set(getInstance(), key, value);
+		},
+		has(_target, key) {
+			return Reflect.has(getInstance(), key);
+		},
+		ownKeys() {
+			return Reflect.ownKeys(getInstance());
+		},
+		getOwnPropertyDescriptor(_target, key) {
+			const descriptor = Reflect.getOwnPropertyDescriptor(getInstance(), key);
+			return descriptor && {
+				...descriptor,
+				configurable: true
+			};
+		}
+	});
+}
+//#endregion
+//#region src/errors.ts
+/**
+* 現在のブラウザ・実行コンテキストに、操作に必要なAPIや機能がない場合のエラー。
+*
+* @remarks
+* 権限不足などのネイティブエラーを一律にこの型へ変換するものではありません。
+* `StorageHelpers.watch()` / `MessageChannel.handle()` では同期的に送出し、`MessageChannel.send()` など
+* Promiseを返す操作では拒否理由になります。捕捉方法は呼び出すAPIに従ってください。
+*/
+var UnsupportedOperationError = class extends Error {
+	operation;
+	/**
+	* 利用できない操作名を含むエラーを作成します。
+	* @param operation - ライブラリ内の操作識別子（例: `storage.watch`）。
+	*/
+	constructor(operation) {
+		super(`webext: ${operation} is unavailable in this browser or context`);
+		this.operation = operation;
+		this.name = "UnsupportedOperationError";
+	}
+};
+/**
+* メッセージの応答待機が送信側の期限を超過した場合のエラー。
+*
+* @remarks
+* `channel.send()` のPromiseの拒否理由です。受信側の処理やネイティブ通信が停止したことは意味しません。
+* 不正な待機上限の指定はこの型ではなく `TypeError` になります。
+*/
+var MessageTimeoutError = class extends Error {
+	timeoutMs;
+	/**
+	* 応答待機の上限を含むエラーを作成します。
+	* @param timeoutMs - 超過した待機上限（ミリ秒）。このコンストラクター自体は値を検証しません。
+	*/
+	constructor(timeoutMs) {
+		super(`webext: message did not respond within ${timeoutMs}ms`);
+		this.timeoutMs = timeoutMs;
+		this.name = "MessageTimeoutError";
+	}
+};
+/**
+* 受信側のハンドラーの失敗を送信側へ伝えるエラー。
+*
+* @remarks
+* ハンドラーの同期例外・Promiseの拒否・応答のJSON化失敗は、`channel.send()` のPromiseをこの型で拒否します。
+* `name` は `RemoteError`、元の名前は `remoteName`、失敗内容は継承した `message` に保持します。
+* 元の例外オブジェクト・スタック・独自プロパティは転送しません。Error以外の例外値は名前を `Error` として
+* 文字列化し、文字列化も失敗した場合は `Error` / `Remote handler failed` にフォールバックします。
+*/
+var RemoteError = class extends Error {
+	remoteName;
+	/**
+	* 受信側から転送された名前とメッセージでエラーを作成します。
+	* @param message - 受信側のエラーメッセージ、または例外値を文字列化した内容。
+	* @param remoteName - 受信側の例外名。名前を取得できない場合は `Error`。
+	*/
+	constructor(message, remoteName) {
+		super(message);
+		this.remoteName = remoteName;
+		this.name = "RemoteError";
+	}
+};
+/**
+* タブIDが非負の安全な整数であることだけを検証します。
+* @param id - 検証するタブID。タブの存在やアクセス可否は確認しません。
+* @returns 戻り値はありません。
+* @throws {TypeError} 非負の安全な整数でなければ同期的に送出します。
+* @internal
+*/
+function assertTabId(id) {
+	if (!Number.isSafeInteger(id) || id < 0) throw new TypeError("Invalid tab ID");
+}
+//#endregion
+//#region src/messaging/serialization.ts
+/** JSON に限定し、Chrome と Firefox のペイロードの扱いを統一します。 */
+function encode(value) {
+	if (value === void 0) return null;
+	const snapshots = /* @__PURE__ */ new WeakMap();
+	const visit = (item, ancestors) => {
+		if (item === null || typeof item === "string" || typeof item === "boolean") return item;
+		if (typeof item === "number" && Number.isFinite(item)) return item;
+		if (typeof item !== "object" || item === null) throw new TypeError("Messages must contain JSON-compatible values");
+		if (ancestors.has(item)) throw new TypeError("Messages must not contain cycles");
+		const cached = snapshots.get(item);
+		if (cached !== void 0) return cached;
+		const isArray = Array.isArray(item);
+		const prototype = Object.getPrototypeOf(item);
+		if (!isArray && prototype !== Object.prototype && prototype !== null) throw new TypeError("Messages must use plain objects and arrays");
+		ancestors.add(item);
+		let snapshot;
+		if (isArray) {
+			const array = [];
+			const length = item.length;
+			for (let index = 0; index < length; index++) array.push(index in item ? visit(item[index], ancestors) : null);
+			snapshot = array;
+		} else {
+			const object = Object.create(null);
+			for (const key of Object.keys(item)) {
+				const child = item[key];
+				if (child !== void 0) object[key] = visit(child, ancestors);
+			}
+			snapshot = object;
+		}
+		ancestors.delete(item);
+		snapshots.set(item, snapshot);
+		return snapshot;
+	};
+	return JSON.parse(JSON.stringify(visit(value, /* @__PURE__ */ new Set())));
+}
+function normalizeError(error) {
+	try {
+		return error instanceof Error ? {
+			name: String(error.name),
+			message: String(error.message)
+		} : {
+			name: "Error",
+			message: String(error)
+		};
+	} catch {
+		return {
+			name: "Error",
+			message: "Remote handler failed"
+		};
+	}
+}
+//#endregion
+//#region src/messaging/transport.ts
+const MAX_TIMEOUT_MS = 2147483647;
+async function sendMessage(api, name, type, request, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMEOUT_MS) throw new TypeError(`timeoutMs must be positive, finite and at most ${MAX_TIMEOUT_MS}`);
+	if (options.signal?.aborted) throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+	if (options.tabId !== void 0) assertTabId(options.tabId);
+	if (options.tabId === void 0 && (options.frameId !== void 0 || options.documentId !== void 0)) throw new TypeError("frameId/documentId requires tabId");
+	const message = {
+		__webext_rpc__: 1,
+		channel: name,
+		type,
+		payload: encode(request),
+		empty: request === void 0
+	};
+	const send = () => {
+		if (options.tabId === void 0) return api.runtime.sendMessage(message);
+		if (!api.tabs?.sendMessage) throw new UnsupportedOperationError("messaging.send to tab");
+		const target = {
+			...options.frameId === void 0 ? {} : { frameId: options.frameId },
+			...options.documentId === void 0 ? {} : { documentId: options.documentId }
+		};
+		return api.tabs.sendMessage(options.tabId, message, target);
+	};
+	let timer;
+	let onAbort;
+	try {
+		const response = await Promise.race([send(), new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(new MessageTimeoutError(timeoutMs)), timeoutMs);
+			if (options.signal) {
+				onAbort = () => reject(options.signal?.reason ?? new DOMException("Aborted", "AbortError"));
+				options.signal.addEventListener("abort", onAbort, { once: true });
+				if (options.signal.aborted) onAbort();
+			}
+		})]);
+		if (response?.__webext_rpc__ !== 1 || typeof response.ok !== "boolean") throw new Error(`No compatible response for ${name}:${type}`);
+		if (!response.ok) throw new RemoteError(response.error?.message ?? "Remote handler failed", response.error?.name ?? "Error");
+		return response.empty ? void 0 : response.value;
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+		if (onAbort) options.signal?.removeEventListener("abort", onAbort);
+	}
+}
+//#endregion
+//#region src/messaging/index.ts
+function createMessaging(api) {
+	const channels = /* @__PURE__ */ new Map();
+	const routes = /* @__PURE__ */ new Map();
+	let listening = false;
+	let factoryDisposed = false;
+	const listener = (message, sender, sendResponse) => {
+		if (!sendResponse || !message || typeof message !== "object") return false;
+		const envelope = message;
+		if (envelope.__webext_rpc__ !== 1 || typeof envelope.channel !== "string" || typeof envelope.type !== "string" || sender.id !== api.runtime.id) return false;
+		const handler = routes.get(envelope.channel)?.get(envelope.type);
+		if (!handler) return false;
+		(async () => {
+			try {
+				const result = await handler(envelope.empty === true ? void 0 : envelope.payload, sender);
+				sendResponse({
+					__webext_rpc__: 1,
+					ok: true,
+					value: encode(result),
+					empty: result === void 0
+				});
+			} catch (error) {
+				sendResponse({
+					__webext_rpc__: 1,
+					ok: false,
+					error: normalizeError(error)
+				});
+			}
+		})();
+		return true;
+	};
+	const removeRoute = (name, handlers) => {
+		if (routes.get(name) !== handlers) return;
+		routes.delete(name);
+		if (!routes.size && listening) {
+			api.runtime.onMessage.removeListener(listener);
+			listening = false;
+		}
+	};
+	return {
+		channel(name) {
+			if (factoryDisposed) throw new Error("Messaging is disposed");
+			if (!name.trim()) throw new TypeError("Message channel name must not be empty");
+			const cached = channels.get(name);
+			if (cached) return cached;
+			const handlers = /* @__PURE__ */ new Map();
+			let disposed = false;
+			const channel = {
+				send(type, request, options = {}) {
+					if (disposed) return Promise.reject(/* @__PURE__ */ new Error("Message channel is disposed"));
+					return sendMessage(api, name, type, request, options);
+				},
+				handle(type, handler) {
+					if (disposed) throw new Error("Message channel is disposed");
+					if (handlers.has(type)) throw new Error(`A handler for ${name}:${type} is already registered`);
+					if (!api.runtime.onMessage) throw new UnsupportedOperationError("messaging.handle");
+					handlers.set(type, handler);
+					routes.set(name, handlers);
+					if (!listening) {
+						api.runtime.onMessage.addListener(listener);
+						listening = true;
+					}
+					let stopped = false;
+					return () => {
+						if (stopped) return;
+						stopped = true;
+						if (handlers.get(type) === handler) handlers.delete(type);
+						if (!handlers.size) removeRoute(name, handlers);
+					};
+				},
+				dispose() {
+					if (disposed) return;
+					removeRoute(name, handlers);
+					handlers.clear();
+					disposed = true;
+					channels.delete(name);
+				}
+			};
+			channels.set(name, channel);
+			return channel;
+		},
+		dispose() {
+			if (factoryDisposed) return;
+			factoryDisposed = true;
+			for (const channel of channels.values()) channel.dispose();
+		}
+	};
+}
+//#endregion
+//#region src/popout.ts
+function createPopout(api, extensionUrl, getTargetId) {
+	async function resolveTabId(options) {
+		if (options.tabId === null) return null;
+		if (options.tabId !== void 0) {
+			assertTabId(options.tabId);
+			return options.tabId;
+		}
+		return await getTargetId() ?? null;
+	}
+	async function openPopout(path, options = {}) {
+		if (!api.windows) throw new UnsupportedOperationError("popout windows");
+		const target = resolveExtensionPath(path, extensionUrl);
+		const { tabId: _requestedTabId, ...createData } = options;
+		const tabId = await resolveTabId(options);
+		target.searchParams.set(POPOUT_NAME, "1");
+		target.searchParams.delete(LINKED_TAB_ID_NAME);
+		if (tabId !== null) target.searchParams.set(LINKED_TAB_ID_NAME, String(tabId));
+		return api.windows.create({
+			...createData,
+			type: "popup",
+			url: target.href
+		});
+	}
+	return {
+		resolveTabId,
+		openPopout
+	};
+}
+//#endregion
+//#region src/disposables.ts
+/** 登録した解除処理を一度だけ実行し、不要になった参照を取り除く。 */
+function createDisposables() {
+	const disposers = /* @__PURE__ */ new Set();
+	return {
+		add(cleanup) {
+			let active = true;
+			const dispose = () => {
+				if (!active) return;
+				active = false;
+				disposers.delete(dispose);
+				cleanup();
+			};
+			disposers.add(dispose);
+			return dispose;
+		},
+		dispose() {
+			for (const dispose of [...disposers]) dispose();
+		}
+	};
+}
+//#endregion
+//#region src/side.ts
+const WINDOW_ID_CURRENT = -2;
+function createSide(api, helpers) {
+	const panel = api.sidePanel;
+	const sidebar = panel ? void 0 : api.sidebarAction;
+	const disposers = createDisposables();
+	const capabilities = Object.freeze({
+		open: !!(panel?.open || sidebar?.open),
+		close: !!(panel?.close || sidebar?.close),
+		path: !!(panel?.getOptions && panel.setOptions || sidebar),
+		isOpen: sidebar?.isOpen ? "native" : panel && api.runtime?.getContexts && api.windows?.getCurrent ? "document" : false,
+		targetedOpen: !!panel?.open,
+		actionClick: !!api.action?.onClicked && !!(panel?.open || sidebar?.open)
+	});
+	function validateTarget(target) {
+		if (target.tabId !== void 0) assertTabId(target.tabId);
+		if (target.windowId !== void 0 && (!Number.isSafeInteger(target.windowId) || target.windowId < 0 && target.windowId !== WINDOW_ID_CURRENT)) throw new TypeError("Invalid window ID");
+	}
+	function requireCurrentWindow(target) {
+		if (target.tabId !== void 0 || target.windowId !== void 0 && target.windowId !== WINDOW_ID_CURRENT) throw new UnsupportedOperationError("side explicit open/close target");
+	}
+	function chromeTarget(target) {
+		return target.tabId !== void 0 || target.windowId !== void 0 ? { ...target } : { windowId: WINDOW_ID_CURRENT };
+	}
+	async function getPath(target = {}) {
+		validateTarget(target);
+		const path = panel?.getOptions ? (await panel.getOptions({ ...target })).path : sidebar ? await sidebar.getPanel({ ...target }) : void 0;
+		if (!panel?.getOptions && !sidebar) throw new UnsupportedOperationError("side.getPath");
+		return path ? helpers.normalizePath(path) : void 0;
+	}
+	const side = {
+		available: capabilities.open,
+		capabilities,
+		async open(target = {}) {
+			validateTarget(target);
+			if (panel?.open) return panel.open(chromeTarget(target));
+			if (sidebar) {
+				requireCurrentWindow(target);
+				return sidebar.open();
+			}
+			throw new UnsupportedOperationError("side.open");
+		},
+		async close(target = {}) {
+			validateTarget(target);
+			if (panel?.close) {
+				const options = chromeTarget(target);
+				if (options.windowId === WINDOW_ID_CURRENT) {
+					if (!api.windows?.getCurrent) throw new UnsupportedOperationError("side.close current window");
+					const windowId = (await api.windows.getCurrent()).id;
+					if (windowId === void 0) throw new Error("No current window is available");
+					options.windowId = windowId;
+				}
+				return panel.close(options);
+			}
+			if (sidebar) {
+				requireCurrentWindow(target);
+				return sidebar.close();
+			}
+			throw new UnsupportedOperationError("side.close");
+		},
+		getPath,
+		async setPath(path, target = {}) {
+			validateTarget(target);
+			const normalized = helpers.normalizePath(path);
+			if (panel?.setOptions) return panel.setOptions({
+				...target,
+				path: normalized
+			});
+			if (sidebar) return sidebar.setPanel({
+				...target,
+				panel: `/${normalized}`
+			});
+			throw new UnsupportedOperationError("side.setPath");
+		},
+		async isOpen(target = {}) {
+			validateTarget(target);
+			if (sidebar?.isOpen) return sidebar.isOpen({ ...target });
+			if (panel && api.runtime?.getContexts && api.windows?.getCurrent) {
+				const windowId = target.windowId === void 0 || target.windowId === WINDOW_ID_CURRENT ? (await api.windows.getCurrent()).id : target.windowId;
+				if (windowId === void 0) return false;
+				return (await api.runtime.getContexts({
+					contextTypes: ["SIDE_PANEL"],
+					windowIds: [windowId]
+				})).length > 0;
+			}
+			throw new UnsupportedOperationError("side.isOpen");
+		},
+		async openPopout(options = {}) {
+			const tabId = await helpers.resolveTabId(options);
+			const path = await getPath(tabId == null ? {} : { tabId });
+			if (!path) throw new Error("No side panel path is configured");
+			return helpers.openPopout(path, {
+				...options,
+				tabId
+			});
+		},
+		bindActionClick(onError) {
+			if (!capabilities.actionClick) throw new UnsupportedOperationError("side.bindActionClick");
+			const listener = (tab) => {
+				side.open(panel && tab.windowId !== void 0 ? { windowId: tab.windowId } : {}).catch(onError);
+			};
+			api.action.onClicked.addListener(listener);
+			return disposers.add(() => api.action.onClicked.removeListener(listener));
+		},
+		dispose() {
+			disposers.dispose();
+		}
+	};
+	return side;
+}
+//#endregion
+//#region src/storage.ts
+const encoder = new TextEncoder();
+function estimateBytes(values) {
+	let bytes = 0;
+	for (const key of Object.keys(values)) {
+		bytes += encoder.encode(key).byteLength;
+		bytes += encoder.encode(JSON.stringify(values[key])).byteLength;
+	}
+	return bytes;
+}
+/**
+* ネイティブAPIを変更せず、存在する領域にヘルパーを追加します。
+* @param storage - ラップするネイティブストレージAPI。
+* @returns 監視の解除処理を管理するストレージラッパー。
+* @internal
+*/
+function createStorage(storage) {
+	const areas = {};
+	const disposers = createDisposables();
+	for (const name of [
+		"local",
+		"sync",
+		"managed",
+		"session"
+	]) {
+		const area = storage[name];
+		if (!area) continue;
+		areas[name] = facade(area, {
+			capabilities: Object.freeze({
+				getKeys: area.getKeys ? "native" : "polyfilled",
+				getBytesInUse: area.getBytesInUse ? "native" : "estimated"
+			}),
+			async getKeys() {
+				return area.getKeys ? area.getKeys() : Object.keys(await area.get(null));
+			},
+			async getBytesInUse(keys = null) {
+				if (area.getBytesInUse) return area.getBytesInUse(keys);
+				return estimateBytes(await area.get(keys));
+			},
+			async getValue(key, defaultValue) {
+				const values = await area.get(key);
+				return Object.hasOwn(values, key) ? values[key] : defaultValue;
+			},
+			async setValue(key, value) {
+				await area.set({ [key]: value });
+			},
+			watch(key, listener) {
+				if (!storage.onChanged) throw new UnsupportedOperationError("storage.watch");
+				const onChanged = (changes, areaName) => {
+					if (areaName !== name || !Object.hasOwn(changes, key)) return;
+					const change = changes[key];
+					listener(change.newValue, change.oldValue);
+				};
+				storage.onChanged.addListener(onChanged);
+				return disposers.add(() => storage.onChanged.removeListener(onChanged));
+			}
+		});
+	}
+	return facade(storage, {
+		...areas,
+		dispose() {
+			disposers.dispose();
+		}
+	});
+}
+//#endregion
+//#region src/tabs.ts
+function createTabs(api, context, messaging) {
+	const native = api.tabs;
+	let internal;
+	let initialized = false;
+	const bridge = () => internal ??= messaging.channel("@midra/webext/internal");
+	async function queryActive(windowId) {
+		if (!native) throw new UnsupportedOperationError("background tab bridge");
+		return (await native.query(windowId === void 0 ? {
+			active: true,
+			currentWindow: true
+		} : {
+			active: true,
+			windowId
+		}))[0];
+	}
+	function initialize() {
+		if (initialized || context.type !== "background") return;
+		if (!native) throw new UnsupportedOperationError("background tab bridge");
+		bridge().handle("selfTab", (_request, sender) => sender.tab);
+		bridge().handle("activeTab", (_request, sender) => queryActive(sender.tab?.windowId));
+		initialized = true;
+	}
+	async function getCurrentActive() {
+		return native ? queryActive() : bridge().send("activeTab", null);
+	}
+	async function getSelf() {
+		if (context.type === "content-script" || !native) return bridge().send("selfTab", null);
+		return native.getCurrent?.();
+	}
+	async function getTarget() {
+		if (context.linkedTabId !== null) {
+			if (!native) throw new UnsupportedOperationError("tabs.get linked target");
+			return native.get(context.linkedTabId);
+		}
+		return context.type === "content-script" ? getSelf() : getCurrentActive();
+	}
+	return {
+		tabs: facade(native ?? {}, {
+			available: !!native,
+			getCurrentActive,
+			async getCurrentActiveId() {
+				return (await getCurrentActive())?.id;
+			},
+			getTarget,
+			async getTargetId() {
+				return (await getTarget())?.id;
+			},
+			getSelf,
+			async getSelfId() {
+				return (await getSelf())?.id;
+			}
+		}),
+		initialize
+	};
+}
+//#endregion
+//#region src/core.ts
+function currentApi() {
+	return globalThis.browser?.runtime?.id ? globalThis.browser : globalThis.chrome;
+}
+/**
+* ネイティブAPIを変更せず、独立した共通APIのインスタンスを作成します。
+*
+* @param options - APIの注入と実行環境の上書き設定。
+* @returns 実行環境・共通ヘルパー・解除処理を持つインスタンス。
+* @remarks
+* backgroundとして作成する場合、内部タブ取得ブリッジはこの呼び出し中に同期登録されます。
+* 権限取得、manifestの変換、ネイティブAPI全体のPromise化は行いません。
+* @throws {Error} 拡張APIがない場合や、初期化に必要なネイティブAPIが失敗した場合。同期例外です。
+* @throws {TypeError} 上書きURLなどをURLとして解析できない場合。同期例外です。
+* @example
+* ```ts
+* const webext = createWebExt({ context: 'sidepanel' })
+* const tab = await webext.tabs.getTarget()
+* ```
+* @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-getURL
+* @see https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/events
+*/
+function createWebExt(options = {}) {
+	const native = options.api ?? currentApi();
+	const api = native;
+	if (!api?.runtime?.getManifest) throw new Error("webext requires a WebExtension context or an injected API");
+	const extensionUrl = new URL(api.runtime.getURL("/"));
+	const context = createContext(api, extensionUrl, options);
+	const messaging = createMessaging(api);
+	const { tabs, initialize } = createTabs(api, context, messaging);
+	const { resolveTabId, openPopout } = createPopout(api, extensionUrl, () => tabs.getTargetId());
+	const action = api.action && facade(api.action, { async openPopout(options = {}) {
+		const tabId = await resolveTabId(options);
+		const path = await api.action.getPopup(tabId === null ? {} : { tabId });
+		if (!path) throw new Error("No action popup path is configured");
+		return openPopout(path, {
+			...options,
+			tabId
+		});
+	} });
+	const side = createSide(api, {
+		resolveTabId,
+		normalizePath: (path) => normalizeExtensionPath(path, extensionUrl),
+		openPopout
+	});
+	const storage = api.storage && createStorage(api.storage);
+	const instance = facade(api, {
+		native,
+		context,
+		tabs,
+		action,
+		side,
+		storage,
+		menus: api.menus ?? api.contextMenus,
+		messaging,
+		initialize,
+		dispose() {
+			side.dispose();
+			storage?.dispose();
+			messaging.dispose();
+		}
+	});
+	initialize();
+	return instance;
+}
+/**
+* 初回のプロパティアクセスで初期化する、既定の共通APIインスタンス。
+*
+* @remarks
+* モジュールのインポートだけでは拡張APIへアクセスしません。プロパティの読み取りや列挙などは
+* 初期化を発生させるため、拡張環境が必要です。backgroundのトップレベルでは
+* `webext.initialize()` を同期的に呼び、内部ブリッジを登録してください。
+* 設定の注入や破棄後の新しいインスタンスには {@link createWebExt} を使用します。
+* @example
+* ```ts
+* import { webext } from '@midra/webext'
+* webext.initialize()
+* ```
+* @see https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/events
+*/
+const webext = lazyFacade(() => createWebExt());
+//#endregion
+export { MessageTimeoutError, RemoteError, UnsupportedOperationError, createWebExt, webext };