@ham2k/extension-sdk 0.9.1 → 0.10.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), `k2hrc-svg-scenes` (experimental interactive SVG) |
+| 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-panel-scenes` (experimental interactive panel scene) |
 | 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,12 +1,17 @@
-// @ham2k/extension-sdk 0.9.1
-/** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
-export interface SvgScene {
+// @ham2k/extension-sdk 0.10.1
+/** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
+export interface PanelScene {
 	version: 1;
 	width: number;
 	height: number;
 	values: Record<string, number>;
-	layers: SvgSceneLayer[];
-	controls?: SvgSceneControl[];
+	/** String state for text fields and choices. A key is in `values` or here, never both. At most 256, each up to 4096 characters. */
+	strings?: Record<string, string>;
+	/** Painted in order, each over the ones before. */
+	layers: PanelSceneLayer[];
+	controls?: PanelSceneControl[];
+	/** Where rect-less native controls and the artwork go. Omitted, the artwork fills the panel. */
+	layout?: PanelSceneLayoutNode;
 }
 /** A clamped, linear mapping. No expressions or extension code run per frame. */
 export interface SceneBinding {
@@ -26,7 +31,7 @@ export interface SceneBinding {
 	/** Optional equally spaced output samples over input; replaces the output ramp. */
 	samples?: number[];
 }
-export interface SvgSceneLayer {
+export interface PanelSceneLayer {
 	id: string;
 	x: number;
 	y: number;
@@ -34,7 +39,12 @@ export interface SvgSceneLayer {
 	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.
+	/**
+	 * Take the clicks that land on this layer. Off by default: layers are click-through, so
+	 * artwork painted over a control does not stop it working. On, it covers the controls under it.
+	 */
+	blocksPointer?: boolean;
+	/** Exactly one of literal/value. A value naming a string shows it as-is. Use text layers, not SVG <text>, for font support.
 	 * Size is unscaled; the host applies OS text scaling once. */
 	text?: {
 		value?: string;
@@ -75,24 +85,77 @@ export interface SvgSceneLayer {
 		flicker?: boolean;
 	};
 }
-export interface SvgSceneControl {
+/**
+ * `button`, `slider` and `knob` are invisible hit areas over the extension's own artwork.
+ * The `native…` kinds are Material widgets, themed by the app:
+ *
+ * - `nativeButton`: sends `activate`. `variant`, `icon`, and optionally `menu`.
+ * - `nativeSlider`: a number, between `min` and `max` in `step`s.
+ * - `nativeTextField`: a string. Commits on Enter, or on leaving the field after typing.
+ * - `nativeDropdown`, `nativeRadio`, `nativeSegmented`: a string, one of `options`.
+ *   A `multi` segmented control holds its chosen values joined with commas, in option order.
+ * - `nativeSwitch`, `nativeCheckbox`: a number, 1 or 0. Shows `label` beside it.
+ * - `nativeChip`: with `value`, a toggle (1 or 0); without, an action that sends `activate`.
+ * - `nativeText`: shows `label`, or its bound value. Sends nothing.
+ *
+ * `label` is every control's accessible name. There are no tooltips.
+ */
+export type PanelSceneControlKind = "button" | "slider" | "knob" | "nativeButton" | "nativeSlider" | "nativeTextField" | "nativeDropdown" | "nativeSwitch" | "nativeCheckbox" | "nativeRadio" | "nativeSegmented" | "nativeChip" | "nativeText";
+export interface PanelSceneControl {
 	id: string;
 	label: string;
-	kind: "button" | "slider" | "knob";
+	kind: PanelSceneControlKind;
 	/** 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;
+	/**
+	 * The control's rect over the artwork, in scene units. Required for the drawn kinds.
+	 * A native control omits all four to be placed by `layout` instead.
+	 */
+	x?: number;
+	y?: number;
+	width?: number;
+	height?: number;
+	/**
+	 * With a rect: the id of the layer this control paints directly after, so later layers draw
+	 * over it. Omitted, the control paints above every layer.
+	 */
+	after?: string;
 	/** Omit event for local-only interaction (for example a chart inspection cursor). */
 	event?: string;
-	/** Send coalesced change events during dragging, plus the final commit. */
+	/** `slider`, `knob`, `nativeSlider` and `nativeTextField` only: send coalesced change events while dragging or typing, plus the final commit. */
 	continuous?: boolean;
+	/**
+	 * The name of the value this control shows and sets: in `values`, or in `strings` for a string kind.
+	 * A choice's string must be `""` or one of its `options` (each part, for `multi`). `nativeButton` takes none.
+	 */
 	value?: string;
+	/** Choices for `nativeDropdown`, `nativeRadio` and `nativeSegmented`. Values are unique. */
+	options?: {
+		label: string;
+		value: string;
+	}[];
+	/** `nativeSegmented` only: choose several. */
+	multi?: boolean;
+	/** Shown but inert: no clicks, drags, keys or screen-reader adjustments act on it. */
+	disabled?: boolean;
+	/**
+	 * 0 to 1, fixed or bound like a layer's. At 0 the control is gone: it takes no clicks,
+	 * keyboard focus or screen-reader node. Anything between is only drawn fainter.
+	 */
+	opacity?: number | SceneBinding;
+	/** `nativeButton` only. Default `filled`. */
+	variant?: "filled" | "tonal" | "outlined" | "text";
+	/** `nativeButton` and `nativeChip`: a Material Design Icons name, such as `radio-tower`. */
+	icon?: string;
+	/** `nativeTextField` and `nativeDropdown`: shown while empty. */
+	placeholder?: string;
+	/** `nativeText` only: a typography role from the render environment. Default `body`. */
+	style?: "body" | "label" | "title" | "display" | "mono";
+	/** `nativeText` only. Default `start`. */
+	align?: "start" | "center" | "end";
 	min?: number;
 	max?: number;
 	step?: number;
@@ -110,12 +173,66 @@ export interface PanelSceneEvent {
 	action: string;
 	phase: "activate" | "change" | "commit";
 	sequence: number;
+	/** The control's number, for a control bound to `values`. */
 	value?: number;
+	/** The control's string, for a control bound to `strings`. */
+	text?: string;
 }
-/** Patch only named scene values. The host ignores stale responses. */
+/** Patch only named scene values and strings. The host ignores stale responses. */
 export interface PanelSceneEventResult {
 	values: Record<string, number>;
+	strings?: Record<string, string>;
 }
+/**
+ * Flutter's Row, Column and Wrap, with Flexible, Spacer and SizedBox as fields.
+ * Sizes are logical pixels, like the render environment's. At most 8 deep and 128 nodes.
+ *
+ * - `{row: [...]}` / `{column: [...]}` / `{wrap: [...]}` lay out their children.
+ * - `{control: "id"}` places a native control that has no rect. Each appears exactly once.
+ * - `{scene: true}` places the artwork, scaled to fit. At most once.
+ * - `{spacer: flex}` takes a share of the free space.
+ *
+ * A text field or dropdown given no width (a row child without `flex` or `width`) is 200 wide.
+ */
+export type PanelSceneLayoutNode = ({
+	row: PanelSceneLayoutNode[];
+} | {
+	column: PanelSceneLayoutNode[];
+} | {
+	wrap: PanelSceneLayoutNode[];
+} | {
+	control: string;
+} | {
+	scene: true;
+} | {
+	spacer: number;
+}) & {
+	/** Only on a row or column's direct child: share the free space, like Expanded (`tight`, the default) or Flexible (`loose`). */
+	flex?: number;
+	fit?: "tight" | "loose";
+	width?: number;
+	height?: number;
+	/** All sides, or `[start, top, end, bottom]`. */
+	padding?: number | [
+		number,
+		number,
+		number,
+		number
+	];
+	/** Gap between children; for a wrap, between items in a run. */
+	spacing?: number;
+	/** Wrap only: gap between runs. */
+	runSpacing?: number;
+	mainAxisAlignment?: "start" | "center" | "end" | "spaceBetween" | "spaceAround" | "spaceEvenly";
+	/** `stretch` on a row or column only. */
+	crossAxisAlignment?: "start" | "center" | "end" | "stretch";
+};
+/** @deprecated Renamed to `PanelScene`. */
+export type SvgScene = PanelScene;
+/** @deprecated Renamed to `PanelSceneLayer`. */
+export type SvgSceneLayer = PanelSceneLayer;
+/** @deprecated Renamed to `PanelSceneControl`. */
+export type SvgSceneControl = PanelSceneControl;
 export declare const HOOK_CATEGORIES: readonly [
 	"account",
 	"activity",
@@ -413,6 +530,7 @@ export interface RefGeojson {
 	url: string;
 	maxAgeInDays?: number;
 	missMaxAgeInDays?: number;
+	sourceName?: string;
 }
 export interface LoggingControlDescriptor {
 	key: string;
@@ -507,6 +625,12 @@ export interface ActivitySuggestion extends Ref {
 	relevance?: number;
 	allowsMultiple?: boolean;
 }
+export interface MapBounds {
+	south: number;
+	west: number;
+	north: number;
+	east: number;
+}
 export interface SuggestArgs {
 	operation: Record<string, JSONValue>;
 	location?: {
@@ -515,6 +639,7 @@ export interface SuggestArgs {
 	};
 	callsign?: string;
 	searchTerm?: string;
+	bounds?: MapBounds;
 	scoped?: boolean;
 }
 export interface ActivityHook {
@@ -536,6 +661,7 @@ export interface AdifFieldsHook {
 	fieldsForOneQSO(args: {
 		qso: Record<string, JSONValue>;
 		operation: Record<string, JSONValue>;
+		mainHandler?: boolean;
 	}, ctx: HookContext): Promise<{
 		name: string;
 		value: string;
@@ -818,6 +944,7 @@ export interface CommandAction {
 		qsoCount?: number;
 	};
 	devLogCat?: Record<string, never>;
+	devMapInfo?: Record<string, never>;
 	toggleExperiment?: {
 		token: string;
 	};
@@ -1411,7 +1538,7 @@ export interface PanelRadioTuneResult {
 	state: PanelRadioState | null;
 }
 export interface PanelRenderArgs {
-	/** Present on environment-capable hosts. Changes automatically request a throttled render of an `svgScene` panel. */
+	/** Present on environment-capable hosts. Changes automatically request a throttled render of a `scene` panel. */
 	environment?: PanelEnvironment;
 	/** Display time follows developer time travel; real time is for network retry/cache budgets. */
 	clock?: {
@@ -1428,8 +1555,18 @@ export interface PanelRenderArgs {
 	reason: string;
 }
 export type PanelContent = {
+	kind: "scene";
+	scene: PanelScene;
+	title?: string;
+	triggers?: string[];
+}
+/**
+ * @deprecated The same kind as `scene`, under its name through SDK 0.9. Apps before extension
+ * API 5 know only `svgScene`; `scene` needs `"api": 5`, as do native controls, `strings` and `layout`.
+ */
+ | {
 	kind: "svgScene";
-	scene: SvgScene;
+	scene: PanelScene;
 	title?: string;
 	triggers?: string[];
 } | {
@@ -1733,6 +1870,21 @@ export interface ReferenceActivityHooks {
 	adifImportHook: AdifImportHook;
 }
 export declare function referenceActivity(config: ReferenceActivityConfig): ReferenceActivityHooks;
+export interface NearbyLookupHost {
+	dbLookupSelectByLocation(category: string, lat: number, lon: number, delta: number, activeOnly?: boolean): Promise<LookupRow[]>;
+	dbLookupSelectInBounds(category: string, bounds: MapBounds, options?: {
+		activeOnly?: boolean;
+		limit?: number;
+	}): Promise<LookupRow[]>;
+}
+export declare const VIEWPORT_LIMIT = 500;
+export declare function nearbyLookupRows(host: NearbyLookupHost, category: string, { location, bounds }: Pick<SuggestArgs, "location" | "bounds">, { delta, activeOnly }: {
+	delta: number;
+	activeOnly?: boolean;
+}): Promise<{
+	rows: LookupRow[];
+	inViewport: boolean;
+}>;
 export declare class TemplateError extends Error {
 	readonly cause?: unknown;
 	constructor(message: string, options?: {
@@ -1836,6 +1988,10 @@ export declare const host: {
 	dbLookupSelectOne(category: string, key: string): Promise<LookupRow | null>;
 	dbLookupSelectAll(category: string, query: string, subCategory?: string, activeOnly?: boolean): Promise<LookupRow[]>;
 	dbLookupSelectByLocation(category: string, lat: number, lon: number, delta: number, activeOnly?: boolean): Promise<LookupRow[]>;
+	dbLookupSelectInBounds(category: string, bounds: MapBounds, options?: {
+		activeOnly?: boolean;
+		limit?: number;
+	}): Promise<LookupRow[]>;
 	showForm(form: FormDefinition, state?: Record<string, any>): Promise<Record<string, any> | null>;
 	statusBar: {
 		setMessage(params: StatusBarMessageParams): Promise<void>;

package/dist/index.js

@@ -2,7 +2,7 @@ import { base64ToBytes, bytesToBase64 } from "./base64.js";
 import { adoptExtensionTimers, clearInterval, clearTimeout, setInterval, setTimeout } from "./timers.js";
 export * from "./types.js";
 export * from "./hookCategories.js";
-export * from "./svgScene.js";
+export * from "./panelScene.js";
 export * from "./i18n.js";
 export * from "./dxcc.js";
 export * from "./location.js";
@@ -16,6 +16,7 @@ export * from "./activityAdifImport.js";
 export * from "./exportNames.js";
 export * from "./exportSettings.js";
 export * from "./referenceActivity.js";
+export * from "./nearby.js";
 export * from "./refTransforms.js";
 export * from "./templates.js";
 export * from "./templateContext.js";
@@ -304,6 +305,13 @@ const host = {
   async dbLookupSelectByLocation(category, lat, lon, delta, activeOnly) {
     return await hostCallFn()("dbLookupSelectByLocation", { category, lat, lon, delta, activeOnly });
   },
+  /// Every row inside `bounds`, nearest its centre first, at most `limit`
+  /// (default 500, never past 1000). `west` past `east` is a box across the
+  /// antimeridian. Only an app that sends `SuggestArgs.bounds` answers this
+  /// call — so call it only when `bounds` arrived, as `nearbyLookupRows` does.
+  async dbLookupSelectInBounds(category, bounds, options = {}) {
+    return await hostCallFn()("dbLookupSelectInBounds", { category, ...bounds, ...options });
+  },
   async showForm(form, state = {}) {
     return kernel().host.showForm(form, state, currentExtensionKey);
   },

package/dist/nearby.js

@@ -0,0 +1,10 @@
+const VIEWPORT_LIMIT = 500;
+async function nearbyLookupRows(host, category, { location, bounds }, { delta, activeOnly }) {
+  if (bounds) return { rows: await host.dbLookupSelectInBounds(category, bounds, { activeOnly, limit: VIEWPORT_LIMIT }), inViewport: true };
+  if (location) return { rows: await host.dbLookupSelectByLocation(category, location.lat, location.lon, delta, activeOnly), inViewport: false };
+  return { rows: [], inViewport: false };
+}
+export {
+  VIEWPORT_LIMIT,
+  nearbyLookupRows
+};

package/dist/referenceActivity.js

@@ -1,3 +1,4 @@
+import { nearbyLookupRows } from "./nearby.js";
 import { distanceOnEarth } from "@ham2k/lib-geo-tools";
 import { activityAdifImport } from "./activityAdifImport.js";
 async function hostApi() {
@@ -186,9 +187,9 @@ function referenceActivity(config) {
         ];
       }
     } : {},
-    async suggest({ location, searchTerm, scoped }, ctx) {
+    async suggest({ location, bounds, searchTerm, scoped }, ctx) {
       const host = await hostApi();
-      const rows = searchTerm ? await host.dbLookupSelectAll(category, searchTerm) : location ? await host.dbLookupSelectByLocation(category, location.lat, location.lon, NEARBY_DELTA) : [];
+      const { rows, inViewport } = searchTerm ? { rows: await host.dbLookupSelectAll(category, searchTerm), inViewport: false } : await nearbyLookupRows(host, category, { location, bounds }, { delta: NEARBY_DELTA });
       const withDistance = rows.map((row) => ({
         row,
         distance: location && row.lat != null && row.lon != null ? distanceOnEarth(location, { lat: row.lat, lon: row.lon }) ?? void 0 : void 0
@@ -196,7 +197,7 @@ function referenceActivity(config) {
       if (!searchTerm) {
         withDistance.sort((a, b) => (a.distance ?? Infinity) - (b.distance ?? Infinity));
       }
-      const suggestions = withDistance.slice(0, MAX_SUGGESTIONS).map(({ row, distance }) => {
+      const suggestions = withDistance.slice(0, inViewport ? withDistance.length : MAX_SUGGESTIONS).map(({ row, distance }) => {
         const data = row.data ?? {};
         return {
           type: config.activationType,

package/docs/distribution.md

@@ -51,7 +51,9 @@ reaches every app that can run it: 2 adds `host.webSocket`, and the packer
 refuses a manifest declaring `webSockets` under anything less; 3 adds timers
 and `onShow`/`onHide`, and from 3 the build rewrites a bare `setTimeout` into
 the SDK's (README's "Timers"); 4 lets `host.fetch` reach a plain-`http://` host
-the app fronts with its https proxy (README's `host.fetch`).
+the app fronts with its https proxy (README's `host.fetch`); 5 adds panel
+scenes' `scene` kind, native controls, `strings`, `layout`, `after` and control
+`opacity` (hooks.md's `panel`).
 
 Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
@@ -260,7 +262,7 @@ It reports every problem at once rather than one per run:
 h2kext-pack: ./build is not ready to package:
 manifest.json: missing required field 'name'
 manifest.json: key 'my-clock' must start with your callsign — 'my' is not one (e.g. ki2d-my-clock)
-manifest.json: missing 'api' — declare the extension API this was built against (currently 4)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 5)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own
@@ -399,8 +401,9 @@ built-in's own state stays where it is.
 One rule bends for these, and only for them:
 
 - **Built-in collisions.** An installed bundle may not claim a key the app
-  ships — judged against what the app is currently OFFERING, which under the
-  catalog experiment is the core extensions and nothing else. `ham2k-lookup`
+  ships — judged against what the app is currently OFFERING, which once the
+  upgrade to catalog extensions is taken is the core extensions and nothing
+  else. `ham2k-lookup`
   is both a built-in and a pre-load, and could otherwise never install.
 
 **Build secrets are not among them, and used to be.** A pre-load holding a
@@ -412,14 +415,16 @@ sees no build secret, whatever key it claims and wherever it came from.
 
 ### The upgrade to catalog extensions
 
-An install that has been running the app's own extensions is offered the move
-at start, and again the moment the catalog experiment is switched on: that
-switch is the operator asking for catalog extensions, and being made to
-relaunch before anything is offered reads as nothing having happened. The
-switch withdraws nothing by itself; only a taken upgrade does, and the offer
-may be deferred either way. A catalog that cannot be reached says so in the
-footer when the operator asked, and says nothing at a launch nobody was
-watching.
+A new install — one whose default profile has never had a callsign — starts
+on the catalog at its first boot, on the bundles the app ships, with nothing
+to offer and nothing to carry; the decision is recorded once
+(`seedExtensionsMigratedDefault`). Onboarding still names its activities by
+their built-in keys, which `offeredKeyFor` maps to the shipped twin that
+actually runs. An install that has been running the app's own extensions is
+offered the move at start, on every launch until it is taken. Only a taken upgrade withdraws
+anything, and the offer may be deferred. A catalog that cannot be reached
+raises no offer and says nothing: it is a launch nobody was watching, and the
+offer comes back next time.
 
 Accepting installs the pre-loads, then fetches the catalog's twin of every
 other built-in the operator had switched on — `wca` becomes `ham2k-wca` —
@@ -521,15 +526,72 @@ Beyond what the packer already refused:
 
 Each has its own message. A bundle that cannot be installed says why.
 
-## Native only, for now
-
-Installed bundles are files on disk. On web the app runs from its own assets
-and, for authors, the dev server — [development.md](https://github.com/ham2k/halo/blob/main/docs/extensions/development.md). So on
-web there is nothing to install into: no install from a file, no install or
-update from the catalog, and none of the pre-loaded extensions above.
-
-"For now" is a deferral, not a fact about the platform. Almost everything
-here is already platform-neutral — the zip walk, the manifest rules, the
-consent screen, the hash check — and what is left is a persistence seam of
-about six operations. `HALO-583` is the card that picks it up, and says what
-has to be decided first.
+## Where installed bundles live
+
+Everything above is platform-neutral — the zip walk, the manifest rules, the
+consent screen, the hash check. What differs is only where the bytes are kept
+(`BundleStorage`):
+
+- **natively**, one directory per key under the app's data directory, one
+  file per bundle entry;
+- **on web**, one IndexedDB record per key (database `halo-extensions`),
+  holding every entry's bytes under its own name. IndexedDB rather than the
+  Origin Private File System, which would mirror the native layout: every
+  browser HaLo runs in supports it the same way, while OPFS writes from the
+  page are newer and patchier on Safari.
+
+So the web build installs from a file, installs and updates from the catalog,
+pre-loads the shipped bundles and takes the upgrade exactly as the native ones
+do.
+
+### When the store is lost
+
+The store can go while the preferences describing it survive: a browser
+clearing IndexedDB alone, a data directory deleted by hand, a store that
+failed mid-session. (When a browser clears a whole site, preferences go with
+it, and the app starts as a new install.) So what the operator installed is
+kept apart from the store that holds it, and put back from there.
+
+`extensionsInstalled` records every extension the operator installed
+(`{key: name}`). Every install writes it; only an uninstall — or Forget, below
+— removes it. An install that predates it is seeded from its store once, and
+after that it never follows the store: a store found short is exactly what it
+must not shrink to. Whatever is recorded there and not in the store is
+**missing**, however it went — judged by the keys the store holds, not by the
+extensions the app offers, since a built-in or a dev server can stand in front
+of an installed bundle. A store that cannot be read at all has lost nothing:
+that launch offers nothing, rather than everything back into a failing store.
+Where each came from is its provenance record's answer, and a key with none
+came from a file.
+
+The operator's on/off choice for a missing extension is kept too: the boot
+cleanup that prunes settings for keys the app no longer knows treats every
+recorded key as known.
+
+Putting them back, after the app starts:
+
+- **Shipped bundles** come back at boot from the app's own assets, unasked and
+  offline. The pre-load record says they were already offered, which is true
+  and beside the point; they are installed anyway, never as a first install,
+  so their settings and on/off choice stand. An install that has not taken the
+  upgrade gets back only what it had.
+- **Everything else** is offered in a dialog once the boot has settled:
+  - extensions from the catalog in use are listed to install, at the release
+    it serves now. **Later** keeps every one for the next launch;
+  - extensions from a file are listed to install again from their files, and
+    ones from a different catalog as not available here. Neither is fetched —
+    the bytes would come from a publisher the operator never agreed to;
+  - every row has **Forget**, which drops it with everything it stored — the
+    only way out for one the catalog no longer serves, which would otherwise
+    be offered, and fail, every launch.
+- **Install** installs each on its own: one that is not listed, will not
+  download or fails the check costs only itself. The runtime restarts with
+  everything that landed; a bundle it will not evaluate is set aside, as the
+  upgrade does, and the runtime restarts without it. The result names what
+  could not be installed (offered again next launch) and what installed but
+  would not run (kept, marked in the panel, where an update is the way back);
+  says so when the runtime would not start at all, rather than calling it a
+  success; and says the app is still busy — offering them again next launch
+  — when another catalog pass holds the store.
+- The offer waits for the boot's catch-up to finish, or for an upgrade that
+  every catch-up stepped aside for to let go.

package/docs/hooks.md

@@ -46,8 +46,8 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   effect must stay invisible until an experiment gating the surface it
   belongs to has shipped ungated — checked per-call, since gating at the
   whole-extension `manifest.experiments` grain would also hide any other
-  hook the same extension registers (e.g. `radio-commands`' POWER command
-  checks `gato` here; its BAND/MODE/frequency siblings don't).
+  hook the same extension registers (e.g. `radio-commands`' WPM command
+  checks `keyer` here; its BAND/MODE/frequency siblings don't).
 * `experiments?: { key, name, aliases }[]` — The experiment catalog itself,
   on or off, so a hook can resolve a typed key-or-alias to one of the keys
   `enabledExperiments` lists (the EXP preview says "Enable"/"Disable" rather
@@ -473,15 +473,18 @@ its own program name reads the wrong program aloud. Programs built on the SDK's
 from one `linkUrl` config line.
 
 `geojsonUrlForRef` says where the reference's own footprint can be fetched as
-GeoJSON — a SOTA summit's activation zone, and whatever equivalent another
-program publishes. Same contract as `linkForRef`: build the URL from the
+GeoJSON — a SOTA summit's activation zone, a POTA park's boundary, and
+whatever equivalent another program publishes. Areas (`Polygon`,
+`MultiPolygon`) are drawn filled with an edge; lines (`LineString`,
+`MultiLineString`) — a trail or a river that is the park — are drawn as an
+edge alone; points are ignored. Same contract as `linkForRef`: build the URL from the
 reference, **never hit the network**, return `null` for a reference the program
 has no shape for. The core does the fetching and the caching (`GeoshapeService`),
 so an extension never decides how long a device keeps a file or how large one may
 be; it only names the two ages the core should use:
 
 ```ts
-// RefGeojson: {url, maxAgeInDays?, missMaxAgeInDays?}
+// RefGeojson: {url, maxAgeInDays?, missMaxAgeInDays?, sourceName?}
 ```
 
 `maxAgeInDays` (default 30) is how long a fetched shape stays usable offline —
@@ -490,6 +493,14 @@ long the core remembers that a reference has NO shape, deliberately shorter so a
 newly surveyed zone appears within a day rather than a month. Both are ignored
 unless positive: a zero would re-fetch on every rebuild of the map.
 
+`sourceName` is who drew the shapes, short enough for the credit line a map
+shows under its outlines ("Source: OSM, sotl.as") — the host of `url` when it
+is left out. Name the data's owner, not the server that relays it: POTA's
+outlines are served by Ham2K and credited to OSM.
+
+A document past 16MB is not kept: the core remembers it as a miss, on
+`missMaxAgeInDays`, rather than downloading it again on every retry.
+
 The URL must be `https`, and the core does not follow redirects to reach it.
 Unlike a link, this one is fetched rather than handed to the platform, and a
 plaintext one — named outright, or arrived at through a `Location:` header —
@@ -497,10 +508,13 @@ would downgrade every activator's connection on a program's say-so.
 
 Shapes are asked for sparingly: the Map tab asks about the operation's own
 references, and the Activities pane's results map about those plus the one
-suggestion whose card is open. Neither fetches a shape per search hit — a search
-answers with dozens of references, and at the zoom that shows dozens of them a
-footprint is a few pixels across. Implemented by: `sota` (both types, via
-SOTLAS's `az.sotl.as`, used with the operators' permission).
+suggestion whose card is open, drawn solid. The rest of the map's suggestions
+are asked about only once it is zoomed in (from GL zoom 7, fading in by 8)
+and drawn as a dashed edge under the solid ones — a search answers with dozens
+of references, and further out a footprint is a few pixels across. Implemented by: `sota` (both types, via
+SOTLAS's `az.sotl.as`, used with the operators' permission) and `pota` (both
+types, via `services.ham2k.net/lookups/outlines/pota/`, which links parks to
+OpenStreetMap shapes; a park not yet linked answers 404).
 
 `suggestOperationTitle` lets an activity build a natural-language operation
 title/subtitle from its refs — "at Yosemite NP" (POTA), "for Field Day"
@@ -537,7 +551,7 @@ interface ActivityHook {
 // extension only says what the short form is.
 // `skipFocus: true` takes a main logging field out of the Space and Tab cycle;
 // the arrow keys still reach it. Every shipped contest sets it on Our Serial.
-// SuggestArgs: {operation, location?: {lat, lon}, callsign?, searchTerm?, scoped?}
+// SuggestArgs: {operation, location?: {lat, lon}, callsign?, searchTerm?, scoped?, bounds?: {south, west, north, east}}
 // ActivitySuggestion: Ref & {distance?, relevance?, allowsMultiple?}
 
 // The input catalog. A new kind is earned by a different WIDGET, never by
@@ -622,7 +636,17 @@ proposing a new `input.kind` is a core PR, deliberately (DESIGN.md §5's
 
 `suggest` powers the Activities view's "add activity" search: called with a
 `location`/`callsign` the core resolves from the operation if set, else the
-station defaults (extensions never need to know which). Called with no
+station defaults (extensions never need to know which). When the operator pans
+the Activities results map it asks again with the map's view as `bounds` (and
+its centre as `location`, no `searchTerm`, the box's scope if it has one):
+answer with EVERY reference inside the view, not the nearest few, or the view's
+corners stay empty however far the operator pans. `nearbyLookupRows` reads
+either case, through the `dbLookupSelectInBounds` host call for a view — only
+an app that sends `bounds` answers that call, so an extension that calls it
+only then runs on older apps unchanged, and one that predates `bounds` answers
+with what is nearest the view's centre. Measure `distance` from the `location`
+given either way; the core re-measures a panned answer from the operation's own
+place before any card shows it. Called with no
 `searchTerm` for nearby suggestions, or with one for name/code search — an
 extension may honor either, both, or neither (returning `[]`). `scoped` is
 true when THIS extension alone was asked — the operator tapped its "Activity
@@ -717,12 +741,17 @@ knowing them. Called by the `adif` extension **inside the runtime** via
 
 ```ts
 interface AdifFieldsHook {
-  fieldsForOneQSO(args: { qso, operation }, ctx): Promise<{name, value}[]>
+  fieldsForOneQSO(args: { qso, operation, mainHandler? }, ctx): Promise<{name, value}[]>
   // One field set PER ADIF RECORD this contact should produce.
-  fieldCombinationsForOneQSO?(args: { qso, operation }, ctx): Promise<{name, value}[][]>
+  fieldCombinationsForOneQSO?(args: { qso, operation, mainHandler? }, ctx): Promise<{name, value}[][]>
 }
 ```
 
+`mainHandler` is true when the file is this extension's own export — app-polo's
+argument of the same name. It is how a program writes what only its own
+submission asks for: SOTA's files carry both stations' gridsquares, which the
+full export leaves to the contact's own privacy rules.
+
 POTA contributes `SIG/SIG_INFO/POTA_REF` (hunted refs on the QSO) and
 `MY_SIG/MY_SIG_INFO/MY_POTA_REF` (activation refs on the operation).
 
@@ -795,11 +824,18 @@ would claim no reference at all.
 **A field name is written once per record, and the first to carry a value
 wins.** ADIF gives no meaning to a repeated field, so where two hooks answer
 the same name — the full export asks every program on the contact, and a park
-and a summit both answer `MY_SIG` — the later one is dropped, and the contact's own fields
-outrank all of them. Hooks are asked main handler first, then each
-`includeFieldsFrom` key in the order given, so that order decides — whichever
-of the two methods each hook answered. app-polo resolves a collision the same
-way ("keep the first one defined"). The **full export**, which asks every
+and a summit both answer `MY_SIG` — the later one is dropped. Hooks are asked
+main handler first, then each `includeFieldsFrom` key in the order given, so
+that order decides — whichever of the two methods each hook answered. The
+contact's own fields come after every hook's: a program knows what its file
+needs in a field better than the contact's generic answer does (the section a
+Field Day station sent, a satellite's downlink band). The exception is what
+identifies the contact — `CALL`, `QSO_DATE`, `TIME_ON`, `QSO_DATE_OFF`,
+`TIME_OFF`, `BAND`, `FREQ`, `MODE`, `SUBMODE`, `STATION_CALLSIGN`,
+`OPERATOR`: a hook answering one of those is dropped, since it would rewrite
+every record it is asked about, the whole-log backup included. This is a
+deliberate divergence from app-polo, whose contact fields come first and whose
+main handler's are appended unchecked, so a name both answer is written twice. The **full export**, which asks every
 program on the contact, has no such order: hooks answering `fieldCombinationsForOneQSO` are asked as one
 group and hooks answering `fieldsForOneQSO` as another, so which of two programs
 keeps a shared `MY_SIG` there is not something either of them chose.
@@ -1389,17 +1425,25 @@ interface PanelHook {
 // PanelDescriptor: {key, title, description?, icon?, preview?, on?, form?}
 // PanelRenderArgs: {panelKey, operation, qso?, qsoCount, config, reason}
 // PanelContent:    {kind: 'markdown' | 'svg' | 'html', content, title?, triggers?}
+//                | {kind: 'scene', scene, title?, triggers?}   (see Panel scene reference)
 ```
 
 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
+An experimental fourth kind, the **panel scene**, adds SVG and text layers, numeric
+bindings, local controls, native Material controls, a layout, and host-run animations.
+Its payload is `{kind: 'scene', scene, title?, triggers?}`; it does not have a
+`content` string. `kind: 'svgScene'` is the same kind under its name through SDK 0.9,
+which the SDK keeps as a deprecated alias along with the `SvgScene*` type names.
+**`scene` and everything it adds are extension API 5**: native controls,
+`strings`, `layout`, `after` and control `opacity`. A bundle using any of them
+declares `"api": 5` ([distribution.md](distribution.md)), and an app speaking
+less refuses it at install rather than showing the panel as an unknown kind.
+A plain scene that must reach those apps keeps `svgScene` and its lower API. 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
+value patches (`values`, and `strings` for string controls); 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`
@@ -1410,8 +1454,8 @@ may hold numbers or preformatted strings; control `valueLabels` supplies accessi
 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 design notes and open milestones](https://github.com/ham2k/halo/blob/main/docs/design/svg-scenes.md)
-and the `k2hrc-svg-scenes` sample. This API is experimental.
+individual readings without bridge calls. See [the design notes and open milestones](https://github.com/ham2k/halo/blob/main/docs/design/panel-scenes.md)
+and the `k2hrc-panel-scenes` sample. This API is experimental.
 
 Scene-capable hosts also supply `args.environment` on **render and event** calls:
 
@@ -1432,7 +1476,7 @@ Scene-capable hosts also supply `args.environment` on **render and event** calls
   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
+For a panel showing a scene, 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
@@ -1450,6 +1494,202 @@ 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.
 
+**Native controls.** Besides the drawn `button`, `slider` and `knob` — invisible
+hit areas over the extension's own artwork — a scene can use Material widgets
+the app themes itself: `nativeButton`, `nativeSlider`, `nativeTextField`,
+`nativeDropdown`, `nativeSwitch`, `nativeCheckbox`, `nativeRadio`,
+`nativeSegmented`, `nativeChip` and `nativeText`. `PanelSceneControl` in the SDK
+lists what each kind takes. String-valued controls (text field, dropdown, radio,
+segmented) bind to the scene's `strings` map, which sits beside `values`; a key
+is in one or the other, never both; a choice's string is `""` or one of its
+`options` (each comma-separated part, for `multi`). Their events carry `text` instead of `value`,
+and an `onEvent` result may return `strings` as well as `values`. A text layer
+whose `value` names a string shows it as-is. A text field commits on Enter, or
+on leaving it after typing; a render that lands while the operator is typing
+does not overwrite the typing. Every control's `label` is its accessible name;
+the app has no tooltips. A text field or dropdown in a panel keeps keyboard
+focus; clicking any other native control hands focus back to the callsign
+field, as clicking a button anywhere else in the Operation view does.
+
+**Layout.** A native control either has an `x`/`y`/`width`/`height` rect over the
+artwork, like the drawn kinds — it takes the rect's width and its own height, up
+to the rect's, so give a field a rect tall enough for it — or omits all four and is placed by
+`scene.layout` — a tree of Flutter's `row`, `column` and `wrap`, with `flex`/`fit`
+(Expanded and Flexible), `width`/`height`, `padding`, `spacing`, the two axis
+alignments, `{spacer: flex}`, `{control: id}`, and `{scene: true}` for the
+artwork, scaled to fit. Sizes are logical pixels, like the render environment's.
+Every rect-less control appears in the layout exactly once; a layout with no
+`scene` node shows no artwork, so it may declare no layers either. A text field
+or dropdown given no width (a row child without `flex` or `width`) is 200 wide,
+and a row's children that do not fit overflow as a Flutter `Row`'s do — use
+`flex` or `wrap`. A `flex` only shares space its row or column has: in a row
+that is itself an unflexed child of a row, there is none, and its children lay
+out at their own size. The layout is at most 8 deep and 128 nodes.
+
+**Controls among the layers.** Layers paint in order, and a control with a rect
+paints above all of them unless its `after` names a layer: then it paints
+directly after that one, and later layers draw over it. Layers are
+click-through: art painted over a control does not stop it working. A layer with
+`blocksPointer: true` takes the clicks that land on it while it is visible,
+covering the controls under it (keyboard focus still reaches them; mark them
+`disabled` too to shut them off). Only a pending action disables action
+controls; a value being sent does not. Any control can take an `opacity`, fixed or bound like a layer's;
+at 0 it takes no clicks, focus or screen-reader node.
+
+### Panel scene reference
+
+The schema in one place; `panelScene.ts` in the SDK carries the same as types.
+Every rule below is checked when the scene arrives: a scene that breaks one is
+refused whole, and the pane shows the error naming what is wrong, rather than
+drawing part of it.
+
+**The scene document**
+
+| Field | |
+|---|---|
+| `version` | `1` |
+| `width`, `height` | The artwork's viewBox, in scene units. Size it to `environment.width`/`height` and a scene unit is a logical pixel. |
+| `values` | `{name: number}`: what bindings, numeric text and numeric controls read. At most 256. |
+| `strings` | `{name: string}`: what text fields and choices hold. At most 256, each up to 4096 characters. A name is in `values` or `strings`, never both. |
+| `layers` | Painted in order, each over the ones before: `svg` artwork or `text`. At most 128, and 1 MiB of artwork and text in all. |
+| `controls` | At most 64. Drawn or native; see below. |
+| `layout` | Optional. Where rect-less native controls and the artwork go; omitted, the artwork fills the pane. |
+
+**Controls.** Every control has an `id` and a `label`, which is its accessible
+name. An `event` names the action sent when it is used; without one the control
+is local-only: its value changes on screen, survives renders, and never reaches
+the extension. `value` names what it shows and sets.
+
+| Kind | Binds to | Sends | Also takes |
+|---|---|---|---|
+| `button` | — | `activate` | `menu` |
+| `slider` | number | `commit` | `min`, `max`, `step`, `discrete`, `hover`, `valueLabels`, `continuous` |
+| `knob` | number | `commit` | `min`, `max`, `step`, `sensitivity`, `valueLabels`, `continuous` |
+| `nativeButton` | — | `activate` | `variant` (`filled`, `tonal`, `outlined`, `text`), `icon`, `menu`; needs `event` or `menu` |
+| `nativeSlider` | number | `commit` | `min`, `max`, `step`, `valueLabels`, `continuous` |
+| `nativeTextField` | string | `commit` on Enter, or on leaving it after typing | `placeholder`, `continuous` |
+| `nativeDropdown` | string | `commit` | `options`, `placeholder` |
+| `nativeRadio` | string | `commit` | `options` |
+| `nativeSegmented` | string | `commit` | `options`, `multi` |
+| `nativeSwitch`, `nativeCheckbox` | number, 1 or 0 | `commit` | — (shows `label` beside it) |
+| `nativeChip` | number, 1 or 0; or none | `commit`; `activate` without a value | `icon`; needs `event` without a value |
+| `nativeText` | number, string, or none | nothing | `style` (a typography role), `align` (`start`, `center`, `end`) |
+
+The three drawn kinds are invisible hit areas over artwork the extension paints;
+the native kinds are Material widgets the app paints and themes. Every control
+may also take:
+
+- `x`, `y`, `width`, `height`: its rect over the artwork, in scene units.
+  Required for the drawn kinds; a native control omits all four to be placed by
+  `layout` instead, and takes the rect's width and its own height when it has one.
+- `after`: with a rect, the layer it paints directly after.
+- `opacity`: 0 to 1, fixed or bound like a layer's. At 0 the control is gone.
+- `disabled`: shown, but no click, drag, key or screen-reader adjustment acts on it.
+
+`options` is `[{label, value}]`, up to 64, with each `value` unique. A choice's
+string is `""` or one of them; a `multi` choice holds its values joined with
+commas in option order, so no option may contain one. `menu` is
+`[{label, event}]`, up to 32: picking an item sends its `event` as the action.
+
+**Layout nodes.** Each is an object with exactly one of these keys:
+
+| Node | |
+|---|---|
+| `{row: [...]}`, `{column: [...]}` | Flutter's `Row` and `Column`. `mainAxisAlignment` (`start`, `center`, `end`, `spaceBetween`, `spaceAround`, `spaceEvenly`), `crossAxisAlignment` (`start`, `center`, `end`, `stretch`), `spacing`. |
+| `{wrap: [...]}` | Flutter's `Wrap`: `spacing`, `runSpacing`, the same alignments but no `stretch`. |
+| `{control: "id"}` | A native control without a rect. Each appears exactly once. |
+| `{scene: true}` | The artwork, scaled to fit. At most once. |
+| `{spacer: n}` | `Spacer(flex: n)`. |
+
+Any node may add `width`, `height` and `padding` (one number, or
+`[start, top, end, bottom]`). A row or column's direct child may add `flex`, with
+`fit: "tight"` (the default, Flutter's `Expanded`) or `"loose"` (`Flexible`). At
+most 8 deep and 128 nodes.
+
+**Events and results.** `onEvent` receives, beside the render args:
+
+```ts
+event: {
+  controlId: string      // the control's id
+  action: string         // its `event`, or the menu item's
+  phase: "activate" | "change" | "commit"
+  sequence: number       // increases with every event from this pane
+  value?: number         // for a control bound to `values`
+  text?: string          // for a control bound to `strings`
+}
+```
+
+It answers `{values, strings?}`: a patch of names already in the scene. An
+answer with neither is taken as a failure, and so is one that throws or runs out
+of time: the pane says the action failed, and the control goes back to what the
+scene last reported. The host sends one event at a time, keeps only the newest
+of a control's queued changes, ignores an answer to an event a newer one has
+superseded, and requests a render after each. Action controls are disabled while an
+action is waiting for its answer; a value being sent does not disable them. A text field's typing is sent before any action, and an
+action queued behind a value the extension refused is not sent.
+
+**An example.** A spot form over a status strip:
+
+```ts
+const state = { call: "", band: "20m", status: "Nothing spotted yet" }
+
+export const spotter: PanelHook = {
+  async getPanels() {
+    return [{ key: "spotter", title: "Spotter", icon: "bullhorn" }]
+  },
+  async render() {
+    return {
+      kind: "scene",
+      scene: {
+        version: 1,
+        width: 400,
+        height: 40,
+        values: {},
+        strings: state,
+        layers: [
+          {
+            id: "strip", x: 0, y: 0, width: 400, height: 40,
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 40"><rect width="400" height="40" rx="8" fill="#142337"/></svg>',
+          },
+          { id: "status", x: 12, y: 8, width: 376, height: 24, text: { value: "status", size: 14, color: "#a9efcf" } },
+        ],
+        controls: [
+          { id: "call", kind: "nativeTextField", label: "Callsign", value: "call", event: "set" },
+          {
+            id: "band", kind: "nativeDropdown", label: "Band", value: "band", event: "set",
+            options: ["40m", "20m", "15m"].map((b) => ({ label: b, value: b })),
+          },
+          { id: "spot", kind: "nativeButton", label: "Spot", icon: "bullhorn", event: "spot" },
+        ],
+        layout: {
+          column: [
+            { row: [{ control: "call", flex: 1 }, { control: "band", width: 110 }, { control: "spot" }], spacing: 8 },
+            { scene: true, flex: 1 },
+          ],
+          padding: 12,
+          spacing: 8,
+          crossAxisAlignment: "stretch",
+        },
+      },
+    }
+  },
+  async onEvent({ event }) {
+    if (event.controlId === "call" && event.text !== undefined) state.call = event.text.toUpperCase()
+    if (event.controlId === "band" && event.text !== undefined) state.band = event.text
+    if (event.action === "spot") {
+      if (!state.call) throw new Error("No callsign to spot")
+      state.status = `Spotted ${state.call} on ${state.band}`
+    }
+    return { values: {}, strings: state }
+  },
+}
+```
+
+The callsign comes back upper-cased, and the field shows the extension's
+version once the typing is committed. A bundle carrying this declares
+`"api": 5`. The `k2hrc-panel-scenes` sample in the SDK has every kind, a
+control faded in over the artwork, and a click-through layer painted over it.
+
 The `ki2d-weather-panel`, `ki2d-solar-panel` and `ki2d-radio-panel` reference
 panels live in
 [ham2k/extensions](https://github.com/ham2k/extensions/tree/main/extensions/dashboard).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",
@@ -71,12 +71,12 @@
     "build": "node build.mjs"
   },
   "//peerDependencies": [
-    "The libraries the extension host carries. An extension does NOT need these",
+    "The libraries the extension host provides. An extension does NOT need these",
     "installed: the build preset rewrites each one the manifest declares into a",
     "lookup on the host's single instance, before esbuild ever resolves it, and",
-    "the published .d.ts carries their types rolled in. They are here, optional,",
+    "the published .d.ts has their types rolled in. They are here, optional,",
     "for the one case that does reach the filesystem \u2014 `inline: [...]`, which",
-    "ships your own copy because you need a version the host does not carry."
+    "ships your own copy because you need a version the host does not provide."
   ],
   "peerDependencies": {
     "@ham2k/lib-callsigns": "*",

package/samples/README.md

@@ -10,7 +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 |
+| `k2hrc-panel-scenes` | Experimental panel scenes: SVG artwork, controls and animations, with simulated radio and weather panels |
 
 ## Running one
 

package/samples/{k2hrc-svg-scenes → k2hrc-panel-scenes}/README.md

@@ -1,7 +1,7 @@
-# SVG Scene Prototypes
+# Panel Scene Prototypes
 
-Experimental radio front face and weather inspection chart, using the public
-`svgScene` / `PanelHook.onEvent` contracts. Requires a host with SVG scene support.
+Experimental radio front face, weather inspection chart and native controls form, using the public
+`scene` / `PanelHook.onEvent` contracts. Requires a host with panel 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
@@ -16,9 +16,9 @@ In this repository:
 
 ```sh
 node build.mjs
-node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-svg-scenes.h2kext
+node ../../tools/h2kext-pack.mjs build -o /tmp/k2hrc-panel-scenes.h2kext
 ```
 
-For the contract and migration plan, see `docs/design/svg-scenes.md` in the
+For the contract and migration plan, see `docs/design/panel-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 → k2hrc-panel-scenes}/manifest.json

@@ -1,13 +1,13 @@
 {
-  "key": "k2hrc-svg-scenes",
-  "name": "SVG Scene Prototypes",
-  "shortName": "SVG Scenes",
+  "key": "k2hrc-panel-scenes",
+  "name": "Panel Scene Prototypes",
+  "shortName": "Panel Scenes",
   "version": "0.1.0",
-  "description": "Experimental radio front face and weather chart; simulated data only",
+  "description": "Experimental radio front face, weather chart and native controls; simulated data only",
   "category": "dashboard",
   "icon": "radio-tower",
   "accentColor": "#4C6EF5",
-  "api": 1,
+  "api": 5,
   "keywords": ["svg", "panel", "sample", "weather", "radio"],
   "hooks": ["panel"],
   "sharedDependencies": {

package/samples/{k2hrc-svg-scenes → k2hrc-panel-scenes}/src/scenes.ts

@@ -1,13 +1,13 @@
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
 // SPDX-License-Identifier: MIT
-import type { PanelContent, PanelHook, SceneBinding, SvgSceneLayer } from "@ham2k/extension-sdk"
+import type { PanelContent, PanelHook, PanelScene, SceneBinding, PanelSceneLayer } 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 => ({
+const textLayer = (id: string, value: string, x: number, y: number, width: number, size: number, prefix = "", suffix = "", decimals = 0): PanelSceneLayer => ({
   id,
   x,
   y,
@@ -17,9 +17,23 @@ const textLayer = (id: string, value: string, x: number, y: number, width: numbe
 })
 
 type RadioState = { requested: number; reported: number; connected: number; due: number; slow: number }
+type FormState = { strings: Record<string, string>; values: Record<string, 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>()
+  const forms = new Map<string, FormState>()
+  function form(id: string): FormState {
+    let f = forms.get(id)
+    if (!f) {
+      if (forms.size >= 64) forms.delete(forms.keys().next().value!)
+      f = {
+        strings: { call: "", band: "20m", mode: "CW", antenna: "vertical", status: "Nothing spotted yet" },
+        values: { power: 100, qrp: 0, cluster: 1, cwOnly: 0, spotted: 0 },
+      }
+      forms.set(id, f)
+    }
+    return f
+  }
   function state(id: string): RadioState {
     let s = radios.get(id)
     if (!s) {
@@ -39,14 +53,16 @@ export function createScenePanels(now: () => number = () => Date.now()): PanelHo
       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 },
+        { key: "controls", title: "Native Controls · Simulation", icon: "form-textbox", multiple: true },
       ]
     },
     async render(args): Promise<PanelContent> {
+      if (args.panelKey === "controls") return { kind: "scene", scene: controlsScene(form(args.instanceId ?? args.panelKey)) }
       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",
+          kind: "scene",
           scene: {
             version: 1,
             width: 640,
@@ -91,7 +107,7 @@ export function createScenePanels(now: () => number = () => Date.now()): PanelHo
       }
       const s = state(args.instanceId ?? args.panelKey)
       return {
-        kind: "svgScene",
+        kind: "scene",
         scene: {
           version: 1,
           width: 640,
@@ -213,8 +229,25 @@ export function createScenePanels(now: () => number = () => Date.now()): PanelHo
       }
     },
     async onEvent(args) {
-      const s = state(args.instanceId ?? args.panelKey)
       const event = args.event
+      if (args.panelKey === "controls") {
+        const f = form(args.instanceId ?? args.panelKey)
+        if (event.text !== undefined) f.strings[event.controlId] = event.text
+        if (event.value !== undefined) f.values[event.controlId] = event.value
+        if (event.action === "spot") {
+          const call = f.strings.call.trim().toUpperCase()
+          if (!call) throw new Error("No callsign to spot")
+          f.strings.call = call
+          f.values.spotted = 1
+          f.strings.status = `Spotted ${call} on ${f.strings.band} ${f.strings.mode}, ${f.values.qrp ? 5 : f.values.power} W`
+        }
+        if (event.action === "clear") {
+          f.values.spotted = 0
+          f.strings.status = "Nothing spotted yet"
+        }
+        return { values: f.values, strings: f.strings }
+      }
+      const s = state(args.instanceId ?? args.panelKey)
       if (event.action === "connect") {
         s.connected = 1 - s.connected
         s.due = 0
@@ -241,3 +274,88 @@ export function createScenePanels(now: () => number = () => Date.now()): PanelHo
     },
   }
 }
+
+/**
+ * Every native control kind, placed by a layout around a strip of artwork. Clear sits
+ * over the strip instead: ordered among its layers, under a click-through sheen, and
+ * faded out until there is something to clear.
+ */
+function controlsScene(f: FormState): PanelScene {
+  return {
+    version: 1,
+    width: 640,
+    height: 60,
+    values: f.values,
+    strings: f.strings,
+    layers: [
+      { id: "strip", x: 0, y: 0, width: 640, height: 60, svg: svg('<rect width="640" height="60" rx="10" fill="#142337"/>', 640, 60) },
+      { id: "status", x: 16, y: 16, width: 490, height: 28, text: { value: "status", size: 16, color: "#a9efcf" } },
+      {
+        id: "sheen",
+        x: 0,
+        y: 0,
+        width: 640,
+        height: 30,
+        svg: svg('<rect width="640" height="30" rx="10" fill="#ffffff" fill-opacity="0.08"/>', 640, 30),
+      },
+    ],
+    controls: [
+      { id: "call", kind: "nativeTextField", label: "Callsign", placeholder: "W1AW", value: "call", event: "set" },
+      {
+        id: "band",
+        kind: "nativeDropdown",
+        label: "Band",
+        value: "band",
+        event: "set",
+        options: ["40m", "20m", "15m", "10m"].map((b) => ({ label: b, value: b })),
+      },
+      { id: "mode", kind: "nativeSegmented", label: "Mode", value: "mode", event: "set", options: ["CW", "SSB", "FT8"].map((m) => ({ label: m, value: m })) },
+      { id: "spot", kind: "nativeButton", label: "Spot", icon: "bullhorn", event: "spot" },
+      {
+        id: "clear",
+        kind: "nativeButton",
+        label: "Clear",
+        variant: "outlined",
+        event: "clear",
+        after: "status",
+        x: 520,
+        y: 10,
+        width: 110,
+        height: 40,
+        opacity: { value: "spotted", input: [0, 1], output: [0, 1] },
+      },
+      { id: "power", kind: "nativeSlider", label: "Power, watts", value: "power", event: "set", min: 5, max: 100, step: 5, disabled: f.values.qrp === 1 },
+      { id: "qrp", kind: "nativeSwitch", label: "QRP", value: "qrp", event: "set" },
+      { id: "cluster", kind: "nativeCheckbox", label: "Send to cluster", value: "cluster", event: "set" },
+      {
+        id: "antenna",
+        kind: "nativeRadio",
+        label: "Antenna",
+        value: "antenna",
+        event: "set",
+        options: [
+          { label: "Vertical", value: "vertical" },
+          { label: "Dipole", value: "dipole" },
+        ],
+      },
+      { id: "cw", kind: "nativeChip", label: "CW only", value: "cwOnly", icon: "filter" },
+      { id: "powerText", kind: "nativeText", label: "Power", value: "power", style: "mono", align: "end" },
+    ],
+    layout: {
+      column: [
+        { row: [{ control: "call", flex: 1 }, { control: "band", width: 110 }, { control: "mode" }], spacing: 8 },
+        { scene: true, flex: 1 },
+        {
+          wrap: [{ control: "qrp" }, { control: "cluster" }, { control: "antenna" }, { control: "cw" }],
+          spacing: 12,
+          runSpacing: 4,
+          crossAxisAlignment: "center",
+        },
+        { row: [{ control: "power", flex: 1 }, { control: "powerText", width: 48 }, { control: "spot" }], spacing: 8 },
+      ],
+      padding: 12,
+      spacing: 8,
+      crossAxisAlignment: "stretch",
+    },
+  }
+}