@ham2k/extension-sdk 0.12.9 → 0.12.11

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/copyOnWrite.js

@@ -1,5 +1,9 @@
 function copyOnWrite(base) {
-  return isContainer(base) ? wrap(base) : base;
+  return isContainer(base) ? wrap(wrappable(base)) : base;
+}
+function wrappable(value) {
+  if (!Object.isFrozen(value)) return value;
+  return Array.isArray(value) ? [...value] : { ...value };
 }
 function isContainer(value) {
   return typeof value === "object" && value !== null;
@@ -13,7 +17,7 @@ function wrap(target) {
       if (deleted.has(key)) return void 0;
       const value = Reflect.get(t, key);
       if (isContainer(value) && Object.prototype.hasOwnProperty.call(t, key)) {
-        const view = wrap(value);
+        const view = wrap(wrappable(value));
         own.set(key, view);
         return view;
       }

package/dist/hookCategories.js

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.9
+// @ham2k/extension-sdk 0.12.11
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -474,6 +474,8 @@ export declare const HOOK_CATEGORIES: readonly [
 	"adifImport",
 	"bench",
 	"callNotes",
+	"chasing",
+	"cluster",
 	"command",
 	"dataFile",
 	"export",
@@ -732,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;
@@ -1119,6 +1154,82 @@ export interface ContestScorer<S extends Scoresheet = Scoresheet> {
 		scope: "day" | "operation";
 	}, ctx: HookContext): Record<string, ScoreTally>;
 }
+export interface ChasingProgram {
+	label: string;
+	icon?: string;
+	color?: string;
+	version: number;
+	editions: "lifetime" | "annual" | "event";
+	supersedes?: string[];
+	refLabel?: string;
+	imports?: ChasingImporter[];
+}
+export interface ChasingImporter {
+	key: string;
+	label: string;
+	extensions: string[];
+}
+export interface ImportedClaim extends QsoClaim {
+	at?: number;
+	match?: {
+		theirCall?: string;
+		startAtMillis?: number;
+		band?: string;
+		mode?: string;
+	};
+}
+export type ClaimLevel = "worked" | "confirmed" | "verified";
+export interface QsoClaim {
+	holder: string;
+	ref: string;
+	band: string | null;
+	mode: string | null;
+	edition?: string;
+	level: ClaimLevel;
+	by?: string;
+	label?: string;
+	guess?: boolean;
+}
+export interface ClaimSlot {
+	ref: string;
+	band: string | null;
+	mode: string | null;
+	level: ClaimLevel;
+	label?: string;
+}
+export type ClaimsTally = Omit<ScoreTally, "for">;
+export interface ChasingHook {
+	program: ChasingProgram;
+	claimsForQsos(args: {
+		qsos: Record<string, JSONValue>[];
+	}, ctx: HookContext): Promise<Record<string, QsoClaim[]>> | Record<string, QsoClaim[]>;
+	holdersFor(args: {
+		station: {
+			call: string;
+		} & Record<string, JSONValue>;
+	}, ctx: HookContext): Promise<string[]> | string[];
+	summarizeClaims(args: {
+		holder: string;
+		edition?: string;
+		slots: ClaimSlot[];
+	}, ctx: HookContext): Promise<Record<string, ClaimsTally>> | Record<string, ClaimsTally>;
+	importClaims?(args: {
+		importer: string;
+		file: {
+			name: string;
+			text: string;
+		};
+		station: {
+			call: string;
+		} & Record<string, JSONValue>;
+	}, ctx: HookContext): Promise<{
+		claims: ImportedClaim[];
+		skipped?: number;
+	}> | {
+		claims: ImportedClaim[];
+		skipped?: number;
+	};
+}
 export interface CommandAction {
 	setVfo?: {
 		freq?: number;
@@ -1142,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?: {
@@ -1203,6 +1318,7 @@ export interface CommandAction {
 	};
 	devLogCat?: Record<string, never>;
 	devMapInfo?: Record<string, never>;
+	devIdle?: Record<string, never>;
 	toggleExperiment?: {
 		token: string;
 	};
@@ -1264,11 +1380,13 @@ export interface CommandHook {
 export interface SyncPayload {
 	operations?: Record<string, JSONValue>[];
 	qsos?: Record<string, JSONValue>[];
+	claims?: Record<string, JSONValue>[];
 	meta?: Record<string, JSONValue>;
 }
 export interface SyncResponse {
 	operations?: Record<string, JSONValue>[];
 	qsos?: Record<string, JSONValue>[];
+	claims?: Record<string, JSONValue>[];
 	meta?: Record<string, JSONValue>;
 	account?: Record<string, JSONValue>;
 	success?: boolean;
@@ -1359,7 +1477,7 @@ export interface AccountHook {
 	synchronizable?: boolean;
 	testCredentials(credentials: Record<string, string>, ctx: HookContext): Promise<string>;
 }
-export type Hook = LookupHook | LookupServiceHook | SpotsHook | ExportHook | ScoringHook | RefHandlerHook | ActivityHook | AdifFieldsHook | AdifImportHook | CommandHook | SyncTransportHook | AccountHook | DataFileDefinition | FormHook | SettingsPanelHook | PanelHook | Record<string, unknown>;
+export type Hook = LookupHook | LookupServiceHook | SpotsHook | ExportHook | ScoringHook | ChasingHook | RefHandlerHook | ActivityHook | AdifFieldsHook | AdifImportHook | CommandHook | SyncTransportHook | AccountHook | DataFileDefinition | FormHook | SettingsPanelHook | PanelHook | Record<string, unknown>;
 export interface RegisterHookParams {
 	hook: Hook;
 	key?: string;
@@ -1400,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, {
@@ -1543,6 +1664,7 @@ export interface FormField {
 	templateContext?: "export" | "adif" | "text";
 	templateSample?: Record<string, JSONValue>;
 	uppercase?: boolean;
+	storedText?: string;
 	suggestions?: {
 		code: string;
 		name?: string;
@@ -1805,6 +1927,12 @@ export interface PanelRadioState {
 	 * cannot read it (extension API 7).
 	 */
 	tuner?: "inline" | "bypassed" | "tuning" | "failed" | null;
+	/**
+	 * Whether the radio starts a tune apart from putting its tuner in line — `setRadio`'s `startTune`.
+	 * False on a FlexRadio, whose in line already is the tune, and wherever `tuner` is null
+	 * (extension API 9).
+	 */
+	canStartTune?: boolean;
 	/**
 	 * The receive filter's edges in Hz from the tuned frequency, as the radio shows them — `100`…`2800`
 	 * in USB, `-2800`…`-100` in LSB, around zero in CW — or null where its driver cannot read it
@@ -1921,6 +2049,13 @@ export interface PanelRadioSet extends PanelRadioTarget {
 	 * On a FlexRadio, in line is a TUNE — a carrier on the air — since its tuner has no other way in.
 	 */
 	tunerInline?: boolean;
+	/**
+	 * Starts a tune — a carrier on the air until the tuner settles. Only for an operator's explicit
+	 * press. Goes alone: with any other setting in the same call it is `invalid`; `unsupported` where
+	 * `canStartTune` is false (extension API 9). Not a keying call: it reaches the radio the panel
+	 * shows, with keying on or off. `host.stopRadioTransmit()` ends a tune the app started.
+	 */
+	startTune?: true;
 	/**
 	 * The receive filter, as `passband` reports it; refused as `unsupported` where that is null. A
 	 * radio that sets only a width from a table takes the nearest, keeping its own shift — read the
@@ -2406,8 +2541,22 @@ export declare const host: {
 	setRadioPtt(args: PanelRadioTarget & {
 		on: boolean;
 	}): Promise<PanelRadioResult>;
-	/** Stops all CW, voice and PTT the app is keying, as Escape does. Needs `requiresRadioWrite` and extension API 7. */
+	/** 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

@@ -193,10 +193,33 @@ const host = {
   async setRadioPtt(args) {
     return await hostCallFn()("setRadioPtt", { ...args });
   },
-  /** Stops all CW, voice and PTT the app is keying, as Escape does. Needs `requiresRadioWrite` and extension API 7. */
+  /** 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. */
   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/logCopy.js

@@ -0,0 +1,87 @@
+const FROZEN_QSOS_API = 9;
+const UNSUPPORTED = "Host call method getQsoChanges not implemented";
+const KEEP = 3;
+const startOf = (qso) => typeof qso.startAtMillis === "number" ? qso.startAtMillis : -Infinity;
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+function createLogCopies(source, keep = KEEP) {
+  const copies = /* @__PURE__ */ new Map();
+  let unsupported = false;
+  function copyFor(operationUuid) {
+    let copy = copies.get(operationUuid);
+    if (copy) copies.delete(operationUuid);
+    else copy = { rows: /* @__PURE__ */ new Map(), list: [], queue: Promise.resolve() };
+    copies.set(operationUuid, copy);
+    for (const stale of copies.keys()) {
+      if (copies.size <= keep) break;
+      copies.delete(stale);
+    }
+    return copy;
+  }
+  async function sync(operationUuid, copy) {
+    let changes = await source.changes(operationUuid, copy.cursor);
+    if (changes === null) return false;
+    const held = apply(copy, changes);
+    if (!changes.reset && typeof changes.count === "number" && held !== changes.count) {
+      changes = await source.changes(operationUuid, void 0);
+      if (changes === null) return false;
+      apply(copy, changes);
+    }
+    if (changes.reset || changes.qsos.length > 0 || changes.removed.length > 0) {
+      copy.list = [...copy.rows.values()].sort((a, b) => startOf(a) - startOf(b));
+      copy.json = void 0;
+    }
+    copy.cursor = changes.cursor;
+    return true;
+  }
+  function apply(copy, changes) {
+    if (changes.reset) copy.rows.clear();
+    for (const qso of changes.qsos) copy.rows.set(String(qso.uuid), deepFreeze(qso));
+    for (const uuid of changes.removed) copy.rows.delete(uuid);
+    return copy.rows.size;
+  }
+  async function synced(operationUuid) {
+    if (unsupported) return UNSUPPORTED;
+    const copy = copyFor(operationUuid);
+    const run = copy.queue.then(() => sync(operationUuid, copy));
+    copy.queue = run.catch(() => void 0);
+    let known;
+    try {
+      known = await run;
+    } catch (error) {
+      if (!String(error?.message ?? error).includes(UNSUPPORTED)) throw error;
+      unsupported = true;
+      copies.clear();
+      return UNSUPPORTED;
+    }
+    if (known) return copy;
+    copies.delete(operationUuid);
+    return null;
+  }
+  return {
+    async read(operationUuid, { frozen }) {
+      const copy = await synced(operationUuid);
+      if (copy === null || copy === UNSUPPORTED) return copy === null ? null : source.whole(operationUuid);
+      if (frozen) return copy.list.slice();
+      copy.json ?? (copy.json = JSON.stringify(copy.list));
+      return JSON.parse(copy.json);
+    },
+    async pick(operationUuid, uuids, { frozen }) {
+      const copy = await synced(operationUuid);
+      if (copy === null) return null;
+      const rows = copy === UNSUPPORTED ? new Map((await source.whole(operationUuid))?.map((qso) => [String(qso.uuid), qso]) ?? []) : copy.rows;
+      const picked = uuids.flatMap((uuid) => rows.has(uuid) ? [rows.get(uuid)] : []);
+      return frozen || copy === UNSUPPORTED ? picked : JSON.parse(JSON.stringify(picked));
+    }
+  };
+}
+export {
+  FROZEN_QSOS_API,
+  createLogCopies,
+  deepFreeze
+};

package/dist/scoring.js

@@ -19,6 +19,11 @@ function chronological(qsos) {
 function isEvent(qso) {
   return qso.band === "event";
 }
+function hasIncompleteCall(qso) {
+  const their = qso.their;
+  const call = their && typeof their === "object" && !Array.isArray(their) ? their.call : void 0;
+  return typeof call === "string" && call.includes("?");
+}
 function startAtMillisOf(qso) {
   const at = qso.startAtMillis;
   return typeof at === "number" ? at : 0;
@@ -61,7 +66,7 @@ function contestScorer(scorer, options = {}) {
     const timeline = segments && segments.length > 1 ? segments : void 0;
     let segmentIndex = 0;
     for (const qso of qsos) {
-      if (isEvent(qso)) continue;
+      if (isEvent(qso) || hasIncompleteCall(qso)) continue;
       let operation = args.operation;
       let ref = args.ref;
       if (timeline) {

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

@@ -60,9 +60,12 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   raw QSON, oldest first, excluding soft-deleted records but *including*
   event markers (`band: 'event'`) — or null when the operation is unknown or
   the host has no log access, distinct from `[]` (the operation exists and
-  simply has no QSOs yet). Each call is a bridge round-trip carrying a whole
-  log — fine at command-execution or export scale, not on per-keystroke
-  paths.
+  simply has no QSOs yet). Every extension reads one copy of the log the
+  runtime keeps, which asks the host only what changed since the last read:
+  a call is never staler than itself, and the whole log crosses the bridge
+  only the first time. Each call gets a new array. From extension API 9 its
+  QSOs are that shared copy, frozen — a write throws, so copy what you mean
+  to change; under an older `api` each call gets QSOs of its own.
 * `getSpotsForCall?(call, maxAgeMinutes = 30)` — the spots the host has
   already fetched for `call`, no older than `maxAgeMinutes` (measured on the
   spot's own `spot.timeInMillis`, not on when it was fetched), newest first.
@@ -327,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
@@ -733,9 +778,11 @@ suggested the nearer of its point's and its outline's distance — so `pota`'s
 still reaches an operator standing on it. Called with no
 `searchTerm` for nearby suggestions, or with one for name/code search — an
 extension may honor either, both, or neither (returning `[]`). `scoped` is
-true when THIS extension alone was asked — the operator tapped its "Activity
-Types" row or typed its key as a scope — which a bare scope otherwise cannot be
-told from the nearby list, since neither carries a `searchTerm`. An extension
+true when THIS extension's own list was asked for — the operator tapped its
+"Activity Types" row or typed one of its words, with or without the colon
+(below) — which otherwise cannot be told from the nearby list, since neither
+carries a `searchTerm`. Without the colon the other extensions are asked too,
+for the word as text. An extension
 that keeps itself out of the nearby list (`cwt`, offered only around a session)
 answers a scoped call anyway: it is the one being asked. The core fans out to
 every `activity` hook via `invokeHookAll`; a scoped search asks only its own
@@ -768,19 +815,38 @@ The row is marked, and the reference is stored, logged and exported as typed —
 the same rule ADIF import follows for a malformed `*_REF` (below).
 
 The activity search box also treats a leading scope word as a scope — typing
-`pota:` (or tapping a row under "Activity Types") asks the extension serving
-that reference type alone, via a key-scoped `invokeHook` rather than the usual
-fan-out. The word is the **reference type's base name**, lowercased —
-`potaActivation` and `pota` both scope as `pota:` — never the extension key: a
-user-published `ki2d-pota` serving `potaActivation` is still scoped as
-`pota:`, since the operator is adding POTA parks whichever extension supplies
-them. Two enabled extensions serving one type share the word, and the scoped
-search asks both. For the hook call to reach the extension, its `activity`
-hook must be registered under its own **extension key**, and its control
-descriptors keyed `<extensionKey>/<name>` (`pota/activation`) — the core
-derives the hook key from the part before the slash. An extension that
-deviates simply never gets scoped: its rows still add references, but the
-scope would ask a hook that doesn't exist and come back empty.
+`pota:` (or tapping a row under "Activity Types") asks only the extensions
+serving that reference type, via a key-scoped `invokeHook` rather than the
+usual fan-out. An extension answers to two kinds of word:
+
+- **Each reference type its manifest declares**, as a plain `ref:<type>` in
+  `hooks`, by the type's base name lowercased — `ref:potaActivation` and
+  `ref:pota` are both `pota:`. A user-published `ki2d-pota` declaring
+  `ref:potaActivation` is scoped as `pota:` too, since the operator is adding
+  POTA parks whichever extension supplies them: two running extensions
+  declaring one type share the word, and the scoped search asks both. A
+  qualified claim (`ref:qp/ny`) makes no word.
+- **Its own extension key** — `ham2k-pota:` asks that extension alone, which
+  is how an operator picks one supplier over another.
+
+The same word without its colon gives precedence instead of scoping. `pota`
+on its own asks the extensions serving the type for their own list (as a
+scope, `scoped: true` with no `searchTerm`) and every other extension to
+search for the text "pota", with the first answers leading. `pota bear mtn`
+asks the extensions serving the type for "bear mtn" and every other one for
+the whole text — a `suggest` matching codes and names against one string
+finds nothing for the word it was named by.
+
+The scoped call reaches the extension under the key it registered its
+`activity` hook with, which has to be its manifest key. The search reads which
+extension supplied a control from the fan-out that returned it, never from
+the descriptor's `key`, so a catalog `ham2k-pota` keying its controls
+`pota/activation` is reached as `ham2k-pota`. (A logging control's serial
+counter is still namespaced by the `key`'s prefix: two extensions keying
+controls under one prefix share a counter.) A
+switched-off or not-yet-installed extension is offered from the same words:
+typing a type it declares, or its key, puts its enable or install row under
+the search.
 
 `editable` declares whether a reference of this type has anything to edit
 once it's on the operation. It defaults to **false**: a plain reference
@@ -1046,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?}
@@ -1165,6 +1231,9 @@ action field — the hook parses "EXP <key-or-alias>" and resolves the token
 against `ctx.experiments` only for its preview ("Enable"/"Disable"); the app
 resolves it again when it flips the state and reports the outcome, since the
 stored per-experiment state lives app-side;
+LANG `<code>` switches the app's language — hidden locales (CW, QRP, QRO)
+included, "LANG SYSTEM" back to the device's — with a plain `updateSetting`
+on the `locale` field, which refuses a code the app has no strings for;
 DEVTT/DEVTIMETRAVEL move the app clock via the `devTimeTravel` action field —
 "DEVTT +3h", "DEVTT -1d", "DEVTT 2x", bare "DEVTT" to return to real time — so
 anything that turns on the date or on elapsed time can be tested without
@@ -1451,6 +1520,92 @@ detection, DXCC entities worked (via `@ham2k/lib-country-files`'
 `useBuiltinCountryFile`, no network needed), and bands/modes worked. US
 States and Canadian Provinces rules are deferred (see [backlog.md](https://github.com/ham2k/halo/blob/main/docs/backlog.md)).
 
+## ✅ `chasing` — what a contact counts toward
+
+A chasing program — DXCC, POTA hunting, WAS — says which lines of its
+checklist each contact fills. The app keeps the best claim per line and ranks
+spots against the result; [claims.md](https://github.com/ham2k/halo/blob/main/docs/design/claims.md) is the design.
+
+One registration per program, keyed by the program's key — the extension's own
+key, or one prefixed `<extension key>_`, so one extension may register
+several:
+
+```ts
+registerHook("chasing", { key: "dxcc", hook: {
+  program: { label: "DXCC", icon: "earth", version: 1, editions: "lifetime" },
+  claimsForQsos({ qsos }, ctx) { /* { [uuid]: QsoClaim[] } */ },
+  holdersFor({ station }, ctx) { /* string[] */ },
+  summarizeClaims({ holder, edition, slots }, ctx) { /* { [key]: ClaimsTally } */ },
+  importClaims({ importer, file, station }, ctx) { /* { claims: ImportedClaim[], skipped? } */ }, // optional
+}})
+```
+
+- **`program`** is plain data, read across every extension in one call
+  without invoking anything. Raise `version` whenever the same contacts would
+  claim something different: the app keeps no claim from an older version.
+  `refLabel` is what one reference is called where a notice names it
+  ("New POTA Park"), the program's `label` when left out.
+  `supersedes` names the scoring notices the program's verdicts stand in for
+  (DXCC: `newDXCC`): wherever the program judges a call or a spot, the
+  scorer's notice is dropped in favor of the verdict.
+- **`claimsForQsos`** answers every contact in the batch, by `uuid` — a
+  caller asking about something that is not a stored contact (a spot, the
+  call being typed) gives it a `uuid` of its own, and a contact without one
+  is left out — with the
+  slots it fills: `{holder, ref, band, mode, level, edition?, by?, label?,
+  guess?}`. `band` and `mode` are explicit — `null` means "any", and a
+  program usually claims several granularities per contact (DXCC: Mixed, the
+  band, the mode). `mode` is the program's own grouping; the app never maps
+  modes for it. `level` is `worked`, `confirmed` (a QSL the program accepts,
+  from `qso.qsl`) or `verified` (sponsor credit, `qso.credits.<program>`).
+  **It must be a pure function of each contact** and the extension's own
+  data — never the log — because the app asks it about spots, and about
+  contacts on a device that holds only part of the log. An empty list is an
+  answer: that contact claims nothing. So is the list for an event marker
+  (`band: 'event'`), whose placeholder calls are not stations. A contact's
+  `our` carries the place it was made from — `grid`, `lat`/`lon` — its own,
+  or its operation's when it states none, for a program that keeps a
+  checklist per place. A spot candidate's `their` carries the lookup's
+  `guess.state` when an offline lookup knows one.
+- **`holdersFor`** lists the holders a station claims as — the opaque
+  strings the program puts on its claims — so the app knows whose checklist
+  to show: the first, in the current edition. `station` carries its call
+  and, when it has one, its place, as a contact's `our` does. An `annual`
+  program names its editions by UTC year (`'2026'`), which is how the app
+  tells the current one; an `event` program's checklist has no current
+  edition to show.
+- **`summarizeClaims`** reads one holder's filled slots (`{ref, band, mode,
+  level, label?}` each) into tallies, a `ScoreTally` without its `for`.
+- **`importClaims`**, for a program whose `program.imports` lists importers
+  (`{key, label, extensions}`), reads one file — `{name, text}` — that the
+  operator picked or dropped, for the station they chase as (`station`, its
+  call and place as `holdersFor` gets them). It answers the
+  claims the file makes, each a `QsoClaim` plus `at` (epoch millis, when the
+  slot was earned) if the file says, and `skipped`, the records it could not
+  read. Each claim is kept in the log as a claim record — an event row, so it
+  syncs with the log ([claims.md](https://github.com/ham2k/halo/blob/main/docs/design/claims.md) §9) — and
+  `claimsForQsos` is never asked about one: the app reads the claim it holds.
+  The file is the whole of its importer's records: importing the same kind of
+  file again replaces every claim the last one gave, and a file answered with
+  no claims replaces nothing.
+
+The host isolates programs from each other
+(`app/lib/services/extensions/extension_chasing.dart`): a program that throws
+or times out answers nothing for that call, and a contact with any
+malformed claim is left out of the answer, keeping the claims it already
+holds, since dropping one claim would read as the contact no longer making
+it. Both are reported once per program and method. The category is
+extension API 9: a bundle that registers a program declares `"api": 9`, which
+the packer enforces, so an older app — which would install it and never ask
+it anything — is never offered it.
+
+Implemented by: `dxcc` (core) — Mixed, per-band and per-mode slots for the
+station call worked from each entity; LoTW and paper QSLs confirm, LoTW credit
+verifies. `ham2k-pota` — one slot per park hunted, worked only; its
+hunted-parks export verifies. `ham2k-was` — Mixed, per-band and per-mode
+slots (plus FT8 and RTTY) for the station call worked from one 4-character
+grid; LoTW and paper QSLs confirm, `WAS` credit verifies.
+
 ## ✅ `bench` — kernel diagnostics
 
 Registered by the kernel itself (`bench/kernel`): `echo` (bridge round-trip
@@ -1471,6 +1626,11 @@ permission (pending challenge code for an email, immediately-active for an
 already-permitted account, or a blank permission for QR-code linking) and
 returns server rejections as `{ error, error_status }` data.
 
+`sync`'s payload and reply carry `claims` beside `operations` and `qsos`
+(docs/design/claims.md §7) once the server's reply has said it takes them
+with `meta.flags.claims`. A transport passes the array through like the
+other two, both ways.
+
 `linkClient` must NOT mail anything. The core shows the challenge code on
 screen and offers the email as a separate choice, so a transport that mails
 here sends a confirmation nobody asked for — and one more on every renewal,
@@ -1941,6 +2101,9 @@ rate. Extension API 7 adds to the answer:
   modes `setRadio` accepts for this radio, in the radio's order.
 - `tuner`: `inline`, `bypassed`, `tuning` or `failed`; null for a radio
   without one, or whose driver cannot read it.
+- `canStartTune` (extension API 9): the radio starts a tune apart from
+  putting its tuner in line — `setRadio`'s `startTune`. False on a FlexRadio,
+  whose in line already is the tune, and wherever `tuner` is null.
 - `passband`: `{lowHz, highHz}`, the receive filter's edges in Hz from the
   tuned frequency as the radio shows them — `100`…`2800` in USB,
   `-2800`…`-100` in LSB, around zero in CW — or null where its driver cannot
@@ -1975,6 +2138,14 @@ extension API 7: a bundle using them declares `"api": 7`.
 - `tunerInline`: puts the antenna tuner in line or bypasses it. On a
   FlexRadio, whose tuner has no other way in, in line is a TUNE — a carrier
   on the air; other radios switch it without transmitting.
+- `startTune: true` (extension API 9): starts a tune — a carrier on the air
+  until the tuner settles, read back through `tuner` as `tuning`. Only for an
+  operator's explicit press: never send it on a hook's own initiative. It
+  goes alone — in the same call as any other setting it is `invalid` — and is
+  `unsupported` where `canStartTune` is false. It is the radio's own tune,
+  not one of the keying calls below: it reaches whichever radio the panel
+  shows, with keying on or off. A start while one is running is ignored, and
+  `stopRadioTransmit` (or Escape) ends a tune the app started.
 - `passband`: `{lowHz, highHz}`, as `passband` reports it. A radio that sets
   only a width from a table takes the nearest, keeping its own shift — read
   the result back from `passband`. It applies to the mode the radio is in: a
@@ -2009,7 +2180,7 @@ rather than keying the logging radio behind the operator's back:
   `on: false` releases whatever key the app holds and is never refused; a
   radio that does not take the key answers `on: true` with `disconnected`.
 - `host.stopRadioTransmit({id, selection?})` stops every CW message, voice
-  memory and PTT the app is keying, as Escape does, whatever radio the
+  memory, PTT and tune the app is keying, as Escape does, whatever radio the
   identity names: a stop is never the call that is refused.
 
 A radio that cannot do what is asked (no CW key, no voice memories, no PTT)
@@ -2143,7 +2314,8 @@ 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. Spots are absent for the same reason:
+render, which comes for every change to the log: a contact logged, edited
+or deleted, or one a sync brought in. 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.
 
@@ -2239,7 +2411,6 @@ Consequences worth knowing:
 
 | Category | Role | Notes |
 |---|---|---|
-| `chasing` | what each contact counts toward a program's checklist (claims) | [claims.md](https://github.com/ham2k/halo/blob/main/docs/design/claims.md) |
 | `confirmation` | QSL/confirmation sources (spot-history cross-checking) | |
 | `opSetting` | per-operation settings contributions | |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "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 })
+  },
+})