style(ui): tighten the new frontend comments to stay inside the size budget

Rollup ships src/ comments verbatim in dist/index.js, and the bundle sits
close to its 800 kB size-limit: 796.76 kB before this branch. The new
comments alone pushed it to 800.61 kB and failed `pnpm size`.

Condense them to the load-bearing reasoning — every "why" is kept, only
restatement is dropped. Two blocks in SlotSetupWizard went entirely: the
surrounding comments already said "any other resolved result proves the
server answered", which covers the new not_found case.

799.34 kB.

Author: danielcopper

src/api/backend.ts

@@ -443,10 +443,10 @@ export interface VersionInfo {
  * the picker renders nothing. When `true`, `versions` lists every version
  * (local + server-only) with markers; `server_query_failed` is `true` when the
  * live `sibling_roms` view could not be fetched, so the list is local-only
- * (partial-success carve-out). A definitive 404 on the bound id is NOT such a
- * failure — the server answered, it just no longer has that ROM — so the
- * local-only list comes back with `server_query_failed: false` and the picker
- * leaves the shared connection state alone (#1570).
+ * (partial-success carve-out). A 404 on the bound id is NOT such a failure —
+ * the server answered — so the local-only list comes back with
+ * `server_query_failed: false` and the picker leaves the connection state
+ * alone (#1570).
  */
 export interface VersionList {
   multi_version: boolean;

src/components/CustomPlayButton.tsx

@@ -735,10 +735,9 @@ export const CustomPlayButton: FC<CustomPlayButtonProps> = ({ appId }) => { // N
       // believing the conflict was cleared. Surface it and stay in conflict,
       // exactly like the network-throw catch below (#1276).
       if (result.server_query_failed) {
-        // Only an explicit unreachable verdict is a connectivity signal. A
-        // definitive 404 means the server ANSWERED, so feeding the global
-        // store off the bare flag would black out the whole UI over a ROM
-        // the server merely no longer has (#1570) — see connectionState.ts.
+        // Only an explicit unreachable verdict is a connectivity signal:
+        // feeding the store off the bare flag blacked out the whole UI over a
+        // ROM the server merely no longer has (#1570).
         if (result.server_query_reason === "server_unreachable") {
           reportServerReachable(false);
         }

src/components/SlotSetupWizard.tsx

@@ -516,12 +516,10 @@ function useSaveSetupInfo(romId: number, onComplete: () => void) {
         if (cancelled) return;
         // Feed the shared store (#1345): a server_unreachable result is a
         // definitive offline signal; any other resolved result proves the
-        // server answered. A throw is a bridge/unknown error, not a verdict —
-        // the catch leaves the store untouched.
-        // Only an explicit unreachable verdict means offline. A `not_found`
-        // result PROVES the server answered, so it reports reachable and
-        // leaves the reconnect gate disarmed — the wizard still holds, it
-        // just doesn't wait for a connection that was never lost (#1570).
+        // server answered — including a `not_found`, which still holds the
+        // wizard but leaves the reconnect gate disarmed (#1570). A throw is a
+        // bridge/unknown error, not a verdict — the catch leaves the store
+        // untouched.
         const reachable = result.recommended_action !== "server_unreachable";
         reportServerReachable(reachable);
         offlineHeldRef.current = !reachable;
@@ -580,10 +578,6 @@ function useSaveSetupInfo(romId: number, onComplete: () => void) {
         // Same conservative feed as the initial load (#1345): the manual
         // Retry re-probes reachability, so a server_unreachable result
         // re-arms offline and any other result reports the server back.
-        // Only an explicit unreachable verdict means offline. A `not_found`
-        // result PROVES the server answered, so it reports reachable and
-        // leaves the reconnect gate disarmed — the wizard still holds, it
-        // just doesn't wait for a connection that was never lost (#1570).
         const reachable = result.recommended_action !== "server_unreachable";
         reportServerReachable(reachable);
         offlineHeldRef.current = !reachable;

src/components/saves/VersionHistoryPanel.tsx

@@ -51,9 +51,7 @@ export const VersionHistoryPanel: FC<VersionHistoryPanelProps> = ({
         // hidden for multi-file slots anyway; this is the defensive backstop.
         setVersions(result.versions);
       } else if (result.status === "not_found") {
-        // The server answered: it has no such ROM / device id. Saying
-        // "couldn't reach RomM" here would blame a connection that is
-        // plainly working (#1570).
+        // The server answered — blaming the connection here would be a lie (#1570).
         detach(debugLog(`VersionHistoryPanel: server has no such entry for ${filename}: ${result.message}`));
         setVersions(null);
         setLoadError("RomM no longer has this game's saves.");
@@ -156,9 +154,8 @@ export const VersionHistoryPanel: FC<VersionHistoryPanelProps> = ({
         // instead of telling the user the version is gone.
         toaster.toast({ title: "RomM Sync", body: "Couldn't reach RomM. Check your connection and try again." });
       } else if (result.status === "not_found") {
-        // The mirror image of the branch above: RomM answered that it no
-        // longer has this game's saves, so a retry cannot help and the
-        // toast must not send the user off to check their connection (#1570).
+        // Mirror of the branch above: RomM answered, so a retry cannot help
+        // and the toast must not send the user to check their connection.
         toaster.toast({ title: "RomM Sync", body: "RomM no longer has this game's saves — nothing was restored." });
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- exhaustive final branch of the 9-member RollbackStatus union; an explicit check (vs. plain `else`) keeps the per-status symmetry and leaves any future-added status unhandled instead of silently routing it to the "unsupported" toast
       } else if (result.status === "unsupported") {

src/types/saves.ts

@@ -93,11 +93,9 @@ export interface SaveStatus {
    *  and surface a misleading uploads-pending indicator on what is in
    *  fact a connectivity blip. */
   server_query_failed?: boolean;
-  /** Why that query failed, as a backend `classify_error` slug (`null` when
-   *  it didn't). The flag says the server's view is unknown — true for a
-   *  definitive 404 as much as for an outage — while this says *why*, so
-   *  only `"server_unreachable"` may drive the global connection store.
-   *  Feeding the store off the bare flag is the #1570 defect. */
+  /** Why it failed (`null` when it didn't). The flag says the server's view is
+   *  unknown — true for a 404 as much as for an outage; this says why, so only
+   *  `"server_unreachable"` may drive the connection store (#1570). */
   server_query_reason?: RommErrorCode | null;
   /** True when the active slot's current save spans more than one distinct
    *  file (e.g. Sega Saturn `.bkr`/`.bcr`/`.smpc`). Those siblings are
@@ -171,15 +169,15 @@ export interface SaveSetupInfo {
   default_slot: string;
   slot_confirmed: boolean;
   active_slot: string | null;
-  // "server_unreachable" means the server-saves fetch failed — the wizard MUST
-  // hold and offer a retry instead of treating the empty server_slots as
-  // authoritative (auto-confirming default would clobber real server saves on
-  // first sync). "not_found" is the same hold for a different cause: the
-  // server ANSWERED that it has no such ROM or device id, so the wizard must
+  // "server_unreachable" and "not_found" both mean the server-saves fetch
+  // failed, so the wizard MUST hold and offer a retry instead of treating the
+  // empty server_slots as authoritative (auto-confirming default would clobber
+  // real server saves on first sync). They differ only in cause: "not_found"
+  // is the server ANSWERING that it has no such ROM or device id, so it must
   // not report the server offline (#1570). See backend `get_save_setup_info`.
   recommended_action: "auto_confirm_default" | "show_wizard" | "server_unreachable" | "not_found";
-  // True whenever the server-saves query failed, whichever way — an explicit
-  // flag for call sites that route on the boolean rather than the enum.
+  // True whenever that query failed, either way — for call sites routing on a
+  // boolean rather than the enum.
   server_query_failed?: boolean;
 }
 
@@ -235,9 +233,9 @@ export type RollbackStatus =
   | { status: "version_deleted" }
   | { status: "unsupported" }
   | { status: "server_unreachable"; message: string }
-  // The server ANSWERED with a definitive 404 — it no longer has this ROM or
-  // the registered device id. Distinct from `server_unreachable` (retryable)
-  // and from `version_deleted` (one missing save inside a ROM it still has).
+  // The server ANSWERED 404 — no such ROM or device id. Distinct from
+  // `server_unreachable` (retryable) and `version_deleted` (one save missing
+  // from a ROM it still has).
   | { status: "not_found"; message: string }
   | { status: "conflict_blocked"; conflicts: SyncConflict[] }
   | { status: "preflight_failed"; errors: string[] }
@@ -246,8 +244,8 @@ export type RollbackStatus =
 export type ListFileVersionsResult =
   | { status: "ok"; versions: SaveVersionEntry[] }
   | { status: "multi_file_unsupported"; versions: SaveVersionEntry[] }
-  | { status: "server_unreachable"; message: string }
   // See RollbackStatus — the server answered, it just has no such entry.
+  | { status: "server_unreachable"; message: string }
   | { status: "not_found"; message: string };
 
 /** Discriminated-status result of `copySaveToSlot` — copies one server save into

src/utils/saveSetup.ts

@@ -9,8 +9,7 @@
  * `recommended_action` carries the explicit failure mode from the backend (see
  * `get_save_setup_info`); the call site MUST NOT treat an empty `server_slots`
  * array as authoritative on either path or it risks clobbering real server
- * saves on first sync. The two hold identically and differ only in copy — one
- * blames the connection, the other says RomM could not find what setup needs.
+ * saves on first sync. They hold identically and differ only in copy.
  */
 
 import type { SaveSetupInfo } from "../types";
@@ -26,9 +25,8 @@ export function resolveSaveSetupOutcome(info: SaveSetupInfo): SaveSetupOutcome {
   if (info.recommended_action === "server_unreachable") {
     return { kind: "server_unreachable" };
   }
-  // The server answered that it has no such ROM or device id. Same hold as
-  // above — an empty `server_slots` is no more authoritative here than on an
-  // outage, so this must NOT fall through to the auto-confirm branch (#1570).
+  // Same hold: an empty `server_slots` is no more authoritative on a 404 than
+  // on an outage, so this must NOT fall through to auto-confirm (#1570).
   if (info.recommended_action === "not_found") {
     return { kind: "not_found" };
   }
@@ -55,11 +53,9 @@ export const SERVER_UNREACHABLE_WIZARD_MESSAGE =
 export const SERVER_UNREACHABLE_TOAST_BODY =
   "Cannot configure save slot — RomM server is not reachable. Open the Saves tab to retry.";
 
-/** Copy for the `not_found` branch — the server answered, it just has no such
- *  ROM or device id. Deliberately does NOT say the game has no saves: the 404
- *  can come from this device's registration (a RomM database reset drops it),
- *  so claiming the saves don't exist would swap one lie for a more specific
- *  one. It states what RomM could not find, and that setup is on hold. */
+/** Copy for the `not_found` branch. Deliberately does NOT say the game has no
+ *  saves: the 404 can come from this device's registration (a RomM database
+ *  reset drops it), so that would swap one lie for a more specific one. */
 export const NOT_FOUND_WIZARD_MESSAGE =
   "RomM couldn't find the save data for this setup — setup paused. The game or this device may no longer be on the server.";
 
@@ -107,8 +103,8 @@ export async function applyLaunchGateSetupOutcome(
     deps.dispatchSavesTab();
     return "abort";
   }
-  // Same abort, honest cause. The launch must NOT proceed with save tracking
-  // unconfigured just because the failure was a 404 rather than an outage.
+  // Same abort, honest cause — a 404 must not let the launch proceed with save
+  // tracking unconfigured.
   if (outcome.kind === "not_found") {
     deps.toast(NOT_FOUND_TOAST_BODY);
     deps.dispatchSavesTab();
@@ -173,7 +169,6 @@ export async function applyWizardInitialSetupResult(result: SaveSetupInfo, deps:
     return;
   }
   if (result.recommended_action === "not_found") {
-    // Same hold, honest cause — never auto-confirm on an unproven server view.
     deps.setError(NOT_FOUND_WIZARD_MESSAGE);
     return;
   }