@ham2k/extension-sdk 0.6.0 → 0.7.0

package/AGENTS.md

@@ -104,6 +104,7 @@ import { host } from "@ham2k/extension-sdk"
 
 await host.fetch(url)          // https only, and only domains your manifest lists
 host.webSocket(url)            // wss:// to hosts your manifest's webSockets lists
+host.setTimeout(fn, ms)        // timers — plain setTimeout reaches these too
 await host.kvGet('key')        // storage, namespaced to your extension
 await host.kvSet('key', value)
 await host.showForm(form)      // ask the user something
@@ -132,6 +133,10 @@ host.log('…')                  // the app's console
   reserved.
 - **`host.secret()` returns null** for anything not built into the app. Degrade;
   don't throw. A hook that throws takes its whole feature down.
+- **Timers are budgeted, not free.** An extension's callbacks may average 10%
+  of real time; past that, or after five throwing in a row, its timers are
+  suspended until the extensions restart. At most 16 at once. Reconnect with a
+  growing delay, never straight from `onclose`.
 - **Hook method names are routed by string.** The host finds your hook by its
   registered key and then calls the method by name, so `renderPanel` where
   `render` was meant is an extension that installs, activates, and does nothing.

package/dist/hookCategories.js

@@ -0,0 +1,25 @@
+const HOOK_CATEGORIES = [
+  "account",
+  "activity",
+  "adifFields",
+  "adifImport",
+  "bench",
+  "callNotes",
+  "command",
+  "dataFile",
+  "export",
+  "form",
+  "lookup",
+  "lookupService",
+  "panel",
+  "recentContextLookup",
+  "runtime",
+  "scoring",
+  "settingsPanel",
+  "spots",
+  "syncTransport",
+  "template"
+];
+export {
+  HOOK_CATEGORIES
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.6.0
+// @ham2k/extension-sdk 0.7.0
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -116,6 +116,30 @@ export interface PanelSceneEvent {
 export interface PanelSceneEventResult {
 	values: Record<string, number>;
 }
+export declare const HOOK_CATEGORIES: readonly [
+	"account",
+	"activity",
+	"adifFields",
+	"adifImport",
+	"bench",
+	"callNotes",
+	"command",
+	"dataFile",
+	"export",
+	"form",
+	"lookup",
+	"lookupService",
+	"panel",
+	"recentContextLookup",
+	"runtime",
+	"scoring",
+	"settingsPanel",
+	"spots",
+	"syncTransport",
+	"template"
+];
+export type HookCategory = (typeof HOOK_CATEGORIES)[number];
+export type HookCategoryName = HookCategory | `ref:${string}`;
 export type CallInfo = {
 	call: string;
 	baseCall?: string;
@@ -793,6 +817,7 @@ export interface CommandAction {
 	devBench?: {
 		qsoCount?: number;
 	};
+	devLogCat?: Record<string, never>;
 	toggleExperiment?: {
 		token: string;
 	};
@@ -938,8 +963,12 @@ export interface RegisterHookParams {
 	priority?: number;
 }
 export interface ActivationApi {
-	registerHook(category: string, params: RegisterHookParams): void;
+	registerHook(category: HookCategoryName, params: RegisterHookParams): void;
 	hostCall(method: string, params: Record<string, unknown>): Promise<unknown>;
+	timers?: {
+		set(callback: unknown, delay: unknown, repeat: boolean, args: unknown[]): number;
+		clear(id: unknown): void;
+	};
 }
 export interface ExtensionRelevance {
 	entities?: string[];
@@ -961,6 +990,7 @@ export interface ExtensionManifest {
 	category?: string;
 	enabledByDefault?: boolean;
 	hooks?: string[];
+	adifFieldsScope?: "always";
 	domains?: string[];
 	webSockets?: string[];
 	allowUserAgentOverride?: boolean;
@@ -977,6 +1007,8 @@ export interface ExtensionManifest {
 }
 export interface ExtensionDefinition extends ExtensionManifest {
 	onActivation(api: ActivationApi): void;
+	onShow?(): void | Promise<void>;
+	onHide?(): void | Promise<void>;
 }
 export interface FetchOptions {
 	method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -1409,6 +1441,10 @@ export interface PanelHook {
 		event: PanelSceneEvent;
 	}, ctx: HookContext): Promise<PanelSceneEventResult>;
 }
+declare function setTimeout$1(callback: (...args: any[]) => unknown, delay?: number, ...args: unknown[]): number;
+declare function setInterval$1(callback: (...args: any[]) => unknown, delay?: number, ...args: unknown[]): number;
+declare function clearTimeout$1(id?: number): void;
+declare function clearInterval$1(id?: number): void;
 /**
  * The standard per-extension translator: takes the extension's i18next
  * resources once and returns a `tFor(ctx)` that hooks call with their
@@ -1693,25 +1729,35 @@ export interface TemplateContextArgs {
 	log?: LogValues;
 	appName?: string;
 	atMillis?: number;
+	keyer?: {
+		messages: string[];
+		current?: number;
+	};
 	nowMillis?: number;
 }
 export declare function templateContext(args: TemplateContextArgs): Record<string, unknown>;
 export declare function isTestOperation(stationCall: JSONValue | undefined): boolean;
 export declare function defineExtension(def: ExtensionDefinition): void;
 export declare const hooks: {
-	invokeAll(category: string, method: string, args: unknown, online?: boolean): Promise<{
+	invokeAll(category: HookCategoryName, method: string, args: unknown, online?: boolean): Promise<{
+		key: string;
+		ok: boolean;
+		value?: unknown;
+		error?: string;
+	}[]>;
+	invokeOne(category: HookCategoryName, key: string, method: string, args: unknown, online?: boolean): Promise<{
 		key: string;
 		ok: boolean;
 		value?: unknown;
 		error?: string;
 	}[]>;
-	invokeOne(category: string, key: string, method: string, args: unknown, online?: boolean): Promise<{
+	invokeForRefs(category: HookCategoryName, method: string, args: unknown, refs: unknown[], online?: boolean): Promise<{
 		key: string;
 		ok: boolean;
 		value?: unknown;
 		error?: string;
 	}[]>;
-	invokeAllSequential(category: string, method: string, initialArgs: unknown, fold: (args: unknown, hookResult: unknown, hookKey: string) => unknown, online?: boolean): Promise<{
+	invokeAllSequential(category: HookCategoryName, method: string, initialArgs: unknown, fold: (args: unknown, hookResult: unknown, hookKey: string) => unknown, online?: boolean): Promise<{
 		key: string;
 		ok: boolean;
 		value?: unknown;
@@ -1753,6 +1799,10 @@ export declare const host: {
 		dismissNotice(key: string): Promise<void>;
 	};
 	log(message: string): void;
+	setTimeout: typeof setTimeout$1;
+	setInterval: typeof setInterval$1;
+	clearTimeout: typeof clearTimeout$1;
+	clearInterval: typeof clearInterval$1;
 	updateInterpretation(input: string, interpretation: Record<string, unknown>): void;
 };
 

package/dist/index.js

@@ -1,5 +1,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 "./i18n.js";
 export * from "./dxcc.js";
@@ -33,8 +35,14 @@ function defineExtension(def) {
   currentExtensionKey = def.key;
   kernel().defineExtension({
     ...def,
+    // Called on the author's own object, as onActivation is below, so `this`
+    // is the same object in all three: state kept on it at activation is there
+    // to stop on hide.
+    onShow: def.onShow && (() => def.onShow()),
+    onHide: def.onHide && (() => def.onHide()),
     onActivation(api) {
       if (typeof api.hostCall === "function") privilegedHostCalls[def.key] = api.hostCall;
+      adoptExtensionTimers(def.key, currentExtensionKey, api.timers);
       return def.onActivation(api);
     }
   });
@@ -133,6 +141,15 @@ const hooks = {
   invokeOne(category, key, method, args, online) {
     return kernel().invokeLocal(category, method, args, online, key);
   },
+  /// Like `invokeAll`, but only the hooks of the extensions that answer for one
+  /// of [refs] — for each, those holding the strongest `ref:<type>` claim on it
+  /// (a `ref:<type>/<code>` prefix beats the bare type) — plus, for
+  /// `adifFields`, any whose manifest sets `adifFieldsScope: "always"`.
+  /// For a fan-out over programs that must leave out the ones a contact has
+  /// nothing to do with, as the full ADIF export does.
+  invokeForRefs(category, method, args, refs, online) {
+    return kernel().invokeLocal(category, method, args, online, null, refs);
+  },
   /// Like `invokeAll`, but calls hooks one at a time in priority order,
   /// threading each result into the next call's args via `fold` — needed
   /// when later hooks must see earlier hooks' contributions.
@@ -318,6 +335,14 @@ const host = {
   log(message) {
     kernel().log(`[${currentExtensionKey}] ${message}`);
   },
+  /// Browser-shaped timers, on real time, bound to this extension and held to
+  /// its budget (docs/extensions/README.md, "Timers"). A bundle built for
+  /// extension API 3 reaches these from a plain `setTimeout` too, npm
+  /// dependencies included (sdk/src/timers.ts).
+  setTimeout,
+  setInterval,
+  clearTimeout,
+  clearInterval,
   /// Pushes a later CommandInterpretation for the same `input` a `command`
   /// hook's `interpret()` was called with — see CommandHook's doc. One-way,
   /// like `log`: call it, don't await anything back.

package/dist/templateContext.js

@@ -1,3 +1,4 @@
+import { TemplateError, renderTemplate } from "./templates.js";
 function utcDate(millis) {
   return new Date(millis).toISOString().slice(0, 10);
 }
@@ -59,10 +60,19 @@ function opValues(operation, extra = {}) {
 function qsoValues(qso) {
   const their = qso.their ?? {};
   const our = qso.our ?? {};
+  const callField = qso.callField ?? {};
+  const guess = their.guess ?? {};
   const startMillis = Number(qso.startAtMillis ?? 0);
   const serialSent = refField(qso.refs, "ourSerial");
   return {
-    call: their.call ?? "",
+    // `||`, not `??`: a blank reading still means "no call", and the field
+    // as typed is a better answer than keying nothing.
+    call: callField.call || their.call || "",
+    // The panel's split of `call` — a logged contact's call is a full one.
+    fullCall: callField.fullCall ?? their.call ?? "",
+    partial: callField.partial ?? "",
+    nextCall: callField.nextCall ?? "",
+    nextPartial: callField.nextPartial ?? "",
     their,
     our,
     band: qso.band ?? "",
@@ -80,12 +90,26 @@ function qsoValues(qso) {
     // that is where these get typed.
     rst: our.sent ?? "",
     serial: serialSent,
+    // What was typed, else what the lookup found — the two places a CW
+    // message's "GM BOB" or "NY" would otherwise have to be chained by hand.
+    // `name` is the first word only: a lookup's "Robert J Smith" keyed in
+    // full is not how anyone greets a station.
+    state: firstText(their.state, guess.state),
+    name: firstText(their.name, guess.name).split(/\s+/)[0],
     notes: qso.notes ?? "",
     refs: qso.refs ?? [],
     ...startMillis > 0 ? dateValues(startMillis) : { date: "", dateCompact: "", time: "", at: "" },
     startAtMillis: startMillis
   };
 }
+function firstText(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const text = value.trim();
+    if (text !== "") return text;
+  }
+  return "";
+}
 function refField(refs, field) {
   if (!Array.isArray(refs)) return "";
   for (const ref of refs) {
@@ -115,7 +139,7 @@ function logValues(values) {
 }
 function templateContext(args) {
   const nowMillis = args.nowMillis ?? Date.now();
-  return {
+  const context = {
     app: { name: args.appName ?? "" },
     now: utcIso(nowMillis),
     ...args.operation ? { op: opValues(args.operation, { qsoCount: args.qsoCount, atMillis: args.atMillis }) } : {},
@@ -123,6 +147,23 @@ function templateContext(args) {
     ...args.log ? { log: logValues(args.log) } : {},
     ...args.config ? { config: args.config } : {}
   };
+  if (args.keyer) context.keyer = keyerValues(context, args.keyer.messages ?? [], args.keyer.current ? [args.keyer.current] : []);
+  return context;
+}
+function keyerValues(base, messages, chain) {
+  const keyer = {};
+  messages.forEach((template, i) => {
+    const n = i + 1;
+    Object.defineProperty(keyer, `msg${n}`, {
+      enumerable: true,
+      get() {
+        const path = [...chain, n];
+        if (chain.includes(n)) throw new TemplateError(`a message includes itself: ${path.map((k) => `F${k}`).join(" \u2192 ")}`);
+        return renderTemplate(template ?? "", { ...base, keyer: keyerValues(base, messages, path) });
+      }
+    });
+  });
+  return keyer;
 }
 export {
   dateValues,

package/dist/timerQueue.js

@@ -0,0 +1,187 @@
+const MAX_TIMERS_PER_EXTENSION = 16;
+const FIRE_COST_MILLIS = 1;
+const TIMER_DUTY_CYCLE = 0.1;
+const TIMER_BURST_MILLIS = 5e3;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const RUN_SLICE_MILLIS = 1e3;
+const MAX_DELAY_MILLIS = 2 ** 31 - 1;
+function createTimerQueue(host) {
+  const timers = /* @__PURE__ */ new Map();
+  const accounts = /* @__PURE__ */ new Set();
+  let nextId = 1;
+  let armed = null;
+  let inCallback = null;
+  function rearm() {
+    let earliest = null;
+    for (const t of timers.values()) {
+      if (earliest === null || t.deadline < earliest) earliest = t.deadline;
+    }
+    if (earliest === armed) return;
+    armed = earliest;
+    host.wake(earliest === null ? null : Math.max(0, Math.ceil(earliest - host.realNow())));
+  }
+  function suspend(owner, reason) {
+    if (owner.suspended || owner.revoked) return;
+    owner.suspended = reason;
+    for (const t of [...timers.values()]) {
+      if (t.owner === owner) timers.delete(t.id);
+    }
+    const why = {
+      budget: `its callbacks used more than ${TIMER_DUTY_CYCLE * 100}% of the time`,
+      failures: `${MAX_CONSECUTIVE_FAILURES} callbacks in a row failed`,
+      interrupted: "a callback ran past the engine's time limit"
+    }[reason];
+    host.log(`ERROR ${owner.key} timers suspended: ${why}`);
+    host.suspended(owner.key, reason);
+    rearm();
+  }
+  function cancelAll(owner) {
+    for (const t of [...timers.values()]) {
+      if (t.owner === owner) timers.delete(t.id);
+    }
+  }
+  function refuse(owner, why) {
+    if (!owner.refusalsLogged.has(why)) {
+      owner.refusalsLogged.add(why);
+      host.log(`ERROR ${owner.key} set a timer ${why}; it will not fire`);
+    }
+    return nextId++;
+  }
+  function charge(owner, cost) {
+    const now = host.realNow();
+    owner.debt = Math.max(0, owner.debt - (now - owner.chargedAt) * TIMER_DUTY_CYCLE) + cost;
+    owner.chargedAt = now;
+    if (owner.debt > TIMER_BURST_MILLIS) suspend(owner, "budget");
+  }
+  function failed(owner, e) {
+    host.log(`ERROR ${owner.key} timer callback: ${host.describeError(e)}`);
+    owner.failures++;
+    if (owner.failures >= MAX_CONSECUTIVE_FAILURES) suspend(owner, "failures");
+  }
+  function succeeded(owner) {
+    owner.failures = 0;
+  }
+  function fire(t, wakeCost) {
+    const startedAt = host.realNow();
+    let result;
+    let threw = false;
+    inCallback = t;
+    try {
+      result = t.callback(...t.args);
+    } catch (e) {
+      threw = true;
+      failed(t.owner, e);
+    }
+    inCallback = null;
+    charge(t.owner, host.realNow() - startedAt + wakeCost);
+    if (threw) return;
+    succeeded(t.owner);
+    if (result instanceof Promise) {
+      result.catch((e) => host.log(`ERROR ${t.owner.key} timer callback: ${host.describeError(e)}`));
+    }
+  }
+  return {
+    owner(key) {
+      const owner = { key, debt: 0, chargedAt: host.realNow(), failures: 0, suspended: null, revoked: false, refusalsLogged: /* @__PURE__ */ new Set() };
+      accounts.add(owner);
+      return owner;
+    },
+    set(handle, callback, delay, repeat, args) {
+      const owner = handle;
+      if (typeof callback !== "function") throw new TypeError("timer callback must be a function");
+      if (owner.revoked) return refuse(owner, "after it was unloaded");
+      if (owner.suspended) return refuse(owner, "while its timers are suspended");
+      let live = 0;
+      for (const t of timers.values()) if (t.owner === owner) live++;
+      if (live >= MAX_TIMERS_PER_EXTENSION) return refuse(owner, `beyond its ${MAX_TIMERS_PER_EXTENSION} live timers`);
+      const n = Number(delay);
+      const ms = n > 0 ? Math.min(Math.trunc(n), MAX_DELAY_MILLIS) : 0;
+      const id = nextId++;
+      timers.set(id, {
+        id,
+        owner,
+        callback,
+        args,
+        deadline: host.realNow() + ms,
+        interval: repeat ? ms : null
+      });
+      rearm();
+      return id;
+    },
+    /// Ids are guessable, so one owner's clear never reaches another's timer.
+    clear(handle, id) {
+      const t = timers.get(id);
+      if (!t || t.owner !== handle) return;
+      timers.delete(t.id);
+      rearm();
+    },
+    /// Fires what was due when it started. A timer set by one of these
+    /// callbacks waits for the next wake even at zero delay: running it here
+    /// would let a zero-delay chain spin inside a single evaluation.
+    run() {
+      armed = null;
+      if (inCallback) {
+        const cutShort = inCallback;
+        inCallback = null;
+        suspend(cutShort.owner, "interrupted");
+      }
+      const now = host.realNow();
+      const due = [...timers.values()].filter((t) => t.deadline <= now).sort((a, b) => a.deadline - b.deadline || a.id - b.id);
+      const woken = /* @__PURE__ */ new Set();
+      for (const t of due) {
+        if (host.realNow() - now >= RUN_SLICE_MILLIS) break;
+        if (timers.get(t.id) !== t) continue;
+        if (t.interval === null) timers.delete(t.id);
+        const wakeCost = woken.has(t.owner) ? 0 : FIRE_COST_MILLIS;
+        woken.add(t.owner);
+        fire(t, wakeCost);
+        if (t.interval !== null && timers.get(t.id) === t) t.deadline = host.realNow() + t.interval;
+      }
+      rearm();
+    },
+    /// Cancels what one activation — one that failed — has set, and nothing
+    /// of a newer activation's: a dev reload can start the new one before the
+    /// old one's failure arrives. The handle stays good, because the hooks
+    /// that activation registered before failing are still called.
+    cancel(handle) {
+      cancelAll(handle);
+      rearm();
+    },
+    /// Revokes every activation of [keys]: their timers go, their handles
+    /// ignore new ones, and a reloaded extension starts clean on a new handle.
+    drop(keys) {
+      for (const owner of [...accounts]) {
+        if (!keys.includes(owner.key)) continue;
+        owner.revoked = true;
+        accounts.delete(owner);
+        cancelAll(owner);
+      }
+      rearm();
+    }
+  };
+}
+function removeAmbientTimers(global = globalThis) {
+  for (const name of ["setTimeout", "setInterval", "clearTimeout", "clearInterval"]) {
+    try {
+      delete global[name];
+    } catch (e) {
+    }
+    if (typeof global[name] === "function") {
+      try {
+        global[name] = void 0;
+      } catch (e) {
+      }
+    }
+  }
+  return ["setTimeout", "setInterval", "clearTimeout", "clearInterval"].every((name) => typeof global[name] !== "function");
+}
+export {
+  FIRE_COST_MILLIS,
+  MAX_CONSECUTIVE_FAILURES,
+  MAX_TIMERS_PER_EXTENSION,
+  RUN_SLICE_MILLIS,
+  TIMER_BURST_MILLIS,
+  TIMER_DUTY_CYCLE,
+  createTimerQueue,
+  removeAmbientTimers
+};

package/dist/timers.js

@@ -0,0 +1,42 @@
+const bound = {};
+let preferredKey = null;
+let activated = false;
+function adoptExtensionTimers(key, currentKey, timers) {
+  activated = true;
+  preferredKey = currentKey;
+  if (timers) bound[key] = timers;
+}
+function boundTimers() {
+  return (preferredKey !== null ? bound[preferredKey] : void 0) ?? Object.values(bound)[0];
+}
+const refusalsLogged = /* @__PURE__ */ new Set();
+function set(callback, delay, repeat, args) {
+  const timers = boundTimers();
+  if (timers) return timers.set(callback, delay, repeat, args);
+  const why = activated ? "this version of HaLo has no timers" : "set before the extension activated";
+  if (!refusalsLogged.has(why)) {
+    refusalsLogged.add(why);
+    const who = preferredKey !== null ? `${preferredKey}: ` : "";
+    globalThis.__polo?.log(`ERROR ${who}a timer was ignored: ${why}`);
+  }
+  return 0;
+}
+function setTimeout(callback, delay, ...args) {
+  return set(callback, delay, false, args);
+}
+function setInterval(callback, delay, ...args) {
+  return set(callback, delay, true, args);
+}
+function clearTimeout(id) {
+  boundTimers()?.clear(id);
+}
+function clearInterval(id) {
+  clearTimeout(id);
+}
+export {
+  adoptExtensionTimers,
+  clearInterval,
+  clearTimeout,
+  setInterval,
+  setTimeout
+};

package/docs/distribution.md

@@ -48,7 +48,9 @@ it does not speak, so an older app meeting a newer bundle says so instead of
 failing somewhere deep in a hook — and the catalog does not list it for that
 app at all. Declare the lowest version that has what the bundle uses, so it
 reaches every app that can run it: 2 adds `host.webSocket`, and the packer
-refuses a manifest declaring `webSockets` under anything less.
+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").
 
 Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
@@ -257,7 +259,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 2)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 3)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own
@@ -322,7 +324,8 @@ configured.
 
 The sandbox is otherwise the same one the built-in extensions run in — no
 filesystem, no network beyond the `domains` and `webSockets` the manifest
-declares and the user approved, no timers.
+declares and the user approved, and timers only within their budget
+(README's "Timers").
 
 ## Installing one
 
@@ -345,6 +348,14 @@ that key is compared — a bundle can change completely and still ask for the
 same things. That may be worth revisiting once a bundle can be shown to come
 from whoever it claims; it is not worth it while a key is all there is.
 
+**Update all is the one exception.** It takes every pending catalog update on
+a single confirmation that names each extension and the version it moves to,
+and skips the per-extension screen for each of them: asking once per entry for
+the one thing the operator asked for once is how a screen gets pressed through
+unread. It is a confirmation of a job the operator started, never a way to
+start one — `install_consent_scope_test` holds it to the one function that
+shows that confirmation first.
+
 Removing an extension removes what it stored with it.
 
 ### Installing from a link
@@ -480,7 +491,14 @@ takes the plain one above.
 At most once every six hours — on launch and on resume — the app asks the
 catalog whether anything installed has a newer release, and says so in the
 status bar and on the row; the notice comes down with the last update taken.
-It never installs unasked. A release the catalog has revoked is put on record
+It never installs unasked: the notice's **Update all** is the panel's own,
+behind the same confirmation, and **More info** opens the panel.
+
+An install or update narrates itself as one status-bar progress item, from the
+first downloaded byte to "Installed", and the Extensions panel mirrors that
+item on the row being installed. Installs share one queue
+(`ExtensionInstaller`): downloads run side by side, while the writes go one at
+a time, since each restarts the runtime. A release the catalog has revoked is put on record
 (`extensionRevoked`: version and note) and stops loading on the spot,
 whatever the operator's own switch says — the row shows "Revoked" with the
 note and no switch, and the record dies with an install of another version

package/docs/hooks.md

@@ -2,11 +2,30 @@
 
 Hooks are registered under a **category** with an optional **key** (defaults
 to the extension key) and **priority** (higher runs first; default 0). The
-host invokes them two ways:
+host invokes them three ways:
 
 - `invokeHook(category, key?, method, args)` — best (highest-priority) hook.
 - `invokeHookAll(category, method, args)` — every hook in the category, one
   bridge round-trip, per-source error isolation.
+- `invokeHookBatch(calls)` — several `invokeHook` calls, one bridge
+  round-trip, per-call error isolation. Each call reaches the same hook it
+  would reach on its own, so a hook cannot tell a batched call from a single
+  one.
+
+The categories are a closed list. `registerHook` takes a `HookCategory`
+([`extensions/sdk/src/hookCategories.ts`](https://github.com/ham2k/halo/blob/main/extensions/sdk/src/hookCategories.ts))
+or `ref:<type>`, so a misspelled category fails the typecheck rather than
+registering a hook nothing calls, and the build rejects a manifest `hooks`
+entry that is neither. A new category goes into that list — and, when the host
+calls it, into the host's catalog as well
+(`packages/halo_core/lib/src/hook_names.dart`).
+
+In both shapes that answer many hooks at once, one hook failing costs its own
+entry and nothing else — whether it throws, has no handler, or answers
+something JSON cannot carry (a circular object, a `BigInt`). One that runs out
+of time does too, when the caller asks for partial results; otherwise, and for
+a batch of several calls that runs out of time before any answer has reached
+the host, the whole call fails.
 
 All argument and result types below are defined in
 [`extensions/sdk/src/types.ts`](https://github.com/ham2k/halo/blob/main/extensions/sdk/src/types.ts). Every
@@ -422,6 +441,18 @@ interface RefHandlerHook {
 etc.); results update ref chips asynchronously in the UI. Implemented by:
 `pota` (both types).
 
+**The core asks about references in batches.** Every reference an ADIF import
+or a deep link brings is decorated in one bridge round-trip, and so is every
+link a list of search results needs, every outline a map draws, and every
+phrase of an operation's title. Each reference is still its own call, to the
+handler `invokeHook` would pick for it (qualified claims included), so a
+handler implements the single-reference methods above and nothing else. The
+time budget belongs to the batch, though: ten seconds for all of its calls
+together. A handler that has not answered by then costs only its own
+reference — it stays as it was, with no name, link or outline — and every
+other reference keeps its answer. A `decorateRef` that goes to the network
+should answer well within that.
+
 `linkForRef` says where a reference can be read about on the web — the
 program's own page for it (POTA's park page, SOTA's summit page), or, for a
 contest, the rules the event is run under. The Operation Setup sheet asks for
@@ -598,8 +629,12 @@ true when THIS extension alone was asked — the operator tapped its "Activity
 Types" row or typed its key as a scope — which a bare scope otherwise cannot be
 told from the nearby list, since neither carries a `searchTerm`. An extension
 that keeps itself out of the nearby list (`cwt`, offered only around a session)
-answers a scoped call anyway: it is the one being asked. The core fans
-out to every `activity` hook via `invokeHookAll`, merges results, and ranks them
+answers a scoped call anyway: it is the one being asked. The core fans out to
+every `activity` hook via `invokeHookAll`; a scoped search asks only its own
+hooks, in one batch (`invokeHookBatch`); and a search naming a type without the
+colon asks that type's hooks in one batch AND fans out to every hook — two
+round-trips, kept apart so a fan-out that runs out of time cannot cost the named
+type's answers. The core merges results and ranks them
 in TWO BANDS (`app/lib/tools/activity_suggestions.dart`): everything carrying a
 `distance` first, by `distance / relevance` ascending — a more relevant hit
 counts as nearer — then everything without one, by DESCENDING `relevance`, with
@@ -715,9 +750,38 @@ file claims its own reference; ask every hook and both programs'
 program to guess which is its. The delegate cannot work out who called it, so
 naming yourself is not optional.
 
-The full ADIF export names no `mainHandler` and every hook contributes —
-polo's `includeOtherRefs`, which only its full export sets. That is the export
-claiming no program: the complete copy the operator keeps.
+The full ADIF export names no `mainHandler`, and every program the contact
+belongs to contributes — polo's `includeOtherRefs`, which only its full export
+sets. That is the export claiming no program: the complete copy the operator
+keeps.
+
+**The full export asks only the extensions a contact belongs to.** For each
+reference on the contact's operation (the segment-effective one) and on the
+contact itself, the kernel takes every extension holding the strongest claim
+on it — the longest `ref:<type>/<code>` prefix that begins the reference's
+code, or else the bare `ref:<type>` — and asks those extensions' hooks, and no
+other's. A hunted reference on the contact counts as much as an activation on
+the operation, so a chaser's log keeps its `SOTA_REF`s. A longer claim excludes
+a shorter one: an old `{type: 'qp', ref: 'CA'}` reference belongs to the party
+that claims `qp/ca`, not also to the extension claiming all of `qp`. Equal
+claims are all asked, whatever their priority: WCA also registers
+`ref:ecaActivation` to resolve a castle while ECA is off, and ECA's fields
+must not depend on which of the two registered first. An installed extension the
+contact has nothing to do with is never asked, so a hook that forgets to check
+its own references costs nothing here; checking them is still how a hook
+behaves correctly when named by a program's own export.
+
+An extension that genuinely has something to say about every contact opts in
+from its **manifest**, `"adifFieldsScope": "always"`, and is asked whatever the
+contact carries. The field lives in the manifest, not on the hook, so the
+packer can check it without running the bundle: a manifest listing
+`adifFields` with neither a `ref:` type nor the opt-in is refused at packing
+and at publishing, and the app's own build refuses it too. The kernel reads the
+opt-in from the extension's definition, so spread the manifest into
+`defineExtension`, and it logs an error at activation for an extension that
+registers `adifFields` but answers for no reference and does not opt in.
+`mainHandler` and `includeFieldsFrom` are unaffected: a named hook is asked
+whatever the contact carries.
 
 An export can also name a **list** of other hooks it accepts,
 `includeFieldsFrom` — polo's all-or-nothing flag narrowed to what the program
@@ -730,13 +794,13 @@ 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 everyone, and a park and a summit both
-answer `MY_SIG` — the later one is dropped, and the contact's own fields
+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 everyone,
-has no such order: hooks answering `fieldCombinationsForOneQSO` are asked as one
+way ("keep the first one defined"). 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.
 
@@ -1479,6 +1543,14 @@ fires when a lookup is ANSWERED, not while a call is being typed, and the
 guess is inside `args.qso` either way — declaring `'lookup'` is enough to be
 sent the draft, so what it saves over `'qso'` is renders, not the QSO.
 
+Beside the QSON, a draft carries one key a logged record never does:
+`callField`, the call field read at the cursor (`call`, `fullCall`,
+`partial`, `nextCall`, `nextPartial`). `their.call` is the field as typed, which may be a whole
+`//` stack or comma list; `callField.call` is the one call Enter logs. It
+is what [templates.md](templates.md)'s `qso.call` renders from, so a panel
+rendering a template needs nothing more, and moving the cursor within a
+stack or a list wakes a `'qso'` panel even when the QSON is unchanged.
+
 `'lookup'` fires when the panel is shown a callsign that HAS an answer —
 which includes opening a QSO whose stored record already carries one, not
 only a fresh lookup resolving. It does not fire when a lookup starts, fails,

package/docs/templates.md

@@ -48,6 +48,7 @@ is `{{ op.refs | refLabels | sentence }}`.
 | `qso` | when the placement's triggers ask for it | — | ✓ | the draft contact, as far as it is typed |
 | `config` | ✓ | — | — | — |
 | `log` | — | ✓ | ✓ | — |
+| `keyer` | — | — | — | ✓ (and the keyer area's labels) |
 
 A namespace a surface has nothing for is **absent**, not blank — which is
 what makes `{% if qso %}` an honest question. Registered exports get the operation plus the selected file’s `log` values.
@@ -75,13 +76,46 @@ printing `{{ op.startTime }}–{{ op.endTime }}` understates the session by
 that contact's length.
 
 ### `qso` — one contact
-`call`, `their`, `our` (both whole, so `qso.their.guess.name` reaches the
+`call`, `fullCall`, `partial`, `nextCall`, `nextPartial`, `state`, `name`, `their`, `our` (both whole, so `qso.their.guess.name` reaches the
 lookup's answer), `band`, `mode`, `freq`, `rstSent`, `rstRcvd`, `serialSent`,
 `serialRcvd`, `notes`, `date`, `dateCompact`, `time`, `at`, `startAtMillis`,
 `refs` — and two short forms for the sent side, `rst` (= `rstSent`) and
 `serial` (= `serialSent`), since a CW message is what we send and that is
 where these get typed: `{{ qso.call }} {{ qso.rst | cut }} {{ qso.serial | pad: 3 | cut }}`.
 
+In a draft, `call` is ONE call, read at the cursor as the call-info line
+reads it — not the field as typed, which may hold a `//` stack or a comma
+list ([logging-fields.md](https://github.com/ham2k/halo/blob/main/docs/design/logging-fields.md)). On a stack it is
+the call Enter logs, or — when there is none — the partial under the
+cursor, or the nearest one beside it when the cursor sits in an empty
+segment a just-typed `//` opened; in
+a comma list, where Enter logs every call, it is the one the cursor is on.
+`their.call` stays the field as typed. On a stack, two more name the rest of
+it: `nextCall`, the call the Enter after this one would log, and
+`nextPartial`, the last entry left in the field once this one logs —
+usually the call still being copied. With `KN2//KI2D//NK2Y//FR` and the
+cursor at the end, that is `NK2Y`, `KI2D` and `FR`; with the cursor on
+`KI2D`, it is `KI2D`, `NK2Y` and `FR`. Both are empty outside a stack and on
+a logged contact.
+
+`call` may be a partial still being copied, which is right for asking it
+back (`{{ qso.call }}?`) and wrong for answering it. `fullCall` is `call`
+when it reads as a callsign and blank otherwise; `partial` is the reverse.
+Exactly one of them is `call`, so a message can branch on which:
+`{% if qso.fullCall != blank %}…{% elsif qso.partial != blank %}{{ qso.partial }}?{% endif %}`.
+A logged contact's call is always a `fullCall`.
+
+`state` and `name` are what was typed, else what the lookup found
+(`their.state` or `their.guess.state`, likewise for the name) — and `name`
+is only the first word, since `GM {{ qso.name }}` is a greeting, not a
+directory entry. Reach the whole name through `qso.their.name` /
+`qso.their.guess.name`.
+
+Enter Sends Messages renders its thanks AFTER the contact logs, against the
+entry the log left ([logging-fields.md](https://github.com/ham2k/halo/blob/main/docs/design/logging-fields.md) § Enter
+Sends Messages) — so in a thanks keyed by ESM, `qso.call`, `qso.name` and
+the rest name the NEXT station, or nothing, never the one just logged.
+
 `rstSent` is what WE sent — QSON stores each side's report under its own
 `sent`, and these are named for the operator's view of the contact.
 
@@ -100,6 +134,22 @@ Whatever that panel's `form` declared, under the keys it used.
 `handlerShortName`, `format`, `exportType`, `modifier`, `extension`,
 `compact`.
 
+### `keyer` — the CW messages
+`msg1` … `msg8`: the active set's messages, each RENDERED against the same
+context, so one message can include another —
+`TU {{ keyer.msg1 }}` thanks the station and calls CQ again with whatever F1
+holds. A message is expanded only where a template names it, so a branch
+not taken costs nothing — which is what lets ESM's thanks answer the next
+stacked caller or ask a partial back, and send nothing more when there is
+neither:
+`TU {% if qso.fullCall != blank %}{{ keyer.msg5 }} {{ keyer.msg2 }}{% elsif qso.partial != blank %}{{ qso.partial }}?{% endif %}`.
+
+A message that reaches itself — directly, or through others — is an error
+naming the loop (`a message includes itself: F3 → F1 → F3`), and like any
+template error it keys nothing: a message that quietly dropped the part that
+looped would go on the air looking fine. A label may name its own message;
+only a message being SENT is part of the chain.
+
 ## Timestamps
 
 Two forms, and the rule is worth learning once:
@@ -146,6 +196,23 @@ operation at an unlisted park would print as though it had none. Liquid's own
 `array_to_sentence_string` is the near miss for `sentence`: it always writes
 the serial comma (`A, B, & C`).
 
+### Fallbacks
+
+`default` chains, taking the first value that isn't blank — and the values
+above are `""` when there is nothing to say, which counts as blank:
+
+```liquid
+{{ qso.their.state | default: qso.their.guess.state | default: qso.their.county | default: "none" }}
+```
+
+The same as a tag, for when each branch wants more than one value. Compare
+against `blank` rather than testing the bare value: in Liquid only `nil` and
+`false` are false, so `{% if "" %}` takes the branch and prints nothing.
+
+```liquid
+{% if qso.their.state != blank %}{{ qso.their.state }}{% elsif qso.their.county != blank %}{{ qso.their.county }}{% else %}none{% endif %}
+```
+
 `alnum` is app-polo's `compact` helper under a different name: Liquid already
 has a `compact` (it drops nils from an **array**, and `op.refs`/`qso.refs` are
 arrays), and `registerFilter` overwrites without warning, so taking that name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",
@@ -39,6 +39,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./timers": {
+      "ham2k-source": "./src/timers.ts",
+      "default": "./dist/timers.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",