@linxin666/dsh-remote-web-ui 0.1.1

package/src/client/RemoteEntry.tsx

@@ -0,0 +1,202 @@
+/**
+ * The sidebar remote-control seat: the phone-icon trigger beside the
+ * settings button plus the pairing panel modal. Owns the panel behavior —
+ * token minting on open, the status SSE subscription, stop/refresh/copy —
+ * and renders the pure {@link RemotePanel} body. Component-local state per
+ * the client stack rules: nothing here survives remounts or crosses
+ * entries.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PairingPhase } from '../pairing.ts'
+import { RemotePanel, type PanelState } from './RemotePanel.tsx'
+import { copyText, issuePair, stopPair, type IssueResponse, type PairStateFrame, type TunnelStatusFrame } from './pair-api.ts'
+import { PhoneIcon } from './PhoneIcon.tsx'
+import css from './remote.module.css'
+
+/** Entry props: the sidebar column state + the standard locale seat. */
+export type RemoteEntryProps = PropsRuntime<'sidebar.remote'> & PropsLocale<'remote'>
+
+/** Apply one status frame onto the current ready state. */
+function mergeFrame(state: PanelState, frame: PairStateFrame): PanelState {
+  if (state.kind !== 'ready') return state
+  return {
+    ...state,
+    phase: frame.phase,
+    deviceCount: frame.deviceCount,
+    onlineCount: frame.onlineCount,
+    ...(frame.tunnel !== undefined ? { tunnel: frame.tunnel as TunnelStatusFrame } : {}),
+  }
+}
+
+/**
+ * Render the remote-control trigger and panel.
+ * @param props - composed slot props (contract in this package).
+ * @returns the entry element tree.
+ */
+export function RemoteEntry({ wide, useWorkspaces, t }: RemoteEntryProps) {
+  const [open, setOpen] = useState(false)
+  const [state, setState] = useState<PanelState>({ kind: 'lan-required' })
+  const [copied, setCopied] = useState(false)
+  const eventSource = useRef<EventSource | undefined>(undefined)
+
+  // The current workspace (the recent-workspace projection the shell's New
+  // Session flow targets) — the deep-link target for the phone.
+  const workspaceId = useWorkspaces(s => s.recentWorkspaceId)
+
+  const closeEventSource = useCallback(() => {
+    eventSource.current?.close()
+    eventSource.current = undefined
+  }, [])
+
+  const mint = useCallback(async (address?: string): Promise<PanelState> => {
+    let result: IssueResponse
+    try {
+      result = await issuePair(workspaceId, address)
+    } catch {
+      // Fetch/network failure: show an explicit state instead of silently
+      // leaving the panel on its initial banner.
+      return { kind: 'unreachable' }
+    }
+    if (!result.ok) {
+      // 403 is the loopback-only fence refusing a LAN origin (the panel is a
+      // desktop control endpoint); 409 means the server never bound 0.0.0.0;
+      // 400 means the requested LAN literal is no longer constructible.
+      if (result.code === 'forbidden') return { kind: 'loopback-required' }
+      if (result.code === 'unknown-address') return { kind: 'unreachable' }
+      return { kind: 'lan-required' }
+    }
+    const publicBaseUrl = result.publicBaseUrl
+    return {
+      kind: 'ready',
+      url: result.url,
+      expiresAt: result.expiresAt,
+      expired: Date.now() > result.expiresAt,
+      phase: 'waiting',
+      deviceCount: 0,
+      onlineCount: 0,
+      // Whether this QR is built on the configured public (tunneled) base.
+      public: publicBaseUrl !== undefined && result.url.startsWith(publicBaseUrl),
+      ...(publicBaseUrl !== undefined ? { publicBaseUrl } : {}),
+      // The issued URL names the requested (or default first) literal; the
+      // public link has no LAN literal, so no radio row is selected then.
+      address: address ?? result.lanAddresses[0] ?? '',
+      lanAddresses: result.lanAddresses,
+    }
+  }, [workspaceId])
+
+  const openPanel = useCallback(async (): Promise<void> => {
+    setOpen(true)
+    const next = await mint()
+    setState(next)
+    // Live status: the desktop panel mirrors the pairing service state. The
+    // stream only makes sense in the ready state — on a failure banner the
+    // events endpoint is unreachable too (loopback fence), so opening it
+    // would just start a doomed reconnect loop.
+    if (next.kind !== 'ready') return
+    const source = new EventSource('/api/pair/events')
+    eventSource.current = source
+    source.onmessage = (event) => {
+      try {
+        const frame = JSON.parse(event.data as string) as PairStateFrame
+        if (frame.type !== 'state') return
+        setState(previous => mergeFrame(previous, frame))
+      } catch {
+        // Malformed frames are dropped; the snapshot on open is authoritative.
+      }
+    }
+  }, [mint])
+
+  const closePanel = useCallback(() => {
+    closeEventSource()
+    setOpen(false)
+  }, [closeEventSource])
+
+  // Expiry flip: one timeout per token lifetime (reset by refresh).
+  useEffect(() => {
+    if (state.kind !== 'ready') return
+    if (state.expired) return
+    const delay = state.expiresAt - Date.now()
+    if (delay <= 0) {
+      setState(previous => previous.kind === 'ready' ? { ...previous, expired: true } : previous)
+      return
+    }
+    const timer = window.setTimeout(() => {
+      setState(previous => previous.kind === 'ready' ? { ...previous, expired: true } : previous)
+    }, delay)
+    return () => { window.clearTimeout(timer) }
+  }, [state])
+
+  // Unmount safety: never leave the stream open.
+  useEffect(() => closeEventSource, [closeEventSource])
+
+  const handleStop = useCallback(() => {
+    // A failed stop request is harmless: the optimistic phase flip below
+    // keeps the UI honest, and the status stream confirms the stopped phase.
+    void stopPair().catch(() => {})
+    // Optimistic fallback; the status stream confirms with the stopped phase.
+    setState(previous => previous.kind === 'ready' ? { ...previous, phase: 'stopped' as PairingPhase } : previous)
+  }, [])
+
+  const handleRefresh = useCallback(() => {
+    void mint().then(setState)
+  }, [mint])
+
+  /** Re-mint against another LAN literal (multi-homed machines). */
+  const handlePickAddress = useCallback((address: string) => {
+    void mint(address).then(setState)
+  }, [mint])
+
+  /** Re-mint against the configured public (tunneled) base. */
+  const handlePickPublic = useCallback(() => {
+    void mint().then(setState)
+  }, [mint])
+
+  const handleCopy = useCallback(() => {
+    if (state.kind !== 'ready') return
+    void copyText(state.url).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      window.setTimeout(() => { setCopied(false) }, 1500)
+    })
+  }, [state])
+
+  return (
+    <>
+      <TooltipAnchor wide={wide} label={t('entry.label')} onClick={openPanel} />
+      {open && createPortal((
+        <div className={css.overlay} role="presentation">
+          <div className={css.mask} aria-hidden="true" onClick={closePanel} />
+          <RemotePanel
+            t={t}
+            state={state}
+            copied={copied}
+            onClose={closePanel}
+            onStop={handleStop}
+            onRefresh={handleRefresh}
+            onCopy={handleCopy}
+            onPickAddress={handlePickAddress}
+            onPickPublic={handlePickPublic}
+          />
+        </div>
+      ), document.body)}
+    </>
+  )
+}
+
+/** The trigger: an icon button matching the settings rail/row geometry. */
+function TooltipAnchor({ wide, label, onClick }: { wide: boolean; label: string; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      className={css.trigger}
+      data-wide={wide ? undefined : 'rail'}
+      aria-label={label}
+      title={label}
+      onClick={onClick}
+    >
+      <PhoneIcon size={wide ? 16 : 18} />
+    </button>
+  )
+}

package/src/client/RemotePanel.tsx

@@ -0,0 +1,186 @@
+/**
+ * The mobile remote-control panel body: status card (state text + badge),
+ * the QR code, the open-on-phone hint with the link text, and the three
+ * actions (stop / refresh / copy). Pure presentation — all state and
+ * actions arrive through props from the entry's behavior component.
+ */
+import clsx from 'clsx'
+import { QRCodeSVG } from 'qrcode.react'
+import {
+  IconCloseOutline16, IconCopyOutline16, IconLinkOutline16, IconRefreshOutline16, IconStopFill16,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PairingPhase } from '../pairing.ts'
+import { formatClock, type TunnelStatusFrame } from './pair-api.ts'
+import css from './remote.module.css'
+
+/** The panel's view state, owned by the entry component. */
+export type PanelState =
+  | { kind: 'lan-required' }
+  | { kind: 'loopback-required' }
+  | { kind: 'unreachable' }
+  | {
+      kind: 'ready'
+      url: string
+      expiresAt: number
+      expired: boolean
+      phase: PairingPhase
+      deviceCount: number
+      onlineCount: number
+      /** The LAN literal the current QR was built from. */
+      address: string
+      /** Every constructible LAN literal (interface order). */
+      lanAddresses: string[]
+      /** Whether this QR is built on the configured public (tunneled) base. */
+      public: boolean
+      /** The configured public (tunneled) base URL, when present. */
+      publicBaseUrl?: string
+      /** Auto-tunnel status, while the auto-tunnel feature is active. */
+      tunnel?: TunnelStatusFrame
+    }
+
+/** Full panel props: copy + view state + actions. */
+export interface RemotePanelProps {
+  t: TranslateNS<'remote'>
+  state: PanelState
+  copied: boolean
+  onClose(): void
+  onStop(): void
+  onRefresh(): void
+  onCopy(): void
+  /** Re-mint the QR against a different LAN address. */
+  onPickAddress(address: string): void
+  /** Re-mint the QR against the configured public (tunneled) base. */
+  onPickPublic(): void
+}
+
+/** Badge text + tone per phase (ready states only). */
+function statusOf(
+  t: TranslateNS<'remote'>,
+  state: Extract<PanelState, { kind: 'ready' }>,
+): { text: string; tone: 'waiting' | 'connected' | 'disconnected' | 'stopped' } {
+  switch (state.phase) {
+    case 'connected': return { text: t('status.connected', { n: state.onlineCount }), tone: 'connected' }
+    case 'disconnected': return { text: t('status.disconnected'), tone: 'disconnected' }
+    case 'stopped': return { text: t('status.stopped'), tone: 'stopped' }
+    case 'lan-required': return { text: t('status.lanRequired'), tone: 'stopped' }
+    case 'waiting': return { text: t('status.waiting'), tone: 'waiting' }
+  }
+}
+
+/**
+ * Render the pairing panel.
+ * @param props - copy, state, and actions.
+ * @returns the panel element tree.
+ */
+export function RemotePanel({ t, state, copied, onClose, onStop, onRefresh, onCopy, onPickAddress, onPickPublic }: RemotePanelProps) {
+  return (
+    <div className={css.panel} role="dialog" aria-modal="true" aria-label={t('title')}>
+      <div className={css.header}>
+        <div className={css.heading}>
+          <h2 className={css.title}>{t('title')}</h2>
+          <p className={css.subtitle}>{t('subtitle')}</p>
+        </div>
+        <button type="button" className={css.close} aria-label={t('close.label')} onClick={onClose}>
+          <IconCloseOutline16 size={14} />
+        </button>
+      </div>
+
+      {state.kind === 'lan-required' ? (
+        <div className={css.banner} role="alert">
+          <p className={css.bannerTitle}>{t('status.lanRequired')}</p>
+          <p className={css.bannerHint}>{t('status.lanRequiredHint')}</p>
+        </div>
+      ) : state.kind === 'loopback-required' ? (
+        <div className={css.banner} role="alert">
+          <p className={css.bannerTitle}>{t('status.loopbackRequired')}</p>
+          <p className={css.bannerHint}>{t('status.loopbackRequiredHint')}</p>
+        </div>
+      ) : state.kind === 'unreachable' ? (
+        <div className={css.banner} role="alert">
+          <p className={css.bannerTitle}>{t('status.unreachable')}</p>
+          <p className={css.bannerHint}>{t('status.unreachableHint')}</p>
+        </div>
+      ) : (
+        <>
+          <div className={css.card}>
+            <div className={css.cardHeader}>
+              <span className={css.cardTitle}>{t('card.title')}</span>
+              <span className={css.badges}>
+                {state.public && <span className={clsx(css.badge, css.badgePublic)}>{t('public.badge')}</span>}
+                <span className={clsx(css.badge, css[`badge-${statusOf(t, state).tone}`])}>
+                  {statusOf(t, state).text}
+                </span>
+              </span>
+            </div>
+            <div className={css.qrWrap} data-testid="remote-qr">
+              <QRCodeSVG value={state.url} size={184} level="M" marginSize={1} className={css.qr} />
+            </div>
+            {state.expired
+              ? <p className={css.expired}>{t('pair.expired')}</p>
+              : <p className={css.expiry}>{t('pair.expires', { time: formatClock(state.expiresAt) })}</p>}
+          </div>
+
+          <p className={css.hint}>{state.public ? t('pair.publicHint') : t('pair.hint')}</p>
+          <p className={css.link} title={state.url}>{state.url}</p>
+          {state.phase === 'stopped' && <p className={css.stoppedHint}>{t('stopped.hint')}</p>}
+          {state.tunnel !== undefined && state.tunnel.state !== 'running' && (
+            <p className={state.tunnel.state === 'failed' ? css.tunnelFailed : css.tunnelNote} role="status">
+              {state.tunnel.state === 'failed'
+                ? t('tunnel.failed', { error: state.tunnel.error ?? t('tunnel.unknownError') })
+                : t('tunnel.starting')}
+            </p>
+          )}
+
+          {(state.publicBaseUrl !== undefined || state.lanAddresses.length > 1) && (
+            <fieldset className={css.addresses}>
+              <legend>{t('address.label')}</legend>
+              {state.publicBaseUrl !== undefined && (
+                <label key="public" className={css.address}>
+                  <input
+                    type="radio"
+                    name="lan-address"
+                    aria-label={t('address.public')}
+                    checked={state.public}
+                    onChange={onPickPublic}
+                  />
+                  <span>{t('address.public')}</span>
+                  <code className={css.addressValue}>{state.publicBaseUrl}</code>
+                </label>
+              )}
+              {state.lanAddresses.map(address => (
+                <label key={address} className={css.address}>
+                  <input
+                    type="radio"
+                    name="lan-address"
+                    aria-label={address}
+                    checked={!state.public && address === state.address}
+                    onChange={() => onPickAddress(address)}
+                  />
+                  <span>{t('address.lan')}</span>
+                  <code className={css.addressValue}>{address}</code>
+                </label>
+              ))}
+              <p className={css.addressHint}>{t('address.hint')}</p>
+            </fieldset>
+          )}
+
+          <div className={css.actions}>
+            <button type="button" className={css.action} onClick={onStop}>
+              <IconStopFill16 size={14} />
+              {t('action.stop')}
+            </button>
+            <button type="button" className={css.action} onClick={onRefresh}>
+              <IconRefreshOutline16 size={14} />
+              {t('action.refresh')}
+            </button>
+            <button type="button" className={css.action} onClick={onCopy}>
+              {copied ? <IconCopyOutline16 size={14} /> : <IconLinkOutline16 size={14} />}
+              {copied ? t('action.copied') : t('action.copy')}
+            </button>
+          </div>
+        </>
+      )}
+    </div>
+  )
+}

package/src/client/RemoteSettingsCard.tsx

@@ -0,0 +1,220 @@
+/**
+ * The remote-control settings card: pairing security and device limits.
+ * Registers into the `settings.plugin.item` slot the plugin-configuration
+ * section renders, bound to the `remote-web-ui` settings namespace.
+ */
+
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { PluginSettingsCard, ValueField, BooleanField } from './PluginSettingsCard.tsx'
+import { CardForm, booleanField, numberField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
+
+/** The remote-control fields this card edits (the namespace's full schema). */
+export interface RemoteSettings {
+  /** Master switch for the plugin. */
+  enabled?: boolean
+  /** Token lifetime in ms; the QR link dies after this. */
+  tokenTtlMs?: number
+  /** A device is "online" while its lastSeenAt is newer than this (ms). */
+  offlineAfterMs?: number
+  /** Hard cap on paired device sessions (oldest evicted when full). */
+  maxDevices?: number
+  /** Cookie name carrying the paired device id. */
+  cookieName?: string
+  /** Fence flag: whether non-loopback /api requests must carry a live paired-device cookie. */
+  requirePairingForLan?: boolean
+  /** Public (tunneled) base URL the QR link is built from when set. */
+  publicBaseUrl?: string
+  /** When on, the plugin runs its own Cloudflare quick tunnel automatically. */
+  autoTunnel?: boolean
+}
+
+/** What the remote-control card renders. */
+export interface RemoteSettingsCardState extends CardShell {
+  /** Master switch. */
+  enabled: CardFieldState
+  /** Token lifetime. */
+  tokenTtlMs: CardFieldState
+  /** Device offline threshold. */
+  offlineAfterMs: CardFieldState
+  /** Paired-device cap. */
+  maxDevices: CardFieldState
+  /** Device cookie name. */
+  cookieName: CardFieldState
+  /** LAN fence flag. */
+  requirePairingForLan: CardFieldState
+  /** Public (tunneled) base URL. */
+  publicBaseUrl: CardFieldState
+  /** Auto public tunnel switch. */
+  autoTunnel: CardFieldState
+}
+
+/** The registration-side face the card's slot entry injects. */
+export interface RemoteSettingsCardFace extends CardActions {
+  hooks: {
+    /** Card snapshot bound by the renderer as useRemoteSettingsCard. */
+    remoteSettingsCard: SnapshotStore<RemoteSettingsCardState>
+  }
+}
+
+/** Bridges the `remote-web-ui` scope onto the card's staged form. */
+export class RemoteSettingsCardController {
+  private readonly form: CardForm<RemoteSettings>
+  private readonly store: SnapshotStore<RemoteSettingsCardState>
+
+  /** @param scope - the bound settings scope for the `remote-web-ui` namespace. */
+  constructor(scope: SettingsScope<RemoteSettings>) {
+    this.form = new CardForm(scope, [
+      booleanField('enabled'),
+      numberField('tokenTtlMs'),
+      numberField('offlineAfterMs'),
+      numberField('maxDevices'),
+      textField('cookieName'),
+      booleanField('requirePairingForLan'),
+      textField('publicBaseUrl'),
+      booleanField('autoTunnel'),
+    ])
+    this.store = this.form.bind(() => this.projection())
+  }
+
+  private projection(): RemoteSettingsCardState {
+    return {
+      ...this.form.shell(),
+      enabled: this.form.field('enabled'),
+      tokenTtlMs: this.form.field('tokenTtlMs'),
+      offlineAfterMs: this.form.field('offlineAfterMs'),
+      maxDevices: this.form.field('maxDevices'),
+      cookieName: this.form.field('cookieName'),
+      requirePairingForLan: this.form.field('requirePairingForLan'),
+      publicBaseUrl: this.form.field('publicBaseUrl'),
+      autoTunnel: this.form.field('autoTunnel'),
+    }
+  }
+
+  /**
+   * Build the face the card's slot registration injects.
+   * @returns the card's snapshot and its form actions.
+   */
+  inject(): RemoteSettingsCardFace {
+    return { hooks: { remoteSettingsCard: this.store }, ...this.form.actions() }
+  }
+}
+
+/** Props the renderer binds for the remote-control card. */
+export type RemoteSettingsCardProps =
+  PropsRuntime<'web-ui.plugin.item'>
+  & PropsLocale<'remote'>
+  & InjectFace<RemoteSettingsCardFace>
+
+/**
+ * Render the remote-control card.
+ * @param props - locale copy, the card snapshot, and its form actions.
+ * @returns the card.
+ */
+export function RemoteSettingsCard(props: RemoteSettingsCardProps) {
+  const { t } = props
+  const state = props.useRemoteSettingsCard(snapshot => snapshot)
+  const disabled = !state.writable
+  const fieldProps = {
+    overriddenLabel: t('settings.overridden'),
+    resetLabel: t('settings.reset'),
+    invalidLabel: t('settings.invalidNumber'),
+    disabled,
+  }
+  return (
+    <PluginSettingsCard
+      t={t}
+      titleKey="settings.title"
+      descriptionKey="settings.description"
+      state={state}
+      onSave={props.save}
+      onDiscard={props.discard}
+    >
+      <BooleanField
+        id="settings-remote-enabled"
+        label={t('settings.enabled')}
+        hint={t('settings.enabledHint')}
+        inheritLabel={t('settings.inherit')}
+        onLabel={t('settings.on')}
+        offLabel={t('settings.off')}
+        {...fieldProps}
+        {...state.enabled}
+        onEdit={(text) => { props.edit('enabled', text) }}
+        onReset={() => { props.resetField('enabled') }}
+      />
+      <ValueField
+        id="settings-remote-token-ttl"
+        label={t('settings.tokenTtlMs')}
+        hint={t('settings.tokenTtlMsHint')}
+        numeric
+        {...fieldProps}
+        {...state.tokenTtlMs}
+        onEdit={(text) => { props.edit('tokenTtlMs', text) }}
+        onReset={() => { props.resetField('tokenTtlMs') }}
+      />
+      <ValueField
+        id="settings-remote-offline"
+        label={t('settings.offlineAfterMs')}
+        hint={t('settings.offlineAfterMsHint')}
+        numeric
+        {...fieldProps}
+        {...state.offlineAfterMs}
+        onEdit={(text) => { props.edit('offlineAfterMs', text) }}
+        onReset={() => { props.resetField('offlineAfterMs') }}
+      />
+      <ValueField
+        id="settings-remote-max-devices"
+        label={t('settings.maxDevices')}
+        hint={t('settings.maxDevicesHint')}
+        numeric
+        {...fieldProps}
+        {...state.maxDevices}
+        onEdit={(text) => { props.edit('maxDevices', text) }}
+        onReset={() => { props.resetField('maxDevices') }}
+      />
+      <ValueField
+        id="settings-remote-cookie"
+        label={t('settings.cookieName')}
+        hint={t('settings.cookieNameHint')}
+        {...fieldProps}
+        {...state.cookieName}
+        onEdit={(text) => { props.edit('cookieName', text) }}
+        onReset={() => { props.resetField('cookieName') }}
+      />
+      <BooleanField
+        id="settings-remote-fence"
+        label={t('settings.requirePairingForLan')}
+        hint={t('settings.requirePairingForLanHint')}
+        inheritLabel={t('settings.inherit')}
+        onLabel={t('settings.on')}
+        offLabel={t('settings.off')}
+        {...fieldProps}
+        {...state.requirePairingForLan}
+        onEdit={(text) => { props.edit('requirePairingForLan', text) }}
+        onReset={() => { props.resetField('requirePairingForLan') }}
+      />
+      <ValueField
+        id="settings-remote-public-base"
+        label={t('settings.publicBaseUrl')}
+        hint={t('settings.publicBaseUrlHint')}
+        placeholder="https://example.trycloudflare.com"
+        {...fieldProps}
+        {...state.publicBaseUrl}
+        onEdit={(text) => { props.edit('publicBaseUrl', text) }}
+        onReset={() => { props.resetField('publicBaseUrl') }}
+      />
+      <BooleanField
+        id="settings-remote-auto-tunnel"
+        label={t('settings.autoTunnel')}
+        hint={t('settings.autoTunnelHint')}
+        inheritLabel={t('settings.inherit')}
+        onLabel={t('settings.on')}
+        offLabel={t('settings.off')}
+        {...fieldProps}
+        {...state.autoTunnel}
+        onEdit={(text) => { props.edit('autoTunnel', text) }}
+        onReset={() => { props.resetField('autoTunnel') }}
+      />
+    </PluginSettingsCard>
+  )
+}