@tx5dr/contracts 2.0.0 → 2.5.0

package/src/schema/qso.schema.ts

@@ -49,6 +49,61 @@ export const SubdivisionConfidenceSchema = z.enum([
   'low',
 ]);
 
+/** Maximum UTF-8 JSON size of contest-owned data persisted with one QSO. */
+export const CONTEST_QSO_ENVELOPE_MAX_BYTES = 8 * 1024;
+
+const ContestQsoExchangeSchema = z.record(z.string(), z.string());
+const ContestQsoAnnotationValueSchema = z.union([z.string(), z.number().finite(), z.boolean()]);
+
+function durableContestQsoJson(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>\u007f-\uffff]/g, character => (
+    `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`
+  ));
+}
+
+/**
+ * Versioned contest facts that must be committed atomically with their QSO.
+ *
+ * The shape is deliberately shallow and bounded. Contest plugins may choose
+ * their exchange and annotation keys, but cannot persist arbitrary object
+ * graphs or binary payloads in the logbook record.
+ */
+export const ContestQsoEnvelopeSchema = z.object({
+  schemaVersion: z.literal(1),
+  contestId: z.string().min(1),
+  editionId: z.string().min(1),
+  rulesetVersion: z.string().min(1),
+  sent: ContestQsoExchangeSchema,
+  received: ContestQsoExchangeSchema,
+  annotations: z.record(z.string(), ContestQsoAnnotationValueSchema).optional(),
+}).strict().superRefine((value, context) => {
+  if (new TextEncoder().encode(durableContestQsoJson(value)).byteLength > CONTEST_QSO_ENVELOPE_MAX_BYTES) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Contest QSO envelope must not exceed ${CONTEST_QSO_ENVELOPE_MAX_BYTES} UTF-8 JSON bytes`,
+    });
+  }
+});
+
+/**
+ * Serialize a validated contest envelope as ASCII-only JSON for durable ADIF
+ * private fields. Escaping non-ASCII and angle brackets keeps legacy string
+ * ADIF readers byte-safe without changing the decoded data.
+ */
+export function serializeContestQsoEnvelope(value: ContestQsoEnvelope): string {
+  return durableContestQsoJson(ContestQsoEnvelopeSchema.parse(value));
+}
+
+/** Parse and validate an envelope read from a durable private field. */
+export function parseContestQsoEnvelope(value: string): ContestQsoEnvelope | undefined {
+  try {
+    const parsed = ContestQsoEnvelopeSchema.safeParse(JSON.parse(value));
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // 操作配置
 export const OperatorConfigSchema = z.object({
   id: z.string(),
@@ -60,6 +115,7 @@ export const OperatorConfigSchema = z.object({
   maxQSOTimeoutCycles: z.number(),
   maxCallAttempts: z.number(),
   frequency: z.number(),
+  maxConcurrentStreams: z.number().int().min(1).max(5).optional(),
   autoResumeCQAfterFail: z.boolean().default(false),
   autoResumeCQAfterSuccess: z.boolean().default(false),
   replyToWorkedStations: z.boolean().default(false),
@@ -112,6 +168,8 @@ export const QSORecordSchema = z.object({
   reportReceived: z.string().optional(), // 接收的信号报告
   messageHistory: z.array(z.string()), // 内部消息历史（FT8 等数字模式）
   comment: z.string().optional(), // 标准 ADIF COMMENT 字段
+  contestId: z.string().optional(), // ADIF CONTEST_ID
+  contestEntry: ContestQsoEnvelopeSchema.optional(), // TX-5DR atomic contest facts
   myCallsign: z.string().optional(), // 我的呼号（操作员呼号）
   myGrid: z.string().optional(), // 我的网格定位（操作员网格）
   qth: z.string().optional(), // 对方 QTH（地点，语音通联常用）
@@ -148,8 +206,19 @@ export const QSORecordSchema = z.object({
 
   // 附注（对应 ADIF NOTES 字段）
   notes: z.string().optional(),
+}).superRefine((value, context) => {
+  if (value.contestId && value.contestEntry && value.contestId !== value.contestEntry.contestId) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['contestEntry', 'contestId'],
+      message: 'contestEntry.contestId must match contestId',
+    });
+  }
 });
 
+/** Host persistence behavior for an automatically completed QSO. */
+export const QSOPersistencePolicySchema = z.enum(['merge-nearby', 'preserve-distinct']);
+
 // 策略执行结果
 export const StrategiesResultSchema = z.object({
   stop: z.boolean().optional(),
@@ -169,6 +238,7 @@ export type DxccStatus = z.infer<typeof DxccStatusSchema>;
 export type DxccSource = z.infer<typeof DxccSourceSchema>;
 export type DxccConfidence = z.infer<typeof DxccConfidenceSchema>;
 export type QSOContext = z.infer<typeof QSOContextSchema>;
+export type ContestQsoEnvelope = z.infer<typeof ContestQsoEnvelopeSchema>;
 
 /**
  * Canonical persisted QSO record used by TX-5DR logbooks and plugin hooks.
@@ -177,4 +247,5 @@ export type QSOContext = z.infer<typeof QSOContextSchema>;
  * logbook queries.
  */
 export type QSORecord = z.infer<typeof QSORecordSchema>;
+export type QSOPersistencePolicy = z.infer<typeof QSOPersistencePolicySchema>;
 export type StrategiesResult = z.infer<typeof StrategiesResultSchema>; 

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

@@ -295,6 +295,7 @@ export const CAPABILITY_IDS = [
   'spectrum_rbw',
   'spectrum_during_tx',
   'spectrum_center_type',
+  'tci_iq_sample_rate',
   'dcs_code',
 ] as const;
 

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { HamlibConfigSchema } from './radio.schema.js';
 import { AudioDeviceSettingsSchema } from './audio.schema.js';
+import { TxAudioInputSourcePolicySchema } from './tx-audio-input.schema.js';
 
 /**
  * Radio Profile Schema
@@ -14,9 +15,13 @@ export const RadioProfileSchema = z.object({
   radio: HamlibConfigSchema,               // 电台连接配置
   audio: AudioDeviceSettingsSchema,        // 音频设备配置
   audioLockedToRadio: z.boolean(),         // ICOM WLAN = true，音频由电台决定
+  /** Optional policy for the radio's physical TX audio input selector. */
+  txAudioInputSource: TxAudioInputSourcePolicySchema.optional(),
   createdAt: z.number(),
   updatedAt: z.number(),
   description: z.string().optional(),
+  isVirtual: z.boolean().optional(),
+  readOnly: z.boolean().optional(),
 });
 
 export type RadioProfile = z.infer<typeof RadioProfileSchema>;
@@ -41,6 +46,7 @@ export const UpdateProfileRequestSchema = z.object({
   radio: HamlibConfigSchema.optional(),
   audio: AudioDeviceSettingsSchema.optional(),
   audioLockedToRadio: z.boolean().optional(),
+  txAudioInputSource: TxAudioInputSourcePolicySchema.optional(),
   description: z.string().optional(),
 });
 
@@ -52,6 +58,7 @@ export type UpdateProfileRequest = z.infer<typeof UpdateProfileRequestSchema>;
 export const ProfileListResponseSchema = z.object({
   profiles: z.array(RadioProfileSchema),
   activeProfileId: z.string().nullable(),
+  hasConfiguredProfiles: z.boolean().optional().default(false),
 });
 
 export type ProfileListResponse = z.infer<typeof ProfileListResponseSchema>;

package/src/schema/radio.schema.ts

@@ -14,15 +14,21 @@ export const ToneSquelchModeSchema = z.enum(['none', 'ctcss', 'dcs']);
 /** Saved dial-frequency preset with band, digital mode and radio modulation. */
 export const PresetFrequencySchema = z.object({
   band: z.string(),
-  mode: z.string(), // 协议模式，如 FT8, FT4
+  mode: z.string(), // 协议模式，如 FT8、FT4、VOICE、SSTV、FAX
   radioMode: z.string().optional(), // 电台调制模式，如 USB, LSB, AM, FM
-  frequency: z.number(),
+  frequency: z.number().int().positive().max(1_000_000_000), // 拨盘频率，单位 Hz（MHz 输入最多 6 位小数）
   description: z.string().optional(),
   repeaterShift: RepeaterShiftSchema.optional(), // 中继差频方向，默认 none
   repeaterOffsetHz: z.number().int().positive().optional(), // 中继偏移，单位 Hz
   toneMode: ToneSquelchModeSchema.optional(), // 哑音类型，默认 none
   ctcssToneTenthsHz: z.number().int().positive().optional(), // CTCSS，单位 0.1Hz
   dcsCode: z.number().int().positive().optional(), // DCS 码
+  region: z.enum(['global', 'iaru1', 'iaru2', 'iaru3']).optional(),
+  imagePurpose: z.enum(['activity', 'iss', 'weatherfax']).optional(),
+  audioCenterHz: z.number().int().positive().optional(),
+  assignedFrequency: z.number().int().positive().max(1_000_000_000).optional(),
+  faxEmission: z.enum(['J3C', 'F3C', 'F1C']).optional(),
+  carrierFrequency: z.number().positive().optional(), // Legacy field; use assignedFrequency for published WEFAX channels.
 }).superRefine((preset, ctx) => {
   const isVoiceFmPreset = preset.mode === 'VOICE' && preset.radioMode?.toUpperCase() === 'FM';
   const hasRepeaterDuplex = preset.repeaterShift === 'minus' || preset.repeaterShift === 'plus';
@@ -195,9 +201,27 @@ export const IcomWlanConfigSchema = z.object({
 /**
  * TCI / SunSDR 连接配置Schema
  */
+const TciWebSocketUrlSchema = z.string().url()
+  .refine((value) => /^wss?:\/\//i.test(value), 'TCI URL must use ws:// or wss://')
+  .refine((value) => {
+    const parsed = new URL(value);
+    return !parsed.username && !parsed.password;
+  }, 'TCI URL must not contain credentials');
+
 export const TciConfigSchema = z.object({
   host: z.string().default('127.0.0.1'),
   port: z.number().int().min(1).max(65535).default(40001),
+  url: TciWebSocketUrlSchema.optional(),
+  dialect: z.enum([
+    'auto',
+    'expertsdr-1.4',
+    'expertsdr-1.5-1.8',
+    'expertsdr-1.9-2.0',
+    'aethersdr-1.5',
+    'thetis-2.0',
+    'generic-observed',
+  ]).default('auto'),
+  autoDiscoverPorts: z.boolean().default(true),
   receiver: z.number().int().min(0).default(0),
   trx: z.number().int().min(0).default(0),
   vfo: z.number().int().min(0).default(0),
@@ -384,6 +408,7 @@ export const SerialPortsResponseSchema = z.object({
 export const TestResponseSchema = z.object({
   success: z.boolean(),
   message: z.string().optional(),
+  details: z.record(z.unknown()).optional(),
 });
 
 /**
@@ -497,6 +522,14 @@ export const CustomFrequencyPresetsSchema = z.object({
   presets: z.array(PresetFrequencySchema).min(1),
 });
 
+/** TCI receiver DDS/IQ center-frequency control request. */
+export const DdsFrequencyRequestSchema = z.object({
+  frequency: z.number().finite().nonnegative(),
+  receiver: z.number().int().nonnegative().optional(),
+});
+
+export type DdsFrequencyRequest = z.infer<typeof DdsFrequencyRequestSchema>;
+
 // 导出类型
 export type CustomFrequencyPresets = z.infer<typeof CustomFrequencyPresetsSchema>;
 export type PresetFrequency = z.infer<typeof PresetFrequencySchema>;

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

@@ -96,7 +96,8 @@ export const FrameMessageSchema = z.object({
   /** 基于日志本的分析结果（可选，仅在客户端定制化数据中提供） */
   logbookAnalysis: LogbookAnalysisSchema.optional(),
   /** 操作员ID（可选，仅 TX 帧使用，用于多操作员覆盖识别） */
-  operatorId: z.string().optional()
+  operatorId: z.string().optional(),
+  streamId: z.string().optional(),
 });
 
 export type FrameMessage = z.infer<typeof FrameMessageSchema>;

package/src/schema/spectrum-config.schema.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+
+export const SpectrumPresetIdSchema = z.enum(['responsive', 'balanced', 'fine']);
+export const SpectrumPresetSchema = z.enum(['responsive', 'balanced', 'fine', 'custom']);
+export type SpectrumPreset = z.infer<typeof SpectrumPresetSchema>;
+export type SpectrumPresetId = z.infer<typeof SpectrumPresetIdSchema>;
+
+export const SpectrumWindowFunctionSchema = z.enum([
+  'hann',
+  'hamming',
+  'blackman',
+  'blackmanHarris',
+  'none',
+]);
+export type SpectrumWindowFunction = z.infer<typeof SpectrumWindowFunctionSchema>;
+
+export const SpectrumFftSizeSchema = z.union([
+  z.literal(1024),
+  z.literal(2048),
+  z.literal(4096),
+  z.literal(8192),
+  z.literal(16384),
+]);
+
+export const SpectrumTargetSampleRateSchema = z.union([
+  z.literal(3000),
+  z.literal(4000),
+  z.literal(6000),
+  z.literal(8000),
+  z.literal(12000),
+]);
+
+export const SpectrumCustomSettingsSchema = z.object({
+  analysisIntervalMs: z.number().int().min(50).max(1000),
+  fftSize: SpectrumFftSizeSchema,
+  targetSampleRate: SpectrumTargetSampleRateSchema,
+  windowFunction: SpectrumWindowFunctionSchema,
+  haloReduce: z.boolean(),
+});
+export type SpectrumCustomSettings = z.infer<typeof SpectrumCustomSettingsSchema>;
+
+export const SpectrumRenderFrequencyRangeSchema = z.object({
+  min: z.number().finite(),
+  max: z.number().finite(),
+}).refine((range) => range.max > range.min, {
+  message: 'Spectrum frequency range maximum must be greater than minimum',
+  path: ['max'],
+});
+
+export const SpectrumRenderConfigSchema = z.object({
+  preset: SpectrumPresetSchema,
+  revision: z.number().int().nonnegative(),
+  analysisIntervalMs: z.number().int().positive(),
+  frameRateHz: z.number().positive(),
+  fftSize: z.number().int().positive(),
+  targetSampleRate: z.number().int().positive(),
+  fftWindowDurationMs: z.number().positive(),
+  frequencyResolutionHz: z.number().positive(),
+  frequencyRange: SpectrumRenderFrequencyRangeSchema,
+  displayBinCount: z.number().int().positive(),
+  windowFunction: SpectrumWindowFunctionSchema,
+  haloReduce: z.boolean(),
+  customSettings: SpectrumCustomSettingsSchema.optional(),
+});
+export type SpectrumRenderConfig = z.infer<typeof SpectrumRenderConfigSchema>;
+
+export const TciIqSampleRateSchema = z.number().int().positive();
+export type TciIqSampleRate = z.infer<typeof TciIqSampleRateSchema>;
+
+export const TciSpectrumSettingsSchema = z.object({
+  fftSize: z.union([
+    z.literal(4096), z.literal(8192), z.literal(16384), z.literal(32768), z.literal(65536),
+  ]),
+  displayBinCount: z.number().int().min(1024).max(16384),
+  analysisIntervalMs: z.number().int().min(20).max(1000),
+});
+export type TciSpectrumSettings = z.infer<typeof TciSpectrumSettingsSchema>;
+
+export const TciSpectrumSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  settings: TciSpectrumSettingsSchema,
+});
+export type TciSpectrumSettingsResponse = z.infer<typeof TciSpectrumSettingsResponseSchema>;
+
+export const TciIqSpectrumSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  configuredSampleRate: TciIqSampleRateSchema.nullable(),
+  appliedSampleRate: TciIqSampleRateSchema.nullable(),
+  supportedSampleRates: z.array(TciIqSampleRateSchema),
+});
+export type TciIqSpectrumSettingsResponse = z.infer<typeof TciIqSpectrumSettingsResponseSchema>;
+
+export const SpectrumPresetDefinitionSchema = SpectrumRenderConfigSchema.omit({
+  revision: true,
+});
+export type SpectrumPresetDefinition = z.infer<typeof SpectrumPresetDefinitionSchema>;
+
+export const SPECTRUM_PRESET_DEFINITIONS: Record<SpectrumPresetId, SpectrumPresetDefinition> = {
+  responsive: {
+    preset: 'responsive',
+    analysisIntervalMs: 100,
+    frameRateHz: 10,
+    fftSize: 2048,
+    targetSampleRate: 6000,
+    fftWindowDurationMs: (2048 / 6000) * 1000,
+    frequencyResolutionHz: 6000 / 2048,
+    frequencyRange: { min: 0, max: 3000 },
+    displayBinCount: 1025,
+    windowFunction: 'blackmanHarris',
+    haloReduce: false,
+  },
+  balanced: {
+    preset: 'balanced',
+    analysisIntervalMs: 150,
+    frameRateHz: 1000 / 150,
+    fftSize: 8192,
+    targetSampleRate: 6000,
+    fftWindowDurationMs: (8192 / 6000) * 1000,
+    frequencyResolutionHz: 6000 / 8192,
+    frequencyRange: { min: 0, max: 3000 },
+    displayBinCount: 4097,
+    windowFunction: 'blackmanHarris',
+    haloReduce: false,
+  },
+  fine: {
+    preset: 'fine',
+    analysisIntervalMs: 200,
+    frameRateHz: 5,
+    fftSize: 16384,
+    targetSampleRate: 6000,
+    fftWindowDurationMs: (16384 / 6000) * 1000,
+    frequencyResolutionHz: 6000 / 16384,
+    frequencyRange: { min: 0, max: 3000 },
+    displayBinCount: 8193,
+    windowFunction: 'blackmanHarris',
+    haloReduce: false,
+  },
+};
+
+export function getSpectrumPresetDefinition(preset: SpectrumPresetId): SpectrumPresetDefinition {
+  return { ...SPECTRUM_PRESET_DEFINITIONS[preset] };
+}
+
+export const SpectrumSettingsUpdateRequestSchema = z.discriminatedUnion('preset', [
+  z.object({ preset: SpectrumPresetIdSchema }),
+  z.object({ preset: z.literal('custom'), settings: SpectrumCustomSettingsSchema }),
+]);
+export type SpectrumSettingsUpdateRequest = z.infer<typeof SpectrumSettingsUpdateRequestSchema>;
+
+export const SpectrumSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  currentSettings: SpectrumRenderConfigSchema,
+  presets: z.array(SpectrumPresetDefinitionSchema),
+});
+export type SpectrumSettingsResponse = z.infer<typeof SpectrumSettingsResponseSchema>;

package/src/schema/spectrum.schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SpectrumPresetDefinitionSchema, SpectrumRenderConfigSchema } from './spectrum-config.schema.js';
 
 export const SpectrumKindSchema = z.enum(['audio', 'radio-sdr', 'openwebrx-sdr']);
 export type SpectrumKind = z.infer<typeof SpectrumKindSchema>;
@@ -26,10 +27,31 @@ export const SpectrumSessionFrequencyRangeModeSchema = z.enum([
 ]);
 export type SpectrumSessionFrequencyRangeMode = z.infer<typeof SpectrumSessionFrequencyRangeModeSchema>;
 
+export const SpectrumSessionViewModeSchema = z.enum(['wide', 'radio-center']);
+export type SpectrumSessionViewMode = z.infer<typeof SpectrumSessionViewModeSchema>;
+
 export const SpectrumFrequencyRangeSchema = z.object({
   min: z.number(),
   max: z.number(),
 });
+export const SpectrumViewportSchema = z.object({
+  min: z.number().finite(),
+  max: z.number().finite(),
+  displayBinCount: z.number().int().positive().max(16384),
+}).refine((range) => range.max > range.min, {
+  message: 'Spectrum viewport maximum must be greater than minimum',
+  path: ['max'],
+});
+export type SpectrumViewport = z.infer<typeof SpectrumViewportSchema>;
+
+export const SpectrumSessionViewportInteractionSchema = z.object({
+  enabled: z.boolean(),
+  canZoom: z.boolean(),
+  canPan: z.boolean(),
+  canTuneAtEdge: z.boolean(),
+  bounds: SpectrumFrequencyRangeSchema.nullable(),
+});
+export type SpectrumSessionViewportInteraction = z.infer<typeof SpectrumSessionViewportInteractionSchema>;
 
 export const SpectrumBinaryFormatSchema = z.object({
   type: z.literal('int16'),
@@ -43,13 +65,53 @@ export const SpectrumBinaryDataSchema = z.object({
   format: SpectrumBinaryFormatSchema,
 });
 
+export const SpectrumLevelDomainSchema = z.enum(['dbfs', 'calibrated-db', 'raw']);
+export type SpectrumLevelDomain = z.infer<typeof SpectrumLevelDomainSchema>;
+
+export const SpectrumLevelUnitSchema = z.enum(['dBFS', 'dB', 'Level']);
+export type SpectrumLevelUnit = z.infer<typeof SpectrumLevelUnitSchema>;
+
+export const SpectrumLevelReferenceSchema = z.enum(['full-scale', 'device', 'none']);
+export type SpectrumLevelReference = z.infer<typeof SpectrumLevelReferenceSchema>;
+
+export const SpectrumLevelDescriptorSchema = z.object({
+  domain: SpectrumLevelDomainSchema,
+  unit: SpectrumLevelUnitSchema,
+  reference: SpectrumLevelReferenceSchema,
+  calibrated: z.boolean(),
+  min: z.number().finite(),
+  max: z.number().finite(),
+}).refine((level) => level.max > level.min, {
+  message: 'Spectrum level maximum must be greater than minimum',
+  path: ['max'],
+});
+export type SpectrumLevelDescriptor = z.infer<typeof SpectrumLevelDescriptorSchema>;
+
+/** A lower-resolution, wider-range representation derived from the same FFT. */
+export const SpectrumFrameSupplementSchema = z.object({
+  frequencyRange: SpectrumFrequencyRangeSchema,
+  binaryData: SpectrumBinaryDataSchema,
+  meta: z.object({
+    sourceBinCount: z.number().int().positive(),
+    displayBinCount: z.number().int().positive(),
+    centerFrequency: z.number().optional(),
+    spanHz: z.number().optional(),
+    level: SpectrumLevelDescriptorSchema.optional(),
+  }),
+});
+export type SpectrumFrameSupplement = z.infer<typeof SpectrumFrameSupplementSchema>;
+
 export const SpectrumFrameMetaSchema = z.object({
   sourceBinCount: z.number().int().positive(),
   displayBinCount: z.number().int().positive(),
+  /** Original source range before a per-client server-side projection. */
+  nativeFrequencyRange: SpectrumFrequencyRangeSchema.optional(),
   centerFrequency: z.number().optional(),
   spanHz: z.number().optional(),
   profileId: z.string().nullable().optional(),
   radioModel: z.string().optional(),
+  level: SpectrumLevelDescriptorSchema.optional(),
+  spectrumConfigRevision: z.number().int().nonnegative().optional(),
 });
 
 export const SpectrumFrameSchema = z.object({
@@ -58,6 +120,7 @@ export const SpectrumFrameSchema = z.object({
   frequencyRange: SpectrumFrequencyRangeSchema,
   binaryData: SpectrumBinaryDataSchema,
   meta: SpectrumFrameMetaSchema,
+  supplement: SpectrumFrameSupplementSchema.optional(),
 });
 
 export const SpectrumSourceAvailabilitySchema = z.object({
@@ -76,6 +139,8 @@ export const SpectrumCapabilitiesSchema = z.object({
   profileId: z.string().nullable(),
   defaultKind: SpectrumKindSchema,
   sources: z.array(SpectrumSourceAvailabilitySchema),
+  renderConfig: SpectrumRenderConfigSchema,
+  presets: z.array(SpectrumPresetDefinitionSchema),
 });
 
 export const SpectrumSessionControlIdSchema = z.enum([
@@ -120,7 +185,30 @@ export const SpectrumSessionPresetMarkerSchema = z.object({
 });
 export type SpectrumSessionPresetMarker = z.infer<typeof SpectrumSessionPresetMarkerSchema>;
 
+export const SpectrumSessionFrequencyOverlaySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  lineFrequency: z.number().finite(),
+  rangeStartFrequency: z.number().finite(),
+  rangeEndFrequency: z.number().finite(),
+  variant: z.enum(['tx', 'rx', 'window']),
+  draggable: z.boolean(),
+  frequencyTarget: z.enum(['radio-frequency', 'operator-tx', 'split-frequency']).nullable(),
+}).refine((overlay) => overlay.rangeEndFrequency >= overlay.rangeStartFrequency, {
+  message: 'Spectrum frequency overlay range is invalid',
+  path: ['rangeEndFrequency'],
+});
+export type SpectrumSessionFrequencyOverlay = z.infer<typeof SpectrumSessionFrequencyOverlaySchema>;
+
 export const SpectrumSessionInteractionStateSchema = z.object({
+  viewMode: SpectrumSessionViewModeSchema.default('radio-center'),
+  viewport: SpectrumSessionViewportInteractionSchema.default({
+    enabled: false,
+    canZoom: false,
+    canPan: false,
+    canTuneAtEdge: false,
+    bounds: null,
+  }),
   showTxMarkers: z.boolean(),
   showRxMarkers: z.boolean(),
   canDragTx: z.boolean(),
@@ -130,6 +218,7 @@ export const SpectrumSessionInteractionStateSchema = z.object({
   frequencyGestureTarget: z.enum(['operator-tx', 'radio-frequency']).nullable(),
   frequencyStepHz: z.number().int().positive().nullable(),
   presetMarkers: z.array(SpectrumSessionPresetMarkerSchema),
+  frequencyOverlays: z.array(SpectrumSessionFrequencyOverlaySchema),
   canDragVoiceOverlay: z.boolean(),
   showVoiceOverlay: z.boolean(),
   canLocalViewportZoom: z.boolean(),

package/src/schema/tx-audio-input.schema.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/** Normalized TX audio input routes used by the capability/profile layers. */
+export const TxAudioInputSourceSchema = z.enum([
+  'mic',
+  'usb',
+  'network',
+  'accessory',
+  'line',
+  'spdif',
+  'mic+usb',
+  'mic+accessory',
+]);
+export type TxAudioInputSource = z.infer<typeof TxAudioInputSourceSchema>;
+
+/** Profile policy. `auto` is resolved by the connection/provider. */
+export const TxAudioInputSourcePolicySchema = z.enum([
+  'auto',
+  'unchanged',
+  ...TxAudioInputSourceSchema.options,
+]);
+export type TxAudioInputSourcePolicy = z.infer<typeof TxAudioInputSourcePolicySchema>;

package/src/schema/voice.schema.ts

@@ -24,5 +24,5 @@ export type VoicePTTLock = z.infer<typeof VoicePTTLockSchema>;
  * digital: FT8/FT4 等数字模式
  * voice: 语音通联模式（SSB/FM/AM）
  */
-export const EngineModeSchema = z.enum(['digital', 'voice', 'cw']);
+export const EngineModeSchema = z.enum(['digital', 'voice', 'cw', 'image']);
 export type EngineMode = z.infer<typeof EngineModeSchema>;