dsh-zen-remote 2.2.7 → 2.2.9

package/src/client/styles/composer.css.ts

@@ -6,11 +6,16 @@
 //
 // Official structure this file reshapes (verified live at 390px, see the S3
 // report): InputBar renders
-//   _card > _row > [_tools > (_add, _modes > PermissionSelect, input.left)]
+//   _card > _row > [_tools > (_add, input[type=file] hidden, _modes >
+//                             PermissionSelect, input.left)]
 //                  [_trailing > (_standardControls > (input.right, input.model), _activity, _primary)]
 // with `_tools` / `_trailing` / `_standardControls` as inner flex groups
 // (0.1.7 added `_standardControls` and moved the ContextMeter out of the row
-// into the dock under the card). Flattening all three to
+// into the dock under the card). That hidden file input is the stand-down
+// probe host-attach.ts USED to key on — since #31 the phone's own attach
+// button is a permanent resident instead, and DSH 0.1.5's second `_add`
+// button (the standalone paperclip 0.2.x removed) is hidden by section 2.
+// Flattening all three to
 // `display: contents` turns every control into a direct flex item of `_row`,
 // which is what makes a pure `order` reflow possible without touching a
 // single official component.
@@ -23,8 +28,21 @@ const ROOT = '[data-slot="conversation.composer.bar"] > [class$="_root"]'
 const RING_W = '30px'
 /** DSH 0.1.7's wrapper around input.right + input.model inside `_trailing`. */
 const STD = `${ROW} > [class$="_trailing"] > [class$="_standardControls"]`
-/** The model seat's own root inside the trailing group (long form so it beats the <=1023px pill rules in layout.css.ts). */
-const MODEL = `${STD} > [data-slot="conversation.input.model"] > [class$="_root"]`
+/**
+ * The model seat's content, whichever plugin owns it: officially ModelSelect's
+ * `_root`, but a third party can replace the whole `conversation.input.model`
+ * slot (…codex-ui mounts its own selector there), and a subagent session has
+ * nothing matching `_root` at all. Spelled `*:not(…)` rather than bare `> *`
+ * on purpose: `:not([data-mobile-nav])` carries the same (0,1,0) the old
+ * `[class$="_root"]` did, keeping every rule below a full attribute CLASS
+ * ahead of the ≤1023px pill rules in layout.css.ts — their `[data-phase] …
+ * :has(…)` forms measure (0,6,1) on the trigger and (0,7,1) on the label
+ * with `!important`, so a bare `> *` would leave the phone winning by
+ * exactly one class on every MODEL-derived rule, one upstream attr away
+ * from losing. The :not() also keeps this plugin's own nodes from ever
+ * reading as the model seat, should one ever be mounted there.
+ */
+const MODEL = `${STD} > [data-slot="conversation.input.model"] > *:not([data-mobile-nav])`
 /** The permission select's trigger button (structure only — the PermissionSelect hashed classes are never named). */
 const PERM = `${ROW} > [class$="_tools"] > [class$="_modes"]`
 /**
@@ -60,6 +78,12 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
 [data-mobile-nav="attach-picker"] {
   display: none !important;
 }
+/* The composer-chips strip (effects/model-sheet-extras.ts) — same
+   every-width default as the picker above: the phone block re-shows it
+   inside the dock rail; the desktop shell keeps none. */
+[data-mobile-nav="composer-chips"] {
+  display: none !important;
+}
 
 @media (max-width: 767px) {
   /* --- 1. flatten the two official groups ---
@@ -83,8 +107,12 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
   }
 
   /* --- 2. the running order ---
-     The attachment button (S3 placeholder, S7 wires it up) sits leftmost;
-     the official "+" command menu keeps its seat right next to it, where
+     The attachment button (S3 placeholder, S7 wires it up) sits leftmost and
+     is a PERMANENT resident now (#31): on DSH 0.2.x the standalone paperclip
+     moved into the "+" command menu while its hidden <input type="file">
+     stayed in _tools, so the old host-attach stand-down probe matched on
+     every host and the phone composer was left with no attach affordance at
+     all. The official "+" command menu keeps its seat right next to it, where
      the two "insert something" affordances read as one cluster. */
   ${ROW} [data-mobile-nav="attach"] {
     order: 1 !important;
@@ -92,6 +120,14 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
   ${ROW} > [class$="_tools"] > [class$="_add"] {
     order: 2 !important;
   }
+  /* DSH ≤ 0.1.5 still renders that second _add button (the standalone
+     paperclip) as a direct _tools child; hide it below 768px so the row
+     keeps exactly one attach control — ours, which uploads into the session
+     workspace the phone can actually reach. On 0.2.x the only button in
+     _tools is the first of its type, so this never matches. */
+  ${ROW} > [class$="_tools"] > button[class$="_add"]:nth-of-type(2) {
+    display: none !important;
+  }
   ${ROW} > [class$="_tools"] > [class$="_modes"] {
     order: 3 !important;
     /* Rigid on purpose. This seat holds the permission chip, whose own
@@ -243,7 +279,8 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
      caps the pill so the row's elastic gap survives extreme model ids;
      the label rules below override the <=1023px grow rules in
      layout.css.ts (flex 1 1 auto) that would otherwise pad the pill. */
-  ${MODEL} > [class$="_trigger"] {
+  ${MODEL} > [class$="_trigger"],
+  ${MODEL} > button {
     background: var(--dsw-specific-selector, rgba(127, 127, 127, .12)) !important;
     height: 30px !important;
     width: auto !important;
@@ -269,6 +306,18 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
     flex: none !important;
     white-space: nowrap !important;
   }
+  /* Third-party model selectors (…codex-ui) render a bare <button> with no
+     _trigger classes and text straight inside it; give that button the same
+     shrink+truncate contract the official label gets, so a long model id
+     ellipsizes instead of stretching the row. The official trigger also
+     matches this (harmless: it already ellipsizes its own label). */
+  ${MODEL} > button {
+    max-width: 100% !important;
+    min-width: 0 !important;
+    overflow: hidden !important;
+    text-overflow: ellipsis !important;
+    white-space: nowrap !important;
+  }
   /* PermissionSelect wraps its trigger in the Menu primitive's root span,
      which must shrink to the icon button's fixed width. */
   ${PERM} > span:has(> button[class$="_trigger"]) {
@@ -336,90 +385,97 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
     border-radius: 12px !important;
     font-size: 15px !important;
   }
-  /* --- 4a. third-party composer entries live in the model sheet ---
-     effects/model-sheet-extras.ts parks the \`conversation.input.right\`
-     container inside the model menu while that menu is open and puts it back
-     when it closes; these rules are the two halves of that trip.
+  /* --- 4a. third-party composer entries live in the dock's chip strip ---
+     effects/model-sheet-extras.ts collects the composer's secondary controls
+     (input.right, input.left, and anything a third party parks directly into
+     _tools / _standardControls / _trailing / _row) and moves the REAL nodes
+     into [data-mobile-nav="composer-chips"] — a 26px horizontally
+     scrollable strip the effect mounts at the head of the dock rail above
+     the card. Always visible, one tap, no sheet in between.
 
-     In the row: hidden, but ONLY once the effect has marked the container as
-     one it manages. Keying the hide off the marker rather than off "not
-     currently parked" is what makes the failure direction safe — if the
-     effect declines to act (nothing in the slot but the vision toggle, so
-     nothing worth moving) or never runs at all, the marker is absent, this
-     rule does not match, and the controls stay exactly where the host put
-     them. The inverse spelling hid them in the row whenever they were not in
-     the sheet, which in those same cases left them reachable from neither
-     place (caught in review, 2026-09-06).
-     Hiding by ancestor rather than by a display rule on the container itself
-     is what lets the parked copy style itself freely — same element, two
-     homes, two rule sets. \`!important\` because the slot container carries an
-     inline \`display: contents\`. */
-  ${STD} > [data-slot="conversation.input.right"][data-zen-sheet-extras] {
+     In the row: hidden, but ONLY once the effect has marked them. Two opt-in
+     markers, both written by the effect: the input.right CONTAINER gets
+     data-zen-sheet-extras (so an emptied wrapper leaves no flex gap), and
+     every collected node gets data-zen-composer-extra. Visibility comes back
+     the moment a node is parked (="open") or the effect releases it (marker
+     removed) — a version of the effect that declines to act, or never runs
+     at all, leaves every control exactly where the host put it; nothing can
+     end up hidden from both places at once (the 2026-09-06 review's rule). */
+  [data-slot="conversation.input.right"][data-zen-sheet-extras],
+  [data-zen-composer-extra]:not([data-zen-composer-extra="open"]) {
     display: none !important;
   }
-  /* Parked in the sheet: a column of full-width rows in the sheet's own
-     language, so a relocated control reads as a sibling of 模型 and 推理等级
-     rather than a chip that wandered in. */
-  ${MODEL_MENU} > [data-zen-sheet-extras] {
+  /* The strip itself: one 26px line at the rail's head (order 0, document
+     order first via the effect's prepend), scrolling sideways when the
+     collected controls overflow. Scoped to the dock CHILD — the generic
+     marker also sits on the emptied input.right container in the row, where
+     nothing but the opt-in hide above may touch it. This specificity (0,2,0)
+     is what beats the section 7 \`> *\` cage wherever they overlap (overflow,
+     max-width, radius are all !important there too). */
+  [data-slot="conversation.input.dock"] > [data-mobile-nav="composer-chips"] {
     display: flex !important;
-    flex-direction: column !important;
-    gap: 2px !important;
-    width: 100% !important;
-  }
-  /* Undo the row's compaction on every parked control: back to full width and
-     the 48px the sheet's own cells use. \`> * > *\` reaches both shapes without
-     naming either plugin — subscriptions wraps its trigger in a positioning
-     div, vision-router puts its button straight in the slot. */
-  ${MODEL_MENU} > [data-zen-sheet-extras] > *,
-  ${MODEL_MENU} > [data-zen-sheet-extras] > * > button {
-    width: 100% !important;
-    max-width: none !important;
+    flex-flow: row nowrap !important;
+    align-items: center !important;
+    gap: 6px !important;
+    order: 0 !important;
+    flex: 0 1 auto !important;
     min-width: 0 !important;
-    justify-content: flex-start !important;
+    max-width: 100% !important;
+    min-height: 26px !important;
+    max-height: 26px !important;
+    border-radius: 0 !important;
+    overflow-x: auto !important;
+    overflow-y: hidden !important;
+    scrollbar-width: none !important;
   }
-  ${MODEL_MENU} > [data-zen-sheet-extras] button {
-    box-sizing: border-box !important;
-    min-height: 48px !important;
-    height: auto !important;
-    padding: 0 12px !important;
-    gap: 10px !important;
-    border-radius: 12px !important;
-    border: none !important;
-    background: transparent !important;
-    font-size: 15px !important;
-    /* Both plugins center their chip label, which is right for a pill in the
-       row and wrong for a full-width row: the sheet's own cells start their
-       label at the left edge. justify-content covers the flex triggers,
-       text-align the ones that are not flex containers. */
-    text-align: left !important;
-    justify-content: flex-start !important;
+  [data-slot="conversation.input.dock"] > [data-mobile-nav="composer-chips"]::-webkit-scrollbar {
+    display: none !important;
   }
-  /* Order comes from the row (compat.css.ts puts the vision toggle at 5 so it
-     parks beside the context ring), and that rule still matches in here on
-     ≤ 0.1.2 — the inline sheet is a DOM descendant of the composer bar even
-     though it paints as a fixed layer (the 0.1.5 body portal is not, where
-     this is a harmless no-op). Reset it so the sheet follows DOM order
-     instead of inheriting a decision that was about a different layout. */
-  ${MODEL_MENU} > [data-zen-sheet-extras] > * {
+  /* Parked controls shrink from whatever the row allowed them to the rail's
+     26px pill scale: auto width again (no full-width rows here), tight
+     height, and the chip font the rest of the rail uses. */
+  [data-mobile-nav="composer-chips"] > * {
+    flex: 0 0 auto !important;
     order: 0 !important;
+    display: inline-flex !important;
+    align-items: center !important;
+    min-height: 26px !important;
+    max-height: 26px !important;
+    width: auto !important;
+    max-width: none !important;
+  }
+  [data-mobile-nav="composer-chips"] button {
+    box-sizing: border-box !important;
+    height: 26px !important;
+    min-height: 26px !important;
+    max-height: 26px !important;
+    width: auto !important;
+    padding: 0 10px !important;
+    gap: 5px !important;
+    border-radius: 999px !important;
+    font-size: 11.5px !important;
+    line-height: 18px !important;
+    white-space: nowrap !important;
   }
-  /* The vision toggle is squeezed to a 28px icon in the row (compat.css.ts);
-     in the sheet it is a row, so its label comes back and the icon leads. */
-  ${MODEL_MENU} > [data-zen-sheet-extras] [data-vision-router-mode-toggle] > span {
+  /* The vision toggle is squeezed to a 28px icon-only button in the row
+     (compat.css.ts); in the strip it is a 14px icon + text pill, so its
+     label comes back. */
+  [data-mobile-nav="composer-chips"] [data-vision-router-mode-toggle] > span {
     display: inline !important;
   }
-  ${MODEL_MENU} > [data-zen-sheet-extras] [data-vision-router-mode-toggle] > svg:first-of-type {
-    width: 18px !important;
-    height: 18px !important;
+  [data-mobile-nav="composer-chips"] [data-vision-router-mode-toggle] > svg:first-of-type {
+    width: 14px !important;
+    height: 14px !important;
   }
   /* The speed chip opens a menu of its own, anchored \`bottom: 100%\` to its
-     trigger. Inside the sheet — which is \`overflow: hidden\` so its rounded
-     top clips its content — that menu would be cut off. Same escape section 4
-     uses for the host's two menus: position: fixed leaves the clip behind
-     (the sheet sets \`transform: none\`, so nothing between here and the
-     viewport captures fixed positioning) and it lands as its own sheet on top
-     of this one. */
-  ${MODEL_MENU} > [data-zen-sheet-extras] [role="menu"] {
+     trigger. Inside the strip — which is \`overflow-x: auto\`, so its content
+     clips at the strip's box — that menu would be cut off. Same escape
+     section 4 uses for the host's two menus: position: fixed leaves the clip
+     behind and it lands as its own bottom sheet over the composer. */
+  [class$="_composerSeat"]:has([data-zen-sheet-extras] [role="menu"]) {
+    z-index: 60 !important;
+  }
+  [data-zen-sheet-extras] [role="menu"] {
     position: fixed !important;
     left: 0 !important;
     right: 0 !important;
@@ -434,13 +490,13 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
     border-radius: 16px 16px 0 0 !important;
     border-bottom: none !important;
     padding: 8px 8px calc(8px + var(--mnav-sab)) !important;
-    /* Above the model sheet it sits on (60, section 4), below the session-info
-       sheet's 70 (info.css.ts) — it is a child of the model sheet, not a peer
-       of the page's own layers. */
+    /* Above the page content behind the seat (the seat is raised to 60 by
+       the rule above while a parked menu is open), below the session-info
+       sheet's 70 (info.css.ts). */
     z-index: 61 !important;
     box-shadow: 0 -8px 32px rgba(0, 0, 0, .18) !important;
   }
-  ${MODEL_MENU} > [data-zen-sheet-extras] [role="menu"] [role="menuitemradio"] {
+  [data-zen-sheet-extras] [role="menu"] [role="menuitemradio"] {
     min-height: 48px !important;
     border-radius: 12px !important;
     font-size: 15px !important;
@@ -468,7 +524,10 @@ export const COMPOSER_CSS = `/* ---------- phone composer (< 768px) ---------- *
   body:has(${MODEL} > [class$="_menu"]) [data-chat-flow] + div,
   body:has(> [id$="-menu"][class$="_menu"]:is([role="menu"], [role="group"])) [data-chat-flow] + div,
   /* T70: the portaled permission menu (marked by effects/permission-sheet.ts). */
-  body:has(> div[role="menu"][data-zen-sheet="perm"]) [data-chat-flow] + div {
+  body:has(> div[role="menu"][data-zen-sheet="perm"]) [data-chat-flow] + div,
+  /* T-issue30: an inline menu a parked chip opened (escaped to a fixed
+     sheet by 4a). */
+  body:has([data-zen-sheet-extras] [role="menu"]) [data-chat-flow] + div {
     display: none !important;
   }
   /* --- 5. input box: two lines minimum, five lines maximum ---

package/src/client-data/remote-status.ts

@@ -35,6 +35,8 @@ import { zh } from '../client/locales.ts'
 /** Same-origin client route feeding this store (host half: T34,
  * src/client-routes.ts). */
 export const REMOTE_STATUS_ROUTE = '/_dsh/zen-remote/client/remote-status'
+/** the browser's network-restored hint (POST). */
+export const NETWORK_HINT_ROUTE = '/_dsh/zen-remote/client/network-hint'
 
 /** Same-origin client route closing one remote session from this machine. */
 export const CLIENT_UNSHARE_ROUTE = '/_dsh/zen-remote/client/unshare'
@@ -224,6 +226,47 @@ export const documentVisibility: VisibilitySource = {
   },
 }
 
+// --- the NETWORK-RESTORED hint source ---------------
+
+/**
+ * the browser-side signal that a previously broken
+ * link MAY be back. Two triggers, both cheap and event-driven (never polled):
+ *
+ *  - `window`'s `online` event — the browser's own reachability flag going
+ *    true. Note this is a HINT, never proof: `navigator.onLine === true`
+ *    means "an interface is up", not "the host is reachable". The host
+ *    resolves the question with an authenticated `/ping` before anything
+ *    reconnects.
+ *  - `visibilitychange` → visible: a backgrounded tab (throttled timers, a
+ *    possibly-changed network) coming back is the other moment a stale
+ *    `offline` is most likely, and it costs one hint at most.
+ *
+ * Deliberately NOT wired: `window`'s `offline` event. Going offline needs no
+ * action (the poll and the streams already notice), and firing a hint there
+ * would only produce refused round-trips.
+ */
+export interface NetworkHintSource {
+  /** Attach; the returned function detaches. */
+  subscribe(listener: () => void): () => void
+}
+
+/** The real source (Node / SSR: never notifying — a host has no navigator). */
+export const windowNetworkHint: NetworkHintSource = {
+  subscribe: (listener) => {
+    if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return () => {}
+    const onOnline = (): void => { listener() }
+    const onVisibility = (): void => {
+      if (typeof document !== 'undefined' && document.visibilityState === 'visible') listener()
+    }
+    window.addEventListener('online', onOnline)
+    if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      window.removeEventListener('online', onOnline)
+      if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility)
+    }
+  },
+}
+
 /** How one `client/unshare` POST ended. A refused action carries the
  * backend's error `code` when it sent one (`not-shared`, `remote-mismatch`,
  * …). */
@@ -243,24 +286,42 @@ export interface RemoteStatusStore {
   /** POST client/unshare for one VIRTUAL session id, then refresh.
    * @returns the action's outcome. */
   unshare(sessionId: string): Promise<RemoteUnshareOutcome>
+
+  /** fire one network-restored hint now (the same
+   * controlled round the window `online` event drives). Exposed for tests
+   * and for a host-side manual probe; never bypasses the host's probe. */
+  notifyNetworkRestored(): void
 }
 
 /** Poll cadence while the page is visible and at least one part is mounted
  * (T34: 15 秒). */
 export const REMOTE_STATUS_POLL_MS = 15_000
 
+/** The minimum gap between two client-side network hints — the same 3s the
+ * host's `networkRestored()` enforces, so the two never fight. `hintGapMs`
+ * injects a smaller one (tests). */
+const NETWORK_HINT_CLIENT_GAP_MS = 3_000
+
 /**
  * Build one store over an injectable fetch and visibility source — the
  * shares-store discipline: latest-wins (an earlier request answering late
  * never overwrites a newer table), every GET failure fails its own round,
  * the timer is real while visible and gone while hidden, and becoming
  * visible pulls once immediately. `pollMs` exists for tests: the shipped
- * cadence is far too slow to observe.
+ * cadence is far too slow to observe. `hintGapMs` exists for the same
+ * reason: the shipped hint gap (default 3000) is far too slow to observe.
  */
 export function createRemoteStatusStore(
   fetchImpl: typeof fetch,
   visibility: VisibilitySource = documentVisibility,
   pollMs: number = REMOTE_STATUS_POLL_MS,
+  /** the network-restored hint source. Omitted → no
+   * hint wiring (a host mount, or a test). */
+  networkHint?: NetworkHintSource,
+  /** the minimum gap between two client-side hints, ms; default 3000 (the
+   * same anti-storm gap the host enforces). Exists for tests, like
+   * `pollMs`: the shipped gap is far too slow to observe. */
+  hintGapMs: number = NETWORK_HINT_CLIENT_GAP_MS,
 ): RemoteStatusStore {
   const gate = createLatestGate()
   const listeners = new Set<() => void>()
@@ -366,18 +427,71 @@ export function createRemoteStatusStore(
     }
   }
 
+  // ONE controlled round per hint.
+  //
+  // The chain is: hint → POST client/network-hint → host runs probeHealth()
+  // (authenticated GET /ping) → only a reachable host advances to
+  // networkRestored() (which is itself offline-only + 3s-gapped) → the next
+  // status poll reflects the new state, and the intercept layer's $zr/events
+  // leg reopens on its own once the relay reads online.
+  //
+  // THREE client-side guards keep a flapping machine from turning the hint
+  // into a poll: a healthy-link gate (the last status read said `online` —
+  // nothing to retire), an in-flight slot (one hint at a time), and a
+  // minimum gap (the same 3s the host enforces, so the two never fight).
+  let hintInFlight = false
+  let lastHintAt = 0
+
+  const sendNetworkHint = async (): Promise<void> => {
+    // The healthy-link gate: a hint exists to retire a stale `offline`. While
+    // the last status read says `online`, a tab switch or a browser `online`
+    // event must not spend the hint→ping→refresh triple. `view` undefined
+    // (no GET answered yet) passes — conservative before the first read.
+    if (snapshot.view?.state === 'online') return
+    if (hintInFlight) return
+    const now = Date.now()
+    if (now - lastHintAt < hintGapMs) return
+    lastHintAt = now
+    hintInFlight = true
+    try {
+      await fetchImpl(NETWORK_HINT_ROUTE, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' })
+    } catch {
+      // A hint that cannot be delivered is simply dropped — the poll and the
+      // streams are still the truth, and the next event tries again.
+    } finally {
+      hintInFlight = false
+      // Whatever the hint achieved, re-read the status so the UI stops
+      // showing a stale `offline` the moment the host is back.
+      void refresh()
+    }
+  }
+
+  let offNetworkHint: (() => void) | undefined
+  const startHintWiring = (): void => {
+    if (networkHint === undefined || offNetworkHint !== undefined) return
+    offNetworkHint = networkHint.subscribe(() => { void sendNetworkHint() })
+  }
+
   return {
     getSnapshot: () => snapshot,
     subscribe(listener: () => void): () => void {
       listeners.add(listener)
       syncPolling()
+      startHintWiring()
       return () => {
         listeners.delete(listener)
         syncPolling()
+        // The hint listener follows the subscribers: no page, no hints.
+        if (listeners.size === 0 && offNetworkHint !== undefined) {
+          offNetworkHint()
+          offNetworkHint = undefined
+        }
       }
     },
     refresh,
     unshare,
+    /** explicit hint trigger (tests / manual probe). */
+    notifyNetworkRestored: () => { void sendNetworkHint() },
   }
 }
 
@@ -399,6 +513,18 @@ export function subscribeIfVirtual(store: RemoteStatusStore, sessionId: string,
  * matter how many of the icon and banner parts are mounted at once. Created
  * lazily over the real fetch, so check scripts never construct it. */
 export function getRemoteStatusStore(): RemoteStatusStore {
-  singleton ??= createRemoteStatusStore((input, init) => fetch(input, init))
+  // the REAL entry wiring. The network-hint source is
+  // passed here and nowhere else, so every mounted remote part (icon + banner)
+  // shares ONE store and therefore ONE hint subscription — no per-component
+  // listeners, no duplicate POSTs.
+  //
+  // Node / SSR: `windowNetworkHint.subscribe` returns a no-op detacher and
+  // never fires (there is no `window`), so a host mount is unaffected.
+  singleton ??= createRemoteStatusStore(
+    (input, init) => fetch(input, init),
+    documentVisibility,
+    REMOTE_STATUS_POLL_MS,
+    windowNetworkHint,
+  )
   return singleton
 }

package/src/client-routes.ts

@@ -52,6 +52,26 @@ export const CLIENT_STATUS_ROUTE = `${CLIENT_ROUTE_PREFIX}/status`
  * answered 409 unless the relay client is currently `offline`. */
 export const CLIENT_RECONNECT_ROUTE = `${CLIENT_ROUTE_PREFIX}/reconnect`
 
+/** POST: the browser's NETWORK-RESTORED hint.
+ *
+ * Why this route exists: the host half runs in a plain Node process with no
+ * OS network events, and the browser half cannot touch the relay client's
+ * memory across the HTTP boundary. So the browser — the only place that can
+ * observe `online`/`visibilitychange` — reports the hint here, and the host
+ * turns it into ONE controlled probe + reconnect.
+ *
+ * Deliberately narrower than `reconnect`:
+ *  - it first runs `probeHealth()` (authenticated GET /ping); a hint NEVER
+ *    alone proves the link is back (`navigator.onLine === true` is not
+ *    evidence);
+ *  - only a successful probe advances to `networkRestored()`, which itself
+ *    refuses outside `offline` and inside its 3s anti-storm gap;
+ *  - it answers the probe outcome so the page can log/annotate it.
+ *
+ * It NEVER changes state by itself: `probeHealth` is read-only, and
+ * `networkRestored` is the same controlled path the settings button uses. */
+export const CLIENT_NETWORK_HINT_ROUTE = `${CLIENT_ROUTE_PREFIX}/network-hint`
+
 /** GET: the remote-session status the T34 client parts render from (T34) —
  * the relay's serving state, the interface-compatibility verdict, the
  * handshake's server name, and the closed-session map. The prefix is
@@ -589,6 +609,39 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
         responseJson(res, 200, { ok: true })
         return
       }
+      if (route === CLIENT_NETWORK_HINT_ROUTE) {
+        if (method !== 'POST') {
+          res.setHeader('Allow', 'POST')
+          responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use POST' } })
+          return
+        }
+        if (!sameOriginPost(req)) {
+          responseJson(res, 403, {
+            ok: false,
+            error: { code: 'origin-rejected', message: 'The request must originate from this DSH Web application' },
+          })
+          return
+        }
+        const relay = options.getRelayClient?.()
+        if (relay === undefined) {
+          responseJson(res, 503, { ok: false, error: { code: 'unavailable', message: 'No relay client is running' } })
+          return
+        }
+        // a hint is a QUESTION, not a verdict.
+        // `probeHealth` is one authenticated GET /ping: it proves the HOST is
+        // reachable with the current token — nothing about the long streams.
+        // Only a reachable host earns the controlled reconnect, and
+        // `networkRestored()` is what enforces "offline only" + the 3s gap.
+        const reachable = await relay.probeHealth()
+        if (!reachable) {
+          // Honest answer: the network may be back, the HOST is not.
+          responseJson(res, 200, { ok: true, reachable: false, reconnected: false })
+          return
+        }
+        const reconnected = relay.networkRestored()
+        responseJson(res, 200, { ok: true, reachable: true, reconnected })
+        return
+      }
       if (route === CLIENT_REMOTE_STATUS_ROUTE) {
         if (method !== 'GET') {
           res.setHeader('Allow', 'GET')