@ham2k/extension-sdk 0.12.12 → 0.12.14

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.14
 /** 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;
 	};
@@ -1518,6 +1537,7 @@ export interface ExtensionManifest {
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
 	requiresRadioWrite?: boolean;
+	requiresRadioRaw?: boolean;
 	requiresClusterRead?: boolean;
 	requiresClusterSpot?: boolean;
 	requiresClusterCommand?: boolean;
@@ -1685,6 +1705,7 @@ export interface FormField {
 	itemFields?: FormField[];
 	itemTitle?: string;
 	orderable?: boolean;
+	itemSwitch?: string;
 	inline?: boolean;
 	itemLabel?: string;
 	defaultValue?: any[];
@@ -1786,6 +1807,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 +1823,7 @@ export interface SimpleSettingsPanel {
 	order?: number;
 	sidebar?: boolean;
 	dataFilesSection?: boolean;
+	section?: string;
 	fields: (SettingsField | FormActionElement)[];
 }
 export interface DynamicSettingsPanel {
@@ -2073,15 +2096,44 @@ export interface PanelRadioSet extends PanelRadioTarget {
 }
 /** @deprecated `setRadio`'s argument through extension API 6. */
 export type PanelRadioTune = PanelRadioSet;
+/**
+ * Commands in the radio's own protocol — exactly one of `text` or `bytes`, up to 4096 bytes
+ * (extension API 11). Where the app's driver keeps one question on the wire (CI-V, Yaesu binary,
+ * HRD, Commander, flrig) each command waits its turn in that queue, and on a FlexRadio is numbered
+ * like the driver's own; the reply is then the answers to these commands alone. Elsewhere the bytes
+ * are written as given. See hooks.md for what each protocol takes.
+ */
+export interface PanelRadioRaw extends PanelRadioTarget {
+	/** Sent as UTF-8: Kenwood, Yaesu and Elecraft ASCII, rigctld, N3FJP, SmartSDR, HRD, Commander, flrig. */
+	text?: string;
+	/** Each 0…255: Icom CI-V, Yaesu's binary protocol. */
+	bytes?: number[];
+	/**
+	 * How long to wait for the reply, up to 2000 ms; omitted or 0, the call answers once the commands
+	 * are handed to the driver. Where they are written as given, the reply is everything the radio
+	 * sent in that time — the answers to the app's own polls included.
+	 */
+	replyMs?: number;
+	/** Ends the reply early, just after the first occurrence of this text or these bytes. Needs `replyMs`. */
+	until?: string | number[];
+}
+export interface PanelRadioRawResult extends PanelRadioResult {
+	/** What came back within `replyMs`, possibly nothing, at most 64 KiB; absent without `replyMs`. `text` is it as UTF-8. */
+	reply?: {
+		text: string;
+		bytes: number[];
+	};
+}
 export interface PanelRadioResult {
 	/** Accepted by the host; confirmation still comes from reported state. */
 	accepted: boolean;
 	/**
 	 * `stopped`: a scope change while no display has the scope running — nothing was sent.
+	 * `busy`: eight raw commands to this radio are already waiting (extension API 11).
 	 * `unsupported`: this radio, or the app's keying, cannot do it — keying calls on a radio that
 	 * is not the logging radio, or with the app's keying off.
 	 */
-	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped" | "unsupported";
+	reason?: "changed" | "disconnected" | "transmitting" | "invalid" | "stopped" | "unsupported" | "busy";
 	state: PanelRadioState | null;
 }
 /** @deprecated `PanelRadioResult`'s name through extension API 6. */
@@ -2543,6 +2595,11 @@ export declare const host: {
 	}): Promise<PanelRadioResult>;
 	/** Stops all CW, voice and PTT the app is keying, and a tune it started (extension API 9), as Escape does. Needs `requiresRadioWrite` and extension API 7. */
 	stopRadioTransmit(args: PanelRadioTarget): Promise<PanelRadioResult>;
+	/**
+	 * Writes any command in the radio's own protocol — one that transmits included — and collects the
+	 * reply for `replyMs`. Needs `requiresRadioRaw` and extension API 11.
+	 */
+	sendRadioRaw(args: PanelRadioRaw): Promise<PanelRadioRawResult>;
 	/** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
 	clusterStatus(): Promise<ClusterStatus>;
 	/** The node's recent lines after `after`, oldest first, at most `limit` of the newest. Needs `requiresClusterRead` and extension API 10. */

package/dist/index.js

@@ -197,6 +197,13 @@ const host = {
   async stopRadioTransmit(args) {
     return await hostCallFn()("stopRadioTransmit", { ...args });
   },
+  /**
+   * Writes any command in the radio's own protocol — one that transmits included — and collects the
+   * reply for `replyMs`. Needs `requiresRadioRaw` and extension API 11.
+   */
+  async sendRadioRaw(args) {
+    return await hostCallFn()("sendRadioRaw", { ...args });
+  },
   /** The app's DX cluster connection, as Settings shows it. Needs `requiresClusterRead` and extension API 10. */
   async clusterStatus() {
     return await hostCallFn()("clusterStatus", {});

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`,
@@ -550,7 +573,7 @@ counts as the catalog's own here. The row and the details show the track, and
 the details' **Follow stable releases only** puts it back on stable; an
 uninstall or a file install clears it with the rest of the record.
 
-At most once every six hours — on launch and on resume — the app asks the
+At most once a day — on launch and on resume — the app asks the
 catalog whether anything installed has a newer release, and says so in the
 status bar and on the row; the notice comes down with the last update taken.
 It never installs unasked: the notice's **Update all** is the panel's own,

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?}
 ```
@@ -2079,7 +2115,9 @@ same shape as `requiresLocation`, and shown to the operator at install:
 `host.setRadioConnection()` and `host.setRadioSpectrum()` — and transmitting
 with them: `host.sendRadioCw()`, `host.playRadioVoice()`, `host.setRadioPtt()`
 and `host.stopRadioTransmit()` — and implies read, since a command answers with the
-radio's state. An undeclared call rejects rather than answering null.
+radio's state. `"requiresRadioRaw": true` (extension API 11) also allows
+`host.sendRadioRaw()`, any command in the radio's own protocol, and implies
+write. An undeclared call rejects rather than answering null.
 A capability belongs to the bundle that declared it, and to the sub-extensions
 that bundle defines under its own key. A separately installed bundle never
 inherits one through its name: `rigpanel-themes` gets nothing from `rigpanel`.
@@ -2195,6 +2233,61 @@ not paced, and not refused for a transmission in progress.
 connection using the same selection and identity checks. Acceptance starts the
 operation; follow reported connection state for completion. It does not switch
 the hardware's mains power or initiate transmission.
+
+`host.sendRadioRaw({id, selection?, text | bytes, replyMs?, until?})`
+(extension API 11, `requiresRadioRaw`) sends commands in the radio's own
+protocol — exactly one of `text`, sent as UTF-8, or `bytes`, each 0…255, up
+to 4096 bytes. **Nothing about them is checked.** They may transmit, change
+any setting or put the radio somewhere the app's own controls never would;
+that is what the operator agreed to at install, where the grant is shown in
+those words. It reaches any local radio through the same `id`/`selection`
+check as `setRadio`, with keying on or off, and is neither paced nor refused
+for a transmission in progress. One radio's calls go one at a time, in order,
+so that one call's reply window never holds the next one's answer, and past
+eight waiting the next is refused as `busy`; the app's own polls may come
+between two calls.
+
+- `replyMs`, up to 2000: how long to wait for the reply. Omitted or 0, the
+  call answers as soon as the commands are handed to the driver, with no
+  `reply`.
+- `until`, text or bytes, needs `replyMs`: the reply ends just after its first
+  occurrence.
+- The answer carries `reply: {text, bytes}`, possibly empty, at most 64 KiB,
+  with `text` its UTF-8 reading.
+
+What the commands are, and what the reply holds, is the protocol's. Where the
+app's driver keeps one question on the wire and reads the next reply as its
+answer, a raw command waits its turn in that queue — written beside it, its
+answer would be read as the answer to the driver's question — or, on a
+FlexRadio, is numbered as the driver's own are. The reply is then the answers
+to the raw commands alone, as the radio sent them, once each has come or the
+window closes:
+
+| Radio | Commands | Reply |
+|---|---|---|
+| Icom CI-V | `bytes`: whole frames, `FE FE` … `FD`, one at a time; the app addresses each to the radio from itself, whatever its address bytes say | each frame's answer frame (`FB`/`FA` or its data) |
+| Yaesu binary (FT-817/857/897) | `bytes`: five-byte commands | what the radio sends for each before it falls quiet; not read by the app |
+| FlexRadio | `text`: one command per line, without `C<seq>\|` — the app numbers each like its own | each one's `R` line |
+| Ham Radio Deluxe | `text`: one command per line, without the radio's context — the app adds it | each one's reply text, one per line |
+| DXLab Commander | `text`: one whole message (`<command:10>CmdGetFreq<parameters:0>`) | the field it is answered with; without `replyMs` it goes out as a set, waiting for nothing |
+| flrig | `text`: one XML-RPC call (`<?xml …?><methodCall>…`) — the app posts it | the response's body |
+
+Every other radio's commands are written as given — several back to back
+(`FA00014074000;MD2;`) in one write, none of the app's own between them —
+since each of their answers names what it answers: Kenwood, Elecraft and
+Yaesu ASCII, rigctld, N3FJP, Guohetec. The reply there is everything the
+connection received in the window, the answers to the app's own polls
+included, so `until` is worth setting.
+
+The app's driver still reads what the radio sends, so a raw command's effect
+shows in `readRadio` as a change made at the front panel would — and a command
+that confuses the driver confuses the app. A radio that is not connected
+answers `disconnected`; one whose driver takes no raw commands (a placeholder
+radio), `unsupported`; a malformed call, or commands that are not the
+protocol's (CI-V bytes that are not whole frames), `invalid`. A refusal heard
+within a second of a raw command on a protocol whose refusals name no command
+(`?;`, rigctld's `RPRT`) is taken as the raw command's, not counted against the
+app's own reads.
 On a host with the panadapter enabled, `readRadio()` carries `spectrum`: null
 for a radio without a scope, otherwise its settings as the radio reports them
 (`mode`, `spanHz`, `lowHz`/`highHz`, `refLevelDb`, `speed`), what it accepts
@@ -2386,6 +2479,39 @@ row/entry→`LookupRow` transform. See `DataFileManager`
 (`fetchType: 'raw'` — the parsed Hams of Note index is cached as JSON and
 replayed through `onLoadRawData` at startup, issue #17).
 
+### N1MM call history files
+
+N1MM Logger+'s call history files are uploaded to
+[n1mmwp.hamdocs.com](https://n1mmwp.hamdocs.com/mmfiles/categories/callhistory/)
+under a new name with every update (`CWOPS_4002.txt`), and downloaded by a
+form POST that carries a nonce from the file's own page, so no URL points at
+the current one. A `url` of `n1mm-history:<stem>` asks the host to find it
+(extension API 11):
+
+```ts
+{ key: 'cwops-history', url: 'n1mm-history:CWOPS', fetchType: 'raw', maxAgeInDays: 7, /* … */ }
+```
+
+- **Which file:** the newest one, by publish date, whose name is the stem or
+  the stem followed by `-` or `_` (extension and case aside). `CWOPS` takes
+  `CWOPS_4002.txt` and `CWOPS_4000-CCC.txt`, never `CWOPSOPEN_2026-002.txt`,
+  though N1MM's search lists all three; to follow one variant only, name it
+  (`n1mm-history:CWOPS_4000-CCC`). The search is read newest first, page by
+  page, until a page lists one of the stem's files.
+- **When:** N1MM sends no ETag; the chosen file's name, publish date and page
+  stand in for one, so a re-upload under the same name still counts as new. A
+  refresh whose newest file is the one last downloaded stops after the search,
+  like a 304. A forced refresh (RELOAD, Refresh) downloads it regardless.
+- **What arrives:** the file as served, in N1MM's format — a `!!Order!!,…`
+  column line, `#` comment lines, then CSV rows. `fetchType: 'raw'` is the one
+  that fits; `rawToJSONData` parses it. `url` in its arguments is the
+  `n1mm-history:` string, not the file's address.
+- **Failures:** a stem nothing matches, a refused download, or a page that no
+  longer has the shape the host reads fails the download with
+  `N1mmCallHistoryUnavailable` — a notice on a refresh the operator asked for,
+  an upload for the background passes. The requests and parsing are
+  `halo_core`'s `n1mm_call_history.dart`, shared by the app and the CLI.
+
 ### How CSV rows reach `csvToLookupEntry`
 
 An extension writes a **per-row** mapper; the kernel synthesizes the batch

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.14",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",