From 927f4e444ab57d7f8369b5b675b542f3e808fd18 Mon Sep 17 00:00:00 2001
From: heznpc <heznpc@gmail.com>
Date: Sun, 26 Apr 2026 22:36:20 +0900
Subject: [PATCH] =?UTF-8?q?fix:=20production=20hotfixes=20for=20v3.5.6=20?=
 =?UTF-8?q?=E2=80=94=206=20bugs=20surfaced=20as=20users=20grow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A deep production-readiness audit (and four direct re-reads to verify) found
six bugs that get worse at scale. Two are user-visible right now; the rest
amplify with traffic.

1. Bridge timeout silent fail (CRITICAL)
   `_injectPageBridge` resolved the readiness promise even on timeout, with
   `isReady` left false. Every later `_sendRequest` rejected "Bridge not
   ready" forever — tutor and Gemini block translation died until reload, no
   UI signal. Now flips a `bridgeFailed` flag and dispatches
   `skillbridge:bridgeunavailable`; content.js renders a persistent banner
   asking the user to refresh.

2. pushState/replaceState wrapper stacking (CRITICAL)
   The history monkey-patches had no idempotency guard, so an extension
   reload (auto-update, dev refresh) captured the previous wrapper as the
   "original" and stacked. Each reload doubled `onRouteChange` per nav,
   amplifying GT load. Guard with `__sb_wrapped__`.

3. Cache-cleanup alarm dead code (HIGH)
   Background sent `{ type: 'CACHE_CLEANUP' }` but the content-script
   handler keys on `request.action`. The 24h alarm reached the default
   "Unknown action" branch and silently no-op'd in long-pinned tabs. The
   page-load fallback still ran, so the bug was hidden — but the alarm
   itself is now unified on `{ action: 'cacheCleanup' }` with a real case.

4. GT rate-limit dropped translations (HIGH)
   `googleTranslateBatch` returned the original English text on rate-limit,
   which content.js silently skipped because `translated === source` looks
   like a no-op. On large lessons over 120 strings/min users got a
   half-translated page. Replaced with a polling `_rateLimiter.acquire()`
   that paces the batch instead. Failed items now return `null` for
   consistent skip-and-retry semantics.

5. Progress UI stuck on language switch (HIGH)
   Mid-batch `gtGeneration` mismatches early-returned past
   `hideTranslationProgress` and `pruneDetachedEntries`, leaving the
   progress bar and verify spinners on screen. Wrapped the loop in
   try/finally so cleanup always runs. Term-preview only fires when the
   generation is still current.

6. Chat history quota silently dropped messages (MEDIUM)
   `pruneOldHistory` deleted the oldest 20 entries on `QuotaExceededError`
   but never retried the failed `add()`, losing the conversation. Now
   `saveConversation` retries once after pruning, and `pruneOldHistory`
   resolves on `tx.oncomplete` so the retry sees the freed space.

Plus one preventative cleanup:
- Drop the `tabs` permission from manifest. Both `chrome.tabs.query` and
  `chrome.tabs.sendMessage` work via `host_permissions` matching the active
  tab. The broader `tabs` permission was unused and triggered the "read
  your browsing history" string in the CWS install prompt.

Version 3.5.5 → 3.5.6. Tests 309/309 pass; lint, format, selector health,
dicts, bg-sync, glossary, translate validate, firefox build, bundle build
all green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                 |  13 ++
 README.md                    |   2 +-
 docs/index.html              |   4 +-
 eslint.config.mjs            |   1 +
 manifest.json                |   3 +-
 package.json                 |   2 +-
 src/background/background.js |  28 ++++-
 src/content/content.js       | 233 ++++++++++++++++++++---------------
 src/content/sidebar-chat.js  |  47 ++++---
 src/data/de.json             |   2 +-
 src/data/es.json             |   2 +-
 src/data/fr.json             |   2 +-
 src/data/ja.json             |   2 +-
 src/data/ko.json             |   2 +-
 src/data/pt-BR.json          |   2 +-
 src/data/ru.json             |   2 +-
 src/data/vi.json             |   2 +-
 src/data/zh-CN.json          |   2 +-
 src/data/zh-TW.json          |   2 +-
 src/lib/constants.js         |  14 +++
 src/lib/translator.js        |   7 +-
 21 files changed, 242 insertions(+), 132 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6844db6..b8007cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.5.6] - 2026-04-26
+
+### Fixed
+- AI features no longer fail silently when the Puter.js bridge fails to confirm `BRIDGE_READY` within 20 s. The translator now flips a `bridgeFailed` flag and dispatches `skillbridge:bridgeunavailable`; content.js shows a persistent banner asking the user to refresh.
+- `history.pushState` / `history.replaceState` wrappers are now idempotent. Extension reloads (auto-update, dev refresh) used to capture the previous wrapper as the "original" and stack handlers, doubling `onRouteChange` calls per SPA nav and amplifying GT load.
+- Cache-cleanup alarm now actually runs in active tabs. Background sent `{ type: 'CACHE_CLEANUP' }` but the content-script handler keys on `request.action`, so the 24 h alarm was dead code. Unified on `{ action: 'cacheCleanup' }` with a matching switch case.
+- Google Translate rate-limit overflow no longer leaves elements in English. `_rateLimiter` now exposes an `acquire()` method that paces the batch instead of returning the source text (which content.js silently skips); the GT batch-item failure path also returns `null` for consistency.
+- Translation progress bar and verify spinners are no longer stuck when the user switches language mid-batch. `processGTQueue` is now wrapped in `try/finally` so `hideTranslationProgress`, `pruneDetachedEntries`, and the gemini-block flush always run.
+- Chat history is no longer silently dropped on `QuotaExceededError`. `saveConversation` now retries the `add()` once after `pruneOldHistory` deletes the oldest 20 entries, and `pruneOldHistory` resolves on the transaction's `oncomplete` so the retry sees the freed space.
+
+### Changed
+- Drop the `tabs` permission from `manifest.json`. Both `chrome.tabs.query` and `chrome.tabs.sendMessage` rely on `host_permissions` matching the active tab — the broader `tabs` permission was unused. Removes the "read your browsing history" warning string in the CWS install prompt.
+
 ## [3.5.5] - 2026-04-19
 
 ### Added
diff --git a/README.md b/README.md
index b535cb7..bd9b9e9 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 <img src="assets/icons/icon128.png" alt="SkillBridge" width="90" />
 
-# SkillBridge for Anthropic Academy <!-- VERSION_START -->v3.5.5<!-- VERSION_END -->
+# SkillBridge for Anthropic Academy <!-- VERSION_START -->v3.5.6<!-- VERSION_END -->
 
 > Available in multiple languages at the [project landing page](https://heznpc.github.io/skillBridge/).
 
diff --git a/docs/index.html b/docs/index.html
index 93805f7..ffd9664 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -6,7 +6,7 @@
   <title>SkillBridge — AI Course Translator for <!-- LANG_COUNT_START -->32+<!-- LANG_COUNT_END --> Languages</title>
   <meta name="description" content="Free Chrome extension to translate Anthropic Academy courses into <!-- LANG_COUNT_START -->32+<!-- LANG_COUNT_END --> languages with AI-powered tutoring. No API keys needed.">
   <meta property="og:title" content="SkillBridge — AI Course Translator">
-  <meta property="og:description" content="Learn Anthropic's free AI courses in your language. Powered by <!-- VERSION_START -->v3.5.5<!-- VERSION_END -->.">
+  <meta property="og:description" content="Learn Anthropic's free AI courses in your language. Powered by <!-- VERSION_START -->v3.5.6<!-- VERSION_END -->.">
   <meta property="og:type" content="website">
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -255,7 +255,7 @@
 <body>
   <section class="hero">
     <div class="container">
-      <div class="hero-badge"><!-- VERSION_START -->v3.5.5<!-- VERSION_END --> &middot; Open Source &middot; Free &middot; No API Key</div>
+      <div class="hero-badge"><!-- VERSION_START -->v3.5.6<!-- VERSION_END --> &middot; Open Source &middot; Free &middot; No API Key</div>
       <h1>Learn Anthropic Courses<br>In Your Language</h1>
       <p>A Chrome extension that translates Anthropic Academy courses into <!-- LANG_COUNT_START -->32+<!-- LANG_COUNT_END --> languages with an AI-powered learning assistant.</p>
       <p style="font-size:13px;opacity:0.85;margin-top:-16px;">Not affiliated with, endorsed by, or sponsored by Anthropic.</p>
diff --git a/eslint.config.mjs b/eslint.config.mjs
index b4309af..c0a237f 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -79,6 +79,7 @@ export default [
         TERM_PREVIEW_LABELS: 'readonly',
         FLASHCARD_COURSE_MAP: 'readonly',
         FLASHCARD_COURSE_SLUGS_SORTED: 'readonly',
+        BRIDGE_UNAVAILABLE_LABELS: 'readonly',
         CODE_COMMENT_PATTERNS: 'readonly',
         COMMENT_TRANSLATE_LABELS: 'readonly',
         // Classes from other content scripts
diff --git a/manifest.json b/manifest.json
index 84edd08..7554e23 100644
--- a/manifest.json
+++ b/manifest.json
@@ -2,14 +2,13 @@
   "manifest_version": 3,
   "name": "__MSG_extName__",
   "description": "__MSG_extDescription__",
-  "version": "3.5.5",
+  "version": "3.5.6",
   "minimum_chrome_version": "120",
   "author": "SkillBridge Contributors",
   "homepage_url": "https://github.com/heznpc/skillbridge",
   "default_locale": "en",
   "permissions": [
     "storage",
-    "tabs",
     "alarms"
   ],
   "host_permissions": [
diff --git a/package.json b/package.json
index 2501faa..13dcea0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "skillbridge",
-  "version": "3.5.5",
+  "version": "3.5.6",
   "private": true,
   "scripts": {
     "test": "jest --verbose",
diff --git a/src/background/background.js b/src/background/background.js
index 5d8fec0..8b5e902 100644
--- a/src/background/background.js
+++ b/src/background/background.js
@@ -94,6 +94,19 @@ const _rateLimiter = {
     this.timestamps.push(now);
     return true;
   },
+  /**
+   * Wait until a slot is available, up to maxWaitMs. Returns true if acquired,
+   * false on timeout. Lets large batches pace naturally instead of dropping
+   * items into the original-English passthrough that callers can't detect.
+   */
+  async acquire(maxWaitMs = 60000) {
+    const start = Date.now();
+    while (!this.check()) {
+      if (Date.now() - start > maxWaitMs) return false;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    return true;
+  },
 };
 
 // ==================== EXPONENTIAL BACKOFF FETCH ====================
@@ -142,7 +155,7 @@ async function handleCacheCleanup() {
   try {
     const tabs = await chrome.tabs.query({ url: 'https://*.skilljar.com/*' });
     for (const tab of tabs) {
-      chrome.tabs.sendMessage(tab.id, { type: 'CACHE_CLEANUP' }).catch(() => {
+      chrome.tabs.sendMessage(tab.id, { action: 'cacheCleanup' }).catch(() => {
         // Tab may not have content script loaded — that is fine
       });
     }
@@ -295,15 +308,22 @@ chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
     const tl = gtLangCode(targetLang);
 
     Promise.all(
-      texts.map((text) => {
-        if (!_rateLimiter.check()) return text; // skip if rate limited
+      texts.map(async (text) => {
+        // Wait for a rate-limit slot. Falling back to the original English
+        // text would be silently dropped by content.js (translated === original
+        // is treated as no-op), so we pace instead.
+        const ok = await _rateLimiter.acquire();
+        if (!ok) {
+          console.warn('[SkillBridge] GT rate-limit acquire timed out');
+          return null;
+        }
         const url = `https://translate.googleapis.com/translate_a/single?client=gtx&sl=${sl}&tl=${tl}&dt=t&q=${encodeURIComponent(text)}`;
         return fetchWithRetry(url)
           .then((resp) => resp.json())
           .then((data) => parseGTResponse(data, text))
           .catch((err) => {
             console.warn('[SkillBridge] GT batch item failed:', err.message);
-            return text;
+            return null;
           });
       }),
     )
diff --git a/src/content/content.js b/src/content/content.js
index e41876a..6c96ffb 100644
--- a/src/content/content.js
+++ b/src/content/content.js
@@ -142,6 +142,21 @@
     }
   }
 
+  // Bridge unavailable — Puter.js script never confirmed BRIDGE_READY.
+  // Persistent banner (no auto-dismiss) so users know AI features are off
+  // until they refresh the page.
+  window.addEventListener('skillbridge:bridgeunavailable', () => {
+    if (document.getElementById('si18n-bridge-banner')) return;
+    const banner = document.createElement('div');
+    banner.id = 'si18n-bridge-banner';
+    banner.className = 'si18n-offline-banner si18n-storage-warn';
+    banner.setAttribute('role', 'alert');
+    banner.setAttribute('aria-live', 'assertive');
+    banner.textContent = t(BRIDGE_UNAVAILABLE_LABELS);
+    document.body.appendChild(banner);
+    requestAnimationFrame(() => banner.classList.add('visible'));
+  });
+
   // Storage quota warning — auto-dismiss after 8 seconds
   document.addEventListener('skillbridge:storagequota', () => {
     if (document.getElementById('si18n-storage-banner')) return;
@@ -468,6 +483,17 @@
         sendResponse({ ready: isReady });
         return false;
 
+      case 'cacheCleanup':
+        // Triggered by the 24h alarm in background.js. Page-load fallback
+        // also runs this on translator init, so the alarm path is for
+        // long-pinned tabs that never get a fresh load.
+        translator
+          ?._cleanupExpiredCache()
+          .then(() => translator?._checkStorageQuota())
+          .catch((err) => console.warn('[SkillBridge] alarm cleanup error:', err.message));
+        sendResponse({ success: true });
+        return false;
+
       case 'toggleCommentTranslation':
         commentTranslateEnabled = request.enabled;
         chrome.storage.local.set({ commentTranslate: request.enabled });
@@ -784,107 +810,111 @@
     let processedItems = 0;
     const geminiQueue = [];
 
-    while (gtTranslateQueue.length > 0) {
-      if (gtGeneration !== myGeneration) {
-        gtProcessing = false;
-        return;
-      }
-
-      const batch = gtTranslateQueue.splice(0, SKILLBRIDGE_THRESHOLDS.GT_BATCH_SIZE);
-      const targetLang = batch[0].targetLang;
-
-      const cacheResults = await Promise.all(batch.map((item) => translator.cachedLookup(item.text, targetLang)));
-
-      if (gtGeneration !== myGeneration) {
-        gtProcessing = false;
-        return;
-      }
-
-      const uncached = [];
-      for (let i = 0; i < batch.length; i++) {
-        if (cacheResults[i]) {
-          const item = batch[i];
-          if (item.el && item.el.parentNode) {
-            if (item.needsGemini) {
-              uncached.push(item);
-            } else {
-              safeReplaceText(item.el, cacheResults[i]);
-              trackTranslatedElement(item.text, item.el);
+    // Wrap the whole batch loop so progress UI and detached-entry pruning
+    // always run, even if the user switches language mid-batch (which trips
+    // the gtGeneration check below). Without this, the progress bar and
+    // verify spinners stay on screen until next nav.
+    try {
+      while (gtTranslateQueue.length > 0) {
+        if (gtGeneration !== myGeneration) return;
+
+        const batch = gtTranslateQueue.splice(0, SKILLBRIDGE_THRESHOLDS.GT_BATCH_SIZE);
+        const targetLang = batch[0].targetLang;
+
+        const cacheResults = await Promise.all(batch.map((item) => translator.cachedLookup(item.text, targetLang)));
+
+        if (gtGeneration !== myGeneration) return;
+
+        const uncached = [];
+        for (let i = 0; i < batch.length; i++) {
+          if (cacheResults[i]) {
+            const item = batch[i];
+            if (item.el && item.el.parentNode) {
+              if (item.needsGemini) {
+                uncached.push(item);
+              } else {
+                safeReplaceText(item.el, cacheResults[i]);
+                trackTranslatedElement(item.text, item.el);
+              }
             }
+          } else {
+            uncached.push(batch[i]);
           }
-        } else {
-          uncached.push(batch[i]);
-        }
-      }
-
-      const gtItems = uncached.filter((item) => !item.needsGemini);
-      const geminiItems = uncached.filter((item) => item.needsGemini);
-
-      for (const item of geminiItems) {
-        if (item.el && item.el.parentNode) {
-          if (!originalTexts.has(item.el)) originalTexts.set(item.el, item.el.innerHTML);
-          geminiQueue.push({ el: item.el, targetLang: item.targetLang });
         }
-      }
 
-      if (gtItems.length > 0) {
-        if (isOffline) {
-          const remaining = SKILLBRIDGE_THRESHOLDS.GT_QUEUE_MAX - _offlinePendingItems.length;
-          if (remaining > 0) _offlinePendingItems.push(...gtItems.slice(0, remaining));
-        } else {
-          // Deduplicate texts — group elements by text to avoid redundant API calls
-          const textToItems = new Map();
-          for (const item of gtItems) {
-            if (!textToItems.has(item.text)) textToItems.set(item.text, []);
-            textToItems.get(item.text).push(item);
-          }
-          const uniqueTexts = [...textToItems.keys()];
-          const translations = await translator.googleTranslateBatch(uniqueTexts, targetLang);
+        const gtItems = uncached.filter((item) => !item.needsGemini);
+        const geminiItems = uncached.filter((item) => item.needsGemini);
 
-          if (gtGeneration !== myGeneration) {
-            gtProcessing = false;
-            return;
+        for (const item of geminiItems) {
+          if (item.el && item.el.parentNode) {
+            if (!originalTexts.has(item.el)) originalTexts.set(item.el, item.el.innerHTML);
+            geminiQueue.push({ el: item.el, targetLang: item.targetLang });
           }
+        }
 
-          for (let i = 0; i < uniqueTexts.length; i++) {
-            let translated = translations[i];
-            if (!translated || translated === uniqueTexts[i]) continue;
-            translated = window._protectedTerms.restoreProtectedTerms(translated);
-            const items = textToItems.get(uniqueTexts[i]);
-            let verifyQueued = false;
-            for (const item of items) {
-              if (!item.el?.parentNode) continue;
-              safeReplaceText(item.el, translated);
-              trackTranslatedElement(item.text, item.el);
-              if (!verifyQueued) {
-                verifyQueued = !!translator.queueGeminiVerify(item.text, translated, targetLang);
+        if (gtItems.length > 0) {
+          if (isOffline) {
+            const remaining = SKILLBRIDGE_THRESHOLDS.GT_QUEUE_MAX - _offlinePendingItems.length;
+            if (remaining > 0) _offlinePendingItems.push(...gtItems.slice(0, remaining));
+          } else {
+            // Deduplicate texts — group elements by text to avoid redundant API calls
+            const textToItems = new Map();
+            for (const item of gtItems) {
+              if (!textToItems.has(item.text)) textToItems.set(item.text, []);
+              textToItems.get(item.text).push(item);
+            }
+            const uniqueTexts = [...textToItems.keys()];
+            const translations = await translator.googleTranslateBatch(uniqueTexts, targetLang);
+
+            if (gtGeneration !== myGeneration) return;
+
+            for (let i = 0; i < uniqueTexts.length; i++) {
+              let translated = translations[i];
+              if (!translated || translated === uniqueTexts[i]) continue;
+              translated = window._protectedTerms.restoreProtectedTerms(translated);
+              const items = textToItems.get(uniqueTexts[i]);
+              let verifyQueued = false;
+              for (const item of items) {
+                if (!item.el?.parentNode) continue;
+                safeReplaceText(item.el, translated);
+                trackTranslatedElement(item.text, item.el);
+                if (!verifyQueued) {
+                  verifyQueued = !!translator.queueGeminiVerify(item.text, translated, targetLang);
+                }
+                if (verifyQueued) addVerifySpinner(item.el);
               }
-              if (verifyQueued) addVerifySpinner(item.el);
             }
           }
         }
-      }
 
-      processedItems += batch.length;
-      updateTranslationProgress(80 + Math.round((processedItems / totalItems) * 15));
+        processedItems += batch.length;
+        updateTranslationProgress(80 + Math.round((processedItems / totalItems) * 15));
 
-      if (gtTranslateQueue.length > 0) {
-        await new Promise((r) => setTimeout(r, SKILLBRIDGE_DELAYS.GT_BATCH));
+        if (gtTranslateQueue.length > 0) {
+          await new Promise((r) => setTimeout(r, SKILLBRIDGE_DELAYS.GT_BATCH));
+        }
       }
-    }
+    } finally {
+      gtProcessing = false;
+      hideTranslationProgress();
+      pruneDetachedEntries();
 
-    gtProcessing = false;
-    hideTranslationProgress();
-    pruneDetachedEntries();
-    setTimeout(showTermPreview, 1500);
-
-    for (const { el, targetLang } of geminiQueue) {
-      if (el && el.parentNode) {
-        window._geminiBlock.queueGeminiBlockTranslation(el, targetLang, {
-          translator,
-          originalTexts,
-          isLikelyEnglish,
-        });
+      // Term-preview only on full completion; on cancellation, the new
+      // generation will trigger its own preview.
+      if (gtGeneration === myGeneration) {
+        setTimeout(showTermPreview, 1500);
+      }
+
+      // Flush any block-translation work queued during this generation.
+      // Stale items get filtered by parentNode + targetLang on the consumer.
+      for (const { el, targetLang } of geminiQueue) {
+        if (el && el.parentNode) {
+          window._geminiBlock.queueGeminiBlockTranslation(el, targetLang, {
+            translator,
+            originalTexts,
+            isLikelyEnglish,
+          });
+        }
       }
     }
   }
@@ -1255,17 +1285,26 @@
   window.addEventListener('popstate', onRouteChange);
   window.addEventListener('hashchange', onRouteChange);
 
-  // Catch pushState/replaceState (Skilljar SPA uses these)
-  const _origPushState = history.pushState;
-  const _origReplaceState = history.replaceState;
-  history.pushState = function (...args) {
-    _origPushState.apply(this, args);
-    onRouteChange();
-  };
-  history.replaceState = function (...args) {
-    _origReplaceState.apply(this, args);
-    onRouteChange();
-  };
+  // Catch pushState/replaceState (Skilljar SPA uses these).
+  // Guard against double-wrapping: extension reloads/updates re-run this
+  // module; without the marker we'd capture the previous wrapper as the
+  // "original" and stack handlers, doubling onRouteChange per nav.
+  let _origPushState = null;
+  let _origReplaceState = null;
+  if (!history.pushState.__sb_wrapped__) {
+    _origPushState = history.pushState;
+    _origReplaceState = history.replaceState;
+    history.pushState = function (...args) {
+      _origPushState.apply(this, args);
+      onRouteChange();
+    };
+    history.replaceState = function (...args) {
+      _origReplaceState.apply(this, args);
+      onRouteChange();
+    };
+    history.pushState.__sb_wrapped__ = true;
+    history.replaceState.__sb_wrapped__ = true;
+  }
 
   // ============================================================
   // BOOT
diff --git a/src/content/sidebar-chat.js b/src/content/sidebar-chat.js
index 33c4c7c..8b90dc8 100644
--- a/src/content/sidebar-chat.js
+++ b/src/content/sidebar-chat.js
@@ -515,28 +515,45 @@
     try {
       const db = await openHistoryDb();
       const chapter = document.querySelector('h1')?.textContent?.trim() || 'Unknown';
-      const tx = db.transaction(HISTORY_STORE, 'readwrite');
-      const req = tx.objectStore(HISTORY_STORE).add({
+      const entry = {
         question,
         answer,
         lang,
         chapter,
         timestamp: Date.now(),
         url: location.href,
-      });
-      req.onerror = (e) => {
-        if (e.target.error?.name === 'QuotaExceededError') {
-          console.warn('[SkillBridge] Chat history quota exceeded — pruning old entries');
-          pruneOldHistory(db);
-        }
       };
+      const ok = await _addHistoryEntry(db, entry);
+      if (!ok) {
+        // First add hit the IDB quota — prune oldest 20 then retry once
+        // (without retry the conversation just gets dropped silently).
+        await pruneOldHistory(db);
+        await _addHistoryEntry(db, entry);
+      }
     } catch (e) {
       console.warn('[SkillBridge] Failed to save conversation:', e);
     }
   }
 
-  async function pruneOldHistory(db) {
-    try {
+  function _addHistoryEntry(db, entry) {
+    return new Promise((resolve) => {
+      const tx = db.transaction(HISTORY_STORE, 'readwrite');
+      const req = tx.objectStore(HISTORY_STORE).add(entry);
+      req.onsuccess = () => resolve(true);
+      req.onerror = (e) => {
+        const isQuota = e.target.error?.name === 'QuotaExceededError';
+        if (isQuota) {
+          console.warn('[SkillBridge] Chat history quota exceeded — will prune and retry');
+        } else {
+          console.warn('[SkillBridge] Chat history add failed:', e.target.error?.name);
+        }
+        resolve(false);
+      };
+    });
+  }
+
+  function pruneOldHistory(db) {
+    return new Promise((resolve) => {
       const tx = db.transaction(HISTORY_STORE, 'readwrite');
       const store = tx.objectStore(HISTORY_STORE);
       const idx = store.index('timestamp');
@@ -544,16 +561,18 @@
       let deleted = 0;
       req.onsuccess = (e) => {
         const cursor = e.target.result;
-        // Delete oldest 20 entries to free space
         if (cursor && deleted < 20) {
           cursor.delete();
           deleted++;
           cursor.continue();
         }
       };
-    } catch (_ignored) {
-      /* best-effort pruning */
-    }
+      // Resolve when the whole transaction commits, so the caller's retry
+      // sees the freed space.
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => resolve();
+      tx.onabort = () => resolve();
+    });
   }
 
   async function getConversations(limit = SKILLBRIDGE_LIMITS.HISTORY) {
diff --git a/src/data/de.json b/src/data/de.json
index 43f81c8..6f2f0a0 100644
--- a/src/data/de.json
+++ b/src/data/de.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "de",
     "langName": "Deutsch",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/es.json b/src/data/es.json
index b2d4dcb..ca75b1d 100644
--- a/src/data/es.json
+++ b/src/data/es.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "es",
     "langName": "Español",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/fr.json b/src/data/fr.json
index b6a73c5..3a41bdc 100644
--- a/src/data/fr.json
+++ b/src/data/fr.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "fr",
     "langName": "Français",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/ja.json b/src/data/ja.json
index f75eec3..8220791 100644
--- a/src/data/ja.json
+++ b/src/data/ja.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "ja",
     "langName": "日本語",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/ko.json b/src/data/ko.json
index b25438c..ba60ec6 100644
--- a/src/data/ko.json
+++ b/src/data/ko.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "ko",
     "langName": "한국어",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/pt-BR.json b/src/data/pt-BR.json
index d511cd5..361774a 100644
--- a/src/data/pt-BR.json
+++ b/src/data/pt-BR.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "pt-BR",
     "langName": "Português (BR)",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/ru.json b/src/data/ru.json
index 6e99ba7..5d24f5e 100644
--- a/src/data/ru.json
+++ b/src/data/ru.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "ru",
     "langName": "Русский",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/vi.json b/src/data/vi.json
index 839aef3..92a1099 100644
--- a/src/data/vi.json
+++ b/src/data/vi.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "vi",
     "langName": "Tiếng Việt",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/zh-CN.json b/src/data/zh-CN.json
index ef3b394..2590b1d 100644
--- a/src/data/zh-CN.json
+++ b/src/data/zh-CN.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "zh-CN",
     "langName": "简体中文",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/data/zh-TW.json b/src/data/zh-TW.json
index 0035380..7ac874c 100644
--- a/src/data/zh-TW.json
+++ b/src/data/zh-TW.json
@@ -2,7 +2,7 @@
   "_meta": {
     "lang": "zh-TW",
     "langName": "中文(繁體)",
-    "version": "3.5.5",
+    "version": "3.5.6",
     "lastUpdated": "2026-04-02"
   },
   "ui": {
diff --git a/src/lib/constants.js b/src/lib/constants.js
index f526f18..cc74dfe 100644
--- a/src/lib/constants.js
+++ b/src/lib/constants.js
@@ -570,6 +570,20 @@ const OFFLINE_LABELS = {
   vi: 'Ngoại tuyến — chỉ sử dụng bản dịch đã lưu',
 };
 
+const BRIDGE_UNAVAILABLE_LABELS = {
+  en: 'AI features unavailable — refresh the page to retry',
+  ko: 'AI 기능을 사용할 수 없습니다 — 페이지를 새로고침하여 다시 시도해주세요',
+  ja: 'AI機能が利用できません — ページを再読み込みして再試行してください',
+  'zh-CN': 'AI 功能不可用 — 刷新页面以重试',
+  'zh-TW': 'AI 功能無法使用 — 重新整理頁面以重試',
+  es: 'Funciones de IA no disponibles — recarga la página para reintentar',
+  fr: 'Fonctions IA indisponibles — rechargez la page pour réessayer',
+  de: 'KI-Funktionen nicht verfügbar — Seite neu laden, um es erneut zu versuchen',
+  'pt-BR': 'Recursos de IA indisponíveis — recarregue a página para tentar novamente',
+  ru: 'ИИ-функции недоступны — обновите страницу, чтобы повторить попытку',
+  vi: 'Tính năng AI không khả dụng — làm mới trang để thử lại',
+};
+
 const STORAGE_WARNING_LABELS = {
   en: 'Storage almost full — old translations will be cleared automatically',
   ko: '저장 공간 부족 — 오래된 번역이 자동으로 삭제됩니다',
diff --git a/src/lib/translator.js b/src/lib/translator.js
index cb92a15..d6f7d2b 100644
--- a/src/lib/translator.js
+++ b/src/lib/translator.js
@@ -681,7 +681,12 @@ User: ${userMessage}`;
   _injectPageBridge() {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
-        console.warn('[SkillBridge] Bridge ready timeout - resolving anyway');
+        // Bridge never confirmed ready — keep isReady=false so _sendRequest
+        // fails fast, and notify UI so the user sees an actionable banner
+        // instead of a silent dead tutor.
+        console.warn('[SkillBridge] Bridge ready timeout — AI features disabled');
+        this.bridgeFailed = true;
+        window.dispatchEvent(new CustomEvent('skillbridge:bridgeunavailable'));
         resolve();
       }, SKILLBRIDGE_THRESHOLDS.BRIDGE_READY_TIMEOUT);