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

package/lib/types/update.js

@@ -1,8 +1,8 @@
 /**
  * Remote update support for the dsh-web-ui family — host half. Detects the
- * installed aggregate package (@linxin666/dsh-web-ui-all) and its family
- * children, probes the npm registry for newer releases, and runs the actual
- * update as `pnpm update --latest` inside the owning dsh profile directory.
+ * installed aggregate package (@linxin666/dsh-web-ui-all), or the directly
+ * installed family packages when the aggregate is absent, probes npm for newer
+ * releases, and runs `pnpm update --latest` inside the owning dsh profile.
  *
  * Pure logic with injected seams (manifest reading, registry fetches, process
  * spawning) so the whole surface is unit-testable without touching disk,
@@ -173,10 +173,13 @@ export function resolveUpdateTarget(deps) {
     const spec = profileManifest?.dependencies?.[anchor];
     if (isLinkedSpec(spec))
         return { error: 'link' };
+    // Standalone installs carry no aggregate: the anchor's own dependency
+    // list misses every sibling @linxin666/* plugin installed directly into
+    // the profile, so union the profile's direct family deps (#377).
     return {
         profileName: profile.name,
         profileDir: profile.dir,
-        packages: [anchor, ...familyChildren(manifest)],
+        packages: familyUpdatePackages(anchor, manifest, profileManifest),
     };
 }
 /** Family children of the anchor: its dependencies under the family scope. */
@@ -191,6 +194,18 @@ export function familyChildren(anchorManifest) {
     }
     return names;
 }
+/** Registry-managed family packages covered by one update operation. */
+function familyUpdatePackages(anchor, anchorManifest, profileManifest) {
+    const names = new Set([anchor, ...familyChildren(anchorManifest)]);
+    const dependencies = profileManifest?.dependencies;
+    if (typeof dependencies !== 'object' || dependencies === null)
+        return [...names];
+    for (const [name, spec] of Object.entries(dependencies)) {
+        if (name.startsWith(FAMILY_SCOPE) && typeof spec === 'string' && !isLinkedSpec(spec))
+            names.add(name);
+    }
+    return [...names];
+}
 /**
  * Probe the npm registry for one package's latest release.
  * @param name - the package name (scope slash URL-encoded).
@@ -228,15 +243,20 @@ export async function fetchLatestVersion(name, fetchImpl, timeoutMs = 10_000) {
  */
 const VERSION_UNKNOWN = '0.0.0';
 /** The resolved current version of one family package (probe failure tolerated). */
-function readInstalledVersion(resolve, name) {
+function readInstalledVersion(resolve, name, profileDir) {
     try {
         const path = resolve(name + '/package.json');
         const version = path === undefined ? undefined : readManifest(path)?.version;
-        return typeof version === 'string' ? version : VERSION_UNKNOWN;
+        if (typeof version === 'string')
+            return version;
     }
-    catch {
+    catch { /* fall through to the profile's direct dependency path */ }
+    // Names originate in the profile dependency map, but still validate the
+    // npm package shape before using one as path segments.
+    if (profileDir === undefined || !/^@linxin666\/[a-z0-9][a-z0-9._-]*$/.test(name))
         return VERSION_UNKNOWN;
-    }
+    const version = readManifest(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'))?.version;
+    return typeof version === 'string' ? version : VERSION_UNKNOWN;
 }
 /**
  * Build the update status: locate the anchor, detect the install mode, and
@@ -267,7 +287,10 @@ export async function checkUpdates(deps) {
     if (profile === undefined) {
         return { mode: 'link', packages: [], outdated: false };
     }
-    const names = [anchor, ...familyChildren(manifest)];
+    // Union the profile's direct family deps so standalone installs (no
+    // aggregate) still check every installed @linxin666/* plugin (#377);
+    // familyUpdatePackages skips link:/file: development dependencies.
+    const names = familyUpdatePackages(anchor, manifest, profileManifest);
     // The registry probes are independent: run them together instead of
     // serializing up to N x 10s of registry latency behind one status call.
     const latestList = await Promise.all(names.map(name => deps.fetchLatest(name)));
@@ -277,7 +300,7 @@ export async function checkUpdates(deps) {
         const latest = latestList[index];
         if (latest === undefined)
             probeFailures++;
-        const current = readInstalledVersion(deps.resolve, name);
+        const current = readInstalledVersion(deps.resolve, name, profile.dir);
         packages.push({
             name,
             current,
@@ -494,7 +517,7 @@ export async function runUpdateVerified(deps) {
     // green exit that left everything in place could be mistaken for success.
     const before = new Map();
     for (const name of deps.run.packages) {
-        const version = readInstalledVersion(deps.check.resolve, name);
+        const version = readInstalledVersion(deps.check.resolve, name, deps.run.profileDir);
         if (version !== VERSION_UNKNOWN)
             before.set(name, version);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-remote-web-ui",
   "description": "Mobile remote control for the dsh web GUI: scan-to-pair QR entry beside the settings button, one-time pairing tokens, live device status, and revocable mobile sessions",
-  "version": "0.1.20",
+  "version": "0.2.0",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -61,17 +61,17 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-host-apiproxy": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-apiproxy": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/client/PluginSettingsCard.tsx

@@ -56,6 +56,12 @@ export interface PluginSettingsCardProps<TKey extends string = string> {
    * already provides the selection.
    */
   alwaysOpen?: boolean
+  /**
+   * Hide the save/discard footer: cards whose body applies its own changes
+   * immediately (an embedded external settings section) have no staged
+   * edits, so the footer would sit there permanently disabled.
+   */
+  hideFooter?: boolean
   /** The plugin's controls. */
   children: ReactNode
 }
@@ -140,6 +146,9 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
           <div className={css.body}>
             {!state.writable ? <p className={css.readOnly} role="status">{props.t('settings.readOnly')}</p> : null}
             {props.children}
+            {props.hideFooter === true
+              ? null
+              : (
             <div className={css.footer}>
               {state.failed
                 ? (
@@ -165,6 +174,7 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
                 {props.t(!state.saving ? 'settings.save' : 'settings.saving')}
               </button>
             </div>
+              )}
           </div>
         )
         : null}

package/src/client/RemoteEntry.tsx

@@ -222,13 +222,13 @@ export function RemoteEntry({ wide, useWorkspaces, t }: RemoteEntryProps) {
   )
 }
 
-/** The trigger: an icon button matching the settings rail/row geometry. */
+/** The trigger: an icon-only control with a persistent accessible label. */
 function TooltipAnchor({ wide, label, onClick }: { wide: boolean; label: string; onClick: () => void }) {
   return (
     <button
       type="button"
       className={css.trigger}
-      data-wide={wide ? undefined : 'rail'}
+      data-wide={wide ? 'wide' : 'rail'}
       aria-label={label}
       title={label}
       onClick={onClick}

package/src/client/RemoteSettingsCard.tsx

@@ -140,6 +140,7 @@ export function RemoteSettingsCard(props: RemoteSettingsCardProps) {
       t={t}
       titleKey="settings.title"
       descriptionKey="settings.description"
+      defaultOpen={false}
       state={state}
       onSave={props.save}
       onDiscard={props.discard}

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/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/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/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%;
+}
 `