@springfield/ham-radio-api 18.1.0 → 18.3.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":"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"}

package/dist/radio/protocol.d.ts

@@ -125,4 +125,23 @@ export interface RadioCatWriteStep {
     catWrite: RadioCatMemoryConfig;
 }
 export type RadioProtocolStep = RadioExchange | RadioReadStep | RadioWriteStep | RadioCatReadStep | RadioCatWriteStep;
+/**
+ * Exchange-only protocol steps (`send`, `expect`, `setBaudRate`, `delay`, `timeout`).
+ * Used for {@link RadioOnError} cleanup lists, which must not include read, write, or CAT loop steps.
+ */
+export type RadioProtocolExchangeStep = RadioExchange;
+/**
+ * Optional cleanup exchanges keyed by memory operation. The driver runs the matching list
+ * best-effort after a protocol step fails or the user cancels; it is not run on success and is
+ * skipped when the serial port is already closed.
+ *
+ * @example Kenwood TH-D74 clone exit at the post-switch baud:
+ * ```json
+ * [{ "setBaudRate": 57600 }, { "send": ["E"] }]
+ * ```
+ */
+export interface RadioOnError {
+    readMemory?: RadioProtocolExchangeStep[];
+    writeMemory?: RadioProtocolExchangeStep[];
+}
 //# sourceMappingURL=protocol.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/radio/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,cAAc,EAAE,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAElG;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,IAAI,EAAE,cAAc,EAAE,CAAC;QACvB,MAAM,EAAE,WAAW,CAAC;QACpB,GAAG,CAAC,EAAE,aAAa,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,cAAc,CAAC;KACxB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,IAAI,EAAE,cAAc,EAAE,CAAC;QACvB,MAAM,EAAE,WAAW,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,kBAAkB,EAAE,CAAC;KAC7B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,iBAAiB,CAAC"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/radio/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,cAAc,EAAE,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAElG;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,IAAI,EAAE,cAAc,EAAE,CAAC;QACvB,MAAM,EAAE,WAAW,CAAC;QACpB,GAAG,CAAC,EAAE,aAAa,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,cAAc,CAAC;KACxB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,IAAI,EAAE,cAAc,EAAE,CAAC;QACvB,MAAM,EAAE,WAAW,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,kBAAkB,EAAE,CAAC;KAC7B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAEtH;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,aAAa,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACzC,WAAW,CAAC,EAAE,yBAAyB,EAAE,CAAC;CAC3C"}

package/dist/radio/radio.d.ts

@@ -1,18 +1,36 @@
 import type { RadioId } from "./id.js";
 import type { RadioMemoryConfig } from "./memory-config.js";
 import type { RadioMemoryMap } from "./memory-map.js";
-import type { RadioProtocolStep } from "./protocol.js";
+import type { RadioOnError, 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;
     readMemory: RadioProtocolStep[];
     writeMemory: RadioProtocolStep[];
+    /**
+     * Optional cleanup exchanges after a failed or cancelled read/write. Not run on success;
+     * skipped when the port is closed. Each list may only contain exchange steps (`send`,
+     * `expect`, `setBaudRate`, `delay`, `timeout`), not read/write/CAT loops.
+     *
+     * @example Kenwood TH-D74 clone exit at the post-switch baud:
+     * `[{ setBaudRate: 57600 }, { send: ['E'] }]`
+     */
+    onError?: RadioOnError;
     /**
      * Optional JSON memory-map for radio-wide settings decode/encode.
      * May be an inline map or a path/$ref resolved by the registry/module.

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,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACrE,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;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;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.3.0",
   "author": "Bryan Hunt",
   "license": "MIT",
   "files": [
@@ -39,12 +39,12 @@
     "@semantic-release/github": "12.0.10",
     "@semantic-release/npm": "13.2.0",
     "husky": "9.1.7",
-    "oxfmt": "^0.71.0",
-    "oxlint": "1.86.0",
+    "oxfmt": "^0.73.0",
+    "oxlint": "1.88.0",
     "semantic-release": "25.0.9",
     "typescript": "7.0.2",
-    "vite": "^8.3.2",
-    "vitest": "^5.0.3"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5"
   },
   "resolutions": {
     "conventional-changelog-conventionalcommits": "9.3.1"

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/protocol.ts

@@ -137,3 +137,24 @@ export interface RadioCatWriteStep {
 }
 
 export type RadioProtocolStep = RadioExchange | RadioReadStep | RadioWriteStep | RadioCatReadStep | RadioCatWriteStep;
+
+/**
+ * Exchange-only protocol steps (`send`, `expect`, `setBaudRate`, `delay`, `timeout`).
+ * Used for {@link RadioOnError} cleanup lists, which must not include read, write, or CAT loop steps.
+ */
+export type RadioProtocolExchangeStep = RadioExchange;
+
+/**
+ * Optional cleanup exchanges keyed by memory operation. The driver runs the matching list
+ * best-effort after a protocol step fails or the user cancels; it is not run on success and is
+ * skipped when the serial port is already closed.
+ *
+ * @example Kenwood TH-D74 clone exit at the post-switch baud:
+ * ```json
+ * [{ "setBaudRate": 57600 }, { "send": ["E"] }]
+ * ```
+ */
+export interface RadioOnError {
+  readMemory?: RadioProtocolExchangeStep[];
+  writeMemory?: RadioProtocolExchangeStep[];
+}

package/src/radio/radio.ts

@@ -1,19 +1,37 @@
 import type { RadioId } from "./id.js";
 import type { RadioMemoryConfig } from "./memory-config.js";
 import type { RadioMemoryMap } from "./memory-map.js";
-import type { RadioProtocolStep } from "./protocol.js";
+import type { RadioOnError, 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;
   readMemory: RadioProtocolStep[];
   writeMemory: RadioProtocolStep[];
+  /**
+   * Optional cleanup exchanges after a failed or cancelled read/write. Not run on success;
+   * skipped when the port is closed. Each list may only contain exchange steps (`send`,
+   * `expect`, `setBaudRate`, `delay`, `timeout`), not read/write/CAT loops.
+   *
+   * @example Kenwood TH-D74 clone exit at the post-switch baud:
+   * `[{ setBaudRate: 57600 }, { send: ['E'] }]`
+   */
+  onError?: RadioOnError;
   /**
    * Optional JSON memory-map for radio-wide settings decode/encode.
    * May be an inline map or a path/$ref resolved by the registry/module.