@gusnips/react 0.9.24 → 0.9.26

package/src/commands.test.ts

@@ -0,0 +1,245 @@
+// @vitest-environment node
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, expectTypeOf, it, vi } from "vitest";
+import {
+  completeCommand,
+  matchCommands,
+  parseCommand,
+  resolveCommand,
+  useSlashCommands,
+} from "./commands.ts";
+
+const help = {
+  name: "help",
+  description: "Show available commands",
+  aliases: ["assist", "GUIDE"],
+  tags: ["manual"],
+};
+const schedule = {
+  name: "schedule",
+  description: "Run a task later",
+  aliases: ["later", "book"],
+  tags: ["timer"],
+  takesArg: true,
+};
+const commands = [help, schedule];
+
+describe("parseCommand", () => {
+  it.each([
+    { text: "/", expected: { name: "" } },
+    { text: "/ ", expected: { name: "", arg: "" } },
+    { text: "/HELP", expected: { name: "help" } },
+    { text: "/help ", expected: { name: "help", arg: "" } },
+    { text: " \t/HeLp", expected: { name: "help" } },
+    {
+      text: "/SCHEDULE   Keep  these spaces\tand case  ",
+      expected: { name: "schedule", arg: "Keep  these spaces\tand case  " },
+    },
+  ])("parses a single line: $text", ({ text, expected }) => {
+    expect(parseCommand(text)).toEqual(expected);
+  });
+
+  it.each(["/tmp/file", "/help/topic", "//help"])(
+    "keeps a slash path as an unknown command token: %s",
+    (text) => {
+      const name = text.slice(1);
+      expect(parseCommand(text)).toEqual({ name });
+      expect(resolveCommand(commands, name)).toEqual({ kind: "unknown", name });
+    },
+  );
+
+  it.each(["", " \t", "help", "Please /help", "https://example.test/help", "Hello /help there"])(
+    "ignores non-command prose: %s",
+    (text) => {
+      expect(parseCommand(text)).toBeNull();
+    },
+  );
+
+  it.each(["\n", "\r", "\r\n", "\u{2028}", "\u{2029}"])(
+    "rejects a line terminator anywhere: %j",
+    (separator) => {
+      for (const text of [`${separator}/help`, `/help${separator}`, `/help ${separator}topic`]) {
+        expect(parseCommand(text)).toBeNull();
+      }
+    },
+  );
+});
+
+describe("resolveCommand", () => {
+  it("prefers an exact canonical name over an earlier alias", () => {
+    const alias = { ...schedule, aliases: ["help"] };
+    expect(resolveCommand([alias, help], "HELP")).toEqual({ kind: "matched", command: help });
+  });
+
+  it.each([
+    { token: "guide", command: help },
+    { token: "LATER", command: schedule },
+  ])("matches an alias without case sensitivity: $token", ({ token, command }) => {
+    expect(resolveCommand(commands, token)).toEqual({ kind: "matched", command });
+  });
+
+  it("reports aliases shared by different commands in registry order", () => {
+    const first = { ...schedule, aliases: ["shared", "SHARED"] };
+    const second = { ...help, aliases: ["shared"] };
+    expect(resolveCommand([first, second], "SHARED")).toEqual({
+      kind: "ambiguous",
+      name: "SHARED",
+      commands: [first, second],
+    });
+    expect(resolveCommand([first], "shared")).toEqual({ kind: "matched", command: first });
+  });
+
+  it("reports duplicate canonical names even when an alias also matches", () => {
+    const duplicate = { ...schedule, name: "HELP" };
+    const alias = { ...schedule, aliases: ["help"] };
+    expect(resolveCommand([help, alias, duplicate], "help")).toEqual({
+      kind: "ambiguous",
+      name: "help",
+      commands: [help, duplicate],
+    });
+  });
+
+  it.each(["manual", "timer", "Show available commands", "hel", "lat", "missing"])(
+    "does not execute a tag, description, prefix or unknown token: %s",
+    (name) => {
+      expect(resolveCommand(commands, name)).toEqual({ kind: "unknown", name });
+    },
+  );
+
+  it("never executes an empty token, even if the registry contains one", () => {
+    expect(resolveCommand([{ ...help, name: "", aliases: [""] }], "")).toEqual({
+      kind: "unknown",
+      name: "",
+    });
+  });
+});
+
+describe("matchCommands", () => {
+  it("ranks names, aliases, prefixes, tags and descriptions with stable ties", () => {
+    const registry = [
+      { name: "description", description: "Find a task", aliases: [], tags: [] },
+      { name: "tag", description: "", aliases: [], tags: ["finder"] },
+      { name: "shortcut", description: "", aliases: ["finder"], tags: [] },
+      { name: "finding", description: "", aliases: [], tags: [] },
+      { name: "alias", description: "", aliases: ["find"], tags: [] },
+      { name: "find", description: "", aliases: [], tags: [] },
+      { name: "second-tag", description: "", aliases: [], tags: ["find"] },
+      { name: "second-description", description: "Find another task", aliases: [], tags: [] },
+      { name: "unrelated", description: "", aliases: [], tags: [] },
+    ];
+    expect(matchCommands(registry, "find").map((command) => command.name)).toEqual([
+      "find",
+      "alias",
+      "finding",
+      "shortcut",
+      "tag",
+      "second-tag",
+      "description",
+      "second-description",
+    ]);
+  });
+
+  const translated = [
+    {
+      name: "ação",
+      description: "A próxima revisão",
+      aliases: ["café"],
+      tags: ["rápido"],
+    },
+    {
+      name: "mañana",
+      description: "Resumen de la reunión",
+      aliases: ["después"],
+      tags: ["configuración"],
+    },
+  ];
+  it.each([
+    { query: " ACAO ", name: "ação" },
+    { query: "ac\u{0327}a\u{0303}o", name: "ação" },
+    { query: "CAFE", name: "ação" },
+    { query: "RAPIDO", name: "ação" },
+    { query: "PROXIMA REVISAO", name: "ação" },
+    { query: "MANANA", name: "mañana" },
+    { query: "DESPUES", name: "mañana" },
+    { query: "CONFIGURACION", name: "mañana" },
+    { query: "REUNION", name: "mañana" },
+  ])("matches case and accents across search fields: $query", ({ query, name }) => {
+    expect(matchCommands(translated, query).map((command) => command.name)).toEqual([name]);
+  });
+
+  it("returns only the first descriptor for each canonical name", () => {
+    const duplicate = { ...help, name: "HELP" };
+    const registry = [help, schedule, duplicate];
+    expect(matchCommands(registry, "help")).toEqual([help]);
+    expect(matchCommands(registry, "")).toEqual(commands);
+  });
+
+  it("does not turn repeated or shared aliases into duplicate rows", () => {
+    const first = { ...help, aliases: ["shared", "shared", "SHARED"] };
+    const second = { ...schedule, aliases: ["shared"] };
+    expect(matchCommands([first, second], "shared")).toEqual([first, second]);
+  });
+
+  it("returns original descriptors and preserves their extra fields in the type", () => {
+    const custom = { ...help, execute: () => "done" };
+    const [matched] = matchCommands([custom], "assist");
+    expectTypeOf(matched).toEqualTypeOf<typeof custom | undefined>();
+    expect(matched).toBe(custom);
+    expect(matched?.execute()).toBe("done");
+  });
+
+  it.each(["", " \t "])("keeps registry order for an empty query: %j", (query) => {
+    expect(matchCommands([schedule, help], query)).toEqual([schedule, help]);
+  });
+
+  it("returns no rows for an unrelated query", () => {
+    expect(matchCommands(commands, "missing")).toEqual([]);
+  });
+});
+
+describe("completeCommand", () => {
+  it.each([
+    ["/later", "/schedule "],
+    ["/sche", "/schedule "],
+    ["/SCHEDULE", "/schedule "],
+    ["/", "/schedule "],
+    ["/later ", "/schedule "],
+    [" \t/later Keep  these spaces\tand case  ", "/schedule Keep  these spaces\tand case  "],
+  ])("canonicalizes an argument-taking command: %s", (text, expected) => {
+    expect(completeCommand(schedule, text)).toBe(expected);
+  });
+
+  it.each([
+    ["/assi", "/help"],
+    ["/GUIDE", "/help"],
+    ["/", "/help"],
+    ["/assist topic  with spaces  ", "/help topic  with spaces  "],
+  ])("canonicalizes a plain command without dropping its arguments: %s", (text, expected) => {
+    expect(completeCommand(help, text)).toBe(expected);
+  });
+});
+
+describe("useSlashCommands on the server", () => {
+  it("imports and renders in Node without browser globals or running callbacks", () => {
+    expect(typeof window).toBe("undefined");
+    expect(typeof document).toBe("undefined");
+    const onChange = vi.fn();
+    const onExecute = vi.fn();
+    const onError = vi.fn();
+
+    function Menu() {
+      const menu = useSlashCommands({ text: "/he", commands, onChange, onExecute, onError });
+      return createElement(
+        "output",
+        { id: menu.listId },
+        `${menu.open}/${menu.active?.name}/${menu.items.length}`,
+      );
+    }
+
+    expect(renderToString(createElement(Menu))).toContain("true/help/1");
+    expect(onChange).not.toHaveBeenCalled();
+    expect(onExecute).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+  });
+});

package/src/commands.ts

@@ -0,0 +1,268 @@
+import { useId, useState } from "react";
+
+export interface SlashCommand {
+  /** One token, without the leading slash. */
+  name: string;
+  description: string;
+  /** Other executable names. Tags only help search. */
+  aliases: readonly string[];
+  tags: readonly string[];
+  takesArg?: boolean;
+}
+
+export interface ParsedCommand {
+  name: string;
+  /** Undefined before a space; empty after a space with no argument yet. */
+  arg?: string;
+}
+
+/** Multiline text and a slash inside a message are not commands. */
+export function parseCommand(text: string): ParsedCommand | null {
+  if (/[\r\n\u{2028}\u{2029}]/u.test(text)) return null;
+  const match = /^\s*\/(\S*)(?:[^\S\r\n]+(.*))?$/u.exec(text);
+  if (!match) return null;
+  const name = (match[1] ?? "").toLowerCase();
+  return match[2] === undefined ? { name } : { name, arg: match[2] };
+}
+
+export type CommandResolution<T extends SlashCommand = SlashCommand> =
+  | { kind: "matched"; command: T }
+  | { kind: "unknown"; name: string }
+  | { kind: "ambiguous"; name: string; commands: readonly T[] };
+
+/** Exact names win over aliases. Search tags never execute an action. */
+export function resolveCommand<T extends SlashCommand>(
+  commands: readonly T[],
+  name: string,
+): CommandResolution<T> {
+  const token = name.toLowerCase();
+  if (!token) return { kind: "unknown", name };
+  let matches = commands.filter((command) => command.name.toLowerCase() === token);
+  if (matches.length === 0) {
+    matches = commands.filter((command) =>
+      command.aliases.some((alias) => alias.toLowerCase() === token),
+    );
+  }
+  if (matches.length > 1) return { kind: "ambiguous", name, commands: matches };
+  const command = matches[0];
+  return command ? { kind: "matched", command } : { kind: "unknown", name };
+}
+
+function searchText(text: string): string {
+  return text.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+}
+
+function rank(command: SlashCommand, query: string): number {
+  if (!query) return 0;
+  const name = searchText(command.name);
+  const aliases = command.aliases.map(searchText);
+  if (name === query) return 0;
+  if (aliases.includes(query)) return 1;
+  if (name.startsWith(query)) return 2;
+  if (aliases.some((alias) => alias.startsWith(query))) return 3;
+  if (command.tags.some((tag) => searchText(tag).includes(query))) return 4;
+  if (searchText(command.description).includes(query)) return 5;
+  return Infinity;
+}
+
+/** One row per name, in registry order when two results have the same rank. */
+export function matchCommands<T extends SlashCommand>(commands: readonly T[], query: string): T[] {
+  const token = searchText(query.trim());
+  const names = new Set<string>();
+  return commands
+    .filter((command) => {
+      const name = command.name.toLowerCase();
+      if (names.has(name)) return false;
+      names.add(name);
+      return true;
+    })
+    .map((command) => ({ command, rank: rank(command, token) }))
+    .filter((match) => Number.isFinite(match.rank))
+    .sort((a, b) => a.rank - b.rank)
+    .map((match) => match.command);
+}
+
+/** Replace only the name, keeping the argument already typed. */
+export function completeCommand(command: SlashCommand, text: string): string {
+  const arg = parseCommand(text)?.arg;
+  if (arg !== undefined) return `/${command.name} ${arg}`;
+  return `/${command.name}${command.takesArg ? " " : ""}`;
+}
+
+export type CommandProblem<T extends SlashCommand = SlashCommand> = Exclude<
+  CommandResolution<T>,
+  { kind: "matched" }
+>;
+
+export interface CommandOptions<T extends SlashCommand> {
+  text: string;
+  /** Supply only commands allowed here, with current translated descriptions and tags. */
+  commands: readonly T[];
+  onChange: (text: string) => void;
+  /** The app owns authorization, errors, draft cleanup and attachments. */
+  onExecute: (command: T, arg: string | undefined, altKey: boolean) => void;
+  /** Required: show a way back to the available commands, never send this text to the model. */
+  onError: (problem: CommandProblem<T>) => void;
+}
+
+/** Structural so React events and small test events both fit. */
+export interface CommandKeyEvent {
+  key: string;
+  shiftKey?: boolean;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  isComposing?: boolean;
+  keyCode?: number;
+  nativeEvent?: { isComposing?: boolean; keyCode?: number };
+  preventDefault: () => void;
+}
+
+export interface SlashCommandMenu<T extends SlashCommand = SlashCommand> {
+  parsed: ParsedCommand | null;
+  open: boolean;
+  items: readonly T[];
+  index: number;
+  active: T | undefined;
+  listId: string;
+  itemId: (command: T) => string;
+  activeId: string | undefined;
+  highlight: (index: number) => void;
+  close: () => void;
+  showAll: () => void;
+  pick: (command: T, altKey?: boolean) => void;
+  submit: (altKey?: boolean) => boolean;
+  handleKeyDown: (event: CommandKeyEvent) => boolean;
+}
+
+/** A controlled textarea menu. No UI, browser globals, timers or attachment state. */
+export function useSlashCommands<T extends SlashCommand>({
+  text,
+  commands,
+  onChange,
+  onExecute,
+  onError,
+}: CommandOptions<T>): SlashCommandMenu<T> {
+  const parsed = parseCommand(text);
+  const resolution = parsed ? resolveCommand(commands, parsed.name) : null;
+  const editingName =
+    parsed !== null && (parsed.arg === undefined || resolution?.kind !== "matched");
+  const items = editingName ? matchCommands(commands, parsed.name) : [];
+  const key = JSON.stringify([text, items.map((command) => command.name)]);
+  const [state, setState] = useState({ key, text, index: 0, deliberate: false, dismissed: false });
+  // Reset selection on a changed result set, but keep Escape's dismissal until the draft changes.
+  if (state.key !== key) {
+    setState({
+      key,
+      text,
+      index: 0,
+      deliberate: false,
+      dismissed: state.text === text && state.dismissed,
+    });
+  }
+
+  const listId = `${useId()}-commands`;
+  const open = editingName && !state.dismissed;
+  const active = open ? items[state.index] : undefined;
+  const itemId = (command: T) => `${listId}-${encodeURIComponent(command.name)}`;
+
+  function close(): void {
+    setState((current) => ({ ...current, dismissed: true }));
+  }
+
+  function showAll(): void {
+    setState((current) => ({ ...current, index: 0, deliberate: false, dismissed: false }));
+    onChange("/");
+  }
+
+  function highlight(index: number): void {
+    if (!items[index]) return;
+    setState((current) => ({ ...current, index, deliberate: true }));
+  }
+
+  function pick(command: T, altKey = false): void {
+    // Re-resolve against current capabilities, not a descriptor retained by a caller.
+    const selected = resolveCommand(commands, command.name);
+    if (selected.kind !== "matched") {
+      onError(selected);
+      return;
+    }
+    if (selected.command.takesArg || parsed?.arg) {
+      onChange(completeCommand(selected.command, text));
+      return;
+    }
+    onExecute(selected.command, parsed?.arg, altKey);
+  }
+
+  /** Call before the normal send/queue/quota path, including button and imperative submits. */
+  function submit(altKey = false): boolean {
+    if (!parsed || !resolution) return false;
+    if (resolution.kind !== "matched") {
+      onError(resolution);
+      return true;
+    }
+    if (
+      resolution.command.takesArg &&
+      parsed.arg === undefined &&
+      parsed.name !== resolution.command.name.toLowerCase()
+    ) {
+      onChange(completeCommand(resolution.command, text));
+      return true;
+    }
+    onExecute(resolution.command, parsed.arg, altKey);
+    return true;
+  }
+
+  /** Call first. True means skip your own key handler; IME still gets the browser's default. */
+  function handleKeyDown(event: CommandKeyEvent): boolean {
+    const native = event.nativeEvent ?? event;
+    if (native.isComposing || native.keyCode === 229) return true;
+    if (event.shiftKey) return false;
+    if (open && event.key === "Escape") {
+      event.preventDefault();
+      close();
+      return true;
+    }
+    if (open && items.length > 0 && !event.ctrlKey && !event.metaKey) {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault();
+        const step = event.key === "ArrowDown" ? 1 : -1;
+        highlight((state.index + step + items.length) % items.length);
+        return true;
+      }
+      if (active && (event.key === "Enter" || event.key === "Tab")) {
+        event.preventDefault();
+        if (event.key === "Tab") {
+          onChange(completeCommand(active, text));
+        } else if (resolution?.kind === "ambiguous" && !state.deliberate) {
+          onError(resolution);
+        } else {
+          pick(active, event.altKey);
+        }
+        return true;
+      }
+    }
+    if (parsed && event.key === "Enter") {
+      event.preventDefault();
+      return submit(event.altKey);
+    }
+    return false;
+  }
+
+  return {
+    parsed,
+    open,
+    items,
+    index: state.index,
+    active,
+    listId,
+    itemId,
+    activeId: active ? itemId(active) : undefined,
+    highlight,
+    close,
+    showAll,
+    pick,
+    submit,
+    handleKeyDown,
+  };
+}

package/src/copy.ts

@@ -29,9 +29,9 @@ export interface CopyOptions {
 }
 
 /**
- * A copy with an outcome the reader can see. What it says stays yours — "Copied", or "Select it
- * and copy it yourself", in a label or a toast — and so does announcing it: a label that changes
- * needs `aria-live="polite"` to be heard.
+ * A copy with an outcome the reader can see. You choose what it says, such as "Copied" or "Select
+ * it and copy it yourself", in a label or a toast. You also choose how to announce it: a label that
+ * changes needs `aria-live="polite"` to be heard.
  *
  * The outcome goes back to `"idle"` on its own. A "Copied" that never clears makes the second copy
  * look like it did not take.

package/src/deploy-recovery.ts

@@ -5,26 +5,26 @@
  * every hashed asset underneath whatever tabs are already open, and those tabs go on running
  * yesterday's bundle. It surfaces two ways, and only one of them looks like a missing file:
  *
- *   1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary
- *      throws, and the person gets a white screen on a click that worked a minute ago.
- *   2. The old bundle reads a field the API has since renamed, and throws. That one arrives as a
- *      plain `TypeError` with nothing in it about a deploy — no file, no hash, no signal.
+ * 1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary throws,
+ * and the person gets a white screen on a click that worked a minute ago. 2. The old bundle reads a
+ * field the API has since renamed, and throws. That one arrives as a plain `TypeError` with nothing
+ * in it about a deploy: no file, no hash, no signal.
  *
  * So there are two detectors here and they are not interchangeable. {@link isChunkLoadError}
- * matches the message, which is all you have for a failure that never reaches a boundary.
- * {@link isStaleBuild} asks the server, which is evidence rather than a guess — and it is the
- * only one that catches case 2 at all.
+ * matches the message, which is all you have for a failure that never reaches a boundary. {@link
+ * isStaleBuild} asks the server for evidence rather than a guess. It is the only one that catches
+ * case 2 at all.
  *
  * **The deepest fix is not in this file, and it is worth more than everything in it.** A static
- * host answers a missing `/assets/x.js` with the SPA fallback — `index.html`, at a 200, as
- * `text/html` — which is what the browser's "MIME type text/html" module-script refusal actually
- * is. Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the
- * `immutable, max-age=31536000` rule written for hashed assets gets applied to that HTML body:
- * one poisoned asset URL, at the edge and in every browser that touched it, for a year. One
- * adopter removed the cause instead of recovering from it — no blanket fallback over `/assets/`,
- * and an edge function that refuses to answer an asset path with `text/html` — which turns a
- * dead chunk into a real, uncacheable 404 and lets everything below be recovery rather than the
- * plan. A package cannot ship that; it can refuse to let it go unwritten.
+ * host answers a missing `/assets/x.js` with the SPA fallback, `index.html`, at a 200, as
+ * `text/html`. That is what the browser's "MIME type text/html" module-script refusal actually is.
+ * Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the `immutable,
+ * max-age=31536000` rule written for hashed assets gets applied to that HTML body: one poisoned
+ * asset URL, at the edge and in every browser that touched it, for a year. One adopter removed the
+ * cause instead of recovering from it: no blanket fallback over `/assets/`, and an edge function
+ * that refuses to answer an asset path with `text/html`. That turns a dead chunk into a real,
+ * uncacheable 404 and lets everything below be recovery rather than the plan. A package cannot ship
+ * that; it can refuse to let it go unwritten.
  */
 
 /**
@@ -48,14 +48,14 @@ const RELOAD_WINDOW_MS = 60_000;
 const PROBE_TIMEOUT_MS = 4_000;
 
 /**
- * A lazy-chunk fetch failure — recoverable by reloading.
+ * A lazy-chunk fetch failure that a reload can fix.
  *
- * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
- * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
- * dynamically imported module", Safari "Importing a module script failed", webpack's
- * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
- * which is the one that fires on a static host that has not fixed the cause above, because the
- * missing `.js` is answered with `index.html`.
+ * Matched by message because no browser gives it a shared type. Every phrasing in the wild is here:
+ * Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading dynamically
+ * imported module", Safari "Importing a module script failed", webpack's ChunkLoadError and
+ * "Loading chunk N failed", and the SPA-fallback "MIME type" refusal. The last one that fires on a
+ * static host that has not fixed the cause above, because the missing `.js` is answered with
+ * `index.html`.
  *
  * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
  * handler can classify the same failure without importing a component.
@@ -93,13 +93,13 @@ function runningEntry(): string {
 /**
  * Is the build this tab is running still the one being served?
  *
- * Asked of the server, so the answer is evidence rather than a guess. Everything ambiguous —
- * offline, a non-200, a captive portal, a probe that times out — resolves to `false`: dressing a
- * genuine bug up as an update hides it from the user and from us.
+ * Asked of the server, so the answer is evidence rather than a guess. An offline request, a non-200
+ * response, a captive portal or a timed-out probe resolves to `false`: dressing a genuine bug up as
+ * an update hides it from the user and from us.
  *
  * It asks for the PAGE, not for the asset, and that is not the obvious choice. A missing asset
  * looks like the direct question, but a CDN commonly serves assets with a long `s-maxage`, so a
- * bundle a deploy retired an hour ago still answers 200 from the edge — it would report "current"
+ * bundle a deploy retired an hour ago still answers 200 from the edge. It would report "current"
  * during exactly the window when skew is most likely. The page is the one URL that cannot lie: it
  * ships `max-age=0, must-revalidate` and never enters the edge cache.
  */
@@ -124,9 +124,9 @@ export async function isStaleBuild(): Promise<boolean> {
  * rather than watching the same attempt loop.
  *
  * The guard is the part that matters. Reloading on a failure is obvious; reloading on a failure
- * that the reload does not fix is an infinite loop with the user inside it. At most one reload
- * per minute, so a genuinely broken deploy degrades to the error screen — which can at least say
- * something — instead of flickering forever.
+ * that the reload does not fix is an infinite loop with the user inside it. At most one reload per
+ * minute, so a genuinely broken deploy shows the error screen instead of flickering forever. That
+ * screen can at least say something.
  *
  * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament, and
  * a stale stamp in another tab must not suppress a reload this one needs. Wrapped because storage
@@ -149,11 +149,11 @@ export function reloadOnce(): boolean {
 /**
  * Vite's *hint* failure, which is not the same thing and must not be treated as one.
  *
- * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
- * When that link fails, the import itself still runs right after and usually succeeds — so this
- * one is worth swallowing, where a failure of the import is the real thing
- * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
- * for a stylesheet link; script hints never reject.
+ * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it. When
+ * that link fails, the import itself still runs right after and usually succeeds, so this one is
+ * worth swallowing, where a failure of the import is the real thing {@link isChunkLoadError}
+ * matches. Vite builds this message in exactly one place and only ever for a stylesheet link;
+ * script hints never reject.
  */
 export function isPreloadHintFailure(error: unknown): boolean {
   return error instanceof Error && error.message.startsWith("Unable to preload CSS for");
@@ -162,12 +162,12 @@ export function isPreloadHintFailure(error: unknown): boolean {
 /**
  * Install the `vite:preloadError` listener. Call once, from the browser entry.
  *
- * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
- * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
+ * Vite offers `preventDefault()` here so an app can own a failed asset itself, but taking that deal
+ * unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
  * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
- * The user gets the crash screen and the developer gets a TypeError with only React frames in
- * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
- * runs. A real module failure is left to throw, where the error boundary can recognise it.
+ * The user gets the crash screen and the developer gets a TypeError with only React frames in it,
+ * naming no chunk. So it is taken ONLY for a failed preload hint, where the import still runs. A
+ * real module failure is left to throw, where the error boundary can recognise it.
  */
 export function installPreloadErrorHandler(): void {
   window.addEventListener("vite:preloadError", (event) => {