@linxin666/dsh-remote-web-ui 0.1.12 → 0.1.14

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

@@ -3,7 +3,7 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import type { SessionModels } from '@deepseek-ai/dsh-host-apiproxy/api/sessions'
-import { ChatView } from './ChatView.tsx'
+import { ChatView, MAX_TAIL_BUFFER_EVENTS } from './ChatView.tsx'
 import { type SessionView } from './App.tsx'
 import type { HistoryPage } from '../api.ts'
 import type { WireEvent } from '../messages.ts'
@@ -11,6 +11,7 @@ import type { WireEvent } from '../messages.ts'
 // The api module is fully mocked; App.tsx's history wrapper is overridden to
 // feed fixed history pages, its pure helpers (errorText / formatTime) stay real.
 vi.mock('../api.ts', () => ({
+  fetchMobilePreferences: vi.fn(),
   models: vi.fn(),
   selectModel: vi.fn(),
   sendCommand: vi.fn(),
@@ -23,8 +24,8 @@ vi.mock('./App.tsx', async importOriginal => {
     prompt: vi.fn(async () => {}),
   }
 })
-import { models, selectModel, sendCommand } from '../api.ts'
-import { loadHistory } from './App.tsx'
+import { fetchMobilePreferences, models, selectModel, sendCommand } from '../api.ts'
+import { loadHistory, prompt } from './App.tsx'
 
 const session: SessionView = {
   sessionId: 's-1',
@@ -67,12 +68,16 @@ function turnEvents(): Array<{ event: WireEvent }> {
   ]
 }
 
+const fetchMobilePreferencesMock = vi.mocked(fetchMobilePreferences)
 const modelsMock = vi.mocked(models)
 const selectModelMock = vi.mocked(selectModel)
 const sendCommandMock = vi.mocked(sendCommand)
 const loadHistoryMock = vi.mocked(loadHistory)
+const promptMock = vi.mocked(prompt)
 
 beforeEach(() => {
+  fetchMobilePreferencesMock.mockResolvedValue({ mobileEnterToSend: true })
+  promptMock.mockResolvedValue(undefined)
   modelsMock.mockResolvedValue({
     current: { provider: 'fx', model: 'fx-1' },
     routable: true,
@@ -95,6 +100,7 @@ beforeEach(() => {
 afterEach(() => {
   cleanup()
   vi.clearAllMocks()
+  vi.restoreAllMocks()
 })
 
 describe('ChatView message folds', () => {
@@ -187,6 +193,115 @@ describe('ChatView message folds', () => {
   })
 })
 
+describe('ChatView initial-load race', () => {
+  /** Minimal mux stand-in: captures the ChatView's frame listener for hand-off. */
+  class FakeMux {
+    listeners = new Set<(frame: unknown) => void>()
+    onFrame(listener: (frame: unknown) => void): () => void {
+      this.listeners.add(listener)
+      return () => { this.listeners.delete(listener) }
+    }
+    emit(frame: unknown): void {
+      for (const listener of this.listeners) listener(frame)
+    }
+  }
+
+  it('keeps live events that arrive while the tail page is still loading', async () => {
+    let resolveHistory: (page: HistoryPage) => void = () => {}
+    loadHistoryMock.mockReturnValue(new Promise<HistoryPage>((resolve) => { resolveHistory = resolve }))
+    const mux = new FakeMux()
+    render(<ChatView session={session} mux={mux as never} onBack={() => {}} />)
+
+    // A live turn starts before the snapshot resolves: chunk, tool call, final.
+    await act(async () => {
+      mux.emit({ type: 'session/event', sessionId: 's-1', event: makeEntry('assistant/chunk', { turn: 1, step: 0, chunk: { type: 'text-delta', text: '正在' } }, 6).event })
+      mux.emit({ type: 'session/event', sessionId: 's-1', event: makeEntry('tool/call', { turn: 1, step: 0, callId: 'c9', name: 'bash', arguments: '{"cmd":"ls"}' }, 7).event })
+      mux.emit({ type: 'session/event', sessionId: 's-1', event: makeEntry('assistant/message', { turn: 1, step: 0, message: { id: 'a-9', role: 'assistant', content: [{ type: 'text', text: '实时新消息' }] } }, 8).event })
+    })
+    // The snapshot predates those events; resolving it must not drop them.
+    await act(async () => { resolveHistory(historyPage(turnEvents())) })
+
+    expect(await screen.findByText('实时新消息')).toBeTruthy()
+    // The history turn's tool disclosure plus the live one both render.
+    expect((await screen.findAllByRole('button', { name: /工具/ })).length).toBe(2)
+  })
+
+  it('caps the tail-load live buffer and re-pulls the history tail after an overflow', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    let resolveHistory: (page: HistoryPage) => void = () => {}
+    loadHistoryMock
+      .mockReturnValueOnce(new Promise<HistoryPage>((resolve) => { resolveHistory = resolve }))
+      // The overflow follow-up load resolves a page newer than the buffered burst.
+      .mockResolvedValueOnce(historyPage([
+        makeEntry('assistant/message', {
+          id: 'a-refetch',
+          role: 'assistant',
+          content: [{ type: 'text', text: '补拉恢复' }],
+        }, 700),
+      ]))
+    const mux = new FakeMux()
+    render(<ChatView session={session} mux={mux as never} onBack={() => {}} />)
+
+    // 501 live final messages arrive before the snapshot resolves: the first one
+    // is dropped by the 500-event cap, the remaining 500 stay buffered.
+    await act(async () => {
+      for (let index = 0; index <= MAX_TAIL_BUFFER_EVENTS; index++) {
+        mux.emit({
+          type: 'session/event',
+          sessionId: 's-1',
+          event: makeEntry('assistant/message', {
+            id: `a-burst-${index}`,
+            role: 'assistant',
+            content: [{ type: 'text', text: `突发消息 ${index}` }],
+          }, 100 + index).event,
+        })
+      }
+    })
+
+    // The overflow is logged exactly once, and the cap mentions the limit.
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain(String(MAX_TAIL_BUFFER_EVENTS))
+
+    await act(async () => { resolveHistory(historyPage(turnEvents())) })
+
+    // The capped buffer keeps the render bounded: the dropped oldest burst
+    // message is gone, while the newest buffered one survives the snapshot fold.
+    expect(await screen.findByText('突发消息 500')).toBeTruthy()
+    expect(screen.queryByText('突发消息 0')).toBeNull()
+
+    // The overflow triggered exactly one follow-up tail load, still carrying the
+    // same abort signal as the initial load.
+    await waitFor(() => { expect(loadHistoryMock).toHaveBeenCalledTimes(2) })
+    expect(loadHistoryMock.mock.calls[1]?.[0]).toBe('s-1')
+    expect(loadHistoryMock.mock.calls[1]?.[1]).toBeUndefined()
+    expect(loadHistoryMock.mock.calls[1]?.[2]).toBeInstanceOf(AbortSignal)
+    expect(loadHistoryMock.mock.calls[1]?.[2]).toBe(loadHistoryMock.mock.calls[0]?.[2])
+
+    // The re-pulled page folds into the already-rendered messages.
+    expect(await screen.findByText('补拉恢复')).toBeTruthy()
+  })
+
+  it('passes an AbortSignal to loadHistory and aborts it on unmount', async () => {
+    let capturedSignal: AbortSignal | undefined
+    loadHistoryMock.mockImplementation((_sessionId, _beforeSeq, signal) => {
+      capturedSignal = signal
+      return Promise.resolve(historyPage(turnEvents()))
+    })
+    const view = render(<ChatView session={session} onBack={() => {}} />)
+
+    expect(await screen.findByText('已完成修改')).toBeTruthy()
+    expect(loadHistoryMock).toHaveBeenCalledTimes(1)
+    expect(loadHistoryMock.mock.calls[0]?.[0]).toBe('s-1')
+    expect(loadHistoryMock.mock.calls[0]?.[1]).toBeUndefined()
+    expect(loadHistoryMock.mock.calls[0]?.[2]).toBeInstanceOf(AbortSignal)
+    expect(capturedSignal).toBeInstanceOf(AbortSignal)
+    expect(capturedSignal?.aborted).toBe(false)
+
+    view.unmount()
+    expect(capturedSignal?.aborted).toBe(true)
+  })
+})
+
 describe('ChatView model sheet', () => {
   it('labels the toolbar chip with the current model and selects a new one', async () => {
     loadHistoryMock.mockResolvedValue(historyPage(turnEvents()))
@@ -241,6 +356,73 @@ describe('ChatView model sheet', () => {
   })
 })
 
+describe('ChatView composer', () => {
+  const inputBox = (): HTMLTextAreaElement => screen.getByRole('textbox') as HTMLTextAreaElement
+
+  /** Dispatch one keydown through the React tree and return the real event. */
+  const pressEnter = (input: HTMLTextAreaElement, shiftKey = false): KeyboardEvent => {
+    const event = new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true, shiftKey })
+    input.dispatchEvent(event)
+    return event
+  }
+
+  it('sends on Enter by default and keeps Shift+Enter inserting a newline', async () => {
+    loadHistoryMock.mockResolvedValue(historyPage(turnEvents()))
+    render(<ChatView session={session} onBack={() => {}} />)
+    await screen.findByText('已完成修改')
+
+    const input = inputBox()
+    expect(input.getAttribute('enterKeyHint')).toBe('send')
+    expect(input.getAttribute('placeholder')).toContain('Enter 发送')
+
+    fireEvent.change(input, { target: { value: '第一行' } })
+    const enter = pressEnter(input)
+    expect(enter.defaultPrevented).toBe(true)
+    await waitFor(() => {
+      expect(promptMock).toHaveBeenCalledWith('s-1', '第一行')
+    })
+
+    // Shift+Enter stays a newline gesture and never sends.
+    promptMock.mockClear()
+    const shifted = pressEnter(input, true)
+    expect(shifted.defaultPrevented).toBe(false)
+    expect(promptMock).not.toHaveBeenCalled()
+  })
+
+  it('inserts a newline on Enter and sends only from the button when the preference is false', async () => {
+    fetchMobilePreferencesMock.mockResolvedValue({ mobileEnterToSend: false })
+    loadHistoryMock.mockResolvedValue(historyPage(turnEvents()))
+    render(<ChatView session={session} onBack={() => {}} />)
+    await screen.findByText('已完成修改')
+
+    const input = inputBox()
+    await waitFor(() => { expect(input.getAttribute('enterKeyHint')).toBe('enter') })
+    expect(input.getAttribute('placeholder')).not.toContain('Enter 发送')
+
+    // The handler no longer prevents Enter, so the browser's default inserts
+    // a newline (emulated here through the controlled value) and no send fires.
+    fireEvent.change(input, { target: { value: '第一行' } })
+    const enter = pressEnter(input)
+    expect(enter.defaultPrevented).toBe(false)
+    fireEvent.change(input, { target: { value: '第一行\n' } })
+    expect(input.value).toBe('第一行\n')
+    expect(promptMock).not.toHaveBeenCalled()
+
+    // The send button still sends the full multi-line draft.
+    fireEvent.change(input, { target: { value: '第一行\n第二行' } })
+    fireEvent.click(screen.getByRole('button', { name: '发送' }))
+    await waitFor(() => {
+      expect(promptMock).toHaveBeenCalledWith('s-1', '第一行\n第二行')
+    })
+
+    // Shift+Enter keeps inserting a newline in either mode.
+    promptMock.mockClear()
+    const shifted = pressEnter(input, true)
+    expect(shifted.defaultPrevented).toBe(false)
+    expect(promptMock).not.toHaveBeenCalled()
+  })
+})
+
 describe('ChatView scrolling', () => {
   // Controllable scrollHeight + a write log for the chat-scroll element. The
   // accessors live on Element.prototype, so patching them here lets every

package/src/mobile/views/ChatView.tsx

@@ -16,7 +16,7 @@ import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api/events'
 import type { SessionModels } from '@deepseek-ai/dsh-host-apiproxy/api/sessions'
 import { loadHistory, prompt, type SessionView } from './App.tsx'
 import { errorText, formatTime, staleHostHint } from './App.tsx'
-import { models, selectModel, sendCommand } from '../api.ts'
+import { fetchMobilePreferences, models, selectModel, sendCommand } from '../api.ts'
 import { foldEvents, type RenderMessage, type ToolCallInfo, type WireEvent } from '../messages.ts'
 import { MuxClient } from '../mux.ts'
 import { ThemeToggle } from '../theme-toggle.tsx'
@@ -29,6 +29,13 @@ export interface ChatViewProps {
   onBack(): void
 }
 
+/**
+ * Hard cap on live events buffered while the initial history tail page is in
+ * flight. Beyond this the oldest buffered event is dropped and a follow-up
+ * history tail re-pull closes the seam.
+ */
+export const MAX_TAIL_BUFFER_EVENTS = 500
+
 /** Extract the raw event from one history entry (the fold consumes events only). */
 function eventOf(entry: { event: WireEvent }): WireEvent {
   return entry.event
@@ -101,6 +108,18 @@ export function ChatView({ session, mux, onBack }: ChatViewProps) {
   const [sending, setSending] = useState(false)
   const scrollRef = useRef<HTMLDivElement | undefined>(undefined)
   const pendingRef = useRef(false)
+  /**
+   * True while the initial tail page is in flight. Live events arriving in
+   * that window go to {@link liveBufferRef} instead of the message list: the
+   * tail load replaces the list wholesale, so a directly folded event would
+   * flash once, be discarded by the snapshot, and then be skipped forever by
+   * the seq watermark.
+   */
+  const tailLoadingRef = useRef(true)
+  /** Live session events buffered while the initial tail page loads. */
+  const liveBufferRef = useRef<WireEvent[]>([])
+  /** True once the live buffer hit its cap (oldest events were dropped). */
+  const liveBufferOverflowRef = useRef(false)
 
   /** The session's permission select (absent = capability not composed). */
   const [permissions, setPermissions] = useState<PermissionSelectValue | undefined>(undefined)
@@ -108,17 +127,49 @@ export function ChatView({ session, mux, onBack }: ChatViewProps) {
   const [currentModel, setCurrentModel] = useState<{ provider: string; model: string; reasoningEffort?: string } | undefined>(undefined)
   /** Which bottom sheet is open. */
   const [sheet, setSheet] = useState<'model' | 'permission' | null>(null)
+  /**
+   * Composer preference from the plugin's host settings (default true keeps
+   * the legacy Enter-to-send behavior until the preference loads).
+   */
+  const [mobileEnterToSend, setMobileEnterToSend] = useState(true)
+
+  // Read-only mobile display preferences ride the plugin's local
+  // `/m/api` method; a failure keeps the default (Enter sends).
+  useEffect(() => {
+    let cancelled = false
+    void fetchMobilePreferences().then(
+      (preferences) => {
+        if (!cancelled) setMobileEnterToSend(preferences.mobileEnterToSend !== false)
+      },
+      () => { /* keep the default */ },
+    )
+    return () => { cancelled = true }
+  }, [])
 
   // Tail page on open (content loads only when the session is opened).
   useEffect(() => {
     let cancelled = false
+    const controller = new AbortController()
+    // A stuck history load must not keep the chat empty (or the live buffer
+    // growing) forever: abort it and surface the transport error.
+    const timeout = setTimeout(() => {
+      controller.abort(new DOMException('history load timed out', 'TimeoutError'))
+    }, 15_000)
+    tailLoadingRef.current = true
+    liveBufferRef.current = []
+    liveBufferOverflowRef.current = false
     setLoading(true)
     setError(undefined)
     setMessages([])
-    void loadHistory(session.sessionId).then(
+    void loadHistory(session.sessionId, undefined, controller.signal).then(
       (page) => {
         if (cancelled) return
-        setMessages(foldEvents(page.events.map(eventOf)))
+        // Buffered live events re-fold on top of the snapshot; the watermark
+        // drops any the snapshot already includes, so nothing is lost or doubled.
+        const buffered = liveBufferRef.current
+        liveBufferRef.current = []
+        tailLoadingRef.current = false
+        setMessages(foldEvents(buffered, foldEvents(page.events.map(eventOf))))
         setHasOlder(page.hasMore)
         setLoading(false)
         // The history-tail projection baseline seeds the permission picker.
@@ -126,9 +177,31 @@ export function ChatView({ session, mux, onBack }: ChatViewProps) {
         // plugin (augmentation), so the base SDK map is indexed loosely.
         const projections = page.projections?.values as Record<string, unknown> | undefined
         setPermissions(parsePermissionSelect(projections?.['permissions']))
+        // The buffer overflowed while waiting (oldest events were dropped), so
+        // re-pull the freshest history page to close the gap on top of what is
+        // already rendered. Best-effort: a failure here only logs, it must not
+        // replace the loaded state with an error.
+        if (liveBufferOverflowRef.current) {
+          void loadHistory(session.sessionId, undefined, controller.signal).then(
+            (fresh) => {
+              if (cancelled) return
+              setMessages(previous => foldEvents(fresh.events.map(eventOf), previous))
+              liveBufferOverflowRef.current = false
+            },
+            (reason: unknown) => {
+              if (cancelled) return
+              console.warn('history tail re-pull after live buffer overflow failed', reason)
+            },
+          )
+        }
       },
       (reason: unknown) => {
         if (cancelled) return
+        // Load failed: flush the buffer so the live stream still renders.
+        const buffered = liveBufferRef.current
+        liveBufferRef.current = []
+        tailLoadingRef.current = false
+        if (buffered.length > 0) setMessages(foldEvents(buffered))
         setError(errorText(reason))
         setLoading(false)
       },
@@ -141,7 +214,11 @@ export function ChatView({ session, mux, onBack }: ChatViewProps) {
       },
       () => { /* chip falls back to a plain label */ },
     )
-    return () => { cancelled = true }
+    return () => {
+      cancelled = true
+      clearTimeout(timeout)
+      controller.abort()
+    }
   }, [session.sessionId])
 
   // Live frames: fold session events for this session in as they arrive.
@@ -150,7 +227,24 @@ export function ChatView({ session, mux, onBack }: ChatViewProps) {
     return mux.onFrame((frame: MuxFrame) => {
       if (frame.type === 'session/event') {
         if (frame.sessionId !== session.sessionId) return
-        setMessages(previous => foldEvents([frame.event as WireEvent], previous))
+        const event = frame.event as WireEvent
+        if (tailLoadingRef.current) {
+          if (liveBufferRef.current.length >= MAX_TAIL_BUFFER_EVENTS) {
+            // Bound the tail-load window: drop the oldest buffered event and
+            // remember that a follow-up history re-pull is needed. Warn once
+            // per load, not for every subsequent overflow.
+            liveBufferRef.current.shift()
+            if (!liveBufferOverflowRef.current) {
+              console.warn(
+                `history tail is slow: live buffer reached ${MAX_TAIL_BUFFER_EVENTS} events; oldest buffered events will be re-fetched`,
+              )
+              liveBufferOverflowRef.current = true
+            }
+          }
+          liveBufferRef.current.push(event)
+          return
+        }
+        setMessages(previous => foldEvents([event], previous))
         return
       }
       // Live projection pushes keep the permission picker current.
@@ -277,11 +371,11 @@ export function ChatView({ session, mux, onBack }: ChatViewProps) {
           className="chat-input"
           rows={1}
           value={input}
-          placeholder="输入消息，Enter 发送…"
-          enterKeyHint="send"
+          placeholder={mobileEnterToSend ? '输入消息，Enter 发送…' : '输入消息，Enter 换行，点按钮发送…'}
+          enterKeyHint={mobileEnterToSend ? 'send' : 'enter'}
           onChange={(event) => { setInput(event.target.value) }}
           onKeyDown={(event) => {
-            if (event.key === 'Enter' && !event.shiftKey) {
+            if (mobileEnterToSend && event.key === 'Enter' && !event.shiftKey) {
               event.preventDefault()
               void send()
             }

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

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+/** Mobile workspace landing: roster rendering and QR deep-link selection. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import type { WorkspaceView as WorkspaceRow } from '@deepseek-ai/dsh-host-apiproxy/api/workspace'
+import { mobileWorkspaceTarget } from './App.tsx'
+import { WorkspaceView } from './WorkspaceView.tsx'
+
+vi.mock('../api.ts', () => ({
+  listWorkspaces: vi.fn(),
+}))
+import { listWorkspaces } from '../api.ts'
+
+const listWorkspacesMock = vi.mocked(listWorkspaces)
+const workspaces: WorkspaceRow[] = [
+  {
+    workspaceId: 'ws-1' as never,
+    path: '/tmp/first',
+    title: 'First',
+    sessionIds: [] as never,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  },
+  {
+    workspaceId: 'ws-2' as never,
+    path: '/tmp/second',
+    title: 'Second',
+    sessionIds: [] as never,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  },
+]
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+describe('mobile workspace deep link', () => {
+  it('reads a non-empty workspace target from the query', () => {
+    expect(mobileWorkspaceTarget('?workspace=ws-2')).toBe('ws-2')
+    expect(mobileWorkspaceTarget('?workspace=')).toBeUndefined()
+    expect(mobileWorkspaceTarget('')).toBeUndefined()
+  })
+
+  it('opens the targeted workspace as soon as the roster loads', async () => {
+    listWorkspacesMock.mockResolvedValue(workspaces)
+    const onPick = vi.fn()
+
+    render(<WorkspaceView initialWorkspaceId="ws-2" onPick={onPick} />)
+
+    await waitFor(() => expect(onPick).toHaveBeenCalledWith(workspaces[1]))
+    expect(onPick).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back to the roster when the target no longer exists', async () => {
+    listWorkspacesMock.mockResolvedValue(workspaces)
+    const onPick = vi.fn()
+
+    render(<WorkspaceView initialWorkspaceId="missing" onPick={onPick} />)
+
+    expect(await screen.findByText('First')).toBeTruthy()
+    expect(await screen.findByText('Second')).toBeTruthy()
+    expect(onPick).not.toHaveBeenCalled()
+  })
+})

package/src/mobile/views/WorkspaceView.tsx

@@ -13,6 +13,8 @@ import { ThemeToggle } from '../theme-toggle.tsx'
 
 /** Props for the workspace roster. */
 export interface WorkspaceViewProps {
+  /** Workspace carried by the pairing link; opened after the roster loads. */
+  initialWorkspaceId?: string
   /** Open one workspace's session list. */
   onPick(workspace: WorkspaceRow): void
 }
@@ -22,7 +24,7 @@ export interface WorkspaceViewProps {
  * @param props - the pick action.
  * @returns the roster.
  */
-export function WorkspaceView({ onPick }: WorkspaceViewProps) {
+export function WorkspaceView({ initialWorkspaceId, onPick }: WorkspaceViewProps) {
   const [items, setItems] = useState<WorkspaceRow[] | undefined>(undefined)
   const [error, setError] = useState<string | undefined>(undefined)
 
@@ -31,6 +33,13 @@ export function WorkspaceView({ onPick }: WorkspaceViewProps) {
     void listWorkspaces().then(
       (rows) => {
         if (cancelled) return
+        const target = initialWorkspaceId === undefined
+          ? undefined
+          : rows.find(workspace => workspace.workspaceId === initialWorkspaceId)
+        if (target !== undefined) {
+          onPick(target)
+          return
+        }
         setItems(rows)
       },
       (reason: unknown) => {
@@ -39,7 +48,7 @@ export function WorkspaceView({ onPick }: WorkspaceViewProps) {
       },
     )
     return () => { cancelled = true }
-  }, [])
+  }, [initialWorkspaceId, onPick])
 
   if (error !== undefined) {
     return (

package/src/mobile-api.ts

@@ -40,6 +40,13 @@ const MOBILE_ALLOWLIST = new Set([
   'session.rename',
 ])
 
+/**
+ * Locally answered display-preference method (the phone's read-only
+ * surface preferences; never proxied to the host ApiProxy and never a
+ * settings-domain write).
+ */
+const MOBILE_PREFERENCES_METHOD = 'mobile.preferences'
+
 /** One session.list page (thin phones load incrementally). */
 const SESSION_PAGE_SIZE = 20
 
@@ -69,6 +76,8 @@ export interface MobileApiDeps {
   service: PairingService
   /** The host ApiProxy service (injected by the plugin). */
   apiProxy: ApiProxy
+  /** The resolved mobile composer preference (live per request). */
+  mobileEnterToSend: () => boolean
 }
 
 /** Mobile API route paths. */
@@ -87,7 +96,7 @@ const MOBILE_API_METHOD_PREFIX = `${MOBILE_API_PREFIX}/`
  * @returns the routes to register on webServer.
  */
 export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
-  const { service, apiProxy } = deps
+  const { service, apiProxy, mobileEnterToSend } = deps
 
   /** The phone gate: a live paired-device cookie, or nothing else proceeds. */
   const gateOk = (req: IncomingMessage): boolean => {
@@ -116,7 +125,8 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
       return
     }
     const method = pathname.slice(MOBILE_API_METHOD_PREFIX.length)
-    if (!MOBILE_ALLOWLIST.has(method)) {
+    const local = method === MOBILE_PREFERENCES_METHOD
+    if (!MOBILE_ALLOWLIST.has(method) && !local) {
       writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: `method ${method} is not exposed to the mobile surface` } })
       return
     }
@@ -133,6 +143,14 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
       writeJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'missing rpcId' } })
       return
     }
+    if (local) {
+      writeJson(res, 200, {
+        type: 'server-response',
+        rpcId,
+        result: { ok: true, value: { mobileEnterToSend: mobileEnterToSend() } },
+      })
+      return
+    }
     try {
       const response = await dispatch(apiProxy, method, parsed?.payload, rpcId)
       writeJson(res, 200, response)