@linxin666/dsh-remote-web-ui 0.3.11 → 0.3.13

package/lib/types/tunnel.js

@@ -1,9 +1,12 @@
 /**
- * Auto-tunnel manager: spawns a Cloudflare quick tunnel (`cloudflared
- * tunnel --url <local>`) through the `cloudflared` npm package — its
- * postinstall downloads the platform binary, so no user-side tooling is
- * involved — surfaces the minted `https://xxx.trycloudflare.com` URL, and
- * restarts the process after unexpected exits with exponential backoff.
+ * Auto-tunnel manager: spawns a Cloudflare tunnel through the `cloudflared`
+ * npm package — its postinstall downloads the platform binary, so no
+ * user-side tooling is involved — surfaces the public URL, and restarts the
+ * process after unexpected exits with exponential backoff. Two modes: the
+ * accountless quick tunnel (`https://xxx.trycloudflare.com`, hostname minted
+ * per start) and an account named tunnel (`cloudflared tunnel run --token`,
+ * fixed public hostname — the mode that lets a paired phone keep its
+ * bookmark and pairing cookie across restarts).
  *
  * The cloudflared package's Tunnel is a thin spawn wrapper; this manager
  * owns the lifecycle policy (binary readiness, URL timeout, restart
@@ -12,15 +15,76 @@
  * a real binary or network.
  */
 import { existsSync } from 'node:fs';
+import { EventEmitter } from 'node:events';
 import { bin, install, Tunnel } from 'cloudflared';
+/** Compare two targets for the start idempotence check. */
+function sameTarget(left, right) {
+    if (left === undefined)
+        return false;
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+ * Wrap a named-tunnel process so it fits the quick-tunnel handle shape: the
+ * fixed public URL is reported through the same `url` event once the first
+ * edge connection registers (cloudflared fires `connected` per connection,
+ * so only the first is taken), and exit/error pass through. The manager's
+ * URL timeout, crash-restart backoff, and stop semantics then stay fully
+ * mode-agnostic.
+ * @param inner - the running named-tunnel process.
+ * @param publicUrl - the fixed public hostname ingress maps to this server.
+ * @returns a handle emitting `url` once the tunnel is reachable.
+ */
+export function namedTunnelHandle(inner, publicUrl) {
+    const handle = new EventEmitter();
+    let registered = false;
+    const onConnected = () => {
+        // cloudflared fires `connected` per edge connection (four on a healthy
+        // registration); the fixed URL only needs reporting once.
+        if (registered)
+            return;
+        registered = true;
+        handle.emit('url', publicUrl);
+    };
+    const onExit = (code, signal) => {
+        handle.emit('exit', code, signal);
+    };
+    const onError = (value) => {
+        handle.emit('error', value);
+    };
+    inner.on('connected', onConnected);
+    inner.on('exit', onExit);
+    inner.on('error', onError);
+    handle.stop = () => {
+        inner.off('connected', onConnected);
+        inner.off('exit', onExit);
+        inner.off('error', onError);
+        return inner.stop();
+    };
+    return handle;
+}
 /** Default binary readiness: download the platform binary on first use. */
 async function defaultEnsureBinary() {
     if (existsSync(bin))
         return;
     await install(bin);
 }
-/** Default factory: the cloudflared package's quick tunnel (no account). */
-function defaultFactory(targetUrl) {
+/** The flags every tunnel mode shares (see the quick factory comment). */
+const SHARED_TUNNEL_FLAGS = { '--no-autoupdate': true, '--protocol': 'http2' };
+/**
+ * Spawn flags for one quick target. `originHostHeader` stamps the Host the
+ * local webserver sees: the plugin's phone-facing fence trusts the configured
+ * public host (the stable relay origin, Host-bound) and the harness
+ * browser-auth binds cookies to the Host authority, while the Workers relay
+ * cannot control the origin-side Host at all (fetch forces it to the URL
+ * authority) — so the connector must restamp it with the stable origin.
+ */
+export function quickTunnelFlags(originHostHeader) {
+    return originHostHeader === undefined
+        ? { ...SHARED_TUNNEL_FLAGS }
+        : { ...SHARED_TUNNEL_FLAGS, '--http-host-header': originHostHeader };
+}
+/** Default factory: the cloudflared package's quick and named tunnels. */
+function defaultFactory(target) {
     // `--no-autoupdate`: the binary must never upgrade itself out from under
     // the manager (a self-updated binary would break the pinned lifecycle).
     // `--protocol http2`: the default `auto` prefers QUIC (UDP 7844), which
@@ -29,7 +93,10 @@ function defaultFactory(targetUrl) {
     // and the auto fallback never fires on a half-open QUIC handshake. http2
     // rides TCP through the same paths reliably (verified live: auto stuck at
     // ready 0 on two fresh registrations; http2 ready immediately).
-    return Tunnel.quick(targetUrl, { '--no-autoupdate': true, '--protocol': 'http2' });
+    if (target.kind === 'quick') {
+        return Tunnel.quick(target.targetUrl, quickTunnelFlags(target.originHostHeader));
+    }
+    return namedTunnelHandle(Tunnel.withToken(target.token, { ...SHARED_TUNNEL_FLAGS }), target.publicUrl);
 }
 /** Node timers. */
 const nodeTimer = { setTimeout, clearTimeout };
@@ -47,7 +114,7 @@ export class TunnelManager {
     phase = 'stopped';
     url;
     error;
-    targetUrl;
+    target;
     handle;
     urlTimer;
     restartTimer;
@@ -78,17 +145,22 @@ export class TunnelManager {
         };
     }
     /**
-     * Start (or keep) a quick tunnel toward `targetUrl`. Restarting with a
-     * different target tears the old tunnel down first; restarting with the
-     * same target while running is a no-op.
-     * @param targetUrl - the local URL to expose, e.g. `http://127.0.0.1:3080`.
+     * Start (or keep) a tunnel toward `target`. Restarting with a different
+     * target tears the old tunnel down first; restarting with the same target
+     * while running is a no-op. A string is the quick mode's local target URL.
+     *
+     * In quick mode the URL surfaces when cloudflared mints the ephemeral
+     * trycloudflare hostname; in named mode the fixed `publicUrl` surfaces
+     * once the first edge connection registers (see {@link namedTunnelHandle}).
+     * @param target - what to run (a string means quick toward that local URL).
      */
-    start(targetUrl) {
-        if (this.targetUrl === targetUrl && (this.phase === 'starting' || this.phase === 'running'))
+    start(target) {
+        const resolved = typeof target === 'string' ? { kind: 'quick', targetUrl: target } : target;
+        if (sameTarget(this.target, resolved) && (this.phase === 'starting' || this.phase === 'running'))
             return;
         this.teardown();
         this.stopping = false;
-        this.targetUrl = targetUrl;
+        this.target = resolved;
         this.attempts = 0;
         this.generation += 1;
         this.attempt();
@@ -97,7 +169,7 @@ export class TunnelManager {
     stop() {
         this.teardown();
         this.stopping = false;
-        this.targetUrl = undefined;
+        this.target = undefined;
         this.setPhase('stopped');
     }
     /** Alias of {@link stop} for plugin-effect disposal. */
@@ -115,7 +187,7 @@ export class TunnelManager {
         return () => { this.phaseListeners.delete(listener); };
     }
     attempt() {
-        if (this.stopping || this.targetUrl === undefined)
+        if (this.stopping || this.target === undefined)
             return;
         const gen = this.generation;
         this.setPhase('starting');
@@ -123,9 +195,9 @@ export class TunnelManager {
         this.url = undefined;
         this.error = undefined;
         void this.ensureBinary().then(() => {
-            if (this.stopping || this.targetUrl === undefined || gen !== this.generation)
+            if (this.stopping || this.target === undefined || gen !== this.generation)
                 return;
-            const handle = this.factory(this.targetUrl);
+            const handle = this.factory(this.target);
             this.handle = handle;
             this.urlTimer = this.timer.setTimeout(() => {
                 // The tunnel never reported a URL: kill it and retry with backoff.
@@ -150,7 +222,7 @@ export class TunnelManager {
             });
         }).catch((value) => {
             // Binary install failed (no network, no platform build): report it.
-            if (this.stopping || this.targetUrl === undefined || gen !== this.generation)
+            if (this.stopping || this.target === undefined || gen !== this.generation)
                 return;
             const message = value instanceof Error ? value.message : String(value);
             this.fail(`could not obtain the cloudflared binary: ${message}`);

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.3.11",
+  "version": "0.3.13",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -36,7 +36,7 @@
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.2-alpha.3"
+      "dsh": ">=0.1.2-alpha.4"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -63,22 +63,22 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-commands": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-commands": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/client/RemoteEntry.tsx

@@ -12,7 +12,7 @@ import { createPortal } from 'react-dom'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { PairingPhase } from '../pairing.ts'
 import { RemotePanel, type PanelState } from './RemotePanel.tsx'
-import { copyText, issuePair, revokePair, stopPair, type DeviceFrame, type IssueResponse, type PairStateFrame, type TunnelStatusFrame } from './pair-api.ts'
+import { copyText, issuePair, revokePair, stopPair, type DeviceFrame, type IssueResponse, type PairStateFrame, type RelayStatusFrame, type TunnelStatusFrame } from './pair-api.ts'
 import { PhoneIcon } from './PhoneIcon.tsx'
 import { UpdateEntry } from './UpdateEntry.tsx'
 import css from './remote.module.css'
@@ -43,6 +43,7 @@ function mergeFrame(state: PanelState, frame: PairStateFrame): PanelState {
     onlineCount: frame.onlineCount,
     devices: frame.devices ?? [],
     ...(frame.tunnel !== undefined ? { tunnel: frame.tunnel as TunnelStatusFrame } : {}),
+    ...(frame.relay !== undefined ? { relay: frame.relay } : {}),
     ...(frame.posture !== undefined ? { posture: frame.posture } : {}),
   }
 }

package/src/client/RemotePanel.tsx

@@ -16,6 +16,7 @@ import {
   formatLastSeen,
   type DeviceFrame,
   type PostureFrame,
+  type RelayStatusFrame,
   type TunnelStatusFrame,
 } from './pair-api.ts'
 import { deviceNameFromUserAgent } from './device-name.ts'
@@ -46,6 +47,8 @@ export type PanelState =
       publicBaseUrl?: string
       /** Auto-tunnel status, while the auto-tunnel feature is active. */
       tunnel?: TunnelStatusFrame
+      /** Relay-registry status, while the stable-origin relay is in play. */
+      relay?: RelayStatusFrame
       /** Latest /api posture probe, once a round has completed. */
       posture?: PostureFrame
     }
@@ -164,6 +167,14 @@ export function RemotePanel({ t, state, copied, onClose, onStop, onRefresh, onCo
                 : t('tunnel.starting')}
             </p>
           )}
+          {state.relay?.state === 'registering' && (
+            <p className={css.tunnelNote} role="status">{t('relay.registering')}</p>
+          )}
+          {state.relay?.state === 'failed' && (
+            <p className={css.tunnelFailed} role="status">
+              {t('relay.failed', { error: state.relay.error ?? t('tunnel.unknownError') })}
+            </p>
+          )}
 
           {(state.publicBaseUrl !== undefined || state.lanAddresses.length > 1) && (
             <fieldset className={css.addresses}>

package/src/client/RemoteSettingsCard.tsx

@@ -9,7 +9,7 @@ import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-cli
 import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { PluginSettingsCard, ValueField, BooleanField } from './PluginSettingsCard.tsx'
-import { CardForm, booleanField, numberField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
+import { CardForm, booleanField, numberField, secretField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
 import { readLanBindStatus, type LanBindFrame } from './pair-api.ts'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 
@@ -33,6 +33,18 @@ export interface RemoteSettings {
   publicBaseUrl?: string
   /** When on, the plugin runs its own Cloudflare quick tunnel automatically. */
   autoTunnel?: boolean
+  /**
+   * Cloudflare named-tunnel token: when set (and autoTunnel is off), the
+   * plugin runs the named tunnel toward the fixed public hostname — a phone
+   * paired once keeps its session across restarts.
+   */
+  tunnelToken?: string
+  /**
+   * Stable-origin relay: when on (default), the quick tunnel is fronted by a
+   * fixed `<id>.dsh-market.com` subdomain so the phone's bookmark and
+   * pairing cookie survive restarts without any setup.
+   */
+  relay?: boolean
   /**
    * LAN bind toggle: once flipped, the plugin manages the profile patch's
    * webserver block (0.0.0.0 / 127.0.0.1) and the host firewall rule.
@@ -60,6 +72,10 @@ export interface RemoteSettingsCardState extends CardShell {
   publicBaseUrl: CardFieldState
   /** Auto public tunnel switch. */
   autoTunnel: CardFieldState
+  /** Named-tunnel token (stored redacted by the Host). */
+  tunnelToken: CardFieldState
+  /** Stable-origin relay switch. */
+  relay: CardFieldState
   /** LAN bind toggle. */
   lanBind: CardFieldState
 }
@@ -89,6 +105,8 @@ export class RemoteSettingsCardController {
       booleanField('requirePairingForLan'),
       textField('publicBaseUrl'),
       booleanField('autoTunnel'),
+      secretField('tunnelToken'),
+      booleanField('relay'),
       booleanField('lanBind'),
     ])
     this.store = this.form.bind(() => this.projection())
@@ -106,6 +124,8 @@ export class RemoteSettingsCardController {
       requirePairingForLan: this.form.field('requirePairingForLan'),
       publicBaseUrl: this.form.field('publicBaseUrl'),
       autoTunnel: this.form.field('autoTunnel'),
+      tunnelToken: this.form.field('tunnelToken'),
+      relay: this.form.field('relay'),
       lanBind: this.form.field('lanBind'),
     }
   }
@@ -253,6 +273,28 @@ export function RemoteSettingsCard(props: RemoteSettingsCardProps) {
         onEdit={(text) => { props.edit('autoTunnel', text) }}
         onReset={() => { props.resetField('autoTunnel') }}
       />
+      <ValueField
+        id="settings-remote-tunnel-token"
+        label={t('settings.tunnelToken')}
+        hint={t('settings.tunnelTokenHint')}
+        placeholder="eyJ..."
+        {...fieldProps}
+        {...state.tunnelToken}
+        onEdit={(text) => { props.edit('tunnelToken', text) }}
+        onReset={() => { props.resetField('tunnelToken') }}
+      />
+      <BooleanField
+        id="settings-remote-relay"
+        label={t('settings.relay')}
+        hint={t('settings.relayHint')}
+        inheritLabel={t('settings.inherit')}
+        onLabel={t('settings.on')}
+        offLabel={t('settings.off')}
+        {...fieldProps}
+        {...state.relay}
+        onEdit={(text) => { props.edit('relay', text) }}
+        onReset={() => { props.resetField('relay') }}
+      />
       <LanBindStatus t={t} />
       <BooleanField
         id="settings-remote-lan-bind"

package/src/client/locales.ts

@@ -65,6 +65,8 @@ export const zh = {
   'tunnel.starting': '公网隧道启动中，二维码将自动变为公网链接…',
   'tunnel.failed': '公网隧道启动失败：{error}',
   'tunnel.unknownError': '未知错误',
+  'relay.registering': '正在把临时隧道同步到固定域名（<id>.dsh-market.com）…',
+  'relay.failed': '固定域名同步失败：{error}。正在自动重试，期间二维码可能使用临时地址。',
   'close.label': '关闭远程访问面板',
   // 插件设置卡片（settings.plugin.item 席位）。
   'settings.title': '远程访问设置',
@@ -84,9 +86,13 @@ export const zh = {
   'settings.requirePairingForLan': '局域网访问要求配对',
   'settings.requirePairingForLanHint': '开启：非本机回环的桌面 Web GUI 改走门控的 /remote，必须携带有效配对 Cookie；关闭：桌面继续走普通路径（仅在该来源已被 SDK 信任时有意义），配对只管理令牌与状态。',
   'settings.publicBaseUrl': '公网地址（可选）',
-  'settings.publicBaseUrlHint': '内网穿透的公网地址，如 Cloudflare Tunnel：https://xxx.trycloudflare.com。填写后二维码将生成公网链接，手机不在同一网络也能配对；留空则仅局域网可用。',
+  'settings.publicBaseUrlHint': '内网穿透的公网地址，如 Cloudflare Tunnel：https://xxx.trycloudflare.com；固定域名隧道（下方令牌）也填这里。填写后二维码将生成公网链接，手机不在同一网络也能配对；留空则仅局域网可用。',
   'settings.autoTunnel': '自动公网隧道',
-  'settings.autoTunnelHint': '开启后插件自动启动 Cloudflare quick tunnel（无需安装任何工具），并自动更新公网地址与信任配置，手机随时可用公网配对；关闭时使用上方手动填写的公网地址。',
+  'settings.autoTunnelHint': '开启后插件自动启动 Cloudflare quick tunnel（无需安装任何工具），并自动更新公网地址与信任配置，手机随时可用公网配对；注意临时域名每次重启都会变化，手机需重新扫码。开启时忽略下方固定隧道令牌与上方手动公网地址。',
+  'settings.tunnelToken': '固定域名隧道令牌（Cloudflare Tunnel）',
+  'settings.tunnelTokenHint': '填入 Cloudflare 命名隧道的 Token（即 cloudflared tunnel run --token 的值），插件会自动运行该隧道：公共主机名固定不变，手机配对一次后重启也无需重新配对。需先在 Cloudflare 控制台把公共主机名映射到 http://127.0.0.1:<端口>，并在上方"公网地址"填写同一域名。优先级低于"自动公网隧道"。',
+  'settings.relay': '固定域名中继（推荐开启）',
+  'settings.relayHint': '开启后自动隧道会额外注册一个固定不变的公网子域名（<id>.dsh-market.com，由 dsh-market 边缘中继到你的临时隧道），手机配对一次后重启无需重新扫码，二维码与书签地址永远不变。流量经由 dsh-market 边缘转发（与临时隧道相同的信任面）；关闭则回退为纯临时地址，每次重启需重新配对。仅对"自动公网隧道"生效。',
   'settings.lanBind': '局域网访问（绑定 0.0.0.0）',
   'settings.lanBindHint': '开启后插件把绑定默认改写为 0.0.0.0 并写入 profile 补丁（显式 --host 仍优先），同时维护主机防火墙放行（Windows/Linux；macOS 无需管理）；关闭回退 127.0.0.1。绑定变化通常在重启 dsh web 后生效。',
   'lan.cardTitle': '局域网访问',
@@ -229,6 +235,8 @@ export const en = {
   'tunnel.starting': 'The public tunnel is starting; the QR code will switch to a public link shortly…',
   'tunnel.failed': 'The public tunnel failed to start: {error}',
   'tunnel.unknownError': 'unknown error',
+  'relay.registering': 'Syncing the ephemeral tunnel to the stable hostname (<id>.dsh-market.com)…',
+  'relay.failed': 'Stable-hostname sync failed: {error}. Retrying automatically; the QR may use the ephemeral address meanwhile.',
   'close.label': 'Close remote access panel',
   // Plugin settings card (the `settings.plugin.item` seat).
   'settings.title': 'Remote access settings',
@@ -248,9 +256,13 @@ export const en = {
   'settings.requirePairingForLan': 'Require pairing for LAN access',
   'settings.requirePairingForLanHint': 'On: a desktop Web GUI at a non-loopback origin rides the gated /remote channel and must carry a live paired-device cookie. Off: the desktop stays on its original paths (only useful when that origin is already trusted) and pairing only manages tokens/status.',
   'settings.publicBaseUrl': 'Public address (optional)',
-  'settings.publicBaseUrlHint': 'The public URL of a tunnel in front of this server, e.g. a Cloudflare Tunnel: https://xxx.trycloudflare.com. When set, the QR link is built from it so a phone anywhere can pair; leave blank for LAN-only usage.',
+  'settings.publicBaseUrlHint': 'The public URL of a tunnel in front of this server, e.g. a Cloudflare Tunnel: https://xxx.trycloudflare.com; a fixed-hostname tunnel (token below) also goes here. When set, the QR link is built from it so a phone anywhere can pair; leave blank for LAN-only usage.',
   'settings.autoTunnel': 'Auto public tunnel',
-  'settings.autoTunnelHint': 'When on, the plugin runs its own Cloudflare quick tunnel (no tool installation needed) and keeps the public address and trust config in sync automatically, so a phone anywhere can pair at any time; when off, the manually entered public address above applies.',
+  'settings.autoTunnelHint': 'When on, the plugin runs its own Cloudflare quick tunnel (no tool installation needed) and keeps the public address and trust config in sync automatically, so a phone anywhere can pair at any time; note the ephemeral hostname changes on every restart, so phones must scan again. The named-tunnel token below and the manual public address above are ignored while this is on.',
+  'settings.tunnelToken': 'Fixed-hostname tunnel token (Cloudflare Tunnel)',
+  'settings.tunnelTokenHint': 'Paste a Cloudflare named-tunnel token (the value of cloudflared tunnel run --token) and the plugin runs the tunnel itself: the public hostname stays fixed, so a phone pairs once and never again across restarts. First map the public hostname to http://127.0.0.1:<port> in the Cloudflare dashboard and enter the same hostname as the public address above. Lower precedence than the auto quick tunnel.',
+  'settings.relay': 'Stable-hostname relay (recommended)',
+  'settings.relayHint': 'When on, the auto tunnel additionally registers a never-changing public subdomain (<id>.dsh-market.com, relayed by the dsh-market edge to your ephemeral tunnel), so a phone pairs once and the QR and bookmark stay valid across restarts. Traffic transits the dsh-market edge (the same trust point as the ephemeral tunnel); turn off to fall back to the raw ephemeral address, which needs re-pairing after every restart. Applies to the auto public tunnel only.',
   'settings.lanBind': 'LAN access (bind 0.0.0.0)',
   'settings.lanBindHint': 'When on, the plugin writes a managed block into the profile patch defaulting the bind to 0.0.0.0 (an explicit --host flag still wins), and maintains the matching host firewall rule (Windows/Linux; other platforms need none). When off, the block pins 127.0.0.1. The bind change usually takes effect after dsh web restarts.',
   'lan.cardTitle': 'LAN access',

package/src/client/pair-api.ts

@@ -62,6 +62,15 @@ export interface TunnelStatusFrame {
   error?: string
 }
 
+/** One relay-registry status frame (absent while the relay is not in play). */
+export interface RelayStatusFrame {
+  state: 'off' | 'registering' | 'running' | 'failed'
+  /** The stable relay origin, once registered. */
+  url?: string
+  /** Human-readable failure detail of the last sync attempt. */
+  error?: string
+}
+
 /** One /api posture frame (host half probe; see src/posture.ts). */
 export interface PostureFrame {
   checkedAt: number
@@ -81,6 +90,8 @@ export interface PairStateFrame {
   devices?: DeviceFrame[]
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   tunnel?: TunnelStatusFrame
+  /** Relay-registry status, while the stable-origin relay is in play. */
+  relay?: RelayStatusFrame
   /** Latest /api fence posture probe, once a round has completed. */
   posture?: PostureFrame
 }

package/src/client/settings-card.module.css

@@ -72,7 +72,10 @@
 }
 
 .description {
-  color: var(--dsw-alias-label-tertiary);
+  /* Secondary, not tertiary: skins whose tertiary token is tuned for large
+     print leave 12-13px hint text below readable contrast (orca-link #778399
+     on cream measures ~3.4:1). */
+  color: var(--dsw-alias-label-secondary);
   font-size: 13px;
   line-height: 1.5;
 }
@@ -106,7 +109,7 @@
 }
 
 .readOnly {
-  color: var(--dsw-alias-label-tertiary);
+  color: var(--dsw-alias-label-secondary);
   margin: 12px 0 0;
   font-size: 12px;
   line-height: 1.5;
@@ -130,7 +133,10 @@
 
 .failed {
   min-width: 0;
-  color: var(--dsw-alias-label-error);
+  /* The suite's error alias is state-error-primary; a label-error token does
+     not exist, so the var() would resolve to nothing and the message would
+     inherit the ink color, losing the failure signal. */
+  color: var(--dsw-alias-state-error-primary, #b42318);
   flex: 1;
   margin: 0;
   font-size: 12px;
@@ -278,7 +284,7 @@
 }
 
 .inputInvalid {
-  border: 1px solid var(--dsw-alias-label-error);
+  border: 1px solid var(--dsw-alias-state-error-primary, #b42318);
   background: var(--dsw-alias-bg-layer-3);
   height: 34px;
   font: inherit;
@@ -290,9 +296,9 @@
 }
 
 .inputInvalid:focus-visible {
-  outline: 2px solid var(--dsw-alias-label-error);
+  outline: 2px solid var(--dsw-alias-state-error-primary, #b42318);
   outline-offset: 1px;
-  border-color: var(--dsw-alias-label-error);
+  border-color: var(--dsw-alias-state-error-primary, #b42318);
 }
 
 .selectWrap {
@@ -384,14 +390,14 @@
 }
 
 .invalid {
-  color: var(--dsw-alias-label-error);
+  color: var(--dsw-alias-state-error-primary, #b42318);
   margin: 0;
   font-size: 12px;
   line-height: 1.5;
 }
 
 .hint {
-  color: var(--dsw-alias-label-tertiary);
+  color: var(--dsw-alias-label-secondary);
   margin: 0;
   font-size: 12px;
   line-height: 1.5;