@ham2k/extension-sdk 0.12.5 → 0.12.7

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.5
+// @ham2k/extension-sdk 0.12.7
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -556,6 +556,7 @@ export interface HookContext {
 	getOperation?(uuid: string): Promise<Record<string, JSONValue> | null>;
 	getQsos?(operationUuid: string): Promise<Record<string, JSONValue>[] | null>;
 	getSpotsForCall?(call: string, maxAgeMinutes?: number): Promise<Spot[]>;
+	getSpots?(options?: GetSpotsOptions): Promise<BoardSpot[]>;
 	getHistoryForCall?(call: string, options?: HistoryForCallOptions): Promise<Record<string, JSONValue>[]>;
 }
 export interface HistoryForCallOptions {
@@ -624,6 +625,24 @@ export interface Spot {
 		sourceInfo?: Record<string, JSONValue>;
 	};
 }
+export interface GetSpotsOptions {
+	filter?: "user" | "all";
+	maxAgeMinutes?: number;
+	band?: string | string[];
+	mode?: string | string[];
+	source?: string | string[];
+	annotate?: boolean;
+	operationUuid?: string;
+}
+export interface BoardSpot extends Spot {
+	hookKey?: string;
+	annotations?: SpotAnnotations;
+}
+export interface SpotAnnotations {
+	worked: boolean;
+	isSelf: boolean;
+	notices: string[];
+}
 export interface SpotEligibility {
 	enabled: boolean;
 	icon?: string;

package/docs/hooks.md

@@ -70,6 +70,31 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   reads above it is cheap enough for the lookup path; it resolves `[]`
   whenever the cache is cold or the host keeps no spots. Used by
   `spot-history` to pull a hunted park or summit into the QSO being logged.
+* `getSpots?(options?)` — the whole spots board the host already holds,
+  for a panel showing spots its own way. Like `getSpotsForCall` it reads the
+  cache and never fetches, and resolves `[]` while the cache is cold. By
+  default it answers what the operator's Spots Panel shows: their sources,
+  enabled bands, band and mode filters (an "auto" filter follows the radio),
+  age and continents, merged and ordered as that panel does — so one spot
+  can stand for several stations, its `their.call` comma-joined
+  (`'K1ABC,W2XYZ'`). `filter: 'all'`
+  starts instead from every held spot, one per source report, newest first.
+  Either way `maxAgeMinutes`, `band`, `mode` (a mode, or `SSB`/`Phone`/`CW`/
+  `Digital` for a family) and `source` (a spot source's hook key, carried on
+  each spot as `hookKey`) narrow it further. Spots come back with
+  `annotations` — `worked`, `isSelf`, `notices`, judged the way the Spots
+  Panel strikes and accents its rows — whenever there is an operation to judge
+  them against: `operationUuid`, or the `operation` the calling hook was
+  handed, so a panel's render gets them without asking. The verdicts are the
+  ones the app already holds for the operation open on screen, so the call
+  never waits on a scorer; another operation's spots, and that one's until
+  its first verdicts land, come back unannotated rather than guessed.
+  `annotate: false` returns the spots as their sources gave them.
+  A panel's `'spots'` trigger fires whenever this answer may have moved: a
+  refresh, new verdicts, the operator's spot filters or bands, or the radio's
+  band or mode. A malformed or unknown option rejects the call. The CLI host
+  has no operator: its `'user'` board is every spot handed to it, never
+  annotated.
 * `getHistoryForCall?(call, options?)` — the most recent non-deleted contacts
   logged with `call` (five unless `limit` says otherwise, never more than
   50), across every operation, newest first, as raw QSON — the one log read
@@ -1975,7 +2000,9 @@ its first render.
 
 The whole log is deliberately absent from `render`'s args. A panel that
 needs it calls `ctx.getQsos(operation.uuid)` — right for a `'qsoLogged'`
-render, wrong for a per-keystroke one.
+render, wrong for a per-keystroke one. Spots are absent for the same reason:
+a panel showing them declares `'spots'` and calls `ctx.getSpots()`, which
+answers the operator's own filtered board, judged against this operation.
 
 ## ✅ `settingsPanel` — extension settings forms
 

package/package.json

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

package/samples/README.md

@@ -11,6 +11,7 @@ building — the header comment in each `src/index.ts` says what it leaves out.
 | `k2hrc-cqww` | A contest: an exchange to type, and a score to keep |
 | `k2hrc-radio` | An HTML panel, and why you should probably write markdown instead |
 | `k2hrc-panel-scenes` | Experimental panel scenes: SVG artwork, controls and animations, with simulated radio and weather panels |
+| `k2hrc-panafall` | A radio's panadapter and waterfall in a scene, styled and tuned by click (extension API 6) |
 
 ## Running one
 

package/samples/k2hrc-panafall/README.md

@@ -0,0 +1,16 @@
+# Panadapter & Waterfall
+
+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 host with the panadapter enabled (`EXP FALL`) and 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.
+
+In this repository:
+
+```sh
+node build.mjs
+node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-panafall.h2kext
+```

package/samples/k2hrc-panafall/build.mjs

@@ -0,0 +1,6 @@
+import { build } from "esbuild"
+import { buildExtension } from "@ham2k/extension-tools"
+
+await buildExtension(build, { dir: import.meta.dirname })
+
+console.log("built build/index.js")

package/samples/k2hrc-panafall/manifest.json

@@ -0,0 +1,24 @@
+{
+  "key": "k2hrc-panafall",
+  "name": "Panadapter & Waterfall",
+  "shortName": "Panafall",
+  "version": "0.1.0",
+  "description": "The radio's panadapter and waterfall, with span, reference level and click-to-tune",
+  "category": "dashboard",
+  "icon": "waveform",
+  "accentColor": "#4C6EF5",
+  "api": 6,
+  "keywords": ["radio", "panadapter", "waterfall", "spectrum", "panel", "sample"],
+  "hooks": ["panel"],
+  "requiresRadioWrite": true,
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.0",
+    "@ham2k/lib-country-files": "^1.0.0",
+    "@ham2k/lib-dxcc-data": "^1.0.0",
+    "@ham2k/lib-format-tools": "^1.0.0",
+    "@ham2k/lib-geo-tools": "^1.0.0",
+    "@ham2k/lib-operation-data": "^1.0.0",
+    "i18next": "^23.0.0",
+    "liquidjs": "^10.0.0"
+  }
+}

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

@@ -0,0 +1,12 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+import { defineExtension } from "@ham2k/extension-sdk"
+import manifest from "../manifest.json" with { type: "json" }
+import { createPanafall } from "./panafall.ts"
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("panel", { key: manifest.key, hook: createPanafall() })
+  },
+})

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

@@ -0,0 +1,238 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// The radio's scope as a scene: the host draws the sweeps in the `spectrum`
+// control, and this extension only places it and turns the radio's knobs.
+import { host } from "@ham2k/extension-sdk"
+import type { PanelContent, PanelHook, PanelRadioSpectrum, PanelRadioState, PanelScene } from "@ham2k/extension-sdk"
+
+type Display = "both" | "pan" | "waterfall"
+
+/** A slider with its label beside it, kept together when the wrap breaks. */
+const labeled = (text: string, control: string) => ({
+  wrap: [{ control: `label-${text}` }, { control, width: 120 }],
+  spacing: 4,
+  crossAxisAlignment: "center" as const,
+})
+
+/** Where the receiver listens, from the tuned frequency, by mode. A sketch: the radio's real filter is not reported. */
+function passband(mode: string | null | undefined): [number, number] | null {
+  if (!mode) return null
+  if (mode.includes("LSB")) return [-2800, -100]
+  if (mode.includes("USB") || mode.startsWith("DATA") || mode === "FT8" || mode === "FT4") return [100, 2800]
+  if (mode.startsWith("CW")) return [-250, 250]
+  if (mode === "AM" || mode === "FM") return [-3000, 3000]
+  return null
+}
+
+const cyan = "#2EC5F0"
+
+/** Landmarks on 20 m: something to read, and to click to go to. */
+const landmarks: [string, number, "start" | "center" | "end"][] = [
+  ["PSK", 14070000, "center"],
+  ["FT8", 14074000, "start"],
+  ["FT4", 14080000, "center"],
+  ["SSTV", 14230000, "start"],
+  ["QRP", 14285000, "end"],
+  ["Maritime net", 14300000, "center"],
+]
+
+const spanLabel = (hz: number) => `±${hz >= 1000 ? `${hz / 1000} kHz` : `${hz} 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 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 },
+    strings: {
+      span: spectrum?.spanHz != null ? String(spectrum.spanHz) : "",
+      speed: spectrum?.speed ?? "",
+      display,
+      step,
+    },
+    layers: [
+      {
+        id: "readout",
+        x: 0,
+        y: 0,
+        width: 600,
+        height: 24,
+        text: { value: "hoverHz", scale: 0.001, decimals: 3, suffix: " kHz", size: 14 },
+      },
+    ],
+    controls: [
+      ...(knobs
+        ? [
+            {
+              id: "span",
+              label: "Span",
+              kind: "nativeDropdown" as const,
+              value: "span",
+              event: "span",
+              options: spectrum.spansHz.map((hz) => ({ label: spanLabel(hz), value: String(hz) })),
+            },
+            {
+              id: "ref",
+              label: "Reference level",
+              kind: "nativeSlider" as const,
+              value: "ref",
+              event: "ref",
+              min: spectrum.refMinDb,
+              max: spectrum.refMaxDb,
+              step: spectrum.refStepDb,
+            },
+            {
+              id: "speed",
+              label: "Speed",
+              kind: "nativeSegmented" as const,
+              value: "speed",
+              event: "speed",
+              options: spectrum.speeds.map((s) => ({ label: s, value: s })),
+            },
+          ]
+        : []),
+      { id: "floor", label: "Contrast", kind: "nativeSlider" as const, value: "floor", min: -30, max: 30, step: 1 },
+      { id: "average", label: "Averaging", kind: "nativeSlider" as const, value: "average", min: 0, max: 95, step: 5 },
+      { 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) => ({
+        id: `label-${text}`,
+        label: text,
+        kind: "nativeText" as const,
+      })),
+      {
+        id: "step",
+        label: "Tuning step",
+        kind: "nativeSegmented" as const,
+        value: "step",
+        event: "step",
+        options: ["10", "100", "500", "1000"].map((hz) => ({ label: Number(hz) >= 1000 ? `${Number(hz) / 1000} kHz` : `${hz} Hz`, value: hz })),
+      },
+      {
+        id: "display",
+        label: "Display",
+        kind: "nativeSegmented" as const,
+        value: "display",
+        event: "display",
+        options: (["both", "pan", "waterfall"] as const).map((d) => ({ label: d, value: d })),
+      },
+      {
+        id: "spectrum",
+        label: "Panadapter",
+        kind: "spectrum" as const,
+        event: "tune",
+        display,
+        floor: "floor",
+        average: "average",
+        fps: "fps",
+        waterfallSpeed: "rows",
+        backgroundColor: "#0B0E17",
+        traceColor: "#3FD0F0",
+        fillColor: "#CC3FD0F0",
+        fillColorBottom: "#B3104A5C",
+        gridColor: "#2A3446",
+        gridDashed: true,
+        scale: {
+          gap: 26,
+          background: "#151B26",
+          borderTop: { color: "#2A3446", width: 1 },
+          borderBottom: { color: "#2A3446", width: 1 },
+          labels: { color: "#8FA3B8", size: 12, offset: 8 },
+          ticks: { color: "#8FA3B8", width: 1, offset: 0, length: 5 },
+        },
+        // Noise to black, as the radio's own display does: the waterfall's window sits above the panadapter's.
+        waterfallFloor: 12,
+        waterfallRange: 50,
+        waterfallColors: ["#000000", "#00004A", "#0000FF", "#00C8FF", "#00FF60", "#FFFF00", "#FF2000"],
+        center: { pan: { color: cyan, width: 4 }, waterfall: { color: cyan, width: 4 } },
+        tuneStep: Number(step),
+        annotations: landmarks.map(([text, hz, align]) => ({
+          id: text,
+          text,
+          hz,
+          align,
+          borderColor: "#FFB020",
+          pointer: { size: 5 },
+          event: "goto",
+          offset: 6,
+          color: "#0B0E17",
+          background: "#E6FFB020",
+          size: 11,
+          weight: 600,
+        })),
+        overlays: [
+          ...(band ? [{ from: band[0], to: band[1], pan: { fill: "#262EC5F0", color: "#992EC5F0" } }] : []),
+          // The bottom of 20 m, and what lies outside it: scenery behind the trace, over the waterfall.
+          { at: 14000000, anchor: "absolute" as const, pan: { color: "#FF3030", width: 3 }, waterfall: { color: "#FF3030", width: 3 } },
+          { from: 13900000, to: 14000000, anchor: "absolute" as const, pan: { fill: "#33FF3030" }, waterfall: { fill: "#33FF3030" } },
+        ],
+        hoverHz: "hoverHz",
+        hoverDb: "hoverDb",
+      },
+    ],
+    layout: {
+      column: [
+        {
+          wrap: [
+            ...(knobs ? [{ control: "span" }, labeled("Ref", "ref"), { control: "speed" }] : []),
+            labeled("Contrast", "floor"),
+            labeled("Avg", "average"),
+            labeled("FPS", "fps"),
+            labeled("Rows", "rows"),
+            { control: "step" },
+            { control: "display" },
+          ],
+          spacing: 8,
+          runSpacing: 4,
+          padding: 4,
+        },
+        { control: "spectrum", flex: 1 },
+        { scene: true, height: 24 },
+      ],
+      crossAxisAlignment: "stretch",
+    },
+  }
+}
+
+export function createPanafall(): PanelHook {
+  const displays = new Map<string, Display>()
+  const steps = new Map<string, string>()
+  return {
+    async getPanels() {
+      return [{ key: "panafall", title: "Panadapter", icon: "waveform", multiple: true, on: ["tick:2"] }]
+    },
+    async render(args): Promise<PanelContent> {
+      const id = args.instanceId ?? ""
+      return { kind: "scene", scene: scene(await host.readRadio(), displays.get(id) ?? "both", steps.get(id) ?? "100") }
+    },
+    async onEvent(args) {
+      const { action, value, text } = args.event
+      if (action === "step") {
+        steps.set(args.instanceId ?? "", text ?? "100")
+        return { values: {} }
+      }
+      if (action === "display") {
+        displays.set(args.instanceId ?? "", (text as Display) ?? "both")
+        return { values: {} }
+      }
+      const radio = await host.readRadio()
+      if (!radio?.id) return { values: {} }
+      if ((action === "tune" || action === "goto") && typeof value === "number") {
+        // Already on the step: the host snapped it.
+        await host.tuneRadio({ id: radio.id, frequencyHz: Math.round(value) })
+      } else if (action === "span" && text) {
+        await host.setRadioSpectrum({ id: radio.id, spanHz: Number(text) })
+      } else if (action === "ref" && typeof value === "number") {
+        await host.setRadioSpectrum({ id: radio.id, refLevelDb: value })
+      } else if (action === "speed" && text) {
+        await host.setRadioSpectrum({ id: radio.id, speed: text as "slow" | "mid" | "fast" })
+      }
+      return { values: {} }
+    },
+  }
+}