@ham2k/extension-sdk 0.2.0 → 0.3.0

package/dist/templateContext.js

@@ -26,6 +26,10 @@ function opValues(operation, extra = {}) {
   return {
     ...atMillis > 0 ? dateValues(atMillis) : { date: "", dateCompact: "", time: "", at: "" },
     station,
+    // `call` says the same thing, for symmetry with `qso.call` — the name an
+    // operator writing a CW message reaches for first; without it,
+    // `{{ op.call }}` renders empty with nothing to say why.
+    call: station,
     // Deduped, like halo_core's `Operation.stationCalls`: "N0DEV, N0DEV" is a
     // typo, and a template fanning out over this would otherwise repeat
     // itself once per typo.

package/docs/distribution.md

@@ -47,7 +47,7 @@ The same manifest a built-in extension carries, plus `api`:
 it does not speak, so an older app meeting a newer bundle says so instead of
 failing somewhere deep in a hook.
 
-Two fields are **refused** in a distributed bundle, and it is worth
+Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
 
 - **No `category`** makes an extension *core* to the host: always enabled, and
@@ -57,6 +57,79 @@ understanding why:
 - **`experiments`** gates availability against the *app's* experiment catalog.
   A key the host doesn't define hides the extension permanently, with nothing
   in the UI to explain it.
+- **`enabledByDefault`** is a shipping app's answer for the extensions it
+  carries whether the operator asked for them or not. An installed bundle is
+  one the operator went and got, so the answer is always yes, and a manifest
+  saying otherwise describes a state it cannot reach.
+
+**`geo` is now `relevance`**, and a manifest still carrying the old name is
+refused at packing and at publishing rather than ignored. Nothing reads
+`geo`, and no check anywhere looks at unknown top-level keys, so accepting it
+would publish a regional extension as a worldwide one and tell its author
+nothing. Rename the key; the four geographic lists inside it are unchanged.
+
+The app itself does NOT refuse either of these at install. The packer and the
+catalog answer to the author, who can fix the manifest and publish again;
+refusing at the door tells the operator instead, who can do nothing about a
+published manifest but go without an extension that would have worked — and
+every bundle published before these rules existed carries one. Neither costs
+them anything: an installed extension is enabled because they installed it,
+and an unread `geo` makes it worldwide rather than regional. What the app
+refuses is what it cannot run.
+
+### Relevance
+
+`relevance` says where, when and for whom the extension matters. The catalog
+ranks its listing by it, for the operators the extension was written for, and
+the Extensions panel's Catalog section shows the catalog's rows in that
+order; nothing hides an extension over it, and a manifest without one is
+worldwide and undated. The build index carries `relevance` for the catalog
+and for later use; the panel does not rank the app's own extensions by it.
+
+```json
+"relevance": {
+  "countries": ["us"],
+  "dates": ["2026-09-19", "2027-09-18"],
+  "interests": ["cw"]
+}
+```
+
+**Where.** Four lists, each an allowlist over the operator's own callsign:
+`entities` (DXCC prefixes as the country file names them: `K`, `VE`, `CE`),
+`countries` (ISO alpha-2: `us`, `cl`), `continents` (`AF AS EU NA OC SA AN`)
+and `ituRegions` (`1`, `2`, `3`). A missing or empty list does not gate;
+values within a list are ORed, the lists ANDed; case is the matcher's job.
+These are the geo keys of HaLo's notices, rule for rule.
+
+**When.** `dates` lists the UTC days the extension's events start, as
+`YYYY-MM-DD`. Start days, not spans: a reader asking "is this soon" needs no
+more, and the extension's own code stays the only place that knows when an
+event opens and closes to the minute. An event on a fixed calendar lists the
+occurrences it knows about; one that runs to a weekly rule lists none,
+because a list that must be right every week is a list that goes stale. An
+absent or empty `dates` says nothing about timing — never "never".
+
+**For whom.** `interests` draws on a closed vocabulary: the modes `cw`,
+`phone`, `digital`; the band groups `hf`, `vhf`, `uhf`, `microwave`; the
+styles `satellite`, `portable`, `qrp`. Only for an extension *dedicated* to
+one — a contest that permits CW is not a `cw` extension, while the CWops CWT
+is. Listing what an extension merely allows makes every interest match
+everything, which is the same as listing none. The list is closed because an
+interest nothing else spells the same way matches nobody while looking like
+it works.
+
+The packer refuses:
+
+- a `relevance` that is not an object, or a key inside it other than those six;
+- a list that is not a list, or an element that is not a non-empty string;
+- a continent outside `AF AS EU NA OC SA AN`, or an ITU region outside `1`–`3`;
+- a country that is not two letters, or an entity prefix that is not letters,
+  digits and `/` (with an optional leading `*`);
+- a date that is not `YYYY-MM-DD`, or that names a day which does not exist;
+- an interest outside the vocabulary above.
+
+The matcher reads a key it cannot parse as "does not gate", so each of the
+shape errors would otherwise ship the bundle as worldwide.
 
 ## Using the host's libraries
 
@@ -95,6 +168,15 @@ The host checks those before loading, and refuses a bundle it cannot satisfy —
 which is a message naming the library and both versions, instead of a call
 failing somewhere deep in a hook against a major you never tested.
 
+**Declare the version you actually build against, not the oldest that
+compiles.** That check compares versions, and cannot see which *functions* a
+version has. A library that gained an export — `qsonToCabrillo` arrived in
+`@ham2k/lib-qson-cabrillo` 1.2.0, whose earlier releases only read Cabrillo —
+satisfies a `^1.0.0` declaration on a host too old to have it, so the bundle
+installs, loads, and throws the first time an operator asks for the feature
+that needs it. The build's own message suggests the version installed beside
+you for exactly this reason; take it rather than rounding down.
+
 The packer refuses a bundle that reaches for a shared module **without**
 declaring it, and one that declares a package the host doesn't carry. Anything
 outside that list you bundle yourself, as normal.
@@ -262,6 +344,80 @@ from whoever it claims; it is not worth it while a key is all there is.
 
 Removing an extension removes what it stored with it.
 
+### Installing from a link
+
+A web page can hand the app a bundle to install:
+
+```
+com.ham2k.logger:///install_extension?url=https://example.org/my-ext.h2kext
+```
+
+Every edition of Ham2K Logger answers that scheme, so on a device with more
+than one installed the platform decides which one opens; the catalog keeps a
+plain download link beside its install button for that reason. The
+edition-specific `com.ham2k.logger.dev` / `.next` / `.prod` schemes exist
+but a link should not need them. The URL must be `https`, redirects are followed by hand and refused the
+moment one leaves `https`, and the consent screen names the host the bytes
+came from. Nothing is written until the operator agrees.
+
+### Pre-loaded extensions
+
+The app ships eight of the catalog's own extensions already packaged, under
+`app/assets/preloaded-extensions/`, and installs them into the ordinary store
+on first run: `ham2k-pota`, `ham2k-sota`, `ham2k-wwff`, and the five lookups.
+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.
+
+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.
+
+Each one that renames a built-in — `ham2k-pota` is the built-in `pota` under
+a name the catalog can serve — carries the operator's settings, panel values
+and account credentials across on its first install. Copied, not moved: the
+built-in's own state stays where it is.
+
+One rule bends for these, and only for them:
+
+- **Built-in collisions.** An installed bundle may not claim a key the app
+  ships — judged against what the app is currently OFFERING, which under the
+  catalog experiment is the core extensions and nothing else. `ham2k-lookup`
+  is both a built-in and a pre-load, and could otherwise never install.
+
+**Build secrets are not among them, and used to be.** A pre-load holding a
+`ham2k-` key could once read the values its name granted. Nothing needs that
+now: every value it carried — SOTA's OAuth client id, WWFF's API key — ships
+as a constant inside the extension that uses it, because these bundles are
+served to anyone who asks and a `.h2kext` is a zip. An installed extension
+sees no build secret, whatever key it claims and wherever it came from.
+
+### Installing from the catalog
+
+**Settings → Extensions → Catalog** lists what [catalog.ham2k.net](https://catalog.ham2k.net)
+publishes on its `stable` channel, in the catalog's own order for the
+operator's callsign (`relevance`, above). Install and Update go through the same consent screen as a
+file, over bytes that must hash to the sha256 the listing gives — a mismatch
+is refused before the zip is opened. A bundle that arrived this way is
+recorded as such (`extensionInstalledFrom`: host, sha256, version), and that
+record is what lets it carry a `ham2k-` key: the rule that refuses the prefix
+to a file stands, waived on every read only for a key whose record names
+`catalog.ham2k.net`, and cleared by an uninstall or by a file install of the
+same key. A key the app ships stays refused whatever the catalog says. The
+catalog's own bundle links (`…/api/v1/extensions/<key>/versions/<version>/bundle`)
+take this verified path when they arrive as a deep link; every other host
+takes the plain one above.
+
+At most once every six hours — 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. A release the catalog has revoked is put on record
+(`extensionRevoked`: version and note) and stops loading on the spot,
+whatever the operator's own switch says — the row shows "Revoked" with the
+note and no switch, and the record dies with an install of another version
+or an uninstall.
+
 ## What is checked at install
 
 Beyond what the packer already refused:
@@ -269,6 +425,8 @@ Beyond what the packer already refused:
 - the key is not one the app ships, and does not begin `ham2k-`;
 - the `api` version is one this build speaks;
 - every `sharedDependencies` range is satisfied by what this build carries;
+- `relevance`, if present, passes the packer's rules — the shape the matcher
+  reads and its vocabulary — applied again by `ExtensionRelevance.validate`;
 - entry names are sanitised on extract, so `../` in one writes nothing.
 
 Each has its own message. A bundle that cannot be installed says why.
@@ -276,4 +434,12 @@ Each has its own message. A bundle that cannot be installed says why.
 ## Native only, for now
 
 Installed bundles are files on disk. On web the app runs from its own assets
-and, for authors, the dev server — [development.md](https://github.com/ham2k/halo/blob/main/docs/extensions/development.md).
+and, for authors, the dev server — [development.md](https://github.com/ham2k/halo/blob/main/docs/extensions/development.md). So on
+web there is nothing to install into: no install from a file, no install or
+update from the catalog, and none of the pre-loaded extensions above.
+
+"For now" is a deferral, not a fact about the platform. Almost everything
+here is already platform-neutral — the zip walk, the manifest rules, the
+consent screen, the hash check — and what is left is a persistence seam of
+about six operations. `HALO-583` is the card that picks it up, and says what
+has to be decided first.

package/docs/forms.md

@@ -70,8 +70,8 @@ export interface FormField {
   // fields — a whole section header can be dev-mode-only too.
   devMode?: boolean;
   // Settings-panel-only (ignored in ad hoc forms) — see settings.md's
-  // "Common Preferences and environment gating". Also shows this field on
-  // the app's Common Preferences quick-access panel.
+  // "Common Settings and environment gating". Also shows this field on
+  // the app's Common Settings quick-access panel.
   common?: boolean;
   // Settings-panel-only. Restricts which platform(s) show this field at
   // all: one or more platform tokens (`ios`, `android`, `macos`,
@@ -93,6 +93,14 @@ export interface FormHeader {
   type: 'header';
   title: string;
   subtitle?: string;
+  // How the heading is drawn. Omitted, it is plain text above the fields
+  // that follow. 'section' is the app's section band — the accent title
+  // over a hairline, which holds the top of the surface while its own rows
+  // scroll under it. 'category' is the FILLED band, for a heading that is
+  // the top-level grouping of its surface rather than one section inside
+  // one (docs/design/user-interface.md § Settings lists). A settings panel
+  // is already inside a category, so its own headings take 'section'.
+  style?: 'default' | 'section' | 'category';
   devMode?: boolean;
   environment?: string | string[]; // settings-panel-only; see FormField.environment (not `common` — see settings.md)
 }

package/docs/hooks.md

@@ -29,6 +29,10 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   whole-extension `manifest.experiments` grain would also hide any other
   hook the same extension registers (e.g. `radio-commands`' POWER command
   checks `gato` here; its BAND/MODE/frequency siblings don't).
+* `experiments?: { key, name, aliases }[]` — The experiment catalog itself,
+  on or off, so a hook can resolve a typed key-or-alias to one of the keys
+  `enabledExperiments` lists (the EXP preview says "Enable"/"Disable" rather
+  than "Toggle"). The app remains the authority when it flips the state.
 * `getOperation?(uuid)` / `getQsos?(operationUuid)` — log-data reads, for
   hooks that only receive part of the picture as arguments (e.g. a `command`
   hook handed the operation it's typed into, needing the existing QSOs —
@@ -170,12 +174,23 @@ interface LookupServiceHook {
   least as specific as the guess's current scope — a more general-scoped
   result can never populate a slot a more specific one already claimed,
   even if that slot is currently empty.
+- Location fields merge as a group, never per field. A same-scope result
+  bringing a pin (a grid, or a full lat/lon pair) to a guess that has none
+  replaces the established city/state/county/country/location with its own
+  values (or just clears them, if it carries only the pin) — even where
+  per-field priority would have kept the earlier town. A result whose own
+  pin loses to an already-established one contributes no location fields at
+  all, and a pinless result's town is used only where the higher-priority
+  lookups left no town or pin (an entity-level `country` alone doesn't
+  count as located): a town is never spliced with a pin — or a town half —
+  it wasn't reported with.
 - 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; conversely, setting city/state/country (without county, and without
-  also setting grid/lat/lon in the same result) clears grid/lat/lon.
+  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.
@@ -237,7 +252,7 @@ interface ExportHook {
   generateExport(args: ExportRequest, ctx): Promise<ExportResult>
 }
 // ExportOptionsRequest: {operation, qsos, compactFilenames?}
-// ExportOption: {exportType, format, label, filename?, icon?, priority?, selectedByDefault?}
+// ExportOption: {exportType, format, label, filename?, icon?, color?, refType?, priority?, selectedByDefault?}
 // ExportRequest: {operation, qsos, exportType?, compactFilenames?}  — full QSON, one coarse call
 // ExportResult:  {filename, mimeType, content}
 ```
@@ -251,6 +266,15 @@ Exporters should compose per-QSO program fields from `adifFields` hooks (see
 below) rather than knowing about specific activities. Implemented by: `adif`
 (key `adif`, one option); Cabrillo will register here too.
 
+**How a row looks.** `refType` names the activity the export covers — the
+core slices the file's QSOs by it, and the panel takes the row's icon and
+accent colour from that activity's own control, so a contest's file is
+recognisably the contest's without saying anything about glyphs. `icon` and
+`color` override that, and are how an export that claims no activity — the
+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.
+
 **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
@@ -280,6 +304,11 @@ One category **per ref type** (e.g. `ref:pota`, `ref:potaActivation`),
 following app-polo's QSON conventions. Handles validation and enrichment of
 activity references on QSOs and operations.
 
+`registerHook` takes the type alone. The **qualified** `ref:<type>/<code>` form
+is a manifest claim, not a category — it tells the host which legacy reference
+an extension answers for so it can rewrite one (docs/extensions/README.md), and
+registering a hook under it would register a category nothing ever invokes.
+
 ```ts
 interface RefHandlerHook {
   validateRef?(args: { ref: Ref }, ctx): Promise<{valid: boolean; normalized?: string}>
@@ -400,7 +429,10 @@ interface ActivityHook {
 //
 // `pattern` is anchored (`^(?:…)$`) and matched case-insensitively for every
 // kind; a malformed regex disables validation rather than throwing. A
-// mismatch tints the field but still accepts the value.
+// mismatch tints the field but still accepts the value — a `refList` segment
+// that fails it becomes a ref like any other, and reaches the log and the
+// 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.
 //
 // `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
@@ -432,8 +464,9 @@ an unrecognized name falls back to a placeholder glyph rather than erroring.
 
 `color` is an optional `'#RRGGBB'` accent (e.g. POTA's `'#068541'`) the core
 may use sparingly to highlight this control's icon — a tinted circle behind
-it in the Activities picker, or the icon itself once a reference is entered
-in the logging panel's secondary pills. Missing or unrecognized values just
+it in the Activities picker, the icon itself once a reference is entered
+in the logging panel's secondary pills, or the reference icon on a spot row
+whose ref is of this control's type. Missing or unrecognized values just
 mean no accent.
 
 `processQsoBeforeSave` is the last chance to shape a QSO before it is written,
@@ -441,7 +474,10 @@ for projecting data the extension owns into the generic QSON fields the rest of
 the app reads. A contest keeps its exchange on its own ref (`theirZone`,
 `theirSerial`, …), which nothing generic knows how to read — mirroring it into
 `their.exchange` is what fills the QSO row's exchange column and a plain ADIF
-export. Return a PATCH, not a mutated QSO: it merges shallowly except `our` and
+export. A contest whose sent exchange changes per QSO (a serial) mirrors that
+into `our.exchange` too, and the column shows it ahead of theirs, in the RST
+cell's order — keep it to the part that varies, since it repeats on every row.
+Return a PATCH, not a mutated QSO: it merges shallowly except `our` and
 `their`, which merge one level deep, so `{their: {exchange: 'ZN5'}}` sets that
 field and leaves the callsign alone. `refs` and `uuid` in a patch are ignored —
 refs are shared with the core and with other activities. Return null to do
@@ -475,15 +511,36 @@ a set of placeless suggestions (dated contest events, say) among themselves, but
 never lifts one above a located park. Implemented by: `pota`, `sota`,
 `stateparks`, `cwt`.
 
-The activity search box also treats a leading `key:` as a scope — typing
-`pota:` (or tapping a row under "Activity Types") asks that extension alone,
-via a key-scoped `invokeHook` rather than the usual fan-out. For that to
-work, an extension's `activity` hook must be registered under its own
-**extension key**, and its control descriptors keyed `<extensionKey>/<name>`
-(`pota/activation`) — the core derives the scope from the part before the
-slash. An extension that deviates simply never gets scoped: its rows still
-add references, but `key:` would ask a hook that doesn't exist and come back
-empty.
+**A scoped search offers the reference the operator typed, listed or not.** The
+reference programs (`pota`, `sota` and every one built on `referenceActivity`)
+answer a scoped search with the typed code itself when no row matched it —
+named `unknownReference` where it fits the program's pattern, `invalidReference`
+where it does not. The search is the only way onto the operation, so a program
+whose list is stale, or whose pattern this app has wrong, would otherwise answer
+a reference the operator was handed on the air with "no results". The scope is
+what keeps the MALFORMED half of that narrow: unscoped, every enabled program
+would answer any text at all with an invented reference of its own, burying the
+real matches. (A well-formed code needs no scope — POTA has always offered one,
+since only that program's own pattern can accept it.) A search term that is not
+code-shaped is left alone either way: a single word is how a park or summit gets
+looked up BY NAME, and `pota: beersel` must not answer with an invented BEERSEL.
+The row is marked, and the reference is stored, logged and exported as typed —
+the same rule ADIF import follows for a malformed `*_REF` (below).
+
+The activity search box also treats a leading scope word as a scope — typing
+`pota:` (or tapping a row under "Activity Types") asks the extension serving
+that reference type alone, via a key-scoped `invokeHook` rather than the usual
+fan-out. The word is the **reference type's base name**, lowercased —
+`potaActivation` and `pota` both scope as `pota:` — never the extension key: a
+user-published `ki2d-pota` serving `potaActivation` is still scoped as
+`pota:`, since the operator is adding POTA parks whichever extension supplies
+them. Two enabled extensions serving one type share the word, and the scoped
+search asks both. For the hook call to reach the extension, its `activity`
+hook must be registered under its own **extension key**, and its control
+descriptors keyed `<extensionKey>/<name>` (`pota/activation`) — the core
+derives the hook key from the part before the slash. An extension that
+deviates simply never gets scoped: its rows still add references, but the
+scope would ask a hook that doesn't exist and come back empty.
 
 `editable` declares whether a reference of this type has anything to edit
 once it's on the operation. It defaults to **false**: a plain reference
@@ -702,8 +759,8 @@ interface CommandHook {
 // CommandInterpretation: {expectsParams?, mixedCase?, error?, describe?, confirm?, commands?: CommandAction[]}
 // CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
-//   sendSpots?, syncAll?, updateSettings?, updateSetting?, openSettings?,
-//   updateOperation?, setCallField?, reloadDataFiles?, devNotice?, devStatus?,
+//   setKeyerSpeed?, showKeyer?, sendSpots?, syncAll?, updateSettings?, updateSetting?, openSettings?,
+//   updateOperation?, markSegment?, setCallField?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
 ```
@@ -817,9 +874,10 @@ the lookup service's offline `their.guess` decoration. The placement rule
 needs the existing log: SEED reads it through `ctx.getQsos`, using the
 `uuid` the logging panel folds into the `operation` map it passes to
 `interpret`; EXP toggles an experimental feature via the `toggleExperiment`
-action field — the hook only parses "EXP <key-or-alias>", and the app
-resolves the token against `app/experiments.yaml` and reports the outcome,
-since the catalog and the stored per-experiment state both live app-side;
+action field — the hook parses "EXP <key-or-alias>" and resolves the token
+against `ctx.experiments` only for its preview ("Enable"/"Disable"); the app
+resolves it again when it flips the state and reports the outcome, since the
+stored per-experiment state lives app-side;
 DEVTT/DEVTIMETRAVEL move the app clock via the `devTimeTravel` action field —
 "DEVTT +3h", "DEVTT -1d", "DEVTT 2x", bare "DEVTT" to return to real time — so
 anything that turns on the date or on elapsed time can be tested without
@@ -923,6 +981,36 @@ can't, since it also blocks execution — which is why SEED returns it on
 every result despite its parameters not being prose: bare "SEED" must be
 executable (default count) yet still extendable to "SEED 15 3H".
 
+## ✅ `template` — rendering on the app's behalf
+
+The Liquid renderer (templates.md) lives in the SDK and runs only inside the
+extension runtime. A Dart-side surface that wants a template filled in — a
+CW message about to be keyed (docs/design/cat.md § CW keying) — reaches it
+through this hook, registered once by the core `templates` extension under
+the key `templates`:
+
+```ts
+interface TemplateHook {
+  render(
+    args: { template: string; operation?; qso?; qsoCount?: number },
+    ctx,
+  ): Promise<{ text: string } | { error: string }>
+  // Several templates against one context in one crossing (the keyer
+  // area's button labels): one result per template, in order.
+  renderMany(
+    args: { templates: string[]; operation?; qso?; qsoCount?: number },
+    ctx,
+  ): Promise<{ results: ({ text: string } | { error: string })[] }>
+}
+```
+
+`operation` and `qso` are the same objects a `panel` hook's `render` gets,
+and the result is built with the same `templateContext`, so a placeholder
+means the same thing wherever the app renders it. A template that does not
+parse comes back as `error` carrying the renderer's own message — a typo in
+a message the operator typed, to show them, not a bridge failure to report.
+The app calls them as `ExtensionService.renderTemplate` and `renderTemplates`.
+
 ## ✅ `scoring` — per-operation score batches
 
 One hook call scores an entire operation's QSOs at once (DESIGN.md §4:
@@ -964,7 +1052,12 @@ about a prior contact (`invalidBand`, `missingExchange`, a bare `{value}`)
 displaces nothing: core's dupe warning is then the only one there is.
 
 So emit `dupe` whenever your dupe test actually ran, `dupe: false` included —
-that is what tells the host you have ruled on the question. And when your
+that is what tells the host you have ruled on the question. It travels on the
+live paths too (`scoreQso`, `scoreCandidates`), not just in `qsoScores`. Rule
+only on what you have seen: a scorer folds only the segments it was running
+for, so a station absent from YOUR history may have been worked in a stretch
+you skipped, and staying silent there hands the question to the scorer holding
+the whole log. And when your
 verdict means "worked before, and this one counts anyway", say it in one of
 those notice keys (`newPark` is state-parks' spelling of `newRef`) rather than
 inventing a spelling of your own: an unrecognized key leaves core's `duplicate`
@@ -999,6 +1092,10 @@ three pure `ContestScorer` functions and gets the loop, the checkpointing and
 both live paths for free.
 
 `scoreQso` answers for ONE not-yet-logged QSO — the callsign being typed.
+A candidate that carries no `startAtMillis` (the draft's time is still
+automatic) reaches the scorer stamped with the current time on both live
+paths, so a day-bucketed rule judges it as of now rather than at the epoch; a
+candidate that states a time keeps it.
 `scoreCandidates` answers the same question for many at once, which is what the
 Spots Panel asks to mark the spots already worked: the log is folded once per
 scorer and every candidate scored against a COPY of the result, so no candidate
@@ -1199,7 +1296,7 @@ and optional OAuth2, surfaced in `SettingsView`'s Accounts panel via
 platform keychain, keyed by the account's `kvKey`. Implemented by: `qrz`
 (username/password) and `sota` (OAuth2 via Keycloak — `sso.sota.org.uk`; the
 host runs the whole PKCE flow itself, see `_doOAuth` in
-`app/lib/views/settings_view.dart`).
+`app/lib/views/settings/accounts_panel.dart`).
 
 **`label` / `description` / `fields`** — each either a plain value, or a
 function `(args, ctx) => value` called the same way any other hook method is,

package/docs/settings.md

@@ -372,17 +372,18 @@ Aliases are for names an operator would plausibly *reach for* — not a thesauru
 Every alias is one more thing that can collide with another setting's real name,
 and a collision costs a disambiguation prompt on a query that used to be exact.
 
-## Common Preferences and environment gating
+## Common Settings and environment gating
 
-The app has two settings screens: **All Settings**, listing every declared
-group and panel, and **Common Preferences**, a short list of the handful of
-settings most users ever touch. Which fields land on Common Preferences —
+The app has one settings screen, **Settings**: a collapsible section per
+declared group and panel, led by **Common Settings**, a short list of the
+handful of settings most users ever touch. Which fields land on Common
+Settings —
 and which platforms show a field at all — is declared per-element, not
 maintained as a separate list somewhere else in the app. Any field, link, or
 action (core-declared or extension-declared, Tier 1 or Tier 2 alike) can set:
 
-- **`common: true`** — also show this element on Common Preferences, in
-  addition to All Settings. Off by default. Not the same thing as
+- **`common: true`** — also show this element in the Common Settings
+  section, on top of its own group's. Off by default. Not the same thing as
   `FormFieldOption.common`/`uncommon` above — that's a `multiselect`
   option's own disclosure tier (upfront vs. behind "Show more"), a
   different scope (an option inside one field, not the field itself).
@@ -393,8 +394,8 @@ action (core-declared or extension-declared, Tier 1 or Tier 2 alike) can set:
 
 - **`environment: 'ios,android'`** (or `'-web'`, or an array either way) —
   restrict which platform(s) show this element at all. This is a platform
-  gate, not a Common-vs-All one: an excluded field disappears from every
-  settings surface on that platform, not just Common Preferences. Every
+  gate, not a common-vs-everything one: an excluded field disappears from every
+  settings surface on that platform, not just Common Settings. Every
   token unprefixed is a whitelist (show ONLY there); every token
   `-`-prefixed is a blacklist (show everywhere EXCEPT there); mixing the two
   forms in one attribute is invalid and treated as if `environment` were
@@ -445,7 +446,7 @@ target but niche enough it shouldn't clutter the default view:
 ```
 
 Omitting `target` doesn't hide a field from anywhere it already appears —
-Common Preferences and All Settings are unaffected either way. It's purely
+The Settings panel is unaffected either way. It's purely
 additive: an extra place a field can be reached from, on top of wherever
 `common`/`environment` already put it.
 
@@ -453,8 +454,8 @@ additive: an extra place a field can be reached from, on top of wherever
 elements can both set `target` and both appear in a target-scoped modal —
 an action's method dispatches through the same extension host call the
 full settings screens use, and an account field's Manage/Connect button
-opens that account's own standalone dialog, exactly as it would from All
-Settings.
+opens that account's own standalone dialog, exactly as it would from the
+Settings panel.
 
 ## Restarting the runtime after a Tier 2 field commits
 

package/docs/templates.md

@@ -38,14 +38,14 @@ the namespaces are deliberately polo's. The syntax around them does not:
 
 ## What a template can name
 
-| namespace | panel `render` | export filename | ADIF fields |
-|---|---|---|---|
-| `app` | ✓ | — | ✓ |
-| `now` | ✓ | ✓ | ✓ |
-| `op` | ✓ | dates only | ✓ |
-| `qso` | when the placement's triggers ask for it | — | ✓ |
-| `config` | ✓ | — | — |
-| `log` | — | ✓ | ✓ |
+| namespace | panel `render` | export filename | ADIF fields | CW message |
+|---|---|---|---|---|
+| `app` | ✓ | — | ✓ | ✓ |
+| `now` | ✓ | ✓ | ✓ | ✓ |
+| `op` | ✓ | dates only | ✓ | ✓ |
+| `qso` | when the placement's triggers ask for it | — | ✓ | the draft contact, as far as it is typed |
+| `config` | ✓ | — | — | — |
+| `log` | — | ✓ | ✓ | — |
 
 A namespace a surface has nothing for is **absent**, not blank — which is
 what makes `{% if qso %}` an honest question. Filenames get only the date
@@ -61,7 +61,8 @@ An ISO-8601 UTC string, for the `date` filter: `{{ now | date: '%H:%M' }}`.
 
 ### `op` — the operation
 `station` (the field as typed, which may hold several comma-separated
-callsigns), `stations` (that list, uppercased and deduped), `operator`,
+callsigns; `call` is the same value, the name `qso.call` has), `stations`
+(that list, uppercased and deduped), `operator`,
 `title` (the generated, ref-derived one), `userTitle` (the operator's own
 words), `grid`, `refs`, `uuid`, `qsoCount`, `date`, `dateCompact`, `time`,
 `at`, `startDate`, `startTime`, `startAt`, `endDate`, `endTime`, `endAt`.
@@ -192,6 +193,7 @@ will jump rather than count. Show HH:MM.
 | Panel documents | `custom-text`'s content and tab name | by the operator, in the panel's config form |
 | Export filenames | `sdk/src/exportNames.ts` `NAME_TEMPLATES` | not yet |
 | ADIF NOTES / COMMENT / QSLMSG | `core/adif`'s `TEXT_FIELD_TEMPLATES` | not yet |
+| CW messages | Radio settings `cwMessage1..8`, keyed on F1-F8 through the radio (docs/design/cat.md § CW keying) — rendered by the `template` hook (hooks.md) | by the operator, in the Station dialog's Messages… dialog |
 
 COMMENT and QSLMSG are empty, so nothing is written for them. app-polo
 defaults COMMENT to the QSO's notes and QSLMSG to the operation's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",
@@ -10,7 +10,7 @@
     "sdk",
     "logging"
   ],
-  "license": "MPL-2.0",
+  "license": "MIT",
   "author": "Sebastian Delmont <sd@ham2k.com>",
   "homepage": "https://ham2k.com",
   "repository": {
@@ -25,8 +25,17 @@
     "subpath, so a tool asking this package its own version is told the package",
     "does not exist. Common enough that npm's own docs call it out."
   ],
+  "//ham2k-source": [
+    "A condition only this repo's own test run asks for (`--conditions=ham2k-source`),",
+    "so a test can import the SDK by name and get the TypeScript sources rather",
+    "than a build of them — the same thing esbuild's alias does when it bundles an",
+    "extension. Deliberately not the conventional `development`: the published",
+    "tarball ships `dist` and not `src`, and a consumer who happened to run with",
+    "that common condition would be pointed at files their install does not have."
+  ],
   "exports": {
     ".": {
+      "ham2k-source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },

package/samples/k2hrc-cqww/manifest.json

@@ -5,7 +5,6 @@
   "version": "1.0.0",
   "description": "CQ WW DX points and multipliers, as a worked example",
   "category": "contest",
-  "enabledByDefault": false,
   "icon": "earth",
   "accentColor": "#B03A2E",
   "api": 1,

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

@@ -1,5 +1,5 @@
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
-// SPDX-License-Identifier: MPL-2.0
+// SPDX-License-Identifier: MIT
 //
 // SAMPLE — a contest: an exchange to type, and a score to keep.
 //