@ham2k/extension-sdk 0.12.6 → 0.12.8

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.6
+// @ham2k/extension-sdk 0.12.8
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -12,7 +12,22 @@ export interface PanelScene {
 	controls?: PanelSceneControl[];
 	/** Where rect-less native controls and the artwork go. Omitted, the artwork fills the panel. */
 	layout?: PanelSceneLayoutNode;
+	/**
+	 * Have the host feed a radio's live readings into `values` — the `PanelSceneRadioValue` names,
+	 * updated as the radio reports them, with no render. `node` is a radio's id; omitted, the
+	 * logging radio. Needs `requiresRadioRead` and extension API 7; without either, every reading
+	 * is missing. A missing reading binds as the bottom of a binding's range and shows as `—`.
+	 */
+	radio?: {
+		node?: 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"
+/** The SWR averaged over the transmission under way, or else the last one. Extension API 7. */
+ | "radio.swrAverage"
+/** 0 while transmitting, then counting up; a long time when there has been none. Extension API 7. */
+ | "radio.secondsSinceTransmit";
 /** A clamped, linear mapping. No expressions or extension code run per frame. */
 export interface SceneBinding {
 	value: string;
@@ -54,6 +69,8 @@ export interface PanelSceneLayer {
 		decimals?: number;
 		size?: number;
 		color?: string;
+		/** `#RRGGBB`: a soft halo of this colour around the letters, to keep them legible over artwork. Extension API 7. */
+		glow?: string;
 		samples?: (number | string)[];
 		/** Multiply numeric text values before formatting. Defaults to 1. */
 		scale?: number;
@@ -71,8 +88,11 @@ export interface PanelSceneLayer {
 	rotation?: SceneBinding;
 	translateX?: SceneBinding;
 	translateY?: SceneBinding;
+	/** Scale about `pivot` — a bar's fill with `pivot: [0, 0.5]`. Extension API 7. */
+	scaleX?: SceneBinding;
+	scaleY?: SceneBinding;
 	opacity?: SceneBinding;
-	/** Rotation origin as fractions of this layer's dimensions; default [0.5, 0.5]. */
+	/** Rotation and scale origin as fractions of this layer's dimensions; default [0.5, 0.5]. */
 	pivot?: [
 		number,
 		number
@@ -157,6 +177,19 @@ export interface PanelSceneSpectrum {
 	gridColor?: string;
 	/** The frequency lines carried down through the waterfall. Omitted, none. */
 	waterfallGridColor?: string;
+	/**
+	 * Keeps the tuned frequency at least this share of the width (0–0.45) from either edge, by
+	 * moving the radio's scope just far enough to put it at that margin. Only where the radio lets
+	 * the app place its scope — a FlexRadio, whose panadapter in SmartSDR moves with it — and the
+	 * panel declares `requiresRadioWrite`; elsewhere it changes nothing. Extension API 7.
+	 */
+	follow?: number;
+	/**
+	 * Hz shown across the control, from the middle of each sweep. A sweep wider than this is cropped
+	 * to it, so a radio whose scope comes in a few widths can be shown at any narrower one — set the
+	 * scope (`setRadioSpectrum`) to the narrowest that covers it. Extension API 7.
+	 */
+	span?: PanelSceneSpectrumNumber;
 	/** A click tunes to the nearest multiple of this many Hz. Omitted, wherever it lands. */
 	tuneStep?: PanelSceneSpectrumNumber;
 	/** Dashes the panadapter's grid lines. */
@@ -195,6 +228,8 @@ export interface PanelSceneSpectrumScale {
 	labels?: boolean | {
 		/** Hz between labels. Omitted, the gridlines' step. */
 		interval?: PanelSceneSpectrumNumber;
+		/** Decimals of MHz every label shows, 0–6. Omitted, as many as tell one label from the next. Extension API 7. */
+		decimals?: number;
 		fontFamily?: string;
 		size?: PanelSceneSpectrumNumber;
 		/** 100–900. */
@@ -287,7 +322,10 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 	id: string;
 	label: string;
 	kind: PanelSceneControlKind;
-	/** A button can open a native dropdown. Picking an item sends its event as the action. */
+	/**
+	 * A button can open a native dropdown. Picking an item sends its event as the action. On a knob
+	 * (extension API 7) a click opens it, while a scroll or a drag still turns the knob.
+	 */
 	menu?: {
 		label: string;
 		event: string;
@@ -349,6 +387,18 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 	valueLabels?: string[];
 	/** Knobs use relative horizontal/upward dragging. Value per scene unit; default 1. */
 	sensitivity?: number;
+	/**
+	 * 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
+	 * knob with an `event` must give, different from it. Its range and feel are `minY`, `maxY`, `stepY`
+	 * and `sensitivityY`. Extension API 7.
+	 */
+	valueY?: string;
+	eventY?: string;
+	minY?: number;
+	maxY?: number;
+	stepY?: number;
+	sensitivityY?: number;
 }
 export interface PanelSceneEvent {
 	controlId: string;
@@ -1748,6 +1798,50 @@ export interface PanelRadioState {
 	transmitting: boolean | null;
 	meters: Partial<Record<"signalDbm" | "powerOut" | "swr" | "alc" | "supplyVolts", number>>;
 	canTune: boolean;
+	/** The model's rated output ceiling, where the app knows it (extension API 7). */
+	maxWatts?: number | null;
+	/**
+	 * The radio's antenna tuner as it reports it, or null for a radio without one, or whose driver
+	 * cannot read it (extension API 7).
+	 */
+	tuner?: "inline" | "bypassed" | "tuning" | "failed" | null;
+	/**
+	 * 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
+	 * (extension API 7).
+	 */
+	passband?: {
+		lowHz: number;
+		highHz: number;
+	} | null;
+	/**
+	 * The radio's own antenna ports, by the radio's names, and which it uses — or null where its driver
+	 * cannot read them. `separate`: it picks receive and transmit antennas independently, as a FlexRadio
+	 * does; otherwise one port serves both (extension API 7).
+	 */
+	antennas?: {
+		rxPorts: string[];
+		txPorts: string[];
+		rx: string | null;
+		tx: string | null;
+		separate: boolean;
+	} | null;
+	/** The modes `setRadio` accepts for this radio, in the radio's order (extension API 7). */
+	modes?: string[];
+	/**
+	 * What the app keys with, while this is the logging radio, connected, and the app's keying
+	 * is on; null otherwise (extension API 7).
+	 */
+	keying?: PanelRadioKeying | null;
+	/**
+	 * The last transmission the radio finished since the app started: its average SWR over the readings taken with
+	 * RF out (null when there were none), and when it ended in real milliseconds — compare it with
+	 * `clock.realNowMillis` (extension API 7).
+	 */
+	lastTransmission?: {
+		swrAverage: number | null;
+		endedAtMillis: number;
+	} | null;
 	/**
 	 * The radio's scope, on hosts with the panadapter enabled: absent there otherwise, and null
 	 * for a radio without one. The sweeps are never sent — a `spectrum` scene control draws them.
@@ -1783,21 +1877,80 @@ export interface PanelRadioSpectrumSet {
 	refLevelDb?: number;
 	speed?: PanelRadioSpectrumSpeed;
 }
-export interface PanelRadioTune {
+/** The logging radio's keying: the designated key, radio1's voice memories and its PTT. */
+export interface PanelRadioKeying {
+	canKeyCw: boolean;
+	cwSending: boolean;
+	/** The key's own report, clamping included; null before it has said. */
+	keyerSpeedWpm: number | null;
+	keyerSpeedRange: {
+		min: number;
+		max: number;
+	} | null;
+	canPtt: boolean;
+	/** Whether the app's PTT latch is holding the transmitter. */
+	ptt: boolean;
+	/** Empty when the radio plays none. `number` is what `playRadioVoice` takes. */
+	voiceMemories: {
+		number: number;
+		label: string;
+	}[];
+}
+/** A radio identity and selection, as every command carries. */
+export interface PanelRadioTarget {
 	/** Reject if this identity no longer matches the selected radio. */
 	id: string;
 	/** Pin a local radio by ID; omitted means follow the designated radio. */
 	selection?: string;
+}
+export interface PanelRadioSet extends PanelRadioTarget {
 	frequencyHz?: number;
-	mode?: "LSB" | "USB" | "CW" | "AM" | "FM";
+	/**
+	 * The frequency comes from an on-screen dial turning, not a typed or clicked target: on the
+	 * logging radio, the app's Smart VFO Snap settles it like the radio's own knob (extension API 7).
+	 */
+	dial?: boolean;
+	/** One of the radio's `modes`. */
+	mode?: string;
+	/** Up to `maxWatts` where the radio states one. On the logging radio this is the power the next QSO logs. */
+	powerWatts?: number;
+	/** The logging radio's keyer; refused as `unsupported` where `keying.canKeyCw` is false. */
+	keyerSpeedWpm?: number;
+	/**
+	 * Puts the antenna tuner in line or bypasses it; refused as `unsupported` where `tuner` is null.
+	 * On a FlexRadio, in line is a TUNE — a carrier on the air — since its tuner has no other way in.
+	 */
+	tunerInline?: boolean;
+	/**
+	 * 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
+	 * result back from `passband`.
+	 */
+	passband?: {
+		lowHz: number;
+		highHz: number;
+	};
+	/** Ports from `antennas`; refused as `unsupported` where that is null. Without `separate`, either names the one port. */
+	antenna?: {
+		rx?: string;
+		tx?: string;
+	};
 }
-export interface PanelRadioTuneResult {
+/** @deprecated `setRadio`'s argument through extension API 6. */
+export type PanelRadioTune = PanelRadioSet;
+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. */
-	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped";
+	/**
+	 * `stopped`: a scope change while no display has the scope running — nothing was sent.
+	 * `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";
 	state: PanelRadioState | null;
 }
+/** @deprecated `PanelRadioResult`'s name through extension API 6. */
+export type PanelRadioTuneResult = PanelRadioResult;
 export interface PanelRenderArgs {
 	/** Present on environment-capable hosts. Changes automatically request a throttled render of a `scene` panel. */
 	environment?: PanelEnvironment;
@@ -2232,14 +2385,29 @@ export declare const hooks: {
 export declare const host: {
 	listRadios(): Promise<PanelRadioState[]>;
 	readRadio(id?: string): Promise<PanelRadioState | null>;
-	setRadioConnection(args: {
-		id: string;
-		selection?: string;
+	setRadioConnection(args: PanelRadioTarget & {
 		connected: boolean;
-	}): Promise<PanelRadioTuneResult>;
-	tuneRadio(args: PanelRadioTune): Promise<PanelRadioTuneResult>;
+	}): Promise<PanelRadioResult>;
+	/** Sets frequency, mode, power, keyer speed, tuner, passband and antennas. Needs `requiresRadioWrite` and extension API 7. */
+	setRadio(args: PanelRadioSet): Promise<PanelRadioResult>;
+	/** @deprecated `setRadio`'s name through extension API 6, still answered by newer hosts. */
+	tuneRadio(args: PanelRadioSet): Promise<PanelRadioResult>;
 	/** Changes the radio's scope. Needs `requiresRadioWrite` and extension API 6; the result's state reports what the radio took. */
-	setRadioSpectrum(args: PanelRadioSpectrumSet): Promise<PanelRadioTuneResult>;
+	setRadioSpectrum(args: PanelRadioSpectrumSet): Promise<PanelRadioResult>;
+	/** Keys `text` on the logging radio's key, as the keyer area does. Needs `requiresRadioWrite` and extension API 7. */
+	sendRadioCw(args: PanelRadioTarget & {
+		text: string;
+	}): Promise<PanelRadioResult>;
+	/** Plays one of `keying.voiceMemories` once — never repeating. Needs `requiresRadioWrite` and extension API 7. */
+	playRadioVoice(args: PanelRadioTarget & {
+		memory: number;
+	}): Promise<PanelRadioResult>;
+	/** Keys or unkeys the logging radio's PTT through the app's own latch. Needs `requiresRadioWrite` and extension API 7. */
+	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. */
+	stopRadioTransmit(args: PanelRadioTarget): Promise<PanelRadioResult>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;
 	kvGet(key: string): Promise<JSONValue | null>;

package/dist/index.js

@@ -169,6 +169,11 @@ const host = {
   async setRadioConnection(args) {
     return await hostCallFn()("setRadioConnection", { ...args });
   },
+  /** Sets frequency, mode, power, keyer speed, tuner, passband and antennas. Needs `requiresRadioWrite` and extension API 7. */
+  async setRadio(args) {
+    return await hostCallFn()("setRadio", { ...args });
+  },
+  /** @deprecated `setRadio`'s name through extension API 6, still answered by newer hosts. */
   async tuneRadio(args) {
     return await hostCallFn()("tuneRadio", { ...args });
   },
@@ -176,6 +181,22 @@ const host = {
   async setRadioSpectrum(args) {
     return await hostCallFn()("setRadioSpectrum", { ...args });
   },
+  /** Keys `text` on the logging radio's key, as the keyer area does. Needs `requiresRadioWrite` and extension API 7. */
+  async sendRadioCw(args) {
+    return await hostCallFn()("sendRadioCw", { ...args });
+  },
+  /** Plays one of `keying.voiceMemories` once — never repeating. Needs `requiresRadioWrite` and extension API 7. */
+  async playRadioVoice(args) {
+    return await hostCallFn()("playRadioVoice", { ...args });
+  },
+  /** Keys or unkeys the logging radio's PTT through the app's own latch. Needs `requiresRadioWrite` and extension API 7. */
+  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. */
+  async stopRadioTransmit(args) {
+    return await hostCallFn()("stopRadioTransmit", { ...args });
+  },
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },

package/docs/distribution.md

@@ -53,7 +53,12 @@ and `onShow`/`onHide`, and from 3 the build rewrites a bare `setTimeout` into
 the SDK's (README's "Timers"); 4 lets `host.fetch` reach a plain-`http://` host
 the app fronts with its https proxy (README's `host.fetch`); 5 adds panel
 scenes' `scene` kind, native controls, `strings`, `layout`, `after` and control
-`opacity` (hooks.md's `panel`).
+`opacity` (hooks.md's `panel`); 6 adds the scene's `spectrum` control and
+`host.setRadioSpectrum`; 7 adds `host.setRadio`, the keying calls
+(`sendRadioCw`, `playRadioVoice`, `setRadioPtt`, `stopRadioTransmit`), what
+`readRadio` adds with them, and the scene's host-fed `radio` values, scale
+bindings, text glow, two-axis and menu knobs and the spectrum's `follow`,
+`span` and label `decimals`.
 
 Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
@@ -262,7 +267,7 @@ It reports every problem at once rather than one per run:
 h2kext-pack: ./build is not ready to package:
 manifest.json: missing required field 'name'
 manifest.json: key 'my-clock' must start with your callsign — 'my' is not one (e.g. ki2d-my-clock)
-manifest.json: missing 'api' — declare the extension API this was built against (currently 6)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 7)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own

package/docs/hooks.md

@@ -1551,7 +1551,11 @@ which the SDK keeps as a deprecated alias along with the `SvgScene*` type names.
 `strings`, `layout`, `after` and control `opacity`. A bundle using any of them
 declares `"api": 5` ([distribution.md](distribution.md)), and an app speaking
 less refuses it at install rather than showing the panel as an unknown kind.
-A plain scene that must reach those apps keeps `svgScene` and its lower API. Scene-capable hosts pass
+A plain scene that must reach those apps keeps `svgScene` and its lower API.
+**Extension API 7** adds the scene's host-fed `radio` values (*Radio values*
+below), `scaleX`/`scaleY` bindings, text `glow`, a knob's `menu` and second
+axis, and the spectrum control's `follow`, `span` and label `decimals`; a
+bundle using any of them declares `"api": 7`. Scene-capable hosts pass
 `instanceId` on render/event calls. `onEvent` handles control events and returns
 value patches (`values`, and `strings` for string controls); local-only controls and animation frames make no bridge
 calls. Controls with `continuous: true` send `change` events during dragging and a
@@ -1561,7 +1565,10 @@ for local numeric formatting; bindings accept `scale`, `truncate` and `modulo`
 too, applied to the value before the ramp. KI2D’s Radio Panel uses these for its Modern
 frequency groups; its settings offer Modern/LCD styles and radio selection. Local sliders may use `hover` and `discrete` hourly buckets. Text `samples`
 may hold numbers or preformatted strings; control `valueLabels` supplies accessible
-value descriptions. Transform/opacity bindings may also supply numeric `samples`,
+value descriptions. A layer binds `rotation`, `translateX`/`translateY`,
+`scaleX`/`scaleY` and `opacity`; rotation and scale turn about its `pivot`, so
+`scaleX` with `pivot: [0, 0.5]` grows a bar's fill from its left end.
+Transform/opacity bindings may also supply numeric `samples`,
 equally spaced over their `input` range, instead of the `output` ramp. The host
 interpolates and clamps these locally; chart markers and callouts can follow
 individual readings without bridge calls. See [the design notes and open milestones](https://github.com/ham2k/halo/blob/main/docs/design/panel-scenes.md)
@@ -1599,10 +1606,13 @@ Both `environment` and `clock` are optional in the SDK for older-host detection.
 Use scene **text layers** for typography; SVG `<text>` is not a portable text path
 through the renderer. Text supports either `literal` or bound `value`, plus
 `fontFamily`, `fontWeight`, `lineHeight`, and `letterSpacing`. Text participates
-in native directionality, accessibility scaling and semantics.
+in native directionality, accessibility scaling and semantics. A text `glow`
+(`#RRGGBB`) draws a soft halo of that colour around the letters, to keep them
+legible over busy artwork.
 Button controls can supply `menu: [{label, event}]` to open a native dropdown.
 Selecting an item emits its `event` as the action with the original control ID;
-dismissing the menu emits nothing.
+dismissing the menu emits nothing. A knob takes a `menu` too: a click opens it,
+while a scroll or a drag still turns the knob.
 
 **Native controls.** Besides the drawn `button`, `slider` and `knob` — invisible
 hit areas over the extension's own artwork — a scene can use Material widgets
@@ -1619,7 +1629,11 @@ on leaving it after typing; a render that lands while the operator is typing
 does not overwrite the typing. Every control's `label` is its accessible name;
 the app has no tooltips. A text field or dropdown in a panel keeps keyboard
 focus; clicking any other native control hands focus back to the callsign
-field, as clicking a button anywhere else in the Operation view does.
+field, as clicking a button anywhere else in the Operation view does. A drawn
+`button` never takes focus from a click, so the operator's typing stays where
+it was. A drawn `slider` or `knob` clicked or dragged holds focus for three
+seconds after its last use — long enough for the arrow keys to adjust it — then
+hands it back to wherever it came from. Focus that arrives by Tab stays.
 
 **Layout.** A native control either has an `x`/`y`/`width`/`height` rect over the
 artwork, like the drawn kinds — it takes the rect's width and its own height, up
@@ -1664,6 +1678,7 @@ drawing part of it.
 | `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. |
 | `layout` | Optional. Where rect-less native controls and the artwork go; omitted, the artwork fills the pane. |
+| `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
 name. An `event` names the action sent when it is used; without one the control
@@ -1674,7 +1689,7 @@ the extension. `value` names what it shows and sets.
 |---|---|---|---|
 | `button` | — | `activate` | `menu` |
 | `slider` | number | `commit` | `min`, `max`, `step`, `discrete`, `hover`, `valueLabels`, `continuous` |
-| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `valueLabels`, `continuous` |
+| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `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` |
@@ -1702,6 +1717,15 @@ 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 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
+`valueY`, which must be in `values`, with its own range, step and feel from the
+`…Y` fields. The second axis sends its events with the action `eventY`, which a
+knob with an `event` must give, different from `event` — an event carries no
+other mark of which axis moved, and a scene without one is refused. The host queues the two axes separately, so neither
+replaces the other's pending value, and a drag commits only the axes it moved.
+
 **Layout nodes.** Each is an object with exactly one of these keys:
 
 | Node | |
@@ -1796,6 +1820,11 @@ export const spotter: PanelHook = {
 }
 ```
 
+The callsign comes back upper-cased, and the field shows the extension's
+version once the typing is committed. A bundle carrying this declares
+`"api": 5`. The `k2hrc-panel-scenes` sample in the SDK has every kind, a
+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
@@ -1820,7 +1849,20 @@ control and takes the fields of `PanelSceneSpectrum` in the SDK:
 - `overlays`: up to 16 lines (`at`) and areas (`from`, `to`) in Hz from the
   tuned frequency, the sweep's middle, or absolute, each styled per part.
 - `scale`: the gap between the panadapter and the waterfall, its fill and
-  borders, and frequency `labels` and `ticks`.
+  borders, and frequency `labels` and `ticks`. `labels.decimals` (0–6) fixes
+  the decimals of MHz every label shows; omitted, as many as tell one label
+  from the next.
+- `span`: Hz shown across the control, from the middle of each sweep — a
+  number or a scene value. A wider sweep is cropped to it, so a radio whose
+  scope comes in a few fixed widths can be shown at any narrower one; set the
+  scope to the narrowest that covers it. Everything is drawn, labelled and
+  clicked on the window shown.
+- `follow` (0–0.45): keeps the tuned frequency at least this share of the
+  width from either edge, by moving the radio's scope just far enough to put
+  it on that margin — the picture scrolls with the dial rather than jumping
+  to centre it. Only where the radio lets the app place its scope (a
+  FlexRadio, whose panadapter in SmartSDR moves with it) and the panel
+  declares `requiresRadioWrite`; elsewhere it changes nothing.
 - `annotations`: up to 64 pieces of text at frequencies, with a pointer to
   where they sit. One with an `event` sends `activate` when clicked, its
   frequency as `value` and its `id` as `annotation`, and does not tune.
@@ -1828,10 +1870,35 @@ control and takes the fields of `PanelSceneSpectrum` in the SDK:
 - `tuneStep`: a click elsewhere sends `commit` with the frequency under it,
   rounded to this many Hz. The extension decides whether to tune.
 
-The callsign comes back upper-cased, and the field shows the extension's
-version once the typing is committed. A bundle carrying this declares
-`"api": 5`. The `k2hrc-panel-scenes` sample in the SDK has every kind, a
-control faded in over the artwork, and a click-through layer painted over it.
+Each waterfall row stays at the frequencies it was taken on: when the radio
+retunes its scope the history slides sideways, and when the span changes it
+stretches, rather than old signals being redrawn where they never were.
+
+#### Radio values
+
+A scene with a document-level `radio` block (extension API 7) is fed that
+radio's live readings by the host, into reserved values a binding, a text
+layer or a control's `opacity` can read like any other:
+
+| Value | |
+|---|---|
+| `radio.signalDbm` | Receive signal, dBm. |
+| `radio.powerOut` | RF out, watts. |
+| `radio.swr`, `radio.alc`, `radio.supplyVolts` | The transmit meters. |
+| `radio.transmitting` | 1 or 0. |
+| `radio.swrAverage` | The SWR averaged over the transmission under way, or else over the last one — only readings taken with RF out count. |
+| `radio.secondsSinceTransmit` | 0 while transmitting, then counting up; a very large number when there has been no transmission. |
+
+They change as the radio reports them — several times a second — with no
+render and no bridge call, so a meter needle moves at the radio's rate while
+the extension renders once a second or not at all. A reading the radio has
+not given, or no longer fresh, is missing: a binding takes it as the bottom
+of its range and a text layer shows `—`. `radio.secondsSinceTransmit` is
+re-read on its own for fifteen seconds after a transmission, so a hold or a
+fade bound to it ends on time. The names are reserved — a scene may not
+declare them in `values` or `strings` — and readable only with the block;
+nothing may set them. The feed needs `requiresRadioRead`: without it every
+reading is missing.
 
 The `ki2d-weather-panel`, `ki2d-solar-panel` and `ki2d-radio-panel` reference
 panels live in
@@ -1843,8 +1910,10 @@ repository's dashboard README for building them.
 The radio host calls are manifest capabilities, refused unless declared — the
 same shape as `requiresLocation`, and shown to the operator at install:
 `"requiresRadioRead": true` allows `host.listRadios()` and `host.readRadio()`;
-`"requiresRadioWrite": true` allows `host.tuneRadio()`,
-`host.setRadioConnection()` and `host.setRadioSpectrum()`, and implies read, since a command answers with the
+`"requiresRadioWrite": true` allows `host.setRadio()`,
+`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.
 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
@@ -1859,19 +1928,93 @@ the hook); the control shows its pending value until the outcome is known.
 local transceivers. `host.readRadio(id?)` returns
 a **local** radio's reported frequency (Hz), mode, connection state,
 power, TX state and fresh telemetry, or null on hosts without this API.
-`meters.signalDbm` is receive power in whole dBm when supported, refreshed a few
+`meters` holds `signalDbm`, `powerOut`, `swr`, `alc` and `supplyVolts`, each
+only while its driver has a fresh reading. `meters.signalDbm` is receive power in whole dBm when supported, refreshed a few
 times a second; it expires after two seconds without a reading. The Flex driver receives the selected slice’s LEVEL
-meter through its native UDP channel. The reference panel draws a segmented
+meter, and the transmitter's forward power and SWR, through its native UDP channel. The reference panel draws a segmented
 receive meter and leaves it unlit when unavailable, stale, or transmitting. It does
-not substitute the app's manually entered VFO for a radio reading.
-`host.tuneRadio({id, frequencyHz?, mode?})` targets that same radio through the
-existing VFO/CAT service. Supported mode requests are LSB, USB, CW, AM and FM.
-The host rejects a changed designation, disconnected/stale radio, transmission
-in progress or malformed command, and spaces accepted tuning requests by at
-least 250 ms. Omitting a selection follows the designated logging radio; an explicit `selection`
-pins tuning to that local radio without changing the logging designation.
+not substitute the app's manually entered VFO for a radio reading. A scene
+that only draws meters reads them as *Radio values* instead, at the radio's
+rate. Extension API 7 adds to the answer:
+
+- `maxWatts`: the model's rated output, where the app knows it; `modes`: the
+  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.
+- `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
+  read it.
+- `antennas`: `{rxPorts, txPorts, rx, tx, separate}`, the radio's own antenna
+  ports by the radio's names and which it uses, or null where its driver
+  cannot read them. `separate`: it picks receive and transmit independently,
+  as a FlexRadio does; otherwise one port serves both.
+- `keying`: what the app keys with — `canKeyCw`, `cwSending`,
+  `keyerSpeedWpm` (the key's own report, null before it has given one),
+  `keyerSpeedRange`, `canPtt`, `ptt` (whether the app's PTT latch holds the
+  transmitter) and `voiceMemories` (`[{number, label}]`, empty for a radio
+  that plays none) — while this is the logging radio, connected, on a host
+  with keying enabled; null otherwise.
+- `lastTransmission`: `{swrAverage, endedAtMillis}` for the last
+  transmission the radio finished since the app started — its SWR averaged over the readings
+  taken with RF out (null when there were none), and when it ended, in real
+  milliseconds to compare with `clock.realNowMillis` — or null.
+
+`host.setRadio({id, selection?, ...settings})` sets any of these on that same
+radio, through the existing VFO/CAT service. It and the keying calls below are
+extension API 7: a bundle using them declares `"api": 7`.
+
+- `frequencyHz`; `dial: true` says it comes from an on-screen dial turning,
+  not a typed or clicked target, and on the logging radio Smart VFO Snap
+  settles it like the radio's own knob.
+- `mode`: one of `modes`.
+- `powerWatts`: up to `maxWatts` where that is stated. On the logging radio
+  it goes through the app's VFO, so it is the power the next QSO logs.
+- `keyerSpeedWpm`: the logging radio's keyer, which clamps to its own range —
+  `keying.keyerSpeedWpm` says what it took.
+- `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.
+- `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
+  call that also changes `mode` is `invalid`.
+- `antenna`: `{rx?, tx?}`, ports from `antennas`; without `separate`, either
+  names the one port, and two different ones are `invalid`. An `rx` naming
+  the `tx` asked for in the same call is taken even where `rxPorts` does not
+  list it yet.
+
+The host rejects a changed designation (`changed`), a disconnected or stale
+radio (`disconnected`), a transmission in progress (`transmitting`) and a
+malformed command or a value out of range (`invalid`); a setting this radio
+cannot take — a tuner, passband or antenna its readout has as null, a keyer
+speed without `keying.canKeyCw` — answers `unsupported`. Accepted requests are
+spaced by at least 250 ms, since a dragged control would otherwise flood the
+CAT link. Omitting a selection follows the designated logging radio; an explicit `selection`
+pins the command to that local radio without changing the logging designation.
 An accepted result means requested, not confirmed; only subsequent
 reported state confirms it. Drivers retain their own protocol/echo handling.
+
+The keying calls transmit, and act only on the logging radio, on a host with
+keying enabled — a panel pinned to another radio is answered `unsupported`
+rather than keying the logging radio behind the operator's back:
+
+- `host.sendRadioCw({id, selection?, text})` keys `text` (up to 1000
+  characters) on the key in use, as the keyer area's messages do.
+- `host.playRadioVoice({id, selection?, memory})` plays one of
+  `keying.voiceMemories` once. It never arms a repeat: a CQ repeating on a
+  panel's say-so is one the operator did not start where they would stop it.
+- `host.setRadioPtt({id, selection?, on})` keys or unkeys PTT through the
+  app's own latch, so Escape releases it as it does the operator's own.
+  `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
+  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)
+answers `unsupported`; one that is not connected, `disconnected`. These are
+not paced, and not refused for a transmission in progress.
 `host.setRadioConnection({id, selection?, connected})` starts or ends a local CAT
 connection using the same selection and identity checks. Acceptance starts the
 operation; follow reported connection state for completion. It does not switch

package/package.json

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

package/samples/README.md

@@ -11,6 +11,7 @@ building — the header comment in each `src/index.ts` says what it leaves out.
 | `k2hrc-cqww` | A contest: an exchange to type, and a score to keep |
 | `k2hrc-radio` | An HTML panel, and why you should probably write markdown instead |
 | `k2hrc-panel-scenes` | Experimental panel scenes: SVG artwork, controls and animations, with simulated radio and weather panels |
+| `k2hrc-panafall` | A radio's panadapter and waterfall in a scene, styled and tuned by click (extension API 7) |
 
 ## Running one
 

package/samples/k2hrc-panafall/README.md

@@ -0,0 +1,16 @@
+# Panadapter & Waterfall
+
+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.
+
+In this repository:
+
+```sh
+node build.mjs
+node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-panafall.h2kext
+```

package/samples/k2hrc-panafall/build.mjs

@@ -0,0 +1,6 @@
+import { build } from "esbuild"
+import { buildExtension } from "@ham2k/extension-tools"
+
+await buildExtension(build, { dir: import.meta.dirname })
+
+console.log("built build/index.js")

package/samples/k2hrc-panafall/manifest.json

@@ -0,0 +1,24 @@
+{
+  "key": "k2hrc-panafall",
+  "name": "Panadapter & Waterfall",
+  "shortName": "Panafall",
+  "version": "0.1.0",
+  "description": "The radio's panadapter and waterfall, with span, reference level and click-to-tune",
+  "category": "dashboard",
+  "icon": "waveform",
+  "accentColor": "#4C6EF5",
+  "api": 7,
+  "keywords": ["radio", "panadapter", "waterfall", "spectrum", "panel", "sample"],
+  "hooks": ["panel"],
+  "requiresRadioWrite": true,
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.0",
+    "@ham2k/lib-country-files": "^1.0.0",
+    "@ham2k/lib-dxcc-data": "^1.0.0",
+    "@ham2k/lib-format-tools": "^1.0.0",
+    "@ham2k/lib-geo-tools": "^1.0.0",
+    "@ham2k/lib-operation-data": "^1.0.0",
+    "i18next": "^23.0.0",
+    "liquidjs": "^10.0.0"
+  }
+}

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

@@ -0,0 +1,12 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+import { defineExtension } from "@ham2k/extension-sdk"
+import manifest from "../manifest.json" with { type: "json" }
+import { createPanafall } from "./panafall.ts"
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("panel", { key: manifest.key, hook: createPanafall() })
+  },
+})

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

@@ -0,0 +1,238 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// The radio's scope as a scene: the host draws the sweeps in the `spectrum`
+// control, and this extension only places it and turns the radio's knobs.
+import { host } from "@ham2k/extension-sdk"
+import type { PanelContent, PanelHook, PanelRadioSpectrum, PanelRadioState, PanelScene } from "@ham2k/extension-sdk"
+
+type Display = "both" | "pan" | "waterfall"
+
+/** A slider with its label beside it, kept together when the wrap breaks. */
+const labeled = (text: string, control: string) => ({
+  wrap: [{ control: `label-${text}` }, { control, width: 120 }],
+  spacing: 4,
+  crossAxisAlignment: "center" as const,
+})
+
+/** Where the receiver listens, from the tuned frequency, by mode. A sketch: the radio's real filter is not reported. */
+function passband(mode: string | null | undefined): [number, number] | null {
+  if (!mode) return null
+  if (mode.includes("LSB")) return [-2800, -100]
+  if (mode.includes("USB") || mode.startsWith("DATA") || mode === "FT8" || mode === "FT4") return [100, 2800]
+  if (mode.startsWith("CW")) return [-250, 250]
+  if (mode === "AM" || mode === "FM") return [-3000, 3000]
+  return null
+}
+
+const cyan = "#2EC5F0"
+
+/** Landmarks on 20 m: something to read, and to click to go to. */
+const landmarks: [string, number, "start" | "center" | "end"][] = [
+  ["PSK", 14070000, "center"],
+  ["FT8", 14074000, "start"],
+  ["FT4", 14080000, "center"],
+  ["SSTV", 14230000, "start"],
+  ["QRP", 14285000, "end"],
+  ["Maritime net", 14300000, "center"],
+]
+
+const spanLabel = (hz: number) => `±${hz >= 1000 ? `${hz / 1000} kHz` : `${hz} 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 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 },
+    strings: {
+      span: spectrum?.spanHz != null ? String(spectrum.spanHz) : "",
+      speed: spectrum?.speed ?? "",
+      display,
+      step,
+    },
+    layers: [
+      {
+        id: "readout",
+        x: 0,
+        y: 0,
+        width: 600,
+        height: 24,
+        text: { value: "hoverHz", scale: 0.001, decimals: 3, suffix: " kHz", size: 14 },
+      },
+    ],
+    controls: [
+      ...(knobs
+        ? [
+            {
+              id: "span",
+              label: "Span",
+              kind: "nativeDropdown" as const,
+              value: "span",
+              event: "span",
+              options: spectrum.spansHz.map((hz) => ({ label: spanLabel(hz), value: String(hz) })),
+            },
+            {
+              id: "ref",
+              label: "Reference level",
+              kind: "nativeSlider" as const,
+              value: "ref",
+              event: "ref",
+              min: spectrum.refMinDb,
+              max: spectrum.refMaxDb,
+              step: spectrum.refStepDb,
+            },
+            {
+              id: "speed",
+              label: "Speed",
+              kind: "nativeSegmented" as const,
+              value: "speed",
+              event: "speed",
+              options: spectrum.speeds.map((s) => ({ label: s, value: s })),
+            },
+          ]
+        : []),
+      { id: "floor", label: "Contrast", kind: "nativeSlider" as const, value: "floor", min: -30, max: 30, step: 1 },
+      { id: "average", label: "Averaging", kind: "nativeSlider" as const, value: "average", min: 0, max: 95, step: 5 },
+      { 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) => ({
+        id: `label-${text}`,
+        label: text,
+        kind: "nativeText" as const,
+      })),
+      {
+        id: "step",
+        label: "Tuning step",
+        kind: "nativeSegmented" as const,
+        value: "step",
+        event: "step",
+        options: ["10", "100", "500", "1000"].map((hz) => ({ label: Number(hz) >= 1000 ? `${Number(hz) / 1000} kHz` : `${hz} Hz`, value: hz })),
+      },
+      {
+        id: "display",
+        label: "Display",
+        kind: "nativeSegmented" as const,
+        value: "display",
+        event: "display",
+        options: (["both", "pan", "waterfall"] as const).map((d) => ({ label: d, value: d })),
+      },
+      {
+        id: "spectrum",
+        label: "Panadapter",
+        kind: "spectrum" as const,
+        event: "tune",
+        display,
+        floor: "floor",
+        average: "average",
+        fps: "fps",
+        waterfallSpeed: "rows",
+        backgroundColor: "#0B0E17",
+        traceColor: "#3FD0F0",
+        fillColor: "#CC3FD0F0",
+        fillColorBottom: "#B3104A5C",
+        gridColor: "#2A3446",
+        gridDashed: true,
+        scale: {
+          gap: 26,
+          background: "#151B26",
+          borderTop: { color: "#2A3446", width: 1 },
+          borderBottom: { color: "#2A3446", width: 1 },
+          labels: { color: "#8FA3B8", size: 12, offset: 8 },
+          ticks: { color: "#8FA3B8", width: 1, offset: 0, length: 5 },
+        },
+        // Noise to black, as the radio's own display does: the waterfall's window sits above the panadapter's.
+        waterfallFloor: 12,
+        waterfallRange: 50,
+        waterfallColors: ["#000000", "#00004A", "#0000FF", "#00C8FF", "#00FF60", "#FFFF00", "#FF2000"],
+        center: { pan: { color: cyan, width: 4 }, waterfall: { color: cyan, width: 4 } },
+        tuneStep: Number(step),
+        annotations: landmarks.map(([text, hz, align]) => ({
+          id: text,
+          text,
+          hz,
+          align,
+          borderColor: "#FFB020",
+          pointer: { size: 5 },
+          event: "goto",
+          offset: 6,
+          color: "#0B0E17",
+          background: "#E6FFB020",
+          size: 11,
+          weight: 600,
+        })),
+        overlays: [
+          ...(band ? [{ from: band[0], to: band[1], pan: { fill: "#262EC5F0", color: "#992EC5F0" } }] : []),
+          // The bottom of 20 m, and what lies outside it: scenery behind the trace, over the waterfall.
+          { at: 14000000, anchor: "absolute" as const, pan: { color: "#FF3030", width: 3 }, waterfall: { color: "#FF3030", width: 3 } },
+          { from: 13900000, to: 14000000, anchor: "absolute" as const, pan: { fill: "#33FF3030" }, waterfall: { fill: "#33FF3030" } },
+        ],
+        hoverHz: "hoverHz",
+        hoverDb: "hoverDb",
+      },
+    ],
+    layout: {
+      column: [
+        {
+          wrap: [
+            ...(knobs ? [{ control: "span" }, labeled("Ref", "ref"), { control: "speed" }] : []),
+            labeled("Contrast", "floor"),
+            labeled("Avg", "average"),
+            labeled("FPS", "fps"),
+            labeled("Rows", "rows"),
+            { control: "step" },
+            { control: "display" },
+          ],
+          spacing: 8,
+          runSpacing: 4,
+          padding: 4,
+        },
+        { control: "spectrum", flex: 1 },
+        { scene: true, height: 24 },
+      ],
+      crossAxisAlignment: "stretch",
+    },
+  }
+}
+
+export function createPanafall(): PanelHook {
+  const displays = new Map<string, Display>()
+  const steps = new Map<string, string>()
+  return {
+    async getPanels() {
+      return [{ key: "panafall", title: "Panadapter", icon: "waveform", multiple: true, on: ["tick:2"] }]
+    },
+    async render(args): Promise<PanelContent> {
+      const id = args.instanceId ?? ""
+      return { kind: "scene", scene: scene(await host.readRadio(), displays.get(id) ?? "both", steps.get(id) ?? "100") }
+    },
+    async onEvent(args) {
+      const { action, value, text } = args.event
+      if (action === "step") {
+        steps.set(args.instanceId ?? "", text ?? "100")
+        return { values: {} }
+      }
+      if (action === "display") {
+        displays.set(args.instanceId ?? "", (text as Display) ?? "both")
+        return { values: {} }
+      }
+      const radio = await host.readRadio()
+      if (!radio?.id) return { values: {} }
+      if ((action === "tune" || action === "goto") && typeof value === "number") {
+        // Already on the step: the host snapped it.
+        await host.setRadio({ id: radio.id, frequencyHz: Math.round(value) })
+      } else if (action === "span" && text) {
+        await host.setRadioSpectrum({ id: radio.id, spanHz: Number(text) })
+      } else if (action === "ref" && typeof value === "number") {
+        await host.setRadioSpectrum({ id: radio.id, refLevelDb: value })
+      } else if (action === "speed" && text) {
+        await host.setRadioSpectrum({ id: radio.id, speed: text as "slow" | "mid" | "fast" })
+      }
+      return { values: {} }
+    },
+  }
+}