@linxin666/dsh-remote-web-ui 0.4.5 → 0.4.7

package/src/client/RemotePanel.tsx

@@ -1,7 +1,10 @@
 /**
  * The mobile remote-control panel body: status card (state text + badge),
- * the QR code, the open-on-phone hint with the link text, and the three
- * actions (stop / refresh / copy). Pure presentation — all state and
+ * the QR code, the open-on-phone hint with the link text, and the two
+ * actions (stop / refresh / copy). The advertised network is not a choice:
+ * the QR names the public base and the landing page decides at connect time
+ * whether to move to a LAN origin (lan-source.ts), so the panel only states
+ * which source the current link carries. Pure presentation — all state and
  * actions arrive through props from the entry's behavior component.
  */
 import clsx from 'clsx'
@@ -47,10 +50,6 @@ export type PanelState =
       onlineCount: number
       /** Authorized devices for the roster under the QR card. */
       devices: DeviceFrame[]
-      /** The LAN literal the current QR was built from. */
-      address: string
-      /** Every constructible LAN literal (interface order). */
-      lanAddresses: string[]
       /** The active pairing token itself (useful in Docker/reverse proxy topologies). */
       token?: string
       /** Whether this QR is built on the configured public (tunneled) base. */
@@ -76,10 +75,6 @@ export interface RemotePanelProps {
   onRefresh(): void
   onCopy(url: string): void
   onCopyToken?(token: string): void
-  /** Re-mint the QR against a different LAN address. */
-  onPickAddress(address: string): void
-  /** Re-mint the QR against the configured public (tunneled) base. */
-  onPickPublic(): void
   /** Revoke one paired device. */
   onRevoke(deviceId: string): void
 }
@@ -113,8 +108,6 @@ export function RemotePanel({
   onRefresh,
   onCopy,
   onCopyToken,
-  onPickAddress,
-  onPickPublic,
   onRevoke,
 }: RemotePanelProps) {
   return (
@@ -221,37 +214,10 @@ export function RemotePanel({
             </p>
           )}
 
-          {(state.publicBaseUrl !== undefined || state.lanAddresses.length > 1) && (
-            <fieldset className={css.addresses}>
-              <legend>{t('address.label')}</legend>
-              {state.publicBaseUrl !== undefined && (
-                <label key="public" className={css.address}>
-                  <input
-                    type="radio"
-                    name="lan-address"
-                    aria-label={t('address.public')}
-                    checked={state.public}
-                    onChange={onPickPublic}
-                  />
-                  <span>{t('address.public')}</span>
-                  <code className={css.addressValue}>{state.publicBaseUrl}</code>
-                </label>
-              )}
-              {state.lanAddresses.map(address => (
-                <label key={address} className={css.address}>
-                  <input
-                    type="radio"
-                    name="lan-address"
-                    aria-label={address}
-                    checked={!state.public && address === state.address}
-                    onChange={() => onPickAddress(address)}
-                  />
-                  <span>{t('address.lan')}</span>
-                  <code className={css.addressValue}>{address}</code>
-                </label>
-              ))}
-              <p className={css.addressHint}>{t('address.hint')}</p>
-            </fieldset>
+          {(state.publicBaseUrl !== undefined || !state.public) && (
+            <p className={css.addressHint}>
+              {state.public ? t('address.auto') : t('address.pinnedLan')}
+            </p>
           )}
 
           <div className={css.actions}>

package/src/client/locales.ts

@@ -20,10 +20,8 @@ export const zh = {
   'status.unreachableHint': '请刷新页面后重试。',
   'pair.hint': '无法扫码？可直接打开下方配对链接',
   'pair.publicHint': '公网链接：设备无需与本机处于同一网络',
-  'address.label': '选择二维码指向的网络',
-  'address.public': '公网地址',
-  'address.lan': '局域网',
-  'address.hint': '远程设备不在同一网络时请使用公网地址；局域网地址仅限同一网络内使用。',
+  'address.auto': '二维码固定指向公网地址；手机与本机处于同一网络时会自动切换到局域网地址。',
+  'address.pinnedLan': '二维码固定指向局域网地址。',
   'pair.expires': '二维码有效至 {time}',
   'pair.expired': '二维码已过期，请刷新',
   'pair.linkLabel': '配对链接',
@@ -149,10 +147,8 @@ export const en = {
   'status.unreachableHint': 'Refresh the page and try again.',
   'pair.hint': 'Cannot scan? Open one of the pairing links below',
   'pair.publicHint': 'Public links work when the device is not on the same network',
-  'address.label': 'Network the QR code points to',
-  'address.public': 'Public',
-  'address.lan': 'LAN',
-  'address.hint': 'Use the public address when the remote device is on another network; LAN addresses only work on the same network.',
+  'address.auto': 'The QR code always points at the public address; a phone on the same network switches to the LAN address by itself.',
+  'address.pinnedLan': 'The QR code points at a LAN address.',
   'pair.expires': 'QR code valid until {time}',
   'pair.expired': 'QR code expired — refresh it',
   'pair.linkLabel': 'Pairing link',

package/src/client/mobile-adapt.ts

@@ -173,14 +173,41 @@ const ADAPT_CSS: readonly string[] = [
   '[class$="_headerUtilities"]{display:none}',
   // v52 composer: the two lines (permission / model) stay stacked with zero
   // row gap; the command, context-meter and send/stop buttons float at the
-  // left/right edges vertically centered over both lines.
+  // left/right edges vertically centered over both lines. "Both lines" is what
+  // makes _row the containing block for those three floats: _row is the one box
+  // that wraps the lines, so nothing between a float and _row may claim it.
   '[class$="_composerSeat"] [class$="_card"]{margin-bottom:1px}',
   '[class$="_composerSeat"] [class$="_row"]{flex-wrap:wrap;row-gap:0;padding:2px 8px 1px;position:relative}',
-  '[class$="_composerSeat"] [class$="_add"]{position:absolute;left:8px;top:50%;transform:translateY(-50%)}',
+  // The attach button is the only file-picker entry on the portrait composer,
+  // and taking it out of flow costs it the paint order it had inline: a
+  // positioned sibling painted after it (the trailing line, see below) covers
+  // it and eats the taps on the covered half. Its own z-index makes the hit
+  // layer a property of the button instead of a side effect of a sibling
+  // (#1829). It clears the composer's own stacking ladder and stays far below
+  // the bottom-sheet menus (2147482000), which own the overlay above it.
+  '[class$="_composerSeat"] [class$="_add"]{position:absolute;left:8px;top:50%;transform:translateY(-50%);z-index:10}',
   '[class$="_composerSeat"] [class$="_modes"]{min-width:0;padding-left:38px}',
   // Model line left-aligned with the permission line (same command-button
   // clearance), rows stay tightly stacked.
-  '[class$="_composerSeat"] [class$="_trailing"]{flex-basis:100%;position:relative;min-height:32px;justify-content:flex-start;padding-left:38px;padding-right:78px}',
+  // The trailing line is forced onto its own row at flex-basis:100% and carries
+  // 116px of side padding (38 left for the command button, 78 right for the
+  // send button). Under the default content-box that padding is ADDED to the
+  // 100% basis, so the line's own box overflowed the card by exactly 116px and
+  // dragged the absolutely-positioned send button out with it: on a 393px phone
+  // the card ended at x=367 while the button sat at x=433..467, past the
+  // viewport's right edge, which is the unreachable button the reporter
+  // measured (#1818). border-box contains the padding inside the basis, so the
+  // line stays within the card and the button lands back inside it.
+  //
+  // The line stays UNPOSITIONED on purpose. position:relative arrived here with
+  // the compact picker and outlived it, but this box is the LAST line only: as
+  // the nearest positioned ancestor it took the containing block from _row, so
+  // the send button and the context meter centered inside the trailing line
+  // instead of over both lines - the send button rode the input's bottom edge,
+  // out of line with the attach button - and, painted after the out-of-flow
+  // attach button, the line covered that button's lower half and swallowed the
+  // taps there (#1829).
+  '[class$="_composerSeat"] [class$="_trailing"]{box-sizing:border-box;flex-basis:100%;min-height:32px;justify-content:flex-start;padding-left:38px;padding-right:78px}',
   '[class$="_composerSeat"] [class$="_trailing"] *{font-size:12px}',
   // v54: smaller permission/model buttons (font + height). v79: the
   // permission trigger collapses to its shield icon on phones — the label

package/src/client/plugin-card-seat.ts

@@ -86,6 +86,11 @@ export interface PluginCardSeat {
   label?: () => string
   /** Locale namespace the card renders with. */
   locale: string
+  /**
+   * Child slots this card declares and renders. Forwarded to whichever seat
+   * the host renders; absent for a card that declares none.
+   */
+  children?: Record<string, unknown>
   /** Business-face factory of the registration. */
   inject?: () => object
   /**
@@ -162,12 +167,14 @@ export function installPluginCard(ctx: PluginCardContext, seat: PluginCardSeat):
           ...(seat.order === undefined ? {} : { order: seat.order }),
           ...(seat.label === undefined ? {} : { label: seat.label }),
           locale: seat.locale,
+          ...(seat.children === undefined ? {} : { children: seat.children }),
           ...(seat.inject === undefined ? {} : { inject }),
         }
         : {
           name: OFFICIAL_PLUGIN_CARD_SEAT,
           key: seat.bundle,
           locale: seat.locale,
+          ...(seat.children === undefined ? {} : { children: seat.children }),
           ...(seat.inject === undefined ? {} : { inject }),
         }) as never, component) as () => void
       current = target

package/src/client/remote.module.css

@@ -573,53 +573,8 @@
   line-height: 1.55;
 }
 
-/* Multi-homed address picker: one radio per constructible LAN literal. */
-.addresses {
-  margin: 12px 0 0;
-  padding: 0;
-  border: none;
-}
-
-.addresses legend {
-  padding: 0;
-  color: var(--dsw-alias-label-secondary);
-  font-size: 13px;
-}
-
-.address {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  margin-top: 6px;
-  padding: 4px 6px;
-  border-radius: 6px;
-  color: var(--dsw-alias-label-primary);
-  font-size: 13px;
-  font-variant-numeric: tabular-nums;
-  cursor: pointer;
-  transition: background-color 120ms ease;
-}
-
-.address:hover {
-  background: var(--dsw-alias-interactive-bg-hover);
-}
-
-.address input:focus-visible {
-  outline: none;
-  box-shadow: 0 0 0 2px var(--dsw-alias-bg-layer-2), 0 0 0 4px var(--dsw-alias-brand-primary);
-  border-radius: 50%;
-}
-
-.addressValue {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  color: var(--dsw-alias-label-secondary);
-  font-size: 12px;
-}
-
+/* Which network source the current QR link carries. Not a control: the landing
+   page decides the source at connect time, so the panel only states the fact. */
 .addressHint {
   margin: 6px 0 0;
   color: var(--dsw-alias-label-tertiary);
@@ -728,7 +683,6 @@
   .trigger,
   .close,
   .action,
-  .address,
   .deviceRevoke {
     transition: none;
   }

package/src/client/settings-entry-form.ts

@@ -52,7 +52,6 @@ function pendingSnapshot<T>(): ConfigFormSnapshot<T> {
     user: undefined,
     revision: undefined,
     writable: false,
-    mode: 'host',
   }
 }
 

package/src/detached-work.ts

@@ -1,12 +1,13 @@
+// Generated by scripts/sync-shared.mjs from shared/host/detached-work.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Run one piece of work outside the caller's async context.
  *
- * The Host performs a settings mutation inside `hmr.runExclusive`, which marks
- * the running async context with an AsyncLocalStorage store. Side effects that
- * live on that path - writing `cordis.patch.yml`, the very file the HMR config
- * watcher refreshes from - must not run under that mark, or the watcher's
- * refresh can re-enter the exclusive transaction and be refused with "HMR
- * transactions cannot be nested" (#1751, #1754).
+ * A Host mutation that runs inside `hmr.runExclusive` marks the running async
+ * context with an AsyncLocalStorage store. Side effects on that path that write
+ * a file the HMR config watcher refreshes from - `cordis.patch.yml` above all -
+ * must not run under that mark, or the watcher's refresh re-enters the
+ * exclusive transaction and is refused with "HMR transactions cannot be nested"
+ * (#1751, #1754, #1816).
  *
  * Deferring is NOT enough, and the earlier belt that this one replaces was
  * built on a disproven premise: Node propagates an AsyncLocalStorage store into
@@ -28,7 +29,7 @@
  * // -> undefined
  * ```
  *
- * @module
+ * @module dsh-web-shared/host/detached-work
  */
 
 import { AsyncResource } from 'node:async_hooks'
@@ -39,7 +40,7 @@ import { AsyncResource } from 'node:async_hooks'
  * instance is the only one the module ever needs. It carries no context of its
  * own, so every job run through it starts from the process's root context.
  */
-const DETACHED = new AsyncResource('dsh-remote-web-ui:detached-work', { triggerAsyncId: 0 })
+const DETACHED = new AsyncResource('dsh-web:detached-work', { triggerAsyncId: 0 })
 
 /**
  * Run `work` outside the caller's AsyncLocalStorage context.

package/src/index.ts

@@ -24,7 +24,7 @@ import { DEFAULT_IDLE_EXPIRE_MS, PairingService, type PairingConfig } from './pa
 import { dshHome } from './dsh-home.ts'
 import { isPairedDeviceRequest, makeGateListener } from './gate.ts'
 import { RemoteWebUiPairing } from './pairing-access.ts'
-import { isTrustedApiRequest, makeRoutes } from './routes.ts'
+import { isTrustedApiRequest, makeRoutes, PAIRING_SOURCE_OPTIONS, type PairingSourcePreference } from './routes.ts'
 import { makeRemoteApiRoutes, makeRemoteApiUpgradeRoutes } from './remote-api.ts'
 import { startRemotePresencePet, type PresencePetSeam } from './remote-presence-pet.ts'
 import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from './posture.ts'
@@ -207,6 +207,16 @@ export interface Config {
   profile?: string
   /** Master switch for the plugin (browser half + host pairing surfaces). */
   enabled?: boolean
+  /**
+   * The manual override of the automatic pairing-network choice, for the case
+   * where the phone's own probe misjudges (see `PairingSourcePreference` in
+   * routes.ts). `auto` (default) names the public base in the QR link and lets
+   * the landing page switch to a LAN origin when one answers; `public` pins the
+   * public base and disables the probe; `lan` pins the first LAN literal and
+   * skips the public hop entirely. Set through the profile patch — the settings
+   * card carries no control for it, so a save from that card leaves it alone.
+   */
+  pairingSource?: PairingSourcePreference
 }
 
 /**
@@ -245,11 +255,18 @@ export const Config = z.object({
   lanBind: z.boolean().volatile(),
   profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
   enabled: z.boolean().default(true).volatile(),
+  pairingSource: z.union([...PAIRING_SOURCE_OPTIONS]).default('auto').volatile(),
 })
 
 /** Presence sweep cadence (a stale device flips to disconnected within two sweeps). */
 const SWEEP_INTERVAL_MS = 10_000
 
+/**
+ * Re-plan retry while the quick tunnel waits for the webServer port to bind
+ * (a recompose pass can run this apply ahead of the listener's bind).
+ */
+const PORT_SETTLE_RETRY_MS = 1_000
+
 /**
  * Fully resolved config: every field non-optional except `publicBaseUrl`,
  * which legitimately resolves to `undefined` when unset (the schema keeps it
@@ -294,6 +311,7 @@ export interface ResolvedConfigFields {
   lanBind?: ConfigField<boolean>
   profile?: ConfigField<string>
   enabled?: ConfigField<boolean>
+  pairingSource?: ConfigField<PairingSourcePreference>
 }
 
 /** Read one resolved config field, following the live reference the schema produces. */
@@ -360,6 +378,7 @@ const DEFAULTS: ResolvedConfig = {
   lanBind: undefined,
   profile: resolveManagedProfile(undefined, undefined, process.env.DSH_PROFILE),
   enabled: true,
+  pairingSource: 'auto',
 }
 
 /**
@@ -406,6 +425,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     lanBind: readOptionalConfigField(config?.lanBind),
     profile: resolveManagedProfile(readOptionalConfigField(config?.profile), launchedProfileName(ctx), process.env.DSH_PROFILE),
     enabled: readConfigField(config?.enabled, DEFAULTS.enabled),
+    pairingSource: readConfigField(config?.pairingSource, DEFAULTS.pairingSource),
   })
   const service = new PairingService(pairingConfigOf(resolve()))
 
@@ -475,6 +495,14 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
   // 'off' until a sync pass turns a mode on; the phase listener only feeds
   // the public base while a plugin-managed tunnel (quick or named) runs.
   let tunnelMode: 'off' | 'quick' | 'named' = resolve().autoTunnel ? 'quick' : 'off'
+  /**
+   * Retry timer while the quick tunnel waits for the webServer port to bind
+   * (undefined when no deferral is pending). Unref'd: never keeps the
+   * process alive on its own.
+   */
+  let portSettleTimer: ReturnType<typeof nodeSetTimeout> | undefined
+  /** Dedupes the unbound-port warning to one line per unsettled episode. */
+  let portSettleWarned = false
   tunnel.onPhase((info: TunnelInfo) => {
     if (tunnelMode === 'off') return
     if (info.phase === 'running' && info.url !== undefined) {
@@ -501,6 +529,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     disposeRelayRegistrar()
     publicBase.dispose()
     tunnel.dispose()
+    if (portSettleTimer !== undefined) clearTimeout(portSettleTimer)
   }, 'remote-web-ui: auto tunnel')
   // The bind facts are known by now (webServer is an inject edge): the LAN
   // bases are frozen per process, matching the CLI's once-per-invocation
@@ -616,6 +645,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     ...makeRoutes({
       service,
       requirePairingForLan: () => resolve().requirePairingForLan,
+      pairingSource: () => resolve().pairingSource,
       lanBindStatus,
       indexDocument: fetchAppShell,
       trustedHosts: () => {
@@ -647,13 +677,13 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     // credential to everything it forwards (issue #1665).
     ...makeRemoteApiRoutes({
       service,
-      port: ctx.webServer.port,
+      port: () => ctx.webServer.port,
       auth: innerAuth,
     }),
   ]
   const upgrades = makeRemoteApiUpgradeRoutes({
     service,
-    port: ctx.webServer.port,
+    port: () => ctx.webServer.port,
     auth: innerAuth,
   })
   const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled)
@@ -669,7 +699,12 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
   let postureWasExposed = false
   const runPostureProbe = (): void => {
     if (!resolve().enabled) return
-    const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, ctx.webServer.port)
+    // The probe and the LAN targets need the bound port; before it settles
+    // (a recompose pass) there is nothing honest to probe — keep the previous
+    // snapshot and let the next trigger retry.
+    const port = ctx.webServer.port
+    if (port === undefined) return
+    const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, port)
     if (targets.length === 0) {
       postureKey = undefined
       service.setPosture(undefined)
@@ -679,7 +714,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     const claim = claimPostureKey(postureKey, key)
     if (!claim.run) return
     postureKey = claim.next
-    void probePosture({ port: ctx.webServer.port, targets }).then((snapshot) => {
+    void probePosture({ port, targets }).then((snapshot) => {
       service.setPosture(snapshot)
       const exposedHosts = snapshot.hosts.filter(host => host.exposed).map(host => host.host)
       const exposed = exposedHosts.length > 0
@@ -833,18 +868,13 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
   }
   ctx.effect(() => () => { lanBindWorkPending = false }, 'remote-web-ui: lan-bind work')
 
-  // Apply the effective configuration to the running surfaces once per
-  // activation: the service tunables, the LAN-bind block/firewall, the tunnel
-  // plan, the pairing routes, the presence sweep, and the posture probe.
-  const sync = (): void => {
-    const value = resolve()
-    service.config = pairingConfigOf(value)
-    scheduleLanBindWork()
-    // The plugin-managed tunnels own the public base while one runs: the URL
-    // lands in the service through the tunnel's phase listener (the minted
-    // quick URL, or the named tunnel's fixed public hostname). The manual
-    // publicBaseUrl applies only when no tunnel runs.
-    const plan = tunnelPlanOf(value, ctx.webServer.port)
+  // Apply one tunnel plan to the running surfaces. The plugin-managed tunnels
+  // own the public base while one runs: the URL lands in the service through
+  // the tunnel's phase listener (the minted quick URL, or the named tunnel's
+  // fixed public hostname). The manual publicBaseUrl applies only when no
+  // tunnel runs.
+  const applyTunnelPlan = (value: ResolvedConfig, port: number | undefined): void => {
+    const plan = tunnelPlanOf(value, port)
     tunnelMode = plan.mode
     publicBase.setMode(plan.mode)
     const liveTunnelUrl = publicBase.quickUrl()
@@ -903,6 +933,36 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
         service.setPublicBaseUrl(value.publicBaseUrl)
       }
     }
+  }
+
+  // Apply the effective configuration to the running surfaces once per
+  // activation: the service tunables, the LAN-bind block/firewall, the tunnel
+  // plan, the pairing routes, the presence sweep, and the posture probe.
+  const sync = (): void => {
+    const value = resolve()
+    service.config = pairingConfigOf(value)
+    scheduleLanBindWork()
+    // The quick tunnel's loopback target URL needs the bound port. A recompose
+    // pass can run this apply before the listener binds: defer the tunnel
+    // branch (and re-plan on a short timer) instead of minting an
+    // http://127.0.0.1:undefined target; everything else in sync applies.
+    const livePort = ctx.webServer.port
+    if (livePort === undefined && value.autoTunnel === true) {
+      if (!portSettleWarned) {
+        portSettleWarned = true
+        console.warn('remote-web-ui: autoTunnel is on but the web server port is not bound yet — the quick tunnel starts once the port settles')
+      }
+      if (portSettleTimer === undefined) {
+        portSettleTimer = nodeSetTimeout(() => {
+          portSettleTimer = undefined
+          sync()
+        }, PORT_SETTLE_RETRY_MS)
+        portSettleTimer.unref()
+      }
+    } else {
+      portSettleWarned = false
+      applyTunnelPlan(value, livePort)
+    }
     const enabled = value.enabled
     if (!enabled) {
       service.stop()

package/src/lan-source.ts

@@ -0,0 +1,132 @@
+/**
+ * The landing page's network-source decision: which origin a paired phone
+ * should keep using.
+ *
+ * The QR link can only name one base, and the server cannot know whether the
+ * scanning phone sits on this machine's own network: the public (relayed)
+ * base is the only one that is always reachable, so the QR names it and the
+ * phone decides at connect time. The device-gated landing (/pair-app) is the
+ * plugin's own page already rendered ahead of the official shell's boot, so it
+ * is the natural place to probe: after the page is served, a short
+ * cross-origin `fetch` per LAN candidate (a no-cors GET at
+ * {@link LAN_PING_PATH}) tells the browser whether that LAN origin answers,
+ * and the first one that does becomes the new origin. A probe that finds
+ * nothing, or that runs out of budget, changes nothing — the page the phone
+ * already holds stays paired and usable, so the probe can never block pairing.
+ *
+ * Browsers do not block this probe. An https page may not normally fetch
+ * `http://` subresources, but a host that is an IP literal is exempt from both
+ * the block and the automatic upgrade (verified against Chrome: the console
+ * reports "This request was not upgraded to HTTPS because its URL's host is an
+ * IP address" and delivers the response), which is exactly the shape every LAN
+ * candidate has.
+ *
+ * @module @linxin666/dsh-remote-web-ui/lan-source
+ */
+
+/** sessionStorage key holding this session's source decision. */
+export const LAN_SOURCE_STORAGE_KEY = 'dsh-remote-lan-source'
+
+/**
+ * Probe budget for the whole candidate set. Long enough for a LAN round trip,
+ * short enough that a phone on another network never waits on it — the probe
+ * is fire-and-forget and the page it runs on is already usable.
+ */
+export const LAN_SOURCE_PROBE_TIMEOUT_MS = 800
+
+/**
+ * How recently a LAN hop must have been taken for a return to a non-LAN origin
+ * to read as "the hop did not stick". A phone that fails to load the LAN page
+ * re-scans the QR (which always names the public base) within seconds, and the
+ * landing then has to choose the public source instead of hopping again into
+ * the same black hole; a deliberate return much later is a fresh decision and
+ * re-probes.
+ */
+export const LAN_SOURCE_RETRY_WINDOW_MS = 120_000
+
+/** One probe payload: everything the injected script needs, JSON-serializable. */
+export interface LanSourceHop {
+  /**
+   * The LAN origins the probe may hop to, normalized (`https://host:port` with
+   * a default port dropped) so they compare equal to `location.origin`.
+   */
+  candidates: readonly string[]
+  /** The path the hop targets on the winning origin. */
+  path: string
+  /** The path the probe itself requests, on each candidate. */
+  pingPath: string
+  /** The one-time grant the hop consumes on the winning origin. */
+  grant: string
+}
+
+/**
+ * Build the inline script that runs the source decision on the landing page.
+ * Reads every browser global through `window`, so a test can run it against
+ * one fake object (the same seam the parse-time boot patch uses).
+ * @param hop - the probe payload for this landing render.
+ * @returns the `<script>` element to splice into the landing's head.
+ */
+export function appShellLanSwitchScript(hop: LanSourceHop): string {
+  const payload = JSON.stringify({
+    key: LAN_SOURCE_STORAGE_KEY,
+    candidates: hop.candidates,
+    path: hop.path,
+    ping: hop.pingPath,
+    grant: hop.grant,
+    timeout: LAN_SOURCE_PROBE_TIMEOUT_MS,
+    retry: LAN_SOURCE_RETRY_WINDOW_MS,
+  })
+  const body = '(function(){try{' +
+    'var w=window,loc=w.location;' +
+    'var P=' + payload + ';' +
+    'var S=w.sessionStorage;' +
+    // The candidate set is the decision's identity: a host whose interfaces
+    // changed hands the landing a different signature, which forces a re-probe.
+    'P.sig=P.candidates.join(",");' +
+    // The stored decision: which source this session settled on, the candidate
+    // set it was made against (so a host whose interfaces changed re-decides),
+    // and when. Anything unreadable is treated as "no decision".
+    'function rd(){try{' +
+    'var raw=S.getItem(P.key);' +
+    'if(typeof raw!=="string"||raw==="")return undefined;' +
+    'var d=JSON.parse(raw);' +
+    'if(typeof d!=="object"||d===null)return undefined;' +
+    'if(d.src!=="lan"&&d.src!=="public")return undefined;' +
+    'if(typeof d.sig!=="string"||typeof d.at!=="number")return undefined;' +
+    'return d' +
+    '}catch(e){return undefined}}' +
+    'function wr(d){try{S.setItem(P.key,JSON.stringify(d))}catch(e){}}' +
+    // Already on a LAN candidate: nothing to decide, and a hop back to it
+    // would be the same origin. Recording the fact keeps a reload from probing.
+    'function own(){for(var i=0;i<P.candidates.length;i++){if(P.candidates[i]===loc.origin)return true}return false}' +
+    'function go(base){try{loc.replace(base+P.path+"?grant="+encodeURIComponent(P.grant))}catch(e){}}' +
+    'function probe(){' +
+    'if(typeof w.fetch!=="function")return;' +
+    'var settled=false;' +
+    'var timer=w.setTimeout(function(){finish(undefined)},P.timeout);' +
+    'function finish(base){' +
+    'if(settled)return;' +
+    'settled=true;' +
+    'try{w.clearTimeout(timer)}catch(e){}' +
+    // The first answer wins: one reachable candidate is all the hop needs, and
+    // the losers keep running their own no-cors GETs harmlessly.
+    'if(base===undefined){wr({src:"public",sig:P.sig,at:Date.now()});return}' +
+    'wr({src:"lan",sig:P.sig,base:base,at:Date.now()});' +
+    'go(base)}' +
+    'for(var i=0;i<P.candidates.length;i++){(function(base){' +
+    'var sent;' +
+    'try{sent=w.fetch(base+P.ping,{mode:"no-cors",cache:"no-store",credentials:"omit",referrerPolicy:"no-referrer"})}catch(e){sent=undefined}' +
+    'if(sent===undefined||typeof sent.then!=="function")return;' +
+    'sent.then(function(){finish(base)},function(){})' +
+    '})(P.candidates[i])}}' +
+    'var d=rd();' +
+    'if(own()){if(d===undefined||d.sig!==P.sig)wr({src:"lan",sig:P.sig,base:loc.origin,at:Date.now()});return}' +
+    'if(d!==undefined&&d.sig===P.sig){' +
+    'if(d.src==="public")return;' +
+    // A LAN decision taken moments ago, on a page that is not a LAN candidate,
+    // is a hop that did not stick. Fall back rather than hop again.
+    'if(Date.now()-d.at<P.retry){wr({src:"public",sig:P.sig,at:Date.now()});return}}' +
+    'probe()' +
+    '}catch(e){}})();'
+  return `<script>${body}</script>`
+}