@www.hyperlinks.space/program-kit 1.2.3

package/windows/build.cjs

@@ -0,0 +1,2247 @@
+const {
+  app,
+  BrowserWindow,
+  Menu,
+  protocol,
+  net,
+  dialog,
+  Notification,
+  ipcMain,
+  nativeImage,
+  nativeTheme,
+} = require("electron");
+
+/** Must match package.json `build.appId`. Call synchronously before `ready` on Windows (Electron + shell taskbar expectations). */
+const WIN_APP_USER_MODEL_ID = "com.sraibaby.app";
+if (process.platform === "win32") {
+  try {
+    app.setAppUserModelId(WIN_APP_USER_MODEL_ID);
+  } catch (_) {}
+}
+
+// Optional: set HSP_DISABLE_GPU=1 to test whether GPU stack affects shortcuts (e.g. Print Screen) on Windows.
+if (process.platform === "win32" && process.env.HSP_DISABLE_GPU === "1") {
+  try {
+    app.disableHardwareAcceleration();
+  } catch (_) {}
+}
+const path = require("path");
+const fs = require("fs");
+const crypto = require("crypto");
+const { spawn, spawnSync } = require("child_process");
+const { pathToFileURL } = require("url");
+const brand = require("./product-brand.cjs");
+
+const UPDATE_GITHUB_OWNER = "HyperlinksSpace";
+/** Must match `build.publish.repo` and the repo where CI uploads releases. */
+const UPDATE_GITHUB_REPO = "HyperlinksSpaceProgram";
+const ZIP_LATEST_YML = "zip-latest.yml";
+/** Same pattern as package.json build.win.artifactName for the zip target. */
+const WIN_PORTABLE_ZIP_PREFIX = brand.portableZipPrefix;
+const LATEST_YML = "latest.yml";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** GitHub / Electron net layer: transient errors worth retrying (backoff in checkForUpdatesWithRetry). */
+function isTransientGithubUpdateError(err) {
+  if (!err) return false;
+  const code = err.statusCode ?? err.status;
+  if (code === 502 || code === 503 || code === 504) return true;
+  const msg = String(err.message || err);
+  if (
+    /\b502\b|\b503\b|\b504\b|Bad Gateway|Service Unavailable|Gateway Timeout|taking too long|ECONNRESET|ETIMEDOUT/i.test(
+      msg,
+    )
+  )
+    return true;
+  // Electron reports URL loader failures as net::ERR_* (not Node ECONNRESET).
+  if (/net::ERR_CONNECTION_RESET|net::ERR_CONNECTION_TIMED_OUT|net::ERR_NETWORK_CHANGED/i.test(msg))
+    return true;
+  return false;
+}
+
+/** Ring buffer for the updater dialog (last lines only). */
+const UPDATER_DIALOG_LOG_MAX = 120;
+const updaterDialogLogBuffer = [];
+
+/** Set in setupAutoUpdater: sends a fully formatted log line (with ISO time) to the dialog. */
+let updaterLogToDialog = null;
+
+function appendUpdaterDialogLogLine(messageBody) {
+  const line = `[${new Date().toISOString()}] ${messageBody}`;
+  updaterDialogLogBuffer.push(line);
+  if (updaterDialogLogBuffer.length > UPDATER_DIALOG_LOG_MAX) {
+    updaterDialogLogBuffer.splice(0, updaterDialogLogBuffer.length - UPDATER_DIALOG_LOG_MAX);
+  }
+  try {
+    updaterLogToDialog?.(line);
+  } catch (_) {}
+}
+
+/** Structured lines in userData/main.log and updater dialog: `[updater:tag] message` */
+function logUpdater(tag, msg) {
+  const body = `[updater:${tag}] ${msg}`;
+  log(body);
+  appendUpdaterDialogLogLine(body);
+}
+
+function safeJson(obj, maxLen = 800) {
+  try {
+    const s = JSON.stringify(obj);
+    return s.length > maxLen ? `${s.slice(0, maxLen)}…` : s;
+  } catch (_) {
+    return String(obj);
+  }
+}
+
+/** Escape for a PowerShell single-quoted literal (only ' is doubled). */
+function escapePsSingleQuotedPath(p) {
+  return String(p).replace(/'/g, "''");
+}
+
+/**
+ * Detached `powershell -File script.ps1 -PlanPath ...` often drops or misparses args on Windows.
+ * Use a short UTF-16LE -EncodedCommand that writes %TEMP%\\hsp-apply-trace.log then invokes the script.
+ */
+function buildWindowsApplyLauncherCommand(ps1Path, planPath) {
+  const qPs1 = escapePsSingleQuotedPath(ps1Path);
+  const qPlan = escapePsSingleQuotedPath(planPath);
+  return (
+    `$ErrorActionPreference='Stop';` +
+    `try{$t=Join-Path $env:TEMP 'hsp-apply-trace.log';` +
+    `$ts=(Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ');` +
+    `Add-Content -LiteralPath $t -Encoding UTF8 -Value ('['+$ts+'] launcher start pid='+$PID)}catch{};` +
+    `& '${qPs1}' -PlanPath '${qPlan}'`
+  );
+}
+
+/**
+ * Prefer zip-latest.yml (has sha512 for the zip). If missing (404), use latest.yml + inferred zip name.
+ * @returns {{ version: string, fileName: string, sha512: string | null, source: string }}
+ */
+async function resolveWindowsZipSidecarMeta(netFetch, currentVersion) {
+  logUpdater("meta", `resolve sidecar manifests (current=${currentVersion})`);
+  const zipLatestUrl = githubLatestAssetUrl(ZIP_LATEST_YML);
+  const zlRes = await netFetch(zipLatestUrl);
+  if (zlRes.ok) {
+    const text = await zlRes.text();
+    const meta = parseSimpleUpdateYml(text);
+    if (meta.version && meta.fileName && meta.sha512) {
+      if (compareSemverLike(meta.version, currentVersion) <= 0) {
+        throw new Error("zip-latest.yml version is not newer than current app");
+      }
+      logUpdater("meta", `using zip-latest.yml version=${meta.version} file=${meta.fileName}`);
+      return { version: meta.version, fileName: meta.fileName, sha512: meta.sha512, source: "zip-latest.yml" };
+    }
+    log("[updater] zip-latest.yml incomplete; falling back to latest.yml + inferred zip name");
+  } else {
+    log(
+      `[updater] zip-latest.yml HTTP ${zlRes.status} — using latest.yml and inferred ${WIN_PORTABLE_ZIP_PREFIX}<version>.zip`,
+    );
+  }
+
+  const lyUrl = githubLatestAssetUrl(LATEST_YML);
+  const lyRes = await netFetch(lyUrl);
+  if (!lyRes.ok) {
+    throw new Error(`latest.yml HTTP ${lyRes.status} (need a GitHub release with latest.yml)`);
+  }
+  const lyText = await lyRes.text();
+  const ly = parseSimpleUpdateYml(lyText);
+  if (!ly.version) {
+    throw new Error("latest.yml has no version");
+  }
+  if (compareSemverLike(ly.version, currentVersion) <= 0) {
+    throw new Error("latest.yml version is not newer than current app");
+  }
+  const fileName = `${WIN_PORTABLE_ZIP_PREFIX}${ly.version}.zip`;
+  logUpdater("meta", `using latest.yml+inferred version=${ly.version} file=${fileName}`);
+  return {
+    version: ly.version,
+    fileName,
+    sha512: null,
+    source: "latest.yml+inferred",
+  };
+}
+
+function compareSemverLike(a, b) {
+  const pa = String(a || "0")
+    .split(".")
+    .map((x) => parseInt(x, 10) || 0);
+  const pb = String(b || "0")
+    .split(".")
+    .map((x) => parseInt(x, 10) || 0);
+  const n = Math.max(pa.length, pb.length);
+  for (let i = 0; i < n; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da < db) return -1;
+    if (da > db) return 1;
+  }
+  return 0;
+}
+
+/**
+ * NSIS install: INSTDIR\versions\<semver>\… plus INSTDIR\current → junction (exe is …\current\<name>.exe).
+ * Legacy installs: exe lives directly in the install folder (no `current`). Returns the app root (parent of `current`, or the folder that contains the exe for legacy).
+ */
+function getWindowsAppRootFromExecPath(execPath) {
+  const dir = path.dirname(execPath);
+  if (path.basename(dir).toLowerCase() === "current") {
+    return path.dirname(dir);
+  }
+  return dir;
+}
+
+function parseSimpleUpdateYml(text) {
+  const versionM = text.match(/^version:\s*(.+)$/m);
+  const version = versionM ? versionM[1].trim() : null;
+  const pathM = text.match(/^path:\s*(.+)$/m);
+  let fileName = pathM ? pathM[1].trim() : null;
+  if (!fileName) {
+    const urlM = text.match(/^\s*url:\s*(.+)$/m);
+    fileName = urlM ? urlM[1].trim() : null;
+  }
+  const shaM = text.match(/^sha512:\s*(.+)$/m);
+  const sha512 = shaM ? shaM[1].trim() : null;
+  const sizeM = text.match(/^\s*size:\s*(\d+)\s*$/m);
+  const size = sizeM ? parseInt(sizeM[1], 10) : null;
+  return { version, fileName, sha512, size };
+}
+
+function githubLatestAssetUrl(fileName) {
+  const enc = encodeURIComponent(fileName).replace(/%20/g, "%20");
+  return `https://github.com/${UPDATE_GITHUB_OWNER}/${UPDATE_GITHUB_REPO}/releases/latest/download/${enc}`;
+}
+
+const GITHUB_API_HEADERS = {
+  Accept: "application/vnd.github+json",
+  "User-Agent": `${brand.productSlug}/electron-updater`,
+};
+
+/**
+ * When /releases/latest/download/<name>.zip returns 404, find the portable zip on the latest release
+ * via the GitHub API (asset names may differ slightly from artifactName).
+ * @returns {Promise<string|null>} browser_download_url or null
+ */
+async function fetchPortableZipBrowserUrlFromGitHubApi(netFetch, version, preferredFileName) {
+  logUpdater(
+    "github-api",
+    `resolve zip URL via API (version=${version} preferred=${preferredFileName})`,
+  );
+  const apiUrl = `https://api.github.com/repos/${UPDATE_GITHUB_OWNER}/${UPDATE_GITHUB_REPO}/releases/latest`;
+  const res = await netFetch(apiUrl, { headers: GITHUB_API_HEADERS });
+  if (!res.ok) {
+    log(`[updater] GitHub API GET releases/latest: HTTP ${res.status}`);
+    return null;
+  }
+  let data;
+  try {
+    data = await res.json();
+  } catch (_) {
+    return null;
+  }
+  const assets = Array.isArray(data.assets) ? data.assets : [];
+  const zips = assets.filter((a) => a && typeof a.name === "string" && /\.zip$/i.test(a.name));
+  const skipName = (n) =>
+    /blockmap|\.7z\.|\.delta/i.test(n) || /-ia32-|arm64|\.msi$/i.test(n);
+  const candidates = zips.filter((a) => !skipName(a.name));
+
+  const exact = candidates.find((a) => a.name === preferredFileName);
+  if (exact?.browser_download_url) {
+    log(`[updater] GitHub API: exact zip match ${exact.name}`);
+    logUpdater("github-api", `picked exact asset url=${exact.browser_download_url.slice(0, 120)}…`);
+    return exact.browser_download_url;
+  }
+
+  const verLoose = String(version).trim();
+  const withVersion = candidates.filter((a) => a.name.includes(verLoose));
+  if (withVersion.length === 1 && withVersion[0].browser_download_url) {
+    log(`[updater] GitHub API: single zip matching version ${verLoose}: ${withVersion[0].name}`);
+    logUpdater("github-api", `picked version-match url=${withVersion[0].browser_download_url.slice(0, 120)}…`);
+    return withVersion[0].browser_download_url;
+  }
+
+  const prefixed = candidates.find(
+    (a) =>
+      a.name.startsWith(WIN_PORTABLE_ZIP_PREFIX) ||
+      brand.portableZipAssetPattern().test(a.name) ||
+      /Hyperlinks\s*Space/i.test(a.name),
+  );
+  if (prefixed?.browser_download_url) {
+    log(`[updater] GitHub API: portable-like zip ${prefixed.name}`);
+    logUpdater("github-api", `picked portable-like url=${prefixed.browser_download_url.slice(0, 120)}…`);
+    return prefixed.browser_download_url;
+  }
+
+  if (candidates.length === 1 && candidates[0].browser_download_url) {
+    log(`[updater] GitHub API: only zip on release: ${candidates[0].name}`);
+    logUpdater("github-api", `picked sole zip url=${candidates[0].browser_download_url.slice(0, 120)}…`);
+    return candidates[0].browser_download_url;
+  }
+
+  log(
+    `[updater] GitHub API: could not pick zip (candidates: ${candidates.map((c) => c.name).join(", ") || "none"})`,
+  );
+  return null;
+}
+
+async function downloadToFile(netFetch, url, destPath, onProgress) {
+  logUpdater("download", `start → ${destPath}`);
+  logUpdater("download", `GET ${url.length > 200 ? `${url.slice(0, 200)}…` : url}`);
+  const res = await netFetch(url);
+  if (!res.ok) {
+    throw new Error(`Download failed ${res.status} ${url}`);
+  }
+  const total =
+    parseInt(res.headers.get("content-length") || res.headers.get("Content-Length") || "0", 10) || 0;
+  const reader = res.body?.getReader?.();
+  if (!reader) {
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (onProgress) onProgress(buf.length, total || buf.length);
+    fs.writeFileSync(destPath, buf);
+    logUpdater("download", `done bytes=${buf.length} (buffer path) → ${destPath}`);
+    return;
+  }
+  const ws = fs.createWriteStream(destPath);
+  let received = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value && value.length) {
+        received += value.length;
+        if (!ws.write(Buffer.from(value))) {
+          await new Promise((res) => ws.once("drain", res));
+        }
+        if (onProgress) onProgress(received, total);
+      }
+    }
+  } finally {
+    await new Promise((resolve, reject) => {
+      ws.end((err) => (err ? reject(err) : resolve()));
+    });
+  }
+  let sizeOnDisk = received;
+  try {
+    sizeOnDisk = fs.statSync(destPath).size;
+  } catch (_) {}
+  logUpdater("download", `done bytes=${sizeOnDisk} streamed=${received} totalHdr=${total || "?"} → ${destPath}`);
+}
+
+/**
+ * Unpack portable app .zip. On Windows, prefer system tar.exe (native I/O; avoids long
+ * apparent stalls streaming huge files through Node). Fall back to extract-zip.
+ * Pulse callback keeps the updater UI moving during large single-file writes (e.g. app.asar).
+ */
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.verifyExeBase] If set, after system tar succeeds we require resolveZipAppContentRoot
+ *   to find the app; otherwise we clear and fall back to extract-zip (tar can exit 0 with a bad tree for some zips).
+ */
+async function extractPortableZipToDir(zipPath, extractDir, logFn, pulse, unpackLo, unpackHi, opts = {}) {
+  const verifyExeBase = opts.verifyExeBase;
+  const runExtractZip = async () => {
+    logUpdater("extract", `extract-zip (yauzl) → ${extractDir}`);
+    const extractZip = require("extract-zip");
+    let unpackEntryCount = 0;
+    let unpackLastName = "";
+    const pulseUnpack = () => {
+      const span = Math.max(1, unpackHi - unpackLo);
+      const bump = Math.min(span, 4 + Math.floor(unpackEntryCount / 30));
+      const pct = Math.min(unpackHi, unpackLo + bump);
+      pulse({
+        text:
+          unpackEntryCount > 0
+            ? `${pct}% — Unpacking… ${unpackEntryCount} files${unpackLastName ? ` — ${unpackLastName.slice(-56)}` : ""}`
+            : `${pct}% — Unpacking… starting`,
+        percent: pct,
+      });
+    };
+    const unpackHeartbeat = setInterval(pulseUnpack, 2800);
+    const t0 = Date.now();
+    logFn(`[updater] extract-zip begin → ${extractDir}`);
+    try {
+      await extractZip(zipPath, {
+        dir: extractDir,
+        onEntry: (entry) => {
+          unpackEntryCount += 1;
+          unpackLastName = entry.fileName || "";
+          if (unpackEntryCount <= 4 || unpackEntryCount % 40 === 0) {
+            setImmediate(() => pulseUnpack());
+          }
+        },
+      });
+    } finally {
+      clearInterval(unpackHeartbeat);
+    }
+    pulse({
+      text: `${unpackHi}% — Unpacking… (done)`,
+      percent: unpackHi,
+    });
+    logFn(`[updater] extract-zip done in ${Date.now() - t0}ms (${unpackEntryCount} entries)`);
+  };
+
+  if (process.platform === "win32") {
+    const tarExe = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "tar.exe");
+    if (fs.existsSync(tarExe)) {
+      logUpdater("extract", `try system tar first ${tarExe}`);
+      try {
+        const t0 = Date.now();
+        logFn(`[updater] extracting with ${tarExe}`);
+        let tarPct = unpackLo;
+        const hb = setInterval(() => {
+          tarPct = Math.min(
+            unpackHi,
+            tarPct + Math.max(1, Math.round((unpackHi - unpackLo) / 35)),
+          );
+          pulse({
+            text: `${tarPct}% — Unpacking… (system archiver)`,
+            percent: tarPct,
+          });
+        }, 450);
+        try {
+          await new Promise((resolve, reject) => {
+            const child = spawn(tarExe, ["-xf", zipPath, "-C", extractDir], {
+              windowsHide: true,
+              stdio: ["ignore", "ignore", "pipe"],
+            });
+            logUpdater(
+              "extract",
+              `system tar pid=${child.pid} cmd=tar -xf <zip> -C <extractDir> zip=${path.basename(zipPath)}`,
+            );
+            let errBuf = "";
+            child.stderr?.on("data", (d) => {
+              errBuf += d.toString();
+            });
+            child.on("error", reject);
+            child.on("close", (code) => {
+              logUpdater("extract", `system tar pid=${child.pid} exit=${code}`);
+              if (code === 0) resolve();
+              else reject(new Error(`tar.exe exited ${code}${errBuf ? `: ${errBuf.slice(-500)}` : ""}`));
+            });
+          });
+        } finally {
+          clearInterval(hb);
+        }
+        pulse({
+          text: `${unpackHi}% — Unpacking… (done)`,
+          percent: unpackHi,
+        });
+        logFn(`[updater] system tar done in ${Date.now() - t0}ms`);
+        if (verifyExeBase) {
+          const root = resolveZipAppContentRoot(extractDir, verifyExeBase);
+          if (!root) {
+            logFn(
+              `[updater] system tar left no recognizable main exe (wanted basename like ${verifyExeBase}); clearing extract dir and using extract-zip`,
+            );
+            logUpdater("extract", "tar output verification failed → extract-zip");
+            try {
+              fs.rmSync(extractDir, { recursive: true, force: true });
+            } catch (_) {}
+            fs.mkdirSync(extractDir, { recursive: true });
+            await runExtractZip();
+            return;
+          }
+        }
+        return;
+      } catch (e) {
+        logFn(`[updater] system tar failed (${e?.message || e}); clearing partial extract, retrying with extract-zip`);
+        try {
+          fs.rmSync(extractDir, { recursive: true, force: true });
+        } catch (_) {}
+        fs.mkdirSync(extractDir, { recursive: true });
+      }
+    } else {
+      logUpdater("extract", `tar.exe not present (${tarExe}) → extract-zip`);
+    }
+  } else {
+    logUpdater("extract", "non-Windows → extract-zip only");
+  }
+
+  await runExtractZip();
+}
+
+function sha512Base64OfFile(filePath) {
+  const hash = crypto.createHash("sha512");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("base64");
+}
+
+/**
+ * Portable zip main exe name may differ from the running process (spaced vs compact).
+ * Must match resolveZipAppContentRoot / apply relaunch candidates.
+ */
+function winStagingDirHasMainExe(stagingDir, exeBaseName) {
+  const alt = new Set([exeBaseName, ...brand.allKnownExeBaseNames()]);
+  for (const name of alt) {
+    const p = path.join(stagingDir, name);
+    try {
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) return true;
+    } catch (_) {}
+  }
+  return false;
+}
+
+function resolveZipAppContentRoot(extractDir, exeBaseName) {
+  const direct = path.join(extractDir, exeBaseName);
+  if (fs.existsSync(direct)) return extractDir;
+
+  /** Names to treat as the main app exe (portable zip vs running binary name can differ). */
+  const altNames = new Set([exeBaseName]);
+  if (process.platform === "win32") {
+    for (const n of brand.allKnownExeBaseNames()) altNames.add(n);
+  }
+
+  const matchesMainExe = (fileName) => {
+    const lower = fileName.toLowerCase();
+    for (const n of altNames) {
+      if (lower === n.toLowerCase()) return true;
+    }
+    return false;
+  };
+
+  /** Prefer shallowest match; skip common subtrees that are not the main exe. */
+  const hits = [];
+  const MAX_DEPTH = 6;
+  const walk = (dir, depth) => {
+    if (depth > MAX_DEPTH) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+    for (const ent of entries) {
+      if (!ent.isFile()) continue;
+      if (!/\.exe$/i.test(ent.name)) continue;
+      if (matchesMainExe(ent.name)) hits.push({ root: dir, depth });
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const n = ent.name.toLowerCase();
+      if (n === "resources" || n === "locales") continue;
+      walk(path.join(dir, ent.name), depth + 1);
+    }
+  };
+  walk(extractDir, 0);
+  if (hits.length === 0) return null;
+  hits.sort((a, b) => a.depth - b.depth || a.root.length - b.root.length);
+  return hits[0].root;
+}
+
+/**
+ * After a successful version switch, remove staged builds older than the running app
+ * (and same-version leftovers if the apply script already removed the folder).
+ */
+function scheduleVersionsFolderCleanup() {
+  if (isDev || !app.isPackaged || process.platform !== "win32") return;
+  const current = app.getVersion();
+  setTimeout(() => {
+    try {
+      logUpdater("cleanup", `versions folder sweep (current=${current})`);
+      const sweep = (versionsRoot, label) => {
+        if (!fs.existsSync(versionsRoot)) return;
+        for (const name of fs.readdirSync(versionsRoot)) {
+          const full = path.join(versionsRoot, name);
+          let st;
+          try {
+            st = fs.statSync(full);
+          } catch (_) {
+            continue;
+          }
+          if (!st.isDirectory()) continue;
+          // Staging for builds older than the running app (previous releases).
+          if (compareSemverLike(name, current) < 0) {
+            fs.rmSync(full, { recursive: true, force: true });
+            log(`[updater] removed old staged folder (${label}): ${name}`);
+          }
+        }
+      };
+      sweep(path.join(app.getPath("userData"), "pending-update-versions"), "userData");
+      sweep(path.join(getWindowsAppRootFromExecPath(process.execPath), "versions"), "installDir versions");
+    } catch (e) {
+      log(`[updater] versions cleanup: ${e?.message || e}`);
+    }
+  }, 5000);
+}
+
+const isDev = process.env.NODE_ENV === "development";
+const updaterMenuApi = {
+  checkNow: null,
+};
+const updateDialogState = {
+  window: null,
+  installEnabled: false,
+  ipcBound: false,
+};
+/** When true, skip app.quit() from window closed handlers so quitAndInstall can run first (avoids race + long hang). */
+let suppressQuitForUpdateInstall = false;
+
+/** Real path to icon.ico (prefer asar-unpacked so Windows can load it for the window/taskbar). */
+function resolveAppIconIcoPath() {
+  const candidates = [
+    process.resourcesPath && path.join(process.resourcesPath, "icon.ico"),
+    process.resourcesPath && path.join(process.resourcesPath, "app.asar.unpacked", "assets", "icon.ico"),
+    process.resourcesPath && path.join(process.resourcesPath, "assets", "icon.ico"),
+    app.getAppPath && path.join(app.getAppPath(), "assets", "icon.ico"),
+    path.join(__dirname, "..", "assets", "icon.ico"),
+  ].filter(Boolean);
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) return p;
+    } catch (_) {}
+  }
+  return null;
+}
+
+/** All existing .ico paths (packaged app may have the file only inside app.asar — see nativeImage note below). */
+function collectAppIconIcoCandidates() {
+  const candidates = [
+    process.resourcesPath && path.join(process.resourcesPath, "icon.ico"),
+    process.resourcesPath && path.join(process.resourcesPath, "app.asar.unpacked", "assets", "icon.ico"),
+    process.resourcesPath && path.join(process.resourcesPath, "assets", "icon.ico"),
+    app.getAppPath && path.join(app.getAppPath(), "assets", "icon.ico"),
+    path.join(__dirname, "..", "assets", "icon.ico"),
+  ].filter(Boolean);
+  const out = [];
+  const seen = new Set();
+  for (const p of candidates) {
+    try {
+      if (!p || !fs.existsSync(p)) continue;
+      const n = path.normalize(p);
+      if (seen.has(n)) continue;
+      seen.add(n);
+      out.push(n);
+    } catch (_) {}
+  }
+  return out;
+}
+
+/**
+ * Paths under app.asar\... are real for Node (readFileSync) but not for nativeImage.createFromPath /
+ * app.getFileIcon (shell/GDI cannot read inside the asar archive). Always prefer readFileSync + createFromBuffer for .ico.
+ */
+function nativeImageFromIcoFilePath(p) {
+  if (!p) return null;
+  try {
+    if (!fs.existsSync(p)) return null;
+    const buf = fs.readFileSync(p);
+    const img = nativeImage.createFromBuffer(buf);
+    return img.isEmpty() ? null : img;
+  } catch (_) {
+    return null;
+  }
+}
+
+function nativeImageFromAppIcon() {
+  const paths = collectAppIconIcoCandidates();
+  for (const p of paths) {
+    const img = nativeImageFromIcoFilePath(p);
+    if (img) return img;
+  }
+  for (const p of paths) {
+    try {
+      const inAsarArchive = p.includes("app.asar") && !p.includes("app.asar.unpacked");
+      if (inAsarArchive) continue;
+      const img = nativeImage.createFromPath(p);
+      if (!img.isEmpty()) return img;
+    } catch (_) {}
+  }
+  if (process.platform === "win32" && app.isPackaged) {
+    try {
+      const img = nativeImage.createFromPath(process.execPath);
+      if (!img.isEmpty()) return img;
+    } catch (_) {}
+  }
+  return undefined;
+}
+
+function resolveNotificationIcon() {
+  const candidates = [
+    resolveAppIconIcoPath(),
+    process.resourcesPath && path.join(process.resourcesPath, "icon.ico"),
+    path.join(process.resourcesPath || "", "assets", "icon.ico"),
+    path.join(app.getAppPath(), "assets", "icon.ico"),
+    app.getPath("exe"),
+  ].filter(Boolean);
+  return candidates.find((p) => {
+    try {
+      return p && fs.existsSync(p);
+    } catch (_) {
+      return false;
+    }
+  });
+}
+
+// One running instance on Windows: avoids two Electron processes during NSIS upgrade.
+if (!isDev && process.platform === "win32") {
+  const gotLock = app.requestSingleInstanceLock();
+  if (!gotLock) {
+    app.quit();
+    process.exit(0);
+  }
+  app.on("second-instance", () => {
+    const win = BrowserWindow.getAllWindows()[0];
+    if (win) {
+      if (win.isMinimized()) win.restore();
+      win.focus();
+    }
+  });
+}
+
+function setupAutoUpdater() {
+  if (isDev || !app.isPackaged) return;
+  try {
+    const { autoUpdater } = require("electron-updater");
+    // Without this, checkForUpdates reads resources/app-update.yml (embedded by electron-builder, absent in Forge installs).
+    autoUpdater.setFeedURL({
+      provider: "github",
+      owner: UPDATE_GITHUB_OWNER,
+      repo: UPDATE_GITHUB_REPO,
+    });
+    let manualCheckInProgress = false;
+    let manualDownloadInProgress = false;
+    let updaterCheckRetrying = false;
+
+    const checkForUpdatesWithRetry = async (attempts = 4) => {
+      let lastErr;
+      for (let i = 0; i < attempts; i++) {
+        try {
+          logUpdater("check", `checkForUpdates attempt ${i + 1}/${attempts}`);
+          const result = await autoUpdater.checkForUpdates();
+          const u = result?.updateInfo ?? result;
+          logUpdater(
+            "check",
+            `checkForUpdates ok version=${u?.version ?? "?"} release=${u?.releaseDate ?? "?"} ` +
+              `downloadURL=${u?.downloadUrl ?? u?.path ?? "?"}`,
+          );
+          return result;
+        } catch (e) {
+          lastErr = e;
+          logUpdater("check", `checkForUpdates error attempt ${i + 1}: ${e?.message || e}`);
+          if (!isTransientGithubUpdateError(e) || i === attempts - 1) throw e;
+          const delayMs = 1500 * 2 ** i;
+          log(
+            `[updater] transient GitHub/update error (${i + 1}/${attempts}), retry in ${delayMs}ms: ${e?.message || e}`,
+          );
+          await sleep(delayMs);
+        }
+      }
+      throw lastErr;
+    };
+    const currentVersion = app.getVersion();
+    const applyUserLogPath = path.join(app.getPath("userData"), "hsp-update-apply.log");
+
+    /** Prefer transferred/total when known; Windows often keeps percent at 0 until late. */
+    const progressPercent = (progress) => {
+      if (!progress || typeof progress !== "object") return 0;
+      const total = progress.total;
+      const transferred = progress.transferred ?? 0;
+      if (typeof total === "number" && total > 0) {
+        return Math.max(0, Math.min(100, (100 * transferred) / total));
+      }
+      const p = progress.percent;
+      if (typeof p === "number" && !Number.isNaN(p)) {
+        if (p > 0 && p <= 1) {
+          return Math.max(0, Math.min(100, p * 100));
+        }
+        return Math.max(0, Math.min(100, p));
+      }
+      return 0;
+    };
+
+    // Single content height: always leave room for the activity log so it is not clipped when progress/actions hide.
+    const UPDATER_LOG_PANEL = 108;
+    const UPDATER_DIALOG_H = 198 + UPDATER_LOG_PANEL;
+
+    const sendUpdaterLogInitToDialog = () => {
+      const w = updateDialogState.window;
+      if (!w || w.isDestroyed()) return;
+      try {
+        w.webContents.send("updater-log-init", updaterDialogLogBuffer.slice());
+      } catch (_) {}
+    };
+
+    updaterLogToDialog = (line) => {
+      const w = updateDialogState.window;
+      if (!w || w.isDestroyed()) return;
+      const wc = w.webContents;
+      const send = () => {
+        try {
+          wc.send("updater-log", line);
+        } catch (_) {}
+      };
+      if (wc.isLoading()) wc.once("did-finish-load", send);
+      else send();
+    };
+
+    /** Set after syncZipReadyUi / stagingHasMainExe; enables main-process installEnabled when opening the dialog. */
+    let refreshUpdaterDialogIfStagedReady = () => {};
+
+    const openOrFocusUpdateDialog = () => {
+      if (updateDialogState.window && !updateDialogState.window.isDestroyed()) {
+        updateDialogState.window.show();
+        updateDialogState.window.focus();
+        sendUpdaterLogInitToDialog();
+        refreshUpdaterDialogIfStagedReady();
+        return;
+      }
+      updateDialogState.window = new BrowserWindow({
+        width: 420,
+        height: UPDATER_DIALOG_H,
+        useContentSize: true,
+        title: "Updater",
+        resizable: false,
+        minimizable: false,
+        maximizable: false,
+        show: false,
+        autoHideMenuBar: true,
+        // No parent: a child window + showMessageBox(modal to child) often leaves alerts behind the main frame.
+        modal: false,
+        webPreferences: { nodeIntegration: true, contextIsolation: false, sandbox: false },
+      });
+      const updaterHtmlPath = path.join(__dirname, "updater-dialog.html");
+      if (!fs.existsSync(updaterHtmlPath)) {
+        log(`[updater] FATAL: updater-dialog.html missing at ${updaterHtmlPath}`);
+      }
+      updateDialogState.window.loadFile(updaterHtmlPath);
+      updateDialogState.window.webContents.once("did-finish-load", () => {
+        const w = updateDialogState.window;
+        if (!w || w.isDestroyed()) return;
+        const wc = w.webContents;
+        const cvText = `Current version: ${currentVersion}`;
+        wc.executeJavaScript(`document.getElementById('cv').textContent = ${JSON.stringify(cvText)}`).catch(() => {});
+        sendUpdaterLogInitToDialog();
+        refreshUpdaterDialogIfStagedReady();
+      });
+      updateDialogState.window.once("ready-to-show", () => {
+        if (updateDialogState.window && !updateDialogState.window.isDestroyed()) updateDialogState.window.show();
+      });
+      updateDialogState.window.on("closed", () => {
+        updateDialogState.window = null;
+      });
+    };
+    /**
+     * @param {object} opts
+     * @param {string} opts.text
+     * @param {number} [opts.percent]
+     * @param {boolean} [opts.showProgress]
+     * @param {boolean} [opts.showActions] Update button row (when false: version + text only; dismiss via title bar X)
+     * @param {boolean} [opts.installEnabled]
+     */
+    const updateDialogUi = ({ text, percent = 0, showProgress = false, showActions = false, installEnabled = false }) => {
+      if (!updateDialogState.window || updateDialogState.window.isDestroyed()) return;
+      const safe = Math.max(0, Math.min(100, Math.round(Number(percent) || 0)));
+      updateDialogState.installEnabled = Boolean(installEnabled);
+      try {
+        updateDialogState.window.setSize(420, UPDATER_DIALOG_H);
+      } catch (_) {}
+      const payload = {
+        text,
+        percent: safe,
+        showProgress,
+        showActions,
+        installEnabled: Boolean(installEnabled),
+      };
+      const wc = updateDialogState.window.webContents;
+      const send = () => {
+        try {
+          wc.send("updater-ui", payload);
+        } catch (e) {
+          log(`[updater] updateDialogUi send: ${e?.message || e}`);
+        }
+      };
+      // IPC survives rapid download-progress; executeJavaScript could drop or race with load state.
+      if (wc.isLoading()) {
+        wc.once("did-finish-load", send);
+      } else {
+        send();
+      }
+    };
+    const closeUpdateDialog = () => {
+      if (updateDialogState.window && !updateDialogState.window.isDestroyed()) updateDialogState.window.close();
+      updateDialogState.window = null;
+      updateDialogState.installEnabled = false;
+    };
+
+    /** Prefer main/browser window so native dialogs are not hidden behind a frame owned as child. */
+    const focusMainWindowForDialog = () => {
+      const all = BrowserWindow.getAllWindows().filter((w) => !w.isDestroyed());
+      const mainLike = all.find((w) => w !== updateDialogState.window) ?? all[0];
+      try {
+        if (mainLike) {
+          if (mainLike.isMinimized()) mainLike.restore();
+          mainLike.focus();
+        }
+      } catch (_) {}
+      return mainLike ?? null;
+    };
+
+    if (!updateDialogState.ipcBound) {
+      updateDialogState.ipcBound = true;
+      // invoke/handle is more reliable than send for click→main from file:// updater pages on some Electron builds.
+      ipcMain.handle("updater-install-now", () => {
+        logUpdater("ipc", "updater-install-now (invoke)");
+        try {
+          requestInstallNow();
+          return { ok: true };
+        } catch (e) {
+          const m = e?.message || String(e);
+          log(`[updater] requestInstallNow threw: ${m}`);
+          return { ok: false, err: m };
+        }
+      });
+      ipcMain.on("updater-install-click", () => {
+        logUpdater("ipc", "updater-install-click received (legacy send)");
+        requestInstallNow();
+      });
+      ipcMain.on("updater-renderer-error", (_e, msg) => {
+        log(`[updater] renderer: ${typeof msg === "string" ? msg : String(msg)}`);
+      });
+    }
+    const logUpdaterChannel = (m) => {
+      const body = `[updater] ${typeof m === "string" ? m : JSON.stringify(m)}`;
+      log(body);
+      appendUpdaterDialogLogLine(body);
+    };
+    autoUpdater.logger = {
+      info: logUpdaterChannel,
+      warn: logUpdaterChannel,
+      error: logUpdaterChannel,
+      debug: logUpdaterChannel,
+    };
+
+    const useWinVersionsSidecar = process.platform === "win32";
+    let zipPrepareInFlight = false;
+    let zipReadyVersion = null;
+    let zipStagingContentPath = null;
+
+    autoUpdater.autoDownload = !useWinVersionsSidecar;
+    // Windows: never install a downloaded NSIS on quit — in-app Update uses staged zip + robocopy only.
+    autoUpdater.autoInstallOnAppQuit = !useWinVersionsSidecar;
+    autoUpdater.autoRunAppAfterInstall = true;
+    log(
+      `[updater] initialized (github, winVersions=${useWinVersionsSidecar}, autoDownload=${autoUpdater.autoDownload})`,
+    );
+    logUpdater(
+      "init",
+      `repo=${UPDATE_GITHUB_OWNER}/${UPDATE_GITHUB_REPO} app=${currentVersion} platform=${process.platform} ` +
+        `winZipSidecar=${useWinVersionsSidecar} autoDownload=${autoUpdater.autoDownload} autoInstallOnQuit=${autoUpdater.autoInstallOnAppQuit}`,
+    );
+
+    let installRequested = false;
+
+    const syncZipReadyUi = (v) => {
+      if (!updateDialogState.window || updateDialogState.window.isDestroyed()) return;
+      updateDialogUi({
+        text: `Update ${v} is ready. Click "Update with reload" to close and open the new version.`,
+        percent: 100,
+        showProgress: true,
+        showActions: true,
+        installEnabled: true,
+      });
+    };
+
+    const stagingHasMainExe = (stagingDir) => {
+      const exeBase = path.basename(process.execPath);
+      if (process.platform === "win32") {
+        return winStagingDirHasMainExe(stagingDir, exeBase);
+      }
+      const direct = path.join(stagingDir, exeBase);
+      if (fs.existsSync(direct)) return true;
+      try {
+        const want = exeBase.toLowerCase();
+        return fs.readdirSync(stagingDir).some((n) => n.toLowerCase() === want);
+      } catch (_) {
+        return false;
+      }
+    };
+
+    refreshUpdaterDialogIfStagedReady = () => {
+      if (!useWinVersionsSidecar || !zipReadyVersion || !zipStagingContentPath) return;
+      if (!stagingHasMainExe(zipStagingContentPath)) return;
+      syncZipReadyUi(zipReadyVersion);
+    };
+
+    const getVersionsStagingRoot = () => path.join(app.getPath("userData"), "pending-update-versions");
+
+    const restoreVersionsStagingFromDisk = () => {
+      const root = getVersionsStagingRoot();
+      logUpdater("staging", `restore scan root=${root}`);
+      if (!fs.existsSync(root)) {
+        logUpdater("staging", "restore skip (root missing)");
+        return;
+      }
+      const exeBase = path.basename(process.execPath);
+      let bestVer = null;
+      let bestContent = null;
+      for (const name of fs.readdirSync(root)) {
+        const full = path.join(root, name);
+        let st;
+        try {
+          st = fs.statSync(full);
+        } catch (_) {
+          continue;
+        }
+        if (!st.isDirectory()) continue;
+        if (compareSemverLike(name, currentVersion) <= 0) continue;
+        const extractDir = path.join(full, "extract");
+        if (!fs.existsSync(extractDir)) continue;
+        const contentRoot = resolveZipAppContentRoot(extractDir, exeBase);
+        if (!contentRoot || !stagingHasMainExe(contentRoot)) continue;
+        if (!bestVer || compareSemverLike(name, bestVer) > 0) {
+          bestVer = name;
+          bestContent = contentRoot;
+        }
+      }
+      if (bestVer && bestContent) {
+        zipReadyVersion = bestVer;
+        zipStagingContentPath = bestContent;
+        log(`[updater] restored staging from disk: ${bestVer} -> ${bestContent}`);
+        logUpdater("staging", `restore picked version=${bestVer} contentRoot=${bestContent}`);
+      } else {
+        logUpdater("staging", "restore no valid staged build found");
+      }
+    };
+
+    restoreVersionsStagingFromDisk();
+
+    const tryBeginVersionsPrepare = async (info, opts) => {
+      const remoteV = info?.version;
+      logUpdater(
+        "prepare",
+        `tryBeginVersionsPrepare enter remote=${remoteV || "?"} feed=${safeJson(info)} opts=${safeJson(opts)}`,
+      );
+      if (!useWinVersionsSidecar) {
+        logUpdater("prepare", "skip (not Windows zip sidecar mode)");
+        return;
+      }
+      if (!remoteV || compareSemverLike(remoteV, currentVersion) <= 0) {
+        logUpdater("prepare", `skip (no remote or not newer remote=${remoteV} current=${currentVersion})`);
+        return;
+      }
+      if (zipPrepareInFlight) {
+        logUpdater("prepare", "skip (zipPrepareInFlight)");
+        return;
+      }
+      const exeBase = path.basename(process.execPath);
+      if (zipReadyVersion === remoteV && zipStagingContentPath && stagingHasMainExe(zipStagingContentPath)) {
+        logUpdater("prepare", `skip (already staged ${remoteV})`);
+        if (!updateDialogState.window || updateDialogState.window.isDestroyed()) {
+          openOrFocusUpdateDialog();
+        }
+        syncZipReadyUi(remoteV);
+        manualDownloadInProgress = false;
+        return;
+      }
+      zipPrepareInFlight = true;
+      logUpdater("prepare", `start pipeline → ${remoteV} exeBase=${exeBase}`);
+      const uiManual = Boolean(opts?.uiManual);
+      const uiActive =
+        uiManual || (updateDialogState.window && !updateDialogState.window.isDestroyed());
+      /** Overall 0–100: 0–81 download, 81–100 verify/unpack/finalize (single bar, monotonic). */
+      let prepareProgressCeiling = 0;
+      const pushUi = (partial) => {
+        if (!uiActive) return;
+        const raw = partial.percent;
+        const n = typeof raw === "number" && !Number.isNaN(raw) ? raw : Number(raw);
+        const next =
+          typeof n === "number" && !Number.isNaN(n)
+            ? Math.max(prepareProgressCeiling, Math.round(Math.max(0, Math.min(100, n))))
+            : prepareProgressCeiling;
+        prepareProgressCeiling = next;
+        updateDialogUi({
+          showProgress: true,
+          showActions: true,
+          installEnabled: false,
+          percent: 0,
+          text: "",
+          ...partial,
+          percent: next,
+        });
+      };
+      let versionsPrepareOk = false;
+      try {
+        const meta = await resolveWindowsZipSidecarMeta((u) => net.fetch(u), currentVersion);
+        if (meta.version !== remoteV) {
+          log(`[updater] sidecar version ${meta.version} vs feed ${remoteV} (using sidecar manifest)`);
+        }
+        log(`[updater] sidecar source: ${meta.source} → ${meta.fileName}`);
+
+        // One bar: 81% for download, 19% for verify + unpack + finalize (overall 0–100).
+        const PREP_PCT_DOWNLOAD_MAX = 81;
+        const PREP_PCT_VERIFY_END = 87;
+        const PREP_UNPACK_LO = 87;
+        const PREP_UNPACK_HI = 99;
+        pushUi({ text: "0% — Downloading update…", percent: 0 });
+
+        const versionsRoot = getVersionsStagingRoot();
+        const versionDir = path.join(versionsRoot, meta.version);
+        const extractDir = path.join(versionDir, "extract");
+        logUpdater("prepare", `paths versionDir=${versionDir} extractDir=${extractDir}`);
+        try {
+          fs.rmSync(versionDir, { recursive: true, force: true });
+        } catch (_) {}
+        fs.mkdirSync(extractDir, { recursive: true });
+
+        const zipPath = path.join(versionDir, meta.fileName);
+        const primaryZipUrl = githubLatestAssetUrl(meta.fileName);
+        logUpdater("prepare", `download primaryURL asset=${meta.fileName}`);
+        let lastZipPush = 0;
+        const onZipProgress = (received, total) => {
+          const now = Date.now();
+          const hasTotal = typeof total === "number" && total > 0;
+          if (hasTotal && now - lastZipPush < 100 && received < total) return;
+          if (!hasTotal && lastZipPush > 0 && now - lastZipPush < 150) return;
+          lastZipPush = now;
+          const mb = received / (1024 * 1024);
+          let overall;
+          if (hasTotal) {
+            const dl = received / total;
+            overall = Math.min(
+              PREP_PCT_DOWNLOAD_MAX,
+              Math.round(PREP_PCT_DOWNLOAD_MAX * dl),
+            );
+          } else {
+            overall = Math.min(
+              PREP_PCT_DOWNLOAD_MAX - 1,
+              Math.round(PREP_PCT_DOWNLOAD_MAX * (1 - Math.exp(-mb / 55))),
+            );
+          }
+          pushUi({
+            text: hasTotal
+              ? `${overall}% — Downloading update…`
+              : `${overall}% — Downloading update… (~${mb.toFixed(1)} MB, size unknown)`,
+            percent: overall,
+          });
+        };
+        try {
+          await downloadToFile((u) => net.fetch(u), primaryZipUrl, zipPath, onZipProgress);
+        } catch (e) {
+          const msg = String(e?.message || e);
+          if (!/404/.test(msg)) throw e;
+          const altUrl = await fetchPortableZipBrowserUrlFromGitHubApi(
+            (u, init) => net.fetch(u, init),
+            meta.version,
+            meta.fileName,
+          );
+          if (!altUrl) throw e;
+          log(`[updater] primary zip 404; downloading from GitHub API URL`);
+          logUpdater("prepare", `download fallbackURL (API) → ${altUrl.length > 160 ? `${altUrl.slice(0, 160)}…` : altUrl}`);
+          await downloadToFile((u) => net.fetch(u), altUrl, zipPath, onZipProgress);
+        }
+
+        pushUi({ text: `${PREP_PCT_DOWNLOAD_MAX}% — Download finished`, percent: PREP_PCT_DOWNLOAD_MAX });
+
+        let verifyHb = null;
+        try {
+          let vPct = PREP_PCT_DOWNLOAD_MAX + 1;
+          verifyHb = setInterval(() => {
+            vPct = Math.min(PREP_PCT_VERIFY_END - 1, vPct + 1);
+            pushUi({ text: `${vPct}% — Verifying update…`, percent: vPct });
+          }, 350);
+          pushUi({ text: `${PREP_PCT_DOWNLOAD_MAX + 1}% — Verifying update…`, percent: PREP_PCT_DOWNLOAD_MAX + 1 });
+
+          if (meta.sha512) {
+            logUpdater("verify", "sha512 check (zip-latest)");
+            const hash = sha512Base64OfFile(zipPath);
+            if (hash !== meta.sha512) throw new Error("zip sha512 mismatch");
+            logUpdater("verify", "sha512 ok");
+          } else {
+            log(
+              "[updater] no sha512 manifest for zip (optional: add zip-latest.yml from cleanup for integrity check)",
+            );
+          }
+        } finally {
+          if (verifyHb) clearInterval(verifyHb);
+        }
+        pushUi({ text: `${PREP_PCT_VERIFY_END}% — Verifying update…`, percent: PREP_PCT_VERIFY_END });
+
+        pushUi({
+          text: `${PREP_UNPACK_LO}% — Unpacking update…`,
+          percent: PREP_UNPACK_LO,
+        });
+
+        await extractPortableZipToDir(zipPath, extractDir, log, pushUi, PREP_UNPACK_LO, PREP_UNPACK_HI, {
+          verifyExeBase: exeBase,
+        });
+
+        pushUi({ text: "99% — Finalizing…", percent: 99 });
+
+        const contentRoot = resolveZipAppContentRoot(extractDir, exeBase);
+        if (!contentRoot) throw new Error("extracted update has no app executable");
+        logUpdater("prepare", `resolveZipAppContentRoot ok contentRoot=${contentRoot}`);
+
+        try {
+          fs.unlinkSync(zipPath);
+        } catch (_) {}
+        logUpdater("prepare", `removed cached zip ${zipPath}`);
+
+        zipStagingContentPath = contentRoot;
+        zipReadyVersion = meta.version;
+        manualDownloadInProgress = false;
+        log(`[updater] staged update at ${contentRoot}`);
+        logUpdater("prepare", `COMPLETE readyVersion=${meta.version} staging=${contentRoot}`);
+        // syncZipReadyUi needs an open dialog; background checks used uiActive=false and would skip UI.
+        if (!uiActive) {
+          openOrFocusUpdateDialog();
+        }
+        syncZipReadyUi(meta.version);
+        if (!uiActive && process.platform === "win32" && Notification.isSupported()) {
+          try {
+            new Notification({
+              title: brand.productDisplayName,
+              body: `Update ${meta.version} is ready. Open Updates → Check for updates.`,
+            }).show();
+          } catch (_) {}
+        }
+        versionsPrepareOk = true;
+      } catch (e) {
+        const errMsg = e?.message || e;
+        const errStack = typeof e?.stack === "string" ? e.stack : "";
+        logUpdater("prepare", `FAILED ${errMsg}`);
+        log(`[updater] versions sidecar failed: ${errMsg}`);
+        if (errStack) log(`[updater] versions sidecar stack: ${errStack.split("\n").slice(0, 8).join(" | ")}`);
+        log(
+          `[updater] Ensure latest GitHub release includes latest.yml, ${WIN_PORTABLE_ZIP_PREFIX}<version>.zip (zip build), and optionally zip-latest.yml from cleanup for sha512.`,
+        );
+        zipStagingContentPath = null;
+        zipReadyVersion = null;
+        manualDownloadInProgress = false;
+        const hint =
+          `Update prepare failed: ${e?.message || String(e)}. ` +
+          `Publish the Windows zip (${WIN_PORTABLE_ZIP_PREFIX}<version>.zip) on https://github.com/${UPDATE_GITHUB_OWNER}/${UPDATE_GITHUB_REPO}/releases/latest — latest.yml is enough; add zip-latest.yml from cleanup for checksum verification.`;
+        if (uiActive) {
+          openOrFocusUpdateDialog();
+          updateDialogUi({
+            text: hint,
+            percent: 0,
+            showProgress: false,
+            showActions: true,
+            installEnabled: false,
+          });
+        }
+      } finally {
+        zipPrepareInFlight = false;
+        logUpdater(
+          "prepare",
+          versionsPrepareOk
+            ? "zipPrepareInFlight=false (success)"
+            : "zipPrepareInFlight=false (incomplete — look for prepare FAILED above)",
+        );
+      }
+    };
+
+    const applyVersionsStagedUpdate = () => {
+      const execPath = process.execPath;
+      const installDir = path.dirname(execPath);
+      const exeName = path.basename(execPath);
+      const appRoot = getWindowsAppRootFromExecPath(execPath);
+      const useVersionedLayout =
+        process.platform === "win32" && path.basename(installDir).toLowerCase() === "current";
+      const applyLogPath = applyUserLogPath;
+      logUpdater(
+        "apply",
+        `applyVersionsStagedUpdate installDir=${installDir} appRoot=${appRoot} versioned=${useVersionedLayout} exe=${exeName} staging=${zipStagingContentPath} version=${zipReadyVersion} pid=${process.pid}`,
+      );
+      logUpdater("apply", `helper log (next run): ${applyLogPath}`);
+      const planPath = path.join(app.getPath("temp"), `hsp-update-plan-${Date.now()}.json`);
+      const stagingVersionDirToRemove = zipReadyVersion
+        ? path.join(getVersionsStagingRoot(), zipReadyVersion)
+        : null;
+      const targetVersionDir =
+        useVersionedLayout && zipReadyVersion ? path.join(appRoot, "versions", zipReadyVersion) : null;
+      const currentLink = useVersionedLayout ? path.join(appRoot, "current") : null;
+      const plan = {
+        stagingContent: zipStagingContentPath,
+        installDir,
+        exeName,
+        waitPid: process.pid,
+        appliedVersion: zipReadyVersion,
+        stagingVersionDirToRemove,
+        logPath: applyLogPath,
+        useVersionedLayout,
+        appRoot,
+        targetVersionDir,
+        currentLink,
+      };
+      fs.writeFileSync(planPath, JSON.stringify(plan), "utf8");
+      logUpdater("apply", `wrote plan ${planPath} ${safeJson(plan)}`);
+
+      const ps1Path = path.join(app.getPath("temp"), `hsp-apply-versions-${Date.now()}.ps1`);
+      /**
+       * Apply script uses no fixed sleeps: wait for parent via Wait-Process, kill stragglers, copy, relaunch.
+       * Robocopy: /R:0 /W:0 (no retry delay), /MT:64 /J (throughput on SSD/large files), staging tree delete is async after relaunch.
+       */
+      const ps1Body = [
+        "param([string]$PlanPath, [string]$LogPath)",
+        '$ErrorActionPreference = "Stop"',
+        "if (-not $PlanPath) { $PlanPath = $env:HSP_UPDATE_PLAN }",
+        "if (-not $LogPath) { $LogPath = $env:HSP_UPDATE_LOG }",
+        "try {",
+        "  $trace = Join-Path $env:TEMP 'hsp-apply-trace.log'",
+        "  $ts = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ')",
+        "  Add-Content -LiteralPath $trace -Encoding UTF8 -Value (\"[$ts] ps1 -File started pid=$PID\")",
+        "  if ($LogPath) {",
+        "    Add-Content -LiteralPath $LogPath -Encoding UTF8 -Value (\"[$ts] [ps1] bootstrap (before plan JSON)\")",
+        "  }",
+        "} catch {}",
+        'if (-not $PlanPath) { throw "Plan path missing (pass -PlanPath to this script or set HSP_UPDATE_PLAN)" }',
+        "try {",
+        "  $plan = Get-Content -LiteralPath $PlanPath -Encoding UTF8 -Raw | ConvertFrom-Json",
+        "} catch {",
+        "  $ts = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ')",
+        "  $m = \"FATAL: plan JSON read/parse failed: \" + $_.Exception.Message",
+        "  if ($LogPath) { try { Add-Content -LiteralPath $LogPath -Encoding UTF8 -Value (\"[$ts] \" + $m) } catch {} }",
+        "  throw",
+        "}",
+        "$LogFile = $plan.logPath",
+        "function Write-ApplyLog([string]$m) {",
+        "  $ts = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ')",
+        '  Add-Content -LiteralPath $LogFile -Value ("[$ts] " + $m) -Encoding UTF8',
+        "}",
+        "try {",
+        '  Write-ApplyLog "apply start waitPid=$($plan.waitPid) exe=$($plan.exeName) versioned=$($plan.useVersionedLayout)"',
+        "  $pp = Get-Process -Id $plan.waitPid -ErrorAction SilentlyContinue",
+        "  if ($pp) { Wait-Process -InputObject $pp -ErrorAction SilentlyContinue }",
+        '  Write-ApplyLog "parent process ended (Wait-Process)"',
+        "  $stem = [System.IO.Path]::GetFileNameWithoutExtension($plan.exeName)",
+        "  $killNames = @($stem, ($stem + \" Helper\"), ($stem + \" Helper (GPU)\"), ($stem + \" Helper (Renderer)\"), ($stem + \" Helper (Plugin)\"))",
+        "  foreach ($kn in $killNames) {",
+        "    try { Get-Process -Name $kn -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue } catch {}",
+        "  }",
+        '  Write-ApplyLog "stopped helpers by process name (fast; avoids Win32_Process scan of every OS process)"',
+        "  $src = $plan.stagingContent",
+        "  if ($plan.useVersionedLayout) {",
+        "    $dst = $plan.targetVersionDir",
+        "    $null = New-Item -ItemType Directory -Force -LiteralPath $dst",
+        '    Write-ApplyLog "mirror target (versioned): $dst"',
+        "  } else {",
+        "    $dst = $plan.installDir",
+        '    Write-ApplyLog "mirror target (flat): $dst"',
+        "  }",
+        '  Write-ApplyLog "copy staging -> dest (robocopy; versioned uses /MIR, flat uses non-destructive /E)"',
+        "  $robocopyExe = Join-Path $env:SystemRoot 'System32\\robocopy.exe'",
+        "  if ($plan.useVersionedLayout) {",
+        "    & $robocopyExe $src $dst /MIR /E /MT:64 /J /R:0 /W:0 /XD versions /NFL /NDL /NJH /NJS",
+        "  } else {",
+        "    # Flat install path: do not purge destination. Keep installer-managed files (e.g. Uninstall *.exe).",
+        "    & $robocopyExe $src $dst /E /MT:64 /J /R:0 /W:0 /XD versions /NFL /NDL /NJH /NJS",
+        "  }",
+        "  $mirrorExit = $LASTEXITCODE",
+        "  Write-ApplyLog (\"robocopy mirror exit=\" + $mirrorExit)",
+        "  if ($mirrorExit -gt 7) {",
+        '    Write-ApplyLog "robocopy mirror failed; Copy-Item full tree fallback"',
+        "    Copy-Item -Path (Join-Path $src '*') -Destination $dst -Recurse -Force",
+        '    Write-ApplyLog "Copy-Item fallback done"',
+        "  }",
+        "  if ($plan.useVersionedLayout) {",
+        "    if (Test-Path -LiteralPath $plan.currentLink) {",
+        "      Remove-Item -LiteralPath $plan.currentLink -Force",
+        '      Write-ApplyLog ("removed old current junction/link")',
+        "    }",
+        "    $null = New-Item -ItemType Junction -Path $plan.currentLink -Target $plan.targetVersionDir",
+        '    Write-ApplyLog ("junction: $($plan.currentLink) -> $($plan.targetVersionDir)")',
+        "  }",
+        "  $workDir = if ($plan.useVersionedLayout) { $plan.currentLink } else { $dst }",
+        `  $candidates = @($plan.exeName, ${brand.allKnownExeBaseNames().map((n) => `"${n}"`).join(", ")}) | Select-Object -Unique`,
+        "  $exePath = $null",
+        "  foreach ($c in $candidates) {",
+        "    $tryExe = Join-Path $workDir $c",
+        "    if (Test-Path -LiteralPath $tryExe) { $exePath = $tryExe; Write-ApplyLog (\"picked exe: \" + $c); break }",
+        "  }",
+        "  if (-not $exePath) { throw (\"main exe missing after apply under \" + $workDir + \" (tried \" + ($candidates -join \", \") + \")\") }",
+        '  Write-ApplyLog ("relaunch " + $exePath + " (wd=" + $workDir + ")")',
+        "  Start-Process -FilePath $exePath -WorkingDirectory $workDir",
+        '  Write-ApplyLog "Start-Process returned (GUI may take a moment)"',
+        "  if ($plan.stagingVersionDirToRemove -and (Test-Path -LiteralPath $plan.stagingVersionDirToRemove)) {",
+        "    $sdRm = $plan.stagingVersionDirToRemove",
+        "    $rdArg = 'rd /s /q \"' + $sdRm.Replace('\"', '\"\"') + '\"'",
+        "    Start-Process -FilePath $env:ComSpec -ArgumentList '/c', $rdArg -WindowStyle Hidden",
+        '    Write-ApplyLog "scheduled async staging dir cleanup (after relaunch)"',
+        "  }",
+        "  try { Remove-Item -LiteralPath $PlanPath -Force } catch {}",
+        '  Write-ApplyLog "apply done"',
+        "} catch {",
+        '  $err = "FATAL: " + $_.Exception.Message',
+        "  if ($LogFile) { try { Write-ApplyLog $err } catch {} }",
+        "  elseif ($plan -and $plan.logPath) { try { Add-Content -LiteralPath $plan.logPath -Value (\"[\" + (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.fffZ') + \"] \" + $err) -Encoding UTF8 } catch {} }",
+        "  try { Remove-Item -LiteralPath $PlanPath -Force } catch {}",
+        "  exit 1",
+        "}",
+        "",
+      ].join("\r\n");
+      // UTF-8 BOM so Windows PowerShell 5.1 parses multi-byte literals reliably in .ps1 files.
+      fs.writeFileSync(ps1Path, `\uFEFF${ps1Body}`, "utf8");
+      logUpdater(
+        "apply",
+        `wrote ps1 ${ps1Path} (Wait-Process; Stop-Process by name; robocopy mirror + Copy-Item fallback)`,
+      );
+
+      try {
+        fs.appendFileSync(
+          applyLogPath,
+          `[${new Date().toISOString()}] [main] spawning apply via spawnSync Start-Process inner -File ps1=${ps1Path} plan=${planPath} log=${applyLogPath} trace=%TEMP%\\hsp-apply-trace.log\n`,
+          "utf8",
+        );
+      } catch (_) {}
+
+      const systemRoot = process.env.SystemRoot || process.env.SYSTEMROOT || "C:\\Windows";
+      const psExe = path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+      // Async spawn (cmd or PowerShell) can lose the race: app.quit() runs before the apply script starts.
+      // Run a one-shot outer PowerShell that Start-Process'es the real script synchronously (spawnSync) so
+      // the inner process exists before we return and quit. Pass -PlanPath/-LogPath on argv (no env required).
+      const psSq = (s) => `'${String(s).replace(/'/g, "''")}'`;
+      const argList = [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        ps1Path,
+        "-PlanPath",
+        planPath,
+        "-LogPath",
+        applyLogPath,
+      ]
+        .map(psSq)
+        .join(",");
+      const startCmd = `Start-Process -WindowStyle Hidden -FilePath ${psSq(psExe)} -ArgumentList ${argList}`;
+
+      let syncResult;
+      try {
+        syncResult = spawnSync(
+          psExe,
+          ["-NoProfile", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-Command", startCmd],
+          {
+            env: {
+              ...process.env,
+              HSP_UPDATE_PLAN: planPath,
+              HSP_UPDATE_LOG: applyLogPath,
+            },
+            windowsHide: true,
+            timeout: 20000,
+            encoding: "utf8",
+            maxBuffer: 1024 * 1024,
+          },
+        );
+      } catch (e) {
+        const msg = e?.message || String(e);
+        logUpdater("apply", `spawnSync launcher threw: ${msg}`);
+        try {
+          fs.appendFileSync(applyLogPath, `[${new Date().toISOString()}] [main] spawnSync launcher threw: ${msg}\n`, "utf8");
+        } catch (_) {}
+        throw e;
+      }
+
+      if (syncResult.error) {
+        const msg = syncResult.error.message || String(syncResult.error);
+        logUpdater("apply", `spawnSync launcher error: ${msg}`);
+        try {
+          fs.appendFileSync(applyLogPath, `[${new Date().toISOString()}] [main] spawnSync launcher error: ${msg}\n`, "utf8");
+        } catch (_) {}
+      }
+      const combinedOut = `${syncResult.stderr || ""}${syncResult.stdout || ""}`.trim();
+      const exitCode = syncResult.status;
+      if (exitCode !== 0) {
+        logUpdater(
+          "apply",
+          `spawnSync Start-Process launcher exit=${exitCode} output=${combinedOut.slice(0, 2000)}`,
+        );
+        try {
+          fs.appendFileSync(
+            applyLogPath,
+            `[${new Date().toISOString()}] [main] spawnSync launcher exit=${exitCode} ${combinedOut.slice(0, 1500)}\n`,
+            "utf8",
+          );
+        } catch (_) {}
+      } else {
+        logUpdater("apply", "spawnSync Start-Process launcher ok (inner apply.ps1 should be running)");
+      }
+      if (syncResult.error || exitCode !== 0) {
+        throw new Error(
+          `apply launcher failed (exit=${exitCode}): ${syncResult.error?.message || combinedOut.slice(0, 600) || "unknown"}`,
+        );
+      }
+    };
+
+    /** True when versions/ staging is ready; preferred over NSIS even if installer also downloaded. */
+    const canApplyVersionsStaging = () => {
+      if (!useWinVersionsSidecar || !zipStagingContentPath || !zipReadyVersion) return false;
+      if (compareSemverLike(zipReadyVersion, currentVersion) <= 0) return false;
+      return stagingHasMainExe(zipStagingContentPath);
+    };
+
+    const requestInstallNow = () => {
+      try {
+        fs.appendFileSync(
+          applyUserLogPath,
+          `[${new Date().toISOString()}] [main] requestInstallNow (Update with reload clicked)\n`,
+          "utf8",
+        );
+      } catch (_) {}
+
+      installRequested = true;
+      log("[updater] user accepted update install");
+      logUpdater("ipc", "requestInstallNow (Update with reload)");
+
+      suppressQuitForUpdateInstall = true;
+
+      const useVersionsApply = canApplyVersionsStaging();
+      const semverNewer =
+        zipReadyVersion && compareSemverLike(zipReadyVersion, currentVersion) > 0;
+      const exeOk =
+        Boolean(zipStagingContentPath) &&
+        stagingHasMainExe(zipStagingContentPath);
+      logUpdater(
+        "ipc",
+        `requestInstallNow useVersionsApply=${useVersionsApply} zipReady=${zipReadyVersion} path=${zipStagingContentPath}`,
+      );
+
+      if (useVersionsApply) {
+        closeUpdateDialog();
+        try {
+          applyVersionsStagedUpdate();
+        } catch (e) {
+          log(`[updater] applyVersionsStagedUpdate failed: ${e?.message || e}`);
+          suppressQuitForUpdateInstall = false;
+          const mw = focusMainWindowForDialog();
+          const errOpts = {
+            type: "error",
+            title: brand.productDisplayName,
+            message: `Could not apply update: ${e?.message || String(e)}`,
+            buttons: ["OK"],
+          };
+          void (mw ? dialog.showMessageBox(mw, errOpts) : dialog.showMessageBox(errOpts));
+          return;
+        }
+        for (const win of BrowserWindow.getAllWindows()) {
+          try {
+            win.removeAllListeners("close");
+            win.destroy();
+          } catch (_) {}
+        }
+        logUpdater("ipc", "requestInstallNow app.quit after staging apply spawn");
+        app.quit();
+        return;
+      }
+
+      // Windows packaged: only the staged-zip path — never launch the NSIS wizard from this button.
+      if (useWinVersionsSidecar) {
+        suppressQuitForUpdateInstall = false;
+        logUpdater("ipc", "requestInstallNow blocked: no staged zip build ready");
+        log(
+          `[updater] Update click ignored: no staged build (ready=${zipReadyVersion} path=${zipStagingContentPath})`,
+        );
+        try {
+          fs.appendFileSync(
+            applyUserLogPath,
+            `[${new Date().toISOString()}] [main] blocked: cannot apply zip staging ` +
+              `(readyVer=${zipReadyVersion} stagingPath=${zipStagingContentPath} ` +
+              `semverNewer=${Boolean(semverNewer)} exeOk=${Boolean(exeOk)} current=${currentVersion})\n`,
+            "utf8",
+          );
+        } catch (_) {}
+        const boxOpts = {
+          type: "info",
+          title: brand.productDisplayName,
+          message:
+            `The quick update is not ready yet. Keep the app open until download and unpack finish, or ensure the latest GitHub release includes zip-latest.yml and ${WIN_PORTABLE_ZIP_PREFIX}<version>.zip from your Windows build (cleanup folder).`,
+          buttons: ["OK"],
+        };
+        try {
+          if (updateDialogState.window && !updateDialogState.window.isDestroyed()) {
+            updateDialogState.window.hide();
+          }
+        } catch (_) {}
+        const mw = focusMainWindowForDialog();
+        void (mw ? dialog.showMessageBox(mw, boxOpts) : dialog.showMessageBox(boxOpts));
+        return;
+      }
+
+      closeUpdateDialog();
+
+      try {
+        if (process.platform === "win32" && Notification.isSupported()) {
+          const n = new Notification({
+            title: brand.productDisplayName,
+            body: "Installing update… The app will restart when finished.",
+          });
+          n.show();
+        }
+      } catch (_) {}
+
+      for (const win of BrowserWindow.getAllWindows()) {
+        try {
+          win.removeAllListeners("close");
+          win.destroy();
+        } catch (_) {}
+      }
+
+      try {
+        log("[updater] invoking quitAndInstall(isSilent=false, isForceRunAfter=true)");
+        autoUpdater.quitAndInstall(false, true);
+      } catch (e) {
+        log(`quitAndInstall failed: ${e?.message || e}`);
+        suppressQuitForUpdateInstall = false;
+        app.quit();
+      }
+    };
+
+    autoUpdater.on("update-downloaded", () => {
+      log("[updater] update-downloaded");
+      logUpdater("event", "update-downloaded (NSIS installer file ready on disk)");
+      manualDownloadInProgress = false;
+      // Windows uses zip sidecar only; ignore NSIS installer download for in-app UX.
+      if (useWinVersionsSidecar) {
+        log("[updater] update-downloaded: ignored on Windows (NSIS not used for Update button)");
+        logUpdater("event", "update-downloaded ignored (Windows uses zip sidecar only)");
+        return;
+      }
+      openOrFocusUpdateDialog();
+      updateDialogUi({
+        text: 'Update is ready. Click "Update with reload".',
+        percent: 100,
+        showProgress: true,
+        showActions: true,
+        installEnabled: true,
+      });
+    });
+
+    autoUpdater.on("checking-for-update", () => {
+      log("[updater] checking-for-update");
+      logUpdater("event", `checking-for-update manual=${manualCheckInProgress}`);
+      if (manualCheckInProgress) {
+        log("[updater] manual check started");
+      }
+    });
+
+    autoUpdater.on("update-available", (info) => {
+      log(`[updater] update-available version=${info?.version || "unknown"}`);
+      logUpdater("event", `update-available ${safeJson({ version: info?.version, path: info?.path })}`);
+      const wasManual = manualCheckInProgress;
+      if (manualCheckInProgress) {
+        manualCheckInProgress = false;
+        manualDownloadInProgress = true;
+        openOrFocusUpdateDialog();
+        updateDialogUi({
+          text: useWinVersionsSidecar
+            ? `Downloading and preparing version ${info?.version || "new"}…`
+            : `Downloading version ${info?.version || "new"}...`,
+          percent: 0,
+          showProgress: true,
+          showActions: true,
+          installEnabled: false,
+        });
+      }
+      if (useWinVersionsSidecar) {
+        void tryBeginVersionsPrepare(info, { uiManual: wasManual });
+      }
+    });
+
+    autoUpdater.on("update-not-available", () => {
+      log("[updater] update-not-available");
+      logUpdater("event", `update-not-available current=${currentVersion}`);
+      if (manualCheckInProgress) {
+        manualCheckInProgress = false;
+        manualDownloadInProgress = false;
+        openOrFocusUpdateDialog();
+        updateDialogUi({
+          text: "You are already on the latest version.",
+          percent: 0,
+          showProgress: false,
+          showActions: true,
+          installEnabled: false,
+        });
+      }
+    });
+    let downloadProgressLoggedSample = false;
+    autoUpdater.on("download-progress", (progress) => {
+      if (useWinVersionsSidecar) return;
+      if (!updateDialogState.window || updateDialogState.window.isDestroyed()) return;
+      if (!downloadProgressLoggedSample) {
+        downloadProgressLoggedSample = true;
+        try {
+          log(`[updater] download-progress sample: ${JSON.stringify(progress)}`);
+        } catch (_) {}
+      }
+      const pct = progressPercent(progress);
+      updateDialogUi({
+        text: `Downloading update... ${Math.round(pct)}%`,
+        percent: pct,
+        showProgress: true,
+        showActions: true,
+        installEnabled: false,
+      });
+    });
+
+    autoUpdater.on("error", (err) => {
+      log(`[updater] error: ${err?.message || String(err)}`);
+      if (updaterCheckRetrying && isTransientGithubUpdateError(err)) {
+        logUpdater("event", `error suppressed (retry) ${err?.message || err}`);
+        return;
+      }
+      logUpdater("event", `error manualCheck=${manualCheckInProgress} download=${manualDownloadInProgress} ${err?.message || err}`);
+      if (manualCheckInProgress || manualDownloadInProgress) {
+        manualCheckInProgress = false;
+        manualDownloadInProgress = false;
+        openOrFocusUpdateDialog();
+        updateDialogUi({
+          text: `Update check failed: ${err?.message || String(err)}`,
+          percent: 0,
+          showProgress: false,
+          showActions: false,
+          installEnabled: false,
+        });
+      }
+    });
+
+    updaterMenuApi.checkNow = async () => {
+      try {
+        log("[updater] manual check requested from menu");
+        logUpdater("ipc", "checkNow from menu");
+        downloadProgressLoggedSample = false;
+        if (
+          useWinVersionsSidecar &&
+          zipReadyVersion &&
+          zipStagingContentPath &&
+          stagingHasMainExe(zipStagingContentPath)
+        ) {
+          logUpdater("ipc", `checkNow short-circuit already staged ${zipReadyVersion}`);
+          openOrFocusUpdateDialog();
+          syncZipReadyUi(zipReadyVersion);
+          return;
+        }
+        manualCheckInProgress = true;
+        manualDownloadInProgress = false;
+        openOrFocusUpdateDialog();
+        updateDialogUi({
+          text: "Checking for updates...",
+          percent: 0,
+          showProgress: false,
+          showActions: false,
+          installEnabled: false,
+        });
+        updaterCheckRetrying = true;
+        try {
+          await checkForUpdatesWithRetry();
+        } finally {
+          updaterCheckRetrying = false;
+        }
+      } catch (e) {
+        manualCheckInProgress = false;
+        manualDownloadInProgress = false;
+        openOrFocusUpdateDialog();
+        updateDialogUi({
+          text: `Update check failed: ${e?.message || String(e)}`,
+          percent: 0,
+          showProgress: false,
+          showActions: false,
+          installEnabled: false,
+        });
+      }
+    };
+
+    app.on("before-quit", () => {
+      if (installRequested) {
+        log("[updater] before-quit for update install");
+      }
+    });
+    autoUpdater.on("before-quit-for-update", () => {
+      log("[updater] before-quit-for-update emitted");
+    });
+
+    let lastCheckAt = 0;
+    const markAndCheck = () => {
+      lastCheckAt = Date.now();
+      log("[updater] scheduled checkForUpdates()");
+      logUpdater("schedule", "periodic/startup checkForUpdates");
+      void (async () => {
+        updaterCheckRetrying = true;
+        try {
+          await checkForUpdatesWithRetry();
+        } catch (e) {
+          log(`[updater] checkForUpdates failed after retries: ${e?.message || e}`);
+          logUpdater("schedule", `check failed after retries: ${e?.message || e}`);
+        } finally {
+          updaterCheckRetrying = false;
+        }
+      })();
+    };
+
+    // 1) On startup (each app launch)
+    markAndCheck();
+
+    // 2) While running: every 1 minute (temporary aggressive polling)
+    const periodicMs = 1 * 60 * 1000;
+    setInterval(markAndCheck, periodicMs);
+
+    // 3) When user brings the app back to foreground (throttled: at most once per 30 min)
+    const minFocusGapMs = 30 * 60 * 1000;
+    app.on("browser-window-focus", () => {
+      if (Date.now() - lastCheckAt < minFocusGapMs) return;
+      log("[updater] check (window focus)");
+      logUpdater("schedule", "window focus → checkForUpdates");
+      markAndCheck();
+    });
+
+    scheduleVersionsFolderCleanup();
+  } catch (e) {
+    log(`autoUpdater failed: ${e?.message || e}`);
+  }
+}
+
+function setupAppMenu() {
+  const template = [
+    {
+      label: "File",
+      submenu: [{ role: "quit", label: "Exit" }],
+    },
+    {
+      label: "Edit",
+      submenu: [
+        { role: "undo" },
+        { role: "redo" },
+        { type: "separator" },
+        { role: "cut" },
+        { role: "copy" },
+        { role: "paste" },
+        { role: "selectAll" },
+      ],
+    },
+    {
+      label: "View",
+      submenu: [{ role: "reload" }, { role: "togglefullscreen" }],
+    },
+    {
+      label: "Updates",
+      submenu: [
+        {
+          label: "Check for updates now",
+          click: () => {
+            if (typeof updaterMenuApi.checkNow === "function") {
+              void updaterMenuApi.checkNow();
+            } else {
+              void dialog.showMessageBox({
+                type: "info",
+                title: "Updates unavailable",
+                message: "Updater is not available in development mode.",
+              });
+            }
+          },
+        },
+      ],
+    },
+  ];
+  const menu = Menu.buildFromTemplate(template);
+  Menu.setApplicationMenu(menu);
+}
+
+protocol.registerSchemesAsPrivileged([
+  { scheme: "app", privileges: { standard: true, supportFetchAPI: true } },
+]);
+
+function log(msg) {
+  try {
+    const logPath = path.join(app.getPath("userData"), "main.log");
+    const line = `[${new Date().toISOString()}] ${msg}`;
+    fs.appendFileSync(logPath, line + "\n");
+    console.error(line);
+  } catch (_) {}
+}
+
+/** Windows: resolve before the first show(); omit `icon` if empty so the shell can fall back to the exe. */
+async function resolveBrowserWindowIcon() {
+  const fromFile = nativeImageFromAppIcon();
+  if (fromFile && !fromFile.isEmpty()) return fromFile;
+  if (process.platform !== "win32" || !app.isPackaged) return fromFile;
+
+  const thumbSize = { width: 256, height: 256 };
+  const inAsarOnly = (p) => p.includes("app.asar") && !p.includes("app.asar.unpacked");
+
+  // Shell-backed extraction: often works for the packaged .exe (embedded rcedit icon) when ICO buffer decode fails.
+  try {
+    if (fs.existsSync(process.execPath)) {
+      const img = await nativeImage.createThumbnailFromPath(process.execPath, thumbSize);
+      if (img && !img.isEmpty()) return img;
+    }
+  } catch (e) {
+    try {
+      log(`createThumbnailFromPath(exe): ${e?.message || e}`);
+    } catch (_) {}
+  }
+
+  for (const p of collectAppIconIcoCandidates()) {
+    if (!p || !fs.existsSync(p) || inAsarOnly(p)) continue;
+    try {
+      const img = await nativeImage.createThumbnailFromPath(p, thumbSize);
+      if (img && !img.isEmpty()) return img;
+    } catch (e) {
+      try {
+        log(`createThumbnailFromPath(${p}): ${e?.message || e}`);
+      } catch (_) {}
+    }
+  }
+
+  const shellPaths = [process.execPath, ...collectAppIconIcoCandidates()].filter((p) => {
+    if (!p || !fs.existsSync(p)) return false;
+    return !inAsarOnly(p);
+  });
+  for (const p of shellPaths) {
+    for (const size of ["large", "normal", "small"]) {
+      try {
+        const img = await app.getFileIcon(p, { size });
+        if (!img.isEmpty()) return img;
+      } catch (e) {
+        try {
+          log(`getFileIcon(${p}, ${size}): ${e?.message || e}`);
+        } catch (_) {}
+      }
+    }
+  }
+  return fromFile;
+}
+
+const WINDOWS_USERDATA_ICON = "window-icon.ico";
+
+/**
+ * Absolute path to a real .ico on disk for Windows shell APIs. Prefer loose/unpacked files; if the only
+ * copy is inside app.asar, copy bytes with readFileSync/writeFileSync (copyFileSync can fail for asar).
+ */
+function ensureWindowsIcoFileOnDiskSync() {
+  if (process.platform !== "win32" || !app.isPackaged) return null;
+  const inAsarOnly = (p) => p.includes("app.asar") && !p.includes("app.asar.unpacked");
+  const dest = path.join(app.getPath("userData"), WINDOWS_USERDATA_ICON);
+  for (const p of collectAppIconIcoCandidates()) {
+    if (!p || !fs.existsSync(p) || !/\.ico$/i.test(p)) continue;
+    if (!inAsarOnly(p)) return path.resolve(p);
+  }
+  for (const p of collectAppIconIcoCandidates()) {
+    if (!p || !fs.existsSync(p) || !/\.ico$/i.test(p)) continue;
+    try {
+      const buf = fs.readFileSync(p);
+      if (buf.length < 32) continue;
+      fs.writeFileSync(dest, buf);
+      if (fs.existsSync(dest) && fs.statSync(dest).size > 0) return path.resolve(dest);
+    } catch (e) {
+      try {
+        log(`ensureWindowsIcoFileOnDiskSync: ${e?.message || e}`);
+      } catch (_) {}
+    }
+  }
+  return null;
+}
+
+/**
+ * Set `HSP_DEBUG_ICON=1` before starting the app to append full `[icon:debug]` lines to userData/main.log
+ * (candidate paths, setAppDetails). Deploy builds always log `[icon] probe(always): ...` without this flag.
+ */
+function iconDebugEnabled() {
+  const v = process.env.HSP_DEBUG_ICON;
+  return v === "1" || v === "true" || v === "yes";
+}
+
+function logIconDebug(line) {
+  if (!iconDebugEnabled()) return;
+  log(`[icon:debug] ${line}`);
+}
+
+function icoPathStatLine(p) {
+  if (!p) return "(null)";
+  try {
+    if (!fs.existsSync(p)) return `${p} (missing)`;
+    return `${p} (size=${fs.statSync(p).size})`;
+  } catch (e) {
+    return `${p} (stat err: ${e?.message || e})`;
+  }
+}
+
+function describeWindowIconForLog(w) {
+  if (w == null) return "none";
+  if (typeof w === "string") return `path:${w}`;
+  try {
+    return `NativeImage isEmpty=${w.isEmpty ? w.isEmpty() : "?"}`;
+  } catch (_) {
+    return "NativeImage";
+  }
+}
+
+/** Always logged on packaged Windows: Chromium decode of chosen .ico and of the .exe (deploy diagnostics). */
+function logWindowsIconProbeAlways(windowIcon) {
+  if (process.platform !== "win32" || !app.isPackaged) return;
+  if (typeof windowIcon === "string") {
+    try {
+      if (!fs.existsSync(windowIcon)) {
+        log(`[icon] probe(always): chosen path missing: ${windowIcon}`);
+      } else {
+        const buf = fs.readFileSync(windowIcon);
+        const niPath = nativeImage.createFromPath(windowIcon);
+        const niBuf = nativeImage.createFromBuffer(buf);
+        log(
+          `[icon] probe(always): ico createFromPath isEmpty=${niPath.isEmpty()} createFromBuffer isEmpty=${niBuf.isEmpty()} bytes=${buf.length}`,
+        );
+      }
+    } catch (e) {
+      log(`[icon] probe(always): ico ${e?.message || e}`);
+    }
+  } else {
+    log(`[icon] probe(always): chosen=${describeWindowIconForLog(windowIcon)}`);
+  }
+  try {
+    if (fs.existsSync(process.execPath)) {
+      const niExe = nativeImage.createFromPath(process.execPath);
+      log(`[icon] probe(always): execPath createFromPath isEmpty=${niExe.isEmpty()}`);
+    }
+  } catch (e) {
+    log(`[icon] probe(always): execPath ${e?.message || e}`);
+  }
+}
+
+/**
+ * Path for setAppDetails (taskbar / Jump List): prefer the .exe when Chromium can decode an embedded
+ * icon — Windows shell uses the exe for the taskbar more reliably than a loose .ico in that case.
+ * Otherwise use resources\\icon.ico (see embed-windows-exe-icon.cjs + afterSign).
+ */
+function resolveWindowsTaskbarDetailsIconPath() {
+  if (process.platform !== "win32" || !app.isPackaged) return null;
+  const exe = process.execPath;
+  const ico = ensureWindowsIcoFileOnDiskSync();
+  try {
+    if (fs.existsSync(exe)) {
+      const niFromExe = nativeImage.createFromPath(exe);
+      if (!niFromExe.isEmpty()) return exe;
+    }
+  } catch (_) {}
+  if (ico && fs.existsSync(ico)) return ico;
+  return fs.existsSync(exe) ? exe : ico;
+}
+
+/** Logs once per main window: summary + probe(always); full dump when HSP_DEBUG_ICON=1. */
+function logWindowsIconEnvironment(windowIcon) {
+  if (process.platform !== "win32" || !app.isPackaged) return;
+  log(`[icon] win32 packaged: ${describeWindowIconForLog(windowIcon)} resourcesPath=${process.resourcesPath}`);
+  logWindowsIconProbeAlways(windowIcon);
+  if (!iconDebugEnabled()) return;
+  logIconDebug(`__dirname=${__dirname}`);
+  logIconDebug(`app.getAppPath=${app.getAppPath()}`);
+  logIconDebug(`execPath=${process.execPath}`);
+  const raw = [
+    process.resourcesPath && path.join(process.resourcesPath, "icon.ico"),
+    process.resourcesPath && path.join(process.resourcesPath, "app.asar.unpacked", "assets", "icon.ico"),
+    process.resourcesPath && path.join(process.resourcesPath, "assets", "icon.ico"),
+    app.getAppPath && path.join(app.getAppPath(), "assets", "icon.ico"),
+    path.join(__dirname, "..", "assets", "icon.ico"),
+  ].filter(Boolean);
+  for (const p of raw) {
+    logIconDebug(`candidate ${icoPathStatLine(p)}`);
+  }
+  logIconDebug(`existing only: ${collectAppIconIcoCandidates().join(" | ") || "(none)"}`);
+  const disk = ensureWindowsIcoFileOnDiskSync();
+  logIconDebug(`ensureWindowsIcoFileOnDiskSync => ${disk || "null"}`);
+}
+
+/** NativeImage for the main window: prefer createFromPath on real disk .ico; buffer decode as fallback. */
+function windowsPackagedWindowNativeIcon() {
+  const p = ensureWindowsIcoFileOnDiskSync();
+  if (!p) return null;
+  try {
+    let img = nativeImage.createFromPath(p);
+    if (!img.isEmpty()) return img;
+    img = nativeImage.createFromBuffer(fs.readFileSync(p));
+    return img.isEmpty() ? null : img;
+  } catch (e) {
+    try {
+      log(`windowsPackagedWindowNativeIcon: ${e?.message || e}`);
+    } catch (_) {}
+    return null;
+  }
+}
+
+async function createWindow() {
+  const appPath = app.getAppPath();
+  const distPath = path.join(appPath, "dist");
+  const indexHtml = path.join(distPath, "index.html");
+
+  if (!isDev && !fs.existsSync(indexHtml)) {
+    log(`ERROR: index.html not found at ${indexHtml}`);
+    log(`appPath=${appPath}`);
+    return;
+  }
+
+  /** `string` = absolute .ico path (preferred on Windows packaged builds; Chromium loads reliably). Else NativeImage. */
+  let windowIcon;
+  if (process.platform === "win32" && app.isPackaged) {
+    const icoPath = ensureWindowsIcoFileOnDiskSync();
+    if (icoPath) {
+      windowIcon = icoPath;
+    } else {
+      const native = windowsPackagedWindowNativeIcon();
+      if (native && !native.isEmpty()) {
+        windowIcon = native;
+      } else {
+        const img = await resolveBrowserWindowIcon();
+        windowIcon = img && !img.isEmpty() ? img : undefined;
+      }
+    }
+  } else {
+    const img = await resolveBrowserWindowIcon();
+    windowIcon = img && !img.isEmpty() ? img : undefined;
+  }
+
+  if (process.platform === "win32" && app.isPackaged && !windowIcon) {
+    try {
+      log(
+        `warn: window icon unresolved; resourcesPath=${process.resourcesPath} ico=${collectAppIconIcoCandidates().join(" | ")} exe=${process.execPath}`,
+      );
+    } catch (_) {}
+  }
+
+  try {
+    logWindowsIconEnvironment(windowIcon);
+  } catch (e) {
+    log(`[icon] logWindowsIconEnvironment failed: ${e?.message || e}`);
+  }
+
+  const applyWindowIcon = () => {
+    if (!windowIcon || mainWindow.isDestroyed()) return;
+    try {
+      mainWindow.setIcon(windowIcon);
+      logIconDebug(`setIcon applied type=${typeof windowIcon}`);
+    } catch (e) {
+      log(`[icon] setIcon failed: ${e?.message || e}`);
+    }
+  };
+
+  // NSIS close-app uses PRODUCT_NAME (package.json → build.productName). The window title must
+  // match that string, not a URL — otherwise the installer cannot find/close the running app.
+  // Keep in sync with app/package.json "build.productName".
+  const windowTitle = isDev ? "http://www.hyperlinks.space/" : brand.productDisplayName;
+
+  const mainWindow = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    title: windowTitle,
+    ...(windowIcon ? { icon: windowIcon } : {}),
+    // Match app dark background (theme.ts); reduces flash and helps menu/client seam blend on Windows.
+    backgroundColor: "#111111",
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+      spellcheck: false,
+    },
+    show: false,
+  });
+
+  try {
+    mainWindow.webContents.setIgnoreMenuShortcuts(false);
+  } catch (_) {}
+
+  mainWindow.once("ready-to-show", () => {
+    // Win32: ties this HWND to AppUserModelID + icon for the taskbar button (see Electron BrowserWindow.setAppDetails).
+    if (process.platform === "win32" && fs.existsSync(process.execPath)) {
+      try {
+        const detailsIcon = resolveWindowsTaskbarDetailsIconPath();
+        if (detailsIcon && fs.existsSync(detailsIcon)) {
+          mainWindow.setAppDetails({
+            appId: WIN_APP_USER_MODEL_ID,
+            appIconPath: detailsIcon,
+            appIconIndex: 0,
+          });
+          logIconDebug(`setAppDetails ok appIconPath=${detailsIcon}`);
+        } else {
+          logIconDebug(`setAppDetails skipped (missing path) detailsIcon=${detailsIcon || "null"}`);
+        }
+      } catch (e) {
+        try {
+          log(`setAppDetails: ${e?.message || e}`);
+        } catch (_) {}
+      }
+    }
+    applyWindowIcon();
+    try {
+      mainWindow.maximize();
+      mainWindow.show();
+    } catch (_) {}
+  });
+
+  mainWindow.webContents.once("did-finish-load", applyWindowIcon);
+
+  mainWindow.webContents.on("page-title-updated", (e) => {
+    e.preventDefault();
+    mainWindow.setTitle(windowTitle);
+  });
+
+  mainWindow.webContents.on("did-fail-load", (_event, code, errMsg, url) => {
+    log(`did-fail-load: code=${code} ${errMsg} ${url}`);
+  });
+
+  mainWindow.webContents.on("did-start-loading", (_, url) => {
+    if (!isDev && url && (url.endsWith("/index.html") || url.includes("/index.html"))) {
+      const root = url.replace(/\/index\.html.*$/, "/");
+      if (root !== url) {
+        mainWindow.loadURL(root);
+      }
+    }
+  });
+
+  if (isDev) {
+    mainWindow.loadURL("http://localhost:8081");
+    mainWindow.webContents.openDevTools();
+  } else {
+    mainWindow.loadURL("app://./");
+  }
+
+  mainWindow.on("closed", () => {
+    if (suppressQuitForUpdateInstall) return;
+    app.quit();
+  });
+}
+
+process.on("uncaughtException", (err) => {
+  try {
+    log(`uncaughtException: ${err.message}\n${err.stack}`);
+  } catch (_) {}
+});
+
+app.whenReady().then(() => {
+  if (process.platform === "win32") {
+    // Dark native chrome (title bar / menu area) so the OS-drawn separator under the menu reads closer to #111111.
+    nativeTheme.themeSource = "dark";
+  }
+  setupAppMenu();
+  if (!isDev) {
+    const appPath = app.getAppPath();
+    const distPath = path.join(appPath, "dist");
+    protocol.handle("app", (request) => {
+      let urlPath = request.url.slice("app://".length).replace(/^\.?\//, "") || "index.html";
+      const filePath = path.join(distPath, urlPath);
+      const resolved = path.normalize(filePath);
+      if (!resolved.startsWith(path.normalize(distPath)) || !fs.existsSync(resolved)) {
+        return new Response("Not Found", { status: 404 });
+      }
+      return net.fetch(pathToFileURL(resolved).toString());
+    });
+  }
+  createWindow().catch((e) => {
+    try {
+      log(`createWindow: ${e?.message || e}`);
+    } catch (_) {}
+  });
+  setupAutoUpdater();
+});
+
+app.on("window-all-closed", () => {
+  if (suppressQuitForUpdateInstall) return;
+  app.quit();
+});
+
+app.on("activate", () => {
+  if (BrowserWindow.getAllWindows().length === 0) {
+    createWindow().catch((e) => {
+      try {
+        log(`createWindow (activate): ${e?.message || e}`);
+      } catch (_) {}
+    });
+  }
+});