@hienlh/ppm 0.20.10 → 0.21.0

package/src/web/hooks/use-terminal.ts

@@ -10,6 +10,7 @@ import { resolveTheme as resolvePpmTheme } from "@/theme/resolve-theme";
 import { getCurrentAppliedTheme, THEME_CHANGE_EVENT } from "@/theme/apply-theme";
 import { onHostResize } from "@/components/floating-window/pip/pip-resize-signal";
 import type { PpmTheme } from "@/theme/types";
+import { TERMINAL_FONT_FAMILY } from "@/lib/editor-font";
 
 /** Current active PpmTheme → xterm ITheme (prefers the live applied theme). */
 function currentXtermTheme(): ITheme {
@@ -347,9 +348,25 @@ export function useTerminal(
       fontSize: 13,
       scrollback: 50000,
       // Explicit terminal-grade stack: the WebGL renderer builds its glyph
-      // atlas via ctx.font and cannot resolve CSS var() values.
-      fontFamily: "Consolas, 'Cascadia Mono', Menlo, 'DejaVu Sans Mono', 'Courier New', monospace",
+      // atlas via ctx.font and cannot resolve CSS var() values. Its own stack
+      // rather than the editor's, because a prompt needs the powerline and
+      // devicon glyphs only a patched Nerd Font has.
+      fontFamily: TERMINAL_FONT_FAMILY,
       theme: currentXtermTheme(),
+      // The two ends of an ANSI palette collapse into the background, and a
+      // prompt cannot know which way round the terminal is. On PPM's light
+      // themes `white` is #e9edf5 against a #f3f7ff background — 1.09:1, i.e.
+      // invisible — and on the dark ones `black` is 1.10:1. oh-my-posh writes
+      // its second prompt line in plain SGR 37, which is correct on the dark
+      // terminal it was designed for and disappeared entirely here.
+      //
+      // Repainting those palette slots is the wrong fix: the same `white` is
+      // also the text *on* a coloured powerline segment, where it is right.
+      // xterm adjusts the foreground per cell against that cell's real
+      // background instead, which leaves every segment untouched and only
+      // rescues the text that had nothing behind it. 4.5 is WCAG AA, and the
+      // value VS Code ships as its own default.
+      minimumContrastRatio: 4.5,
     });
 
     const fitAddon = new FitAddon();
@@ -382,6 +399,23 @@ export function useTerminal(
     termRef.current = term;
     fitRef.current = fitAddon;
 
+    // A webfont that is still in flight is not in the stack yet: xterm measures
+    // the cell and bakes the glyph atlas from ctx.font at open(), so a terminal
+    // opened during the first paint would keep whatever fallback was resolved
+    // then, for the rest of the session. Re-measuring once the face lands is
+    // the whole fix; the atlas is rebuilt from the new metrics by fit().
+    let fontsSettled = false;
+    document.fonts.ready.then(() => {
+      if (fontsSettled || termRef.current !== term) return;
+      fontsSettled = true;
+      try {
+        term.options.fontFamily = TERMINAL_FONT_FAMILY;
+        fitAddon.fit();
+      } catch {
+        // A terminal disposed between the promise and here; nothing to redraw.
+      }
+    });
+
     // Wire input to WS + track command boundaries
     term.onData((data) => {
       // When user presses Enter, mark next row as command output start
@@ -452,8 +486,32 @@ export function useTerminal(
     window.addEventListener(THEME_CHANGE_EVENT, onThemeChange);
     const unsubTheme = () => window.removeEventListener(THEME_CHANGE_EVENT, onThemeChange);
 
+    // The icon faces are fetched on demand — a `unicode-range` face is not
+    // requested until something lays out a character inside it, which for a
+    // prompt's Private Use Area glyphs is the first time the prompt is drawn.
+    // That is long after `document.fonts.ready` above has resolved, so the
+    // one-shot re-measure cannot see it.
+    //
+    // And nothing else redraws: measured in Chromium, a canvas `fillText` does
+    // start the fetch, but the glyph it painted is tofu and the canvas never
+    // repaints itself — ink stayed identical after the face finished loading
+    // and only tripled on a redraw. So the atlas the WebGL and canvas renderers
+    // baked has to be thrown away by hand, or the prompt is tofu for the rest
+    // of the session with the right font sitting loaded in the page.
+    const onFontLoaded = () => {
+      if (termRef.current !== term) return;
+      try {
+        term.clearTextureAtlas();
+        term.refresh(0, term.rows - 1);
+      } catch {
+        // Disposed between the event and here; nothing left to redraw.
+      }
+    };
+    document.fonts.addEventListener("loadingdone", onFontLoaded);
+
     return () => {
       unsubTheme();
+      document.fonts.removeEventListener("loadingdone", onFontLoaded);
       unsubHostResize();
       if (fitTimer) clearTimeout(fitTimer);
       resizeObserver.disconnect();

package/src/web/hooks/use-touch-tab-drag.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 import { setDragging, clearDragging, type DragPayload } from "./use-tab-drag";
 import { usePanelStore } from "@/stores/panel-store";
 import { findPanelPosition, maxColumns, MAX_ROWS } from "@/stores/panel-utils";
@@ -186,5 +186,21 @@ export function useTouchTabDrag(panelId: string) {
     if (timer.current) { clearTimeout(timer.current); timer.current = null; }
   }, []);
 
-  return { handleTouchStart, handleTouchMove, handleTouchEnd };
+  /**
+   * The *pre-arm* timer's cancel. There is already a document-level
+   * `touchcancel` above, but it belongs to a drag that has begun and is only
+   * registered once `beginDrag` has run — it says nothing about the 200ms
+   * window before that. And that window is exactly where the problem is: a
+   * scroll fires `touchcancel` and then delivers no further `touchmove` or
+   * `touchend` to the tab, so the `MOVE_PX` tolerance never sees the moves it
+   * would have measured and the drag begins under a finger that was scrolling.
+   */
+  const handleTouchCancel = useCallback(() => {
+    if (timer.current) { clearTimeout(timer.current); timer.current = null; }
+    origin.current = null;
+  }, []);
+
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+
+  return { handleTouchStart, handleTouchMove, handleTouchEnd, handleTouchCancel };
 }

package/src/web/hooks/use-url-sync.ts

@@ -25,6 +25,20 @@ const VALID_TAB_TYPES: TabType[] = [
 // Parse URL → state
 // ---------------------------------------------------------------------------
 
+/**
+ * `decodeURIComponent` throws `URIError` on a percent that is not an escape —
+ * a hand-edited address, a truncated share link, a `%` in a branch name that
+ * was never encoded. Thrown from here it reaches the root and unmounts the app,
+ * so a mistyped URL would blank the page instead of just not resolving to a tab.
+ */
+function decodePathSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
 /**
  * Parse the current URL to extract project name and tab info.
  * Format: /project/{name}/{tabType}/{...identifier}
@@ -37,7 +51,7 @@ export function parseUrlState(): UrlState {
   const match = path.match(/^\/project\/([^/]+)(?:\/([^/]+)(\/.*)?)?/);
   if (!match) return { projectName: null, tabType: null, tabIdentifier: null, openChat };
 
-  const projectName = decodeURIComponent(match[1]!);
+  const projectName = decodePathSegment(match[1]!);
   const rawType = match[2] ?? null;
   const rawIdentifier = match[3] ? match[3].slice(1) : null; // strip leading /
 

package/src/web/index.html

@@ -48,6 +48,80 @@
     <div id="portal" style="position: fixed; left: 0; top: 0; z-index: 9999;" /></div>
     <div id="root"></div>
     <script type="module" src="./main.tsx"></script>
+    <!-- Boot watchdog: the last resort, and the only code that can still run.
+         The entry's module graph is ~39 separately-hashed chunks, and if any one
+         of them 404s — an upgrade replaced dist/web, or a stale index.html is
+         still naming last week's hashes — the entry module never executes. No
+         React, no error boundary, no listener: `#root` stays empty and the page
+         shows nothing but the body's background. That is the white screen, and
+         nothing bundled can report it, because nothing bundled ran. Hence
+         inline, dependency-free, and gated on the flag main.tsx sets: a boundary
+         inside React already covers the case where the entry *did* run. -->
+    <script>
+      (function () {
+        var KEY = "ppm:boot-retry";
+        // Every cache, not just this app's: the stale index.html that named the
+        // missing hashes comes from the service worker's *precache*, which is
+        // workbox's to name. It repopulates itself on the next activation.
+        function purge() {
+          if (!window.caches) return Promise.resolve();
+          return caches
+            .keys()
+            .then(function (names) { return Promise.all(names.map(function (n) { return caches.delete(n); })); })
+            .catch(function () {});
+        }
+        function panic() {
+          // The wrapper carries its own background: if the stylesheet was one of
+          // the chunks that went missing, `var(--bg)` on <body> resolves to
+          // nothing and dark-mode text would be white on white.
+          document.getElementById("root").innerHTML =
+            '<div style="min-height:100dvh;display:flex;align-items:center;justify-content:center;padding:24px;' +
+            'background:var(--bg-solid,#0a0e17);color:var(--text,#eaeefb);font:16px/1.5 system-ui,sans-serif">' +
+            '<div role="alert" style="width:100%;max-width:440px;background:var(--panel,#141820);' +
+            'border:1px solid var(--border,rgba(255,255,255,0.12));border-radius:18px;padding:24px">' +
+            '<h1 style="margin:0;font-size:18px;font-weight:600">PPM could not finish loading</h1>' +
+            '<p style="margin:12px 0 0;color:var(--text-2,#9aa6c2)">Part of the app is missing from the server, ' +
+            'which usually means it was replaced by an upgrade. Reloading fetches the current version.</p>' +
+            '<button id="ppm-boot-retry" type="button" style="min-height:44px;width:100%;margin-top:20px;' +
+            'padding:0 20px;border:0;border-radius:12px;background:var(--accent,#5b8cff);' +
+            'color:var(--accent-fg,#fff);font:inherit;font-weight:600;cursor:pointer">Reload</button>' +
+            "</div></div>";
+          document.getElementById("ppm-boot-retry").onclick = function () {
+            try { sessionStorage.removeItem(KEY); } catch (e) {}
+            purge().then(function () { location.reload(); });
+          };
+        }
+        function check() {
+          // Module scripts execute before `load`, so a flag still unset here is
+          // never going to be set — this cannot misfire on a slow boot.
+          //
+          // A boot that worked also clears the key. The silent retry is meant to
+          // be one per *incident*, and the key was only ever written: after one
+          // upgrade healed itself, a second upgrade in the same tab session went
+          // straight to the panic card without trying the reload that would have
+          // fixed it — on a long-lived tab, which is exactly the tab this is for.
+          if (window.__ppmEntryRan) {
+            try { sessionStorage.removeItem(KEY); } catch (e) {}
+            return;
+          }
+          var retried;
+          try {
+            retried = sessionStorage.getItem(KEY) === "1";
+            sessionStorage.setItem(KEY, "1");
+          } catch (e) {
+            // No storage means no way to count attempts, and an uncounted
+            // reload is a loop. Go straight to the message.
+            retried = true;
+          }
+          // One silent attempt first: index.html is served `no-cache`, so a
+          // reload with this origin's caches dropped is exactly how a tab
+          // holding an upgraded-away chunk list heals itself.
+          if (!retried) { purge().then(function () { location.reload(); }); return; }
+          panic();
+        }
+        window.addEventListener("load", function () { setTimeout(check, 4000); });
+      })();
+    </script>
     <!-- Eruda: mobile console for debugging. Activate with ?debug in URL -->
     <script>
       if (/debug=true|debug(&|$)/.test(location.search)) {

package/src/web/lib/blame-hover-commands.ts

@@ -0,0 +1,82 @@
+/**
+ * The commands behind the blame hover's buttons.
+ *
+ * A Monaco hover can only contain markdown, so a button is a `command:` link
+ * and there has to be something registered under that id for it to reach. These
+ * are registered on the standalone `CommandsRegistry`, which is global to the
+ * page — hence the idempotence, and hence ids namespaced under `ppm.blame.`.
+ *
+ * Three of the four hand off to the Git Graph extension, which already has the
+ * views: `ext:command:execute` is the same event core UI uses elsewhere
+ * (`git-status-panel.tsx`), and `git-graph.blame` and `git-graph.fileHistory`
+ * already accept a file path as their second argument.
+ *
+ * Every handler re-checks its arguments even though `buildBlameHoverMarkdown`
+ * is the only thing that writes these links, and even though the hover's trust
+ * is narrowed so a commit message cannot forge one. The registry is global: any
+ * other markdown on the page could name these ids.
+ */
+import type * as MonacoType from "monaco-editor";
+import { toast } from "sonner";
+import { copyToClipboard } from "./clipboard";
+
+let registered = false;
+
+/** Dispatch an extension command the way the rest of the app does. */
+function runExtensionCommand(command: string, args: unknown[]): void {
+  window.dispatchEvent(new CustomEvent("ext:command:execute", { detail: { command, args } }));
+}
+
+function asHash(value: unknown): string | null {
+  return typeof value === "string" && /^[0-9a-f]{7,40}$/.test(value) ? value : null;
+}
+
+function asPath(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Both paths are required. An extension view command reads a falsy first
+ * argument as "resolve the project yourself", which for a hover that named a
+ * specific file would silently open some other project's history.
+ */
+function runForFile(command: string, projectPath: unknown, filePath: unknown): void {
+  const root = asPath(projectPath);
+  const path = asPath(filePath);
+  if (!root || !path) return;
+  runExtensionCommand(command, [root, path]);
+}
+
+export function registerBlameHoverCommands(monaco: typeof MonacoType): void {
+  if (registered) return;
+  registered = true;
+
+  monaco.editor.registerCommand("ppm.blame.copySha", (_accessor, hash: unknown) => {
+    const sha = asHash(hash);
+    if (!sha) return;
+    // The full hash, not the abbreviation the link shows: an abbreviation is
+    // for reading, and what you paste into a command has to be unambiguous.
+    void copyToClipboard(sha).then((ok) => {
+      toast[ok ? "success" : "error"](ok ? `Copied ${sha.slice(0, 7)}` : "Could not copy");
+    });
+  });
+
+  monaco.editor.registerCommand("ppm.blame.fileHistory", (_accessor, projectPath: unknown, filePath: unknown) => {
+    runForFile("git-graph.fileHistory", projectPath, filePath);
+  });
+
+  monaco.editor.registerCommand("ppm.blame.blameFile", (_accessor, projectPath: unknown, filePath: unknown) => {
+    runForFile("git-graph.blame", projectPath, filePath);
+  });
+
+  monaco.editor.registerCommand("ppm.blame.showInGraph", (_accessor, projectPath: unknown) => {
+    const root = asPath(projectPath);
+    if (!root) return;
+    runExtensionCommand("git-graph.view", [root]);
+  });
+}
+
+/** Test seam. */
+export function _resetBlameHoverCommands(): void {
+  registered = false;
+}

package/src/web/lib/blame-hover.ts

@@ -0,0 +1,199 @@
+/**
+ * The markdown behind the editor's blame hover — GitLens' hover, rebuilt.
+ *
+ * Monaco's hover renders a markdown string and nothing else, so everything the
+ * hover shows has to survive being written as markdown: the avatar is a data-URI
+ * image, the buttons are `command:` links, and the diff is a fenced block.
+ *
+ * Three things about that are load-bearing and were each verified against a real
+ * Monaco 0.55.1 rather than assumed:
+ *
+ * - `command:` links are stripped unless the string is trusted, and a trusted
+ *   string with `isTrusted: true` allows *every* registered command. This one
+ *   carries a commit message, and anyone who can land a commit can put
+ *   `[click](command:whatever)` in one — so the trust is narrowed to the four
+ *   commands here via `enabledCommands`, and the message is escaped on top.
+ * - `supportHtml` stays off. The avatar is `![](data:image/svg+xml,…)`, which
+ *   renders inline at its own intrinsic size, so no `<img width>` is needed and
+ *   no HTML from a commit message can render at all.
+ * - a ```diff block is only coloured because `monaco-diff-language.ts`
+ *   registers the language Monaco lacks.
+ */
+import type * as MonacoType from "monaco-editor";
+import {
+  formatAbsoluteTime,
+  formatRelativeTime,
+  isUncommittedHash,
+  type BlameCommitInfo,
+  type BlameLineDetail,
+} from "../../shared/blame";
+
+/** The commands the hover's links may run. Nothing else, whatever a message says. */
+export const BLAME_HOVER_COMMANDS = [
+  "ppm.blame.copySha",
+  "ppm.blame.fileHistory",
+  "ppm.blame.blameFile",
+  "ppm.blame.showInGraph",
+] as const;
+
+/** How much of a sha to show. Git's own default abbreviation. */
+const SHORT_SHA = 7;
+
+/**
+ * Escape the markdown a commit message or an author name would otherwise be
+ * read as. The character set is VS Code's own `escapeMarkdownSyntaxTokens`.
+ *
+ * `[` and `]` are the ones that matter most: without them a message reading
+ * `[click](command:…)` becomes a button in the hover.
+ *
+ * `<` and `>` are added to VS Code's set because the renderer does not leave an
+ * unknown tag alone — it strips the tag and keeps the text inside, so a message
+ * mentioning `<script>alert(1)</script>` displayed as `alert(1)`. Not a script
+ * that runs, but a commit message rewritten in the one view whose job is to
+ * show it verbatim. A backslash escape rather than an entity: `&lt;` would come
+ * back out literally, since `&` is not escaped here.
+ *
+ * Newlines are left alone; the message's own line breaks are wanted.
+ */
+export function escapeMarkdown(text: string): string {
+  return text.replace(/[\\`*_{}[\]()#+\-!<>]/g, (c) => `\\${c}`);
+}
+
+/** Initials for the avatar: first letters of the first and last word. */
+export function authorInitials(author: string): string {
+  const words = author.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return "?";
+  const first = words[0]![0]!;
+  const last = words.length > 1 ? words[words.length - 1]![0]! : "";
+  return (first + last).toUpperCase();
+}
+
+/**
+ * A stable colour per author, from VS Code's chart palette.
+ *
+ * Deliberately not a gravatar. Fetching one would send a hash of the
+ * committer's email to a third party on every hover, which a self-hosted tool
+ * must not do silently — the same reason the git graph's author chips are
+ * initials.
+ */
+const AVATAR_COLOURS = ["4E79A7", "F28E2B", "E15759", "76B7B2", "59A14F", "AF7AA1", "9C755F", "B07AA1"];
+
+export function authorColour(author: string): string {
+  let hash = 0;
+  for (let i = 0; i < author.length; i++) hash = (hash * 31 + author.charCodeAt(i)) | 0;
+  return AVATAR_COLOURS[Math.abs(hash) % AVATAR_COLOURS.length]!;
+}
+
+/**
+ * The avatar as an inline SVG data URI, sized 16×16 so it needs no HTML
+ * attributes to sit on the same line as the name.
+ *
+ * `charset=utf-8` matters: initials can be non-ASCII, and without it the
+ * browser decodes the percent-escapes as latin-1 and draws mojibake.
+ */
+export function avatarDataUri(author: string): string {
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">` +
+    `<circle cx="8" cy="8" r="8" fill="#${authorColour(author)}"/>` +
+    `<text x="8" y="11.5" font-family="sans-serif" font-size="7" font-weight="700" ` +
+    `fill="#ffffff" text-anchor="middle">${escapeXml(authorInitials(author))}</text></svg>`;
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+
+function escapeXml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** `command:id?["arg","arg"]`, percent-encoded as the opener expects. */
+function commandUri(command: (typeof BLAME_HOVER_COMMANDS)[number], args: unknown[]): string {
+  return `command:${command}?${encodeURIComponent(JSON.stringify(args))}`;
+}
+
+export interface BlameHoverOptions {
+  commit: BlameCommitInfo;
+  /** Null while the `git show` is still in flight, or when it found nothing. */
+  detail: BlameLineDetail | null;
+  /** Project-relative path of the open file, for the action links. */
+  filePath: string;
+  /** Absolute path of the project, which is what the git-graph commands take. */
+  projectPath?: string;
+  /** Parameter rather than the clock, so the wording is testable. */
+  now?: number;
+}
+
+/**
+ * The hover for a committed line.
+ *
+ * Returns null for an uncommitted line: there is no commit to describe, and the
+ * annotation already says "You, uncommitted changes".
+ */
+export function buildBlameHoverMarkdown(options: BlameHoverOptions): MonacoType.IMarkdownString | null {
+  const { commit, detail, filePath, projectPath, now = Date.now() } = options;
+  if (isUncommittedHash(commit.hash)) return null;
+
+  const author = commit.author || "Unknown";
+  const shortSha = commit.hash.slice(0, SHORT_SHA);
+  const lines: string[] = [];
+
+  // Row 1: avatar, author, and both readings of the date — "9 months ago" is
+  // what you want to know, the exact date is what you need to go looking.
+  const when = commit.authorTime > 0
+    ? `${formatRelativeTime(commit.authorTime * 1000, now)} (${formatAbsoluteTime(commit.authorTime * 1000)})`
+    : "";
+  lines.push(`![](${avatarDataUri(author)}) **${escapeMarkdown(author)}**${when ? ` &nbsp;$(history) ${escapeMarkdown(when)}` : ""}`);
+
+  // Row 2: the whole message, not just the summary the annotation shows.
+  const message = detail?.message || commit.summary;
+  if (message) {
+    lines.push("");
+    // A blank line inside the message would end the markdown paragraph and
+    // leave the body unindented; two trailing spaces make each line its own.
+    lines.push(escapeMarkdown(message).split("\n").join("  \n"));
+  }
+
+  // A rule between sections, as GitLens has. It must be preceded by a blank
+  // line: `text` then `---` on the next line is a setext heading in markdown,
+  // which would turn the last line of the commit message into a title.
+  const RULE = ["", "---", ""];
+
+  // Row 3: the sha, and the things PPM can actually do with it.
+  const actions = [
+    `[$(git-commit) ${shortSha}](${commandUri("ppm.blame.copySha", [commit.hash])} "Copy commit hash")`,
+  ];
+  // The Git Graph views are addressed by absolute project path. Without one the
+  // links would dispatch an empty first argument, which the extension reads as
+  // "resolve the project yourself" — so it might open a *different* project's
+  // history. Better to not offer the button.
+  if (projectPath) {
+    actions.push(
+      `[$(history) File History](${commandUri("ppm.blame.fileHistory", [projectPath, filePath])} "Open the file's history")`,
+      `[$(users) Blame](${commandUri("ppm.blame.blameFile", [projectPath, filePath])} "Open the blame view")`,
+      `[$(git-branch) Graph](${commandUri("ppm.blame.showInGraph", [projectPath])} "Open the commit graph")`,
+    );
+  }
+  lines.push(...RULE);
+  lines.push(actions.join(" &nbsp; "));
+
+  // Row 4: what this commit did to this line.
+  const diff = [...(detail?.removed ?? []).map((l) => `-${l}`), ...(detail?.added ?? []).map((l) => `+${l}`)];
+  if (diff.length > 0) {
+    lines.push(...RULE);
+    lines.push("```diff");
+    lines.push(...diff);
+    lines.push("```");
+    lines.push("");
+    // GitLens' wording, and the distinction is worth keeping: a line that only
+    // ever appeared in this commit reads differently from one it rewrote.
+    const verb = (detail?.removed.length ?? 0) === 0 ? "added in" : "in";
+    lines.push(`Changes ${verb} \`${shortSha}\``);
+  }
+
+  return {
+    value: lines.join("\n"),
+    // Narrowed on purpose. `true` here would let a commit message's own
+    // `command:` link run anything registered, and a commit message is not
+    // ours. See the module comment.
+    isTrusted: { enabledCommands: [...BLAME_HOVER_COMMANDS] },
+    supportThemeIcons: true,
+  };
+}

package/src/web/lib/chunk-recovery.ts

@@ -0,0 +1,113 @@
+/**
+ * Recovery for the one failure that empties the screen instead of reporting an
+ * error: a lazy chunk the running app asks for and cannot get.
+ *
+ * The chain, reproduced end to end. An upgrade replaces `dist/web` and Vite's
+ * `emptyOutDir` deletes the previous content hashes, so a tab that has been open
+ * across the upgrade asks for a chunk that is no longer on disk. `static.ts`
+ * used to answer that with the app shell — `200 text/html` — which a module load
+ * refuses on its strict MIME check; it now answers 404, but a 404 is still a
+ * rejected `import()`, which is a throw inside `React.lazy`. A throw with no
+ * boundary above it unmounts the whole tree: `#root` empties and the page is
+ * left showing nothing but the body's background.
+ *
+ * The service worker made it *permanent*. `CacheFirst` on `/assets/` had stored
+ * that `text/html` under the chunk's own URL, and content-hashed assets are
+ * never revalidated — so restoring the file on the server changed nothing and
+ * only `caches.delete("ppm-assets")` recovered the tab. `sw.ts` now refuses to
+ * store or serve HTML for an asset, but an install that already holds a poisoned
+ * entry has to be cleaned from the page, which is what this does before
+ * reloading.
+ *
+ * Reloading is allowed once per tab. A second failure means the chunk is
+ * genuinely unavailable, and a page that reloads itself forever is worse than
+ * one that says what happened.
+ */
+
+const RELOAD_KEY = "ppm:chunk-reload";
+
+/**
+ * Set once a recovery reload is on its way, and read by the `beforeunload`
+ * guard in `app.tsx`.
+ *
+ * That guard is unconditional while authenticated — it exists to catch a stray
+ * Ctrl+W — and `beforeunload` cannot tell who asked for the navigation. So the
+ * automatic recovery put a "Leave site?" dialog in front of the one reload the
+ * user never chose and cannot act on knowledgeably: the tab is already showing
+ * a broken app. Declining it leaves them there.
+ */
+let recoveryReloadPending = false;
+
+export function isRecoveryReloadPending(): boolean {
+  return recoveryReloadPending;
+}
+
+/**
+ * The wordings browsers use when a dynamic import does not produce a module.
+ * Chrome, Firefox and Safari each phrase it differently, and the MIME refusal
+ * is phrased differently again from a plain network failure.
+ */
+const CHUNK_ERROR =
+  /dynamically imported module|importing a module script failed|failed to load module script|error loading chunk|expected a javascript(-or-wasm)? module script/i;
+
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false;
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  return CHUNK_ERROR.test(message);
+}
+
+/** Drop the caches this app owns, so the next load asks the server again. */
+export async function purgeAssetCaches(): Promise<void> {
+  if (typeof caches === "undefined") return;
+  try {
+    const names = await caches.keys();
+    await Promise.all(names.filter((n) => n.startsWith("ppm-")).map((n) => caches.delete(n)));
+  } catch {
+    // A browser in private mode can refuse the Cache API outright. Reloading
+    // without the purge is still the right next move.
+  }
+}
+
+/** Purge and reload unconditionally — the button in the error boundary. */
+export async function purgeAndReload(): Promise<void> {
+  try {
+    sessionStorage.removeItem(RELOAD_KEY);
+  } catch {
+    // Nothing to clear; the reload below is what matters.
+  }
+  recoveryReloadPending = true;
+  await purgeAssetCaches();
+  window.location.reload();
+}
+
+/**
+ * Purge and reload at most once per tab. Returns whether a reload was started,
+ * so a caller can tell "recovering" from "this is as good as it gets".
+ */
+export function reloadOnceForChunkError(): boolean {
+  let already: boolean;
+  try {
+    already = sessionStorage.getItem(RELOAD_KEY) === "1";
+    sessionStorage.setItem(RELOAD_KEY, "1");
+  } catch {
+    // No storage means no way to count attempts, and an uncounted auto-reload
+    // is an infinite loop. Leave it to the boundary's button.
+    return false;
+  }
+  if (already) return false;
+  recoveryReloadPending = true;
+  void purgeAssetCaches().then(() => window.location.reload());
+  return true;
+}
+
+export function installChunkErrorRecovery(): void {
+  // Vite's preload helper dispatches this when a chunk, or one of the chunks it
+  // preloads, cannot be fetched. It is deliberately *not* `preventDefault`ed:
+  // cancelling the event makes the helper resolve with `undefined` rather than
+  // rethrow, and `React.lazy` then fails reading `.default` of undefined — an
+  // error that says nothing about what actually happened. The reload normally
+  // wins the race; when it does not, the boundary catches the real throw.
+  window.addEventListener("vite:preloadError", () => {
+    reloadOnceForChunkError();
+  });
+}