Merge branch 'main' into refactor/migration

Author: ishiko732

.agents/skills/webext-core/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation
+
+- Source: https://github.com/aklinker1/webext-core
+- Submodule path: sources/webext-core
+- Commit: `3bfdf7953963c96b54f8dd8f6d2e8824f456273d` — docs: fix redirects (#127)

.agents/skills/webext-core/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: webext-core
+description: Utilities for browser extensions - proxy services for cross-context RPC, type-safe messaging, URL match patterns, fake browser for testing, job scheduling, and shadow DOM isolation.
+---
+
+# webext-core - Browser Extension Utilities
+
+## When to Use
+
+Apply this skill when:
+- `package.json` has any `@webext-core/*` dependency
+- Code imports `defineProxyService`, `flattenPromise` from `@webext-core/proxy-service`
+- Code imports `defineExtensionMessaging`, `defineWindowMessaging` from `@webext-core/messaging`
+- Code uses `MatchPattern` from `@webext-core/match-patterns`
+- Tests use `fakeBrowser` from `@webext-core/fake-browser`
+- Code uses `defineJobScheduler` from `@webext-core/job-scheduler`
+- Code uses `createIsolatedElement` from `@webext-core/isolated-element`
+
+## Quick Reference
+
+| Package | Purpose | Reference |
+|---------|---------|-----------|
+| `@webext-core/proxy-service` | Cross-context RPC — call background services from anywhere | [references/proxy-service.md](references/proxy-service.md) |
+| `@webext-core/messaging` | Type-safe extension/window/custom event messaging | [references/messaging.md](references/messaging.md) |
+| `@webext-core/match-patterns` | URL pattern matching utilities | [references/match-patterns.md](references/match-patterns.md) |
+| `@webext-core/fake-browser` | In-memory browser API for unit testing | [references/fake-browser.md](references/fake-browser.md) |
+| `@webext-core/job-scheduler` | Background job scheduling via Alarms API | [references/job-scheduler.md](references/job-scheduler.md) |
+| `@webext-core/isolated-element` | Shadow DOM containers for content script UIs | [references/isolated-element.md](references/isolated-element.md) |
+| `@webext-core/storage` | localStorage-like wrapper (prefer WXT storage if using WXT) | [references/storage.md](references/storage.md) |
+| Cross-package patterns and anti-patterns | — | [references/patterns.md](references/patterns.md) |
+
+## Most Common Pattern
+
+```ts
+// services/counter.ts
+import { defineProxyService } from '@webext-core/proxy-service';
+
+const [registerCounter, getCounter] = defineProxyService('CounterService', () => {
+  let count = 0;
+  return {
+    increment: () => ++count,
+    getCount: () => count,
+  };
+});
+
+export { registerCounter, getCounter };
+
+// background.ts — register the real implementation
+registerCounter();
+
+// popup or content script — call via proxy (all methods return Promise)
+const counter = getCounter();
+const newCount = await counter.increment();
+```

.agents/skills/webext-core/references/fake-browser.md

@@ -0,0 +1,138 @@
+# webext-core - Fake Browser
+
+Package: `@webext-core/fake-browser`
+
+An in-memory implementation of `webextension-polyfill` for unit testing. Implements the `browser` APIs without requiring a real browser environment.
+
+## Setup (Standalone / Non-WXT)
+
+```ts
+// vitest.setup.ts
+import { fakeBrowser } from '@webext-core/fake-browser';
+
+// Replace the global browser mock with the fake
+vi.mock('webextension-polyfill');
+globalThis.browser = fakeBrowser;
+```
+
+## Setup (WXT)
+
+WXT's `WxtVitest()` plugin configures `fakeBrowser` automatically. Import it from:
+
+```ts
+import { fakeBrowser } from 'wxt/testing';
+```
+
+## Usage in Tests
+
+```ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { fakeBrowser } from '@webext-core/fake-browser';
+
+vi.mock('webextension-polyfill');
+
+describe('my service', () => {
+  beforeEach(() => {
+    fakeBrowser.reset(); // Always reset state between tests
+  });
+
+  it('stores and retrieves data', async () => {
+    await browser.storage.local.set({ key: 'value' });
+    const result = await browser.storage.local.get('key');
+    expect(result).toEqual({ key: 'value' });
+  });
+
+  it('creates and reads alarms', async () => {
+    await browser.alarms.create('test', { delayInMinutes: 1 });
+    const alarm = await browser.alarms.get('test');
+    expect(alarm?.name).toBe('test');
+  });
+});
+```
+
+## Implemented APIs
+
+| API | Status | Notes |
+|---|---|---|
+| `browser.alarms` | Full | `create`, `get`, `getAll`, `clear`, `clearAll`, `onAlarm` |
+| `browser.notifications` | Full | `onClosed`, `onClicked`, `onButtonClicked`, `onShown` |
+| `browser.runtime` | Partial | `id`, `getURL`, `sendMessage`, `onMessage`, `onInstalled`, `onStartup`, `onSuspend`, `onSuspendCanceled`, `onUpdateAvailable` |
+| `browser.storage` | Full | `local`, `session`, `sync`, `managed`; all four support `get`, `set`, `remove`, `clear`, `onChanged` |
+| `browser.tabs` | Partial | `get`, `getCurrent`, `create`, `duplicate`, `query`, `highlight`, `update`, `remove`; `onCreated`, `onUpdated`, `onActivated`, `onHighlighted`, `onRemoved` |
+| `browser.windows` | Partial | `get`, `getAll`, `create`, `getCurrent`, `getLastFocused`, `update`, `remove`; `onCreated`, `onRemoved`, `onFocusChanged` |
+| `browser.webNavigation` | Events only | `onBeforeNavigate`, `onCommitted`, `onDOMContentLoaded`, `onCompleted`, `onErrorOccurred`, `onCreatedNavigationTarget`, `onReferenceFragmentUpdated`, `onTabReplaced`, `onHistoryStateUpdated` |
+
+## `EventForTesting` — Triggering Events in Tests
+
+Every implemented event has a `.trigger(...args)` method that manually fires the event and returns a `Promise` resolving to an array of all listener return values.
+
+```ts
+import { fakeBrowser } from '@webext-core/fake-browser';
+import { vi, expect, it } from 'vitest';
+
+it('handles tab creation', async () => {
+  const handler = vi.fn();
+  browser.tabs.onCreated.addListener(handler);
+
+  // Manually fire the event
+  await fakeBrowser.tabs.onCreated.trigger({
+    id: 1,
+    url: 'https://example.com',
+    active: true,
+    index: 0,
+    pinned: false,
+    highlighted: false,
+    windowId: 1,
+    incognito: false,
+  });
+
+  expect(handler).toHaveBeenCalledOnce();
+});
+
+it('handles alarm firing', async () => {
+  const handler = vi.fn();
+  browser.alarms.onAlarm.addListener(handler);
+
+  await fakeBrowser.alarms.onAlarm.trigger({ name: 'my-alarm', scheduledTime: Date.now() });
+
+  expect(handler).toHaveBeenCalledWith({ name: 'my-alarm', scheduledTime: expect.any(Number) });
+});
+
+it('handles runtime.onInstalled', async () => {
+  const handler = vi.fn();
+  browser.runtime.onInstalled.addListener(handler);
+
+  await fakeBrowser.runtime.onInstalled.trigger({ reason: 'install' });
+
+  expect(handler).toHaveBeenCalledWith({ reason: 'install' });
+});
+```
+
+## `reset()` Between Tests
+
+`fakeBrowser.reset()` clears all in-memory state:
+
+- All stored data in `storage.local`, `storage.session`, `storage.sync`, `storage.managed`
+- All registered alarms
+- All tabs (resets to a default tab)
+- All windows (resets to a default window)
+- All event listeners on every implemented API
+- Resets `runtime.id` to `'test-extension-id'`
+
+```ts
+beforeEach(() => {
+  fakeBrowser.reset();
+});
+```
+
+Omitting this causes state to bleed between tests, producing hard-to-diagnose failures.
+
+## `runtime.id` and `runtime.getURL`
+
+The fake runtime uses `'test-extension-id'` as the extension ID by default:
+
+```ts
+browser.runtime.id; // 'test-extension-id'
+browser.runtime.getURL('/icons/icon.png');
+// 'chrome-extension://test-extension-id/icons/icon.png'
+```

.agents/skills/webext-core/references/isolated-element.md

@@ -0,0 +1,143 @@
+# webext-core - Isolated Element
+
+Package: `@webext-core/isolated-element`
+
+Create a Shadow DOM container for content script UIs. Isolates styles from the host page and controls event bubbling. Supports Chrome, Firefox, and Safari.
+
+## Basic Usage
+
+```ts
+import { createIsolatedElement } from '@webext-core/isolated-element';
+
+const { parentElement, isolatedElement, shadow } = await createIsolatedElement({
+  name: 'my-extension-ui', // valid custom element name (must contain a hyphen)
+  css: {
+    textContent: `
+      p { color: red; font-family: sans-serif; }
+      button { background: #0070f3; color: white; padding: 8px 16px; border: none; }
+    `,
+  },
+});
+
+// Mount your UI inside isolatedElement — styles are scoped here
+const p = document.createElement('p');
+p.textContent = 'Isolated text';
+isolatedElement.appendChild(p);
+
+// Add parentElement to the page DOM to show the UI
+document.body.appendChild(parentElement);
+```
+
+## Returned Values
+
+| Value | Type | Description |
+|---|---|---|
+| `parentElement` | `HTMLElement` | The custom element you append to `document.body` |
+| `isolatedElement` | `HTMLElement` | A `<div>` inside the shadow root; mount your UI here |
+| `shadow` | `ShadowRoot` | The shadow root; use for advanced DOM manipulation |
+
+## `createIsolatedElement` Options
+
+```ts
+export interface CreateIsolatedElementOptions {
+  name: string;                            // Tag name for the shadow host
+  mode?: 'open' | 'closed';               // ShadowRoot.mode, default: 'closed'
+  css?: { url: string } | { textContent: string }; // Styles loaded into shadow DOM
+  isolateEvents?: boolean | string[];      // Stop events from bubbling to host page
+}
+```
+
+### `name`
+
+The tag name used for the shadow host element. Must be a valid HTML tag that supports shadow DOM attachment — either a known semantic element (`div`, `span`, `article`, `aside`, `blockquote`, `body`, `footer`, `h1`–`h6`, `header`, `main`, `nav`, `p`, `section`) or a valid **custom element name**.
+
+Custom element naming rules:
+- Must contain at least one hyphen (`-`)
+- Must be all lowercase
+- Cannot start with a digit
+- Cannot be a reserved name (e.g., `annotation-xml`, `color-profile`, `font-face`, `font-face-src`, `font-face-uri`, `font-face-format`, `font-face-name`, `missing-glyph`)
+
+```ts
+// Valid
+name: 'my-extension-ui'
+name: 'github-line-diff'
+name: 'div'
+
+// Invalid — throws Error
+name: 'myui'        // no hyphen
+name: 'MyExtUI'     // uppercase
+name: '1-ext-ui'    // starts with digit
+```
+
+### `mode`
+
+Shadow DOM mode. Defaults to `'closed'`, which prevents external JavaScript from accessing the shadow root via `element.shadowRoot`. Use `'open'` if you need programmatic access from outside.
+
+### `css`
+
+Inject styles that are scoped to the shadow DOM:
+
+```ts
+// From a URL (fetched at creation time)
+css: { url: browser.runtime.getURL('/content-scripts/style.css') }
+
+// Inline text
+css: { textContent: 'p { color: blue; }' }
+```
+
+### `isolateEvents`
+
+Prevents specified events from bubbling up through the shadow boundary to the host page. Useful to stop the page from intercepting keyboard shortcuts or click events from your UI.
+
+```ts
+// Default set: ['keydown', 'keyup', 'keypress']
+isolateEvents: true
+
+// Custom list
+isolateEvents: ['click', 'keydown', 'keyup', 'input', 'pointerdown']
+```
+
+## Framework Integration (Vue)
+
+```ts
+import { createIsolatedElement } from '@webext-core/isolated-element';
+import { createApp } from 'vue';
+import App from './App.vue';
+import browser from 'webextension-polyfill';
+
+const { parentElement, isolatedElement } = await createIsolatedElement({
+  name: 'my-extension-overlay',
+  css: { url: browser.runtime.getURL('/assets/content-style.css') },
+  mode: 'closed',
+  isolateEvents: true,
+});
+
+const app = createApp(App);
+app.mount(isolatedElement);
+document.body.appendChild(parentElement);
+```
+
+## Framework Integration (React)
+
+```ts
+import { createIsolatedElement } from '@webext-core/isolated-element';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+const { parentElement, isolatedElement } = await createIsolatedElement({
+  name: 'my-extension-panel',
+  css: { textContent: styles },
+  isolateEvents: ['keydown', 'keyup'],
+});
+
+createRoot(isolatedElement).render(<App />);
+document.body.appendChild(parentElement);
+```
+
+## Cleanup
+
+To remove the UI from the page, remove `parentElement` from the DOM:
+
+```ts
+parentElement.remove();
+```