@ham2k/extension-sdk 0.3.0 → 0.5.0

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/README.md

@@ -53,6 +53,26 @@ offline and describe the version installed here rather than whatever the
 repository says today. If an agent is writing your extension, point it at
 `node_modules/@ham2k/extension-sdk/AGENTS.md` — `h2kext-init` does that for you.
 
+## Export types and settings
+
+Export hooks can register shared types with `getExportTypes()`. Use
+`exportTypeDefinition(activationType, format, label)` for an identity shared
+by extensions serving the same activity. `exportType` identifies the settings;
+`exportKey` identifies an individual file, such as one park in an activation.
+
+The `activityExportHook` and `huntingExportHook` helpers register their types
+and forward export settings to the ADIF generator. Reference activity types
+use `templateCategory: 'reference'`; other types use the other-activity defaults.
+`GlobalExportSettings` provides separate normal filename, compact filename,
+and title templates for each category, plus shared ADIF field templates.
+
+When updating an exporter from SDK 0.3, keep a reference-specific identifier
+in `exportKey`, register a stable `exportType`, and forward `exportSettings`,
+`exportData`, `exportTitle`, and `includeLookupData` when delegating generation.
+Per-type custom templates override inherited defaults only when enabled.
+See `docs/hooks.md` §`export` for the complete contract and `docs/forms.md`
+for the `textTemplate` form field.
+
 ## About the peer dependencies
 
 This package lists the libraries the extension host carries — `@ham2k/lib-*`,

package/dist/activityExports.js

@@ -1,3 +1,4 @@
+import { exportTypeDefinition } from "./exportSettings.js";
 import { exportFilename, startMillisOf } from "./exportNames.js";
 import { segmentsWith } from "./segments.js";
 import { createCachedTranslator } from "./i18n.js";
@@ -21,11 +22,23 @@ function filenameFor(operation, qsos, ref, compact) {
 function activityExportHook(rules) {
   const prefix = `${rules.key}-adif`;
   return {
+    async getExportTypes() {
+      return [{
+        ...exportTypeDefinition(rules.activationType, "adif", rules.label),
+        templateCategory: "reference",
+        templateSample: rules.templateSample ?? {
+          log: { ref: "REF-1234", refName: "Example Reference" },
+          operation: { refs: [{ type: rules.activationType, ref: "REF-1234" }] }
+        }
+      }];
+    },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       const refs = refsOfType(operation, rules.activationType);
       const t = tFor(ctx);
       return refs.map((ref) => ({
-        exportType: `${prefix}${SEPARATOR}${ref.ref}`,
+        exportType: `${rules.activationType}-adif`,
+        templateData: { ref: ref.ref, refName: ref.name ?? "", activity: rules.label },
+        exportKey: `${prefix}${SEPARATOR}${ref.ref}`,
         format: "adif",
         // The FORMAT leads: a park activated on a contest weekend offers
         // several files for the same reference, and "POTA US-1234" alone said
@@ -44,10 +57,11 @@ function activityExportHook(rules) {
     },
     async generateExport(args, ctx) {
       const exportType = String(args.exportType ?? "");
-      if (!exportType.startsWith(`${prefix}${SEPARATOR}`)) {
-        throw new Error(`${rules.key}: unknown export type '${exportType}'`);
+      const exportKey = String(args.exportKey ?? "");
+      if (exportType !== `${rules.activationType}-adif` || !exportKey.startsWith(`${prefix}${SEPARATOR}`)) {
+        throw new Error(`${rules.key}: unknown export type/key '${exportType}' / '${exportKey}'`);
       }
-      const wanted = exportType.slice(prefix.length + SEPARATOR.length);
+      const wanted = exportKey.slice(prefix.length + SEPARATOR.length);
       if (!refsOfType(args.operation, rules.activationType).some((r) => r.ref === wanted)) {
         throw new Error(`${rules.key}: operation has no ${rules.activationType} reference '${wanted}'`);
       }
@@ -62,6 +76,10 @@ function activityExportHook(rules) {
         qsos: args.qsos,
         segments: segmentsWith(args.segments, claimOnly),
         includePrivateData: args.includePrivateData,
+        includeLookupData: args.includeLookupData,
+        exportSettings: args.exportSettings,
+        exportData: args.exportData,
+        exportTitle: args.exportTitle,
         mainHandler: rules.key,
         includeFieldsFrom: rules.includeFieldsFrom
       });
@@ -83,17 +101,22 @@ function filenameForHunt(operation, qsos, activity, compact) {
   });
 }
 function huntingExportHook(rules) {
-  const exportType = `${rules.key}-hunter`;
+  const exportType = `${rules.huntingType}-hunter`;
   function huntedQsos(qsos) {
     return qsos.filter((qso) => refsOfType(qso, rules.huntingType).length > 0);
   }
   return {
+    async getExportTypes() {
+      return [{ exportType, format: "adif", label: `${rules.label} Hunter Log` }];
+    },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       if (refsOfType(operation, rules.activationType).length > 0) return [];
       if (huntedQsos(qsos ?? []).length === 0) return [];
       const t = tFor(ctx);
       return [{
         exportType,
+        qsoCount: huntedQsos(qsos ?? []).length,
+        templateData: { activity: rules.label },
         format: "adif",
         label: t("adifForHunter", { program: rules.label }),
         filename: filenameForHunt(operation, qsos ?? [], rules.label, compactFilenames),
@@ -119,6 +142,10 @@ function huntingExportHook(rules) {
         qsos: huntedQsos(args.qsos ?? []),
         segments: args.segments,
         includePrivateData: args.includePrivateData,
+        includeLookupData: args.includeLookupData,
+        exportSettings: args.exportSettings,
+        exportData: args.exportData,
+        exportTitle: args.exportTitle,
         // The hunter file is submitted to ONE program too — see
         // `activityExportHook.generateExport`. `rules.key` is the ACTIVITY's
         // key ('pota'), which is what its `adifFields` hook registers under;
@@ -136,7 +163,7 @@ function huntingExportHook(rules) {
     }
   };
 }
-async function adifForExport({ operation, qsos, segments, includePrivateData, mainHandler, includeFieldsFrom }) {
+async function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }) {
   const { hooks } = await import("@ham2k/extension-sdk");
   const entries = await hooks.invokeOne("export", "adif", "generateExport", {
     operation,
@@ -146,6 +173,10 @@ async function adifForExport({ operation, qsos, segments, includePrivateData, ma
     // Forwarded, or the delegate defaults to withholding and the user's
     // "include private info" setting silently does nothing here.
     includePrivateData,
+    includeLookupData,
+    exportSettings,
+    exportData,
+    exportTitle,
     mainHandler,
     includeFieldsFrom
   });

package/dist/exportSettings.js

@@ -0,0 +1,133 @@
+import { startMillisOf } from "./exportNames.js";
+import { templateContext } from "./templateContext.js";
+import { oneLine, renderTemplate } from "./templates.js";
+import { isTestOperation } from "./testOperation.js";
+const EXPORT_DEFAULTS = {
+  includePrivateData: false,
+  includeLookupData: true,
+  customTemplates: false,
+  filenameTemplate: "{{ op.date }} {{ log.station }}{% if log.ref != blank %} at {{ log.ref }}{% elsif log.activity != blank %} for {{ log.activity }}{% endif %} {{ log.modifier }}",
+  compactFilenameTemplate: "{{ log.station | dash }}{% if log.ref != blank %}@{{ log.ref | dash }}{% elsif log.activity != blank %}-{{ log.activity | downcase | dash }}{% endif %}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  titleTemplate: "{{ log.station }}{% if log.ref != blank %}: {{ log.activity }} at {{ log.ref }} {{ log.refName }}{% elsif log.activity != blank %}: {{ log.activity }}{% endif %} on {{ op.date }}",
+  adifNotesTemplate: "{{ qso.notes }}",
+  adifCommentTemplate: "{{ qso.notes }}",
+  adifQslMessageTemplate: ""
+};
+const GLOBAL_EXPORT_DEFAULTS = {
+  ...EXPORT_DEFAULTS,
+  referenceFilenameTemplate: "{{ op.date }} {{ log.station }} at {{ log.ref }} {{ log.modifier }}",
+  referenceCompactFilenameTemplate: "{{ log.station | dash }}@{{ log.ref | dash }}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  referenceTitleTemplate: "{{ log.station }}: {{ log.activity }} at {{ log.ref }} {{ log.refName }} on {{ op.date }}",
+  otherFilenameTemplate: "{{ op.date }} {{ log.station }}{% if log.activity != blank %} for {{ log.activity }}{% endif %} {{ log.modifier }}",
+  otherCompactFilenameTemplate: "{{ log.station | dash }}{% if log.activity != blank %}-{{ log.activity | downcase | dash }}{% endif %}-{{ op.dateCompact }}{% if log.modifier != blank %}-{{ log.modifier | downcase | dash }}{% endif %}",
+  otherTitleTemplate: "{{ log.station }}{% if log.activity != blank %}: {{ log.activity }}{% endif %} on {{ op.date }}"
+};
+function resolveGlobalExportSettings(global = {}) {
+  const resolved = { ...GLOBAL_EXPORT_DEFAULTS, ...global };
+  for (const prefix of ["reference", "other"]) {
+    for (const suffix of ["FilenameTemplate", "CompactFilenameTemplate", "TitleTemplate"]) {
+      const key = `${prefix}${suffix}`;
+      const legacy = `${suffix[0].toLowerCase()}${suffix.slice(1)}`;
+      if (global[key] === void 0 && typeof global[legacy] === "string") {
+        Object.assign(resolved, { [key]: global[legacy] });
+      }
+    }
+  }
+  return resolved;
+}
+function exportTypeDefinition(activationType, format, label, defaults) {
+  return { exportType: `${activationType}-${format}`, activationType, format, label, defaults };
+}
+const templateKeys = [
+  "filenameTemplate",
+  "compactFilenameTemplate",
+  "titleTemplate",
+  "adifNotesTemplate",
+  "adifCommentTemplate",
+  "adifQslMessageTemplate"
+];
+function resolveExportSettings(definition, global = {}, overrides = {}) {
+  const defaults = resolveGlobalExportSettings(global);
+  const reference = definition.templateCategory === "reference";
+  const resolved = {
+    includePrivateData: defaults.includePrivateData,
+    includeLookupData: defaults.includeLookupData,
+    adifNotesTemplate: defaults.adifNotesTemplate,
+    adifCommentTemplate: defaults.adifCommentTemplate,
+    adifQslMessageTemplate: defaults.adifQslMessageTemplate,
+    filenameTemplate: reference ? defaults.referenceFilenameTemplate : defaults.otherFilenameTemplate,
+    compactFilenameTemplate: reference ? defaults.referenceCompactFilenameTemplate : defaults.otherCompactFilenameTemplate,
+    titleTemplate: reference ? defaults.referenceTitleTemplate : defaults.otherTitleTemplate,
+    ...definition.defaults
+  };
+  for (const key of ["includePrivateData", "includeLookupData"]) {
+    if (typeof overrides[key] === "boolean") resolved[key] = overrides[key];
+  }
+  resolved.customTemplates = overrides.customTemplates === true;
+  if (resolved.customTemplates) {
+    for (const key of templateKeys) {
+      if (typeof overrides[key] === "string") resolved[key] = overrides[key];
+    }
+  }
+  if (definition.format !== "adif") {
+    delete resolved.includePrivateData;
+    delete resolved.includeLookupData;
+    for (const key of templateKeys.slice(2)) delete resolved[key];
+  }
+  return resolved;
+}
+function exportQso(qso, settings) {
+  const copy = { ...qso };
+  for (const side of ["their", "our"]) {
+    if (copy[side] && typeof copy[side] === "object" && !Array.isArray(copy[side])) {
+      const station = { ...copy[side] };
+      if (settings.includeLookupData === false) delete station.guess;
+      if (settings.includePrivateData === false) {
+        for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete station[key];
+        if (typeof station.grid === "string") station.grid = station.grid.slice(0, 6);
+        if (station.guess && typeof station.guess === "object") {
+          const guess = { ...station.guess };
+          for (const key of ["name", "city", "email", "notes", "lat", "lon", "multiIdentifier"]) delete guess[key];
+          if (typeof guess.grid === "string") guess.grid = guess.grid.slice(0, 6);
+          station.guess = guess;
+        }
+      }
+      copy[side] = station;
+    }
+  }
+  if (settings.includePrivateData === false) delete copy.notes;
+  return copy;
+}
+function prepareExportOption(option, operation, qsos, compact) {
+  const settings = option.exportSettings;
+  const extension = { adif: "adi", cabrillo: "log", reg1test: "edi" }[option.format] ?? option.filename?.split(".").pop() ?? "txt";
+  const data = {
+    station: String(operation.stationCall ?? ""),
+    ref: "",
+    activity: "",
+    modifier: "",
+    ...option.templateData,
+    exportType: option.exportType,
+    format: option.format,
+    extension,
+    compact
+  };
+  if (isTestOperation(operation.stationCall)) data.modifier = [data.modifier, "Testing"].filter(Boolean).join(" ");
+  const context = templateContext({ operation, qsoCount: option.qsoCount ?? qsos.length, atMillis: startMillisOf(operation, qsos) ?? Date.now(), log: data });
+  const template = compact ? settings.compactFilenameTemplate : settings.filenameTemplate;
+  const rendered = oneLine(renderTemplate(template ?? "", context, "Export filename"));
+  const stem = rendered.replace(/[/\\:*?"<>|\x00-\x1f]+/g, "-").replace(/[. ]+$/g, "").trim() || "export";
+  const filename = stem.toLowerCase().endsWith(`.${extension}`) ? stem : `${stem}.${extension}`;
+  const titleContext = settings.includePrivateData === false ? { ...context, op: { ...context.op, title: "", userTitle: "", userNotes: "", grid: String(context.op.grid ?? "").slice(0, 6) }, log: { ...context.log, modifier: "" } } : context;
+  const title = oneLine(renderTemplate(settings.titleTemplate ?? "", titleContext, "Export title"));
+  return { ...option, filename, exportTitle: title, exportData: settings.includePrivateData === false ? { ...data, modifier: "" } : data };
+}
+export {
+  EXPORT_DEFAULTS,
+  GLOBAL_EXPORT_DEFAULTS,
+  exportQso,
+  exportTypeDefinition,
+  prepareExportOption,
+  resolveExportSettings,
+  resolveGlobalExportSettings
+};

package/dist/index.d.ts

@@ -1,4 +1,121 @@
-// @ham2k/extension-sdk 0.3.0
+// @ham2k/extension-sdk 0.5.0
+/** 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;
@@ -388,11 +505,44 @@ export interface AdifImportHook {
 		}[];
 	}, ctx: HookContext): Promise<(AdifImportResult | null)[]>;
 }
+export interface ExportSettings {
+	includePrivateData?: boolean;
+	includeLookupData?: boolean;
+	customTemplates?: boolean;
+	filenameTemplate?: string;
+	compactFilenameTemplate?: string;
+	titleTemplate?: string;
+	adifNotesTemplate?: string;
+	adifCommentTemplate?: string;
+	adifQslMessageTemplate?: string;
+}
+export interface GlobalExportSettings extends ExportSettings {
+	referenceFilenameTemplate?: string;
+	referenceCompactFilenameTemplate?: string;
+	referenceTitleTemplate?: string;
+	otherFilenameTemplate?: string;
+	otherCompactFilenameTemplate?: string;
+	otherTitleTemplate?: string;
+}
+export interface ExportTypeDefinition {
+	exportType: string;
+	label: string;
+	format: string;
+	activationType?: string;
+	templateCategory?: "reference" | "other";
+	defaults?: ExportSettings;
+	templateSample?: Record<string, JSONValue>;
+}
 export interface ExportRequest {
+	exportSettings?: ExportSettings;
+	exportData?: Record<string, JSONValue>;
+	exportTitle?: string;
+	includeLookupData?: boolean;
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
 	exportType?: string;
+	exportKey?: string;
 	compactFilenames?: boolean;
 	includePrivateData?: boolean;
 	mainHandler?: string;
@@ -409,7 +559,10 @@ export interface ExportOptionsRequest {
 	compactFilenames?: boolean;
 }
 export interface ExportOption {
+	qsoCount?: number;
+	templateData?: Record<string, JSONValue>;
 	exportType: string;
+	exportKey?: string;
 	format: string;
 	label: string;
 	filename?: string;
@@ -421,6 +574,7 @@ export interface ExportOption {
 	refType?: string;
 }
 export interface ExportHook {
+	getExportTypes?(args: Record<string, never>, ctx: HookContext): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions?(args: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 }
@@ -770,6 +924,8 @@ export interface ExtensionManifest {
 	domains?: string[];
 	allowUserAgentOverride?: boolean;
 	requiresLocation?: boolean;
+	requiresRadioRead?: boolean;
+	requiresRadioWrite?: boolean;
 	experiments?: string[];
 	relevance?: ExtensionRelevance;
 	translations?: Record<string, {
@@ -871,7 +1027,7 @@ export interface DataFileDefinition {
 	onLoadRawData?: (data: any) => void;
 	onRemoveRawData?: () => Promise<void>;
 }
-export type FormFieldType = "text" | "multiline" | "email" | "callsign" | "number" | "select" | "radio" | "checkbox" | "secret" | "list" | "multiselect" | "account";
+export type FormFieldType = "text" | "multiline" | "textTemplate" | "email" | "callsign" | "number" | "select" | "radio" | "checkbox" | "secret" | "list" | "multiselect" | "account";
 export interface FormFieldOption {
 	label: string;
 	value: any;
@@ -885,6 +1041,8 @@ export interface FormField {
 	label: string;
 	value?: any;
 	placeholder?: string;
+	templateContext?: "export" | "adif" | "text";
+	templateSample?: Record<string, JSONValue>;
 	uppercase?: boolean;
 	options?: FormFieldOption[] | string;
 	validate?: (value: any, state: Record<string, any>) => string | null | undefined | Promise<string | null | undefined>;
@@ -934,6 +1092,8 @@ export interface FormMarkdownBlock {
 	title?: string;
 }
 export interface FormActionElement {
+	style?: "row";
+	icon?: string;
 	type: "action";
 	key: string;
 	label: string;
@@ -1081,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>;
@@ -1090,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;
@@ -1108,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
@@ -1235,12 +1471,14 @@ export type ActivityScoresheet = {
 export declare function activityScorer(rules: ActivityScoringRules): ContestScorer<ActivityScoresheet>;
 export interface ActivityExportRules {
 	key: string;
+	templateSample?: Record<string, JSONValue>;
 	label: string;
 	activationType: string;
 	icon?: string;
 	includeFieldsFrom?: string[];
 }
 export declare function activityExportHook(rules: ActivityExportRules): {
+	getExportTypes(): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
@@ -1254,14 +1492,19 @@ export interface HuntingExportRules {
 	includeFieldsFrom?: string[];
 }
 export declare function huntingExportHook(rules: HuntingExportRules): {
+	getExportTypes(): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
-export declare function adifForExport({ operation, qsos, segments, includePrivateData, mainHandler, includeFieldsFrom }: {
+export declare function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }: {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
 	includePrivateData?: boolean;
+	includeLookupData?: boolean;
+	exportSettings?: ExportSettings;
+	exportData?: Record<string, JSONValue>;
+	exportTitle?: string;
 	mainHandler: string;
 	includeFieldsFrom?: string[];
 }): Promise<string>;
@@ -1284,6 +1527,19 @@ export interface ExportNameParts {
 }
 export declare function exportFilename(parts: ExportNameParts): string;
 export declare function startMillisOf(operation: Record<string, JSONValue>, qsos?: Record<string, JSONValue>[]): number | undefined;
+export declare const EXPORT_DEFAULTS: ExportSettings;
+export declare const GLOBAL_EXPORT_DEFAULTS: GlobalExportSettings;
+export declare function resolveGlobalExportSettings(global?: GlobalExportSettings): GlobalExportSettings;
+export declare function exportTypeDefinition(activationType: string, format: string, label: string, defaults?: ExportSettings): ExportTypeDefinition;
+export declare function resolveExportSettings(definition: ExportTypeDefinition, global?: GlobalExportSettings, overrides?: ExportSettings): ExportSettings;
+export declare function exportQso(qso: Record<string, JSONValue>, settings: ExportSettings): Record<string, JSONValue>;
+export declare function prepareExportOption(option: ExportOption & {
+	exportSettings: ExportSettings;
+}, operation: Record<string, JSONValue>, qsos: Record<string, JSONValue>[], compact: boolean): ExportOption & {
+	exportSettings: ExportSettings;
+	exportTitle: string;
+	exportData: Record<string, JSONValue>;
+};
 export type RefTransform = {
 	pattern: string;
 	replacement: string;
@@ -1397,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";
@@ -9,6 +10,7 @@ export * from "./activityScoring.js";
 export * from "./activityExports.js";
 export * from "./activityAdifImport.js";
 export * from "./exportNames.js";
+export * from "./exportSettings.js";
 export * from "./referenceActivity.js";
 export * from "./refTransforms.js";
 export * from "./templates.js";
@@ -59,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/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'
@@ -70,8 +71,8 @@ export interface FormField {
   // fields — a whole section header can be dev-mode-only too.
   devMode?: boolean;
   // Settings-panel-only (ignored in ad hoc forms) — see settings.md's
-  // "Common Settings and environment gating". Also shows this field on
-  // the app's Common Settings quick-access panel.
+  // "Common Preferences and environment gating". Also shows this field on
+  // the app's Common Preferences quick-access panel.
   common?: boolean;
   // Settings-panel-only. Restricts which platform(s) show this field at
   // all: one or more platform tokens (`ios`, `android`, `macos`,
@@ -129,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;
@@ -277,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

@@ -248,23 +248,91 @@ 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?, color?, refType?, 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
@@ -1169,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}
@@ -1179,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/settings.md

@@ -372,17 +372,18 @@ Aliases are for names an operator would plausibly *reach for* — not a thesauru
 Every alias is one more thing that can collide with another setting's real name,
 and a collision costs a disambiguation prompt on a query that used to be exact.
 
-## Common Settings and environment gating
+## Common Preferences and environment gating
 
-The app has one settings screen, **Settings**: a collapsible section per
-declared group and panel, led by **Common Settings**, a short list of the
+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
-Settings —
+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 in the Common Settings
+- **`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
@@ -395,7 +396,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-everything one: an excluded field disappears from every
-  settings surface on that platform, not just Common Settings. 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
   forms in one attribute is invalid and treated as if `environment` were

package/docs/templates.md

@@ -19,7 +19,7 @@ const text = renderTemplate("{{ op.station }} — {{ op.qsoCount }} QSOs", templ
 
 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
+between operators, and are 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.
@@ -42,15 +42,15 @@ the namespaces are deliberately polo's. The syntax around them does not:
 |---|---|---|---|---|
 | `app` | ✓ | — | ✓ | ✓ |
 | `now` | ✓ | ✓ | ✓ | ✓ |
-| `op` | ✓ | dates only | ✓ | ✓ |
+| `op` | ✓ | ✓ | ✓ | ✓ |
 | `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`).
+what makes `{% if qso %}` an honest question. Registered exports get the operation plus the selected file’s `log` values.
+The low-level `exportFilename(parts)` helper still supplies only dates and
+filename parts.
 
 ### `app`
 `app.name` — the platform-appropriate name ("Ham2K Logger" on desktop,
@@ -191,16 +191,16 @@ will jump rather than count. Show HH:MM.
 | 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 |
+| Export filenames and titles | Registered export types and `sdk/src/exportSettings.ts` | Settings → Exports, globally and per type |
+| ADIF NOTES / COMMENT / QSLMSG | Export type settings, consumed by `core/adif` | Settings → Exports; empty templates suppress a field |
 | 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.
+NOTES and COMMENT default to QSO notes and are withheld when private data
+is off. QSLMSG defaults to empty for program exports, and to the operation’s
+references for the whole-log ADIF. Custom QSL messages may use contact values.
+Templates receive no withheld private or lookup values. File titles obey the
+private-data choice; filename templates are labels for the operator’s files.
 
-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.
+The `textTemplate` form field provides sample previews and an insertable
+reference; see [forms.md](forms.md). Invalid Liquid reports an error rather
+than silently replacing the operator’s template with a default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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 } }
+    },
+  }
+}