@rune-kit/rune 2.8.0 → 2.11.0

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

@@ -1,139 +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);
-  }
-});
-```
+---
+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);
+  }
+});
+```

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

@@ -1,133 +1,133 @@
----
-name: "ext-storage"
-pack: "@rune/chrome-ext"
-description: "Typed Chrome storage patterns — choose the right storage tier, define schema, implement typed helpers, handle schema migrations, and monitor quota."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# ext-storage
-
-Typed Chrome storage patterns — choose the right storage tier, define schema, implement typed helpers, handle schema migrations, and monitor quota. Prevents the #3 MV3 failure: storing state in service worker JS variables that reset on termination.
-
-#### Workflow
-
-**Step 1 — Choose storage type**
-| Type | Capacity | Persistence | Sync | Use For |
-|------|----------|-------------|------|---------|
-| `chrome.storage.local` | 10 MB | Until uninstall | No | User data, large payloads, cached content |
-| `chrome.storage.sync` | 100 KB / 8 KB per item | Cross-device | Yes | Settings, small preferences |
-| `chrome.storage.session` | 10 MB | Until browser closes | No | Ephemeral state that service worker needs across terminations |
-| `chrome.storage.managed` | Read-only | Admin-controlled | No | Enterprise policy |
-
-CRITICAL: `chrome.storage.session` is the correct replacement for service worker JS variables. If you need state to survive a 30-second termination but clear on browser close, use session storage.
-
-**Step 2 — Define TypeScript storage schema**
-Create `src/types/storage.ts` with versioned schema interface. Include a `version` field for migration tracking.
-
-**Step 3 — Implement typed get/set helpers**
-Create `src/lib/storage.ts` with typed wrappers that preserve the schema type. Avoid `chrome.storage.*.get(null)` which returns `any` — always specify keys.
-
-**Step 4 — Add migration logic**
-On `chrome.runtime.onInstalled` with `reason === 'update'`, check stored schema version and run incremental migrations. Each migration transforms data from version N to N+1.
-
-**Step 5 — Implement quota monitoring**
-Chrome storage has hard limits that throw `QUOTA_BYTES_PER_ITEM` and `QUOTA_BYTES` errors on write. Wrap all writes with error handling and warn the user or prune old data when approaching 80% capacity.
-
-#### Example
-
-```typescript
-// src/types/storage.ts — versioned storage schema
-export const STORAGE_VERSION = 2;
-
-export interface StorageSchema {
-  version: number;
-  settings: {
-    useBuiltinAI: boolean;
-    externalApiKey: string;
-    maxLength: number;
-    theme: 'light' | 'dark' | 'system';
-  };
-  cache: {
-    lastSummary: string;
-    lastUrl: string;
-    timestamp: number;
-  } | null;
-}
-
-export const STORAGE_DEFAULTS: StorageSchema = {
-  version: STORAGE_VERSION,
-  settings: {
-    useBuiltinAI: true,
-    externalApiKey: '',
-    maxLength: 500,
-    theme: 'system',
-  },
-  cache: null,
-};
-```
-
-```typescript
-// src/lib/storage.ts — typed get/set helpers with quota monitoring
-
-import type { StorageSchema } from '../types/storage';
-import { STORAGE_DEFAULTS, STORAGE_VERSION } from '../types/storage';
-
-type StorageKey = keyof StorageSchema;
-
-export async function storageGet<K extends StorageKey>(
-  key: K
-): Promise<StorageSchema[K]> {
-  const result = await chrome.storage.local.get(key);
-  return (result[key] as StorageSchema[K]) ?? STORAGE_DEFAULTS[key];
-}
-
-export async function storageSet<K extends StorageKey>(
-  key: K,
-  value: StorageSchema[K]
-): Promise<void> {
-  try {
-    await chrome.storage.local.set({ [key]: value });
-  } catch (err) {
-    const error = err as Error;
-    if (error.message.includes('QUOTA_BYTES')) {
-      console.warn('[Storage] Quota exceeded — clearing cache');
-      await chrome.storage.local.remove('cache');
-      // retry once after clearing cache
-      await chrome.storage.local.set({ [key]: value });
-    } else {
-      throw err;
-    }
-  }
-}
-
-// Quota monitoring — warn at 80% capacity
-export async function checkStorageQuota(): Promise<void> {
-  const bytesUsed = await chrome.storage.local.getBytesInUse(null);
-  const quota = chrome.storage.local.QUOTA_BYTES; // 10 MB = 10,485,760 bytes
-  const pct = (bytesUsed / quota) * 100;
-  if (pct > 80) {
-    console.warn(`[Storage] ${pct.toFixed(1)}% of local storage used (${bytesUsed} / ${quota} bytes)`);
-  }
-}
-
-// Migration runner — call on onInstalled with reason='update'
-export async function runMigrations(): Promise<void> {
-  const stored = await chrome.storage.local.get('version');
-  const currentVersion = (stored['version'] as number | undefined) ?? 1;
-
-  if (currentVersion < 2) {
-    // v1 → v2: renamed 'apiKey' to 'externalApiKey'
-    const legacy = await chrome.storage.local.get('settings');
-    const legacySettings = legacy['settings'] as Record<string, unknown> | undefined;
-    if (legacySettings?.['apiKey']) {
-      await chrome.storage.local.set({
-        settings: { ...legacySettings, externalApiKey: legacySettings['apiKey'], apiKey: undefined },
-        version: 2,
-      });
-    }
-  }
-
-  await chrome.storage.local.set({ version: STORAGE_VERSION });
-}
-```
+---
+name: "ext-storage"
+pack: "@rune/chrome-ext"
+description: "Typed Chrome storage patterns — choose the right storage tier, define schema, implement typed helpers, handle schema migrations, and monitor quota."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ext-storage
+
+Typed Chrome storage patterns — choose the right storage tier, define schema, implement typed helpers, handle schema migrations, and monitor quota. Prevents the #3 MV3 failure: storing state in service worker JS variables that reset on termination.
+
+#### Workflow
+
+**Step 1 — Choose storage type**
+| Type | Capacity | Persistence | Sync | Use For |
+|------|----------|-------------|------|---------|
+| `chrome.storage.local` | 10 MB | Until uninstall | No | User data, large payloads, cached content |
+| `chrome.storage.sync` | 100 KB / 8 KB per item | Cross-device | Yes | Settings, small preferences |
+| `chrome.storage.session` | 10 MB | Until browser closes | No | Ephemeral state that service worker needs across terminations |
+| `chrome.storage.managed` | Read-only | Admin-controlled | No | Enterprise policy |
+
+CRITICAL: `chrome.storage.session` is the correct replacement for service worker JS variables. If you need state to survive a 30-second termination but clear on browser close, use session storage.
+
+**Step 2 — Define TypeScript storage schema**
+Create `src/types/storage.ts` with versioned schema interface. Include a `version` field for migration tracking.
+
+**Step 3 — Implement typed get/set helpers**
+Create `src/lib/storage.ts` with typed wrappers that preserve the schema type. Avoid `chrome.storage.*.get(null)` which returns `any` — always specify keys.
+
+**Step 4 — Add migration logic**
+On `chrome.runtime.onInstalled` with `reason === 'update'`, check stored schema version and run incremental migrations. Each migration transforms data from version N to N+1.
+
+**Step 5 — Implement quota monitoring**
+Chrome storage has hard limits that throw `QUOTA_BYTES_PER_ITEM` and `QUOTA_BYTES` errors on write. Wrap all writes with error handling and warn the user or prune old data when approaching 80% capacity.
+
+#### Example
+
+```typescript
+// src/types/storage.ts — versioned storage schema
+export const STORAGE_VERSION = 2;
+
+export interface StorageSchema {
+  version: number;
+  settings: {
+    useBuiltinAI: boolean;
+    externalApiKey: string;
+    maxLength: number;
+    theme: 'light' | 'dark' | 'system';
+  };
+  cache: {
+    lastSummary: string;
+    lastUrl: string;
+    timestamp: number;
+  } | null;
+}
+
+export const STORAGE_DEFAULTS: StorageSchema = {
+  version: STORAGE_VERSION,
+  settings: {
+    useBuiltinAI: true,
+    externalApiKey: '',
+    maxLength: 500,
+    theme: 'system',
+  },
+  cache: null,
+};
+```
+
+```typescript
+// src/lib/storage.ts — typed get/set helpers with quota monitoring
+
+import type { StorageSchema } from '../types/storage';
+import { STORAGE_DEFAULTS, STORAGE_VERSION } from '../types/storage';
+
+type StorageKey = keyof StorageSchema;
+
+export async function storageGet<K extends StorageKey>(
+  key: K
+): Promise<StorageSchema[K]> {
+  const result = await chrome.storage.local.get(key);
+  return (result[key] as StorageSchema[K]) ?? STORAGE_DEFAULTS[key];
+}
+
+export async function storageSet<K extends StorageKey>(
+  key: K,
+  value: StorageSchema[K]
+): Promise<void> {
+  try {
+    await chrome.storage.local.set({ [key]: value });
+  } catch (err) {
+    const error = err as Error;
+    if (error.message.includes('QUOTA_BYTES')) {
+      console.warn('[Storage] Quota exceeded — clearing cache');
+      await chrome.storage.local.remove('cache');
+      // retry once after clearing cache
+      await chrome.storage.local.set({ [key]: value });
+    } else {
+      throw err;
+    }
+  }
+}
+
+// Quota monitoring — warn at 80% capacity
+export async function checkStorageQuota(): Promise<void> {
+  const bytesUsed = await chrome.storage.local.getBytesInUse(null);
+  const quota = chrome.storage.local.QUOTA_BYTES; // 10 MB = 10,485,760 bytes
+  const pct = (bytesUsed / quota) * 100;
+  if (pct > 80) {
+    console.warn(`[Storage] ${pct.toFixed(1)}% of local storage used (${bytesUsed} / ${quota} bytes)`);
+  }
+}
+
+// Migration runner — call on onInstalled with reason='update'
+export async function runMigrations(): Promise<void> {
+  const stored = await chrome.storage.local.get('version');
+  const currentVersion = (stored['version'] as number | undefined) ?? 1;
+
+  if (currentVersion < 2) {
+    // v1 → v2: renamed 'apiKey' to 'externalApiKey'
+    const legacy = await chrome.storage.local.get('settings');
+    const legacySettings = legacy['settings'] as Record<string, unknown> | undefined;
+    if (legacySettings?.['apiKey']) {
+      await chrome.storage.local.set({
+        settings: { ...legacySettings, externalApiKey: legacySettings['apiKey'], apiKey: undefined },
+        version: 2,
+      });
+    }
+  }
+
+  await chrome.storage.local.set({ version: STORAGE_VERSION });
+}
+```