@ham2k/extension-sdk 1.12.0 → 1.12.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 1.12.0
+// @ham2k/extension-sdk 1.12.2
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -1242,6 +1242,14 @@ export interface ChasingProgram {
 	supersedes?: string[];
 	refLabel?: string;
 	imports?: ChasingImporter[];
+	notices?: Partial<Record<ChaseNoticeVerdict, string>>;
+	modeLabels?: Record<string, string>;
+	translations?: Record<string, ChasingNoticeLabels>;
+}
+export type ChaseNoticeVerdict = "newRef" | "newBand" | "newMode" | "unconfirmed";
+export interface ChasingNoticeLabels {
+	notices?: Partial<Record<ChaseNoticeVerdict, string>>;
+	modeLabels?: Record<string, string>;
 }
 export interface ChasingImporter {
 	key: string;
@@ -1595,6 +1603,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;
@@ -1620,6 +1634,7 @@ export interface ExtensionManifest {
 	requiresClusterCommand?: boolean;
 	experiments?: string[];
 	relevance?: ExtensionRelevance;
+	settings?: ExtensionSettingsPlacement;
 	translations?: Record<string, {
 		name?: string;
 		description?: string;

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
@@ -395,12 +417,14 @@ can move it forward from there.
 
 Which ones ship is staged. Today it is the catalog twin of every extension the
 app used to build in (see [Retired built-ins](#retired-built-ins)), so that an
-install moving off them has every one to hand with no network. Once installs
-still on a build with the built-ins are few enough, it shrinks to the eight a
-new install needs — `ham2k-pota`, `ham2k-sota`, `ham2k-wwff` and the five
-lookups — and the rest are fetched from the catalog when switched on
+install moving off them has every one to hand with no network, and
+`ham2k-dxcc`, which replaced the core `dxcc` chasing program and is on for
+everyone as that was. Once installs still on a build with the built-ins are few
+enough, it shrinks to the nine a new install needs — `ham2k-pota`,
+`ham2k-sota`, `ham2k-wwff`, `ham2k-dxcc` and the five lookups — and the rest
+are fetched from the catalog when switched on
 ([HALO-743](https://cabo.ham2k.com/halo/c/743)). The app's own tests rely on
-only those eight, the core, and the never-shipped samples, so the shrink
+only those nine, the core, and the never-shipped samples, so the shrink
 touches none of them.
 
 **They have to be kept current.** A pre-load is frozen into the binary, so

package/docs/hooks.md

@@ -1607,7 +1607,14 @@ registerHook("chasing", { key: "dxcc", hook: {
   without invoking anything. Raise `version` whenever the same contacts would
   claim something different: the app keeps no claim from an older version.
   `refLabel` is what one reference is called where a notice names it
-  ("New POTA Park"), the program's `label` when left out.
+  ("New POTA Park"), the program's `label` when left out. A program may
+  instead word a verdict's notice itself: `notices` by verdict (`newRef`,
+  `newBand`, `newMode`, `unconfirmed`), where `{{band}}` names the band a
+  new band is on and `{{mode}}` the mode a new mode is in, through
+  `modeLabels`, with both per language under `translations` (`{ es: {
+  notices, modeLabels } }`). A verdict it leaves out, or one whose notice
+  lacks the band or mode its words name, reads the app's way; a guess reads
+  "Probably …" around the program's words.
   `supersedes` names the scoring notices the program's verdicts stand in for
   (DXCC: `newDXCC`): wherever the program judges a call or a spot, the
   scorer's notice is dropped in favor of the verdict.
@@ -1662,9 +1669,12 @@ extension API 9: a bundle that registers a program declares `"api": 9`, which
 the packer enforces, so an older app — which would install it and never ask
 it anything — is never offered it.
 
-Implemented by: `dxcc` (core) — Mixed, per-band and per-mode slots for the
-station call worked from each entity; LoTW and paper QSLs confirm, LoTW credit
-verifies. `ham2k-pota` — one slot per park hunted, worked only; its
+Implemented by: `ham2k-dxcc` (catalog, pre-loaded; core `dxcc` until
+HALO-844) — Mixed, per-mode and per-band slots for the station call worked
+from each entity, worded "DXCC ATNO", "DXCC in CW", "DXCC in 80m"; LoTW and
+paper QSLs confirm, `credits.dxcc` verifies; the DXCC Challenge is a tally of
+its band slots. A stored goal for `dxcc` carries to it
+(`kRenamedChasePrograms`). `k2hrc-dxcc` is the SDK's worked example. `ham2k-pota` — one slot per park hunted, worked only; its
 hunted-parks export verifies. `ham2k-was` — Mixed, per-band and per-mode
 slots (plus FT8 and RTTY) for the station call worked from one 4-character
 grid; LoTW and paper QSLs confirm, `WAS` credit verifies.
@@ -1961,7 +1971,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
@@ -2477,6 +2488,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": "1.12.0",
+  "version": "1.12.2",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",

package/samples/README.md

@@ -10,6 +10,7 @@ building — the header comment in each `src/index.ts` says what it leaves out.
 | `k2hrc-hamqth` | A callsign lookup, and the `account` hook that asks for a password |
 | `k2hrc-llota` | An award program: references, an offline list, activation scoring |
 | `k2hrc-cqww` | A contest: an exchange to type, and a score to keep |
+| `k2hrc-dxcc` | A chasing program: what each contact counts toward, and how its notices read (extension API 9) |
 | `k2hrc-radio` | An HTML panel, and why you should probably write markdown instead |
 | `k2hrc-panel-scenes` | Experimental panel scenes: SVG artwork, controls and animations, with simulated radio and weather panels |
 | `k2hrc-panafall` | A radio's panadapter and waterfall in a scene, styled and tuned by click (extension API 7) |

package/samples/k2hrc-dxcc/build.mjs

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

package/samples/k2hrc-dxcc/manifest.json

@@ -0,0 +1,23 @@
+{
+  "key": "k2hrc-dxcc",
+  "name": "DXCC (sample)",
+  "shortName": "DXCC*",
+  "version": "1.0.0",
+  "description": "The DXCC entities a station has worked and confirmed, as a worked example of a chasing program",
+  "category": "award",
+  "icon": "earth",
+  "accentColor": "#2E7D32",
+  "api": 9,
+  "keywords": ["award", "dxcc", "chasing", "sample"],
+  "hooks": ["chasing"],
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.0",
+    "@ham2k/lib-country-files": "^1.0.0",
+    "@ham2k/lib-dxcc-data": "^1.0.0",
+    "@ham2k/lib-format-tools": "^1.0.0",
+    "@ham2k/lib-geo-tools": "^1.0.0",
+    "@ham2k/lib-operation-data": "^1.0.0",
+    "i18next": "^23.0.0",
+    "liquidjs": "^10.0.0"
+  }
+}

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

@@ -0,0 +1,104 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// SAMPLE — a chasing program: what each contact counts toward.
+//
+// An award is a checklist, and a chasing program says which lines of it a
+// contact fills. The app keeps the best claim for each line, ranks spots by
+// what working the station would add, and alerts on what is new. The program
+// never reads the log: `claimsForQsos` is a pure function of each contact,
+// because the app also asks it about spots and about the call being typed.
+//
+// One contact makes several claims, one per kind of line the award keeps —
+// here DXCC's three: Mixed (any band, any mode), its band, and its mode. A
+// missing Mixed line is a new entity, a missing band or mode line a new band
+// or mode, and `notices` says how each reads ("DXCC in 80m").
+//
+// The rules here are DXCC's, simplified: the catalog's `ham2k-dxcc` adds
+// deleted entities, maritime mobile, satellites and the DXCC Challenge. See
+// `docs/hooks.md` §`chasing`.
+
+import { defineExtension, entityForCall } from "@ham2k/extension-sdk"
+import type { ChasingHook, JSONValue, QsoClaim } from "@ham2k/extension-sdk"
+import { parseCallsign } from "@ham2k/lib-callsigns"
+import { ADIF_MODES_AND_SUBMODES, superModeForMode } from "@ham2k/lib-operation-data"
+
+import manifest from "../manifest.json" with { type: "json" }
+
+/// DXCC's three mode awards. `superModeForMode` calls anything it does not
+/// know `DATA`, so a mode is checked against ADIF's list first.
+const KNOWN_MODES = new Set(ADIF_MODES_AND_SUBMODES.map((mode) => mode.toUpperCase()))
+const AWARD_MODES: Record<string, string> = { CW: "CW", PHONE: "PHONE", DATA: "DIGITAL" }
+
+function obj(value: JSONValue | undefined): Record<string, JSONValue> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {}
+}
+
+/// Who the claim belongs to: an opaque string the program builds. DXCC goes
+/// to a call, for contacts made from one entity — KI2D and KI2D/P share a
+/// checklist, KI2D/VE2 keeps its own.
+function holderFor(station: Record<string, JSONValue>): string | undefined {
+  if (typeof station.call !== "string" || !station.call) return undefined
+  const call = station.call.trim().toUpperCase()
+  const base = parseCallsign(call).baseCall || call
+  const entity = typeof station.dxccCode === "number" ? station.dxccCode : entityForCall(call).dxccCode
+  return entity == null ? base : `${base}@${entity}`
+}
+
+/// `worked` from the contact itself, `confirmed` by a QSL the award takes.
+function levelOf(qso: Record<string, JSONValue>): Pick<QsoClaim, "level" | "by"> {
+  const qsl = obj(qso.qsl)
+  if (obj(qsl.lotw).received === true) return { level: "confirmed", by: "lotw" }
+  if (obj(qsl.qsl).received === true) return { level: "confirmed", by: "qsl" }
+  return { level: "worked" }
+}
+
+function claimsFor(qso: Record<string, JSONValue>): QsoClaim[] {
+  // An event marker's calls are placeholders, not stations.
+  if (qso.band === "event") return []
+  const their = obj(qso.their)
+  const holder = holderFor(obj(qso.our))
+  if (typeof their.call !== "string" || !holder) return []
+  const { dxccCode, entityName } = entityForCall(their.call)
+  if (dxccCode == null) return []
+
+  const base = { holder, ref: String(dxccCode), ...(entityName ? { label: entityName } : {}), ...levelOf(qso) }
+  const claims: QsoClaim[] = [{ ...base, band: null, mode: null }]
+  if (typeof qso.band === "string" && qso.band) claims.push({ ...base, band: qso.band, mode: null })
+  const mode = typeof qso.mode === "string" && KNOWN_MODES.has(qso.mode.toUpperCase()) ? AWARD_MODES[superModeForMode(qso.mode.toUpperCase())] : undefined
+  if (mode) claims.push({ ...base, band: null, mode })
+  return claims
+}
+
+const program: ChasingHook = {
+  // Plain data, read without calling anything. Raise `version` whenever the
+  // same contacts would claim something different.
+  program: {
+    label: "DXCC*",
+    icon: "earth",
+    version: 1,
+    editions: "lifetime",
+    notices: { newRef: "New DXCC* entity", newBand: "DXCC* on {{band}}", newMode: "DXCC* in {{mode}}" },
+    modeLabels: { PHONE: "Phone", DIGITAL: "Digital" },
+  },
+  // Keyed by each contact's uuid; one without a uuid has no key to answer under.
+  claimsForQsos: ({ qsos }) =>
+    Object.fromEntries(qsos.filter((qso) => typeof qso.uuid === "string" && qso.uuid).map((qso) => [qso.uuid as string, claimsFor(qso)])),
+  holdersFor: ({ station }) => {
+    const holder = holderFor(station)
+    return holder ? [holder] : []
+  },
+  // One tally per thing worth counting: entities, from their Mixed lines.
+  summarizeClaims: ({ slots }) => {
+    const entities = slots.filter((slot) => slot.band === null && slot.mode === null)
+    const confirmed = entities.filter((slot) => slot.level !== "worked").length
+    return { entities: { key: "entities", icon: "earth", label: `${entities.length} entities`, summary: `${confirmed} confirmed`, total: entities.length } }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("chasing", { hook: program, key: manifest.key })
+  },
+})