@ham2k/extension-sdk 0.12.2 → 0.12.6

package/dist/dxcc.js

@@ -1,16 +1,22 @@
 import { parseCallsign } from "@ham2k/lib-callsigns";
-import { annotateFromCountryFile, useBuiltinCountryFile } from "@ham2k/lib-country-files";
+import { annotateFromCountryFile, BIGCTY, useBuiltinCountryFile } from "@ham2k/lib-country-files";
 import { DXCC_BY_CODE } from "@ham2k/lib-dxcc-data";
 useBuiltinCountryFile();
 function annotateCallAgainstCountryFile(call, options) {
   const annotated = annotateFromCountryFile(parseCallsign(call), options);
-  return annotated.tz ? { ...annotated, tz: ordinarySignTz(annotated.tz) } : annotated;
+  if (!WEST_POSITIVE) return annotated;
+  return {
+    ...annotated,
+    ...typeof annotated.lon === "number" ? { lon: 0 - annotated.lon } : {},
+    ...annotated.tz ? { tz: flippedTz(annotated.tz) } : {}
+  };
 }
-function ordinarySignTz(tz) {
+const WEST_POSITIVE = (BIGCTY.entities.K?.lon ?? 0) > 0;
+function flippedTz(tz) {
   const match = /^GMT([+-]?\d+(?:\.\d+)?)$/.exec(tz);
   if (!match) return tz;
-  const offset = -Number(match[1]);
-  return offset > 0 ? `GMT+${offset}` : `GMT${offset === 0 ? 0 : offset}`;
+  const offset = 0 - Number(match[1]);
+  return offset > 0 ? `GMT+${offset}` : `GMT${offset}`;
 }
 function entityPrefixForCall(call) {
   if (!call) return void 0;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.2
+// @ham2k/extension-sdk 0.12.6
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -97,11 +97,193 @@ export interface PanelSceneLayer {
  * - `nativeSwitch`, `nativeCheckbox`: a number, 1 or 0. Shows `label` beside it.
  * - `nativeChip`: with `value`, a toggle (1 or 0); without, an action that sends `activate`.
  * - `nativeText`: shows `label`, or its bound value. Sends nothing.
+ * - `spectrum`: the radio's panadapter and waterfall, drawn by the host from sweeps that never
+ *   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`.
  *
  * `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";
-export interface PanelSceneControl {
+export type PanelSceneControlKind = "button" | "slider" | "knob" | "nativeButton" | "nativeSlider" | "nativeTextField" | "nativeDropdown" | "nativeSwitch" | "nativeCheckbox" | "nativeRadio" | "nativeSegmented" | "nativeChip" | "nativeText" | "spectrum";
+/** 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;
+/**
+ * A `spectrum` control's display. All of it happens on the host after the sweep arrives, so it
+ * means the same on every radio; the radio's own scope (span, reference level, sweep speed) is
+ * `host.setRadioSpectrum`'s. Colors are `#RRGGBB`, or `#AARRGGBB` with transparency. Defaults
+ * follow the app's theme.
+ */
+export interface PanelSceneSpectrum {
+	/** A radio's id from `listRadios`. Omitted, the designated radio. */
+	radio?: string;
+	/** Default `both`. */
+	display?: "both" | "pan" | "waterfall";
+	/**
+	 * Which way the waterfall moves; the panadapter sits on the side it comes from. Frequency rises
+	 * left to right for `down` (the default) and `up`, bottom to top for `right` and `left`. Text
+	 * stays upright; offsets and `corner`s are measured as if flowing down.
+	 */
+	flow?: "down" | "up" | "right" | "left";
+	/** The panadapter's share of the height with `both`, 0.1–0.9. Default 0.4. */
+	split?: number;
+	/** dB added to the radio's own floor. */
+	floor?: PanelSceneSpectrumNumber;
+	/** The panadapter's height in dB. Omitted, the radio's. */
+	range?: PanelSceneSpectrumNumber;
+	/** Written as the pointer moves: the frequency and level under it. */
+	hoverHz?: string;
+	hoverDb?: string;
+	/** 0–99: the share of the trace each sweep keeps from the last. Default 40. The waterfall stays raw. */
+	average?: PanelSceneSpectrumNumber;
+	/** The most times a second the panadapter redraws, 1–60. Default 15. The waterfall keeps its own pace. */
+	fps?: PanelSceneSpectrumNumber;
+	/** Waterfall rows a second, 0.1–60; each row keeps the loudest reading since the last. Omitted, one per sweep. */
+	waterfallSpeed?: PanelSceneSpectrumNumber;
+	/** The waterfall's own dB window, like `floor` and `range`. Omitted, the panadapter's. */
+	waterfallFloor?: PanelSceneSpectrumNumber;
+	waterfallRange?: PanelSceneSpectrumNumber;
+	/** Default `classic`. */
+	palette?: "classic" | "gray" | "heat";
+	/** 2 to 8 stops, lowest level first, in place of `palette`. */
+	waterfallColors?: string[];
+	traceColor?: string;
+	/** 0.25–8. Default 1. */
+	traceWidth?: PanelSceneSpectrumNumber;
+	/** Under the trace. With `fillColorBottom`, a gradient from the top of the panadapter to its bottom. */
+	fillColor?: string;
+	fillColorBottom?: string;
+	backgroundColor?: string;
+	/** The panadapter's dB and frequency lines. */
+	gridColor?: string;
+	/** The frequency lines carried down through the waterfall. Omitted, none. */
+	waterfallGridColor?: string;
+	/** A click tunes to the nearest multiple of this many Hz. Omitted, wherever it lands. */
+	tuneStep?: PanelSceneSpectrumNumber;
+	/** Dashes the panadapter's grid lines. */
+	gridDashed?: boolean;
+	/** The gap between the panadapter and the waterfall, with frequency labels and ticks. `true` takes the defaults. */
+	scale?: boolean | PanelSceneSpectrumScale;
+	/** The tuned-frequency line, styled per part; a part it leaves out has none. Omitted, the theme's on both. */
+	center?: {
+		pan?: PanelSceneSpectrumStyle;
+		waterfall?: PanelSceneSpectrumStyle;
+	};
+	/** Up to 16 lines and areas at Hz offsets — a passband, a CW offset. */
+	overlays?: PanelSceneSpectrumOverlay[];
+	/** Up to 64 pieces of text at frequencies — a spot, a net, a beacon. */
+	annotations?: PanelSceneSpectrumAnnotation[];
+}
+/**
+ * The gap sits between the panadapter and the waterfall — above the waterfall with no panadapter,
+ * below the panadapter with no waterfall. Labels and ticks are drawn over the whole control, so an
+ * `offset` can place them anywhere: it is pixels from the base of the panadapter (the top of the
+ * waterfall where there is none), negative rising into the panadapter.
+ */
+export interface PanelSceneSpectrumScale {
+	/** Pixels, 0–200. Default 20. */
+	gap?: PanelSceneSpectrumNumber;
+	background?: string;
+	borderTop?: {
+		color?: string;
+		width?: PanelSceneSpectrumNumber;
+	};
+	borderBottom?: {
+		color?: string;
+		width?: PanelSceneSpectrumNumber;
+	};
+	/** On by default; `false` hides them. */
+	labels?: boolean | {
+		/** Hz between labels. Omitted, the gridlines' step. */
+		interval?: PanelSceneSpectrumNumber;
+		fontFamily?: string;
+		size?: PanelSceneSpectrumNumber;
+		/** 100–900. */
+		weight?: PanelSceneSpectrumNumber;
+		italic?: boolean;
+		color?: string;
+		/** To the top of the text. Omitted, centered in the gap. */
+		offset?: PanelSceneSpectrumNumber;
+	};
+	/** Off by default. */
+	ticks?: boolean | {
+		/** Hz between ticks. Omitted, the labels'. */
+		interval?: PanelSceneSpectrumNumber;
+		color?: string;
+		width?: PanelSceneSpectrumNumber;
+		/** To the top of the tick. Default 0. */
+		offset?: PanelSceneSpectrumNumber;
+		/** Default 4. */
+		length?: PanelSceneSpectrumNumber;
+	};
+}
+/**
+ * Text at a frequency, drawn by the host. With an `event`, a click sends `activate` with the
+ * frequency as `value` and this `id` as `annotation`, and does not tune; without one, a click
+ * on it tunes like anywhere else.
+ */
+export interface PanelSceneSpectrumAnnotation {
+	/** Unique within the control. */
+	id: string;
+	/** At most 256 characters. */
+	text: string;
+	/** A frequency, or an offset from the tuned frequency or the sweep's middle with `anchor`. */
+	hz: PanelSceneSpectrumNumber;
+	/** Default `absolute`. */
+	anchor?: "vfo" | "center" | "absolute";
+	/** Default `pan`. */
+	part?: "pan" | "waterfall";
+	/** Pixels from the panadapter's bottom up to the text's, or from the waterfall's top down to the text's. Default 4. */
+	offset?: PanelSceneSpectrumNumber;
+	/** Which end of the text sits at `hz`. Default `center`. */
+	align?: "start" | "center" | "end";
+	/**
+	 * The point the box makes at `hz`: a drawn-out corner for `start`/`end`, a notch for `center`.
+	 * With the default `corner`, its tip sits at `offset`; turned the other way, the box's edge
+	 * does. Shown by default (size 4, pointing toward the panadapter's bottom
+	 * or the waterfall's top); `false` or `show: false` hides it.
+	 */
+	pointer?: boolean | {
+		show?: boolean;
+		size?: PanelSceneSpectrumNumber;
+		corner?: "top" | "bottom";
+	};
+	fontFamily?: string;
+	size?: PanelSceneSpectrumNumber;
+	weight?: PanelSceneSpectrumNumber;
+	italic?: boolean;
+	color?: string;
+	background?: string;
+	borderColor?: string;
+	borderWidth?: PanelSceneSpectrumNumber;
+	/** Default 2. */
+	padding?: PanelSceneSpectrumNumber;
+	/** Default 2. */
+	radius?: PanelSceneSpectrumNumber;
+	event?: string;
+}
+/** `color` and `width` draw a line, or an area's edges; `fill` fills an area. */
+export interface PanelSceneSpectrumStyle {
+	color?: string;
+	width?: PanelSceneSpectrumNumber;
+	fill?: string;
+}
+/**
+ * A line at `at`, or an area between `from` and `to`, in Hz from the tuned frequency — from the
+ * middle of the sweep with `anchor: "center"` (a Flex's panadapter is not centered on its slice),
+ * or as frequencies with `anchor: "absolute"` (a band edge, a segment). On the panadapter an area
+ * draws behind the trace and a line in front of it unless `behind` — which absolute ones default to.
+ * On the waterfall all of it draws over the rows. A part with no style is not drawn on.
+ */
+export interface PanelSceneSpectrumOverlay {
+	at?: PanelSceneSpectrumNumber;
+	from?: PanelSceneSpectrumNumber;
+	to?: PanelSceneSpectrumNumber;
+	anchor?: "vfo" | "center" | "absolute";
+	behind?: boolean;
+	pan?: PanelSceneSpectrumStyle;
+	waterfall?: PanelSceneSpectrumStyle;
+}
+export interface PanelSceneControl extends PanelSceneSpectrum {
 	id: string;
 	label: string;
 	kind: PanelSceneControlKind;
@@ -177,6 +359,8 @@ export interface PanelSceneEvent {
 	value?: number;
 	/** The control's string, for a control bound to `strings`. */
 	text?: string;
+	/** The `id` of the spectrum annotation clicked; `value` is its frequency. */
+	annotation?: string;
 }
 /** Patch only named scene values and strings. The host ignores stale responses. */
 export interface PanelSceneEventResult {
@@ -372,6 +556,7 @@ export interface HookContext {
 	getOperation?(uuid: string): Promise<Record<string, JSONValue> | null>;
 	getQsos?(operationUuid: string): Promise<Record<string, JSONValue>[] | null>;
 	getSpotsForCall?(call: string, maxAgeMinutes?: number): Promise<Spot[]>;
+	getSpots?(options?: GetSpotsOptions): Promise<BoardSpot[]>;
 	getHistoryForCall?(call: string, options?: HistoryForCallOptions): Promise<Record<string, JSONValue>[]>;
 }
 export interface HistoryForCallOptions {
@@ -440,6 +625,24 @@ export interface Spot {
 		sourceInfo?: Record<string, JSONValue>;
 	};
 }
+export interface GetSpotsOptions {
+	filter?: "user" | "all";
+	maxAgeMinutes?: number;
+	band?: string | string[];
+	mode?: string | string[];
+	source?: string | string[];
+	annotate?: boolean;
+	operationUuid?: string;
+}
+export interface BoardSpot extends Spot {
+	hookKey?: string;
+	annotations?: SpotAnnotations;
+}
+export interface SpotAnnotations {
+	worked: boolean;
+	isSelf: boolean;
+	notices: string[];
+}
 export interface SpotEligibility {
 	enabled: boolean;
 	icon?: string;
@@ -492,6 +695,7 @@ export interface Ref {
 	program?: string;
 	activationRadiusInMeters?: number;
 	activationRadiusInFeet?: number;
+	largeArea?: boolean;
 	retired?: boolean;
 	for?: "operation" | "qso";
 	[key: string]: JSONValue | undefined;
@@ -1544,6 +1748,40 @@ export interface PanelRadioState {
 	transmitting: boolean | null;
 	meters: Partial<Record<"signalDbm" | "powerOut" | "swr" | "alc" | "supplyVolts", number>>;
 	canTune: boolean;
+	/**
+	 * 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.
+	 */
+	spectrum?: PanelRadioSpectrum | null;
+}
+export type PanelRadioSpectrumSpeed = "slow" | "mid" | "fast";
+export interface PanelRadioSpectrum {
+	/** Why nothing can be drawn, in the operator's language, or null. */
+	problem: string | null;
+	mode: "center" | "fixed" | null;
+	/** Half the width shown while centered — what the radio's menu shows as ±. */
+	spanHz: number | null;
+	/** The edges while fixed. */
+	lowHz: number | null;
+	highHz: number | null;
+	refLevelDb: number | null;
+	speed: PanelRadioSpectrumSpeed | null;
+	/** What `setRadioSpectrum` accepts. A span between two is snapped to the nearer. */
+	spansHz: number[];
+	refMinDb: number;
+	refMaxDb: number;
+	refStepDb: number;
+	modes: ("center" | "fixed")[];
+	speeds: PanelRadioSpectrumSpeed[];
+}
+export interface PanelRadioSpectrumSet {
+	/** Reject if this identity no longer matches the selected radio. */
+	id: string;
+	selection?: string;
+	mode?: "center" | "fixed";
+	spanHz?: number;
+	refLevelDb?: number;
+	speed?: PanelRadioSpectrumSpeed;
 }
 export interface PanelRadioTune {
 	/** Reject if this identity no longer matches the selected radio. */
@@ -1556,7 +1794,8 @@ export interface PanelRadioTune {
 export interface PanelRadioTuneResult {
 	/** Accepted by the host; confirmation still comes from reported state. */
 	accepted: boolean;
-	reason?: "changed" | "disconnected" | "transmitting" | "invalid";
+	/** `stopped`: a scope change while no display has the scope running — nothing was sent. */
+	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped";
 	state: PanelRadioState | null;
 }
 export interface PanelRenderArgs {
@@ -1650,7 +1889,8 @@ export interface ParsedCallsign {
 	indicators?: string[];
 	ssid?: string;
 }
-export type CombinedCallInfo = ParsedCallsign & {
+export type CombinedCallInfo = Omit<ParsedCallsign, "call"> & {
+	call?: string;
 	isoPrefix?: string;
 	dxccCode?: number;
 	regionCode?: string;
@@ -1998,6 +2238,8 @@ export declare const host: {
 		connected: boolean;
 	}): Promise<PanelRadioTuneResult>;
 	tuneRadio(args: PanelRadioTune): Promise<PanelRadioTuneResult>;
+	/** 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>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;
 	kvGet(key: string): Promise<JSONValue | null>;

package/dist/index.js

@@ -172,6 +172,10 @@ const host = {
   async tuneRadio(args) {
     return await hostCallFn()("tuneRadio", { ...args });
   },
+  /** Changes the radio's scope. Needs `requiresRadioWrite` and extension API 6; the result's state reports what the radio took. */
+  async setRadioSpectrum(args) {
+    return await hostCallFn()("setRadioSpectrum", { ...args });
+  },
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },

package/docs/distribution.md

@@ -262,7 +262,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 5)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 6)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own

package/docs/hooks.md

@@ -70,6 +70,31 @@ 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.
+* `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
+  default it answers what the operator's Spots Panel shows: their sources,
+  enabled bands, band and mode filters (an "auto" filter follows the radio),
+  age and continents, merged and ordered as that panel does — so one spot
+  can stand for several stations, its `their.call` comma-joined
+  (`'K1ABC,W2XYZ'`). `filter: 'all'`
+  starts instead from every held spot, one per source report, newest first.
+  Either way `maxAgeMinutes`, `band`, `mode` (a mode, or `SSB`/`Phone`/`CW`/
+  `Digital` for a family) and `source` (a spot source's hook key, carried on
+  each spot as `hookKey`) narrow it further. Spots come back with
+  `annotations` — `worked`, `isSelf`, `notices`, judged the way the Spots
+  Panel strikes and accents its rows — whenever there is an operation to judge
+  them against: `operationUuid`, or the `operation` the calling hook was
+  handed, so a panel's render gets them without asking. The verdicts are the
+  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.
+  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
+  has no operator: its `'user'` board is every spot handed to it, never
+  annotated.
 * `getHistoryForCall?(call, options?)` — the most recent non-deleted contacts
   logged with `call` (five unless `limit` says otherwise, never more than
   50), across every operation, newest first, as raw QSON — the one log read
@@ -247,14 +272,17 @@ interface LookupServiceHook {
   carried one (`preferStationValues`) — only while the guess's scope is
   `qth`, since on a portable or prefixed contact a source describes the
   home QTH. `tz` is a UTC offset with its ordinary sign, `"GMT-5"` being
-  five hours behind; the SDK's `annotateCallAgainstCountryFile` flips the
-  country file's west-positive offsets to match.
+  five hours behind. lib-country-files states it that way from 1.1; the
+  SDK's `annotateCallAgainstCountryFile` answers with the ordinary signs
+  whichever version the app ships, flipping an older one's west-positive
+  `tz` and `lon`.
 - **`locSource: 'prefix'` is reserved**, and a `lat`/`lon` merged under it is
   never read as a coordinate (`locationFromGuess`, halo_core). It marks
-  lib-country-files' DXCC entity centroid, whose longitude follows cty.dat's
-  west-positive convention — the opposite of every other coordinate here. A
-  source reporting a real position must leave `locSource` unset or name
-  itself; tagging one `'prefix'` gets its coordinate discarded.
+  lib-country-files' DXCC entity centroid, which synced records carry signed
+  either way — west-positive from versions before 1.1 — with nothing to tell
+  the two apart. A source reporting a real position must leave `locSource`
+  unset or name itself; tagging one `'prefix'` gets its coordinate
+  discarded.
 
 Implemented by: `lookups` (key `core`). The merge algorithm itself
 (`mergeLookupIntoGuess`/`runLookupPipeline` in
@@ -441,7 +469,7 @@ interface RefHandlerHook {
   geojsonUrlForRef?(args: { ref: Ref }, ctx): Promise<RefGeojson | null>
 }
 // Ref: {type, ref?, name?, label?, shortLabel?, grid?, lat?, lon?, location?, program?,
-//       activationRadiusInMeters?, activationRadiusInFeet?, ...}
+//       activationRadiusInMeters?, activationRadiusInFeet?, largeArea?, ...}
 // TitleSuggestion: {title?, for?, at?, subtitle?, priority?} — a fragment of
 // the operation's title/subtitle sentence (ham2k/halo-dist#174). Only
 // return one for the ref type that means "this operation is happening AT/FOR
@@ -558,6 +586,15 @@ and is not offered for an outline report. Programs built on the SDK's
 `referenceActivity` factory get this from one `activationRadius` config line —
 a value, or a function of the list row for rules that vary.
 
+**A reference too large to stand for one place says so.** An operation with
+no location of its own takes the first of its references that has one
+(docs/design/locations.md), which is right for a summit or a park a few
+kilometres across and wrong for a 3,500 km trail. A reference whose point is
+representative rather than where an activator stands — POTA's parks that span
+several states — carries `largeArea: true`, and that reference never places
+the operation. Nothing else reads it: the maps draw it, and the nearby search
+finds it, exactly as before.
+
 `suggestOperationTitle` lets an activity build a natural-language operation
 title/subtitle from its refs — "at Yosemite NP" (POTA), "for Field Day"
 (contest programs, when ported) — mirroring app-polo's
@@ -1647,6 +1684,7 @@ the extension. `value` names what it shows and sets.
 | `nativeSwitch`, `nativeCheckbox` | number, 1 or 0 | `commit` | — (shows `label` beside it) |
 | `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 |
 
 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
@@ -1758,6 +1796,38 @@ export const spotter: PanelHook = {
 }
 ```
 
+#### 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
+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:
+
+- `radio` (an id from `listRadios`; omitted, the designated radio), `display`
+  (`both`, `pan`, `waterfall`), `split`, and `flow` — which way the waterfall
+  moves (`down`, `up`, `right`, `left`), the panadapter on the side it comes
+  from.
+- `floor`, `range`, `average` (0–99, default 40), `fps` (default 15),
+  `waterfallSpeed`, `waterfallFloor`, `waterfallRange`: numbers, or the names
+  of scene values the control reads on every sweep.
+- Colors (`#RRGGBB` or `#AARRGGBB`): `palette` or `waterfallColors`,
+  `traceColor`/`traceWidth`, `fillColor`/`fillColorBottom`, `backgroundColor`,
+  `gridColor`/`gridDashed`, `waterfallGridColor`.
+- `center`: the tuned-frequency line, styled per part.
+- `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`.
+- `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.
+- `hoverHz`, `hoverDb`: scene values the pointer writes, for a text layer.
+- `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
@@ -1773,8 +1843,8 @@ 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()` and
-`host.setRadioConnection()`, and implies read, since a command answers with the
+`"requiresRadioWrite": true` allows `host.tuneRadio()`,
+`host.setRadioConnection()` and `host.setRadioSpectrum()`, 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
@@ -1805,7 +1875,17 @@ reported state confirms it. Drivers retain their own protocol/echo handling.
 `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
-the hardware's mains power or initiate transmission. The reference panel samples
+the hardware's mains power or initiate transmission.
+On a host with the panadapter enabled, `readRadio()` carries `spectrum`: 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
+cannot run, in the operator's language. The settings are known only while a
+`spectrum` control has the scope running, and null otherwise.
+`host.setRadioSpectrum({id, selection?, mode?, spanHz?, refLevelDb?, speed?})`
+changes them; a span between two the radio offers is snapped to the nearer. It
+answers `stopped` when no control is running the scope: nothing is queued for
+later. The reference panel samples
 state once per second while visible; knob motion and LCD digit updates run locally,
 and tuning is sent continuously during dragging, paced by the CAT adapter. The
 main readout follows the requested value immediately; confirmation status distinguishes pending requests from the radio
@@ -1920,7 +2000,9 @@ its first render.
 
 The whole log is deliberately absent from `render`'s args. A panel that
 needs it calls `ctx.getQsos(operation.uuid)` — right for a `'qsoLogged'`
-render, wrong for a per-keystroke one.
+render, wrong for a per-keystroke one. Spots are absent for the same reason:
+a panel showing them declares `'spots'` and calls `ctx.getSpots()`, which
+answers the operator's own filtered board, judged against this operation.
 
 ## ✅ `settingsPanel` — extension settings forms
 

package/package.json

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