@tx5dr/contracts 1.4.0 → 1.5.0

package/src/schema/radio-power-support.ts

@@ -17,32 +17,40 @@ import type { HamlibConfig } from './radio.schema.js';
 export interface PowerCapableRigEntry {
   mfg: string | RegExp;
   model: string | RegExp;
+  /**
+   * Physical powerstat targets that are safe to expose while CAT is connected.
+   * `on` is represented by canPowerOn and is not part of this connected-state list.
+   */
+  supportedStates?: ReadonlyArray<'operate' | 'standby' | 'off'>;
 }
 
 export const POWER_CAPABLE_RIGS: ReadonlyArray<PowerCapableRigEntry> = [
   // Icom modern transceivers (CI-V 0x18 command)
-  { mfg: /^icom$/i, model: /^IC-?705$/i },
-  { mfg: /^icom$/i, model: /^IC-?7300$/i },
-  { mfg: /^icom$/i, model: /^IC-?7610$/i },
-  { mfg: /^icom$/i, model: /^IC-?7100$/i },
-  { mfg: /^icom$/i, model: /^IC-?7851$/i },
-  { mfg: /^icom$/i, model: /^IC-?9700$/i },
-  { mfg: /^icom$/i, model: /^IC-?R8600$/i },
+  { mfg: /^icom$/i, model: /^IC-?705$/i, supportedStates: ['off', 'standby', 'operate'] },
+  { mfg: /^icom$/i, model: /^IC-?7300$/i, supportedStates: ['off', 'standby', 'operate'] },
+  { mfg: /^icom$/i, model: /^IC-?7610$/i, supportedStates: ['off', 'standby', 'operate'] },
+  { mfg: /^icom$/i, model: /^IC-?7100$/i, supportedStates: ['off', 'standby', 'operate'] },
+  { mfg: /^icom$/i, model: /^IC-?7851$/i, supportedStates: ['off', 'standby', 'operate'] },
+  { mfg: /^icom$/i, model: /^IC-?9700$/i, supportedStates: ['off', 'standby', 'operate'] },
+  { mfg: /^icom$/i, model: /^IC-?R8600$/i, supportedStates: ['off', 'standby', 'operate'] },
 
   // Kenwood
-  { mfg: /^kenwood$/i, model: /^TS-590SG?$/i },
-  { mfg: /^kenwood$/i, model: /^TS-890$/i },
-  { mfg: /^kenwood$/i, model: /^TS-990$/i },
+  { mfg: /^kenwood$/i, model: /^TS-590SG?$/i, supportedStates: ['off', 'standby'] },
+  { mfg: /^kenwood$/i, model: /^TS-890$/i, supportedStates: ['off', 'standby'] },
+  { mfg: /^kenwood$/i, model: /^TS-990$/i, supportedStates: ['off', 'standby'] },
 
-  // Yaesu
-  { mfg: /^yaesu$/i, model: /^FT-991A?$/i },
-  { mfg: /^yaesu$/i, model: /^FTDX-?10$/i },
-  { mfg: /^yaesu$/i, model: /^FTDX-?101(MP|D)?$/i },
-  { mfg: /^yaesu$/i, model: /^FT-?710$/i },
+  // Yaesu: FT-710 rejects powerstat(operate), so do not expose it by default.
+  { mfg: /^yaesu$/i, model: /^FT-991A?$/i, supportedStates: ['off', 'standby'] },
+  { mfg: /^yaesu$/i, model: /^FTDX-?10$/i, supportedStates: ['off', 'standby'] },
+  { mfg: /^yaesu$/i, model: /^FTDX-?101(MP|D)?$/i, supportedStates: ['off', 'standby'] },
+  { mfg: /^yaesu$/i, model: /^FT-?710$/i, supportedStates: ['off'] },
 ];
 
-export function isRigModelPowerCapable(mfgName: string, modelName: string): boolean {
-  return POWER_CAPABLE_RIGS.some((entry) => {
+export function findPowerCapableRigEntry(
+  mfgName: string,
+  modelName: string
+): PowerCapableRigEntry | undefined {
+  return POWER_CAPABLE_RIGS.find((entry) => {
     const mfgOk =
       typeof entry.mfg === 'string'
         ? entry.mfg.toLowerCase() === mfgName.toLowerCase()
@@ -55,6 +63,10 @@ export function isRigModelPowerCapable(mfgName: string, modelName: string): bool
   });
 }
 
+export function isRigModelPowerCapable(mfgName: string, modelName: string): boolean {
+  return findPowerCapableRigEntry(mfgName, modelName) !== undefined;
+}
+
 export type PowerSupportReason =
   | 'model-unsupported'
   | 'network-mode-no-wake'
@@ -65,6 +77,8 @@ export interface PowerSupportDecision {
   canPowerOn: boolean;
   /** Whether the UI should surface a "power off" control. */
   canPowerOff: boolean;
+  /** Connected-state physical power targets the UI may offer. */
+  supportedStates: Array<'operate' | 'standby' | 'off'>;
   /** Machine-readable reason when `canPowerOn` is false. */
   reason?: PowerSupportReason;
 }
@@ -85,23 +99,32 @@ export function decidePowerSupport(
 ): PowerSupportDecision {
   switch (config.type) {
     case 'none':
-      return { canPowerOn: false, canPowerOff: false, reason: 'none-mode' };
+      return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'none-mode' };
     case 'network':
-      return { canPowerOn: false, canPowerOff: true, reason: 'network-mode-no-wake' };
+      return {
+        canPowerOn: false,
+        canPowerOff: true,
+        supportedStates: ['off'],
+        reason: 'network-mode-no-wake',
+      };
     case 'icom-wlan':
       // ICOM WLAN 的 CI-V-over-UDP 通道在电台关机后无法维持；即便已连接
       // 发送 powerstat(off) 也不能可靠恢复。整体不暴露电源控制。
-      return { canPowerOn: false, canPowerOff: false, reason: 'model-unsupported' };
+      return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
     case 'serial': {
       if (!rigInfo) {
-        return { canPowerOn: false, canPowerOff: false, reason: 'model-unsupported' };
+        return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
       }
-      const supported = isRigModelPowerCapable(rigInfo.mfgName, rigInfo.modelName);
-      return supported
-        ? { canPowerOn: true, canPowerOff: true }
-        : { canPowerOn: false, canPowerOff: false, reason: 'model-unsupported' };
+      const entry = findPowerCapableRigEntry(rigInfo.mfgName, rigInfo.modelName);
+      return entry
+        ? {
+            canPowerOn: true,
+            canPowerOff: true,
+            supportedStates: [...(entry.supportedStates ?? ['off'])],
+          }
+        : { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
     }
     default:
-      return { canPowerOn: false, canPowerOff: false, reason: 'model-unsupported' };
+      return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
   }
 }

package/src/schema/radio-power.schema.ts

@@ -5,10 +5,10 @@ import { HamlibConfigSchema } from './radio.schema.js';
  * High-level runtime state tracked by the RadioPowerController.
  *
  * - `off`: radio is known to be off (or was never connected).
- * - `waking`: power-on command sent, waiting for the radio to respond.
- * - `awake`: radio is responding; the engine is being started (if autoEngine).
- * - `shutting_down`: engine is stopping in preparation for a power-off command.
- * - `entering_standby`: powerstat(2) sent, waiting for radio to drop CAT link.
+ * - `waking`: physical power-on command sent, waiting for the radio to respond.
+ * - `awake`: radio is physically responding; software engine startup is optional.
+ * - `shutting_down`: physical power-off command is being applied.
+ * - `entering_standby`: physical standby command is being applied.
  * - `failed`: last transition failed; UI should show an error + retry.
  */
 export const RadioPowerStateSchema = z.enum([
@@ -53,14 +53,15 @@ export type RadioPowerStateEvent = z.infer<typeof RadioPowerStateEventSchema>;
 /**
  * REST request body: POST /api/radio/power
  */
-/** Allowed target states for a power request. */
+/** Allowed physical radio target states for a power request. */
 export const RadioPowerTargetSchema = z.enum(['on', 'off', 'standby', 'operate']);
 export type RadioPowerTarget = z.infer<typeof RadioPowerTargetSchema>;
 
 export const RadioPowerRequestSchema = z.object({
   profileId: z.string().min(1),
+  /** Physical radio power target. This is not the TX-5DR software engine state. */
   state: RadioPowerTargetSchema,
-  /** Automatically start the engine after successful power-on. Defaults to true. */
+  /** Automatically start the TX-5DR engine after successful physical power-on. */
   autoEngine: z.boolean().optional().default(true),
 });
 export type RadioPowerRequest = z.infer<typeof RadioPowerRequestSchema>;
@@ -70,6 +71,7 @@ export type RadioPowerRequest = z.infer<typeof RadioPowerRequestSchema>;
  */
 export const RadioPowerResponseSchema = z.object({
   success: z.boolean(),
+  target: RadioPowerTargetSchema,
   state: RadioPowerStateSchema,
 });
 export type RadioPowerResponse = z.infer<typeof RadioPowerResponseSchema>;

package/src/schema/realtime.schema.ts

@@ -3,10 +3,7 @@ import { z } from 'zod';
 export const RealtimeScopeSchema = z.enum(['radio', 'openwebrx-preview']);
 export type RealtimeScope = z.infer<typeof RealtimeScopeSchema>;
 
-export const RealtimeParticipantKindSchema = z.enum(['listener', 'publisher', 'bridge']);
-export type RealtimeParticipantKind = z.infer<typeof RealtimeParticipantKindSchema>;
-
-export const RealtimeTransportKindSchema = z.enum(['livekit', 'ws-compat']);
+export const RealtimeTransportKindSchema = z.enum(['rtc-data-audio', 'ws-compat']);
 export type RealtimeTransportKind = z.infer<typeof RealtimeTransportKindSchema>;
 
 export const RealtimeSessionDirectionSchema = z.enum(['recv', 'send']);
@@ -27,10 +24,14 @@ export type RealtimeConnectivityErrorCode = z.infer<typeof RealtimeConnectivityE
 
 export const RealtimeConnectivityHintsSchema = z.object({
   signalingUrl: z.string(),
-  signalingPort: z.number().int().positive(),
-  rtcTcpPort: z.number().int().positive(),
-  udpPortRange: z.string(),
-  publicUrlOverrideActive: z.boolean(),
+  localUdpPort: z.number().int().min(1).max(65535),
+  publicCandidateEnabled: z.boolean(),
+  publicEndpoint: z.object({
+    host: z.string(),
+    port: z.number().int().min(1).max(65535),
+  }).nullable(),
+  iceServers: z.array(z.string()),
+  fallbackTransport: z.literal('ws-compat'),
 });
 export type RealtimeConnectivityHints = z.infer<typeof RealtimeConnectivityHintsSchema>;
 
@@ -45,14 +46,6 @@ export const RealtimeConnectivityIssueSchema = z.object({
 });
 export type RealtimeConnectivityIssue = z.infer<typeof RealtimeConnectivityIssueSchema>;
 
-export const RealtimeTokenRequestSchema = z.object({
-  scope: RealtimeScopeSchema,
-  publish: z.boolean().optional(),
-  previewSessionId: z.string().optional(),
-});
-
-export type RealtimeTokenRequest = z.infer<typeof RealtimeTokenRequestSchema>;
-
 export const RealtimeSessionRequestSchema = z.object({
   scope: RealtimeScopeSchema,
   direction: RealtimeSessionDirectionSchema,
@@ -62,30 +55,6 @@ export const RealtimeSessionRequestSchema = z.object({
 
 export type RealtimeSessionRequest = z.infer<typeof RealtimeSessionRequestSchema>;
 
-export const RealtimeParticipantMetadataSchema = z.object({
-  role: z.string(),
-  tokenId: z.string().nullable().optional(),
-  operatorIds: z.array(z.string()).optional(),
-  clientKind: z.string(),
-  participantKind: RealtimeParticipantKindSchema,
-  scope: RealtimeScopeSchema,
-  previewSessionId: z.string().optional(),
-});
-
-export type RealtimeParticipantMetadata = z.infer<typeof RealtimeParticipantMetadataSchema>;
-
-export const RealtimeTokenResponseSchema = z.object({
-  url: z.string(),
-  roomName: z.string(),
-  token: z.string(),
-  participantIdentity: z.string(),
-  participantName: z.string(),
-  participantMetadata: RealtimeParticipantMetadataSchema,
-  connectivityHints: RealtimeConnectivityHintsSchema,
-});
-
-export type RealtimeTokenResponse = z.infer<typeof RealtimeTokenResponseSchema>;
-
 export const RealtimeTransportOfferSchema = z.object({
   transport: RealtimeTransportKindSchema,
   direction: RealtimeSessionDirectionSchema,
@@ -93,7 +62,6 @@ export const RealtimeTransportOfferSchema = z.object({
   token: z.string(),
   participantIdentity: z.string().nullable().optional(),
   participantName: z.string().nullable().optional(),
-  roomName: z.string().nullable().optional(),
 });
 
 export type RealtimeTransportOffer = z.infer<typeof RealtimeTransportOfferSchema>;
@@ -101,8 +69,74 @@ export type RealtimeTransportOffer = z.infer<typeof RealtimeTransportOfferSchema
 export const RealtimeTransportPolicySchema = z.enum(['auto', 'force-compat']);
 export type RealtimeTransportPolicy = z.infer<typeof RealtimeTransportPolicySchema>;
 
-export const LiveKitNetworkModeSchema = z.enum(['lan', 'internet-auto', 'internet-manual']);
-export type LiveKitNetworkMode = z.infer<typeof LiveKitNetworkModeSchema>;
+function isValidIpv4Literal(value: string): boolean {
+  const parts = value.split('.');
+  return parts.length === 4 && parts.every((part) => {
+    if (!/^\d{1,3}$/.test(part)) {
+      return false;
+    }
+    const parsed = Number.parseInt(part, 10);
+    return parsed >= 0 && parsed <= 255;
+  });
+}
+
+function isValidIpv6Literal(value: string): boolean {
+  if (!value.includes(':') || value.includes('[') || value.includes(']')) {
+    return false;
+  }
+  try {
+    // WHATWG URL parsing gives us a portable IPv6 sanity check without Node-only APIs.
+    // The schema still forbids bracket notation because the setting is host-only.
+    const parsed = new URL(`http://[${value}]/`);
+    return parsed.hostname.length > 2;
+  } catch {
+    return false;
+  }
+}
+
+function isValidDnsHostname(value: string): boolean {
+  if (value.length > 253 || value.endsWith('.')) {
+    return false;
+  }
+  const labels = value.split('.');
+  return labels.every((label) => (
+    label.length >= 1
+    && label.length <= 63
+    && /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label)
+  ));
+}
+
+function isValidRtcDataAudioPublicHost(value: string): boolean {
+  const host = value.trim();
+  if (!host || /\s/.test(host) || /[/?#@]/.test(host) || /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(host)) {
+    return false;
+  }
+  return isValidIpv4Literal(host) || isValidIpv6Literal(host) || isValidDnsHostname(host);
+}
+
+export const RtcDataAudioPublicHostSchema = z.preprocess(
+  (value) => (typeof value === 'string' ? value.trim() : value),
+  z.union([
+    z.literal('').transform(() => null),
+    z.string().min(1).max(253).refine(isValidRtcDataAudioPublicHost, {
+      message: 'Public host must be an IP address or DNS hostname without scheme, port, or path',
+    }),
+    z.null(),
+  ]),
+);
+export type RtcDataAudioPublicHost = z.infer<typeof RtcDataAudioPublicHostSchema>;
+
+export const RtcDataAudioPublicUdpPortSchema = z.preprocess((value) => {
+  if (value === '' || value === undefined) {
+    return null;
+  }
+  if (typeof value === 'string') {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : value;
+  }
+  return value;
+}, z.number().int().min(1).max(65535).nullable());
+export type RtcDataAudioPublicUdpPort = z.infer<typeof RtcDataAudioPublicUdpPortSchema>;
 
 export const RealtimeSessionResponseSchema = z.object({
   scope: RealtimeScopeSchema,
@@ -112,10 +146,8 @@ export const RealtimeSessionResponseSchema = z.object({
   selectionReason: z.enum([
     'client-override',
     'server-policy',
-    'bridge-unhealthy',
-    'livekit-disabled',
-    'runtime-unavailable',
-    'default-livekit',
+    'default-rtc-data-audio',
+    'rtc-data-audio-unavailable',
   ]),
   forcedCompatibilityMode: z.boolean(),
   offers: z.array(RealtimeTransportOfferSchema).min(1),
@@ -125,34 +157,27 @@ export const RealtimeSessionResponseSchema = z.object({
 export type RealtimeSessionResponse = z.infer<typeof RealtimeSessionResponseSchema>;
 
 export const RealtimeSettingsSchema = z.object({
-  publicWsUrl: z.string().url().nullable().optional(),
   transportPolicy: RealtimeTransportPolicySchema.optional(),
-  networkMode: LiveKitNetworkModeSchema.optional(),
-  nodeIp: z.string().nullable().optional(),
+  rtcDataAudioPublicHost: RtcDataAudioPublicHostSchema.optional(),
+  rtcDataAudioPublicUdpPort: RtcDataAudioPublicUdpPortSchema.optional(),
 });
 
 export type RealtimeSettings = z.infer<typeof RealtimeSettingsSchema>;
 
-export const RealtimeCredentialSourceSchema = z.enum(['managed-file', 'environment-override', 'missing']);
-export type RealtimeCredentialSource = z.infer<typeof RealtimeCredentialSourceSchema>;
-
-export const RealtimeCredentialStatusSchema = z.object({
-  initialized: z.boolean(),
-  source: RealtimeCredentialSourceSchema,
-  filePath: z.string().nullable(),
-  apiKeyPreview: z.string().nullable(),
-  createdAt: z.string().nullable(),
-  rotatedAt: z.string().nullable(),
+export const RealtimeRtcDataAudioRuntimeSchema = z.object({
+  localUdpPort: z.number().int().min(1).max(65535),
+  publicCandidateEnabled: z.boolean(),
+  publicEndpoint: z.object({
+    host: z.string(),
+    port: z.number().int().min(1).max(65535),
+  }).nullable(),
 });
-export type RealtimeCredentialStatus = z.infer<typeof RealtimeCredentialStatusSchema>;
+export type RealtimeRtcDataAudioRuntime = z.infer<typeof RealtimeRtcDataAudioRuntimeSchema>;
 
 export const RealtimeSettingsRuntimeSchema = z.object({
-  liveKitEnabled: z.boolean(),
   connectivityHints: RealtimeConnectivityHintsSchema,
   radioReceiveTransport: RealtimeTransportKindSchema,
-  radioBridgeHealthy: z.boolean(),
-  radioBridgeIssueCode: RealtimeConnectivityErrorCodeSchema.nullable(),
-  credentialStatus: RealtimeCredentialStatusSchema,
+  rtcDataAudio: RealtimeRtcDataAudioRuntimeSchema,
 });
 
 export type RealtimeSettingsRuntime = z.infer<typeof RealtimeSettingsRuntimeSchema>;
@@ -234,6 +259,10 @@ export const RealtimeVoiceTxServerIngressStatsSchema = z.object({
   queueDepthFrames: z.number().int().nonnegative(),
   queuedAudioMs: z.number().nonnegative(),
   droppedFrames: z.number().int().nonnegative(),
+  staleDroppedFrames: z.number().int().nonnegative(),
+  underrunCount: z.number().int().nonnegative(),
+  plcFrames: z.number().int().nonnegative(),
+  jitterTargetMs: z.number().nonnegative(),
 });
 
 export type RealtimeVoiceTxServerIngressStats = z.infer<typeof RealtimeVoiceTxServerIngressStatsSchema>;
@@ -242,8 +271,10 @@ export const RealtimeVoiceTxServerOutputStatsSchema = z.object({
   resampleMs: RealtimeVoiceTxMetricWindowSchema,
   queueWaitMs: RealtimeVoiceTxMetricWindowSchema,
   writeMs: RealtimeVoiceTxMetricWindowSchema,
+  serverPipelineMs: RealtimeVoiceTxMetricWindowSchema,
   endToEndMs: RealtimeVoiceTxMetricWindowSchema,
   outputBufferedMs: RealtimeVoiceTxMetricWindowSchema,
+  outputWriteIntervalMs: RealtimeVoiceTxMetricWindowSchema,
   outputSampleRate: z.number().nullable(),
   outputBufferSize: z.number().nullable(),
   writeFailures: z.number().int().nonnegative(),

package/src/schema/server-message-keys.ts

@@ -18,8 +18,8 @@ export enum ServerMessageKey {
   /** 实时语音连接异常 */
   REALTIME_CONNECTIVITY_WARNING = 'realtimeConnectivityWarning',
 
-  /** 服务端实时语音桥接异常 */
-  REALTIME_BRIDGE_DOWN = 'realtimeBridgeDown',
+  /** 服务端实时语音服务异常 */
+  REALTIME_SERVICE_DOWN = 'realtimeServiceDown',
 
   /** 实时语音链路无音频数据 */
   REALTIME_NO_AUDIO = 'realtimeNoAudio',

package/src/schema/slot-info.schema.ts

@@ -148,7 +148,9 @@ export const SlotPackSchema = z.object({
     /** 去重后的帧数 */
     totalFramesAfterDedup: z.number().default(0),
     /** 最后更新时间戳 */
-    lastUpdated: z.number().default(() => Date.now())
+    lastUpdated: z.number().default(() => Date.now()),
+    /** SlotPack 单调更新序号，用于客户端丢弃乱序旧包 */
+    updateSeq: z.number().int().nonnegative().optional()
   }).default({}),
   /** 解码历史（用于调试） */
   decodeHistory: z.array(z.object({

package/src/schema/websocket.schema.ts

@@ -187,6 +187,7 @@ export enum WSMessageType {
   PLUGIN_USER_ACTION = 'pluginUserAction',
   PLUGIN_PAGE_PUSH = 'pluginPagePush',
   PLUGIN_PANEL_META = 'pluginPanelMeta',
+  PLUGIN_PANEL_CONTRIBUTIONS_CHANGED = 'pluginPanelContributionsChanged',
 
   // ===== OpenWebRX SDR =====
   OPENWEBRX_LISTEN_STATUS = 'openwebrxListenStatus',
@@ -216,7 +217,7 @@ export const SystemStatusSchema = z.object({
   /** 当前电台调制模式（语音模式下使用，如 USB/LSB/FM/AM） */
   currentRadioMode: z.string().optional(),
   /** 引擎状态机当前状态 */
-  engineState: z.enum(['idle', 'waking', 'starting', 'running', 'stopping']).optional(),
+  engineState: z.enum(['idle', 'starting', 'running', 'stopping']).optional(),
   /** 引擎状态机上下文的精简投影 */
   engineContext: z.object({
     error: z.string().optional(),
@@ -1490,6 +1491,7 @@ export interface DigitalRadioEngineEvents {
     data?: unknown;
   }) => void;
   pluginPanelMeta: (data: import('./plugin.schema.js').PluginPanelMetaPayload) => void;
+  pluginPanelContributionsChanged: (data: import('./plugin.schema.js').PluginUIPanelContributionGroup) => void;
 
   // 内部子系统间通信事件（不通过 WebSocket 广播，用于 engine emitter 内部编排）
   encodeStart: (slotInfo: z.infer<typeof SlotInfoSchema>) => void;