@fairfox/polly 0.1.0

package/dist/shared/adapters/index.js

@@ -0,0 +1,298 @@
+// src/shared/adapters/chrome/context-menus.chrome.ts
+class ChromeContextMenusAdapter {
+  async create(createProperties) {
+    return new Promise((resolve, reject) => {
+      chrome.contextMenus.create(createProperties, () => {
+        if (chrome.runtime.lastError) {
+          reject(new Error(chrome.runtime.lastError.message));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+  async update(id, updateProperties) {
+    await chrome.contextMenus.update(id, updateProperties);
+  }
+  async remove(id) {
+    await chrome.contextMenus.remove(id);
+  }
+  async removeAll() {
+    await chrome.contextMenus.removeAll();
+  }
+  onClicked(callback) {
+    chrome.contextMenus.onClicked.addListener(callback);
+  }
+}
+
+// src/shared/adapters/chrome/offscreen.chrome.ts
+class ChromeOffscreenAdapter {
+  async createDocument(parameters) {
+    await chrome.offscreen.createDocument({
+      url: parameters.url,
+      reasons: parameters.reasons,
+      justification: parameters.justification
+    });
+  }
+  async closeDocument() {
+    await chrome.offscreen.closeDocument();
+  }
+  async hasDocument() {
+    const existingContexts = await chrome.runtime.getContexts({
+      contextTypes: ["OFFSCREEN_DOCUMENT"]
+    });
+    return existingContexts.length > 0;
+  }
+}
+
+// src/shared/adapters/chrome/runtime.chrome.ts
+class ChromeRuntimeAdapter {
+  messageListeners = new Map;
+  static listenerCount = 0;
+  sendMessage(message) {
+    return chrome.runtime.sendMessage(message);
+  }
+  onMessage(callback) {
+    const wrappedCallback = (message, sender, sendResponse) => {
+      const mappedSender = {
+        ...sender.tab && {
+          tab: {
+            id: sender.tab.id ?? 0,
+            url: sender.tab.url ?? "",
+            title: sender.tab.title ?? ""
+          }
+        },
+        ...sender.frameId !== undefined && { frameId: sender.frameId },
+        ...sender.url && { url: sender.url }
+      };
+      return callback(message, mappedSender, sendResponse);
+    };
+    this.messageListeners.set(callback, wrappedCallback);
+    chrome.runtime.onMessage.addListener(wrappedCallback);
+    ChromeRuntimeAdapter.listenerCount++;
+    if (ChromeRuntimeAdapter.listenerCount > 1) {
+      console.warn(`⚠️  WARNING: ${ChromeRuntimeAdapter.listenerCount} chrome.runtime.onMessage listeners registered!
+
+Multiple listeners will cause message handlers to execute multiple times.
+This is usually caused by:
+  1. Creating both MessageBus and MessageRouter with separate listeners
+  2. Calling createBackground() multiple times
+  3. Calling getMessageBus('background') after createBackground()
+
+Fix: In background scripts, use createBackground() ONCE at startup.
+Do not call getMessageBus('background') separately.`);
+    }
+  }
+  removeMessageListener(callback) {
+    const wrappedCallback = this.messageListeners.get(callback);
+    if (wrappedCallback) {
+      chrome.runtime.onMessage.removeListener(wrappedCallback);
+      this.messageListeners.delete(callback);
+      ChromeRuntimeAdapter.listenerCount = Math.max(0, ChromeRuntimeAdapter.listenerCount - 1);
+    }
+  }
+  connect(name) {
+    const port = chrome.runtime.connect({ name });
+    return new ChromePortAdapter(port);
+  }
+  onConnect(callback) {
+    chrome.runtime.onConnect.addListener((port) => {
+      callback(new ChromePortAdapter(port));
+    });
+  }
+  getURL(path) {
+    return chrome.runtime.getURL(path);
+  }
+  getId() {
+    return chrome.runtime.id;
+  }
+  openOptionsPage() {
+    chrome.runtime.openOptionsPage();
+  }
+}
+
+class ChromePortAdapter {
+  port;
+  listeners = {
+    message: new Set,
+    disconnect: new Set
+  };
+  constructor(port) {
+    this.port = port;
+    this.port.onMessage.addListener((message) => {
+      for (const callback of this.listeners.message) {
+        callback(message);
+      }
+    });
+    this.port.onDisconnect.addListener(() => {
+      for (const callback of this.listeners.disconnect) {
+        callback();
+      }
+    });
+  }
+  get name() {
+    return this.port.name;
+  }
+  postMessage(message) {
+    this.port.postMessage(message);
+  }
+  onMessage(callback) {
+    this.listeners.message.add(callback);
+  }
+  onDisconnect(callback) {
+    this.listeners.disconnect.add(callback);
+  }
+  disconnect() {
+    this.port.disconnect();
+  }
+}
+
+// src/shared/adapters/chrome/storage.chrome.ts
+class ChromeStorageAdapter {
+  async get(keys) {
+    return await chrome.storage.local.get(keys);
+  }
+  async set(items) {
+    await chrome.storage.local.set(items);
+  }
+  async remove(keys) {
+    await chrome.storage.local.remove(keys);
+  }
+  async clear() {
+    await chrome.storage.local.clear();
+  }
+  onChanged(callback) {
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+      const mappedChanges = {};
+      for (const [key, change] of Object.entries(changes)) {
+        mappedChanges[key] = {
+          oldValue: change.oldValue,
+          newValue: change.newValue
+        };
+      }
+      callback(mappedChanges, areaName);
+    });
+  }
+}
+
+// src/shared/adapters/chrome/tabs.chrome.ts
+class ChromeTabsAdapter {
+  async query(queryInfo) {
+    return chrome.tabs.query(queryInfo);
+  }
+  async get(tabId) {
+    return chrome.tabs.get(tabId);
+  }
+  async sendMessage(tabId, message) {
+    return chrome.tabs.sendMessage(tabId, message);
+  }
+  async reload(tabId, reloadProperties) {
+    await chrome.tabs.reload(tabId, reloadProperties);
+  }
+  onRemoved(callback) {
+    chrome.tabs.onRemoved.addListener(callback);
+  }
+  onUpdated(callback) {
+    chrome.tabs.onUpdated.addListener(callback);
+  }
+  onActivated(callback) {
+    chrome.tabs.onActivated.addListener(callback);
+  }
+  async create(createProperties) {
+    return chrome.tabs.create(createProperties);
+  }
+}
+
+// src/shared/adapters/chrome/window.chrome.ts
+class ChromeWindowAdapter {
+  postMessage(message, targetOrigin) {
+    window.postMessage(message, targetOrigin);
+  }
+  addEventListener(type, listener) {
+    window.addEventListener(type, listener);
+  }
+  removeEventListener(type, listener) {
+    window.removeEventListener(type, listener);
+  }
+}
+
+// src/shared/adapters/fetch.adapter.ts
+class BrowserFetchAdapter {
+  fetch(input, init) {
+    return fetch(input, init);
+  }
+}
+
+// src/shared/adapters/logger.adapter.ts
+class MessageLoggerAdapter {
+  runtime;
+  sourceContext;
+  options;
+  constructor(runtime, sourceContext, options) {
+    this.runtime = runtime;
+    this.sourceContext = sourceContext;
+    this.options = options;
+  }
+  debug(message, context) {
+    this.sendLog("debug", message, context);
+  }
+  info(message, context) {
+    this.sendLog("info", message, context);
+  }
+  warn(message, context) {
+    this.sendLog("warn", message, context);
+  }
+  error(message, error, context) {
+    this.sendLog("error", message, context, error);
+  }
+  log(level, message, context) {
+    this.sendLog(level, message, context);
+  }
+  sendLog(level, message, context, error) {
+    if (this.options?.consoleMirror) {
+      const consoleMethod = console[level] || console.log;
+      consoleMethod(`[${this.sourceContext}]`, message, context || "", error || "");
+    }
+    const logMessage = {
+      type: "LOG",
+      level,
+      message,
+      context,
+      error: error?.message,
+      stack: error?.stack,
+      source: this.sourceContext,
+      timestamp: Date.now()
+    };
+    this.runtime.sendMessage(logMessage).catch((sendError) => {
+      if (this.options?.fallbackToConsole !== false) {
+        console[level](`[${this.sourceContext}] ${message}`, context || "", error || "");
+        console.warn("Failed to send log message:", sendError);
+      }
+    });
+  }
+}
+
+// src/shared/adapters/index.ts
+function createChromeAdapters(context, options) {
+  const runtime2 = new ChromeRuntimeAdapter;
+  return {
+    runtime: runtime2,
+    storage: new ChromeStorageAdapter,
+    tabs: new ChromeTabsAdapter,
+    window: new ChromeWindowAdapter,
+    offscreen: new ChromeOffscreenAdapter,
+    contextMenus: new ChromeContextMenusAdapter,
+    fetch: new BrowserFetchAdapter,
+    logger: new MessageLoggerAdapter(runtime2, context, {
+      ...options?.consoleMirror !== undefined && { consoleMirror: options.consoleMirror },
+      fallbackToConsole: true
+    })
+  };
+}
+export {
+  createChromeAdapters,
+  MessageLoggerAdapter,
+  BrowserFetchAdapter
+};
+
+//# debugId=88CAE80DB6C0B30564756E2164756E21

package/dist/shared/adapters/index.js.map

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "sources": ["../src/shared/adapters/chrome/context-menus.chrome.ts", "../src/shared/adapters/chrome/offscreen.chrome.ts", "../src/shared/adapters/chrome/runtime.chrome.ts", "../src/shared/adapters/chrome/storage.chrome.ts", "../src/shared/adapters/chrome/tabs.chrome.ts", "../src/shared/adapters/chrome/window.chrome.ts", "../src/shared/adapters/fetch.adapter.ts", "../src/shared/adapters/logger.adapter.ts", "../src/shared/adapters/index.ts"],
+  "sourcesContent": [
+    "// Chrome context menus adapter implementation\n\nimport type { ContextMenusAdapter } from \"../context-menus.adapter\";\n\nexport class ChromeContextMenusAdapter implements ContextMenusAdapter {\n  async create(createProperties: chrome.contextMenus.CreateProperties): Promise<void> {\n    return new Promise((resolve, reject) => {\n      chrome.contextMenus.create(createProperties, () => {\n        if (chrome.runtime.lastError) {\n          reject(new Error(chrome.runtime.lastError.message));\n        } else {\n          resolve();\n        }\n      });\n    });\n  }\n\n  async update(id: string, updateProperties: chrome.contextMenus.UpdateProperties): Promise<void> {\n    await chrome.contextMenus.update(id, updateProperties);\n  }\n\n  async remove(id: string): Promise<void> {\n    await chrome.contextMenus.remove(id);\n  }\n\n  async removeAll(): Promise<void> {\n    await chrome.contextMenus.removeAll();\n  }\n\n  onClicked(\n    callback: (info: chrome.contextMenus.OnClickData, tab?: chrome.tabs.Tab) => void\n  ): void {\n    chrome.contextMenus.onClicked.addListener(callback);\n  }\n}\n",
+    "// Chrome offscreen adapter implementation\n\nimport type { CreateOffscreenDocumentParameters, OffscreenAdapter } from \"../offscreen.adapter\";\n\nexport class ChromeOffscreenAdapter implements OffscreenAdapter {\n  async createDocument(parameters: CreateOffscreenDocumentParameters): Promise<void> {\n    await chrome.offscreen.createDocument({\n      url: parameters.url,\n      reasons: parameters.reasons as chrome.offscreen.Reason[],\n      justification: parameters.justification,\n    });\n  }\n\n  async closeDocument(): Promise<void> {\n    await chrome.offscreen.closeDocument();\n  }\n\n  async hasDocument(): Promise<boolean> {\n    // Chrome doesn't provide a direct API, so we query for offscreen contexts\n    const existingContexts = await chrome.runtime.getContexts({\n      contextTypes: [\"OFFSCREEN_DOCUMENT\" as chrome.runtime.ContextType],\n    });\n    return existingContexts.length > 0;\n  }\n}\n",
+    "// Chrome runtime adapter implementation\n\nimport type { MessageSender, PortAdapter, RuntimeAdapter } from \"../runtime.adapter\";\n\ntype MessageListener = (\n  message: unknown,\n  sender: MessageSender,\n  sendResponse: (response: unknown) => void\n) => undefined | boolean;\n\ntype ChromeMessageListener = (\n  message: unknown,\n  sender: chrome.runtime.MessageSender,\n  sendResponse: (response?: unknown) => void\n) => undefined | boolean;\n\nexport class ChromeRuntimeAdapter implements RuntimeAdapter {\n  private messageListeners = new Map<MessageListener, ChromeMessageListener>();\n  private static listenerCount = 0;\n\n  sendMessage<T>(message: T): Promise<unknown> {\n    return chrome.runtime.sendMessage(message);\n  }\n\n  onMessage(\n    callback: (\n      message: unknown,\n      sender: MessageSender,\n      sendResponse: (response: unknown) => void\n    ) => undefined | boolean\n  ): void {\n    const wrappedCallback = (\n      message: unknown,\n      sender: chrome.runtime.MessageSender,\n      sendResponse: (response?: unknown) => void\n    ) => {\n      const mappedSender: MessageSender = {\n        ...(sender.tab && {\n          tab: {\n            id: sender.tab.id ?? 0,\n            url: sender.tab.url ?? \"\",\n            title: sender.tab.title ?? \"\",\n          },\n        }),\n        ...(sender.frameId !== undefined && { frameId: sender.frameId }),\n        ...(sender.url && { url: sender.url }),\n      };\n      return callback(message, mappedSender, sendResponse);\n    };\n\n    this.messageListeners.set(callback, wrappedCallback);\n    // Chrome's listener signature uses void | boolean, ours uses undefined | boolean\n    // These are compatible - undefined is assignable to void for return types\n    chrome.runtime.onMessage.addListener(\n      wrappedCallback as (\n        message: unknown,\n        sender: chrome.runtime.MessageSender,\n        sendResponse: (response?: unknown) => void\n      ) => undefined | boolean\n    );\n\n    // Track listener count and warn if multiple listeners registered\n    ChromeRuntimeAdapter.listenerCount++;\n\n    if (ChromeRuntimeAdapter.listenerCount > 1) {\n      console.warn(\n        `⚠️  WARNING: ${ChromeRuntimeAdapter.listenerCount} chrome.runtime.onMessage listeners registered!\\n\\nMultiple listeners will cause message handlers to execute multiple times.\\nThis is usually caused by:\\n  1. Creating both MessageBus and MessageRouter with separate listeners\\n  2. Calling createBackground() multiple times\\n  3. Calling getMessageBus('background') after createBackground()\\n\\nFix: In background scripts, use createBackground() ONCE at startup.\\nDo not call getMessageBus('background') separately.`\n      );\n    }\n  }\n\n  removeMessageListener(\n    callback: (\n      message: unknown,\n      sender: MessageSender,\n      sendResponse: (response: unknown) => void\n    ) => undefined | boolean\n  ): void {\n    const wrappedCallback = this.messageListeners.get(callback);\n    if (wrappedCallback) {\n      // Type-safe cast: wrappedCallback is stored with compatible signature\n      chrome.runtime.onMessage.removeListener(\n        wrappedCallback as (\n          message: unknown,\n          sender: chrome.runtime.MessageSender,\n          sendResponse: (response?: unknown) => void\n        ) => undefined | boolean\n      );\n      this.messageListeners.delete(callback);\n\n      // Decrement listener count\n      ChromeRuntimeAdapter.listenerCount = Math.max(0, ChromeRuntimeAdapter.listenerCount - 1);\n    }\n  }\n\n  connect(name: string): PortAdapter {\n    const port = chrome.runtime.connect({ name });\n    return new ChromePortAdapter(port);\n  }\n\n  onConnect(callback: (port: PortAdapter) => void): void {\n    chrome.runtime.onConnect.addListener((port) => {\n      callback(new ChromePortAdapter(port));\n    });\n  }\n\n  getURL(path: string): string {\n    return chrome.runtime.getURL(path);\n  }\n\n  getId(): string {\n    return chrome.runtime.id;\n  }\n\n  openOptionsPage(): void {\n    chrome.runtime.openOptionsPage();\n  }\n}\n\nclass ChromePortAdapter implements PortAdapter {\n  private listeners = {\n    message: new Set<(message: unknown) => void>(),\n    disconnect: new Set<() => void>(),\n  };\n\n  constructor(private port: chrome.runtime.Port) {\n    // Set up Chrome port listeners\n    this.port.onMessage.addListener((message) => {\n      for (const callback of this.listeners.message) {\n        callback(message);\n      }\n    });\n\n    this.port.onDisconnect.addListener(() => {\n      for (const callback of this.listeners.disconnect) {\n        callback();\n      }\n    });\n  }\n\n  get name(): string {\n    return this.port.name;\n  }\n\n  postMessage(message: unknown): void {\n    this.port.postMessage(message);\n  }\n\n  onMessage(callback: (message: unknown) => void): void {\n    this.listeners.message.add(callback);\n  }\n\n  onDisconnect(callback: () => void): void {\n    this.listeners.disconnect.add(callback);\n  }\n\n  disconnect(): void {\n    this.port.disconnect();\n  }\n}\n",
+    "// Chrome storage adapter implementation\n\nimport type { StorageAdapter, StorageChanges } from \"../storage.adapter\";\n\nexport class ChromeStorageAdapter implements StorageAdapter {\n  async get<T = Record<string, unknown>>(keys: string | string[] | null): Promise<T> {\n    return (await chrome.storage.local.get(keys)) as T;\n  }\n\n  async set(items: Record<string, unknown>): Promise<void> {\n    await chrome.storage.local.set(items);\n  }\n\n  async remove(keys: string | string[]): Promise<void> {\n    await chrome.storage.local.remove(keys);\n  }\n\n  async clear(): Promise<void> {\n    await chrome.storage.local.clear();\n  }\n\n  onChanged(callback: (changes: StorageChanges, areaName: string) => void): void {\n    chrome.storage.onChanged.addListener((changes, areaName) => {\n      const mappedChanges: StorageChanges = {};\n      for (const [key, change] of Object.entries(changes)) {\n        mappedChanges[key] = {\n          oldValue: change.oldValue,\n          newValue: change.newValue,\n        };\n      }\n      callback(mappedChanges, areaName);\n    });\n  }\n}\n",
+    "// Chrome tabs adapter implementation\n\nimport type { TabsAdapter } from \"../tabs.adapter\";\n\nexport class ChromeTabsAdapter implements TabsAdapter {\n  async query(queryInfo: chrome.tabs.QueryInfo): Promise<chrome.tabs.Tab[]> {\n    return chrome.tabs.query(queryInfo);\n  }\n\n  async get(tabId: number): Promise<chrome.tabs.Tab> {\n    return chrome.tabs.get(tabId);\n  }\n\n  async sendMessage(tabId: number, message: unknown): Promise<unknown> {\n    return chrome.tabs.sendMessage(tabId, message);\n  }\n\n  async reload(tabId: number, reloadProperties?: { bypassCache?: boolean }): Promise<void> {\n    await chrome.tabs.reload(tabId, reloadProperties);\n  }\n\n  onRemoved(callback: (tabId: number, removeInfo: chrome.tabs.TabRemoveInfo) => void): void {\n    chrome.tabs.onRemoved.addListener(callback);\n  }\n\n  onUpdated(\n    callback: (tabId: number, changeInfo: chrome.tabs.TabChangeInfo, tab: chrome.tabs.Tab) => void\n  ): void {\n    chrome.tabs.onUpdated.addListener(callback);\n  }\n\n  onActivated(callback: (activeInfo: { tabId: number; windowId: number }) => void): void {\n    chrome.tabs.onActivated.addListener(callback);\n  }\n\n  async create(createProperties: chrome.tabs.CreateProperties): Promise<chrome.tabs.Tab> {\n    return chrome.tabs.create(createProperties);\n  }\n}\n",
+    "// Chrome window adapter implementation\n\nimport type { WindowAdapter } from \"../window.adapter\";\n\nexport class ChromeWindowAdapter implements WindowAdapter {\n  postMessage(message: unknown, targetOrigin: string): void {\n    window.postMessage(message, targetOrigin);\n  }\n\n  addEventListener(type: \"message\", listener: (event: MessageEvent) => void): void {\n    window.addEventListener(type, listener as EventListener);\n  }\n\n  removeEventListener(type: \"message\", listener: (event: MessageEvent) => void): void {\n    window.removeEventListener(type, listener as EventListener);\n  }\n}\n",
+    "// Fetch adapter interface (wraps fetch API)\n\nexport interface FetchAdapter {\n  fetch(input: string | URL, init?: RequestInit): Promise<Response>;\n}\n\nexport class BrowserFetchAdapter implements FetchAdapter {\n  fetch(input: string | URL, init?: RequestInit): Promise<Response> {\n    return fetch(input, init);\n  }\n}\n",
+    "import type { Context, LogLevel } from \"../types/messages\";\n// Logger adapter interface (message-based centralized logging)\nimport type { RuntimeAdapter } from \"./runtime.adapter\";\n\nexport interface LoggerAdapter {\n  /**\n   * Debug-level logging (verbose, development info)\n   */\n  debug(message: string, context?: Record<string, unknown>): void;\n\n  /**\n   * Info-level logging (general information)\n   */\n  info(message: string, context?: Record<string, unknown>): void;\n\n  /**\n   * Warning-level logging (non-critical issues)\n   */\n  warn(message: string, context?: Record<string, unknown>): void;\n\n  /**\n   * Error-level logging (errors and exceptions)\n   */\n  error(message: string, error?: Error, context?: Record<string, unknown>): void;\n\n  /**\n   * Log with explicit level\n   */\n  log(level: LogLevel, message: string, context?: Record<string, unknown>): void;\n}\n\nexport interface MessageLoggerOptions {\n  consoleMirror?: boolean; // Also log to console (for development)\n  fallbackToConsole?: boolean; // Log to console if message send fails (default: true)\n}\n\n/**\n * Message-based logger that sends LOG messages to background LogStore\n * Uses RuntimeAdapter directly to avoid circular dependency with MessageBus\n */\nexport class MessageLoggerAdapter implements LoggerAdapter {\n  constructor(\n    private runtime: RuntimeAdapter,\n    private sourceContext: Context,\n    private options?: MessageLoggerOptions\n  ) {}\n\n  debug(message: string, context?: Record<string, unknown>): void {\n    this.sendLog(\"debug\", message, context);\n  }\n\n  info(message: string, context?: Record<string, unknown>): void {\n    this.sendLog(\"info\", message, context);\n  }\n\n  warn(message: string, context?: Record<string, unknown>): void {\n    this.sendLog(\"warn\", message, context);\n  }\n\n  error(message: string, error?: Error, context?: Record<string, unknown>): void {\n    this.sendLog(\"error\", message, context, error);\n  }\n\n  log(level: LogLevel, message: string, context?: Record<string, unknown>): void {\n    this.sendLog(level, message, context);\n  }\n\n  private sendLog(\n    level: LogLevel,\n    message: string,\n    context?: Record<string, unknown>,\n    error?: Error\n  ): void {\n    // Optional console mirror for development\n    if (this.options?.consoleMirror) {\n      const consoleMethod = console[level] || console.log;\n      consoleMethod(`[${this.sourceContext}]`, message, context || \"\", error || \"\");\n    }\n\n    // Send LOG message to background (fire-and-forget)\n    const logMessage = {\n      type: \"LOG\" as const,\n      level,\n      message,\n      context,\n      error: error?.message,\n      stack: error?.stack,\n      source: this.sourceContext,\n      timestamp: Date.now(),\n    };\n\n    // Use runtime.sendMessage for fire-and-forget messaging\n    this.runtime.sendMessage(logMessage).catch((sendError) => {\n      // Fallback to console if messaging fails\n      if (this.options?.fallbackToConsole !== false) {\n        console[level](`[${this.sourceContext}] ${message}`, context || \"\", error || \"\");\n        console.warn(\"Failed to send log message:\", sendError);\n      }\n    });\n  }\n}\n",
+    "// Adapter factory and exports\n\nimport { ChromeContextMenusAdapter } from \"./chrome/context-menus.chrome\";\nimport { ChromeOffscreenAdapter } from \"./chrome/offscreen.chrome\";\nimport { ChromeRuntimeAdapter } from \"./chrome/runtime.chrome\";\nimport { ChromeStorageAdapter } from \"./chrome/storage.chrome\";\nimport { ChromeTabsAdapter } from \"./chrome/tabs.chrome\";\nimport { ChromeWindowAdapter } from \"./chrome/window.chrome\";\nimport { BrowserFetchAdapter } from \"./fetch.adapter\";\nimport { MessageLoggerAdapter } from \"./logger.adapter\";\n\nimport type { Context } from \"../types/messages\";\nimport type { ContextMenusAdapter } from \"./context-menus.adapter\";\nimport type { FetchAdapter } from \"./fetch.adapter\";\nimport type { LoggerAdapter } from \"./logger.adapter\";\nimport type { OffscreenAdapter } from \"./offscreen.adapter\";\nimport type { RuntimeAdapter } from \"./runtime.adapter\";\nimport type { StorageAdapter } from \"./storage.adapter\";\nimport type { TabsAdapter } from \"./tabs.adapter\";\nimport type { WindowAdapter } from \"./window.adapter\";\n\nexport interface ExtensionAdapters {\n  runtime: RuntimeAdapter;\n  storage: StorageAdapter;\n  tabs: TabsAdapter;\n  window: WindowAdapter;\n  offscreen: OffscreenAdapter;\n  contextMenus: ContextMenusAdapter;\n  fetch: FetchAdapter;\n  logger: LoggerAdapter;\n}\n\nexport interface CreateChromeAdaptersOptions {\n  consoleMirror?: boolean; // Mirror logs to console for development\n}\n\n/**\n * Create Chrome-specific adapters with context\n */\nexport function createChromeAdapters(\n  context: Context,\n  options?: CreateChromeAdaptersOptions\n): ExtensionAdapters {\n  const runtime = new ChromeRuntimeAdapter();\n\n  return {\n    runtime,\n    storage: new ChromeStorageAdapter(),\n    tabs: new ChromeTabsAdapter(),\n    window: new ChromeWindowAdapter(),\n    offscreen: new ChromeOffscreenAdapter(),\n    contextMenus: new ChromeContextMenusAdapter(),\n    fetch: new BrowserFetchAdapter(),\n    logger: new MessageLoggerAdapter(runtime, context, {\n      ...(options?.consoleMirror !== undefined && { consoleMirror: options.consoleMirror }),\n      fallbackToConsole: true,\n    }),\n  };\n}\n\n// Re-export types\nexport * from \"./runtime.adapter\";\nexport * from \"./storage.adapter\";\nexport * from \"./tabs.adapter\";\nexport * from \"./window.adapter\";\nexport * from \"./offscreen.adapter\";\nexport * from \"./context-menus.adapter\";\nexport * from \"./fetch.adapter\";\nexport * from \"./logger.adapter\";\n"
+  ],
+  "mappings": "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",
+  "debugId": "88CAE80DB6C0B30564756E2164756E21",
+  "names": []
+}

package/dist/shared/adapters/logger.adapter.d.ts

@@ -0,0 +1,44 @@
+import type { Context, LogLevel } from "../types/messages";
+import type { RuntimeAdapter } from "./runtime.adapter";
+export interface LoggerAdapter {
+    /**
+     * Debug-level logging (verbose, development info)
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Info-level logging (general information)
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Warning-level logging (non-critical issues)
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Error-level logging (errors and exceptions)
+     */
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+    /**
+     * Log with explicit level
+     */
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+}
+export interface MessageLoggerOptions {
+    consoleMirror?: boolean;
+    fallbackToConsole?: boolean;
+}
+/**
+ * Message-based logger that sends LOG messages to background LogStore
+ * Uses RuntimeAdapter directly to avoid circular dependency with MessageBus
+ */
+export declare class MessageLoggerAdapter implements LoggerAdapter {
+    private runtime;
+    private sourceContext;
+    private options?;
+    constructor(runtime: RuntimeAdapter, sourceContext: Context, options?: MessageLoggerOptions | undefined);
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    private sendLog;
+}

package/dist/shared/adapters/offscreen.adapter.d.ts

@@ -0,0 +1,20 @@
+export interface OffscreenAdapter {
+    /**
+     * Create offscreen document
+     */
+    createDocument(parameters: CreateOffscreenDocumentParameters): Promise<void>;
+    /**
+     * Close offscreen document
+     */
+    closeDocument(): Promise<void>;
+    /**
+     * Check if offscreen document exists
+     */
+    hasDocument(): Promise<boolean>;
+}
+export interface CreateOffscreenDocumentParameters {
+    url: string;
+    reasons: OffscreenReason[];
+    justification: string;
+}
+export type OffscreenReason = "AUDIO_PLAYBACK" | "BLOBS" | "CLIPBOARD" | "DOM_PARSER" | "DOM_SCRAPING" | "IFRAME_SCRIPTING" | "LOCAL_STORAGE" | "MATCH_MEDIA" | "TESTING" | "USER_MEDIA" | "WEB_RTC" | "WORKERS";

package/dist/shared/adapters/runtime.adapter.d.ts

@@ -0,0 +1,66 @@
+export interface RuntimeAdapter {
+    /**
+     * Send a one-off message to another context
+     */
+    sendMessage<T>(message: T): Promise<unknown>;
+    /**
+     * Listen for one-off messages
+     * Return true from callback to indicate async response
+     */
+    onMessage(callback: (message: unknown, sender: MessageSender, sendResponse: (response: unknown) => void) => undefined | boolean): void;
+    /**
+     * Remove a previously registered message listener
+     */
+    removeMessageListener(callback: (message: unknown, sender: MessageSender, sendResponse: (response: unknown) => void) => undefined | boolean): void;
+    /**
+     * Create a long-lived connection
+     */
+    connect(name: string): PortAdapter;
+    /**
+     * Listen for incoming connections
+     */
+    onConnect(callback: (port: PortAdapter) => void): void;
+    /**
+     * Get URL for extension resource
+     */
+    getURL(path: string): string;
+    /**
+     * Get extension ID
+     */
+    getId(): string;
+    /**
+     * Open the extension's options page
+     */
+    openOptionsPage(): void;
+}
+export interface PortAdapter {
+    /**
+     * Port name
+     */
+    readonly name: string;
+    /**
+     * Send message through port
+     */
+    postMessage(message: unknown): void;
+    /**
+     * Listen for messages on port
+     */
+    onMessage(callback: (message: unknown) => void): void;
+    /**
+     * Listen for disconnection
+     */
+    onDisconnect(callback: () => void): void;
+    /**
+     * Disconnect port
+     */
+    disconnect(): void;
+}
+export interface MessageSender {
+    tab?: {
+        id: number;
+        url: string;
+        title: string;
+    };
+    frameId?: number;
+    url?: string;
+}

package/dist/shared/adapters/storage.adapter.d.ts

@@ -0,0 +1,29 @@
+export interface StorageAdapter {
+    /**
+     * Get items from storage
+     * @param keys - String, array of strings, object with defaults, or null for all items
+     */
+    get<T = Record<string, unknown>>(keys?: string | string[] | Record<string, unknown> | null): Promise<T>;
+    /**
+     * Set items in storage
+     */
+    set(items: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove items from storage
+     */
+    remove(keys: string | string[]): Promise<void>;
+    /**
+     * Clear all storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Listen for storage changes
+     */
+    onChanged(callback: (changes: StorageChanges, areaName: string) => void): void;
+}
+export interface StorageChanges {
+    [key: string]: {
+        oldValue?: unknown;
+        newValue?: unknown;
+    };
+}

package/dist/shared/adapters/tabs.adapter.d.ts

@@ -0,0 +1,39 @@
+export interface TabsAdapter {
+    /**
+     * Query tabs
+     */
+    query(queryInfo: chrome.tabs.QueryInfo): Promise<chrome.tabs.Tab[]>;
+    /**
+     * Get tab by ID
+     */
+    get(tabId: number): Promise<chrome.tabs.Tab>;
+    /**
+     * Send message to specific tab
+     */
+    sendMessage(tabId: number, message: unknown): Promise<unknown>;
+    /**
+     * Reload tab
+     */
+    reload(tabId: number, reloadProperties?: {
+        bypassCache?: boolean;
+    }): Promise<void>;
+    /**
+     * Listen for tab removal
+     */
+    onRemoved(callback: (tabId: number, removeInfo: chrome.tabs.TabRemoveInfo) => void): void;
+    /**
+     * Listen for tab updates
+     */
+    onUpdated(callback: (tabId: number, changeInfo: chrome.tabs.TabChangeInfo, tab: chrome.tabs.Tab) => void): void;
+    /**
+     * Listen for tab activation
+     */
+    onActivated(callback: (activeInfo: {
+        tabId: number;
+        windowId: number;
+    }) => void): void;
+    /**
+     * Create a new tab
+     */
+    create(createProperties: chrome.tabs.CreateProperties): Promise<chrome.tabs.Tab>;
+}

package/dist/shared/adapters/window.adapter.d.ts

@@ -0,0 +1,14 @@
+export interface WindowAdapter {
+    /**
+     * Post message to window
+     */
+    postMessage(message: unknown, targetOrigin: string): void;
+    /**
+     * Listen for messages
+     */
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    /**
+     * Remove message listener
+     */
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+}

package/dist/shared/lib/context-helpers.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Context Helpers - DX Improvements for Extension Context Initialization
+ *
+ * Provides utilities to reduce boilerplate when initializing extension contexts.
+ */
+import type { BaseMessage, Context, ExtensionMessage } from "../types/messages";
+import { type MessageBus } from "./message-bus";
+export interface ContextConfig<TMessage extends BaseMessage = ExtensionMessage> {
+    /**
+     * Called when the context is initialized.
+     * Use this to register handlers, setup UI, etc.
+     */
+    onInit?: (bus: MessageBus<TMessage>) => Promise<void> | void;
+    /**
+     * Called when an error occurs during initialization or runtime.
+     */
+    onError?: (error: Error, bus: MessageBus<TMessage>) => void;
+    /**
+     * Whether to wait for DOM to be ready before initializing.
+     * Only applies to contexts with a window (popup, options, devtools, sidepanel).
+     * @default true
+     */
+    waitForDOM?: boolean;
+    /**
+     * Custom logger prefix.
+     * @default `[${context}]`
+     */
+    logPrefix?: string;
+}
+/**
+ * Create and initialize an extension context with reduced boilerplate.
+ *
+ * @example
+ * ```typescript
+ * // src/popup/index.ts
+ * createContext<MyMessages>('popup', {
+ *   async onInit(bus) {
+ *     registerHandlers(bus)
+ *     setupUI()
+ *   },
+ *   onError(err) {
+ *     console.error('Popup failed:', err)
+ *   }
+ * })
+ * ```
+ */
+export declare function createContext<TMessage extends BaseMessage = ExtensionMessage>(context: Context, config?: ContextConfig<TMessage>): MessageBus<TMessage>;
+/**
+ * Helper to run code only in specific contexts.
+ * Useful for shared modules that need context-specific behavior.
+ *
+ * @example
+ * ```typescript
+ * // shared/features/analytics.ts
+ * const bus = createContext('popup', { ... })
+ *
+ * if (bus.context === 'popup' || bus.context === 'options') {
+ *   setupUI()
+ * }
+ * ```
+ *
+ * @deprecated Use bus.context directly instead. This function cannot reliably detect context.
+ */
+export declare function runInContext(context: Context, contexts: Context | Context[], fn: (bus: MessageBus) => void | Promise<void>): void;