@ham2k/extension-sdk 0.1.0 → 0.3.0

package/docs/templates.md

@@ -0,0 +1,206 @@
+# Templates
+
+One templating engine for every place HaLo turns log data into text: a
+panel's document, an export's filename, an ADIF field. One vocabulary too —
+`{{ op.station }}` means the same thing wherever it appears.
+
+The engine is **[Liquid](https://liquidjs.com)** (`liquidjs`), a kernel
+shared module wrapped by `sdk/src/templates.ts`. Everything goes through that
+wrapper: it owns the option set, and a second engine built elsewhere would
+disagree about timezones without anyone noticing.
+
+```ts
+import { renderTemplate, templateContext, triggersForTemplate } from "@ham2k/extension-sdk"
+
+const text = renderTemplate("{{ op.station }} — {{ op.qsoCount }} QSOs", templateContext({ operation, qsoCount }))
+```
+
+## Why Liquid rather than app-polo's Handlebars
+
+A template is DATA. Liquid parses and interprets; Handlebars compiles
+through `new Function`. These templates are written by operators, copied
+between operators, and will eventually be editable in settings, so the one
+that cannot become code is the one to have. Liquid also has comparisons
+(`{% if op.qsoCount > 100 %}`) and loops built in, where Handlebars needs a
+registered helper for `>` and Mustache cannot compare at all.
+
+Measured in the shipped QuickJS-NG build: 80 KB minified (24 KB gzipped),
+6 ms to evaluate at startup, 0.33 ms per parse+render of a small template —
+and parsed templates are cached, so repeated renders of one document cost
+about 2 µs each.
+
+**Porting from PoLo**: the plain majority of polo's templates —
+`{{ op.date }} {{ log.station }} at {{ log.ref }}` — parse unchanged, because
+the namespaces are deliberately polo's. The syntax around them does not:
+`{{#if}}` is `{% if %}{% endif %}`, `{{#each}}` is `{% for %}{% endfor %}`,
+`{{> Partial}}` has no equivalent, and helpers are filters
+(`{{ dash x }}` → `{{ x | dash }}`).
+
+## What a template can name
+
+| 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
+half of `op` because a filename is built from parts rather than from an
+operation (`exportNames.ts`).
+
+### `app`
+`app.name` — the platform-appropriate name ("Ham2K Logger" on desktop,
+"Ham2K Portable Logger" on mobile).
+
+### `now`
+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; `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`.
+
+`endDate` / `endTime` / `endAt` are the LAST CONTACT'S START — an operation
+row records when its final QSO began and not when it ended, so a template
+printing `{{ op.startTime }}–{{ op.endTime }}` understates the session by
+that contact's length.
+
+### `qso` — one contact
+`call`, `their`, `our` (both whole, so `qso.their.guess.name` reaches the
+lookup's answer), `band`, `mode`, `freq`, `rstSent`, `rstRcvd`, `notes`,
+`date`, `dateCompact`, `time`, `at`, `startAtMillis`, `refs`.
+
+`rstSent` is what WE sent — QSON stores each side's report under its own
+`sent`, and these are named for the operator's view of the contact.
+
+### `config` — a panel's own form values
+Whatever that panel's `form` declared, under the keys it used.
+
+### `log` — one export
+`station`, `ref`, `refName`, `refShortName`, `activity`, `handlerName`,
+`handlerShortName`, `format`, `exportType`, `modifier`, `extension`,
+`compact`.
+
+## Timestamps
+
+Two forms, and the rule is worth learning once:
+
+- **`…At` fields are ISO-8601 UTC strings** — feed these to the `date`
+  filter: `{{ qso.at | date: '%H:%MZ' }}`.
+- **`date` / `dateCompact` / `time` are preformatted UTC** —
+  `2026-07-27`, `20260727`, `1430`.
+
+Everything is UTC. A log is kept in UTC, and a filename that shifted with
+the reader's zone would name the wrong day.
+
+**`op`'s dates can be empty.** `startAtMillisMin`/`startAtMillisMax` are
+columns on the operation row, not keys in the QSON `data` a hook is handed,
+so they arrive only where the caller adds them: the panel host does, and the
+ADIF export passes the first QSO's time instead. Where neither happens,
+`op.date` and the `start…`/`end…` fields render empty rather than falling
+back to today — a pane showing yesterday's log must not print today's date
+with nothing to say it was invented.
+
+## Filters
+
+All of Liquid's own (`date`, `downcase`, `upcase`, `strip`, `default`,
+`join`, `size`, `first`, `last`, `round`, `truncate`, `replace`, `map`,
+`where`, …), plus two:
+
+| filter | does | example |
+|---|---|---|
+| `dash` | non-alphanumerics → `-`, collapsed and trimmed, **case preserved** | `N0CALL/P` → `N0CALL-P` |
+| `alnum` | strip to alphanumerics | `2026-07-27` → `20260727` |
+
+`alnum` is app-polo's `compact` helper under a different name: Liquid already
+has a `compact` (it drops nils from an **array**, and `op.refs`/`qso.refs` are
+arrays), and `registerFilter` overwrites without warning, so taking that name
+would silently break templates written against Liquid's own documentation.
+
+`dash` keeps case because callsigns and references are written in capitals
+and stop being legible flattened. For free text, `{{ x | downcase | dash }}`
+is the slug form.
+
+## Traps
+
+Each of these was measured against the shipped runtime, not assumed.
+
+**An empty string is TRUE.** In Liquid only `nil` and `false` are falsy, so
+`{% if log.modifier %}` fires on `""`. Ask for blankness explicitly:
+`{% if log.modifier != blank %}`.
+
+**A raw millisecond timestamp is not a date.** The `date` filter reads a
+number as SECONDS, so epoch millis render in the year 58567. Use the `…At`
+strings.
+
+**Unknown names are silent.** An unknown variable renders empty and an
+unknown filter passes its value through. That is deliberate — an operator's
+typo costs one line, not the document — but it means a misspelled
+`{{ op.stationCall }}` looks like missing data rather than a mistake.
+
+**Text written before templating existed can lose a span.** `{{ TODO }}` in
+an old note is a perfectly valid reference to a variable that doesn't exist,
+so it renders as nothing at all rather than as an error — the note quietly
+comes back a few words shorter. Only clearly broken syntax (`{% if` with no
+`{% endif %}`) reports itself; `custom-text` then shows the message with the
+operator's own text intact below it, because a pane that answered by
+deleting what somebody wrote would be the worse failure.
+
+**Literal braces need `{% raw %}`.** That is also the fix for the case
+above: wrap the passage and it renders as typed.
+
+**`{% include %}` throws.** There is no filesystem in the runtime. Partials
+would have to be supplied in memory.
+
+**Loops are bounded by time, not by iterations.** A render is abandoned
+after 250 ms with a `TemplateError` naming the limit.
+
+## Errors
+
+`renderTemplate` throws `TemplateError`, carrying Liquid's own message with
+the line and column. It does not fall back: a broken template is either an
+operator's typo, which they can only fix if they are told, or a bug in one
+of ours, which tests should catch. Where the template is the operator's,
+show them the message — `custom-text` renders it in the pane.
+
+## Panel triggers
+
+`triggersForTemplate(text)` reports which panel triggers a template needs,
+derived from the namespaces it names: `qso` → `qso` + `lookup`, `qsoCount` →
+`qsoLogged`, `op` → `operation`, `now` → `tick:30`. A panel rendering
+operator-written text passes these back as `PanelContent.triggers`
+(hooks.md, `panel`), so each pane pays only for what its own text asks for.
+
+Only `{{ … }}` and `{% … %}` spans are read, never the prose around them —
+"Goal: 100 qso today" is a note, not a request to be woken per keystroke.
+Inside a span it is deliberately generous: `{% if qso %}` counts as naming
+the QSO, since a false negative shows stale text with no clue why.
+
+`now` is refreshed on a **30-second** tick, so `{{ now | date: '%H:%M:%S' }}`
+will jump rather than count. Show HH:MM.
+
+## Where templates are used today
+
+| what | where | editable |
+|---|---|---|
+| 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
+references; both wait here until there is a settings screen to edit them in,
+since a default nobody can see is one nobody can turn off, and these fields
+travel to a program's servers.
+
+Whatever fills them must respect the private/public split: `notes` is the
+operator's own words and belongs only in a field the export withholds when
+private data is off. NOTES is such a field. COMMENT and QSLMSG are not.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.1.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": {
@@ -19,11 +19,27 @@
     "directory": "extensions/sdk"
   },
   "type": "module",
+  "//exports": [
+    "`./package.json` is exported because an `exports` map without it makes the",
+    "file unreadable through package resolution: Node refuses an undeclared",
+    "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.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -39,6 +55,9 @@
   ],
   "files": [
     "dist",
+    "docs",
+    "samples",
+    "AGENTS.md",
     "README.md"
   ],
   "engines": {

package/samples/README.md

@@ -0,0 +1,33 @@
+# Samples
+
+One extension per shape, each one real: it builds, it packs, and it does what
+it says against the live service. Read the one whose shape matches what you are
+building — the header comment in each `src/index.ts` says what it leaves out.
+
+| | |
+| --- | --- |
+| `k2hrc-hamqth` | A callsign lookup, and the `account` hook that asks for a password |
+| `k2hrc-llota` | An award program: references, an offline list, activation scoring |
+| `k2hrc-cqww` | A contest: an exchange to type, and a score to keep |
+| `k2hrc-radio` | An HTML panel, and why you should probably write markdown instead |
+
+## Running one
+
+```sh
+mkdir my-extension && cd my-extension
+npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name>
+npm install
+```
+
+Then copy a sample's `manifest.json` and `src/` over the scaffolded ones,
+change the `key` back to yours, and:
+
+```sh
+npm run build && npm run pack
+```
+
+The key must stay `<yourcallsign>-<name>` — it namespaces your extension's
+storage, and the packer refuses anything else. The `k2hrc-` keys here belong
+to the samples, so leaving one in place would collide with them.
+
+See `../AGENTS.md` for the map, and `../docs/` for the references.

package/samples/k2hrc-cqww/build.mjs

@@ -0,0 +1,6 @@
+import { build } from 'esbuild'
+import { buildExtension } from '@ham2k/extension-tools'
+
+await buildExtension(build, { dir: import.meta.dirname })
+
+console.log('built build/index.js')

package/samples/k2hrc-cqww/manifest.json

@@ -0,0 +1,23 @@
+{
+  "key": "k2hrc-cqww",
+  "name": "CQ WW DX (sample)",
+  "shortName": "CQWW*",
+  "version": "1.0.0",
+  "description": "CQ WW DX points and multipliers, as a worked example",
+  "category": "contest",
+  "icon": "earth",
+  "accentColor": "#B03A2E",
+  "api": 1,
+  "keywords": ["contest", "cqww", "dx", "sample"],
+  "hooks": ["activity", "ref:k2hrcCqww", "scoring"],
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.0",
+    "@ham2k/lib-country-files": "^1.0.0",
+    "@ham2k/lib-dxcc-data": "^1.0.0",
+    "@ham2k/lib-format-tools": "^1.0.0",
+    "@ham2k/lib-geo-tools": "^1.0.0",
+    "@ham2k/lib-operation-data": "^1.0.0",
+    "i18next": "^23.0.0",
+    "liquidjs": "^10.0.0"
+  }
+}

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

@@ -0,0 +1,273 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// SAMPLE — a contest: an exchange to type, and a score to keep.
+//
+// A contest extension is three things. The `activity` hook contributes the
+// setup form and the per-QSO exchange field; the `ref:` handler says what the
+// operation's contest reference means; the `scoring` hook keeps the score.
+//
+// The scorer is the part worth studying. It is a FOLD: the host hands you a
+// scoresheet and one QSO, you return the scoresheet with that QSO in it. The
+// host owns when it runs — a fresh log, a re-score after an edit, a running
+// total while operating — so a scorer that reaches for anything outside its
+// arguments gives different answers on the same log.
+//
+// The rules here are CQ WW's, and real: points by continent, multipliers per
+// band, one contact per station per band. What this sample leaves out is
+// everything around them — Cabrillo export, the ADIF exchange fields, the
+// country-file zone suggestion, and writing a guessed exchange onto the QSO.
+// See `docs/hooks.md` §`scoring`, and `contests/cqww` in the app's repository
+// for the whole thing.
+
+import { annotateCallAgainstCountryFile, contestScorer, defineExtension } from "@ham2k/extension-sdk"
+import type {
+  ContestScorer,
+  HookContext,
+  JSONValue,
+  LoggingControlDescriptor,
+  Ref,
+  ScoreTally,
+} from "@ham2k/extension-sdk"
+import { fmtInteger } from "@ham2k/lib-format-tools"
+
+import manifest from "../manifest.json" with { type: "json" }
+
+const TYPE = "k2hrcCqww"
+
+/// CQ WW is an HF contest: the WARC bands are excluded by the rules, not by
+/// oversight.
+const VALID_BANDS = ["160m", "80m", "40m", "20m", "15m", "10m"]
+
+/// A CQ zone as typed: 1-40, with or without a leading zero. The core anchors
+/// and case-folds it, so this is only the body.
+const ZONE_PATTERN = "0?(?:[1-9]|[1-3][0-9]|40)"
+
+function str(value: JSONValue | undefined): string {
+  return typeof value === "string" ? value : ""
+}
+
+function refOfType(container: Record<string, JSONValue>, type: string): Record<string, JSONValue> | undefined {
+  return ((container.refs as Record<string, JSONValue>[] | undefined) ?? []).find((r) => r?.type === type)
+}
+
+/// "05" and "5" are the same multiplier and must not count twice.
+function normalizeZone(value: JSONValue | undefined): string {
+  const digits = String(value ?? "").trim().replace(/^0+(?=\d)/, "")
+  return /^([1-9]|[1-3][0-9]|40)$/.test(digits) ? digits : ""
+}
+
+type Scoresheet = {
+  /// call → the bands already worked with it. One QSO per station per band.
+  workedByCall: Record<string, string[]>
+  /// Every `band|Z<zone>` and `band|C<entity>` seen. Multipliers are per band,
+  /// so the band is part of the key.
+  mults: Record<string, number>
+  qsos: number
+  points: number
+  /// Ours, resolved once: every point below is relative to where we are.
+  ourContinent?: string
+  ourEntity?: string
+}
+
+const CQWWScorer: ContestScorer<Scoresheet> = {
+  /// Called once at the start of a fold. Anything derived from the operation
+  /// belongs here, not in `scoreQso` — this runs once, that runs per contact.
+  startScoresheet({ operation }): Scoresheet {
+    const ours = annotateCallAgainstCountryFile(str(operation.stationCall))
+    return {
+      workedByCall: {},
+      mults: {},
+      qsos: 0,
+      points: 0,
+      ourContinent: ours.continent,
+      ourEntity: ours.entityPrefix,
+    }
+  },
+
+  /// Mutates and returns the scoresheet it was given.
+  ///
+  /// The verdict is as important as the number: `dupe` is what greys the QSO
+  /// out in the log, and `alerts` is what tells the operator WHY something
+  /// scored nothing. A scorer that silently returns 0 leaves them wondering.
+  scoreQso({ scoresheet, qso }) {
+    const their = (qso.their as Record<string, JSONValue>) ?? {}
+    const call = str(their.call)
+    if (!call) return { scoresheet, score: { value: 0 } }
+
+    const band = str(qso.band)
+    if (!VALID_BANDS.includes(band)) {
+      return { scoresheet, score: { value: 0, alerts: ["invalidBand"] } }
+    }
+
+    const worked = scoresheet.workedByCall[call] ?? []
+    if (worked.includes(band)) {
+      return { scoresheet, score: { value: 0, dupe: true, alerts: ["duplicate"] } }
+    }
+
+    const theirs = annotateCallAgainstCountryFile(call)
+    // The exchange the operator typed wins; the country file's answer for the
+    // callsign is the fallback, so a QSO logged without one still scores.
+    const zone = normalizeZone(refOfType(qso, TYPE)?.theirZone) || normalizeZone(theirs.cqZone)
+
+    // Points: nothing within our own DXCC entity, 1 inside our continent, 2
+    // for North America to North America, 3 across continents.
+    let points = 3
+    if (theirs.entityPrefix && theirs.entityPrefix === scoresheet.ourEntity) points = 0
+    else if (theirs.continent && theirs.continent === scoresheet.ourContinent) {
+      points = theirs.continent === "NA" ? 2 : 1
+    }
+
+    scoresheet.workedByCall[call] = [...worked, band]
+    scoresheet.qsos += 1
+    scoresheet.points += points
+
+    // Two multipliers per contact, each counted once per band: the zone, and
+    // the country. Recorded even when the contact is worth no points — working
+    // your own country still gives you the multiplier.
+    if (zone) scoresheet.mults[`${band}|Z${zone}`] = 1
+    if (theirs.entityPrefix) scoresheet.mults[`${band}|C${theirs.entityPrefix}`] = 1
+
+    return { scoresheet, score: { value: points } }
+  },
+
+  /// The score as the operator reads it. `scope` is 'day' or the whole
+  /// contest; this sample reports the same totals for both, where the real
+  /// extension tracks a separate per-day tally.
+  summarizeScore({ scoresheet, scope }): Record<string, ScoreTally> {
+    const mults = Object.keys(scoresheet.mults).length
+    return {
+      [TYPE]: {
+        key: TYPE,
+        for: scope,
+        icon: manifest.icon,
+        total: scoresheet.points * mults,
+        points: scoresheet.points,
+        mults,
+        qsos: scoresheet.qsos,
+        label: `${fmtInteger(scoresheet.points)} × ${fmtInteger(mults)}`,
+        summary: `${fmtInteger(scoresheet.points * mults)}`,
+      },
+    }
+  },
+}
+
+const ActivityHook = {
+  /// What the operator fills in when adding this contest to an operation.
+  async operationControls(
+    _args: { operation: Record<string, JSONValue> },
+    _ctx: HookContext,
+  ): Promise<LoggingControlDescriptor[]> {
+    return [
+      {
+        key: "k2hrc-cqww/setup",
+        label: "CQ WW DX (sample)",
+        icon: manifest.icon,
+        color: manifest.accentColor,
+        order: 10,
+        input: {
+          kind: "form",
+          // Naming the ref type is what makes the form's values land on a ref
+          // of that type on the operation — which is then what the scorer's
+          // `scope` matches, and what the handler below decorates.
+          refType: TYPE,
+          form: {
+            title: "CQ WW DX",
+            elements: [
+              {
+                type: "field",
+                fieldType: "radio",
+                key: "mode",
+                label: "Mode",
+                // Separate contests on separate weekends, not a filter.
+                options: [
+                  { value: "CW", label: "CW" },
+                  { value: "SSB", label: "SSB" },
+                  { value: "RTTY", label: "RTTY" },
+                ],
+              },
+              { type: "field", fieldType: "text", key: "zone", label: "Our CQ zone", placeholder: "8" },
+            ],
+          },
+        },
+      },
+    ]
+  },
+
+  /// The one field typed per QSO.
+  ///
+  /// Contributed only while this operation is actually running the contest.
+  /// The core would refuse it anyway, so this guard is an optimization, not
+  /// the rule — but it runs on the typing path, once per enabled contest
+  /// extension, which is why it is worth having.
+  async loggingControls(
+    args: { operation: Record<string, JSONValue>; qso?: Record<string, JSONValue> },
+    _ctx: HookContext,
+  ): Promise<LoggingControlDescriptor[]> {
+    if (!refOfType(args.operation, TYPE)) return []
+
+    const their = (args.qso?.their as Record<string, JSONValue>) ?? {}
+    const guess = (their.guess as Record<string, JSONValue>) ?? {}
+    const call = str(their.call)
+    const suggested =
+      normalizeZone(guess.cqZone) || (call ? normalizeZone(annotateCallAgainstCountryFile(call).cqZone) : "")
+
+    return [
+      {
+        key: "k2hrc-cqww/zone",
+        label: "Zone",
+        icon: manifest.icon,
+        color: manifest.accentColor,
+        order: 10,
+        input: {
+          kind: "text",
+          refType: TYPE,
+          field: "theirZone",
+          numeric: true,
+          maxLength: 3,
+          pattern: ZONE_PATTERN,
+          // The guessed zone for THIS callsign, never a format hint like
+          // "1-40" — a hint reads as a real value at a glance.
+          placeholder: suggested || undefined,
+          // Filled in for the operator, but never over what they typed.
+          suggestedValue: suggested || undefined,
+        },
+      },
+    ]
+  },
+}
+
+const RefHandler = {
+  async validateRef({ ref }: { ref: Ref }, _ctx: HookContext) {
+    return { valid: true, normalized: (ref.ref ?? "").trim() }
+  },
+
+  /// A contest reference names an event, not a place, so what it decorates to
+  /// is the contest and the exchange we are sending.
+  async decorateRef({ ref }: { ref: Ref }, _ctx: HookContext): Promise<Ref> {
+    const mode = str((ref as Record<string, JSONValue>).mode)
+    const zone = normalizeZone((ref as Record<string, JSONValue>).zone)
+    const label = mode ? `CQ WW ${mode}` : "CQ WW DX"
+    return {
+      ...ref,
+      program: "Contest",
+      label,
+      shortLabel: label,
+      name: zone ? `Zone ${zone}` : "Not configured",
+    }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("activity", { hook: ActivityHook, key: manifest.key })
+    registerHook(`ref:${TYPE}`, { hook: RefHandler, key: manifest.key })
+    // `scope` is what keeps this scorer out of every operation that is not
+    // running this contest.
+    registerHook("scoring", {
+      hook: contestScorer(CQWWScorer, { scope: { refTypes: [TYPE] } }),
+      key: manifest.key,
+    })
+  },
+})

package/samples/k2hrc-hamqth/build.mjs

@@ -0,0 +1,6 @@
+import { build } from 'esbuild'
+import { buildExtension } from '@ham2k/extension-tools'
+
+await buildExtension(build, { dir: import.meta.dirname })
+
+console.log('built build/index.js')

package/samples/k2hrc-hamqth/manifest.json

@@ -0,0 +1,24 @@
+{
+  "key": "k2hrc-hamqth",
+  "name": "HamQTH Lookups",
+  "shortName": "HamQTH",
+  "version": "1.0.0",
+  "description": "Looks up callsign details with a free HamQTH.com account",
+  "category": "lookup",
+  "icon": "card-account-details-outline",
+  "accentColor": "#1E6F5C",
+  "api": 1,
+  "keywords": ["callsign", "lookup", "hamqth", "sample"],
+  "hooks": ["account", "lookup"],
+  "domains": ["www.hamqth.com"],
+  "sharedDependencies": {
+    "@ham2k/lib-callsigns": "^1.0.0",
+    "@ham2k/lib-country-files": "^1.0.0",
+    "@ham2k/lib-dxcc-data": "^1.0.0",
+    "@ham2k/lib-format-tools": "^1.0.0",
+    "@ham2k/lib-geo-tools": "^1.0.0",
+    "@ham2k/lib-operation-data": "^1.0.0",
+    "i18next": "^23.0.0",
+    "liquidjs": "^10.0.0"
+  }
+}