@ham2k/extension-sdk 0.1.0 → 0.3.0

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

@@ -0,0 +1,202 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// SAMPLE — a callsign lookup source, with the credentials one needs.
+//
+// HamQTH's XML API is free and its shape is the common one: log in once with a
+// username and password, get a session id back, and spend that id on lookups
+// until it expires. So this sample is really two things an extension author
+// needs together — the `lookup` hook that answers about a callsign, and the
+// `account` hook that is the ONLY way to ask an operator for a secret.
+//
+// Never put a password in a settings field of your own: `account` stores
+// credentials in the platform keychain, keeps the session out of your hands,
+// and gives the operator one place to see what they have connected. A `secret`
+// field in a settings panel is for a bare API key with no login behind it.
+//
+// What this sample leaves out: the country-file cross-checks, the
+// already-know-enough short circuits, and the per-call caching a production
+// source wants. Read `docs/hooks.md` §`lookup` before shipping one.
+
+import { defineExtension, host } from "@ham2k/extension-sdk"
+import type { AnnotatedCallInfo, CallInfoLookup, HookContext, JSONValue, LookupResult } from "@ham2k/extension-sdk"
+import { cleanLocationParams } from "@ham2k/lib-geo-tools"
+
+import manifest from "../manifest.json" with { type: "json" }
+
+const API = "https://www.hamqth.com/xml.php"
+
+/// HamQTH asks every caller to identify itself, and rejects an empty `prg`.
+const PROGRAM = "ham2k-sample"
+
+/// HamQTH's XML is flat and carries no attributes worth reading, so a tag
+/// extractor beats a parser the sandbox would have to ship.
+function tag(xml: string, name: string): string | undefined {
+  return xml.match(new RegExp(`<${name}[^>]*>([^<]*)</${name}>`, "i"))?.[1]?.trim() || undefined
+}
+
+/// Trades the operator's credentials for a session id, and hands it to the
+/// host to hold.
+///
+/// `host.setAccountSession` rather than a module variable or `host.kvSet`: the
+/// session outlives a reload of this extension, and it is a credential — the
+/// host keeps it beside the password rather than in your storage.
+async function login(ctx: HookContext): Promise<string> {
+  const username = ctx.account?.credentials?.username
+  const password = ctx.account?.credentials?.password
+  if (!username || !password) throw new Error("No HamQTH account configured")
+
+  const response = await host.fetch(
+    `${API}?u=${encodeURIComponent(username)}&p=${encodeURIComponent(password)}`)
+  const sessionId = tag(response.body, "session_id")
+  if (!sessionId) throw new Error(tag(response.body, "error") ?? `HTTP ${response.status}`)
+
+  await host.setAccountSession({ sessionId })
+  return sessionId
+}
+
+/// One lookup, renewing the session if this one has aged out.
+///
+/// HamQTH sessions expire on their own schedule, so an expired one is a normal
+/// Tuesday rather than an error: the retry is the happy path, not recovery.
+/// Note that it re-logs-in only ONCE — a second failure is a real one, and
+/// looping on it would hammer the API behind the operator's back.
+async function fetchCall(call: string, ctx: HookContext): Promise<string> {
+  const search = (id: string) =>
+    host.fetch(`${API}?id=${id}&callsign=${encodeURIComponent(call)}&prg=${PROGRAM}`)
+
+  const sessionId = ctx.account?.session?.sessionId ?? (await login(ctx))
+  const response = await search(sessionId)
+
+  if (/session does not exist|expired/i.test(tag(response.body, "error") ?? "")) {
+    await host.setAccountSession({})
+    return (await search(await login(ctx))).body
+  }
+  return response.body
+}
+
+async function lookupCall(
+  { callInfo }: { callInfo: AnnotatedCallInfo; qso: Record<string, JSONValue>; operation: Record<string, JSONValue> },
+  ctx: HookContext,
+): Promise<LookupResult> {
+  const call = (callInfo.call || "").trim().toUpperCase()
+  // Offline, or too short to be a callsign: answer with nothing rather than
+  // spend a round-trip. `ctx.online` is the host's own answer, and a lookup
+  // hook runs on the typing path.
+  if (call.length < 3 || !ctx.online) return []
+
+  try {
+    const xml = await fetchCall(call, ctx)
+
+    const error = tag(xml, "error")
+    if (error) {
+      // "Callsign not found" is an ANSWER, not a fault — most operators work
+      // stations HamQTH has never heard of, and logging each one would bury
+      // the errors that matter (a bad password, a subscription problem).
+      if (!/not found/i.test(error)) host.log(`HamQTH said: ${error}`)
+      return []
+    }
+
+    // `<nick>` is a SHORTER FORM of the same name rather than a handle the
+    // operator also goes by: "Martin" against an `<adr_name>` of "Martin
+    // Kratoska", "Sebastian Delmont" against "Sebastian D Delmont", and for
+    // W1AW the identical string twice. Appending it reads as information and
+    // is not, so the full name wins and the nickname is only a fallback.
+    //
+    // QRZ's `nickname` deliberately goes the other way — there it IS what the
+    // operator goes by on the air, and its extension shows both. Same-looking
+    // field, opposite verdict; don't make the two consistent.
+    const name = tag(xml, "adr_name") ?? tag(xml, "nick")
+
+    const city = tag(xml, "adr_city")
+    const state = tag(xml, "us_state")
+
+    // The coordinate AND the grid. HamQTH reports both, and where a pair is
+    // present it outranks the locator — a lookup that kept only the grid would
+    // throw away the more precise of the two answers it was given. Parsed
+    // through `cleanLocationParams` rather than `Number`, because a service
+    // that has no fix for a record says so with an empty string, a "0", or a
+    // pair of zeroes, and none of those is a place.
+    const [lat, lon] = cleanLocationParams(tag(xml, "latitude"), tag(xml, "longitude"))
+
+    const result: CallInfoLookup = {
+      // HamQTH answers in lower case, whatever was asked.
+      call: tag(xml, "callsign")?.toUpperCase() ?? call,
+      // Named so the app can say where this came from, and so the merge can
+      // tell your answer from another source's.
+      source: "hamqth.com",
+      scope: "general",
+      name,
+      location: [city, state].filter((x) => x).join(", "),
+      city,
+      state,
+      country: tag(xml, "country"),
+      grid: tag(xml, "grid"),
+      lat,
+      lon,
+    }
+    return [result]
+  } catch (e) {
+    // A lookup that throws takes down the call-info panel for every source,
+    // not just this one.
+    host.log(`HamQTH lookup failed for ${call}: ${(e as Error).message ?? e}`)
+    return []
+  }
+}
+
+/// What the operator fills in under Settings → Accounts.
+///
+/// `testCredentials` returns a STRING to show them — it is the only feedback
+/// they get that a password is right, so make it name what was found rather
+/// than saying "OK".
+const HamQTHAccount = {
+  label: "HamQTH.com",
+  description: "A free account at hamqth.com, for callsign lookups",
+  kvKey: "k2hrc-hamqth",
+  // The same login on every device the operator owns, so it rides iCloud
+  // Keychain. A per-install credential (a device key, a sync token) must NOT
+  // set this.
+  synchronizable: true,
+  fields: [
+    { key: "username", label: "Username", type: "text" as const },
+    { key: "password", label: "Password", type: "secret" as const },
+  ],
+
+  async testCredentials(credentials: Record<string, string>, _ctx: HookContext): Promise<string> {
+    const username = (credentials.username || "").trim()
+    if (!username || !credentials.password) return "Enter your HamQTH username and password"
+
+    try {
+      const response = await host.fetch(
+        `${API}?u=${encodeURIComponent(username)}&p=${encodeURIComponent(credentials.password)}`)
+      const sessionId = tag(response.body, "session_id")
+      if (!sessionId) return tag(response.body, "error") ?? `HamQTH returned HTTP ${response.status}`
+
+      const check = await host.fetch(
+        `${API}?id=${sessionId}&callsign=${encodeURIComponent(username)}&prg=${PROGRAM}`)
+      const name = tag(check.body, "adr_name")
+      return `✅ ${username.toUpperCase()}${name ? `: ${name}` : ""}`
+    } catch (e) {
+      return `Could not reach HamQTH: ${(e as Error).message ?? e}`
+    }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    // No `priority`, which means 0 — and 0 is where a third-party callbook
+    // belongs. The ladder it lands in: the operator's own call notes at 100,
+    // QRZ at 99, the Ham2K lookup service at 10, and Call History last at -1,
+    // deliberately below the 0 an undeclared hook defaults to, because the log
+    // describes a station whenever it was last worked while a live source
+    // describes it today.
+    //
+    // So the default already reads "a real source, but not one that outranks
+    // what the operator typed or what the core provides". Set a priority only
+    // when you mean to move against that, and know which source you are
+    // stepping over.
+    registerHook("lookup", { hook: { lookupCall }, key: manifest.key })
+    registerHook("account", { hook: HamQTHAccount, key: manifest.key })
+  },
+})

package/samples/k2hrc-llota/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-llota/manifest.json

@@ -0,0 +1,25 @@
+{
+  "key": "k2hrc-llota",
+  "name": "Lakes on the Air (sample)",
+  "shortName": "LLOTA*",
+  "version": "1.0.0",
+  "description": "Lake references and activation scoring, as a worked example",
+  "category": "activity",
+  "icon": "waves",
+  "accentColor": "#2F7FA6",
+  "api": 1,
+  "keywords": ["lakes", "activation", "hunting", "sample"],
+  "hooks": ["activity", "adifFields", "adifImport", "dataFile", "ref:k2hrcLlota", "ref:k2hrcLlotaActivation", "scoring"],
+  "domains": ["llota.app"],
+  "relevance": { "continents": ["SA"] },
+  "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-llota/src/index.ts

@@ -0,0 +1,172 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// SAMPLE — an award program: references, an offline list, and activation
+// scoring.
+//
+// This is the shape of POTA, SOTA, WWFF and a dozen others, and almost none of
+// it is written by hand. `referenceActivity()` builds the reference handler,
+// the logging controls and the ADIF fields from one description; the manifest
+// says which `ref:` types they answer for. What is left for you is what the
+// program actually is: its reference format, where the list comes from, and
+// what it takes to activate.
+//
+// Modelled on LLOTA (Lakes and Lagoons on the Air) and using its public list.
+// The reference TYPES are namespaced to this sample (`k2hrcLlota`), so
+// installing it cannot collide with the real LLOTA extension's records.
+//
+// What this sample leaves out: the spot feed and spot posting, which need an
+// API key the program issues, and the export hooks that submit a log. See
+// `docs/hooks.md` §`spots` and §`export`.
+
+import {
+  activityScorer,
+  contestScorer,
+  defineExtension,
+  referenceActivity,
+} from "@ham2k/extension-sdk"
+import type { DataFileDefinition, HookContext } from "@ham2k/extension-sdk"
+import { locationToGrid6 } from "@ham2k/lib-geo-tools"
+
+import manifest from "../manifest.json" with { type: "json" }
+
+/// The type a QSO carries for a lake the OTHER station was at, and the type an
+/// operation carries while activating one. Two types, because they are two
+/// different claims about the same reference.
+const HUNTING_TYPE = "k2hrcLlota"
+const ACTIVATION_TYPE = "k2hrcLlotaActivation"
+
+const REFERENCE_REGEX = /^LL[A-Z0-9]+-(?:[0-9]{4,5}|TEST)$/i
+
+/// Every user-visible string reaches the SDK through a translator, so that one
+/// written against several locales needs no different wiring. A real extension
+/// builds this with `createCachedTranslator` over its own JSON files — see
+/// `activities/*/src/i18n.ts` in the app's repository. This is the smallest
+/// thing with the right shape.
+///
+/// `invalidReference` and `unknownReference` are the vocabulary
+/// `referenceActivity` looks up; `activationControl` and `huntingControl` name
+/// the two logging controls it builds.
+const STRINGS: Record<string, string> = {
+  invalidReference: "Not a lake reference",
+  unknownReference: "Unknown lake",
+  activationControl: "Lake",
+  huntingControl: "Lake",
+}
+const tFor = (_ctx: { locale?: string }) => (key: string) => STRINGS[key] ?? key
+
+/// What it takes to activate: ten contacts in a UTC day.
+///
+/// `uniquePer` is the rule that decides when a repeat contact counts AGAIN —
+/// here, a station already worked is worth another contact on a new band, a
+/// new mode, a new day, or at a different lake. Get this wrong and the score
+/// is wrong in a way no test of yours will notice, because it only shows up on
+/// the second QSO with the same station.
+const SCORING = {
+  label: "LLOTA",
+  icon: manifest.icon,
+  activationType: ACTIVATION_TYPE,
+  huntingType: HUNTING_TYPE,
+  qsosToActivate: 10,
+  // Several lakes activated at once, and one contact crediting several hunted
+  // ones. Programs genuinely differ here; most of the simpler awards do not
+  // allow it, and the default is false.
+  allowsMultipleReferences: true,
+  uniquePer: ["band", "mode", "day", "ref"] as const,
+  activates: "daily" as const,
+}
+
+const { refHandler, activityHook, adifFieldsHook, adifImportHook } = referenceActivity({
+  key: "k2hrc-llota",
+  label: "LLOTA",
+  activationType: ACTIVATION_TYPE,
+  huntingType: HUNTING_TYPE,
+  referenceRegex: REFERENCE_REGEX,
+  icon: manifest.icon,
+  color: manifest.accentColor,
+  placeholder: "LLUS-0001",
+  tFor,
+  // Where the `lookups` rows below are written and read. It must match the
+  // data file's `category`, or the handler will look up references nothing
+  // ever stored.
+  category: "k2hrc-llota",
+  linkUrl: (reference: string) => `https://llota.app/list/ref/${encodeURIComponent(reference)}`,
+  // One ADIF record per hunted lake rather than one naming them all. The
+  // programs disagree, and it decides how many contacts the award sees.
+  splitRecordsPerHuntedRef: true,
+  adifRefField: "LLOTA",
+  // Read off the scoring rule rather than restated, so the control and the
+  // scorer cannot disagree about whether this award allows n-fers.
+  allowsMultiple: SCORING.allowsMultipleReferences,
+})
+
+/// The reference list, downloaded and kept offline.
+///
+/// This is what makes a reference resolve to a lake's name in the field, with
+/// no signal and no per-reference API. The host does the fetching, the
+/// scheduling and the storage; the extension's whole job is turning one
+/// entry of somebody else's JSON into one row.
+const referenceList: DataFileDefinition = {
+  key: "k2hrc-llota-references",
+  name: (_args: Record<string, never>, _ctx: HookContext) => "LLOTA Lakes",
+  description: (_args: Record<string, never>, _ctx: HookContext) => "Every lake reference, for offline lookup",
+  url: "https://llota.app/api/public/references?version=lite",
+  maxAgeInDays: 30,
+  fetchType: "json",
+  category: "k2hrc-llota",
+
+  jsonToLookupEntry: (entry: Record<string, any>) => {
+    const ref = String(entry?.reference_code ?? "").trim().toUpperCase()
+    // Returning null drops the entry. A list of this size will contain a few
+    // rows that are not references, and throwing would abandon the rest.
+    if (!ref) return null
+
+    const lat = typeof entry?.latitude === "number" ? entry.latitude : undefined
+    const lon = typeof entry?.longitude === "number" ? entry.longitude : undefined
+
+    return {
+      // The country part of the code (`LLUS` of `LLUS-0001`), which is how an
+      // operator narrows a search to their own country.
+      subCategory: ref.split("-")[0],
+      key: ref,
+      name: entry?.name,
+      lat,
+      lon,
+      flags: 1,
+      data: {
+        ref,
+        name: entry?.name,
+        location: ref.split("-")[0],
+        // The grid is DERIVED from the coordinate, never stored instead of it:
+        // where both are present the pair outranks the grid, and a grid with
+        // no coordinate behind it would quietly lose precision the list had.
+        grid: lat != null && lon != null ? locationToGrid6(lat, lon) : undefined,
+        lat,
+        lon,
+      },
+    }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    // One handler, both types: an activation and a hunted reference are the
+    // same lake, validated and decorated the same way.
+    registerHook(`ref:${HUNTING_TYPE}`, { hook: refHandler, key: manifest.key })
+    registerHook(`ref:${ACTIVATION_TYPE}`, { hook: refHandler, key: manifest.key })
+    registerHook("activity", { hook: activityHook, key: manifest.key })
+    registerHook("adifFields", { hook: adifFieldsHook, key: manifest.key })
+    registerHook("adifImport", { hook: adifImportHook, key: manifest.key })
+    registerHook("dataFile", { hook: referenceList, key: "k2hrc-llota-references" })
+    // `contestScorer` wraps the activity rules in the scoring hook's own
+    // interface, and `scope` is what keeps this scorer out of operations that
+    // have nothing to do with the program.
+    registerHook("scoring", {
+      hook: contestScorer(activityScorer(SCORING), {
+        scope: { refTypes: [ACTIVATION_TYPE, HUNTING_TYPE], huntingRefTypes: [HUNTING_TYPE] },
+      }),
+      key: manifest.key,
+    })
+  },
+})

package/samples/k2hrc-radio/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-radio/manifest.json

@@ -0,0 +1,23 @@
+{
+  "key": "k2hrc-radio",
+  "name": "Radio Readout",
+  "shortName": "Radio",
+  "version": "1.0.0",
+  "description": "A big band, mode and frequency readout across the room",
+  "category": "dashboard",
+  "icon": "radio-tower",
+  "accentColor": "#4C6EF5",
+  "api": 1,
+  "keywords": ["radio", "frequency", "band", "panel", "sample"],
+  "hooks": ["panel"],
+  "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-radio/src/index.ts

@@ -0,0 +1,145 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// SAMPLE — an HTML panel: what the radio is doing, big enough to read from
+// across the room.
+//
+// A panel returns a DOCUMENT, not widgets, and `html` is the escape hatch for
+// when `markdown` cannot express the layout. It buys you exactly one thing —
+// arbitrary CSS — and costs several:
+//
+//   * No JavaScript. None. The document is static from the moment it renders,
+//     so anything that changes has to come from another render.
+//   * No network for subresources. Fonts, images and stylesheets must be
+//     inlined, as text or as `data:` URIs.
+//   * No navigation. A link the operator taps opens in their browser; one the
+//     document triggers itself is blocked.
+//   * It does not render at all where there is no web view — Linux, Windows
+//     without WebView2, and the web build. The pane says so, which is a worse
+//     experience than markdown that simply works.
+//
+// So reach for `markdown` first: it renders with the app's own typography,
+// theme, font scale and density, and costs no web view. This panel earns the
+// escape hatch because a readout is about type size and nothing else.
+//
+// See `docs/hooks.md` §`panel` for the whole contract, including `form`,
+// `multiple` and every trigger name.
+
+import { defineExtension } from "@ham2k/extension-sdk"
+import type { HookContext, PanelContent, PanelDescriptor, PanelHook, PanelRenderArgs } from "@ham2k/extension-sdk"
+
+import manifest from "../manifest.json" with { type: "json" }
+
+/// A still image for the panel picker. It carries its own pixels — never a URL,
+/// because the list renders offline and a remote preview would make opening it
+/// a network fetch (and a beacon).
+const PREVIEW = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <rect x="2" y="5" width="20" height="14" rx="2" fill="#4C6EF5"/>
+  <rect x="4" y="8" width="16" height="5" rx="1" fill="#1B2559"/>
+  <rect x="5.5" y="9.5" width="9" height="2" rx="1" fill="#8FA4FF"/>
+  <circle cx="7" cy="16" r="1.2" fill="#1B2559"/>
+  <circle cx="11" cy="16" r="1.2" fill="#1B2559"/>
+</svg>`
+
+/// Everything that reaches the document goes through here.
+///
+/// The values below are the operator's own — a callsign they typed, a mode
+/// their radio reported — and none of it is trusted markup. A panel that
+/// interpolates raw strings into HTML is one odd character away from a
+/// document that does not parse, and the sandbox is a mitigation, not a reason
+/// to skip this.
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}
+
+/// 14074000 → "14.074.0" — the grouping a radio's own display uses, which is
+/// what makes a frequency readable at a glance rather than counted digit by
+/// digit.
+function formatFrequency(hz: number): string {
+  const khz = hz / 1000
+  const whole = Math.floor(khz)
+  const fraction = Math.round((khz - whole) * 10)
+  return `${whole.toLocaleString("en-US").replace(/,/g, ".")}.${fraction}`
+}
+
+const RadioPanel: PanelHook = {
+  async getPanels(_args: Record<string, never>, _ctx: HookContext): Promise<PanelDescriptor[]> {
+    return [
+      {
+        key: "readout",
+        title: "Radio Readout",
+        description: "Band, mode and frequency, in large type",
+        icon: manifest.icon,
+        preview: PREVIEW,
+        // `on` is a refresh BUDGET, not a subscription: every trigger named
+        // here is paid by every placement of this panel, every time it fires.
+        //
+        // 'qso' is the expensive one — it is the whole QSO being composed, and
+        // it changes as fast as the operator types (the host debounces it to
+        // one wake per pause). It is the right trigger here anyway, because
+        // the band and mode on that draft ARE the radio's, and they are what
+        // this panel exists to show. A panel wanting only a resolved callsign
+        // should declare 'lookup' instead and get far fewer renders.
+        on: ["qso", "operation"],
+      },
+    ]
+  },
+
+  async render(args: PanelRenderArgs, _ctx: HookContext): Promise<PanelContent> {
+    const qso = (args.qso ?? {}) as Record<string, any>
+
+    // `args.qso` is absent unless some panel in the arrangement asked for it —
+    // which this one does. It is still absent when there is no logging panel
+    // in the view at all, so the empty state is a real state, not a bug.
+    const band = typeof qso.band === "string" ? qso.band : ""
+    const mode = typeof qso.mode === "string" ? qso.mode : ""
+    const freq = typeof qso.freq === "number" ? qso.freq : undefined
+
+    const primary = freq ? formatFrequency(freq) : band || "—"
+    const unit = freq ? "kHz" : ""
+
+    // One inline stylesheet, no external anything, and `prefers-color-scheme`
+    // rather than a fixed palette: the panel sits inside the app's own theme,
+    // and a readout that stays white at night is a readout nobody uses at
+    // night. `vw` units so the type grows with the pane rather than the pane
+    // scrolling.
+    const content = `<style>
+  :root { color-scheme: light dark; }
+  body {
+    margin: 0; height: 100vh;
+    display: flex; flex-direction: column;
+    align-items: center; justify-content: center;
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    background: #fff; color: #1B2559;
+  }
+  .frequency { font-size: min(18vw, 22vh); font-weight: 600; line-height: 1; letter-spacing: -0.02em; }
+  .unit { font-size: min(4vw, 5vh); opacity: 0.5; margin-left: 0.3em; }
+  .details { margin-top: 0.6em; font-size: min(6vw, 7vh); letter-spacing: 0.08em; opacity: 0.75; }
+  .details span + span::before { content: "·"; margin: 0 0.5em; opacity: 0.4; }
+  .idle { opacity: 0.4; font-size: min(5vw, 6vh); }
+  @media (prefers-color-scheme: dark) {
+    body { background: #10121A; color: #E8ECFF; }
+  }
+</style>
+<div class="frequency">${escapeHtml(primary)}<span class="unit">${unit}</span></div>
+<div class="details">
+  ${band ? `<span>${escapeHtml(band)}</span>` : ""}
+  ${mode ? `<span>${escapeHtml(mode)}</span>` : ""}
+  <span>${args.qsoCount} Q</span>
+</div>
+${freq || band ? "" : '<div class="idle">No radio connected</div>'}`
+
+    return { kind: "html", content }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook("panel", { key: manifest.key, hook: RadioPanel })
+  },
+})