@ham2k/extension-sdk 0.12.14 → 0.12.15

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.14
+// @ham2k/extension-sdk 0.12.15
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -21,6 +21,20 @@ export interface PanelScene {
 	radio?: {
 		node?: string;
 	};
+	/**
+	 * A scene longer than its pane along `axis` (default `y`), scrolled by the app itself — wheel,
+	 * trackpad and drag, a drag begun on a button included — with no call to the extension. Scaled
+	 * to fill the pane across, it runs on past it along the axis. The position, in scene units from
+	 * the start, is written to the scene value `value` as it scrolls; a render that changes that
+	 * value moves the view there, and one that leaves it alone leaves the operator's scroll alone.
+	 * `event`, when given, is sent as a `commit` with the position as `value` once scrolling comes
+	 * to rest. Layers and controls marked `fixed` stay put over the pane. No `layout`. Extension API 12.
+	 */
+	scroll?: {
+		axis?: "x" | "y";
+		value: string;
+		event?: string;
+	};
 }
 /** Host-fed values of a scene with `radio`: its meters, and `radio.transmitting` as 1 or 0. Reserved: a scene may not declare them. */
 export type PanelSceneRadioValue = "radio.signalDbm" | "radio.powerOut" | "radio.swr" | "radio.alc" | "radio.supplyVolts" | "radio.transmitting"
@@ -52,13 +66,28 @@ export interface PanelSceneLayer {
 	y: number;
 	width: number;
 	height: number;
-	/** Supply exactly one of svg or text. SVG must be self-contained. */
+	/** Supply exactly one of svg, text or icon. SVG must be self-contained. */
 	svg?: string;
+	/**
+	 * A named icon — MDI, or FontAwesome with `fa-` — drawn by the app to fit the layer, in `color`
+	 * (`#RRGGBB`) or the theme's. Extension API 12.
+	 */
+	icon?: {
+		name: string;
+		color?: string;
+	};
 	/**
 	 * Take the clicks that land on this layer. Off by default: layers are click-through, so
 	 * artwork painted over a control does not stop it working. On, it covers the controls under it.
 	 */
 	blocksPointer?: boolean;
+	/** In a scene with `scroll`: drawn over the pane where it is, in pane coordinates, not scrolled. Extension API 12. */
+	fixed?: boolean;
+	/**
+	 * While a `zoom` strip is dragged, scaled along the scroll about the pane's middle, rather than
+	 * moved there at its own size: for a background, or a line that runs the whole way. Extension API 12.
+	 */
+	stretch?: boolean;
 	/** Exactly one of literal/value. A value naming a string shows it as-is. Use text layers, not SVG <text>, for font support.
 	 * Size is unscaled; the host applies OS text scaling once. */
 	text?: {
@@ -121,10 +150,16 @@ export interface PanelSceneLayer {
  *   reach the extension. Needs `requiresRadioRead`; a host without the feature, or a radio
  *   without a scope, shows why instead. A click sends `commit` with the frequency as `value`.
  *   Takes no `value`; see `PanelSceneSpectrum` for the rest. Extension API 6: declare `"api": 6`.
+ * - `zoom`: a strip of a scene with `scroll`, drawn by nothing, where a drag along the scroll zooms
+ *   about the pane's middle — away from it in, toward it out, by the ratio of the distances. While
+ *   the drag lasts the app moves each layer and control to where the zoom puts its middle, at its
+ *   own size (a `stretch` layer scales instead), and on release sends `commit` with the factor as
+ *   `value`; `min` and `max` are the factors allowed. A tap on it still reaches what lies there,
+ *   and a drag elsewhere still scrolls. Needs `event`. Extension API 12.
  *
  * `label` is every control's accessible name. There are no tooltips.
  */
-export type PanelSceneControlKind = "button" | "slider" | "knob" | "nativeButton" | "nativeSlider" | "nativeTextField" | "nativeDropdown" | "nativeSwitch" | "nativeCheckbox" | "nativeRadio" | "nativeSegmented" | "nativeChip" | "nativeText" | "spectrum";
+export type PanelSceneControlKind = "button" | "slider" | "knob" | "nativeButton" | "nativeSlider" | "nativeTextField" | "nativeDropdown" | "nativeSwitch" | "nativeCheckbox" | "nativeRadio" | "nativeSegmented" | "nativeChip" | "nativeText" | "spectrum" | "zoom";
 /** A literal, or the name of a scene value — which a slider with no `event` retunes with no bridge call. */
 export type PanelSceneSpectrumNumber = number | string;
 /**
@@ -361,6 +396,18 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 	multi?: boolean;
 	/** Shown but inert: no clicks, drags, keys or screen-reader adjustments act on it. */
 	disabled?: boolean;
+	/** In a scene with `scroll`: placed over the pane, in pane coordinates, not scrolled. Needs a rect. Extension API 12. */
+	fixed?: boolean;
+	/**
+	 * A drawn control only (`button`, `slider`, `knob`): while the pointer is over it, the scene value
+	 * `value` reads `to`, set by the host with no call to the extension; leaving puts back the scene's
+	 * own value. Artwork bound to it lights up under the pointer — a spot's line with its call.
+	 * Survives renders while the pointer stays. Extension API 12.
+	 */
+	hoverSet?: {
+		value: string;
+		to: number;
+	};
 	/**
 	 * 0 to 1, fixed or bound like a layer's. At 0 the control is gone: it takes no clicks,
 	 * keyboard focus or screen-reader node. Anything between is only drawn fainter.
@@ -387,6 +434,17 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 	valueLabels?: string[];
 	/** Knobs use relative horizontal/upward dragging. Value per scene unit; default 1. */
 	sensitivity?: number;
+	/**
+	 * A knob only: a drag moves the value the other way — content held under the finger, scrolled
+	 * by dragging, rather than a dial turned. Scrolling is unchanged. Extension API 12.
+	 */
+	invertDrag?: boolean;
+	/**
+	 * A slider or knob only: it also takes the scrolls that land on drawn buttons over it — labels
+	 * drawn over a knob that scrolls the artwork. A native control, a `blocksPointer` layer or another
+	 * slider or knob in between keeps the scroll. Extension API 12.
+	 */
+	scrollThrough?: boolean;
 	/**
 	 * A knob's second axis: with `valueY`, horizontal scrolling, dragging and the left/right keys set
 	 * `value`, and vertical ones (and up/down) set `valueY` — sent as its own event, `eventY`, which a
@@ -687,8 +745,22 @@ export interface GetSpotsOptions {
 	annotate?: boolean;
 	operationUuid?: string;
 }
+export interface SuggestedQso {
+	their: {
+		call: string;
+	};
+	freq?: number;
+	band?: string;
+	mode?: string;
+	refs?: SpotRef[];
+}
 export interface BoardSpot extends Spot {
 	hookKey?: string;
+	display?: {
+		icon: string;
+		iconColor?: string;
+		emoji?: string;
+	};
 	annotations?: SpotAnnotations;
 }
 export interface SpotAnnotations {
@@ -1994,7 +2066,7 @@ export interface PanelRadioState {
 		endedAtMillis: number;
 	} | null;
 	/**
-	 * The radio's scope, on hosts with the panadapter enabled: absent there otherwise, and null
+	 * The radio's scope: absent on an app without a panadapter, and null
 	 * for a radio without one. The sweeps are never sent — a `spectrum` scene control draws them.
 	 */
 	spectrum?: PanelRadioSpectrum | null;
@@ -2614,6 +2686,20 @@ export declare const host: {
 	clusterPostSpot(args: ClusterPostSpotRequest): Promise<ClusterReply>;
 	/** Sends any one command line, in the operator's name. Needs `requiresClusterCommand` and extension API 10. */
 	clusterSend(command: string): Promise<ClusterReply>;
+	/**
+	 * Puts a station into the logging fields of the operation in front, as tapping its spot in the
+	 * Spots Panel does — call, frequency, band, mode and references; nothing else of `qso` is used.
+	 * With `operationUuid` (a panel's `operation.uuid`), only that operation's: `accepted` is false
+	 * when it is not the one in front, or none is open. It tunes the radio as a tap does, so it needs
+	 * `requiresRadioWrite`, and it is refused outside the extension's own panel `onEvent`. Extension
+	 * API 12.
+	 */
+	suggestQso(args: {
+		qso: SuggestedQso;
+		operationUuid?: string;
+	}): Promise<{
+		accepted: boolean;
+	}>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;
 	kvGet(key: string): Promise<JSONValue | null>;

package/dist/index.js

@@ -227,6 +227,17 @@ const host = {
   async clusterSend(command) {
     return await hostCallFn()("clusterSend", { command });
   },
+  /**
+   * Puts a station into the logging fields of the operation in front, as tapping its spot in the
+   * Spots Panel does — call, frequency, band, mode and references; nothing else of `qso` is used.
+   * With `operationUuid` (a panel's `operation.uuid`), only that operation's: `accepted` is false
+   * when it is not the one in front, or none is open. It tunes the radio as a tap does, so it needs
+   * `requiresRadioWrite`, and it is refused outside the extension's own panel `onEvent`. Extension
+   * API 12.
+   */
+  async suggestQso(args) {
+    return await hostCallFn()("suggestQso", { ...args });
+  },
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },

package/docs/distribution.md

@@ -540,6 +540,13 @@ catalog's own bundle links (`…/api/v1/extensions/<key>/versions/<version>/bund
 take this verified path when they arrive as a deep link; every other host
 takes the plain one above.
 
+An extension's screenshots — published beside its bundles, never inside them
+(the tools README says how) — show as a strip of thumbnails on its row in the
+operation sheet's activity search, on the consent screen of a catalog install,
+and in an installed extension's details; a tap opens them full size. The app
+loads them only from the catalog's own host: a listing naming any other is
+shown without them.
+
 ### Release tracks
 
 A catalog channel — `stable`, `unstable` or `bleeding` — says how finished a

package/docs/hooks.md

@@ -73,6 +73,17 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   reads above it is cheap enough for the lookup path; it resolves `[]`
   whenever the cache is cold or the host keeps no spots. Used by
   `spot-history` to pull a hunted park or summit into the QSO being logged.
+* `host.suggestQso({qso, operationUuid?})` (extension API 12) — puts a
+  station into the logging fields of the operation in front, as tapping its
+  spot in the Spots Panel does: `qso.their.call`, and `freq`, `band`, `mode`
+  and `refs` where given; nothing else of `qso` reaches the fields. With
+  `operationUuid` — a panel's own `operation.uuid` — only that operation's
+  fields, so a panel never fills a log the operator is not looking at.
+  Answers `{accepted}`, false when no such operation is open. It tunes the
+  radio as a tap does, so it needs `requiresRadioWrite`, and it is refused
+  except from inside the extension's own panel `onEvent`: it answers the
+  operator clicking something, never a timer or a render, which would
+  overwrite what they are typing.
 * `getSpots?(options?)` — the whole spots board the host already holds,
   for a panel showing spots its own way. Like `getSpotsForCall` it reads the
   cache and never fetches, and resolves `[]` while the cache is cold. By
@@ -92,7 +103,12 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   ones the app already holds for the operation open on screen, so the call
   never waits on a scorer; another operation's spots, and that one's until
   its first verdicts land, come back unannotated rather than guessed.
-  `annotate: false` returns the spots as their sources gave them.
+  From extension API 12 each also carries `display` — `icon` (an MDI or
+  `fa-` name), `iconColor` (`#RRGGBB`, where the activity declares one) and
+  `emoji` (the call's note emoji, where it has one): what the Spots Panel's row
+  shows beside the call, the activity's icon and tint for the spot's first
+  reference, else the source's own icon. `annotate: false` returns the spots
+  as their sources gave them.
   A panel's `'spots'` trigger fires whenever this answer may have moved: a
   refresh, new verdicts, the operator's spot filters or bands, or the radio's
   band or mode. A malformed or unknown option rejects the call. The CLI host
@@ -287,6 +303,14 @@ interface LookupServiceHook {
   unset or name itself; tagging one `'prefix'` gets its coordinate
   discarded.
 
+- **A guess field of the wrong type is dropped.** The bridge enforces none of
+  `CallInfo`'s declared types, so the app normalizes the answer
+  (`normalizeLookupResult`, halo_core) before anything reads it: a field its
+  readers cannot use — a numeric `continent`, a boolean `emoji` — is dropped
+  and reported once by name, and the rest of the guess is still used. A
+  numeric string where a number is read (`cqZone: '05'`) is taken as that
+  number.
+
 Implemented by: `lookups` (key `core`). The merge algorithm itself
 (`mergeLookupIntoGuess`/`runLookupPipeline` in
 `extensions/core/lookups/src/mergeLookup.ts`) is a pure, host-independent
@@ -1876,9 +1900,10 @@ drawing part of it.
 | `width`, `height` | The artwork's viewBox, in scene units. Size it to `environment.width`/`height` and a scene unit is a logical pixel. |
 | `values` | `{name: number}`: what bindings, numeric text and numeric controls read. At most 256. |
 | `strings` | `{name: string}`: what text fields and choices hold. At most 256, each up to 4096 characters. A name is in `values` or `strings`, never both. |
-| `layers` | Painted in order, each over the ones before: `svg` artwork or `text`. At most 128, and 1 MiB of artwork and text in all. |
-| `controls` | At most 64. Drawn or native; see below. |
+| `layers` | Painted in order, each over the ones before: `svg` artwork, `text`, or an `icon`. At most 512 (128 before extension API 12), and 1 MiB of artwork and text in all. |
+| `controls` | At most 256 (64 before extension API 12). Drawn or native; see below. |
 | `layout` | Optional. Where rect-less native controls and the artwork go; omitted, the artwork fills the pane. |
+| `scroll` | Optional, `{axis?, value, event?}` (extension API 12): a scene longer than its pane along `axis` (`y` by default), scrolled natively by the app — wheel, trackpad and drag, a drag begun on a button included — with no call to the extension. It fills the pane across and runs on past it. The position, in scene units, is written to the scene value `value`; a render that changes that value moves the view there, one that leaves it alone leaves the operator's scroll alone. `event` is sent as a `commit`, the position as `value`, once a scroll comes to rest. Layers and controls with `fixed: true` stay put over the pane, in pane coordinates. A drag along the scroll on a slider or knob that scrolls with the content is the scroll's: make one that must be dragged `fixed`. Not with `layout`. |
 | `radio` | Optional, `{node?}`: the host feeds that radio's live readings into the reserved `radio.*` values. `node` is an id from `listRadios`; omitted, the logging radio. See *Radio values*. |
 
 **Controls.** Every control has an `id` and a `label`, which is its accessible
@@ -1889,8 +1914,8 @@ the extension. `value` names what it shows and sets.
 | Kind | Binds to | Sends | Also takes |
 |---|---|---|---|
 | `button` | — | `activate` | `menu` |
-| `slider` | number | `commit` | `min`, `max`, `step`, `discrete`, `hover`, `valueLabels`, `continuous` |
-| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `valueLabels`, `continuous`, `menu`, a second axis (`valueY`, `eventY`, `minY`, `maxY`, `stepY`, `sensitivityY`) |
+| `slider` | number | `commit` | `min`, `max`, `step`, `discrete`, `hover`, `valueLabels`, `continuous`, `scrollThrough` |
+| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `invertDrag`, `scrollThrough`, `valueLabels`, `continuous`, `menu`, a second axis (`valueY`, `eventY`, `minY`, `maxY`, `stepY`, `sensitivityY`) |
 | `nativeButton` | — | `activate` | `variant` (`filled`, `tonal`, `outlined`, `text`), `icon`, `menu`; needs `event` or `menu` |
 | `nativeSlider` | number | `commit` | `min`, `max`, `step`, `valueLabels`, `continuous` |
 | `nativeTextField` | string | `commit` on Enter, or on leaving it after typing | `placeholder`, `continuous` |
@@ -1901,6 +1926,7 @@ the extension. `value` names what it shows and sets.
 | `nativeChip` | number, 1 or 0; or none | `commit`; `activate` without a value | `icon`; needs `event` without a value |
 | `nativeText` | number, string, or none | nothing | `style` (a typography role), `align` (`start`, `center`, `end`) |
 | `spectrum` | — | `commit` with the frequency clicked; `activate` from an annotation | see *Spectrum* below |
+| `zoom` | — | `commit` with the factor, on release | `min`, `max` (the factors allowed); only in a scene with `scroll`; extension API 12 |
 
 The three drawn kinds are invisible hit areas over artwork the extension paints;
 the native kinds are Material widgets the app paints and themes. Every control
@@ -1912,12 +1938,37 @@ may also take:
 - `after`: with a rect, the layer it paints directly after.
 - `opacity`: 0 to 1, fixed or bound like a layer's. At 0 the control is gone.
 - `disabled`: shown, but no click, drag, key or screen-reader adjustment acts on it.
+- `hoverSet` (drawn kinds only; extension API 12): `{value, to}`. While the
+  pointer is over the control, the scene value `value` reads `to` — set by the
+  host, with no call to the extension — and leaving puts back the scene's own
+  value. A layer bound to it lights up under the pointer, and several controls
+  naming one value with different `to`s light up one thing each. It survives
+  renders while the pointer stays.
 
 `options` is `[{label, value}]`, up to 64, with each `value` unique. A choice's
 string is `""` or one of them; a `multi` choice holds its values joined with
 commas in option order, so no option may contain one. `menu` is
 `[{label, event}]`, up to 32: picking an item sends its `event` as the action.
 
+A `zoom` strip is drawn by nothing: it claims a drag that begins on it along a scrolling
+scene's axis. Away from the pane's middle zooms in and toward it zooms out, by the ratio of
+the two distances from the middle, clamped to `min`…`max`. While the drag lasts the app moves
+each layer and control to where the zoom puts its middle, keeping its size, so text and dots
+stay as drawn and only spread apart or close in; a layer with `stretch: true` — a background,
+a line the length of the scene — scales along the scroll instead. That preview holds until
+the render that answers the `commit` arrives, so a scene meant to zoom draws its pieces as
+layers of their own rather than as one picture. A tap on the strip still reaches the button there, and a drag that starts off it
+still scrolls.
+
+A scroll steps a slider or knob by its `step`, down and left lowering it; a one-axis
+control takes a sideways scroll by its own direction. A slider or knob with
+`scrollThrough` (API 12) also takes the scrolls landing on drawn buttons over it, so labels
+drawn over a knob that scrolls the artwork do not stop the scroll; anything else in the
+way — a native control, a `blocksPointer` layer, another slider or knob — keeps the scroll
+from it.
+A knob with `invertDrag` (API 12) moves the other way to a drag, as content held under
+the finger does — what a knob that scrolls the artwork wants — while its scroll is unchanged.
+
 A knob with `valueY` sets two numbers from one patch of artwork — a passband's
 shift across and its width up, say. Horizontal dragging, horizontal scrolling
 and the left/right keys set `value`; vertical ones and the up/down keys set
@@ -2029,9 +2080,8 @@ control faded in over the artwork, and a click-through layer painted over it.
 #### Spectrum
 
 A `spectrum` control is a radio's panadapter and waterfall, drawn by the host
-from sweeps that never reach the extension, on a host with the panadapter
-enabled. It is **extension API 6**, as is `host.setRadioSpectrum`: a bundle
-using either declares `"api": 6`, and an app speaking less refuses it at install
+from sweeps that never reach the extension. It is **extension API 6**, as is
+`host.setRadioSpectrum`: a bundle using either declares `"api": 6`, and an app speaking less refuses it at install
 rather than failing to render the scene. It needs `requiresRadioRead`; without it, or on a host or radio
 without a spectrum, the control says why instead. It is placed like a native
 control and takes the fields of `PanelSceneSpectrum` in the SDK:
@@ -2288,7 +2338,7 @@ protocol's (CI-V bytes that are not whole frames), `invalid`. A refusal heard
 within a second of a raw command on a protocol whose refusals name no command
 (`?;`, rigctld's `RPRT`) is taken as the raw command's, not counted against the
 app's own reads.
-On a host with the panadapter enabled, `readRadio()` carries `spectrum`: null
+`readRadio()` carries `spectrum` (absent on an app without a panadapter): null
 for a radio without a scope, otherwise its settings as the radio reports them
 (`mode`, `spanHz`, `lowHz`/`highHz`, `refLevelDb`, `speed`), what it accepts
 (`spansHz`, `refMinDb`…`refStepDb`, `modes`, `speeds`) and `problem`, why it

package/package.json

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

package/samples/k2hrc-panafall/README.md

@@ -4,9 +4,9 @@ The radio's panadapter and waterfall in a scene panel, with its span, reference
 level and sweep speed, a local contrast control, and click-to-tune. The host
 draws the sweeps in the `spectrum` control; they never reach the extension.
 
-Needs a host with the panadapter enabled (`EXP FALL`) and a radio whose CAT
-protocol carries its scope: an Icom IC-705/7300/7610 (at 115200 bps on a serial
-line), or a FlexRadio, which is mirrored through a DAX IQ channel.
+Needs a radio whose CAT protocol carries its scope: an Icom IC-705/7300/7610 (at
+115200 bps on a serial line), or a FlexRadio, which is mirrored through a DAX IQ
+channel.
 
 In this repository: