@salesforce/platform-sdk 11.4.7 → 11.6.0

package/dist/core/index.d.ts

@@ -7,7 +7,7 @@ export { Surface, getVerifiedSurface, initialize, isSfEmbeddingIframe, resetSurf
 export type { InitializeOptions } from './surface';
 export type { SDKOptions } from './options';
 export type { HostContext, HostStyles, ChatMessage, ChatSDK, ContentBlock, DeviceCapabilities, DisplayMode, ResourceRequest, SafeAreaInsets, SetWidgetStateOptions, ToolCall, ToolState, } from './chat';
-export type { AlertOptions, MessageLevel, ModalOptions, ToastOptions, Theme, ThemeMode, ViewSDK, } from './view';
+export type { AlertOptions, MessageLevel, ModalOptions, ToastOptions, Theme, ThemeMode, UiState, UiStyles, ViewSDK, } from './view';
 export type { CacheControl, DataSDK, DataSDKGraphQL, GraphQLError, GraphQLRawDocument, GraphQLRequest, GraphQLResponse, MutateOptions, MutationResult, QueryOptions, QueryResult, QuerySubscriber, Unsubscribe, } from './data';
 export type { LightningSDK, LMSMessage, LMSSubscription, MessageChannel } from './lightning';
 export type { OpenAISDK } from './platforms';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACN,OAAO,EACP,kBAAkB,EAClB,UAAU,EACV,mBAAmB,EACnB,YAAY,GACZ,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,YAAY,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,OAAO,EACP,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,SAAS,GACT,MAAM,QAAQ,CAAC;AAGhB,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,SAAS,EACT,OAAO,GACP,MAAM,QAAQ,CAAC;AAGhB,YAAY,EACX,YAAY,EACZ,OAAO,EACP,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,GACX,MAAM,QAAQ,CAAC;AAGhB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7F,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC7E,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACN,OAAO,EACP,kBAAkB,EAClB,UAAU,EACV,mBAAmB,EACnB,YAAY,GACZ,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,YAAY,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,OAAO,EACP,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,SAAS,GACT,MAAM,QAAQ,CAAC;AAGhB,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,SAAS,EACT,OAAO,EACP,QAAQ,EACR,OAAO,GACP,MAAM,QAAQ,CAAC;AAGhB,YAAY,EACX,YAAY,EACZ,OAAO,EACP,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,GACX,MAAM,QAAQ,CAAC;AAGhB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7F,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC7E,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/view.d.ts

@@ -3,6 +3,34 @@
  * All rights reserved.
  * For full license text, see the LICENSE.txt file
  */
+/**
+ * CSS-adjacent styling the host publishes for the embedded surface.
+ *
+ * `variables` are CSS custom properties (`--*`) read off the host element's inline
+ * style; `attributes` are mirrored a11y/i18n/input attributes from the host LWC.
+ */
+export interface UiStyles {
+    variables?: Record<string, string>;
+    attributes?: Record<string, string>;
+}
+/**
+ * Host → embedding rendering snapshot exposed to bundles via {@link ViewSDK.getUiState}.
+ *
+ * `props` are host-configurable inputs (theme, locale, mode, etc.); `styles` are the
+ * CSS custom properties and attributes the host wants mirrored onto the surface.
+ *
+ * Declared locally (not re-exported from `@salesforce/sf-embedding-bridge`) to keep the
+ * wire-layer package off the SDK's public type graph; the shape mirrors the bridge's, so
+ * surface-side code assigns without a cast.
+ *
+ * This is the open, fully-permissive shape. A bundle that knows its host contract can
+ * declare a narrower type that `extends UiState` (tighter `props`/`styles`) and pass it to
+ * {@link ViewSDK.getUiState}'s single type parameter for precise typing.
+ */
+export interface UiState {
+    props: Record<string, unknown>;
+    styles: UiStyles;
+}
 /**
  * Theme mode
  */
@@ -93,6 +121,19 @@ export interface ModalOptions {
  * alerts, toast notifications, modal dialogs, and managing application state. All methods
  * are optional and may not be available depending on the runtime surface.
  *
+ * ## Events
+ *
+ * A ViewSDK is a DOM {@link EventTarget}: the event API is the native
+ * `addEventListener` / `removeEventListener` / `dispatchEvent`. On surfaces backed by a
+ * host bridge (e.g. the embedded MicroFrontend surface), `dispatchEvent` both notifies
+ * local listeners and forwards the event to the host, and events pushed by the host are
+ * re-dispatched onto the SDK so `addEventListener` hears them too — one unified stream of
+ * host-pushed and same-document events.
+ *
+ * The `EventTarget` members are declared via {@link Partial} so that surfaces without an
+ * event bus (e.g. the WebApp/Mosaic degraded SDK, which is a bare `{}`) still satisfy the
+ * type. Feature-detect before use: `viewSDK.dispatchEvent?.(...)`.
+ *
  * @example
  * ```typescript
  * const viewSDK = await createViewSDK();
@@ -103,11 +144,17 @@ export interface ModalOptions {
  *   level: 'success'
  * });
  *
+ * // Listen for events (host-pushed or same-document) and dispatch your own
+ * viewSDK.addEventListener?.('user-action', (e) => {
+ *   console.log('received:', (e as CustomEvent).detail);
+ * });
+ * viewSDK.dispatchEvent?.(new CustomEvent('user-action', { detail: { action: 'click' } }));
+ *
  * // Mark application as having unsaved changes
  * await viewSDK.markDirtyState?.();
  * ```
  */
-export interface ViewSDK {
+export type ViewSDK = Partial<EventTarget> & {
     /**
      * Display an alert message in the host environment
      *
@@ -226,52 +273,50 @@ export interface ViewSDK {
      */
     clearDirtyState?(label?: string): Promise<void>;
     /**
-     * Dispatch a custom event to the host environment
-     *
-     * This allows the application to send custom events with associated data to the
-     * host. The host can listen for these events and respond accordingly.
+     * Get the current host UI state and a `subscribe` function for future changes.
      *
-     * @param event - The event name/type to dispatch
-     * @param data - Associated event data as key-value pairs
-     * @returns Promise that resolves when the event is dispatched
-     *
-     * @example
-     * ```typescript
-     * await viewSDK.dispatchEvent?.('user-action', {
-     *   action: 'click',
-     *   buttonId: 'submit',
-     *   timestamp: Date.now()
-     * });
-     * ```
-     */
-    dispatchEvent?(event: string, data: Record<string, unknown>): Promise<void>;
-    /**
-     * Get UI properties from the host and subscribe to changes
+     * Returns the latest known snapshot synchronously — the underlying wire subscription is
+     * opened once, is session-scoped, and is shared across every caller ({@link getTheme} is
+     * its synchronous sibling). Call `subscribe` with a handler to be notified on every
+     * subsequent host push; `subscribe` returns an `unsubscribe` function that detaches that
+     * one handler. Detaching is local fan-out only — the shared wire subscription stays open.
      *
-     * Returns an object containing a promise for the initial props and a subscribe
-     * function to listen for prop updates. UI props allow the host to configure
-     * the application's appearance or behavior dynamically.
+     * The optional `State` type parameter describes the host contract this caller expects:
+     * pass a type that `extends UiState` (narrower `props`/`styles`) and both `state` and the
+     * `subscribe` handler's argument are typed as it. It defaults to the open {@link UiState},
+     * so `getUiState()` with no type argument is the fully-permissive snapshot. `State` is
+     * erased at runtime — purely a compile-time convenience, so pin only what the host
+     * actually guarantees.
      *
-     * @returns Object with props promise and subscribe function
+     * @typeParam State - The expected snapshot shape; must extend {@link UiState}.
+     * @returns `{ state, subscribe }` — the current snapshot and a subscribe function whose
+     *   return value is the per-handler `unsubscribe`.
      *
      * @example
      * ```typescript
-     * const uiProps = viewSDK.getUiProps?.();
-     *
-     * // Get initial props
-     * const initialProps = await uiProps.props;
-     * console.log('Theme:', initialProps.theme);
-     *
-     * // Subscribe to prop changes
-     * uiProps.subscribe((newProps) => {
-     *   console.log('Props updated:', newProps);
-     *   // Update UI based on new props
-     * });
+     * // Untyped — the permissive default.
+     * const { state, subscribe } = viewSDK.getUiState?.() ?? {
+     *   state: { props: {}, styles: {} },
+     *   subscribe: () => () => {},
+     * };
+     * applyProps(state.props);
+     * const unsubscribe = subscribe((next) => applyProps(next.props));
+     * unsubscribe(); // later, when the caller no longer cares
+     *
+     * // Typed — pin the exact snapshot the host guarantees.
+     * interface MyUiState extends UiState {
+     *   props: { theme: "light" | "dark" };
+     *   styles: { variables?: { "--accent": string } };
+     * }
+     * const { state } = viewSDK.getUiState?.<MyUiState>() ??
+     *   { state: { props: { theme: "light" }, styles: {} } };
+     * state.props.theme;                    // "light" | "dark"
+     * state.styles.variables?.["--accent"]; // string | undefined
      * ```
      */
-    getUiProps?(): {
-        props: Promise<Record<string, unknown>>;
-        subscribe: (callback: (props: Record<string, unknown>) => void) => void;
+    getUiState?<State extends UiState = UiState>(): {
+        state: State;
+        subscribe: (handler: (state: State) => void) => () => void;
     };
     /**
      * Resize the application viewport
@@ -310,5 +355,5 @@ export interface ViewSDK {
      * ```
      */
     getTheme?(): Theme | null;
-}
+};
 //# sourceMappingURL=view.d.ts.map

package/dist/core/view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/core/view.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,SAAS,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,OAAO;IACvB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,UAAU,CAAC,IAAI;QACd,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACxC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;KACxE,CAAC;IAEF;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC;CAC1B"}
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/core/view.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE,QAAQ,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,SAAS,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG;IAC5C;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,UAAU,CAAC,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,KAAK;QAC/C,KAAK,EAAE,KAAK,CAAC;QACb,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;KAC3D,CAAC;IAEF;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC;CAC1B,CAAC"}

package/dist/data/index.js

@@ -196,7 +196,7 @@ class ie {
     })).structuredContent;
   }
 }
-const ce = "X-SFDC-Client-Name", ue = "X-SFDC-Client-Version", he = "@salesforce/platform-sdk", le = "11.4.7", de = (t) => {
+const ce = "X-SFDC-Client-Name", ue = "X-SFDC-Client-Version", he = "@salesforce/platform-sdk", le = "11.6.0", de = (t) => {
   let e = y(ce, he, t);
   return e = y(ue, le, e), u(e);
 }, pe = "X-CSRF-Token";

package/dist/view/embedding.d.ts

@@ -1,15 +1,105 @@
-import { ViewSDK } from '../core';
+import { UiState, ViewSDK } from '../core';
 /** Pixel-only dimension string: bare number or `Npx`. The empty string is allowed so a caller can omit one axis. */
 export type PixelSize = `${number}` | `${number}px` | "";
-/** ViewSDK for the sf-embedding surface; wraps bridge wire-layer primitives. */
-export declare class EmbeddingViewSDK implements ViewSDK {
+/**
+ * ViewSDK for the sf-embedding surface; wraps bridge wire-layer primitives.
+ *
+ * This SDK **is** a DOM {@link EventTarget}: the public event API is the native
+ * `addEventListener` / `removeEventListener` / `dispatchEvent`. Events flow through it in
+ * both directions and are unified into a single stream:
+ *
+ * - **Outbound** — {@link dispatchEvent} both notifies local listeners (via the native
+ *   {@link EventTarget}) *and* forwards the event to the host over the wire.
+ * - **Inbound** — events the host pushes over the wire are re-dispatched onto this
+ *   `EventTarget`, so `addEventListener` consumers hear host-pushed and same-document
+ *   events alike.
+ *
+ * The wire is host-trusted; same-document dispatches are not. Consumers that must trust
+ * the origin of an event should validate its payload rather than assume it came from the
+ * host.
+ */
+export declare class EmbeddingViewSDK extends EventTarget implements ViewSDK {
     private readonly session;
     static create(): Promise<EmbeddingViewSDK>;
+    private currentUiState;
+    private readonly uiStateListeners;
     private constructor();
+    /**
+     * Dispatch a custom event.
+     *
+     * Overrides {@link EventTarget.dispatchEvent} to be symmetric across both channels an
+     * embedded bundle can reach: it forwards the event to the host over the wire **and**
+     * notifies local listeners on this `EventTarget`. A {@link CustomEvent}'s `detail` is
+     * the payload sent to the host; a plain `Event` (no `detail`) is delivered to local
+     * listeners only, since there is nothing to carry over the wire.
+     *
+     * A bundle's own dispatch reaches its own listeners exactly once — synchronously, here
+     * — and is not echoed back: the host does not relay a bundle's own dispatch down the
+     * wire to the originating iframe (inbound re-dispatch goes through `super.dispatchEvent`,
+     * never back out through this override).
+     *
+     * @param event - The event to dispatch. Use a {@link CustomEvent} to carry a payload.
+     * @returns `false` if the event is cancelable and a listener called `preventDefault()`,
+     *   otherwise `true` (native {@link EventTarget} semantics).
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Get the current host UI state and a `subscribe` function for future changes.
+     *
+     * The snapshot is fetched once at {@link EmbeddingViewSDK.create} and refreshed on every
+     * host push, so this returns synchronously. `subscribe(handler)` registers the handler for
+     * every subsequent push and returns an `unsubscribe` that detaches just that handler; the
+     * underlying wire subscription is session-scoped and shared, so detaching is a local
+     * `Set.delete`, not a wire teardown.
+     *
+     * The optional `State` type parameter narrows `state` and the `subscribe` handler for this
+     * caller; it is erased at runtime, so the stored snapshot and listeners are the open-shaped
+     * {@link UiState} and the narrowed handler is adapted to that at the boundary.
+     *
+     * @returns `{ state, subscribe }` — the latest cached snapshot and a subscribe function
+     *   whose return value is the per-handler `unsubscribe`.
+     */
+    getUiState<State extends UiState = UiState>(): {
+        state: State;
+        subscribe: (handler: (state: State) => void) => () => void;
+    };
     markDirtyState(label?: string): Promise<void>;
     clearDirtyState(label?: string): Promise<void>;
     /** Resize the embedded surface. Pass `""` for either axis to leave it unchanged; both empty is a no-op. */
     resize(width: PixelSize, height: PixelSize): Promise<void>;
+    /**
+     * Send an event to the host over the wire. Private wire-layer plumbing; the public
+     * entry point is {@link dispatchEvent}, which calls this in addition to notifying
+     * local listeners.
+     */
+    private dispatchHostEvent;
+    /**
+     * Open the host's event stream and pipe inbound host-pushed events onto this
+     * `EventTarget`, so `addEventListener` consumers hear them alongside same-document
+     * dispatches. Private wire-layer plumbing, opened once per session — the bridge
+     * delivers a single stream and per-type fan-out is the native `EventTarget`'s job
+     * ("one subscription per session").
+     *
+     * Inbound events are re-dispatched through `super.dispatchEvent`, not the
+     * {@link dispatchEvent} override, so a host push notifies local listeners without
+     * being echoed straight back up the wire.
+     *
+     * Best-effort: if the subscription cannot be opened, inbound host events simply do not
+     * arrive; outbound {@link dispatchEvent} and every other method still work. The wire is
+     * not explicitly torn down — it lives for the session and is released when the bridge
+     * is disposed.
+     */
+    private subscribeToHostEvent;
+    /**
+     * Open the host's ui-state stream once per session and cache the initial snapshot,
+     * then fan out every subsequent push to registered listeners. Private wire-layer
+     * plumbing — the public entry point is {@link getUiState}.
+     *
+     * Best-effort, mirroring {@link subscribeToHostEvent}: if the subscription cannot be
+     * opened, {@link getUiState} still returns a usable (empty) snapshot and every other
+     * method continues to work. The wire is not explicitly torn down.
+     */
+    private subscribeToUiState;
     private setDirty;
 }
 //# sourceMappingURL=embedding.d.ts.map

package/dist/view/embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/view/embedding.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMvC,oHAAoH;AACpH,MAAM,MAAM,SAAS,GAAG,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC;AAEzD,gFAAgF;AAChF,qBAAa,gBAAiB,YAAW,OAAO;IAM3B,OAAO,CAAC,QAAQ,CAAC,OAAO;WAL/B,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAKhD,OAAO;IAED,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,2GAA2G;IACrG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE,OAAO,CAAC,QAAQ;CAOhB"}
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/view/embedding.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMhD,oHAAoH;AACpH,MAAM,MAAM,SAAS,GAAG,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,SAAQ,WAAY,YAAW,OAAO;IAa/C,OAAO,CAAC,QAAQ,CAAC,OAAO;WAZ/B,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAShD,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;IAExE,OAAO;IAIP;;;;;;;;;;;;;;;;;OAiBG;IACM,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IA0B7C;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,KAAK;QAC9C,KAAK,EAAE,KAAK,CAAC;QACb,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;KAC3D;IAeK,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,2GAA2G;IACrG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;;;;;;;OAeG;YACW,oBAAoB;IAyBlC;;;;;;;;OAQG;YACW,kBAAkB;IAiBhC,OAAO,CAAC,QAAQ;CAOhB"}

package/dist/view/index.d.ts

@@ -25,5 +25,5 @@ export interface ViewSDKOptions extends SDKOptions {
 export declare function createViewSDK(options?: ViewSDKOptions): Promise<ViewSDK>;
 export { MCPAppsViewSDK } from './mcpapps';
 export { getViewSDK, getViewSDKSync, resetViewSDK } from './singleton';
-export type { AlertOptions, ModalOptions, SDKOptions, Theme, ThemeMode, ToastOptions, ViewSDK, } from '../core';
+export type { AlertOptions, ModalOptions, SDKOptions, Theme, ThemeMode, ToastOptions, UiState, UiStyles, ViewSDK, } from '../core';
 //# sourceMappingURL=index.d.ts.map

package/dist/view/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/view/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKnD;;;;;;GAMG;AAEH,MAAM,WAAW,cAAe,SAAQ,UAAU;CAAG;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAgCxE;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvE,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,KAAK,EACL,SAAS,EACT,YAAY,EACZ,OAAO,GACP,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/view/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKnD;;;;;;GAMG;AAEH,MAAM,WAAW,cAAe,SAAQ,UAAU;CAAG;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAgCxE;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvE,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,KAAK,EACL,SAAS,EACT,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,OAAO,GACP,MAAM,SAAS,CAAC"}

package/dist/view/index.js

@@ -1,8 +1,8 @@
-import { g as w, S as a, a as h } from "../surface-Dd2tqrPi.js";
-import { w as m } from "../sdk-promise-D0sy7OW1.js";
-import { requireSharedSession as f } from "../sf-embedding/index.js";
-function p(n) {
-  switch (n) {
+import { g as h, S as n, a as w } from "../surface-Dd2tqrPi.js";
+import { w as p } from "../sdk-promise-D0sy7OW1.js";
+import { requireSharedSession as m } from "../sf-embedding/index.js";
+function f(i) {
+  switch (i) {
     case "info":
       return "ℹ️";
     case "success":
@@ -15,33 +15,98 @@ function p(n) {
       return "ℹ️";
   }
 }
-function u(n, e) {
-  return `${p(e)} ${n}`;
+function u(i, e) {
+  return `${f(e)} ${i}`;
 }
-function o(n, e) {
-  const t = n.trim();
-  if (t === "")
+function o(i, e) {
+  const s = i.trim();
+  if (s === "")
     return { success: !0, value: void 0 };
-  const s = t.match(/^(\d+(?:\.\d+)?)(px)?$/);
-  if (!s || !s[1])
+  const t = s.match(/^(\d+(?:\.\d+)?)(px)?$/);
+  if (!t || !t[1])
     return {
       success: !1,
-      error: `Invalid ${e}: "${n}". Only pixel values are supported (e.g., "800px" or "800").`
+      error: `Invalid ${e}: "${i}". Only pixel values are supported (e.g., "800px" or "800").`
     };
-  const r = parseFloat(s[1]);
+  const r = parseFloat(t[1]);
   return r < 0 || !isFinite(r) ? {
     success: !1,
-    error: `Invalid ${e}: "${n}". Value must be a positive number.`
+    error: `Invalid ${e}: "${i}". Value must be a positive number.`
   } : { success: !0, value: r };
 }
-const g = "trackdirtystate";
-class l {
+const b = "trackdirtystate";
+class l extends EventTarget {
   constructor(e) {
-    this.session = e;
+    super(), this.session = e;
   }
   static async create() {
-    const e = await f("EmbeddingViewSDK");
-    return new l(e);
+    const e = await m("EmbeddingViewSDK"), s = new l(e);
+    return await Promise.all([s.subscribeToHostEvent(), s.subscribeToUiState()]), s;
+  }
+  // Latest snapshot, refreshed on every host push. Session-scoped — the wire subscription
+  // is opened once at create() and never torn down.
+  currentUiState = { props: {}, styles: {} };
+  uiStateListeners = /* @__PURE__ */ new Set();
+  /**
+   * Dispatch a custom event.
+   *
+   * Overrides {@link EventTarget.dispatchEvent} to be symmetric across both channels an
+   * embedded bundle can reach: it forwards the event to the host over the wire **and**
+   * notifies local listeners on this `EventTarget`. A {@link CustomEvent}'s `detail` is
+   * the payload sent to the host; a plain `Event` (no `detail`) is delivered to local
+   * listeners only, since there is nothing to carry over the wire.
+   *
+   * A bundle's own dispatch reaches its own listeners exactly once — synchronously, here
+   * — and is not echoed back: the host does not relay a bundle's own dispatch down the
+   * wire to the originating iframe (inbound re-dispatch goes through `super.dispatchEvent`,
+   * never back out through this override).
+   *
+   * @param event - The event to dispatch. Use a {@link CustomEvent} to carry a payload.
+   * @returns `false` if the event is cancelable and a listener called `preventDefault()`,
+   *   otherwise `true` (native {@link EventTarget} semantics).
+   */
+  dispatchEvent(e) {
+    if (e instanceof CustomEvent)
+      try {
+        this.dispatchHostEvent(e.type, e.detail, {
+          bubbles: e.bubbles,
+          composed: e.composed,
+          cancelable: e.cancelable
+        });
+      } catch (s) {
+        console.warn(
+          `[EmbeddingViewSDK] wire dispatch failed for "${e.type}"; local listeners will still fire`,
+          s
+        );
+      }
+    return super.dispatchEvent(e);
+  }
+  /**
+   * Get the current host UI state and a `subscribe` function for future changes.
+   *
+   * The snapshot is fetched once at {@link EmbeddingViewSDK.create} and refreshed on every
+   * host push, so this returns synchronously. `subscribe(handler)` registers the handler for
+   * every subsequent push and returns an `unsubscribe` that detaches just that handler; the
+   * underlying wire subscription is session-scoped and shared, so detaching is a local
+   * `Set.delete`, not a wire teardown.
+   *
+   * The optional `State` type parameter narrows `state` and the `subscribe` handler for this
+   * caller; it is erased at runtime, so the stored snapshot and listeners are the open-shaped
+   * {@link UiState} and the narrowed handler is adapted to that at the boundary.
+   *
+   * @returns `{ state, subscribe }` — the latest cached snapshot and a subscribe function
+   *   whose return value is the per-handler `unsubscribe`.
+   */
+  getUiState() {
+    return {
+      state: this.currentUiState,
+      subscribe: (e) => {
+        const s = e;
+        return this.uiStateListeners.add(s), () => {
+          this.uiStateListeners.delete(s);
+        };
+      }
+    };
   }
   async markDirtyState(e) {
     this.setDirty(!0, e);
@@ -50,25 +115,95 @@ class l {
     this.setDirty(!1, e);
   }
   /** Resize the embedded surface. Pass `""` for either axis to leave it unchanged; both empty is a no-op. */
-  async resize(e, t) {
-    const s = o(e, "width");
-    if (!s.success) throw new Error(s.error);
-    const r = o(t, "height");
+  async resize(e, s) {
+    const t = o(e, "width");
+    if (!t.success) throw new Error(t.error);
+    const r = o(s, "height");
     if (!r.success) throw new Error(r.error);
-    s.value === void 0 && r.value === void 0 || this.session.bridge.sendResize({
-      ...s.value !== void 0 ? { width: s.value } : {},
+    t.value === void 0 && r.value === void 0 || this.session.bridge.sendResize({
+      ...t.value !== void 0 ? { width: t.value } : {},
       ...r.value !== void 0 ? { height: r.value } : {}
     });
   }
-  setDirty(e, t) {
-    this.session.bridge.sendEventDispatch(g, {
+  /**
+   * Send an event to the host over the wire. Private wire-layer plumbing; the public
+   * entry point is {@link dispatchEvent}, which calls this in addition to notifying
+   * local listeners.
+   */
+  dispatchHostEvent(e, s, t) {
+    this.session.bridge.sendEventDispatch(e, s, t);
+  }
+  /**
+   * Open the host's event stream and pipe inbound host-pushed events onto this
+   * `EventTarget`, so `addEventListener` consumers hear them alongside same-document
+   * dispatches. Private wire-layer plumbing, opened once per session — the bridge
+   * delivers a single stream and per-type fan-out is the native `EventTarget`'s job
+   * ("one subscription per session").
+   *
+   * Inbound events are re-dispatched through `super.dispatchEvent`, not the
+   * {@link dispatchEvent} override, so a host push notifies local listeners without
+   * being echoed straight back up the wire.
+   *
+   * Best-effort: if the subscription cannot be opened, inbound host events simply do not
+   * arrive; outbound {@link dispatchEvent} and every other method still work. The wire is
+   * not explicitly torn down — it lives for the session and is released when the bridge
+   * is disposed.
+   */
+  async subscribeToHostEvent() {
+    const e = this.session.bridge;
+    e.onEventDispatch((s) => {
+      super.dispatchEvent(
+        new CustomEvent(s.eventType, {
+          detail: s.detail,
+          bubbles: s.bubbles ?? !0,
+          composed: s.composed ?? !0,
+          cancelable: s.cancelable ?? !1
+        })
+      );
+    });
+    try {
+      await e.sendEventSubscribe();
+    } catch (s) {
+      console.warn(
+        "[EmbeddingViewSDK] host event subscription failed; inbound host events will not be delivered",
+        s
+      );
+    }
+  }
+  /**
+   * Open the host's ui-state stream once per session and cache the initial snapshot,
+   * then fan out every subsequent push to registered listeners. Private wire-layer
+   * plumbing — the public entry point is {@link getUiState}.
+   *
+   * Best-effort, mirroring {@link subscribeToHostEvent}: if the subscription cannot be
+   * opened, {@link getUiState} still returns a usable (empty) snapshot and every other
+   * method continues to work. The wire is not explicitly torn down.
+   */
+  async subscribeToUiState() {
+    const e = this.session.bridge;
+    e.onUiStateChanged((s) => {
+      this.currentUiState = s.current;
+      for (const t of this.uiStateListeners) t(s.current);
+    });
+    try {
+      const { current: s } = await e.sendUiStateSubscribe();
+      this.currentUiState = s;
+    } catch (s) {
+      console.warn(
+        "[EmbeddingViewSDK] ui-state subscription failed; getUiState will return an empty snapshot",
+        s
+      );
+    }
+  }
+  setDirty(e, s) {
+    this.session.bridge.sendEventDispatch(b, {
       isDirty: e,
       instanceId: this.session.hostMetaData.instanceId,
-      label: t ?? ""
+      label: s ?? ""
     });
   }
 }
-class v {
+class g {
   constructor(e) {
     this.session = e;
   }
@@ -77,14 +212,14 @@ class v {
    * @param message - The message text
    * @param level - The message severity level (defaults to "info")
    */
-  async sendMessage(e, t = "info") {
-    const s = u(e, t);
+  async sendMessage(e, s = "info") {
+    const t = u(e, s);
     await this.session.request("ui/message", {
       role: "user",
       content: [
         {
           type: "text",
-          text: s
+          text: t
         }
       ]
     });
@@ -102,25 +237,25 @@ class v {
     const e = this.session.getHostContext().theme;
     return e ? { mode: e } : null;
   }
-  async resize(e, t) {
-    const s = o(e, "width");
-    if (!s.success)
-      return Promise.reject(new Error(s.error));
-    const r = o(t, "height");
+  async resize(e, s) {
+    const t = o(e, "width");
+    if (!t.success)
+      return Promise.reject(new Error(t.error));
+    const r = o(s, "height");
     if (!r.success)
       return Promise.reject(new Error(r.error));
     const c = {};
-    return s.value !== void 0 && (c.width = s.value), r.value !== void 0 && (c.height = r.value), this.session.sendNotification("ui/notifications/size-changed", c), Promise.resolve();
+    return t.value !== void 0 && (c.width = t.value), r.value !== void 0 && (c.height = r.value), this.session.sendNotification("ui/notifications/size-changed", c), Promise.resolve();
   }
 }
-class y {
+class v {
   async displayAlert(e) {
-    const t = e.level || "info", s = u(e.message, t);
-    await window.openai.sendFollowUpMessage({ prompt: s });
+    const s = e.level || "info", t = u(e.message, s);
+    await window.openai.sendFollowUpMessage({ prompt: t });
   }
   async displayToast(e) {
-    const t = e.level || "info", s = u(e.message, t);
-    await window.openai.sendFollowUpMessage({ prompt: s });
+    const s = e.level || "info", t = u(e.message, s);
+    await window.openai.sendFollowUpMessage({ prompt: t });
   }
   async displayModal(e) {
     await window.openai.requestModal({
@@ -133,31 +268,31 @@ class y {
     return e ? { mode: e } : null;
   }
 }
-let i = null, d = null;
-function A(n) {
-  return i || (i = S(n).then((e) => (d = e, e))), i;
+let a = null, d = null;
+function M(i) {
+  return a || (a = y(i).then((e) => (d = e, e))), a;
 }
-function E() {
+function T() {
   return d;
 }
-function I() {
-  i = null, d = null;
+function V() {
+  a = null, d = null;
 }
-function S(n) {
-  return m(
+function y(i) {
+  return p(
     (async () => {
       try {
-        switch (await w(n?.surface)) {
-          case a.OpenAI:
-            return new y();
-          case a.WebApp:
-          case a.Mosaic:
+        switch (await h(i?.surface)) {
+          case n.OpenAI:
+            return new v();
+          case n.WebApp:
+          case n.Mosaic:
             return {};
-          case a.MicroFrontend:
+          case n.MicroFrontend:
             return await l.create();
-          case a.MCPApps: {
-            const t = await h.getInstance();
-            return new v(t);
+          case n.MCPApps: {
+            const s = await w.getInstance();
+            return new g(s);
           }
           default:
             return {};
@@ -170,9 +305,9 @@ function S(n) {
   );
 }
 export {
-  v as MCPAppsViewSDK,
-  S as createViewSDK,
-  A as getViewSDK,
-  E as getViewSDKSync,
-  I as resetViewSDK
+  g as MCPAppsViewSDK,
+  y as createViewSDK,
+  M as getViewSDK,
+  T as getViewSDKSync,
+  V as resetViewSDK
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/platform-sdk",
-  "version": "11.4.7",
+  "version": "11.6.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -115,7 +115,7 @@
     "@conduit-client/service-pubsub": "3.19.6",
     "@conduit-client/service-retry": "3.19.6",
     "@conduit-client/utils": "3.19.6",
-    "@salesforce/jsonrpc": "^11.4.7",
+    "@salesforce/jsonrpc": "^11.6.0",
     "@salesforce/sf-embedding-bridge": "2.2.4-rc.1"
   },
   "peerDependencies": {