@tx5dr/contracts 1.4.0 → 1.6.0

package/src/schema/plugin.schema.ts

@@ -36,7 +36,7 @@ export type PluginInstanceScope = z.infer<typeof PluginInstanceScopeSchema>;
  * Permissions let the host gate sensitive capabilities behind manifest-level
  * intent. Plugins should request the smallest possible set.
  */
-export const PluginPermissionSchema = z.enum(['network']);
+export const PluginPermissionSchema = z.enum(['network', 'radio:read', 'radio:control', 'radio:power']);
 
 /**
  * Explicit permission declarations requested by a plugin.
@@ -61,7 +61,7 @@ export type PluginPanelComponent = z.infer<typeof PluginPanelComponentSchema>;
  * These values control both validation expectations and default frontend
  * rendering in plugin settings UIs.
  */
-export const PluginSettingTypeSchema = z.enum(['boolean', 'number', 'string', 'string[]', 'info']);
+export const PluginSettingTypeSchema = z.enum(['boolean', 'number', 'string', 'string[]', 'object[]', 'info']);
 
 /**
  * Supported generated-form field types for plugin settings.
@@ -81,6 +81,16 @@ export const PluginSettingOptionSchema = z.object({
  */
 export type PluginSettingOption = z.infer<typeof PluginSettingOptionSchema>;
 
+export const PluginObjectArrayFieldSchema = z.object({
+  key: z.string(),
+  type: z.enum(['string', 'number', 'boolean']).optional().default('string'),
+  label: z.string(),
+  description: z.string().optional(),
+  placeholder: z.string().optional(),
+  required: z.boolean().optional(),
+});
+export type PluginObjectArrayField = z.infer<typeof PluginObjectArrayFieldSchema>;
+
 /**
  * Persistence and UI scope for a plugin setting.
  *
@@ -110,6 +120,10 @@ export const PluginSettingDescriptorSchema = z.object({
   min: z.number().optional(),
   max: z.number().optional(),
   options: z.array(PluginSettingOptionSchema).optional(),
+  /** Field schema used by generated editors for `object[]` settings. */
+  itemFields: z.array(PluginObjectArrayFieldSchema).optional(),
+  /** Internal settings are persisted/injected but hidden from generated UIs. */
+  hidden: z.boolean().optional(),
   /** 设置作用域：global（所有操作员共享）或 operator（每操作员独立），默认 global */
   scope: PluginSettingScopeSchema.optional().default('global'),
 });
@@ -212,7 +226,8 @@ export type PluginPanelWidth = z.infer<typeof PluginPanelWidthSchema>;
  *
  * Panels are passive containers rendered by the host. A plugin sends data into
  * them through `ctx.ui.send(panelId, data)`. When `component` is `'iframe'`,
- * the panel renders a custom UI page inside a sandboxed iframe instead.
+ * the panel renders a custom UI page inside a sandboxed iframe instead. Static
+ * manifest panels and runtime UI contributions use this same descriptor.
  */
 export const PluginPanelDescriptorSchema = z.object({
   id: z.string(),
@@ -220,6 +235,8 @@ export const PluginPanelDescriptorSchema = z.object({
   component: PluginPanelComponentSchema,
   /** Required when `component` is `'iframe'`. References a page id from `ui.pages`. */
   pageId: z.string().optional(),
+  /** Optional string params forwarded to iframe panels as URL/init params. */
+  params: z.record(z.string(), z.string()).optional(),
   /** Where the panel renders. Defaults to `'operator'` (operator card live-panel area). */
   slot: PluginPanelSlotSchema.optional(),
   /** Preferred width hint. Defaults to `'half'`. */
@@ -231,6 +248,29 @@ export const PluginPanelDescriptorSchema = z.object({
  */
 export type PluginPanelDescriptor = z.infer<typeof PluginPanelDescriptorSchema>;
 
+export const PluginUIPanelContributionTargetSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('global') }),
+  z.object({ kind: z.literal('operator'), operatorId: z.string() }),
+]);
+export type PluginUIPanelContributionTarget = z.infer<typeof PluginUIPanelContributionTargetSchema>;
+
+/**
+ * A normalized group of plugin UI panels.
+ *
+ * Static `PluginDefinition.panels` are emitted by the host as the reserved
+ * `manifest` group. Runtime groups are replaced by
+ * `ctx.ui.setPanelContributions(groupId, panels)` and cleared by publishing an
+ * empty panel list for the same group.
+ */
+export const PluginUIPanelContributionGroupSchema = z.object({
+  pluginName: z.string(),
+  groupId: z.string(),
+  source: z.enum(['manifest', 'runtime']),
+  instanceTarget: PluginUIPanelContributionTargetSchema.optional(),
+  panels: z.array(PluginPanelDescriptorSchema),
+});
+export type PluginUIPanelContributionGroup = z.infer<typeof PluginUIPanelContributionGroupSchema>;
+
 // ===== 自定义 UI 页面 =====
 
 /**
@@ -422,6 +462,7 @@ export const PluginSystemSnapshotSchema = z.object({
   generation: z.number().int().nonnegative(),
   plugins: z.array(PluginStatusSchema),
   panelMeta: z.array(PluginPanelMetaPayloadSchema).optional().default([]),
+  panelContributions: z.array(PluginUIPanelContributionGroupSchema).optional().default([]),
   lastError: z.string().optional(),
 });
 export type PluginSystemSnapshot = z.infer<typeof PluginSystemSnapshotSchema>;

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

@@ -42,6 +42,18 @@ export type CapabilityOptionValue = z.infer<typeof CapabilityOptionValueSchema>;
 export const CapabilityValueSchema = z.union([z.boolean(), z.number(), z.string()]);
 export type CapabilityValue = z.infer<typeof CapabilityValueSchema>;
 
+export const CapabilityAvailabilitySchema = z.enum(['available', 'unavailable', 'unknown']);
+export type CapabilityAvailability = z.infer<typeof CapabilityAvailabilitySchema>;
+
+export const CapabilityAvailabilityReasonSchema = z.enum([
+  'runtime_error',
+  'busy',
+  'unsupported_by_current_mode',
+  'radio_reported_unavailable',
+  'unknown',
+]);
+export type CapabilityAvailabilityReason = z.infer<typeof CapabilityAvailabilityReasonSchema>;
+
 /**
  * 枚举项定义。
  */
@@ -161,9 +173,21 @@ export const CapabilityStateSchema = z.object({
   /** 能力 ID，与 CapabilityDescriptor.id 对应 */
   id: z.string(),
 
-  /** 当前连接的电台是否支持此能力（探测结果） */
+  /** 当前连接的电台型号/后端是否声明支持此能力 */
   supported: z.boolean(),
 
+  /**
+   * 当前运行时是否可用。
+   * 兼容旧客户端：缺省时应按 supported=true 视为 available，supported=false 视为 unknown。
+   */
+  availability: CapabilityAvailabilitySchema.optional(),
+
+  /** 当前不可用的机器可读原因 */
+  availabilityReason: CapabilityAvailabilityReasonSchema.optional(),
+
+  /** 最近一次运行时读写错误摘要 */
+  lastError: z.string().optional(),
+
   /**
    * 当前值
    * - boolean 类能力：true/false

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>;