@krapwoo/ds-viewer 0.9.0 → 0.9.1

package/dist/cli/dev.js

@@ -6,7 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
-import { clearDevLock, liveDevLock, missingWorkspaceFiles, workspacePath, writeDevLock, writeWorkspace } from "./workspace.js";
+import { clearDevLock, liveDevLock, missingWorkspaceFiles, readEndpointRecord, workspacePath, writeDevLock, writeEndpointRecord, writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
 import { buildVersionStatus, createVersionController, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck, runUpdateCheck, statusFromCheck, writeUpdateFile, writeVersionFile, } from "./updateCheck.js";
@@ -362,6 +362,44 @@ export function repairWorkspaceIfMissing(deps) {
     sync(config);
     return { missing, repaired: true };
 }
+function listenOnce(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.removeListener('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            resolve(server.address().port);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, '127.0.0.1');
+    });
+}
+/** Resolves the update endpoint's real port: the stored record's port when it's actually free, a
+ *  fresh OS-assigned one otherwise. Tries the real bind directly, once — a separate "is this free?"
+ *  probe followed by a real bind would leave a window for something else to take the port in
+ *  between, and could never tell "a foreign process holds it" from "nothing does" anyway, which
+ *  Part 1 says this must never try to resolve: a bind failure for any reason falls back the same
+ *  way, never killing, probing, or assuming ownership of whatever holds it. Mutates
+ *  `secretHolder.secret` to a fresh value only on that fallback path — reusing the stored *port*
+ *  without the *secret* minted for it would pair a stale secret with an address nobody recorded. */
+export async function bindEndpointServer(server, secretHolder, storedPort) {
+    if (storedPort !== undefined) {
+        try {
+            const port = await listenOnce(server, storedPort);
+            return { port, reused: true };
+        }
+        catch {
+            // Taken — by a foreign process, a second catalog, anything. Fall through to a fresh port and
+            // secret below; never retry the same port or investigate what's holding it.
+        }
+    }
+    secretHolder.secret = randomBytes(24).toString('hex');
+    const port = await listenOnce(server, 0);
+    return { port, reused: false };
+}
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
@@ -480,14 +518,20 @@ export async function dev(initialConfig, devOptions = {}) {
     let updateEndpoint;
     let endpointServer;
     if (!devOptions.noUpdateEndpoint) {
+        // Reused across restarts so an already-open page's baked-in endpoint keeps working: the
+        // stored record's secret is the candidate here, replaced by `bindEndpointServer` itself only
+        // if the stored port turns out to be taken.
+        const stored = readEndpointRecord(config);
+        endpointDeps.secret = stored?.secret ?? secret;
         endpointServer = createUpdateEndpoint(endpointDeps);
-        await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
-        const endpointPort = endpointServer.address().port;
+        const binding = await bindEndpointServer(endpointServer, endpointDeps, stored?.port);
+        if (!binding.reused)
+            writeEndpointRecord(config, { port: binding.port, secret: endpointDeps.secret });
         // Printed for the same reason the Metro port above is printed: a developer (or Task 20's own
         // verification) checking the endpoint directly (e.g. with curl) needs its port — the secret
         // itself is never printed; the endpoint rejects anything that doesn't already have it.
-        console.log(`Update endpoint listening on 127.0.0.1:${endpointPort}`);
-        updateEndpoint = { baseUrl: `http://127.0.0.1:${endpointPort}`, secret };
+        console.log(`Update endpoint listening on 127.0.0.1:${binding.port}`);
+        updateEndpoint = { baseUrl: `http://127.0.0.1:${binding.port}`, secret: endpointDeps.secret };
     }
     else {
         console.log('Update endpoint disabled for this run (--no-update-endpoint).');

package/dist/cli/workspace.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { globBaseFolder } from "./glob.js";
 import { DEFAULT_WORKSPACE_DIR } from "./types.js";
@@ -151,6 +151,42 @@ export function liveDevLock(config, ownPid = process.pid) {
         return undefined;
     return lock;
 }
+const ENDPOINT_RECORD_FILE = 'endpoint.json';
+/** `bindEndpointServer` never writes a secret shorter than this (`randomBytes(24).toString('hex')`
+ *  is 48 characters), so a shorter one can only come from a hand-written record — but a
+ *  hand-written `{"secret":""}` is reused verbatim and `secretMatches` in `cli/endpoint.ts`
+ *  compares two zero-length buffers as equal, authenticating every request. Minor finding,
+ *  correction pass 4: treated the same as any other invalid record field below. */
+const MIN_SECRET_LENGTH = 32;
+/** The endpoint address a previous `dev` run bound, so a restart can reuse it instead of minting a
+ *  fresh one — otherwise an already-open page's baked-in endpoint goes stale on every restart.
+ *  Missing, corrupt, or partially-written is all treated the same: absent, so the caller falls
+ *  back to generating a fresh pair exactly as if `dev` had never run before. */
+export function readEndpointRecord(config) {
+    const recordPath = workspacePath(config, ENDPOINT_RECORD_FILE);
+    if (!existsSync(recordPath))
+        return undefined;
+    try {
+        const record = JSON.parse(readFileSync(recordPath, 'utf8'));
+        if (typeof record.port !== 'number' || record.port <= 0 || typeof record.secret !== 'string' || record.secret.length < MIN_SECRET_LENGTH)
+            return undefined;
+        return { port: record.port, secret: record.secret };
+    }
+    catch {
+        return undefined; // A partial write from a process that crashed mid-write owns nothing.
+    }
+}
+/** Written with mode 0600 — not a new exposure (the same secret already lands in cleartext inside
+ *  the generated `entry.tsx`, see `writeWorkspace`), but it must not be any more exposed than
+ *  that. `chmodSync` runs in addition to `writeFileSync`'s own `mode` option: that option only
+ *  applies when the file is newly created, so a pre-existing record left with looser permissions
+ *  would otherwise keep them across every later rewrite. */
+export function writeEndpointRecord(config, record) {
+    mkdirSync(workspacePath(config), { recursive: true });
+    const recordPath = workspacePath(config, ENDPOINT_RECORD_FILE);
+    writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(recordPath, 0o600);
+}
 /** The files `writeWorkspace` always writes: the ones that define the workspace to Expo and Metro.
  *  `babel.config.js` is conditional and the update files are written separately, so neither counts
  *  as missing here. */

package/native/catalog/UpdatePanel.tsx

@@ -1,10 +1,13 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
+import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { CatalogButton } from './CatalogButton';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
 import {
-  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, isRemoteOrigin, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+  acceptsDeliveredStatus, autoCheckHelp, backgroundPlanFetchOutcome, bumpLabel, checkedAgoLabel, resultNote, classifyRejectedFetch, daysAgoLabel, isAlreadyUpToDateError, isRemoteOrigin,
+  nextWaitingAttempt, PLAN_FETCH_ERROR, planShowsError, reachabilityNote, recoveredReachabilityState, remoteOriginLocalErrorMessage,
+  requestOrUnreachable, resolvePanelPhase, restartReachability, statusPollFailureOutcome, versionOverview,
+  type ReachabilityState, type UpdatePlanView, type UpdateStatusView,
 } from './updatePanelState';
 import type { UpdateNotice, VersionStatus } from './types';
 
@@ -19,6 +22,18 @@ function remoteOrigin(endpoint: Endpoint | undefined): boolean {
   return isRemoteOrigin(window.location.protocol, window.location.hostname);
 }
 
+/** Minor finding, Fable correction pass: bounds the `waiting` poller's own endpoint retry so a hung
+ *  request (a firewall `DROP`, not a clean refusal) still counts as a failure instead of blocking
+ *  it — and every later retry behind it — forever. */
+const PROBE_TIMEOUT_MS = 3000;
+
+/** Minor finding, correction pass 5: a single rejected `/update/status` while `updating` enters
+ *  `restarting` even when the server never actually went down (a one-off network hiccup, not a
+ *  real restart) — the Metro-origin probe below then never sees a failure, so it never reloads,
+ *  and `restarting` is otherwise terminal in-app. Bounds how long the page waits before offering a
+ *  manual way out, long enough for a real restart's own install-and-relaunch window. */
+const RESTART_RELOAD_TIMEOUT_MS = 15000;
+
 type Endpoint = { baseUrl: string; secret: string };
 
 async function authedFetch(endpoint: Endpoint, path: string, init: RequestInit = {}): Promise<Response> {
@@ -67,11 +82,42 @@ const NOTE_BOX_VARIANT = {
   ok: { box: { backgroundColor: CATALOG_COLOR.successSubtle }, text: { color: CATALOG_COLOR.success } },
 } as const;
 
-function NoteBox({ variant, children }: { variant: keyof typeof NOTE_BOX_VARIANT; children: React.ReactNode }) {
+/** `spinner` is the approved mockup's own `.row .spin` treatment (waiting only) — a leading
+ *  `ActivityIndicator`, the same primitive `CatalogButton`'s own `busy` state already uses, so
+ *  this isn't a new component or colour. */
+function NoteBox({
+  variant,
+  spinner,
+  live,
+  hint,
+  children,
+}: {
+  variant: keyof typeof NOTE_BOX_VARIANT;
+  spinner?: boolean;
+  /** Only the reachability notes (`waiting`/`recovered`/`stuck`) appear, change and disappear with
+   *  no user action — `ResultNoteBox` already establishes the `role="status"` pattern for its own
+   *  note at :209. Every other `NoteBox` stays silent to a screen reader, same as today. */
+  live?: boolean;
+  /** Minor finding, Fable correction pass #2: a recovery command (e.g. `npx ds-viewer dev`) used
+   *  to render outside this box, so a screen reader announced the problem via `live` but never
+   *  the fix sitting right next to it. Rendered inside the same `role="status"` container so both
+   *  are announced together. */
+  hint?: React.ReactNode;
+  children: React.ReactNode;
+}) {
   const v = NOTE_BOX_VARIANT[variant];
+  const text = <Text style={[styles.noteBoxText, v.text]}>{children}</Text>;
   return (
-    <View style={[styles.noteBox, v.box]}>
-      <Text style={[styles.noteBoxText, v.text]}>{children}</Text>
+    <View style={[styles.noteBox, v.box]} {...(live ? { role: 'status' as const } : {})}>
+      {spinner ? (
+        <View style={styles.noteBoxRow}>
+          <ActivityIndicator size="small" color={CATALOG_COLOR.accent} />
+          {text}
+        </View>
+      ) : (
+        text
+      )}
+      {hint}
     </View>
   );
 }
@@ -133,6 +179,44 @@ function Code({ children }: { children: string }) {
   return <Text style={styles.code}>{children}</Text>;
 }
 
+/** Replaces this page's normal content for `waiting`/`stuck` (approved mockup states 1 and
+ *  "Edge"): the version line stays, but the action goes unavailable rather than offering a press
+ *  that cannot work (decision 3), except `stuck`'s own `Reconnect`. */
+function ReachabilityOverride({
+  reachability,
+  header,
+  actionLabel,
+  onReconnect,
+}: {
+  reachability: ReachabilityState;
+  header: React.ReactNode;
+  actionLabel: string;
+  onReconnect: () => void;
+}) {
+  const note = reachabilityNote(reachability.phase);
+  return (
+    <>
+      {header}
+      <NoteBox
+        variant={note.variant}
+        spinner={note.spinner}
+        live
+        hint={note.hint && <Text style={styles.muted}>{note.hint.prefix}<Code>{note.hint.command}</Code></Text>}
+      >
+        {note.bold ? <Text style={styles.noteBoxBold}>{note.bold}</Text> : null}
+        {note.text}
+      </NoteBox>
+      <View style={styles.actions}>
+        {reachability.phase === 'stuck' ? (
+          <CatalogButton label="Reconnect" variant="secondary" onPress={onReconnect} />
+        ) : (
+          <CatalogButton label={actionLabel} disabled />
+        )}
+      </View>
+    </>
+  );
+}
+
 
 
 /**
@@ -150,6 +234,11 @@ function ResultNoteBox({
   status: Extract<UpdateStatusView, { phase: 'success' | 'failure' }>;
   current: string;
   latest?: string;
+  /** Named for its one legitimate "already running" caller (`noteBusy`/`starting`), but also true
+   *  while the panel is reachability-unavailable (decision 3) — a press can't work for either
+   *  reason, so the button renders the same flat-grey/muted-text treatment
+   *  `CatalogButton.disabled` already uses for both (Minor finding, Fable correction pass #2),
+   *  rather than the full-colour fill at reduced opacity that used to read as merely pressed. */
   busy: boolean;
   onAction: (kind: 'dismiss' | 'retry' | 'resume') => void;
 }) {
@@ -178,9 +267,13 @@ function ResultNoteBox({
           disabled={busy}
           accessibilityRole="button"
           accessibilityState={{ disabled: busy }}
-          style={({ pressed }) => [styles.resultButton, { backgroundColor: tone }, (pressed || busy) && styles.resultButtonPressed]}
+          style={({ pressed }) => [
+            styles.resultButton,
+            busy ? styles.resultButtonDisabled : { backgroundColor: tone },
+            pressed && !busy && styles.resultButtonPressed,
+          ]}
         >
-          <Text style={styles.resultButtonText}>{note.action.label}</Text>
+          <Text style={[styles.resultButtonText, busy && styles.resultButtonTextDisabled]}>{note.action.label}</Text>
         </Pressable>
         {note.hasLog && status.phase === 'failure' && (
           <Pressable onPress={() => setShowLog((v) => !v)} accessibilityRole="button" accessibilityState={{ expanded: showLog }}>
@@ -204,12 +297,20 @@ function VersionDetails({
   endpoint,
   onStatus,
   onCheck,
+  onUnreachable,
+  onReachable,
 }: {
   status: VersionStatus;
   endpoint?: Endpoint;
   onStatus: (next: VersionStatus) => void;
   /** Called as Check now starts (clears an update result note). */
   onCheck?: () => void;
+  /** `authedFetch` itself rejected (the endpoint socket is gone) — the page-wide reachability flow
+   *  takes over; this component shows nothing further for the attempt that triggered it. */
+  onUnreachable?: () => void;
+  /** The endpoint answered, whatever it said — clears a reachability note left over from an
+   *  earlier unreachable attempt, same as every other endpoint call on this page. */
+  onReachable?: () => void;
 }) {
   const [checking, setChecking] = useState(false);
   const [justChecked, setJustChecked] = useState(false);
@@ -225,19 +326,37 @@ function VersionDetails({
     setChecking(true);
     setJustChecked(false);
     setLocalError(undefined);
+    // `requestOrUnreachable` separates a rejected fetch (the endpoint socket is gone) from an
+    // actual response (401/409/502 included) — only the former goes to the shared reachability
+    // flow below; a real HTTP response keeps this `try` block's existing handling untouched.
+    const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/version/check', { method: 'POST' }));
+    if (outcome.kind === 'unreachable') {
+      // Critical finding, Fable correction pass (C4): a rejected `Origin` (no CORS headers at
+      // all) rejects `fetch` the same way a dead socket does — self-healing is meaningless for a
+      // page that can never use the endpoint, so this must keep the preserved remote-origin/
+      // tunnel message below instead of entering the page-wide reachability flow.
+      if (classifyRejectedFetch(remoteOrigin(endpoint)) === 'remote-origin') {
+        setLocalError(remoteOriginLocalErrorMessage());
+      } else {
+        onUnreachable?.();
+      }
+      setChecking(false);
+      return;
+    }
     try {
-      const res = await authedFetch(endpoint, '/version/check', { method: 'POST' });
+      const res = outcome.response;
       if (!res.ok) throw new Error(String(res.status));
       const next = (await res.json()) as VersionStatus;
       // A newer version moves the whole page into the update flow (the parent re-renders with it).
       setJustChecked(next.lastOutcome === 'ok' && !next.update);
       onStatus(next);
+      onReachable?.();
     } catch {
       setLocalError(remoteOrigin(endpoint)
         // The endpoint only answers its own origin, and it can install packages and restart the
         // server — so saying "restart the viewer" here would send the reader after a fault that
         // isn't there. The page itself is fine over a tunnel; only its actions are local.
-        ? 'This page is open from another address, and the viewer only takes actions from the machine it runs on. Open the catalog on that machine, or run npx ds-viewer update there.'
+        ? remoteOriginLocalErrorMessage()
         : 'Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
     } finally {
       setChecking(false);
@@ -248,14 +367,25 @@ function VersionDetails({
     if (!endpoint || saving) return;
     setSaving(true);
     setLocalError(undefined);
+    const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/version/auto-check', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ enabled }),
+    }));
+    if (outcome.kind === 'unreachable') {
+      // Same reasoning as `checkNow` above.
+      if (classifyRejectedFetch(remoteOrigin(endpoint)) === 'remote-origin') {
+        setLocalError(remoteOriginLocalErrorMessage());
+      } else {
+        onUnreachable?.();
+      }
+      setSaving(false);
+      return;
+    }
     try {
-      const res = await authedFetch(endpoint, '/version/auto-check', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ enabled }),
-      });
-      if (!res.ok) throw new Error(String(res.status));
-      onStatus((await res.json()) as VersionStatus);
+      if (!outcome.response.ok) throw new Error(String(outcome.response.status));
+      onStatus((await outcome.response.json()) as VersionStatus);
+      onReachable?.();
     } catch {
       setLocalError('Couldn’t save the setting. Try again.');
     } finally {
@@ -358,6 +488,13 @@ export function UpdatePanel({
   headingRef?: React.Ref<View>;
 }) {
   const [status, setStatus] = useState<UpdateStatusView>({ phase: 'idle' });
+  // Critical finding, Fable correction pass (C6): mirrors `status`, read instead of a value
+  // assigned inside a `setStatus` updater — updaters run during React's render phase, not at
+  // dispatch, so a read-after-write inside one can see stale or re-invoked state.
+  const statusRef = useRef<UpdateStatusView>(status);
+  useEffect(() => {
+    statusRef.current = status;
+  }, [status]);
   const [planResult, setPlanResult] = useState<UpdatePlanView | { error: string } | undefined>(undefined);
   // Critical finding, Fable correction pass: while this is true, the endpoint's own `/update` POST
   // is in flight (re-planning before it can even start) — **Update now** must disable itself for
@@ -366,31 +503,175 @@ export function UpdatePanel({
   const [starting, setStarting] = useState(false);
   const pollRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
 
+  // Important finding, Fable correction pass (I4): the catalog is a single-page app, so a probe
+  // started before the user navigates away can still resolve after this component unmounts — set
+  // once, on unmount, and checked after every `await` below before any state is dispatched or the
+  // page is reloaded out from under whatever's there now.
+  const cancelledRef = useRef(false);
+  useEffect(() => () => {
+    cancelledRef.current = true;
+  }, []);
+
+  // The page-wide reachability flow (approved `.hermes-task/approved-unreachable-states.html`):
+  // shared by every endpoint call below and by `VersionDetails`' own calls, since the two UI modes
+  // are never visible at once. `undefined` means "nothing wrong" — the same convention
+  // `UpdateStatusView`'s `idle` phase already uses for "nothing in flight".
+  const [reachability, setReachability] = useState<ReachabilityState | undefined>(undefined);
+  const reachabilityRef = useRef<ReachabilityState | undefined>(undefined);
+  useEffect(() => {
+    reachabilityRef.current = reachability;
+  }, [reachability]);
+
+  // Critical finding, Fable correction pass (C4): a page that can never use the endpoint at all
+  // (a tunnel, or a plain `127.0.0.1` the endpoint's own Origin check rejects) gets no
+  // self-healing — see `routeUnreachable` below. Kept apart from `reachability` because the two
+  // conditions are mutually exclusive and need entirely different, non-retrying treatment.
+  const [remoteOriginError, setRemoteOriginError] = useState(false);
+
+  // Called by `routeUnreachable` below for a rejected fetch this page can actually recover from.
+  // Final slice: a stable endpoint address means the `waiting` poller's own direct endpoint retry
+  // (below) is the whole recovery mechanism, so this just advances the bounded attempt counter —
+  // no origin probe, no reload, no marker.
+  const markUnreachable = useCallback(() => {
+    if (!isWeb()) return;
+    setReachability((prev) => nextWaitingAttempt(prev ?? { phase: 'waiting', attempts: 0 }));
+  }, []);
+
+  // Critical finding, Fable correction pass (C4): the one place every rejected-fetch call site on
+  // this page routes through. `cli/endpoint.ts` answers a rejected `Origin` with no CORS headers
+  // at all, so the browser blocks the response and `fetch` rejects exactly like a dead socket —
+  // without this check first, that rejection used to enter the reachability flow and reload, then
+  // sit there "still not answering" forever, for a page that was never going to be able to act
+  // regardless.
+  const routeUnreachable = useCallback(() => {
+    if (classifyRejectedFetch(remoteOrigin(endpoint)) === 'remote-origin') {
+      setRemoteOriginError(true);
+      return;
+    }
+    markUnreachable();
+  }, [endpoint, markUnreachable]);
+
+  // Important finding, Fable correction pass #2: a background poll (`fetchStatus`/`fetchPlan`,
+  // both run unprompted on mount and on a plain interval) must never latch `remoteOriginError` —
+  // that replaces the whole page with a red error for every non-`localhost` page (a tunnel, LAN
+  // address, reverse proxy, or plain `127.0.0.1`) the instant it loads, something the user never
+  // triggered. Only a user-initiated call (`startUpdate`, `dismissResult`, `resumeResult`, and
+  // `VersionDetails`' own handlers, which already own their local copy of the message) may show
+  // that error, via `routeUnreachable` above. A genuinely unreachable endpoint (not a
+  // remote-origin refusal) still enters the reachability flow either way.
+  // Correction pass 3: reports back whether it actually did anything (`true` once it has entered
+  // the reachability flow, `false` when it declined to for a remote-origin page) — a background
+  // caller that can't just swallow a refusal (`fetchPlan` below) needs to know so it can apply its
+  // own fallback instead of leaving required state unset.
+  const routeUnreachableInBackground = useCallback((): boolean => {
+    if (classifyRejectedFetch(remoteOrigin(endpoint)) === 'remote-origin') return false;
+    markUnreachable();
+    return true;
+  }, [endpoint, markUnreachable]);
+
+  // Called by any endpoint call on this page that got a real response — clears a reachability
+  // note left over from an earlier unreachable attempt (a no-op the vast majority of the time).
+  const markReachable = useCallback(() => {
+    if (!isWeb()) return;
+    // Important finding, Fable correction pass (I2): computed from the ref, not from inside the
+    // `setReachability` updater — a re-invoked updater could otherwise read the state it just set
+    // on a prior invocation and settle back on "nothing to recover," silently losing the approved
+    // "Reconnected." note.
+    const next = recoveredReachabilityState(reachabilityRef.current);
+    if (next) setReachability(next);
+  }, []);
+
+  // "Recovered: … auto-dismissing" (approved design) — a plain timeout, cleared on unmount or on
+  // leaving the state early (e.g. another unreachable attempt right after recovering).
+  useEffect(() => {
+    if (reachability?.phase !== 'recovered') return;
+    const timeout = setTimeout(() => setReachability(undefined), 3000);
+    return () => clearTimeout(timeout);
+  }, [reachability?.phase]);
+
+  // Part 3 (final slice): one explicit, user-initiated reload — the only reload left anywhere in
+  // this flow. Restarts the bounded cycle first so that if `window.location.reload()` turns out
+  // to be a no-op (some embedded webviews block it), the page falls back to retrying the endpoint
+  // in place instead of sitting on `stuck` with a press that silently did nothing.
+  const reconnect = useCallback(() => {
+    if (!isWeb()) return;
+    setReachability(restartReachability());
+    window.location.reload();
+  }, []);
+
   const fetchStatus = useCallback(async () => {
     if (!endpoint || !isWeb()) return;
+    const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/update/status'));
+    if (outcome.kind === 'unreachable') {
+      // Errata 2a: a failed poll while an update was in flight or already restarting means "still
+      // restarting," not unreachable — the dedicated restart-handoff effect below already owns
+      // that recovery, so this page-wide flow only takes over for every other phase.
+      const fallback = statusPollFailureOutcome(statusRef.current.phase);
+      if (fallback) {
+        setStatus(fallback);
+      } else {
+        routeUnreachableInBackground();
+      }
+      return;
+    }
     try {
-      const res = await authedFetch(endpoint, '/update/status');
-      setStatus((await res.json()) as UpdateStatusView);
+      // Critical finding, Fable correction pass (C1): a delivered-but-unusable response (a stale
+      // secret on a reused port answers 401 `text/plain`, with CORS headers, so it's delivered and
+      // `.json()` rejects) is not "unreachable" — the endpoint answered — so it must not enter the
+      // reachability flow; fall back the same way a failed poll mid-update already does.
+      if (!outcome.response.ok) throw new Error(String(outcome.response.status));
+      const next = (await outcome.response.json()) as UpdateStatusView;
+      // Correction pass 4 (Critical): once restarted, this poll reaches the server on the same
+      // reused address and succeeds before Metro has served the new bundle — only the Metro-origin
+      // reload poller below may move the page out of `restarting`.
+      if (acceptsDeliveredStatus(statusRef.current.phase, next.phase)) setStatus(next);
+      markReachable();
     } catch {
-      // Errata 2a: the endpoint's own process exits mid-restart — a failed poll while an update
-      // was in flight or already restarting means "still restarting," not "idle again."
-      setStatus((prev) => (prev.phase === 'updating' || prev.phase === 'restarting' ? { phase: 'restarting' } : prev));
+      const fallback = statusPollFailureOutcome(statusRef.current.phase);
+      if (fallback) setStatus(fallback);
     }
-  }, [endpoint]);
+  }, [endpoint, routeUnreachableInBackground, markReachable]);
 
-  const fetchPlan = useCallback(async () => {
-    if (!endpoint || !isWeb()) return;
+  // Part 4 (final slice): returns whether the endpoint was actually reached, so a caller that's
+  // about to claim "Reconnected. Everything below is current." (the waiting poller's success
+  // branch, below) can gate that claim on this fetch having actually succeeded, instead of
+  // assuming it did just because an earlier call in the same tick did.
+  // Correction pass 5 (Important): also returns the plan it just stored, taken from the fetch
+  // itself rather than left for the caller to read back from a ref — a ref filled in by a passive
+  // effect only updates once React flushes effects after this render, which is always later than
+  // the very next line of an async caller, so that read would deterministically see the prior
+  // plan, never this one.
+  const fetchPlan = useCallback(async (): Promise<{ reached: boolean; result?: UpdatePlanView | { error: string } }> => {
+    if (!endpoint || !isWeb()) return { reached: true };
     // Important finding, Fable correction pass: an unhandled rejection here (the endpoint
     // unreachable, CORS-blocked, or mid-restart) previously left `planResult` `undefined` forever
     // — the panel sat on "Checking…" with no way out. The same error shape `buildUpdatePlan`
-    // itself returns on failure drives the existing `offline` phase.
+    // itself returns on failure drives the existing `offline` phase. A genuinely unreachable
+    // endpoint (the socket itself is gone) now goes through the shared reachability flow instead.
+    const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/plan', { method: 'POST' }));
+    if (outcome.kind === 'unreachable') {
+      // Correction pass 3: a remote-origin page's refusal leaves `routeUnreachableInBackground`
+      // reporting `false` — apply the same offline plan-error outcome the `catch` below already
+      // shows for every other plan failure, rather than leaving `planResult` (and the panel) stuck
+      // on `undefined`/"Checking…" forever.
+      const fallback = backgroundPlanFetchOutcome(routeUnreachableInBackground());
+      if (fallback) setPlanResult(fallback);
+      return { reached: false };
+    }
     try {
-      const res = await authedFetch(endpoint, '/plan', { method: 'POST' });
-      setPlanResult((await res.json()) as UpdatePlanView | { error: string });
+      // Critical finding, Fable correction pass (C1): see `fetchStatus` above — a delivered 401
+      // (stale secret) must fall back to the pre-existing offline plan-error note, with a working
+      // **Try again**, instead of hanging forever on a rejected `.json()`.
+      if (!outcome.response.ok) throw new Error(String(outcome.response.status));
+      const result = (await outcome.response.json()) as UpdatePlanView | { error: string };
+      setPlanResult(result);
+      markReachable();
+      return { reached: true, result };
     } catch {
-      setPlanResult({ error: "Couldn't prepare the update. You may be offline, or npm didn't respond. Nothing was changed." });
+      setPlanResult(PLAN_FETCH_ERROR);
+      return { reached: true, result: PLAN_FETCH_ERROR };
     }
-  }, [endpoint]);
+  }, [endpoint, routeUnreachableInBackground, markReachable]);
 
   useEffect(() => {
     // Errata 1c: never call `fetchPlan` when there is no update to plan for.
@@ -399,6 +680,74 @@ export function UpdatePanel({
     });
   }, [fetchStatus, fetchPlan, update]);
 
+  // Final slice: with a stable endpoint address, this direct retry is the whole recovery
+  // mechanism — no origin probe, no reload. A restart lands on the same port and secret, so this
+  // keeps failing only while the viewer is actually down, and succeeds the moment it's back.
+  useEffect(() => {
+    if (!isWeb() || !endpoint || reachability?.phase !== 'waiting') return;
+    // Important finding, Fable correction pass (I4): stacked probes (if one tick's probe is still
+    // in flight when the next fires) are refused rather than piling up.
+    let inFlight = false;
+    const interval = setInterval(async () => {
+      if (inFlight) return;
+      inFlight = true;
+      try {
+        // Minor finding, Fable correction pass #2: this retry sits behind the `inFlight` latch
+        // above with no timeout of its own — a hung request (a firewall `DROP` on the stale port,
+        // not a clean refusal) would otherwise pin `inFlight` forever, blocking every later probe
+        // and never reaching `stuck`.
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+        let outcome: Awaited<ReturnType<typeof requestOrUnreachable>>;
+        try {
+          outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/update/status', { signal: controller.signal }));
+        } finally {
+          clearTimeout(timeout);
+        }
+        if (cancelledRef.current) return;
+        if (outcome.kind === 'ok' && outcome.response.ok) {
+          // Important finding, Fable correction pass #2: `markReachable` only flips the
+          // reachability phase to `recovered` — it never refreshes `status` or re-runs
+          // `fetchPlan`, so the note's "Everything below is current" was false by construction,
+          // and a page still waiting on its first plan (`planResult === undefined` at mount)
+          // was left stranded on "Checking…" with no way out. Feed the response through, and
+          // refresh the plan too, *before* calling `markReachable` — so the claim is true by
+          // the time it's shown.
+          try {
+            setStatus((await outcome.response.json()) as UpdateStatusView);
+          } catch {
+            // The regular poll (once `phase` leaves `waiting`) retries `/update/status` on its
+            // own; `markReachable` below still ends the reachability flow cleanly.
+          }
+          // Part 4: a delivered status does not, by itself, make "Everything below is current"
+          // true — the plan refresh it's paired with must also have actually reached the
+          // endpoint. Without this gate, a plan fetch that failed right after a successful status
+          // poll still showed the recovered note while the endpoint was gone, tore the poller
+          // down, and could strand the panel on "Checking…" with no button.
+          const planOutcome = update ? await fetchPlan() : { reached: true };
+          if (cancelledRef.current) return;
+          // Minor finding, correction pass 4: `/plan` answers 200 with an `{ error }` body for the
+          // offline case, so a reached-but-erroring plan still leaves this reached — showing
+          // "Reconnected. Everything below is current." directly above the red offline note it
+          // contradicts. Suppress the note instead of changing the gate above: leave the page on
+          // its `offline` state (with a working **Try again**) rather than reporting a reachability
+          // failure, which would distort the waiting poller's own bounded-attempt counter.
+          // Correction pass 5 (Important): `planShowsError` reads `planOutcome.result` — the value
+          // this very `fetchPlan()` call just stored — never a ref a passive effect fills in later.
+          if (planOutcome.reached) {
+            if (planShowsError(planOutcome.result)) setReachability(undefined);
+            else markReachable();
+          }
+          return;
+        }
+        setReachability((prev) => (prev && prev.phase === 'waiting' ? nextWaitingAttempt(prev) : prev));
+      } finally {
+        inFlight = false;
+      }
+    }, 500);
+    return () => clearInterval(interval);
+  }, [reachability?.phase, endpoint, markReachable, fetchPlan, update]);
+
   // A finished update (success or failure) shows as a note at the top; the page under it behaves
   // as if idle, so Check now, the switch and a newer update all keep working.
   const result = status.phase === 'success' || status.phase === 'failure' ? status : undefined;
@@ -406,13 +755,36 @@ export function UpdatePanel({
   const [noteBusy, setNoteBusy] = useState(false);
   const dismissResult = useCallback(async () => {
     if (!endpoint || !isWeb()) return;
+    // Important finding, Fable correction pass (I3): routed through the same reachability flow as
+    // every other endpoint call, instead of silently swallowing a rejected fetch with **Got it**
+    // left doing nothing visible.
+    const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/update/dismiss', { method: 'POST' }));
+    if (outcome.kind === 'unreachable') {
+      routeUnreachable();
+      return;
+    }
     try {
-      const res = await authedFetch(endpoint, '/update/dismiss', { method: 'POST' });
-      if (res.ok) setStatus((await res.json()) as UpdateStatusView);
+      if (!outcome.response.ok) throw new Error(String(outcome.response.status));
+      setStatus((await outcome.response.json()) as UpdateStatusView);
+      markReachable();
     } catch {
       // The note stays; the next status poll or reload settles it.
     }
-  }, [endpoint]);
+  }, [endpoint, routeUnreachable, markReachable]);
+
+  // Important finding, Fable correction pass (I3): **Finish migration** / **Rerun doctor** had no
+  // guard at all — a rejected fetch here did nothing visible. Routed through the same reachability
+  // flow as every other endpoint call.
+  const resumeResult = useCallback(async () => {
+    if (!endpoint || !isWeb()) return;
+    const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/update/resume', { method: 'POST' }));
+    if (outcome.kind === 'unreachable') {
+      routeUnreachable();
+      return;
+    }
+    markReachable();
+    await fetchStatus();
+  }, [endpoint, routeUnreachable, markReachable, fetchStatus]);
 
   // Polls `/update/status` at a plain interval while an update is in flight — design §5 never
   // asks for push/websocket progress, only "the panel shows progress."
@@ -422,6 +794,19 @@ export function UpdatePanel({
     return () => clearInterval(pollRef.current);
   }, [phase, fetchStatus]);
 
+  // Minor finding, correction pass 5: offers a manual way out of `restarting` once it's held for
+  // longer than a real restart should take — the one case the bounded Metro-origin probe below
+  // cannot resolve on its own (the server never actually went down, so it never sees a failure).
+  const [restartTimedOut, setRestartTimedOut] = useState(false);
+  useEffect(() => {
+    if (phase !== 'restarting') {
+      setRestartTimedOut(false);
+      return;
+    }
+    const timeout = setTimeout(() => setRestartTimedOut(true), RESTART_RELOAD_TIMEOUT_MS);
+    return () => clearTimeout(timeout);
+  }, [phase]);
+
   // Restart handoff step 4 (design §5): once the server reports "restarting", Metro itself (not
   // this endpoint — the endpoint's own process is about to exit) is polled on the *page's own
   // origin* until it answers again, then the page reloads onto the new version. Errata 2b: reload
@@ -433,6 +818,9 @@ export function UpdatePanel({
     const interval = setInterval(() => {
       fetch(window.location.origin, { method: 'HEAD' })
         .then((res) => {
+          // Important finding, Fable correction pass (I4): the catalog is a single-page app — a
+          // probe started before the user navigated away can still resolve after unmount.
+          if (cancelledRef.current) return;
           if (res.ok && hadFailure) {
             clearInterval(interval);
             window.location.reload();
@@ -448,25 +836,31 @@ export function UpdatePanel({
   const startUpdate = useCallback(async () => {
     if (!endpoint) return;
     setStarting(true);
+    // Critical finding, Fable correction pass (C2): `try`/`finally` so a rejection from
+    // `fetchPlan()`/`fetchStatus()` below can never leave **Update now** disabled on "Starting…"
+    // until a manual reload.
     try {
-      const res = await authedFetch(endpoint, '/update', { method: 'POST' });
+      // Important finding, Fable correction pass: a failed `POST /update` must not leave the panel
+      // stuck mid-click with no way forward — a genuinely unreachable endpoint now goes through the
+      // shared reachability flow instead of the offline plan-error text.
+      const outcome = await requestOrUnreachable(() => authedFetch(endpoint, '/update', { method: 'POST' }));
+      if (outcome.kind === 'unreachable') {
+        routeUnreachable();
+        return;
+      }
       // A non-202 (409 dirty/already-running, or 502 "couldn't prepare") means a file was dirtied
       // — or the plan went stale — after this panel's own `ready` plan was fetched; re-fetching the
       // plan surfaces the `dirty`/`offline` phase instead of silently staying on `ready` forever
       // (Minor finding, Fable correction pass).
-      if (res.status !== 202) {
+      if (outcome.response.status !== 202) {
         await fetchPlan();
-        return;
+      } else {
+        await fetchStatus();
       }
-      await fetchStatus();
-    } catch {
-      // Important finding, Fable correction pass: same reasoning as `fetchPlan` above — a failed
-      // `POST /update` must not leave the panel stuck mid-click with no way forward.
-      setPlanResult({ error: "Couldn't prepare the update. You may be offline, or npm didn't respond. Nothing was changed." });
     } finally {
       setStarting(false);
     }
-  }, [endpoint, fetchPlan, fetchStatus]);
+  }, [endpoint, fetchPlan, fetchStatus, routeUnreachable]);
 
   const plan = planResult && !('error' in planResult) ? planResult : undefined;
 
@@ -477,11 +871,53 @@ export function UpdatePanel({
   // once the footer link existed). `content` is computed per phase below, then wrapped once.
   let content: React.ReactNode = null;
 
-  if (!update) {
+  // Takes priority over every other phase below — it replaces whichever of the two UI modes
+  // (an update pending, or just the installed version) was about to render, since neither can be
+  // trusted while the endpoint itself is unreachable. Never shown mid-restart: that recovery is
+  // already owned by the dedicated restart-handoff effect above (see `fetchStatus`).
+  const reachabilityOverride = reachability && reachability.phase !== 'recovered' && phase !== 'updating' && phase !== 'restarting';
+
+  if (remoteOriginError) {
+    // Critical finding, Fable correction pass (C4): a page that can never use the endpoint gets
+    // no self-healing at all — just the preserved remote-origin/tunnel message, with nothing to
+    // retry (there is nothing a reload or a probe could fix here).
+    content = (
+      <>
+        {update ? (
+          <VersionsHeader current={update.current} latest={update.latest} breaking={update.breaking} releasedAt={update.releasedAt} />
+        ) : versionStatus ? (
+          <View style={styles.versionsRow}><Text style={styles.versionsText}>{versionStatus.current}</Text></View>
+        ) : null}
+        <NoteBox variant="err">{remoteOriginLocalErrorMessage()}</NoteBox>
+      </>
+    );
+  } else if (reachabilityOverride && reachability) {
+    content = (
+      <ReachabilityOverride
+        reachability={reachability}
+        header={update ? (
+          <VersionsHeader current={update.current} latest={update.latest} breaking={update.breaking} releasedAt={update.releasedAt} />
+        ) : versionStatus ? (
+          // Minor finding, Fable correction pass: without `versionStatus` there's no version to
+          // show at all — fall back to the note-only layout instead of an empty 2xl row.
+          <View style={styles.versionsRow}><Text style={styles.versionsText}>{versionStatus.current}</Text></View>
+        ) : null}
+        actionLabel={update ? 'Update now' : 'Check now'}
+        onReconnect={reconnect}
+      />
+    );
+  } else if (!update) {
     // Errata 1c: no update known (disabled, offline, or genuinely up to date). `status` still
     // reflects a just-finished update read from the (surviving) endpoint across the reload.
     content = versionStatus ? (
-        <VersionDetails status={versionStatus} endpoint={endpoint} onStatus={onVersionStatus ?? (() => {})} onCheck={result ? dismissResult : undefined} />
+        <VersionDetails
+          status={versionStatus}
+          endpoint={endpoint}
+          onStatus={onVersionStatus ?? (() => {})}
+          onCheck={result ? dismissResult : undefined}
+          onUnreachable={markUnreachable}
+          onReachable={markReachable}
+        />
       ) : (
         <NoteBox variant="ok">You’re already up to date.</NoteBox>
       );
@@ -583,11 +1019,18 @@ export function UpdatePanel({
           {' This page reloads by itself.'}
         </NoteBox>
         <Text style={styles.muted}>If it doesn’t come back, run <Code>npx ds-viewer dev</Code> in your terminal.</Text>
+        {restartTimedOut && (
+          <View style={styles.actions}>
+            <CatalogButton label="Reload" variant="secondary" onPress={() => isWeb() && window.location.reload()} />
+          </View>
+        )}
       </>
     );
 
   }
 
+  const recoveredNote = reachability?.phase === 'recovered' ? reachabilityNote('recovered') : undefined;
+
   return (
     <View style={styles.wrap}>
       <Text style={styles.crumb}>{`${appName} / DS Viewer`}</Text>
@@ -601,23 +1044,32 @@ export function UpdatePanel({
           status={result}
           current={update?.current ?? versionStatus?.current ?? ''}
           latest={update?.latest}
-          busy={noteBusy || starting}
+          // Important finding, Fable correction pass (I3): disabled while unreachable (or on a
+          // page that can never be) — otherwise the calm reachability note and a live, enabled
+          // **Retry update** / **Finish migration** / **Rerun doctor** show together, for the
+          // panel's most consequential buttons, contradicting decision 3.
+          busy={noteBusy || starting || remoteOriginError || Boolean(reachability && reachability.phase !== 'recovered')}
           onAction={async (kind) => {
             if (!endpoint) return;
             setNoteBusy(true);
             try {
               if (kind === 'dismiss') await dismissResult();
               else if (kind === 'retry') await startUpdate();
-              else {
-                await authedFetch(endpoint, '/update/resume', { method: 'POST' });
-                await fetchStatus();
-              }
+              else await resumeResult();
             } finally {
               setNoteBusy(false);
             }
           }}
         />
       )}
+      {recoveredNote && (
+        // Minor finding, Fable correction pass: reads `variant`/`spinner` from the same
+        // `reachabilityNote('recovered')` the copy comes from, instead of hardcoding `variant="ok"`
+        // separately, so the approved copy and its treatment have one source.
+        <NoteBox variant={recoveredNote.variant} spinner={recoveredNote.spinner} live>
+          {recoveredNote.text}
+        </NoteBox>
+      )}
       {content}
     </View>
   );
@@ -635,7 +1087,12 @@ const styles = StyleSheet.create({
   // The catalog's smallest control size (the major banner's close button), filled in the note's colour.
   resultButton: { height: 32, paddingHorizontal: 14, borderRadius: 16, alignItems: 'center', justifyContent: 'center' },
   resultButtonPressed: { opacity: 0.8 },
+  // Minor finding, Fable correction pass #2: the same flat-grey treatment `CatalogButton.disabled`
+  // uses, so "unavailable" doesn't read as merely "pressed" (the note's own full-colour fill at
+  // reduced opacity).
+  resultButtonDisabled: { backgroundColor: CATALOG_COLOR.controlDisabled },
   resultButtonText: { color: '#ffffff', fontSize: CATALOG_TYPE.sm, fontWeight: '700' },
+  resultButtonTextDisabled: { color: CATALOG_COLOR.controlDisabledText },
   resultLink: { fontSize: CATALOG_TYPE.panelHeading, fontWeight: '700', textDecorationLine: 'underline' },
   crumb: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
   headingTarget: { marginTop: 4, marginBottom: 6 },
@@ -681,7 +1138,8 @@ const styles = StyleSheet.create({
   fileReasonDirty: { color: CATALOG_COLOR.warning, fontWeight: '700' },
   actions: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 20 },
   noteBox: { borderRadius: CATALOG_RADIUS.md, padding: 12, marginTop: 18 },
-  noteBoxText: { fontSize: CATALOG_TYPE.md },
+  noteBoxRow: { flexDirection: 'row', alignItems: 'flex-start', gap: 9 },
+  noteBoxText: { fontSize: CATALOG_TYPE.md, flexShrink: 1 },
   noteBoxBold: { fontWeight: '700' },
   steps: { marginTop: 12 },
   stepRow: { flexDirection: 'row', alignItems: 'center', gap: 10, paddingVertical: 6 },

package/native/catalog/updatePanelState.ts

@@ -219,3 +219,176 @@ export function resultNote(
 export function isRemoteOrigin(protocol: string, hostname: string): boolean {
   return !(protocol === 'http:' && hostname === 'localhost');
 }
+
+/** `VersionDetails`' own near-miss message, when the endpoint answered with a non-ok status (not
+ *  a rejected fetch) and the page is open from a tunnelled/remote origin. Pulled out as its own
+ *  function only so a test can pin it exactly — the approved design leaves this condition alone
+ *  ("Keep the existing distinct remote-origin/tunnel message exactly as is"). */
+export function remoteOriginLocalErrorMessage(): string {
+  return 'This page is open from another address, and the viewer only takes actions from the machine it runs on. Open the catalog on that machine, or run npx ds-viewer update there.';
+}
+
+/** The result of one endpoint call, classified the one way that matters for self-healing: did
+ *  `fetch` itself reject (the socket is simply gone — *unreachable*, see the implementation
+ *  brief), or did it resolve with a response at all, however unhappy (401/409/502 included — the
+ *  endpoint answered, so the caller's existing status/body handling is unchanged and untouched by
+ *  this module). Every endpoint call on the update page routes through this one function so "one
+ *  condition has one treatment" instead of each call site re-deriving it. */
+export type EndpointOutcome = { kind: 'ok'; response: Response } | { kind: 'unreachable' };
+
+export async function requestOrUnreachable(doFetch: () => Promise<Response>): Promise<EndpointOutcome> {
+  try {
+    return { kind: 'ok', response: await doFetch() };
+  } catch {
+    return { kind: 'unreachable' };
+  }
+}
+
+/** Critical finding, Fable correction pass: `cli/endpoint.ts` answers a rejected `Origin` with
+ *  403 and *no* CORS headers, so the browser blocks the response and the page's own `fetch`
+ *  rejects — exactly like a genuinely dead socket. Without this check, that rejection was routed
+ *  straight into the page-wide reachability flow, which reloads and then polls forever for a
+ *  server that was never down; self-healing is meaningless for a page that can never use the
+ *  endpoint in the first place (a tunnel, or `isRemoteOrigin`'s own `127.0.0.1` case). Every call
+ *  site with a rejected fetch must check this *before* calling into the reachability flow, and
+ *  keep showing `remoteOriginLocalErrorMessage()` instead. */
+export function classifyRejectedFetch(isRemoteOriginPage: boolean): 'remote-origin' | 'unreachable' {
+  return isRemoteOriginPage ? 'remote-origin' : 'unreachable';
+}
+
+/** The pre-existing offline plan-error outcome (`fetchPlan`'s own `catch`) — pulled out so the one
+ *  other place that needs it (below) can't drift from this wording. */
+export const PLAN_FETCH_ERROR: { error: string } = { error: "Couldn't prepare the update. You may be offline, or npm didn't respond. Nothing was changed." };
+
+/** Correction pass 3: a background `fetchPlan` whose fetch was rejected routes through
+ *  `routeUnreachableInBackground`, which refuses to act for a remote-origin page (it must never
+ *  latch the page-wide `remoteOriginError` state for a call the user didn't make — correction pass
+ *  #2). That refusal used to be the end of it: `planResult` stayed `undefined` forever, and
+ *  `resolvePanelPhase` reads that as `'checking'` with no button and no way out. `handled` is
+ *  whatever that route reports back — `true` once it has entered the reachability flow (which owns
+ *  the page from there), `false` when it declined to act. Only the `false` case needs anything
+ *  here: fall back to the exact same plan-error note (and working **Try again**) the pre-existing
+ *  `catch` already shows for every other kind of plan failure. */
+export function backgroundPlanFetchOutcome(handled: boolean): { error: string } | undefined {
+  return handled ? undefined : PLAN_FETCH_ERROR;
+}
+
+/** Critical finding, Fable correction pass: the restart-handoff rule ("a failed `/update/status`
+ *  poll while an update was already in flight or restarting means 'still restarting,' not
+ *  unreachable") used to be decided by reading a value assigned inside the very `setStatus`
+ *  updater that decided it — updaters run during React's render phase, not at dispatch, so under
+ *  any pending update the read could see stale or re-invoked state. Pulled out as a pure function
+ *  of the *already-committed* phase (read from a ref, never from inside an updater) so the
+ *  decision is both correct and independently testable. `undefined` means "not mid-update": the
+ *  caller must still classify the failure itself (unreachable vs. remote-origin, vs. a delivered
+ *  but unusable response). */
+export function statusPollFailureOutcome(currentPhase: UpdateStatusView['phase']): UpdateStatusView | undefined {
+  return currentPhase === 'updating' || currentPhase === 'restarting' ? { phase: 'restarting' } : undefined;
+}
+
+/** Correction pass 4 (Critical): a stable endpoint address means the restarted server answers the
+ *  already-open page's poll *before* Metro has served the new bundle — same host, same pinned
+ *  Metro origin, same reused secret, so the poll succeeds and would otherwise accept the delivered
+ *  `{ phase: 'success' }` onto the still-old page. `restarting` must be terminal for the page: only
+ *  the Metro-origin reload poller (which owns the actual reload) may leave it, by delivering
+ *  `'restarting'` right back — every other delivered phase while `restarting` is stale and must be
+ *  ignored. */
+export function acceptsDeliveredStatus(current: UpdateStatusView['phase'], next: UpdateStatusView['phase']): boolean {
+  return current !== 'restarting' || next === 'restarting';
+}
+
+/** Correction pass 5 (Important): whether a just-fetched plan is the offline error note rather
+ *  than a usable plan — `/plan` answers 200 with an `{ error }` body for that case, so a reached
+ *  plan fetch alone doesn't mean "Everything below is current." Takes the plan straight from the
+ *  fetch that produced it, never from a ref a passive effect fills in later, so this reads the
+ *  value that was actually just stored. */
+export function planShowsError(result?: UpdatePlanView | { error: string }): boolean {
+  return result !== undefined && 'error' in result && !isAlreadyUpToDateError(result);
+}
+
+/** The approved design's unreachable-recovery states (`waiting`/`stuck` replace this page's normal
+ *  content; `recovered` is a transient banner over content that's already current). Never
+ *  `'ok'`/absent here — the panel represents "nothing wrong" as no `ReachabilityState` at all, the
+ *  same way `UpdateStatusView`'s `idle` phase represents nothing in flight.
+ *
+ *  Final slice: a stable endpoint address (`cli/dev.ts` now reuses its port and secret across
+ *  restarts) means an ordinary restart recovers through the `waiting` poller's own direct endpoint
+ *  retry alone — no reload is needed, so there is no `reconnecting` phase anymore, and nothing in
+ *  this module ever calls `window.location.reload()`. The only reload left is the user's own
+ *  explicit press of **Reconnect** on `stuck`, handled entirely in `UpdatePanel.tsx`. */
+export type ReachabilityPhase = 'waiting' | 'recovered' | 'stuck';
+
+export interface ReachabilityState {
+  phase: ReachabilityPhase;
+  /** Consecutive failed endpoint retries while `waiting` — the bound `nextWaitingAttempt` gives up
+   *  at. Meaningless (and left unchanged) for every other phase. */
+  attempts: number;
+}
+
+/** ~20 seconds of 500ms retries (the same interval the existing restart flow already polls at) —
+ *  long enough for someone to actually type `npx ds-viewer dev`, short enough that the page
+ *  doesn't spin forever before offering the manual `Reconnect`. */
+export const REACHABILITY_MAX_ATTEMPTS = 40;
+
+/** One more failed attempt while `waiting`: advances the bounded counter and gives up once it
+ *  reaches `REACHABILITY_MAX_ATTEMPTS`, exactly as the approved design's "Edge · Still not back"
+ *  state requires. The caller (the `waiting` poller) only calls this when its own direct retry
+ *  against the endpoint has already failed; a retry that succeeds recovers in place and never
+ *  reaches this function at all. */
+export function nextWaitingAttempt(current: ReachabilityState): ReachabilityState {
+  const attempts = current.attempts + 1;
+  return { phase: attempts >= REACHABILITY_MAX_ATTEMPTS ? 'stuck' : 'waiting', attempts };
+}
+
+/** The manual **Reconnect** button on the gave-up state: starts the same bounded cycle over from
+ *  zero, exactly like the first time an endpoint call found the viewer unreachable. `UpdatePanel.tsx`
+ *  pairs this with its own, separate `window.location.reload()` — one press, one reload, initiated
+ *  by the user, so no marker or loop guard is needed here or anywhere else. */
+export function restartReachability(): ReachabilityState {
+  return { phase: 'waiting', attempts: 0 };
+}
+
+/** Called on every endpoint call that actually succeeds. Most of the time there was nothing to
+ *  recover from (`current` is `undefined`) and this is a no-op — the ordinary case, which must not
+ *  show a "Reconnected" banner on every routine poll. Otherwise the panel shows the approved
+ *  design's auto-dismissing `recovered` note while its normal content — already current, since the
+ *  endpoint itself just answered — resumes underneath. */
+export function recoveredReachabilityState(current: ReachabilityState | undefined): ReachabilityState | undefined {
+  if (current === undefined) return undefined;
+  return { phase: 'recovered', attempts: 0 };
+}
+
+export interface ReachabilityNote {
+  variant: 'muted' | 'ok';
+  spinner: boolean;
+  bold?: string;
+  text: string;
+  /** A recovery command to render in `Code`, split from its lead-in text so the component can
+   *  place the two in separate `Text`/`Code` nodes. */
+  hint?: { prefix: string; command: string };
+}
+
+/** The exact approved copy (`.hermes-task/approved-unreachable-states.html`) for each reachability
+ *  phase — never invent wording beyond this. */
+export function reachabilityNote(phase: ReachabilityPhase): ReachabilityNote {
+  switch (phase) {
+    case 'waiting':
+      return {
+        variant: 'muted',
+        spinner: true,
+        bold: 'The viewer isn’t running.',
+        text: ' Nothing was changed. This page reconnects by itself as soon as it’s back.',
+        hint: { prefix: 'Start it with ', command: 'npx ds-viewer dev' },
+      };
+    case 'recovered':
+      return { variant: 'ok', spinner: false, text: 'Reconnected. Everything below is current.' };
+    case 'stuck':
+      return {
+        variant: 'muted',
+        spinner: false,
+        bold: 'The viewer still isn’t answering.',
+        text: ' Nothing was changed.',
+        hint: { prefix: 'or start it with ', command: 'npx ds-viewer dev' },
+      };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",