@ham2k/extension-sdk 0.12.13 → 0.12.15

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.13
+// @ham2k/extension-sdk 0.12.15
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -21,6 +21,20 @@ export interface PanelScene {
 	radio?: {
 		node?: string;
 	};
+	/**
+	 * A scene longer than its pane along `axis` (default `y`), scrolled by the app itself — wheel,
+	 * trackpad and drag, a drag begun on a button included — with no call to the extension. Scaled
+	 * to fill the pane across, it runs on past it along the axis. The position, in scene units from
+	 * the start, is written to the scene value `value` as it scrolls; a render that changes that
+	 * value moves the view there, and one that leaves it alone leaves the operator's scroll alone.
+	 * `event`, when given, is sent as a `commit` with the position as `value` once scrolling comes
+	 * to rest. Layers and controls marked `fixed` stay put over the pane. No `layout`. Extension API 12.
+	 */
+	scroll?: {
+		axis?: "x" | "y";
+		value: string;
+		event?: string;
+	};
 }
 /** Host-fed values of a scene with `radio`: its meters, and `radio.transmitting` as 1 or 0. Reserved: a scene may not declare them. */
 export type PanelSceneRadioValue = "radio.signalDbm" | "radio.powerOut" | "radio.swr" | "radio.alc" | "radio.supplyVolts" | "radio.transmitting"
@@ -52,13 +66,28 @@ export interface PanelSceneLayer {
 	y: number;
 	width: number;
 	height: number;
-	/** Supply exactly one of svg or text. SVG must be self-contained. */
+	/** Supply exactly one of svg, text or icon. SVG must be self-contained. */
 	svg?: string;
+	/**
+	 * A named icon — MDI, or FontAwesome with `fa-` — drawn by the app to fit the layer, in `color`
+	 * (`#RRGGBB`) or the theme's. Extension API 12.
+	 */
+	icon?: {
+		name: string;
+		color?: string;
+	};
 	/**
 	 * Take the clicks that land on this layer. Off by default: layers are click-through, so
 	 * artwork painted over a control does not stop it working. On, it covers the controls under it.
 	 */
 	blocksPointer?: boolean;
+	/** In a scene with `scroll`: drawn over the pane where it is, in pane coordinates, not scrolled. Extension API 12. */
+	fixed?: boolean;
+	/**
+	 * While a `zoom` strip is dragged, scaled along the scroll about the pane's middle, rather than
+	 * moved there at its own size: for a background, or a line that runs the whole way. Extension API 12.
+	 */
+	stretch?: boolean;
 	/** Exactly one of literal/value. A value naming a string shows it as-is. Use text layers, not SVG <text>, for font support.
 	 * Size is unscaled; the host applies OS text scaling once. */
 	text?: {
@@ -121,10 +150,16 @@ export interface PanelSceneLayer {
  *   reach the extension. Needs `requiresRadioRead`; a host without the feature, or a radio
  *   without a scope, shows why instead. A click sends `commit` with the frequency as `value`.
  *   Takes no `value`; see `PanelSceneSpectrum` for the rest. Extension API 6: declare `"api": 6`.
+ * - `zoom`: a strip of a scene with `scroll`, drawn by nothing, where a drag along the scroll zooms
+ *   about the pane's middle — away from it in, toward it out, by the ratio of the distances. While
+ *   the drag lasts the app moves each layer and control to where the zoom puts its middle, at its
+ *   own size (a `stretch` layer scales instead), and on release sends `commit` with the factor as
+ *   `value`; `min` and `max` are the factors allowed. A tap on it still reaches what lies there,
+ *   and a drag elsewhere still scrolls. Needs `event`. Extension API 12.
  *
  * `label` is every control's accessible name. There are no tooltips.
  */
-export type PanelSceneControlKind = "button" | "slider" | "knob" | "nativeButton" | "nativeSlider" | "nativeTextField" | "nativeDropdown" | "nativeSwitch" | "nativeCheckbox" | "nativeRadio" | "nativeSegmented" | "nativeChip" | "nativeText" | "spectrum";
+export type PanelSceneControlKind = "button" | "slider" | "knob" | "nativeButton" | "nativeSlider" | "nativeTextField" | "nativeDropdown" | "nativeSwitch" | "nativeCheckbox" | "nativeRadio" | "nativeSegmented" | "nativeChip" | "nativeText" | "spectrum" | "zoom";
 /** A literal, or the name of a scene value — which a slider with no `event` retunes with no bridge call. */
 export type PanelSceneSpectrumNumber = number | string;
 /**
@@ -361,6 +396,18 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 	multi?: boolean;
 	/** Shown but inert: no clicks, drags, keys or screen-reader adjustments act on it. */
 	disabled?: boolean;
+	/** In a scene with `scroll`: placed over the pane, in pane coordinates, not scrolled. Needs a rect. Extension API 12. */
+	fixed?: boolean;
+	/**
+	 * A drawn control only (`button`, `slider`, `knob`): while the pointer is over it, the scene value
+	 * `value` reads `to`, set by the host with no call to the extension; leaving puts back the scene's
+	 * own value. Artwork bound to it lights up under the pointer — a spot's line with its call.
+	 * Survives renders while the pointer stays. Extension API 12.
+	 */
+	hoverSet?: {
+		value: string;
+		to: number;
+	};
 	/**
 	 * 0 to 1, fixed or bound like a layer's. At 0 the control is gone: it takes no clicks,
 	 * keyboard focus or screen-reader node. Anything between is only drawn fainter.
@@ -387,6 +434,17 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 	valueLabels?: string[];
 	/** Knobs use relative horizontal/upward dragging. Value per scene unit; default 1. */
 	sensitivity?: number;
+	/**
+	 * A knob only: a drag moves the value the other way — content held under the finger, scrolled
+	 * by dragging, rather than a dial turned. Scrolling is unchanged. Extension API 12.
+	 */
+	invertDrag?: boolean;
+	/**
+	 * A slider or knob only: it also takes the scrolls that land on drawn buttons over it — labels
+	 * drawn over a knob that scrolls the artwork. A native control, a `blocksPointer` layer or another
+	 * slider or knob in between keeps the scroll. Extension API 12.
+	 */
+	scrollThrough?: boolean;
 	/**
 	 * A knob's second axis: with `valueY`, horizontal scrolling, dragging and the left/right keys set
 	 * `value`, and vertical ones (and up/down) set `valueY` — sent as its own event, `eventY`, which a
@@ -687,8 +745,22 @@ export interface GetSpotsOptions {
 	annotate?: boolean;
 	operationUuid?: string;
 }
+export interface SuggestedQso {
+	their: {
+		call: string;
+	};
+	freq?: number;
+	band?: string;
+	mode?: string;
+	refs?: SpotRef[];
+}
 export interface BoardSpot extends Spot {
 	hookKey?: string;
+	display?: {
+		icon: string;
+		iconColor?: string;
+		emoji?: string;
+	};
 	annotations?: SpotAnnotations;
 }
 export interface SpotAnnotations {
@@ -1537,6 +1609,7 @@ export interface ExtensionManifest {
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
 	requiresRadioWrite?: boolean;
+	requiresRadioRaw?: boolean;
 	requiresClusterRead?: boolean;
 	requiresClusterSpot?: boolean;
 	requiresClusterCommand?: boolean;
@@ -1993,7 +2066,7 @@ export interface PanelRadioState {
 		endedAtMillis: number;
 	} | null;
 	/**
-	 * The radio's scope, on hosts with the panadapter enabled: absent there otherwise, and null
+	 * The radio's scope: absent on an app without a panadapter, and null
 	 * for a radio without one. The sweeps are never sent — a `spectrum` scene control draws them.
 	 */
 	spectrum?: PanelRadioSpectrum | null;
@@ -2095,15 +2168,44 @@ export interface PanelRadioSet extends PanelRadioTarget {
 }
 /** @deprecated `setRadio`'s argument through extension API 6. */
 export type PanelRadioTune = PanelRadioSet;
+/**
+ * Commands in the radio's own protocol — exactly one of `text` or `bytes`, up to 4096 bytes
+ * (extension API 11). Where the app's driver keeps one question on the wire (CI-V, Yaesu binary,
+ * HRD, Commander, flrig) each command waits its turn in that queue, and on a FlexRadio is numbered
+ * like the driver's own; the reply is then the answers to these commands alone. Elsewhere the bytes
+ * are written as given. See hooks.md for what each protocol takes.
+ */
+export interface PanelRadioRaw extends PanelRadioTarget {
+	/** Sent as UTF-8: Kenwood, Yaesu and Elecraft ASCII, rigctld, N3FJP, SmartSDR, HRD, Commander, flrig. */
+	text?: string;
+	/** Each 0…255: Icom CI-V, Yaesu's binary protocol. */
+	bytes?: number[];
+	/**
+	 * How long to wait for the reply, up to 2000 ms; omitted or 0, the call answers once the commands
+	 * are handed to the driver. Where they are written as given, the reply is everything the radio
+	 * sent in that time — the answers to the app's own polls included.
+	 */
+	replyMs?: number;
+	/** Ends the reply early, just after the first occurrence of this text or these bytes. Needs `replyMs`. */
+	until?: string | number[];
+}
+export interface PanelRadioRawResult extends PanelRadioResult {
+	/** What came back within `replyMs`, possibly nothing, at most 64 KiB; absent without `replyMs`. `text` is it as UTF-8. */
+	reply?: {
+		text: string;
+		bytes: number[];
+	};
+}
 export interface PanelRadioResult {
 	/** Accepted by the host; confirmation still comes from reported state. */
 	accepted: boolean;
 	/**
 	 * `stopped`: a scope change while no display has the scope running — nothing was sent.
+	 * `busy`: eight raw commands to this radio are already waiting (extension API 11).
 	 * `unsupported`: this radio, or the app's keying, cannot do it — keying calls on a radio that
 	 * is not the logging radio, or with the app's keying off.
 	 */
-	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped" | "unsupported";
+	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped" | "unsupported" | "busy";
 	state: PanelRadioState | null;
 }
 /** @deprecated `PanelRadioResult`'s name through extension API 6. */
@@ -2565,6 +2667,11 @@ 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>;
+	/**
+	 * Writes any command in the radio's own protocol — one that transmits included — and collects the
+	 * reply for `replyMs`. Needs `requiresRadioRaw` and extension API 11.
+	 */
+	sendRadioRaw(args: PanelRadioRaw): Promise<PanelRadioRawResult>;
 	/** 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. */
@@ -2579,6 +2686,20 @@ export declare const host: {
 	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>;
+	/**
+	 * Puts a station into the logging fields of the operation in front, as tapping its spot in the
+	 * Spots Panel does — call, frequency, band, mode and references; nothing else of `qso` is used.
+	 * With `operationUuid` (a panel's `operation.uuid`), only that operation's: `accepted` is false
+	 * when it is not the one in front, or none is open. It tunes the radio as a tap does, so it needs
+	 * `requiresRadioWrite`, and it is refused outside the extension's own panel `onEvent`. Extension
+	 * API 12.
+	 */
+	suggestQso(args: {
+		qso: SuggestedQso;
+		operationUuid?: string;
+	}): Promise<{
+		accepted: boolean;
+	}>;
 	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,13 @@ const host = {
   async stopRadioTransmit(args) {
     return await hostCallFn()("stopRadioTransmit", { ...args });
   },
+  /**
+   * Writes any command in the radio's own protocol — one that transmits included — and collects the
+   * reply for `replyMs`. Needs `requiresRadioRaw` and extension API 11.
+   */
+  async sendRadioRaw(args) {
+    return await hostCallFn()("sendRadioRaw", { ...args });
+  },
   /** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
   async clusterStatus() {
     return await hostCallFn()("clusterStatus", {});
@@ -220,6 +227,17 @@ const host = {
   async clusterSend(command) {
     return await hostCallFn()("clusterSend", { command });
   },
+  /**
+   * Puts a station into the logging fields of the operation in front, as tapping its spot in the
+   * Spots Panel does — call, frequency, band, mode and references; nothing else of `qso` is used.
+   * With `operationUuid` (a panel's `operation.uuid`), only that operation's: `accepted` is false
+   * when it is not the one in front, or none is open. It tunes the radio as a tap does, so it needs
+   * `requiresRadioWrite`, and it is refused outside the extension's own panel `onEvent`. Extension
+   * API 12.
+   */
+  async suggestQso(args) {
+    return await hostCallFn()("suggestQso", { ...args });
+  },
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },

package/docs/distribution.md

@@ -540,6 +540,13 @@ catalog's own bundle links (`…/api/v1/extensions/<key>/versions/<version>/bund
 take this verified path when they arrive as a deep link; every other host
 takes the plain one above.
 
+An extension's screenshots — published beside its bundles, never inside them
+(the tools README says how) — show as a strip of thumbnails on its row in the
+operation sheet's activity search, on the consent screen of a catalog install,
+and in an installed extension's details; a tap opens them full size. The app
+loads them only from the catalog's own host: a listing naming any other is
+shown without them.
+
 ### Release tracks
 
 A catalog channel — `stable`, `unstable` or `bleeding` — says how finished a
@@ -573,7 +580,7 @@ counts as the catalog's own here. The row and the details show the track, and
 the details' **Follow stable releases only** puts it back on stable; an
 uninstall or a file install clears it with the rest of the record.
 
-At most once every six hours — on launch and on resume — the app asks the
+At most once a day — on launch and on resume — the app asks the
 catalog whether anything installed has a newer release, and says so in the
 status bar and on the row; the notice comes down with the last update taken.
 It never installs unasked: the notice's **Update all** is the panel's own,

package/docs/hooks.md

@@ -73,6 +73,17 @@ 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.
+* `host.suggestQso({qso, operationUuid?})` (extension API 12) — puts a
+  station into the logging fields of the operation in front, as tapping its
+  spot in the Spots Panel does: `qso.their.call`, and `freq`, `band`, `mode`
+  and `refs` where given; nothing else of `qso` reaches the fields. With
+  `operationUuid` — a panel's own `operation.uuid` — only that operation's
+  fields, so a panel never fills a log the operator is not looking at.
+  Answers `{accepted}`, false when no such operation is open. It tunes the
+  radio as a tap does, so it needs `requiresRadioWrite`, and it is refused
+  except from inside the extension's own panel `onEvent`: it answers the
+  operator clicking something, never a timer or a render, which would
+  overwrite what they are typing.
 * `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
@@ -92,7 +103,12 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   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.
+  From extension API 12 each also carries `display` — `icon` (an MDI or
+  `fa-` name), `iconColor` (`#RRGGBB`, where the activity declares one) and
+  `emoji` (the call's note emoji, where it has one): what the Spots Panel's row
+  shows beside the call, the activity's icon and tint for the spot's first
+  reference, else the source's own icon. `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
@@ -287,6 +303,14 @@ interface LookupServiceHook {
   unset or name itself; tagging one `'prefix'` gets its coordinate
   discarded.
 
+- **A guess field of the wrong type is dropped.** The bridge enforces none of
+  `CallInfo`'s declared types, so the app normalizes the answer
+  (`normalizeLookupResult`, halo_core) before anything reads it: a field its
+  readers cannot use — a numeric `continent`, a boolean `emoji` — is dropped
+  and reported once by name, and the rest of the guess is still used. A
+  numeric string where a number is read (`cqZone: '05'`) is taken as that
+  number.
+
 Implemented by: `lookups` (key `core`). The merge algorithm itself
 (`mergeLookupIntoGuess`/`runLookupPipeline` in
 `extensions/core/lookups/src/mergeLookup.ts`) is a pure, host-independent
@@ -1876,9 +1900,10 @@ drawing part of it.
 | `width`, `height` | The artwork's viewBox, in scene units. Size it to `environment.width`/`height` and a scene unit is a logical pixel. |
 | `values` | `{name: number}`: what bindings, numeric text and numeric controls read. At most 256. |
 | `strings` | `{name: string}`: what text fields and choices hold. At most 256, each up to 4096 characters. A name is in `values` or `strings`, never both. |
-| `layers` | Painted in order, each over the ones before: `svg` artwork or `text`. At most 128, and 1 MiB of artwork and text in all. |
-| `controls` | At most 64. Drawn or native; see below. |
+| `layers` | Painted in order, each over the ones before: `svg` artwork, `text`, or an `icon`. At most 512 (128 before extension API 12), and 1 MiB of artwork and text in all. |
+| `controls` | At most 256 (64 before extension API 12). Drawn or native; see below. |
 | `layout` | Optional. Where rect-less native controls and the artwork go; omitted, the artwork fills the pane. |
+| `scroll` | Optional, `{axis?, value, event?}` (extension API 12): a scene longer than its pane along `axis` (`y` by default), scrolled natively by the app — wheel, trackpad and drag, a drag begun on a button included — with no call to the extension. It fills the pane across and runs on past it. The position, in scene units, is written to the scene value `value`; a render that changes that value moves the view there, one that leaves it alone leaves the operator's scroll alone. `event` is sent as a `commit`, the position as `value`, once a scroll comes to rest. Layers and controls with `fixed: true` stay put over the pane, in pane coordinates. A drag along the scroll on a slider or knob that scrolls with the content is the scroll's: make one that must be dragged `fixed`. Not with `layout`. |
 | `radio` | Optional, `{node?}`: the host feeds that radio's live readings into the reserved `radio.*` values. `node` is an id from `listRadios`; omitted, the logging radio. See *Radio values*. |
 
 **Controls.** Every control has an `id` and a `label`, which is its accessible
@@ -1889,8 +1914,8 @@ the extension. `value` names what it shows and sets.
 | Kind | Binds to | Sends | Also takes |
 |---|---|---|---|
 | `button` | — | `activate` | `menu` |
-| `slider` | number | `commit` | `min`, `max`, `step`, `discrete`, `hover`, `valueLabels`, `continuous` |
-| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `valueLabels`, `continuous`, `menu`, a second axis (`valueY`, `eventY`, `minY`, `maxY`, `stepY`, `sensitivityY`) |
+| `slider` | number | `commit` | `min`, `max`, `step`, `discrete`, `hover`, `valueLabels`, `continuous`, `scrollThrough` |
+| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `invertDrag`, `scrollThrough`, `valueLabels`, `continuous`, `menu`, a second axis (`valueY`, `eventY`, `minY`, `maxY`, `stepY`, `sensitivityY`) |
 | `nativeButton` | — | `activate` | `variant` (`filled`, `tonal`, `outlined`, `text`), `icon`, `menu`; needs `event` or `menu` |
 | `nativeSlider` | number | `commit` | `min`, `max`, `step`, `valueLabels`, `continuous` |
 | `nativeTextField` | string | `commit` on Enter, or on leaving it after typing | `placeholder`, `continuous` |
@@ -1901,6 +1926,7 @@ the extension. `value` names what it shows and sets.
 | `nativeChip` | number, 1 or 0; or none | `commit`; `activate` without a value | `icon`; needs `event` without a value |
 | `nativeText` | number, string, or none | nothing | `style` (a typography role), `align` (`start`, `center`, `end`) |
 | `spectrum` | — | `commit` with the frequency clicked; `activate` from an annotation | see *Spectrum* below |
+| `zoom` | — | `commit` with the factor, on release | `min`, `max` (the factors allowed); only in a scene with `scroll`; extension API 12 |
 
 The three drawn kinds are invisible hit areas over artwork the extension paints;
 the native kinds are Material widgets the app paints and themes. Every control
@@ -1912,12 +1938,37 @@ may also take:
 - `after`: with a rect, the layer it paints directly after.
 - `opacity`: 0 to 1, fixed or bound like a layer's. At 0 the control is gone.
 - `disabled`: shown, but no click, drag, key or screen-reader adjustment acts on it.
+- `hoverSet` (drawn kinds only; extension API 12): `{value, to}`. While the
+  pointer is over the control, the scene value `value` reads `to` — set by the
+  host, with no call to the extension — and leaving puts back the scene's own
+  value. A layer bound to it lights up under the pointer, and several controls
+  naming one value with different `to`s light up one thing each. It survives
+  renders while the pointer stays.
 
 `options` is `[{label, value}]`, up to 64, with each `value` unique. A choice's
 string is `""` or one of them; a `multi` choice holds its values joined with
 commas in option order, so no option may contain one. `menu` is
 `[{label, event}]`, up to 32: picking an item sends its `event` as the action.
 
+A `zoom` strip is drawn by nothing: it claims a drag that begins on it along a scrolling
+scene's axis. Away from the pane's middle zooms in and toward it zooms out, by the ratio of
+the two distances from the middle, clamped to `min`…`max`. While the drag lasts the app moves
+each layer and control to where the zoom puts its middle, keeping its size, so text and dots
+stay as drawn and only spread apart or close in; a layer with `stretch: true` — a background,
+a line the length of the scene — scales along the scroll instead. That preview holds until
+the render that answers the `commit` arrives, so a scene meant to zoom draws its pieces as
+layers of their own rather than as one picture. A tap on the strip still reaches the button there, and a drag that starts off it
+still scrolls.
+
+A scroll steps a slider or knob by its `step`, down and left lowering it; a one-axis
+control takes a sideways scroll by its own direction. A slider or knob with
+`scrollThrough` (API 12) also takes the scrolls landing on drawn buttons over it, so labels
+drawn over a knob that scrolls the artwork do not stop the scroll; anything else in the
+way — a native control, a `blocksPointer` layer, another slider or knob — keeps the scroll
+from it.
+A knob with `invertDrag` (API 12) moves the other way to a drag, as content held under
+the finger does — what a knob that scrolls the artwork wants — while its scroll is unchanged.
+
 A knob with `valueY` sets two numbers from one patch of artwork — a passband's
 shift across and its width up, say. Horizontal dragging, horizontal scrolling
 and the left/right keys set `value`; vertical ones and the up/down keys set
@@ -2029,9 +2080,8 @@ control faded in over the artwork, and a click-through layer painted over it.
 #### Spectrum
 
 A `spectrum` control is a radio's panadapter and waterfall, drawn by the host
-from sweeps that never reach the extension, on a host with the panadapter
-enabled. It is **extension API 6**, as is `host.setRadioSpectrum`: a bundle
-using either declares `"api": 6`, and an app speaking less refuses it at install
+from sweeps that never reach the extension. It is **extension API 6**, as is
+`host.setRadioSpectrum`: a bundle using either declares `"api": 6`, and an app speaking less refuses it at install
 rather than failing to render the scene. It needs `requiresRadioRead`; without it, or on a host or radio
 without a spectrum, the control says why instead. It is placed like a native
 control and takes the fields of `PanelSceneSpectrum` in the SDK:
@@ -2115,7 +2165,9 @@ same shape as `requiresLocation`, and shown to the operator at install:
 `host.setRadioConnection()` and `host.setRadioSpectrum()` — and transmitting
 with them: `host.sendRadioCw()`, `host.playRadioVoice()`, `host.setRadioPtt()`
 and `host.stopRadioTransmit()` — and implies read, since a command answers with the
-radio's state. An undeclared call rejects rather than answering null.
+radio's state. `"requiresRadioRaw": true` (extension API 11) also allows
+`host.sendRadioRaw()`, any command in the radio's own protocol, and implies
+write. An undeclared call rejects rather than answering null.
 A capability belongs to the bundle that declared it, and to the sub-extensions
 that bundle defines under its own key. A separately installed bundle never
 inherits one through its name: `rigpanel-themes` gets nothing from `rigpanel`.
@@ -2231,7 +2283,62 @@ not paced, and not refused for a transmission in progress.
 connection using the same selection and identity checks. Acceptance starts the
 operation; follow reported connection state for completion. It does not switch
 the hardware's mains power or initiate transmission.
-On a host with the panadapter enabled, `readRadio()` carries `spectrum`: null
+
+`host.sendRadioRaw({id, selection?, text | bytes, replyMs?, until?})`
+(extension API 11, `requiresRadioRaw`) sends commands in the radio's own
+protocol — exactly one of `text`, sent as UTF-8, or `bytes`, each 0…255, up
+to 4096 bytes. **Nothing about them is checked.** They may transmit, change
+any setting or put the radio somewhere the app's own controls never would;
+that is what the operator agreed to at install, where the grant is shown in
+those words. It reaches any local radio through the same `id`/`selection`
+check as `setRadio`, with keying on or off, and is neither paced nor refused
+for a transmission in progress. One radio's calls go one at a time, in order,
+so that one call's reply window never holds the next one's answer, and past
+eight waiting the next is refused as `busy`; the app's own polls may come
+between two calls.
+
+- `replyMs`, up to 2000: how long to wait for the reply. Omitted or 0, the
+  call answers as soon as the commands are handed to the driver, with no
+  `reply`.
+- `until`, text or bytes, needs `replyMs`: the reply ends just after its first
+  occurrence.
+- The answer carries `reply: {text, bytes}`, possibly empty, at most 64 KiB,
+  with `text` its UTF-8 reading.
+
+What the commands are, and what the reply holds, is the protocol's. Where the
+app's driver keeps one question on the wire and reads the next reply as its
+answer, a raw command waits its turn in that queue — written beside it, its
+answer would be read as the answer to the driver's question — or, on a
+FlexRadio, is numbered as the driver's own are. The reply is then the answers
+to the raw commands alone, as the radio sent them, once each has come or the
+window closes:
+
+| Radio | Commands | Reply |
+|---|---|---|
+| Icom CI-V | `bytes`: whole frames, `FE FE` … `FD`, one at a time; the app addresses each to the radio from itself, whatever its address bytes say | each frame's answer frame (`FB`/`FA` or its data) |
+| Yaesu binary (FT-817/857/897) | `bytes`: five-byte commands | what the radio sends for each before it falls quiet; not read by the app |
+| FlexRadio | `text`: one command per line, without `C<seq>\|` — the app numbers each like its own | each one's `R` line |
+| Ham Radio Deluxe | `text`: one command per line, without the radio's context — the app adds it | each one's reply text, one per line |
+| DXLab Commander | `text`: one whole message (`<command:10>CmdGetFreq<parameters:0>`) | the field it is answered with; without `replyMs` it goes out as a set, waiting for nothing |
+| flrig | `text`: one XML-RPC call (`<?xml …?><methodCall>…`) — the app posts it | the response's body |
+
+Every other radio's commands are written as given — several back to back
+(`FA00014074000;MD2;`) in one write, none of the app's own between them —
+since each of their answers names what it answers: Kenwood, Elecraft and
+Yaesu ASCII, rigctld, N3FJP, Guohetec. The reply there is everything the
+connection received in the window, the answers to the app's own polls
+included, so `until` is worth setting.
+
+The app's driver still reads what the radio sends, so a raw command's effect
+shows in `readRadio` as a change made at the front panel would — and a command
+that confuses the driver confuses the app. A radio that is not connected
+answers `disconnected`; one whose driver takes no raw commands (a placeholder
+radio), `unsupported`; a malformed call, or commands that are not the
+protocol's (CI-V bytes that are not whole frames), `invalid`. A refusal heard
+within a second of a raw command on a protocol whose refusals name no command
+(`?;`, rigctld's `RPRT`) is taken as the raw command's, not counted against the
+app's own reads.
+`readRadio()` carries `spectrum` (absent on an app without a panadapter): null
 for a radio without a scope, otherwise its settings as the radio reports them
 (`mode`, `spanHz`, `lowHz`/`highHz`, `refLevelDb`, `speed`), what it accepts
 (`spansHz`, `refMinDb`…`refStepDb`, `modes`, `speeds`) and `problem`, why it
@@ -2422,6 +2529,39 @@ row/entry→`LookupRow` transform. See `DataFileManager`
 (`fetchType: 'raw'` — the parsed Hams of Note index is cached as JSON and
 replayed through `onLoadRawData` at startup, issue #17).
 
+### N1MM call history files
+
+N1MM Logger+'s call history files are uploaded to
+[n1mmwp.hamdocs.com](https://n1mmwp.hamdocs.com/mmfiles/categories/callhistory/)
+under a new name with every update (`CWOPS_4002.txt`), and downloaded by a
+form POST that carries a nonce from the file's own page, so no URL points at
+the current one. A `url` of `n1mm-history:<stem>` asks the host to find it
+(extension API 11):
+
+```ts
+{ key: 'cwops-history', url: 'n1mm-history:CWOPS', fetchType: 'raw', maxAgeInDays: 7, /* … */ }
+```
+
+- **Which file:** the newest one, by publish date, whose name is the stem or
+  the stem followed by `-` or `_` (extension and case aside). `CWOPS` takes
+  `CWOPS_4002.txt` and `CWOPS_4000-CCC.txt`, never `CWOPSOPEN_2026-002.txt`,
+  though N1MM's search lists all three; to follow one variant only, name it
+  (`n1mm-history:CWOPS_4000-CCC`). The search is read newest first, page by
+  page, until a page lists one of the stem's files.
+- **When:** N1MM sends no ETag; the chosen file's name, publish date and page
+  stand in for one, so a re-upload under the same name still counts as new. A
+  refresh whose newest file is the one last downloaded stops after the search,
+  like a 304. A forced refresh (RELOAD, Refresh) downloads it regardless.
+- **What arrives:** the file as served, in N1MM's format — a `!!Order!!,…`
+  column line, `#` comment lines, then CSV rows. `fetchType: 'raw'` is the one
+  that fits; `rawToJSONData` parses it. `url` in its arguments is the
+  `n1mm-history:` string, not the file's address.
+- **Failures:** a stem nothing matches, a refused download, or a page that no
+  longer has the shape the host reads fails the download with
+  `N1mmCallHistoryUnavailable` — a notice on a refresh the operator asked for,
+  an upload for the background passes. The requests and parsing are
+  `halo_core`'s `n1mm_call_history.dart`, shared by the app and the CLI.
+
 ### How CSV rows reach `csvToLookupEntry`
 
 An extension writes a **per-row** mapper; the kernel synthesizes the batch

package/package.json

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

package/samples/k2hrc-panafall/README.md

@@ -4,9 +4,9 @@ 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.
+Needs a radio whose CAT protocol carries its scope: an Icom IC-705/7300/7610 (at
+115200 bps on a serial line), or a FlexRadio, which is mirrored through a DAX IQ
+channel.
 
 In this repository: