@ham2k/extension-sdk 0.12.10 → 0.12.12

package/AGENTS.md

@@ -81,7 +81,7 @@ will actually call.
 
 | 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), `k2hrc-panel-scenes` (experimental interactive panel scene) |
+| Anything, before the reference — a whole worked extension of that shape | `samples/`: `k2hrc-hello-world` (the smallest panel), `k2hrc-hamqth` (lookup + credentials), `k2hrc-llota` (award program), `k2hrc-cqww` (contest + scoring), `k2hrc-radio` (HTML panel), `k2hrc-panel-scenes` (experimental interactive panel scene), `k2hrc-panafall` (panadapter and waterfall scene) |
 | 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>` |

package/dist/hookCategories.js

@@ -6,6 +6,7 @@ const HOOK_CATEGORIES = [
   "bench",
   "callNotes",
   "chasing",
+  "cluster",
   "command",
   "dataFile",
   "export",

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.10
+// @ham2k/extension-sdk 0.12.12
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -475,6 +475,7 @@ export declare const HOOK_CATEGORIES: readonly [
 	"bench",
 	"callNotes",
 	"chasing",
+	"cluster",
 	"command",
 	"dataFile",
 	"export",
@@ -733,6 +734,39 @@ export interface SpotsHook {
 	postSelfSpot?(args: PostSelfSpotRequest, ctx: HookContext): Promise<PostResult>;
 	postOtherSpot?(args: PostOtherSpotRequest, ctx: HookContext): Promise<PostResult>;
 }
+export interface ClusterLine {
+	seq: number;
+	at: number;
+	text: string;
+}
+export interface ClusterStatus {
+	state: "idle" | "connecting" | "connected" | "failed";
+	node: {
+		name: string;
+		host: string;
+		port: number;
+	};
+	call?: string;
+	error?: string;
+	message?: string;
+	lastSeq: number;
+}
+export interface ClusterReply {
+	ok: boolean;
+	lines: string[];
+	error?: string;
+	message?: string;
+}
+export interface ClusterPostSpotRequest {
+	freq: number;
+	call: string;
+	comment?: string;
+}
+export interface ClusterHook {
+	onLines(args: {
+		lines: ClusterLine[];
+	}, ctx: HookContext): Promise<void>;
+}
 export interface Ref {
 	type: string;
 	ref?: string;
@@ -1219,6 +1253,10 @@ export interface CommandAction {
 		comment?: string;
 		target?: "self" | "last";
 	};
+	autoRespot?: {
+		minutes?: number;
+		off?: boolean;
+	};
 	syncAll?: Record<string, never>;
 	purgeTests?: Record<string, never>;
 	updateSettings?: {
@@ -1480,6 +1518,9 @@ export interface ExtensionManifest {
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
 	requiresRadioWrite?: boolean;
+	requiresClusterRead?: boolean;
+	requiresClusterSpot?: boolean;
+	requiresClusterCommand?: boolean;
 	experiments?: string[];
 	relevance?: ExtensionRelevance;
 	translations?: Record<string, {
@@ -1623,6 +1664,7 @@ export interface FormField {
 	templateContext?: "export" | "adif" | "text";
 	templateSample?: Record<string, JSONValue>;
 	uppercase?: boolean;
+	storedText?: string;
 	suggestions?: {
 		code: string;
 		name?: string;
@@ -2501,6 +2543,20 @@ export declare const host: {
 	}): Promise<PanelRadioResult>;
 	/** Stops all CW, voice and PTT the app is keying, and a tune it started (extension API 9), as Escape does. Needs `requiresRadioWrite` and extension API 7. */
 	stopRadioTransmit(args: PanelRadioTarget): Promise<PanelRadioResult>;
+	/** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
+	clusterStatus(): Promise<ClusterStatus>;
+	/** The node's recent lines after `after`, oldest first, at most `limit` of the newest. Needs `requiresClusterRead` and extension API 10. */
+	clusterLines(args?: {
+		after?: number;
+		limit?: number;
+	}): Promise<ClusterLine[]>;
+	/** Connects if need be and delivers every new line to this extension's `cluster` hook until `clusterUnsubscribe`. Needs `requiresClusterRead` and extension API 10. */
+	clusterSubscribe(): Promise<ClusterStatus>;
+	clusterUnsubscribe(): Promise<ClusterStatus>;
+	/** Posts a spot, logged in as the operator. Needs `requiresClusterSpot` and extension API 10. */
+	clusterPostSpot(args: ClusterPostSpotRequest): Promise<ClusterReply>;
+	/** Sends any one command line, in the operator's name. Needs `requiresClusterCommand` and extension API 10. */
+	clusterSend(command: string): Promise<ClusterReply>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;
 	kvGet(key: string): Promise<JSONValue | null>;

package/dist/index.js

@@ -197,6 +197,29 @@ const host = {
   async stopRadioTransmit(args) {
     return await hostCallFn()("stopRadioTransmit", { ...args });
   },
+  /** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
+  async clusterStatus() {
+    return await hostCallFn()("clusterStatus", {});
+  },
+  /** The node's recent lines after `after`, oldest first, at most `limit` of the newest. Needs `requiresClusterRead` and extension API 10. */
+  async clusterLines(args = {}) {
+    return await hostCallFn()("clusterLines", { ...args });
+  },
+  /** Connects if need be and delivers every new line to this extension's `cluster` hook until `clusterUnsubscribe`. Needs `requiresClusterRead` and extension API 10. */
+  async clusterSubscribe() {
+    return await hostCallFn()("clusterSubscribe", {});
+  },
+  async clusterUnsubscribe() {
+    return await hostCallFn()("clusterUnsubscribe", {});
+  },
+  /** Posts a spot, logged in as the operator. Needs `requiresClusterSpot` and extension API 10. */
+  async clusterPostSpot(args) {
+    return await hostCallFn()("clusterPostSpot", { ...args });
+  },
+  /** Sends any one command line, in the operator's name. Needs `requiresClusterCommand` and extension API 10. */
+  async clusterSend(command) {
+    return await hostCallFn()("clusterSend", { command });
+  },
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },

package/dist/templateContext.js

@@ -39,7 +39,9 @@ function opValues(operation, extra = {}) {
         station.split(",").map((call) => call.trim().toUpperCase()).filter((call) => call !== "")
       )
     ],
-    operator: operation.operator ?? "",
+    // Resolved by the host for this device's position; a template cannot do it
+    // itself, because the position never crosses the bridge.
+    operator: operation.operatorCall ?? "",
     // The generated, ref-derived title ("at US-1234") and the operator's own
     // words, kept apart: an export that withholds private data withholds the
     // second and keeps the first (see the adif hook's preamble).

package/docs/distribution.md

@@ -240,7 +240,7 @@ what you want, which is how you use a version the host does not carry, say so:
 await buildExtension(build, { dir: import.meta.dirname, inline: ["liquidjs"] })
 ```
 
-`extensions/samples/hello-world` is the shortest complete example. Declaring
+`extensions/samples/k2hrc-hello-world` is the shortest complete example. Declaring
 what it uses rather than carrying it took the packaged bundle from 185 KB to
 **4 KB**.
 

package/docs/forms.md

@@ -38,6 +38,10 @@ export interface FormField {
   value?: any; // initial state value if not provided in host call state
   placeholder?: string;
   uppercase?: boolean; // force typed input to uppercase (callsign fields always are)
+  // Only used when fieldType === 'secret' in a settings list: what the row
+  // says while a value is stored, in place of the fixed mask. A host older
+  // than this shows the mask.
+  storedText?: string;
   // Only used when fieldType === 'text': the codes the field takes, offered
   // in a list under it as the operator types (matched on code and name, as a
   // `kind: 'options'` logging control matches) and named beside it — a value

package/docs/hooks.md

@@ -330,6 +330,48 @@ directly to the POTA API, no auth required). `sota`'s spot API requires an
 authenticated account app-halo doesn't have yet, so `sota` stays
 fetch-only for now.
 
+## ✅ `cluster` — the DX cluster connection
+
+```ts
+interface ClusterHook {
+  onLines(args: { lines: ClusterLine[] }, ctx): Promise<void>
+}
+// ClusterLine: {seq, at, text}
+// host.clusterSubscribe(): Promise<ClusterStatus>   // then onLines, until
+// host.clusterUnsubscribe(): Promise<ClusterStatus> // this
+// host.clusterLines({after?, limit?}): Promise<ClusterLine[]>
+// host.clusterStatus(): Promise<ClusterStatus>
+// host.clusterPostSpot({freq, call, comment?}): Promise<ClusterReply>
+// host.clusterSend(command): Promise<ClusterReply>
+// ClusterReply: {ok, lines: string[], error?, message?}
+```
+
+The app holds one telnet connection to the DX cluster node the operator picked
+in Settings, logged in as the operator. Extensions share it rather than open
+their own, because a node logs a call in once
+([docs/design/cluster.md](https://github.com/ham2k/halo/blob/main/docs/design/cluster.md)). Not on web, where every call
+answers `error: 'unsupported'`. Extension API 10.
+
+`clusterPostSpot` is how a `spots` hook posts to the cluster: the host builds
+the `DX` command, sends at most 60 characters of comment, and spaces spots five
+seconds apart. A reply with `ok: true` means the node took the spot without
+refusing it. It does not prove the spot left that node: a DXSpider node can keep
+a self-spot local and still echo it.
+
+`onLines` is called only for an extension that called `clusterSubscribe()`,
+with the lines since the last batch, at most once a second. Register the hook
+under the extension's own key (the default): that is the key the host delivers
+to. A subscription lasts until `clusterUnsubscribe()` or the runtime restarts,
+and keeps the session open while it lasts. A reader that only polls
+`clusterLines({ after })` holds nothing open.
+
+Three manifest grants gate it, each including the ones before it:
+`"requiresClusterRead": true` for status, lines and subscribing;
+`"requiresClusterSpot": true` adds `clusterPostSpot`;
+`"requiresClusterCommand": true` adds `clusterSend`, which sends any command in
+the operator's name. Declare the least you need: the consent screen names it.
+Implemented by: `ki2d-cluster-spotter` (spot).
+
 ## ✅ `export` — log file generation
 
 ```ts
@@ -1070,7 +1112,7 @@ interface CommandHook {
 // CommandInterpretation: {expectsParams?, mixedCase?, error?, describe?, confirm?, commands?: CommandAction[]}
 // CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
-//   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, syncAll?, updateSettings?, updateSetting?, openSettings?,
+//   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, autoRespot?, syncAll?, updateSettings?, updateSetting?, openSettings?,
 //   updateOperation?, markSegment?, setCallField?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
@@ -1656,6 +1698,11 @@ interface PanelHook {
 //                | {kind: 'scene', scene, title?, triggers?}   (see Panel scene reference)
 ```
 
+`operation` is the operation's data with its `uuid`, its
+`startAtMillisMin`/`startAtMillisMax`, and `operatorCall`: who is at the key on
+this device, resolved for its position in a multi-station operation, and empty
+when nobody is named.
+
 The host addresses a panel as `ext:<hookKey>:<key>`, and that id is stored
 inside saved layouts — renaming a `key` drops the panel out of every
 arrangement holding it.

package/docs/templates.md

@@ -65,7 +65,8 @@ An ISO-8601 UTC string, for the `date` filter: `{{ now | date: '%H:%M' }}`.
 ### `op` — the operation
 `station` (the field as typed, which may hold several comma-separated
 callsigns; `call` is the same value, the name `qso.call` has), `stations`
-(that list, uppercased and deduped), `operator`,
+(that list, uppercased and deduped), `operator` (who is at the key on this
+device, empty when nobody is named),
 `title` (the generated, ref-derived one), `userTitle` (the operator's own
 words), `grid`, `refs`, `uuid`, `qsoCount`, `date`, `dateCompact`, `time`,
 `at`, `startDate`, `startTime`, `startAt`, `endDate`, `endTime`, `endAt`.

package/package.json

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

package/samples/README.md

@@ -6,6 +6,7 @@ building — the header comment in each `src/index.ts` says what it leaves out.
 
 | | |
 | --- | --- |
+| `k2hrc-hello-world` | The smallest extension there is: one panel, saying hello |
 | `k2hrc-hamqth` | A callsign lookup, and the `account` hook that asks for a password |
 | `k2hrc-llota` | An award program: references, an offline list, activation scoring |
 | `k2hrc-cqww` | A contest: an exchange to type, and a score to keep |

package/samples/k2hrc-hello-world/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-hello-world/manifest.json

@@ -0,0 +1,22 @@
+{
+  "key": "k2hrc-hello-world",
+  "name": "Hello World",
+  "shortName": "Hello",
+  "version": "1.0.0",
+  "description": "The smallest possible Ham2K extension — a panel that says hello",
+  "category": "dashboard",
+  "icon": "hand-wave-outline",
+  "api": 1,
+  "keywords": ["sample", "example", "hello"],
+  "hooks": ["panel"],
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.2",
+    "@ham2k/lib-country-files": "^1.0.202605301",
+    "@ham2k/lib-dxcc-data": "^1.0.1",
+    "@ham2k/lib-format-tools": "^1.1.3",
+    "@ham2k/lib-geo-tools": "^1.1.1",
+    "@ham2k/lib-operation-data": "^1.1.3",
+    "i18next": "^23.16.8",
+    "liquidjs": "^10.28.0"
+  }
+}

package/samples/k2hrc-hello-world/src/index.ts

@@ -0,0 +1,53 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// The smallest extension that does something visible: one panel, saying hello.
+//
+// It exists to be COPIED. Everything here is the minimum — one hook, one
+// descriptor, one render — so that what a real extension adds is obvious by
+// comparison. See the catalog's `ham2k-custom-text` for a panel that earns its
+// keep, and docs/extensions/hooks.md for every other hook there is.
+//
+// Its manifest still lists the host's shared libraries in `sharedDependencies`:
+// the SDK reaches them, and declaring them makes the bundle use the host's
+// copy rather than carry its own — see docs/extensions/distribution.md.
+
+import { defineExtension } from "@ham2k/extension-sdk"
+import type { HookContext, PanelContent, PanelDescriptor, PanelHook, PanelRenderArgs } from "@ham2k/extension-sdk"
+
+import manifest from "../manifest.json"
+
+const HelloPanel: PanelHook = {
+  /// What the operator sees when choosing a panel to place.
+  async getPanels(_args: Record<string, never>, _ctx: HookContext): Promise<PanelDescriptor[]> {
+    return [
+      {
+        key: "hello",
+        title: "Hello World",
+        description: "A panel that says hello",
+        icon: "hand-wave-outline",
+      },
+    ]
+  },
+
+  /// What the pane shows. Markdown, rendered by the app — a panel returns
+  /// content, never widgets, which is what keeps extensions out of the UI
+  /// toolkit's way.
+  ///
+  /// The method is `render`, not `renderPanel`: the host routes to the hook by
+  /// its registered key and then calls this by name, so a near-miss is a panel
+  /// that installs, activates, and then renders nothing.
+  async render(_args: PanelRenderArgs, _ctx: HookContext): Promise<PanelContent> {
+    return {
+      kind: "markdown",
+      content: ["# Hello, World!", "", "This panel came from an extension installed from a `.h2kext` file."].join("\n"),
+    }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("panel", { key: "k2hrc-hello-world", hook: HelloPanel })
+  },
+})