@tx5dr/contracts 1.2.0

package/src/schema/realtime.schema.ts

@@ -0,0 +1,262 @@
+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 type RealtimeTransportKind = z.infer<typeof RealtimeTransportKindSchema>;
+
+export const RealtimeSessionDirectionSchema = z.enum(['recv', 'send']);
+export type RealtimeSessionDirection = z.infer<typeof RealtimeSessionDirectionSchema>;
+
+export const RealtimeConnectivityErrorCodeSchema = z.enum([
+  'TOKEN_REQUEST_FAILED',
+  'SIGNALING_UNREACHABLE',
+  'PUBLIC_URL_MISCONFIGURED',
+  'ICE_CONNECTION_FAILED',
+  'NO_AUDIO_TRACK',
+  'AUDIO_PLAYBACK_BLOCKED',
+  'SESSION_EXPIRED_OR_INVALID',
+  'MEDIA_DEVICE_PERMISSION_DENIED',
+  'UNKNOWN_REALTIME_ERROR',
+]);
+export type RealtimeConnectivityErrorCode = z.infer<typeof RealtimeConnectivityErrorCodeSchema>;
+
+export const RealtimeConnectivityHintsSchema = z.object({
+  signalingUrl: z.string(),
+  signalingPort: z.number().int().positive(),
+  rtcTcpPort: z.number().int().positive(),
+  udpPortRange: z.string(),
+  publicUrlOverrideActive: z.boolean(),
+});
+export type RealtimeConnectivityHints = z.infer<typeof RealtimeConnectivityHintsSchema>;
+
+export const RealtimeConnectivityIssueSchema = z.object({
+  code: RealtimeConnectivityErrorCodeSchema,
+  scope: RealtimeScopeSchema,
+  stage: z.enum(['token', 'connect', 'publish', 'subscribe', 'runtime']),
+  userMessage: z.string(),
+  suggestions: z.array(z.string()),
+  technicalDetails: z.string().optional(),
+  context: z.record(z.string()).optional(),
+});
+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,
+  previewSessionId: z.string().optional(),
+  transportOverride: RealtimeTransportKindSchema.optional(),
+});
+
+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,
+  url: z.string(),
+  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>;
+
+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>;
+
+export const RealtimeSessionResponseSchema = z.object({
+  scope: RealtimeScopeSchema,
+  direction: RealtimeSessionDirectionSchema,
+  preferredTransport: RealtimeTransportKindSchema,
+  effectiveTransportPolicy: RealtimeTransportPolicySchema,
+  selectionReason: z.enum([
+    'client-override',
+    'server-policy',
+    'bridge-unhealthy',
+    'livekit-disabled',
+    'runtime-unavailable',
+    'default-livekit',
+  ]),
+  forcedCompatibilityMode: z.boolean(),
+  offers: z.array(RealtimeTransportOfferSchema).min(1),
+  connectivityHints: RealtimeConnectivityHintsSchema,
+});
+
+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(),
+});
+
+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 type RealtimeCredentialStatus = z.infer<typeof RealtimeCredentialStatusSchema>;
+
+export const RealtimeSettingsRuntimeSchema = z.object({
+  liveKitEnabled: z.boolean(),
+  connectivityHints: RealtimeConnectivityHintsSchema,
+  radioReceiveTransport: RealtimeTransportKindSchema,
+  radioBridgeHealthy: z.boolean(),
+  radioBridgeIssueCode: RealtimeConnectivityErrorCodeSchema.nullable(),
+  credentialStatus: RealtimeCredentialStatusSchema,
+});
+
+export type RealtimeSettingsRuntime = z.infer<typeof RealtimeSettingsRuntimeSchema>;
+
+export const RealtimeSettingsResponseDataSchema = RealtimeSettingsSchema.extend({
+  runtime: RealtimeSettingsRuntimeSchema.optional(),
+});
+
+export type RealtimeSettingsResponseData = z.infer<typeof RealtimeSettingsResponseDataSchema>;
+
+export const RealtimeSourceStatsSchema = z.object({
+  latencyMs: z.number(),
+  bufferFillPercent: z.number(),
+  isActive: z.boolean(),
+  audioLevel: z.number().optional(),
+  droppedSamples: z.number().optional(),
+  sampleRate: z.number(),
+});
+
+export type RealtimeSourceStats = z.infer<typeof RealtimeSourceStatsSchema>;
+
+export const RealtimeStatsRequestSchema = z.object({
+  scope: RealtimeScopeSchema,
+  previewSessionId: z.string().optional(),
+});
+
+export type RealtimeStatsRequest = z.infer<typeof RealtimeStatsRequestSchema>;
+
+export const RealtimeStatsResponseSchema = z.object({
+  scope: RealtimeScopeSchema,
+  previewSessionId: z.string().nullable().optional(),
+  source: RealtimeSourceStatsSchema.nullable(),
+  transport: RealtimeTransportKindSchema.nullable().optional(),
+});
+
+export type RealtimeStatsResponse = z.infer<typeof RealtimeStatsResponseSchema>;
+
+export const RealtimeVoiceTxMetricWindowSchema = z.object({
+  current: z.number().nullable(),
+  rolling: z.number().nullable(),
+  peak: z.number().nullable(),
+});
+
+export type RealtimeVoiceTxMetricWindow = z.infer<typeof RealtimeVoiceTxMetricWindowSchema>;
+
+export const RealtimeVoiceTxBottleneckStageSchema = z.enum([
+  'client-capture',
+  'transport',
+  'server-ingress',
+  'server-queue',
+  'server-output',
+]);
+
+export type RealtimeVoiceTxBottleneckStage = z.infer<typeof RealtimeVoiceTxBottleneckStageSchema>;
+
+export const RealtimeVoiceTxSummarySchema = z.object({
+  active: z.boolean(),
+  transport: RealtimeTransportKindSchema.nullable(),
+  bottleneckStage: RealtimeVoiceTxBottleneckStageSchema.nullable(),
+  startedAt: z.number().nullable(),
+  updatedAt: z.number().nullable(),
+  clientId: z.string().nullable(),
+  label: z.string().nullable(),
+});
+
+export type RealtimeVoiceTxSummary = z.infer<typeof RealtimeVoiceTxSummarySchema>;
+
+export const RealtimeVoiceTxTransportStatsSchema = z.object({
+  receivedFrames: z.number().int().nonnegative(),
+  sequenceGaps: z.number().int().nonnegative(),
+  lastSequence: z.number().int().nullable(),
+  clientToServerMs: RealtimeVoiceTxMetricWindowSchema,
+});
+
+export type RealtimeVoiceTxTransportStats = z.infer<typeof RealtimeVoiceTxTransportStatsSchema>;
+
+export const RealtimeVoiceTxServerIngressStatsSchema = z.object({
+  frameIntervalMs: RealtimeVoiceTxMetricWindowSchema,
+  queueDepthFrames: z.number().int().nonnegative(),
+  queuedAudioMs: z.number().nonnegative(),
+  droppedFrames: z.number().int().nonnegative(),
+});
+
+export type RealtimeVoiceTxServerIngressStats = z.infer<typeof RealtimeVoiceTxServerIngressStatsSchema>;
+
+export const RealtimeVoiceTxServerOutputStatsSchema = z.object({
+  resampleMs: RealtimeVoiceTxMetricWindowSchema,
+  queueWaitMs: RealtimeVoiceTxMetricWindowSchema,
+  writeMs: RealtimeVoiceTxMetricWindowSchema,
+  endToEndMs: RealtimeVoiceTxMetricWindowSchema,
+  outputBufferedMs: RealtimeVoiceTxMetricWindowSchema,
+  outputSampleRate: z.number().nullable(),
+  outputBufferSize: z.number().nullable(),
+  writeFailures: z.number().int().nonnegative(),
+});
+
+export type RealtimeVoiceTxServerOutputStats = z.infer<typeof RealtimeVoiceTxServerOutputStatsSchema>;
+
+export const RealtimeVoiceTxStatsResponseSchema = z.object({
+  scope: RealtimeScopeSchema,
+  summary: RealtimeVoiceTxSummarySchema,
+  transport: RealtimeVoiceTxTransportStatsSchema,
+  serverIngress: RealtimeVoiceTxServerIngressStatsSchema,
+  serverOutput: RealtimeVoiceTxServerOutputStatsSchema,
+});
+
+export type RealtimeVoiceTxStatsResponse = z.infer<typeof RealtimeVoiceTxStatsResponseSchema>;

package/src/schema/rigctld.schema.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/**
+ * rigctld-compatible TCP bridge configuration.
+ *
+ * Disabled by default — opening a TCP port that accepts CAT control without
+ * authentication is a sensitive default, so users must opt in.
+ */
+export const RigctldBridgeConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  bindAddress: z.string().default('0.0.0.0'),
+  port: z.number().int().min(1).max(65535).default(4532),
+  /**
+   * When true (default), the bridge rejects every write command
+   * (`F`/`M`/`T`/`S`/`L`/`set_*`) with `RPRT -11` and only allows reads.
+   * Covers the safe "N1MM records QSOs while the operator tunes manually"
+   * workflow. Disable only when you need software like N1MM / WSJT-X to
+   * actively control the rig (set frequency, PTT, split).
+   */
+  readOnly: z.boolean().default(true),
+});
+
+export type RigctldBridgeConfig = z.infer<typeof RigctldBridgeConfigSchema>;
+
+export const DEFAULT_RIGCTLD_BRIDGE_CONFIG: RigctldBridgeConfig = {
+  enabled: false,
+  bindAddress: '0.0.0.0',
+  port: 4532,
+  readOnly: true,
+};
+
+/** Per-connection client snapshot used by the status API and UI. */
+export const RigctldClientSnapshotSchema = z.object({
+  id: z.number().int(),
+  peer: z.string(),
+  connectedAt: z.number().int(),
+  lastCommand: z.string().optional(),
+  lastCommandAt: z.number().int().optional(),
+});
+
+export type RigctldClientSnapshot = z.infer<typeof RigctldClientSnapshotSchema>;
+
+export const RigctldStatusSchema = z.object({
+  config: RigctldBridgeConfigSchema,
+  running: z.boolean(),
+  address: z.object({ host: z.string(), port: z.number().int() }).optional(),
+  clients: z.array(RigctldClientSnapshotSchema),
+  error: z.string().optional(),
+});
+
+export type RigctldStatus = z.infer<typeof RigctldStatusSchema>;

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

@@ -0,0 +1,26 @@
+/**
+ * 服务端推送的文本消息 key 枚举
+ * 前端根据 key 查找对应翻译，兜底显示 title/text 原始值
+ */
+export enum ServerMessageKey {
+  /** 时序告警：操作员自动决策可能赶不上此发射时隙的编码 */
+  TIMING_ALERT = 'timingAlert',
+
+  /** 电台已连接 */
+  RADIO_CONNECTED = 'radioConnected',
+
+  /** QSO 已记录 */
+  QSO_LOGGED = 'qsoLogged',
+
+  /** QSO 已更新 */
+  QSO_UPDATED = 'qsoUpdated',
+
+  /** 实时语音连接异常 */
+  REALTIME_CONNECTIVITY_WARNING = 'realtimeConnectivityWarning',
+
+  /** 服务端实时语音桥接异常 */
+  REALTIME_BRIDGE_DOWN = 'realtimeBridgeDown',
+
+  /** 实时语音链路无音频数据 */
+  REALTIME_NO_AUDIO = 'realtimeNoAudio',
+}

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

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { DxccStatusSchema, SubdivisionConfidenceSchema } from './qso.schema.js';
+
+/**
+ * 时隙周期（偶数奇数）
+ */
+
+/**
+ * 时隙信息
+ */
+export const SlotInfoSchema = z.object({
+  /** 时隙唯一标识符 */
+  id: z.string(),
+  /** 时隙开始时间戳（毫秒） */
+  startMs: z.number(),
+  /** 相位偏移（毫秒） */
+  phaseMs: z.number(),
+  /** 时钟漂移（毫秒） */
+  driftMs: z.number().default(0),
+  /** 时隙周期号 */
+  cycleNumber: z.number(),
+  /** 时隙UTC时间戳（秒） */
+  utcSeconds: z.number(),
+  /** 时隙类型（FT8/FT4） */
+  mode: z.string()
+});
+
+export type SlotInfo = z.infer<typeof SlotInfoSchema>;
+
+/**
+ * 基于日志本的消息分析结果
+ */
+export const LogbookAnalysisSchema = z.object({
+  /** 是否为新呼号（之前没有通联过） */
+  isNewCallsign: z.boolean().optional(),
+  /** 是否为新 DXCC 实体（之前没有通联过该实体） */
+  isNewDxccEntity: z.boolean().optional(),
+  /** 是否为该波段的新 DXCC 实体 */
+  isNewBandDxccEntity: z.boolean().optional(),
+  /** 是否为已确认 DXCC */
+  isConfirmedDxcc: z.boolean().optional(),
+  /** 是否为新网格（之前没有通联过此网格） */
+  isNewGrid: z.boolean().optional(),
+  /** 解析出的呼号（如果有） */
+  callsign: z.string().optional(),
+  /** 解析出的网格（如果有） */
+  grid: z.string().optional(),
+  /** 解析出的前缀（如果有） */
+  prefix: z.string().optional(),
+  /** 美国 subdivision code（州/属地），仅在可解析时提供 */
+  state: z.string().optional(),
+  /** subdivision 置信度 */
+  stateConfidence: SubdivisionConfidenceSchema.optional(),
+  /** DXCC 实体编号 */
+  dxccId: z.number().int().positive().optional(),
+  /** DXCC 实体名 */
+  dxccEntity: z.string().optional(),
+  /** 实体状态 */
+  dxccStatus: DxccStatusSchema.optional(),
+});
+
+export type LogbookAnalysis = z.infer<typeof LogbookAnalysisSchema>;
+
+/**
+ * FT8 帧数据
+ */
+export const FrameMessageSchema = z.object({
+  /** 信号强度 (dB) */
+  snr: z.number(),
+  /** 频率偏移 (Hz) */
+  freq: z.number(),
+  /** 时间偏移 (秒) */
+  dt: z.number(),
+  /** 解码消息 */
+  message: z.string(),
+  /** 置信度 0-1 */
+  confidence: z.number().min(0).max(1).default(1.0),
+  /** 基于日志本的分析结果（可选，仅在客户端定制化数据中提供） */
+  logbookAnalysis: LogbookAnalysisSchema.optional(),
+  /** 操作员ID（可选，仅 TX 帧使用，用于多操作员覆盖识别） */
+  operatorId: z.string().optional()
+});
+
+export type FrameMessage = z.infer<typeof FrameMessageSchema>;
+
+/**
+ * 解码请求，用于SlotScheduler内部
+ */
+export const DecodeRequestSchema = z.object({
+  /** 关联的时隙ID */
+  slotId: z.string(),
+  /** 子窗口索引 */
+  windowIdx: z.number().int().nonnegative(),
+  /** PCM 音频数据 */
+  pcm: z.instanceof(ArrayBuffer),
+  /** 采样率 */
+  sampleRate: z.number().positive().default(12000),
+  /** 请求时间戳 */
+  timestamp: z.number().default(() => Date.now()),
+  /** 窗口时间偏移（毫秒） */
+  windowOffsetMs: z.number().default(0)
+});
+
+export type DecodeRequest = z.infer<typeof DecodeRequestSchema>;
+
+/**
+ * 解码结果，用于SlotScheduler内部
+ */
+export const DecodeResultSchema = z.object({
+  /** 关联的时隙ID */
+  slotId: z.string(),
+  /** 子窗口索引 */
+  windowIdx: z.number().int().nonnegative(),
+  /** 解码出的帧数据 */
+  frames: z.array(FrameMessageSchema),
+  /** 结果时间戳 */
+  timestamp: z.number().default(() => Date.now()),
+  /** 处理耗时（毫秒） */
+  processingTimeMs: z.number().nonnegative().default(0),
+  /** 错误信息（如果有） */
+  error: z.string().optional(),
+  /** 窗口时间偏移（毫秒） */
+  windowOffsetMs: z.number().default(0)
+});
+
+export type DecodeResult = z.infer<typeof DecodeResultSchema>;
+
+/**
+ * 时隙封装信息（去重和多次解码取优）
+ */
+export const SlotPackSchema = z.object({
+  /** 时隙ID */
+  slotId: z.string(),
+  /** 时隙开始时间戳（毫秒） */
+  startMs: z.number(),
+  /** 时隙结束时间戳（毫秒） */
+  endMs: z.number(),
+  /** 去重后的最优解码结果 */
+  frames: z.array(FrameMessageSchema),
+  /** 解码统计信息 */
+  stats: z.object({
+    /** 总解码次数 */
+    totalDecodes: z.number().default(0),
+    /** 成功解码次数 */
+    successfulDecodes: z.number().default(0),
+    /** 去重前的总帧数 */
+    totalFramesBeforeDedup: z.number().default(0),
+    /** 去重后的帧数 */
+    totalFramesAfterDedup: z.number().default(0),
+    /** 最后更新时间戳 */
+    lastUpdated: z.number().default(() => Date.now())
+  }).default({}),
+  /** 解码历史（用于调试） */
+  decodeHistory: z.array(z.object({
+    windowIdx: z.number(),
+    timestamp: z.number(),
+    frameCount: z.number(),
+    processingTimeMs: z.number()
+  })).default([])
+});
+
+export type SlotPack = z.infer<typeof SlotPackSchema>;

package/src/schema/spectrum.schema.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+
+export const SpectrumKindSchema = z.enum(['audio', 'radio-sdr', 'openwebrx-sdr']);
+export type SpectrumKind = z.infer<typeof SpectrumKindSchema>;
+
+export const SpectrumDisplayModeSchema = z.enum(['center', 'fixed', 'scroll-center', 'scroll-fixed', 'unknown']);
+export type SpectrumDisplayMode = z.infer<typeof SpectrumDisplayModeSchema>;
+
+export const SpectrumSessionSourceModeSchema = z.enum([
+  'baseband',
+  'center',
+  'fixed',
+  'scroll-center',
+  'scroll-fixed',
+  'full',
+  'detail',
+  'unknown',
+]);
+export type SpectrumSessionSourceMode = z.infer<typeof SpectrumSessionSourceModeSchema>;
+
+export const SpectrumSessionFrequencyRangeModeSchema = z.enum([
+  'baseband',
+  'absolute-center',
+  'absolute-fixed',
+  'absolute-windowed',
+]);
+export type SpectrumSessionFrequencyRangeMode = z.infer<typeof SpectrumSessionFrequencyRangeModeSchema>;
+
+export const SpectrumFrequencyRangeSchema = z.object({
+  min: z.number(),
+  max: z.number(),
+});
+
+export const SpectrumBinaryFormatSchema = z.object({
+  type: z.literal('int16'),
+  length: z.number().int().positive(),
+  scale: z.number().optional(),
+  offset: z.number().optional(),
+});
+
+export const SpectrumBinaryDataSchema = z.object({
+  data: z.string(),
+  format: SpectrumBinaryFormatSchema,
+});
+
+export const SpectrumFrameMetaSchema = z.object({
+  sourceBinCount: z.number().int().positive(),
+  displayBinCount: z.number().int().positive(),
+  centerFrequency: z.number().optional(),
+  spanHz: z.number().optional(),
+  profileId: z.string().nullable().optional(),
+  radioModel: z.string().optional(),
+});
+
+export const SpectrumFrameSchema = z.object({
+  timestamp: z.number(),
+  kind: SpectrumKindSchema,
+  frequencyRange: SpectrumFrequencyRangeSchema,
+  binaryData: SpectrumBinaryDataSchema,
+  meta: SpectrumFrameMetaSchema,
+});
+
+export const SpectrumSourceAvailabilitySchema = z.object({
+  kind: SpectrumKindSchema,
+  supported: z.boolean(),
+  available: z.boolean(),
+  defaultSelected: z.boolean(),
+  reason: z.string().optional(),
+  sourceBinCount: z.number().int().positive().nullable().optional(),
+  displayBinCount: z.number().int().positive(),
+  supportsWaterfall: z.boolean(),
+  frequencyRangeMode: z.enum(['absolute', 'baseband']),
+});
+
+export const SpectrumCapabilitiesSchema = z.object({
+  profileId: z.string().nullable(),
+  defaultKind: SpectrumKindSchema,
+  sources: z.array(SpectrumSourceAvailabilitySchema),
+});
+
+export const SpectrumSessionControlIdSchema = z.enum([
+  'zoom-step',
+  'digital-window-toggle',
+  'openwebrx-detail-toggle',
+  'viewport-zoom',
+]);
+export type SpectrumSessionControlId = z.infer<typeof SpectrumSessionControlIdSchema>;
+
+export const SpectrumSessionControlActionSchema = z.enum(['in', 'out', 'toggle']);
+export type SpectrumSessionControlAction = z.infer<typeof SpectrumSessionControlActionSchema>;
+
+export const SpectrumSessionControlKindSchema = z.enum(['server', 'local']);
+export type SpectrumSessionControlKind = z.infer<typeof SpectrumSessionControlKindSchema>;
+
+export const SpectrumSessionControlSchema = z.object({
+  id: SpectrumSessionControlIdSchema,
+  action: SpectrumSessionControlActionSchema,
+  kind: SpectrumSessionControlKindSchema,
+  visible: z.boolean(),
+  enabled: z.boolean(),
+  active: z.boolean(),
+  pending: z.boolean(),
+});
+export type SpectrumSessionControl = z.infer<typeof SpectrumSessionControlSchema>;
+
+export const SpectrumSessionVoiceStateSchema = z.object({
+  radioMode: z.string().nullable(),
+  bandwidthLabel: z.string().nullable(),
+  occupiedBandwidthHz: z.number().nullable(),
+  offsetModel: z.enum(['upper', 'lower', 'symmetric']).nullable(),
+});
+export type SpectrumSessionVoiceState = z.infer<typeof SpectrumSessionVoiceStateSchema>;
+
+export const SpectrumSessionPresetMarkerSchema = z.object({
+  id: z.string(),
+  frequency: z.number(),
+  label: z.string(),
+  description: z.string().nullable(),
+  clickable: z.boolean(),
+});
+export type SpectrumSessionPresetMarker = z.infer<typeof SpectrumSessionPresetMarkerSchema>;
+
+export const SpectrumSessionInteractionStateSchema = z.object({
+  showTxMarkers: z.boolean(),
+  showRxMarkers: z.boolean(),
+  canDragTx: z.boolean(),
+  canRightClickSetFrequency: z.boolean(),
+  canDoubleClickSetFrequency: z.boolean(),
+  canDragFrequency: z.boolean(),
+  frequencyGestureTarget: z.enum(['operator-tx', 'radio-frequency']).nullable(),
+  frequencyStepHz: z.number().int().positive().nullable(),
+  presetMarkers: z.array(SpectrumSessionPresetMarkerSchema),
+  canDragVoiceOverlay: z.boolean(),
+  showVoiceOverlay: z.boolean(),
+  canLocalViewportZoom: z.boolean(),
+  canLocalViewportPan: z.boolean(),
+  supportsManualRange: z.boolean(),
+  supportsAutoRange: z.boolean(),
+  defaultRangeMode: z.enum(['auto', 'manual']).nullable(),
+});
+export type SpectrumSessionInteractionState = z.infer<typeof SpectrumSessionInteractionStateSchema>;
+
+export const SpectrumSessionStateSchema = z.object({
+  kind: SpectrumKindSchema.nullable(),
+  sourceMode: SpectrumSessionSourceModeSchema,
+  frequencyRangeMode: SpectrumSessionFrequencyRangeModeSchema,
+  displayRange: SpectrumFrequencyRangeSchema.nullable(),
+  centerFrequency: z.number().nullable(),
+  currentRadioFrequency: z.number().nullable(),
+  standardFrequencyHz: z.number().nullable(),
+  edgeLowHz: z.number().nullable(),
+  edgeHighHz: z.number().nullable(),
+  spanHz: z.number().nullable(),
+  voice: SpectrumSessionVoiceStateSchema,
+  interaction: SpectrumSessionInteractionStateSchema,
+  controls: z.array(SpectrumSessionControlSchema),
+});
+export type SpectrumSessionState = z.infer<typeof SpectrumSessionStateSchema>;
+
+export type SpectrumFrequencyRange = z.infer<typeof SpectrumFrequencyRangeSchema>;
+export type SpectrumBinaryFormat = z.infer<typeof SpectrumBinaryFormatSchema>;
+export type SpectrumBinaryData = z.infer<typeof SpectrumBinaryDataSchema>;
+export type SpectrumFrameMeta = z.infer<typeof SpectrumFrameMetaSchema>;
+export type SpectrumFrame = z.infer<typeof SpectrumFrameSchema>;
+export type SpectrumSourceAvailability = z.infer<typeof SpectrumSourceAvailabilitySchema>;
+export type SpectrumCapabilities = z.infer<typeof SpectrumCapabilitiesSchema>;