@ham2k/extension-sdk 0.12.15 → 1.12.0

package/README.md

@@ -53,6 +53,13 @@ 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.
 
+## Versions
+
+The minor version is the extension API: SDK 1.12 describes API 12, and
+exports it as `API_VERSION`. `@ham2k/extension-tools` follows the same rule,
+so a `^1.12.0` range says the extension needs API 12 and admits every later
+one. A major version is a change that breaks an extension already written.
+
 ## Export types and settings
 
 Export hooks can register shared types with `getExportTypes()`. Use

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.15
+// @ham2k/extension-sdk 1.12.0
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -1360,6 +1360,9 @@ export interface CommandAction {
 	findInLog?: {
 		query?: string;
 	};
+	navigate?: {
+		to: string;
+	};
 	setCallField?: {
 		text: string;
 	};
@@ -1456,6 +1459,8 @@ export interface CommandCatalogEntry {
 	params?: string;
 	category?: string;
 	needsOperation?: boolean;
+	needsTestData?: boolean;
+	keywords?: string[];
 	expectsParams?: boolean;
 	suggest?: boolean;
 }
@@ -2614,6 +2619,14 @@ export interface TemplateContextArgs {
 }
 export declare function templateContext(args: TemplateContextArgs): Record<string, unknown>;
 export declare function isTestOperation(stationCall: JSONValue | undefined): boolean;
+/**
+ * The extension API this SDK describes: the highest `api` a manifest written
+ * against it can declare, and the one its types and host calls are for. The
+ * SDK's and `@ham2k/extension-tools`' minor version is this number, so a
+ * `^1.<api>.0` range names the oldest API an extension needs and admits every
+ * later one.
+ */
+export declare const API_VERSION = 12;
 export declare function defineExtension(def: ExtensionDefinition): void;
 export declare const hooks: {
 	invokeAll(category: HookCategoryName, method: string, args: unknown, online?: boolean): Promise<{

package/dist/index.js

@@ -1,5 +1,6 @@
 import { base64ToBytes, bytesToBase64 } from "./base64.js";
 import { adoptExtensionTimers, clearInterval, clearTimeout, setInterval, setTimeout } from "./timers.js";
+const API_VERSION = 12;
 export * from "./types.js";
 export * from "./hookCategories.js";
 export * from "./panelScene.js";
@@ -426,6 +427,7 @@ const host = {
   }
 };
 export {
+  API_VERSION,
   defineExtension,
   hooks,
   host

package/docs/hooks.md

@@ -1170,10 +1170,10 @@ interface CommandHook {
   catalog?(ctx): Promise<CommandCatalogEntry[]>
 }
 // CommandInterpretation: {expectsParams?, mixedCase?, error?, describe?, confirm?, commands?: CommandAction[]}
-// CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
+// CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, needsTestData?, keywords?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
 //   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, autoRespot?, syncAll?, updateSettings?, updateSetting?, openSettings?,
-//   updateOperation?, markSegment?, findInLog?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
+//   updateOperation?, markSegment?, findInLog?, navigate?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
 ```
@@ -1366,9 +1366,12 @@ Three things differ from `interpret`, all deliberate:
 - **Called once and cached**, not per keystroke — dropped when the runtime is
   replaced (an extension enabled/disabled) or the hook context is
   invalidated (locale change, since `describe` is localized by the hook).
-- **Matching is host-side**, plain case-insensitive substring against
-  `command` and `describe`. Same rule `interpret`'s own matching follows: the
-  host never compiles extension-supplied patterns.
+- **Matching is host-side**, case-insensitive, at the start of a word in
+  `command` or in `keywords` — never mid-word, and `describe` is never
+  searched. Every word that should find a command belongs in its
+  `keywords`: the aliases it accepts when typed, and plain words for what it
+  does. Same rule `interpret`'s own matching follows: the host never
+  compiles extension-supplied patterns.
 - **List commands, not variants.** `radio-commands` advertises one BAND
   entry, not fifteen; `call-notes` advertises `//`, not every key the user
   has defined.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.12.15",
+  "version": "1.12.0",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",

package/samples/k2hrc-panafall/README.md

@@ -4,9 +4,17 @@ The radio's panadapter and waterfall in a scene panel, with its span, reference
 level and sweep speed, a local contrast control, and click-to-tune. The host
 draws the sweeps in the `spectrum` control; they never reach the extension.
 
-Needs a radio whose CAT protocol carries its scope: an Icom IC-705/7300/7610 (at
-115200 bps on a serial line), or a FlexRadio, which is mirrored through a DAX IQ
-channel.
+Needs a supported radio:
+
+- Icom IC-705/7300/7610, at 115200 bps when using a serial line.
+- FlexRadio, mirrored through a DAX IQ channel.
+- Elecraft K4 over Ethernet, with a separate local TCP spectrum connection on
+  port 9201 alongside CAT. It displays the main panadapter with local zoom,
+  reference and speed controls. Levels are displayed as received, without an
+  RF calibration claim.
+
+The panel shows only the controls each radio supports; contrast, averaging,
+frame rate and waterfall rows remain local.
 
 In this repository:
 
@@ -14,3 +22,8 @@ In this repository:
 node build.mjs
 node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-panafall.h2kext
 ```
+
+Samples are not included in the app's regular extension build. Install the
+resulting `.h2kext` through **Settings → Extensions & Features → Install from
+file…**, then add its **Panadapter** panel to an operation. The host must have
+the matching radio support.

package/samples/k2hrc-panafall/src/panafall.ts

@@ -42,15 +42,25 @@ const spanLabel = (hz: number) => `±${hz >= 1000 ? `${hz / 1000} kHz` : `${hz}
 export function scene(radio: PanelRadioState | null, display: Display, step = "100"): PanelScene {
   const spectrum: PanelRadioSpectrum | null | undefined = radio?.spectrum
   const knobs = spectrum && !spectrum.problem
+  const hasSpan = knobs && spectrum.spansHz.length > 0
+  const hasSpeed = knobs && spectrum.speeds.length > 0
+  const hasRef =
+    knobs &&
+    Number.isFinite(spectrum.refMinDb) &&
+    Number.isFinite(spectrum.refMaxDb) &&
+    Number.isFinite(spectrum.refStepDb) &&
+    spectrum.refMinDb < spectrum.refMaxDb &&
+    spectrum.refStepDb > 0
+  const ref = hasRef ? Math.max(spectrum.refMinDb, Math.min(spectrum.refMaxDb, spectrum.refLevelDb ?? spectrum.refMinDb)) : 0
   const band = passband(radio?.mode)
   return {
     version: 1,
     width: 600,
     height: 24,
-    values: { floor: 0, average: 40, fps: 15, rows: 10, hoverHz: 0, hoverDb: 0, ref: spectrum?.refLevelDb ?? 0 },
+    values: { floor: 0, average: 40, fps: 15, rows: 10, hoverHz: 0, hoverDb: 0, ref },
     strings: {
-      span: spectrum?.spanHz != null ? String(spectrum.spanHz) : "",
-      speed: spectrum?.speed ?? "",
+      span: hasSpan && spectrum.spanHz != null && spectrum.spansHz.includes(spectrum.spanHz) ? String(spectrum.spanHz) : "",
+      speed: hasSpeed && spectrum.speed != null && spectrum.speeds.includes(spectrum.speed) ? spectrum.speed : "",
       display,
       step,
     },
@@ -65,7 +75,7 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
       },
     ],
     controls: [
-      ...(knobs
+      ...(hasSpan
         ? [
             {
               id: "span",
@@ -75,6 +85,10 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
               event: "span",
               options: spectrum.spansHz.map((hz) => ({ label: spanLabel(hz), value: String(hz) })),
             },
+          ]
+        : []),
+      ...(hasRef
+        ? [
             {
               id: "ref",
               label: "Reference level",
@@ -85,6 +99,10 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
               max: spectrum.refMaxDb,
               step: spectrum.refStepDb,
             },
+          ]
+        : []),
+      ...(hasSpeed
+        ? [
             {
               id: "speed",
               label: "Speed",
@@ -100,7 +118,7 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
       { id: "fps", label: "Panadapter FPS", kind: "nativeSlider" as const, value: "fps", min: 1, max: 30, step: 1 },
       { id: "rows", label: "Waterfall rows per second", kind: "nativeSlider" as const, value: "rows", min: 1, max: 30, step: 1 },
       // A control the layout does not place fails the scene: Ref's label goes with its slider.
-      ...[...(knobs ? ["Ref"] : []), "Contrast", "Avg", "FPS", "Rows"].map((text) => ({
+      ...[...(hasRef ? ["Ref"] : []), "Contrast", "Avg", "FPS", "Rows"].map((text) => ({
         id: `label-${text}`,
         label: text,
         kind: "nativeText" as const,
@@ -179,7 +197,9 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
       column: [
         {
           wrap: [
-            ...(knobs ? [{ control: "span" }, labeled("Ref", "ref"), { control: "speed" }] : []),
+            ...(hasSpan ? [{ control: "span" }] : []),
+            ...(hasRef ? [labeled("Ref", "ref")] : []),
+            ...(hasSpeed ? [{ control: "speed" }] : []),
             labeled("Contrast", "floor"),
             labeled("Avg", "average"),
             labeled("FPS", "fps"),