dsh-cherry-bridge 0.1.10 → 0.2.0

package/ui/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md — `ui/`
+
+The settings page: pairing wizard, device cards and the tool-scope panel. It
+builds to `lib/client.js` (`npm run build:client`) and that bundle is COMMITTED
+with its source. Loaded automatically when a file tool touches `ui/**`.
+
+- **One view, no router.** `App.tsx` owns the two things that outlive both
+  children: the SSE stream and the device map.
+- **The stream opens ONCE on mount and closes on unmount, in that order.** The
+  verification code exists only as a frame with no replay, so the stream must
+  exist before the wizard can `POST /pair` — which is why the submit button
+  stays disabled until `subscribed` flips true.
+- **`device-state` is a FIRST-FRAME contract.** The REST list supplies the
+  static fields; a card's light shows only a state the server actually sent.
+- **Every user-visible string goes through `t()`** (`i18n.ts`, zh and en in the
+  same change). A token that must never render — the missing-`EventSource`
+  marker — is a constant, not a sentence, and the component translates it.
+- **HTTP lives in `api.ts`** (same-origin `/cherry-remote/api`); a component
+  never fetches directly. Both seams are injected for tests
+  (`eventSourceFactory`, `scopeClient`), so no test stands up a server.
+- **jsdom only.** `tests/unit/ui.test.ts` and `uiScopePanel.test.ts` render the
+  page; a browser-only API needs a fake in the test, not a guard in the page.
+

package/ui/src/DeviceCard.tsx

@@ -42,6 +42,22 @@ function parseHosts(raw: string): string[] {
     .filter((entry) => entry !== '')
 }
 
+/** The dial port for one host: its own stored port, else the record-level one. */
+function dialPort(device: DeviceSummary, host: string): number {
+  return device.ports?.[host] ?? device.port
+}
+
+/**
+ * `host:port` as one readable address.
+ *
+ * An IPv6 literal contains colons, so `fe80::1:4343` reads as an ambiguous
+ * host; stored hosts are bare (`normalizeHost` strips the brackets), so the
+ * brackets are added here, for display only.
+ */
+function formatAddress(host: string, port: number): string {
+  return host.includes(':') ? `[${host}]:${port}` : `${host}:${port}`
+}
+
 export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProps): ReturnType<typeof Object> {
   const t = useT()
   const [editor, setEditor] = useState<Editor>('none')
@@ -141,6 +157,13 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
     })
   }
 
+  // The record-level `port` alone would claim every host dials it, which is
+  // false for a record whose map disagrees. `mixedPorts` decides whether the
+  // card has anything to say beyond that single number; `addressList` is the
+  // per-host truth (map value, record port as the fallback).
+  const mixedPorts = device.hosts.some((host) => dialPort(device, host) !== device.port)
+  const addressList = device.hosts.map((host) => formatAddress(host, dialPort(device, host))).join(', ')
+
   // `?? state` keeps an unknown future state transparent — the enum is the only
   // honest thing left to show for one this build has no copy for — while every
   // state it DOES know renders through the dictionary.
@@ -183,10 +206,18 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
         <dd>{device.hosts.join(', ')}</dd>
         <dt>{t('device.field.port')}</dt>
         <dd>{device.port}</dd>
+        {mixedPorts && (
+          <>
+            <dt>{t('device.field.ports')}</dt>
+            <dd className="cherry-mono">{addressList}</dd>
+          </>
+        )}
         <dt>{t('device.field.id')}</dt>
         <dd className="cherry-mono">{device.deviceId}</dd>
       </dl>
 
+      {mixedPorts && <p className="cherry-hint">{t('device.ports.hint')}</p>}
+
       {editor === 'rename' && (
         <form className="cherry-inline-form" onSubmit={saveName}>
           <label htmlFor={`name-${device.deviceId}`}>{t('device.field.name')}</label>
@@ -210,6 +241,9 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
             onChange={(event: ChangeEvent<HTMLInputElement>) => setHostsText(event.target.value)}
           />
           <span className="cherry-hint">{t('device.hosts.hint')}</span>
+          <span className="cherry-hint">
+            {t('device.ports.current')} <span className="cherry-mono">{addressList}</span>
+          </span>
           <label htmlFor={`port-${device.deviceId}`}>{t('device.field.port')}</label>
           <input
             id={`port-${device.deviceId}`}
@@ -217,6 +251,7 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
             value={portText}
             onChange={(event: ChangeEvent<HTMLInputElement>) => setPortText(event.target.value)}
           />
+          <span className="cherry-hint">{t('device.port.hint')}</span>
           <button type="submit" disabled={busy}>
             {t('device.save.addresses')}
           </button>

package/ui/src/i18n.ts

@@ -86,6 +86,10 @@ const zh: Dict = {
   'device.field.name': '设备名称',
   'device.field.hosts': '主机地址',
   'device.hosts.hint': '多个候选地址用逗号分隔（整体替换）',
+  'device.field.ports': '每地址端口',
+  'device.ports.hint': '部分候选地址的端口与上方的端口不同；在「地址维护」里改动端口会把所有候选地址改为同一端口。',
+  'device.ports.current': '当前端口映射：',
+  'device.port.hint': '保持当前值会保留各地址自己的端口；改成新值会把所有候选地址重指到该端口。',
   'device.save.name': '保存名称',
   'device.save.addresses': '保存地址',
   'device.remove.confirm': '确认移除',
@@ -236,6 +240,12 @@ const en: Dict = {
   'device.field.name': 'Device name',
   'device.field.hosts': 'Host addresses',
   'device.hosts.hint': 'Separate candidate addresses with commas (the whole list is replaced)',
+  'device.field.ports': 'Ports per address',
+  'device.ports.hint':
+    'Some candidate addresses dial a different port than the one above; changing the port in address maintenance moves every candidate address to that one port.',
+  'device.ports.current': 'Current port map:',
+  'device.port.hint':
+    'Keeping the current value preserves each address’s own port; a new value re-points every candidate address.',
   'device.save.name': 'Save name',
   'device.save.addresses': 'Save addresses',
   'device.remove.confirm': 'Confirm removal',

package/ui/src/types.ts

@@ -23,7 +23,14 @@ export const API_BASE = '/cherry-remote/api'
 /** The five device states the connection layer reports. */
 export type DeviceState = 'connected' | 'connecting' | 'offline' | 'disabled' | 'identity-mismatch'
 
-/** One device exactly as `GET /devices` returns it. Never carries a credential. */
+/**
+ * One device exactly as `GET /devices` returns it. Never carries a credential.
+ *
+ * `ports` is the per-HOST dial port map: each candidate address dials its own
+ * port, and the record-level `port` is the fallback for a host the map does not
+ * carry (a stored v4 record has an entry for every host, so the card's `??` arm
+ * only fires on a malformed map). Required — `GET /devices` always emits it.
+ */
 export interface DeviceSummary {
   deviceId: string
   displayName: string
@@ -31,6 +38,7 @@ export interface DeviceSummary {
   enabled: boolean
   hosts: string[]
   port: number
+  ports: Record<string, number>
 }
 
 /** A `PATCH /devices/:id` body; every field optional, `hosts` is whole-replace. */

package/src/urlHost.ts

@@ -1,15 +0,0 @@
-/**
- * Renders a host as a URL authority component. The device archive and pairing
- * flow store BARE hosts (plan-mandated normalization), so a bare IPv6 literal
- * must be bracketed before it is spliced into a URL — `ws://::1:35543/...`
- * is not a valid URL and `new WebSocket(...)` throws synchronously on it.
- *
- * Shared home for the dial sites: both `connection.ts` (per-device dial) and
- * `pairing.ts` (candidate dial) splice hosts into URLs and must bracket the
- * same way.
- */
-export function urlHost(host: string): string {
-  // A colon can only mean IPv6 here: a `host:port` pair never reaches this
-  // layer (the port travels separately).
-  return host.includes(':') ? `[${host}]` : host
-}