@ham2k/extension-sdk 0.12.14 → 1.12.0

package/README.md

@@ -53,6 +53,13 @@ offline and describe the version installed here rather than whatever the
 repository says today. If an agent is writing your extension, point it at
 `node_modules/@ham2k/extension-sdk/AGENTS.md` — `h2kext-init` does that for you.
 
+## Versions
+
+The minor version is the extension API: SDK 1.12 describes API 12, and
+exports it as `API_VERSION`. `@ham2k/extension-tools` follows the same rule,
+so a `^1.12.0` range says the extension needs API 12 and admits every later
+one. A major version is a change that breaks an extension already written.
+
 ## Export types and settings
 
 Export hooks can register shared types with `getExportTypes()`. Use

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.14
+// @ham2k/extension-sdk 1.12.0
 /** 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 {
@@ -1288,6 +1360,9 @@ export interface CommandAction {
 	findInLog?: {
 		query?: string;
 	};
+	navigate?: {
+		to: string;
+	};
 	setCallField?: {
 		text: string;
 	};
@@ -1384,6 +1459,8 @@ export interface CommandCatalogEntry {
 	params?: string;
 	category?: string;
 	needsOperation?: boolean;
+	needsTestData?: boolean;
+	keywords?: string[];
 	expectsParams?: boolean;
 	suggest?: boolean;
 }
@@ -1994,7 +2071,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;
@@ -2542,6 +2619,14 @@ export interface TemplateContextArgs {
 }
 export declare function templateContext(args: TemplateContextArgs): Record<string, unknown>;
 export declare function isTestOperation(stationCall: JSONValue | undefined): boolean;
+/**
+ * The extension API this SDK describes: the highest `api` a manifest written
+ * against it can declare, and the one its types and host calls are for. The
+ * SDK's and `@ham2k/extension-tools`' minor version is this number, so a
+ * `^1.<api>.0` range names the oldest API an extension needs and admits every
+ * later one.
+ */
+export declare const API_VERSION = 12;
 export declare function defineExtension(def: ExtensionDefinition): void;
 export declare const hooks: {
 	invokeAll(category: HookCategoryName, method: string, args: unknown, online?: boolean): Promise<{
@@ -2614,6 +2699,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

@@ -1,5 +1,6 @@
 import { base64ToBytes, bytesToBase64 } from "./base64.js";
 import { adoptExtensionTimers, clearInterval, clearTimeout, setInterval, setTimeout } from "./timers.js";
+const API_VERSION = 12;
 export * from "./types.js";
 export * from "./hookCategories.js";
 export * from "./panelScene.js";
@@ -227,6 +228,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 });
   },
@@ -415,6 +427,7 @@ const host = {
   }
 };
 export {
+  API_VERSION,
   defineExtension,
   hooks,
   host

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

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
@@ -1146,10 +1170,10 @@ interface CommandHook {
   catalog?(ctx): Promise<CommandCatalogEntry[]>
 }
 // CommandInterpretation: {expectsParams?, mixedCase?, error?, describe?, confirm?, commands?: CommandAction[]}
-// CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
+// CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, needsTestData?, keywords?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
 //   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, autoRespot?, syncAll?, updateSettings?, updateSetting?, openSettings?,
-//   updateOperation?, markSegment?, findInLog?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
+//   updateOperation?, markSegment?, findInLog?, navigate?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
 ```
@@ -1342,9 +1366,12 @@ Three things differ from `interpret`, all deliberate:
 - **Called once and cached**, not per keystroke — dropped when the runtime is
   replaced (an extension enabled/disabled) or the hook context is
   invalidated (locale change, since `describe` is localized by the hook).
-- **Matching is host-side**, plain case-insensitive substring against
-  `command` and `describe`. Same rule `interpret`'s own matching follows: the
-  host never compiles extension-supplied patterns.
+- **Matching is host-side**, case-insensitive, at the start of a word in
+  `command` or in `keywords` — never mid-word, and `describe` is never
+  searched. Every word that should find a command belongs in its
+  `keywords`: the aliases it accepts when typed, and plain words for what it
+  does. Same rule `interpret`'s own matching follows: the host never
+  compiles extension-supplied patterns.
 - **List commands, not variants.** `radio-commands` advertises one BAND
   entry, not fifteen; `call-notes` advertises `//`, not every key the user
   has defined.
@@ -1876,9 +1903,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 +1917,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 +1929,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 +1941,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 +2083,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:
@@ -2288,7 +2341,7 @@ 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.
-On a host with the panadapter enabled, `readRadio()` carries `spectrum`: null
+`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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.12.14",
+  "version": "1.12.0",
   "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,17 @@ 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 supported radio:
+
+- Icom IC-705/7300/7610, at 115200 bps when using a serial line.
+- FlexRadio, mirrored through a DAX IQ channel.
+- Elecraft K4 over Ethernet, with a separate local TCP spectrum connection on
+  port 9201 alongside CAT. It displays the main panadapter with local zoom,
+  reference and speed controls. Levels are displayed as received, without an
+  RF calibration claim.
+
+The panel shows only the controls each radio supports; contrast, averaging,
+frame rate and waterfall rows remain local.
 
 In this repository:
 
@@ -14,3 +22,8 @@ In this repository:
 node build.mjs
 node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-panafall.h2kext
 ```
+
+Samples are not included in the app's regular extension build. Install the
+resulting `.h2kext` through **Settings → Extensions & Features → Install from
+file…**, then add its **Panadapter** panel to an operation. The host must have
+the matching radio support.

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

@@ -42,15 +42,25 @@ const spanLabel = (hz: number) => `±${hz >= 1000 ? `${hz / 1000} kHz` : `${hz}
 export function scene(radio: PanelRadioState | null, display: Display, step = "100"): PanelScene {
   const spectrum: PanelRadioSpectrum | null | undefined = radio?.spectrum
   const knobs = spectrum && !spectrum.problem
+  const hasSpan = knobs && spectrum.spansHz.length > 0
+  const hasSpeed = knobs && spectrum.speeds.length > 0
+  const hasRef =
+    knobs &&
+    Number.isFinite(spectrum.refMinDb) &&
+    Number.isFinite(spectrum.refMaxDb) &&
+    Number.isFinite(spectrum.refStepDb) &&
+    spectrum.refMinDb < spectrum.refMaxDb &&
+    spectrum.refStepDb > 0
+  const ref = hasRef ? Math.max(spectrum.refMinDb, Math.min(spectrum.refMaxDb, spectrum.refLevelDb ?? spectrum.refMinDb)) : 0
   const band = passband(radio?.mode)
   return {
     version: 1,
     width: 600,
     height: 24,
-    values: { floor: 0, average: 40, fps: 15, rows: 10, hoverHz: 0, hoverDb: 0, ref: spectrum?.refLevelDb ?? 0 },
+    values: { floor: 0, average: 40, fps: 15, rows: 10, hoverHz: 0, hoverDb: 0, ref },
     strings: {
-      span: spectrum?.spanHz != null ? String(spectrum.spanHz) : "",
-      speed: spectrum?.speed ?? "",
+      span: hasSpan && spectrum.spanHz != null && spectrum.spansHz.includes(spectrum.spanHz) ? String(spectrum.spanHz) : "",
+      speed: hasSpeed && spectrum.speed != null && spectrum.speeds.includes(spectrum.speed) ? spectrum.speed : "",
       display,
       step,
     },
@@ -65,7 +75,7 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
       },
     ],
     controls: [
-      ...(knobs
+      ...(hasSpan
         ? [
             {
               id: "span",
@@ -75,6 +85,10 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
               event: "span",
               options: spectrum.spansHz.map((hz) => ({ label: spanLabel(hz), value: String(hz) })),
             },
+          ]
+        : []),
+      ...(hasRef
+        ? [
             {
               id: "ref",
               label: "Reference level",
@@ -85,6 +99,10 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
               max: spectrum.refMaxDb,
               step: spectrum.refStepDb,
             },
+          ]
+        : []),
+      ...(hasSpeed
+        ? [
             {
               id: "speed",
               label: "Speed",
@@ -100,7 +118,7 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
       { id: "fps", label: "Panadapter FPS", kind: "nativeSlider" as const, value: "fps", min: 1, max: 30, step: 1 },
       { id: "rows", label: "Waterfall rows per second", kind: "nativeSlider" as const, value: "rows", min: 1, max: 30, step: 1 },
       // A control the layout does not place fails the scene: Ref's label goes with its slider.
-      ...[...(knobs ? ["Ref"] : []), "Contrast", "Avg", "FPS", "Rows"].map((text) => ({
+      ...[...(hasRef ? ["Ref"] : []), "Contrast", "Avg", "FPS", "Rows"].map((text) => ({
         id: `label-${text}`,
         label: text,
         kind: "nativeText" as const,
@@ -179,7 +197,9 @@ export function scene(radio: PanelRadioState | null, display: Display, step = "1
       column: [
         {
           wrap: [
-            ...(knobs ? [{ control: "span" }, labeled("Ref", "ref"), { control: "speed" }] : []),
+            ...(hasSpan ? [{ control: "span" }] : []),
+            ...(hasRef ? [labeled("Ref", "ref")] : []),
+            ...(hasSpeed ? [{ control: "speed" }] : []),
             labeled("Contrast", "floor"),
             labeled("Avg", "average"),
             labeled("FPS", "fps"),