hackertube-zh 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crisxuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,16 @@
-# HackerTube 中文助手
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.png">
+    <img src="docs/logo-light.png" width="470" alt="HackerTube 中文插件">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/hackertube-zh"><img src="https://img.shields.io/npm/v/hackertube-zh?color=ff6600" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+</p>
+
+<p align="center"><code>npx hackertube-zh</code></p>
 
 给 [HackerTube](https://hackertube.org)（Karpathy 做的“HN 推荐过的 YouTube 视频”站）用的 Chrome 扩展，把整个观看体验实时变成中文：
 
@@ -8,7 +20,8 @@
 - **中文搜索**：在搜索框输入中文，会先翻译成英文再交给 HackerTube 的语义搜索（它只理解英文）。
 - **用 YouTube 登录状态播放**（可选）：解决嵌入播放器一直提示 “Sign in to confirm you're not a bot” 的问题，见下方“常见问题”。
 - **三种翻译引擎**：Google 翻译（免费，默认）、Claude、任意 OpenAI 兼容接口（DeepSeek、通义千问、Ollama 等）。LLM 出错时自动临时回退到 Google。
-- 所有译文缓存在本地，同一个视频、同一页再次打开不再请求翻译。
+- 所有译文缓存在本地，同一个视频、同一页再次打开不再请求翻译。缓存有上限，很久没用到的译文会自动清掉。
+- 翻译请求失败（断网、被限流）时会自动重试，网络恢复后页面和字幕会自己补上中文，不用刷新。
 
 ## 安装
 
@@ -109,7 +122,7 @@ hackertube.org 页面                         YouTube 嵌入播放器（iframe,
 ```bash
 npm test          # 单元测试：字幕解析与分句、引擎请求/响应、界面词典
 npm run check     # 静态检查：manifest 引用的文件都存在、所有 JS 语法正确
-npm run icons     # 重新生成图标（Python 标准库）
+npm run icons     # 从 icons/*.svg 渲染插件图标 PNG 和 README 横版 logo（用本机 Chrome 的无头模式）
 npm run zip       # 打包到 dist/hackertube-zh.zip（上架 Chrome 应用商店用）
 ```
 
@@ -119,7 +132,7 @@ npm run zip       # 打包到 dist/hackertube-zh.zip（上架 Chrome 应用商
 npm publish                        # 之后任何人都能 npx hackertube-zh
 ```
 
-不想发布到 npm 的话，推到 GitHub 后也可以用 `npx github:<你的用户名>/<仓库名>`。发布前在本地试：`npm pack` 后运行 `npx --package=./hackertube-zh-0.1.0.tgz hackertube-zh --dir /tmp/htz-test --no-open`。
+不想发布到 npm 的话，推到 GitHub 后也可以用 `npx github:crisxuan/hackertube-zh`。发布前在本地试：`npm pack` 后运行 `npx --package=./hackertube-zh-<版本号>.tgz hackertube-zh --dir /tmp/htz-test --no-open`。
 
 不安装扩展也能调试：`node dev/server.js 8787 <放测试视频的目录>` 启动开发服务器（HackerTube 的 CSP 禁止注入脚本，所以这里用本地镜像）：
 
@@ -132,6 +145,7 @@ manifest.json          扩展清单（MV3）
 background.js          Service Worker：翻译调度、并发限制、缓存、引擎回退
 lib/                   公共模块（浏览器和 node 测试共用）
   engines.js           Google / Claude / OpenAI 兼容引擎
+  cache.js             译文缓存（内存 + storage.local，分两代淘汰旧条目）
   embedlogin.js        “用 YouTube 登录状态播放”的重定向规则
   subtitles.js         json3 / srv3 / WebVTT 解析与分句
   uidict.js            HackerTube 界面词典
@@ -142,4 +156,15 @@ popup/ options/ ui/    弹窗、选项页、公共样式
 bin/install.js         npx 安装器
 dev/                   本地调试服务器和模拟页面
 tests/                 node:test 单元测试
+scripts/               静态检查、图标渲染
+icons/                 插件图标：icon.svg（48/128px）、icon-small.svg（16/32px 简化版）及渲染出的 PNG
+docs/                  README 横版 logo（浅色 / 深色两版，由 npm run icons 生成）
 ```
+
+## 参与贡献
+
+欢迎提 Issue 和 Pull Request。提交前请跑一下 `npm test` 和 `npm run check`；改动行为时请补上对应的测试。HackerTube 或 YouTube 改版导致失效时，欢迎附上出问题的页面地址。
+
+## 许可证
+
+[MIT](LICENSE)。本项目与 HackerTube、Hacker News、YouTube 均无关联。

package/background.js

@@ -1,11 +1,12 @@
 // Service worker: the only place that talks to translation engines. Content scripts send batches of text;
-// results are cached (memory + chrome.storage.local) per engine, so revisiting a page or video is free and instant.
+// results are cached (lib/cache.js) per engine, so revisiting a page or video is free and instant.
 import "./lib/textutil.js";
 import "./lib/engines.js";
 import "./lib/runtime.js";
 import "./lib/embedlogin.js";
+import "./lib/cache.js";
 
-const { text: T, engines: E, runtime: R, embedlogin: EL } = globalThis.HTZ;
+const { text: T, engines: E, runtime: R, embedlogin: EL, cache: C } = globalThis.HTZ;
 
 // keep the embed redirect rule in step with the setting: on every service worker start, and on every change
 const syncEmbedLogin = (s) => EL.sync(!!s.embedLogin).catch((e) => console.warn("[HackerTube 中文] embed rule:", e));
@@ -15,7 +16,8 @@ R.onSettings(syncEmbedLogin);
 const ENGINE_NAMES = { google: "Google 翻译", claude: "Claude", openai: "OpenAI 兼容接口" };
 const LIMITS = {
   google: { maxItems: 50, maxChars: 4500, concurrency: 4 },
-  llm: { maxItems: 40, maxChars: 6000, concurrency: 3 },
+  // small batches: a model has to finish the whole reply inside the engines' 25 s limit (see lib/engines.js)
+  llm: { maxItems: 12, maxChars: 1500, concurrency: 3 },
 };
 
 // ---------- small helpers ----------
@@ -33,13 +35,7 @@ function limiter(n) {
 const limits = { google: limiter(LIMITS.google.concurrency), llm: limiter(LIMITS.llm.concurrency) };
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-const MEM_MAX = 8000;
-const mem = new Map();
-function memSet(k, v) {
-  mem.delete(k);
-  mem.set(k, v);
-  if (mem.size > MEM_MAX) mem.delete(mem.keys().next().value);
-}
+const cache = C.create(chrome.storage.local);
 
 // The cache key includes everything that changes the output: engine, model, target language and, for LLMs,
 // the kind of text (subtitle prompts differ from page prompts).
@@ -96,16 +92,8 @@ async function translate({ texts, kind = "page", to = "zh-CN", context }) {
   if (texts.some((t) => typeof t !== "string")) throw new Error("texts must be strings");
   const [settings, secrets] = await Promise.all([R.loadSettings(), R.loadSecrets()]);
   const eid = engineId(settings, kind, to);
-  const keys = texts.map((t) => "c:" + T.hash(eid + "\u0001" + t));
-  const out = keys.map((k) => mem.get(k));
-
-  const missingKeys = keys.filter((k, i) => out[i] == null);
-  if (missingKeys.length) {
-    const stored = await chrome.storage.local.get(missingKeys);
-    keys.forEach((k, i) => {
-      if (out[i] == null && stored[k] != null) { out[i] = stored[k]; memSet(k, stored[k]); }
-    });
-  }
+  const ids = texts.map((t) => T.hash(eid + "\u0001" + t));
+  const out = await cache.get(ids);
 
   const todo = [];
   out.forEach((v, i) => { if (v == null) todo.push(i); });
@@ -119,18 +107,13 @@ async function translate({ texts, kind = "page", to = "zh-CN", context }) {
     const toStore = {};
     for (const i of todo) {
       out[i] = byText.get(texts[i]);
-      if (res.cache) { memSet(keys[i], out[i]); toStore[keys[i]] = out[i]; }
+      if (res.cache) toStore[ids[i]] = out[i];
     }
-    if (Object.keys(toStore).length) chrome.storage.local.set(toStore);
+    cache.put(toStore);
   }
   return { translations: out, warning };
 }
 
-async function cacheKeys() {
-  const all = await chrome.storage.local.get(null);
-  return Object.keys(all).filter((k) => k.startsWith("c:"));
-}
-
 async function testEngine() {
   const [settings, secrets] = await Promise.all([R.loadSettings(), R.loadSecrets()]);
   const sample = ["Overwatch Gameplay Architecture and Netcode", "The quick brown fox jumps over the lazy dog."];
@@ -150,8 +133,8 @@ chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
   switch (msg && msg.type) {
     case "translate": return reply(translate(msg));
     case "testEngine": return reply(testEngine());
-    case "cacheStats": return reply(cacheKeys().then((k) => ({ entries: k.length })));
-    case "clearCache": return reply(cacheKeys().then(async (k) => { mem.clear(); await chrome.storage.local.remove(k); return { removed: k.length }; }));
+    case "cacheStats": return reply(cache.count().then((entries) => ({ entries })));
+    case "clearCache": return reply(cache.clear().then((removed) => ({ removed })));
     default: return false;
   }
 });

package/content/player-main.js

@@ -80,11 +80,14 @@
       try { list = p.getOption("captions", "tracklist", { includeAsr: true }) || []; } catch {}
       if (!list.length) await sleep(300);
     }
+    // subtitles were switched off while we waited: leave the player alone, and try again if they come back on
+    if (!wanted) { triedFor = null; return; }
     const tracks = responseTracks(p);
     if (!list.length && !tracks.length) return post("nocaptions", { vid });
-    if (list.length) { try { p.setOption("captions", "track", choose(list)); } catch {} }
+    if (list.length) { try { p.setOption("captions", "track", choose(list)); turnedOnFor = vid; } catch {} }
     await sleep(3500);
     if (gotFor === vid) return;
+    if (!wanted) { triedFor = null; return; }
     // second route: the track's own URL (works for videos whose captions aren't token-gated)
     const t = tracks.length && choose(tracks);
     if (t && t.baseUrl) {
@@ -98,7 +101,16 @@
     if (gotFor !== vid) post("captionsfailed", { vid });
   }
 
-  let wanted = false, triedFor = null;
+  // Our subtitles going off also turns off the YouTube captions we switched on to get the caption file, or they
+  // would show in their place. Captions the viewer turned on themselves are theirs and stay.
+  function restoreCaptions() {
+    const p = player();
+    if (!p || turnedOnFor === null || turnedOnFor !== lastVid) return;
+    turnedOnFor = null;
+    try { p.setOption("captions", "track", {}); } catch {}
+  }
+
+  let wanted = false, triedFor = null, turnedOnFor = null;
   setInterval(() => {
     const p = player();
     if (!p || !p.getVideoData) return;
@@ -115,7 +127,10 @@
 
   window.addEventListener("message", (e) => {
     if (e.source !== window || !e.data || e.data.source !== "htz-iso") return;
-    if (e.data.type === "config") wanted = !!e.data.enabled;
+    if (e.data.type !== "config") return;
+    const was = wanted;
+    wanted = !!e.data.enabled;
+    if (was && !wanted) restoreCaptions();
   });
   post("hello");
 })();

package/content/player.css

@@ -11,10 +11,20 @@
 /* lift above the control bar while it is visible */
 #movie_player:not(.ytp-autohide) .htz-sub { bottom: calc(var(--htz-bottom, 8) * 1% + 52px); }
 
+/* Default: outlined text with no box, so the picture isn't covered. The layered shadows make a soft dark outline
+   that keeps white text readable on bright frames and slides. */
 .htz-line {
-  display: inline-block; max-width: 100%; padding: .08em .45em; border-radius: 4px;
-  background: rgba(8, 8, 8, .72); color: #fff; line-height: 1.38; white-space: pre-wrap;
+  display: inline-block; max-width: 100%; padding: 0 .2em; color: #fff; line-height: 1.38; white-space: pre-wrap;
   font-family: "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", "Source Han Sans SC", Roboto, Arial, sans-serif;
+  text-shadow:
+    0 0 1px rgba(0, 0, 0, .95), 0 0 2px rgba(0, 0, 0, .9),
+    1px 1px 1px rgba(0, 0, 0, .85), -1px -1px 1px rgba(0, 0, 0, .85),
+    1px -1px 1px rgba(0, 0, 0, .85), -1px 1px 1px rgba(0, 0, 0, .85),
+    0 2px 6px rgba(0, 0, 0, .55);
+}
+/* Optional: a compact translucent box, for videos with lots of white slides */
+.htz-style-box .htz-line {
+  padding: .06em .4em; border-radius: 6px; background: rgba(0, 0, 0, .55); text-shadow: 0 1px 2px rgba(0, 0, 0, .6);
 }
 .htz-line:empty { display: none; }
 .htz-zh { font-size: max(15px, calc(var(--htz-h, 360px) * .05 * var(--htz-scale, 1))); font-weight: 500; }

package/content/player.js

@@ -16,8 +16,9 @@
 
   let settings = { ...R.DEFAULTS };
   let vid = null, title = "";
-  let sentences = [], zh = [], st = []; // st: 0 = not sent, 1 = in flight, 2 = done, 3 = gave up
+  let sentences = [], zh = [], st = []; // st: 0 = not sent, 1 = in flight, 2 = done
   let gen = 0, inflight = 0, failures = 0, doneCount = 0;
+  let retryAt = 0; // after a failed request nothing is sent before this time
 
   const post = (type, data = {}) => window.postMessage({ source: "htz-iso", type, ...data }, "*");
   const sendConfig = () => post("config", { enabled: settings.subMode !== "off" });
@@ -52,6 +53,7 @@
     if (!p) return;
     p.style.setProperty("--htz-scale", String(settings.subScale || 1));
     p.style.setProperty("--htz-bottom", String(settings.subBottom ?? 8));
+    p.classList.toggle("htz-style-box", settings.subStyle === "box");
     // our lines include the English, so YouTube's own captions would only duplicate them
     p.classList.toggle("htz-hide-native", settings.subMode !== "off" && sentences.length > 0);
   }
@@ -101,7 +103,7 @@
   }
 
   function pump() {
-    if (settings.subMode === "off" || !sentences.length) return;
+    if (settings.subMode === "off" || !sentences.length || Date.now() < retryAt) return;
     const v = video();
     const now = v ? v.currentTime * 1000 : 0;
     while (inflight < MAX_INFLIGHT) {
@@ -127,10 +129,12 @@
         .catch((err) => {
           if (myGen !== gen) return;
           failures++;
-          const giveUp = failures >= 3;
-          idx.forEach((k) => { st[k] = giveUp ? 3 : 0; });
+          idx.forEach((k) => { st[k] = 0; });
           say(`字幕翻译失败：${err.message}`, { error: true, ms: 6000 });
-          if (!giveUp) setTimeout(pump, 2500 * failures);
+          // never give up for good, the network may come back mid-video: wait longer each time, up to 30 s
+          const wait = Math.min(2500 * failures, 30000);
+          retryAt = Date.now() + wait;
+          setTimeout(pump, wait + 50);
         })
         .finally(() => {
           if (myGen !== gen) return;
@@ -138,7 +142,7 @@
           shown = "";
           render();
           progress();
-          if (failures < 3) pump();
+          pump();
         });
     }
     progress();
@@ -148,7 +152,7 @@
     gen++;
     vid = newVid;
     sentences = []; zh = []; st = [];
-    inflight = 0; failures = 0; doneCount = 0; shown = "";
+    inflight = 0; failures = 0; doneCount = 0; shown = ""; retryAt = 0;
     if (overlay) { zhLine.textContent = ""; enLine.textContent = ""; overlay.classList.remove("on"); }
     applyStyle();
   }
@@ -187,7 +191,8 @@
   // media events don't bubble, but a capturing listener on the document still sees them
   let lastPump = 0;
   document.addEventListener("play", kick, true);
-  document.addEventListener("seeked", () => { shown = ""; render(); pump(); }, true);
+  // a seek or a changed setting is the viewer asking again: retry now instead of waiting out the pause
+  document.addEventListener("seeked", () => { shown = ""; retryAt = 0; render(); pump(); }, true);
   document.addEventListener("pause", render, true);
   document.addEventListener("timeupdate", () => {
     render();
@@ -209,6 +214,7 @@
       st = new Array(keep.length).fill(0);
     }
     shown = "";
+    retryAt = 0;
     render();
     pump();
   });

package/content/site.js

@@ -40,6 +40,7 @@
   const memo = new Map();       // source text -> translation, for this page's lifetime
   const waiting = new Map();    // source text -> elements waiting for it
   const inflight = new Set();   // source texts currently being translated
+  let failures = 0;             // requests failed in a row: sets the pause before the next retry
   const replaced = new Map();   // Text node -> original text, so "off" can restore the page exactly
   let handled = new WeakSet();
 
@@ -158,11 +159,18 @@
     try {
       const res = await R.translate(texts, { kind: "page" });
       if (mode !== myMode) return;
+      failures = 0;
       texts.forEach((t, i) => memo.set(t, res.translations[i]));
       for (const t of texts) for (const el of waiting.get(t) || []) if (el.isConnected) render(el);
       if (res.warning) status(res.warning, { error: true, ms: 6000 });
     } catch (e) {
       status(`翻译失败：${e.message}`, { error: true, ms: 6000 });
+      // hand the elements back to the viewport observer after a pause (longer each time, up to 30 s): whatever
+      // is still near the screen then is asked for again, so the page recovers once the network or engine does
+      const els = texts.flatMap((t) => waiting.get(t) || []);
+      setTimeout(() => {
+        if (mode === myMode) for (const el of els) if (el.isConnected) io.observe(el);
+      }, Math.min(3000 * ++failures, 30000));
     } finally {
       texts.forEach((t) => { inflight.delete(t); waiting.delete(t); });
       if (!document.querySelector("#htz-status.err.on")) showProgress();

package/icons/icon-small.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
+  <!-- 16 / 32 px toolbar art: the same play button and puzzle piece as icon.svg, filling more of the square, with a
+       wider gap. The piece gets a second knob on the right: with only the top knob it reads as a padlock when tiny. -->
+  <defs>
+    <linearGradient id="play" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#FF6A33"/>
+      <stop offset="1" stop-color="#FC4C1B"/>
+    </linearGradient>
+    <linearGradient id="piece" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#FF961F"/>
+      <stop offset="1" stop-color="#FF7E14"/>
+    </linearGradient>
+    <mask id="gap">
+      <rect width="128" height="128" fill="#fff"/>
+      <g fill="#000" stroke="#000" stroke-width="14" stroke-linejoin="round">
+        <rect x="66" y="74" width="46" height="46" rx="7"/>
+        <circle cx="89" cy="63" r="11"/>
+        <circle cx="116" cy="97" r="9.5"/>
+      </g>
+    </mask>
+  </defs>
+
+  <g mask="url(#gap)">
+    <rect x="2" y="10" width="116" height="94" rx="28" fill="url(#play)"/>
+    <path d="M34 36 L34 74 L64 55 Z" fill="#fff" stroke="#fff" stroke-width="11" stroke-linejoin="round"/>
+  </g>
+
+  <g fill="url(#piece)">
+    <rect x="66" y="74" width="46" height="46" rx="7"/>
+    <circle cx="89" cy="63" r="11"/>
+    <rect x="83" y="63" width="12" height="12"/>
+    <circle cx="116" cy="97" r="9.5"/>
+    <rect x="110" y="91" width="7" height="12"/>
+  </g>
+</svg>

package/icons/icon.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
+  <!-- HackerTube 中文插件: a video play button with a browser-extension puzzle piece, kept apart by a transparent
+       gap. Used for the 48 and 128 px icons and the README wordmark; icon-small.svg is the 16 / 32 px art. -->
+  <defs>
+    <linearGradient id="play" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#FF6A33"/>
+      <stop offset="1" stop-color="#FC4C1B"/>
+    </linearGradient>
+    <linearGradient id="piece" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#FF961F"/>
+      <stop offset="1" stop-color="#FF7E14"/>
+    </linearGradient>
+    <!-- the puzzle piece's footprint, grown by the gap, is cut out of the play button -->
+    <mask id="gap">
+      <rect width="128" height="128" fill="#fff"/>
+      <g fill="#000" stroke="#000" stroke-width="9" stroke-linejoin="round">
+        <rect x="75.5" y="71" width="44.5" height="40" rx="5"/>
+        <circle cx="99" cy="63.5" r="9.6"/>
+      </g>
+    </mask>
+    <!-- the socket on the piece's left side -->
+    <mask id="socket">
+      <rect width="128" height="128" fill="#fff"/>
+      <circle cx="76.5" cy="91" r="6.4" fill="#000"/>
+    </mask>
+  </defs>
+
+  <g mask="url(#gap)">
+    <rect x="8" y="17" width="106" height="83" rx="26" fill="url(#play)"/>
+    <path d="M49.5 43 L49.5 72 L76.5 57.5 Z" fill="#fff" stroke="#fff" stroke-width="9" stroke-linejoin="round"/>
+  </g>
+
+  <g fill="url(#piece)" mask="url(#socket)">
+    <rect x="75.5" y="71" width="44.5" height="40" rx="5"/>
+    <circle cx="99" cy="63.5" r="9.6"/>
+    <rect x="94" y="64" width="10" height="9"/>
+  </g>
+</svg>

package/lib/cache.js

@@ -0,0 +1,98 @@
+// Translation cache: a small in-memory copy in front of chrome.storage.local.
+// Storage is capped by generations. New entries go to the current generation; when it has taken genMax entries a
+// new one starts and everything older than the previous generation is deleted. An entry found in the previous
+// generation is copied to the current one, so translations that are still in use survive the rotation.
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === "object" && module.exports) module.exports = api;
+  else (root.HTZ = root.HTZ || {}).cache = api;
+})(globalThis, function () {
+  const META = "cacheMeta";
+  const ENTRY = /^c\d*:/;
+  // entries saved before generations existed are keyed "c:<id>": they are read as generation 0
+  const prefix = (gen) => (gen > 0 ? `c${gen}:` : "c:");
+  // an entry copied forward exists in two generations but is one translation
+  const distinct = (keys) => new Set(keys.map((k) => k.slice(k.indexOf(":") + 1))).size;
+
+  function create(storage, { genMax = 20000, memMax = 8000 } = {}) {
+    const mem = new Map();
+    let meta; // { gen, count }: the current generation and how many entries were written to it
+
+    function remember(id, value) {
+      mem.delete(id);
+      mem.set(id, value);
+      if (mem.size > memMax) mem.delete(mem.keys().next().value);
+    }
+
+    let loading;
+    const load = () => loading
+      || (loading = storage.get(META).then((got) => { meta = got[META] || { gen: 1, count: 0 }; }));
+
+    async function entryKeys() {
+      // getKeys (Chrome 130+) lists the keys without reading every cached translation into memory
+      const keys = storage.getKeys ? await storage.getKeys() : Object.keys(await storage.get(null));
+      return keys.filter((k) => ENTRY.test(k));
+    }
+
+    async function rotate() {
+      const gen = meta.gen + 1;
+      meta = { gen, count: 0 };
+      await storage.set({ [META]: meta });
+      const keep = [prefix(gen), prefix(gen - 1)];
+      const stale = (await entryKeys()).filter((k) => !keep.some((p) => k.startsWith(p)));
+      if (stale.length) await storage.remove(stale);
+    }
+
+    // entries: { id: translation }
+    async function put(entries) {
+      const ids = Object.keys(entries);
+      if (!ids.length) return;
+      await load();
+      const items = {};
+      for (const id of ids) { remember(id, entries[id]); items[prefix(meta.gen) + id] = entries[id]; }
+      meta = { gen: meta.gen, count: meta.count + ids.length };
+      items[META] = meta;
+      await storage.set(items);
+      if (meta.count >= genMax) await rotate();
+    }
+
+    // the cached translation for each id, in order; undefined where there is none
+    async function get(ids) {
+      const out = ids.map((id) => mem.get(id));
+      const missing = ids.filter((id, i) => out[i] === undefined);
+      if (!missing.length) return out;
+      await load();
+      const cur = prefix(meta.gen), old = prefix(meta.gen - 1);
+      const stored = await storage.get(missing.flatMap((id) => [cur + id, old + id]));
+      const carry = {};
+      ids.forEach((id, i) => {
+        if (out[i] !== undefined) return;
+        if (stored[cur + id] != null) out[i] = stored[cur + id];
+        else if (stored[old + id] != null) out[i] = carry[id] = stored[old + id];
+        else return;
+        remember(id, out[i]);
+      });
+      await put(carry);
+      return out;
+    }
+
+    async function count() {
+      return distinct(await entryKeys());
+    }
+
+    // removes every cached translation and nothing else; resolves to how many there were
+    async function clear() {
+      await load();
+      mem.clear();
+      const keys = await entryKeys();
+      if (keys.length) await storage.remove(keys);
+      meta = { gen: meta.gen, count: 0 };
+      await storage.set({ [META]: meta });
+      return distinct(keys);
+    }
+
+    return { get, put, count, clear };
+  }
+
+  return { create };
+});

package/lib/engines.js

@@ -125,13 +125,25 @@
     return checkCount(extractJson(text).translations, n, "Claude");
   }
 
+  // Chrome stops an extension's service worker when a fetch() has had no response for 30 s, and the request is
+  // then lost without any error. Model calls give up just before that, so the caller can fall back and say why.
+  const LLM_TIMEOUT_MS = 25000;
+  async function postJson(fetchImpl, req) {
+    try {
+      return await fetchImpl(req.url, {
+        method: "POST", headers: req.headers, body: JSON.stringify(req.body), signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
+      });
+    } catch (e) {
+      if (e.name === "TimeoutError") throw fail(`no reply within ${LLM_TIMEOUT_MS / 1000} s`);
+      throw e;
+    }
+  }
+
   async function claude(texts, opts) {
     if (!opts.apiKey) throw fail("Claude API key is not set");
     const fetchImpl = opts.fetchImpl || fetch;
     const req = buildClaudeRequest(texts, opts);
-    const r = await fetchImpl(req.url, {
-      method: "POST", headers: req.headers, body: JSON.stringify(req.body), signal: AbortSignal.timeout(120000),
-    });
+    const r = await postJson(fetchImpl, req);
     const json = await r.json().catch(() => ({}));
     if (!r.ok) throw fail(`Claude HTTP ${r.status}: ${json.error?.message || ""}`.trim(), r.status);
     return parseClaude(json, texts.length);
@@ -163,10 +175,7 @@
     if (!opts.baseUrl || !opts.model) throw fail("OpenAI-compatible base URL or model is not set");
     const fetchImpl = opts.fetchImpl || fetch;
     const send = async (jsonMode) => {
-      const req = buildOpenAIRequest(texts, opts, jsonMode);
-      const r = await fetchImpl(req.url, {
-        method: "POST", headers: req.headers, body: JSON.stringify(req.body), signal: AbortSignal.timeout(120000),
-      });
+      const r = await postJson(fetchImpl, buildOpenAIRequest(texts, opts, jsonMode));
       return { r, json: await r.json().catch(() => ({})) };
     };
     let { r, json } = await send(true);

package/lib/runtime.js

@@ -12,6 +12,7 @@
     embedLogin: false,            // play HackerTube's embeds via youtube.com/embed so the user's YouTube login applies
     subScale: 1,                  // subtitle size multiplier
     subBottom: 8,                 // subtitle distance from the bottom of the video, in %
+    subStyle: "outline",          // outline (text with a dark outline, no box) | box (translucent box)
     claudeModel: "claude-opus-5-5",
     claudeEffort: "low",          // translation is a simple task: low effort keeps latency and thinking spend down
     openaiBaseUrl: "https://api.openai.com/v1",

package/manifest.json

@@ -2,7 +2,8 @@
   "manifest_version": 3,
   "name": "HackerTube 中文助手",
   "short_name": "HackerTube 中文",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "homepage_url": "https://github.com/crisxuan/hackertube-zh",
   "description": "为 HackerTube 提供实时中文：双语界面，视频标题、简介和 HN 评论翻译，以及嵌入视频的实时中英双语字幕。",
   "minimum_chrome_version": "116",
   "icons": {

package/options/options.html

@@ -32,6 +32,12 @@
     </div>
     <label class="field"><span>字幕大小</span>
       <input type="range" id="subScale" min="0.7" max="1.8" step="0.1"><output id="subScaleOut"></output></label>
+    <div class="field">
+      <span>字幕样式</span>
+      <div class="seg" data-key="subStyle">
+        <button value="outline">描边（不挡画面）</button><button value="box">半透明底框（白底幻灯片更清楚）</button>
+      </div>
+    </div>
     <label class="field"><span>字幕离底部</span>
       <input type="range" id="subBottom" min="2" max="30" step="1"><output id="subBottomOut"></output></label>
     <label class="field check"><input type="checkbox" id="searchTranslate">

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "hackertube-zh",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "HackerTube 中文助手 Chrome 扩展：双语界面、标题评论翻译、实时中文字幕。npx hackertube-zh 一行安装。",
   "keywords": ["hackertube", "chrome-extension", "translation", "subtitles", "chinese"],
+  "author": "crisxuan",
+  "license": "MIT",
+  "homepage": "https://github.com/crisxuan/hackertube-zh#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crisxuan/hackertube-zh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/crisxuan/hackertube-zh/issues"
+  },
   "bin": {
     "hackertube-zh": "bin/install.js"
   },
@@ -26,7 +36,7 @@
   "scripts": {
     "test": "node --test \"tests/*.test.js\"",
     "check": "node scripts/check.js",
-    "icons": "python3 scripts/make_icons.py",
+    "icons": "node scripts/render-icons.js",
     "zip": "node scripts/check.js && rm -f dist/hackertube-zh.zip && mkdir -p dist && zip -r dist/hackertube-zh.zip manifest.json background.js lib content popup options ui icons"
   }
 }

package/popup/popup.css

@@ -4,6 +4,8 @@ section { margin-bottom: 14px; }
 .row { display: flex; align-items: center; gap: 8px; margin-top: 10px; color: var(--muted); font-size: 13px; }
 .row input { flex: 1; accent-color: var(--accent); }
 .row output { width: 34px; text-align: right; color: var(--text); }
+.row .seg { flex: 1; font-size: 13px; }
+.row .seg button { padding: 4px; }
 .toggle { display: flex; align-items: center; gap: 8px; margin-top: 12px; cursor: pointer; }
 .toggle input { accent-color: var(--accent); margin: 0; }
 footer { display: flex; justify-content: space-between; border-top: 1px solid var(--line); padding-top: 10px; font-size: 13px; }

package/popup/popup.html

@@ -28,6 +28,9 @@
       <input type="range" id="subScale" min="0.7" max="1.8" step="0.1">
       <output id="subScaleOut"></output>
     </label>
+    <div class="row">字幕样式
+      <div class="seg" data-key="subStyle"><button value="outline">描边</button><button value="box">半透明底框</button></div>
+    </div>
     <label class="toggle"><input type="checkbox" id="embedLogin"><span>用我的 YouTube 登录状态播放</span></label>
     <p class="hint">播放器提示 “Sign in to confirm you're not a bot” 时打开。观看会计入你的 YouTube 历史记录，开启后刷新视频页生效。</p>
   </section>