@ham2k/extension-sdk 0.2.0 → 0.4.0

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

@@ -14,6 +14,7 @@ All types are defined in `extensions/sdk/src/types.ts`.
 export type FormFieldType =
   | 'text'
   | 'multiline'
+  | 'textTemplate'
   | 'email'
   | 'callsign'
   | 'number'
@@ -93,6 +94,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)
 }
@@ -121,6 +130,8 @@ export interface FormMarkdownBlock {
 // SDK already permits (see settings.md's settingsPanel note). Not used for
 // account credentials — those have their own testCredentials on AccountHook.
 export interface FormActionElement {
+  style?: 'row'; // icon row with a chevron; omit for a button
+  icon?: string;
   type: 'action';
   key: string;
   label: string;
@@ -269,3 +280,28 @@ api.registerHook('form', {
    - Any validation error returns back to Dart and is displayed underneath the field. If any fields have errors, submission is aborted.
 3. **Submit transformation**: When all fields are successfully validated, Dart invokes any JS transformation callbacks for each field.
 4. **Completion**: The final transformed state is resolved and returned back to the caller (or saved in the view context).
+
+## Text templates
+
+`fieldType: 'textTemplate'` is a string field displayed as an editor row in
+forms and settings. It opens a multiline Liquid editor with a sample preview,
+syntax errors, insertable attributes and flow-control examples, and a read-only
+filter reference inside collapsed Templating Docs. Editing and preview stay
+above the scrollable reference. Template rows also display rendered samples. Save commits
+the draft; Cancel, Escape and dismissal discard it. `defaultValue` supplies
+the Reset button. Disabled fields cannot open the editor.
+
+```ts
+{
+  type: 'field', fieldType: 'textTemplate', key: 'filename',
+  label: 'File name', value: '{{ op.date }} {{ log.station }}',
+  templateContext: 'export', // 'adif' adds contact attributes; 'text' is generic
+  templateSample: { log: { activity: 'POTA', ref: 'US-1234' } },
+}
+```
+
+The preview uses the same runtime and vocabulary as exports; sample values
+are illustrative. `templateSample` can replace values in `operation`, `qso`
+and `log`. The app provides the rendering callback through
+`TemplateEditorScope`, keeping the form widget independent of extensions.
+See [templates.md](templates.md) for Liquid syntax and supported namespaces.

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.
@@ -233,23 +248,100 @@ fetch-only for now.
 
 ```ts
 interface ExportHook {
+  getExportTypes?(args: {}, ctx): Promise<ExportTypeDefinition[]>
   suggestExportOptions?(args: ExportOptionsRequest, ctx): Promise<ExportOption[]>
   generateExport(args: ExportRequest, ctx): Promise<ExportResult>
 }
 // ExportOptionsRequest: {operation, qsos, compactFilenames?}
-// ExportOption: {exportType, format, label, filename?, icon?, priority?, selectedByDefault?}
-// ExportRequest: {operation, qsos, exportType?, compactFilenames?}  — full QSON, one coarse call
+// ExportOption: {exportType, exportKey?, format, label, filename?, icon?, color?, refType?, priority?, selectedByDefault?}
+// ExportRequest: {operation, qsos, exportType?, exportKey?, compactFilenames?}  — full QSON, one coarse call
 // ExportResult:  {filename, mimeType, content}
 ```
 
 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
-chosen option's `exportType` — only for the options the user selected. The
-core owns file I/O and save/share; the hook only produces content.
+chosen option's `exportType` and `exportKey` — only for the options the user
+selected. The core owns file I/O and save/share; the hook only produces content.
+
+`exportType` is the stable kind (for example `potaActivation-adif`); `exportKey`
+identifies an individual option within the hook (for example
+`pota-adif:US-1234`). Options sharing a type must have distinct keys. Omit
+`exportKey` for a single option of a type: selection and generation default
+it to `exportType`. Both values round-trip unchanged when an explicit key is
+provided; the core does not interpret them. Selection also includes the
+hook key and station callsign, keeping different hooks and stations independent.
+
 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.
+below) rather than knowing about specific activities. Implemented by the whole-log `adif` exporter, activity exports, and contest
+ADIF/Cabrillo exporters.
+
+**Registering types and settings.** `getExportTypes` runs without an operation,
+so Settings can list types even before the operator has a matching log:
+
+```ts
+async getExportTypes() {
+  return [{
+    exportType: 'potaActivation-adif',
+    activationType: 'potaActivation',
+    format: 'adif',
+    label: 'POTA',
+    defaults: { includePrivateData: false, includeLookupData: true },
+  }]
+}
+```
+
+Prefer `<activationType>-<format>` to an extension-key namespace. Two
+extensions offering that type share one settings entry. The highest-priority
+registration supplies its definition; other exporters using it must honor
+that contract. Distinct sponsor requirements can use a distinct type. The
+SDK's `exportTypeDefinition(activationType, format, label, defaults?)` builds
+the conventional definition; the activity and hunting helpers register their
+own types. An exporter without `getExportTypes` still works, but does not
+appear in the export settings list.
+
+`ExportSettings` contains `includePrivateData`, `includeLookupData`,
+`customTemplates`, `filenameTemplate`, `compactFilenameTemplate`,
+`titleTemplate`, `adifNotesTemplate`, `adifCommentTemplate`, and
+`adifQslMessageTemplate`. All are optional. Defaults resolve from the SDK,
+then global preferences, then the type's declared defaults.
+`GlobalExportSettings` adds `referenceFilenameTemplate`,
+`referenceCompactFilenameTemplate`, `referenceTitleTemplate` and the matching
+`other…` fields. A type with `templateCategory: 'reference'` uses the reference
+set; other types use the other set. The activity export helper registers
+reference types automatically. ADIF field templates remain common to both sets.
+Saved common filename/title defaults remain fallbacks for categories without
+an explicit setting. Per-type data
+choices override those; per-type template overrides apply only when
+`customTemplates` is on. Empty templates intentionally suppress text. Turning
+custom templates off preserves the operator's edits for later. Non-ADIF
+formats expose only the filename templates and their custom-template switch.
+
+Type definitions may supply `templateSample: {operation, log}` for representative
+editor examples. Each format supplies its own filename extension in the sample.
+
+An option can supply `qsoCount` when its hook further filters the contacts
+(for example, a hunter export). Otherwise the host derives the count from
+activity and station scope. Filename and title templates use this count.
+
+Options can carry `templateData: {ref, refName, activity, modifier, ...}`,
+which populates the `log` namespace. The app renders filenames and titles
+before showing the option, and passes the same `exportSettings`, `exportData`
+and `exportTitle` to generation. It also passes the resolved
+`includePrivateData` and `includeLookupData` for ADIF. Forward those fields
+when delegating through `adifForExport`, or a program's preferences will not
+reach the ADIF writer. Settings apply globally and per type, never per operation.
+The whole-log ADIF defaults to including private data, but its type setting
+can override that default.
+
+**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 —
@@ -280,6 +372,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 +497,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 +532,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 +542,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 +579,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 +827,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 +942,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 +1049,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 +1120,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 +1160,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 +1364,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

@@ -374,15 +374,17 @@ and a collision costs a disambiguation prompt on a query that used to be exact.
 
 ## Common Preferences 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**, whose **Application
+Preferences** panel has a collapsible section per declared group and panel,
+led by **Common Preferences**, a short list of the
+handful of settings most users ever touch. Which fields land on Common
+Preferences —
 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 Preferences
+  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,7 +395,7 @@ 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
+  gate, not a common-vs-everything one: an excluded field disappears from every
   settings surface on that platform, not just Common Preferences. Every
   token unprefixed is a whitelist (show ONLY there); every token
   `-`-prefixed is a blacklist (show everywhere EXCEPT there); mixing the two
@@ -445,7 +447,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 +455,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