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

package/lib/types/routes.d.ts

@@ -9,6 +9,7 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import { z } from 'zod';
 import { type PairingService, type PairingSnapshot } from './pairing.ts';
 /**
  * Browser-trust fence for the /api/pair routes, mirroring the connection
@@ -43,6 +44,22 @@ export declare const PAIR_PATHS: {
     readonly status: "/api/pair/status";
     readonly events: "/api/pair/events";
 };
+/**
+ * /api/pair request payload contracts. Each POST endpoint validates its body
+ * against one of these instead of reaching into a hand-parsed object: the
+ * control-plane endpoints that carry no meaningful payload use the permissive
+ * pairActionPayloadSchema so their smoke calls keep working unchanged, while
+ * issue/accept enforce their optional/required fields. Unknown (extra) keys
+ * are tolerated exactly as the previous manual reads ignored them.
+ */
+export declare const issuePayloadSchema: z.ZodObject<{
+    workspaceId: z.ZodOptional<z.ZodString>;
+    address: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const acceptPayloadSchema: z.ZodObject<{
+    token: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export declare const pairActionPayloadSchema: z.ZodObject<{}, z.core.$loose>;
 /** The SSE fan-out for desktop panel status. */
 export declare class PairingEventsStream {
     private readonly streams;

package/lib/types/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAGhG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6BtG;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOxE;AAKD,8CAA8C;AAC9C,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAA;AAiCV,gDAAgD;AAChD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;OAEG;gBACS,OAAO,EAAE,cAAc;IAInC,4DAA4D;IAC5D,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAiBrD,kEAAkE;IAClE,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAYrC,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,OAAO,EAAE,cAAc,CAAA;IACvB,0EAA0E;IAC1E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,QAAQ,EAAE,CAgK3D"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAA;AACrC,OAAO,EAA0B,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAGhG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6BtG;AAKD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOxE;AAKD,8CAA8C;AAC9C,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAA;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAA;AACF,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AACF,eAAO,MAAM,uBAAuB,gCAA6B,CAAA;AA4CjE,gDAAgD;AAChD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;OAEG;gBACS,OAAO,EAAE,cAAc;IAInC,4DAA4D;IAC5D,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAiBrD,kEAAkE;IAClE,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAYrC,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,OAAO,EAAE,cAAc,CAAA;IACvB,0EAA0E;IAC1E,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,QAAQ,EAAE,CA4K3D"}

package/lib/types/routes.js

@@ -7,6 +7,7 @@
  * cookie set on accept is the device identity the api/gate listener checks
  * on every other /api request.
  */
+import { z } from 'zod';
 import { UnknownLanAddressError } from "./pairing.js";
 import { isLoopbackClient, readCookie } from "./gate.js";
 /**
@@ -90,6 +91,32 @@ export const PAIR_PATHS = {
     status: '/api/pair/status',
     events: '/api/pair/events',
 };
+/**
+ * /api/pair request payload contracts. Each POST endpoint validates its body
+ * against one of these instead of reaching into a hand-parsed object: the
+ * control-plane endpoints that carry no meaningful payload use the permissive
+ * pairActionPayloadSchema so their smoke calls keep working unchanged, while
+ * issue/accept enforce their optional/required fields. Unknown (extra) keys
+ * are tolerated exactly as the previous manual reads ignored them.
+ */
+export const issuePayloadSchema = z.object({
+    workspaceId: z.string().min(1).optional(),
+    address: z.string().min(1).optional(),
+});
+export const acceptPayloadSchema = z.object({
+    token: z.string().default(''),
+});
+export const pairActionPayloadSchema = z.object({}).passthrough();
+/**
+ * Parse a pair request body through schema. A missing/empty or non-object
+ * body is treated as an empty object (the same way the previous manual reads
+ * yielded absent fields), and a value that fails the schema returns
+ * `undefined` so the caller can answer with the existing error shape.
+ */
+function parsePairPayload(schema, body) {
+    const result = schema.safeParse(body ?? {});
+    return result.success ? result.data : undefined;
+}
 /** One JSON response. */
 function writeJson(res, status, body) {
     const payload = JSON.stringify(body);
@@ -205,12 +232,12 @@ export function makeRoutes(deps) {
             return;
         }
         const body = await readJsonBody(req);
-        const workspaceId = body === undefined || typeof body.workspaceId !== 'string' || body.workspaceId === ''
-            ? undefined
-            : body.workspaceId;
-        const address = body === undefined || typeof body.address !== 'string' || body.address === ''
-            ? undefined
-            : body.address;
+        const payload = parsePairPayload(issuePayloadSchema, body);
+        if (payload === undefined) {
+            writeJson(res, 400, { ok: false, code: 'bad-payload' });
+            return;
+        }
+        const { workspaceId, address } = payload;
         try {
             const { token, expiresAt } = service.issue(workspaceId, address);
             // The default base is the public (tunneled) URL when configured — a
@@ -255,8 +282,12 @@ export function makeRoutes(deps) {
             return;
         }
         const body = await readJsonBody(req);
-        const token = typeof body?.token === 'string' ? body.token : '';
-        const result = service.accept(token);
+        const payload = parsePairPayload(acceptPayloadSchema, body);
+        if (payload === undefined) {
+            writeJson(res, 400, { ok: false, code: 'bad-payload' });
+            return;
+        }
+        const result = service.accept(payload.token);
         if (!result.ok) {
             writeJson(res, result.code === 'used' ? 409 : 404, { ok: false, code: result.code });
             return;
@@ -276,7 +307,11 @@ export function makeRoutes(deps) {
             writeJson(res, 403, { ok: false, code: 'forbidden' });
             return;
         }
-        await readJsonBody(req);
+        const body = await readJsonBody(req);
+        if (parsePairPayload(pairActionPayloadSchema, body) === undefined) {
+            writeJson(res, 400, { ok: false, code: 'bad-payload' });
+            return;
+        }
         service.stop();
         writeJson(res, 200, { ok: true });
     };
@@ -287,7 +322,11 @@ export function makeRoutes(deps) {
             writeJson(res, 403, { ok: false, code: 'forbidden' });
             return;
         }
-        await readJsonBody(req);
+        const body = await readJsonBody(req);
+        if (parsePairPayload(pairActionPayloadSchema, body) === undefined) {
+            writeJson(res, 400, { ok: false, code: 'bad-payload' });
+            return;
+        }
         const deviceId = readCookie(req.headers.cookie, service.config.cookieName);
         if (deviceId === undefined || !service.heartbeat(deviceId)) {
             writeJson(res, 401, { ok: false, code: 'unpaired' });

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.14",
+  "version": "0.1.15",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/PluginSettingsCard.tsx

@@ -1,25 +1,44 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/PluginSettingsCard.tsx. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
- * Shared chrome for the plugin settings card: a disclosure header naming the
- * plugin and what its settings govern, the controls inside, and the save that
- * writes them. Renders nothing while the namespace is unavailable — a
+ * Family-shared chrome for plugin settings cards: a disclosure header naming
+ * the plugin and what its settings govern, the controls inside, and the save
+ * that writes them. Renders nothing while the namespace is unavailable — a
  * deployment that does not compose the owning plugin should show no trace of
- * it. Mirrors the official ui-plugin-config PluginCard in a self-contained
- * slice (this package must not depend on a sibling UI package).
+ * it. Inlined into each consumer's client bundle; mirrors the official
+ * ui-plugin-config PluginCard in a self-contained slice.
  */
 
 import { useState, type ReactNode } from 'react'
 import type { CardShell } from './settings-form.ts'
-import type { SettingsCardKey } from './locales.ts'
 import css from './settings-card.module.css'
 
+/** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
+export const CARD_COPY_KEYS = [
+  'settings.collapse',
+  'settings.expand',
+  'settings.notExposed',
+  'settings.unsaved',
+  'settings.readOnly',
+  'settings.saveFailed',
+  'settings.discard',
+  'settings.save',
+  'settings.saving',
+] as const
+
+/** Copy key the card chrome itself reads. */
+export type CardCopyKey = (typeof CARD_COPY_KEYS)[number]
+
+/** Key domain for the plugin's own copy (inferred per consumer). */
+export type SettingsCardKey<TKey extends string = string> = TKey | CardCopyKey
+
 /** Card chrome shared by every plugin settings card. */
-export interface PluginSettingsCardProps {
+export interface PluginSettingsCardProps<TKey extends string = string> {
   /** Locale reader for this card's copy. */
-  t: (key: SettingsCardKey) => string
+  t: (key: SettingsCardKey<TKey>, params?: Record<string, string | number>) => string
   /** Locale key of the plugin's name. */
-  titleKey: SettingsCardKey
+  titleKey: TKey
   /** Locale key of the line describing what this plugin's settings govern. */
-  descriptionKey: SettingsCardKey
+  descriptionKey: TKey
   /** The card's form state: availability, writability, and what a save would do. */
   state: CardShell
   /** Write every staged edit. */
@@ -35,11 +54,12 @@ export interface PluginSettingsCardProps {
  * @param props - the plugin's copy keys, its form state, and its controls.
  * @returns the card, or nothing while the namespace is still loading.
  */
-export function PluginSettingsCard(props: PluginSettingsCardProps) {
+export function PluginSettingsCard<TKey extends string = string>(props: PluginSettingsCardProps<TKey>) {
   const [open, setOpen] = useState(false)
   const { state } = props
   if (!state.available) return null
   const title = props.t(props.titleKey)
+  const description = props.t(props.descriptionKey)
   const blocked = !state.dirty || state.invalid || state.saving
   const cardClass = open ? `${css.cardOpen} ${css.card}` : css.card
   // The namespace exists but the Host does not serve it to this client (the
@@ -57,8 +77,8 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
           onClick={() => { setOpen(!open) }}
         >
           <span className={css.headText}>
-            <span className={css.name}>{title}</span>
-            <span className={css.description}>{props.t(props.descriptionKey)}</span>
+            <span className={css.name} title={title}>{title}</span>
+            <span className={css.description} title={description}>{description}</span>
           </span>
           <svg
             width="14"
@@ -94,10 +114,10 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
         onClick={() => { setOpen(!open) }}
       >
         <span className={css.headText}>
-          <span className={css.name}>{title}</span>
-          <span className={css.description}>{props.t(props.descriptionKey)}</span>
+          <span className={css.name} title={title}>{title}</span>
+          <span className={css.description} title={description}>{description}</span>
         </span>
-        {state.dirty ? <span className={css.pending}>{props.t('settings.unsaved')}</span> : null}
+        {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
         <svg
           width="14"
           height="14"
@@ -259,4 +279,50 @@ export function BooleanField(props: FieldProps & {
       <p className={css.hint}>{props.hint}</p>
     </div>
   )
-}
+}
+
+/** A staged enumerated field rendered as a select. */
+export function ChoiceField(props: FieldProps & {
+  /** Copy for the inherit option (draft text is the empty string). */
+  inheritLabel: string
+  /** Choices rendered in order; `value` is the draft/stored text. */
+  choices: ReadonlyArray<{ value: string; label: string }>
+}) {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden
+          ? (
+            <span className={css.badges}>
+              <span className={css.badge}>{props.overriddenLabel}</span>
+              <button
+                type="button"
+                className={css.reset}
+                disabled={props.disabled}
+                onClick={props.onReset}
+              >
+                {props.resetLabel}
+              </button>
+            </span>
+          )
+          : null}
+      </div>
+      <select
+        id={props.id}
+        className={css.select}
+        value={props.text}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      >
+        <option value="">{props.inheritLabel}</option>
+        {props.choices.map(choice => (
+          <option key={choice.value} value={choice.value}>{choice.label}</option>
+        ))}
+      </select>
+      <p className={props.invalid ? css.invalid : css.hint}>
+        {props.invalid ? props.invalidLabel : props.hint}
+      </p>
+    </div>
+  )
+}

package/src/client/settings-card.module.css

@@ -1,3 +1,4 @@
+/* Generated by scripts/sync-shared.mjs from shared/client/settings/settings-card.module.css. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs". */
 /* Plugin settings card chrome + staged form fields.
  * Aligned with the official ui-settings-plugins PluginCard / fields CSS:
  * same semantic tokens, radius, typography and states so family cards read
@@ -229,6 +230,11 @@
   outline-offset: 2px;
 }
 
+.reset:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: 2px;
+}
+
 .input,
 .select {
   border: 1px solid var(--dsw-alias-border-l2);

package/src/client/settings-form.ts

@@ -1,10 +1,11 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 
 import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -90,8 +91,17 @@ interface PlannedWrite {
   run: (() => Promise<boolean>) | undefined
 }
 
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export function numberField(field: string): FieldSpec {
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+  /** The accepted value must be a whole number. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
   return {
     field,
     format: value => typeof value === 'number' ? String(value) : '',
@@ -99,7 +109,10 @@ export function numberField(field: string): FieldSpec {
       const trimmed = text.trim()
       if (trimmed === '') return { kind: 'clear' }
       const parsed = Number(trimmed)
-      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
     },
   }
 }
@@ -122,13 +135,27 @@ export function booleanField(field: string): FieldSpec {
     field,
     format: value => typeof value === 'boolean' ? String(value) : '',
     parse: (text) => {
-      if (text === 'true') return { kind: 'set', value: true }
-      if (text === 'false') return { kind: 'set', value: false }
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
       return undefined
     },
   }
 }
 
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *
@@ -215,6 +242,9 @@ export class CardForm<T> {
     const plan = this.plan()
     const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
     if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    // Snapshot the fields this save writes, so edits staged while it is in
+    // flight survive: only the staged keys this save actually wrote are cleared.
+    const fields = new Set(plan.map(item => item.field))
     this.saving = true
     this.failed = false
     this.publish()
@@ -222,7 +252,9 @@ export class CardForm<T> {
     for (const write of writes) {
       landed = await write() && landed
     }
-    if (landed) this.staged.clear()
+    if (landed) {
+      for (const field of fields) this.staged.delete(field)
+    }
     this.saving = false
     this.failed = !landed
     this.publish()

package/src/mobile/mux.test.ts

@@ -80,8 +80,9 @@ describe('MuxClient polling fallback', () => {
     await vi.advanceTimersByTimeAsync(400)
     expect(pollLatest).not.toHaveBeenCalled()
 
-    // Past the stall threshold the first poll runs and emits seq 0.
-    await vi.advanceTimersByTimeAsync(700) // 1100ms total -> first stall-checker tick
+    // The single tick (400 ms) crosses the 800 ms stall threshold at 1200 ms:
+    // the same tick then runs the first poll and emits seq 0.
+    await vi.advanceTimersByTimeAsync(800) // 1200ms total -> first stall crossing tick
     expect(pollLatest).toHaveBeenCalledWith('s1')
     expect(frames).toHaveLength(1)
     expect(frames[0]).toMatchObject({ type: 'session/event', sessionId: 's1' })
@@ -104,7 +105,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100) // first poll -> 3 events
+    await vi.advanceTimersByTimeAsync(1200) // first poll -> 3 events
     expect(frames).toHaveLength(3)
 
     await vi.advanceTimersByTimeAsync(400) // second poll -> same page, nothing new
@@ -119,7 +120,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalled()
 
     client.observe(undefined)
@@ -136,7 +137,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalled()
 
     client.stop()
@@ -156,7 +157,7 @@ describe('MuxClient polling fallback', () => {
     client.observe('s1')
 
     // Stall into polling.
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalledTimes(1)
 
     // A live mux frame proves SSE delivers again -> fallback stops.
@@ -169,4 +170,81 @@ describe('MuxClient polling fallback', () => {
     expect(live[0]).toMatchObject({ type: 'session/subscribed', sessionId: 's1' })
     client.stop()
   })
+
+  it('drives the whole lifecycle on a single scheduler tick (one interval)', async () => {
+    const { factory } = makeSources()
+    const setIntervalSpy = vi.spyOn(globalThis, 'setInterval')
+    try {
+      const pages = [pageOf([0]), pageOf([0, 1])]
+      const pollLatest = vi.fn(async (_sessionId: string) => pages.shift() ?? pageOf([]))
+      const client = new MuxClient('/m/api/events.mux', {
+        sourceFactory: factory,
+        pollLatest,
+        stallThresholdMs: 1500,
+        pollIntervalMs: 2000,
+      })
+      client.start()
+      client.observe('s1')
+
+      // Exactly one interval is ever created: the single tick scheduler.
+      expect(setIntervalSpy).toHaveBeenCalledTimes(1)
+
+      // The tick fires below the stall threshold without polling.
+      await vi.advanceTimersByTimeAsync(1000)
+      expect(pollLatest).not.toHaveBeenCalled()
+
+      // The same interval arms the fallback once silence passes the threshold
+      // (tick at 2000 crosses 1500) and runs the first poll immediately.
+      await vi.advanceTimersByTimeAsync(1100) // 2100ms total
+      expect(pollLatest).toHaveBeenCalledTimes(1)
+      expect(setIntervalSpy).toHaveBeenCalledTimes(1) // still one timer
+
+      // Subsequent polls ride the same tick at the poll cadence (2000 ms).
+      await vi.advanceTimersByTimeAsync(2000)
+      expect(pollLatest).toHaveBeenCalledTimes(2)
+      client.stop()
+    } finally {
+      setIntervalSpy.mockRestore()
+    }
+  })
+
+  it('paces polls on the tick only after the stall phase ends', async () => {
+    const { factory } = makeSources()
+    const pages = [pageOf([0]), pageOf([0, 1]), pageOf([0, 1, 2]), pageOf([0, 1, 2, 3])]
+    const pollLatest = vi.fn(async (_sessionId: string) => pages.shift() ?? pageOf([]))
+    const client = new MuxClient('/m/api/events.mux', {
+      sourceFactory: factory,
+      pollLatest,
+      stallThresholdMs: 800,
+      pollIntervalMs: 400,
+    })
+    client.start()
+    client.observe('s1')
+
+    // At 1200 ms the stall threshold is crossed on this single 400 ms tick.
+    await vi.advanceTimersByTimeAsync(1200)
+    expect(pollLatest).toHaveBeenCalledTimes(1)
+
+    // Each subsequent 400 ms tick is a poll, matching the poll cadence.
+    await vi.advanceTimersByTimeAsync(400)
+    await vi.advanceTimersByTimeAsync(400)
+    await vi.advanceTimersByTimeAsync(400)
+    expect(pollLatest).toHaveBeenCalledTimes(4)
+    client.stop()
+  })
+
+  it('observe() already in the stall window starts the single-tick poller immediately', async () => {
+    const { factory } = makeSources()
+    const pollLatest = vi.fn(async (_sessionId: string) => pageOf([0]))
+    const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory))
+    client.start()
+    // Advance well past the stall threshold while nothing is observed.
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(pollLatest).not.toHaveBeenCalled()
+
+    // Observing a session now is already in the stall window: poll right away.
+    client.observe('s1')
+    expect(pollLatest).toHaveBeenCalledTimes(1)
+    client.stop()
+  })
 })

package/src/mobile/mux.ts

@@ -66,6 +66,12 @@ type SessionEventFrame = Extract<MuxFrame, { type: 'session/event' }>
 
 const DEFAULT_POLL_INTERVAL_MS = 3000
 const DEFAULT_STALL_THRESHOLD_MS = 12000
+/**
+ * Stall-check granularity: the single scheduler tick runs at least this
+ * often so fallback arms within a second of the stall threshold passing,
+ * while the poll cadence itself stays {@link MuxClientOptions.pollIntervalMs}.
+ */
+const STALL_CHECK_MS = 1000
 /** Poll window: enough recent events to cover a few seconds of agent output. */
 const DEFAULT_POLL_PAGE_SIZE = 50
 
@@ -98,9 +104,11 @@ export class MuxClient {
   private sseAlive = false
   /** Per-session highest event seq already emitted, for poll dedup. */
   private readonly pollWatermark = new Map<string, number>()
-  private stallTimer: ReturnType<typeof setInterval> | undefined
-  private pollTimer: ReturnType<typeof setInterval> | undefined
+  /** Single scheduler tick: both the stall check and the poll cadence ride this one interval. */
+  private tickTimer: ReturnType<typeof setInterval> | undefined
   private polling = false
+  /** Epoch ms of the next due poll while polling (kept on the same tick timer). */
+  private nextPollAt = 0
 
   /**
    * @param url - the mobile events endpoint (browser-relative).
@@ -120,16 +128,17 @@ export class MuxClient {
     this.stopped = false
     this.lastDataAt = this.now()
     if (this.source === undefined) this.connect()
-    this.startStallChecker()
+    this.startTick()
   }
 
   /** Close for good. */
   stop(): void {
     this.stopped = true
-    this.stopStallChecker()
+    this.stopTick()
     this.stopPolling()
     this.closeSource()
     this.observeSessionId = undefined
+    this.nextPollAt = 0
   }
 
   /** Subscribe to validated frames; returns an unsubscribe function. */
@@ -176,40 +185,52 @@ export class MuxClient {
     }
   }
 
-  private startStallChecker(): void {
-    this.stopStallChecker()
-    this.stallTimer = setInterval(() => {
-      if (this.stopped) return
-      if (this.observeSessionId === undefined) return
-      if (this.polling) return
-      // A live SSE channel only goes silent while the agent idles; never
-      // poll against it. Fallback arms again only via onerror or a stream
-      // that has never delivered.
-      if (this.sseAlive) return
-      if ((this.now() - this.lastDataAt) > this.stallThresholdMs) this.startPolling()
-    }, 1000)
+  /**
+   * The single scheduler tick is the only interval this client owns. One
+   * timer (at the finer of the stall-check and poll cadences) both arms the
+   * polling fallback once the stall threshold passes and drives each poll at
+   * {@link MuxClientOptions.pollIntervalMs} — one timer instead of two.
+   */
+  private startTick(): void {
+    if (this.tickTimer !== undefined) return
+    const cadence = Math.min(this.pollIntervalMs, STALL_CHECK_MS)
+    this.tickTimer = setInterval(() => { this.tick() }, cadence)
+  }
+
+  private stopTick(): void {
+    if (this.tickTimer !== undefined) {
+      clearInterval(this.tickTimer)
+      this.tickTimer = undefined
+    }
   }
 
-  private stopStallChecker(): void {
-    if (this.stallTimer !== undefined) {
-      clearInterval(this.stallTimer)
-      this.stallTimer = undefined
+  private tick(): void {
+    if (this.stopped) return
+    if (this.observeSessionId === undefined) return
+    if (this.polling) {
+      // The stall phase has ended; the same tick now paces the polls.
+      if (this.now() >= this.nextPollAt) {
+        this.nextPollAt = this.now() + this.pollIntervalMs
+        void this.pollTick()
+      }
+      return
     }
+    // A live SSE channel only goes silent while the agent idles; never poll
+    // against it. Fallback arms again only via onerror or a stream that has
+    // never delivered.
+    if (this.sseAlive) return
+    if ((this.now() - this.lastDataAt) > this.stallThresholdMs) this.startPolling()
   }
 
   private startPolling(): void {
     if (this.polling || this.stopped) return
     this.polling = true
+    this.nextPollAt = this.now() + this.pollIntervalMs
     void this.pollTick()
-    this.pollTimer = setInterval(() => { void this.pollTick() }, this.pollIntervalMs)
   }
 
   private stopPolling(): void {
     this.polling = false
-    if (this.pollTimer !== undefined) {
-      clearInterval(this.pollTimer)
-      this.pollTimer = undefined
-    }
   }
 
   /**