@ham2k/extension-sdk 0.5.6 → 0.6.0

package/AGENTS.md

@@ -34,24 +34,24 @@ build/             generated: index.js + manifest.json
 ## The smallest whole extension
 
 ```ts
-import { defineExtension } from '@ham2k/extension-sdk'
-import type { PanelHook } from '@ham2k/extension-sdk'
+import { defineExtension } from "@ham2k/extension-sdk"
+import type { PanelHook } from "@ham2k/extension-sdk"
 
-import manifest from '../manifest.json'
+import manifest from "../manifest.json"
 
 const HelloPanel: PanelHook = {
   async getPanels() {
-    return [{ key: 'hello', title: 'Hello World', icon: 'hand-wave-outline' }]
+    return [{ key: "hello", title: "Hello World", icon: "hand-wave-outline" }]
   },
   async render() {
-    return { kind: 'markdown', content: '# Hello, World!' }
+    return { kind: "markdown", content: "# Hello, World!" }
   },
 }
 
 defineExtension({
   ...manifest,
   onActivation({ registerHook }) {
-    registerHook('panel', { key: manifest.key, hook: HelloPanel })
+    registerHook("panel", { key: manifest.key, hook: HelloPanel })
   },
 })
 ```
@@ -100,9 +100,10 @@ No Node, no DOM, no `fetch`, no `window`, no filesystem. One ES2020 engine
 evaluating one script. Reach the outside world through `host`:
 
 ```ts
-import { host } from '@ham2k/extension-sdk'
+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
 await host.kvGet('key')        // storage, namespaced to your extension
 await host.kvSet('key', value)
 await host.showForm(form)      // ask the user something
@@ -114,7 +115,7 @@ host.log('…')                  // the app's console
 
 ## Traps worth knowing before you write anything
 
-- **A panel returns content, not widgets.** `{ kind: 'markdown', content }` and
+- **A panel returns content, not widgets.** `{ kind: "markdown", content }` and
   its siblings. There is no way to reach the app's UI toolkit, by design.
 - **`host.fetch` only reaches domains your manifest's `domains` lists**, over
   https. An undeclared host is refused at the call, not at build.
@@ -122,7 +123,7 @@ host.log('…')                  // the app's console
   carries `@ham2k/lib-*`, `i18next` and `liquidjs`; naming one in
   `sharedDependencies` rewrites your imports into lookups on the app's single
   copy, which is worth roughly thirty times the bundle size. Don't install them.
-  `inline: ['liquidjs']` in your build ships your own copy, for when you need a
+  `inline: ["liquidjs"]` in your build ships your own copy, for when you need a
   version the app does not carry. A scaffolded manifest already declares the
   eight this SDK's own modules reach — importing anything from it pulls them
   in — so deleting one from the manifest breaks a build that was working.

package/README.md

@@ -9,24 +9,24 @@ npm install --save-dev @ham2k/extension-tools esbuild
 ```
 
 ```ts
-import { defineExtension } from '@ham2k/extension-sdk'
-import type { PanelHook } from '@ham2k/extension-sdk'
+import { defineExtension } from "@ham2k/extension-sdk"
+import type { PanelHook } from "@ham2k/extension-sdk"
 
-import manifest from '../manifest.json'
+import manifest from "../manifest.json"
 
 const HelloPanel: PanelHook = {
   async getPanels() {
-    return [{ key: 'hello', title: 'Hello World', icon: 'hand-wave-outline' }]
+    return [{ key: "hello", title: "Hello World", icon: "hand-wave-outline" }]
   },
   async render() {
-    return { kind: 'markdown', content: '# Hello, World!' }
+    return { kind: "markdown", content: "# Hello, World!" }
   },
 }
 
 defineExtension({
   ...manifest,
   onActivation({ registerHook }) {
-    registerHook('panel', { key: manifest.key, hook: HelloPanel })
+    registerHook("panel", { key: manifest.key, hook: HelloPanel })
   },
 })
 ```

package/dist/activityExports.js

@@ -23,14 +23,16 @@ function activityExportHook(rules) {
   const prefix = `${rules.key}-adif`;
   return {
     async getExportTypes() {
-      return [{
-        ...exportTypeDefinition(rules.activationType, "adif", rules.label),
-        templateCategory: "reference",
-        templateSample: rules.templateSample ?? {
-          log: { ref: "REF-1234", refName: "Example Reference" },
-          operation: { refs: [{ type: rules.activationType, ref: "REF-1234" }] }
+      return [
+        {
+          ...exportTypeDefinition(rules.activationType, "adif", rules.label),
+          templateCategory: "reference",
+          templateSample: rules.templateSample ?? {
+            log: { ref: "REF-1234", refName: "Example Reference" },
+            operation: { refs: [{ type: rules.activationType, ref: "REF-1234" }] }
+          }
         }
-      }];
+      ];
     },
     async suggestExportOptions({ operation, qsos, compactFilenames }, ctx) {
       const refs = refsOfType(operation, rules.activationType);
@@ -113,21 +115,23 @@ function huntingExportHook(rules) {
       if (refsOfType(operation, rules.activationType).length > 0) return [];
       if (huntedQsos(qsos ?? []).length === 0) return [];
       const t = tFor(ctx);
-      return [{
-        exportType,
-        qsoCount: huntedQsos(qsos ?? []).length,
-        templateData: { activity: rules.label },
-        format: "adif",
-        label: t("adifForHunter", { program: rules.label }),
-        filename: filenameForHunt(operation, qsos ?? [], rules.label, compactFilenames),
-        icon: rules.icon,
-        color: rules.color,
-        selectedByDefault: true
-        // No `refType`: hunted refs live on QSOs, not on operation segments,
-        // so this isn't the segment-scoped slice `activityExportHook` uses —
-        // it spans the whole log. (See `HuntingExportRules.color` for why the
-        // accent has to be threaded explicitly instead.)
-      }];
+      return [
+        {
+          exportType,
+          qsoCount: huntedQsos(qsos ?? []).length,
+          templateData: { activity: rules.label },
+          format: "adif",
+          label: t("adifForHunter", { program: rules.label }),
+          filename: filenameForHunt(operation, qsos ?? [], rules.label, compactFilenames),
+          icon: rules.icon,
+          color: rules.color,
+          selectedByDefault: true
+          // No `refType`: hunted refs live on QSOs, not on operation segments,
+          // so this isn't the segment-scoped slice `activityExportHook` uses —
+          // it spans the whole log. (See `HuntingExportRules.color` for why the
+          // accent has to be threaded explicitly instead.)
+        }
+      ];
     },
     async generateExport(args, ctx) {
       const requested = String(args.exportType ?? "");
@@ -163,7 +167,18 @@ function huntingExportHook(rules) {
     }
   };
 }
-async function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }) {
+async function adifForExport({
+  operation,
+  qsos,
+  segments,
+  includePrivateData,
+  includeLookupData,
+  exportSettings,
+  exportData,
+  exportTitle,
+  mainHandler,
+  includeFieldsFrom
+}) {
   const { hooks } = await import("@ham2k/extension-sdk");
   const entries = await hooks.invokeOne("export", "adif", "generateExport", {
     operation,

package/dist/activityScoring.js

@@ -62,9 +62,7 @@ function activityScorer(rules) {
       if (candidates.length === 0) notice ?? (notice = "mode");
     }
     if (unique.has("ref")) {
-      candidates = candidates.filter(
-        (c) => c.refs.length === 0 && now.refs.length === 0 || c.refs.some((r) => now.refs.includes(r))
-      );
+      candidates = candidates.filter((c) => c.refs.length === 0 && now.refs.length === 0 || c.refs.some((r) => now.refs.includes(r)));
       if (candidates.length === 0 && now.refs.length > 0) notice ?? (notice = "ref");
     }
     if (notice) return notice;
@@ -189,14 +187,10 @@ function summarizeActivation(activatedRefs, qsos, duplicates, huntedQsos, scope,
   const detail = refKeys.map(
     (key) => activatedRefs[key] >= qsosToActivate ? `\u2705 **${key}: ${fmtInteger(activatedRefs[key])}**` : `\u274C ${key}: ${fmtInteger(activatedRefs[key])}/${fmtInteger(qsosToActivate)}`
   );
-  const parts = [
-    qsos === 1 ? t("activationQsoOne") : t("activationQsoMany", { formatted: fmtInteger(qsos) })
-  ];
+  const parts = [qsos === 1 ? t("activationQsoOne") : t("activationQsoMany", { formatted: fmtInteger(qsos) })];
   if (huntedQsos > 0) {
     const p2p = resolveRuleText(rules.p2pLabel, ctx, t("ref2ref"));
-    parts.push(
-      huntedQsos === 1 ? t("p2pQsoOne", { label: p2p }) : t("p2pQsoMany", { label: p2p, formatted: fmtInteger(huntedQsos) })
-    );
+    parts.push(huntedQsos === 1 ? t("p2pQsoOne", { label: p2p }) : t("p2pQsoMany", { label: p2p, formatted: fmtInteger(huntedQsos) }));
   }
   return {
     key: "activation",

package/dist/base64.js

@@ -0,0 +1,38 @@
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const VALUES = new Map([...ALPHABET].map((c, i) => [c, i]));
+function bytesToBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    const n = a << 16 | b << 8 | c;
+    out += ALPHABET[n >> 18 & 63] + ALPHABET[n >> 12 & 63];
+    out += i + 1 < bytes.length ? ALPHABET[n >> 6 & 63] : "=";
+    out += i + 2 < bytes.length ? ALPHABET[n & 63] : "=";
+  }
+  return out;
+}
+function base64ToBytes(text) {
+  if (text.length % 4 !== 0) throw new Error("invalid base64");
+  const padding = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  const bytes = new Uint8Array(text.length / 4 * 3 - padding);
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    let n = 0;
+    for (let j = 0; j < 4; j++) {
+      const ch = text[i + j];
+      const value = ch === "=" && i + 4 === text.length && j >= 4 - padding ? 0 : VALUES.get(ch);
+      if (value === void 0) throw new Error("invalid base64");
+      n = n << 6 | value;
+    }
+    if (o < bytes.length) bytes[o++] = n >> 16 & 255;
+    if (o < bytes.length) bytes[o++] = n >> 8 & 255;
+    if (o < bytes.length) bytes[o++] = n & 255;
+  }
+  return bytes;
+}
+export {
+  base64ToBytes,
+  bytesToBase64
+};

package/dist/copyOnWrite.js

@@ -0,0 +1,71 @@
+function copyOnWrite(base) {
+  return isContainer(base) ? wrap(base) : base;
+}
+function isContainer(value) {
+  return typeof value === "object" && value !== null;
+}
+function wrap(target) {
+  const own = /* @__PURE__ */ new Map();
+  const deleted = /* @__PURE__ */ new Set();
+  return new Proxy(target, {
+    get(t, key) {
+      if (own.has(key)) return own.get(key);
+      if (deleted.has(key)) return void 0;
+      const value = Reflect.get(t, key);
+      if (isContainer(value) && Object.prototype.hasOwnProperty.call(t, key)) {
+        const view = wrap(value);
+        own.set(key, view);
+        return view;
+      }
+      return value;
+    },
+    set(_t, key, value) {
+      own.set(key, value);
+      deleted.delete(key);
+      return true;
+    },
+    has(t, key) {
+      if (deleted.has(key)) return false;
+      return own.has(key) || key in t;
+    },
+    deleteProperty(t, key) {
+      const descriptor = Reflect.getOwnPropertyDescriptor(t, key);
+      if (descriptor && !descriptor.configurable) return false;
+      own.delete(key);
+      if (descriptor) deleted.add(key);
+      return true;
+    },
+    ownKeys(t) {
+      const keys = Reflect.ownKeys(t).filter((key) => !deleted.has(key));
+      for (const key of own.keys()) {
+        if (!keys.includes(key)) keys.push(key);
+      }
+      return keys;
+    },
+    getOwnPropertyDescriptor(t, key) {
+      if (deleted.has(key)) return void 0;
+      const descriptor = Reflect.getOwnPropertyDescriptor(t, key);
+      if (!own.has(key)) return descriptor;
+      return descriptor ? { ...descriptor, value: own.get(key) } : { value: own.get(key), writable: true, enumerable: true, configurable: true };
+    },
+    // The other ways to write. Without these traps `Object.defineProperty`
+    // and `Object.freeze` fall through to the base — the held checkpoint —
+    // and one such call would enter a candidate into every later verdict, or
+    // lock the sheet for the rest of the session.
+    defineProperty(_t, key, descriptor) {
+      if ("get" in descriptor || "set" in descriptor) return false;
+      own.set(key, descriptor.value);
+      deleted.delete(key);
+      return true;
+    },
+    preventExtensions() {
+      return false;
+    },
+    setPrototypeOf() {
+      return false;
+    }
+  });
+}
+export {
+  copyOnWrite
+};

package/dist/exportNames.js

@@ -26,22 +26,23 @@ function exportFilename(parts) {
   const millis = parts.startAtMillis && parts.startAtMillis > 0 ? parts.startAtMillis : Date.now();
   const extension = parts.extension.replace(/^\./, "");
   const shape = `${parts.compact ? "Compact" : "Normal"}${parts.ref ? "Ref" : parts.activity ? "Activity" : ""}Name`;
-  const modifier = [
-    (parts.modifier ?? "").trim(),
-    isTestOperation(parts.stationCall) ? "Testing" : ""
-  ].filter((part) => part !== "").join(" ");
+  const modifier = [(parts.modifier ?? "").trim(), isTestOperation(parts.stationCall) ? "Testing" : ""].filter((part) => part !== "").join(" ");
   const stem = oneLine(
-    renderTemplate(NAME_TEMPLATES[shape], {
-      op: dateValues(millis),
-      log: logValues({
-        station: String(parts.stationCall ?? "").trim(),
-        ref: parts.ref,
-        activity: parts.activity,
-        modifier,
-        extension,
-        compact: parts.compact
-      })
-    }, shape)
+    renderTemplate(
+      NAME_TEMPLATES[shape],
+      {
+        op: dateValues(millis),
+        log: logValues({
+          station: String(parts.stationCall ?? "").trim(),
+          ref: parts.ref,
+          activity: parts.activity,
+          modifier,
+          extension,
+          compact: parts.compact
+        })
+      },
+      shape
+    )
   );
   return `${sanitize(stem) || "export"}.${extension}`;
 }

package/dist/exportSettings.js

@@ -118,7 +118,17 @@ function prepareExportOption(option, operation, qsos, compact) {
   const rendered = oneLine(renderTemplate(template ?? "", context, "Export filename"));
   const stem = rendered.replace(/[/\\:*?"<>|\x00-\x1f]+/g, "-").replace(/[. ]+$/g, "").trim() || "export";
   const filename = stem.toLowerCase().endsWith(`.${extension}`) ? stem : `${stem}.${extension}`;
-  const titleContext = settings.includePrivateData === false ? { ...context, op: { ...context.op, title: "", userTitle: "", userNotes: "", grid: String(context.op.grid ?? "").slice(0, 6) }, log: { ...context.log, modifier: "" } } : context;
+  const titleContext = settings.includePrivateData === false ? {
+    ...context,
+    op: {
+      ...context.op,
+      title: "",
+      userTitle: "",
+      userNotes: "",
+      grid: String(context.op.grid ?? "").slice(0, 6)
+    },
+    log: { ...context.log, modifier: "" }
+  } : context;
   const title = oneLine(renderTemplate(settings.titleTemplate ?? "", titleContext, "Export title"));
   return { ...option, filename, exportTitle: title, exportData: settings.includePrivateData === false ? { ...data, modifier: "" } : data };
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.6
+// @ham2k/extension-sdk 0.6.0
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -394,6 +394,7 @@ export interface LoggingControlDescriptor {
 	key: string;
 	label: string;
 	shortLabel?: string;
+	skipFocus?: boolean;
 	icon?: string;
 	color?: string;
 	order?: number;
@@ -634,12 +635,15 @@ export interface ScoreQsosRequest {
 	ref?: Record<string, JSONValue>;
 	resumeFrom?: JSONValue;
 	resumeDay?: number;
+	resumeKey?: string;
+	checkpointKey?: string;
 }
 export interface ScoreQsosResult {
 	qsoScores: Record<string, QsoScoreVerdict>;
 	daySections: DayScoreSummary[];
 	operationSummary: Record<string, ScoreTally>;
 	scoresheet?: JSONValue;
+	checkpointHeld?: true;
 	scoresheetDay?: number;
 }
 export interface ScoreQsoRequest {
@@ -651,11 +655,13 @@ export interface ScoreQsoRequest {
 	resumeFrom?: JSONValue;
 	resumeDay?: number;
 	qsos?: Record<string, JSONValue>[];
+	resumeKey?: string;
 }
 export interface QsoScoreNotices {
 	notices: string[];
 	alerts: string[];
 	dupe?: boolean;
+	checkpointHeld?: true;
 }
 export interface ScoreCandidatesRequest {
 	operation: Record<string, JSONValue>;
@@ -668,8 +674,11 @@ export interface ScoreCandidatesRequest {
 	resumeFrom?: JSONValue;
 	resumeDay?: number;
 	qsos?: Record<string, JSONValue>[];
+	resumeKey?: string;
 }
-export type ScoreCandidatesResult = Record<string, QsoScoreNotices>;
+export type ScoreCandidatesResult = Record<string, QsoScoreNotices> & {
+	$checkpointHeld?: true;
+};
 export interface ScoringHook {
 	scoreQsos(args: ScoreQsosRequest, ctx: HookContext): Promise<ScoreQsosResult>;
 	scoreQso?(args: ScoreQsoRequest, ctx: HookContext): Promise<QsoScoreNotices>;
@@ -953,6 +962,7 @@ export interface ExtensionManifest {
 	enabledByDefault?: boolean;
 	hooks?: string[];
 	domains?: string[];
+	webSockets?: string[];
 	allowUserAgentOverride?: boolean;
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
@@ -997,6 +1007,29 @@ export interface FetchResponse {
 	status: number;
 	body: string;
 }
+export interface WebSocketOptions {
+	protocols?: string[];
+}
+export interface WebSocketCloseEvent {
+	code: number;
+	reason: string;
+	wasClean: boolean;
+}
+export interface ExtensionWebSocket {
+	readonly url: string;
+	readonly readyState: 0 | 1 | 2 | 3;
+	readonly protocol: string;
+	onopen: (() => void) | null;
+	onmessage: ((event: {
+		data: string | ArrayBuffer;
+	}) => void) | null;
+	onerror: ((event: {
+		message: string;
+	}) => void) | null;
+	onclose: ((event: WebSocketCloseEvent) => void) | null;
+	send(data: string | ArrayBuffer | ArrayBufferView): void;
+	close(code?: number, reason?: string): void;
+}
 export interface DeviceLocation {
 	latitude: number;
 	longitude: number;
@@ -1461,6 +1494,8 @@ export declare function isUnexpectedSideband(mode: string | undefined | null, {
 	freqKHz?: number;
 	band?: string;
 }): boolean;
+export declare const RESUME_MISSING = "resume-missing";
+export declare const CHECKPOINT_HELD_KEY = "$checkpointHeld";
 export interface ContestScorerOptions {
 	scope?: ScoringScope;
 }
@@ -1527,7 +1562,7 @@ export declare function huntingExportHook(rules: HuntingExportRules): {
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
-export declare function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom }: {
+export declare function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom, }: {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
@@ -1693,6 +1728,7 @@ export declare const host: {
 	}): Promise<PanelRadioTuneResult>;
 	tuneRadio(args: PanelRadioTune): Promise<PanelRadioTuneResult>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
+	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;
 	kvGet(key: string): Promise<JSONValue | null>;
 	getLocation(): Promise<DeviceLocation | null>;
 	getVersionInfo(): Promise<VersionInfo>;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { base64ToBytes, bytesToBase64 } from "./base64.js";
 export * from "./types.js";
 export * from "./svgScene.js";
 export * from "./i18n.js";
@@ -38,6 +39,85 @@ function defineExtension(def) {
     }
   });
 }
+const MAX_FRAME_SIZE = 1024 * 1024;
+function utf8Length(text) {
+  let length = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    length += cp < 128 ? 1 : cp < 2048 ? 2 : cp < 65536 ? 3 : 4;
+  }
+  return length;
+}
+function openWebSocket(call, url, options) {
+  let readyState = 0;
+  let protocol = "";
+  const failed = (what) => (e) => kernel().log(`webSocket ${what} on ${url} failed: ${e instanceof Error ? e.message : String(e)}`);
+  const socket = {
+    url,
+    get readyState() {
+      return readyState;
+    },
+    get protocol() {
+      return protocol;
+    },
+    onopen: null,
+    onmessage: null,
+    onerror: null,
+    onclose: null,
+    send(data) {
+      if (readyState !== 1) throw new Error("WebSocket is not open");
+      let frame;
+      if (typeof data === "string") {
+        if (data.length > MAX_FRAME_SIZE) throw new Error("WebSocket message too big");
+        frame = { data };
+      } else {
+        const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        if (bytes.length > MAX_FRAME_SIZE) throw new Error("WebSocket message too big");
+        frame = { binary: bytesToBase64(bytes) };
+      }
+      call("webSocketSend", { socketId, ...frame }).catch(failed("send"));
+    },
+    close(code, reason) {
+      if (code !== void 0 && (!Number.isInteger(code) || code !== 1e3 && (code < 3e3 || code > 4999))) {
+        throw new Error("close code must be 1000 or 3000-4999");
+      }
+      if (reason !== void 0 && (typeof reason !== "string" || utf8Length(reason) > 123)) {
+        throw new Error("close reason must be a string of at most 123 UTF-8 bytes");
+      }
+      if (readyState >= 2) return;
+      const before = readyState;
+      readyState = 2;
+      call("webSocketClose", { socketId, ...code !== void 0 ? { code } : {}, ...reason !== void 0 ? { reason } : {} }).catch((e) => {
+        if (readyState === 2) readyState = before;
+        failed("close")(e);
+      });
+    }
+  };
+  if (typeof kernel().registerSocket !== "function") throw new Error("host.webSocket needs a newer version of HaLo");
+  const socketId = kernel().registerSocket((event) => {
+    switch (event.type) {
+      case "open":
+        if (readyState !== 0) return;
+        readyState = 1;
+        protocol = String(event.protocol ?? "");
+        return socket.onopen?.();
+      case "message": {
+        const data = typeof event.binary === "string" ? base64ToBytes(event.binary).buffer : String(event.data);
+        return socket.onmessage?.({ data });
+      }
+      case "error":
+        return socket.onerror?.({ message: String(event.message ?? "") });
+      case "close":
+        readyState = 3;
+        return socket.onclose?.({ code: Number(event.code), reason: String(event.reason ?? ""), wasClean: event.wasClean === true });
+    }
+  });
+  call("webSocketOpen", { socketId, url, ...options?.protocols ? { protocols: options.protocols } : {} }).catch((e) => {
+    kernel().socketEvent(socketId, JSON.stringify({ type: "error", message: e instanceof Error ? e.message : String(e) }));
+    kernel().socketEvent(socketId, JSON.stringify({ type: "close", code: 1006, reason: "", wasClean: false }));
+  });
+  return socket;
+}
 const hooks = {
   /// EVERY hook in the category — including the CALLER's own. A hook that
   /// delegates within its own category therefore re-enters itself; use
@@ -76,6 +156,11 @@ const host = {
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },
+  /// A WebSocket to a host the manifest's `webSockets` lists — see
+  /// `ExtensionWebSocket`. Returns at once, connecting, as a browser's does.
+  webSocket(url, options) {
+    return openWebSocket(hostCallFn(), url, options);
+  },
   async kvGet(key) {
     return await hostCallFn()("kvGet", { ns: currentExtensionKey, key });
   },