refactor(truapi): iframe MessagePort handshake and SCALE codec additions

Switch the in-iframe client to the host-transferred MessagePort handshake
(truapi-ready / truapi-init) used by the WASM host runtime, and extend the
SCALE primitives (Struct, _void, str, hex helpers) consumed by the generated
codecs. Pulls @noble/hashes in as a hex-codec dependency.

Author: pgherveou

js/packages/truapi/package.json

@@ -79,6 +79,7 @@
     "typescript": "^6.0"
   },
   "dependencies": {
+    "@noble/hashes": "^2.2.0",
     "neverthrow": "^8.2.0",
     "scale-ts": "^1.6.1"
   }

js/packages/truapi/src/sandbox.ts

@@ -11,7 +11,6 @@
  */
 
 import {
-  createIframeProvider,
   createMessagePortProvider,
   type WireProvider,
 } from "./transport.js";
@@ -62,10 +61,7 @@ export function isCorrectEnvironment(): boolean {
 }
 
 /**
- * Origin used as the `targetOrigin` for outbound `postMessage` frames. Frames
- * carry signed payloads and account ids, so this fails closed: when no concrete
- * origin can be pinned it returns `null` (rather than falling back to `"*"`) and
- * provider construction throws.
+ * Origin used as the `targetOrigin` for iframe bootstrap messages.
  */
 function resolveHostOrigin(): string | null {
   if (typeof document !== "undefined" && document.referrer) {
@@ -80,7 +76,8 @@ function resolveHostOrigin(): string | null {
   return null;
 }
 
-const WEBVIEW_PORT_TIMEOUT_MS = 20_000;
+const HOST_PORT_TIMEOUT_MS = 20_000;
+let iframePortPromise: Promise<MessagePort> | null = null;
 
 /**
  * Resolve the host-injected `MessagePort`, polling `window.__HOST_API_PORT__`
@@ -93,7 +90,7 @@ const WEBVIEW_PORT_TIMEOUT_MS = 20_000;
  */
 async function waitForWebviewPort(
   signal?: AbortSignal,
-  timeoutMs = WEBVIEW_PORT_TIMEOUT_MS,
+  timeoutMs = HOST_PORT_TIMEOUT_MS,
 ): Promise<MessagePort> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
@@ -107,18 +104,93 @@ async function waitForWebviewPort(
   );
 }
 
+/**
+ * Resolve the iframe `MessagePort` transferred by `createIframeHost`.
+ */
+function waitForIframePort(
+  signal?: AbortSignal,
+  timeoutMs = HOST_PORT_TIMEOUT_MS,
+): Promise<MessagePort> {
+  const existing = hostWindow()?.__HOST_API_PORT__;
+  if (existing) return Promise.resolve(existing);
+  if (iframePortPromise) return iframePortPromise;
+
+  iframePortPromise = new Promise<MessagePort>((resolve, reject) => {
+    const win = hostWindow();
+    if (!win) {
+      reject(new Error("window is unavailable"));
+      return;
+    }
+
+    const hostOrigin = resolveHostOrigin();
+    let done = false;
+    const cleanup = (): void => {
+      win.removeEventListener("message", onMessage);
+      signal?.removeEventListener("abort", onAbort);
+      clearTimeout(timer);
+    };
+    const finish = (result: MessagePort | Error): void => {
+      if (done) return;
+      done = true;
+      cleanup();
+      if (result instanceof Error) {
+        reject(result);
+      } else {
+        win.__HOST_API_PORT__ = result;
+        resolve(result);
+      }
+    };
+    const onAbort = (): void => {
+      finish(new Error("waitForIframePort aborted"));
+    };
+    const onMessage = (event: MessageEvent): void => {
+      if (event.source !== win.parent) return;
+      if (
+        hostOrigin !== null &&
+        event.origin !== hostOrigin &&
+        event.origin !== "null"
+      ) {
+        return;
+      }
+      if (event.data?.type !== "truapi-init") return;
+      const [port] = event.ports;
+      if (!port) {
+        finish(new Error("truapi-init did not include a MessagePort"));
+        return;
+      }
+      finish(port);
+    };
+    const timer = setTimeout(() => {
+      finish(
+        new Error(`Timed out waiting for iframe MessagePort (${timeoutMs}ms)`),
+      );
+    }, timeoutMs);
+
+    win.addEventListener("message", onMessage);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    win.parent.postMessage({ type: "truapi-ready" }, hostOrigin ?? "*");
+  }).catch((error: unknown) => {
+    iframePortPromise = null;
+    throw error;
+  });
+
+  return iframePortPromise;
+}
+
 /** Build the {@link WireProvider} matching the detected environment (iframe or webview). */
 function createSandboxProvider(): WireProvider {
+  const portController = new AbortController();
   if (isIframe()) {
-    const hostOrigin = resolveHostOrigin();
-    if (!hostOrigin) {
-      throw new Error(
-        "TrUAPI iframe provider could not resolve the host origin from document.referrer / ancestorOrigins.",
-      );
-    }
-    return createIframeProvider({ target: window.parent, hostOrigin });
+    const provider = createMessagePortProvider(
+      waitForIframePort(portController.signal),
+    );
+    const baseDispose = provider.dispose;
+    provider.dispose = () => {
+      portController.abort();
+      baseDispose?.();
+    };
+    return provider;
   }
-  const portController = new AbortController();
   const provider = createMessagePortProvider(
     waitForWebviewPort(portController.signal),
   );
@@ -166,14 +238,21 @@ export function getClientSync(): TrUApiClient | null {
 export function subscribeConnectionStatus(
   callback: (status: ConnectionStatus) => void,
 ): () => void {
-  statusListeners.add(callback);
-  callback(status);
+  let emitted = false;
+  const listener = (next: ConnectionStatus) => {
+    emitted = true;
+    callback(next);
+  };
+  statusListeners.add(listener);
 
   if (status === "disconnected") {
     setStatus(getClientSync() ? "connected" : "disconnected");
   }
+  if (!emitted) {
+    callback(status);
+  }
 
   return () => {
-    statusListeners.delete(callback);
+    statusListeners.delete(listener);
   };
 }

js/packages/truapi/src/scale.ts

@@ -8,17 +8,25 @@
 import {
   Bytes,
   Enum,
+  Struct,
+  _void,
   createCodec,
   createDecoder,
   enhanceCodec,
+  str as scaleStr,
   u8,
   type Codec,
 } from "scale-ts";
+import {
+  bytesToHex as encodeHex,
+  hexToBytes as decodeHex,
+} from "@noble/hashes/utils.js";
 
 export type { Codec };
 export type { ResultPayload } from "scale-ts";
 
 export {
+  Bytes,
   Enum,
   Option,
   Result,
@@ -59,7 +67,9 @@ export const OptionBool: Codec<boolean | undefined> = enhanceCodec(
       case 2:
         return false;
       default:
-        throw new Error(`Unknown OptionBool byte: ${byte}. Expected 0, 1, or 2.`);
+        throw new Error(
+          `Unknown OptionBool byte: ${byte}. Expected 0, 1, or 2.`,
+        );
     }
   },
 );
@@ -79,22 +89,12 @@ export function toHexString(value: string): HexString {
 
 /** Encode a byte array as a lower-case hex string with a `0x` prefix. */
 export function bytesToHex(bytes: Uint8Array): HexString {
-  let hex = "0x";
-  for (let i = 0; i < bytes.length; i++) {
-    hex += bytes[i]!.toString(16).padStart(2, "0");
-  }
-  return hex as HexString;
+  return `0x${encodeHex(bytes)}`;
 }
 
 /** Decode a hex string into a byte array. Tolerates a missing `0x` prefix. */
 export function hexToBytes(hex: string): Uint8Array {
-  const start = hex.startsWith("0x") ? 2 : 0;
-  const length = (hex.length - start) >> 1;
-  const bytes = new Uint8Array(length);
-  for (let i = 0; i < length; i++) {
-    bytes[i] = parseInt(hex.substring(start + i * 2, start + i * 2 + 2), 16);
-  }
-  return bytes;
+  return decodeHex(hex.startsWith("0x") ? hex.slice(2) : hex);
 }
 
 /**
@@ -123,6 +123,51 @@ export function TaggedUnion<O extends TaggedUnionCodecs>(
   return Enum(inner) as unknown as Codec<TaggedUnionValue<O>>;
 }
 
+/**
+ * Wire codec for Rust `CallError<D>`, projected to the public domain error `D`.
+ *
+ * Generated TypeScript APIs expose only the domain error union in
+ * `ResultAsync<Ok, D>`. The Rust host still wraps that value in
+ * `CallError::Domain` on the wire so framework errors can share the response
+ * channel. Encoding always emits `Domain`; decoding returns the inner domain
+ * value and throws for framework-level failures that have no public `D` shape.
+ */
+export function CallError<D>(domain: Codec<D>): Codec<D> {
+  type WireCallError =
+    | { tag: "Domain"; value: D }
+    | { tag: "Denied"; value?: undefined }
+    | { tag: "Unsupported"; value?: undefined }
+    | { tag: "MalformedFrame"; value: { reason: string } }
+    | { tag: "HostFailure"; value: { reason: string } };
+
+  const wire = Enum({
+    Domain: domain,
+    Denied: _void,
+    Unsupported: _void,
+    MalformedFrame: Struct({ reason: scaleStr }),
+    HostFailure: Struct({ reason: scaleStr }),
+  }) as unknown as Codec<WireCallError>;
+
+  return enhanceCodec(
+    wire,
+    (value: D): WireCallError => ({ tag: "Domain", value }),
+    (value: WireCallError): D => {
+      switch (value.tag) {
+        case "Domain":
+          return value.value;
+        case "Denied":
+          throw new Error("Host denied the request");
+        case "Unsupported":
+          throw new Error("Host does not support this request");
+        case "MalformedFrame":
+          throw new Error(`Malformed request frame: ${value.value.reason}`);
+        case "HostFailure":
+          throw new Error(`Host failure: ${value.value.reason}`);
+      }
+    },
+  );
+}
+
 type TaggedUnionCodecs = {
   [Sym: symbol]: never;
   [Num: number]: never;

js/packages/truapi/src/transport.ts

@@ -279,6 +279,10 @@ export interface WireProvider {
 
   /**
    * Register a callback for provider-level close or failure events.
+   *
+   * Providers keep a terminal close reason. The callback fires at most once
+   * for an active subscription, and fires immediately when registered after
+   * the provider has already closed.
    **/
   subscribeClose?(callback: (error: Error) => void): () => void;
 

package-lock.json

@@ -7,6 +7,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 An interactive explorer for the TrUAPI, the Host API surface exposed to products running inside the Polkadot Desktop Browser webview. The app must be opened from within a Host environment. It talks to the host over iframe `postMessage` frames or the native webview `window.__HOST_API_PORT__` MessagePort.
 
 To develop locally, run `yarn dev` and open the app via `https://dot.li/localhost:3000` inside the Desktop Host.
+For host-backed diagnosis/e2e runs, signer-bot settings may live in the
+repo-root `.env`; if they are not present in the current worktree environment,
+load or copy them from that file before treating signer-bot as unavailable.
 
 ## Commands
 

playground/CLAUDE.md

@@ -23,6 +23,7 @@ import {
   runDiagnosis,
   runSingleTest,
 } from "@/src/lib/auto-test";
+import { installE2EHooks } from "@/src/lib/e2e-hooks";
 import packageJson from "../../package.json";
 
 const VERSION_LABEL = `v${packageJson.version}`;
@@ -188,6 +189,7 @@ export default function PlaygroundPage() {
 
   useEffect(() => {
     try {
+      installE2EHooks();
       return subscribeConnectionStatus(setStatus);
     } catch {
       setStatus("disconnected");