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

package/dist/modules/lightning/uiEmbedding/utils/request-router.js

@@ -0,0 +1,375 @@
+function _defineProperty(e, r, t) {return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e;}function _toPropertyKey(t) {var i = _toPrimitive(t, "string");return "symbol" == typeof i ? i : i + "";}function _toPrimitive(t, r) {if ("object" != typeof t || !t) return t;var e = t[Symbol.toPrimitive];if (void 0 !== e) {var i = e.call(t, r || "default");if ("object" != typeof i) return i;throw new TypeError("@@toPrimitive must return a primitive value.");}return ("string" === r ? String : Number)(t);}function o(e) {
+  return typeof e == "object" && e !== null && !Array.isArray(e);
+}
+function c(e) {
+  return typeof e.id == "number" && Number.isInteger(e.id) && e.id >= 0;
+}
+function i(e) {
+  return o(e) && e.jsonrpc === "2.0";
+}
+function m(e) {
+  if (!i(e)) return false;
+  const t = e;
+  return c(t) && typeof t.method == "string";
+}
+function d(e) {
+  if (!i(e)) return false;
+  const t = e;
+  return !("id" in t) && typeof t.method == "string";
+}
+function p(e) {
+  if (!i(e)) return false;
+  const t = e;
+  return c(t) && "result" in t && !("error" in t) && !("method" in t);
+}
+function u(e) {
+  if (!i(e)) return false;
+  const t = e;
+  if (!c(t) || "result" in t || "method" in t) return false;
+  const s = t.error;
+  return o(s) && typeof s.code == "number";
+}
+function g(e) {
+  return p(e) || u(e);
+}
+class b {
+
+
+
+
+  /**
+   * Construct a JSON-RPC client bound to the given transport.
+   *
+   * @param transport - the transport to use.
+   */
+  constructor(_t) {_defineProperty(this, "nextRequestId", 1);_defineProperty(this, "pending", /* @__PURE__ */new Map());_defineProperty(this, "notificationHandlers", /* @__PURE__ */new Map());_defineProperty(this, "transport", void 0);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+    /**
+     * Handle inbound JSON-RPC messages from the transport.
+     *
+     * Processes both responses (for requests) and notifications.
+     * Non-JSON-RPC payloads are silently ignored so that a shared transport
+     * can be used for multiple protocols without cross-talk.
+     */_defineProperty(this, "onMessage",
+    (t) => {
+      if (g(t)) {
+        const s = this.pending.get(t.id);
+        if (!s)
+        return;
+        this.pending.delete(t.id), this.onInboundMeta(t, t._meta), u(t) ? s.reject(new Error(t.error.message || "Request failed")) : s.resolve(t.result);
+        return;
+      }
+      if (d(t)) {
+        this.onInboundMeta(t, t._meta);
+        const s = this.notificationHandlers.get(t.method);
+        if (s) {
+          const n = t._meta;
+          s.forEach((r) => {
+            r(t.params, n);
+          });
+        }
+      }
+    });this.transport = _t, this.transport.onMessage(this.onMessage);} /**
+   * Register a handler for a specific JSON-RPC notification method.
+   *
+   * Subclasses can register handlers to process specific notification
+   * types. When a notification with the registered method is received,
+   * the handler will be invoked with the notification params.
+   *
+   * @param method - The notification method to handle (e.g.
+   *   "ui/notifications/host-context-changed")
+   * @param handler - Callback function to process the notification params
+   *
+   * @example
+   * this.registerNotificationHandler("ui/notifications/host-context-changed", (params) => {
+   *   this.handleHostContextChanged(params);
+   * });
+   */registerNotificationHandler(t, s) {this.notificationHandlers.has(t) || this.notificationHandlers.set(t, /* @__PURE__ */new Set()), this.notificationHandlers.get(t).add(s);} /**
+   * Send a JSON-RPC request to the peer.
+   *
+   * @param method - The JSON-RPC method name
+   * @param params - The method parameters
+   * @returns Promise that resolves with the result or rejects with error
+   *
+   * @example
+   * const result = await this.request("ui/message", {
+   *   role: "user",
+   *   content: { type: "text", text: "Hello" }
+   * });
+   */request(t, s) {const n = this.nextRequestId++,r = { jsonrpc: "2.0", id: n, method: t, params: s };return this.applyOutboundMeta(r, t), new Promise((f, h) => {this.pending.set(n, { resolve: f, reject: h }), this.transport.post(r);});}
+  /**
+   * Send a JSON-RPC notification to the peer.
+   *
+   * Notifications are one-way messages that do not expect a response.
+   * Use notifications for:
+   * - Informing the host of state changes
+   * - Fire-and-forget operations
+   * - Events that don't require confirmation
+   *
+   * Use request() instead when you need:
+   * - A response from the host
+   * - Confirmation of success/failure
+   * - Return values from the operation
+   *
+   * @param method - The JSON-RPC method name
+   * @param params - Optional method parameters
+   *
+   * @example
+   * this.sendNotification("ui/notifications/size-changed", {
+   *   width: 800,
+   *   height: 600
+   * });
+   */
+  sendNotification(t, s) {
+    const n = {
+      jsonrpc: "2.0",
+      method: t,
+      params: s
+    };
+    this.applyOutboundMeta(n, t), this.transport.post(n);
+  }
+  /**
+   * Outbound `_meta` hook. Override to attach protocol-meta (e.g. a
+   * per-message `traceId`) to every outgoing request and notification.
+   *
+   * Default returns `undefined` so the envelope ships without `_meta`,
+   * matching JSON-RPC 2.0 baseline behavior.
+   */
+  getOutboundMeta(t) {
+  }
+  /**
+   * Inbound `_meta` hook. Invoked once per validated inbound frame
+   * (response or notification) before the value is dispatched to the
+   * pending-request resolver or notification handlers.
+   *
+   * Default is a no-op. Override to feed log correlation, tracing, etc.
+   */
+  onInboundMeta(t, s) {
+  }
+  applyOutboundMeta(t, s) {
+    const n = this.getOutboundMeta(s);
+    n !== void 0 && (t._meta = n);
+  }
+}
+const a = {
+    METHOD_NOT_FOUND: -32601,
+    INTERNAL_ERROR: -32603,
+    /** `default` / `long` timeout-class request expired. */
+    REQUEST_TIMEOUT: -32018,
+    /** In-flight cap reached. */
+    BACKPRESSURE: -32019 },l = /* @__PURE__ */new Set([
+  a.REQUEST_TIMEOUT,
+  a.BACKPRESSURE]
+  );
+function E(e) {
+  return !!l.has(e);
+}
+function I(e, t = {}) {
+  const n = { retryable: t.retryable ?? E(e) };
+  t.details !== void 0 && (n.details = t.details);
+  const r = { code: e };
+  return t.message !== void 0 && (r.message = t.message), r.data = n, r;
+}
+
+/**
+ * JSON-RPC plumbing shared by both peers of the sf-embedding protocol.
+ *
+ * Two layers live here:
+ *
+ *  - `BridgeClient` — the OUTBOUND half plus inbound responses/notifications.
+ *    Extends the library `JsonRpcClient`, so it already correlates outbound
+ *    `send()` requests with their inbound responses, dispatches inbound
+ *    notifications to `onNotification` handlers, and stamps every outbound
+ *    frame with a `_meta.traceId`. It owns the single `Transport`.
+ *
+ *  - `JsonRpcRouter` — the INBOUND-REQUEST half. It HOLDS a `BridgeClient`
+ *    and adds the one thing the client deliberately lacks: routing inbound
+ *    JSON-RPC *requests* to registered handlers and replying success/error
+ *    on the same transport (echoing `_meta` for tracing). Notifications,
+ *    responses, and outbound traffic are delegated straight to the client —
+ *    no duplicate handler tables.
+ *
+ * Request vs response/notification dispatch does not collide on the shared
+ * transport: `JsonRpcClient` ignores frames carrying both an `id` and a
+ * `method` (requests), so the router is free to claim them.
+ *
+ * Each peer subclasses `JsonRpcRouter` (see `HostBridge` /
+ * `EmbeddingBridge`): the subclass registers its inbound handlers in the
+ * constructor and exposes named methods for its outbound requests.
+ */
+// makeJsonRpcError is the upstream factory; sf-embedding's NON_RETRYABLE_CODES wrapper
+// (in sf-embedding-bridge/src/errors.ts) is bypassed here because `utils` cannot depend
+// on the bridge package. A ratchet test in sf-embedding-contract guards the invariant
+// that NON_RETRYABLE_CODES never overlaps the upstream RETRYABLE set.
+function isRequestHandlerError(err) {
+  return err instanceof Error && typeof err.code === "number";
+}
+/**
+ * Outbound + response/notification half of a JSON-RPC peer, bound to one
+ * transport. Promotes the library client's `protected` send/notify/register
+ * methods to a `public` surface the router (and its subclasses) can call, and
+ * exposes `post`/`subscribe` so the router can reply to and listen for inbound
+ * requests over the same transport.
+ *
+ * Stamps `_meta.traceId` on every outbound frame; both peers want tracing.
+ */
+class BridgeClient extends b {
+
+  constructor(transport) {
+    super(transport);_defineProperty(this, "sharedTransport", void 0);
+    this.sharedTransport = transport;
+  }
+  /** Send a request and await its correlated response. */
+  send(method, params) {
+    return this.request(method, params);
+  }
+  /** Send a fire-and-forget notification. */
+  notify(method, params) {
+    this.sendNotification(method, params);
+  }
+  /** Register an inbound-notification handler. */
+  onNotification(method, handler) {
+    this.registerNotificationHandler(method, handler);
+  }
+  /** @internal — used by JsonRpcRouter to reply to inbound requests. */
+  post(frame) {
+    this.sharedTransport.post(frame);
+  }
+  /** @internal — used by JsonRpcRouter to claim inbound requests. */
+  subscribe(callback) {
+    return this.sharedTransport.onMessage(callback);
+  }
+  /** Tear down the underlying transport if it is disposable (e.g. MessageChannelTransport closes its port). */
+  dispose() {
+    const transport = this.sharedTransport;
+    if (typeof transport.dispose === "function") {
+      transport.dispose();
+    }
+  }
+  /** Mints `_meta.traceId` for every outbound request and notification. */
+  getOutboundMeta(_method) {
+    return { traceId: crypto.randomUUID() };
+  }
+}
+/**
+ * Inbound-request router. Holds a `BridgeClient` for everything else
+ * (outbound requests/notifications, inbound responses, inbound notifications)
+ * and adds inbound-request routing + replies on the shared transport.
+ *
+ * Subclass it per peer: register handlers in the constructor, add named
+ * outbound methods that call `send`/`notify`.
+ */
+class JsonRpcRouter {
+
+
+
+
+  constructor(client, log = () => {}) {_defineProperty(this, "client", void 0);_defineProperty(this, "requestHandlers", new Map());_defineProperty(this, "log", void 0);_defineProperty(this, "unsubscribe", null);
+    this.client = client;
+    this.log = log;
+    // Claim inbound *requests*; the client already handles responses and
+    // notifications on the same transport and ignores request frames.
+    this.unsubscribe = this.client.subscribe((data) => this.handle(data));
+  }
+  /** Register a handler for an inbound request method. Returns a disposer; re-registering overwrites. */
+  onRequest(method, handler) {
+    this.requestHandlers.set(method, handler);
+    return () => {
+      if (this.requestHandlers.get(method) === handler) {
+        this.requestHandlers.delete(method);
+      }
+    };
+  }
+  /** Register an inbound-notification handler (delegates to the client). */
+  onNotification(method, handler) {
+    this.client.onNotification(method, handler);
+  }
+  /** Send an outbound request and await its response (delegates to the client). */
+  send(method, params) {
+    return this.client.send(method, params);
+  }
+  /** Send an outbound notification (delegates to the client). */
+  notify(method, params) {
+    this.client.notify(method, params);
+  }
+  /**
+   * Tear down: drop the inbound-request subscription, clear handlers, and
+   * dispose the client's transport (closes the port). Idempotent.
+   */
+  dispose() {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    this.requestHandlers.clear();
+    this.client.dispose();
+  }
+  /** Route one inbound frame. Only requests are handled here; the rest is the client's. */
+  handle(data) {
+    if (!m(data))
+    return;
+    this.handleRequest(data);
+  }
+  handleRequest(req) {
+    const handler = this.requestHandlers.get(req.method);
+    if (!handler) {
+      this.respondError(req.id, a.METHOD_NOT_FOUND, `Method not found: ${req.method}`, req._meta);
+      return;
+    }
+    Promise.resolve().
+    then(() => handler(req.params, req._meta)).
+    then((result) => this.respondSuccess(req.id, result, req._meta), (err) => {
+      const code = isRequestHandlerError(err) ? err.code : a.INTERNAL_ERROR;
+      const message = err instanceof Error ? err.message : String(err);
+      this.respondError(req.id, code, message, req._meta);
+    });
+  }
+  respondSuccess(id, result, meta) {
+    const frame = { jsonrpc: "2.0", id, result };
+    if (meta)
+    frame._meta = meta;
+    this.postSafely(frame);
+  }
+  respondError(id, code, message, meta) {
+    const frame = {
+      jsonrpc: "2.0",
+      id,
+      error: I(code, { message })
+    };
+    if (meta)
+    frame._meta = meta;
+    this.postSafely(frame);
+  }
+  postSafely(frame) {
+    try {
+      this.client.post(frame);
+    }
+    catch (err) {
+      // Transport.post should not throw on transient failure, but guard so a
+      // misbehaving transport can't take down request handling.
+      this.log("response post threw —", err);
+    }
+  }
+}
+
+export { BridgeClient, JsonRpcRouter };

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

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+import { DEFAULT_SANDBOX_TOKENS } from "./constants";
+
+export function computeSandboxTokens(addList, removeList) {
+    const tokens = new Set(DEFAULT_SANDBOX_TOKENS);
+
+    if (addList) {
+        for (const t of addList.split(/\s+/).filter(Boolean)) tokens.add(t);
+    }
+    if (removeList) {
+        for (const t of removeList.split(/\s+/).filter(Boolean)) {
+            if (tokens.has(t)) {
+                tokens.delete(t);
+            } else {
+                window.console.warn(
+                    `[lightning-ui-embedding] removeSandboxTokens: '${t}' was not in the resolved sandbox; ignored.`,
+                );
+            }
+        }
+    }
+
+    return Array.from(tokens).join(" ");
+}

package/dist/modules/lightning/uiEmbedding/utils/sf-embedding-contract.js

@@ -0,0 +1,66 @@
+function _defineProperty(e, r, t) {return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e;}function _toPropertyKey(t) {var i = _toPrimitive(t, "string");return "symbol" == typeof i ? i : i + "";}function _toPrimitive(t, r) {if ("object" != typeof t || !t) return t;var e = t[Symbol.toPrimitive];if (void 0 !== e) {var i = e.call(t, r || "default");if ("object" != typeof i) return i;throw new TypeError("@@toPrimitive must return a primitive value.");}return ("string" === r ? String : Number)(t);} // Bootstrap envelope vocabulary. Spec: EMBEDDING-PROTOCOL.md §3.1, §3.1.1,
+// MC-7/MC-8/MC-10 in §2.2.
+/** Wire identifier for this protocol. Carried verbatim on every bootstrap envelope. */
+const PROTOCOL_NAME = "sf-embedding";
+/** Discriminator for the host → embedding bootstrap envelope. */
+const BOOTSTRAP_ENVELOPE_TYPE = "sf-embedding.bootstrap";
+/** Discriminator for the embedding → host content-free heartbeat. */
+const HEARTBEAT_TYPE = "sf-embedding/ready";
+/**
+ * Discriminator for the embedding → host fail-closed shutdown signal
+ * (e.g., duplicate-transfer detection). Posted via window-level postMessage,
+ * not over the JSON-RPC port.
+ */
+const SHUTDOWN_TYPE = "sf-embedding/shutdown";
+
+// Bidirectional custom-event channel.
+const EVENTS_DISPATCH_METHOD = "ui/events/dispatch";
+const EVENTS_SUBSCRIBE_METHOD = "ui/events/subscribe";
+const EVENTS_UNSUBSCRIBE_METHOD = "ui/events/unsubscribe";
+
+// Host LWC reserved DOM event names and detail shapes. Spec §12.3.
+//
+// These are dispatched by the host LWC on its own element so application
+// code on the page can react. The embedding never observes them.
+/** Event names the host LWC dispatches on its own element. Reserved by the protocol. */
+const HostLwcEvent = {
+  /** Synchronous with `ui/discover-capabilities` response; session reaches READY. */
+  READY: "sf-embedding.component.ready",
+  /** Misconfiguration, bootstrap failure, embedding-reported fatal, or protocol violation. */
+  ERROR: "sf-embedding.component.error"
+};
+
+// Host-supplied iframe URL metadata (per ADR 0029). Spec §3.1, MC-8/MC-10.
+/** URL query-parameter name carrying the JSON-encoded `HostMetaData`. */
+const HOST_META_DATA_PARAM = "hostMetaData";
+
+// Shared error class for inbound-request handlers on either side of the wire.
+// Routers translate it into a JSON-RPC error response with the carried `code`;
+// any other thrown value falls back to INTERNAL_ERROR (-32603).
+/** Throw from a request handler to surface a specific JSON-RPC error code. */
+class JsonRpcHandlerError extends Error {
+
+  constructor(code, message) {
+    super(message);_defineProperty(this, "code", void 0);
+    this.code = code;
+    this.name = "JsonRpcHandlerError";
+  }
+}
+
+// JSON-RPC method names on the wire today.
+/** Host announces session identity to the embedding over the port. */
+const HOST_INITIALIZED_METHOD = "ui/notifications/host-initialized";
+/** Embedding acknowledges receipt of `host-initialized`. Fire-and-forget. */
+const EMBEDDING_INITIALIZED_METHOD = "ui/notifications/embedding-initialized";
+/** Iframe-side error notification. Fire-and-forget, non-PII observability signal. */
+const ERROR_METHOD = "ui/notifications/error";
+
+// Resize hint channel: embedding → host, fire-and-forget. CSS pixels.
+const RESIZE_METHOD = "ui/notifications/resize";
+
+// UI-state subscription axis. Snapshot in subscribe response; full-replacement change pushes.
+const UI_STATE_SUBSCRIBE_METHOD = "ui/subscribe/ui-state";
+const UI_STATE_UNSUBSCRIBE_METHOD = "ui/unsubscribe/ui-state";
+const UI_STATE_CHANGED_METHOD = "ui/notifications/ui-state-changed";
+
+export { BOOTSTRAP_ENVELOPE_TYPE, EMBEDDING_INITIALIZED_METHOD, ERROR_METHOD, EVENTS_DISPATCH_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, HEARTBEAT_TYPE, HOST_INITIALIZED_METHOD, HOST_META_DATA_PARAM, HostLwcEvent, JsonRpcHandlerError, PROTOCOL_NAME, RESIZE_METHOD, SHUTDOWN_TYPE, UI_STATE_CHANGED_METHOD, UI_STATE_SUBSCRIBE_METHOD, UI_STATE_UNSUBSCRIBE_METHOD };

package/dist/modules/lightning/uiEmbedding/utils/ui-state.js

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+// UiState snapshot composition. Reads from @api props, data-*, mirrored attrs, inline style (--*).
+
+/** Mirrored attributes read off the host LWC element. */
+export const MIRRORED_ATTRIBUTES = [
+    "autocapitalize",
+    "autocorrect",
+    "dir",
+    "enterkeyhint",
+    "inputmode",
+    "lang",
+    "spellcheck",
+    "title",
+    "translate",
+];
+
+/** Convert kebab-case to camelCase: `record-id` → `recordId`. */
+function kebabToCamel(name) {
+    return name.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+
+/** Read `data-*` attributes; strip prefix; convert kebab to camel. Tolerates non-Element host. */
+export function readDataAttributes(element) {
+    const out = {};
+    if (!element || !element.attributes) return out;
+    for (const attr of element.attributes) {
+        if (attr.name.startsWith("data-")) {
+            const key = kebabToCamel(attr.name.slice("data-".length));
+            out[key] = attr.value;
+        }
+    }
+    return out;
+}
+
+/** Read CSS custom-property values off the element's inline style. */
+export function readCssVariables(element) {
+    const out = {};
+    if (!element || !element.style) return out;
+    const style = element.style;
+    for (let i = 0; i < style.length; i++) {
+        const name = style.item(i);
+        if (name.startsWith("--")) {
+            out[name] = style.getPropertyValue(name).trim();
+        }
+    }
+    return out;
+}
+
+/** Read the mirrored attribute set off the element. Skips absent attributes. */
+export function readMirroredAttributes(element) {
+    const out = {};
+    if (!element || typeof element.getAttribute !== "function") return out;
+    for (const name of MIRRORED_ATTRIBUTES) {
+        const value = element.getAttribute(name);
+        if (value !== null) out[name] = value;
+    }
+    return out;
+}
+
+/** `@api props` wins over `data-*` on collision (typed beats string). */
+export function composeUiState(input) {
+    const dataProps = readDataAttributes(input.hostElement);
+    const attributes = readMirroredAttributes(input.hostElement);
+    const variables = readCssVariables(input.hostElement);
+    const props = { ...dataProps, ...input.apiProps };
+
+    const styles = {};
+    if (Object.keys(variables).length > 0) styles.variables = variables;
+    if (Object.keys(attributes).length > 0) styles.attributes = attributes;
+
+    return { props, styles };
+}

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

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+import { HOST_META_DATA_PARAM } from "./sf-embedding-contract";
+
+export function parseOrigin(src) {
+    try {
+        return new URL(src).origin;
+    } catch {
+        return null;
+    }
+}
+
+export function appendHostMetaData(src, instanceId, hostAppOrigin) {
+    const url = new URL(src);
+    const meta = { instanceId, hostAppOrigin };
+    url.searchParams.set(HOST_META_DATA_PARAM, JSON.stringify(meta));
+    return url.href;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@salesforce-ui-embedding/internal-lightning-ui-embedding",
+    "version": "2.2.7-rc.2",
+    "private": false,
+    "description": "Lightning Base Component (LWC) host for sf-embedding-protocol iframes",
+    "license": "SEE LICENSE IN LICENSE.txt",
+    "author": "Salesforce ECS Team",
+    "type": "module",
+    "files": [
+        "dist/",
+        "!dist/__tests__/",
+        "!dist/__mocks__/",
+        "!dist/*.test.js",
+        "!dist/*.map",
+        "LICENSE.txt"
+    ],
+    "scripts": {
+        "build": "node scripts/build.mjs",
+        "typecheck": "tsc --noEmit",
+        "test": "jest --passWithNoTests",
+        "clean": "rimraf dist"
+    },
+    "devDependencies": {
+        "@salesforce/jsonrpc": "^10.12.3",
+        "@salesforce/sf-embedding-contract": "2.2.7-rc.2",
+        "utils": "2.2.7-rc.2"
+    },
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    }
+}