@linxin666/dsh-remote-web-ui 0.1.20 → 0.2.1

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'
@@ -89,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
@@ -115,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),
@@ -128,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 = {
@@ -138,6 +170,7 @@ const DEFAULTS: ResolvedConfig = {
   cookieName: 'dsh_pair',
   requirePairingForLan: true,
   publicBaseUrl: undefined,
+  devicesFile: undefined,
   autoTunnel: false,
   mobileEnterToSend: true,
   enabled: true,
@@ -158,6 +191,7 @@ function applyImpl(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,
@@ -175,17 +209,13 @@ function applyImpl(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
@@ -312,14 +342,15 @@ function applyImpl(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/api.ts

@@ -6,6 +6,7 @@
  */
 
 import type { WorkspaceView } from '@deepseek-ai/dsh-host-apiproxy/api/workspace'
+import type { AgentPresetEntry } from '@deepseek-ai/dsh-host-apiproxy/api/agent-presets'
 import type { SessionSummary, SessionModels, SessionProjectionsBlock } from '@deepseek-ai/dsh-host-apiproxy/api/sessions'
 import { callUnary } from './rpc.ts'
 
@@ -24,6 +25,13 @@ export interface CreatedSession {
   agentPreset?: string
 }
 
+/** Agent presets available when composing a new session. */
+export interface AgentPresetRoster {
+  presets: readonly AgentPresetEntry[]
+  authorable: boolean
+  hasDocument: boolean
+}
+
 /** One history page (already bounded to whole messages by the host). */
 export interface HistoryPage {
   events: import('@deepseek-ai/dsh-host-apiproxy/api/sessions').HistoryEntry[]
@@ -57,12 +65,17 @@ export async function listSessions(cursor?: string): Promise<SessionPage> {
   return await callUnary<SessionPage>('session.list', cursor === undefined ? {} : { cursor })
 }
 
+/** Read the available agent compositions for a new session. */
+export async function listAgentPresets(): Promise<AgentPresetRoster> {
+  return await callUnary<AgentPresetRoster>('agentPreset.list', {})
+}
+
 /**
  * Create a blank session (entity birth precedes the first message). Name a
  * workspace to attach it there, or a cwd; omitting both uses the host cwd.
  */
 export async function createSession(
-  options: { workspaceId?: string; cwd?: string } = {},
+  options: { workspaceId?: string; cwd?: string; agentPreset?: string } = {},
 ): Promise<CreatedSession> {
   return await callUnary<CreatedSession>('session.create', options)
 }

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/messages.test.ts

@@ -1,6 +1,6 @@
 /** foldEvents: message-list folding from a session event stream. */
 import { describe, expect, it } from 'vitest'
-import { foldEvents, type WireEvent } from './messages.ts'
+import { EventFolder, foldEvents, type WireEvent } from './messages.ts'
 
 /** Assemble one event with an auto-incrementing seq / time. */
 function makeEvent(
@@ -326,3 +326,54 @@ describe('foldEvents', () => {
     expect(result[0]).toMatchObject({ id: 'u-1', kind: 'user' })
   })
 })
+
+describe('EventFolder incremental folding', () => {
+  it('matches a one-shot fold when events arrive one at a time', () => {
+    const stream: WireEvent[] = [
+      makeEvent('user/message', userMessageData('u-1', 'hi'), 0),
+      textChunk(0, 0, '你', 1),
+      textChunk(0, 0, '好', 2),
+      makeEvent('assistant/message', assistantMessageData('a-1', 0, 0, '你好'), 3),
+      makeEvent('message/update', { id: 'u-1', text: '更新' }, 4),
+    ]
+    const oneShot = foldEvents(stream)
+    const folder = new EventFolder()
+    let incremental: ReturnType<typeof foldEvents> = []
+    for (const event of stream) incremental = folder.fold([event])
+    expect(incremental).toEqual(oneShot)
+  })
+
+  it('replays and re-folds are no-ops and reuse the previous snapshot identity', () => {
+    const folder = new EventFolder(foldEvents([
+      makeEvent('user/message', userMessageData('u-1', 'hi'), 0),
+      textChunk(0, 0, '你', 1),
+    ]))
+    const first = folder.fold([textChunk(0, 0, '好', 2)])
+    expect(first[first.length - 1]).toMatchObject({ text: '你好', pending: true })
+    // Same event again (wire replay or a double-invoked state updater): no change, same identity.
+    const replay = folder.fold([textChunk(0, 0, '好', 2)])
+    expect(replay).toBe(first)
+    // A no-op batch over an already folded stream also keeps the identity.
+    expect(folder.fold([])).toBe(first)
+  })
+
+  it('prepends older pages and keeps folding live events on top', () => {
+    const folder = new EventFolder(foldEvents([
+      makeEvent('user/message', userMessageData('u-2', '第二页'), 10),
+    ]))
+    folder.prepend(foldEvents([makeEvent('user/message', userMessageData('u-1', '第一页'), 5)]))
+    const withLive = folder.fold([textChunk(0, 0, '新', 11)])
+    expect(withLive.map(message => message.id)).toEqual(['u-1', 'u-2', 'assistant,0.0#11'])
+    // The live fold must not lose the prepended rows on later events.
+    const later = folder.fold([textChunk(0, 0, '续', 12)])
+    expect(later.map(message => message.id)).toEqual(['u-1', 'u-2', 'assistant,0.0#11'])
+    expect(later[2]).toMatchObject({ text: '新续', pending: true })
+  })
+
+  it('seed replaces the whole stream', () => {
+    const folder = new EventFolder(foldEvents([makeEvent('user/message', userMessageData('u-1', '旧'), 0)]))
+    folder.seed(foldEvents([makeEvent('user/message', userMessageData('u-2', '新'), 5)]))
+    expect(folder.snapshot().map(message => message.id)).toEqual(['u-2'])
+    expect(folder.fold([textChunk(0, 0, '追加', 6)]).map(message => message.id)).toEqual(['u-2', 'assistant,0.0#6'])
+  })
+})

package/src/mobile/messages.ts

@@ -191,16 +191,6 @@ function chunkTarget(data: unknown): { text: string; kind: 'text' | 'reasoning';
   return result
 }
 
-/** Max message seq across an existing list, or -1 for an empty list. */
-function watermarkOf(existing: readonly RenderMessage[] | undefined): number {
-  if (existing === undefined) return -1
-  let maxSeq = -1
-  for (const message of existing) {
-    if (message.seq > maxSeq) maxSeq = message.seq
-  }
-  return maxSeq
-}
-
 /** Mutable fold state; message objects are immutable and swapped on change. */
 interface FoldState {
   messages: RenderMessage[]
@@ -215,6 +205,8 @@ interface FoldState {
   toolNames: Map<string, Set<string>>
   /** Context window for the current model (from request/context). */
   contextWindow?: number
+  /** Highest seq folded so far; the replay/watermark gate. */
+  maxSeq: number
 }
 
 function createState(existing: readonly RenderMessage[] | undefined): FoldState {
@@ -226,8 +218,10 @@ function createState(existing: readonly RenderMessage[] | undefined): FoldState
     turnStepMessage: new Map(),
     messageTurn: new Map(),
     toolNames: new Map(),
+    maxSeq: -1,
   }
   for (const message of messages) {
+    if (message.seq > state.maxSeq) state.maxSeq = message.seq
     state.byId.set(message.id, message)
     if (message.kind !== 'assistant') continue
     // Rebuild the (turn, step) and turn index maps lost when `existing` was
@@ -287,6 +281,7 @@ function retargetTurnStep(state: FoldState, key: string | undefined, oldMessage:
 
 /** Fold one event into the working state. Assumes the event passes the watermark. */
 function applyEvent(state: FoldState, event: WireEvent): void {
+  if (event.seq > state.maxSeq) state.maxSeq = event.seq
   switch (event.type) {
     case 'user/message':
       applyUserMessage(state, event)
@@ -608,17 +603,65 @@ function applyTurnEnd(state: FoldState, event: WireEvent): void {
  * @returns messages sorted by seq.
  */
 export function foldEvents(events: readonly WireEvent[], existing?: readonly RenderMessage[]): RenderMessage[] {
-  const sorted = [...events].sort((a, b) => a.seq - b.seq)
-  const watermark = watermarkOf(existing)
-  const state = createState(existing)
-  for (const event of sorted) {
-    if (event.seq <= watermark) continue
-    applyEvent(state, event)
-  }
-  // 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
+  return new EventFolder(existing).fold(events)
+}
+
+/**
+ * Incremental folder for one message stream. Live chat folds one event at a
+ * time; rebuilding the five index maps by scanning every message per event
+ * made that path O(n) per event (O(n * events) per turn). A folder keeps the
+ * indexes alive across folds, applies each event in O(1) map operations, and
+ * returns the previous snapshot identity unchanged when nothing applied, so
+ * React skips the re-render entirely. Replayed events are no-ops: the maxSeq
+ * watermark advanced by the first application skips them, which also makes a
+ * double-invoked React state updater harmless.
+ */
+export class EventFolder {
+  private state: FoldState
+  private snapshotList: RenderMessage[] | undefined
+
+  /** @param initial - seed rows (history tail load); omit for an empty stream. */
+  constructor(initial?: readonly RenderMessage[]) {
+    this.state = createState(initial)
+  }
+
+  /** Fold one batch incrementally; returns the current snapshot list. */
+  fold(events: readonly WireEvent[]): RenderMessage[] {
+    const sorted = [...events].sort((a, b) => a.seq - b.seq)
+    let applied = false
+    for (const event of sorted) {
+      if (event.seq <= this.state.maxSeq) continue
+      applyEvent(this.state, event)
+      applied = true
+    }
+    if (!applied && this.snapshotList !== undefined) return this.snapshotList
+    this.snapshotList = snapshotOf(this.state)
+    return this.snapshotList
+  }
+
+  /** Replace the whole stream (history reload / session switch). */
+  seed(messages: readonly RenderMessage[]): void {
+    this.state = createState(messages)
+    this.snapshotList = undefined
+  }
+
+  /** Prepend an older history page (exact seam; no overlapping seqs). */
+  prepend(older: readonly RenderMessage[]): void {
+    this.state = createState([...older, ...this.state.messages])
+    this.snapshotList = undefined
+  }
+
+  /** Current snapshot list; a fresh copy whenever the folder changed. */
+  snapshot(): RenderMessage[] {
+    if (this.snapshotList !== undefined) return this.snapshotList
+    this.snapshotList = snapshotOf(this.state)
+    return this.snapshotList
+  }
+}
+
+/** Copy the folder's rows and keep them seq-ordered (skips re-sorting the common ordered case). */
+function snapshotOf(state: FoldState): RenderMessage[] {
+  const out = [...state.messages]
   let ordered = true
   for (let index = 1; index < out.length; index += 1) {
     const prev = out[index - 1]!
@@ -628,5 +671,5 @@ export function foldEvents(events: readonly WireEvent[], existing?: readonly Ren
       break
     }
   }
-  return ordered ? out : [...out].sort((a, b) => a.seq - b.seq || (a.id < b.id ? -1 : 1))
+  return ordered ? out : out.sort((a, b) => a.seq - b.seq || (a.id < b.id ? -1 : 1))
 }

package/src/mobile/mobile-styles.ts

@@ -252,6 +252,43 @@ body {
   padding: 8px 16px;
 }
 
+.mobile-create {
+  display: grid;
+  gap: 8px;
+}
+
+.mobile-preset {
+  display: grid;
+  gap: 4px;
+}
+
+.mobile-presetLabel {
+  color: var(--m-text-secondary);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.mobile-presetSelect {
+  width: 100%;
+  height: 40px;
+  padding: 0 36px 0 12px;
+  border: 1px solid var(--m-border);
+  border-radius: 10px;
+  background: var(--m-bg-input);
+  color: var(--m-text);
+  font: inherit;
+}
+
+.mobile-presetSelect:disabled {
+  opacity: 0.6;
+}
+
+.mobile-presetDescription {
+  margin: 0;
+  color: var(--m-text-tertiary);
+  font-size: 12px;
+}
+
 /* ── buttons ─────────────────────────────────────────────────────────── */
 
 .mobile-button {
@@ -896,6 +933,7 @@ body {
 .mobile-row:focus-visible,
 .mobile-button:focus-visible,
 .mobile-new:focus-visible,
+.mobile-presetSelect:focus-visible,
 .chat-send:focus-visible,
 .chat-chip:focus-visible,
 .chat-msg-toggle:focus-visible,
@@ -1020,4 +1058,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 }
+}