@linxin666/dsh-remote-web-ui 0.3.12 → 0.3.14

package/lib/types/index.js

@@ -22,6 +22,8 @@ import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from
 import { lanIPv4Addresses } from "./lan.js";
 import { ensureFirewallRule, firewallSummary, removeFirewallRule } from "./firewall.js";
 import { lanBindState, writeLanBind } from "./lan-bind.js";
+import { isHttpUrl, tunnelPlanOf } from "./tunnel-plan.js";
+import { loadRelayIdentity, RelayRegistrar } from "./relay-registry.js";
 import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf } from "./lan-bind-plan.js";
 import { createInnerAuth } from "./inner-auth.js";
 import { TunnelManager } from "./tunnel.js";
@@ -50,6 +52,8 @@ export const Config = z.object({
     publicBaseUrl: z.string(),
     devicesFile: z.string(),
     autoTunnel: z.boolean().default(false),
+    tunnelToken: z.string().role('secret'),
+    relay: z.boolean().default(true),
     lanBind: z.boolean(),
     profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
     enabled: z.boolean().default(true),
@@ -87,6 +91,8 @@ const DEFAULTS = {
     publicBaseUrl: undefined,
     devicesFile: defaultDevicesFile(),
     autoTunnel: false,
+    tunnelToken: undefined,
+    relay: true,
     lanBind: undefined,
     profile: process.env.DSH_PROFILE ?? 'web',
     enabled: true,
@@ -108,6 +114,8 @@ function applyImpl(ctx, config) {
         publicBaseUrl: config?.publicBaseUrl,
         devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
         autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
+        tunnelToken: config?.tunnelToken,
+        relay: config?.relay ?? DEFAULTS.relay,
         lanBind: config?.lanBind,
         profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
         enabled: config?.enabled ?? DEFAULTS.enabled,
@@ -128,6 +136,8 @@ function applyImpl(ctx, config) {
             publicBaseUrl: value.publicBaseUrl,
             devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
             autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
+            tunnelToken: value.tunnelToken,
+            relay: value.relay ?? DEFAULTS.relay,
             lanBind: value.lanBind,
             profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
             enabled: value.enabled ?? DEFAULTS.enabled,
@@ -141,27 +151,100 @@ function applyImpl(ctx, config) {
     // mutation is needed here (a distributable plugin must not change the
     // harness's connection plugin).
     const tunnel = new TunnelManager();
-    let autoTunnel = resolved.autoTunnel;
+    // Relay registry: one stable `<id>.dsh-market.com` subdomain per profile
+    // in front of the quick tunnel. The QR base prefers the relay origin once
+    // it is registered; until then (or when the registry is unreachable) the
+    // raw quick URL is used, exactly as before. Named tunnels keep their fixed
+    // dashboard hostname and never touch the relay.
+    let relayRegistrar;
+    let relayUrl;
+    let rawTunnelUrl;
+    /** The tunnel target the registrar last announced (dedupes sync re-runs). */
+    let relayAnnouncedFor;
+    const setPublicBase = () => {
+        service.setPublicBaseUrl(relayUrl ?? rawTunnelUrl);
+    };
+    const disposeRelayRegistrar = (unregister = false) => {
+        const registrar = relayRegistrar;
+        relayRegistrar = undefined;
+        relayUrl = undefined;
+        relayAnnouncedFor = undefined;
+        if (registrar === undefined)
+            return;
+        // Toggle-off removes the registry row so the stable origin stops
+        // proxying; teardown/mode changes keep the row (the phone then sees the
+        // relay's offline page instead of a dangling claim, and re-enabling
+        // reuses the same identity).
+        if (unregister)
+            void registrar.unregister().catch(() => undefined);
+        registrar.dispose();
+    };
+    const ensureRelayRegistrar = () => {
+        if (resolve().relay === false)
+            return undefined;
+        if (relayRegistrar === undefined) {
+            try {
+                const identity = loadRelayIdentity(resolve().profile);
+                relayRegistrar = new RelayRegistrar(identity, (state) => {
+                    service.setRelayStatus(state.state === 'off' ? undefined : state);
+                    if (state.state === 'running') {
+                        relayUrl = state.url;
+                    }
+                    else if (state.state === 'off') {
+                        relayUrl = undefined;
+                    }
+                    else if (state.state === 'failed') {
+                        // Keep the last relay URL on failures: the phone origin only
+                        // breaks when the mapping itself goes stale, not when one
+                        // refresh call fails. The registrar retries with backoff.
+                        console.warn(`remote-web-ui: relay registration failed (${state.error}) — the stable origin may serve its offline page until the retry lands`);
+                    }
+                    setPublicBase();
+                });
+            }
+            catch (error) {
+                console.warn(`remote-web-ui: relay registry unavailable (${error instanceof Error ? error.message : String(error)}) — the quick URL is the QR base`);
+            }
+        }
+        return relayRegistrar;
+    };
+    const announceRelay = (registrar, target) => {
+        if (relayAnnouncedFor === target)
+            return;
+        relayAnnouncedFor = target;
+        void registrar.announce(target);
+    };
+    // '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 = resolved.autoTunnel ? 'quick' : 'off';
     tunnel.onPhase((info) => {
-        if (!autoTunnel)
+        if (tunnelMode === 'off')
             return;
         if (info.phase === 'running' && info.url !== undefined) {
-            service.setPublicBaseUrl(info.url);
+            rawTunnelUrl = info.url;
+            setPublicBase();
             service.setTunnelStatus({ state: 'running', url: info.url });
+            const registrar = tunnelMode === 'quick' ? ensureRelayRegistrar() : undefined;
+            if (registrar !== undefined)
+                announceRelay(registrar, info.url);
             runPostureProbe();
         }
         else if (info.phase === 'starting') {
             // A restart mints a NEW hostname: the previous URL dies with the old
             // process, so clear it now rather than advertising a dead link.
-            service.setPublicBaseUrl(undefined);
+            rawTunnelUrl = undefined;
+            relayUrl = undefined;
+            setPublicBase();
             service.setTunnelStatus({ state: 'starting' });
         }
         else if (info.phase === 'failed') {
-            service.setPublicBaseUrl(undefined);
+            rawTunnelUrl = undefined;
+            setPublicBase();
             service.setTunnelStatus(info.error === undefined ? { state: 'failed' } : { state: 'failed', error: info.error });
         }
     });
     ctx.effect(() => () => {
+        disposeRelayRegistrar();
         tunnel.dispose();
     }, 'remote-web-ui: auto tunnel');
     // The bind facts are known by now (webServer is an inject edge): the LAN
@@ -510,18 +593,60 @@ function applyImpl(ctx, config) {
                 }
             }
         }
-        // The auto tunnel owns the public base while enabled: the minted URL
-        // lands in the service through the tunnel's phase listener. The manual
-        // publicBaseUrl applies only when the auto tunnel is off.
-        autoTunnel = value.autoTunnel === true;
-        if (autoTunnel) {
-            if (value.publicBaseUrl !== undefined) {
-                console.warn('remote-web-ui: autoTunnel is on — ignoring the manually configured publicBaseUrl');
+        // 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);
+        tunnelMode = plan.mode;
+        if (plan.mode !== 'quick') {
+            // The relay only fronts the quick tunnel; named mode owns its fixed
+            // dashboard hostname and the off mode has no public base at all.
+            disposeRelayRegistrar();
+            if (plan.mode !== 'named')
+                setPublicBase();
+        }
+        else if (value.relay === false) {
+            // The relay toggle is off: no stable origin, the raw quick URL is the
+            // QR base exactly as before the relay existed.
+            disposeRelayRegistrar(true);
+            setPublicBase();
+        }
+        else if (rawTunnelUrl !== undefined) {
+            // The relay just turned on (or the registrar is new) while the tunnel
+            // already runs: announce now — no phase event will fire for an
+            // unchanged target.
+            const registrar = ensureRelayRegistrar();
+            if (registrar !== undefined)
+                announceRelay(registrar, rawTunnelUrl);
+        }
+        if (plan.mode === 'quick') {
+            for (const ignored of plan.ignored) {
+                console.warn(`remote-web-ui: autoTunnel is on — ignoring the configured ${ignored}`);
             }
-            tunnel.start(`http://127.0.0.1:${String(ctx.webServer.port)}`);
+            // With the relay on, the connector stamps the stable origin as the
+            // origin-side Host (`--http-host-header`): the plugin fence and the
+            // harness browser-auth are Host-bound to the relay origin, and the
+            // Workers relay cannot control the origin-side Host (fetch forces it
+            // to the URL authority). The target identity change is also what
+            // restarts a running tunnel on a relay toggle.
+            const registrar = ensureRelayRegistrar();
+            const originHostHeader = registrar === undefined ? undefined : new URL(registrar.baseUrl).host;
+            tunnel.start(originHostHeader === undefined
+                ? plan.targetUrl
+                : { kind: 'quick', targetUrl: plan.targetUrl, originHostHeader });
+        }
+        else if (plan.mode === 'named') {
+            tunnel.start({ kind: 'named', token: plan.token, publicUrl: plan.publicUrl });
         }
         else {
             tunnel.stop();
+            // A named-tunnel token without a usable public hostname cannot serve
+            // the QR: stay off and say exactly what is missing instead of running
+            // a tunnel nothing points at.
+            if (value.tunnelToken !== undefined && value.tunnelToken !== '') {
+                console.warn('remote-web-ui: tunnelToken is set but publicBaseUrl is missing or not a valid URL — fill the fixed public hostname of the named tunnel (e.g. https://dsh.example.com) to run it');
+            }
             // A malformed public base is ignored with a warning — LAN-only behavior
             // stays intact rather than silently minting unusable QR links.
             if (value.publicBaseUrl !== undefined && !isHttpUrl(value.publicBaseUrl)) {
@@ -594,13 +719,3 @@ function applyImpl(ctx, config) {
     });
     sync();
 }
-/** Whether a configured public base is a parseable http(s) URL with a host. */
-function isHttpUrl(value) {
-    try {
-        const url = new URL(value);
-        return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== '';
-    }
-    catch {
-        return false;
-    }
-}

package/lib/types/pairing.d.ts

@@ -89,6 +89,18 @@ export interface TunnelStatus {
     /** Human-readable failure detail. */
     error?: string;
 }
+/**
+ * One relay-registry status frame (undefined while the stable-origin relay
+ * is not in play: autoTunnel off, or the relay toggle disabled).
+ */
+export interface RelayStatus {
+    /** registering: a sync is in flight; running: the mapping is accepted. */
+    state: 'off' | 'registering' | 'running' | 'failed';
+    /** The stable relay origin (`https://<id>.dsh-market.com`). */
+    url?: string;
+    /** Human-readable failure detail of the last sync attempt. */
+    error?: string;
+}
 /** One snapshot frame pushed to desktop status streams. */
 export interface PairingSnapshot {
     phase: PairingPhase;
@@ -100,6 +112,8 @@ export interface PairingSnapshot {
     publicUrl?: string;
     /** Auto-tunnel status, while the auto-tunnel feature is active. */
     tunnel?: TunnelStatus;
+    /** Relay-registry status, while the stable-origin relay is in play. */
+    relay?: RelayStatus;
     /** Latest /api posture probe (undefined until the first round completes). */
     posture?: PostureSnapshot;
     /** Opaque (non-secret) id of the active token (undefined when stopped/lan-required). */
@@ -182,6 +196,7 @@ export declare class PairingService {
     private publicBase;
     /** Auto-tunnel status, while the auto-tunnel feature is active. */
     private tunnelStatus;
+    private relayStatus;
     private posture;
     /** True when lastSeenAt changed since the last persist (flushed on sweep). */
     private dirty;
@@ -230,6 +245,8 @@ export declare class PairingService {
     setPublicBaseUrl(url: string | undefined): void;
     /** Set or clear the auto-tunnel status frame (undefined when the feature is off). */
     setTunnelStatus(status: TunnelStatus | undefined): void;
+    /** Set or clear the relay-registry status frame (undefined when not in play). */
+    setRelayStatus(status: RelayStatus | undefined): void;
     /** Set the latest /api posture probe result (see posture.ts). */
     setPosture(snapshot: PostureSnapshot | undefined): void;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEnD,uDAAuD;AACvD,MAAM,MAAM,YAAY;AACtB,mEAAmE;AACjE,cAAc;AAChB,oEAAoE;GAClE,SAAS;AACX,4DAA4D;GAC1D,SAAS;AACX,sDAAsD;GACpD,WAAW;AACb,6EAA6E;GAC3E,cAAc,CAAA;AAElB,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAA;IACjB,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAA;IACV,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAA2B,CAAA;AAK9D,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAA;IACV,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAA;IACf,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAA;IACxC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAA;IACnB,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAA;IACnB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAA;IACnB,iFAAiF;IACjF,OAAO,EAAE,cAAc,EAAE,CAAA;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,sCAAsC;AACtC,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAA;AAE3C,yEAAyE;AACzE,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C;;OAEG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,GAAG,IAAI,MAAM,CAAA;IACb,WAAW,IAAI,MAAM,CAAA;CACtB;AAED,yDAAyD;AACzD,eAAO,MAAM,YAAY,EAAE,YAG1B,CAAA;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAwBhB,MAAM,EAAE,aAAa;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAxBxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,WAAW,CAAI;IACvB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAA4B;IAC5C,sEAAsE;IACtE,OAAO,CAAC,UAAU,CAAoB;IACtC,mEAAmE;IACnE,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,OAAO,CAA6B;IAC5C,8EAA8E;IAC9E,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;OAKG;gBAEM,MAAM,EAAE,aAAa,EACX,KAAK,GAAE,YAA2B;IAKrD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IA6BrB,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB;IAOzB,iEAAiE;IACjE,OAAO,CAAC,SAAS;IAajB;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO;IAgBf,wFAAwF;IACxF,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;IAED,oFAAoF;IACpF,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIlD,wEAAwE;IACxE,IAAI,YAAY,IAAI,MAAM,EAAE,CAE3B;IAED,6EAA6E;IAC7E,WAAW,CAAC,OAAO,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAKxE,+DAA+D;IAC/D,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAEtC;IAED,2EAA2E;IAC3E,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAK/C,qFAAqF;IACrF,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAKvD,iEAAiE;IACjE,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI;IAKvD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAwBnF;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY;IA6BvD;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAQZ;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQjC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQtC,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIpC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAMb,2EAA2E;IAC3E,QAAQ,IAAI,eAAe;IAqB3B,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIpC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlE,OAAO,CAAC,WAAW;IASnB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,MAAM;CAaf;AAwCD,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAK7E"}
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/pairing.ts"],"names":[],"mappings":"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"}

package/lib/types/pairing.js

@@ -74,6 +74,7 @@ export class PairingService {
     publicBase;
     /** Auto-tunnel status, while the auto-tunnel feature is active. */
     tunnelStatus;
+    relayStatus;
     posture;
     /** True when lastSeenAt changed since the last persist (flushed on sweep). */
     dirty = false;
@@ -205,6 +206,11 @@ export class PairingService {
         this.tunnelStatus = status;
         this.notify();
     }
+    /** Set or clear the relay-registry status frame (undefined when not in play). */
+    setRelayStatus(status) {
+        this.relayStatus = status;
+        this.notify();
+    }
     /** Set the latest /api posture probe result (see posture.ts). */
     setPosture(snapshot) {
         this.posture = snapshot;
@@ -361,6 +367,7 @@ export class PairingService {
             lanAddresses: [...this.lanBases.keys()],
             ...(this.publicBase !== undefined ? { publicUrl: this.publicBase } : {}),
             ...(this.tunnelStatus !== undefined ? { tunnel: this.tunnelStatus } : {}),
+            ...(this.relayStatus !== undefined ? { relay: this.relayStatus } : {}),
             ...(this.posture !== undefined ? { posture: this.posture } : {}),
             ...(token !== undefined ? { tokenId: token.record.id, tokenExpiresAt: token.record.expiresAt } : {}),
             deviceCount: this.devices.size,
@@ -454,6 +461,7 @@ function snapshotsEqual(a, b) {
         && sameStrings(a.lanAddresses, b.lanAddresses)
         && a.publicUrl === b.publicUrl
         && tunnelEqual(a.tunnel, b.tunnel)
+        && relayEqual(a.relay, b.relay)
         && a.tokenId === b.tokenId
         && a.tokenExpiresAt === b.tokenExpiresAt
         && a.deviceCount === b.deviceCount
@@ -477,6 +485,11 @@ function tunnelEqual(a, b) {
     return a === b || (a !== undefined && b !== undefined
         && a.state === b.state && a.url === b.url && a.error === b.error);
 }
+/** Relay frame equality (same shape as the tunnel frame). */
+function relayEqual(a, b) {
+    return a === b || (a !== undefined && b !== undefined
+        && a.state === b.state && a.url === b.url && a.error === b.error);
+}
 /** Element-wise string list equality (interface order is meaningful). */
 function sameStrings(a, b) {
     return a.length === b.length && a.every((value, index) => value === b[index]);

package/lib/types/relay-registry.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Relay registry client: a stable `https://<id>.dsh-market.com` origin in
+ * front of the plugin-managed quick tunnel, so a paired phone keeps one
+ * bookmark and one cookie context across `dsh web` restarts.
+ *
+ * The plugin mints an id + secret on first run and persists them per profile
+ * under `$DSH_HOME/remote-web-ui-registry/`; every tunnel (re)start
+ * re-registers the current quick URL with the market worker. Registration is
+ * best-effort: a registry outage never blocks the tunnel — the QR just falls
+ * back to the raw quick URL for that session (the pre-relay behavior).
+ */
+/** The market worker's registration endpoints (dsh-market.com edge API). */
+export declare const RELAY_REGISTER_URL = "https://dsh-market.com/api/relay/register";
+export declare const RELAY_UNREGISTER_URL = "https://dsh-market.com/api/relay/unregister";
+/**
+ * The public origin template: one stable single-label subdomain per
+ * registration id. Single label on purpose — Universal SSL covers exactly
+ * one subdomain level, so a two-level hostname would get no certificate.
+ */
+export declare const RELAY_BASE_SUFFIX = ".dsh-market.com";
+export declare const RELAY_ID_RE: RegExp;
+export declare const RELAY_SECRET_RE: RegExp;
+/** Persisted per-profile relay identity. */
+export interface RelayIdentity {
+    id: string;
+    secret: string;
+    /**
+     * True only for an identity minted in this process that has never been
+     * accepted by the registry: the first register carries `new_secret` so
+     * the endpoint may create the row; refreshes authenticate with `secret`
+     * alone and must not re-claim an id that already exists.
+     */
+    fresh?: boolean;
+}
+/** The observable relay lifecycle the settings card renders. */
+export type RelayState = {
+    state: 'off';
+} | {
+    state: 'registering';
+} | {
+    state: 'running';
+    url: string;
+} | {
+    state: 'failed';
+    error: string;
+};
+/** Registry storage layout: one file per profile under the relay directory. */
+export declare function relayIdentityFile(profile: string, home?: string): string;
+/** Generate one identity pair (id: 8-byte hex slug; secret: 32-byte base64url). */
+export declare function generateRelayIdentity(random?: (size: number) => Buffer): RelayIdentity;
+/**
+ * Load (or lazily mint) the per-profile relay identity. The file is written
+ * owner-only on first mint; a corrupt file is reminted (the phone then
+ * re-pairs once — the same cost as losing the devices file).
+ */
+export declare function loadRelayIdentity(profile: string, home?: string, random?: (size: number) => Buffer): RelayIdentity;
+/** Best-effort removal of the mapping (used on disable; errors are swallowed). */
+export declare function unregisterRelay(identity: RelayIdentity, endpoint?: string, fetchFn?: typeof fetch): Promise<void>;
+/**
+ * The stable relay base for one identity — the origin the QR and the phone
+ * bookmark use while (or after) the registration is accepted.
+ */
+export declare function relayBaseOf(identity: RelayIdentity): string;
+/**
+ * Registration loop with capped exponential backoff. Re-registration happens
+ * on every tunnel start (the quick URL can change after a crash-restart);
+ * failures retry with backoff and surface the last error to the card.
+ */
+export declare class RelayRegistrar {
+    private readonly identity;
+    private readonly setState;
+    private readonly options;
+    private timer;
+    private attempts;
+    private lastError;
+    private disposed;
+    constructor(identity: RelayIdentity, setState: (state: RelayState) => void, options?: {
+        fetchFn?: typeof fetch;
+        registerUrl?: string;
+        unregisterUrl?: string;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        timerFn?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    });
+    /** The stable relay base for the QR while registered. */
+    get baseUrl(): string;
+    /** The last registration failure detail (undefined while healthy). */
+    get error(): string | undefined;
+    /** Push one tunnel target; resolves the stable base once accepted. */
+    announce(target: string): Promise<string | undefined>;
+    /** Best-effort removal of the registry row (the relay toggle turned off). */
+    unregister(): Promise<void>;
+    private scheduleRetry;
+    /** Stop retrying and clear the card state (tunnel stopped or disabled). */
+    dispose(): void;
+}
+//# sourceMappingURL=relay-registry.d.ts.map

package/lib/types/relay-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-registry.d.ts","sourceRoot":"","sources":["../../src/relay-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,8CAA8C,CAAA;AAC7E,eAAO,MAAM,oBAAoB,gDAAgD,CAAA;AACjF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAA;AAElD,eAAO,MAAM,WAAW,QAAmB,CAAA;AAC3C,eAAO,MAAM,eAAe,QAAwB,CAAA;AAEpD,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,UAAU,GAClB;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,GAChB;IAAE,KAAK,EAAE,aAAa,CAAA;CAAE,GACxB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAKnF;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAoB,GAAG,aAAa,CAMnG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,EAAE,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAoB,GAAG,aAAa,CAmB1I;AAYD,kFAAkF;AAClF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,aAAa,EACvB,QAAQ,GAAE,MAA6B,EACvC,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,QAAQ,CAAQ;gBAGL,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACrC,OAAO,GAAE;QACxB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;QACtB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,OAAO,CAAA;KACpD;IAGR,yDAAyD;IACzD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,sEAAsE;IACtE,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAE9B;IAED,sEAAsE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAyC3D,6EAA6E;IACvE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,OAAO,CAAC,aAAa;IAiBrB,2EAA2E;IAC3E,OAAO,IAAI,IAAI;CAQhB"}

package/lib/types/relay-registry.js

@@ -0,0 +1,191 @@
+/**
+ * Relay registry client: a stable `https://<id>.dsh-market.com` origin in
+ * front of the plugin-managed quick tunnel, so a paired phone keeps one
+ * bookmark and one cookie context across `dsh web` restarts.
+ *
+ * The plugin mints an id + secret on first run and persists them per profile
+ * under `$DSH_HOME/remote-web-ui-registry/`; every tunnel (re)start
+ * re-registers the current quick URL with the market worker. Registration is
+ * best-effort: a registry outage never blocks the tunnel — the QR just falls
+ * back to the raw quick URL for that session (the pre-relay behavior).
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { dshHome } from "./dsh-home.js";
+/** The market worker's registration endpoints (dsh-market.com edge API). */
+export const RELAY_REGISTER_URL = 'https://dsh-market.com/api/relay/register';
+export const RELAY_UNREGISTER_URL = 'https://dsh-market.com/api/relay/unregister';
+/**
+ * The public origin template: one stable single-label subdomain per
+ * registration id. Single label on purpose — Universal SSL covers exactly
+ * one subdomain level, so a two-level hostname would get no certificate.
+ */
+export const RELAY_BASE_SUFFIX = '.dsh-market.com';
+export const RELAY_ID_RE = /^[a-z0-9]{16}$/;
+export const RELAY_SECRET_RE = /^[A-Za-z0-9_-]{43}$/;
+/** Registry storage layout: one file per profile under the relay directory. */
+export function relayIdentityFile(profile, home = dshHome()) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(profile)) {
+        throw new Error(`relay registry: profile ${JSON.stringify(profile)} is not a safe path segment`);
+    }
+    return join(home, 'remote-web-ui-registry', `${profile}.json`);
+}
+/** Generate one identity pair (id: 8-byte hex slug; secret: 32-byte base64url). */
+export function generateRelayIdentity(random = randomBytes) {
+    return {
+        id: random(8).toString('hex'),
+        secret: random(32).toString('base64url'),
+        fresh: true,
+    };
+}
+/**
+ * Load (or lazily mint) the per-profile relay identity. The file is written
+ * owner-only on first mint; a corrupt file is reminted (the phone then
+ * re-pairs once — the same cost as losing the devices file).
+ */
+export function loadRelayIdentity(profile, home = dshHome(), random = randomBytes) {
+    const file = relayIdentityFile(profile, home);
+    try {
+        if (existsSync(file)) {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof parsed.id === 'string' && RELAY_ID_RE.test(parsed.id)
+                && typeof parsed.secret === 'string' && RELAY_SECRET_RE.test(parsed.secret)) {
+                // A persisted identity has certainly been registered before.
+                return { id: parsed.id, secret: parsed.secret };
+            }
+            console.warn(`relay registry: ${file} is malformed — reminting the identity (paired devices must scan the QR once more)`);
+        }
+    }
+    catch (error) {
+        console.warn(`relay registry: could not read ${file} (${error instanceof Error ? error.message : String(error)}) — reminting`);
+    }
+    const identity = generateRelayIdentity(random);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ id: identity.id, secret: identity.secret }, null, 2) + '\n', { mode: 0o600 });
+    return identity;
+}
+/** Build the registration request body for one identity + tunnel target. */
+function registrationBody(identity, target) {
+    return JSON.stringify({
+        id: identity.id,
+        secret: identity.secret,
+        new_secret: identity.fresh === true ? identity.secret : undefined,
+        target,
+    });
+}
+/** Best-effort removal of the mapping (used on disable; errors are swallowed). */
+export async function unregisterRelay(identity, endpoint = RELAY_UNREGISTER_URL, fetchFn = fetch) {
+    await fetchFn(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: identity.id, secret: identity.secret }),
+    });
+}
+/**
+ * The stable relay base for one identity — the origin the QR and the phone
+ * bookmark use while (or after) the registration is accepted.
+ */
+export function relayBaseOf(identity) {
+    return `https://${identity.id}${RELAY_BASE_SUFFIX}`;
+}
+/**
+ * Registration loop with capped exponential backoff. Re-registration happens
+ * on every tunnel start (the quick URL can change after a crash-restart);
+ * failures retry with backoff and surface the last error to the card.
+ */
+export class RelayRegistrar {
+    identity;
+    setState;
+    options;
+    timer;
+    attempts = 0;
+    lastError;
+    disposed = false;
+    constructor(identity, setState, options = {}) {
+        this.identity = identity;
+        this.setState = setState;
+        this.options = options;
+    }
+    /** The stable relay base for the QR while registered. */
+    get baseUrl() {
+        return relayBaseOf(this.identity);
+    }
+    /** The last registration failure detail (undefined while healthy). */
+    get error() {
+        return this.lastError;
+    }
+    /** Push one tunnel target; resolves the stable base once accepted. */
+    async announce(target) {
+        // A disposed registrar stays disposed: a pending retry timer must not
+        // resurrect it (re-enabling creates a fresh registrar instead).
+        if (this.disposed)
+            return undefined;
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.setState({ state: 'registering' });
+        try {
+            const fetchFn = this.options.fetchFn ?? fetch;
+            const response = await fetchFn(this.options.registerUrl ?? RELAY_REGISTER_URL, {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: registrationBody(this.identity, target),
+            });
+            if (!response.ok) {
+                const detail = await response.json().catch(() => undefined);
+                const error = detail && typeof detail.error === 'string' ? detail.error : `HTTP ${String(response.status)}`;
+                throw new Error(error);
+            }
+            // The row exists now: never claim a fresh id twice.
+            this.identity.fresh = false;
+            this.attempts = 0;
+            this.lastError = undefined;
+            this.setState({ state: 'running', url: this.baseUrl });
+            return this.baseUrl;
+        }
+        catch (error) {
+            this.lastError = error instanceof Error ? error.message : String(error);
+            if (this.lastError === 'invalid-params' && this.identity.fresh !== true) {
+                // The registry lost the row (a D1 restore or manual wipe): re-claim
+                // the id with a fresh claim on the next retry. A 403 auth-failed
+                // means the id is owned by another secret and stays failed.
+                this.identity.fresh = true;
+            }
+            this.setState({ state: 'failed', error: this.lastError });
+            this.scheduleRetry(target);
+            return undefined;
+        }
+    }
+    /** Best-effort removal of the registry row (the relay toggle turned off). */
+    async unregister() {
+        await unregisterRelay(this.identity, this.options.unregisterUrl, this.options.fetchFn);
+    }
+    scheduleRetry(target) {
+        if (this.disposed)
+            return;
+        const base = this.options.baseDelayMs ?? 5_000;
+        const max = this.options.maxDelayMs ?? 60_000;
+        const delay = Math.min(base * 2 ** this.attempts, max);
+        this.attempts += 1;
+        const timerFn = this.options.timerFn ?? ((fn, ms) => {
+            const timer = setTimeout(fn, ms);
+            timer.unref?.();
+            return timer;
+        });
+        this.timer = timerFn(() => {
+            this.timer = undefined;
+            void this.announce(target);
+        }, delay);
+    }
+    /** Stop retrying and clear the card state (tunnel stopped or disabled). */
+    dispose() {
+        this.disposed = true;
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.setState({ state: 'off' });
+    }
+}

package/lib/types/remote-api.d.ts

@@ -25,7 +25,7 @@ import type { IncomingMessage } from 'node:http';
 import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { PairingService } from './pairing.ts';
 import type { InnerAuth } from './inner-auth.ts';
-export { DESKTOP_LAUNCHER_PATH, LOCAL_ONLY_PREFIXES, PLUGIN_MANAGER_PATH, REMOTE_API_PATHS, REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY, REMOTE_PREFIX, REMOTE_UPGRADE_PATHS, WEB_UI_SETTINGS_BRIDGE_PATH, localOnlyDenial, } from './remote-methods.ts';
+export { LOCAL_ONLY_PREFIXES, PLUGIN_MANAGER_PATH, REMOTE_API_PATHS, REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY, REMOTE_PREFIX, REMOTE_UPGRADE_PATHS, WEB_UI_SETTINGS_BRIDGE_PATH, localOnlyDenial, } from './remote-methods.ts';
 export { REMOTE_API_PREFIX } from './remote-methods.ts';
 /** Route-family dependencies. */
 export interface RemoteApiDeps {

package/lib/types/remote-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAUhD,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;IAChD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CA0CnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CA2CjF"}
+{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAUhD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;IAChD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CA0CnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CA2CjF"}