@springfield/ham-radio-api 18.1.0 → 18.2.0

package/README.md

@@ -6,6 +6,8 @@ Packages that talk to radios depend on this library. It does not open a serial p
 
 Docs: [HamBench developer docs](https://springfield-ham-radio.github.io/ham-radio-docs/developer/)
 
+Package docs: [radio read/write dialog messages](docs/radio-dialog-messages.md)
+
 ## License
 
 MIT — Copyright (c) 2026 Bryan Hunt. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./radio/codec-factory.js";
 export * from "./radio/connection.js";
 export * from "./radio/ctcss.js";
 export * from "./radio/dcs.js";
+export * from "./radio/dialog-message.js";
 export * from "./radio/driver.js";
 export * from "./radio/driver-provider.js";
 export * from "./radio/id.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,oBAAoB,CAAC;AAEnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AAExC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,oBAAoB,CAAC;AAEnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AAExC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./radio/codec-factory.js";
 export * from "./radio/connection.js";
 export * from "./radio/ctcss.js";
 export * from "./radio/dcs.js";
+export * from "./radio/dialog-message.js";
 export * from "./radio/driver.js";
 export * from "./radio/driver-provider.js";
 export * from "./radio/id.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,oBAAoB,CAAC;AAEnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AAExC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,oBAAoB,CAAC;AAEnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AAExC,cAAc,mBAAmB,CAAC;AAElC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}

package/dist/radio/dialog-message.d.ts

@@ -0,0 +1,25 @@
+import type { ValidationResult } from "./validation.js";
+/** UAlert-style severity for optional read/write setup text in HamBench. */
+export type RadioDialogSeverity = "info" | "warning";
+/**
+ * Optional setup text shown in HamBench before a memory read or write.
+ * Radio modules set this on the driver config JSON (`readMessage` / `writeMessage`).
+ */
+export interface RadioDialogMessage {
+    /** Short alert title (plain text). */
+    title: string;
+    /** Alert body (plain text; newlines are line breaks). */
+    body: string;
+    /**
+     * Visual weight in HamBench. Omit for `info`.
+     */
+    severity?: RadioDialogSeverity;
+}
+export declare const RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH = 80;
+export declare const RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH = 600;
+/**
+ * Validate an optional `readMessage` or `writeMessage` value from a radio config.
+ * `undefined` is valid (field omitted).
+ */
+export declare function validateRadioDialogMessage(fieldPath: string, value: unknown): ValidationResult;
+//# sourceMappingURL=dialog-message.d.ts.map

package/dist/radio/dialog-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog-message.d.ts","sourceRoot":"","sources":["../../src/radio/dialog-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED,eAAO,MAAM,qCAAqC,KAAK,CAAC;AACxD,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAoBxD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAoD9F"}

package/dist/radio/dialog-message.js

@@ -0,0 +1,69 @@
+export const RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH = 80;
+export const RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH = 600;
+const DIALOG_SEVERITIES = new Set(["info", "warning"]);
+function hasDisallowedControlCharacters(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code === 9 || code === 10) {
+            continue;
+        }
+        if (code < 32 || code === 127) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate an optional `readMessage` or `writeMessage` value from a radio config.
+ * `undefined` is valid (field omitted).
+ */
+export function validateRadioDialogMessage(fieldPath, value) {
+    const errors = [];
+    const warnings = [];
+    if (value === undefined) {
+        return { isValid: true, errors, warnings };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push(`${fieldPath} must be an object`);
+        return { isValid: false, errors, warnings };
+    }
+    const record = value;
+    if (typeof record.title !== "string") {
+        errors.push(`${fieldPath}.title must be a string`);
+    }
+    else {
+        const title = record.title.trim();
+        if (title.length === 0) {
+            errors.push(`${fieldPath}.title must not be empty`);
+        }
+        else if (title.length > RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH) {
+            errors.push(`${fieldPath}.title must be at most ${RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH} characters`);
+        }
+    }
+    if (typeof record.body !== "string") {
+        errors.push(`${fieldPath}.body must be a string`);
+    }
+    else {
+        const body = record.body.trim();
+        if (body.length === 0) {
+            errors.push(`${fieldPath}.body must not be empty`);
+        }
+        else if (body.length > RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH) {
+            errors.push(`${fieldPath}.body must be at most ${RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH} characters`);
+        }
+        else if (hasDisallowedControlCharacters(record.body)) {
+            errors.push(`${fieldPath}.body must not contain control characters other than tab or newline`);
+        }
+    }
+    if (record.severity !== undefined) {
+        if (typeof record.severity !== "string" || !DIALOG_SEVERITIES.has(record.severity)) {
+            errors.push(`${fieldPath}.severity must be "info" or "warning"`);
+        }
+    }
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=dialog-message.js.map

package/dist/radio/dialog-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog-message.js","sourceRoot":"","sources":["../../src/radio/dialog-message.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,qCAAqC,GAAG,EAAE,CAAC;AACxD,MAAM,CAAC,MAAM,oCAAoC,GAAG,GAAG,CAAC;AAExD,MAAM,iBAAiB,GAAqC,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEzF,SAAS,8BAA8B,CAAC,IAAY;IAClD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAEpC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAC9B,SAAS;QACX,CAAC;QAED,IAAI,IAAI,GAAG,EAAE,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,SAAiB,EAAE,KAAc;IAC1E,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,oBAAoB,CAAC,CAAC;QAC9C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC9C,CAAC;IAED,MAAM,MAAM,GAAG,KAAgC,CAAC;IAEhD,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,yBAAyB,CAAC,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAElC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,0BAA0B,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,GAAG,qCAAqC,EAAE,CAAC;YAChE,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,0BAA0B,qCAAqC,aAAa,CAAC,CAAC;QACxG,CAAC;IACH,CAAC;IAED,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,wBAAwB,CAAC,CAAC;IACpD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAEhC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,yBAAyB,CAAC,CAAC;QACrD,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,GAAG,oCAAoC,EAAE,CAAC;YAC9D,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,yBAAyB,oCAAoC,aAAa,CAAC,CAAC;QACtG,CAAC;aAAM,IAAI,8BAA8B,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,qEAAqE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,QAA+B,CAAC,EAAE,CAAC;YAC1G,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,uCAAuC,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC5B,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/radio/radio.d.ts

@@ -3,11 +3,20 @@ import type { RadioMemoryConfig } from "./memory-config.js";
 import type { RadioMemoryMap } from "./memory-map.js";
 import type { RadioProtocolStep } from "./protocol.js";
 import type { RadioSchema } from "./schema.js";
+import type { RadioDialogMessage } from "./dialog-message.js";
 import type { RadioSerialConfig } from "./serial-config.js";
 export interface Radio {
     id: RadioId;
     version: string;
     description: string;
+    /**
+     * Optional setup text for HamBench **Read from Radio** (plain text; see `RadioDialogMessage`).
+     */
+    readMessage?: RadioDialogMessage;
+    /**
+     * Optional setup text for HamBench **Write to Radio** (plain text; see `RadioDialogMessage`).
+     */
+    writeMessage?: RadioDialogMessage;
     settingsSchema: RadioSchema;
     memoryConfig: RadioMemoryConfig;
     serialConfig: RadioSerialConfig;

package/dist/radio/radio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"radio.d.ts","sourceRoot":"","sources":["../../src/radio/radio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,WAAW,CAAC;IAC5B,YAAY,EAAE,iBAAiB,CAAC;IAChC,YAAY,EAAE,iBAAiB,CAAC;IAChC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C"}
+{"version":3,"file":"radio.d.ts","sourceRoot":"","sources":["../../src/radio/radio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;OAEG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,cAAc,EAAE,WAAW,CAAC;IAC5B,YAAY,EAAE,iBAAiB,CAAC;IAChC,YAAY,EAAE,iBAAiB,CAAC;IAChC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springfield/ham-radio-api",
-  "version": "18.1.0",
+  "version": "18.2.0",
   "author": "Bryan Hunt",
   "license": "MIT",
   "files": [

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./radio/codec-factory.js";
 export * from "./radio/connection.js";
 export * from "./radio/ctcss.js";
 export * from "./radio/dcs.js";
+export * from "./radio/dialog-message.js";
 export * from "./radio/driver.js";
 export * from "./radio/driver-provider.js";
 export * from "./radio/id.js";

package/src/radio/dialog-message.ts

@@ -0,0 +1,98 @@
+import type { ValidationResult } from "./validation.js";
+
+/** UAlert-style severity for optional read/write setup text in HamBench. */
+export type RadioDialogSeverity = "info" | "warning";
+
+/**
+ * Optional setup text shown in HamBench before a memory read or write.
+ * Radio modules set this on the driver config JSON (`readMessage` / `writeMessage`).
+ */
+export interface RadioDialogMessage {
+  /** Short alert title (plain text). */
+  title: string;
+  /** Alert body (plain text; newlines are line breaks). */
+  body: string;
+  /**
+   * Visual weight in HamBench. Omit for `info`.
+   */
+  severity?: RadioDialogSeverity;
+}
+
+export const RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH = 80;
+export const RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH = 600;
+
+const DIALOG_SEVERITIES: ReadonlySet<RadioDialogSeverity> = new Set(["info", "warning"]);
+
+function hasDisallowedControlCharacters(text: string): boolean {
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+
+    if (code === 9 || code === 10) {
+      continue;
+    }
+
+    if (code < 32 || code === 127) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Validate an optional `readMessage` or `writeMessage` value from a radio config.
+ * `undefined` is valid (field omitted).
+ */
+export function validateRadioDialogMessage(fieldPath: string, value: unknown): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (value === undefined) {
+    return { isValid: true, errors, warnings };
+  }
+
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    errors.push(`${fieldPath} must be an object`);
+    return { isValid: false, errors, warnings };
+  }
+
+  const record = value as Record<string, unknown>;
+
+  if (typeof record.title !== "string") {
+    errors.push(`${fieldPath}.title must be a string`);
+  } else {
+    const title = record.title.trim();
+
+    if (title.length === 0) {
+      errors.push(`${fieldPath}.title must not be empty`);
+    } else if (title.length > RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH) {
+      errors.push(`${fieldPath}.title must be at most ${RADIO_DIALOG_MESSAGE_TITLE_MAX_LENGTH} characters`);
+    }
+  }
+
+  if (typeof record.body !== "string") {
+    errors.push(`${fieldPath}.body must be a string`);
+  } else {
+    const body = record.body.trim();
+
+    if (body.length === 0) {
+      errors.push(`${fieldPath}.body must not be empty`);
+    } else if (body.length > RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH) {
+      errors.push(`${fieldPath}.body must be at most ${RADIO_DIALOG_MESSAGE_BODY_MAX_LENGTH} characters`);
+    } else if (hasDisallowedControlCharacters(record.body)) {
+      errors.push(`${fieldPath}.body must not contain control characters other than tab or newline`);
+    }
+  }
+
+  if (record.severity !== undefined) {
+    if (typeof record.severity !== "string" || !DIALOG_SEVERITIES.has(record.severity as RadioDialogSeverity)) {
+      errors.push(`${fieldPath}.severity must be "info" or "warning"`);
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}

package/src/radio/radio.ts

@@ -3,12 +3,21 @@ import type { RadioMemoryConfig } from "./memory-config.js";
 import type { RadioMemoryMap } from "./memory-map.js";
 import type { RadioProtocolStep } from "./protocol.js";
 import type { RadioSchema } from "./schema.js";
+import type { RadioDialogMessage } from "./dialog-message.js";
 import type { RadioSerialConfig } from "./serial-config.js";
 
 export interface Radio {
   id: RadioId;
   version: string;
   description: string;
+  /**
+   * Optional setup text for HamBench **Read from Radio** (plain text; see `RadioDialogMessage`).
+   */
+  readMessage?: RadioDialogMessage;
+  /**
+   * Optional setup text for HamBench **Write to Radio** (plain text; see `RadioDialogMessage`).
+   */
+  writeMessage?: RadioDialogMessage;
   settingsSchema: RadioSchema;
   memoryConfig: RadioMemoryConfig;
   serialConfig: RadioSerialConfig;