@ham2k/extension-sdk 0.10.0 → 0.10.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.10.0
+// @ham2k/extension-sdk 0.10.1
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -661,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;

package/docs/distribution.md

@@ -526,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

@@ -741,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).
 
@@ -819,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.

package/package.json

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