@ham2k/extension-sdk 0.12.0 → 0.12.5

package/dist/dxcc.js

@@ -1,9 +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) {
-  return annotateFromCountryFile(parseCallsign(call), options);
+  const annotated = annotateFromCountryFile(parseCallsign(call), options);
+  if (!WEST_POSITIVE) return annotated;
+  return {
+    ...annotated,
+    ...typeof annotated.lon === "number" ? { lon: 0 - annotated.lon } : {},
+    ...annotated.tz ? { tz: flippedTz(annotated.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 = 0 - Number(match[1]);
+  return offset > 0 ? `GMT+${offset}` : `GMT${offset}`;
 }
 function entityPrefixForCall(call) {
   if (!call) return void 0;

package/dist/exportSettings.js

@@ -76,6 +76,7 @@ function resolveExportSettings(definition, global = {}, overrides = {}) {
   }
   return resolved;
 }
+const PRIVATE_STATION_FIELDS = ["name", "city", "street", "postal", "email", "qslVia", "url", "notes", "lat", "lon", "multiIdentifier"];
 function exportQso(qso, settings) {
   const copy = { ...qso };
   for (const side of ["their", "our"]) {
@@ -83,11 +84,11 @@ function exportQso(qso, settings) {
       const station = { ...copy[side] };
       if (settings.includeLookupData === false) delete station.guess;
       if (settings.includePrivateData === false) {
-        for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete station[key];
+        for (const key of PRIVATE_STATION_FIELDS) delete station[key];
         if (typeof station.grid === "string") station.grid = station.grid.slice(0, 6);
         if (station.guess && typeof station.guess === "object") {
           const guess = { ...station.guess };
-          for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete guess[key];
+          for (const key of PRIVATE_STATION_FIELDS) delete guess[key];
           if (typeof guess.grid === "string") guess.grid = guess.grid.slice(0, 6);
           station.guess = guess;
         }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.0
+// @ham2k/extension-sdk 0.12.5
 /** 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 {
@@ -492,6 +676,7 @@ export interface Ref {
 	program?: string;
 	activationRadiusInMeters?: number;
 	activationRadiusInFeet?: number;
+	largeArea?: boolean;
 	retired?: boolean;
 	for?: "operation" | "qso";
 	[key: string]: JSONValue | undefined;
@@ -1544,6 +1729,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 +1775,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 +1870,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 +2219,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

@@ -209,9 +209,11 @@ interface LookupServiceHook {
 **locationScope merge rules** (`CallInfo.locationScope`, ranked
 `qth < prefixed < portable`, most general to most specific):
 - A result whose `locationScope` is strictly more specific than the current
-  guess's clears all location fields (`locSource, lat, lon, grid, city,
-  state, county, country`) before merging the result in, and the guess
-  adopts the more specific scope.
+  guess's clears all location fields (`locSource, lat, lon, grid, street,
+  city, state, postal, county, country`) before merging the result in, and
+  the guess adopts the more specific scope. `street` and `postal` are the
+  mailing address's own lines, grouped with the town they complete so an
+  address never puts one source's street on another source's town.
 - Otherwise, priority order applies as usual: a field already present in the
   guess is never overwritten by a later (lower-priority) result. A
   location field additionally requires the result's own scope to be at
@@ -231,19 +233,31 @@ interface LookupServiceHook {
 - Grid/lat-lon reconciliation, scoped to fields the result actually set:
   grid-only → lat/lon computed from the grid; lat/lon-only → a 6-digit grid
   computed from them; both given → taken verbatim. Setting grid/lat/lon
-  clears city/state/country/county unless the *same* result also supplies
-  them. The converse clause — a town write clearing grid/lat/lon — can only
+  clears street/city/state/postal/country/county unless the *same* result
+  also supplies them. The converse clause — a town write clearing grid/lat/lon — can only
   sweep a leftover half lat/lon pair: the group rule above blocks a town
   from landing at all where a full pin already stands.
 - `notes`/`history` are per-`CallInfoLookup` fields, not part of the merged
   `guess` — they simply accumulate, unconditionally, in the returned
   `lookups[]` array.
+- **`cqZone`, `ituZone` and `tz` are the exception to first-answer-wins.** The
+  pre-step can only answer them for a whole entity or call area (a W6 call
+  reads CQ zone 3 wherever the station lives), so once every hook has run,
+  a value the pre-step still holds goes to the first hook result that
+  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. 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
@@ -430,7 +444,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
@@ -518,6 +532,18 @@ SOTLAS's `az.sotl.as`, used with the operators' permission) and `pota` (both
 types, via `services.ham2k.net/lookups/outlines/pota/`, which links parks to
 OpenStreetMap shapes; a park not yet linked answers 404).
 
+**POTA is the one exception, and the core makes it, not the hook.** For a
+POTA suggestion's dashed outline the core skips `geojsonUrlForRef` and reads
+`services.ham2k.net`'s grid bundles instead — every outlined park touching a
+Maidenhead cell, simplified and clipped to it, one cached document per cell
+(500 m blocks below GL zoom 9, 10 m squares from 9). A long trail's whole
+outline runs to megabytes; its pieces in a cell, to kilobytes. The same
+bundles add to `suggest`'s answers the parks whose outline, not just whose
+point, is near: within 5 km for the nearby list, touching the view for a pan
+close in (from about GL zoom 10; see `suggest` below). An open card's POTA suggestion is drawn solid from the
+same pieces; the operation's own references still come from
+`geojsonUrlForRef`.
+
 **An activation radius is a circle, drawn the same way.** A reference that
 carries `activationRadiusInMeters` or `activationRadiusInFeet` — how far from
 its point the program lets an activator be — is circled on both maps, in the
@@ -535,6 +561,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
@@ -665,7 +700,12 @@ an app that sends `bounds` answers that call, so an extension that calls it
 only then runs on older apps unchanged, and one that predates `bounds` answers
 with what is nearest the view's centre. Measure `distance` from the `location`
 given either way; the core re-measures a panned answer from the operation's own
-place before any card shows it. Called with no
+place before any card shows it. For POTA only, the core also adds the parks
+whose OUTLINE is near (from the grid bundles above) to the nearby list and to a
+pan, labelled by POTA's own `decorateRef`, and gives a park POTA already
+suggested the nearer of its point's and its outline's distance — so `pota`'s
+`suggest` keeps answering by point, and a trail whose point is a state away
+still reaches an operator standing on it. Called with no
 `searchTerm` for nearby suggestions, or with one for name/code search — an
 extension may honor either, both, or neither (returning `[]`). `scoped` is
 true when THIS extension alone was asked — the operator tapped its "Activity
@@ -1619,6 +1659,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
@@ -1730,6 +1771,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
@@ -1745,8 +1818,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
@@ -1777,7 +1850,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

package/package.json

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