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

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

@@ -0,0 +1,965 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+import { api, LightningElement } from "lwc";
+
+import { buildBootstrapEnvelope, validateHeartbeat, validateShutdown } from "./utils/bootstrap";
+import { DEFAULT_HEARTBEAT_TIMEOUT_MS, ERROR_CODES, ERROR_PHASES, STATES } from "./utils/constants";
+import { HostBridge } from "./utils/host-bridge";
+import { HOST_INFO } from "./utils/host-info";
+import { createInstrumentation } from "./utils/instrumentation";
+import { createLogger } from "./utils/log";
+import { computeSandboxTokens } from "./utils/sandbox";
+import {
+    EVENTS_DISPATCH_METHOD,
+    EVENTS_SUBSCRIBE_METHOD,
+    EVENTS_UNSUBSCRIBE_METHOD,
+    HEARTBEAT_TYPE,
+    HostLwcEvent,
+    RESIZE_METHOD,
+    SHUTDOWN_TYPE,
+    UI_STATE_CHANGED_METHOD,
+    UI_STATE_SUBSCRIBE_METHOD,
+    UI_STATE_UNSUBSCRIBE_METHOD,
+} from "./utils/sf-embedding-contract";
+import { composeUiState, MIRRORED_ATTRIBUTES } from "./utils/ui-state";
+import { appendHostMetaData, parseOrigin } from "./utils/url";
+
+/** Stable reference for null/undefined `props` so the setter's `===` guard can short-circuit. */
+const EMPTY_PROPS = Object.freeze({});
+
+/** Reserved event names that must never be forwarded (component's own outbound events). */
+const RESERVED_EVENT_NAMES = new Set([HostLwcEvent.READY, HostLwcEvent.ERROR]);
+
+/**
+ * Normalize event.detail for MessageChannel: JSON round-trip an object to strip LWC/LWS membrane
+ * proxies that fail structured-clone. Strings and other primitives pass through untouched (no auto-parse).
+ *
+ * @remarks Intentional JSON-only contract — structuredClone is NOT usable here (it throws DataCloneError on the
+ * membrane proxy identically to postMessage; the round-trip reads through the proxy via property gets). The contract
+ * is lossy for out-of-band types: Date→ISO string, Map/Set→{}, undefined/functions/symbols dropped, NaN/Infinity→null,
+ * BigInt/circular refs throw (caught + logged as EVENT_FORWARD_FAILED, forward skipped, local dispatch still fires).
+ * Dispatch only primitives + plain objects in CustomEvent detail.
+ */
+function toCloneableDetail(detail) {
+    if (detail !== null && typeof detail === "object") {
+        return JSON.parse(JSON.stringify(detail));
+    }
+    return detail;
+}
+
+export default class Embedding extends LightningElement {
+    _iframe = null;
+    _container = null;
+    _frameShadow = null;
+    _iframeCreated = false;
+
+    _currentState = STATES.PRE_HEARTBEAT;
+    _instanceId = crypto.randomUUID();
+    _debugEnabled = false;
+    _log = createLogger("[lightning-ui-embedding]", () => this._debugEnabled);
+
+    _channel = null;
+    _hostPort = null;
+    _portTransferred = false;
+    _heartbeatHandler = null;
+
+    // True once the iframe element has fired at least one `load` event on the current channel.
+    // Reset in `_resetChannel`. Paired with `_portTransferred` to discriminate a real full-doc-nav
+    // reload from the initial-bootstrap load that fires AFTER the embedded document's heartbeat.
+    //
+    // Why this matters: when the embedded app uses the Platform SDK, the SDK defers its heartbeat
+    // until DOMContentLoaded, so the parent's `load` task is queued before the SDK's `message`
+    // task and the natural order holds. But the protocol is also documented as plain
+    // `postMessage`-friendly so integrators (e.g. DVAG, who asked us to support this) can embed
+    // without the SDK — an inline `<script>` in the document head can call
+    // `parent.postMessage("sf-embedding/ready", …)` during HTML parse, long before the iframe's
+    // `load` event fires at the parent. The parent's event loop is then free to process the
+    // queued `message` task before the queued `load` task, so the very first `load` arrives with
+    // the port already transferred.
+    _initialLoadConsumed = false;
+
+    // Infinity disables the deadline; AbortController allows active cancellation.
+    _heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    _heartbeatController = null;
+
+    _src = null;
+    _iframeSrcOrigin = null;
+    _sandbox = null;
+    _removeSandboxTokens = null;
+    _title = "Embedded widget";
+
+    _bridge = null;
+    _negotiatedProtocolVersion = null;
+
+    // UiState provider state. The active wire subscription itself lives on the
+    // HostBridge (it owns the inbound subscribe/unsubscribe requests); the
+    // component owns the snapshot content and change detection below.
+    _props = EMPTY_PROPS;
+    _mutationObserver = null;
+    _uiStateFlushScheduled = false;
+
+    /** Re-entrancy guard: tracks the specific event objects we're re-dispatching from the embedding,
+     * so the override below skips only those (not unrelated events fired by listeners during the same task). */
+    _inboundDispatches = new WeakSet();
+    _forwardTarget = null;
+    _originalDispatchEvent = null;
+
+    // Instrumentation
+    _instrumentation = null;
+    _loadActivity = null;
+    _loadActivityStopped = false;
+    _activityStartedAt = 0;
+
+    @api
+    get src() {
+        return this._src;
+    }
+    set src(value) {
+        const val = value || null;
+        if (this._src === val) return;
+        if (!this._canMutateSessionBinding("src")) return;
+        this._src = val;
+        this._iframeSrcOrigin = val ? parseOrigin(val) : null;
+        this._updateIframeSrc();
+    }
+
+    @api
+    get sandbox() {
+        return this._sandbox;
+    }
+    set sandbox(value) {
+        const val = value || null;
+        if (this._sandbox === val) return;
+        if (!this._canMutateSessionBinding("sandbox")) return;
+        this._sandbox = val;
+        this._applySandbox();
+    }
+
+    @api
+    get removeSandboxTokens() {
+        return this._removeSandboxTokens;
+    }
+    set removeSandboxTokens(value) {
+        const val = value || null;
+        if (this._removeSandboxTokens === val) return;
+        if (!this._canMutateSessionBinding("removeSandboxTokens")) return;
+        this._removeSandboxTokens = val;
+        this._applySandbox();
+    }
+
+    @api
+    get props() {
+        return this._props;
+    }
+    set props(value) {
+        // Reference equality: authors must assign a new object to trigger ui-state-changed.
+        // null/undefined coerce to the shared EMPTY_PROPS sentinel so repeated unsets are a no-op.
+        const next = value ?? EMPTY_PROPS;
+        if (this._props === next) return;
+        this._props = next;
+        this._scheduleUiStateFlush();
+    }
+
+    @api
+    get title() {
+        return this._title;
+    }
+    set title(value) {
+        this._title = value || "embedding";
+        this._reflectHostTitle();
+        this._updateTitle();
+    }
+
+    @api
+    get debug() {
+        return this._debugEnabled;
+    }
+    set debug(value) {
+        this._debugEnabled = !!value;
+    }
+
+    // Positive number arms the deadline; Infinity disables it; anything else uses the default.
+    // Advisory only — fires sf-embedding.component.error / HEARTBEAT_TIMEOUT, no teardown.
+    @api
+    get heartbeatTimeoutMs() {
+        return this._heartbeatTimeoutMs;
+    }
+    set heartbeatTimeoutMs(value) {
+        if (typeof value !== "number" || Number.isNaN(value) || value <= 0) {
+            this._heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS;
+        } else {
+            this._heartbeatTimeoutMs = value === Infinity ? Infinity : Math.floor(value);
+        }
+        if (this._heartbeatController) {
+            this._armHeartbeatDeadline();
+        }
+    }
+
+    @api
+    get bootstrapPhase() {
+        return this._currentState;
+    }
+
+    @api
+    get resolvedSandbox() {
+        return computeSandboxTokens(this._sandbox, this._removeSandboxTokens);
+    }
+
+    get currentState() {
+        return this._currentState;
+    }
+
+    connectedCallback() {
+        this._installHeartbeatListener();
+        this._installMutationObserver();
+        this._installHostDispatchOverride();
+        this._instrumentation = createInstrumentation("LightningUiEmbedding", this._src, window.location.origin);
+        this._startLoadActivity();
+        this._log("connectedCallback");
+    }
+
+    renderedCallback() {
+        if (this._iframeCreated) return;
+        this._iframeCreated = true;
+
+        this._container = this.template.querySelector(".container");
+        if (!this._container) return;
+
+        const configError = this._validateConfiguration();
+        if (configError) {
+            this._instrumentation?.incrementCounter("sfembedding.config.validation_failed", 1, true, {
+                reason: configError.code,
+            });
+            this._error(ERROR_PHASES.CONFIGURATION, configError.code, configError.message, STATES.CLOSED);
+            return;
+        }
+
+        this._frameShadow = this._container.attachShadow({ mode: "closed" });
+        const innerStyle = document.createElement("style");
+        innerStyle.textContent = `
+            .frame {
+                visibility: var(--frame-visibility, hidden);
+                display: block;
+                width: 100%;
+                height: 100%;
+                border: none;
+            }
+        `;
+        this._frameShadow.appendChild(innerStyle);
+
+        const frame = document.createElement("iframe");
+        frame.className = "frame";
+        frame.title = this._title;
+        frame.addEventListener("load", () => this._handleIframeLoad());
+
+        this._frameShadow.appendChild(frame);
+        this._iframe = frame;
+
+        this._applySandbox();
+        this._updateIframeSrc();
+
+        this._log("renderedCallback: iframe ready");
+    }
+
+    // src/sandbox/removeSandboxTokens are session-binding — read at mount, MUST NOT
+    // be mutated mid-instance. Post-mount changes are an unmount/remount boundary, so we reject
+    // them with a configuration error rather than silently re-rendering.
+    _canMutateSessionBinding(prop) {
+        if (!this._iframeCreated) return true;
+        this._instrumentation?.incrementCounter("sfembedding.session_binding.mutation_rejected", 1, true, {
+            property: prop,
+        });
+        this._error(
+            ERROR_PHASES.CONFIGURATION,
+            ERROR_CODES.SESSION_BINDING_MUTATED,
+            `'${prop}' is session-binding; remount the component to change it.`,
+        );
+        return false;
+    }
+
+    _validateConfiguration() {
+        const tokens = computeSandboxTokens(this._sandbox, this._removeSandboxTokens).split(" ");
+        if (!tokens.includes("allow-scripts")) {
+            return {
+                code: ERROR_CODES.ALLOW_SCRIPTS_STRIPPED,
+                message: "iframe sandbox MUST include 'allow-scripts'; embedding cannot run without it.",
+            };
+        }
+        if (tokens.includes("allow-top-navigation")) {
+            return {
+                code: ERROR_CODES.BLOCKED_SANDBOX_TOKEN,
+                message: "iframe sandbox MUST NOT include 'allow-top-navigation'; poses phishing risk.",
+            };
+        }
+        if (tokens.includes("allow-popups-to-escape-sandbox")) {
+            return {
+                code: ERROR_CODES.BLOCKED_SANDBOX_TOKEN,
+                message: "iframe sandbox MUST NOT include 'allow-popups-to-escape-sandbox'; poses security risk.",
+            };
+        }
+        if (!this._src) {
+            return {
+                code: ERROR_CODES.MISSING_SRC,
+                message: "iframe src MUST be provided; the embedding cannot start without a src.",
+            };
+        }
+        if (!this._iframeSrcOrigin) {
+            return {
+                code: ERROR_CODES.INVALID_SRC,
+                message: "iframe src MUST be a parseable URL.",
+            };
+        }
+        if (this._iframeSrcOrigin === window.location.origin) {
+            return {
+                code: ERROR_CODES.SAME_ORIGIN_SRC,
+                message: "iframe src origin MUST differ from the host document origin.",
+            };
+        }
+        return null;
+    }
+
+    /**
+     * Single error entry point. Reports exactly one uxerr — scoped to the open embedding_init span
+     * (which also counts embedding.init.error) when one is active, otherwise a standalone log —
+     * fires the public ERROR event, and logs. `code` doubles as the telemetry errorType. Pass
+     * `nextState` (e.g. STATES.CLOSED) to transition the instance. Pass `details.retryable = true`
+     * for transient errors where the embedding may recover (e.g. heartbeat timeout).
+     */
+    _error(phase, code, message, nextState, details) {
+        if (nextState) this._currentState = nextState;
+
+        if (!this._loadActivityStopped && this._loadActivity) {
+            this._errorLoadActivity(new Error(message), code);
+        }
+
+        // Error telemetry: phase/code/message only (PII-safe — no params.props).
+        this._instrumentation?.logError(new Error(message), { phase, code, instanceId: this._instanceId });
+
+        this.dispatchEvent(
+            // eslint-disable-next-line @sfdc-internal/lightning-base-components/no-custom-event-identifier-arguments
+            new CustomEvent(HostLwcEvent.ERROR, {
+                detail: { instanceId: this._instanceId, phase, code, message, retryable: details?.retryable ?? false },
+                bubbles: true,
+                composed: true,
+            }),
+        );
+
+        this._log(`${code} —`, message);
+    }
+
+    disconnectedCallback() {
+        // TODO: host-initiated teardown: send ui/notifications/shutdown + 500ms drain before close.
+        this._cancelHeartbeatDeadline();
+        if (this._heartbeatHandler) {
+            window.removeEventListener("message", this._heartbeatHandler);
+            this._heartbeatHandler = null;
+        }
+        if (this._mutationObserver) {
+            this._mutationObserver.disconnect();
+            this._mutationObserver = null;
+        }
+        this._restoreOriginalDispatchEvent();
+        // A pending microtask flush isn't cancellable, but `_closeHostBridge` nulls `_bridge` so the flush no-ops.
+        this._closeHostBridge();
+        this._channel = null;
+        this._container = null;
+        this._currentState = STATES.CLOSED;
+        this._frameShadow = null;
+        this._iframe = null;
+        this._iframeCreated = false;
+        this._initialLoadConsumed = false;
+        this._loadActivity = null;
+        this._loadActivityStopped = true;
+        this._portTransferred = false;
+        this._log("disconnectedCallback");
+    }
+
+    _closeHostBridge() {
+        if (this._bridge) {
+            // Disposing the bridge clears handlers, drops the subscription, and
+            // disposes the transport — which closes the port (idempotent).
+            this._bridge.dispose();
+            this._bridge = null;
+            this._hostPort = null;
+            return;
+        }
+        // No bridge yet (port created but never opened): close the raw port.
+        if (!this._hostPort) return;
+        try {
+            this._hostPort.close();
+        } catch (err) {
+            // ignore — already-closed ports throw on some runtimes.
+            this._instrumentation?.logError(err, { code: "PORT_CLOSE_FAILED", instanceId: this._instanceId });
+        }
+        this._hostPort = null;
+    }
+
+    _installHeartbeatListener() {
+        const handler = (event) => this._handleWindowMessage(event);
+        this._heartbeatHandler = handler;
+        window.addEventListener("message", handler);
+    }
+
+    // New src / new logical session: re-mint instanceId and rebuild the channel.
+    _resetSession() {
+        this._instanceId = crypto.randomUUID();
+        this._instrumentation?.incrementCounter("sfembedding.session.reset", 1, false);
+        this._resetChannel();
+    }
+
+    // Same logical session, new iframe document: rebuild channel state only; instanceId is
+    // stable so validateHeartbeat's expectedInstanceId check still passes.
+    _resetChannel() {
+        const prevState = this._currentState;
+        this._instrumentation?.incrementCounter("sfembedding.channel.reset", 1, false, { from: String(prevState) });
+        this._cancelHeartbeatDeadline();
+        this._closeHostBridge();
+        this._channel = new MessageChannel();
+        this._hostPort = this._channel.port2;
+        this._portTransferred = false;
+        this._initialLoadConsumed = false;
+        this._negotiatedProtocolVersion = null;
+        this._currentState = STATES.PRE_HEARTBEAT;
+    }
+
+    _handleIframeLoad() {
+        if (!this._iframeCreated) return;
+        // Both flags must be set to identify a real full-doc-nav reload. `_portTransferred` alone
+        // isn't enough: the embedded document can heartbeat before the iframe element's `load`
+        // task fires, so the very first `load` may arrive with the port already transferred.
+        if (this._initialLoadConsumed && this._portTransferred) {
+            this._log("iframe load: subsequent (full-doc nav) — rebuilding channel for instanceId", this._instanceId);
+            this._instrumentation?.incrementCounter("sfembedding.iframe.reload", 1, false);
+            this._resetChannel();
+        }
+        this._initialLoadConsumed = true;
+        // If the heartbeat won the race the deadline is already cancelled and the channel is READY;
+        // re-arming would re-open a closed deadline window for no reason.
+        if (!this._portTransferred) {
+            this._armHeartbeatDeadline();
+        }
+    }
+
+    // Advisory deadline; expiry fires an error event but never tears down state.
+    _armHeartbeatDeadline() {
+        this._cancelHeartbeatDeadline();
+        const ms = this._heartbeatTimeoutMs;
+        if (!Number.isFinite(ms)) return;
+        const timeout = this._safeTimeoutSignal(ms);
+        if (!timeout) return;
+
+        const controller = new AbortController();
+        this._heartbeatController = controller;
+
+        // Pin identity so a later src/session reset doesn't mis-attribute this timeout.
+        const snapshotSrc = this._src;
+        const snapshotInstanceId = this._instanceId;
+
+        const combined = this._anySignal([controller.signal, timeout]);
+        combined.addEventListener(
+            "abort",
+            () => {
+                if (controller.signal.aborted) return;
+                if (this._portTransferred) return;
+                if (this._src !== snapshotSrc) return;
+                if (this._instanceId !== snapshotInstanceId) return;
+                const message = `Embedded document did not send sf-embedding/ready heartbeat within ${ms}ms`;
+                this._instrumentation?.incrementCounter("sfembedding.heartbeat.timeout", 1, true);
+                this._error(ERROR_PHASES.BOOTSTRAP, ERROR_CODES.HEARTBEAT_TIMEOUT, message, undefined, {
+                    retryable: true,
+                });
+            },
+            { once: true },
+        );
+    }
+
+    _cancelHeartbeatDeadline() {
+        if (this._heartbeatController) {
+            this._heartbeatController.abort();
+            this._heartbeatController = null;
+        }
+    }
+
+    // AbortSignal.timeout is used over setTimeout to satisfy @lwc/lwc/no-async-operation.
+    _anySignal(signals) {
+        const AS = AbortSignal;
+        if (typeof AS.any === "function") {
+            return AS.any(signals);
+        }
+        return signals[signals.length - 1];
+    }
+
+    _safeTimeoutSignal(ms) {
+        const AS = AbortSignal;
+        if (typeof AS.timeout === "function") {
+            return AS.timeout(ms);
+        }
+        return null;
+    }
+
+    _handleWindowMessage(event) {
+        const iframe = this._iframe;
+        const channel = this._channel;
+        if (!iframe || !channel) return;
+
+        const type = event.data?.type;
+        if (type === HEARTBEAT_TYPE) {
+            this._handleHeartbeat(event, iframe, channel);
+        } else if (type === SHUTDOWN_TYPE) {
+            this._handleShutdown(event, iframe);
+        }
+    }
+
+    _handleHeartbeat(event, iframe, channel) {
+        const result = validateHeartbeat({
+            data: event.data,
+            source: event.source,
+            origin: event.origin,
+            expectedSource: iframe.contentWindow,
+            expectedOrigin: this._iframeSrcOrigin,
+            expectedInstanceId: this._instanceId,
+            alreadyTransferred: this._portTransferred,
+        });
+
+        if (!result.ok) {
+            if (result.reason === ERROR_CODES.WRONG_SOURCE) {
+                this._countWrongSource("heartbeat", event.origin);
+                return;
+            }
+            const messages = {
+                WRONG_ORIGIN: `heartbeat origin '${event.origin}' does not match the expected iframe src origin '${this._iframeSrcOrigin ?? "<unset>"}'`,
+                PROTOCOL_VERSION_MISMATCH: `declared version '${result.protocolVersion ?? "<missing>"}' is not supported by host`,
+                INSTANCE_ID_MISMATCH: "heartbeat instanceId does not match the host-minted session instanceId",
+                DUPLICATE: "heartbeat received after port1 was already transferred",
+            };
+            const message = messages[result.reason] ?? `heartbeat rejected: ${result.reason}`;
+            this._instrumentation?.incrementCounter("sfembedding.heartbeat.rejected", 1, true, {
+                reason: result.reason,
+            });
+            this._error(ERROR_PHASES.BOOTSTRAP, result.reason, message);
+            return;
+        }
+
+        this._negotiatedProtocolVersion = result.protocolVersion;
+        this._log("heartbeat: negotiated protocol version", result.protocolVersion);
+
+        // Initialize the host bridge before transferring port1 — host end live before embedding can post back.
+        this._initializeHostBridge();
+
+        const envelope = buildBootstrapEnvelope({
+            instanceId: this._instanceId,
+            allowedOrigins: this._iframeSrcOrigin ? [this._iframeSrcOrigin] : [],
+        });
+
+        try {
+            iframe.contentWindow.postMessage(envelope, this._iframeSrcOrigin, [channel.port1]);
+        } catch (err) {
+            // Transfer threw (e.g. detached contentWindow); close the started port that has no peer.
+            this._instrumentation?.incrementCounter("sfembedding.bootstrap.transfer_failed", 1, true);
+            this._cancelHeartbeatDeadline();
+            this._closeHostBridge();
+            this._error(
+                ERROR_PHASES.BOOTSTRAP,
+                ERROR_CODES.TRANSFER_FAILED,
+                `<iframe> port transfer threw. Error: ${err instanceof Error ? err.message : String(err)}`,
+                STATES.CLOSED,
+            );
+            return;
+        }
+
+        this._portTransferred = true;
+        this._cancelHeartbeatDeadline();
+        this._instrumentation?.incrementCounter("sfembedding.heartbeat.received", 1, false, {
+            protocolVersion: result.protocolVersion,
+        });
+        this._currentState = STATES.POST_HEARTBEAT;
+        this._log("heartbeat: validated, port1 transferred");
+
+        // Phase A approximation: transition to READY now, before sending host-initialized.
+        // Once ui/select-version and ui/discover-capabilities land, READY will fire
+        // synchronously with the discover-capabilities response.
+        this._currentState = STATES.READY;
+
+        this._completeLoadActivity();
+
+        this.dispatchEvent(
+            // eslint-disable-next-line @sfdc-internal/lightning-base-components/no-custom-event-identifier-arguments
+            new CustomEvent(HostLwcEvent.READY, {
+                detail: { instanceId: this._instanceId },
+                bubbles: true,
+                composed: true,
+            }),
+        );
+
+        this._announceHostInitialized();
+    }
+
+    _initializeHostBridge() {
+        const port = this._hostPort;
+        if (!port) return;
+
+        // The bridge wraps the port in the shared transport and subscribes,
+        // which lazily starts the port (no manual addEventListener/start here).
+        // The bridge owns the ui/subscribe + ui/unsubscribe routing, the events
+        // subscribe/unsubscribe registry, and the resize-hint notification; it
+        // calls back into _composeUiState() for the snapshot returned on
+        // subscribe, _redispatchEventFromEmbedding() for inbound
+        // `ui/events/dispatch`, and _handleResizeHint() for `ui/notifications/resize`.
+        this._bridge = new HostBridge(
+            port,
+            () => this._composeUiState(),
+            (params) => this._redispatchEventFromEmbedding(params),
+            (params) => this._handleResizeHint(params),
+            (params) => this._handleSfEmbeddingError(params),
+            (...args) => this._log(...args),
+            this._instrumentation,
+        );
+    }
+
+    /** Pipe iframe errors to o11y (non-PII). */
+    _handleSfEmbeddingError(params) {
+        if (!params) return;
+        // Clamp untrusted iframe-supplied type/sdkMethod to bounded values before tagging (cardinality guard).
+        const KNOWN_ERROR_TYPES = [
+            "javascript-error",
+            "unhandled-rejection",
+            "rpc-failed",
+            "session-aborted",
+            "bootstrap-failed",
+        ];
+
+        const KNOWN_SDK_METHODS = [
+            "uncaught",
+            "bootstrapSession",
+            UI_STATE_SUBSCRIBE_METHOD,
+            UI_STATE_UNSUBSCRIBE_METHOD,
+            EVENTS_SUBSCRIBE_METHOD,
+            EVENTS_UNSUBSCRIBE_METHOD,
+            EVENTS_DISPATCH_METHOD,
+            RESIZE_METHOD,
+        ];
+
+        const boundedType = KNOWN_ERROR_TYPES.includes(params.type) ? params.type : "other";
+        const boundedSdkMethod = KNOWN_SDK_METHODS.includes(params.sdkMethod) ? params.sdkMethod : "other";
+
+        this._log("embedding-error", params.type, params.sdkMethod, params.filename ?? "");
+        const err = new Error(boundedType);
+        err.name = boundedType;
+        this._instrumentation?.logError(err, {
+            instanceId: this._instanceId,
+            sdkMethod: boundedSdkMethod,
+            type: boundedType,
+            isHostError: false,
+        });
+        this._instrumentation?.incrementCounter("embedding.sdk.error", 1, true, { type: boundedType });
+    }
+
+    /** Apply an inbound `ui/notifications/resize` hint directly to the iframe. */
+    _handleResizeHint(params) {
+        if (!params || !this._iframe) return;
+        // Both axes optional: an absent (or invalid) axis leaves that side of the iframe untouched.
+        const widthOk = Number.isFinite(params.width) && params.width >= 0;
+        const heightOk = Number.isFinite(params.height) && params.height >= 0;
+        if (!widthOk && !heightOk) {
+            this._instrumentation?.incrementCounter("sfembedding.resize.rejected", 1, true, {
+                reason: "invalid_dimensions",
+            });
+            return;
+        }
+        if (widthOk) this._iframe.style.width = `${params.width}px`;
+        if (heightOk) this._iframe.style.height = `${params.height}px`;
+        this._instrumentation?.incrementCounter("sfembedding.resize.applied", 1, false, {
+            width: widthOk ? "yes" : "no",
+            height: heightOk ? "yes" : "no",
+        });
+    }
+
+    /** Re-dispatch an inbound custom event from the embedding on the host element. */
+    _redispatchEventFromEmbedding(params) {
+        if (!params || typeof params.eventType !== "string") return;
+        // eslint-disable-next-line @sfdc-internal/lightning-base-components/no-custom-event-identifier-arguments
+        const event = new CustomEvent(params.eventType, {
+            detail: params.detail,
+            bubbles: params.bubbles ?? true,
+            composed: params.composed ?? true,
+            cancelable: params.cancelable ?? false,
+        });
+        // Mark *this specific event* as inbound so the override skips only its forward, not unrelated
+        // events a listener may dispatch synchronously during handling.
+        this._inboundDispatches.add(event);
+        this.dispatchEvent(event);
+    }
+
+    /** Resolve the real host DOM element (the shadow root's host); */
+    _getHostElement() {
+        const el = this.template?.host ?? this;
+        return el && typeof el.getAttribute === "function" ? el : undefined;
+    }
+
+    /** Compose a fresh UiState snapshot. */
+    _composeUiState() {
+        return composeUiState({
+            apiProps: this._props,
+            hostElement: this._getHostElement() ?? this,
+        });
+    }
+
+    /** Microtask-batched ui-state-changed flush; coalesces sync writes into one notification. */
+    _scheduleUiStateFlush() {
+        if (this._uiStateFlushScheduled) return;
+        this._uiStateFlushScheduled = true;
+        queueMicrotask(() => {
+            this._uiStateFlushScheduled = false;
+            this._flushUiStateChanged();
+        });
+    }
+
+    _flushUiStateChanged() {
+        const subscriptionId = this._bridge?.uiStateSubscriptionId;
+        if (!subscriptionId || !this._bridge) return;
+        const params = { subscriptionId, current: this._composeUiState() };
+        // Bridge stamps `_meta.traceId` centrally; never throws on transient failure.
+        this._bridge.notify(UI_STATE_CHANGED_METHOD, params);
+    }
+
+    /** Observe style + mirrored attrs + data-* on the host LWC; mutations schedule a flush. */
+    _installMutationObserver() {
+        if (this._mutationObserver) return;
+        const hostElement = this._getHostElement();
+        if (!hostElement) return;
+        const watched = new Set(["style", ...MIRRORED_ATTRIBUTES]);
+        const observer = new MutationObserver((mutations) => {
+            for (const m of mutations) {
+                if (m.type === "attributes" && m.attributeName) {
+                    if (watched.has(m.attributeName) || m.attributeName.startsWith("data-")) {
+                        if (m.attributeName === "title") {
+                            // Only the raw-setAttribute path diverges here; the property setter already synced + stamped before reflecting.
+                            const next = hostElement.getAttribute("title") || "embedding";
+                            if (next !== this._title) {
+                                this._title = next;
+                                this._updateTitle();
+                            }
+                        }
+                        this._scheduleUiStateFlush();
+                        return;
+                    }
+                }
+            }
+        });
+        try {
+            // No `attributeFilter`: it's an allowlist with no prefix support, and we need data-*.
+            observer.observe(hostElement, { attributes: true });
+            this._mutationObserver = observer;
+        } catch (err) {
+            this._log("MutationObserver attach failed —", err);
+            this._instrumentation?.logError(err, { code: "OBSERVER_ATTACH_FAILED", instanceId: this._instanceId });
+        }
+    }
+
+    /** Install dispatchEvent override on the real host element to forward all eligible CustomEvents. */
+    _installHostDispatchOverride() {
+        const hostElement = this._getHostElement();
+        if (!hostElement || this._originalDispatchEvent) return; // no host, or already patched
+
+        // Capture the original so teardown can restore it; host element is stable for the instance lifetime.
+        const original = hostElement.dispatchEvent.bind(hostElement);
+
+        try {
+            hostElement.dispatchEvent = (event) => {
+                if (
+                    event instanceof CustomEvent &&
+                    !RESERVED_EVENT_NAMES.has(event.type) &&
+                    !event.type.startsWith("sf-embedding.") &&
+                    !this._inboundDispatches.has(event) &&
+                    this._bridge &&
+                    this._bridge.hostEventSubscriberCount > 0
+                ) {
+                    try {
+                        this._bridge.notify(EVENTS_DISPATCH_METHOD, {
+                            eventType: event.type,
+                            detail: toCloneableDetail(event.detail),
+                        });
+                    } catch (err) {
+                        this._log("forward to embedding failed —", err);
+                        this._instrumentation?.logError(err, {
+                            code: "EVENT_FORWARD_FAILED",
+                            phase: ERROR_PHASES.EVENT_FORWARDING,
+                            instanceId: this._instanceId,
+                        });
+                    }
+                }
+                return original(event);
+            };
+            this._forwardTarget = hostElement;
+            this._originalDispatchEvent = original;
+        } catch (err) {
+            this._log("dispatchEvent override install failed —", err);
+            this._instrumentation?.logError(err, {
+                code: "EVENT_FORWARD_FAILED",
+                phase: ERROR_PHASES.EVENT_FORWARDING,
+                instanceId: this._instanceId,
+            });
+        }
+    }
+
+    /** Restore the original dispatchEvent on the host element. */
+    _restoreOriginalDispatchEvent() {
+        if (!this._forwardTarget || !this._originalDispatchEvent) return;
+        this._forwardTarget.dispatchEvent = this._originalDispatchEvent;
+        this._originalDispatchEvent = null;
+        this._forwardTarget = null;
+    }
+
+    _announceHostInitialized() {
+        if (!this._bridge) return;
+
+        const params = {
+            instanceId: this._instanceId,
+            hostInfo: HOST_INFO,
+        };
+        // Transport.post never throws on transient failure; traceId is stamped
+        // by the bridge's client.
+        this._bridge.announceInitialized(params);
+        this._instrumentation?.incrementCounter("sfembedding.host_initialized.sent", 1, false);
+        this._log("host-initialized sent");
+    }
+
+    _handleShutdown(event, iframe) {
+        const result = validateShutdown({
+            data: event.data,
+            source: event.source,
+            origin: event.origin,
+            expectedSource: iframe.contentWindow,
+            expectedOrigin: this._iframeSrcOrigin,
+        });
+
+        if (!result.ok) {
+            if (result.reason === ERROR_CODES.WRONG_SOURCE) {
+                this._countWrongSource("shutdown", event.origin);
+                return;
+            }
+            this._log("shutdown: rejected —", result.reason);
+            this._instrumentation?.incrementCounter("sfembedding.shutdown.rejected", 1, true, {
+                reason: result.reason,
+            });
+            this._instrumentation?.logError(new Error("shutdown rejected"), {
+                code: "SHUTDOWN_REJECTED",
+                reason: result.reason,
+                instanceId: this._instanceId,
+            });
+            return;
+        }
+
+        this._log("shutdown received from embedding", result.reason);
+        this._instrumentation?.incrementCounter("sfembedding.shutdown.received", 1, false);
+        this._closeHostBridge();
+        this._error(
+            ERROR_PHASES.CONFIGURATION,
+            result.reason ?? ERROR_CODES.EMBEDDING_SHUTDOWN,
+            "embedding signalled shutdown.",
+            STATES.CLOSED,
+        );
+    }
+
+    _applySandbox() {
+        if (!this._iframe) return;
+        const tokens = computeSandboxTokens(this._sandbox, this._removeSandboxTokens);
+        this._iframe.setAttribute("sandbox", tokens);
+        this._log("sandbox", tokens);
+    }
+
+    _updateIframeSrc() {
+        if (!this._iframe) return;
+
+        this._resetSession();
+
+        this._iframe.removeAttribute("src");
+        if (this._src) {
+            try {
+                this._iframe.setAttribute(
+                    "src",
+                    appendHostMetaData(this._src, this._instanceId, window.location.origin),
+                );
+            } catch (err) {
+                this._error(
+                    ERROR_PHASES.CONFIGURATION,
+                    ERROR_CODES.INVALID_SRC,
+                    `iframe src MUST be a parseable URL. Error: ${err instanceof Error ? err.message : String(err)}`,
+                    STATES.CLOSED,
+                );
+                return;
+            }
+        }
+        this._log("updateIframeSrc", this._src ? "src set" : "blank");
+    }
+
+    _reflectHostTitle() {
+        const host = this._getHostElement();
+        if (host) {
+            host.setAttribute("title", this._title);
+        }
+    }
+
+    _updateTitle() {
+        if (this._iframe) {
+            this._iframe.setAttribute("title", this._title);
+        }
+    }
+
+    _startLoadActivity() {
+        if (this._loadActivity && !this._loadActivityStopped) {
+            this._loadActivityStopped = true;
+            this._instrumentation?.incrementCounter("sfembedding.load_activity.superseded", 1, false);
+            this._instrumentation?.stopLoadActivity(this._loadActivity, {
+                instanceId: this._instanceId,
+                widgetSrc: this._src,
+                hostAppOrigin: window.location.origin,
+                outcome: "superseded",
+            });
+            this._loadActivity = null;
+        }
+        this._activityStartedAt = Date.now();
+        this._loadActivityStopped = false;
+        this._loadActivity = this._instrumentation?.startLoadActivity() ?? null;
+    }
+
+    _completeLoadActivity() {
+        if (this._loadActivityStopped || !this._loadActivity) return;
+        this._loadActivityStopped = true;
+        const timeToReady = Date.now() - this._activityStartedAt;
+        this._instrumentation?.stopLoadActivity(this._loadActivity, {
+            instanceId: this._instanceId,
+            widgetSrc: this._src,
+            hostAppOrigin: window.location.origin,
+            outcome: "embedding_success",
+            timeToReady,
+        });
+        this._loadActivity = null;
+        this._instrumentation?.incrementCounter("embedding.init.count", 1, false);
+    }
+
+    _errorLoadActivity(err, code) {
+        if (this._loadActivityStopped || !this._loadActivity) return;
+        this._loadActivityStopped = true;
+        this._instrumentation?.errorLoadActivity(this._loadActivity, err, {
+            widgetSrc: this._src,
+            hostAppOrigin: window.location.origin,
+            message: err instanceof Error ? err.message : String(err),
+            isHostError: true,
+            instanceId: this._instanceId,
+        });
+        this._loadActivity = null;
+        // Use the bounded error code (not the free-text message) as the Argus tag to avoid
+        // unbounded cardinality — each unique string would mint a new time series.
+        this._instrumentation?.incrementCounter("embedding.init.error", 1, true, { reason: code });
+    }
+
+    // Records expected multi-MFE WRONG_SOURCE fan-out as a non-error counter.
+    _countWrongSource(kind, origin) {
+        this._instrumentation?.incrementCounter(`sfembedding.${kind}.wrong_source`, 1, false, { origin });
+        this._log(`${kind}: WRONG_SOURCE from`, origin);
+    }
+}