@thoughtspot/visual-embed-sdk 1.50.1 → 1.51.0-test

package/src/embed/ts-embed.ts

@@ -10,6 +10,7 @@ import isEqual from 'lodash/isEqual';
 import isEmpty from 'lodash/isEmpty';
 import isObject from 'lodash/isObject';
 import {
+    HostEventRequest,
     TriggerPayload,
     TriggerResponse,
     UIPassthroughArrayResponse,
@@ -66,6 +67,8 @@ import {
     MessagePayload,
     ContextType,
     ContextObject,
+    PreRenderConfig,
+    BaseViewConfig,
 } from '../types';
 import { uploadMixpanelEvent, MIXPANEL_EVENT } from '../mixpanel-service';
 import { processEventData, processAuthFailure } from '../utils/processData';
@@ -206,7 +209,7 @@ export class TsEmbed {
 
     private resizeObserver: ResizeObserver;
 
-    private preRenderContainerEl: HTMLElement | null = null;
+    private preRenderContainerEl: HTMLElement = document.body;
 
     private containerScrollListener: (() => void) | null = null;
 
@@ -959,11 +962,27 @@ export class TsEmbed {
         return iFrame;
     }
 
+    /**
+     * Returns a merged {@link PreRenderConfig} object where each shared key
+     * prefers `preRenderConfig.key` over the top-level `viewConfig.key` for
+     * backward compatibility.
+     */
+    protected getPreRenderConfig(): PreRenderConfig {
+        const viewCfg = this.viewConfig as BaseViewConfig;
+        const preRenderCfg = viewCfg.preRenderConfig ?? {};
+        return {
+            ...preRenderCfg,
+            preRenderId: preRenderCfg.preRenderId ?? viewCfg.preRenderId,
+            preRenderContainer: preRenderCfg.preRenderContainer ?? viewCfg.preRenderContainer,
+            doNotTrackPreRenderSize: preRenderCfg.doNotTrackPreRenderSize ?? viewCfg.doNotTrackPreRenderSize,
+        };
+    }
+
     /**
      * Returns true if this embed instance is configured for pre-rendering.
      */
     protected isPreRenderEmbed() {
-        return !!this.viewConfig.preRenderId;
+        return !!this.getPreRenderConfig().preRenderId;
     }
     protected handleInsertionIntoDOM(child: string | Node): void {
         if (this.isPreRenderEmbed()) {
@@ -1119,6 +1138,7 @@ export class TsEmbed {
                 this.setIframeElement(this.preRenderChild);
             }
             this.isRendered = true;
+            this.inheritPreRenderContainer();
         }
 
         return this.isPreRenderConnected();
@@ -1176,7 +1196,7 @@ export class TsEmbed {
      * fresh element; an element passed directly cannot be re-resolved.
      */
     private resolvePreRenderContainerTarget(): HTMLElement {
-        const containerConfig = this.viewConfig.preRenderContainer;
+        const containerConfig = this.getPreRenderConfig().preRenderContainer;
         let container: Element | null = null;
         if (typeof containerConfig === 'string') {
             try {
@@ -1193,15 +1213,40 @@ export class TsEmbed {
         return (container as HTMLElement) ?? document.body;
     }
 
+    private inheritPreRenderContainer(): void {
+        const preRenderedObject = this.getPreRenderObj<TsEmbed>();
+        if (!preRenderedObject || preRenderedObject === (this as TsEmbed)) {
+            return;
+        }
+        const ownerContainer = preRenderedObject.preRenderContainerEl ?? document.body;
+        if (
+            this.getPreRenderConfig().preRenderContainer
+            && this.resolvePreRenderContainerTarget() !== ownerContainer
+        ) {
+            logger.warn(
+                'preRenderContainer is applied only by the component that creates the preRender; '
+                    + 'the one passed here is ignored. Set it on the PreRender component instead.',
+            );
+        }
+        this.preRenderContainerEl = ownerContainer;
+        this.applyPreRenderContainerPositioning();
+    }
+
+    private getCustomPreRenderContainer(): HTMLElement | null {
+        const container = this.preRenderContainerEl;
+        return container && container !== document.body ? container : null;
+    }
+
     /**
-     * Makes the container a positioning context for the absolutely positioned
-     * wrapper, stashing the original inline `position` on the element (once) so
-     * destroy() can restore it exactly, leaving no trace. Recording it on the
-     * element rather than per-instance lets the override be reverted even when
-     * embeds share the same container.
+     * Makes the resolved container a positioning context for the absolutely
+     * positioned wrapper, stashing the original inline `position` on the element
+     * (once) so destroy() can restore it exactly, leaving no trace. Recording it
+     * on the element rather than per-instance lets the override be reverted even
+     * when embeds share the same container.
      */
-    private applyPreRenderContainerPositioning(container: HTMLElement): void {
-        if (container === document.body) {
+    private applyPreRenderContainerPositioning(): void {
+        const container = this.getCustomPreRenderContainer();
+        if (!container) {
             return;
         }
         const pos = window.getComputedStyle(container).position;
@@ -1247,11 +1292,11 @@ export class TsEmbed {
                 resolved.addEventListener('scroll', this.containerScrollListener);
             }
         }
-        this.applyPreRenderContainerPositioning(resolved);
+        this.preRenderContainerEl = resolved;
+        this.applyPreRenderContainerPositioning();
         if (wrapper.parentNode !== resolved) {
             resolved.appendChild(wrapper);
         }
-        this.preRenderContainerEl = resolved;
     }
 
     protected insertIntoDOMForPreRender(child: string | Node): void {
@@ -1279,7 +1324,7 @@ export class TsEmbed {
 
         const targetContainer = this.resolvePreRenderContainerTarget();
         this.preRenderContainerEl = targetContainer;
-        this.applyPreRenderContainerPositioning(targetContainer);
+        this.applyPreRenderContainerPositioning();
         targetContainer.appendChild(preRenderWrapper);
     }
 
@@ -1625,7 +1670,11 @@ export class TsEmbed {
      * ```
      * @version SDK: 1.45.2 | ThoughtSpot: 26.3.0.cl (for context parameter)
      */
-    public async trigger<HostEventT extends HostEvent, PayloadT, ContextT extends ContextType>(
+    public async trigger<
+        HostEventT extends HostEvent,
+        PayloadT = HostEventRequest<HostEventT>,
+        ContextT extends ContextType = ContextType,
+    >(
         messageType: HostEventT,
         data: TriggerPayload<PayloadT, HostEventT> = {} as any,
         context?: ContextT,
@@ -1710,6 +1759,9 @@ export class TsEmbed {
      * @param args
      */
     public async render(): Promise<TsEmbed> {
+        uploadMixpanelEvent(MIXPANEL_EVENT.VISUAL_SDK_RENDER_CALLED, {
+            embedComponentType: this.viewConfig.embedComponentType,
+        });
         if (!getIsInitCalled()) {
             logger.error(ERROR_MESSAGE.RENDER_CALLED_BEFORE_INIT);
         }
@@ -1790,7 +1842,11 @@ export class TsEmbed {
         showPreRenderByDefault = false,
         replaceExistingPreRender = false,
     ): Promise<TsEmbed> {
-        if (!this.viewConfig.preRenderId) {
+        uploadMixpanelEvent(MIXPANEL_EVENT.VISUAL_SDK_PRE_RENDER, {
+            showPreRenderByDefault,
+            replaceExistingPreRender,
+        });
+        if (!this.getPreRenderConfig().preRenderId) {
             logger.error(ERROR_MESSAGE.PRERENDER_ID_MISSING);
             return this;
         }
@@ -1849,13 +1905,13 @@ export class TsEmbed {
      * same container — a shared container still needs the positioning context.
      */
     private restorePreRenderContainerPosition(): void {
-        const container = this.preRenderContainerEl as HTMLElement | null;
+        const container = this.preRenderContainerEl;
         if (!container || container === document.body) {
             return;
         }
         // Drop our reference up front so a destroyed embed never pins a
         // detached container in memory; restoration uses the local handle.
-        this.preRenderContainerEl = null;
+        this.preRenderContainerEl = document.body;
         const originalPosition = container.dataset[PRERENDER_CONTAINER_ORIGINAL_POSITION_KEY];
         if (originalPosition === undefined) {
             // We never overrode this container's position; nothing to restore.
@@ -1881,10 +1937,7 @@ export class TsEmbed {
         if (!this.containerScrollListener) {
             return;
         }
-        const customContainer = 
-            this.preRenderContainerEl && this.preRenderContainerEl !== document.body
-                ? this.preRenderContainerEl
-                : null;
+        const customContainer = this.getCustomPreRenderContainer();
         customContainer?.removeEventListener('scroll', this.containerScrollListener);
         this.containerScrollListener = null;
     }
@@ -1978,9 +2031,15 @@ export class TsEmbed {
      * wrapper to overlay it.
      */
     public async showPreRender(): Promise<TsEmbed> {
+        uploadMixpanelEvent(MIXPANEL_EVENT.VISUAL_SDK_SHOW_PRE_RENDER, {
+            preRenderId: this.getPreRenderConfig().preRenderId,
+            embedComponentType: this.viewConfig.embedComponentType,
+        });
+
         if (this.shouldWaitForRenderPromise) await this.isReadyForRenderPromise;
 
-        if (!this.viewConfig.preRenderId) {
+
+        if (!this.getPreRenderConfig().preRenderId) {
             logger.error(ERROR_MESSAGE.PRERENDER_ID_MISSING);
             return this;
         }
@@ -2016,16 +2075,13 @@ export class TsEmbed {
 
             this.syncPreRenderStyle();
 
-            const customContainer =
-                this.preRenderContainerEl && this.preRenderContainerEl !== document.body
-                    ? this.preRenderContainerEl
-                    : null;
+            const customContainer = this.getCustomPreRenderContainer();
             if (customContainer && !this.containerScrollListener) {
                 this.containerScrollListener = () => this.syncPreRenderStyle();
                 customContainer.addEventListener('scroll', this.containerScrollListener);
             }
 
-            if (!this.viewConfig.doNotTrackPreRenderSize) {
+            if (!this.getPreRenderConfig().doNotTrackPreRenderSize) {
                 const observeTarget = (this.insertedDomEl as HTMLElement) ?? this.hostElement;
                 this.resizeObserver = new ResizeObserver((entries) => {
                     entries.forEach((entry) => {
@@ -2071,15 +2127,16 @@ export class TsEmbed {
             logger.error(ERROR_MESSAGE.SYNC_STYLE_CALLED_BEFORE_RENDER);
             return;
         }
+        if (!this.getPreRenderPlaceHolderElement().isConnected) {
+            logger.debug('syncPreRenderStyle skipped: placeholder is detached');
+            return;
+        }
         // Self-heal if the resolved container was remounted/detached, so we
         // never measure a stale node (which would collapse the wrapper).
         this.reconcilePreRenderContainer();
         const elBoundingClient = this.getPreRenderPlaceHolderElement().getBoundingClientRect();
 
-        const containerEl =
-            this.preRenderContainerEl && this.preRenderContainerEl !== document.body
-                ? this.preRenderContainerEl
-                : null;
+        const containerEl = this.getCustomPreRenderContainer();
         const containerRect = containerEl?.getBoundingClientRect() ?? { x: 0, y: 0 };
         const scrollX = containerEl ? containerEl.scrollLeft : window.scrollX;
         const scrollY = containerEl ? containerEl.scrollTop : window.scrollY;
@@ -2098,16 +2155,22 @@ export class TsEmbed {
      * If the component is not preRendered, it issues a warning.
      */
     public hidePreRender(): void {
+        uploadMixpanelEvent(MIXPANEL_EVENT.VISUAL_SDK_HIDE_PRE_RENDER, {
+            preRenderId: this.getPreRenderConfig().preRenderId,
+            embedComponentType: this.viewConfig.embedComponentType,
+        });
+
         logger.debug('HidePreRender Called');
         if (!this.isPreRenderConnected()) {
             // if the embed component is not preRendered , nothing to hide
             logger.warn('PreRender should be called before hiding it using hidePreRender.');
             return;
         }
+        const { zIndex } = this.getPreRenderConfig();
         const preRenderHideStyles = {
             opacity: '0',
             pointerEvents: 'none',
-            zIndex: '-1000',
+            zIndex: zIndex !== undefined ? String(zIndex) : '-1000',
             position: 'absolute',
             top: '0',
             left: '0',
@@ -2137,10 +2200,11 @@ export class TsEmbed {
      * @property {string} child - The HTML element ID for the PreRender child.
      */
     public getPreRenderIds() {
+        const preRenderId = this.getPreRenderConfig().preRenderId;
         return {
-            wrapper: `${PRERENDER_WRAPPER_ID_PREFIX}${this.viewConfig.preRenderId}`,
-            child: `tsEmbed-pre-render-child-${this.viewConfig.preRenderId}`,
-            placeHolder: `tsEmbed-pre-render-placeholder-${this.viewConfig.preRenderId}`,
+            wrapper: `${PRERENDER_WRAPPER_ID_PREFIX}${preRenderId}`,
+            child: `tsEmbed-pre-render-child-${preRenderId}`,
+            placeHolder: `tsEmbed-pre-render-placeholder-${preRenderId}`,
         };
     }
 

package/src/index.ts

@@ -32,7 +32,7 @@ import { PinboardEmbed, LiveboardViewConfig, LiveboardEmbed } from './embed/live
 import { SearchEmbed, SearchViewConfig } from './embed/search';
 import { SearchBarEmbed, SearchBarViewConfig } from './embed/search-bar';
 import { SpotterAgentEmbed, SpotterAgentEmbedViewConfig, BodylessConversation, BodylessConversationViewConfig} from './embed/bodyless-conversation';
-import { SpotterEmbed, SpotterEmbedViewConfig, SpotterChatViewConfig, SpotterSidebarViewConfig, SpotterQueryMode, ConversationEmbed, ConversationViewConfig } from './embed/conversation';
+import { SpotterEmbed, SpotterEmbedViewConfig, SpotterChatViewConfig, SpotterSidebarViewConfig, SpotterAnalystConfig, SpotterQueryMode, SpotterShareConversationConfig, StarterPromptsConfig, StarterPromptCategory, StarterPreviewDataCategory, StarterPromptQuestion, ConversationEmbed, ConversationViewConfig } from './embed/conversation';
 import { SpotterVizConfig, SpotterVizStarterPrompt, SpotterVizLoaderTip } from './embed/spotter-viz-utils';
 import {
     AuthFailureType, AuthStatus, AuthEvent, AuthEventEmitter,
@@ -88,7 +88,24 @@ import { uploadMixpanelEvent, MIXPANEL_EVENT } from './mixpanel-service';
 import { tokenizedFetch } from './tokenizedFetch';
 import { getAnswerFromQuery } from './utils/graphql/nlsService/nls-answer-service';
 import { createLiveboardWithAnswers } from './utils/liveboardService/liveboardService';
-import { UIPassthroughEvent } from './embed/hostEventClient/contracts';
+import {
+    UIPassthroughEvent,
+    UIPassthroughContractBase,
+    UIPassthroughRequest,
+    UIPassthroughResponse,
+    UIPassthroughArrayResponse,
+    HostEventRequest,
+    HostEventResponse,
+    TriggerPayload,
+    TriggerResponse,
+    LiveboardTab,
+    LiveboardGroup,
+    ApplicabilityLevel,
+    Applicability,
+    FilterUpdate,
+    LiveboardFilter,
+    LiveboardParameter,
+} from './embed/hostEventClient/contracts';
 
 export {
     init,
@@ -117,7 +134,13 @@ export {
     SpotterEmbedViewConfig,
     SpotterChatViewConfig,
     SpotterSidebarViewConfig,
+    SpotterAnalystConfig,
     SpotterQueryMode,
+    SpotterShareConversationConfig,
+    StarterPromptsConfig,
+    StarterPromptCategory,
+    StarterPreviewDataCategory,
+    StarterPromptQuestion,
     ConversationViewConfig,
     ConversationEmbed,
     AuthFailureType,
@@ -169,6 +192,25 @@ export {
     VizPoint,
     CustomActionPayload,
     UIPassthroughEvent,
+    // Host event payload / response contracts. These describe what to send with
+    // `embed.trigger(HostEvent.X, payload)` and what the returned promise
+    // resolves with. See `UIPassthroughContractBase` for the per-event
+    // request/response shapes.
+    UIPassthroughContractBase,
+    UIPassthroughRequest,
+    UIPassthroughResponse,
+    UIPassthroughArrayResponse,
+    HostEventRequest,
+    HostEventResponse,
+    TriggerPayload,
+    TriggerResponse,
+    LiveboardTab,
+    LiveboardGroup,
+    ApplicabilityLevel,
+    Applicability,
+    FilterUpdate,
+    LiveboardFilter,
+    LiveboardParameter,
     ListPageColumns,
     DataPanelCustomColumnGroupsAccordionState,
     CustomActionsPosition,

package/src/mixpanel-service.ts

@@ -26,6 +26,10 @@ export const MIXPANEL_EVENT = {
     VISUAL_SDK_IFRAME_LOAD_PERFORMANCE: 'visual-sdk-iframe-load-performance',
     VISUAL_SDK_EMBED_CREATE: 'visual-sdk-embed-create',
     VERCEL_INTEGRATION_COMPLETED: 'vercel-integration-completed',
+    VISUAL_SDK_RENDER_CALLED: 'visual-sdk-render-called',
+    VISUAL_SDK_PRE_RENDER: 'visual-sdk-pre-render',
+    VISUAL_SDK_SHOW_PRE_RENDER: 'visual-sdk-show-pre-render',
+    VISUAL_SDK_HIDE_PRE_RENDER: 'visual-sdk-hide-pre-render',
 };
 
 let isMixpanelInitialized = false;

package/src/react/all-types-export.parity.spec.ts

@@ -0,0 +1,208 @@
+/**
+ * Parity gate: every symbol exported from `src/index.ts` must also be exported
+ * from `src/react/all-types-export.ts`.
+ *
+ * `package.json` `exports` restricts consumers to two entry points — `.` and
+ * `./react` — and the React surface is a HAND-MAINTAINED duplicate export list,
+ * not a `export * from '../index'`. So a symbol added only to `src/index.ts` is
+ * invisible to every React consumer.
+ *
+ * The sibling `all-types-export.spec.ts` cannot catch this: it inspects the
+ * module at runtime, and type-only exports (interfaces, type aliases) are
+ * erased by the compiler. This spec therefore compares the two files as TEXT.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+const INDEX_PATH = path.join(__dirname, '..', 'index.ts');
+const REACT_EXPORT_PATH = path.join(__dirname, 'all-types-export.ts');
+
+/**
+ * Symbols intentionally absent from the React surface.
+ * Add here only with a reason — every entry is a thing React users cannot use.
+ */
+const REACT_EXEMPT = new Set<string>([
+    // React has its own component wrappers for these; the raw classes are not
+    // part of the /react surface.
+    'SearchEmbed',
+    'SearchBarEmbed',
+    'LiveboardEmbed',
+    'AppEmbed',
+    'SpotterEmbed',
+    'SpotterAgentEmbed',
+    'ConversationEmbed',
+    'BodylessConversation',
+    'PreRenderedSearchEmbed',
+    'PreRenderedSearchBarEmbed',
+    'PreRenderedLiveboardEmbed',
+    'PreRenderedAppEmbed',
+    'PreRenderedConversationEmbed',
+    'PinboardEmbed',
+    'TsEmbed',
+    'V1Embed',
+]);
+
+/**
+ * PRE-EXISTING gaps, discovered when this spec was introduced. These are
+ * symbols React consumers cannot import today — most look like oversights
+ * rather than deliberate omissions (e.g. `ContextType`, `CustomActionPayload`,
+ * `VizPoint`, the Spotter view configs).
+ *
+ * This list may only ever SHRINK. Do not add to it — a new entry means a
+ * symbol was added to `src/index.ts` without adding it to the React surface,
+ * which is exactly what this spec exists to prevent. Removing entries (by
+ * exporting them from `all-types-export.ts`) is a welcome follow-up; it is
+ * deliberately out of scope for the change that introduced this gate.
+ */
+const KNOWN_REACT_GAPS = new Set<string>([
+    'AnswerService',
+    'AutoMCPFrameRendererViewConfig',
+    'BackgroundFormatType',
+    'BodylessConversationViewConfig',
+    'ConditionalFormattingComparisonType',
+    'ConditionalFormattingOperator',
+    'ContextMenuTriggerOptions',
+    'ContextType',
+    'ConversationViewConfig',
+    'CustomActionPayload',
+    'DataLabelFilterOperator',
+    'EmbedErrorCodes',
+    'EmbedErrorDetailsEvent',
+    'ErrorDetailsTypes',
+    'HomeLeftNavItem',
+    'HomePage',
+    'HomePageSearchBarMode',
+    'HomepageModule',
+    'LegendPosition',
+    'ListPage',
+    'ListPageColumns',
+    'LogLevel',
+    'MIXPANEL_EVENT',
+    'PrimaryNavbarVersion',
+    'SessionInterface',
+    'SpotterAgentEmbedViewConfig',
+    'SpotterChatViewConfig',
+    'SpotterEmbedViewConfig',
+    'SpotterQueryMode',
+    'SpotterShareConversationConfig',
+    'SpotterSidebarViewConfig',
+    'SpotterVizConfig',
+    'SpotterVizLoaderTip',
+    'SpotterVizStarterPrompt',
+    'TableContentDensity',
+    'TableTheme',
+    'UnderlyingDataPoint',
+    'VisualizationOverrides',
+    'VizPoint',
+    // Standalone helpers re-exported from src/index.ts outside the main block.
+    'createLiveboardWithAnswers',
+    'executeTML',
+    'executeTMLInput',
+    'exportTML',
+    'exportTMLInput',
+    'getAnswerFromQuery',
+    'startAutoMCPFrameRenderer',
+    'tokenizedFetch',
+]);
+
+/**
+ * Extract identifiers from every `export { ... }` / `export type { ... }` block
+ * in a source file. Handles `a`, `a as b` (records the exported name `b`),
+ * comments and trailing commas.
+ *
+ * `export * from '...'` cannot be enumerated by name (the names live in another
+ * module), so it would silently defeat this parity gate. We refuse to run
+ * against it: if either file adopts a star re-export, this throws so the gate
+ * is extended deliberately rather than passing blind.
+ */
+const extractExportedNames = (source: string): Set<string> => {
+    if (/export\s*\*/.test(source)) {
+        throw new Error(
+            'Parity extractor found an `export *` re-export, which it cannot '
+            + 'enumerate by name. Extend extractExportedNames to resolve star '
+            + 'exports before relying on this gate.',
+        );
+    }
+    const names = new Set<string>();
+    // Matches `export { ... }` and `export type { ... }`.
+    const blockRe = /export\s*(?:type\s+)?\{([\s\S]*?)\}/g;
+    let match = blockRe.exec(source);
+    while (match !== null) {
+        match[1]
+            // strip line and block comments
+            .replace(/\/\*[\s\S]*?\*\//g, '')
+            .replace(/\/\/[^\n]*/g, '')
+            .split(',')
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .forEach((entry) => {
+                // `foo as bar` exports the name `bar`
+                const parts = entry.split(/\s+as\s+/);
+                const exported = (parts[parts.length - 1] || '').trim();
+                if (/^[A-Za-z_$][\w$]*$/.test(exported)) {
+                    names.add(exported);
+                }
+            });
+        match = blockRe.exec(source);
+    }
+    return names;
+};
+
+describe('react/all-types-export parity with index', () => {
+    it('exports every symbol that src/index.ts exports', () => {
+        const indexNames = extractExportedNames(fs.readFileSync(INDEX_PATH, 'utf8'));
+        const reactNames = extractExportedNames(fs.readFileSync(REACT_EXPORT_PATH, 'utf8'));
+
+        // Sanity: the extractor found something. Guards against a regex that
+        // silently matches nothing after a refactor.
+        expect(indexNames.size).toBeGreaterThan(50);
+        expect(reactNames.size).toBeGreaterThan(50);
+
+        const missing = [...indexNames]
+            .filter((name) => !reactNames.has(name))
+            .filter((name) => !REACT_EXEMPT.has(name))
+            .filter((name) => !KNOWN_REACT_GAPS.has(name))
+            .sort();
+
+        if (missing.length > 0) {
+            throw new Error(
+                'These symbols are exported from src/index.ts but NOT from '
+                    + 'src/react/all-types-export.ts, so React consumers cannot '
+                    + `import them:\n  ${missing.join('\n  ')}\n\n`
+                    + 'Add them to src/react/all-types-export.ts. Do NOT add them '
+                    + 'to KNOWN_REACT_GAPS — that list is a shrinking backlog of '
+                    + 'pre-existing gaps and must never grow.',
+            );
+        }
+    });
+
+    it('KNOWN_REACT_GAPS only lists symbols that are genuinely still missing', () => {
+        // Ratchet: once a gap is fixed, its entry must be deleted, so the list
+        // can only shrink.
+        const indexNames = extractExportedNames(fs.readFileSync(INDEX_PATH, 'utf8'));
+        const reactNames = extractExportedNames(fs.readFileSync(REACT_EXPORT_PATH, 'utf8'));
+
+        const stale = [...KNOWN_REACT_GAPS]
+            .filter((name) => reactNames.has(name) || !indexNames.has(name))
+            .sort();
+
+        if (stale.length > 0) {
+            throw new Error(
+                'These entries in KNOWN_REACT_GAPS are no longer gaps (they are '
+                    + 'now exported from the React surface, or no longer exported '
+                    + `from src/index.ts). Delete them from the list:\n  ${stale.join('\n  ')}`,
+            );
+        }
+    });
+
+    it('exposes the host event contract types on the React surface', () => {
+        const reactNames = extractExportedNames(fs.readFileSync(REACT_EXPORT_PATH, 'utf8'));
+        [
+            'UIPassthroughContractBase',
+            'HostEventRequest',
+            'HostEventResponse',
+            'TriggerPayload',
+            'TriggerResponse',
+        ].forEach((name) => expect(reactNames.has(name)).toBe(true));
+    });
+});

package/src/react/all-types-export.ts

@@ -56,8 +56,30 @@ export {
     RuntimeParameter,
     resetCachedAuthToken,
     UIPassthroughEvent,
+    // Host event payload / response contracts — kept in sync with src/index.ts
+    // (enforced by all-types-export.parity.spec.ts).
+    UIPassthroughContractBase,
+    UIPassthroughRequest,
+    UIPassthroughResponse,
+    UIPassthroughArrayResponse,
+    HostEventRequest,
+    HostEventResponse,
+    TriggerPayload,
+    TriggerResponse,
+    LiveboardTab,
+    LiveboardGroup,
+    ApplicabilityLevel,
+    Applicability,
+    FilterUpdate,
+    LiveboardFilter,
+    LiveboardParameter,
     DataPanelCustomColumnGroupsAccordionState,
     InterceptedApiType,
     CustomActionsPosition,
     CustomActionTarget,
+    SpotterAnalystConfig,
+    StarterPromptsConfig,
+    StarterPromptCategory,
+    StarterPreviewDataCategory,
+    StarterPromptQuestion,
 } from '../index';