@ham2k/extension-sdk 0.4.0 → 0.5.1

package/AGENTS.md

@@ -81,7 +81,7 @@ will actually call.
 
 | Doing this | Read |
 | --- | --- |
-| Anything, before the reference — a whole worked extension of that shape | `samples/`: `k2hrc-hamqth` (lookup + credentials), `k2hrc-llota` (award program), `k2hrc-cqww` (contest + scoring), `k2hrc-radio` (HTML panel) |
+| Anything, before the reference — a whole worked extension of that shape | `samples/`: `k2hrc-hamqth` (lookup + credentials), `k2hrc-llota` (award program), `k2hrc-cqww` (contest + scoring), `k2hrc-radio` (HTML panel), `k2hrc-svg-scenes` (experimental interactive SVG) |
 | Any hook at all — what the category is, what it's handed, what it must return | `docs/hooks.md`, the section named for the category |
 | A pane in a view: `getPanels`, `render`, panel content kinds | `docs/hooks.md` §`panel` |
 | Callsign lookups, spot sources, exporters, reference types (POTA-style) | `docs/hooks.md` §`lookup`, §`spots`, §`export`, §`ref:<type>` |

package/dist/index.d.ts

@@ -1,4 +1,121 @@
-// @ham2k/extension-sdk 0.4.0
+// @ham2k/extension-sdk 0.5.1
+/** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
+export interface SvgScene {
+	version: 1;
+	width: number;
+	height: number;
+	values: Record<string, number>;
+	layers: SvgSceneLayer[];
+	controls?: SvgSceneControl[];
+}
+/** A clamped, linear mapping. No expressions or extension code run per frame. */
+export interface SceneBinding {
+	value: string;
+	/** Transform the source before mapping (for example selecting a display digit). */
+	scale?: number;
+	truncate?: boolean;
+	modulo?: number;
+	input: [
+		number,
+		number
+	];
+	output: [
+		number,
+		number
+	];
+	/** Optional equally spaced output samples over input; replaces the output ramp. */
+	samples?: number[];
+}
+export interface SvgSceneLayer {
+	id: string;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	/** Supply exactly one of svg or text. SVG must be self-contained. */
+	svg?: string;
+	/** Exactly one of literal/value. Use text layers, not SVG <text>, for font support.
+	 * Size is unscaled; the host applies OS text scaling once. */
+	text?: {
+		value?: string;
+		literal?: string;
+		prefix?: string;
+		suffix?: string;
+		decimals?: number;
+		size?: number;
+		color?: string;
+		samples?: (number | string)[];
+		/** Multiply numeric text values before formatting. Defaults to 1. */
+		scale?: number;
+		/** Numeric formatting after scaling: truncate, then modulo, then zero padding. */
+		truncate?: boolean;
+		modulo?: number;
+		minIntegerDigits?: number;
+		fontFamily?: string;
+		fontWeight?: number;
+		lineHeight?: number;
+		letterSpacing?: number;
+		/** Horizontal alignment within the layer. Defaults to start. */
+		align?: "start" | "center" | "end";
+	};
+	rotation?: SceneBinding;
+	translateX?: SceneBinding;
+	translateY?: SceneBinding;
+	opacity?: SceneBinding;
+	/** Rotation origin as fractions of this layer's dimensions; default [0.5, 0.5]. */
+	pivot?: [
+		number,
+		number
+	];
+	transitionMs?: number;
+	/** Local deterministic flicker/pulse; pauses when hidden, disabled for reduced motion. */
+	pulse?: {
+		periodMs: number;
+		minOpacity: number;
+		flicker?: boolean;
+	};
+}
+export interface SvgSceneControl {
+	id: string;
+	label: string;
+	kind: "button" | "slider" | "knob";
+	/** A button can open a native dropdown. Picking an item sends its event as the action. */
+	menu?: {
+		label: string;
+		event: string;
+	}[];
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	/** Omit event for local-only interaction (for example a chart inspection cursor). */
+	event?: string;
+	/** Send coalesced change events during dragging, plus the final commit. */
+	continuous?: boolean;
+	value?: string;
+	min?: number;
+	max?: number;
+	step?: number;
+	/** Equal-width buckets, with one bucket per step (useful for hourly charts). */
+	discrete?: boolean;
+	/** Inspect on hover. Only allowed on local-only sliders; touch/keyboard also work. */
+	hover?: boolean;
+	/** Accessible descriptions indexed by (value - min) / step. */
+	valueLabels?: string[];
+	/** Knobs use relative horizontal/upward dragging. Default: step per scene unit. */
+	sensitivity?: number;
+}
+export interface PanelSceneEvent {
+	controlId: string;
+	action: string;
+	phase: "activate" | "change" | "commit";
+	sequence: number;
+	value?: number;
+}
+/** Patch only named scene values. The host ignores stale responses. */
+export interface PanelSceneEventResult {
+	values: Record<string, number>;
+}
 export type CallInfo = {
 	call: string;
 	baseCall?: string;
@@ -807,6 +924,8 @@ export interface ExtensionManifest {
 	domains?: string[];
 	allowUserAgentOverride?: boolean;
 	requiresLocation?: boolean;
+	requiresRadioRead?: boolean;
+	requiresRadioWrite?: boolean;
 	experiments?: string[];
 	relevance?: ExtensionRelevance;
 	translations?: Record<string, {
@@ -1122,7 +1241,75 @@ export interface PanelDescriptor {
 	multiple?: boolean;
 	form?: SettingsField[];
 }
+/** Resolved host typography; sizes are logical pixels, not the app Font Scale. */
+export interface PanelTypography {
+	fontFamily: string | null;
+	fontFamilyFallback: string[];
+	fontSize: number;
+	/** OS text scaling at this exact role size (the scaler may be nonlinear). */
+	scaledFontSize: number;
+	fontWeight: number;
+	lineHeight: number;
+	letterSpacing: number;
+}
+/** Current placement environment. Never multiply coordinates by devicePixelRatio. */
+export interface PanelEnvironment {
+	version: 1;
+	width: number;
+	height: number;
+	safeInsets: {
+		left: number;
+		top: number;
+		right: number;
+		bottom: number;
+	};
+	brightness: "light" | "dark";
+	colors: Record<"surface" | "surfaceContainer" | "onSurface" | "onSurfaceVariant" | "accent" | "primary" | "onPrimary" | "secondary" | "outline" | "outlineVariant" | "error" | "onError", string>;
+	typography: Record<"body" | "label" | "title" | "display" | "mono", PanelTypography>;
+	locale: string;
+	textDirection: "ltr" | "rtl";
+	devicePixelRatio: number;
+	reducedMotion: boolean;
+	highContrast: boolean;
+}
+/** A local CAT radio. Values are reported readings, never manual VFO fallbacks. */
+export interface PanelRadioState {
+	id: string | null;
+	name: string | null;
+	status: "disconnected" | "connecting" | "connected" | "disconnecting" | "error";
+	stale: boolean;
+	problem: string | null;
+	frequencyHz: number | null;
+	mode: string | null;
+	powerWatts: number | null;
+	transmitting: boolean | null;
+	meters: Partial<Record<"signalDbm" | "powerOut" | "swr" | "alc" | "supplyVolts", number>>;
+	canTune: boolean;
+}
+export interface PanelRadioTune {
+	/** Reject if this identity no longer matches the selected radio. */
+	id: string;
+	/** Pin a local radio by ID; omitted means follow the designated radio. */
+	selection?: string;
+	frequencyHz?: number;
+	mode?: "LSB" | "USB" | "CW" | "AM" | "FM";
+}
+export interface PanelRadioTuneResult {
+	/** Accepted by the host; confirmation still comes from reported state. */
+	accepted: boolean;
+	reason?: "changed" | "disconnected" | "transmitting" | "invalid";
+	state: PanelRadioState | null;
+}
 export interface PanelRenderArgs {
+	/** Present on environment-capable hosts. Changes automatically request a throttled render of an `svgScene` panel. */
+	environment?: PanelEnvironment;
+	/** Display time follows developer time travel; real time is for network retry/cache budgets. */
+	clock?: {
+		nowMillis: number;
+		realNowMillis: number;
+	};
+	/** Stable placement identity, supplied by scene-capable hosts. */
+	instanceId?: string;
 	panelKey: string;
 	operation: Record<string, JSONValue>;
 	qso?: Record<string, JSONValue>;
@@ -1131,6 +1318,11 @@ export interface PanelRenderArgs {
 	reason: string;
 }
 export type PanelContent = {
+	kind: "svgScene";
+	scene: SvgScene;
+	title?: string;
+	triggers?: string[];
+} | {
 	kind: "markdown";
 	content: string;
 	title?: string;
@@ -1149,6 +1341,9 @@ export type PanelContent = {
 export interface PanelHook {
 	getPanels(args: Record<string, never>, ctx: HookContext): Promise<PanelDescriptor[]>;
 	render(args: PanelRenderArgs, ctx: HookContext): Promise<PanelContent>;
+	onEvent?(args: PanelRenderArgs & {
+		event: PanelSceneEvent;
+	}, ctx: HookContext): Promise<PanelSceneEventResult>;
 }
 /**
  * The standard per-extension translator: takes the extension's i18next
@@ -1458,6 +1653,14 @@ export declare const hooks: {
 	}[]>;
 };
 export declare const host: {
+	listRadios(): Promise<PanelRadioState[]>;
+	readRadio(id?: string): Promise<PanelRadioState | null>;
+	setRadioConnection(args: {
+		id: string;
+		selection?: string;
+		connected: boolean;
+	}): Promise<PanelRadioTuneResult>;
+	tuneRadio(args: PanelRadioTune): Promise<PanelRadioTuneResult>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
 	kvGet(key: string): Promise<JSONValue | null>;
 	getLocation(): Promise<DeviceLocation | null>;

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./types.js";
+export * from "./svgScene.js";
 export * from "./i18n.js";
 export * from "./dxcc.js";
 export * from "./location.js";
@@ -60,6 +61,18 @@ const hooks = {
   }
 };
 const host = {
+  async listRadios() {
+    return await hostCallFn()("listRadios", {});
+  },
+  async readRadio(id) {
+    return await hostCallFn()("readRadio", { ...id ? { id } : {} });
+  },
+  async setRadioConnection(args) {
+    return await hostCallFn()("setRadioConnection", { ...args });
+  },
+  async tuneRadio(args) {
+    return await hostCallFn()("tuneRadio", { ...args });
+  },
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },

package/dist/templateContext.js

@@ -60,6 +60,7 @@ function qsoValues(qso) {
   const their = qso.their ?? {};
   const our = qso.our ?? {};
   const startMillis = Number(qso.startAtMillis ?? 0);
+  const serialSent = refField(qso.refs, "ourSerial");
   return {
     call: their.call ?? "",
     their,
@@ -71,12 +72,31 @@ function qsoValues(qso) {
     // sides — `qso.our.sent` is what WE sent, i.e. the report they received.
     rstSent: our.sent ?? "",
     rstRcvd: their.sent ?? "",
+    // Unpadded, as stored: `001` or `1` is the operator's call, not the
+    // contest's, so it is left to the `pad` filter.
+    serialSent,
+    serialRcvd: refField(qso.refs, "theirSerial"),
+    // The short forms are the SENT side: a CW message is what we send, and
+    // that is where these get typed.
+    rst: our.sent ?? "",
+    serial: serialSent,
     notes: qso.notes ?? "",
     refs: qso.refs ?? [],
     ...startMillis > 0 ? dateValues(startMillis) : { date: "", dateCompact: "", time: "", at: "" },
     startAtMillis: startMillis
   };
 }
+function refField(refs, field) {
+  if (!Array.isArray(refs)) return "";
+  for (const ref of refs) {
+    if (ref === null || typeof ref !== "object" || Array.isArray(ref)) continue;
+    const value = ref[field];
+    if (typeof value !== "string" && typeof value !== "number") continue;
+    const text = String(value).trim();
+    if (text !== "") return text;
+  }
+  return "";
+}
 function logValues(values) {
   return {
     station: values.station ?? "",

package/dist/templates.js

@@ -30,7 +30,16 @@ function registerFilters(liquid2) {
     (value) => String(value ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")
   );
   liquid2.registerFilter("alnum", (value) => String(value ?? "").replace(/[^A-Za-z0-9]/g, ""));
+  liquid2.registerFilter("pad", (value, width = 3) => {
+    const text = String(value ?? "").trim();
+    return text === "" ? "" : text.padStart(Number(width) || 0, "0");
+  });
+  liquid2.registerFilter("cut", (value, digits = "09") => {
+    const chosen = String(digits ?? "");
+    return String(value ?? "").replace(/[0159]/g, (digit) => chosen.includes(digit) ? CUT_NUMBERS[digit] : digit);
+  });
 }
+const CUT_NUMBERS = { "0": "T", "1": "A", "5": "E", "9": "N" };
 class TemplateError extends Error {
   constructor(message, options) {
     super(message);

package/docs/hooks.md

@@ -1237,6 +1237,7 @@ own identity, config form and refresh budget.
 interface PanelHook {
   getPanels(args: {}, ctx): Promise<PanelDescriptor[]>
   render(args: PanelRenderArgs, ctx): Promise<PanelContent>
+  onEvent?(args: PanelRenderArgs & {event: PanelSceneEvent}, ctx): Promise<PanelSceneEventResult>
 }
 // PanelDescriptor: {key, title, description?, icon?, preview?, on?, form?}
 // PanelRenderArgs: {panelKey, operation, qso?, qsoCount, config, reason}
@@ -1247,6 +1248,101 @@ The host addresses a panel as `ext:<hookKey>:<key>`, and that id is stored
 inside saved layouts — renaming a `key` drops the panel out of every
 arrangement holding it.
 
+An experimental fourth kind, `svgScene`, adds native SVG layers, numeric bindings,
+local controls, and host-run animations. Its payload is `{kind: 'svgScene', scene,
+title?, triggers?}`; it does not have a `content` string. Scene-capable hosts pass
+`instanceId` on render/event calls. `onEvent` handles control events and returns
+numeric value patches; local-only controls and animation frames make no bridge
+calls. Controls with `continuous: true` send `change` events during dragging and a
+final `commit` on release; pending movements are coalesced to the newest value.
+Numeric text supports `scale`, `truncate`, `modulo`, and `minIntegerDigits`
+for local numeric formatting. The Radio Panel Example uses these for its Modern
+frequency groups; its settings offer Modern/LCD styles and radio selection. Local sliders may use `hover` and `discrete` hourly buckets. Text `samples`
+may hold numbers or preformatted strings; control `valueLabels` supplies accessible
+value descriptions. Transform/opacity bindings may also supply numeric `samples`,
+equally spaced over their `input` range, instead of the `output` ramp. The host
+interpolates and clamps these locally; chart markers and callouts can follow
+individual readings without bridge calls. See [the prototype contract and migration plan](https://github.com/ham2k/halo/blob/main/docs/design/svg-scenes.md)
+and the `k2hrc-svg-scenes` sample. This API is experimental.
+
+Scene-capable hosts also supply `args.environment` on **render and event** calls:
+
+- `width`, `height`, and `safeInsets` describe the current panel in logical pixels.
+  The app's Font Scale is already applied to this coordinate space. Do not multiply
+  coordinates by a font-scale preference or `devicePixelRatio`.
+- `brightness` is resolved to `light` or `dark`, including system theme changes.
+  `colors` contains `surface`, `surfaceContainer`, `onSurface`, `onSurfaceVariant`,
+  `accent`, `primary`, `onPrimary`, `secondary`, `outline`, `outlineVariant`,
+  `error`, and `onError`, all `#RRGGBB` strings.
+- `typography` contains `body`, `label`, `title`, `display`, and `mono` roles, each
+  with `fontFamily`, fallbacks, `fontSize`, `scaledFontSize`, `fontWeight`,
+  `lineHeight`, and `letterSpacing`. Family can be null for a platform default.
+  `scaledFontSize` describes OS accessibility scaling **at that role's size**;
+  do not assume one linear factor for all sizes. Use it when reserving label space.
+  Supply the unscaled `fontSize` as scene text `size`: the host scales text once.
+- `locale`, `textDirection`, `devicePixelRatio`, `reducedMotion`, and `highContrast`
+  describe the resolved presentation context. Font names refer to host fonts;
+  they are not URLs or permission to load remote fonts.
+
+For a panel showing an `svgScene`, environment changes automatically request a
+render through the existing throttle, even with no triggers declared. Hidden
+panels catch up on reveal; repeated resize updates coalesce; a scene laid out for
+an old environment cannot overwrite a newer one. Markdown and HTML panels are
+themed and laid out by the host, so an environment change does not re-render
+them; their next render carries the current environment.
+`args.clock.nowMillis` follows the app clock; `realNowMillis` is for network retry
+and cache budgets, so developer time travel does not hammer an external API.
+Both `environment` and `clock` are optional in the SDK for older-host detection.
+
+Use scene **text layers** for typography; SVG `<text>` is not a portable text path
+through the renderer. Text supports either `literal` or bound `value`, plus
+`fontFamily`, `fontWeight`, `lineHeight`, and `letterSpacing`. Text participates
+in native directionality, accessibility scaling and semantics.
+Button controls can supply `menu: [{label, event}]` to open a native dropdown.
+Selecting an item emits its `event` as the action with the original control ID;
+dismissing the menu emits nothing.
+
+The `svg-weather`, `svg-solar`, and `svg-radio` reference panels live in
+[ham2k/extensions](https://github.com/ham2k/extensions/tree/main/extensions/dashboard).
+They use public host APIs and ship as `.h2kext` packages, not app assets.
+Install the packages, then add their panels through Edit Layout. Their original
+extension and panel keys are retained so existing placements and settings survive.
+See that repository’s dashboard README for building against the unreleased SDK.
+
+The radio host calls are manifest capabilities, refused unless declared — the
+same shape as `requiresLocation`, and shown to the operator at install:
+`"requiresRadioRead": true` allows `host.listRadios()` and `host.readRadio()`;
+`"requiresRadioWrite": true` allows `host.tuneRadio()` and
+`host.setRadioConnection()`, and implies read, since a command answers with the
+radio's state. An undeclared call rejects rather than answering null.
+
+**Radio Panel Example** is the CAT reference extension. `host.listRadios()` lists configured
+local transceivers. `host.readRadio(id?)` returns
+a **local** radio's reported frequency (Hz), mode, connection state,
+power, TX state and fresh telemetry, or null on hosts without this API.
+`meters.signalDbm` is receive power in whole dBm when supported, refreshed a few
+times a second; it expires after two seconds without a reading. The Flex driver receives the selected slice’s LEVEL
+meter through its native UDP channel. The reference panel draws a segmented
+receive meter and leaves it unlit when unavailable, stale, or transmitting. It does
+not substitute the app's manually entered VFO for a radio reading.
+`host.tuneRadio({id, frequencyHz?, mode?})` targets that same radio through the
+existing VFO/CAT service. Supported mode requests are LSB, USB, CW, AM and FM.
+The host rejects a changed designation, disconnected/stale radio, transmission
+in progress or malformed command, and spaces accepted tuning requests by at
+least 250 ms. Omitting a selection follows the designated logging radio; an explicit `selection`
+pins tuning to that local radio without changing the logging designation.
+An accepted result means requested, not confirmed; only subsequent
+reported state confirms it. Drivers retain their own protocol/echo handling.
+`host.setRadioConnection({id, selection?, connected})` starts or ends a local CAT
+connection using the same selection and identity checks. Acceptance starts the
+operation; follow reported connection state for completion. It does not switch
+the hardware's mains power or initiate transmission. The reference panel samples
+state once per second while visible; knob motion and LCD digit updates run locally,
+and tuning is sent continuously during dragging, paced by the CAT adapter. The
+main readout follows the requested value immediately; confirmation status distinguishes pending requests from the radio
+reporting the requested frequency. Radio-specific hardware verification remains
+necessary before considering the experimental control API stable.
+
 **Content is a document, not widgets** — the same UI-catalog seam every
 other declarative hook sits behind. Prefer `markdown`: it renders with the
 app's own typography, theme, font scale and density, and costs no web view.

package/docs/templates.md

@@ -74,12 +74,22 @@ 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`.
+lookup's answer), `band`, `mode`, `freq`, `rstSent`, `rstRcvd`, `serialSent`,
+`serialRcvd`, `notes`, `date`, `dateCompact`, `time`, `at`, `startAtMillis`,
+`refs` — and two short forms for the sent side, `rst` (= `rstSent`) and
+`serial` (= `serialSent`), since a CW message is what we send and that is
+where these get typed: `{{ qso.call }} {{ qso.rst | cut }} {{ qso.serial | pad: 3 | cut }}`.
 
 `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.
 
+`serialSent` / `serialRcvd` are a contest's serial numbers, blank outside
+one. A contest keeps them on its own ref, so they are found by field name —
+the first ref carrying `ourSerial` / `theirSerial` — which is what lets one
+message serve every serial contest (docs/design/contests.md §5.8). In a CW
+message `serialSent` is the number the serial field is SHOWING, the one the
+QSO will be logged with. It is unpadded (`7`, not `007`): use `pad`.
+
 ### `config` — a panel's own form values
 Whatever that panel's `form` declared, under the keys it used.
 
@@ -112,12 +122,19 @@ with nothing to say it was invented.
 
 All of Liquid's own (`date`, `downcase`, `upcase`, `strip`, `default`,
 `join`, `size`, `first`, `last`, `round`, `truncate`, `replace`, `map`,
-`where`, …), plus two:
+`where`, …), plus four:
 
 | filter | does | example |
 |---|---|---|
 | `dash` | non-alphanumerics → `-`, collapsed and trimmed, **case preserved** | `N0CALL/P` → `N0CALL-P` |
 | `alnum` | strip to alphanumerics | `2026-07-27` → `20260727` |
+| `pad: n` | zero-pad on the left to `n` characters (default 3); **blank stays blank** | `7` → `007` |
+| `cut: "digits"` | CW cut numbers for the listed digits, of `0`→`T` `1`→`A` `5`→`E` `9`→`N`; default `"09"` | `599` → `5NN`, `{{ 9 \| pad: 3 \| cut }}` → `TTN` |
+
+`pad` leaves a blank alone because a CW message can be keyed before the
+serial field has a number, and `000` sent in that gap is a serial the log
+will never agree with. Order matters with `cut`: pad first, or the padding
+zeros go out uncut.
 
 `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
@@ -140,6 +157,10 @@ Each of these was measured against the shipped runtime, not assumed.
 number as SECONDS, so epoch millis render in the year 58567. Use the `…At`
 strings.
 
+**`cut`'s digit list must be quoted.** Liquid reads a bare `0159` as the
+number 159 before the filter sees it, so `{{ n | cut: 09 }}` cuts only the
+nines — the zero is gone with no error. Write `cut: "09"`.
+
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",

package/samples/README.md

@@ -10,6 +10,7 @@ building — the header comment in each `src/index.ts` says what it leaves out.
 | `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 |
+| `k2hrc-svg-scenes` | Experimental SVG controls and animations, with simulated radio and weather panels |
 
 ## Running one
 

package/samples/k2hrc-svg-scenes/README.md

@@ -0,0 +1,24 @@
+# SVG Scene Prototypes
+
+Experimental radio front face and weather inspection chart, using the public
+`svgScene` / `PanelHook.onEvent` contracts. Requires a host with SVG scene support.
+All data is simulated; this extension does not fetch weather or control a radio.
+
+The radio keeps requested frequency separate from reported frequency, simulates
+2-second CAT acknowledgments, and has buttons for external tuning, disconnection,
+and changing acknowledgment delay. Drag the knob horizontally/upward, use the band
+slider, or focus either control and use arrows (Shift for larger steps) / the wheel.
+
+The weather chart demonstrates local-only cursor and numeric sample inspection.
+Drag, click, or use arrows; no interaction events cross the extension bridge.
+
+In this repository:
+
+```sh
+node build.mjs
+node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-svg-scenes.h2kext
+```
+
+For the standalone Flutter preview and migration plan, see
+`docs/design/svg-scenes.md` in the logger repository. This is an API experiment,
+not a replacement for the production weather/solar panels yet.

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

@@ -0,0 +1,31 @@
+{
+  "key": "k2hrc-svg-scenes",
+  "name": "SVG Scene Prototypes",
+  "shortName": "SVG Scenes",
+  "version": "0.1.0",
+  "description": "Experimental radio front face and weather chart; simulated data only",
+  "category": "dashboard",
+  "icon": "radio-tower",
+  "accentColor": "#4C6EF5",
+  "api": 1,
+  "keywords": [
+    "svg",
+    "panel",
+    "sample",
+    "weather",
+    "radio"
+  ],
+  "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-svg-scenes/src/index.ts

@@ -0,0 +1,12 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+import { defineExtension } from '@ham2k/extension-sdk'
+import manifest from '../manifest.json' with { type: 'json' }
+import { createScenePanels } from './scenes.ts'
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook('panel', { key: manifest.key, hook: createScenePanels() })
+  },
+})

package/samples/k2hrc-svg-scenes/src/scenes.ts

@@ -0,0 +1,128 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+import type { PanelContent, PanelHook, SceneBinding, SvgSceneLayer } from '@ham2k/extension-sdk'
+
+const svg = (body: string, width = 640, height = 360) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}">${body}</svg>`
+const bind = (value: string, input: [number, number], output: [number, number]): SceneBinding => ({ value, input, output })
+const label = (x: number, y: number, text: string, size = 16, color = '#9aaec6') =>
+  `<text x="${x}" y="${y}" fill="${color}" font-family="sans-serif" font-size="${size}">${text}</text>`
+const button = (x: number, text: string) => `<rect x="${x}" y="298" width="172" height="38" rx="8" fill="#283b52"/>${label(x + 12, 322, text, 14, '#e7edf4')}`
+const textLayer = (id: string, value: string, x: number, y: number, width: number,
+  size: number, prefix = '', suffix = '', decimals = 0): SvgSceneLayer =>
+  ({ id, x, y, width, height: size + 12, text: { value, prefix, suffix, decimals, size, color: '#a9efcf' } })
+
+type RadioState = { requested: number; reported: number; connected: number; due: number; slow: number }
+/** Inject time for deterministic tests; no timers or per-frame extension work. */
+export function createScenePanels(now: () => number = () => Date.now()): PanelHook {
+  const radios = new Map<string, RadioState>()
+  function state(id: string): RadioState {
+    let s = radios.get(id)
+    if (!s) {
+      // Bounded session-only simulator state; no storage or CAT commands.
+      if (radios.size >= 64) radios.delete(radios.keys().next().value!)
+      s = { requested: 14074, reported: 14074, connected: 1, due: 0, slow: 1 }
+      radios.set(id, s)
+    }
+    if (s.connected && s.due && now() >= s.due) { s.reported = s.requested; s.due = 0 }
+    return s
+  }
+  return {
+    async getPanels() {
+      return [
+        { key: 'radio', title: 'Radio Front Face · Simulation', icon: 'radio-tower', multiple: true, on: ['tick:1'] },
+        { key: 'weather', title: 'Weather Chart · Simulation', icon: 'weather-partly-cloudy', multiple: true },
+      ]
+    },
+    async render(args): Promise<PanelContent> {
+      if (args.panelKey === 'weather') {
+        const temperatures = [17, 18, 21, 24, 25, 23, 20, 18]
+        const points = temperatures.map((t, i) => `${60 + i * 74},${265 - (t - 15) * 14}`).join(' ')
+        return { kind: 'svgScene', scene: {
+          version: 1, width: 640, height: 360, values: { hour: 0 },
+          layers: [
+            { id: 'chart', x: 0, y: 0, width: 640, height: 360, svg: svg(`
+              <rect width="640" height="360" rx="18" fill="#142337"/>
+              ${label(30, 38, 'FORECAST / SIMULATED DATA', 18, '#e7edf4')}
+              ${[15, 20, 25].map(t => `<path d="M60 ${265 - (t - 15) * 14}H580" stroke="#31445b"/>${label(20, 270 - (t - 15) * 14, String(t), 12)}`).join('')}
+              <polyline points="${points}" fill="none" stroke="#8bdccc" stroke-width="4"/>
+              ${temperatures.map((t, i) => `<circle cx="${60 + i * 74}" cy="${265 - (t - 15) * 14}" r="5" fill="#e7edf4"/>${label(52 + i * 74, 288, '+' + i + 'h', 12)}`).join('')}
+              ${label(30, 334, 'Drag the chart to inspect · Arrow keys to step', 14)}
+            `) },
+            { id: 'cursor', x: 59, y: 100, width: 2, height: 172,
+              svg: svg('<rect width="2" height="172" fill="#f7c576"/>', 2, 172),
+              translateX: bind('hour', [0, 7], [0, 518]) },
+            textLayer('hour', 'hour', 30, 52, 250, 24, 'In ', ' hours'),
+            { ...textLayer('temperature', 'hour', 370, 52, 240, 24, '', ' °C'),
+              text: { value: 'hour', samples: temperatures, suffix: ' °C', size: 24, color: '#a9efcf' } },
+          ],
+          controls: [{ id: 'inspect', kind: 'slider', label: 'Forecast hour', x: 60, y: 100, width: 518, height: 185,
+            value: 'hour', min: 0, max: 7, step: 1 }],
+        } }
+      }
+      const s = state(args.instanceId ?? args.panelKey)
+      return { kind: 'svgScene', scene: {
+        version: 1, width: 640, height: 360,
+        values: { requested: s.requested, reported: s.reported, connected: s.connected, slow: s.slow },
+        layers: [
+          { id: 'face', x: 0, y: 0, width: 640, height: 360, svg: svg(`
+            <rect width="640" height="360" rx="18" fill="#142337"/>
+            ${label(28, 35, 'RADIO FRONT FACE / SIMULATED CAT', 18, '#e7edf4')}
+            <rect x="28" y="58" width="350" height="114" rx="12" fill="#0a1622"/>
+            ${label(42, 78, 'REPORTED VFO', 12)}${label(42, 143, 'REQUESTED', 12)}
+            <path d="M417 150 A90 90 0 0 1 597 150" fill="none" stroke="#52657d" stroke-width="5"/>
+            ${label(423, 170, '14.0', 12)}${label(565, 170, '14.35', 12)}
+            ${label(424, 197, 'VFO POSITION', 12)}
+            <path d="M42 236 H332" stroke="#52657d" stroke-width="6"/>
+            ${label(42, 268, 'Band position / kHz', 14)}
+            ${label(548, 256, 'LINK', 12)}
+            ${button(28, 'Connect / disconnect')}${button(234, 'External tune +5 kHz')}${button(440, 'Toggle 2 s / 0 s delay')}
+          `) },
+          textLayer('reported', 'reported', 42, 78, 320, 34, '', ' kHz', 1),
+          textLayer('requested', 'requested', 168, 121, 210, 22, '', '', 1),
+          { id: 'needle', x: 503, y: 72, width: 8, height: 80, pivot: [0.5, 1], transitionMs: 450,
+            svg: svg('<path d="M4 0 L7 80 H1 Z" fill="#f6c673"/>', 8, 80),
+            rotation: bind('reported', [14000, 14350], [-80, 80]) },
+          { id: 'knob', x: 400, y: 204, width: 72, height: 72,
+            svg: svg('<circle cx="36" cy="36" r="34" fill="#31455d" stroke="#7187a0" stroke-width="2"/><path d="M36 8V22" stroke="#f6c673" stroke-width="4"/>', 72, 72),
+            rotation: bind('requested', [14000, 14350], [-150, 150]) },
+          { id: 'handle', x: 36, y: 224, width: 12, height: 24,
+            svg: svg('<rect width="12" height="24" rx="4" fill="#a9efcf"/>', 12, 24),
+            translateX: bind('requested', [14000, 14350], [0, 290]) },
+          { id: 'led', x: 548, y: 208, width: 40, height: 40,
+            svg: svg('<defs><radialGradient id="glow"><stop stop-color="#a9ffbd"/><stop offset="0.3" stop-color="#58e8a2"/><stop offset="1" stop-color="#58e8a2" stop-opacity="0"/></radialGradient></defs><circle cx="20" cy="20" r="20" fill="url(#glow)"/>', 40, 40),
+            opacity: bind('connected', [0, 1], [0.08, 1]), pulse: { periodMs: 1700, minOpacity: 0.55, flicker: true } },
+        ],
+        controls: [
+          { id: 'tune', label: 'Tuning knob, kHz', kind: 'knob', x: 398, y: 202, width: 76, height: 76,
+            value: 'requested', min: 14000, max: 14350, step: 0.1, sensitivity: 0.1, event: 'tune' },
+          { id: 'band', label: 'Band position, kHz', kind: 'slider', x: 42, y: 215, width: 290, height: 42,
+            value: 'requested', min: 14000, max: 14350, step: 0.1, event: 'tune' },
+          ...(['connect', 'external', 'delay'] as const).map((event, i) => ({
+            id: event, label: ['Toggle connection', 'Simulate external tuning', 'Toggle CAT delay'][i],
+            kind: 'button' as const, x: 28 + i * 206, y: 298, width: 172, height: 38, event,
+          })),
+        ],
+      } }
+    },
+    async onEvent(args) {
+      const s = state(args.instanceId ?? args.panelKey)
+      const event = args.event
+      if (event.action === 'connect') { s.connected = 1 - s.connected; s.due = 0; s.requested = s.reported }
+      if (event.action === 'delay') s.slow = 1 - s.slow
+      if (event.action === 'external') {
+        if (!s.connected) throw new Error('Radio disconnected')
+        s.reported = s.reported + 5 > 14350 ? 14000 : s.reported + 5
+        s.requested = s.reported; s.due = 0
+      }
+      if (event.action === 'tune') {
+        if (!s.connected) throw new Error('Radio disconnected')
+        if (typeof event.value !== 'number' || !Number.isFinite(event.value)) throw new Error('Invalid frequency')
+        s.requested = Math.max(14000, Math.min(14350, event.value))
+        s.due = now() + (s.slow ? 2000 : 0)
+        if (!s.slow) { s.reported = s.requested; s.due = 0 }
+      }
+      return { values: { requested: s.requested, reported: s.reported, connected: s.connected, slow: s.slow } }
+    },
+  }
+}