poi-plugin-kai-planner 1.0.19 → 1.0.20

package/README.md

@@ -6,10 +6,10 @@
 
 - 在`每日改修`页面查看当天可改修装备、基础消耗、秘书舰要求与可进化状态。
 - 在`每日改修`页面把常看的装备标记为收藏，收藏项会优先排序并长期保存在本地。
-- 在`改修心愿清单`页面创建、编辑、刷新和追踪个人改修计划，查看实时完成进度与资源缺口。
+- 在`改修规划`页面创建、编辑、刷新和追踪个人改修计划，查看实时完成进度与资源缺口。
 - 在`装备获取规划`页面管理想提前准备的装备，查看它们与未完成改修计划之间的待消耗关联。
-- 在`Debug`页面查看插件运行时数据与调试信息。
-- 静态数据支持远端版本更新；插件默认每 2 天自动检查一次，也可以手动点击“检查更新”。
+- 按需开启 `poiPlugin.enableDebug` 后，在 `Debug` 页面查看运行时数据；默认隐藏。
+- 静态数据在页面挂载时检查：成功后间隔 2 个 UTC 自然日，失败后间隔 15 分钟；可手动“检查更新”。下载有超时和有限重试，成功后页面自动刷新并保留编辑草稿。
 - 改修规划的待消耗道具会区分 useitem 与 `api_material` 资源类材料，例如高速建造材、高速修复材、开发资材、改修资材。
 
 ## 技术文档

package/index.js

@@ -7,6 +7,8 @@ const { WindowEnv } = require("views/components/etc/window-env");
 const { KaiPlannerApp } = require("./src/app/KaiPlannerApp");
 const { subscribeMaterialResourceUpdates } = require("./src/services/player/materialResourceCounts");
 
+const { enableDataUpdates, disposeDataUpdates } = require("./src/services/static/version/dataUpdateManager");
+
 let unsubscribeMaterialResourceUpdates = null;
 
 function KaiPlannerAppWithEnv() {
@@ -21,27 +23,26 @@ function KaiPlannerAppWithEnv() {
   });
 }
 
-module.exports = {
-  reactClass: KaiPlannerAppWithEnv,
-  windowMode: true,
-
-  pluginDidLoad() {
-    if (!unsubscribeMaterialResourceUpdates) {
-      unsubscribeMaterialResourceUpdates = subscribeMaterialResourceUpdates(
-        typeof window !== "undefined" ? window : null
-      );
-    }
-    if (typeof window !== "undefined" && window.log) {
-      window.log("[kai-planner] loaded");
-    }
-  },
-  pluginWillUnload() {
-    if (unsubscribeMaterialResourceUpdates) {
-      unsubscribeMaterialResourceUpdates();
-      unsubscribeMaterialResourceUpdates = null;
-    }
-    if (typeof window !== "undefined" && window.log) {
-      window.log("[kai-planner] unloaded");
-    }
-  },
+exports.reactClass = KaiPlannerAppWithEnv;
+exports.windowMode = true;
+exports.pluginDidLoad = function pluginDidLoad() {
+  enableDataUpdates();
+  if (!unsubscribeMaterialResourceUpdates) {
+    unsubscribeMaterialResourceUpdates = subscribeMaterialResourceUpdates(
+      typeof window !== "undefined" ? window : null
+    );
+  }
+  if (typeof window !== "undefined" && window.log) {
+    window.log("[kai-planner] loaded");
+  }
+};
+exports.pluginWillUnload = function pluginWillUnload() {
+  disposeDataUpdates();
+  if (unsubscribeMaterialResourceUpdates) {
+    unsubscribeMaterialResourceUpdates();
+    unsubscribeMaterialResourceUpdates = null;
+  }
+  if (typeof window !== "undefined" && window.log) {
+    window.log("[kai-planner] unloaded");
+  }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poi-plugin-kai-planner",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "main": "index.js",
   "author": "aulu",
   "contributors": ["aulu"],

package/src/app/KaiPlannerApp.js

@@ -1,7 +1,8 @@
 const React = require("react");
 const { DailyTabV2 } = require("./tabs/daily/DailyTabV2");
-const { checkAndUpdateData } = require("../services/static/version/dataUpdateManager");
+const { checkAndUpdateData, getUpdateState, subscribeDataUpdates } = require("../services/static/version/dataUpdateManager");
 const { readMeta } = require("../services/static/version/versionStore");
+const { ensurePluginWindowVisible } = require("../core/poi/ensurePluginWindowVisible");
 const {
   DEFAULT_THEME_TOKENS,
   readPoiTheme,
@@ -66,7 +67,7 @@ function getUpdateFailureTip(result) {
     data_source_not_configured: "未配置远端数据源",
   };
   const label = labels[reason] || "检查失败";
-  return result && result.error ? `${label}：${result.error}` : label;
+  return reason === "update_cancelled" ? "更新已取消。" : `${label}，可点击检查更新重试。`;
 }
 
 class KaiPlannerApp extends React.Component {
@@ -77,7 +78,10 @@ class KaiPlannerApp extends React.Component {
       wishlistLoadError: null,
       acquisitionLoadError: null,
       debugLoadError: null,
-      checkingUpdate: false,
+      checkingUpdate: getUpdateState().checking,
+      dataRevision: getUpdateState().dataRevision,
+      updateDiagnostic: "",
+      copyTip: "",
       lastUpdateAtText: "-",
       updateTip: "",
       materialResourceVersion: 0,
@@ -89,12 +93,17 @@ class KaiPlannerApp extends React.Component {
     this._unsubscribeTheme = null;
     this._unsubscribeMaterialResources = null;
     this._themeWarmupTimer = null;
+    this._cancelWindowVisibility = null;
     this.enableDebug = readEnableDebugFlag();
     this.handleCheckUpdate = this.handleCheckUpdate.bind(this);
     this.syncTheme = this.syncTheme.bind(this);
   }
 
   componentDidMount() {
+    this._mounted = true;
+    this._unsubscribeDataUpdates = subscribeDataUpdates(() => this.syncDataUpdateState());
+    this.syncDataUpdateState();
+    this._cancelWindowVisibility = ensurePluginWindowVisible(this.props.envWindow, this.props.envCtx);
     this.syncTheme();
     this._unsubscribeTheme = subscribePoiTheme(this.props.envWindow, (hostTheme) => {
       this.setState({ themeTokens: buildPlannerThemeTokens(hostTheme) });
@@ -109,6 +118,10 @@ class KaiPlannerApp extends React.Component {
   }
 
   componentWillUnmount() {
+    this._mounted = false;
+    if (this._unsubscribeDataUpdates) this._unsubscribeDataUpdates();
+    if (this._cancelWindowVisibility) this._cancelWindowVisibility();
+    this._cancelWindowVisibility = null;
     if (typeof this._unsubscribeTheme === "function") this._unsubscribeTheme();
     if (typeof this._unsubscribeMaterialResources === "function") this._unsubscribeMaterialResources();
     if (this._themeWarmupTimer != null) {
@@ -133,21 +146,44 @@ class KaiPlannerApp extends React.Component {
     } catch {}
   }
 
+  syncDataUpdateState() {
+    if (!this._mounted) return;
+    const update = getUpdateState();
+    const meta = readMeta();
+    const result = update.result;
+    const failure = result && !result.ok ? result : ((!result || result.skipped) && meta.lastCheckOk === false ? {
+      reason: meta.lastCheckReason, error: meta.lastCheckError, diagnostic: meta.lastCheckDiagnostic,
+    } : null);
+    this.setState({
+      checkingUpdate: update.checking,
+      dataRevision: update.dataRevision,
+      updateDiagnostic: failure ? JSON.stringify({ checkedAt: meta.lastCheckAt, reason: failure.reason, diagnostic: failure.diagnostic, error: failure.error }, null, 2) : "",
+    });
+    this.syncUpdateMeta();
+  }
+
+  async copyUpdateDiagnostic() {
+    try {
+      await require("views/services/clipboard").writeClipboardText(this.state.updateDiagnostic);
+      if (this._mounted) this.setState({ copyTip: "已复制" });
+    } catch {
+      if (this._mounted) this.setState({ copyTip: "复制失败，请选中下方详情手动复制。" });
+    }
+  }
+
   async handleCheckUpdate(force) {
-    if (this.state.checkingUpdate) return;
-    this.setState({ checkingUpdate: true, updateTip: force ? "正在检查..." : "" });
+    if (!this._mounted) return;
+    this.setState({ updateTip: force ? "正在检查..." : "", copyTip: "" });
     try {
       const result = await checkAndUpdateData({ force: !!force });
-      this.syncUpdateMeta();
+      if (!this._mounted) return;
       if (force) {
-        if (result && result.ok && result.updated) this.setState({ updateTip: `已更新到数据版本 ${result.remoteVersion}` });
-        else if (result && result.ok && !result.updated) this.setState({ updateTip: "当前已是最新数据。" });
+        if (result.ok && result.updated) this.setState({ updateTip: `已更新到数据版本 ${result.remoteVersion}` });
+        else if (result.ok) this.setState({ updateTip: "当前已是最新数据。" });
         else this.setState({ updateTip: getUpdateFailureTip(result) });
       }
     } catch (error) {
-      if (force) this.setState({ updateTip: `检查失败：${String(error && (error.stack || error))}` });
-    } finally {
-      this.setState({ checkingUpdate: false });
+      if (this._mounted) this.setState({ updateTip: "检查失败，可重试。", updateDiagnostic: String(error.stack || error) });
     }
   }
 
@@ -177,6 +213,7 @@ class KaiPlannerApp extends React.Component {
       content = React.createElement(DailyTabV2, {
         envWindow: this.props.envWindow,
         envCtx: this.props.envCtx,
+        dataRevision: this.state.dataRevision,
         themeTokens,
       });
     } else if (tab === "wishlist") {
@@ -198,6 +235,7 @@ class KaiPlannerApp extends React.Component {
         content = React.createElement(this._WishlistTab, {
           envWindow: this.props.envWindow,
           envCtx: this.props.envCtx,
+        dataRevision: this.state.dataRevision,
           materialResourceVersion: this.state.materialResourceVersion,
           themeTokens,
         });
@@ -223,6 +261,7 @@ class KaiPlannerApp extends React.Component {
         content = React.createElement(this._AcquisitionTab, {
           envWindow: this.props.envWindow,
           envCtx: this.props.envCtx,
+        dataRevision: this.state.dataRevision,
           themeTokens,
         });
       } else {
@@ -247,6 +286,7 @@ class KaiPlannerApp extends React.Component {
         content = React.createElement(this._DebugTab, {
           envWindow: this.props.envWindow,
           envCtx: this.props.envCtx,
+        dataRevision: this.state.dataRevision,
           themeTokens,
         });
       } else {
@@ -284,6 +324,13 @@ class KaiPlannerApp extends React.Component {
           this.state.updateTip ? React.createElement("span", { style: { fontSize: 14, color: themeTokens.textMuted } }, this.state.updateTip) : null
         )
       ),
+      this.state.updateDiagnostic ? React.createElement("details", { style: { marginBottom: 12 } },
+        React.createElement("summary", null, "最近一次更新未完成：查看诊断详情"),
+        React.createElement("button", { onClick: () => this.copyUpdateDiagnostic() }, "复制诊断详情"),
+        React.createElement("span", null, this.state.copyTip),
+        React.createElement("textarea", { readOnly: true, value: this.state.updateDiagnostic,
+          style: { width: "100%", height: 140 }, onFocus: (event) => event.target.select() })
+      ) : null,
       content
     );
   }

package/src/app/tabs/acquisition/AcquisitionTab.js

@@ -48,11 +48,7 @@ class AcquisitionTab extends React.Component {
   constructor(props) {
     super(props);
 
-    this.staticData = loadStaticData();
-    this.consumeIndexes = buildConsumeIndexes(this.staticData);
-    this.upgradeIndexes = buildUpgradeIndexes(this.staticData);
-    this.pathByPair = buildPathIndexes(this.staticData).pathByPair;
-    this.arrangementIndex = buildArrangementIndex(this.staticData.improvementArrangement).index;
+    this.reloadStaticData();
 
     this.state = {
       nowText: formatTokyoText(),
@@ -77,11 +73,26 @@ class AcquisitionTab extends React.Component {
     this.refresh = this.refresh.bind(this);
   }
 
+  reloadStaticData() {
+    this.staticData = loadStaticData();
+    this.consumeIndexes = buildConsumeIndexes(this.staticData);
+    this.upgradeIndexes = buildUpgradeIndexes(this.staticData);
+    this.pathByPair = buildPathIndexes(this.staticData).pathByPair;
+    this.arrangementIndex = buildArrangementIndex(this.staticData.improvementArrangement).index;
+  }
+
   componentDidMount() {
     this._timer = setInterval(() => this.setState({ nowText: formatTokyoText() }), 1000);
     this.refresh();
   }
 
+  componentDidUpdate(prevProps) {
+    if (prevProps.dataRevision !== this.props.dataRevision) {
+      this.reloadStaticData();
+      this.refresh();
+    }
+  }
+
   componentWillUnmount() {
     if (this._timer) clearInterval(this._timer);
   }

package/src/app/tabs/daily/DailyTabV2.js

@@ -185,6 +185,10 @@ class DailyTabV2 extends React.Component {
     }, 1000);
   }
 
+  componentDidUpdate(prevProps) {
+    if (prevProps.dataRevision !== this.props.dataRevision) this.refresh();
+  }
+
   componentWillUnmount() {
     if (this._timer) clearInterval(this._timer);
   }

package/src/app/tabs/debug/debugDiagnostics.js

@@ -42,6 +42,7 @@ function buildDebugDiagnostics({
       lastCheckAt: meta.lastCheckAt || "",
       lastCheckOk: meta.lastCheckOk == null ? null : !!meta.lastCheckOk,
       lastCheckReason: meta.lastCheckReason || "",
+      lastCheckDiagnostic: meta.lastCheckDiagnostic || null,
       dataDir: staticInfo.dataDir || "",
       cachePath: staticInfo.cachePath || "",
       cacheExists: !!staticInfo.cacheExists,

package/src/app/tabs/wishlist/WishlistTabV2.js

@@ -121,11 +121,7 @@ class WishlistTabV2 extends React.Component {
   constructor(props) {
     super(props);
 
-    this.staticData = loadStaticData();
-    this.consumeIndexes = buildConsumeIndexes(this.staticData);
-    this.upgradeIndexes = buildUpgradeIndexes(this.staticData);
-    this.pathByPair = buildPathIndexes(this.staticData).pathByPair;
-    this.arrangementIndex = buildArrangementIndex(this.staticData.improvementArrangement).index;
+    this.reloadStaticData();
     this._ownerShipIndexCache = { shipsRef: null, map: {} };
     this._startOptionsCache = { targetEquipId: null, equipsRef: null, plansKey: "", ownerMapRef: null, options: [] };
 
@@ -167,6 +163,14 @@ class WishlistTabV2 extends React.Component {
     this.refreshPlanById = this.refreshPlanById.bind(this);
   }
 
+  reloadStaticData() {
+    this.staticData = loadStaticData();
+    this.consumeIndexes = buildConsumeIndexes(this.staticData);
+    this.upgradeIndexes = buildUpgradeIndexes(this.staticData);
+    this.pathByPair = buildPathIndexes(this.staticData).pathByPair;
+    this.arrangementIndex = buildArrangementIndex(this.staticData.improvementArrangement).index;
+  }
+
   componentDidMount() {
     this._timer = setInterval(() => this.setState({ nowText: formatTokyoText() }), 1000);
     this.refreshPlans();
@@ -179,6 +183,12 @@ class WishlistTabV2 extends React.Component {
   }
 
   componentDidUpdate(prevProps) {
+    if (prevProps.dataRevision !== this.props.dataRevision) {
+      this.reloadStaticData();
+      this._startOptionsCache = {};
+      this.refreshPlans({ preserveInteraction: true });
+      return;
+    }
     if (prevProps.materialResourceVersion === this.props.materialResourceVersion) return;
     const state = this.getReduxState();
     if (!state || !state.const || !state.info) return;
@@ -374,7 +384,8 @@ class WishlistTabV2 extends React.Component {
   setFilterNote(value) {
     this.setState(this.clearSelectionState({ filterNote: value, info: null }));
   }
-  refreshPlans() {
+  refreshPlans({ preserveInteraction = false } = {}) {
+    const interactionPatch = (patch) => preserveInteraction ? patch : this.clearSelectionState(patch);
     try {
       const state = this.getReduxState();
       const plans = loadPlans();
@@ -461,7 +472,7 @@ class WishlistTabV2 extends React.Component {
       };
 
       this.setState(
-        this.clearSelectionState({
+        interactionPatch({
           ...buildInitialWishlistHydrationState({
             plans,
             initialSnapshot,
@@ -474,7 +485,7 @@ class WishlistTabV2 extends React.Component {
         }
       );
     } catch (error) {
-      this.setState(this.clearSelectionState({ error: String(error && (error.stack || error)), hydrating: false, hydrationQueue: [] }));
+      this.setState(interactionPatch({ error: String(error && (error.stack || error)), hydrating: false, hydrationQueue: [] }));
     }
   }
 

package/src/core/poi/ensurePluginWindowVisible.js

@@ -0,0 +1,54 @@
+const PLUGIN_QUERY = "?poi-plugin-kai-planner";
+
+// Portal components execute in poi's main renderer. Never use
+// remote.getCurrentWindow(): that would target the main window.
+function ensurePluginWindowVisible(envWindow, envCtx, options = {}) {
+  let cancelled = false;
+  let timer = null;
+  const schedule = options.schedule || setTimeout;
+  const clear = options.clear || clearTimeout;
+  const warn = options.warn || ((error) => console.warn("[kai-planner] window visibility fallback failed", error));
+  const cancel = () => {
+    cancelled = true;
+    if (timer !== null) clear(timer);
+    timer = null;
+  };
+
+  try {
+    const mountPoint = envCtx && envCtx.mountPoint;
+    if (!envWindow || envWindow.closed || envWindow.isWindowMode !== true || !mountPoint) return cancel;
+    const doc = envWindow.document;
+    const url = new URL(envWindow.location.href);
+    if (url.protocol !== "file:" || !url.pathname.endsWith("/index-plugin.html") || url.search !== PLUGIN_QUERY) return cancel;
+    if (mountPoint.ownerDocument !== doc || !mountPoint.isConnected) return cancel;
+
+    const remote = options.remote || require("@electron/remote");
+    const matches = remote.BrowserWindow.getAllWindows().filter(
+      (win) => !win.isDestroyed() && win.webContents.getURL() === url.href
+    );
+    if (matches.length !== 1) return cancel;
+    // Capture this instance now, never search again after a close/reopen.
+    const target = matches[0];
+    if (target.isVisible() || target.isMinimized()) return cancel;
+
+    // Run after the mount commit; one check only, no polling or focus call.
+    timer = schedule(() => {
+      timer = null;
+      if (cancelled) return;
+      try {
+        if (envWindow.closed || target.isDestroyed()) return;
+        if (envWindow.document !== doc || envWindow.location.href !== url.href) return;
+        if (!mountPoint.isConnected || mountPoint.ownerDocument !== doc || !mountPoint.querySelector(".kai-planner-root")) return;
+        if (target.webContents.getURL() !== url.href || target.isVisible() || target.isMinimized()) return;
+        target.show();
+      } catch (error) {
+        warn(error);
+      }
+    }, 0);
+  } catch (error) {
+    warn(error);
+  }
+  return cancel;
+}
+
+module.exports = { ensurePluginWindowVisible };

package/src/services/static/version/dataUpdateManager.js

@@ -13,14 +13,31 @@ const {
 
 const CHECK_INTERVAL_DAYS = 2;
 
-function nowMs() {
-  return Date.now();
-}
+const { requestText, throwIfCancelled } = require("./requestText");
+const FAILURE_RETRY_MS = 15 * 60 * 1000;
+let activeTask = null;
+let enabled = true;
+let dataRevision = 0;
+let lastResult = null;
+const listeners = new Set();
 
-function toMs(iso) {
-  if (!iso) return 0;
-  const t = new Date(iso).getTime();
-  return Number.isFinite(t) ? t : 0;
+function getUpdateState() {
+  return { checking: !!activeTask, dataRevision, result: lastResult };
+}
+function subscribeDataUpdates(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function notify() {
+  for (const listener of listeners) {
+    try { listener(getUpdateState()); } catch (error) { console.warn("[kai-planner] update subscriber failed", error); }
+  }
+}
+function enableDataUpdates() { enabled = true; }
+function disposeDataUpdates() {
+  enabled = false;
+  if (activeTask) activeTask.controller.abort();
+  listeners.clear();
 }
 
 function parseVersion(v) {
@@ -48,30 +65,14 @@ function makeReasonError(reason, message) {
   return error;
 }
 
-async function fetchJson(url) {
-  let res;
-  try {
-    res = await fetch(url, { method: "GET", cache: "no-store" });
-  } catch (error) {
-    throw makeReasonError("manifest_fetch_failed", String(error && (error.stack || error)));
-  }
-  if (!res.ok) throw makeReasonError("manifest_fetch_failed", `http ${res.status} for ${url}`);
-  try {
-    return await res.json();
-  } catch (error) {
-    throw makeReasonError("manifest_invalid", String(error && (error.stack || error)));
-  }
-}
-
-async function fetchText(url) {
-  let res;
-  try {
-    res = await fetch(url, { method: "GET", cache: "no-store" });
-  } catch (error) {
-    throw makeReasonError("remote_file_fetch_failed", String(error && (error.stack || error)));
+async function fetchJson(url, signal) {
+  const text = await requestText(url, { signal, file: "data_manifest.json", reason: "manifest_fetch_failed" });
+  try { return JSON.parse(text); }
+  catch (error) {
+    throw Object.assign(makeReasonError("manifest_invalid", error.message), {
+      diagnostic: { file: "data_manifest.json", url, stage: "parse", error: String(error.stack || error) },
+    });
   }
-  if (!res.ok) throw makeReasonError("remote_file_fetch_failed", `http ${res.status} for ${url}`);
-  return res.text();
 }
 
 function getDaySerial(d) {
@@ -85,12 +86,13 @@ function shouldAutoCheck(meta) {
   if (!lastIso) return true;
   const last = new Date(lastIso);
   if (!Number.isFinite(last.getTime())) return true;
+  if (meta.lastCheckOk === false) return Date.now() - last.getTime() >= FAILURE_RETRY_MS;
   const now = new Date();
   const diffDays = getDaySerial(now) - getDaySerial(last);
   return diffDays >= CHECK_INTERVAL_DAYS;
 }
 
-async function applyRemoteData(remoteManifest, rawBaseUrl) {
+async function applyRemoteData(remoteManifest, rawBaseUrl, signal) {
   const files = Array.isArray(remoteManifest && remoteManifest.files) ? remoteManifest.files : [];
   if (!files.length) {
     throw makeReasonError("manifest_invalid", "remote manifest has no files");
@@ -108,17 +110,19 @@ async function applyRemoteData(remoteManifest, rawBaseUrl) {
     for (const f of files) {
       const fileName = String(f);
       const url = `${rawBaseUrl.replace(/\/+$/, "")}/${fileName}`;
-      const text = await fetchText(url);
+      const text = await requestText(url, { signal, file: fileName, reason: "remote_file_fetch_failed" });
+      throwIfCancelled(signal);
       try {
         JSON.parse(text);
       } catch (error) {
-        throw makeReasonError("remote_file_invalid_json", `${fileName}: ${String(error && error.message ? error.message : error)}`);
+        throw Object.assign(makeReasonError("remote_file_invalid_json", error.message), { diagnostic: { file: fileName, url, stage: "parse", error: String(error.stack || error) } });
       }
       if (!writeCacheFileToDir(tempDir, fileName, text)) {
         throw makeReasonError("cache_stage_failed", `failed to stage ${fileName}`);
       }
     }
 
+    throwIfCancelled(signal);
     if (!commitCacheDir(tempDir)) {
       throw makeReasonError("cache_commit_failed", "failed to commit remote data cache");
     }
@@ -153,12 +157,13 @@ function getLocalManifestUpdatedAt() {
   return null;
 }
 
-async function checkAndUpdateData({ force = false } = {}) {
+async function runUpdate(force, signal) {
+  throwIfCancelled(signal);
   const cfg = getDataSourceConfig();
   const meta = readMeta();
   const startCheckAt = new Date().toISOString();
 
-    if (!cfg.manifestRawUrl || !cfg.rawBaseUrl) {
+  if (!cfg.manifestRawUrl || !cfg.rawBaseUrl) {
     const nextMeta = writeMeta({
       lastCheckAt: startCheckAt,
       lastCheckOk: false,
@@ -182,7 +187,7 @@ async function checkAndUpdateData({ force = false } = {}) {
   }
 
   try {
-    const remoteManifest = await fetchJson(cfg.manifestRawUrl);
+    const remoteManifest = await fetchJson(cfg.manifestRawUrl, signal);
     if (!remoteManifest || typeof remoteManifest !== "object" || !remoteManifest.data_version) {
       throw makeReasonError("manifest_invalid", "remote manifest missing data_version");
     }
@@ -191,7 +196,7 @@ async function checkAndUpdateData({ force = false } = {}) {
     const hasNewer = compareVersion(remoteVersion, localVersion) > 0;
 
     if (hasNewer) {
-      await applyRemoteData(remoteManifest, cfg.rawBaseUrl);
+      await applyRemoteData(remoteManifest, cfg.rawBaseUrl, signal);
     }
 
     const nextMeta = writeMeta({
@@ -199,6 +204,7 @@ async function checkAndUpdateData({ force = false } = {}) {
       lastCheckOk: true,
       lastCheckReason: hasNewer ? "updated" : "not_updated",
       lastCheckError: "",
+      lastCheckDiagnostic: null,
       lastVersion: hasNewer ? remoteVersion : localVersion,
       lastUpdateAt: hasNewer
         ? (remoteManifest.updated_at || startCheckAt)
@@ -215,25 +221,54 @@ async function checkAndUpdateData({ force = false } = {}) {
       meta: nextMeta,
     };
   } catch (e) {
+    if (signal.aborted) return { ok: false, reason: "update_cancelled" };
     const reason = e && e.reason ? String(e.reason) : "update_failed";
     const nextMeta = writeMeta({
       lastCheckAt: startCheckAt,
       lastCheckOk: false,
       lastCheckReason: reason,
       lastCheckError: String(e && (e.stack || e)),
+      lastCheckDiagnostic: e.diagnostic || { stage: reason, error: String(e && (e.stack || e)) },
     });
     return {
       ok: false,
       skipped: false,
       reason,
       error: String(e && (e.stack || e)),
+      diagnostic: nextMeta.lastCheckDiagnostic,
       meta: nextMeta,
     };
   }
 }
 
+// A single promise belongs to the service, not a mounted React component.
+function checkAndUpdateData({ force = false } = {}) {
+  if (!enabled) return Promise.resolve({ ok: false, reason: "update_cancelled" });
+  if (activeTask) {
+    if (activeTask.controller.signal.aborted) {
+      return activeTask.promise.then(() => checkAndUpdateData({ force }));
+    }
+    return activeTask.promise;
+  }
+  const task = { controller: new AbortController(), promise: null };
+  activeTask = task;
+  task.promise = Promise.resolve().then(() => runUpdate(force, task.controller.signal))
+    .catch(error => ({ ok: false, reason: task.controller.signal.aborted ? "update_cancelled" : "update_failed", error: String(error.stack || error) }))
+    .then(result => {
+      if (!task.controller.signal.aborted) {
+        if (!result.skipped || !lastResult) lastResult = result;
+        if (result.ok && result.updated) dataRevision++;
+      }
+      return result;
+    }).finally(() => {
+      if (activeTask === task) activeTask = null;
+      if (enabled) notify();
+    });
+  notify();
+  return task.promise;
+}
+
 module.exports = {
-  CHECK_INTERVAL_DAYS,
-  shouldAutoCheck,
-  checkAndUpdateData,
+  CHECK_INTERVAL_DAYS, FAILURE_RETRY_MS, shouldAutoCheck, checkAndUpdateData,
+  getUpdateState, subscribeDataUpdates, enableDataUpdates, disposeDataUpdates,
 };

package/src/services/static/version/requestText.js

@@ -0,0 +1,81 @@
+const REQUEST_TIMEOUT_MS = 15000;
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAYS_MS = [500, 1500];
+
+function cancelledError() {
+  return Object.assign(new Error("Update cancelled"), { reason: "update_cancelled" });
+}
+
+function throwIfCancelled(signal) {
+  if (signal && signal.aborted) throw cancelledError();
+}
+
+function waitForRetry(ms, signal) {
+  return new Promise((resolve, reject) => {
+    throwIfCancelled(signal);
+    const abort = () => { clearTimeout(timer); reject(cancelledError()); };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+// Keep the renderer fetch implementation so Electron session proxy settings apply.
+// The deadline includes reading the response body, not just receiving headers.
+async function requestText(url, { signal, file, reason, timeoutMs = REQUEST_TIMEOUT_MS,
+  delays = RETRY_DELAYS_MS, fetchImpl = (...args) => fetch(...args) } = {}) {
+  const started = Date.now();
+  const parentSignal = signal || new AbortController().signal;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    throwIfCancelled(parentSignal);
+    const controller = new AbortController();
+    let timer;
+    let abort;
+    let stage = "request";
+    let status = null;
+    try {
+      const interrupt = new Promise((_, reject) => {
+        abort = () => { reject(cancelledError()); controller.abort(); };
+        parentSignal.addEventListener("abort", abort, { once: true });
+        timer = setTimeout(() => {
+          reject(Object.assign(new Error("Request timed out"), { timeout: true }));
+          controller.abort();
+        }, timeoutMs);
+      });
+      const work = (async () => {
+        const response = await fetchImpl(url, { method: "GET", cache: "no-store", signal: controller.signal });
+        status = response.status || null;
+        if (!response.ok) {
+          stage = "http";
+          const error = Object.assign(new Error(`HTTP ${status}`), {
+            retryable: status === 408 || status === 429 || status >= 500,
+          });
+          controller.abort();
+          throw error;
+        }
+        stage = "body";
+        return await response.text();
+      })();
+      const text = await Promise.race([work, interrupt]);
+      throwIfCancelled(parentSignal);
+      return text;
+    } catch (error) {
+      throwIfCancelled(parentSignal);
+      if (attempt === MAX_ATTEMPTS || error.retryable === false) {
+        throw Object.assign(new Error(error.message || String(error)), {
+          reason,
+          diagnostic: { file, url, stage, attempt, elapsedMs: Date.now() - started,
+            status, timeout: !!error.timeout, error: String(error.stack || error) },
+        });
+      }
+    } finally {
+      clearTimeout(timer);
+      parentSignal.removeEventListener("abort", abort);
+    }
+    await waitForRetry(delays[attempt - 1] || 0, parentSignal);
+  }
+}
+
+module.exports = { requestText, throwIfCancelled, REQUEST_TIMEOUT_MS, MAX_ATTEMPTS, RETRY_DELAYS_MS };