@ham2k/extension-sdk 1.12.1 → 1.12.4

package/dist/activityExports.js

@@ -1,11 +1,44 @@
 import { exportTypeDefinition } from "./exportSettings.js";
 import { exportFilename, startMillisOf } from "./exportNames.js";
-import { segmentsWith } from "./segments.js";
+import { operationForQso, segmentsWith } from "./segments.js";
+import { utcDate } from "./templateContext.js";
 import { createCachedTranslator } from "./i18n.js";
 import en from "./i18n/activityExports.en.json";
 import es from "./i18n/activityExports.es.json";
 const tFor = createCachedTranslator({ en: { translation: en }, es: { translation: es } });
 const SEPARATOR = ":";
+const DAY_MARK = "@";
+const DAY_LENGTH = "YYYY-MM-DD".length;
+function byUtcDay(qsos) {
+  const timed = /* @__PURE__ */ new Map();
+  const timeless = [];
+  for (const qso of qsos) {
+    const millis = Number(qso.startAtMillis ?? 0);
+    if (!(millis > 0)) {
+      timeless.push(qso);
+      continue;
+    }
+    const day = utcDate(millis);
+    const list = timed.get(day);
+    if (list) list.push(qso);
+    else timed.set(day, [qso]);
+  }
+  const days = [...timed.keys()].filter((day) => timed.get(day).some((qso) => !qso.deleted)).sort();
+  return new Map(days.map((day, i) => [day, i === 0 ? [...timeless, ...timed.get(day)] : timed.get(day)]));
+}
+function activeQsos(operation, qsos, segments, activationType, ref) {
+  if (!segments || segments.length === 0) return qsos;
+  const refsAt = (qso) => refsOfType(operationForQso(operation, qso, segments), activationType);
+  const segmentRefs = segments.map((segment) => refsOfType(segment.operation, activationType).map((r) => r.ref));
+  const known = new Set(segmentRefs.flat());
+  if (known.has(ref)) {
+    const own = qsos.filter((qso) => refsAt(qso).some((r) => r.ref === ref));
+    const movedHere = known.size > 1 && segmentRefs.slice(1).some((refs) => refs.includes(ref));
+    if (own.length > 0 || movedHere) return own;
+  }
+  const active = qsos.filter((qso) => refsAt(qso).length > 0);
+  return active.length > 0 ? active : qsos;
+}
 function refsOfType(container, type) {
   const refs = container.refs ?? [];
   return refs.filter((r) => r && r.type === type && typeof r.ref === "string" && r.ref.length > 0).map((r) => ({ ref: r.ref, name: typeof r.name === "string" ? r.name : void 0 }));
@@ -34,10 +67,10 @@ function activityExportHook(rules) {
         }
       ];
     },
-    async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
+    async suggestExportOptions({ operation, qsos, segments, compactFilenames }, ctx) {
       const refs = refsOfType(operation, rules.activationType);
       const t = tFor(ctx);
-      return refs.map((ref) => ({
+      const whole = (ref) => ({
         exportType: `${rules.activationType}-adif`,
         templateData: { ref: ref.ref, refName: ref.name ?? "", activity: rules.label },
         exportKey: `${prefix}${SEPARATOR}${ref.ref}`,
@@ -57,15 +90,44 @@ function activityExportHook(rules) {
         // being activated.
         refType: rules.activationType,
         ref: ref.ref
-      }));
+      });
+      const daysOf = (ref) => byUtcDay(activeQsos(operation, qsos ?? [], segments, rules.activationType, ref));
+      const split = rules.splitByUtcDay ? refs.map((ref) => ({ ref, days: daysOf(ref.ref) })) : [];
+      if (split.some(({ days }) => days.size > 1)) {
+        return split.flatMap(
+          ({ ref, days }) => days.size === 0 ? [whole(ref)] : [...days].map(([day, dayQsos]) => ({
+            exportType: `${rules.activationType}-adif`,
+            // The day rides as the filename template's modifier: a template
+            // is dated by the whole log's first contact, and two files that
+            // differed only in their contents would overwrite each other.
+            templateData: { ref: ref.ref, refName: ref.name ?? "", activity: rules.label, modifier: day },
+            exportKey: `${prefix}${DAY_MARK}${day}${SEPARATOR}${ref.ref}`,
+            format: "adif",
+            label: t("adifForRefOnDay", { program: rules.label, ref: ref.ref, day }),
+            // Dated by the day's own first contact, which the file is.
+            filename: filenameFor(operation, dayQsos, ref.ref, compactFilenames),
+            // The day's own count: the operator checking that a day reached
+            // its threshold needs that day's number, not the whole log's.
+            qsoCount: dayQsos.filter((qso) => !qso.deleted).length,
+            icon: rules.icon,
+            selectedByDefault: true,
+            refType: rules.activationType,
+            ref: ref.ref
+          }))
+        );
+      }
+      return refs.map(whole);
     },
     async generateExport(args, ctx) {
       const exportType = String(args.exportType ?? "");
       const exportKey = String(args.exportKey ?? "");
-      if (exportType !== `${rules.activationType}-adif` || !exportKey.startsWith(`${prefix}${SEPARATOR}`)) {
+      const dayed = exportKey.startsWith(`${prefix}${DAY_MARK}`) && exportKey.charAt(prefix.length + DAY_MARK.length + DAY_LENGTH) === SEPARATOR;
+      const day = dayed ? exportKey.slice(prefix.length + DAY_MARK.length, prefix.length + DAY_MARK.length + DAY_LENGTH) : void 0;
+      const head = dayed ? prefix.length + DAY_MARK.length + DAY_LENGTH : prefix.length;
+      if (exportType !== `${rules.activationType}-adif` || !(dayed || exportKey.startsWith(`${prefix}${SEPARATOR}`))) {
         throw new Error(`${rules.key}: unknown export type/key '${exportType}' / '${exportKey}'`);
       }
-      const wanted = exportKey.slice(prefix.length + SEPARATOR.length);
+      const wanted = exportKey.slice(head + SEPARATOR.length);
       if (!refsOfType(args.operation, rules.activationType).some((r) => r.ref === wanted)) {
         throw new Error(`${rules.key}: operation has no ${rules.activationType} reference '${wanted}'`);
       }
@@ -75,9 +137,13 @@ function activityExportHook(rules) {
           (r) => r?.type !== rules.activationType || r?.ref === wanted
         )
       });
+      const qsos = day === void 0 ? args.qsos : byUtcDay(args.qsos ?? []).get(day) ?? [];
+      if (day !== void 0 && !qsos.some((qso) => !qso.deleted)) {
+        throw new Error(`${rules.key}: no contacts on ${day} for ${wanted}`);
+      }
       const content = await adifForExport({
         operation: claimOnly(args.operation),
-        qsos: args.qsos,
+        qsos,
         segments: segmentsWith(args.segments, claimOnly),
         includePrivateData: args.includePrivateData,
         includeLookupData: args.includeLookupData,
@@ -89,7 +155,7 @@ function activityExportHook(rules) {
         operatorFallback: rules.operatorFallback
       });
       return {
-        filename: filenameFor(args.operation, args.qsos, wanted, args.compactFilenames),
+        filename: filenameFor(args.operation, qsos, wanted, args.compactFilenames),
         mimeType: "text/plain",
         content
       };

package/dist/activityScoring.js

@@ -34,6 +34,7 @@ function activityScorer(rules) {
     return typeof rule === "function" ? rule(activatedRefs) : rule;
   }
   const freshRefRescuesActivation = rules.freshRefRescuesActivation ?? true;
+  const distinctCallsPerDay = rules.distinctCallsPerDay ?? false;
   const tracksActivation = rules.tracksActivation ?? true;
   const tracksOperators = rules.tracksOperators ?? true;
   const allowsMultiple = rules.allowsMultipleReferences ?? false;
@@ -125,16 +126,22 @@ function activityScorer(rules) {
       const now = { day, band, mode, refs: huntedRefs };
       const priors = sheet.workedByCall[call] ?? [];
       const verdict = judge(priors, now);
-      const isDupe = verdict === "duplicate";
+      let isDupe = verdict === "duplicate";
       const freshRefOnly = verdict === "ref" && !freshRefRescuesActivation;
-      const activationCredit = freshRefOnly ? 0 : activationValue;
+      let activationCredit = freshRefOnly ? 0 : activationValue;
+      if (distinctCallsPerDay && activationCredit > 0 && !isDupe) {
+        const days = sheet.activationCallDays ?? (sheet.activationCallDays = {});
+        activationCredit = days[call] === day ? 0 : 1;
+        days[call] = day;
+        if (activationCredit + huntingValue === 0 && !verdict) isDupe = true;
+      }
       const hasStake = activationValue + huntingValue > 0;
       const score = { value: isDupe ? 0 : activationCredit + huntingValue };
       if (!hasStake) {
       } else if (isDupe) {
         score.dupe = true;
         score.alerts = ["duplicate"];
-      } else if (verdict) {
+      } else if (verdict && verdict !== "duplicate") {
         score.notices = [NOTICE_KEYS[verdict]];
       } else if (priors.length > 0 && score.value > 0 && freshRefRescuesActivation) {
         score.dupe = false;

package/dist/i18n/activityExports.en.json

@@ -1,4 +1,5 @@
 {
   "adifForRef": "ADIF for {{program}} {{ref}}",
+  "adifForRefOnDay": "ADIF for {{program}} {{ref}} on {{day}}",
   "adifForHunter": "{{program}} Hunter Log"
 }

package/dist/i18n/activityExports.es.json

@@ -1,4 +1,5 @@
 {
   "adifForRef": "ADIF para {{program}} {{ref}}",
+  "adifForRefOnDay": "ADIF para {{program}} {{ref}} del {{day}}",
   "adifForHunter": "Registro de Cazador {{program}}"
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 1.12.1
+// @ham2k/extension-sdk 1.12.4
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -175,10 +175,18 @@ export interface PanelSceneSpectrum {
 	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.
+	 * as `rising` says: by default left to right for `down` (the default) and `up`, bottom to top for
+	 * `right` and top to bottom for `left` — `down` turned a quarter either way. Text stays upright;
+	 * offsets and `corner`s are measured as if flowing down.
 	 */
 	flow?: "down" | "up" | "right" | "left";
+	/**
+	 * Which way frequency rises, across the `flow`: `right` or `left` for `down` and `up`, `down` or
+	 * `up` for `right` and `left`. Omitted, `right` for `down` and `up`, `up` for `right`, `down` for
+	 * `left`. Offsets, `align` and `corner`s are still measured as if frequency rose to the right.
+	 * Extension API 12; before it, `left` rose bottom to top as `right` does.
+	 */
+	rising?: "right" | "left" | "down" | "up";
 	/** 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. */
@@ -222,7 +230,9 @@ export interface PanelSceneSpectrum {
 	/**
 	 * Hz shown across the control, from the middle of each sweep. A sweep wider than this is cropped
 	 * to it, so a radio whose scope comes in a few widths can be shown at any narrower one — set the
-	 * scope (`setRadioSpectrum`) to the narrowest that covers it. Extension API 7.
+	 * scope (`setRadioSpectrum`) to the narrowest that covers it. Where the radio's `spectrum` says
+	 * `autoSpan`, the app sets the scope itself, wide enough for the widest `span` on screen.
+	 * Extension API 7; `autoSpan` 12.
 	 */
 	span?: PanelSceneSpectrumNumber;
 	/** A click tunes to the nearest multiple of this many Hz. Omitted, wherever it lands. */
@@ -408,6 +418,12 @@ export interface PanelSceneControl extends PanelSceneSpectrum {
 		value: string;
 		to: number;
 	};
+	/**
+	 * A `button` only: a click sends, as the event's `value`, where along the button's longer side it
+	 * landed — 0 at its top or left end, 1 at its bottom or right — so a scale can be clicked at a
+	 * place. Keys and screen readers activate it with no value, as does an app before this. Extension API 12.
+	 */
+	tapAt?: boolean;
 	/**
 	 * 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.
@@ -1099,6 +1115,7 @@ export interface ExportResult {
 export interface ExportOptionsRequest {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
+	segments?: OperationSegmentPayload[];
 	compactFilenames?: boolean;
 }
 export interface ExportOption {
@@ -1242,6 +1259,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;
@@ -2090,13 +2115,24 @@ export interface PanelRadioSpectrum {
 	mode: "center" | "fixed" | null;
 	/** Half the width shown while centered — what the radio's menu shows as ±. */
 	spanHz: number | null;
-	/** The edges while fixed. */
+	/**
+	 * The edges shown: while fixed, and while centred where the radio places its scope apart from the
+	 * dial (a FlexRadio's panadapter, which a retune inside it does not move). Null where the scope
+	 * sits on the dial, `spanHz` either side of it.
+	 */
 	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[];
+	/**
+	 * The app sets the span itself — a sweep it computes, whose width changes nothing on the radio
+	 * (a FlexRadio's) — to the narrowest covering the widest `span` of the spectrum controls shown,
+	 * each cropping its own width. A panel then names its width with `span` and leaves
+	 * `setRadioSpectrum`'s `spanHz` alone, or the panels take turns. Absent before extension API 12.
+	 */
+	autoSpan?: boolean;
 	refMinDb: number;
 	refMaxDb: number;
 	refStepDb: number;
@@ -2415,6 +2451,7 @@ export interface ActivityScoringRules {
 	tracksActivation?: boolean;
 	tracksOperators?: boolean;
 	freshRefRescuesActivation?: boolean;
+	distinctCallsPerDay?: boolean;
 	allowsMultipleReferences?: boolean;
 	uniquePer?: readonly UniqueAxis[];
 	activates?: "daily" | "once";
@@ -2438,6 +2475,7 @@ export type ActivityScoresheet = {
 	dayActivatedQsos: number;
 	dayHuntedQsos: number;
 	dayDuplicates: number;
+	activationCallDays?: Record<string, number>;
 };
 export declare function activityScorer(rules: ActivityScoringRules): ContestScorer<ActivityScoresheet>;
 export interface ActivityExportRules {
@@ -2448,10 +2486,11 @@ export interface ActivityExportRules {
 	icon?: string;
 	includeFieldsFrom?: string[];
 	operatorFallback?: OperatorFallback;
+	splitByUtcDay?: boolean;
 }
 export declare function activityExportHook(rules: ActivityExportRules): {
 	getExportTypes(): Promise<ExportTypeDefinition[]>;
-	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
+	suggestExportOptions({ operation, qsos, segments, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
 export interface HuntingExportRules {

package/docs/distribution.md

@@ -417,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

@@ -413,7 +413,7 @@ interface ExportHook {
   suggestExportOptions?(args: ExportOptionsRequest, ctx): Promise<ExportOption[]>
   generateExport(args: ExportRequest, ctx): Promise<ExportResult>
 }
-// ExportOptionsRequest: {operation, qsos, compactFilenames?}
+// ExportOptionsRequest: {operation, qsos, segments?, compactFilenames?}
 // ExportOption: {exportType, exportKey?, format, label, filename?, icon?, color?, refType?, ref?, priority?, selectedByDefault?}
 // ExportRequest: {operation, qsos, segments?, events?, exportType?, exportKey?, compactFilenames?}  — full QSON, one coarse call
 // ExportResult:  {filename, mimeType, content}
@@ -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.
@@ -1916,7 +1926,7 @@ the extension. `value` names what it shows and sets.
 
 | Kind | Binds to | Sends | Also takes |
 |---|---|---|---|
-| `button` | — | `activate` | `menu` |
+| `button` | — | `activate` | `menu`, `tapAt` (extension API 12: a click's `value` is where along the button's longer side it landed, 0 at its top or left end to 1 at its bottom or right; a key or screen reader activates it with none) |
 | `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` |
@@ -2094,6 +2104,13 @@ control and takes the fields of `PanelSceneSpectrum` in the SDK:
   (`both`, `pan`, `waterfall`), `split`, and `flow` — which way the waterfall
   moves (`down`, `up`, `right`, `left`), the panadapter on the side it comes
   from.
+- `rising` (extension API 12): which way frequency increases, across the
+  flow — `right` or `left` for `down` and `up`, `down` or `up` for `right` and
+  `left`; one along the flow is refused. Omitted, each flow is `down` turned a
+  quarter, never mirrored: `right` for `down` and `up`, `up` for `right`,
+  `down` for `left` (before API 12, `left` rose up the screen too). Text stays
+  upright, and offsets, `align` and pointer corners are measured as if
+  frequency rose to the right.
 - `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.
@@ -2111,7 +2128,10 @@ control and takes the fields of `PanelSceneSpectrum` in the SDK:
   number or a scene value. A wider sweep is cropped to it, so a radio whose
   scope comes in a few fixed widths can be shown at any narrower one; set the
   scope to the narrowest that covers it. Everything is drawn, labelled and
-  clicked on the window shown.
+  clicked on the window shown. Where the radio's `spectrum` says `autoSpan`
+  (extension API 12), the app sets the scope itself, to the narrowest span
+  covering the widest `span` among the spectrum controls on screen, so each
+  panel names its width here and leaves `setRadioSpectrum`'s `spanHz` alone.
 - `follow` (0–0.45): keeps the tuned frequency at least this share of the
   width from either edge, by moving the radio's scope just far enough to put
   it on that margin — the picture scrolls with the dial rather than jumping
@@ -2347,7 +2367,13 @@ 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.
+`spectrum` control has the scope running, and null otherwise. `autoSpan`
+(extension API 12) is true where the app sizes the scope for its displays — a
+sweep it computes, whose width changes nothing on the radio (a FlexRadio's DAX
+IQ): it runs at the narrowest span covering the widest spectrum control's
+`span` on screen, each control cropping its own width from it, and narrows
+again as wider ones go. A panel there names its width with `span`; setting
+`spanHz` too has the panels take turns.
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "1.12.1",
+  "version": "1.12.4",
   "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 })
+  },
+})