@awarevue/agent-sdk-browser 2.0.91

package/README.md

@@ -0,0 +1,203 @@
+# @awarevue/agent-sdk-browser
+
+Browser transport adapters for the [Aware Agent Protocol](../agent-sdk-typescript/README.md). Enables agents to run inside `<iframe>` elements and communicate with the host page over the [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) — a drop-in replacement for the WebSocket transport with 100% protocol parity.
+
+## Overview
+
+```
+  Host page                                       iframe (agent)
+  ─────────────────────────────────────────       ─────────────────────────────
+  PostMessageHostDuplexTransport(iframeEl)  ←──→  PostMessageIframeDuplexTransport()
+         │                                                   │
+  InMemoryHub.addPeer(id, transport)              WsJsonEncoder
+         │                                                   │
+  AgentServer                                     LoggingDuplexTransport
+                                                             │
+                                                        AgentProtocol
+                                                             │
+                                                         AgentApp
+```
+
+Both transports implement `DuplexTransport<string, string>` — the exact same interface as `WsDuplexTransport` / `WsServerDuplexTransport` from the core SDK. **Nothing in the protocol stack above the transport layer changes.** Switching between WebSocket and postMessage is a single constructor swap.
+
+## Installation
+
+```bash
+npm install @awarevue/agent-sdk-browser
+# peer dependencies
+npm install @awarevue/agent-sdk @awarevue/api-types rxjs
+```
+
+## Example 1 — Agent inside an iframe
+
+`createBrowserAgentApp` mirrors `createAgentApp` from the core SDK but defaults the transport to `PostMessageIframeDuplexTransport`.
+
+```ts
+// agent/index.ts  — bundled and loaded inside an <iframe>
+import { createBrowserAgentApp } from '@awarevue/agent-sdk-browser';
+import { Agent, RunContext } from '@awarevue/agent-sdk';
+
+const myAgent: Agent = {
+  async start(provider: string, config: unknown, ctx: RunContext) {
+    ctx.pushState('door-1', { connected: true, locked: true });
+  },
+
+  async stop(provider: string) {},
+
+  async runCommand(provider, device, command) {
+    if (command.command === 'door.unlock') {
+      return { success: true };
+    }
+    return { success: false, error: 'Unknown command' };
+  },
+
+  async query() {
+    return [];
+  },
+};
+
+const app = createBrowserAgentApp(myAgent, {
+  agentId: 'my-agent',
+  providers: {
+    'my-provider': {
+      title: 'My Provider',
+      configSchema: {},
+      configDefault: {},
+    },
+  },
+});
+
+app.start();
+```
+
+## Example 2 — Host page managing multiple iframe agents
+
+Use `PostMessageHostDuplexTransport` (one per iframe), wire each into an `InMemoryHub`, then attach an `AgentServer` — the same server-side setup used with WebSocket agents.
+
+```ts
+// host/index.ts  — runs in the parent page
+import {
+  AgentServer,
+  InMemoryHub,
+  WsJsonEncoder,
+} from '@awarevue/agent-sdk';
+import { PostMessageHostDuplexTransport } from '@awarevue/agent-sdk-browser';
+import { FromAgent, FromServer, Message } from '@awarevue/api-types';
+
+type AgentMsg  = Message<FromAgent>;
+type ServerMsg = Message<FromServer>;
+
+const hub = new InMemoryHub<AgentMsg, ServerMsg, string>();
+const server = new AgentServer(hub);
+server.init();
+
+// Called once per iframe, after the iframe's src has loaded
+function registerIframeAgent(iframeEl: HTMLIFrameElement, peerId: string) {
+  const rawTransport = new PostMessageHostDuplexTransport(iframeEl);
+
+  // Wrap in the same JSON encoding layer used on the WebSocket path
+  const transport = new WsJsonEncoder(rawTransport) as unknown as import('@awarevue/agent-sdk').DuplexTransport<AgentMsg, ServerMsg>;
+
+  hub.addPeer(peerId, transport as any);
+}
+
+// Wire up iframes declared in your HTML
+const iframe1 = document.getElementById('agent-iframe-1') as HTMLIFrameElement;
+iframe1.addEventListener('load', () => registerIframeAgent(iframe1, 'agent-1'));
+iframe1.src = '/agents/my-agent/index.html';
+```
+
+> **Note:** `WsJsonEncoder` is applied on the host side too, because `PostMessageHostDuplexTransport` is a `DuplexTransport<string, string>` (raw strings). This matches exactly how `WsServerDuplexTransport` is used in server-side code.
+
+## Example 3 — Testing an iframe agent over WebSocket (transport swap)
+
+Because `createBrowserAgentApp` accepts a `transport` override, you can replace the postMessage stack with the standard WebSocket stack for out-of-browser integration testing — zero changes to the agent code:
+
+```ts
+import { createBrowserAgentApp } from '@awarevue/agent-sdk-browser';
+import {
+  WsDuplexTransport,
+  WsJsonEncoder,
+  LoggingDuplexTransport,
+} from '@awarevue/agent-sdk';
+
+// The exact same agent code runs against a real Aware server over WebSocket
+const app = createBrowserAgentApp(myAgent, {
+  agentId: 'my-agent',
+  providers: { 'my-provider': { title: 'My Provider', configSchema: {}, configDefault: {} } },
+  transport: new LoggingDuplexTransport(
+    new WsJsonEncoder(
+      new WsDuplexTransport({
+        url: 'wss://hub.example.com/agent',
+        headers: { Authorization: 'APIKey <key>' },
+      }),
+    ) as any,
+  ),
+});
+
+app.start();
+```
+
+## API reference
+
+### `PostMessageIframeDuplexTransport`
+
+Agent-side transport. Listens for messages on `window` and sends to `window.parent`.
+
+```ts
+new PostMessageIframeDuplexTransport(opts?: {
+  targetOrigin?: string; // default '*'
+})
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `connected$` | `Observable<boolean>` | Emits `true` immediately, then `false` on `close()` |
+| `messages$` | `Observable<string>` | Inbound string messages from the host |
+| `send(msg)` | `void` | Sends a string to `window.parent` |
+| `close()` | `void` | Tears down all subscriptions; idempotent |
+
+### `PostMessageHostDuplexTransport`
+
+Host-side transport. Wraps a single `HTMLIFrameElement` and filters `window` message events by `event.source`.
+
+```ts
+new PostMessageHostDuplexTransport(
+  iframe: HTMLIFrameElement,
+  targetOrigin?: string, // default '*'
+)
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `connected$` | `Observable<boolean>` | Emits `true` immediately, then `false` on `close()` |
+| `messages$` | `Observable<string>` | Inbound string messages from the specific iframe |
+| `send(msg)` | `void` | Sends a string to `iframe.contentWindow` |
+| `close()` | `void` | Tears down all subscriptions; idempotent |
+
+### `createBrowserAgentApp`
+
+Convenience factory. Mirrors `createAgentApp` from the core SDK.
+
+```ts
+createBrowserAgentApp(agent: Agent, options: BrowserAgentAppOptions): AgentApp
+```
+
+`BrowserAgentAppOptions` extends `AgentOptions` (minus `transport`) with:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `targetOrigin` | `string` | `'*'` | Passed to the default `PostMessageIframeDuplexTransport` |
+| `transport` | `DuplexTransport<...>` | — | Override the full transport stack (e.g. for WebSocket testing) |
+
+## Origin security
+
+Both transports default `targetOrigin` to `'*'` for ease of development. In production, set it to the exact origin of the other party to prevent cross-origin message leakage:
+
+```ts
+// Agent side (inside iframe)
+new PostMessageIframeDuplexTransport({ targetOrigin: 'https://app.example.com' })
+
+// Host side
+new PostMessageHostDuplexTransport(iframeEl, 'https://agents.example.com')
+```

package/dist/browser-agent-app.d.ts

@@ -0,0 +1,29 @@
+import { FromAgent, FromServer, Message } from "@awarevue/api-types";
+import { Agent, AgentApp, AgentOptions, DuplexTransport } from "@awarevue/agent-sdk";
+export type BrowserAgentAppOptions = Omit<AgentOptions, "transport"> & {
+    /**
+     * Target origin passed to the default `PostMessageIframeDuplexTransport`.
+     * Ignored when a custom `transport` is provided.
+     * Defaults to `'*'`.
+     */
+    targetOrigin?: string;
+    /**
+     * Provide a fully-wired custom transport to replace the default
+     * postMessage stack.  Use this to swap in a WebSocket transport for
+     * out-of-browser testing without changing any other code.
+     */
+    transport?: DuplexTransport<Message<FromServer>, Message<FromAgent>>;
+};
+/**
+ * Creates an AgentApp wired to the iframe postMessage transport by default.
+ *
+ * Transport stack (bottom → top):
+ *   PostMessageIframeDuplexTransport  (raw string channel)
+ *   → WsJsonEncoder                  ({ event, data } ↔ Message<T>)
+ *   → LoggingDuplexTransport         (console logging)
+ *   → AgentApp / AgentProtocol
+ *
+ * To test outside the browser, pass any DuplexTransport<Message<FromServer>,
+ * Message<FromAgent>> as the `transport` option — no other changes needed.
+ */
+export declare function createBrowserAgentApp(agent: Agent, options: BrowserAgentAppOptions): AgentApp;

package/dist/browser-agent-app.js

@@ -0,0 +1,35 @@
+"use strict";
+// browser-agent-app.ts
+// ----------------------------------------------------------------
+// Convenience factory that mirrors createAgentApp() from the core SDK
+// but defaults to the postMessage transport stack instead of WebSocket.
+//
+// Consumers who want explicit control can pass a custom `transport`
+// (e.g. the full WsJsonEncoder(...) stack) and skip this factory
+// entirely — AgentApp / createAgentApp accept any DuplexTransport.
+// ----------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserAgentApp = createBrowserAgentApp;
+const agent_sdk_1 = require("@awarevue/agent-sdk");
+const post_message_iframe_1 = require("./post-message-iframe");
+/* ---------------------------------------------------------------- */
+/* Factory                                                          */
+/* ---------------------------------------------------------------- */
+/**
+ * Creates an AgentApp wired to the iframe postMessage transport by default.
+ *
+ * Transport stack (bottom → top):
+ *   PostMessageIframeDuplexTransport  (raw string channel)
+ *   → WsJsonEncoder                  ({ event, data } ↔ Message<T>)
+ *   → LoggingDuplexTransport         (console logging)
+ *   → AgentApp / AgentProtocol
+ *
+ * To test outside the browser, pass any DuplexTransport<Message<FromServer>,
+ * Message<FromAgent>> as the `transport` option — no other changes needed.
+ */
+function createBrowserAgentApp(agent, options) {
+    const { targetOrigin, transport, ...rest } = options;
+    const finalTransport = transport ??
+        new agent_sdk_1.LoggingDuplexTransport(new agent_sdk_1.WsJsonEncoder(new post_message_iframe_1.PostMessageIframeDuplexTransport({ targetOrigin })));
+    return new agent_sdk_1.AgentApp(agent, { ...rest, transport: finalTransport });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./post-message-iframe";
+export * from "./post-message-host";
+export * from "./browser-agent-app";
+export * from "./post-message-hub";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./post-message-iframe"), exports);
+__exportStar(require("./post-message-host"), exports);
+__exportStar(require("./browser-agent-app"), exports);
+__exportStar(require("./post-message-hub"), exports);

package/dist/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@awarevue/agent-sdk-browser",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linc-Security-Systems/aware-essentials.git"
+  },
+  "version": "2.0.91",
+  "description": "Browser transport adapters for the Aware agent protocol — iframe/postMessage drop-in replacement for the WebSocket transport.",
+  "author": "Yaser Awajan",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp package.json dist/",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "yarn lint --fix"
+  },
+  "peerDependencies": {
+    "@awarevue/agent-sdk": "2.0.91",
+    "@awarevue/api-types": "2.0.91",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@awarevue/agent-sdk": "2.0.91",
+    "@awarevue/api-types": "2.0.91",
+    "@typescript-eslint/eslint-plugin": "^8.31.1",
+    "@typescript-eslint/parser": "^8.31.1",
+    "eslint": "^9.25.1",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-import": "^2.31.0",
+    "jsdom": "^26.1.0",
+    "rxjs": "7.8.2",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/dist/post-message-host.d.ts

@@ -0,0 +1,20 @@
+import { Observable } from "rxjs";
+import { DuplexTransport } from "@awarevue/agent-sdk";
+export declare class PostMessageHostDuplexTransport implements DuplexTransport<string, string> {
+    private readonly iframe;
+    readonly connected$: Observable<boolean>;
+    readonly messages$: Observable<string>;
+    private readonly _connected$;
+    private readonly destroy$;
+    private readonly targetOrigin;
+    private closed;
+    /**
+     * @param iframe       The iframe element whose agent this transport represents.
+     * @param targetOrigin Target origin for outbound `postMessage` calls and for
+     *                     filtering inbound messages by `event.origin`.
+     *                     Defaults to `'*'`.
+     */
+    constructor(iframe: HTMLIFrameElement, targetOrigin?: string);
+    send(msg: string): void;
+    close(): void;
+}

package/dist/post-message-host.js

@@ -0,0 +1,51 @@
+"use strict";
+// transports/post-message-host.ts
+// ----------------------------------------------------------------
+// DuplexTransport backed by the window.postMessage API — host side.
+//
+// Designed to run in the parent page. One instance wraps a single
+// HTMLIFrameElement: inbound messages are accepted only when
+// event.source matches that iframe's contentWindow, and outbound
+// messages are sent directly to iframe.contentWindow.postMessage.
+//
+// Implements DuplexTransport<string, string> — the exact same
+// interface contract as WsServerDuplexTransport — so it plugs into
+// InMemoryHub + AgentServer without any changes to the server stack.
+// ----------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostMessageHostDuplexTransport = void 0;
+const rxjs_1 = require("rxjs");
+const rxjs_2 = require("rxjs");
+/* ---------------------------------------------------------------- */
+/* Implementation                                                   */
+/* ---------------------------------------------------------------- */
+class PostMessageHostDuplexTransport {
+    /**
+     * @param iframe       The iframe element whose agent this transport represents.
+     * @param targetOrigin Target origin for outbound `postMessage` calls and for
+     *                     filtering inbound messages by `event.origin`.
+     *                     Defaults to `'*'`.
+     */
+    constructor(iframe, targetOrigin = "*") {
+        this.iframe = iframe;
+        this._connected$ = new rxjs_1.BehaviorSubject(true);
+        this.destroy$ = new rxjs_1.Subject();
+        this.closed = false;
+        this.targetOrigin = targetOrigin;
+        this.connected$ = this._connected$.asObservable();
+        this.messages$ = (0, rxjs_1.fromEvent)(window, "message").pipe((0, rxjs_2.takeUntil)(this.destroy$), (0, rxjs_2.filter)((e) => e.source === this.iframe.contentWindow), (0, rxjs_2.filter)((e) => this.targetOrigin === "*" ? true : e.origin === this.targetOrigin), (0, rxjs_2.filter)((e) => typeof e.data === "string"), (0, rxjs_2.map)((e) => e.data));
+    }
+    send(msg) {
+        this.iframe.contentWindow.postMessage(msg, this.targetOrigin);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.destroy$.next();
+        this.destroy$.complete();
+        this._connected$.next(false);
+        this._connected$.complete();
+    }
+}
+exports.PostMessageHostDuplexTransport = PostMessageHostDuplexTransport;

package/dist/post-message-hub.d.ts

@@ -0,0 +1,23 @@
+import { Observable } from "rxjs";
+import { DuplexTransport, HubTransport, PeerEvent } from "@awarevue/agent-sdk";
+export declare class PostMessageHub implements HubTransport<string, string, string> {
+    private readonly targetOrigin;
+    private readonly _peerEvents$;
+    readonly peerEvents$: Observable<PeerEvent<string>>;
+    private readonly peers;
+    /** Maps source window reference → agentId */
+    private readonly sourceToAgent;
+    private readonly destroy$;
+    private readonly sub;
+    private closed;
+    /**
+     * @param targetOrigin  Target origin for outbound `postMessage` calls.
+     *                      Defaults to `'*'`. Set to a specific origin in
+     *                      production to prevent cross-origin message leakage.
+     */
+    constructor(targetOrigin?: string);
+    private onMessage;
+    connection(peer: string): DuplexTransport<string, string> | null;
+    closePeer(peer: string): void;
+    close(): void;
+}

package/dist/post-message-hub.js

@@ -0,0 +1,152 @@
+"use strict";
+// post-message-hub.ts
+// ----------------------------------------------------------------
+// HubTransport backed by window.postMessage — host side.
+//
+// Unlike PostMessageHostDuplexTransport (which is a 1:1 DuplexTransport
+// that requires an iframe element upfront), this class is a
+// server-style hub: it discovers peers automatically from incoming
+// window 'message' events, just like a WebSocket server accepts
+// incoming connections.
+//
+// How peer discovery works:
+//   1. The first JSON message from an unknown source window is parsed.
+//   2. The `data.from` field (the stable agent ID chosen by the
+//      developer, e.g. "demo_agent") is used as the TPeer identifier.
+//   3. A PostMessagePeerTransport is created for that source window.
+//   4. A 'join' PeerEvent is emitted so AgentServer can register it.
+//   5. Subsequent messages from the same source are routed to the
+//      existing peer transport without another round of parsing.
+//
+// Implements HubTransport<string, string, string> so it slots directly
+// into WsJsonHubAdapter → AgentServer.
+// ----------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostMessageHub = void 0;
+const rxjs_1 = require("rxjs");
+const rxjs_2 = require("rxjs");
+/* ---------------------------------------------------------------- */
+/* Internal: per-peer transport                                     */
+/* ---------------------------------------------------------------- */
+class PostMessagePeerTransport {
+    constructor(source, targetOrigin, onClose) {
+        this.source = source;
+        this.targetOrigin = targetOrigin;
+        this.onClose = onClose;
+        this._connected$ = new rxjs_1.BehaviorSubject(true);
+        this._messages$ = new rxjs_1.Subject();
+        this.closed = false;
+        this.connected$ = this._connected$.asObservable();
+        this.messages$ = this._messages$.asObservable();
+    }
+    /** Called by PostMessageHub to route an inbound string to this peer. */
+    receive(msg) {
+        if (!this.closed) {
+            this._messages$.next(msg);
+        }
+    }
+    send(msg) {
+        if (!this.closed) {
+            this.source.postMessage(msg, this.targetOrigin);
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this._connected$.next(false);
+        this._connected$.complete();
+        this._messages$.complete();
+        this.onClose();
+    }
+}
+/* ---------------------------------------------------------------- */
+/* Public: PostMessageHub                                           */
+/* ---------------------------------------------------------------- */
+class PostMessageHub {
+    /**
+     * @param targetOrigin  Target origin for outbound `postMessage` calls.
+     *                      Defaults to `'*'`. Set to a specific origin in
+     *                      production to prevent cross-origin message leakage.
+     */
+    constructor(targetOrigin = "*") {
+        this.targetOrigin = targetOrigin;
+        this._peerEvents$ = new rxjs_1.Subject();
+        this.peerEvents$ = this._peerEvents$.asObservable();
+        this.peers = new Map();
+        /** Maps source window reference → agentId */
+        this.sourceToAgent = new Map();
+        this.destroy$ = new rxjs_1.Subject();
+        this.closed = false;
+        this.sub = (0, rxjs_1.fromEvent)(window, "message")
+            .pipe((0, rxjs_2.takeUntil)(this.destroy$))
+            .subscribe((e) => this.onMessage(e));
+    }
+    onMessage(e) {
+        if (!e.source || typeof e.data !== "string")
+            return;
+        const existing = this.sourceToAgent.get(e.source);
+        if (existing !== undefined) {
+            // Route to existing peer
+            this.peers.get(existing)?.receive(e.data);
+            return;
+        }
+        // New source: parse the WsJsonEncoder envelope to extract agentId
+        let agentId;
+        try {
+            const envelope = JSON.parse(e.data);
+            const from = envelope?.data?.from;
+            if (typeof from === "string" && from.length > 0) {
+                agentId = from;
+            }
+        }
+        catch {
+            return; // not valid JSON — ignore
+        }
+        if (!agentId)
+            return;
+        // Guard against duplicate agentId from a different source
+        if (this.peers.has(agentId)) {
+            // Route anyway — same agent re-connecting on a different source
+            this.peers.get(agentId)?.receive(e.data);
+            return;
+        }
+        const transport = new PostMessagePeerTransport(e.source, this.targetOrigin, () => this.closePeer(agentId));
+        this.peers.set(agentId, transport);
+        this.sourceToAgent.set(e.source, agentId);
+        this._peerEvents$.next({ type: "join", peer: agentId });
+        // Replay the first message into the peer stream
+        transport.receive(e.data);
+    }
+    connection(peer) {
+        return this.peers.get(peer) ?? null;
+    }
+    closePeer(peer) {
+        const transport = this.peers.get(peer);
+        if (!transport)
+            return;
+        // Remove maps first to prevent re-entry from transport.close()
+        for (const [src, id] of this.sourceToAgent) {
+            if (id === peer) {
+                this.sourceToAgent.delete(src);
+                break;
+            }
+        }
+        this.peers.delete(peer);
+        transport.close(); // no-op if already closed
+        this._peerEvents$.next({ type: "leave", peer });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.destroy$.next();
+        this.destroy$.complete();
+        this.sub.unsubscribe();
+        for (const peer of [...this.peers.keys()]) {
+            this.closePeer(peer);
+        }
+        this._peerEvents$.complete();
+    }
+}
+exports.PostMessageHub = PostMessageHub;

package/dist/post-message-iframe.d.ts

@@ -0,0 +1,24 @@
+import { Observable } from "rxjs";
+import { DuplexTransport } from "@awarevue/agent-sdk";
+export interface PostMessageIframeDuplexTransportOptions {
+    /**
+     * The target origin used for outbound `postMessage` calls and for
+     * filtering inbound messages by `event.origin`.
+     *
+     * Defaults to `'*'` (no origin filtering, send to any origin).
+     * Set to a specific origin (e.g. `'https://app.example.com'`) for
+     * production deployments to prevent cross-origin message leakage.
+     */
+    targetOrigin?: string;
+}
+export declare class PostMessageIframeDuplexTransport implements DuplexTransport<string, string> {
+    readonly connected$: Observable<boolean>;
+    readonly messages$: Observable<string>;
+    private readonly _connected$;
+    private readonly destroy$;
+    private readonly targetOrigin;
+    private closed;
+    constructor(opts?: PostMessageIframeDuplexTransportOptions);
+    send(msg: string): void;
+    close(): void;
+}

package/dist/post-message-iframe.js

@@ -0,0 +1,44 @@
+"use strict";
+// transports/post-message-iframe.ts
+// ----------------------------------------------------------------
+// DuplexTransport backed by the window.postMessage API — agent side.
+//
+// Designed to run inside an iframe. Messages are received from the
+// parent via the window 'message' event and sent to the parent via
+// window.parent.postMessage.
+//
+// Implements DuplexTransport<string, string> — the exact same
+// interface contract as WsDuplexTransport — so the full transport
+// stack (WsJsonEncoder → LoggingDuplexTransport → AgentProtocol) can
+// be composed without modification.
+// ----------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostMessageIframeDuplexTransport = void 0;
+const rxjs_1 = require("rxjs");
+const rxjs_2 = require("rxjs");
+/* ---------------------------------------------------------------- */
+/* Implementation                                                   */
+/* ---------------------------------------------------------------- */
+class PostMessageIframeDuplexTransport {
+    constructor(opts = {}) {
+        this._connected$ = new rxjs_1.BehaviorSubject(true);
+        this.destroy$ = new rxjs_1.Subject();
+        this.closed = false;
+        this.targetOrigin = opts.targetOrigin ?? "*";
+        this.connected$ = this._connected$.asObservable();
+        this.messages$ = (0, rxjs_1.fromEvent)(window, "message").pipe((0, rxjs_2.takeUntil)(this.destroy$), (0, rxjs_2.filter)((e) => this.targetOrigin === "*" ? true : e.origin === this.targetOrigin), (0, rxjs_2.filter)((e) => typeof e.data === "string"), (0, rxjs_2.map)((e) => e.data));
+    }
+    send(msg) {
+        window.parent.postMessage(msg, this.targetOrigin);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.destroy$.next();
+        this.destroy$.complete();
+        this._connected$.next(false);
+        this._connected$.complete();
+    }
+}
+exports.PostMessageIframeDuplexTransport = PostMessageIframeDuplexTransport;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@awarevue/agent-sdk-browser",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linc-Security-Systems/aware-essentials.git"
+  },
+  "version": "2.0.91",
+  "description": "Browser transport adapters for the Aware agent protocol — iframe/postMessage drop-in replacement for the WebSocket transport.",
+  "author": "Yaser Awajan",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp package.json dist/",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "yarn lint --fix"
+  },
+  "peerDependencies": {
+    "@awarevue/agent-sdk": "2.0.91",
+    "@awarevue/api-types": "2.0.91",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@awarevue/agent-sdk": "2.0.91",
+    "@awarevue/api-types": "2.0.91",
+    "@typescript-eslint/eslint-plugin": "^8.31.1",
+    "@typescript-eslint/parser": "^8.31.1",
+    "eslint": "^9.25.1",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-import": "^2.31.0",
+    "jsdom": "^26.1.0",
+    "rxjs": "7.8.2",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}