@ham2k/extension-sdk 0.12.12 → 0.12.13

package/dist/activityExports.js

@@ -53,8 +53,10 @@ function activityExportHook(rules) {
         filename: filenameFor(operation, qsos ?? [], ref.ref, compactFilenames),
         icon: rules.icon,
         selectedByDefault: true,
-        // Segment slicing: only the contacts made while this activity ran.
-        refType: rules.activationType
+        // Segment slicing: only the contacts made while THIS reference was
+        // being activated.
+        refType: rules.activationType,
+        ref: ref.ref
       }));
     },
     async generateExport(args, ctx) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.12.12
+// @ham2k/extension-sdk 0.12.13
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -597,6 +597,7 @@ export interface HookContext {
 	distanceUnits?: string;
 	decimalSeparator?: string;
 	groupingSeparator?: string;
+	dateOrder?: "mdy" | "dmy" | "ymd";
 	gridPrecision?: number;
 	edition?: string;
 	enabledExperiments?: string[];
@@ -703,6 +704,7 @@ export interface PostResult {
 	ok: boolean;
 	message?: string;
 	userMessage?: ResultMessage;
+	skipped?: boolean;
 }
 export interface ResultMessage {
 	presentation: "status" | "dialog";
@@ -869,6 +871,7 @@ export interface TextInputDescriptor {
 	}[];
 	numeric?: boolean;
 	uppercase?: boolean;
+	numbersRowKey?: string;
 	maxLength?: number;
 	suggestedValue?: string;
 }
@@ -890,6 +893,7 @@ export interface OptionsInputDescriptor {
 	minCharsForSuggestions?: number;
 	placeholder?: string;
 	uppercase?: boolean;
+	numbersRowKey?: string;
 	maxLength?: number;
 	suggestedValue?: string;
 	pattern?: string;
@@ -910,6 +914,7 @@ export interface RefListInputDescriptor {
 		replacement: string;
 		flags?: string;
 	}[];
+	numbersRowKey?: string;
 }
 export interface ActivitySuggestion extends Ref {
 	distance?: number;
@@ -1004,6 +1009,7 @@ export interface ExportRequest {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
+	events?: Record<string, JSONValue>[];
 	exportType?: string;
 	exportKey?: string;
 	compactFilenames?: boolean;
@@ -1037,6 +1043,7 @@ export interface ExportOption {
 	priority?: number;
 	selectedByDefault?: boolean;
 	refType?: string;
+	ref?: string;
 }
 export interface ExportHook {
 	getExportTypes?(args: Record<string, never>, ctx: HookContext): Promise<ExportTypeDefinition[]>;
@@ -1278,9 +1285,21 @@ export interface CommandAction {
 		kind: "start" | "break" | "stop";
 		setLocation?: boolean;
 	};
+	findInLog?: {
+		query?: string;
+	};
 	setCallField?: {
 		text: string;
 	};
+	setTime?: {
+		now?: boolean;
+		deltaMillis?: number;
+		hour?: number;
+		minute?: number;
+		second?: number;
+		month?: number;
+		day?: number;
+	};
 	reloadDataFiles?: {
 		target: string;
 	};
@@ -1685,6 +1704,7 @@ export interface FormField {
 	itemFields?: FormField[];
 	itemTitle?: string;
 	orderable?: boolean;
+	itemSwitch?: string;
 	inline?: boolean;
 	itemLabel?: string;
 	defaultValue?: any[];
@@ -1786,6 +1806,7 @@ export interface SettingsPanelDescriptor {
 	order?: number;
 	sidebar?: boolean;
 	dataFilesSection?: boolean;
+	section?: string;
 }
 export interface SettingsField extends Omit<FormField, "validate" | "transform" | "itemFields"> {
 	pattern?: string;
@@ -1801,6 +1822,7 @@ export interface SimpleSettingsPanel {
 	order?: number;
 	sidebar?: boolean;
 	dataFilesSection?: boolean;
+	section?: string;
 	fields: (SettingsField | FormActionElement)[];
 }
 export interface DynamicSettingsPanel {

package/dist/settingsPanels.js

@@ -18,7 +18,8 @@ function settingsPanelEntriesFor(record, descriptors) {
         order: hook.order ?? null,
         kind: "simple",
         sidebar: hook.sidebar ?? true,
-        dataFilesSection: hook.dataFilesSection ?? false
+        dataFilesSection: hook.dataFilesSection ?? false,
+        section: hook.section ?? null
       }
     ];
   }
@@ -33,7 +34,8 @@ function settingsPanelEntriesFor(record, descriptors) {
         order: d.order ?? null,
         kind: "dynamic",
         sidebar: d.sidebar ?? true,
-        dataFilesSection: d.dataFilesSection ?? false
+        dataFilesSection: d.dataFilesSection ?? false,
+        section: d.section ?? null
       }));
     }
     return [
@@ -46,7 +48,8 @@ function settingsPanelEntriesFor(record, descriptors) {
         order: null,
         kind: "dynamic",
         sidebar: true,
-        dataFilesSection: false
+        dataFilesSection: false,
+        section: null
       }
     ];
   }

package/docs/distribution.md

@@ -388,7 +388,7 @@ The app builds in only its **core** extensions — the ones that are the app
 itself: `adif`, `scoring`, `lookups`, `templates`, the command sets and
 `ham2k-lofi` sync. Every other extension is a catalog bundle, and the app ships
 some of them already packaged under `app/assets/preloaded-extensions/`,
-installing them into the ordinary store on first run. Afterwards they are
+installing the ones the operator has switched on into the ordinary store. Afterwards they are
 ordinary installed extensions — the same rows, the same update check, the same
 Update and uninstall — so an operator starts with a working app and the catalog
 can move it forward from there.
@@ -416,7 +416,30 @@ ship pre-loads that fail the check ([releases.md §6.4](https://github.com/ham2k
 They are installed once, not every launch. A record of the highest version
 ever pre-loaded per key is what makes that true: an app update carrying a
 newer bundle installs it, a catalog release already ahead of it is left
-alone, and a key the operator uninstalled stays gone.
+alone, and a key the operator uninstalled stays gone — its uninstall leaves
+its switch off, which is what the pre-load asks before installing a newer copy.
+
+**Only what is switched on is installed** — by the operator's choice for the
+key, else its built-in's, else on. One switched off would be a dead row in the
+Extensions panel, and for a new install that is most of them. Skipped, it is
+not recorded as offered, so switching on one never offered brings it in; one
+already offered comes back from the catalog. A shipped key's switch is kept
+after it leaves the store, and an uninstall or a Forget leaves it off, so an
+app update carrying a newer copy does not bring back one the operator
+removed. Nothing is
+installed until onboarding has been answered, since the activities it asks
+about are pre-loads: installed on their defaults first, whichever the operator
+then turns down would stay installed and switched off. Onboarding settles them
+as it finishes (`settleOnboardingExtensions`), as `ONBOARD_AS` does.
+
+An install can hold every bundle the app ships, whatever its switch. It takes
+the pre-loaded bundles and built-ins' twins it holds switched off out of the
+store once (`extensionsSwitchedOffRemoved`), keeping their settings,
+credentials and switch for a reinstall, and records that done only once it has
+read the whole store. Other catalog extensions are the operator's own and stay,
+as do file installs. A replayed onboarding (DEVONBOARD) removes nothing. A
+catalog install the operator makes is always switched on, whatever switch it
+inherits.
 
 An installed bundle may not claim a key the app builds in, and a pre-load is
 no exception: it goes through the same door as any other install.
@@ -445,8 +468,8 @@ a callsign before its extension state was first recorded
 a build without them, unasked: there is nothing left to run instead. The boot's
 catch-up (`catchUpOnCatalogExtensions`) carries each built-in's on/off choice
 onto its twin, over whatever an earlier attempt left there; installs the
-pre-loads, which carry the built-in's settings, panel values and credentials on
-a twin's first install, and its default where the operator never chose; then
+pre-loads switched on, which carry the built-in's settings, panel values and
+credentials on a twin's first install; then
 fetches the twin of any other built-in the operator had switched on. It records
 the move done once the pre-load has run, so a boot killed half way carries the
 choices again next time. It needs no network while every twin is pre-loaded.
@@ -469,8 +492,8 @@ refuses the bundle itself: a keychain that would not open or a full disk is
 tried again next launch, and meanwhile the adoption fetches the catalog's copy
 if the operator had it on. A twin the pre-load did install is never fetched
 back after the operator uninstalls it. A choice stored under the pre-load's own
-name — `ham2k-lookup`'s, which kept its name — is kept rather than dropped as
-stale.
+name — `ham2k-lookup`'s, which kept its name — decides whether it is installed,
+and is kept rather than dropped as stale.
 
 **What does not come along.** A few built-ins have no twin on purpose — `qp`,
 which the catalog carries as one extension per party instead, and `stateparks`,

package/docs/forms.md

@@ -66,15 +66,20 @@ export interface FormField {
   // Record<string, any>[]; each item is shaped like itemFields. By default
   // the field renders as one summary row (from itemTitle, templated
   // against the item's values, e.g. "${name}" — NOT "{{name}}") that opens
-  // an editor dialog with per-item rows and add/edit/delete; `inline: true`
-  // instead renders those rows (with reorder handle/delete per row, and an
-  // Add row) directly in the form, skipping that outer dialog — for a list
-  // that's the main content of its own section. Either way, tapping a row
-  // (or Add) opens the same itemFields editor dialog (the form renderer
-  // recursively, scoped to itemFields).
+  // an editor dialog with per-item rows and Add; `inline: true` instead
+  // renders those rows (with a reorder handle per row, and an Add row)
+  // directly in the form, skipping that outer dialog — for a list that's the
+  // main content of its own section. Either way, tapping a row (or Add)
+  // opens the same itemFields editor dialog (the form renderer recursively,
+  // scoped to itemFields), whose footer holds Delete for an existing item,
+  // which asks the operator to confirm.
   itemFields?: FormField[];
   itemTitle?: string;
   orderable?: boolean;
+  // The key of an on/off value in each item, set from a switch at the end of
+  // the item's row; leave it out of itemFields. An item without the key reads
+  // as on. An app that predates this shows no switch.
+  itemSwitch?: string;
   inline?: boolean;
   // Singular noun for one item (e.g. "custom note file"), used in the
   // editor dialog's Add/Edit titles and the Add button instead of `label`

package/docs/hooks.md

@@ -309,7 +309,7 @@ interface SpotsHook {
 // Spot: {their: {call}, freq?, band?, mode?, refs?: Ref[],
 //        spot: {timeInMillis, source, label?, sourceInfo?}}
 // SpotEligibility: {enabled, icon?}
-// PostResult: {ok, message?}
+// PostResult: {ok, message?, userMessage?, skipped?}
 // PostSelfSpotRequest: {operation, freq, mode?, comment?}
 // PostOtherSpotRequest: {qso, comment?, spotterCall?}
 ```
@@ -330,6 +330,15 @@ directly to the POTA API, no auth required). `sota`'s spot API requires an
 authenticated account app-halo doesn't have yet, so `sota` stays
 fetch-only for now.
 
+A poster whose own rules decline a particular spot — a Discord channel whose
+message template renders blank for it — answers `{ok: true, skipped: true}`.
+Its icon stays neutral gray instead of lighting as sent, and no failure is
+reported. The Spotting chip's color counts only the sources that did not skip.
+When every one did, the chip stays neutral and the operator is told so, in
+each source's `message` when it gives one; that spot is never what
+auto-respotting repeats, and a round of it every source skips ends it.
+`skipped` without `ok` is still a failure.
+
 ## ✅ `cluster` — the DX cluster connection
 
 ```ts
@@ -381,11 +390,17 @@ interface ExportHook {
   generateExport(args: ExportRequest, ctx): Promise<ExportResult>
 }
 // ExportOptionsRequest: {operation, qsos, compactFilenames?}
-// ExportOption: {exportType, exportKey?, format, label, filename?, icon?, color?, refType?, priority?, selectedByDefault?}
-// ExportRequest: {operation, qsos, exportType?, exportKey?, compactFilenames?}  — full QSON, one coarse call
+// 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}
 ```
 
+`qsos` holds contacts alone. The log's event rows — `break`, `start`, notes —
+come separately in `events`, for a file that writes the timeline (the full
+ADIF does, with private data); `segments` is what they resolve to.
+`operation` carries `startAtMillisMin`/`startAtMillisMax`: the span of the
+contacts in `qsos`, not of the whole operation.
+
 Two-step flow: the Exports Panel calls `suggestExportOptions` on every
 `export` hook to build its selectable list (a hook that omits it never
 appears in the panel), then calls `generateExport` — passing back the
@@ -471,6 +486,12 @@ whole-log ADIF — asks for a glyph of its own instead of borrowing one. An
 `icon` name that doesn't resolve falls back to the activity's, same as an
 unreadable `color` does.
 
+**One reference's file.** An export claiming one reference of its `refType` —
+one park's log, when the operation activated several — names it in `ref`, and
+the core narrows the slice to the segments carrying that reference. Without
+it, a park activated after a break gets every contact made at the park before
+it. `activityExportHook` sets it for you.
+
 **Filenames.** Build them with the SDK's `exportFilename` rather than
 spelling one out, passing the request's `compactFilenames` straight through —
 that is what makes the user's "Use compact file names" setting apply to your
@@ -491,7 +512,7 @@ filename: exportFilename({
 Set `filename` on the OPTION, not just on the result: the panel shows the
 option's name, and the core writes the file under it. A name computed again
 in `generateExport` sees a different input — that call is handed only the
-QSOs the option's `refType` covers — so the two would otherwise disagree in
+QSOs the option's `refType` (and `ref`) covers — so the two would otherwise disagree in
 front of the user.
 
 ## ✅ `ref:<type>` — reference handlers
@@ -681,14 +702,15 @@ interface ActivityHook {
 // The input catalog. A new kind is earned by a different WIDGET, never by
 // different validation — so a pattern-constrained field is `text` with a
 // `pattern`, not a kind of its own (docs/design/contests.md §5.3).
-//   {kind: 'refList', refType, placeholder?, pattern?, transforms?}
+//   {kind: 'refList', refType, placeholder?, pattern?, transforms?,
+//                     numbersRowKey?}
 //   {kind: 'text',    refType, field, placeholder?, pattern?, transforms?,
-//                     numeric?, uppercase? /* default true */, maxLength?,
-//                     suggestedValue?}
+//                     numeric?, uppercase? /* default true */, numbersRowKey?,
+//                     maxLength?, suggestedValue?}
 //   {kind: 'options', refType, field, options: [{code, name?}], matchOn?,
 //                     allowFreeform?, preferredCodes?, minCharsForSuggestions?,
 //                     placeholder?, pattern?, transforms?, numeric?, uppercase?,
-//                     maxLength?, suggestedValue?}
+//                     numbersRowKey?, maxLength?, suggestedValue?}
 //   {kind: 'serial',  refType, field, sequence: {key, scope?, start?, padTo?},
 //                     editable?}
 //   {kind: 'form',    refType, form}   // operationControls only
@@ -700,6 +722,12 @@ interface ActivityHook {
 // exports as typed. The pattern is HaLo's idea of the program rather than the
 // program's own, so it may never cost the operator a reference.
 //
+// `numbersRowKey` is the one character the mobile numbers row offers after
+// its digits while the field has focus, where the operator would otherwise
+// switch keyboard layers for it. Without it a `refList` field offers `'-'`,
+// which joins most programs' prefixes to their digits, and the other kinds
+// the operator's decimal separator.
+//
 // `text`, `options` and `serial` values round-trip onto a ref of `refType` under
 // `field`, through the same core-owned path refList writes refs — several may
 // share one refType and are merged into a single ref. `suggestedValue` fills the
@@ -919,6 +947,14 @@ returning several is describing individual records. Declaring both methods is
 fine and expected — a hook that does is asked only for its combinations, so
 its plain fields aren't written twice. Implemented by: `pota`.
 
+Only a program's **own** export asks for combinations. The full ADIF export is
+one record per contact — the copy the operator keeps, which a reimport or a
+log processor must not read as several contacts — so it asks every hook for
+`fieldsForOneQSO` alone, as app-polo's does. A splitting program answers that
+method too, for the one record — POTA names its first hunted park in `SIG_INFO`
+and every one in `POTA_REF`. A hook answering only combinations is left out of
+the full export, and the kernel logs an error for it as it activates.
+
 **Only the export's OWN hook is asked.** A file submitted to one program is
 that program's log, so an export that delegates the ADIF build names itself as
 `mainHandler` in the `ExportRequest` — app-polo's "main handler"
@@ -992,9 +1028,9 @@ writes the contact's own operator on every record, falling back to the station
 call's base call or the station call itself. This is a
 deliberate divergence from app-polo, whose contact fields come first and whose
 main handler's are appended unchecked, so a name both answer is written twice. The **full export**, which asks every
-program on the contact, has no such order: hooks answering `fieldCombinationsForOneQSO` are asked as one
-group and hooks answering `fieldsForOneQSO` as another, so which of two programs
-keeps a shared `MY_SIG` there is not something either of them chose.
+program on the contact, has no main handler to order by: hooks are asked in priority order,
+so which of two programs keeps a shared `MY_SIG` there is not something either
+of them chose.
 
 Because the winner is picked per field name, **answer a pair whole or not at
 all**: a hook offering `MY_SIG` without `MY_SIG_INFO` takes the name and leaves
@@ -1113,7 +1149,7 @@ interface CommandHook {
 // CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
 //   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, autoRespot?, syncAll?, updateSettings?, updateSetting?, openSettings?,
-//   updateOperation?, markSegment?, setCallField?, reloadDataFiles?, devNotice?, devStatus?,
+//   updateOperation?, markSegment?, findInLog?, setCallField?, setTime?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
 ```

package/docs/settings.md

@@ -79,13 +79,19 @@ export interface SimpleSettingsPanel {
   // below — this only controls the top-level nav.
   sidebar?: boolean;
   // Defaults false. Set true to also show this panel as a row in the Data
-  // Files screen's own "Extensions" section — the ONLY host-recognized
-  // alternate surface today, so leave this false for anything not actually
-  // about managing data files. Independent of `sidebar`; a panel usually
-  // wants both false-then-true, but the two aren't coupled at the type
-  // level — inferring this from `sidebar: false` alone would sweep any
-  // sidebar-opt-out panel in here.
+  // Files screen's own "Extensions" section — leave this false for anything
+  // not actually about managing data files. Independent of `sidebar`; a
+  // panel usually wants both false-then-true, but the two aren't coupled at
+  // 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
+  // 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;
   fields: (SettingsField | FormActionElement)[];
 }
 ```
@@ -136,6 +142,7 @@ export interface SettingsPanelDescriptor {
   order?: number;
   sidebar?: boolean; // see SimpleSettingsPanel.sidebar above; defaults true
   dataFilesSection?: boolean; // see SimpleSettingsPanel.dataFilesSection above; defaults false
+  section?: string; // see SimpleSettingsPanel.section above
 }
 
 export interface DynamicSettingsPanel {
@@ -204,7 +211,14 @@ values). Tapping it opens an editor dialog with a row per item plus an
 dialog. Editing or adding an item opens the same form renderer
 recursively, scoped to `itemFields`, in a nested dialog — there is no
 separate "list item editor" widget, just `FormRenderer` given a smaller
-`FormDefinition`.
+`FormDefinition`. An existing item is deleted from that dialog's footer,
+once the operator confirms.
+Saving it merges what it edited into the item, so keys it has no field
+for are kept.
+
+Set `itemSwitch` to the key of an on/off value in each item to give every
+row a switch for it, and leave that key out of `itemFields`. An item without
+it reads as on.
 
 Set `orderable: true` to allow drag-to-reorder in the editor; omit it for
 lists where order doesn't matter.

package/package.json

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