@midra/webext 0.0.0-stage → 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,899 @@
+/// <reference types="chrome" preserve="true" />
+import Browser from "webextension-polyfill";
+//#region src/context.d.ts
+/**
+ * インスタンス作成時に取得・推測した実行環境と、ポップアウトの関連付け情報。
+ *
+ * @remarks
+ * このオブジェクトは凍結され、作成後のURLやmanifest設定の変更には追従しません。
+ * ポップアウト関連の情報は拡張ページのクエリから取得する便宜上の情報であり、
+ * 認証・アクセス制御や、関連付け先タブが現在も存在することの保証には使えません。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-getURL
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/getURL
+ */
+interface WebExtContext {
+  /** 関連付け先タブIDを格納する内部クエリの名前（`_webext_linked_tab_id`）。 */
+  readonly LINKED_TAB_ID_NAME: string;
+  /** 拡張URLのスキームから判定するブラウザ種別。Chromium系は `chrome`。明示指定があればそちらを優先します。 */
+  readonly browser: 'chrome' | 'firefox' | 'unknown';
+  /** 実行コンテキストの役割。manifestや実行環境から判定できない場合は `null`。 */
+  readonly type: 'background' | 'content-script' | 'popup' | 'sidepanel' | null;
+  /** 拡張ページの内部クエリに指定された非負の安全な整数ID。未指定・不正・通常のWebページでは `null`。 */
+  readonly linkedTabId: number | null;
+  /** 拡張ページにポップアウト用の内部クエリがあるか。関連付け先がなくても `true` になり得ます。 */
+  readonly isPopout: boolean;
+}
+/** `CreateWebExtOptions` に含まれる実行環境の上書き設定。 */
+interface ContextOptions {
+  /**
+   * 実行コンテキストの役割を明示します。省略時だけ自動判定し、`null` は判定しない指定です。
+   *
+   * @remarks 動的に変更したpopup・パネルのパスや独自の拡張ページでは、役割を明示してください。
+   */
+  context?: WebExtContext['type'];
+  /** ブラウザ種別を明示します。APIを切り替えたり、未対応機能を有効化したりする設定ではありません。 */
+  browser?: WebExtContext['browser'];
+  /**
+   * 環境判定と内部クエリの取得に使う絶対URL。省略時は `globalThis.location?.href`。
+   *
+   * @remarks テストなどで使う上書き値です。ページ遷移や権限の付与は行いません。
+   */
+  url?: string;
+}
+//#endregion
+//#region src/messaging/types.d.ts
+/**
+ * 1種類のメッセージの要求型と応答型。
+ *
+ * @remarks
+ * 型の定義であり、実行時スキーマではありません。要求・応答の内容は利用側で検証してください。
+ * 送受信値はJSON互換値に限定し、Firefoxのstructured cloneで送れる値より厳しく制限します。
+ * 有限数・文字列・真偽値・`null`・配列・プレーンオブジェクトが対象で、Date・Map・BigInt・
+ * 関数・循環参照などは拒否します。オブジェクト内の `undefined` は省略、疎配列の穴は `null` に変換し、
+ * 配列要素として明示した `undefined` は拒否します。最上位の `undefined` は内部で `null` とフラグに
+ * 符号化し、受信時に `undefined` に復元します。要求・応答とも同じ規則です。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-sendMessage
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage
+ */
+interface MessageDefinition {
+  /** 送信する要求の型。型指定だけでは受信値を実行時検証しません。 */
+  request: unknown;
+  /** ハンドラーが返す応答の型。JSON互換性以外の実行時検証は行いません。 */
+  response: unknown;
+}
+/**
+ * メッセージ名から要求型・応答型への対応表。
+ *
+ * @remarks 同じチャンネルの送受信側で共有する型であり、実行時の登録・検証は行いません。
+ * @example
+ * ```ts
+ * interface Messages {
+ *   greet: { request: { name: string }; response: string }
+ * }
+ * ```
+ */
+type MessageSchema = Record<string, MessageDefinition>;
+/**
+ * 送信先と送信側の応答待機を指定するオプション。
+ *
+ * @remarks
+ * `tabId` がなければ自拡張への `runtime.sendMessage()`、あれば `tabs.sendMessage()` を使用します。
+ * 外部拡張・Webページ宛ての送信は提供しません。対象フレーム・ドキュメントの存在と各オプションへの
+ * 対応はネイティブAPIに従い、未対応の指定を代替しません。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-sendMessage
+ * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-sendMessage
+ */
+interface SendOptions {
+  /**
+   * 送信先コンテンツスクリプトを含むタブID。非負の安全な整数が必要です。
+   * @remarks ネイティブの `tabs.sendMessage()` が使えるコンテキストと、対象タブの受信ハンドラーが必要です。
+   * `tabs` 権限が一律に必須という意味ではありません。省略時はアクティブタブを検索せず、自拡張へ送信します。
+   */
+  tabId?: number;
+  /**
+   * 対象フレームのID。`tabId` が必須です。`0` はトップレベルフレーム。
+   * @remarks 値の有効性・対象の存在はネイティブAPIに従います。省略時はネイティブの既定の送信範囲です。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-sendMessage
+   */
+  frameId?: number;
+  /**
+   * 対象ドキュメントのID。`tabId` と、ネイティブAPIのこのオプションへの対応が必要です。
+   * @remarks 値・対象の有効性はネイティブAPIに従い、未対応環境での補完は行いません。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-sendMessage
+   */
+  documentId?: string;
+  /**
+   * 送信側の待機上限（ミリ秒）。既定値は10,000、正の有限数で最大2,147,483,647。
+   * @remarks 範囲外は送信前に `TypeError` でPromiseが拒否されます。期限超過は `MessageTimeoutError`。
+   * 終了するのはローカルの待機だけで、受信側の処理や送信済みのネイティブ通信はキャンセルしません。
+   */
+  timeoutMs?: number;
+  /**
+   * 送信側の待機を中止するシグナル。
+   * @remarks 既に中止済みなら送信しません。中止時は `signal.reason`（なければ `AbortError`）で
+   * Promiseが拒否されます。送信後の中止はローカルの待機だけを終了し、受信処理はキャンセルしません。
+   */
+  signal?: AbortSignal;
+}
+/**
+ * 同じ拡張内の名前付き要求・応答チャンネル。
+ *
+ * @typeParam Schema - メッセージ名ごとの要求型・応答型。実行時スキーマ検証は行いません。
+ * @remarks
+ * ファクトリーごとに単一の `runtime.onMessage` ルーターを共有し、ハンドラーがある間だけ登録します。
+ * 受信は `sender.id === runtime.id` の内部メッセージに限定し、未登録のチャンネル・メッセージは扱いません。
+ * この確認は要求内容や送信元URLの信頼性を保証しません。必要な検証はハンドラーで行ってください。
+ * 1つの要求に応答するコンテキストは1つにしてください。複数の受信先が応答する場合の順序は保証しません。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#type-MessageSender
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage
+ */
+interface MessageChannel<Schema extends { [K in keyof Schema]: MessageDefinition; }> {
+  /**
+   * JSON互換の要求を送り、対応するハンドラーの応答を待ちます。
+   *
+   * @typeParam K - スキーマ内のメッセージ名。
+   * @param type - 送受信側で共有するメッセージ名。
+   * @param request - 要求値。直列化の制約は {@link MessageDefinition} を参照してください。
+   * @param options - 送信先・待機上限・中止シグナル。
+   * @returns 応答値で解決するPromise。応答型の実行時検証は行いません。
+   * @throws {TypeError} 無効なタブID・待機上限、`tabId` なしのframe/document指定、非JSON互換の要求。
+   * @throws {UnsupportedOperationError} タブ送信に必要なネイティブAPIが利用できない場合。
+   * @throws {MessageTimeoutError} 応答待機の期限を超過した場合。
+   * @throws {RemoteError} ハンドラーの例外・Promise拒否、または応答のJSON化失敗。
+   * @throws 破棄済みチャンネル・非互換の応答・ネイティブ通信エラー・シグナル中止理由。
+   * @remarks
+   * 上記の失敗はすべて戻り値のPromiseの拒否です（同期例外ではありません）。受信先がない場合も成功扱いにしません。
+   * `tabId` なしの送信は送信元自身を除く拡張コンテキスト宛てで、コンテンツスクリプト宛てではありません。
+   * コンテンツスクリプトへは `tabId` を指定してください。待機の中止は受信処理を停止しません。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-sendMessage
+   * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-sendMessage
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage
+   */
+  send<K extends keyof Schema & string>(type: K, request: Schema[K]['request'], options?: SendOptions): Promise<Schema[K]['response']>;
+  /**
+   * 1種類のメッセージを処理するハンドラーを登録します。
+   *
+   * @typeParam K - スキーマ内のメッセージ名。
+   * @param type - 処理するメッセージ名。同じチャンネル内で重複登録はできません。
+   * @param handler - 要求値とネイティブのMessageSenderを受け取り、JSON互換の応答値またはそのPromiseを返す関数。
+   * @returns この登録だけを解除する関数。繰り返し呼んでも一度だけ解除し、後続の再登録は解除しません。
+   * @throws {UnsupportedOperationError} `runtime.onMessage` が利用できない場合に同期的に送出します。
+   * @throws 破棄済みチャンネル・同じメッセージ名の重複登録は同期例外です。
+   * @remarks
+   * 受信イベント内でハンドラーを同期的に呼び、その結果をawaitしてcallbackで応答します。
+   * Chrome / Firefoxとも内部リスナーは `true` を返して非同期応答を維持します。
+   * ハンドラーの例外は送信側で `RemoteError` となります。要求値・senderの追加検証は利用側の責任です。
+   * backgroundでは再起動時にも登録されるようトップレベルで呼んでください。
+   * @example
+   * ```ts
+   * const channel = webext.messaging.channel<Messages>('app/background')
+   * const stop = channel.handle('greet', ({ name }) => `Hello, ${name}`)
+   * // 別コンテキストで同名チャンネルを作成し、send('greet', { name: 'Midra' })
+   * stop()
+   * ```
+   * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#event-onMessage
+   * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#type-MessageSender
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage
+   */
+  handle<K extends keyof Schema & string>(type: K, handler: (request: Schema[K]['request'], sender: Browser.Runtime.MessageSender) => Schema[K]['response'] | Promise<Schema[K]['response']>): () => void;
+  /**
+   * このチャンネルの全ハンドラーを解除し、このオブジェクトを終端的に破棄します。
+   *
+   * @returns 戻り値はありません。繰り返し呼べます。
+   * @remarks
+   * 以後の `send()` はPromiseの拒否、`handle()` は同期例外になります。
+   * ファクトリーが未破棄なら `messaging.channel(name)` で同名の新しいチャンネルを作れます。
+   * 既に実行中のハンドラーや送信側の待機はキャンセルしません。
+   */
+  dispose(): void;
+}
+/** 名前付きチャンネルを管理する、WebExtインスタンスごとのメッセージングファクトリー。 */
+interface Messaging {
+  /**
+   * 名前に対応するチャンネルを取得・作成します。
+   *
+   * @typeParam Schema - 送受信側で共有する型。同じ名前に異なる型を指定しても実行時に検出しません。
+   * @param name - チャンネル名。空文字・空白のみは禁止で、それ以外は空白も含め完全一致で識別します。
+   * @returns 同じファクトリー内では、同名の未破棄チャンネルを再利用します。
+   * @throws {TypeError} 名前が空文字・空白のみなら同期的に送出します。
+   * @throws ファクトリーが破棄済みなら同期例外です。
+   * @remarks 取得だけでは受信リスナーを登録しません。送受信側で同じ名前とスキーマを共有してください。
+   * @example
+   * ```ts
+   * const channel = webext.messaging.channel<Messages>('app/background')
+   * const greeting = await channel.send('greet', { name: 'Midra' })
+   * ```
+   */
+  channel<Schema extends { [K in keyof Schema]: MessageDefinition; }>(name: string): MessageChannel<Schema>;
+  /**
+   * 全チャンネルと共有ルーターを解除し、ファクトリーを終端的に破棄します。
+   *
+   * @returns 戻り値はありません。繰り返し呼べます。
+   * @remarks
+   * `webext.dispose()` でも呼ばれます。破棄後は `channel()` を呼べません。
+   * 再利用には `createWebExt()` で新しいインスタンスを作成してください。
+   * 送信済みの待機や実行中の受信処理をキャンセルするものではありません。
+   */
+  dispose(): void;
+}
+//#endregion
+//#region src/popout.d.ts
+/**
+ * actionのpopupやサイドパネルの拡張ページを別ウィンドウで開くためのライブラリ独自設定。
+ *
+ * @remarks
+ * ウィンドウの種類は `popup`、URLは対象ページから生成する。
+ * `tabId` 以外の値は `windows.create` にそのまま渡し、省略値もブラウザの既定に従う。
+ * 寸法・位置・状態の組み合わせやプライベートウィンドウの制約はネイティブ側で検証され、エラーは伝播する。
+ * @example
+ * ```ts
+ * await webext.side.openPopout({ tabId: null, width: 420, height: 720 })
+ * ```
+ * @see https://developer.chrome.com/docs/extensions/reference/api/windows#method-create
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/windows/create
+ */
+interface PopoutOptions {
+  /**
+   * 関連付けるタブの非負の安全な整数ID。既存タブは移動しない。
+   *
+   * @remarks
+   * 省略時は `tabs.getTargetId()` の対象を使う。`null` または対象がない場合は関連付けなし。
+   * URLの内部クエリに記録する独自の関連付けであり、認証・アクセス制御には使わない。
+   * タブを移動するネイティブの `windows.create` の `tabId` には渡さない。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/windows/create#parameters
+   */
+  tabId?: number | null;
+  /** フレームを含むウィンドウ幅（ピクセル）。省略時はブラウザが決定する。`state` の併用制約に注意。 */
+  width?: number;
+  /** フレームを含むウィンドウ高さ（ピクセル）。省略時はブラウザが決定する。`state` の併用制約に注意。 */
+  height?: number;
+  /** 画面左端からの位置（ピクセル）。省略時はブラウザが決定する。`state` の併用制約に注意。 */
+  left?: number;
+  /** 画面上端からの位置（ピクセル）。省略時はブラウザが決定する。`state` の併用制約に注意。 */
+  top?: number;
+  /** `true` ならフォーカスして開き、`false` なら非アクティブで開く。省略時はネイティブの既定に従う。 */
+  focused?: boolean;
+  /**
+   * シークレット／プライベートウィンドウとして開くか。
+   *
+   * @remarks
+   * 拡張機能のプライベート利用許可やブラウザの制約により、ネイティブ側で拒否される場合がある。
+   * 利用許可の取得や別のウィンドウへのフォールバックは行わない。
+   */
+  incognito?: boolean;
+  /**
+   * 作成時のウィンドウ状態。
+   *
+   * @remarks `minimized`・`maximized`・`fullscreen` は `left`・`top`・`width`・`height` と併用できない。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/windows#method-create
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/windows/create#parameters
+   */
+  state?: 'normal' | 'minimized' | 'maximized' | 'fullscreen';
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * 現在のブラウザ・実行コンテキストに、操作に必要なAPIや機能がない場合のエラー。
+ *
+ * @remarks
+ * 権限不足などのネイティブエラーを一律にこの型へ変換するものではありません。
+ * `StorageHelpers.watch()` / `MessageChannel.handle()` では同期的に送出し、`MessageChannel.send()` など
+ * Promiseを返す操作では拒否理由になります。捕捉方法は呼び出すAPIに従ってください。
+ */
+export declare class UnsupportedOperationError extends Error {
+  /** 利用できなかった操作の識別子。 */
+  readonly operation: string;
+  /**
+   * 利用できない操作名を含むエラーを作成します。
+   * @param operation - ライブラリ内の操作識別子（例: `storage.watch`）。
+   */
+  constructor(
+  /** 利用できなかった操作の識別子。 */
+  operation: string);
+}
+/**
+ * メッセージの応答待機が送信側の期限を超過した場合のエラー。
+ *
+ * @remarks
+ * `channel.send()` のPromiseの拒否理由です。受信側の処理やネイティブ通信が停止したことは意味しません。
+ * 不正な待機上限の指定はこの型ではなく `TypeError` になります。
+ */
+export declare class MessageTimeoutError extends Error {
+  /** 送信側で設定した応答待機の上限（ミリ秒）。 */
+  readonly timeoutMs: number;
+  /**
+   * 応答待機の上限を含むエラーを作成します。
+   * @param timeoutMs - 超過した待機上限（ミリ秒）。このコンストラクター自体は値を検証しません。
+   */
+  constructor(
+  /** 送信側で設定した応答待機の上限（ミリ秒）。 */
+  timeoutMs: number);
+}
+/**
+ * 受信側のハンドラーの失敗を送信側へ伝えるエラー。
+ *
+ * @remarks
+ * ハンドラーの同期例外・Promiseの拒否・応答のJSON化失敗は、`channel.send()` のPromiseをこの型で拒否します。
+ * `name` は `RemoteError`、元の名前は `remoteName`、失敗内容は継承した `message` に保持します。
+ * 元の例外オブジェクト・スタック・独自プロパティは転送しません。Error以外の例外値は名前を `Error` として
+ * 文字列化し、文字列化も失敗した場合は `Error` / `Remote handler failed` にフォールバックします。
+ */
+export declare class RemoteError extends Error {
+  /** 受信側で正規化した例外名。送信側の `name` とは異なります。 */
+  readonly remoteName: string;
+  /**
+   * 受信側から転送された名前とメッセージでエラーを作成します。
+   * @param message - 受信側のエラーメッセージ、または例外値を文字列化した内容。
+   * @param remoteName - 受信側の例外名。名前を取得できない場合は `Error`。
+   */
+  constructor(message: string,
+  /** 受信側で正規化した例外名。送信側の `name` とは異なります。 */
+  remoteName: string);
+}
+//#endregion
+//#region src/side.d.ts
+/**
+ * サイドパネルの開閉対象。
+ *
+ * @remarks
+ * 対象省略時は現在のウィンドウ。ChromeではネイティブAPIへ対象を渡す。
+ * Firefoxの開閉は対象指定に対応せず、省略または `windowId: -2` のみ受け付ける。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#type-OpenOptions
+ * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#type-CloseOptions
+ */
+interface SideTarget {
+  /** 対象タブの非負の安全な整数ID。Firefoxの開閉では指定不可。 */
+  tabId?: number;
+  /** 対象ウィンドウの非負の安全な整数ID。`-2` は現在のウィンドウを表す。 */
+  windowId?: number;
+}
+/**
+ * サイドパネルのパス設定を取得・変更する対象。ウィンドウ単位の指定は提供しない。
+ *
+ * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#type-GetPanelOptions
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/setPanel
+ */
+interface SidePathTarget {
+  /** 対象タブの非負の安全な整数ID。省略時はグローバル（既定）の設定を扱う。 */
+  tabId?: number;
+}
+/**
+ * 初期化時に検出したサイドパネル関連APIの対応状況。
+ *
+ * @remarks
+ * APIの存在に基づく判定であり、権限・manifest設定・バージョン要件や操作の成功は保証しない。
+ */
+interface SideCapabilities {
+  /** パネルを開くAPIがあるか。 */
+  readonly open: boolean;
+  /** パネルを閉じるAPIがあるか。ChromeのネイティブAPIは141以降。 */
+  readonly close: boolean;
+  /** パス設定の取得・変更に必要なAPIがあるか。 */
+  readonly path: boolean;
+  /**
+   * 開状態の判定方式。`false` は未対応。
+   *
+   * @remarks
+   * `native` はFirefoxの表示状態取得、`document` はChromeのパネルドキュメントの存在観測。
+   * 後者は切り替え・終了途中などの厳密なUI表示状態と一致しない可能性がある。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/isOpen
+   * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-getContexts
+   */
+  readonly isOpen: 'native' | 'document' | false;
+  /** 明示的なタブ・ウィンドウを指定して開くAPIがあるか。閉じる操作の対応状況ではない。 */
+  readonly targetedOpen: boolean;
+  /** actionクリックイベントとパネルを開くAPIがあり、クリック連携を登録できるか。 */
+  readonly actionClick: boolean;
+}
+/**
+ * ChromeのsidePanelとFirefoxのsidebarActionを共通の操作として扱うライブラリ独自API。
+ *
+ * @remarks
+ * ネイティブAPIの完全な模倣ではなく、パスの統一やポップアウトなどの補助操作を提供する。
+ * 非同期操作の検証エラー・未対応エラー・ネイティブAPIのエラーはPromiseの拒否として伝播する。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/open
+ */
+interface Side {
+  /** 開くAPIがあるか。表示中かどうかや、権限・manifest設定の正しさを示すものではない。 */
+  readonly available: boolean;
+  /** APIの存在から検出した機能別の対応状況。 */
+  readonly capabilities: SideCapabilities;
+  /**
+   * 拡張機能のサイドパネルを開く。
+   *
+   * @param target - 開く対象。省略時、Chromeは現在のウィンドウのグローバルパネルを開く。
+   * @returns 開く処理が完了すると値なしで解決するPromise。
+   * @remarks
+   * 両ブラウザでユーザー操作のハンドラーから直接呼ぶ。Chromeの `sidePanel.open` は116以降。
+   * Chromeで `tabId` を指定するとタブ固有パネルを使い、未設定ならグローバルパネルを使う。
+   * `windowId` のみではタブ固有パネルを選ばない。Firefoxはアクティブなウィンドウで開く。
+   * 省略時はChromeへ `windowId: -2` を同期的に渡すため、この定数に未対応の環境では実際のIDを指定する。
+   * @throws {@link UnsupportedOperationError} 開くAPIがない場合、またはFirefoxで明示的な対象を指定した場合。
+   * @throws {TypeError} タブ・ウィンドウIDが不正な場合。
+   * @example
+   * ```ts
+   * button.addEventListener('click', () => {
+   *   void webext.side.open().catch(console.error)
+   * })
+   * ```
+   * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#method-open
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/open
+   */
+  open(target?: SideTarget): Promise<void>;
+  /**
+   * 拡張機能のサイドパネルを閉じる。無効化やパス設定の変更は行わない。
+   *
+   * @param target - 閉じる対象。省略時は現在のウィンドウ（Chromeではグローバルパネル）。
+   * @returns 閉じる処理が完了すると値なしで解決するPromise。
+   * @remarks
+   * Chromeの `sidePanel.close` は141以降。現在のウィンドウ指定は実際のIDを取得してから渡す。
+   * タブ指定時の動作はネイティブに従い、Chrome 145以降はグローバルパネルしか開いていないと拒否される。
+   * Firefoxはアクティブなウィンドウで閉じる。MDNの制約に従いユーザー操作のハンドラーから呼ぶ。
+   * @throws {@link UnsupportedOperationError} 閉じるためのAPIがない場合、またはFirefoxで明示的な対象を指定した場合。
+   * @throws {TypeError} タブ・ウィンドウIDが不正な場合。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#method-close
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/close
+   */
+  close(target?: SideTarget): Promise<void>;
+  /**
+   * 設定中のパネルのパスを拡張ルート相対形式で取得する。
+   *
+   * @param target - 設定の取得対象。省略時はグローバル（既定）の設定。
+   * @returns クエリ・ハッシュを保持したパス。パスが未設定または空なら `undefined`。
+   * @throws {@link UnsupportedOperationError} パスを取得するAPIがない場合。
+   * @throws {TypeError} タブIDが不正、または取得したパスが同じ拡張内を指さない場合。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#method-getOptions
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/getPanel
+   */
+  getPath(target?: SidePathTarget): Promise<string | undefined>;
+  /**
+   * パネルに使用する拡張ページのパスを変更する。
+   *
+   * @param path - 拡張ルート相対パス、または同じ拡張内の絶対URL。クエリ・ハッシュを保持する。
+   * @param target - 設定の変更対象。省略時はグローバル（既定）の設定。
+   * @returns パス設定の変更が完了すると値なしで解決するPromise。
+   * @remarks パネルを開く操作ではない。FirefoxのネイティブAPIと異なり、外部URLや空文字列による設定解除は受け付けない。
+   * @throws {@link UnsupportedOperationError} パスを変更するAPIがない場合。
+   * @throws {TypeError} タブIDやパスが不正、空のパス、または外部URLを指定した場合。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel#method-setOptions
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/setPanel
+   */
+  setPath(path: string, target?: SidePathTarget): Promise<void>;
+  /**
+   * 指定ウィンドウでパネルが開いているかを判定する。
+   *
+   * @param target - 判定対象。
+   * @param target.windowId - ウィンドウID。省略または `-2` は現在のウィンドウ（Firefoxでは最前面）。
+   * @returns Firefoxではネイティブの表示状態、Chromeでは対象ウィンドウの `SIDE_PANEL` コンテキストが存在するか。
+   * @remarks
+   * Firefoxでは開閉と異なり明示的なウィンドウIDを指定できる。
+   * Chromeは `runtime.getContexts` によるドキュメントの存在観測であり、厳密なUI表示状態を保証しない。
+   * @throws {@link UnsupportedOperationError} 状態判定に必要なAPIがない場合。
+   * @throws {TypeError} ウィンドウIDが不正な場合。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction/isOpen
+   * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-getContexts
+   */
+  isOpen(target?: {
+    windowId?: number;
+  }): Promise<boolean>;
+  /**
+   * 対象タブに設定中のパネルページを別ウィンドウで開くライブラリ独自ヘルパー。
+   *
+   * @param options - 関連付けるタブとウィンドウの設定。`tabId: null` は関連付けなしでグローバルのパスを使う。
+   * @returns ネイティブの `windows.create` が返すウィンドウ情報、または `undefined`。
+   * @remarks
+   * `tabId` 省略時は `tabs.getTargetId()` の対象を使い、対象がなければグローバルのパスを使う。
+   * 既存タブの移動やサイドパネルの開閉は行わない。寸法・状態・プライベート設定の制約は {@link PopoutOptions} を参照。
+   * @throws {@link UnsupportedOperationError} パス取得やウィンドウ作成に必要なAPIがない場合。
+   * @throws {TypeError} タブIDやパスが不正な場合。
+   * @throws {Error} パネルのパスが未設定の場合。対象解決・設定取得・ウィンドウ作成のエラーも伝播する。
+   * @example
+   * ```ts
+   * await webext.side.openPopout({ tabId: null, width: 420, height: 720 })
+   * ```
+   * @see https://developer.chrome.com/docs/extensions/reference/api/windows#method-create
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/windows/create
+   */
+  openPopout(options?: PopoutOptions): Promise<Browser.Windows.Window | undefined>;
+  /**
+   * actionクリックでパネルを開くリスナーを登録するライブラリ独自ヘルパー。
+   *
+   * @param onError - パネルを開くPromiseが拒否されたときに呼ぶエラーハンドラー。
+   * @returns この登録を解除する関数。繰り返し呼んでもよい。
+   * @remarks
+   * background起動時のトップレベルで同期的に登録する。actionのpopupが設定されているタブではクリックイベントが発火しない。
+   * Chromeではクリックしたタブのウィンドウのグローバルパネルを開き、Firefoxではアクティブなウィンドウで開く。
+   * ネイティブの `setPanelBehavior` を設定するものではなく、クリック時に `open` を呼ぶ。
+   * @throws {@link UnsupportedOperationError} クリックイベントまたはパネルを開くAPIがない場合。
+   * @example
+   * ```ts
+   * const unbind = webext.side.bindActionClick(console.error)
+   * ```
+   * @see https://developer.chrome.com/docs/extensions/reference/api/action#event-onClicked
+   */
+  bindActionClick(onError: (error: unknown) => void): () => void;
+  /** このインスタンスが登録したactionクリックのリスナーをすべて解除する。パネルは閉じない。繰り返し呼んでもよい。 */
+  dispose(): void;
+}
+//#endregion
+//#region src/storage.d.ts
+/**
+ * 利用可能なストレージ領域に追加する共通ヘルパー。
+ *
+ * @remarks
+ * `storage` 権限が必要です。領域へのアクセス制限・保存形式・クォータはネイティブAPIに従います。
+ * Promiseを返すメソッドの失敗は拒否として伝播し、`watch()` の登録失敗は同期例外です。
+ * 型引数 `T` は実行時のデータ検証・変換を行いません。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/storage
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage
+ */
+interface StorageHelpers {
+  /** 補完メソッドの実装方式。権限・領域へのアクセス可否を保証するものではありません。 */
+  readonly capabilities: {
+    /** `native` はネイティブ呼び出し、`polyfilled` は全値の取得によるキー列挙。 */
+    readonly getKeys: 'native' | 'polyfilled';
+    /** `native` はネイティブの計測、`estimated` はJSONに基づく推定。 */
+    readonly getBytesInUse: 'native' | 'estimated';
+  };
+  /**
+   * 領域内の全キーを取得します。
+   *
+   * @returns キーの配列。ネイティブが未対応なら `get(null)` で全値を読み、キーを列挙します。
+   * @throws ネイティブの読み取りエラーでPromiseが拒否されます。
+   * @remarks 補完時はキーだけでなく全値の読み取りコストが発生します。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea
+   */
+  getKeys(): Promise<string[]>;
+  /**
+   * 指定キーの使用バイト数を取得し、ネイティブが未対応なら推定します。
+   *
+   * @param keys - 対象キー。省略・`null` は全件、空配列は対象なし。
+   * @returns ネイティブの計測値、またはキーとJSON化した値のUTF-8バイト数の合計。
+   * @throws 読み取り・JSON化の失敗でPromiseが拒否されます。
+   * @remarks
+   * `capabilities.getBytesInUse` で実装方式を確認できます。推定値はディスク使用量でも
+   * ブラウザのクォータ計測値でもなく、クォータ超過の判定には使えません。
+   * 特にsession領域のメモリ使用量とは異なります。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/storage
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get
+   */
+  getBytesInUse(keys?: string | string[] | null): Promise<number>;
+  /**
+   * 単一キーの値を取得します。
+   *
+   * @typeParam T - 期待する値の型。実行時検証は行いません。
+   * @param key - 取得するキー。
+   * @returns 保存値。キーが存在しなければ `undefined`。
+   * @throws ネイティブの読み取りエラーでPromiseが拒否されます。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get
+   */
+  getValue<T>(key: string): Promise<T | undefined>;
+  /**
+   * 単一キーの値を、未保存時の既定値付きで取得します。
+   *
+   * @typeParam T - 期待する値の型。保存値の実行時検証は行いません。
+   * @param key - 取得するキー。
+   * @param defaultValue - キーが存在しない場合だけ返す値。ストレージには保存しません。
+   * @returns 保存値、または既定値。既存の `null` などは既定値に置き換えません。
+   * @throws ネイティブの読み取りエラーでPromiseが拒否されます。既定値ではエラーを補いません。
+   * @example
+   * ```ts
+   * const theme = await webext.storage.local.getValue('theme', 'system')
+   * ```
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get
+   */
+  getValue<T>(key: string, defaultValue: T): Promise<T>;
+  /**
+   * 単一キーの値をネイティブの `set()` で保存・更新します。
+   *
+   * @typeParam T - 保存する値の型。実行時検証は行いません。
+   * @param key - 保存先のキー。
+   * @param value - ネイティブのストレージAPIで保存可能な値。
+   * @returns 保存完了時に解決するPromise。
+   * @throws 保存形式・権限・クォータなどのネイティブエラーでPromiseが拒否されます。
+   * managed領域は読み取り専用のため書き込みが拒否されます。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/storage
+   */
+  setValue<T>(key: string, value: T): Promise<void>;
+  /**
+   * この領域・キーに対するネイティブの変更通知を監視します。
+   *
+   * @typeParam T - 通知値の期待する型。実行時検証は行いません。
+   * @param key - 監視するキー。
+   * @param listener - 新しい値と以前の値を受け取る関数。削除後の値・追加前の値は `undefined`。
+   * @returns この監視だけを解除する関数。繰り返し呼んでも解除処理は一度だけです。
+   * @throws {UnsupportedOperationError} `storage.onChanged` がなければ同期的に送出します。
+   * @remarks
+   * 登録時に現在値は通知しません。値の比較や重複排除は行わず、Firefoxでは値が変わらなくても
+   * 通知される場合があります。managedの通知可否もネイティブに従います。
+   * `storage.dispose()` / `webext.dispose()` でもこのヘルパーの監視を解除します。
+   * @example
+   * ```ts
+   * const stop = webext.storage.local.watch<string>('theme', (value, previous) => {
+   *   console.log(previous, value)
+   * })
+   * stop()
+   * ```
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/onChanged
+   */
+  watch<T>(key: string, listener: (value: T | undefined, previous: T | undefined) => void): () => void;
+}
+/**
+ * ネイティブのStorageAreaに共通ヘルパーを追加した領域。
+ *
+ * @remarks
+ * 継承する `get(keys)` は値の辞書を取得し、省略・`null` は全件、既定値の辞書も指定できます。
+ * `set(items)` はキーと値の辞書を保存、`remove(keys)` は指定キーを削除、`clear()` は全件削除します。
+ * これらはネイティブのPromiseを返し、失敗は拒否として伝播します。managedへの変更操作は拒否されます。
+ * `onChanged` は領域単位のネイティブイベントです。直接登録したリスナーは利用側で解除してください。
+ * 共通ヘルパー以外のネイティブメソッド・イベントの対応状況やアクセス制限は補完しません。
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get
+ */
+type StorageArea = Omit<Browser.Storage.StorageArea, 'getBytesInUse'> & StorageHelpers;
+/**
+ * 拡張機能のネイティブストレージと共通ヘルパー。
+ *
+ * @remarks `storage` 権限が必要です。領域の存在だけでは権限・アクセス設定・ポリシーの利用可否を保証しません。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/storage
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage
+ */
+interface WebExtStorage {
+  /** ローカルに永続保存する領域。保存量の制限はネイティブに従います。 */
+  local: StorageArea;
+  /** ブラウザの同期設定に従って同期する領域。容量・書き込み頻度の制限はネイティブに従います。 */
+  sync: StorageArea;
+  /**
+   * 管理者などが構成する読み取り専用領域。`setValue()` やネイティブの変更操作は拒否されます。
+   *
+   * @remarks
+   * Chromeはスキーマと企業ポリシー、Firefoxはネイティブマニフェストまたは `3rdparty` ポリシーなどで
+   * 利用側が事前構成します。Firefoxでは未構成の領域の読み取りも失敗し得るため、空の辞書を前提にしないでください。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/storage
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/managed
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get
+   */
+  managed: StorageArea;
+  /**
+   * ブラウザが提供する、ディスクに永続保存しないメモリ上のsession領域。
+   *
+   * @remarks
+   * 未対応なら `undefined`。service worker内のメモリやlocalなどの永続領域では代用しません。
+   * 利用可否・寿命はブラウザと実行コンテキストに依存し、通常コンテンツスクリプトには公開されません。
+   * 必要なネイティブのアクセス設定は利用側で行います。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/storage
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/session
+   */
+  session?: StorageArea;
+  /**
+   * 全領域のネイティブ変更イベント。値の重複排除は行いません。
+   *
+   * @remarks 直接登録したリスナーは `dispose()` の対象外です。利用側で `removeListener()` してください。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/onChanged
+   */
+  onChanged: Browser.Storage.Static['onChanged'];
+  /**
+   * このラッパーの `watch()` が登録した監視を解除します。
+   *
+   * @returns 戻り値はありません。
+   * @remarks
+   * 繰り返し呼べます。保存値・ネイティブ設定・直接登録されたリスナーは変更しません。
+   * 終端的な破棄ではなく、その後も読み書きや新しい `watch()` の登録が可能です。
+   */
+  dispose(): void;
+}
+//#endregion
+//#region src/tabs.d.ts
+/**
+ * ネイティブのtabs APIに、実行コンテキストを考慮したタブ取得ヘルパーを追加したAPI。
+ *
+ * @remarks
+ * コンテンツスクリプトでは、backgroundのトップレベルで `webext.initialize()` を呼ぶと
+ * 共通ヘルパーを内部メッセージ経由で利用できます。ネイティブの `query()` などを
+ * コンテンツスクリプトへ公開するものではありません。
+ * タブIDの取得自体に `tabs` 権限が一律に必要なわけではありませんが、返されるタブの
+ * `url`・`pendingUrl`・`title`・`favIconUrl` などの情報には `tabs` または対象のホスト権限が必要です。
+ * ヘルパーの失敗はPromiseの拒否として伝播します。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/tabs
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query
+ */
+type WebExtTabs = Browser.Tabs.Static & {
+  /** ネイティブのtabs APIが存在するか。`false` でも内部ブリッジ経由の共通ヘルパーは利用できます。 */
+  readonly available: boolean;
+  /**
+   * 現在のウィンドウのアクティブタブを取得します。ポップアウトの関連付け先は優先しません。
+   *
+   * @returns 条件に合う最初のタブ。タブがなければ `undefined`。
+   * @remarks
+   * ネイティブでは `query({ active: true, currentWindow: true })` を使います。
+   * 内部ブリッジ経由では、送信元タブのウィンドウIDがあればそのウィンドウに限定して検索します。
+   * 受信先がない場合やネイティブAPIの失敗は、メッセージング・ネイティブのエラーで拒否されます。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-query
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query
+   */
+  getCurrentActive(): Promise<Browser.Tabs.Tab | undefined>;
+  /**
+   * `getCurrentActive()` で取得したタブのIDを返します。
+   * @returns タブID。タブまたはIDがなければ `undefined`。取得エラーは伝播します。
+   */
+  getCurrentActiveId(): Promise<number | undefined>;
+  /**
+   * 関連付け先タブ、コンテンツスクリプト自身のタブ、アクティブタブの順に対象を解決します。
+   *
+   * @returns 解決したタブ。対象がなければ `undefined`。
+   * @remarks
+   * `context.linkedTabId` があればネイティブの `tabs.get()` を使います。
+   * 未指定ならコンテンツスクリプトでは `getSelf()`、それ以外では `getCurrentActive()` を使います。
+   * 関連付け先が閉じられていても別のタブへフォールバックせず、取得エラーを伝播します。
+   * @throws {UnsupportedOperationError} 関連付け先が指定されているのにネイティブのtabs APIがない場合。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-get
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/get
+   */
+  getTarget(): Promise<Browser.Tabs.Tab | undefined>;
+  /**
+   * `getTarget()` で解決したタブのIDを返します。
+   * @returns タブID。対象タブまたはIDがなければ `undefined`。取得エラーは伝播します。
+   */
+  getTargetId(): Promise<number | undefined>;
+  /**
+   * このスクリプト自身を含むタブを取得します。アクティブタブや関連付け先とは異なります。
+   *
+   * @returns 自身を含むタブ。backgroundや通常のaction popupなど、タブに属さなければ `undefined`。
+   * @remarks
+   * コンテンツスクリプト、またはネイティブのtabs APIがない環境では、backgroundが受け取る
+   * `MessageSender.tab` を利用します。それ以外ではネイティブの `tabs.getCurrent()` を使います。
+   * ブリッジの未登録やネイティブの取得失敗はエラーとして伝播します。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/tabs#method-getCurrent
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/getCurrent
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/MessageSender
+   */
+  getSelf(): Promise<Browser.Tabs.Tab | undefined>;
+  /**
+   * `getSelf()` で取得した自身のタブIDを返します。
+   * @returns タブID。自身のタブまたはIDがなければ `undefined`。取得エラーは伝播します。
+   */
+  getSelfId(): Promise<number | undefined>;
+};
+//#endregion
+//#region src/core.d.ts
+/**
+ * 共通APIインスタンスの作成設定。省略した値はネイティブAPIと実行環境から取得します。
+ *
+ * @remarks
+ * ブラウザAPIのアクセス権限を付与したり、ネイティブAPI全体をPromise化したりする設定ではありません。
+ * 環境判定の上書きは継承した `context`・`browser`・`url` で指定します。
+ * @see https://developer.chrome.com/docs/extensions/reference/api/runtime#method-getManifest
+ */
+interface CreateWebExtOptions extends ContextOptions {
+  /**
+   * 利用するネイティブAPI。テストでは互換のモックを注入できます。
+   *
+   * @remarks
+   * 省略時は `runtime.id` があるグローバルの `browser` を優先し、なければ `chrome` を使います。
+   * ライブラリからこのオブジェクトやグローバルのAPIを変更しません。
+   */
+  api?: typeof chrome | Browser.Browser;
+}
+/**
+ * Chrome / FirefoxのネイティブAPIに、共通操作と実用ヘルパーを追加したライブラリの公開API。
+ *
+ * @remarks
+ * Manifest V3とPromise版のネイティブAPIがある環境を対象にします。
+ * APIの利用可否はブラウザ・権限・manifest・実行コンテキストに依存し、未対応の
+ * ネイティブAPI全体を補完するものではありません。独自ヘルパーの仕様は各メンバーを参照してください。
+ * @see https://developer.chrome.com/docs/extensions/reference/api
+ * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API
+ */
+type WebExt = Omit<Browser.Browser, 'tabs' | 'action' | 'storage' | 'menus' | 'sidebarAction'> & {
+  /** ブラウザ固有APIへのアクセス用の元のAPIオブジェクト。ライブラリからは変更しません。 */
+  readonly native: typeof chrome | Browser.Browser;
+  /** 初期化時の実行環境とポップアウトの関連付け情報。作成後の変更には追従しません。 */
+  readonly context: WebExtContext;
+  /** サイドパネルの共通操作。ネイティブのsidePanel / sidebarActionとは別の独自APIです。 */
+  readonly side: Side;
+  /** 同じ拡張内の型付き要求・応答チャンネルを管理する独自API。 */
+  readonly messaging: Messaging;
+  /** ネイティブのtabs APIと、コンテンツスクリプトでも使える共通タブ取得ヘルパー。 */
+  readonly tabs: WebExtTabs;
+  /** ネイティブの各ストレージ領域と、値取得・変更監視などの共通ヘルパー。`storage` 権限が必要です。 */
+  readonly storage: WebExtStorage;
+  /**
+   * Firefoxの `menus`、またはChromeの `contextMenus` をネイティブのまま公開します。
+   * @remarks 利用するブラウザのメニュー権限が必要です。ネイティブのcallback専用メソッドはPromise化しません。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/contextMenus
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus
+   */
+  readonly menus: Browser.ContextMenus.Static;
+  /**
+   * 存在する場合のみ公開するChromeのネイティブsidePanel API。共通操作には `side` を使用します。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/sidePanel
+   */
+  readonly sidePanel?: typeof chrome.sidePanel;
+  /**
+   * 存在する場合のみ公開するFirefoxのネイティブsidebarAction API。共通操作には `side` を使用します。
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/sidebarAction
+   */
+  readonly sidebarAction?: Browser.SidebarAction.Static;
+  /**
+   * ネイティブaction APIと、popupページを別ウィンドウで開く独自ヘルパー。
+   * @remarks manifestのaction設定や、利用可能な実行コンテキストが必要です。
+   * @see https://developer.chrome.com/docs/extensions/reference/api/action
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/action
+   */
+  readonly action: Browser.Action.Static & {
+    /**
+     * 対象タブに現在設定されているactionのpopupページを別ウィンドウで開きます。
+     *
+     * @param options - 関連付けるタブとウィンドウの設定。省略した `tabId` は `tabs.getTargetId()`、`null` は関連付けなし。
+     * @returns ネイティブの `windows.create()` が返すウィンドウ情報、または `undefined`。
+     * @remarks
+     * 既存タブは移動しません。URLのクエリとハッシュを保持します。
+     * popupが空に設定されている場合は、manifestの初期値へ戻さずエラーにします。
+     * @throws {TypeError} タブIDや取得したページのパスが不正な場合。Promiseの拒否として伝播します。
+     * @throws {Error} popup未設定、対象解決やネイティブAPIの失敗。ウィンドウAPI未対応時は `UnsupportedOperationError`。
+     * @see https://developer.chrome.com/docs/extensions/reference/api/action#method-getPopup
+     * @see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/action/getPopup
+     * @see https://developer.chrome.com/docs/extensions/reference/api/windows#method-create
+     */
+    openPopout(options?: PopoutOptions): Promise<Browser.Windows.Window | undefined>;
+  };
+  /**
+   * background側の内部タブ取得ブリッジを同期的に登録します。
+   *
+   * @remarks
+   * backgroundのトップレベルで呼んでください。service workerの起動ごとに同期登録される必要があります。
+   * `createWebExt()` は作成時にもこの処理を呼びます。遅延初期化される `webext` では、
+   * トップレベルの `webext.initialize()` により初期化と登録をその場で行えます。
+   * 複数回呼んでも登録は増えず、background以外では何もしません。
+   * @throws {UnsupportedOperationError} backgroundでネイティブのtabs APIが利用できない場合。同期例外です。
+   * @see https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/events
+   */
+  initialize(): void;
+  /**
+   * このインスタンスのメッセージ受信、storage.watch、actionクリック連携を解除します。
+   *
+   * @remarks
+   * 繰り返し呼べます。保存値・パネル・ネイティブ設定・直接登録されたリスナーは変更しません。
+   * 送信済みの待機や実行中の受信処理はキャンセルしません。
+   * メッセージングは終端的に破棄されるため、再利用には `createWebExt()` で新しいインスタンスを作成してください。
+   */
+  dispose(): void;
+};
+/**
+ * ネイティブ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
+ */
+export declare function createWebExt(options?: CreateWebExtOptions): WebExt;
+/**
+ * 初回のプロパティアクセスで初期化する、既定の共通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
+ */
+export declare const webext: WebExt;
+//#endregion
+export type { CreateWebExtOptions, MessageChannel, MessageDefinition, MessageSchema, Messaging, PopoutOptions, SendOptions, Side, SideCapabilities, SidePathTarget, SideTarget, StorageArea, StorageHelpers, WebExt, WebExtContext, WebExtStorage, WebExtTabs };