@rune-kit/rune 2.2.0 → 2.2.1

package/extensions/chrome-ext/skills/cws-preflight.md

@@ -0,0 +1,143 @@
+---
+name: "cws-preflight"
+pack: "@rune/chrome-ext"
+description: "Chrome Web Store compliance audit — scan for over-permissioning, remote code execution, CSP violations, missing assets, and generate permission justification text."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# cws-preflight
+
+Chrome Web Store compliance audit — scan for over-permissioning, remote code execution, CSP violations, missing assets, and generate permission justification text. The highest-value skill in this pack: 58% of CWS rejections are preventable compliance errors caught here before submission.
+
+**Top 5 CWS rejection reasons (2024 data):**
+1. Over-permissioning — requesting permissions not demonstrably used in submitted code
+2. Remote code execution — `eval()`, `Function()` constructor, CDN `<script>` tags, `import()` from external URLs
+3. Misleading description — functionality not matching store listing claims
+4. Missing or inaccessible privacy policy — required for any extension that handles user data
+5. Branding violations — trademarked names (Google, Chrome, YouTube) in extension name or icon
+
+**Triggers for manual review (3+ weeks instead of 24-72h):**
+- Broad `host_permissions` with `<all_urls>` or `https://*/*`
+- Sensitive permission combinations: `tabs` + `history` + `cookies`
+- New developer account submitting extension with sensitive permissions
+- Relaxed `content_security_policy` (`unsafe-eval`, `unsafe-inline`)
+- First submission of a new extension (always manual)
+
+#### Workflow
+
+**Step 1 — Lint manifest for over-permissioning**
+Use `Read` on `manifest.json`. For each declared permission, verify it is actually used in source code with `Grep`. Flag any permission declared but not found in `*.ts` / `*.js` source files. Severity: HIGH.
+
+Common over-permissioning patterns to flag:
+- `"tabs"` declared when only `activeTab` is needed (activeTab is granted on user click, requires no declaration)
+- `"history"` declared without `chrome.history.*` usage
+- `"bookmarks"` declared without `chrome.bookmarks.*` usage
+- `"<all_urls>"` in `host_permissions` when specific domains suffice
+- `"cookies"` declared without `chrome.cookies.*` usage
+
+**Step 2 — Scan for remote code execution**
+Use `Grep` to find patterns that trigger automatic CWS rejection:
+
+```
+pattern: "eval\s*\(" → remote code execution
+pattern: "new Function\s*\(" → remote code execution
+pattern: "<script[^>]+src=['\"]https?://" → remote script loading in HTML files
+pattern: "import\s*\(['\"]https?://" → dynamic import from external URL
+```
+
+Flag each result as CRITICAL — these cause automatic rejection with no appeal path.
+
+**Step 3 — Validate Content Security Policy**
+Read the `content_security_policy.extension_pages` value from `manifest.json`. Flag any of:
+- `'unsafe-eval'` in `script-src` — allows eval, triggers rejection
+- `'unsafe-inline'` in `script-src` — allows inline scripts, triggers rejection
+- External domains in `script-src` (anything not `'self'`) — remote code execution risk
+- Missing CSP entirely — defaults to `script-src 'self'` which is fine, but document it
+
+**Step 4 — Verify privacy policy**
+Check if the extension collects user data (network requests to external servers, `chrome.storage` usage, content script reading page content). If yes:
+- Privacy policy URL must be set in CWS Developer Dashboard
+- Privacy policy must be publicly accessible (verify URL is live)
+- Generate a minimal privacy policy template if none exists
+
+**Step 5 — Check required assets**
+Verify the following exist at declared paths in `manifest.json`:
+- Icon at 128×128px (required for store listing)
+- Screenshots: at least 1, dimensions 1280×800 or 640×400 (PNG or JPEG)
+- Promotional tile: 440×280px (optional but strongly recommended)
+- All declared icons (16, 32, 48, 128px) present at referenced paths
+
+Use `Glob` to verify file existence. Use `Bash` to check image dimensions with `file` or `identify` if ImageMagick is available.
+
+**Step 6 — Generate permission justification text**
+For each declared permission, generate CWS-ready justification text. The CWS dashboard requires one justification per permission. Justifications must be specific — "We need this to work" is rejected.
+
+**Step 7 — Produce preflight report**
+Write `.rune/chrome-ext/preflight-report.md` with:
+- PASS / WARN / FAIL per check
+- Specific file + line for each issue
+- Fix instructions
+- Estimated review timeline (fast-track vs manual review triggers)
+- Submission checklist
+
+#### Example
+
+```markdown
+<!-- .rune/chrome-ext/preflight-report.md (generated by cws-preflight) -->
+
+# CWS Preflight Report — Page Summarizer v1.0.0
+Generated: 2026-03-12
+
+## Summary
+| Check | Status | Issues |
+|-------|--------|--------|
+| Permissions audit | ⚠️ WARN | 1 over-permission |
+| Remote code execution | ✅ PASS | None found |
+| Content Security Policy | ✅ PASS | Correct default |
+| Privacy policy | ⚠️ WARN | URL not set in manifest |
+| Required assets | ✅ PASS | All present |
+| Permission justifications | ✅ READY | Generated below |
+
+## Issues
+
+### WARN: Over-permission — `"tabs"` not required
+**File**: manifest.json line 7
+**Detail**: `"tabs"` permission is declared but no `chrome.tabs.*` API calls found in source.
+The extension uses `activeTab` (implicit on action click) — remove `"tabs"` from permissions array.
+**Fix**: Remove `"tabs"` from `"permissions"` array.
+
+### WARN: Privacy policy URL missing
+**Detail**: Extension reads page content via content script (content.ts:L12 — `document.body.innerText`).
+This constitutes user data handling and requires a privacy policy URL in the CWS Developer Dashboard.
+**Fix**: Add privacy policy URL at publish time. Template: `.rune/chrome-ext/privacy-policy-template.md`
+
+## Permission Justifications (paste into CWS dashboard)
+
+### activeTab
+"The extension reads the content of the current active tab when the user clicks the toolbar button
+to initiate a summarization. No data is collected without explicit user action."
+
+### storage
+"The extension stores user settings (AI preference, API key, summary length) locally to persist
+preferences between browser sessions. No data is synced externally."
+
+### sidePanel
+"The extension uses the Side Panel API to display AI-generated summaries in a persistent panel
+without obscuring the page content."
+
+## Estimated Review Timeline
+- No sensitive permissions detected
+- No broad host_permissions
+- Timeline: **24–72 hours** (standard review)
+- Recommendation: submit Tuesday–Thursday for fastest turnaround
+
+## Submission Checklist
+- [ ] Remove `"tabs"` from permissions array
+- [ ] Add privacy policy URL to CWS Developer Dashboard
+- [ ] Upload 1280×800 screenshot showing extension in use
+- [ ] Write store description (min 132 chars for detailed description)
+- [ ] Set category: Productivity
+- [ ] Set language: English
+- [ ] $5 one-time developer registration fee paid
+```

package/extensions/chrome-ext/skills/cws-publish.md

@@ -0,0 +1,104 @@
+---
+name: "cws-publish"
+pack: "@rune/chrome-ext"
+description: "Chrome Web Store listing preparation and submission guide — store listing copy, screenshot descriptions, permission justifications, visibility settings, and timeline expectations."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# cws-publish
+
+Chrome Web Store listing preparation and submission guide — store listing copy, screenshot descriptions, permission justifications, visibility settings, and timeline expectations. Produces a ready-to-paste store listing document.
+
+#### Workflow
+
+**Step 1 — Verify preflight passed**
+Check for `.rune/chrome-ext/preflight-report.md`. If it does not exist or contains FAIL items, halt and direct user to run `cws-preflight` first. WARN items should be reviewed and resolved before submission.
+
+**Step 2 — Prepare store listing copy**
+Generate CWS listing text following Google's constraints:
+- **Name**: max 45 characters. Must not include trademarked names (Google, Chrome, YouTube, Gmail). Cannot include "Extension" (Chrome adds it automatically).
+- **Short description**: max 132 characters. First thing users see in search results — front-load the value proposition.
+- **Detailed description**: no hard limit but 400–800 words is optimal. Structure: opening hook (1 sentence) → feature bullets (5-7) → how it works (2-3 sentences) → privacy statement (1-2 sentences).
+- Avoid keyword stuffing — Google's policy considers it spam.
+
+**Step 3 — Generate screenshot descriptions**
+CWS screenshots need captions (optional but recommended). Generate 3-5 screenshot scenarios showing distinct use cases. Each screenshot should be 1280×800 or 640×400 pixels, PNG or JPEG, <2MB.
+
+**Step 4 — Fill permission justifications**
+Pull from `cws-preflight` output. Each permission needs a one-paragraph justification in plain English. Write from the user's perspective: "This permission allows the extension to..." not "We need this to...".
+
+**Step 5 — Choose visibility and distribution**
+| Visibility | Use Case |
+|------------|----------|
+| Public | Visible in CWS search — default for most extensions |
+| Unlisted | Direct URL only — good for beta testing with known users |
+| Private | Team-only — enterprise internal tools |
+
+Select distribution regions (default: all). Consider unlisted for v1.0 while gathering initial feedback, then switch to public after first positive reviews.
+
+**Step 6 — Generate submission guide with timeline**
+Emit `.rune/chrome-ext/store-listing.md` with all copy ready to paste. Include submission steps and timeline expectations.
+
+**Timeline expectations:**
+- Simple extension, experienced developer account, no sensitive permissions: **24–72 hours**
+- Sensitive permissions (`tabs`, `history`, `cookies`, `management`): **3–7 business days**
+- Broad `host_permissions` or first submission: **up to 3 weeks** (manual review queue)
+- Rejection: **10-day resubmission window** after fixing issues; same review time applies
+
+**Submission tips:**
+- Never submit on Friday — reviewers are less available Mon-Tue; submit Tue-Thu
+- Use `optional_permissions` for non-critical features — reduces barrier to install and CWS scrutiny
+- `optional_host_permissions` can be requested at runtime, reducing declared permissions
+- Version bump required for each resubmission after rejection
+- Include a test account in submission notes if extension requires authentication
+
+#### Example
+
+```markdown
+<!-- .rune/chrome-ext/store-listing.md (generated by cws-publish) -->
+
+# CWS Store Listing — Page Summarizer
+
+## Name (max 45 chars)
+Page Summarizer — AI-Powered Summaries
+(38 chars ✅)
+
+## Short Description (max 132 chars)
+Summarize any webpage instantly with built-in Chrome AI. One click, no account required, no data sent externally.
+(113 chars ✅)
+
+## Detailed Description
+Tired of spending 10 minutes reading a page to find out it wasn't worth your time?
+
+**Page Summarizer** gives you the core ideas of any webpage in seconds — powered by Chrome's built-in Gemini Nano model, which runs entirely on your device.
+
+**Features:**
+- One-click summarization — click the toolbar button or select text to summarize a section
+- Built-in AI — no API key required, no data leaves your device (requires Chrome 138+ with AI hardware support)
+- External API fallback — configure your own OpenAI or Anthropic key for older hardware
+- Summary length control — short (100 words), medium (300 words), or detailed (500 words)
+- Side panel view — summaries appear in a non-intrusive panel alongside the page
+- Dark mode support
+
+**How it works:**
+Click the toolbar button on any page. The extension reads the visible text and generates a summary using the on-device Gemini Nano model. If your hardware does not support built-in AI, the extension falls back to an external API of your choice (optional — extension still works without it in built-in AI mode).
+
+**Privacy:**
+No user data is collected, stored, or transmitted without your action. Summaries generated via the built-in AI model never leave your device. External API calls (if configured) are made directly to the API provider — not through any intermediary server.
+
+## Screenshots (1280x800px)
+
+1. **Main Use** — Extension sidebar showing a 3-paragraph summary of a news article beside the original page.
+2. **Settings** — Settings panel showing AI model selector, API key field, and length preference.
+3. **Text Selection** — Right-click context menu on selected text showing "Summarize selection" option.
+
+## Category
+Productivity
+
+## Language
+English
+
+## Submission Notes (visible to reviewers, not users)
+Test the extension on https://en.wikipedia.org/wiki/Artificial_intelligence — click the toolbar button to summarize. The extension requires Chrome 138+ for built-in AI. On older Chrome versions, configure an external API key in Settings to test the fallback path.
+```

package/extensions/chrome-ext/skills/ext-ai-integration.md

@@ -0,0 +1,251 @@
+---
+name: "ext-ai-integration"
+pack: "@rune/chrome-ext"
+description: "Chrome built-in AI and external API integration — detect AI type, check hardware requirements, implement Gemini Nano with graceful fallback, wire streaming responses via ports, handle rate limits, and test offline behavior."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ext-ai-integration
+
+Chrome built-in AI and external API integration — detect AI type, check hardware requirements, implement Gemini Nano with graceful fallback, wire streaming responses via ports, handle rate limits, and test offline behavior. The differentiating skill for next-generation extensions.
+
+**Chrome AI APIs (Chrome 138+ stable):**
+| API | Namespace | Purpose |
+|-----|-----------|---------|
+| Prompt API | `chrome.aiLanguageModel` | General text generation, Q&A, classification |
+| Summarizer | `chrome.aiSummarizer` | Condense long text |
+| Writer | `chrome.aiWriter` | Generate new content from prompts |
+| Rewriter | `chrome.aiRewriter` | Transform existing text (tone, length, format) |
+| Translator | `chrome.aiTranslator` | Language translation |
+| Language Detector | `chrome.aiLanguageDetector` | Detect text language |
+
+**Hardware requirements for Gemini Nano:**
+- Storage: 22 GB free disk space (model download)
+- RAM: 4 GB VRAM (dedicated GPU) OR 16 GB system RAM (CPU inference)
+- OS: macOS 13+, Windows 10/11 64-bit, ChromeOS (no Linux support)
+- Cannot be checked programmatically — use capability API and handle `NotSupportedError`
+
+**Manifest permission:**
+```json
+{ "permissions": ["aiLanguageModelParams"] }
+```
+
+#### Workflow
+
+**Step 1 — Detect AI integration type**
+Use `Read` on existing source and `manifest.json` to determine:
+- Does `"aiLanguageModelParams"` appear in permissions? → Built-in Nano intended
+- Does code reference `openai`, `anthropic`, `fetch` to an external AI endpoint? → External API
+- Neither? → Need to design integration from scratch
+
+Ask the user: "Do you want to use Chrome's built-in Gemini Nano (no API cost, runs on device, requires Chrome 138+ and compatible hardware), an external API (OpenAI/Anthropic, requires API key and network), or both with automatic fallback?"
+
+**Step 2 — Check hardware capability for Nano**
+`chrome.aiLanguageModel.capabilities()` returns `{ available: 'readily' | 'after-download' | 'no' }`. Map these:
+- `'readily'` → model is downloaded, use immediately
+- `'after-download'` → model needs download (~2GB), show progress UI and wait
+- `'no'` → hardware not supported, fall through to fallback
+
+This check MUST happen in the service worker (not content script — restricted APIs). Cache the result in `chrome.storage.session` to avoid repeated capability checks.
+
+**Step 3 — Implement with graceful fallback chain**
+Fallback chain: Gemini Nano → External API → Static response
+
+Each tier is a distinct function with the same signature. The orchestrator tries each in order, catching `NotSupportedError`, network errors, and quota errors.
+
+**Step 4 — Wire streaming responses via port messaging**
+AI streaming MUST use ports — not `sendMessage`. `sendMessage` is one-shot: the response is sent once and the channel closes. Streaming requires a port to send multiple `CHUNK` messages followed by a `DONE` message.
+
+See `ext-messaging` skill for port setup. Streaming pattern:
+1. Sidebar/popup opens a port named `'ai-stream'`
+2. Sends `{ text: inputText }` to start generation
+3. Service worker receives, calls `session.promptStreaming()`
+4. For each chunk in the async iterator, posts `{ type: 'CHUNK', content: chunk }` back on the port
+5. On completion, posts `{ type: 'DONE' }` and calls `session.destroy()`
+
+**Step 5 — Handle rate limits and quota**
+Chrome built-in AI has per-session token limits. External APIs have rate limits and cost.
+- Per session: call `session.destroy()` after each summary to free context window
+- External API: implement exponential backoff on 429 responses (1s, 2s, 4s, cap 30s)
+- User-facing: show token usage in settings panel if using external API
+
+**Step 6 — Test offline behavior**
+Extensions may run without network. Test:
+- Built-in Nano: works offline (on-device model)
+- External API: fails offline — catch `TypeError: Failed to fetch` and show "No network connection" message
+- Storage: `chrome.storage.local` works offline
+- Service worker: registers and responds to messages offline
+
+#### Example
+
+```typescript
+// src/lib/ai.ts — AI integration with graceful fallback
+import { storageGet } from './storage';
+
+export interface AiSummaryResult {
+  summary: string;
+  source: 'builtin' | 'external' | 'error';
+  error?: string;
+}
+
+// Check and cache Nano capability
+export async function getNanoCapability(): Promise<'readily' | 'after-download' | 'no'> {
+  // Check session cache first (avoid repeated API calls)
+  const cached = await chrome.storage.session.get('nanoCapability');
+  if (cached['nanoCapability']) return cached['nanoCapability'] as 'readily' | 'after-download' | 'no';
+
+  const caps = await chrome.aiLanguageModel.capabilities();
+  await chrome.storage.session.set({ nanoCapability: caps.available });
+  return caps.available;
+}
+
+// Tier 1: Gemini Nano (built-in, on-device)
+async function summarizeWithNano(text: string): Promise<string> {
+  const capability = await getNanoCapability();
+
+  if (capability === 'no') {
+    throw new Error('NotSupportedError: Built-in AI not available on this device');
+  }
+
+  if (capability === 'after-download') {
+    // Notify UI that model is downloading — caller can show progress
+    // Download starts automatically when create() is called
+    chrome.runtime.sendMessage({ type: 'AI_DOWNLOADING' });
+  }
+
+  const session = await chrome.aiLanguageModel.create({
+    systemPrompt: 'You are a concise summarizer. Summarize the provided text in 3-5 sentences.',
+  });
+
+  try {
+    const summary = await session.prompt(
+      `Summarize this text:\n\n${text.slice(0, 4000)}` // context window limit
+    );
+    return summary;
+  } finally {
+    session.destroy(); // always destroy to free resources
+  }
+}
+
+// Tier 2: External API (OpenAI-compatible)
+async function summarizeWithExternalApi(text: string): Promise<string> {
+  const settings = await storageGet('settings');
+  if (!settings.externalApiKey) {
+    throw new Error('No external API key configured');
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 30_000);
+
+  try {
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${settings.externalApiKey}`,
+      },
+      body: JSON.stringify({
+        model: 'gpt-4o-mini',
+        messages: [
+          { role: 'system', content: 'Summarize the provided text in 3-5 sentences.' },
+          { role: 'user', content: text.slice(0, 8000) },
+        ],
+        max_tokens: 300,
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      if (response.status === 429) throw new Error('RateLimitError');
+      throw new Error(`API error: ${response.status}`);
+    }
+
+    const data = await response.json() as {
+      choices: Array<{ message: { content: string } }>;
+    };
+    return data.choices[0]?.message.content ?? '';
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// Orchestrator — tries each tier in order
+export async function summarize(text: string): Promise<AiSummaryResult> {
+  const settings = await storageGet('settings');
+
+  if (settings.useBuiltinAI) {
+    try {
+      const summary = await summarizeWithNano(text);
+      return { summary, source: 'builtin' };
+    } catch (err) {
+      console.warn('[AI] Nano failed, falling back to external API:', err);
+    }
+  }
+
+  if (settings.externalApiKey) {
+    try {
+      const summary = await summarizeWithExternalApi(text);
+      return { summary, source: 'external' };
+    } catch (err) {
+      console.error('[AI] External API failed:', err);
+      return {
+        summary: '',
+        source: 'error',
+        error: err instanceof Error ? err.message : 'Unknown error',
+      };
+    }
+  }
+
+  return {
+    summary: '',
+    source: 'error',
+    error: 'No AI source available. Enable built-in AI or configure an external API key in Settings.',
+  };
+}
+```
+
+```typescript
+// Streaming with port (service worker side)
+// background.ts
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name !== 'ai-stream') return;
+
+  let session: chrome.aiLanguageModel.LanguageModel | null = null;
+
+  port.onMessage.addListener(async (message: { text: string }) => {
+    try {
+      const capability = await getNanoCapability();
+      if (capability === 'no') throw new Error('NotSupportedError');
+
+      session = await chrome.aiLanguageModel.create({
+        systemPrompt: 'Summarize concisely.',
+      });
+
+      const stream = session.promptStreaming(
+        `Summarize:\n\n${message.text.slice(0, 4000)}`
+      );
+
+      let previous = '';
+      for await (const chunk of stream) {
+        // Chrome's streaming returns cumulative text — extract the delta
+        const delta = chunk.slice(previous.length);
+        previous = chunk;
+        port.postMessage({ type: 'CHUNK', content: delta });
+      }
+
+      port.postMessage({ type: 'DONE' });
+    } catch (err) {
+      port.postMessage({ type: 'ERROR', error: String(err) });
+    } finally {
+      session?.destroy();
+      session = null;
+    }
+  });
+
+  port.onDisconnect.addListener(() => {
+    session?.destroy();
+    session = null;
+  });
+});
+```

package/extensions/chrome-ext/skills/ext-messaging.md

@@ -0,0 +1,139 @@
+---
+name: "ext-messaging"
+pack: "@rune/chrome-ext"
+description: "Typed message passing between popup, service worker, and content script — discriminated union message types, one-shot sendMessage, long-lived port connections for streaming, and Chrome 146+ error handling."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ext-messaging
+
+Typed message passing between popup, service worker, and content script — discriminated union message types, one-shot `sendMessage`, long-lived port connections for streaming, and Chrome 146+ error handling. Prevents the #2 MV3 failure: untyped `any` messages, missing `return true` for async handlers, and ports used for single messages.
+
+#### Workflow
+
+**Step 1 — Identify message flows**
+Use `Grep` to find existing `chrome.runtime.sendMessage`, `chrome.tabs.sendMessage`, and `chrome.runtime.connect` calls. Map the full message topology:
+- popup → service worker (sendMessage — one-shot)
+- service worker → content script (chrome.tabs.sendMessage — requires tab ID)
+- content script → service worker (sendMessage — one-shot)
+- service worker → popup (port — only if popup is open)
+- streaming AI responses → use Port (not sendMessage — ports survive multiple sends)
+
+**Step 2 — Define TypeScript message types**
+Create `src/types/messages.ts` with a discriminated union covering all message directions. Each message type has a `type` literal and a strongly-typed `payload`. Response types are paired per message type.
+
+**Step 3 — Implement chrome.runtime.sendMessage patterns**
+For one-shot request/response between extension contexts. Key rules:
+- Listener must `return true` if the response is sent asynchronously (inside a Promise or async function)
+- `chrome.runtime.lastError` MUST be checked in the callback — unhandled errors throw in MV3
+- Content scripts cannot receive messages via `chrome.runtime.sendMessage` — use `chrome.tabs.sendMessage` from the service worker with the target tab's ID
+
+**Step 4 — Implement chrome.tabs.sendMessage (service worker → content)**
+Service worker must resolve the target tab ID before sending. Use `chrome.tabs.query({ active: true, currentWindow: true })` or receive the tab ID from the content script's original message (sender.tab.id).
+
+**Step 5 — Implement port-based long-lived connections**
+Use `chrome.runtime.connect` for streaming scenarios (AI token streaming, progress updates, live data feeds). Ports stay open until explicitly disconnected. Each side must handle `port.onDisconnect` to clean up.
+
+**Step 6 — Add Chrome 146+ error handling**
+Chrome 146 changed message listener error behavior: uncaught errors in listeners now reject the Promise returned by `sendMessage` on the sender side. Wrap all listener handlers in try/catch and send structured error responses.
+
+#### Example
+
+```typescript
+// src/types/messages.ts — discriminated union message types
+export type ExtensionMessage =
+  | { type: 'SUMMARIZE_PAGE'; payload: { text: string; tabId: number } }
+  | { type: 'GET_SETTINGS'; payload: Record<string, never> }
+  | { type: 'UPDATE_SETTINGS'; payload: Partial<Settings> }
+  | { type: 'OPEN_SIDEBAR'; payload: { tabId: number } };
+
+export type ExtensionResponse<T extends ExtensionMessage> =
+  T extends { type: 'SUMMARIZE_PAGE' } ? { summary: string; error?: string } :
+  T extends { type: 'GET_SETTINGS' } ? { settings: Settings } :
+  T extends { type: 'UPDATE_SETTINGS' } ? { ok: boolean } :
+  T extends { type: 'OPEN_SIDEBAR' } ? { ok: boolean } :
+  never;
+
+export interface Settings {
+  useBuiltinAI: boolean;
+  externalApiKey: string;
+  maxLength: number;
+}
+```
+
+```typescript
+// background.ts — typed message handler
+import type { ExtensionMessage } from './types/messages';
+
+chrome.runtime.onMessage.addListener(
+  (message: ExtensionMessage, sender, sendResponse) => {
+    // CRITICAL: return true to keep channel open for async response
+    (async () => {
+      try {
+        switch (message.type) {
+          case 'SUMMARIZE_PAGE': {
+            const summary = await summarize(message.payload.text);
+            sendResponse({ summary });
+            break;
+          }
+          case 'GET_SETTINGS': {
+            const result = await chrome.storage.sync.get('settings');
+            sendResponse({ settings: result['settings'] as Settings });
+            break;
+          }
+          default:
+            sendResponse({ error: 'Unknown message type' });
+        }
+      } catch (err) {
+        // Chrome 146+: send error response instead of letting it throw
+        sendResponse({ error: String(err) });
+      }
+    })();
+    return true; // MUST return true — async response
+  }
+);
+```
+
+```typescript
+// Port-based streaming (service worker → sidebar/popup)
+// background.ts
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name !== 'ai-stream') return;
+
+  port.onMessage.addListener(async (message: { text: string }) => {
+    try {
+      const session = await chrome.aiLanguageModel.create();
+      const stream = session.promptStreaming(message.text);
+
+      for await (const chunk of stream) {
+        port.postMessage({ type: 'CHUNK', content: chunk });
+      }
+      port.postMessage({ type: 'DONE' });
+      session.destroy();
+    } catch (err) {
+      port.postMessage({ type: 'ERROR', error: String(err) });
+    }
+  });
+
+  port.onDisconnect.addListener(() => {
+    // cleanup — sidebar/popup was closed
+  });
+});
+
+// sidebar.ts — connect and stream
+const port = chrome.runtime.connect({ name: 'ai-stream' });
+port.postMessage({ text: selectedText });
+
+port.onMessage.addListener((msg: { type: string; content?: string; error?: string }) => {
+  if (msg.type === 'CHUNK') appendToOutput(msg.content ?? '');
+  if (msg.type === 'DONE') finalizeOutput();
+  if (msg.type === 'ERROR') showError(msg.error ?? 'Unknown error');
+});
+
+port.onDisconnect.addListener(() => {
+  if (chrome.runtime.lastError) {
+    console.error('[Sidebar] Port disconnected with error:', chrome.runtime.lastError.message);
+  }
+});
+```