chrome-proxy

Small helpers for working with Chrome extension APIs in extension and page modes.

• extension: use the real Chrome APIs when the app runs as an extension
• page: use page-safe shims when the app runs as a normal web page

Storage behavior

createChromeStorage('extension')

• uses the Chrome extension APIs directly
• storage.local maps to chrome.storage.local
• storage.session maps to chrome.storage.session
• storage.sync maps to chrome.storage.sync

createChromeStorage('page')

• keeps the same API shape for local, session, and sync
• adds localStorage as a page-friendly alias for local
• adds sessionStorage and syncStorage as page-friendly aliases for session and sync
• exposes chrome.localStorage, chrome.sessionStorage, and chrome.syncStorage globally in page mode for easy local development and testing
• persists page-mode local and sync values through browser localStorage when available
• persists page-mode session values through browser sessionStorage when available
• also exposes the storage shim on window.__chromeProxyPage.storage

Example

import { createChromeStorage } from '@toocoolname/chrome-proxy';

const storage = createChromeStorage('page');

await storage.localStorage.set('theme', 'dark');
await storage.sessionStorage.set('draft', { id: 1 });
await storage.syncStorage.set('prefs', { compact: true });
const theme = await storage.local.get<string>('theme');

// page mode only
await chrome.localStorage.set('token', 'demo');
await chrome.sessionStorage.set('session-id', 'page-mode');
await chrome.syncStorage.set('settings', { compact: true });

const extensionStorage = createChromeStorage('extension');
await extensionStorage.local.set('theme', 'dark'); // uses chrome.storage.local
await extensionStorage.session.set('draft', { id: 1 }); // uses chrome.storage.session
await extensionStorage.sync.set('prefs', { compact: true }); // uses chrome.storage.sync

Message behavior

• createChromeMessage('extension'): uses chrome.runtime and chrome.tabs
• createChromeMessage('page'): uses the in-memory page-mode message bus
• page mode exposes window.__chromeProxyPage.message.dispatchLocal(...)
• page mode exposes window.__chromeProxyPage.message.dispatchExternal(...)

Tabs behavior

• createChromeTabs('extension'): uses chrome.tabs
• createChromeTabs('page'): uses an in-memory tab model with query, get, onUpdated, onRemoved, and onActivated
• page mode exposes window.__chromeProxyPage.tabs for test control

Playwright / MCP

When your UI is loaded as a normal page, create the page-mode shims in the app and then drive them from Playwright with page.evaluate.

import { createChromeMessage, createChromeStorage, createChromeTabs } from '@toocoolname/chrome-proxy';

const storage = createChromeStorage('page');
const message = createChromeMessage('page');
const tabs = createChromeTabs('page');

await page.evaluate(() => {
  window.__chromeProxyPage.tabs.set([
    { id: 1, index: 0, windowId: 1, active: true, highlighted: true, pinned: false, selected: true, incognito: false, discarded: false, autoDiscardable: true, frozen: false, groupId: -1, status: 'complete', url: 'https://app.local/', title: 'App' }
  ]);
});

await page.evaluate(() => {
  return window.__chromeProxyPage.message.dispatchLocal({
    type: 'PING',
    payload: { ok: true }
  });
});

Useful page-mode test hooks:

• window.__chromeProxyPage.storage
• window.__chromeProxyPage.message.dispatchLocal(message, sender?)
• window.__chromeProxyPage.message.dispatchExternal(message, sender?)
• window.__chromeProxyPage.tabs.list()
• window.__chromeProxyPage.tabs.set(tabs)
• window.__chromeProxyPage.tabs.create(tab)
• window.__chromeProxyPage.tabs.update(tabId, updates)
• window.__chromeProxyPage.tabs.activate(tabId)
• window.__chromeProxyPage.tabs.remove(tabId)
• window.__chromeProxyPage.tabs.reset()

TypeScript users can also import the page-bridge types directly from the package.

Notes

• Use chrome.localStorage, chrome.sessionStorage, and chrome.syncStorage only in page mode.
• In extension mode, the actual Chrome APIs are chrome.storage.local, chrome.storage.session, and chrome.storage.sync.