@ham2k/extension-sdk 0.12.15 → 1.12.1

package/README.md

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.15
+// @ham2k/extension-sdk 1.12.1
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -1360,6 +1360,9 @@ export interface CommandAction {
 	findInLog?: {
 		query?: string;
 	};
+	navigate?: {
+		to: string;
+	};
 	setCallField?: {
 		text: string;
 	};
@@ -1456,6 +1459,8 @@ export interface CommandCatalogEntry {
 	params?: string;
 	category?: string;
 	needsOperation?: boolean;
+	needsTestData?: boolean;
+	keywords?: string[];
 	expectsParams?: boolean;
 	suggest?: boolean;
 }
@@ -1590,6 +1595,12 @@ export interface ExtensionRelevance {
 	dates?: string[];
 	interests?: string[];
 }
+export type SettingsSection = "activities" | "hunting" | "contests" | "lookups" | "spotting" | "dashboard" | "logging" | "radio" | "map" | "exports";
+export interface ExtensionSettingsPlacement {
+	section?: SettingsSection | (string & {});
+	sidebar?: boolean;
+	common?: boolean;
+}
 export interface ExtensionManifest {
 	key: string;
 	name: string;
@@ -1615,6 +1626,7 @@ export interface ExtensionManifest {
 	requiresClusterCommand?: boolean;
 	experiments?: string[];
 	relevance?: ExtensionRelevance;
+	settings?: ExtensionSettingsPlacement;
 	translations?: Record<string, {
 		name?: string;
 		description?: string;
@@ -2614,6 +2626,14 @@ export interface TemplateContextArgs {
 }
 export declare function templateContext(args: TemplateContextArgs): Record<string, unknown>;
 export declare function isTestOperation(stationCall: JSONValue | undefined): boolean;
+/**
+ * The extension API this SDK describes: the highest `api` a manifest written
+ * against it can declare, and the one its types and host calls are for. The
+ * SDK's and `@ham2k/extension-tools`' minor version is this number, so a
+ * `^1.<api>.0` range names the oldest API an extension needs and admits every
+ * later one.
+ */
+export declare const API_VERSION = 12;
 export declare function defineExtension(def: ExtensionDefinition): void;
 export declare const hooks: {
 	invokeAll(category: HookCategoryName, method: string, args: unknown, online?: boolean): Promise<{

package/dist/index.js

@@ -1,5 +1,6 @@
 import { base64ToBytes, bytesToBase64 } from "./base64.js";
 import { adoptExtensionTimers, clearInterval, clearTimeout, setInterval, setTimeout } from "./timers.js";
+const API_VERSION = 12;
 export * from "./types.js";
 export * from "./hookCategories.js";
 export * from "./panelScene.js";
@@ -426,6 +427,7 @@ const host = {
   }
 };
 export {
+  API_VERSION,
   defineExtension,
   hooks,
   host

package/docs/distribution.md

@@ -144,6 +144,28 @@ The packer refuses:
 The matcher reads a key it cannot parse as "does not gate", so each of the
 shape errors would otherwise ship the bundle as worldwide.
 
+### Settings
+
+An extension with a `settingsPanel` says where its panel goes:
+
+```json
+"settings": { "section": "activities" }
+```
+
+`section` is one of the app's settings sections, picked by the extension's
+main purpose; `sidebar: true` asks for a sidebar entry for a panel that is a
+category of its own, and `common: true` for Common Preferences rows. The section list, and what the app does with a
+placement the manifest does not declare, are in
+[settings.md](./settings.md#where-an-extensions-settings-go).
+
+The packer refuses a `settings` that is not an object, a key inside it other
+than those three, a `section` that is not a section key, and a `sidebar` or
+`common` that is not `true` or `false`. It does not refuse a placement beyond
+the usual — a section outside the list, no section for a `settingsPanel`, a
+sidebar entry, Common Preferences — but prints `held for review on the
+catalog` for each, because the catalog holds such an upload for an admin
+even from a trusted publisher.
+
 ## Using the host's libraries
 
 The host carries a set of libraries and hands every extension the same

package/docs/hooks.md

@@ -1170,10 +1170,10 @@ interface CommandHook {
   catalog?(ctx): Promise<CommandCatalogEntry[]>
 }
 // CommandInterpretation: {expectsParams?, mixedCase?, error?, describe?, confirm?, commands?: CommandAction[]}
-// CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
+// CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, needsTestData?, keywords?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
 //   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, autoRespot?, syncAll?, updateSettings?, updateSetting?, openSettings?,
-//   updateOperation?, markSegment?, findInLog?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
+//   updateOperation?, markSegment?, findInLog?, navigate?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
 ```
@@ -1366,9 +1366,12 @@ Three things differ from `interpret`, all deliberate:
 - **Called once and cached**, not per keystroke — dropped when the runtime is
   replaced (an extension enabled/disabled) or the hook context is
   invalidated (locale change, since `describe` is localized by the hook).
-- **Matching is host-side**, plain case-insensitive substring against
-  `command` and `describe`. Same rule `interpret`'s own matching follows: the
-  host never compiles extension-supplied patterns.
+- **Matching is host-side**, case-insensitive, at the start of a word in
+  `command` or in `keywords` — never mid-word, and `describe` is never
+  searched. Every word that should find a command belongs in its
+  `keywords`: the aliases it accepts when typed, and plain words for what it
+  does. Same rule `interpret`'s own matching follows: the host never
+  compiles extension-supplied patterns.
 - **List commands, not variants.** `radio-commands` advertises one BAND
   entry, not fifteen; `call-notes` advertises `//`, not every key the user
   has defined.
@@ -1958,7 +1961,8 @@ stay as drawn and only spread apart or close in; a layer with `stretch: true`
 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.
+still scrolls. A trackpad's two-finger swipe scrolls on the strip as anywhere else; a trackpad
+pinch begun on it zooms by the pinch's own scale, clamped the same way, and commits as a drag does.
 
 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
@@ -2474,6 +2478,12 @@ schema, kernel dispatch, `ExtensionService`, and `SettingsView` wiring; see
 [settings.md](./settings.md). Complementary to `account`, not a replacement.
 Implemented by: `settings` (the core General panel).
 
+An extension puts all its settings in one panel, placed in the section that
+fits its main purpose and declared in the manifest's `settings` — see
+[Where an extension's settings go](./settings.md#where-an-extensions-settings-go).
+A category of its own, a sidebar entry or Common Preferences rows are reviewed
+on the catalog.
+
 ## ✅ `account` — account connections
 
 Account connections (QRZ, LoFi, SOTA): credential fields, `testCredentials`,

package/docs/settings.md

@@ -26,6 +26,122 @@ There are two tiers, discriminated by a required `kind` tag.
 
 ---
 
+## Where an extension's settings go
+
+**Put all of an extension's settings in one panel, and that panel in the
+section that fits the extension's main purpose.** The panel shows there as a
+single row that opens it in a dialog. An extension does not add a category of
+its own to Application Preferences, an entry to the Settings sidebar, or
+fields to Common Preferences — not without an admin's review on the catalog.
+
+These sections take an extension's panel without review:
+
+| `section` | Shown as | For |
+|---|---|---|
+| `activities` | Activities | an activity program — POTA, SOTA, WWFF |
+| `hunting` | Hunting | chasing and awards: what an operator works rather than activates |
+| `contests` | Contests | a contest or event |
+| `lookups` | Lookups | callsign lookups, notes and history |
+| `spotting` | Spotting | a spot source or destination |
+| `dashboard` | Dashboard | a dashboard panel's app-wide preferences |
+| `logging` | Logging | something that changes how QSOs are entered |
+| `radio` | CAT Control | radios, rigs and keyers |
+| `map` | Maps | the map views |
+| `exports` | Exports | export files and formats |
+
+Prefer the first six — they say what the extension is. The last four suit an
+extension that tunes something the app already has a section for. A section
+holding no panel is not shown.
+
+The section is declared twice: in the **manifest**, which is what the catalog
+reviews and what the app places the panel by, and on the **panel**, for an app
+older than the manifest field. In `manifest.json`:
+
+```json
+{
+  "key": "w7abc-park-notes",
+  "category": "activity",
+  "hooks": ["settingsPanel"],
+  "settings": { "section": "activities" }
+}
+```
+
+And where the panel is registered:
+
+```ts
+api.registerHook('settingsPanel', {
+  hook: {
+    kind: 'simple',
+    title: 'Park Notes',
+    section: 'activities',
+    sidebar: false,
+    fields: [ /* … */ ],
+  },
+});
+```
+
+`settings` has three keys, all optional:
+
+- **`section`** — the key of the section, from the table above.
+- **`sidebar: true`** — a panel that is a category of its own (no `section`,
+  or one the app does not have) may also have an entry in the Settings
+  sidebar. A panel placed in a section is a row there and never has one.
+  Reviewed.
+- **`common: true`** — the panel's fields flagged `common: true` may also show
+  in Common Preferences. Reviewed.
+
+### What is reviewed
+
+The catalog reads a manifest and never runs a bundle, so the manifest is what
+it reviews. An upload is held for an admin — even one from a trusted
+publisher, whose uploads otherwise skip the queue — when its manifest:
+
+- lists `settingsPanel` in `hooks` and names no `settings.section` — the panel
+  would be a category of its own;
+- names a `settings.section` outside the table above — a new category, which
+  the app also has to know (a section the app does not know is shown as a
+  category of its own);
+- sets `settings.sidebar` or `settings.common`.
+
+A placement an admin has approved stays approved: a later version whose
+`settings` are unchanged is not held for it again. To ask for a new category
+or a sidebar entry, declare it and say why in the release notes; the reviewer
+reads both. `npm run pack` (`h2kext-pack`) prints `held for review on the
+catalog` for each of these, so it is no surprise.
+
+### What the app enforces
+
+The manifest is a promise the code could break, so the app holds every
+extension it did not ship to its manifest, whatever the panel asks for:
+
+- the panel goes in the manifest's `settings.section`; with none declared, in
+  the panel's own `section` if it is one of the table's; otherwise it is a
+  category of its own;
+- it has a sidebar entry only when it is a category of its own, the panel's
+  `sidebar` is not false AND the manifest declares `sidebar: true` — so with
+  no `settings`, `sidebar` reads as false;
+- its `common: true` fields reach Common Preferences only when the manifest
+  declares `common: true`; otherwise the flag is ignored and the fields stay
+  in the panel.
+
+A panel from an extension whose manifest `hooks` does not list
+`settingsPanel` is not shown at all: the catalog decides what to review by
+that list, so an undeclared panel is one nobody was asked about.
+`buildExtension` fails the build when the bundle registers a panel its
+manifest does not declare, unless it cannot activate the bundle to find out,
+in which case it warns.
+
+An extension installed from a `.h2kext` file never passed through the
+catalog, so nobody reviewed its manifest: the app takes its `settings` as
+written, `sidebar` and `common` included. Installing a file is the
+operator's own choice to trust it.
+
+Everything else about a panel is untouched: `dataFilesSection` still adds its
+row to the Data Files screen, and `target` still reaches the Logging and
+Developer dialogs (see [Settings targets](#settings-targets)).
+
+---
+
 ## Key namespacing
 
 Wherever an extension can define more than one of something under one
@@ -76,7 +192,9 @@ export interface SimpleSettingsPanel {
   order?: number;
   // Defaults true. Set false to keep this panel out of the app's top-level
   // settings navigation (the sidebar list). Independent of dataFilesSection
-  // below — this only controls the top-level nav.
+  // below — this only controls the top-level nav. An extension the app did
+  // not ship also needs the manifest's `settings.sidebar: true`, which is
+  // reviewed; see "Where an extension's settings go".
   sidebar?: boolean;
   // Defaults false. Set true to also show this panel as a row in the Data
   // Files screen's own "Extensions" section — leave this false for anything
@@ -85,10 +203,12 @@ export interface SimpleSettingsPanel {
   // the type level — inferring this from `sidebar: false` alone would sweep
   // any sidebar-opt-out panel in here.
   dataFilesSection?: boolean;
-  // The key of one of the app's own settings sections ('spotting', the
-  // Spotting section) to show this panel inside, as one row that opens it
-  // in a dialog — instead of a section of its own in Settings and a sidebar
-  // entry, whatever `sidebar` says. An app without that section (an older
+  // The key of one of the app's own settings sections ('activities',
+  // 'spotting', … — see "Where an extension's settings go") to show this
+  // panel inside, as one row that opens it in a dialog — instead of a
+  // section of its own in Settings and a sidebar entry, whatever `sidebar`
+  // says. Declare the same key as the manifest's `settings.section`, which is
+  // what the app places the panel by. An app without that section (an older
   // one, or a key it doesn't know) shows the panel as if this weren't set,
   // so it needs no newer API level.
   section?: string;
@@ -363,8 +483,11 @@ override) without it cluttering the panel for regular users:
 A panel with nothing to show at the current developer-mode setting is left
 out of the Settings screen's list of categories rather than shown as an empty
 heading, so a panel whose every field is `devMode` appears there only while
-developer mode is on. Its sidebar entry is not: give such a panel
-`sidebar: false`, or the entry opens on an empty page.
+developer mode is on. A panel placed in a `section` is treated the same way:
+its row there is a developer-mode row when every field it has is `devMode`,
+and it has no row at all when it has no fields on this platform. Its sidebar
+entry is not: give such a panel `sidebar: false`, or the entry opens on an
+empty page.
 
 ## `aliases`: short names for the SET command
 
@@ -404,7 +527,10 @@ maintained as a separate list somewhere else in the app. Any field, link, or
 action (core-declared or extension-declared, Tier 1 or Tier 2 alike) can set:
 
 - **`common: true`** — also show this element in the Common Preferences
-  section, on top of its own group's. Off by default. Not the same thing as
+  section, on top of its own group's. Off by default. An extension's
+  `common` fields reach Common Preferences only when its manifest declares
+  `settings.common: true`, which is reviewed — see
+  [Where an extension's settings go](#where-an-extensions-settings-go). Not the same thing as
   `FormFieldOption.common`/`uncommon` above — that's a `multiselect`
   option's own disclosure tier (upfront vs. behind "Show more"), a
   different scope (an option inside one field, not the field itself).

package/package.json

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

package/samples/k2hrc-panafall/README.md

@@ -4,9 +4,17 @@ The radio's panadapter and waterfall in a scene panel, with its span, reference
 level and sweep speed, a local contrast control, and click-to-tune. The host
 draws the sweeps in the `spectrum` control; they never reach the extension.
 
-Needs a radio whose CAT protocol carries its scope: an Icom IC-705/7300/7610 (at
-115200 bps on a serial line), or a FlexRadio, which is mirrored through a DAX IQ
-channel.
+Needs a supported radio:
+
+- Icom IC-705/7300/7610, at 115200 bps when using a serial line.
+- FlexRadio, mirrored through a DAX IQ channel.
+- Elecraft K4 over Ethernet, with a separate local TCP spectrum connection on
+  port 9201 alongside CAT. It displays the main panadapter with local zoom,
+  reference and speed controls. Levels are displayed as received, without an
+  RF calibration claim.
+
+The panel shows only the controls each radio supports; contrast, averaging,
+frame rate and waterfall rows remain local.
 
 In this repository:
 
@@ -14,3 +22,8 @@ In this repository:
 node build.mjs
 node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-panafall.h2kext
 ```
+
+Samples are not included in the app's regular extension build. Install the
+resulting `.h2kext` through **Settings → Extensions & Features → Install from
+file…**, then add its **Panadapter** panel to an operation. The host must have
+the matching radio support.

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

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