@salesforce-ui-embedding/internal-lightning-ui-embedding 2.2.7-rc.2

package/dist/modules/lightning/uiEmbedding/uiEmbedding.js-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2026 Salesforce, Inc. All rights reserved.
+  For full license text, see the LICENSE.txt file in this package.
+-->
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isExposed>true</isExposed>
+    <minApiVersion>62.0</minApiVersion>
+</LightningComponentBundle>

package/dist/modules/lightning/uiEmbedding/utils/bootstrap.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+import { ERROR_CODES } from "./constants";
+import { BOOTSTRAP_ENVELOPE_TYPE, HEARTBEAT_TYPE, PROTOCOL_NAME, SHUTDOWN_TYPE } from "./sf-embedding-contract";
+
+// TODO: MVP — exact-match. API stays the same; internal algorithm as per spec definition will change later.
+const HOST_SUPPORTED_PROTOCOL_VERSIONS = new Set(["1.0.0"]);
+
+export function negotiateProtocolVersion(version) {
+    if (typeof version === "string" && HOST_SUPPORTED_PROTOCOL_VERSIONS.has(version)) {
+        return { ok: true, protocolVersion: version };
+    }
+    return { ok: false, protocolVersion: version };
+}
+
+export function validateHeartbeat(input) {
+    if (!hasMessageType(input.data, HEARTBEAT_TYPE)) return { ok: false, reason: ERROR_CODES.WRONG_TYPE };
+    if (input.source !== input.expectedSource) return { ok: false, reason: ERROR_CODES.WRONG_SOURCE };
+    if (input.origin !== input.expectedOrigin) return { ok: false, reason: ERROR_CODES.WRONG_ORIGIN };
+    const declared = input.data.protocolVersion;
+    const negotiated = negotiateProtocolVersion(declared);
+    if (!negotiated.ok) {
+        return {
+            ok: false,
+            reason: ERROR_CODES.PROTOCOL_VERSION_MISMATCH,
+            protocolVersion: typeof negotiated.protocolVersion === "string" ? negotiated.protocolVersion : undefined,
+        };
+    }
+    const instanceId = input.data.instanceId;
+    if (typeof instanceId !== "string" || instanceId !== input.expectedInstanceId) {
+        return { ok: false, reason: ERROR_CODES.INSTANCE_ID_MISMATCH };
+    }
+    if (input.alreadyTransferred) return { ok: false, reason: ERROR_CODES.DUPLICATE };
+    return { ok: true, protocolVersion: negotiated.protocolVersion };
+}
+
+export function validateShutdown(input) {
+    if (!hasMessageType(input.data, SHUTDOWN_TYPE)) return { ok: false, reason: ERROR_CODES.WRONG_TYPE };
+    if (input.source !== input.expectedSource) return { ok: false, reason: ERROR_CODES.WRONG_SOURCE };
+    if (input.origin !== input.expectedOrigin) return { ok: false, reason: ERROR_CODES.WRONG_ORIGIN };
+    const reason = input.data.reason;
+    // Any string is accepted as-is; non-strings resolve to undefined and the caller uses
+    // ?? EMBEDDING_SHUTDOWN. Callers that emit this to Argus must bound cardinality themselves.
+    const safeReason = typeof reason === "string" ? reason : undefined;
+    return { ok: true, reason: safeReason };
+}
+
+export function buildBootstrapEnvelope(opts) {
+    return {
+        type: BOOTSTRAP_ENVELOPE_TYPE,
+        protocol: PROTOCOL_NAME,
+        instanceId: opts.instanceId,
+        allowedOrigins: opts.allowedOrigins,
+    };
+}
+
+function hasMessageType(value, expected) {
+    if (typeof value !== "object" || value === null) return false;
+    return value.type === expected;
+}

package/dist/modules/lightning/uiEmbedding/utils/constants.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+export const DEFAULT_SANDBOX_TOKENS = ["allow-scripts", "allow-same-origin"];
+
+// Default advisory heartbeat deadline; Infinity opts out.
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 30_000;
+
+export const ERROR_PHASES = {
+    CONFIGURATION: "configuration",
+    BOOTSTRAP: "bootstrap",
+    EVENT_FORWARDING: "event-forwarding",
+};
+
+export const ERROR_CODES = {
+    // Configuration Errors
+    ALLOW_SCRIPTS_STRIPPED: "ALLOW_SCRIPTS_STRIPPED",
+    BLOCKED_SANDBOX_TOKEN: "BLOCKED_SANDBOX_TOKEN",
+    MISSING_SRC: "MISSING_SRC",
+    INVALID_SRC: "INVALID_SRC",
+    SAME_ORIGIN_SRC: "SAME_ORIGIN_SRC",
+    SESSION_BINDING_MUTATED: "SESSION_BINDING_MUTATED",
+    // Bootstrap / Heartbeat Errors
+    PROTOCOL_VERSION_MISMATCH: "PROTOCOL_VERSION_MISMATCH",
+    HEARTBEAT_TIMEOUT: "HEARTBEAT_TIMEOUT",
+    TRANSFER_FAILED: "TRANSFER_FAILED",
+    WRONG_TYPE: "WRONG_TYPE",
+    WRONG_SOURCE: "WRONG_SOURCE",
+    WRONG_ORIGIN: "WRONG_ORIGIN",
+    INSTANCE_ID_MISMATCH: "INSTANCE_ID_MISMATCH",
+    DUPLICATE: "DUPLICATE",
+    DUPLICATE_PORT_TRANSFER: "DUPLICATE_PORT_TRANSFER",
+    EMBEDDING_SHUTDOWN: "EMBEDDING_SHUTDOWN",
+};
+
+export const STATES = {
+    PRE_HEARTBEAT: "pre-heartbeat",
+    POST_HEARTBEAT: "post-heartbeat",
+    READY: "ready",
+    CLOSED: "closed",
+};

package/dist/modules/lightning/uiEmbedding/utils/host-bridge.js

@@ -0,0 +1,150 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+// Host-side peer. One object that routes inbound requests (via the shared
+// JsonRpcRouter), handles inbound notifications, and exposes named methods for
+// the host's outbound traffic. Inbound handlers are registered in the
+// constructor; outbound methods (e.g. announceInitialized) wrap the inherited
+// send/notify so traceId `_meta` is stamped centrally by the BridgeClient.
+
+import { HostEventRegistry } from "./host-event-registry";
+
+import { MessageChannelTransport, StandardErrorCode } from "./jsonrpc";
+import { createLogger } from "./log";
+import { BridgeClient, JsonRpcRouter } from "./request-router";
+import {
+    EMBEDDING_INITIALIZED_METHOD,
+    ERROR_METHOD,
+    EVENTS_DISPATCH_METHOD,
+    EVENTS_SUBSCRIBE_METHOD,
+    EVENTS_UNSUBSCRIBE_METHOD,
+    HOST_INITIALIZED_METHOD,
+    JsonRpcHandlerError,
+    RESIZE_METHOD,
+    UI_STATE_SUBSCRIBE_METHOD,
+    UI_STATE_UNSUBSCRIBE_METHOD,
+} from "./sf-embedding-contract";
+
+export class HostBridge extends JsonRpcRouter {
+    // Active UiState wire subscription. Only one is permitted at a time; a second
+    // subscribe rejects until the first unsubscribes. Lives on the bridge because
+    // it's pure wire-routing state, scoped to the session the bridge represents.
+    _uiStateSubscriptionId = null;
+    _uiStateSubscriptionCounter = 0;
+
+    // Custom-event subscriptions for this session. Coarse "is anyone listening?"
+    // bookkeeping; per-eventType filtering happens on the embedding side.
+    _hostEvents = new HostEventRegistry();
+
+    _instrumentation = null;
+
+    constructor(
+        port,
+        composeUiState,
+        redispatchToHost,
+        onResizeHint,
+        onSfEmbeddingError,
+        log = createLogger("[lightning-ui-embedding:host-bridge]", () => false),
+        instrumentation,
+    ) {
+        // Wrap the transferred port in the shared transport; the BridgeClient
+        // subscribes to it (lazily starting the port), and the router claims
+        // inbound requests on the same transport.
+        super(new BridgeClient(new MessageChannelTransport(port)), log);
+        this._instrumentation = instrumentation ?? null;
+
+        // Lifecycle notification: the embedding side signals it has initialized.
+        // No host action beyond logging today, but routing it keeps the single
+        // dispatch path (no special-casing in a raw port listener).
+        this.onNotification(EMBEDDING_INITIALIZED_METHOD, () => {
+            log("embedding-initialized received");
+            this._instrumentation?.incrementCounter("sfembedding.embedding_initialized.received", 1, false);
+        });
+
+        // UiState subscription axis. One active subscription per session; the
+        // subscribe response carries the initial snapshot, and the host pushes
+        // ui-state-changed notifications (via the component) until unsubscribe.
+        this.onRequest(UI_STATE_SUBSCRIBE_METHOD, () => {
+            if (this._uiStateSubscriptionId !== null) {
+                this._instrumentation?.incrementCounter("sfembedding.uistate.subscribe_rejected", 1, true, {
+                    reason: "already_active",
+                });
+                throw new JsonRpcHandlerError(StandardErrorCode.INVALID_PARAMS, "ui-state subscription already active");
+            }
+            const subscriptionId = `ui-state-${++this._uiStateSubscriptionCounter}`;
+            this._uiStateSubscriptionId = subscriptionId;
+            this._instrumentation?.incrementCounter("sfembedding.uistate.subscribed", 1, false);
+            return { subscriptionId, current: composeUiState() };
+        });
+        this.onRequest(UI_STATE_UNSUBSCRIBE_METHOD, (params) => {
+            if (!params || params.subscriptionId !== this._uiStateSubscriptionId) {
+                this._instrumentation?.incrementCounter("sfembedding.uistate.unsubscribe_rejected", 1, true, {
+                    reason: "unknown_id",
+                });
+                throw new JsonRpcHandlerError(
+                    StandardErrorCode.INVALID_PARAMS,
+                    `unknown subscriptionId: ${params?.subscriptionId}`,
+                );
+            }
+            this._uiStateSubscriptionId = null;
+            this._instrumentation?.incrementCounter("sfembedding.uistate.unsubscribed", 1, false);
+        });
+
+        // Bidirectional custom events. Inbound dispatch re-fires on the host
+        // element (via the component-supplied callback, which owns the re-entrancy
+        // guard); subscribe/unsubscribe maintain the session-wide registry.
+        this.onNotification(EVENTS_DISPATCH_METHOD, (params) => {
+            this._instrumentation?.incrementCounter("sfembedding.events.dispatched_to_host", 1, false);
+            redispatchToHost(params);
+        });
+        this.onRequest(EVENTS_SUBSCRIBE_METHOD, () => {
+            this._instrumentation?.incrementCounter("sfembedding.events.subscribed", 1, false);
+            return { subscriptionId: this._hostEvents.subscribe() };
+        });
+        this.onRequest(EVENTS_UNSUBSCRIBE_METHOD, (params) => {
+            const id = params?.subscriptionId;
+            if (typeof id !== "string") {
+                this._instrumentation?.incrementCounter("sfembedding.events.unsubscribe_rejected", 1, true, {
+                    reason: "missing_id",
+                });
+                throw new JsonRpcHandlerError(StandardErrorCode.INVALID_PARAMS, "subscriptionId required");
+            }
+            if (!this._hostEvents.unsubscribe(id)) {
+                this._instrumentation?.incrementCounter("sfembedding.events.unsubscribe_rejected", 1, true, {
+                    reason: "unknown_id",
+                });
+                throw new JsonRpcHandlerError(StandardErrorCode.INVALID_PARAMS, `unknown subscriptionId: ${id}`);
+            }
+            this._instrumentation?.incrementCounter("sfembedding.events.unsubscribed", 1, false);
+        });
+
+        // Resize hint (fire-and-forget); component applies to iframe.
+        this.onNotification(RESIZE_METHOD, (params) => {
+            this._instrumentation?.incrementCounter("sfembedding.resize.hint_received", 1, false);
+            onResizeHint(params);
+        });
+
+        // Iframe error notification (non-PII); component pipes to o11y.
+        this.onNotification(ERROR_METHOD, (params) => {
+            log("embedding error received:", params);
+            onSfEmbeddingError(params);
+        });
+    }
+
+    /** The active UiState wire subscription id, or null when none is active. */
+    get uiStateSubscriptionId() {
+        return this._uiStateSubscriptionId;
+    }
+
+    /** Number of active custom-event subscriptions for this session. */
+    get hostEventSubscriberCount() {
+        return this._hostEvents.size;
+    }
+
+    /** Announce that the host has initialized. traceId `_meta` is stamped by the client. */
+    announceInitialized(params) {
+        this.notify(HOST_INITIALIZED_METHOD, params);
+    }
+}

package/dist/modules/lightning/uiEmbedding/utils/host-event-registry.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+// Subscription registry for ui/events/subscribe + ui/events/unsubscribe.
+// Global subscribe — tracks "is anyone listening from this iframe?" coarsely;
+// per-eventType filtering happens on the embedding side.
+
+export class HostEventRegistry {
+    ids = new Set();
+    counter = 0;
+
+    /** Register a new session-wide subscription. Returns an opaque ID. */
+    subscribe() {
+        const id = `evt-${++this.counter}`;
+        this.ids.add(id);
+        return id;
+    }
+
+    /** Drop a subscription by id. Returns false for unknown ids. */
+    unsubscribe(id) {
+        return this.ids.delete(id);
+    }
+
+    /** True iff at least one subscription is active. */
+    get size() {
+        return this.ids.size;
+    }
+
+    /** Drop everything. */
+    clear() {
+        this.ids.clear();
+    }
+}

package/dist/modules/lightning/uiEmbedding/utils/host-info.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+// `"2.2.7-rc.2"` is a repo-wide ambient declared in /types/globals.d.ts;
+// build.mjs substitutes the literal at build time, jest globals supply a test value.
+
+/** Identity emitted on `ui/notifications/host-initialized`. */
+export const HOST_INFO = {
+    name: "lightning-ui-embedding",
+    version: "2.2.7-rc.2",
+};

package/dist/modules/lightning/uiEmbedding/utils/instrumentation.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2025 salesforce.com, inc.
+ * All Rights Reserved
+ * Company Confidential
+ *
+ * o11y wrapper for the lightning-ui-embedding host component. Narrowed to the
+ * bootstrap lifecycle and host-side error reporting:
+ *
+ *   - uiEmbeddingLoadSchema  (uxact) — embedding_init activity; stop() = success
+ *                                    (timed span from src-set to READY)
+ *   - uiEmbeddingErrorSchema (uxerr) — failure on the bootstrap path or any
+ *                                    host-side protocol error
+ *
+ * Channel: LightningUiEmbedding.
+ */
+
+import { getInstrumentation } from "o11y/client";
+import { uiEmbeddingErrorSchema, uiEmbeddingLoadSchema } from "o11y_schema/sf_uiEmbedding";
+
+/** Free-form user payload merged into an o11y activity/error record. */
+
+/** Opaque o11y activity handle returned by `startActivity` — surface varies by runtime. */
+
+export function createInstrumentation(channelName, widgetSrc, hostAppOrigin) {
+    const instrumentation = getInstrumentation(channelName);
+
+    function logError(error, details) {
+        if (!instrumentation || typeof instrumentation.error !== "function") return;
+        try {
+            instrumentation.error(error, uiEmbeddingErrorSchema, {
+                widgetSrc,
+                hostAppOrigin,
+                message: error?.message || String(error),
+                isHostError: true,
+                ...details,
+            });
+        } catch {
+            // swallow
+        }
+    }
+
+    function startLoadActivity(instrumentationContext) {
+        if (!instrumentation || typeof instrumentation.startActivity !== "function") return null;
+        try {
+            return instrumentation.startActivity("embedding_init", { instrumentationContext });
+        } catch {
+            return null;
+        }
+    }
+
+    function errorLoadActivity(activity, err, details) {
+        const act = activity;
+        if (!act || typeof act.error !== "function") return;
+        try {
+            act.error(err, uiEmbeddingErrorSchema, details);
+        } catch {
+            // swallow
+        }
+    }
+
+    function stopLoadActivity(activity, details) {
+        const act = activity;
+        if (!act || typeof act.stop !== "function") return;
+        try {
+            act.stop(uiEmbeddingLoadSchema, details);
+        } catch {
+            // swallow
+        }
+    }
+
+    // Direct-to-Argus counter emission. In production the o11y client's
+    // incrementCounter() flows through Core → Funnel → Argus.
+    // Metric naming: core_ui_LightningUiEmbedding:<scope>.<name>.COUNT.Count
+    function incrementCounter(name, value, isError, tags) {
+        if (!instrumentation || typeof instrumentation.incrementCounter !== "function") return;
+        try {
+            instrumentation.incrementCounter(name, value, isError, tags || {});
+        } catch {
+            // swallow
+        }
+    }
+
+    return {
+        logError,
+        startLoadActivity,
+        errorLoadActivity,
+        stopLoadActivity,
+        incrementCounter,
+    };
+}

package/dist/modules/lightning/uiEmbedding/utils/jsonrpc.js

@@ -0,0 +1,122 @@
+function _classPrivateMethodInitSpec(e, a) {_checkPrivateRedeclaration(e, a), a.add(e);}function _classPrivateFieldInitSpec(e, t, a) {_checkPrivateRedeclaration(e, t), t.set(e, a);}function _checkPrivateRedeclaration(e, t) {if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");}function _classPrivateFieldGet(s, a) {return s.get(_assertClassBrand(s, a));}function _classPrivateFieldSet(s, a, r) {return s.set(_assertClassBrand(s, a), r), r;}function _assertClassBrand(e, t, n) {if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;throw new TypeError("Private element is not present on this object");}function R() {
+}var _t = /*#__PURE__*/new WeakMap();var _s = /*#__PURE__*/new WeakMap();var _r = /*#__PURE__*/new WeakMap();var _n = /*#__PURE__*/new WeakMap();var _e = /*#__PURE__*/new WeakMap();var _O_brand = /*#__PURE__*/new WeakSet();var _i = /*#__PURE__*/new WeakMap();
+class O {
+
+
+
+
+
+
+  constructor(_t2) {_classPrivateMethodInitSpec(this, _O_brand);_classPrivateFieldInitSpec(this, _t, void 0);_classPrivateFieldInitSpec(this, _s, /* @__PURE__ */new Set());_classPrivateFieldInitSpec(this, _r, false);_classPrivateFieldInitSpec(this, _n, false); /** Messages queued before `port.start()` has been called. Flushed on first subscribe. */_classPrivateFieldInitSpec(this, _e, []);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+    _classPrivateFieldInitSpec(this, _i, (t) => {
+      const s = [..._classPrivateFieldGet(_s, this)];
+      for (const n of s)
+      try {
+        n(t.data);
+      } catch {
+      }
+    });_classPrivateFieldSet(_t, this, _t2);} /**
+   * Post a message to the peer.
+   *
+   * Never throws on transient failure — a closed / neutered / disposed
+   * port silently drops the message. If the transport has not yet
+   * started (no `onMessage` subscriber), the message is buffered and
+   * flushed on first subscription.
+   */post(t) {if (!_classPrivateFieldGet(_n, this)) {if (!_classPrivateFieldGet(_r, this)) {_classPrivateFieldGet(_e, this).push(t);return;}try {_classPrivateFieldGet(_t, this).postMessage(t);} catch {}}} /**
+   * Subscribe to inbound messages from the peer. The callback receives
+   * the **unwrapped** payload (`MessageEvent.data`) — callers never see
+   * the `MessageEvent` wrapper.
+   *
+   * Starts the underlying port on first subscription and flushes any
+   * messages queued via `post` before the port was started.
+   *
+   * Returns an unsubscribe function. Calling it is idempotent.
+   */onMessage(t) {if (_classPrivateFieldGet(_n, this)) return R;_classPrivateFieldGet(_s, this).add(t), _classPrivateFieldGet(_r, this) || _assertClassBrand(_O_brand, this, _o).call(this);let s = false;return () => {s || (s = true, _classPrivateFieldGet(_s, this).delete(t));};} /**
+   * Tear down the transport:
+   *  - remove the internal `message` listener
+   *  - call `port.close()`
+   *  - clear subscriber set and outbound buffer
+   *  - subsequent `post` calls silently no-op
+   *  - subsequent `onMessage` calls return a no-op unsubscribe
+   */dispose() {if (!_classPrivateFieldGet(_n, this)) {_classPrivateFieldSet(_n, this, true);try {_classPrivateFieldGet(_t, this).removeEventListener("message", _classPrivateFieldGet(_i, this));} catch {}_classPrivateFieldGet(_s, this).clear(), _classPrivateFieldGet(_e, this).length = 0;try {_classPrivateFieldGet(_t, this).close();} catch {}}}}function _o() {_classPrivateFieldSet(_r, this, true), _classPrivateFieldGet(_t, this).addEventListener("message", _classPrivateFieldGet(_i, this));try {_classPrivateFieldGet(_t, this).start();} catch {}if (_classPrivateFieldGet(_e, this).length > 0) {const t = _classPrivateFieldGet(_e, this);_classPrivateFieldSet(_e, this, []);for (const s of t) try {_classPrivateFieldGet(_t, this).postMessage(s);} catch {}}}const a = { // --- Standard JSON-RPC 2.0 ----------------------------------------------
+  PARSE_ERROR: -32700, INVALID_REQUEST: -32600, METHOD_NOT_FOUND: -32601, INVALID_PARAMS: -32602, INTERNAL_ERROR: -32603, // --- Transport-level (any JsonRpcClient over a transport will emit) -----
+  /** Transport closed; pending requests rejected locally. */PORT_CLOSED: -32016, /** Payload could not be structured-cloned across the transport. */SERIALIZATION_FAILURE: -32017, /** `default` / `long` timeout-class request expired. */REQUEST_TIMEOUT: -32018, /** In-flight cap reached. */BACKPRESSURE: -32019, /** Terminal response to a $/cancel-ed request. */REQUEST_CANCELLED: -32024 }; /* @__PURE__ */new Set([a.REQUEST_TIMEOUT, a.BACKPRESSURE]);export { O as MessageChannelTransport, a as StandardErrorCode };

package/dist/modules/lightning/uiEmbedding/utils/log.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+// TODO: require per-event log levels (warn/error/info), not a single debug-gated level.
+
+export function createLogger(prefix, isEnabled) {
+    return (...args) => {
+        if (isEnabled()) window.console.log(prefix, ...args);
+    };
+}