@linxin666/dsh-remote-web-ui 0.1.19 → 0.2.0

package/src/client/UpdateEntry.tsx

@@ -29,14 +29,31 @@ export interface UpdateEntryProps {
 export function UpdateEntry({ wide, t }: UpdateEntryProps) {
   const [open, setOpen] = useState(false)
   const [view, setView] = useState<UpdateView>({ kind: "checking" })
+  const [updateAvailable, setUpdateAvailable] = useState(false)
   const runToken = useRef(0)
+  const availabilityToken = useRef(0)
+  const mounted = useRef(false)
+
+  const probeAvailability = useCallback(async (): Promise<void> => {
+    const token = ++availabilityToken.current
+    try {
+      const status = await fetchUpdateStatus()
+      if (token === availabilityToken.current) {
+        setUpdateAvailable(status.mode === "npm" && status.outdated)
+      }
+    } catch {
+      if (token === availabilityToken.current) setUpdateAvailable(false)
+    }
+  }, [])
 
   const check = useCallback(async (): Promise<void> => {
+    const availabilityCheck = ++availabilityToken.current
     setView({ kind: "checking" })
     let status: UpdateStatus
     try {
       status = await fetchUpdateStatus()
     } catch (error) {
+      if (availabilityCheck === availabilityToken.current) setUpdateAvailable(false)
       // HTTP 404: the update route is not mounted — the host process runs an
       // older plugin build (client refreshed, host did not). Restarting dsh
       // web loads the new plugin; a plain network failure gets the generic
@@ -48,6 +65,9 @@ export function UpdateEntry({ wide, t }: UpdateEntryProps) {
       setView({ kind: "error", message: t("update.offline"), detail: t("update.offlineDetail") })
       return
     }
+    if (availabilityCheck === availabilityToken.current) {
+      setUpdateAvailable(status.mode === "npm" && status.outdated)
+    }
     if (status.error === "registry-unreachable") {
       setView({ kind: "result", status })
       return
@@ -60,6 +80,7 @@ export function UpdateEntry({ wide, t }: UpdateEntryProps) {
     const token = ++runToken.current
     try {
       const result = await runUpdate()
+      if (result.ok && mounted.current) setUpdateAvailable(false)
       if (token !== runToken.current) return
       setView({ kind: "done", result })
     } catch {
@@ -78,8 +99,18 @@ export function UpdateEntry({ wide, t }: UpdateEntryProps) {
     setOpen(false)
   }, [])
 
-  // Unmount safety: an in-flight update must not land on a dead component.
-  useEffect(() => () => { runToken.current++ }, [])
+  // Check once after mount without opening the panel or starting an update.
+  useEffect(() => {
+    mounted.current = true
+    void probeAvailability()
+    return () => {
+      mounted.current = false
+      runToken.current++
+      availabilityToken.current++
+    }
+  }, [probeAvailability])
+
+  const updateLabel = updateAvailable ? t("update.availableLabel") : t("update.label")
 
   return (
     <>
@@ -87,8 +118,9 @@ export function UpdateEntry({ wide, t }: UpdateEntryProps) {
         type="button"
         className={css.trigger}
         data-wide={wide ? undefined : "rail"}
-        aria-label={t("update.label")}
-        title={t("update.label")}
+        data-update-available={updateAvailable ? "true" : undefined}
+        aria-label={updateLabel}
+        title={updateLabel}
         onClick={openPanel}
       >
         <IconDownloadOutline16 size={wide ? 16 : 18} />

package/src/client/deep-link.ts

@@ -95,7 +95,7 @@ async function runAccept(token: string, page: PageSurface): Promise<void> {
     // mobile surface can open the intended workspace instead of losing the
     // QR context at this navigation boundary.
     if (isMobileSurface()) {
-      url.pathname = '/m'
+      url.pathname = '/m/'
       page.navigate(`${url.pathname}${url.search}${url.hash}`)
     } else {
       page.reload()

package/src/client/locales.ts

@@ -74,6 +74,7 @@ export const zh = {
   'settings.invalidNumber': '请输入数字，留空则使用默认值。',
   // 更新面板（侧边栏更新按钮）。
   'update.label': '检查更新',
+  'update.availableLabel': '发现新版本，检查更新',
   'update.title': '检查更新',
   'update.checking': '正在检查远程仓库中的新版本…',
   'update.upToDate': '当前已是最新版本',
@@ -187,6 +188,7 @@ export const en = {
   'settings.invalidNumber': 'Enter a number, or leave blank to use the default.',
   // Update panel (the sidebar update trigger).
   'update.label': 'Check for updates',
+  'update.availableLabel': 'New version available. Check for updates',
   'update.title': 'Check for updates',
   'update.checking': 'Checking the remote repository for newer releases…',
   'update.upToDate': 'Everything is up to date',

package/src/client/remote.module.css

@@ -21,6 +21,7 @@
 /* Trigger: settings row height beside the trigger row (wide), or the 36px
    rail circle; the seat's owner (ui-sidebar) lays out the geometry. */
 .trigger {
+  position: relative;
   flex: none;
   display: inline-flex;
   align-items: center;
@@ -37,6 +38,30 @@
   transition: background-color 120ms ease, color 120ms ease, box-shadow 120ms ease;
 }
 
+.trigger[data-update-available]::after {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  width: 8px;
+  height: 8px;
+  box-sizing: border-box;
+  border: 2px solid var(--dsw-alias-bg-layer-1);
+  border-radius: 50%;
+  background: var(--dsw-alias-brand-primary);
+  content: '';
+  pointer-events: none;
+}
+
+.trigger[data-wide='wide'] {
+  flex: 1 1 auto;
+  justify-content: flex-start;
+  width: auto;
+  min-width: 0;
+  border-radius: 8px;
+  gap: 8px;
+  padding: 0 10px;
+}
+
 .trigger:hover:not(:disabled) {
   background: var(--dsw-alias-interactive-bg-hover);
   color: var(--dsw-alias-label-primary);
@@ -429,6 +454,7 @@
   display: flex;
   align-items: center;
   gap: 6px;
+  min-width: 0;
 }
 
 .entryRow[data-rail='rail'] {

package/src/gate.ts

@@ -89,8 +89,20 @@ export function makeGateListener(
     if (!active) return false
     const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
     if (!require) return next()
-    const deviceId = readCookie(request.headers.cookie, service.config.cookieName)
-    if (deviceId === undefined) return false
-    return service.touchDevice(deviceId) ? next() : false
+    return isPairedDeviceRequest(service, request) ? next() : false
   }
 }
+
+/**
+ * Whether a request carries a live, non-revoked paired-device cookie for
+ * this service. Sibling host routes outside /api (aionui-panel, etc.) use
+ * the same check via the remoteWebUiPairing service.
+ * @param service - the pairing service that owns the device table.
+ * @param request - the incoming HTTP request.
+ * @returns true when the cookie names a live session (and lastSeenAt was refreshed).
+ */
+export function isPairedDeviceRequest(service: PairingService, request: IncomingMessage): boolean {
+  const deviceId = readCookie(request.headers.cookie, service.config.cookieName)
+  if (deviceId === undefined) return false
+  return service.touchDevice(deviceId)
+}

package/src/http.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared HTTP helpers for the route families: one JSON writer and one
+ * bounded JSON body reader. Previously copy-pasted across routes.ts,
+ * update-routes.ts, and mobile-api.ts with drifting failure contracts.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** One JSON response. */
+export function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' })
+  res.end(payload)
+}
+
+/**
+ * Read a request body up to maxBytes and parse it as JSON.
+ * @throws 'body too large' beyond the cap, or the JSON.parse error.
+ */
+export async function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > maxBytes) throw new Error('body too large')
+    chunks.push(buffer)
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}

package/src/index.ts

@@ -15,8 +15,9 @@ import type { Context } from '@deepseek-ai/cordis'
 import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-host-webserver'
-import { PairingService } from './pairing.ts'
-import { makeGateListener } from './gate.ts'
+import { PairingService, type PairingConfig } from './pairing.ts'
+import { isPairedDeviceRequest, makeGateListener } from './gate.ts'
+import { RemoteWebUiPairing } from './pairing-access.ts'
 import { isTrustedApiRequest, makeRoutes } from './routes.ts'
 import { makeMobileRoutes } from './mobile-routes.ts'
 import { makeMobileApiRoutes } from './mobile-api.ts'
@@ -31,6 +32,7 @@ import {
   type UpdateRunResult,
 } from './update.ts'
 import { makeUpdateRoutes } from './update-routes.ts'
+import { mountOnce } from './mount-once.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Events {
@@ -88,6 +90,14 @@ export interface Config {
    * warning (LAN-only behavior preserved). Ignored while `autoTunnel` is on.
    */
   publicBaseUrl?: string
+  /**
+   * Absolute path to a JSON file where paired device sessions are persisted.
+   * When set, a paired phone keeps its session across `dsh web` restarts
+   * (the phone-side cookie already lives 365 days), so re-scanning the QR
+   * after each restart is unnecessary. Unset keeps sessions memory-only
+   * (previous behavior).
+   */
+  devicesFile?: string
   /**
    * When true, the plugin runs its own Cloudflare quick tunnel (the
    * cloudflared binary ships with the package — no user-side install) and
@@ -114,6 +124,7 @@ export const Config: z<Config> = z.object({
   cookieName: z.string().min(1).default('dsh_pair'),
   requirePairingForLan: z.boolean().default(true),
   publicBaseUrl: z.string(),
+  devicesFile: z.string(),
   autoTunnel: z.boolean().default(false),
   mobileEnterToSend: z.boolean().default(true),
   enabled: z.boolean().default(true),
@@ -127,7 +138,29 @@ const SWEEP_INTERVAL_MS = 10_000
  * which legitimately resolves to `undefined` when unset (the schema keeps it
  * optional, so `Required` alone would over-narrow it to `string`).
  */
-type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl'>> & { publicBaseUrl: string | undefined }
+type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile'>> & {
+  publicBaseUrl: string | undefined
+  devicesFile: string | undefined
+}
+
+/**
+ * The single mapping from resolved plugin config to the pairing service
+ * config. Both the constructed service and every live settings sync reuse
+ * it, so no field can be silently dropped when the web settings surface
+ * pushes a new value into the running service.
+ */
+export function pairingConfigOf(resolved: Pick<
+  ResolvedConfig,
+  'tokenTtlMs' | 'offlineAfterMs' | 'maxDevices' | 'cookieName' | 'devicesFile'
+>): PairingConfig {
+  return {
+    tokenTtlMs: resolved.tokenTtlMs,
+    offlineAfterMs: resolved.offlineAfterMs,
+    maxDevices: resolved.maxDevices,
+    cookieName: resolved.cookieName,
+    devicesFile: resolved.devicesFile,
+  }
+}
 
 /** Schema defaults, re-read for hand-built test contexts (the loader applies them normally). */
 const DEFAULTS: ResolvedConfig = {
@@ -137,6 +170,7 @@ const DEFAULTS: ResolvedConfig = {
   cookieName: 'dsh_pair',
   requirePairingForLan: true,
   publicBaseUrl: undefined,
+  devicesFile: undefined,
   autoTunnel: false,
   mobileEnterToSend: true,
   enabled: true,
@@ -147,7 +181,9 @@ const DEFAULTS: ResolvedConfig = {
  * @param ctx - host plugin context carrying webServer.
  * @param config - resolved plugin config (schema defaults applied by the loader).
  */
-export function apply(ctx: Context, config?: Config): void {
+export const apply = mountOnce('@linxin666/dsh-remote-web-ui', applyImpl)
+
+function applyImpl(ctx: Context, config?: Config): void {
   const resolved: ResolvedConfig = {
     tokenTtlMs: config?.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
     offlineAfterMs: config?.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
@@ -155,6 +191,7 @@ export function apply(ctx: Context, config?: Config): void {
     cookieName: config?.cookieName ?? DEFAULTS.cookieName,
     requirePairingForLan: config?.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
     publicBaseUrl: config?.publicBaseUrl,
+    devicesFile: config?.devicesFile,
     autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
     mobileEnterToSend: config?.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
     enabled: config?.enabled ?? DEFAULTS.enabled,
@@ -172,17 +209,13 @@ export function apply(ctx: Context, config?: Config): void {
       cookieName: value.cookieName ?? DEFAULTS.cookieName,
       requirePairingForLan: value.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
       publicBaseUrl: value.publicBaseUrl,
+      devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
       autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
       mobileEnterToSend: value.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
       enabled: value.enabled ?? DEFAULTS.enabled,
     }
   }
-  const service = new PairingService({
-    tokenTtlMs: resolved.tokenTtlMs,
-    offlineAfterMs: resolved.offlineAfterMs,
-    maxDevices: resolved.maxDevices,
-    cookieName: resolved.cookieName,
-  })
+  const service = new PairingService(pairingConfigOf(resolved))
 
   // ── auto tunnel ─────────────────────────────────────────────────────────
   // The minted public URL becomes the QR base (and the pairing fence's
@@ -309,14 +342,15 @@ export function apply(ctx: Context, config?: Config): void {
   ]
   const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled)
   ctx.effect(() => ctx.on('api/gate', gate), 'remote-web-ui: api gate')
+  // Sibling plugins (aionui-panel, …) look this up by name. Absent when this
+  // plugin is not installed; stop() / enabled=false still refuse cookies.
+  new RemoteWebUiPairing(ctx, (request) => {
+    if (!resolve().enabled) return false
+    return isPairedDeviceRequest(service, request)
+  })
   const sync = (): void => {
     const value = resolve()
-    service.config = {
-      tokenTtlMs: value.tokenTtlMs,
-      offlineAfterMs: value.offlineAfterMs,
-      maxDevices: value.maxDevices,
-      cookieName: value.cookieName,
-    }
+    service.config = pairingConfigOf(value)
     // 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.

package/src/mobile/PairRequiredView.test.tsx

@@ -0,0 +1,28 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { PairRequiredView } from './PairRequiredView.tsx'
+
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
+
+describe('PairRequiredView', () => {
+  it('accepts a pasted link in the installed app context', async () => {
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }))
+    vi.stubGlobal('fetch', fetch)
+    const onPaired = vi.fn()
+    render(<PairRequiredView onPaired={onPaired} />)
+
+    fireEvent.change(screen.getByLabelText('配对链接'), { target: { value: 'https://phone.example/m/?pair=tok-1&workspace=ws-7' } })
+    fireEvent.click(screen.getByRole('button', { name: '配对' }))
+
+    await waitFor(() => expect(onPaired).toHaveBeenCalledWith('/m/?workspace=ws-7'))
+  })
+
+  it('shows an initial QR failure without starting the mobile data channel', () => {
+    render(<PairRequiredView initialError="配对链接已被使用。" onPaired={vi.fn()} />)
+    expect(screen.getByRole('alert').textContent).toContain('配对链接已被使用。')
+  })
+})

package/src/mobile/PairRequiredView.tsx

@@ -0,0 +1,58 @@
+/** Device-pairing gate for installed mobile web-app contexts with isolated storage. */
+import { type FormEvent, useState } from 'react'
+import { acceptMobilePair, mobilePairPath, parseMobilePairInput } from './pairing.ts'
+
+export interface PairRequiredViewProps {
+  initialError?: string
+  onPaired(path: string): void
+}
+
+/** Collect a fresh desktop-issued pairing link when this client has no paired cookie. */
+export function PairRequiredView({ initialError, onPaired }: PairRequiredViewProps) {
+  const [value, setValue] = useState('')
+  const [error, setError] = useState<string | undefined>(initialError)
+  const [submitting, setSubmitting] = useState(false)
+
+  const submit = async (event: FormEvent<HTMLFormElement>): Promise<void> => {
+    event.preventDefault()
+    const input = parseMobilePairInput(value)
+    if (input === undefined) {
+      setError('请输入有效的配对链接。')
+      return
+    }
+
+    setSubmitting(true)
+    setError(undefined)
+    const result = await acceptMobilePair(input.token)
+    setSubmitting(false)
+    if (!result.ok) {
+      setError(result.message)
+      return
+    }
+
+    onPaired(mobilePairPath(input.workspaceId))
+  }
+
+  return (
+    <main className="mobile mobile-pair" aria-labelledby="mobile-pair-title">
+      <form className="mobile-pairCard" onSubmit={(event) => { void submit(event) }}>
+        <h1 id="mobile-pair-title" className="mobile-title">设备配对</h1>
+        <p className="mobile-muted">粘贴桌面端复制的配对链接以连接此设备。</p>
+        <label className="mobile-pairLabel" htmlFor="mobile-pair-link">配对链接</label>
+        <input
+          id="mobile-pair-link"
+          className="mobile-pairInput"
+          value={value}
+          onChange={(event) => { setValue(event.target.value) }}
+          autoComplete="off"
+          autoCapitalize="off"
+          spellCheck={false}
+        />
+        {error === undefined ? null : <p className="mobile-error" role="alert">{error}</p>}
+        <button className="mobile-new mobile-pairSubmit" type="submit" disabled={submitting}>
+          {submitting ? '正在配对' : '配对'}
+        </button>
+      </form>
+    </main>
+  )
+}

package/src/mobile/index.tsx

@@ -11,6 +11,8 @@ import { createRoot } from 'react-dom/client'
 import { App } from './views/App.tsx'
 import { mobileCss } from './mobile-styles.ts'
 import { initMobileTheme } from './mobile-theme.ts'
+import { registerMobilePwa } from '../mobile-pwa.ts'
+import { consumeMobilePairUrl } from './pairing.ts'
 
 // Apply the persisted (or default light) theme before first paint, so the
 // page never flashes the wrong palette.
@@ -24,4 +26,16 @@ document.head.appendChild(style)
 
 const root = document.getElementById('root')
 if (root === null) throw new Error('mobile: #root missing')
-createRoot(root).render(<App />)
+void bootMobile(root)
+
+async function bootMobile(mount: HTMLElement): Promise<void> {
+  const pair = await consumeMobilePairUrl(window.location.href)
+  if (pair.kind === 'accepted') {
+    window.location.replace(pair.path)
+    return
+  }
+  if (pair.kind === 'failed') window.history.replaceState(null, '', pair.path)
+
+  void registerMobilePwa()
+  createRoot(mount).render(<App initialPairError={pair.kind === 'failed' ? pair.message : undefined} />)
+}

package/src/mobile/markdown.test.ts

@@ -22,6 +22,11 @@ describe('safeUrl', () => {
     expect(safeUrl('')).toBeNull()
     expect(safeUrl('   ')).toBeNull()
   })
+
+  it('rejects protocol-relative targets that escape the origin', () => {
+    expect(safeUrl('//attacker.example/x')).toBeNull()
+    expect(safeUrl('  //attacker.example/track.png')).toBeNull()
+  })
 })
 
 describe('renderInline', () => {

package/src/mobile/markdown.ts

@@ -22,15 +22,18 @@ export function escapeHtml(text: string): string {
 
 /**
  * Guard a raw link/image target against dangerous protocols. Returns the
- * (trimmed) raw string when safe, else null. Only http:, https:, mailto:
- * and fragment anchors (#...) are allowed; anything with another scheme
- * — javascript:, data:, vbscript:, etc. — is rejected so the value never
- * reaches dangerouslySetInnerHTML.
+ * (trimmed) raw string when safe, else null. Only http:, https:, mailto:,
+ * fragment anchors (#...) and strictly relative paths are allowed; anything
+ * with another scheme — javascript:, data:, vbscript:, etc. — or a
+ * protocol-relative //host target (the browser resolves it against the
+ * current scheme, reaching an arbitrary origin) is rejected so the value
+ * never reaches dangerouslySetInnerHTML.
  */
 export function safeUrl(raw: string): string | null {
   const trimmed = raw.trim()
   if (trimmed === '') return null
   if (trimmed.startsWith('#')) return trimmed
+  if (trimmed.startsWith('//')) return null
   const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(trimmed)
   if (scheme === null) return trimmed
   const name = scheme[1].toLowerCase()

package/src/mobile/messages.ts

@@ -615,5 +615,18 @@ export function foldEvents(events: readonly WireEvent[], existing?: readonly Ren
     if (event.seq <= watermark) continue
     applyEvent(state, event)
   }
-  return [...state.messages].sort((a, b) => a.seq - b.seq || (a.id < b.id ? -1 : 1))
+  // Incremental tails (the live-stream hot path) are appended in seq order
+  // or updated in place, so the list is usually ordered already — verify in
+  // O(n) and skip the O(n log n) re-sort when it is.
+  const out = state.messages
+  let ordered = true
+  for (let index = 1; index < out.length; index += 1) {
+    const prev = out[index - 1]!
+    const current = out[index]!
+    if (prev.seq > current.seq || (prev.seq === current.seq && prev.id >= current.id)) {
+      ordered = false
+      break
+    }
+  }
+  return ordered ? out : [...out].sort((a, b) => a.seq - b.seq || (a.id < b.id ? -1 : 1))
 }

package/src/mobile/mobile-styles.ts

@@ -1020,4 +1020,52 @@ body {
     transition: none;
   }
 }
+
+/* ── installed-app pairing ───────────────────────────────────────────── */
+
+.mobile-pair {
+  min-height: 100dvh;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+}
+
+.mobile-pairCard {
+  display: grid;
+  width: min(100%, 420px);
+  gap: 12px;
+  padding: 24px;
+  border: 1px solid var(--m-border);
+  border-radius: 12px;
+  background: var(--m-bg-raised);
+  box-shadow: var(--m-shadow-raise);
+}
+
+.mobile-pairLabel {
+  color: var(--m-text-secondary);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.mobile-pairInput {
+  width: 100%;
+  min-height: 42px;
+  box-sizing: border-box;
+  padding: 9px 12px;
+  border: 1px solid var(--m-border);
+  border-radius: 8px;
+  background: var(--m-bg-input);
+  color: var(--m-text);
+  font: inherit;
+  outline: none;
+}
+
+.mobile-pairInput:focus-visible {
+  border-color: var(--m-accent);
+  box-shadow: 0 0 0 2px var(--m-bg), 0 0 0 4px var(--m-accent);
+}
+
+.mobile-pairSubmit {
+  width: 100%;
+}
 `

package/src/mobile/pairing.ts

@@ -0,0 +1,77 @@
+/** Pairing helpers owned by the standalone /m mobile surface. */
+export type PairFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
+export interface MobilePairInput {
+  token: string
+  workspaceId?: string
+}
+
+export type MobilePairAccept =
+  | { ok: true }
+  | { ok: false; message: string }
+
+export type MobilePairBootstrap =
+  | { kind: 'none' }
+  | { kind: 'accepted'; path: string }
+  | { kind: 'failed'; path: string; message: string }
+
+const MOBILE_ROOT = '/m/'
+
+/** Parse a pairing token or a copied pairing link without following its origin. */
+export function parseMobilePairInput(value: string): MobilePairInput | undefined {
+  const trimmed = value.trim()
+  if (trimmed === '') return undefined
+
+  try {
+    const url = new URL(trimmed)
+    const token = url.searchParams.get('pair')
+    if (token === null || token === '') return undefined
+    const workspaceId = url.searchParams.get('workspace')
+    return {
+      token,
+      ...(workspaceId !== null && workspaceId !== '' ? { workspaceId } : {}),
+    }
+  } catch {
+    return { token: trimmed }
+  }
+}
+
+/** Build the safe, token-free mobile destination after successful pairing. */
+export function mobilePairPath(workspaceId?: string): string {
+  return workspaceId === undefined ? MOBILE_ROOT : MOBILE_ROOT + '?workspace=' + encodeURIComponent(workspaceId)
+}
+
+/** Accept one pairing token on this exact browser or installed-web-app context. */
+export async function acceptMobilePair(token: string, fetcher: PairFetch = fetch): Promise<MobilePairAccept> {
+  try {
+    const response = await fetcher('/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, message: '配对链接无效或已过期。' }
+    if (response.status === 409) return { ok: false, message: '配对链接已被使用。' }
+    return { ok: false, message: '此设备无法使用该配对链接。' }
+  } catch {
+    return { ok: false, message: '无法连接到配对服务。' }
+  }
+}
+
+/** Consume a QR pairing token before the mobile application starts making RPC calls. */
+export async function consumeMobilePairUrl(href: string, fetcher: PairFetch = fetch): Promise<MobilePairBootstrap> {
+  let url: URL
+  try {
+    url = new URL(href)
+  } catch {
+    return { kind: 'none' }
+  }
+
+  const token = url.searchParams.get('pair')
+  if (token === null || token === '') return { kind: 'none' }
+
+  const workspaceId = url.searchParams.get('workspace')
+  const path = mobilePairPath(workspaceId === null || workspaceId === '' ? undefined : workspaceId)
+  const result = await acceptMobilePair(token, fetcher)
+  return result.ok ? { kind: 'accepted', path } : { kind: 'failed', path, message: result.message }
+}