@ham2k/extension-sdk 0.12.9 → 0.12.10

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,7 @@ const HOOK_CATEGORIES = [
   "adifImport",
   "bench",
   "callNotes",
+  "chasing",
   "command",
   "dataFile",
   "export",

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.9
+// @ham2k/extension-sdk 0.12.10
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -474,6 +474,7 @@ export declare const HOOK_CATEGORIES: readonly [
 	"adifImport",
 	"bench",
 	"callNotes",
+	"chasing",
 	"command",
 	"dataFile",
 	"export",
@@ -1119,6 +1120,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;
@@ -1203,6 +1280,7 @@ export interface CommandAction {
 	};
 	devLogCat?: Record<string, never>;
 	devMapInfo?: Record<string, never>;
+	devIdle?: Record<string, never>;
 	toggleExperiment?: {
 		token: string;
 	};
@@ -1264,11 +1342,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 +1439,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;
@@ -1805,6 +1885,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 +2007,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,7 +2499,7 @@ 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>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;

package/dist/index.js

@@ -193,7 +193,7 @@ 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 });
   },

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/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.
@@ -733,9 +736,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 +773,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
@@ -1165,6 +1189,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 +1478,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 +1584,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 +2059,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 +2096,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 +2138,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 +2272,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 +2369,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.10",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",