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

package/lib/types/remote-channel-boot.js

@@ -200,7 +200,7 @@ export function buildRemoteChannelBootScript(rules = REMOTE_CHANNEL_RULES) {
 }
 /** Boot-watchdog latch: one self-reload per session while the boot is broken. */
 export const BOOT_WATCHDOG_KEY = 'dsh-remote-boot-reload';
-/** Total wait for the app's first conversation surface before the reload. */
+/** Post-load wait for the app's first conversation surface before the reload. */
 const BOOT_WATCHDOG_WAIT_MS = 15_000;
 /** Watchdog poll cadence. */
 const BOOT_WATCHDOG_POLL_MS = 1_000;
@@ -221,6 +221,9 @@ export function buildBootWatchdogScript(waitMs = BOOT_WATCHDOG_WAIT_MS, pollMs =
     ';function wBoot(){try{return !!(w.document&&w.document.querySelector&&(w.document.querySelector("[data-conversation-scroll]")||w.document.querySelector("[data-slot=\\"conversation\\"]")))}catch(e){return false}}' +
         'function wTick(n){try{' +
         'if(wBoot()){try{w.sessionStorage.removeItem(' + key + ')}catch(e){}return}' +
+        // Parse-time installation must not spend the recovery budget downloading
+        // the initial scripts/styles over a slow remote link (issue #1845).
+        'if(!w.document||w.document.readyState!=="complete"){w.setTimeout(function(){wTick(0)},' + pollMs + ');return}' +
         'if(n<' + waitMs + '){w.setTimeout(function(){wTick(n+' + pollMs + ')},' + pollMs + ');return}' +
         'var done=false;try{done=w.sessionStorage.getItem(' + key + ')==="1"}catch(e){}' +
         'if(done)return;' +

package/lib/types/routes.d.ts

@@ -24,6 +24,7 @@ import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import { z } from 'zod';
 import { type PairingService, type PairingSnapshot } from './pairing.ts';
 import { type PairGrantStore } from './pair-grant.ts';
+import { type LanSourceHop } from './lan-source.ts';
 /**
  * Browser-trust fence for the /api/pair routes, mirroring the connection
  * package's internal fence semantics (Host/Origin based, DNS-rebinding and
@@ -119,11 +120,18 @@ export declare function publicHostOf(url: string | undefined): string | undefine
  * The cookieless device credential: pass the device id from the /pair-app
  * URL into sessionStorage (and localStorage for tab reloads) before any app
  * script runs - same key the boot patch and the channel gate read. The
- * replaceState to '/' hides the credential URL from the address bar and
- * leaves the SPA at its canonical root path. The reopen service worker is
- * registered in the same breath: later navigations to '/' (history,
- * bookmark, tab restore) must not fall through to the harness index gate,
- * which the cookieless flow can never satisfy.
+ * replaceState drops the one-time grant from the address bar and leaves the
+ * SPA on a path this plugin answers again; which path depends on the origin.
+ *
+ * A secure context registers the reopen service worker in the same breath,
+ * and that worker owns navigations to '/', so the SPA keeps its canonical
+ * root. A plain-HTTP LAN origin is never a secure context, so the worker
+ * cannot exist there and '/' falls through to the harness index gate the
+ * cookieless flow can never satisfy (issue #1867). The address bar therefore
+ * keeps the plugin-owned landing path, which re-validates the device
+ * credential on every reload and serves the bilingual re-pair page once the
+ * pairing is gone. Both targets are bare paths: the one-time grant never
+ * survives the rewrite, and no credential is ever left in the URL.
  */
 export declare const APP_DEVICE_STORAGE_KEY = "dsh-remote-device";
 export declare function appShellCaptureScript(deviceId: string): string;
@@ -134,8 +142,18 @@ export declare function appShellCaptureScript(deviceId: string): string;
  * hook only when this server-served marker is already set (see
  * remote-channel-boot.ts), so host mode is granted by the device-gated landing
  * instead of being asserted from the origin.
+ *
+ * A landing reached on a base other than the machine's own LAN origin also
+ * carries the source-decision script (lan-source.ts): the phone decides at
+ * connect time whether a LAN candidate answers, and switches its origin when
+ * one does. It runs after the capture script so the granted page is fully
+ * usable before the probe's outcome can move it.
+ * @param html - the official index document.
+ * @param deviceId - the device session this landing is being served for.
+ * @param hop - the LAN candidates to probe, when a switch is possible.
+ * @returns the patched document.
  */
-export declare function patchAppShell(html: string, deviceId: string): string;
+export declare function patchAppShell(html: string, deviceId: string, hop?: LanSourceHop): string;
 /**
  * The reopen service worker served at PAIR_PATHS.appServiceWorker. A paired
  * phone comes back to `/` from history, bookmarks, or tab restore; the
@@ -144,9 +162,10 @@ export declare function patchAppShell(html: string, deviceId: string): string;
  * worker owns navigations to `/` instead: network-first through /pair-app
  * (which validates the device cookie and refreshes its presence), the
  * cached shell for offline opens, and a pass-through of the original
- * request when the plugin no longer answers. Plain-HTTP LAN origins are not
- * secure contexts, so the worker never registers there — the LAN reopen
- * path stays "scan a fresh QR", which is cheap in-network.
+ * request when the plugin no longer answers. A plain-HTTP LAN origin is
+ * never a secure context, so the worker cannot exist there; the capture
+ * script keeps the plugin-owned landing path in the address bar instead,
+ * and that landing re-validates the device credential on every reload.
  *
  * Kept as a plain string (same pattern as the capture script): it must load
  * with no build step, run on every JS engine that ships service workers,
@@ -168,6 +187,12 @@ export declare const PAIR_PATHS: {
     readonly acceptPage: "/pair-accept";
     /** The cookieless app landing: serves the official shell for a paired device. */
     readonly appPage: "/pair-app";
+    /**
+     * The landing page's LAN reachability beacon (lan-source.ts): an inert
+     * no-cors GET target, so a probe proves the origin answers without touching
+     * a credential or any state.
+     */
+    readonly ping: "/pair-ping";
     /**
      * The reopen service worker (registered by the capture script). Root-level
      * path so its default script-directory scope already covers `/`.
@@ -206,12 +231,49 @@ export declare class PairingEventsStream {
     /** Stream count (tests/diagnostics). */
     get size(): number;
 }
+/**
+ * The manual override of the automatic network choice, for the case where the
+ * phone's own probe misjudges (a firewall that answers the reachability ping
+ * but not the page, or a LAN the probe cannot see).
+ *
+ * - `auto` (default): the QR link names the public base when one is configured
+ *   and the landing page probes the LAN candidates, switching to the first one
+ *   that answers.
+ * - `public`: the public base only, and the landing page never probes. For a
+ *   deployment where the LAN hop is undesirable.
+ * - `lan`: the first LAN literal directly, with no public hop. For a phone that
+ *   is known to sit on this machine's own network.
+ */
+export type PairingSourcePreference = 'auto' | 'public' | 'lan';
+/**
+ * The accepted {@link PairingSourcePreference} values, shared with the config
+ * schema so the patch that admits a value and the handler that reads it cannot
+ * drift apart.
+ */
+export declare const PAIRING_SOURCE_OPTIONS: readonly PairingSourcePreference[];
+/**
+ * The LAN origins a landing page served from one authority may hop to: every
+ * LAN base the service advertises except the authority serving the request
+ * (hopping to the current origin would be a no-op), normalized through `URL`
+ * so a default port compares equal to `location.origin`.
+ * @param lanBases - the advertised LAN base URLs, in interface order.
+ * @param currentOrigin - the origin serving the landing page.
+ * @returns the distinct candidate origins, in interface order.
+ */
+export declare function lanSourceCandidates(lanBases: readonly string[], currentOrigin: string): string[];
 /** Route-family dependencies (test seam). */
 export interface PairRoutesDeps {
     /** The pairing service. */
     service: PairingService;
     /** Current desktop gate policy, re-read for every status response. */
     requirePairingForLan?: boolean | (() => boolean);
+    /**
+     * The manual override of the automatic network choice
+     * ({@link PairingSourcePreference}), re-read per request. Defaults to
+     * `auto`: the QR link names the public base and the landing page decides
+     * whether to switch to a LAN origin.
+     */
+    pairingSource?: () => PairingSourcePreference;
     /**
      * LAN-bind facts for the settings card (managed patch block state, live
      * bind host/port, firewall summary). Re-read per request so a hot-reloaded

package/lib/types/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"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"}

package/lib/types/routes.js

@@ -26,6 +26,7 @@ import { isLoopbackClient, readCookie } from "./gate.js";
 import { readJsonBody, writeJson } from "./http.js";
 import { createPairGrantStore } from "./pair-grant.js";
 import { REMOTE_HOST_GRANT_GLOBAL } from "./remote-channel-rules.js";
+import { appShellLanSwitchScript } from "./lan-source.js";
 /**
  * Browser-trust fence for the /api/pair routes, mirroring the connection
  * package's internal fence semantics (Host/Origin based, DNS-rebinding and
@@ -299,18 +300,26 @@ const COOKIE_MAX_AGE_SEC = 365 * 24 * 60 * 60;
  * The cookieless device credential: pass the device id from the /pair-app
  * URL into sessionStorage (and localStorage for tab reloads) before any app
  * script runs - same key the boot patch and the channel gate read. The
- * replaceState to '/' hides the credential URL from the address bar and
- * leaves the SPA at its canonical root path. The reopen service worker is
- * registered in the same breath: later navigations to '/' (history,
- * bookmark, tab restore) must not fall through to the harness index gate,
- * which the cookieless flow can never satisfy.
+ * replaceState drops the one-time grant from the address bar and leaves the
+ * SPA on a path this plugin answers again; which path depends on the origin.
+ *
+ * A secure context registers the reopen service worker in the same breath,
+ * and that worker owns navigations to '/', so the SPA keeps its canonical
+ * root. A plain-HTTP LAN origin is never a secure context, so the worker
+ * cannot exist there and '/' falls through to the harness index gate the
+ * cookieless flow can never satisfy (issue #1867). The address bar therefore
+ * keeps the plugin-owned landing path, which re-validates the device
+ * credential on every reload and serves the bilingual re-pair page once the
+ * pairing is gone. Both targets are bare paths: the one-time grant never
+ * survives the rewrite, and no credential is ever left in the URL.
  */
 export const APP_DEVICE_STORAGE_KEY = 'dsh-remote-device';
 export function appShellCaptureScript(deviceId) {
     const safeId = JSON.stringify(deviceId);
     const grantGlobal = JSON.stringify(REMOTE_HOST_GRANT_GLOBAL);
+    const reopenPath = JSON.stringify(PAIR_PATHS.appPage);
     const register = `try{if('serviceWorker' in navigator){navigator.serviceWorker.register(${JSON.stringify(PAIR_PATHS.appServiceWorker)},{scope:'/'}).catch(function(e){})}}catch(e){}`;
-    return `<script>(function(){try{sessionStorage.setItem(${JSON.stringify(APP_DEVICE_STORAGE_KEY)},${safeId});}catch(e){}try{history.replaceState(null,'','/')}catch(e){}try{window[${grantGlobal}]=true}catch(e){}${register}})()</script>`;
+    return `<script>(function(){try{sessionStorage.setItem(${JSON.stringify(APP_DEVICE_STORAGE_KEY)},${safeId});}catch(e){}try{history.replaceState(null,'',window.isSecureContext?'/':${reopenPath})}catch(e){}try{window[${grantGlobal}]=true}catch(e){}${register}})()</script>`;
 }
 /**
  * Patch the official index document with the device-capture script. The script
@@ -319,9 +328,19 @@ export function appShellCaptureScript(deviceId) {
  * hook only when this server-served marker is already set (see
  * remote-channel-boot.ts), so host mode is granted by the device-gated landing
  * instead of being asserted from the origin.
+ *
+ * A landing reached on a base other than the machine's own LAN origin also
+ * carries the source-decision script (lan-source.ts): the phone decides at
+ * connect time whether a LAN candidate answers, and switches its origin when
+ * one does. It runs after the capture script so the granted page is fully
+ * usable before the probe's outcome can move it.
+ * @param html - the official index document.
+ * @param deviceId - the device session this landing is being served for.
+ * @param hop - the LAN candidates to probe, when a switch is possible.
+ * @returns the patched document.
  */
-export function patchAppShell(html, deviceId) {
-    const script = appShellCaptureScript(deviceId);
+export function patchAppShell(html, deviceId, hop) {
+    const script = appShellCaptureScript(deviceId) + (hop === undefined ? '' : appShellLanSwitchScript(hop));
     const head = /<head[^>]*>/i.exec(html);
     if (head === null)
         return script + html;
@@ -336,9 +355,10 @@ export function patchAppShell(html, deviceId) {
  * worker owns navigations to `/` instead: network-first through /pair-app
  * (which validates the device cookie and refreshes its presence), the
  * cached shell for offline opens, and a pass-through of the original
- * request when the plugin no longer answers. Plain-HTTP LAN origins are not
- * secure contexts, so the worker never registers there — the LAN reopen
- * path stays "scan a fresh QR", which is cheap in-network.
+ * request when the plugin no longer answers. A plain-HTTP LAN origin is
+ * never a secure context, so the worker cannot exist there; the capture
+ * script keeps the plugin-owned landing path in the address bar instead,
+ * and that landing re-validates the device credential on every reload.
  *
  * Kept as a plain string (same pattern as the capture script): it must load
  * with no build step, run on every JS engine that ships service workers,
@@ -437,6 +457,12 @@ export const PAIR_PATHS = {
     acceptPage: '/pair-accept',
     /** The cookieless app landing: serves the official shell for a paired device. */
     appPage: '/pair-app',
+    /**
+     * The landing page's LAN reachability beacon (lan-source.ts): an inert
+     * no-cors GET target, so a probe proves the origin answers without touching
+     * a credential or any state.
+     */
+    ping: '/pair-ping',
     /**
      * The reopen service worker (registered by the capture script). Root-level
      * path so its default script-directory scope already covers `/`.
@@ -517,6 +543,37 @@ export class PairingEventsStream {
         return this.streams.size;
     }
 }
+/**
+ * The accepted {@link PairingSourcePreference} values, shared with the config
+ * schema so the patch that admits a value and the handler that reads it cannot
+ * drift apart.
+ */
+export const PAIRING_SOURCE_OPTIONS = ['auto', 'public', 'lan'];
+/**
+ * The LAN origins a landing page served from one authority may hop to: every
+ * LAN base the service advertises except the authority serving the request
+ * (hopping to the current origin would be a no-op), normalized through `URL`
+ * so a default port compares equal to `location.origin`.
+ * @param lanBases - the advertised LAN base URLs, in interface order.
+ * @param currentOrigin - the origin serving the landing page.
+ * @returns the distinct candidate origins, in interface order.
+ */
+export function lanSourceCandidates(lanBases, currentOrigin) {
+    const origins = [];
+    for (const base of lanBases) {
+        let origin;
+        try {
+            origin = new URL(base).origin;
+        }
+        catch {
+            continue;
+        }
+        if (origin === currentOrigin || origins.includes(origin))
+            continue;
+        origins.push(origin);
+    }
+    return origins;
+}
 /**
  * Build the /api/pair route family.
  * @param deps - service + fence inputs.
@@ -527,6 +584,28 @@ export function makeRoutes(deps) {
     const pairingRequired = () => typeof requirePairingForLan === 'function'
         ? requirePairingForLan()
         : requirePairingForLan;
+    /** The manual network override, re-read per request (default: automatic). */
+    const sourcePreference = () => deps.pairingSource?.() ?? 'auto';
+    /**
+     * Every authority this surface serves, as {@link isTrustedHost} wants them
+     * (bare `host` or `host:port` literals). The LAN literals are re-read per
+     * request: a hot rebind (the lan-bind toggle) updates them mid-process, and
+     * both the fence and the reachability beacon must follow.
+     */
+    const servedAuthorities = () => {
+        const publicHost = publicHostOf(service.publicBaseUrl);
+        const extraHosts = typeof deps.trustedHosts === 'function' ? deps.trustedHosts() : (deps.trustedHosts ?? []);
+        return [
+            ...service.lanAddresses,
+            ...(publicHost !== undefined ? [publicHost] : []),
+            ...extraHosts,
+            ...dynamicTrustedHosts,
+        ];
+    };
+    /** Every LAN base URL the service currently advertises, in interface order. */
+    const lanBaseUrls = () => service.lanAddresses
+        .map(address => service.lanBaseUrlFor(address))
+        .filter((base) => base !== undefined);
     const grants = deps.grants ?? createPairGrantStore();
     const events = new PairingEventsStream(service);
     const dynamicTrustedHosts = new Set();
@@ -539,17 +618,7 @@ export function makeRoutes(deps) {
      * pairing entry pages), never for an API or subresource request.
      */
     const lanFence = (req, navigation = false) => {
-        const publicHost = publicHostOf(service.publicBaseUrl);
-        // The service's LAN bases re-read per request: a hot rebind (the lan-bind
-        // toggle) updates them mid-process, and the fence must follow.
-        const bases = service.lanAddresses;
-        const extraHosts = typeof deps.trustedHosts === 'function' ? deps.trustedHosts() : (deps.trustedHosts ?? []);
-        const combined = [
-            ...bases,
-            ...(publicHost !== undefined ? [publicHost] : []),
-            ...extraHosts,
-            ...dynamicTrustedHosts,
-        ];
+        const combined = servedAuthorities();
         if (navigation && isTopLevelDocumentNavigation(req) ? isTrustedHost(req, combined) : isTrustedApiRequest(req, combined))
             return true;
         // If request carries a valid paired device cookie from a private LAN host (e.g. after service restart), trust and remember it
@@ -662,10 +731,23 @@ export function makeRoutes(deps) {
             // the injected portrait adaptation, PCs the full desktop UI), so the
             // remote surface can never drift from the official one.
             const { token, expiresAt } = service.issue(undefined, address);
-            // The default base is the public (tunneled) URL when configured — a
-            // phone anywhere can reach it — and the first LAN interface otherwise.
-            // An explicit address always names a LAN literal.
-            const base = address === undefined ? (service.publicBaseUrl ?? service.lanBaseUrl) : service.lanBaseUrlFor(address);
+            // The advertised base is the public (tunneled/relayed) one whenever it is
+            // configured: it is the only base a phone anywhere can reach, so the QR
+            // never depends on the scanning phone being on this machine's network.
+            // The landing page then decides at connect time whether to move to a LAN
+            // origin (lan-source.ts). `lan` is the manual override that pins the QR to
+            // a LAN literal; an explicit address always names one.
+            const preference = sourcePreference();
+            const base = address !== undefined
+                ? service.lanBaseUrlFor(address)
+                : preference === 'lan'
+                    ? service.lanBaseUrl
+                    : preference === 'public'
+                        // Pinned to public: with none configured there is no satisfiable
+                        // link, which the caller reports as lan-required rather than
+                        // silently advertising a base the override excluded.
+                        ? service.publicBaseUrl
+                        : (service.publicBaseUrl ?? service.lanBaseUrl);
             if (base === undefined)
                 throw new Error('remote-web-ui: base unavailable');
             writeJson(res, 200, {
@@ -954,7 +1036,51 @@ export function makeRoutes(deps) {
             'referrer-policy': 'no-referrer',
             'set-cookie': [deviceCookie(req, service.config.cookieName, id)],
         });
-        res.end(patchAppShell(html, id));
+        res.end(patchAppShell(html, id, lanHop(req, id)));
+    };
+    /**
+     * The LAN hop this landing may take, or undefined when there is nothing to
+     * decide. Three conditions have to hold together: the automatic preference
+     * (both overrides answer the question already — `lan` serves the QR from a
+     * LAN origin, `public` forbids the move), at least one LAN candidate other
+     * than this origin, and a fresh one-time grant for the target landing. The
+     * grant is what lets the target origin serve the shell: the device cookie is
+     * origin-scoped, so the LAN origin has no credential of its own, and the
+     * grant table lives in this process regardless of which interface answered.
+     * The candidate set is carried to the client as origins (lan-source.ts
+     * compares them against `location.origin`).
+     * @param req - the landing request (its authority is the current origin).
+     * @param deviceId - the device session the landing is served for.
+     * @returns the hop payload, or undefined when no switch is possible.
+     */
+    const lanHop = (req, deviceId) => {
+        if (sourcePreference() !== 'auto')
+            return undefined;
+        const candidates = lanSourceCandidates(lanBaseUrls(), appOrigin(req));
+        if (candidates.length === 0)
+            return undefined;
+        return { candidates, path: PAIR_PATHS.appPage, pingPath: PAIR_PATHS.ping, grant: grants.issue(deviceId).grant };
+    };
+    /**
+     * The landing page's LAN reachability beacon: a 204 for a Host this plugin
+     * serves, a 403 otherwise. It carries no credential and no state — a phone
+     * that reaches it has proved the origin answers, which is all the source
+     * decision needs, and the fence's browser-marker half is deliberately not
+     * applied here: the probe is cross-site by construction (a page on the
+     * public origin fetching a LAN origin), so the marker check would turn every
+     * probe into the same 403 that means "not ours" and make the two
+     * indistinguishable.
+     */
+    const handlePing = (req, res) => {
+        if (!requireMethod(req, res, 'GET'))
+            return;
+        if (!isTrustedHost(req, servedAuthorities())) {
+            res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end();
+            return;
+        }
+        res.writeHead(204, { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' });
+        res.end();
     };
     /**
      * The reopen service worker script. Same phone-facing fence as the app
@@ -993,6 +1119,10 @@ export function makeRoutes(deps) {
         routes.push({ kind: 'exact', path: PAIR_PATHS.lanBind, handler: handleLanBind });
     }
     routes.push({ kind: 'exact', path: PAIR_PATHS.acceptPage, handler: handleAcceptPage });
+    // The beacon is independent of the app landing: a deployment with no
+    // indexDocument still advertises LAN bases, and a landing served some other
+    // way may still probe them.
+    routes.push({ kind: 'exact', path: PAIR_PATHS.ping, handler: handlePing });
     if (deps.indexDocument !== undefined) {
         routes.push({ kind: 'exact', path: PAIR_PATHS.appPage, handler: handleAppPage });
         // The reopen worker is only meaningful when the app landing it

package/lib/types/tunnel-plan.d.ts

@@ -25,12 +25,18 @@ export type TunnelPlan = {
  * token AND a valid public hostname (the token does not carry the hostname,
  * so the QR base and the fence trust would have no source without it);
  * otherwise no tunnel and the manual public base applies.
+ *
+ * The quick target URL names the local webServer port, so a plan made before
+ * the listener binds cannot be quick: it comes back `off` and the caller —
+ * which can observe the port settle — re-plans. The planner itself never
+ * emits an `http://127.0.0.1:undefined` target.
  * @param value - the resolved settings slice that drives the tunnel.
- * @param port - the local webServer port the tunnel forwards to.
+ * @param port - the local webServer port the tunnel forwards to (undefined
+ *   before the listener binds).
  */
 export declare function tunnelPlanOf(value: {
     autoTunnel?: boolean;
     tunnelToken?: string;
     publicBaseUrl?: string;
-}, port: number): TunnelPlan;
+}, port: number | undefined): TunnelPlan;
 //# sourceMappingURL=tunnel-plan.d.ts.map

package/lib/types/tunnel-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel-plan.d.ts","sourceRoot":"","sources":["../../src/tunnel-plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOhD;AAED,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC,aAAa,GAAG,eAAe,CAAC,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7E,IAAI,EAAE,MAAM,GACX,UAAU,CAcZ"}
+{"version":3,"file":"tunnel-plan.d.ts","sourceRoot":"","sources":["../../src/tunnel-plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOhD;AAED,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC,aAAa,GAAG,eAAe,CAAC,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7E,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,UAAU,CAeZ"}

package/lib/types/tunnel-plan.js

@@ -21,11 +21,19 @@ export function isHttpUrl(value) {
  * token AND a valid public hostname (the token does not carry the hostname,
  * so the QR base and the fence trust would have no source without it);
  * otherwise no tunnel and the manual public base applies.
+ *
+ * The quick target URL names the local webServer port, so a plan made before
+ * the listener binds cannot be quick: it comes back `off` and the caller —
+ * which can observe the port settle — re-plans. The planner itself never
+ * emits an `http://127.0.0.1:undefined` target.
  * @param value - the resolved settings slice that drives the tunnel.
- * @param port - the local webServer port the tunnel forwards to.
+ * @param port - the local webServer port the tunnel forwards to (undefined
+ *   before the listener binds).
  */
 export function tunnelPlanOf(value, port) {
     if (value.autoTunnel === true) {
+        if (port === undefined)
+            return { mode: 'off' };
         const ignored = [];
         if (value.tunnelToken !== undefined && value.tunnelToken !== '')
             ignored.push('tunnelToken');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-remote-web-ui",
   "description": "Scan-to-pair remote access for the dsh web GUI that shares one official interface: a QR beside the settings button pairs phones and PCs into the same Web GUI (a portrait-touch adaptation layer for phones, full desktop on PCs) through one-time tokens and revocable device sessions, with a LAN bind toggle, optional Cloudflare tunnel, and one-click family self-update",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "icon": "icon.svg",
   "type": "module",
   "engines": {
@@ -14,10 +14,6 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./client": {
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
@@ -38,7 +34,7 @@
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.2.0-rc.2"
+      "dsh": ">=0.2.1-rc.2"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -53,7 +49,7 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.4",
+    "@deepseek-ai/schemastery": "^3.18.5",
     "cloudflared": "^0.7.3",
     "clsx": "^2.1.1",
     "qrcode.react": "^4.2.0",
@@ -61,28 +57,27 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh": ">=0.2.1-rc.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-remotes": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-session-controller": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-workspace-controller": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-sidebar": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-commands": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-store": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.1-rc.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/client/RemoteEntry.tsx

@@ -73,10 +73,10 @@ export function RemoteEntry({ wide, t }: RemoteEntryProps) {
     eventSource.current = undefined
   }, [])
 
-  const mint = useCallback(async (address?: string): Promise<PanelState> => {
+  const mint = useCallback(async (): Promise<PanelState> => {
     let result: IssueResponse
     try {
-      result = await issuePair(address)
+      result = await issuePair()
     } catch {
       // Fetch/network failure: show an explicit state instead of silently
       // leaving the panel on its initial banner.
@@ -104,10 +104,6 @@ export function RemoteEntry({ wide, t }: RemoteEntryProps) {
       // Whether this QR is built on the configured public (tunneled) base.
       public: publicBaseUrl !== undefined && result.url.startsWith(publicBaseUrl),
       ...(publicBaseUrl !== undefined ? { publicBaseUrl } : {}),
-      // The issued URL names the requested (or default first) literal; the
-      // public link has no LAN literal, so no radio row is selected then.
-      address: address ?? result.lanAddresses[0] ?? '',
-      lanAddresses: result.lanAddresses,
     }
   }, [])
 
@@ -203,16 +199,6 @@ export function RemoteEntry({ wide, t }: RemoteEntryProps) {
     void mint().then(setState)
   }, [mint])
 
-  /** Re-mint against another LAN literal (multi-homed machines). */
-  const handlePickAddress = useCallback((address: string) => {
-    void mint(address).then(setState)
-  }, [mint])
-
-  /** Re-mint against the configured public (tunneled) base. */
-  const handlePickPublic = useCallback(() => {
-    void mint().then(setState)
-  }, [mint])
-
   const handleCopy = useCallback((url: string) => {
     void copyText(url).then((ok) => {
       if (!ok) return
@@ -247,8 +233,6 @@ export function RemoteEntry({ wide, t }: RemoteEntryProps) {
             onRefresh={handleRefresh}
             onCopy={handleCopy}
             onCopyToken={handleCopyToken}
-            onPickAddress={handlePickAddress}
-            onPickPublic={handlePickPublic}
             onRevoke={handleRevoke}
           />
         </div>