@linxin666/dsh-remote-web-ui 0.1.1

package/src/client/deep-link.ts

@@ -0,0 +1,137 @@
+/**
+ * Phone-side boot flow: the QR link's `pair` + `workspace` parameters.
+ * Runs from the client apply on every page load, on any device:
+ * - `pair` present → accept the token, then reload so the whole SPA boots
+ *   with the device cookie (the accept endpoint is exempt from the pairing
+ *   gate; every other /api request needs the cookie).
+ * - `workspace` present (and paired) → deep-link: connect that workspace's
+ *   session and open it, then strip the parameter.
+ * Failure of accept leaves a sessionStorage marker the entry renders as a
+ * one-time notice.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import { acceptPair, readPairParams } from './pair-api.ts'
+
+/** sessionStorage key for the failed-pair notice. */
+export const PAIR_FAILED_MARKER = 'dsh-remote-pair-failed'
+
+/** Poll budget for the runtime services (activation order is unconstrained). */
+const SERVICE_WAIT_MS = 10_000
+
+/**
+ * The page-navigation surface the boot flow drives. Browser pages use the
+ * default (window.location/history); tests inject a fake.
+ */
+export interface PageSurface {
+  /** The current page URL (read fresh on each access). */
+  href: string
+  /** Replace the URL without reloading. */
+  replaceState(url: string): void
+  /** Navigate to a URL (a fresh page load). */
+  navigate(url: string): void
+  /** Reload the page. */
+  reload(): void
+}
+
+/** The browser implementation of {@link PageSurface}. */
+export const browserPage: PageSurface = {
+  get href(): string {
+    return window.location.href
+  },
+  replaceState(url: string): void {
+    window.history.replaceState(null, '', url)
+  },
+  navigate(url: string): void {
+    window.location.assign(url)
+  },
+  reload(): void {
+    window.location.reload()
+  },
+}
+
+/** Whether this browser looks like a phone/tablet (the simplified mobile surface). */
+export function isMobileSurface(): boolean {
+  if (typeof navigator === 'undefined') return false
+  return /Android|iPhone|iPad|iPod|Mobile|mobile/i.test(navigator.userAgent)
+}
+
+/**
+ * Run the pair/workspace boot flow for this page load.
+ * @param ctx - client root context (workspaces/sessions read at need time).
+ * @param search - the current location.search.
+ * @param page - the page surface (defaults to the browser).
+ */
+export function runPairBootFlow(ctx: Context, search: string, page: PageSurface = browserPage): void {
+  const params = readPairParams(search)
+  if (params.pair !== undefined) {
+    void runAccept(params.pair, page)
+    return
+  }
+  if (params.workspace !== undefined) {
+    void runDeepLink(ctx, params.workspace, page)
+  }
+}
+
+/** Accept the token, then reload (the workspace param survives the reload). */
+async function runAccept(token: string, page: PageSurface): Promise<void> {
+  let ok = false
+  try {
+    const result = await acceptPair(token)
+    ok = result.ok
+    if (!ok) sessionStorage.setItem(PAIR_FAILED_MARKER, 'failed')
+  } catch {
+    sessionStorage.setItem(PAIR_FAILED_MARKER, 'failed')
+  }
+  // Drop the token from the URL either way: an accepted token is consumed
+  // (a re-scan would 409), and a failed one must not loop.
+  const url = new URL(page.href)
+  url.searchParams.delete('pair')
+  page.replaceState(`${url.pathname}${url.search}${url.hash}`)
+  if (ok) {
+    // Phones land on the standalone simplified surface (the full desktop UI
+    // is not built for small screens); desktops stay on the full UI.
+    if (isMobileSurface()) page.navigate('/m')
+    else page.reload()
+  }
+}
+
+/**
+ * Connect the deep-linked workspace and open its session. Waits for the
+ * runtime services AND for the target workspace to appear in the workspace
+ * list (both are asynchronous after boot), then connects and opens; gives
+ * up silently within the budget — the workspace param is stripped either
+ * way, so a late failure cannot loop.
+ * @param ctx - client root context.
+ * @param workspaceId - the target workspace.
+ * @param page - the page surface.
+ */
+async function runDeepLink(ctx: Context, workspaceId: string, page: PageSurface): Promise<void> {
+  const target = workspaceId as WorkspaceId
+  const deadline = Date.now() + SERVICE_WAIT_MS
+  while (Date.now() < deadline) {
+    const workspaces = ctx.get('workspaces')
+    const sessions = ctx.get('sessions') as { open(id: string): void } | undefined
+    if (workspaces !== undefined && sessions !== undefined) {
+      const items = workspaces.list.getSnapshot().items
+      if (items.some(item => item.workspaceId === target)) {
+        try {
+          // Open unconditionally: a host-side "current" session may already
+          // exist (multi-client mirroring), but the QR's workspace target is
+          // explicit user intent and must win.
+          const sessionId = await workspaces.connectWorkspace(target)
+          sessions.open(sessionId)
+        } catch {
+          // Unknown workspace or a failed connect: fall through to the
+          // runtime's own default initial selection.
+        }
+        break
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, 200))
+  }
+  const url = new URL(page.href)
+  url.searchParams.delete('workspace')
+  page.replaceState(`${url.pathname}${url.search}${url.hash}`)
+}

package/src/client/index.ts

@@ -0,0 +1,167 @@
+/**
+ * Mobile remote control — browser half. Registers the `remote` dictionaries,
+ * the sidebar-foot entry (phone trigger + pairing panel) into the
+ * ui-sidebar-declared `sidebar.remote` seat, and runs the phone-side boot
+ * flow (pair accept + workspace deep-link + presence heartbeats) plus the
+ * one-time failed-pair notice. Export discipline: packages/client/AGENTS.md
+ * — the /client surface carries only what cordis loading needs plus types.
+ */
+import { createElement } from 'react'
+import { createRoot } from 'react-dom/client'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale) and the
+// ui-sidebar SlotMap merge (the 'sidebar.remote' hole).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: pulls the settings-surface SlotMap merge (the 'settings.section'
+// entry) and the ctx.settingsScope Context merge.
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import { RemoteEntry } from './RemoteEntry.tsx'
+import { PairFailedNotice } from './PairFailedNotice.tsx'
+import { RemoteSettingsCard, RemoteSettingsCardController, type RemoteSettings } from './RemoteSettingsCard.tsx'
+import { en, zh, type RemoteKey } from './locales.ts'
+import { PAIR_FAILED_MARKER, runPairBootFlow } from './deep-link.ts'
+import { sendHeartbeat } from './pair-api.ts'
+
+export type { RemoteEntryProps } from './RemoteEntry.tsx'
+export type { PanelState, RemotePanelProps } from './RemotePanel.tsx'
+export type { PairFailedNoticeProps } from './PairFailedNotice.tsx'
+export type { RemoteKey } from './locales.ts'
+export type { RemoteSettingsCardFace, RemoteSettingsCardState } from './RemoteSettingsCard.tsx'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Mobile remote-control surface copy. */
+    remote: RemoteKey
+  }
+
+  interface SlotMap {
+    /**
+     * The sidebar foot seat beside the settings trigger, declared by the
+     * sidebar shell on deployments that carry the feature seat; the shell
+     * passes only its column display state.
+     */
+    'sidebar.remote': { kind: 'single'; scope: 'root'; owner: SidebarRemoteOwnerProps }
+    /**
+     * The child slot the Web UI plugin group declares; this card registers
+     * into the group instead of the top-level `settings.plugin.item` list.
+     * Spelled here with the same shape so this package can register without
+     * depending on the sibling UI package.
+     */
+    'web-ui.plugin.item': { kind: 'list'; scope: 'root'; owner: SettingsPluginItemOwnerProps }
+  }
+}
+
+/** Owner share of the sidebar remote-control seat: the column display state the trigger renders against. */
+export interface SidebarRemoteOwnerProps {
+  /** Whether the sidebar renders wide content (false = 56px rail). */
+  wide: boolean
+}
+
+/** Owner share of a plugin card (the section supplies nothing). */
+export interface SettingsPluginItemOwnerProps {
+  /** Marker field: card owner props are intentionally empty. */
+  children?: never
+}
+
+/** Dictionary namespace owned by this plugin. */
+const NS = 'remote'
+
+/** Settings namespace the remote-control card edits (the Host plugin registers it). */
+const REMOTE_WEB_UI_NS = 'remote-web-ui'
+
+/** Heartbeat cadence from a paired phone (presence + revocation liveness). */
+const HEARTBEAT_INTERVAL_MS = 10_000
+
+/** Services required by this plugin. */
+export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote']
+
+/**
+ * Register the remote-control surface.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'remote-web-ui: dictionaries')
+
+  const t = ctx.locale.bind(NS)
+  const settingsScope = ctx.settingsScope.bind<RemoteSettings>({ namespace: REMOTE_WEB_UI_NS })
+  const enabled = (): boolean => {
+    const snapshot = settingsScope.getSnapshot()
+    return snapshot.status === 'ready'
+      ? snapshot.value?.enabled ?? true
+      : snapshot.status === 'unavailable'
+  }
+
+  // Sidebar foot entry: the shell declares 'sidebar.remote' in unconstrained
+  // order, so registration is declaration-aware — slots.inject waits on the
+  // declaration, removes the contribution when it collapses, and re-runs
+  // after a redeclaration. The entry follows the plugin's enabled setting:
+  // toggling it off removes the trigger, toggling it back on re-registers it.
+  ctx.slots.inject('sidebar.remote', () => {
+    let disposeEntry: (() => void) | undefined
+    const syncEntry = (): void => {
+      if (enabled() && disposeEntry === undefined) {
+        disposeEntry = ctx.slots.register({ name: 'sidebar.remote', locale: NS }, RemoteEntry)
+      } else if (!enabled() && disposeEntry !== undefined) {
+        disposeEntry()
+        disposeEntry = undefined
+      }
+    }
+    const unsubscribe = settingsScope.subscribe(syncEntry)
+    syncEntry()
+    return () => {
+      unsubscribe()
+      disposeEntry?.()
+    }
+  })
+
+  // Plugin configuration card: one staged form over the `remote-web-ui`
+  // settings namespace, contributed to the Web UI plugin group.
+  const remoteSettings = new RemoteSettingsCardController(settingsScope)
+  ctx.slots.inject('web-ui.plugin.item', () => ctx.slots.register({
+    name: 'web-ui.plugin.item',
+    id: 'remote-web-ui',
+    order: 90,
+    locale: NS,
+    inject: () => remoteSettings.inject(),
+  }, RemoteSettingsCard))
+
+  // Phone-side boot flow + heartbeats. Loopback pages (the desktop) never
+  // heartbeat; the server ignores unpaired heartbeats anyway. Both run only
+  // while the plugin is enabled.
+  let disposeRuntime: (() => void) | undefined
+  const syncRuntime = (): void => {
+    if (enabled() && disposeRuntime === undefined) {
+      disposeRuntime = ctx.effect(() => {
+        const connection = ctx.get('connection') as ConnectionHandle | undefined
+        const loopback = connection?.isLoopback ?? true
+        runPairBootFlow(ctx, window.location.search)
+        if (loopback) return () => {}
+        const timer = window.setInterval(() => { void sendHeartbeat().catch(() => {}) }, HEARTBEAT_INTERVAL_MS)
+        return () => { window.clearInterval(timer) }
+      }, 'remote-web-ui: pair flow + heartbeats')
+    } else if (!enabled() && disposeRuntime !== undefined) {
+      disposeRuntime()
+      disposeRuntime = undefined
+    }
+  }
+  settingsScope.subscribe(syncRuntime)
+  syncRuntime()
+
+  // One-time failed-pair toast. The accept result lands asynchronously, so
+  // the marker check is deferred past the accept round trip.
+  ctx.effect(() => {
+    const timer = window.setTimeout(() => {
+      if (sessionStorage.getItem(PAIR_FAILED_MARKER) === null) return
+      sessionStorage.removeItem(PAIR_FAILED_MARKER)
+      const mount = document.createElement('div')
+      document.body.appendChild(mount)
+      const root = createRoot(mount)
+      root.render(createElement(PairFailedNotice, { t }))
+      // The toast owns its dismissal; the root lives for the page lifetime.
+      void root
+    }, 1500)
+    return () => { window.clearTimeout(timer) }
+  }, 'remote-web-ui: failed-pair notice')
+}

package/src/client/locales.ts

@@ -0,0 +1,149 @@
+/** `remote` namespace dictionaries: the mobile remote-control surface copy. */
+
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'entry.label': '移动端远程控制',
+  'title': '移动端远程控制',
+  'subtitle': '扫码或在手机上打开链接，即可远程控制当前工作区',
+  'card.title': '手机扫码连接',
+  'public.badge': '公网',
+  'status.waiting': '等待手机连接',
+  'status.connected': '已连接 {n} 台设备',
+  'status.disconnected': '已配对设备离线',
+  'status.stopped': '已停止移动端访问',
+  'status.lanRequired': '此功能需要以 --host 0.0.0.0 启动 dsh web，或配置公网地址才能使用',
+  'status.lanRequiredHint': '当前服务仅绑定在 127.0.0.1 且未配置公网地址，手机无法访问。请用 dsh web --host 0.0.0.0 重新启动，或在设置中填写内网穿透的公网地址。',
+  'status.loopbackRequired': '配对面板仅限本机使用',
+  'status.loopbackRequiredHint': '请通过 http://127.0.0.1 打开此页面后重试；手机请使用配对链接访问。',
+  'status.unreachable': '无法连接配对服务',
+  'status.unreachableHint': '请刷新页面后重试。',
+  'pair.hint': '无法扫码？可以在手机上打开链接',
+  'pair.publicHint': '公网链接：手机无需与电脑在同一网络',
+  'address.label': '选择二维码指向的网络',
+  'address.public': '公网地址',
+  'address.lan': '局域网',
+  'address.hint': '公网地址适合手机不在同一网络时使用；局域网地址仅在手机与电脑同一网络时可用。',
+  'pair.expires': '二维码有效至 {time}',
+  'pair.expired': '二维码已过期，请刷新',
+  'pair.failed.title': '配对失败',
+  'pair.failed.detail': '链接无效或已使用，请回到电脑端刷新二维码后重新扫码。',
+  'action.stop': '停止',
+  'action.refresh': '刷新二维码',
+  'action.copy': '复制链接',
+  'action.copied': '已复制',
+  'stopped.hint': '已停止移动端访问。点击"刷新二维码"重新开启。',
+  'tunnel.starting': '公网隧道启动中，二维码将自动变为公网链接…',
+  'tunnel.failed': '公网隧道启动失败：{error}',
+  'tunnel.unknownError': '未知错误',
+  'close.label': '关闭移动端远程控制面板',
+  // 插件设置卡片（settings.plugin.item 席位）。
+  'settings.title': '移动端远程控制',
+  'settings.description': '配对安全与设备限额。',
+  'settings.enabled': '启用移动端远程控制',
+  'settings.enabledHint': '关闭后移除侧边栏入口并停用配对路由与局域网栅栏。',
+  'settings.tokenTtlMs': '配对令牌有效期（毫秒）',
+  'settings.tokenTtlMsHint': '新生成的二维码链接在此时间后失效。',
+  'settings.offlineAfterMs': '设备离线判定（毫秒）',
+  'settings.offlineAfterMsHint': '配对设备超过该时长未上报心跳即视为离线。',
+  'settings.maxDevices': '已配对设备上限',
+  'settings.maxDevicesHint': '超过上限时淘汰最旧的设备会话。',
+  'settings.cookieName': '设备 Cookie 名',
+  'settings.cookieNameHint': '携带已配对设备标识的 Cookie 名称。',
+  'settings.requirePairingForLan': '局域网访问要求配对',
+  'settings.requirePairingForLanHint': '开启：所有非本机回环的 /api 请求必须携带有效配对 Cookie；关闭：局域网栅栏放开，配对仅用于令牌与状态管理。',
+  'settings.publicBaseUrl': '公网地址（可选）',
+  'settings.publicBaseUrlHint': '内网穿透的公网地址，如 Cloudflare Tunnel：https://xxx.trycloudflare.com。填写后二维码将生成公网链接，手机不在同一网络也能配对；留空则仅局域网可用。',
+  'settings.autoTunnel': '自动公网隧道',
+  'settings.autoTunnelHint': '开启后插件自动启动 Cloudflare quick tunnel（无需安装任何工具），并自动更新公网地址与信任配置，手机随时可用公网配对；关闭时使用上方手动填写的公网地址。',
+  'settings.inherit': '继承',
+  'settings.on': '开',
+  'settings.off': '关',
+  'settings.overridden': '已覆盖',
+  'settings.reset': '恢复默认',
+  'settings.readOnly': '当前部署的设置只读。',
+  'settings.expand': '展开设置',
+  'settings.collapse': '收起设置',
+  'settings.save': '保存',
+  'settings.saving': '保存中…',
+  'settings.discard': '放弃',
+  'settings.unsaved': '未保存',
+  'settings.saveFailed': '部署未接受这些值，已保留供你修改。',
+  'settings.invalidNumber': '请输入数字，留空则使用默认值。',
+} satisfies Record<string, string>
+
+/** The remote namespace key union. */
+export type RemoteKey = keyof typeof zh
+
+/** The settings-card slice of the remote dictionary. */
+export type SettingsCardKey = RemoteKey
+
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+  'entry.label': 'Mobile remote control',
+  'title': 'Mobile remote control',
+  'subtitle': 'Scan the QR code or open the link on your phone to control this workspace remotely',
+  'card.title': 'Scan to connect',
+  'public.badge': 'Public',
+  'status.waiting': 'Waiting for a phone',
+  'status.connected': '{n} device(s) connected',
+  'status.disconnected': 'Paired devices offline',
+  'status.stopped': 'Mobile access stopped',
+  'status.lanRequired': 'This feature needs dsh web started with --host 0.0.0.0, or a configured public address',
+  'status.lanRequiredHint': 'The server is bound to 127.0.0.1 and no public address is configured, so a phone cannot reach it. Restart with dsh web --host 0.0.0.0, or set the tunneled public address in settings.',
+  'status.loopbackRequired': 'The pairing panel works on this machine only',
+  'status.loopbackRequiredHint': 'Open this page at http://127.0.0.1 to mint a QR code; phones use the paired link.',
+  'status.unreachable': 'Cannot reach the pairing service',
+  'status.unreachableHint': 'Refresh the page and try again.',
+  'pair.hint': 'Cannot scan? Open the link on your phone',
+  'pair.publicHint': 'Public link: the phone does not need to be on the same network',
+  'address.label': 'Network the QR code points to',
+  'address.public': 'Public',
+  'address.lan': 'LAN',
+  'address.hint': 'Use the public address when the phone is not on the same network; LAN addresses only work on the same network.',
+  'pair.expires': 'QR code valid until {time}',
+  'pair.expired': 'QR code expired — refresh it',
+  'pair.failed.title': 'Pairing failed',
+  'pair.failed.detail': 'The link is invalid or was already used. Refresh the QR code on your computer and scan again.',
+  'action.stop': 'Stop',
+  'action.refresh': 'Refresh QR',
+  'action.copy': 'Copy link',
+  'action.copied': 'Copied',
+  'stopped.hint': 'Mobile access is stopped. Click "Refresh QR" to re-enable it.',
+  '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',
+  'close.label': 'Close mobile remote control panel',
+  // Plugin settings card (the `settings.plugin.item` seat).
+  'settings.title': 'Mobile remote control',
+  'settings.description': 'Pairing security and device limits.',
+  'settings.enabled': 'Enable mobile remote control',
+  'settings.enabledHint': 'When off, the sidebar entry is removed and pairing routes plus the LAN fence stop.',
+  'settings.tokenTtlMs': 'Pairing token lifetime (ms)',
+  'settings.tokenTtlMsHint': 'How long a minted QR link stays valid before it dies.',
+  'settings.offlineAfterMs': 'Device offline threshold (ms)',
+  'settings.offlineAfterMsHint': 'A paired device flips to offline when it has not been seen for this long.',
+  'settings.maxDevices': 'Paired device cap',
+  'settings.maxDevicesHint': 'Hard cap on paired device sessions; the oldest is evicted when full.',
+  'settings.cookieName': 'Device cookie name',
+  'settings.cookieNameHint': 'Cookie that carries the paired device id.',
+  'settings.requirePairingForLan': 'Require pairing for LAN access',
+  'settings.requirePairingForLanHint': 'On: every non-loopback /api request must carry a live paired-device cookie. Off: the LAN fence is open 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.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.inherit': 'Inherit',
+  'settings.on': 'On',
+  'settings.off': 'Off',
+  'settings.overridden': 'Overridden',
+  'settings.reset': 'Reset to default',
+  'settings.readOnly': 'This deployment stores settings read-only.',
+  'settings.expand': 'Show settings',
+  'settings.collapse': 'Hide settings',
+  'settings.save': 'Save',
+  'settings.saving': 'Saving…',
+  'settings.discard': 'Discard',
+  'settings.unsaved': 'Unsaved',
+  'settings.saveFailed': 'The deployment did not accept these values; they were left for you to correct.',
+  'settings.invalidNumber': 'Enter a number, or leave blank to use the default.',
+} satisfies Record<RemoteKey, string>

package/src/client/pair-api.ts

@@ -0,0 +1,176 @@
+/**
+ * Browser-side wire helpers for the /api/pair surface. Plain fetch over
+ * same-origin /api (like the connection client); JSON bodies, string
+ * responses for the error codes.
+ */
+
+/** issue() response. */
+export interface IssueResult {
+  ok: true
+  url: string
+  token: string
+  expiresAt: number
+  /** Every constructible LAN base address (interface order). */
+  lanAddresses: string[]
+  /** The configured public (tunneled) base URL, when present. */
+  publicBaseUrl?: string
+}
+
+/** issue() refusal: the server is not LAN-reachable. */
+export interface IssueLanRequired {
+  ok: false
+  code: 'lan-required'
+}
+
+/** issue() refusal: the requested LAN address is not constructible. */
+export interface IssueUnknownAddress {
+  ok: false
+  code: 'unknown-address'
+}
+
+/** issue() refusal: the loopback-only fence rejected this origin. */
+export interface IssueLoopbackRequired {
+  ok: false
+  code: 'forbidden'
+}
+
+export type IssueResponse = IssueResult | IssueLanRequired | IssueUnknownAddress | IssueLoopbackRequired
+
+/** accept() refusal codes. */
+export type AcceptFailure = { ok: false; code: 'invalid' | 'used' | 'forbidden' }
+
+/** One auto-tunnel status frame (absent while the feature is off). */
+export interface TunnelStatusFrame {
+  state: 'starting' | 'running' | 'failed'
+  url?: string
+  error?: string
+}
+
+/** One /api/pair/events frame. */
+export interface PairStateFrame {
+  type: 'state'
+  phase: 'lan-required' | 'stopped' | 'waiting' | 'connected' | 'disconnected'
+  lanAvailable: boolean
+  tokenId?: string
+  tokenExpiresAt?: number
+  deviceCount: number
+  onlineCount: number
+  /** Auto-tunnel status, while the auto-tunnel feature is active. */
+  tunnel?: TunnelStatusFrame
+}
+
+/**
+ * Mint a fresh pairing token (one active token at a time — this invalidates
+ * any previous link).
+ * @param workspaceId - optional current workspace to deep-link the phone into.
+ * @param address - optional LAN IP literal the QR must be built from (the
+ * default is the first interface); unknown literals refuse with
+ * 'unknown-address'.
+ * @returns the issued link, the lan-required refusal (server never bound
+ * 0.0.0.0), or the forbidden refusal (the loopback-only fence rejected this
+ * origin — the panel is a desktop control endpoint).
+ */
+export async function issuePair(workspaceId?: string, address?: string): Promise<IssueResponse> {
+  const response = await fetch('/api/pair/issue', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      ...(workspaceId !== undefined ? { workspaceId } : {}),
+      ...(address !== undefined ? { address } : {}),
+    }),
+  })
+  if (!response.ok) {
+    if (response.status === 409) return { ok: false, code: 'lan-required' }
+    if (response.status === 403) return { ok: false, code: 'forbidden' }
+    if (response.status === 400) return { ok: false, code: 'unknown-address' }
+    throw new Error(`remote-web-ui: issue failed with ${String(response.status)}`)
+  }
+  return await response.json() as IssueResult
+}
+
+/**
+ * Accept a pairing token (the phone's first open of the QR link). Success
+ * sets the device cookie; the page then reloads to boot with it.
+ * @param token - the token from the URL.
+ * @returns the wire result.
+ */
+export async function acceptPair(token: string): Promise<{ ok: true } | AcceptFailure> {
+  const response = await fetch('/api/pair/accept', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token }),
+  })
+  if (response.ok) return { ok: true }
+  if (response.status === 404) return { ok: false, code: 'invalid' }
+  if (response.status === 409) return { ok: false, code: 'used' }
+  return { ok: false, code: 'forbidden' }
+}
+
+/** Revoke mobile access (paired devices + the current token). */
+export async function stopPair(): Promise<void> {
+  const response = await fetch('/api/pair/stop', { method: 'POST' })
+  if (!response.ok) throw new Error(`remote-web-ui: stop failed with ${String(response.status)}`)
+}
+
+/** Presence heartbeat from a paired phone (unpaired heartbeats 401 harmlessly). */
+export async function sendHeartbeat(): Promise<void> {
+  await fetch('/api/pair/heartbeat', { method: 'POST' })
+}
+
+/** Whether the current page URL carries a pairing token / workspace target. */
+export function readPairParams(search: string): { pair?: string; workspace?: string } {
+  const params = new URLSearchParams(search)
+  const pair = params.get('pair')
+  const workspace = params.get('workspace')
+  return {
+    ...(pair !== null && pair !== '' ? { pair } : {}),
+    ...(workspace !== null && workspace !== '' ? { workspace } : {}),
+  }
+}
+
+/**
+ * Strip one query parameter from the current URL without reloading.
+ * @param name - the parameter to remove.
+ * @returns the new search string ('' when empty).
+ */
+export function stripParam(name: string): string {
+  const url = new URL(window.location.href)
+  url.searchParams.delete(name)
+  return url.search
+}/** Human-readable expiry clock, e.g. "10:35". */
+export function formatClock(epochMs: number): string {
+  const date = new Date(epochMs)
+  const hours = String(date.getHours()).padStart(2, '0')
+  const minutes = String(date.getMinutes()).padStart(2, '0')
+  return `${hours}:${minutes}`
+}
+
+/**
+ * Copy text to the clipboard with a fallback for insecure contexts
+ * (plain-HTTP LAN origins lack navigator.clipboard).
+ * @param text - the text to copy.
+ * @returns whether the copy succeeded.
+ */
+export async function copyText(text: string): Promise<boolean> {
+  if (typeof navigator !== 'undefined' && navigator.clipboard !== undefined) {
+    try {
+      await navigator.clipboard.writeText(text)
+      return true
+    } catch {
+      // fall through to the execCommand path
+    }
+  }
+  try {
+    const area = document.createElement('textarea')
+    area.value = text
+    area.style.position = 'fixed'
+    area.style.opacity = '0'
+    document.body.appendChild(area)
+    area.select()
+    const ok = document.execCommand('copy')
+    area.remove()
+    return ok
+  } catch {
+    return false
+  }
+}