@ham2k/extension-sdk 0.1.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,139 @@
+# Writing a Ham2K Logger extension
+
+*This file describes the published `@ham2k/extension-sdk` package, as installed
+in an extension project's `node_modules`. Working inside the Ham2K Logger
+repository itself is a different setup — see `docs/extensions/README.md` there.*
+
+You are building an extension for the Ham2K Logger — a TypeScript module the
+app loads into a sandbox and calls through **hooks**. Extensions are where the
+app's domain knowledge lives: award programs, contests, callsign lookups, spot
+sources, exporters, panels.
+
+Everything you need is in this package. `samples/` holds one worked extension
+per shape — start there, with the one whose shape matches what you are
+building. `docs/` is the reference, pinned to the version of the SDK installed
+here; `dist/index.d.ts` is the typed surface, and is the final word wherever
+prose and types disagree.
+
+Paths like `app/lib/config/secret_policy.dart` or `app/experiments.yaml`,
+mentioned in those docs, are files in the Ham2K Logger's own repository
+(<https://github.com/ham2k/halo>). They are not part of your project and you
+cannot read them here.
+
+## The shape of a project
+
+```
+manifest.json      your extension's public identity — read without running code
+src/index.ts       imports the manifest, calls defineExtension
+build.mjs          runs @ham2k/extension-tools' build preset
+build/             generated: index.js + manifest.json
+```
+
+`npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name>` writes all of it.
+
+## The smallest whole extension
+
+```ts
+import { defineExtension } from '@ham2k/extension-sdk'
+import type { PanelHook } from '@ham2k/extension-sdk'
+
+import manifest from '../manifest.json'
+
+const HelloPanel: PanelHook = {
+  async getPanels() {
+    return [{ key: 'hello', title: 'Hello World', icon: 'hand-wave-outline' }]
+  },
+  async render() {
+    return { kind: 'markdown', content: '# Hello, World!' }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook('panel', { key: manifest.key, hook: HelloPanel })
+  },
+})
+```
+
+`manifest.json` needs at least `key`, `name`, `version`, `description`,
+`category`, `api`, and the `sharedDependencies` below. The manifest is spread
+into `defineExtension` rather than retyped: two sources for the same identity
+drift, and the packer reads the file.
+
+## Building and shipping
+
+```sh
+node build.mjs                              # → build/index.js
+npx -p @ham2k/extension-tools h2kext-pack build -o my-extension.h2kext
+```
+
+The packer is also the checker. It reports every problem at once and refuses
+anything that would install cleanly and then misbehave where you cannot watch
+it, so a clean pack is the strongest evidence available outside the app itself.
+Run it whenever you have changed the manifest or the hooks you register.
+
+`tsc --noEmit` is the other half: the hook interfaces are typed, and a hook that
+typechecks is registered under a category the host knows, with the methods it
+will actually call.
+
+## Where to read next
+
+| Doing this | Read |
+| --- | --- |
+| Anything, before the reference — a whole worked extension of that shape | `samples/`: `k2hrc-hamqth` (lookup + credentials), `k2hrc-llota` (award program), `k2hrc-cqww` (contest + scoring), `k2hrc-radio` (HTML panel) |
+| Any hook at all — what the category is, what it's handed, what it must return | `docs/hooks.md`, the section named for the category |
+| A pane in a view: `getPanels`, `render`, panel content kinds | `docs/hooks.md` §`panel` |
+| Callsign lookups, spot sources, exporters, reference types (POTA-style) | `docs/hooks.md` §`lookup`, §`spots`, §`export`, §`ref:<type>` |
+| Contest or award scoring, and the UI an activity contributes | `docs/hooks.md` §`scoring`, §`activity` |
+| A settings screen for your extension | `docs/settings.md` |
+| Any form, dialog or field the user fills in | `docs/forms.md` |
+| Panel text, export filenames, ADIF fields — anything with `{{ }}` in it | `docs/templates.md` |
+| Packaging, the `.h2kext` format, keys, using the host's libraries | `docs/distribution.md` |
+
+`docs/hooks.md` is long. Read the section for the category you are registering,
+not the file.
+
+## What the sandbox is
+
+No Node, no DOM, no `fetch`, no `window`, no filesystem. One ES2020 engine
+evaluating one script. Reach the outside world through `host`:
+
+```ts
+import { host } from '@ham2k/extension-sdk'
+
+await host.fetch(url)          // https only, and only domains your manifest lists
+await host.kvGet('key')        // storage, namespaced to your extension
+await host.kvSet('key', value)
+await host.showForm(form)      // ask the user something
+await host.showMessage({ … })  // tell them something
+host.log('…')                  // the app's console
+```
+
+`dist/index.d.ts` has the rest, with the types.
+
+## Traps worth knowing before you write anything
+
+- **A panel returns content, not widgets.** `{ kind: 'markdown', content }` and
+  its siblings. There is no way to reach the app's UI toolkit, by design.
+- **`host.fetch` only reaches domains your manifest's `domains` lists**, over
+  https. An undeclared host is refused at the call, not at build.
+- **Using a shared library without declaring it fails the build.** The app
+  carries `@ham2k/lib-*`, `i18next` and `liquidjs`; naming one in
+  `sharedDependencies` rewrites your imports into lookups on the app's single
+  copy, which is worth roughly thirty times the bundle size. Don't install them.
+  `inline: ['liquidjs']` in your build ships your own copy, for when you need a
+  version the app does not carry. A scaffolded manifest already declares the
+  eight this SDK's own modules reach — importing anything from it pulls them
+  in — so deleting one from the manifest breaks a build that was working.
+- **Your key is `<callsign>-<name>`**, lowercase. It namespaces your storage and
+  is what the app shows when it says where something came from. `ham2k-` is
+  reserved.
+- **`host.secret()` returns null** for anything not built into the app. Degrade;
+  don't throw. A hook that throws takes its whole feature down.
+- **Hook method names are routed by string.** The host finds your hook by its
+  registered key and then calls the method by name, so `renderPanel` where
+  `render` was meant is an extension that installs, activates, and does nothing.
+  This is what typing your hook as `PanelHook` (or its siblings) catches.
+- **Every hook is async and crosses a bridge.** Some context reads carry a whole
+  log — fine when exporting, not on a per-keystroke path.

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sebastian Delmont <sd@ham2k.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,7 +26,7 @@ const HelloPanel: PanelHook = {
 defineExtension({
   ...manifest,
   onActivation({ registerHook }) {
-    registerHook('panel', { key: 'ki2d-hello-world', hook: HelloPanel })
+    registerHook('panel', { key: manifest.key, hook: HelloPanel })
   },
 })
 ```
@@ -34,9 +34,24 @@ defineExtension({
 A panel returns *content*, not widgets — which is what keeps extensions out of
 the app's UI toolkit.
 
-`@ham2k/extension-tools` builds and packages it into a `.h2kext` the app can
-install. See [the extension docs](https://github.com/ham2k/halo/tree/main/docs/extensions)
-for hooks, forms, templates and distribution.
+`npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name>` writes
+all of that and the build script; the same package packages the result into a
+`.h2kext` the app can install.
+
+## The reference is in this package
+
+`samples/` holds one worked extension per shape — a callsign lookup with the
+credentials it needs, an award program, a contest and its scorer, an HTML
+panel. Each builds and packs; each says in its header what it leaves out.
+
+`AGENTS.md` beside this file is the map — the manifest, the sandbox's limits,
+and which of `docs/` answers what. `docs/` holds the references themselves:
+every hook category, forms, settings panels, templates, and the bundle format.
+
+They travel in the package rather than being linked to, so they are readable
+offline and describe the version installed here rather than whatever the
+repository says today. If an agent is writing your extension, point it at
+`node_modules/@ham2k/extension-sdk/AGENTS.md` — `h2kext-init` does that for you.
 
 ## About the peer dependencies
 
@@ -52,7 +67,3 @@ in, so your editor works with only this package installed.
 
 Install one only to `inline` it — to ship your own copy because you need a
 version the host does not carry.
-
-## License
-
-MPL-2.0

package/dist/activityExports.js

@@ -1,4 +1,5 @@
 import { exportFilename, startMillisOf } from "./exportNames.js";
+import { segmentsWith } from "./segments.js";
 import { createCachedTranslator } from "./i18n.js";
 import en from "./i18n/activityExports.en.json";
 import es from "./i18n/activityExports.es.json";
@@ -50,13 +51,16 @@ function activityExportHook(rules) {
       if (!refsOfType(args.operation, rules.activationType).some((r) => r.ref === wanted)) {
         throw new Error(`${rules.key}: operation has no ${rules.activationType} reference '${wanted}'`);
       }
-      const refs = (args.operation.refs ?? []).filter(
-        (r) => r?.type !== rules.activationType || r?.ref === wanted
-      );
-      const operation = { ...args.operation, refs };
+      const claimOnly = (operation) => ({
+        ...operation,
+        refs: (operation.refs ?? []).filter(
+          (r) => r?.type !== rules.activationType || r?.ref === wanted
+        )
+      });
       const content = await adifForExport({
-        operation,
+        operation: claimOnly(args.operation),
         qsos: args.qsos,
+        segments: segmentsWith(args.segments, claimOnly),
         includePrivateData: args.includePrivateData,
         mainHandler: rules.key,
         includeFieldsFrom: rules.includeFieldsFrom
@@ -113,6 +117,7 @@ function huntingExportHook(rules) {
       const content = await adifForExport({
         operation: args.operation,
         qsos: huntedQsos(args.qsos ?? []),
+        segments: args.segments,
         includePrivateData: args.includePrivateData,
         // The hunter file is submitted to ONE program too — see
         // `activityExportHook.generateExport`. `rules.key` is the ACTIVITY's
@@ -131,11 +136,12 @@ function huntingExportHook(rules) {
     }
   };
 }
-async function adifForExport({ operation, qsos, includePrivateData, mainHandler, includeFieldsFrom }) {
+async function adifForExport({ operation, qsos, segments, includePrivateData, mainHandler, includeFieldsFrom }) {
   const { hooks } = await import("@ham2k/extension-sdk");
   const entries = await hooks.invokeOne("export", "adif", "generateExport", {
     operation,
     qsos,
+    segments,
     exportType: "adif",
     // Forwarded, or the delegate defaults to withholding and the user's
     // "include private info" setting silently does nothing here.

package/dist/activityScoring.js

@@ -127,6 +127,8 @@ function activityScorer(rules) {
         score.alerts = ["duplicate"];
       } else if (verdict) {
         score.notices = [NOTICE_KEYS[verdict]];
+      } else if (priors.length > 0 && score.value > 0 && freshRefRescuesActivation) {
+        score.dupe = false;
       }
       const packed = packContact(day, band, mode, huntedRefs);
       if (priors.length > 0) priors.push(packed);

package/dist/dxcc.js

@@ -2,8 +2,8 @@ import { parseCallsign } from "@ham2k/lib-callsigns";
 import { annotateFromCountryFile, useBuiltinCountryFile } from "@ham2k/lib-country-files";
 import { DXCC_BY_CODE } from "@ham2k/lib-dxcc-data";
 useBuiltinCountryFile();
-function annotateCallAgainstCountryFile(call) {
-  return annotateFromCountryFile(parseCallsign(call));
+function annotateCallAgainstCountryFile(call, options) {
+  return annotateFromCountryFile(parseCallsign(call), options);
 }
 function entityPrefixForCall(call) {
   if (!call) return void 0;
@@ -17,8 +17,21 @@ function regionAndCountryForDxccCode(dxccCode) {
   const entity = DXCC_BY_CODE[dxccCode];
   return { ituRegion: entity?.ituRegion, countryCode: entity?.countryCode };
 }
+function countryPrefixForCall(call) {
+  if (!call) return void 0;
+  const annotated = annotateCallAgainstCountryFile(call);
+  const { countryCode } = regionAndCountryForDxccCode(annotated.dxccCode);
+  return countryCode ? countryCode.toUpperCase() : annotated.entityPrefix;
+}
+function entityForCall(call) {
+  if (!call) return {};
+  const { dxccCode, continent, entityName } = annotateCallAgainstCountryFile(call);
+  return { dxccCode, continent, entityName };
+}
 export {
   annotateCallAgainstCountryFile,
+  countryPrefixForCall,
+  entityForCall,
   entityPrefixForCall,
   flagForDxccCode,
   regionAndCountryForDxccCode

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.1.0
+// @ham2k/extension-sdk 0.3.0
 export type CallInfo = {
 	call: string;
 	baseCall?: string;
@@ -103,8 +103,14 @@ export interface HookContext {
 	distanceUnits?: string;
 	decimalSeparator?: string;
 	groupingSeparator?: string;
+	gridPrecision?: number;
 	edition?: string;
 	enabledExperiments?: string[];
+	experiments?: {
+		key: string;
+		name: string;
+		aliases: string[];
+	}[];
 	getOperation?(uuid: string): Promise<Record<string, JSONValue> | null>;
 	getQsos?(operationUuid: string): Promise<Record<string, JSONValue>[] | null>;
 	getSpotsForCall?(call: string, maxAgeMinutes?: number): Promise<Spot[]>;
@@ -275,6 +281,7 @@ export interface SerialInputDescriptor {
 export interface FormInputDescriptor {
 	kind: "form";
 	refType: string;
+	alsoHandles?: string[];
 	form: FormDefinition;
 }
 export interface TextInputDescriptor {
@@ -304,6 +311,10 @@ export interface OptionsInputDescriptor {
 	matchOn?: ("code" | "name")[];
 	allowFreeform?: boolean;
 	preferredCodes?: string[];
+	multiValue?: {
+		separator: string;
+		inheritPrefix?: number;
+	};
 	minCharsForSuggestions?: number;
 	placeholder?: string;
 	uppercase?: boolean;
@@ -380,6 +391,7 @@ export interface AdifImportHook {
 export interface ExportRequest {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
+	segments?: OperationSegmentPayload[];
 	exportType?: string;
 	compactFilenames?: boolean;
 	includePrivateData?: boolean;
@@ -464,6 +476,7 @@ export interface ScoreQsoRequest {
 export interface QsoScoreNotices {
 	notices: string[];
 	alerts: string[];
+	dupe?: boolean;
 }
 export interface ScoreCandidatesRequest {
 	operation: Record<string, JSONValue>;
@@ -517,6 +530,10 @@ export interface CommandAction {
 	setPower?: {
 		watts: number;
 	};
+	setKeyerSpeed?: {
+		wpm: number;
+	};
+	showKeyer?: Record<string, never>;
 	updateQso?: Record<string, JSONValue>;
 	addQso?: Record<string, JSONValue>;
 	sendSpots?: {
@@ -540,6 +557,10 @@ export interface CommandAction {
 		operatorCall?: string;
 		multiIdentifier?: string;
 	};
+	markSegment?: {
+		kind: "start" | "break" | "stop";
+		setLocation?: boolean;
+	};
 	setCallField?: {
 		text: string;
 	};
@@ -575,6 +596,9 @@ export interface CommandAction {
 		deltaMillis?: number;
 		speed?: number;
 	};
+	devBench?: {
+		qsoCount?: number;
+	};
 	toggleExperiment?: {
 		token: string;
 	};
@@ -723,6 +747,14 @@ export interface ActivationApi {
 	registerHook(category: string, params: RegisterHookParams): void;
 	hostCall(method: string, params: Record<string, unknown>): Promise<unknown>;
 }
+export interface ExtensionRelevance {
+	entities?: string[];
+	countries?: string[];
+	continents?: string[];
+	ituRegions?: number[];
+	dates?: string[];
+	interests?: string[];
+}
 export interface ExtensionManifest {
 	key: string;
 	name: string;
@@ -739,6 +771,7 @@ export interface ExtensionManifest {
 	allowUserAgentOverride?: boolean;
 	requiresLocation?: boolean;
 	experiments?: string[];
+	relevance?: ExtensionRelevance;
 	translations?: Record<string, {
 		name?: string;
 		description?: string;
@@ -883,7 +916,7 @@ export interface FormHeader {
 	title: string;
 	subtitle?: string;
 	devMode?: boolean;
-	style?: "default" | "section";
+	style?: "default" | "section" | "category";
 	environment?: string | string[];
 }
 export interface FormSectionDivider {
@@ -1129,13 +1162,17 @@ type AnnotatedCallInfo$1 = CombinedCallInfo & {
 	originalValues?: AnnotatedCallInfo$1;
 	cfValues?: AnnotatedCallInfo$1;
 };
-export declare function annotateCallAgainstCountryFile(call: string): AnnotatedCallInfo$1;
+export declare function annotateCallAgainstCountryFile(call: string, options?: {
+	wae?: boolean;
+}): AnnotatedCallInfo$1;
 export declare function entityPrefixForCall(call: string | undefined): string | undefined;
 export declare function flagForDxccCode(dxccCode: number | undefined): string | undefined;
 export declare function regionAndCountryForDxccCode(dxccCode: number | undefined): {
 	ituRegion?: number;
 	countryCode?: string;
 };
+export declare function countryPrefixForCall(call: string | undefined): string | undefined;
+export declare function entityForCall(call: string | undefined): Pick<AnnotatedCallInfo$1, "dxccCode" | "continent" | "entityName">;
 export declare const LOCATION_ACCURACY: {
 	readonly EXACT: 0;
 	readonly ACCURATE: 2;
@@ -1149,6 +1186,14 @@ export declare function applyLatLonFromApiFields(target: {
 }, raw: Record<string, unknown>): void;
 export declare function canonicalMode(mode: string): string;
 export declare function modesMatchForDupe(worked: string, candidate: string): boolean;
+export declare function expectedSideband({ freqKHz, band }: {
+	freqKHz?: number;
+	band?: string;
+}): string | undefined;
+export declare function isUnexpectedSideband(mode: string | undefined | null, { freqKHz, band }: {
+	freqKHz?: number;
+	band?: string;
+}): boolean;
 export interface ContestScorerOptions {
 	scope?: ScoringScope;
 }
@@ -1156,6 +1201,8 @@ export declare function contestScorer<S extends Scoresheet = Scoresheet>(scorer:
 	scope: ScoringScope;
 };
 export declare function tally(key: string, forScope: "day" | "operation", total: number, extra?: Partial<ScoreTally>): ScoreTally;
+export declare function operationForQso(base: Record<string, JSONValue>, qso: Record<string, JSONValue>, segments?: OperationSegmentPayload[]): Record<string, JSONValue>;
+export declare function segmentsWith(segments: OperationSegmentPayload[] | undefined, transform: (operation: Record<string, JSONValue>) => Record<string, JSONValue>): OperationSegmentPayload[] | undefined;
 export type UniqueAxis = "day" | "band" | "mode" | "ref";
 export interface ActivityScoringRules {
 	label: string;
@@ -1210,9 +1257,10 @@ export declare function huntingExportHook(rules: HuntingExportRules): {
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
-export declare function adifForExport({ operation, qsos, includePrivateData, mainHandler, includeFieldsFrom }: {
+export declare function adifForExport({ operation, qsos, segments, includePrivateData, mainHandler, includeFieldsFrom }: {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
+	segments?: OperationSegmentPayload[];
 	includePrivateData?: boolean;
 	mainHandler: string;
 	includeFieldsFrom?: string[];
@@ -1236,6 +1284,12 @@ export interface ExportNameParts {
 }
 export declare function exportFilename(parts: ExportNameParts): string;
 export declare function startMillisOf(operation: Record<string, JSONValue>, qsos?: Record<string, JSONValue>[]): number | undefined;
+export type RefTransform = {
+	pattern: string;
+	replacement: string;
+	flags?: string;
+};
+export declare function transformsForPrefix(prefix: string): RefTransform[];
 export interface ReferenceActivityConfig {
 	key: string;
 	label: string;
@@ -1254,7 +1308,20 @@ export interface ReferenceActivityConfig {
 	adifRefField?: string;
 	allowsMultiple?: boolean;
 	linkUrl?: (reference: string) => string;
+	transforms?: RefTransform[];
+	refInput?: (args: RefInputArgs, ctx: HookContext) => Promise<RefInputExtras> | RefInputExtras;
+}
+export interface RefInputArgs {
+	operation: Record<string, JSONValue>;
+	qso?: Record<string, JSONValue>;
+	side: "activation" | "hunting";
+}
+export interface RefInputExtras {
+	placeholder?: string;
+	transforms?: RefTransform[];
 }
+export declare function learnedReferencePrefix(category: string, entityPrefix: string, fallback: string): Promise<string>;
+export declare function looksLikeReference(text: string, referenceRegex: RegExp): boolean;
 export interface ReferenceActivityHooks {
 	refHandler: Record<string, unknown>;
 	activityHook: Record<string, unknown>;

package/dist/index.js

@@ -1,17 +1,19 @@
-export * from "./types";
-export * from "./i18n";
-export * from "./dxcc";
-export * from "./location";
-export * from "./modes";
-export * from "./scoring";
-export * from "./activityScoring";
-export * from "./activityExports";
-export * from "./activityAdifImport";
-export * from "./exportNames";
-export * from "./referenceActivity";
-export * from "./templates";
-export * from "./templateContext";
-export * from "./testOperation";
+export * from "./types.js";
+export * from "./i18n.js";
+export * from "./dxcc.js";
+export * from "./location.js";
+export * from "./modes.js";
+export * from "./scoring.js";
+export * from "./segments.js";
+export * from "./activityScoring.js";
+export * from "./activityExports.js";
+export * from "./activityAdifImport.js";
+export * from "./exportNames.js";
+export * from "./referenceActivity.js";
+export * from "./refTransforms.js";
+export * from "./templates.js";
+export * from "./templateContext.js";
+export * from "./testOperation.js";
 let currentExtensionKey = "unknown";
 const privilegedHostCalls = {};
 function kernel() {

package/dist/modes.js

@@ -22,7 +22,27 @@ function modesMatchForDupe(worked, candidate) {
   const superMode = COARSE_SUPER_MODES[c];
   return Boolean(superMode) && KNOWN_MODES.has(w) && superModeForMode(w) === superMode;
 }
+const LSB_BANDS = /* @__PURE__ */ new Set(["2190m", "2200m", "630m", "560m", "160m", "80m", "75m", "40m"]);
+const UPPER_SIDEBAND_FLOOR_KHZ = 9e3;
+const SIXTY_METRE_LO_KHZ = 5e3;
+const SIXTY_METRE_HI_KHZ = 6e3;
+function expectedSideband({ freqKHz, band }) {
+  if (freqKHz != null) {
+    if (freqKHz >= UPPER_SIDEBAND_FLOOR_KHZ) return "USB";
+    return freqKHz >= SIXTY_METRE_LO_KHZ && freqKHz < SIXTY_METRE_HI_KHZ ? "USB" : "LSB";
+  }
+  if (!band) return void 0;
+  return LSB_BANDS.has(band) ? "LSB" : "USB";
+}
+function isUnexpectedSideband(mode, { freqKHz, band }) {
+  const upper = (mode ?? "").toUpperCase();
+  if (upper !== "USB" && upper !== "LSB") return false;
+  const expected = expectedSideband({ freqKHz, band });
+  return expected !== void 0 && upper !== expected;
+}
 export {
   canonicalMode,
+  expectedSideband,
+  isUnexpectedSideband,
   modesMatchForDupe
 };

package/dist/refTransforms.js

@@ -0,0 +1,34 @@
+function transformsForPrefix(prefix) {
+  return [
+    // a run of spaces between two refs -> ", " (normalize to one separator style)
+    { pattern: "([A-Z0-9]-\\d+|TEST) +(?=[A-Z0-9])", replacement: "${1}, ", flags: "gi" },
+    // bare number (or "TEST"), at the start or right after a separator -> prefix-number
+    // (the separator itself is captured and replayed, not consumed, so a
+    // pasted "US-1234,5678" keeps its comma instead of merging into one ref).
+    // Braced `${1}`/`${2}`, not bare `$1`/`$2` — `prefix` can itself start
+    // with a digit (e.g. DXCC "3D2" for Fiji), and a bare "$1" immediately
+    // followed by that would misparse as capture group 13.
+    { pattern: "(^|,\\s*)(\\d\\d+|TEST)", replacement: `\${1}${prefix}-\${2}`, flags: "gi" },
+    // "US1234" -> "US-1234". Anchored with a negative lookbehind so it only
+    // fires at the START of a not-yet-dashed reference — without it, a
+    // multi-character DXCC prefix that mixes letters and digits (e.g.
+    // Fiji's "3D2") gets its OWN internal "D2" mismatched as an undashed
+    // reference once transform 2 above has already inserted "3D2-1234",
+    // corrupting it into "3D-2-1234".
+    { pattern: "(?<![A-Z0-9])([A-Z]+)(\\d+|TEST)", replacement: "${1}-${2}", flags: "gi" },
+    // NOTE: deliberately no "eagerly insert the next prefix right after a
+    // trailing comma" rule here (app-polo's inputs have one) — transform 2
+    // above already prefixes a second reference once 2+ digits appear after
+    // the comma, the same way it does at the start of the field. An eager
+    // version that inserted "US-" the instant a trailing comma appeared
+    // makes deleting back through a second reference impossible: backspacing
+    // "US-1234,US-5678" down to "US-1234,US-" and then to "US-1234," would
+    // immediately re-grow the trailing "US-1234,US-" the transform had just
+    // reinserted, so the comma itself could never be reached.
+    // strip anything that can't appear in a reference list
+    { pattern: "[^A-Z0-9\\-, ]", replacement: "", flags: "gi" }
+  ];
+}
+export {
+  transformsForPrefix
+};