@ham2k/extension-sdk 0.11.0 → 0.12.2

package/dist/dxcc.js

@@ -3,7 +3,14 @@ import { annotateFromCountryFile, useBuiltinCountryFile } from "@ham2k/lib-count
 import { DXCC_BY_CODE } from "@ham2k/lib-dxcc-data";
 useBuiltinCountryFile();
 function annotateCallAgainstCountryFile(call, options) {
-  return annotateFromCountryFile(parseCallsign(call), options);
+  const annotated = annotateFromCountryFile(parseCallsign(call), options);
+  return annotated.tz ? { ...annotated, tz: ordinarySignTz(annotated.tz) } : annotated;
+}
+function ordinarySignTz(tz) {
+  const match = /^GMT([+-]?\d+(?:\.\d+)?)$/.exec(tz);
+  if (!match) return tz;
+  const offset = -Number(match[1]);
+  return offset > 0 ? `GMT+${offset}` : `GMT${offset === 0 ? 0 : offset}`;
 }
 function entityPrefixForCall(call) {
   if (!call) return void 0;

package/dist/exportSettings.js

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.11.0
+// @ham2k/extension-sdk 0.12.2
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -490,6 +490,8 @@ export interface Ref {
 	lon?: number;
 	location?: string;
 	program?: string;
+	activationRadiusInMeters?: number;
+	activationRadiusInFeet?: number;
 	retired?: boolean;
 	for?: "operation" | "qso";
 	[key: string]: JSONValue | undefined;
@@ -1874,7 +1876,9 @@ export interface ReferenceActivityConfig {
 	linkUrl?: (reference: string) => string;
 	transforms?: RefTransform[];
 	refInput?: (args: RefInputArgs, ctx: HookContext) => Promise<RefInputExtras> | RefInputExtras;
+	activationRadius?: ActivationRadius | ((row: LookupRow) => ActivationRadius | undefined);
 }
+export type ActivationRadius = Pick<Ref, "activationRadiusInMeters" | "activationRadiusInFeet">;
 export interface RefInputArgs {
 	operation: Record<string, JSONValue>;
 	qso?: Record<string, JSONValue>;

package/dist/referenceActivity.js

@@ -58,6 +58,10 @@ function referenceActivity(config) {
   const category = config.category ?? config.key;
   const program = config.adifProgram ?? config.label;
   const allowsMultiple = config.allowsMultiple ?? false;
+  function radiusFor(row) {
+    const radius = row ? typeof config.activationRadius === "function" ? config.activationRadius(row) : config.activationRadius : void 0;
+    return { activationRadiusInMeters: radius?.activationRadiusInMeters, activationRadiusInFeet: radius?.activationRadiusInFeet };
+  }
   async function lookupReference(ref) {
     const host = await hostApi();
     try {
@@ -78,7 +82,8 @@ function referenceActivity(config) {
       grid: void 0,
       lat: void 0,
       lon: void 0,
-      location: void 0
+      location: void 0,
+      ...radiusFor(null)
     };
   }
   function decorate(ref, reference, row, unknown) {
@@ -91,6 +96,7 @@ function referenceActivity(config) {
       grid: data.grid,
       lat: row.lat,
       lon: row.lon,
+      ...radiusFor(row),
       location: data.location,
       program,
       label: `${config.label} ${reference}: ${row.name}`,
@@ -206,6 +212,7 @@ function referenceActivity(config) {
           grid: data.grid,
           lat: row.lat,
           lon: row.lon,
+          ...radiusFor(row),
           location: data.location,
           program,
           label: `${config.label} ${row.key}: ${row.name ?? ""}`,
@@ -230,6 +237,7 @@ function referenceActivity(config) {
           grid: data.grid,
           lat: row?.lat,
           lon: row?.lon,
+          ...radiusFor(row),
           location: data.location,
           program,
           label: `${config.label} ${typed}: ${name}`,

package/docs/hooks.md

@@ -209,9 +209,11 @@ interface LookupServiceHook {
 **locationScope merge rules** (`CallInfo.locationScope`, ranked
 `qth < prefixed < portable`, most general to most specific):
 - A result whose `locationScope` is strictly more specific than the current
-  guess's clears all location fields (`locSource, lat, lon, grid, city,
-  state, county, country`) before merging the result in, and the guess
-  adopts the more specific scope.
+  guess's clears all location fields (`locSource, lat, lon, grid, street,
+  city, state, postal, county, country`) before merging the result in, and
+  the guess adopts the more specific scope. `street` and `postal` are the
+  mailing address's own lines, grouped with the town they complete so an
+  address never puts one source's street on another source's town.
 - Otherwise, priority order applies as usual: a field already present in the
   guess is never overwritten by a later (lower-priority) result. A
   location field additionally requires the result's own scope to be at
@@ -231,13 +233,22 @@ interface LookupServiceHook {
 - Grid/lat-lon reconciliation, scoped to fields the result actually set:
   grid-only → lat/lon computed from the grid; lat/lon-only → a 6-digit grid
   computed from them; both given → taken verbatim. Setting grid/lat/lon
-  clears city/state/country/county unless the *same* result also supplies
-  them. The converse clause — a town write clearing grid/lat/lon — can only
+  clears street/city/state/postal/country/county unless the *same* result
+  also supplies them. The converse clause — a town write clearing grid/lat/lon — can only
   sweep a leftover half lat/lon pair: the group rule above blocks a town
   from landing at all where a full pin already stands.
 - `notes`/`history` are per-`CallInfoLookup` fields, not part of the merged
   `guess` — they simply accumulate, unconditionally, in the returned
   `lookups[]` array.
+- **`cqZone`, `ituZone` and `tz` are the exception to first-answer-wins.** The
+  pre-step can only answer them for a whole entity or call area (a W6 call
+  reads CQ zone 3 wherever the station lives), so once every hook has run,
+  a value the pre-step still holds goes to the first hook result that
+  carried one (`preferStationValues`) — only while the guess's scope is
+  `qth`, since on a portable or prefixed contact a source describes the
+  home QTH. `tz` is a UTC offset with its ordinary sign, `"GMT-5"` being
+  five hours behind; the SDK's `annotateCallAgainstCountryFile` flips the
+  country file's west-positive offsets to match.
 - **`locSource: 'prefix'` is reserved**, and a `lat`/`lon` merged under it is
   never read as a coordinate (`locationFromGuess`, halo_core). It marks
   lib-country-files' DXCC entity centroid, whose longitude follows cty.dat's
@@ -429,7 +440,8 @@ interface RefHandlerHook {
   linkForRef?(args: { ref: Ref }, ctx): Promise<RefLink | null>   // {url, label?}
   geojsonUrlForRef?(args: { ref: Ref }, ctx): Promise<RefGeojson | null>
 }
-// Ref: {type, ref?, name?, label?, shortLabel?, grid?, location?, program?, ...}
+// Ref: {type, ref?, name?, label?, shortLabel?, grid?, lat?, lon?, location?, program?,
+//       activationRadiusInMeters?, activationRadiusInFeet?, ...}
 // TitleSuggestion: {title?, for?, at?, subtitle?, priority?} — a fragment of
 // the operation's title/subtitle sentence (ham2k/halo-dist#174). Only
 // return one for the ref type that means "this operation is happening AT/FOR
@@ -517,6 +529,35 @@ SOTLAS's `az.sotl.as`, used with the operators' permission) and `pota` (both
 types, via `services.ham2k.net/lookups/outlines/pota/`, which links parks to
 OpenStreetMap shapes; a park not yet linked answers 404).
 
+**POTA is the one exception, and the core makes it, not the hook.** For a
+POTA suggestion's dashed outline the core skips `geojsonUrlForRef` and reads
+`services.ham2k.net`'s grid bundles instead — every outlined park touching a
+Maidenhead cell, simplified and clipped to it, one cached document per cell
+(500 m blocks below GL zoom 9, 10 m squares from 9). A long trail's whole
+outline runs to megabytes; its pieces in a cell, to kilobytes. The same
+bundles add to `suggest`'s answers the parks whose outline, not just whose
+point, is near: within 5 km for the nearby list, touching the view for a pan
+close in (from about GL zoom 10; see `suggest` below). An open card's POTA suggestion is drawn solid from the
+same pieces; the operation's own references still come from
+`geojsonUrlForRef`.
+
+**An activation radius is a circle, drawn the same way.** A reference that
+carries `activationRadiusInMeters` or `activationRadiusInFeet` — how far from
+its point the program lets an activator be — is circled on both maps, in the
+same color and under the same rules as an outline: solid for the operation's
+own references and the open card, dashed for the other suggestions once
+zoomed in. It is set on the reference itself, by `suggest` and `decorateRef`,
+because some programs set different distances by region or by kind of
+reference; a suggestion is stored on the operation verbatim, so the Map tab
+draws it too. Give whichever unit the rules are written in; meters win when
+both are set. It is drawn only around `lat`/`lon`, never around a `grid`,
+whose centre can sit further from the reference than the whole radius
+(docs/design/locations.md). A reference with an outline AND a radius draws
+both. A circle has no source, so it adds nothing to the map's outline credits
+and is not offered for an outline report. Programs built on the SDK's
+`referenceActivity` factory get this from one `activationRadius` config line —
+a value, or a function of the list row for rules that vary.
+
 `suggestOperationTitle` lets an activity build a natural-language operation
 title/subtitle from its refs — "at Yosemite NP" (POTA), "for Field Day"
 (contest programs, when ported) — mirroring app-polo's
@@ -647,7 +688,12 @@ an app that sends `bounds` answers that call, so an extension that calls it
 only then runs on older apps unchanged, and one that predates `bounds` answers
 with what is nearest the view's centre. Measure `distance` from the `location`
 given either way; the core re-measures a panned answer from the operation's own
-place before any card shows it. Called with no
+place before any card shows it. For POTA only, the core also adds the parks
+whose OUTLINE is near (from the grid bundles above) to the nearby list and to a
+pan, labelled by POTA's own `decorateRef`, and gives a park POTA already
+suggested the nearer of its point's and its outline's distance — so `pota`'s
+`suggest` keeps answering by point, and a trail whose point is a state away
+still reaches an operator standing on it. Called with no
 `searchTerm` for nearby suggestions, or with one for name/code search — an
 extension may honor either, both, or neither (returning `[]`). `scoped` is
 true when THIS extension alone was asked — the operator tapped its "Activity

package/package.json

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