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

package/src/mobile/views/App.test.tsx

@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import { RpcTransportError } from '../rpc.ts'
+
+const api = vi.hoisted(() => ({
+  fetchMobilePreferences: vi.fn(),
+  history: vi.fn(),
+  listSessions: vi.fn(),
+  listWorkspaces: vi.fn(),
+  prompt: vi.fn(),
+}))
+
+vi.mock('../api.ts', () => api)
+vi.mock('../mux.ts', () => ({
+  MuxClient: class {
+    start(): void {}
+    stop(): void {}
+    observe(): void {}
+  },
+}))
+vi.mock('./WorkspaceView.tsx', () => ({ WorkspaceView: () => <div>workspace-ready</div> }))
+vi.mock('./SessionListView.tsx', () => ({ SessionListView: () => <div>sessions-ready</div> }))
+vi.mock('./ChatView.tsx', () => ({ ChatView: () => <div>chat-ready</div> }))
+
+import { App, mobilePairStateForError } from './App.tsx'
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+describe('mobile paired-device gate', () => {
+  it('distinguishes a missing paired cookie from a transport outage', () => {
+    expect(mobilePairStateForError(new RpcTransportError('HTTP 403'))).toBe('unpaired')
+    expect(mobilePairStateForError(new RpcTransportError('HTTP 503'))).toBe('unavailable')
+    expect(mobilePairStateForError(new Error('offline'))).toBe('unavailable')
+  })
+
+  it('keeps a valid paired context usable after a failed QR token', async () => {
+    api.fetchMobilePreferences.mockResolvedValue({ mobileEnterToSend: true })
+    render(<App initialPairError="配对链接已被使用。" />)
+
+    await waitFor(() => expect(screen.getByText('workspace-ready')).toBeDefined())
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  it('shows the pairing screen only when the mobile gateway rejects the device', async () => {
+    api.fetchMobilePreferences.mockRejectedValue(new RpcTransportError('HTTP 403'))
+    render(<App initialPairError="配对链接已被使用。" />)
+
+    await waitFor(() => expect(screen.getByRole('alert').textContent).toContain('配对链接已被使用。'))
+  })
+
+  it('shows a retryable connection failure rather than mounting remote views on outage', async () => {
+    api.fetchMobilePreferences.mockRejectedValue(new RpcTransportError('HTTP 503'))
+    render(<App />)
+
+    await waitFor(() => expect(screen.getByRole('alert').textContent).toContain('无法连接到运行中的 DSH host。'))
+    expect(screen.queryByText('workspace-ready')).toBeNull()
+  })
+})

package/src/mobile/views/App.tsx

@@ -7,12 +7,13 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react'
 import type { WorkspaceView as WorkspaceRow } from '@deepseek-ai/dsh-host-apiproxy/api/workspace'
-import { history as fetchHistory, listSessions, listWorkspaces, prompt } from '../api.ts'
+import { fetchMobilePreferences, history as fetchHistory, listSessions, listWorkspaces, prompt } from '../api.ts'
 import { MuxClient } from '../mux.ts'
 import { RpcCallError, RpcTransportError } from '../rpc.ts'
 import { ChatView } from './ChatView.tsx'
 import { SessionListView } from './SessionListView.tsx'
 import { WorkspaceView as WorkspaceRoster } from './WorkspaceView.tsx'
+import { PairRequiredView } from '../PairRequiredView.tsx'
 
 /** One navigation level. */
 type Route =
@@ -30,18 +31,6 @@ export interface SessionView {
   blank: boolean
 }
 
-/** One rendered chat message (produced by the fold). */
-export interface RenderMessage {
-  id: string
-  kind: 'user' | 'assistant'
-  text: string
-  seq: number
-  time: number
-  pending?: boolean
-  failed?: boolean
-  toolSummary?: string
-}
-
 /** Read the optional workspace target carried from the pairing QR flow. */
 export function mobileWorkspaceTarget(search: string): string | undefined {
   const value = new URLSearchParams(search).get('workspace')
@@ -83,11 +72,57 @@ export function formatTime(epochMs: number): string {
   return `${String(date.getMonth() + 1)}月${String(date.getDate())}日 ${clock}`
 }
 
-/**
- * The surface root.
- * @returns the app tree.
- */
-export function App() {
+/** Props accepted by the mobile root before it begins paired-device RPC calls. */
+export interface AppProps {
+  initialPairError?: string
+}
+
+/** Whether the mobile gateway rejected this browser for lack of a paired cookie. */
+export function isUnpairedMobileError(error: unknown): boolean {
+  return error instanceof RpcTransportError && error.message === 'HTTP 403'
+}
+
+/** The result of probing the paired-device-only mobile preference endpoint. */
+export type MobilePairState = 'checking' | 'paired' | 'unpaired' | 'unavailable'
+
+/** Classify an initial mobile preference failure without treating outage as authorization. */
+export function mobilePairStateForError(error: unknown): Extract<MobilePairState, 'unpaired' | 'unavailable'> {
+  return isUnpairedMobileError(error) ? 'unpaired' : 'unavailable'
+}
+
+/** Gate the independent mobile bundle until its own browser context is paired. */
+export function App({ initialPairError }: AppProps) {
+  const [pairState, setPairState] = useState<MobilePairState>('checking')
+
+  useEffect(() => {
+    let current = true
+    void fetchMobilePreferences().then(
+      () => { if (current) setPairState('paired') },
+      (error: unknown) => { if (current) setPairState(mobilePairStateForError(error)) },
+    )
+    return () => { current = false }
+  }, [])
+
+  if (pairState === 'checking') {
+    return <main className="mobile mobile-empty"><p className="mobile-muted">正在连接...</p></main>
+  }
+  if (pairState === 'unpaired') {
+    return <PairRequiredView initialError={initialPairError} onPaired={(path) => { window.location.replace(path) }} />
+  }
+  if (pairState === 'unavailable') {
+    return (
+      <main className="mobile mobile-empty">
+        <p className="mobile-error" role="alert">无法连接到运行中的 DSH host。</p>
+        <button className="mobile-new" type="button" onClick={() => { window.location.reload() }}>重试</button>
+      </main>
+    )
+  }
+
+  return <PairedApp />
+}
+
+/** The existing remote mobile surface, mounted only after device pairing succeeds. */
+function PairedApp() {
   const [route, setRoute] = useState<Route>({ kind: 'workspaces' })
   const [initialWorkspaceId, setInitialWorkspaceId] = useState<string | undefined>(
     () => mobileWorkspaceTarget(window.location.search),

package/src/mobile-api.ts

@@ -25,6 +25,7 @@ import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
 import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import type { PairingService } from './pairing.ts'
+import { readBoundedJson, writeJson } from './http.ts'
 import { readCookie } from './gate.ts'
 
 /** Methods the phone surface may call. Everything else is refused. */
@@ -122,11 +123,6 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
     return touchDeviceFor(req)
   }
 
-  const writeJson = (res: ServerResponse, status: number, body: unknown): void => {
-    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
-    res.end(JSON.stringify(body))
-  }
-
   const handleMethod = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (req.method !== 'POST') {
       res.writeHead(405)
@@ -170,7 +166,11 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
       return
     }
     try {
-      const response = await dispatch(apiProxy, method, parsed?.payload, rpcId)
+      // Cancel the host-side work when the phone goes away mid-call (the
+      // response stream closing before we answer means nobody is listening).
+      const abort = new AbortController()
+      res.on('close', () => { if (!res.writableEnded) abort.abort() })
+      const response = await dispatch(apiProxy, method, parsed?.payload, rpcId, abort.signal)
       writeJson(res, 200, response)
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
@@ -244,19 +244,11 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
 
 /** Read a request body as JSON (bounded). */
 async function readJsonBody(req: IncomingMessage): Promise<unknown> {
-  const chunks: Buffer[] = []
-  let size = 0
-  for await (const chunk of req) {
-    const buffer = chunk as Buffer
-    size += buffer.length
-    if (size > 64 * 1024) throw new Error('body too large')
-    chunks.push(buffer)
-  }
-  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  return readBoundedJson(req, 64 * 1024)
 }
 
 /** Dispatch one allowlisted method through the host ApiProxy. */
-async function dispatch(apiProxy: ApiProxy, method: string, payload: unknown, rpcId: string): Promise<unknown> {
+async function dispatch(apiProxy: ApiProxy, method: string, payload: unknown, rpcId: string, signal?: AbortSignal): Promise<unknown> {
   const request: RpcRequest<unknown> = { rpcId: RpcId(rpcId), payload }
   if (method === 'session.list') {
     const full = await apiProxy.sessions.list(request as never)
@@ -302,7 +294,7 @@ async function dispatch(apiProxy: ApiProxy, method: string, payload: unknown, rp
   if (method === 'workspace.list') return wrap(await apiProxy.workspace.list(request as never))
   if (method === 'session.create') return wrap(await apiProxy.sessions.create(request as never))
   if (method === 'session.history') return wrap(await apiProxy.sessions.history(request as never))
-  if (method === 'session.search') return wrap(await apiProxy.sessions.search(request as never, new AbortController().signal))
+  if (method === 'session.search') return wrap(await apiProxy.sessions.search(request as never, signal ?? new AbortController().signal))
   if (method === 'session.prompt') return wrap(await apiProxy.sessions.prompt(request as never))
   if (method === 'session.models') return wrap(await apiProxy.sessions.models(request as never))
   if (method === 'session.selectModel') return wrap(await apiProxy.sessions.selectModel(request as never))

package/src/mobile-pwa.ts

@@ -0,0 +1,19 @@
+/** PWA registration for the standalone /m mobile surface. */
+export const MOBILE_PWA_SCOPE = '/m/'
+export const MOBILE_SERVICE_WORKER_URL = '/m/service-worker.js'
+
+/** Register the mobile shell worker when the current browser supports it. */
+export async function registerMobilePwa(
+  serviceWorker: Pick<ServiceWorkerContainer, 'register'> | undefined = typeof navigator === 'undefined' ? undefined : navigator.serviceWorker,
+): Promise<void> {
+  if (serviceWorker === undefined) return
+
+  try {
+    await serviceWorker.register(MOBILE_SERVICE_WORKER_URL, {
+      scope: MOBILE_PWA_SCOPE,
+      updateViaCache: 'none',
+    })
+  } catch {
+    // HTTP LAN origins cannot register workers; the online mobile UI still works.
+  }
+}

package/src/mobile-routes.ts

@@ -1,11 +1,8 @@
 /**
- * The mobile surface's page routes: `/m` serves the standalone phone UI
- * (an independent bundle, built to lib/mobile.js by the mobile tsdown
- * entry), `/m/mobile.js` serves the bundle itself. The page talks to the
- * host exclusively through the shared /api transport (paired-device cookie
- * already crosses the api/gate fence), so no host-side data plumbing is
- * needed here — only static serving, loopback+paired-fence via the normal
- * webserver route registration.
+ * The mobile surface's page routes: /m canonicalizes to /m/, which serves the
+ * standalone phone UI. The page and worker live in the /m/ scope so the PWA
+ * can cache only its static shell; the paired-device data channel remains at
+ * /m/api and is never handled by the worker.
  */
 
 import { readFile } from 'node:fs/promises'
@@ -14,17 +11,23 @@ import { fileURLToPath } from 'node:url'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 
+const MOBILE_ROOT = '/m/'
+const MOBILE_BUNDLE_URL = '/m/mobile.js'
+const MOBILE_MANIFEST_URL = '/m/manifest.webmanifest'
+const MOBILE_WORKER_URL = '/m/service-worker.js'
+const MOBILE_OFFLINE_URL = '/m/offline.html'
+
 /** The standalone mobile bundle (built artifact, next to this file's own lib output). */
 function mobileBundlePath(): string {
   return fileURLToPath(new URL('../lib/mobile.js', import.meta.url))
 }
 
-/** The apple-touch-icon shipped with the package (iOS home-screen icon, 180x180 PNG). */
-function appleTouchIconPath(): string {
-  return fileURLToPath(new URL('../assets/apple-touch-icon.png', import.meta.url))
+/** A package asset available to the host after a registry or git install. */
+function mobileAssetPath(name: string): string {
+  return fileURLToPath(new URL('../assets/' + name, import.meta.url))
 }
 
-/** The mobile page shell: minimal, offline-safe, no external assets. */
+/** The mobile page shell: self-contained, with no document-level user data. */
 function pageHtml(bundleUrl: string): string {
   return [
     '<!doctype html>',
@@ -34,31 +37,78 @@ function pageHtml(bundleUrl: string): string {
     '<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">',
     '<meta name="theme-color" content="#f3f5f9">',
     '<meta name="referrer" content="no-referrer">',
-    // iOS "Add to Home Screen" uses apple-touch-icon for the tile icon;
-    // the PNG ships with the package (opaque background — iOS composites
-    // transparency onto black, so the icon avoids transparent regions).
+    '<meta name="mobile-web-app-capable" content="yes">',
+    '<meta name="apple-mobile-web-app-capable" content="yes">',
+    '<meta name="apple-mobile-web-app-title" content="DSH Remote">',
+    '<link rel="manifest" href="/m/manifest.webmanifest">',
     '<link rel="apple-touch-icon" href="/m/apple-touch-icon.png">',
     '<title>移动端远程控制</title>',
     '</head>',
     '<body>',
     '<div id="root"></div>',
-    `<script type="module" src="${bundleUrl}"></script>`,
+    '<script type="module" src="' + bundleUrl + '"></script>',
     '</body>',
     '</html>',
   ].join('')
 }
 
-/** Send a small static body with cache headers (the bundle is content-hashed by rebuild). */
+/** The installable app identity and icon declarations for the /m scope. */
+function manifestJson(): string {
+  return JSON.stringify({
+    id: MOBILE_ROOT,
+    name: 'DSH Remote',
+    short_name: 'DSH Remote',
+    start_url: MOBILE_ROOT,
+    scope: MOBILE_ROOT,
+    display: 'standalone',
+    background_color: '#151424',
+    theme_color: '#f3f5f9',
+    icons: [
+      { src: '/m/icon-192.png', sizes: '192x192', type: 'image/png', purpose: 'any' },
+      { src: '/m/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'any maskable' },
+    ],
+  }, null, 2)
+}
+
+/** A static fallback that contains no paired-device, session, or workspace data. */
+function offlineHtml(): string {
+  return [
+    '<!doctype html>',
+    '<html lang="zh-CN">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">',
+    '<meta name="theme-color" content="#151424">',
+    '<title>DSH Remote</title>',
+    '<style>body{margin:0;background:#151424;color:#f3f5f9;font:16px system-ui,sans-serif}main{box-sizing:border-box;display:grid;min-height:100vh;place-content:center;padding:32px;text-align:center}h1{margin:0 0 12px;font-size:24px}p{margin:0;color:#c4c7d8;line-height:1.5}</style>',
+    '</head>',
+    '<body><main><h1>DSH Remote</h1><p>Cannot reach the running DSH host. Restore the connection and reopen the app.</p></main></body>',
+    '</html>',
+  ].join('')
+}
+
+/** Send a small static UTF-8 body with revalidation headers. */
 function writeStatic(res: ServerResponse, status: number, type: string, body: string): void {
   res.writeHead(status, {
-    'content-type': `${type}; charset=utf-8`,
+    'content-type': type + '; charset=utf-8',
+    'cache-control': 'no-cache',
+    'referrer-policy': 'no-referrer',
+  })
+  res.end(body)
+}
+
+/** Send the worker with the same scope it registers for, without HTTP caching. */
+function writeServiceWorker(res: ServerResponse, body: string): void {
+  res.writeHead(200, {
+    'content-type': 'text/javascript; charset=utf-8',
     'cache-control': 'no-cache',
     'referrer-policy': 'no-referrer',
+    'service-worker-allowed': MOBILE_ROOT,
   })
   res.end(body)
 }
 
-/** Send the PNG icon as a binary body (unlike text assets, the PNG must not be decoded to utf-8). */
+/** Send a PNG body without decoding it to UTF-8. */
 function writePng(res: ServerResponse, status: number, body: Buffer): void {
   res.writeHead(status, {
     'content-type': 'image/png',
@@ -68,43 +118,92 @@ function writePng(res: ServerResponse, status: number, body: Buffer): void {
   res.end(body)
 }
 
+/** Canonicalize the old /m route while retaining pair and workspace query parameters. */
+function redirectToMobileRoot(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url ?? '/m', 'http://x')
+  res.writeHead(308, {
+    location: MOBILE_ROOT + url.search,
+    'cache-control': 'no-store',
+    'referrer-policy': 'no-referrer',
+  })
+  res.end()
+}
+
 /**
  * Build the mobile page routes.
- * @returns the two exact routes to register on webServer.
+ * @returns Exact routes for the canonical page, static shell, and PWA assets.
  */
 export function makeMobileRoutes(): WebRoute[] {
   const handlePage = (_req: IncomingMessage, res: ServerResponse): void => {
-    writeStatic(res, 200, 'text/html', pageHtml('/m/mobile.js'))
+    writeStatic(res, 200, 'text/html', pageHtml(MOBILE_BUNDLE_URL))
+  }
+  const handleManifest = (_req: IncomingMessage, res: ServerResponse): void => {
+    writeStatic(res, 200, 'application/manifest+json', manifestJson())
   }
+  const handleOffline = (_req: IncomingMessage, res: ServerResponse): void => {
+    writeStatic(res, 200, 'text/html', offlineHtml())
+  }
+
+  // The bundle is immutable for the process lifetime (a rebuild requires a
+  // host restart), so the body is read from disk once, not per phone.
+  let bundleBody: string | undefined
   const handleBundle = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
-    const path = mobileBundlePath()
-    if (!existsSync(path)) {
-      writeStatic(res, 503, 'text/plain', 'mobile bundle not built: run pnpm --filter @linxin666/dsh-remote-web-ui build')
-      return
+    if (bundleBody === undefined) {
+      const path = mobileBundlePath()
+      if (!existsSync(path)) {
+        writeStatic(res, 503, 'text/plain', 'mobile bundle not built: run pnpm --filter @linxin666/dsh-remote-web-ui build')
+        return
+      }
+      try {
+        bundleBody = await readFile(path, 'utf8')
+      } catch {
+        writeStatic(res, 500, 'text/plain', 'failed to read the mobile bundle')
+        return
+      }
     }
-    try {
-      const body = await readFile(path, 'utf8')
-      writeStatic(res, 200, 'text/javascript', body)
-    } catch {
-      writeStatic(res, 500, 'text/plain', 'failed to read the mobile bundle')
+    writeStatic(res, 200, 'text/javascript', bundleBody)
+  }
+
+  let workerBody: string | undefined
+  const handleWorker = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (workerBody === undefined) {
+      const path = mobileAssetPath('mobile-service-worker.js')
+      if (!existsSync(path)) {
+        writeStatic(res, 503, 'text/plain', 'mobile service worker not found')
+        return
+      }
+      try {
+        workerBody = await readFile(path, 'utf8')
+      } catch {
+        writeStatic(res, 500, 'text/plain', 'failed to read the mobile service worker')
+        return
+      }
     }
+    writeServiceWorker(res, workerBody)
   }
-  const handleIcon = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
-    const path = appleTouchIconPath()
+
+  const makeIconHandler = (asset: string): WebRoute['handler'] => async (_req, res) => {
+    const path = mobileAssetPath(asset)
     if (!existsSync(path)) {
-      writeStatic(res, 404, 'text/plain', 'apple-touch-icon not found')
+      writeStatic(res, 404, 'text/plain', asset + ' not found')
       return
     }
     try {
-      const body = await readFile(path)
-      writePng(res, 200, body)
+      writePng(res, 200, await readFile(path))
     } catch {
-      writeStatic(res, 500, 'text/plain', 'failed to read the apple-touch-icon')
+      writeStatic(res, 500, 'text/plain', 'failed to read ' + asset)
     }
   }
+
   return [
-    { kind: 'exact', path: '/m', handler: handlePage },
-    { kind: 'exact', path: '/m/mobile.js', handler: handleBundle },
-    { kind: 'exact', path: '/m/apple-touch-icon.png', handler: handleIcon },
+    { kind: 'exact', path: '/m', handler: redirectToMobileRoot },
+    { kind: 'exact', path: MOBILE_ROOT, handler: handlePage },
+    { kind: 'exact', path: MOBILE_BUNDLE_URL, handler: handleBundle },
+    { kind: 'exact', path: MOBILE_MANIFEST_URL, handler: handleManifest },
+    { kind: 'exact', path: MOBILE_WORKER_URL, handler: handleWorker },
+    { kind: 'exact', path: MOBILE_OFFLINE_URL, handler: handleOffline },
+    { kind: 'exact', path: '/m/apple-touch-icon.png', handler: makeIconHandler('apple-touch-icon.png') },
+    { kind: 'exact', path: '/m/icon-192.png', handler: makeIconHandler('mobile-icon-192.png') },
+    { kind: 'exact', path: '/m/icon-512.png', handler: makeIconHandler('mobile-icon-512.png') },
   ]
 }

package/src/mount-once.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+
+const MOUNTED = Symbol.for('dsh-web-ui.mounted-plugins')
+
+interface MountRegistry {
+  [MOUNTED]?: Set<string>
+}
+
+function mountedSet(): Set<string> {
+  const registry = globalThis as MountRegistry
+  return (registry[MOUNTED] ??= new Set())
+}
+
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
+  return ((...args: unknown[]) => {
+    const mounted = mountedSet()
+    if (mounted.has(packageName)) return
+    mounted.add(packageName)
+    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
+    ctx?.effect?.(() => () => {
+      mounted.delete(packageName)
+    })
+    return fn(...args)
+  }) as T
+}

package/src/pairing-access.ts

@@ -0,0 +1,36 @@
+/**
+ * Optional cordis service other host plugins can ctx.get without taking a
+ * package dependency: a live paired-device cookie is an allow path on
+ * routes that sit outside /api (and therefore outside api/gate).
+ */
+import type { IncomingMessage } from 'node:http'
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+/** Named lookup key sibling plugins pass to ctx.get. */
+export const REMOTE_WEB_UI_PAIRING = 'remoteWebUiPairing'
+
+/**
+ * Pairing identity for one HTTP request. Structural: consumers must not
+ * import this class, only the method shape.
+ */
+export class RemoteWebUiPairing extends Service {
+  /**
+   * @param ctx - host plugin context.
+   * @param check - live cookie + session predicate (re-read per request).
+   */
+  constructor(
+    ctx: Context,
+    private readonly check: (request: IncomingMessage) => boolean,
+  ) {
+    super(ctx, REMOTE_WEB_UI_PAIRING)
+  }
+
+  /**
+   * Whether the request carries a live paired-device cookie.
+   * @param request - the incoming HTTP request.
+   * @returns true when the session is live and was refreshed.
+   */
+  isPairedDevice(request: IncomingMessage): boolean {
+    return this.check(request)
+  }
+}