WebclientWire

The WebclientWire class is the postMessage transport between a dashlet iframe and the webclient host. It is the internal plumbing the facade methods reuse; it is exported so consumers and tests can drive it directly.

1. Constructor

new WebclientWire(options: WebclientWireOptions): WebclientWire;

Option Meaning

Option	Meaning
`window`	The window the wire listens on (structural `WindowLike`).
`expectedOrigin`	Configured origin (never `"*"`). A usable value puts the wire in STRICT mode — anchored at construction. Absent/empty puts it in LEARNING mode: the wire starts unanchored, the first accepted message — which must be an `onInit` — anchors the received origin string as-is, and the anchor is immutable from then on. A configured value must be a file-origin-group member or a valid absolute URL; anything else is rejected with a `TypeError` at construction (see the origin guide).
`timeoutMs`	Response timeout in ms for `call()`.
`onEvent`	Receives origin-validated host events: `HostEvent` = `{ type: 'onInit' \| 'onUpdate', data }`.
`listen`	When `true` (default), `start()` attaches the wire’s own `message` listener. Set `false` when a shared host listener routes events to `dispatch` instead.

window

The window the wire listens on (structural WindowLike).

expectedOrigin

Configured origin (never "*"). A usable value puts the wire in STRICT mode — anchored at construction. Absent/empty puts it in LEARNING mode: the wire starts unanchored, the first accepted message — which must be an onInit — anchors the received origin string as-is, and the anchor is immutable from then on. A configured value must be a file-origin-group member or a valid absolute URL; anything else is rejected with a TypeError at construction (see the origin guide).

timeoutMs

Response timeout in ms for call().

onEvent

Receives origin-validated host events: HostEvent = { type: 'onInit' | 'onUpdate', data }.

listen

When true (default), start() attaches the wire’s own message listener. Set false when a shared host listener routes events to dispatch instead.

2. Methods

start(): void;                 // attach the listener (if listen is true)
dispatch(event: MessageEventLike): void;  // route an event in shared-listener mode
destroy(): void;               // detach
get pendingCount(): number;    // correlated calls awaiting a reply
call<T = unknown>(method: string, params: unknown = [], msgId?: string): Promise<T>;

call posts [method, params, { msgId }] on the wire and correlates the reply by msgId. The id is unguessable: crypto.getRandomValues produces dmsg- + 32 hex characters, with a sequential dashlet-msg-N fallback where the API is absent. If the bound elapses without a reply, the pending call rejects with a TimeoutError (a late reply is ignored); a host { error } payload rejects with the host error (see error model).

3. Origin validation and outbound posts

Inbound: every message is validated against the configured origin (strict) or the learned anchor (learning, after the first onInit); non-matching messages are dropped. Origin comparison is originMatches — the file-origin group (including the desktop-app "null" serialization) matches bidirectionally.

Outbound: posts target the last accepted origin, with one exception — a host whose origin is a file-origin-group member is addressed as "*", the only target token guaranteed delivery to it. With no trusted origin at all, calls never post (and reject on the bounded timeout instead).