@gengage/assistant-fe 0.5.7 → 0.6.0

package/dist/common/native-webview.d.ts

@@ -0,0 +1,60 @@
+import type { OverlayWidgetsController, OverlayWidgetsOptions } from './overlay.js';
+export declare const DEFAULT_NATIVE_TRACKED_EVENTS: readonly ["gengage:chat:open", "gengage:chat:close", "gengage:chat:ready", "gengage:chat:add-to-cart", "gengage:qna:action", "gengage:qna:open-chat", "gengage:similar:product-click", "gengage:similar:grouping-click", "gengage:similar:products-impression", "gengage:similar:add-to-cart", "gengage:global:error", "gengage:context:update"];
+export type NativeTrackedEvent = (typeof DEFAULT_NATIVE_TRACKED_EVENTS)[number];
+export type NativeInboundMessage = 'openChat' | 'closeChat' | 'updateContext' | 'updatePageContext' | 'setPageContext' | 'updateSku' | 'setSession' | 'destroy';
+export type NativeBridgeEnvironment = 'ios' | 'android' | 'react-native' | 'browser';
+export interface NativeSessionPayload {
+    sessionId?: string;
+    userId?: string;
+}
+export interface NativeBridgeMessage {
+    type: string;
+    payload?: unknown;
+}
+export interface NativeWebViewBridgeOptions {
+    iosHandlerName?: string;
+    androidInterfaceName?: string;
+    reactNativeInterfaceName?: string;
+    trackedEvents?: NativeTrackedEvent[] | string[];
+    /** Log unhandled inbound message types to console in addition to forwarding to postMessage. */
+    logUnhandled?: boolean;
+    /** Injected for tests; defaults to global window. */
+    win?: Window;
+}
+export interface NativeWebViewBridge {
+    readonly env: NativeBridgeEnvironment;
+    sendToNative(type: string, payload?: unknown): void;
+    receive(message: NativeBridgeMessage | string): void;
+    setController(controller: OverlayWidgetsController | null): void;
+    destroy(): void;
+}
+export interface NativeOverlayInitOptions extends OverlayWidgetsOptions {
+    nativeBridge?: Omit<NativeWebViewBridgeOptions, 'win'>;
+    emitReadyEvent?: boolean;
+}
+export interface NativeOverlayInitResult {
+    controller: OverlayWidgetsController;
+    bridge: NativeWebViewBridge;
+    destroy(): void;
+}
+export declare function detectNativeEnvironment(options?: Pick<NativeWebViewBridgeOptions, 'iosHandlerName' | 'androidInterfaceName' | 'reactNativeInterfaceName' | 'win'>): NativeBridgeEnvironment;
+/**
+ * Applies native-provided session identity so widgets can share correlation IDs
+ * with the host app. Safe to call before or after widget initialization.
+ */
+export declare function applyNativeSession(payload: NativeSessionPayload, options?: Pick<NativeWebViewBridgeOptions, 'win'>): void;
+/**
+ * Installs a native WebView bridge compatible with:
+ *  - iOS WKWebView (`webkit.messageHandlers`)
+ *  - Android JavascriptInterface (`window.GengageNative`)
+ *  - React Native WebView (`window.ReactNativeWebView`)
+ * and exposes it on `window.gengageNative`.
+ */
+export declare function createNativeWebViewBridge(options?: NativeWebViewBridgeOptions): NativeWebViewBridge;
+/**
+ * Convenience helper for mobile WebViews:
+ *  1) installs native bridge
+ *  2) initializes overlay widgets
+ *  3) sends a `ready` message to native
+ */
+export declare function initNativeOverlayWidgets(options: NativeOverlayInitOptions): Promise<NativeOverlayInitResult>;

package/dist/common/navigation.d.ts

@@ -0,0 +1 @@
+export declare function navigateToUrl(url: string, newTab?: boolean): boolean;

package/dist/common/overlay.d.ts

@@ -0,0 +1,172 @@
+import type { GengageChat } from '../chat/runtime.js';
+import type { ChatI18n, ChatWidgetConfig } from '../chat/types.js';
+import type { GengageQNA } from '../qna/runtime.js';
+import type { QNAWidgetConfig } from '../qna/types.js';
+import type { GengageSimRel } from '../simrel/runtime.js';
+import type { SimRelWidgetConfig } from '../simrel/types.js';
+import type { GengageSimBut } from '../simbut/index.js';
+import type { SimButWidgetConfig } from '../simbut/types.js';
+import type { AddToCartHandlerResult, AddToCartParams, PageContext, SessionContext, WidgetTheme } from './types.js';
+import type { InjectorAdapter } from './transport.js';
+export interface OverlayChatOptions {
+    enabled?: boolean;
+    /** AGENTIC_ADAPTER_SEAM: optional chat transport override from the injector. */
+    injectorAdapter?: InjectorAdapter;
+    variant?: ChatWidgetConfig['variant'];
+    mountTarget?: HTMLElement | string;
+    launcherSvg?: string;
+    launcherImageUrl?: string;
+    mobileLauncherImageUrl?: string;
+    headerTitle?: string;
+    headerAvatarUrl?: string;
+    headerBadge?: string;
+    headerCartUrl?: string;
+    headerFavoritesToggle?: boolean;
+    /** Opens merchant favorites page (passed to chat `onFavoritesClick`). */
+    onFavoritesClick?: () => void;
+    hideMobileLauncher?: boolean;
+    mobileBreakpoint?: number;
+    mobileInitialState?: 'half' | 'full';
+    i18n?: Partial<ChatI18n>;
+    actionHandling?: ChatWidgetConfig['actionHandling'];
+    /** UISpec renderer overrides for chat components. */
+    renderer?: ChatWidgetConfig['renderer'];
+    /** When true, allow full product details in the assistant side panel; default is chat summary only. */
+    productDetailsExtended?: boolean;
+    /** Hides percent discount badges on chat product cards / details when true. */
+    hideProductDiscountBadge?: ChatWidgetConfig['hideProductDiscountBadge'];
+    /** When true, hides user reviews (ReviewHighlights, review chip, AITopPicks reviewHighlight). */
+    hideUserReviews?: ChatWidgetConfig['hideUserReviews'];
+    /** When true, hides in-stock / out-of-stock labels on product cards. */
+    hideStockStatus?: ChatWidgetConfig['hideStockStatus'];
+    isDemoWebsite?: ChatWidgetConfig['isDemoWebsite'];
+    /** Pill launcher — forwarded to `chat.pillLauncher` (applied inside GengageChat). */
+    pillLauncher?: ChatWidgetConfig['pillLauncher'];
+    /** Search-bar style floating launcher — forwarded to `chat.floatingLauncher`. */
+    floatingLauncher?: ChatWidgetConfig['floatingLauncher'];
+    /** Dynamic launcher positioning relative to page elements. */
+    launcherAnchor?: ChatWidgetConfig['launcherAnchor'];
+    /** Called when the chat panel opens. */
+    onOpen?: () => void;
+    /** Called when the chat panel closes. */
+    onClose?: () => void;
+    productPriceUi?: ChatWidgetConfig['productPriceUi'];
+}
+export interface OverlayQNAOptions {
+    enabled?: boolean;
+    mountTarget?: HTMLElement | string;
+    chrome?: QNAWidgetConfig['chrome'];
+    ctaText?: string;
+    hideButtonRowCta?: boolean;
+    inputPlaceholder?: QNAWidgetConfig['inputPlaceholder'];
+    inputAfterPills?: QNAWidgetConfig['inputAfterPills'];
+    i18n?: QNAWidgetConfig['i18n'];
+    /** UISpec renderer overrides for QNA components. */
+    renderer?: QNAWidgetConfig['renderer'];
+    /**
+     * Q&A panel heading (e.g. "Koçtaş'a Sor"). Independent from `chat.headerTitle`.
+     * If omitted, falls back to the deprecated `headingTitle` field.
+     * Set this explicitly — it does not inherit from `chat.headerTitle`.
+     */
+    headerTitle?: string;
+    /** @deprecated Use `headerTitle` */
+    headingTitle?: string;
+}
+export interface OverlaySimRelOptions {
+    enabled?: boolean;
+    mountTarget?: HTMLElement | string;
+    discountType?: SimRelWidgetConfig['discountType'];
+    gridColumns?: SimRelWidgetConfig['gridColumns'];
+    enableProductGroupings?: SimRelWidgetConfig['enableProductGroupings'];
+    /** Custom card element renderer for the direct rendering path (GroupTabs/ProductGrid). */
+    renderCardElement?: SimRelWidgetConfig['renderCardElement'];
+    /** UISpec renderer overrides for simrel components. */
+    renderer?: SimRelWidgetConfig['renderer'];
+}
+export interface OverlaySimButOptions {
+    enabled?: boolean;
+    mountTarget?: HTMLElement | string;
+    layout?: SimButWidgetConfig['layout'];
+    inlineCard?: SimButWidgetConfig['inlineCard'];
+    /** Optional product image URL for custom `onFindSimilar`; chat actions use SKU when available. */
+    imageUrl?: string;
+    i18n?: SimButWidgetConfig['i18n'];
+    /** Custom click behavior, used instead of `chat` when provided. */
+    onFindSimilar?: SimButWidgetConfig['onFindSimilar'];
+}
+export interface OverlayWidgetsOptions {
+    accountId: string;
+    middlewareUrl: string;
+    /** AGENTIC_ADAPTER_SEAM: top-level adapter forwarded into chat only. */
+    injectorAdapter?: InjectorAdapter;
+    locale?: string;
+    session?: Partial<SessionContext>;
+    pageContext?: Partial<PageContext>;
+    sku?: string;
+    theme?: WidgetTheme;
+    /** Backward-compatible alias for `chat.isDemoWebsite`. */
+    isDemoWebsite?: ChatWidgetConfig['isDemoWebsite'];
+    /** Backward-compatible alias for `chat.productDetailsExtended`. */
+    productDetailsExtended?: ChatWidgetConfig['productDetailsExtended'];
+    /** Price formatting options. Defaults to Turkish locale. */
+    pricing?: import('./price-formatter.js').PriceFormatConfig;
+    idempotencyKey?: string;
+    wireQnaToChat?: boolean;
+    chat?: OverlayChatOptions;
+    qna?: OverlayQNAOptions;
+    simrel?: OverlaySimRelOptions;
+    simbut?: OverlaySimButOptions;
+    onAddToCart?: (params: AddToCartParams) => AddToCartHandlerResult;
+    onProductNavigate?: SimRelWidgetConfig['onProductNavigate'];
+    onScriptCall?: ChatWidgetConfig['onScriptCall'];
+}
+export interface OverlayWidgetsController {
+    readonly idempotencyKey: string;
+    readonly session: SessionContext;
+    readonly chat: GengageChat | null;
+    readonly qna: GengageQNA | null;
+    readonly simrel: GengageSimRel | null;
+    readonly simbut: GengageSimBut | null;
+    openChat(options?: {
+        state?: 'half' | 'full';
+    }): void;
+    closeChat(): void;
+    /**
+     * Merges partial page context (SKU, page type, category, …) into the active
+     * widgets. Use after SPA navigation so chat and PDP stay aligned.
+     */
+    updateContext(patch: Partial<PageContext>): Promise<void>;
+    /** @see {@link updateContext} */
+    updatePageContext(patch: Partial<PageContext>): Promise<void>;
+    /**
+     * Merge-only page context update. This is an alias of {@link updateContext},
+     * not a full replacement of the existing PageContext.
+     */
+    setPageContext(patch: Partial<PageContext>): Promise<void>;
+    updateSku(sku: string, pageType?: PageContext['pageType']): Promise<void>;
+    destroy(): void;
+}
+/**
+ * Initialize chat, QNA, SimRel, and optional SimBut (PDP image “find similar” pill) in one call.
+ * Idempotent — safe to call multiple times from GTM; deduplicates by account + SKU key.
+ *
+ * @example
+ * ```ts
+ * import { initOverlayWidgets } from '@gengage/assistant-fe/overlay';
+ *
+ * const controller = await initOverlayWidgets({
+ *   accountId: 'mystore',
+ *   middlewareUrl: '<backend service location provided for your Gengage account>',
+ *   sku: window.productSku,
+ *   pageContext: { pageType: 'pdp' },
+ *   chat: { variant: 'floating' },
+ *   qna: { mountTarget: '#qna-section' },
+ *   simrel: { mountTarget: '#similar-products' },
+ *   simbut: { mountTarget: '#pdp-image-wrap' },
+ * });
+ * ```
+ */
+export declare function initOverlayWidgets(options: OverlayWidgetsOptions): Promise<OverlayWidgetsController>;
+export declare function getOverlayWidgets(idempotencyKey: string): OverlayWidgetsController | null;
+export declare function destroyOverlayWidgets(idempotencyKey: string): void;
+export declare function buildOverlayIdempotencyKey(accountId: string): string;

package/dist/common/page-detect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * URL-based page type detection.
+ *
+ * Provides auto-detection of page type from URL patterns and DOM signals.
+ * Falls back to 'other' when no rule matches.
+ */
+import type { PageContext } from './types.js';
+export type DetectablePageType = PageContext['pageType'];
+export interface PageDetectionRule {
+    /** Page type to assign when this rule matches. */
+    pageType: DetectablePageType;
+    /** URL pathname patterns (tested with `new RegExp(pattern)`). */
+    urlPatterns?: string[];
+    /** If present, page type is detected only when this query param exists. */
+    queryParam?: string;
+    /** DOM selector — if an element matching this exists, rule matches. */
+    selector?: string;
+}
+/**
+ * Detects page type from the current URL and optional DOM signals.
+ *
+ * @param rules - Custom rules (defaults to common Turkish e-commerce patterns).
+ * @param url   - URL to analyze (defaults to window.location).
+ * @returns Detected page type, or 'other' if no rule matches.
+ */
+export declare function detectPageType(rules?: PageDetectionRule[], url?: URL): DetectablePageType;
+/**
+ * Attempts to extract a product SKU from the URL path.
+ * Looks for common patterns like `/p/SKU`, `/urun/SKU`, `/-p-SKU`.
+ */
+export declare function extractSkuFromUrl(url?: URL): string | undefined;
+/**
+ * Auto-detects page context from URL and DOM signals.
+ * Use as a fallback when the host page doesn't set pageContext explicitly.
+ */
+export declare function autoDetectPageContext(rules?: PageDetectionRule[]): Partial<PageContext>;

package/dist/common/pill-launcher.d.ts

@@ -0,0 +1,51 @@
+/**
+ * makePillLauncher — creates a pill-shaped chat launcher that combines an
+ * avatar image with a text label, replacing the default circular FAB.
+ *
+
+ *   });
+ *
+ * Or call `makePillLauncher` + `apply()` manually when you need custom control.
+ */
+export interface PillLauncherOptions {
+    /** Text label shown beside the avatar inside the pill */
+    label: string;
+    /** Avatar image URL — also used as `launcherImageUrl` to activate image-mode */
+    avatarUrl: string;
+    /** Brand primary color — used for border and hover effects */
+    primaryColor: string;
+    /** Dark text / shadow color for the label and drop shadow (default: '#111827') */
+    secondaryColor?: string;
+    /** CSS font-family string for the label text */
+    fontFamily?: string;
+    /** CSS class name injected on the label span (default: 'gengage-pill-launcher-label') */
+    labelClassName?: string;
+    /** id for the <style> tag injected into the shadow root (default: 'gengage-pill-launcher-style') */
+    styleId?: string;
+    /** Mobile breakpoint in px (default: 768) */
+    mobileBreakpoint?: number;
+    /** Desktop pill width (default: '188px') */
+    desktopWidth?: string;
+    /** Desktop pill height (default: '60px') */
+    desktopHeight?: string;
+    /** Avatar icon diameter (default: '46px') */
+    iconSize?: string;
+}
+export interface PillLauncherKit {
+    /**
+     * Pass as `chat.launcherImageUrl` to `initOverlayWidgets`.
+     * Equals `avatarUrl` — activates image-mode on the launcher button.
+     */
+    launcherImageUrl: string;
+    /**
+     * Call after `initOverlayWidgets` resolves.
+     * Injects pill CSS into the widget shadow root, fixes the header avatar
+     * class, and appends the text label span to the launcher button.
+     * Retries via requestAnimationFrame for up to ~1.5 s.
+     *
+     * Pass the widget's shadow root when it is available to avoid a global DOM
+     * scan — required when multiple GengageChat instances share the same page.
+     */
+    apply(targetShadow?: ShadowRoot): Promise<void>;
+}
+export declare function makePillLauncher(options: PillLauncherOptions): PillLauncherKit;

package/dist/common/preflight.d.ts

@@ -0,0 +1,13 @@
+import type { AccountRuntimeConfig } from './config-schema.js';
+export interface PreflightWarning {
+    code: string;
+    message: string;
+    severity: 'warn' | 'error';
+}
+export interface PreflightResult {
+    ok: boolean;
+    warnings: PreflightWarning[];
+}
+export declare function preflightDiagnostics(config: AccountRuntimeConfig, options?: {
+    skipCspCheck?: boolean;
+}): PreflightResult;

package/dist/common/price-formatter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Configurable price formatting.
+ *
+ * Defaults to Turkish locale (dot thousands, comma decimal, TL suffix),
+ * but renders whole TL amounts without kurus for a cleaner retail UI.
+ * Configure via widget config `pricing` field for any locale/currency.
+ */
+export interface PriceFormatConfig {
+    /** ISO 4217 currency code (e.g. 'TRY', 'USD'). Not consumed by formatPrice(). */
+    currencyCode?: string;
+    /** Currency symbol. Default: 'TL' */
+    currencySymbol?: string;
+    /** Where to place the symbol. Default: 'suffix' */
+    currencyPosition?: 'prefix' | 'suffix';
+    /** Separator between thousands. Default: '.' (Turkish) */
+    thousandsSeparator?: string;
+    /** Decimal point character. Default: ',' (Turkish) */
+    decimalSeparator?: string;
+    /** Whether to show decimal part for whole numbers. Default: false */
+    alwaysShowDecimals?: boolean;
+}
+/**
+ * Formats a raw numeric price string into the configured locale format.
+ *
+ * Examples (default Turkish):
+ *   "17990"   → "17.990 TL"
+ *   "17990.5" → "17.990,50 TL"
+ *
+ * Examples (GBP prefix):
+ *   "17990" with { currencySymbol: '£', currencyPosition: 'prefix', thousandsSeparator: ',', decimalSeparator: '.' }
+ *   → "£17,990"
+ *
+ * Returns the input as-is if it's not a valid number.
+ */
+export declare function formatPrice(raw: string, config?: PriceFormatConfig): string;

package/dist/common/product-utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared product rendering utilities.
+ *
+ * Extracted from chat/renderUISpec and simrel/ProductCard to eliminate
+ * duplication and provide consistent behavior across all widgets.
+ */
+/** Clamp a rating value to the 0–5 range. Returns 0 for NaN/non-finite. */
+export declare function clampRating(value: number): number;
+/** Clamp a discount percentage to the 0–100 range, rounded to integer. Returns 0 for NaN/non-finite. */
+export declare function clampDiscount(value: number): number;
+/**
+ * Render a star rating string with full, half, and empty stars.
+ *
+ * @param rating - A numeric rating (will be clamped to 0–5).
+ * @param halfStars - Whether to render half-star characters. Defaults to true.
+ * @returns A string like "★★★½☆" or "★★★☆☆" (without half-stars).
+ */
+export declare function renderStarRating(rating: number, halfStars?: boolean): string;
+/**
+ * Create a star rating DOM element with proper half-filled star rendering.
+ *
+ * Uses a CSS-clipped full star overlaid on an empty star for the half-star,
+ * giving a visually accurate half-filled appearance instead of the "½" character.
+ *
+ * @param rating - A numeric rating (will be clamped to 0–5).
+ * @returns An HTMLSpanElement containing the star icons.
+ */
+export declare function createStarRatingElement(rating: number): HTMLSpanElement;
+/**
+ * Attach a one-time error handler that hides the image on load failure.
+ *
+ * Works with any HTMLImageElement. Hides the element by setting
+ * `display: none` so layout doesn't break from broken images.
+ */
+export declare function addImageErrorHandler(img: HTMLImageElement): void;

package/dist/common/protocol-adapter.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Wire protocol adapter.
+ *
+ * Backend emits NDJSON events with `type` values like
+ * `outputText`, `suggestedActions`, `productList`, etc.
+ *
+ * This module translates those backend events into the SDK's normalized
+ * `StreamEvent` model.
+ *
+ * Also handles JSON-mode responses from `similar_products` and
+ * `product_groupings` endpoints.
+ */
+import type { StreamEvent } from './types.js';
+export interface V1Product {
+    sku: string;
+    name: string;
+    brand?: string;
+    images?: string[];
+    price?: number;
+    price_discounted?: number;
+    price_discount_rate?: number;
+    price_currency?: string;
+    discount_reason?: string;
+    url?: string;
+    rating?: number;
+    review_count?: number;
+    cart_code?: string;
+    in_stock?: boolean;
+    description?: string;
+    description_html?: string;
+    features?: Array<{
+        name?: string;
+        key?: string;
+        value?: string | number | boolean;
+        [key: string]: unknown;
+    }>;
+    specifications?: Record<string, string> | Array<{
+        key: string;
+        value: string;
+    }>;
+    short_name?: string;
+    category_ids?: string[];
+    category_names?: string[];
+    variants?: Array<Record<string, unknown>>;
+    facet_hits?: Record<string, unknown> | null;
+    promotions?: string[];
+}
+export declare function adaptBackendEvent(raw: Record<string, unknown>): StreamEvent | null;
+export interface NormalizedProduct {
+    sku: string;
+    name: string;
+    imageUrl?: string;
+    images?: string[];
+    price?: string;
+    originalPrice?: string;
+    discountPercent?: number;
+    url: string;
+    brand?: string;
+    rating?: number;
+    reviewCount?: number;
+    cartCode?: string;
+    inStock?: boolean;
+    variants?: Array<Record<string, unknown>>;
+    discountReason?: string;
+    promotions?: string[];
+    description?: string;
+    descriptionHtml?: string;
+    features?: Array<{
+        name?: string;
+        key?: string;
+        value?: string | number | boolean;
+        [key: string]: unknown;
+    }>;
+    specifications?: Record<string, string> | Array<{
+        key: string;
+        value: string;
+    }>;
+    facetHits?: Record<string, unknown>;
+    categoryNames?: string[];
+    shortName?: string;
+    /** Pass-through bag for backend fields not consumed by the SDK. */
+    extras?: Record<string, unknown>;
+}
+export declare function productToNormalized(p: V1Product): NormalizedProduct;
+export interface SimilarProductsJsonResponse {
+    results: V1Product[];
+    count: number;
+    source_sku?: string;
+}
+export interface ProductGroupingsJsonResponse {
+    intro_message?: string;
+    product_groupings: Array<{
+        name: string;
+        description?: string;
+        highlight?: string;
+        repr_sku?: string;
+        repr_image?: string;
+        group_skus?: string[];
+        group_products?: V1Product[];
+    }>;
+    count: number;
+}
+export declare function normalizeSimilarProductsResponse(json: SimilarProductsJsonResponse): NormalizedProduct[];
+export declare function normalizeProductGroupingsResponse(json: ProductGroupingsJsonResponse): Array<{
+    name: string;
+    highlight?: string;
+    products: NormalizedProduct[];
+}>;

package/dist/common/renderer/dom.d.ts

@@ -0,0 +1,3 @@
+import type { UISpecDomUnknownRenderer, RenderUISpecWithRegistryOptions } from './types.js';
+export declare const defaultUnknownUISpecRenderer: UISpecDomUnknownRenderer<unknown>;
+export declare function renderUISpecWithRegistry<TContext>(options: RenderUISpecWithRegistryOptions<TContext>): HTMLElement;

package/dist/common/renderer/index.d.ts

@@ -0,0 +1,4 @@
+export { renderUISpecWithRegistry, defaultUnknownUISpecRenderer } from './dom.js';
+export { mergeUISpecRegistry } from './registry.js';
+export type { UISpecRenderHelpers, UISpecRendererOverrides } from './overrides.js';
+export type { UISpecDomComponentRenderParams, UISpecDomComponentRenderer, UISpecDomRegistry, UISpecDomUnknownRendererParams, UISpecDomUnknownRenderer, RenderUISpecWithRegistryOptions, } from './types.js';

package/dist/common/renderer/overrides.d.ts

@@ -0,0 +1,23 @@
+import type { UISpec } from '../types.js';
+import type { UISpecDomRegistry, UISpecDomUnknownRenderer } from './types.js';
+export interface UISpecRenderHelpers<TContext> {
+    registry: UISpecDomRegistry<TContext>;
+    unknownRenderer?: UISpecDomUnknownRenderer<TContext>;
+    defaultRender: (spec: UISpec, context: TContext) => HTMLElement;
+}
+export interface UISpecRendererOverrides<TContext> {
+    /**
+     * Component-level overrides. Merged on top of the widget's default registry.
+     */
+    registry?: Partial<UISpecDomRegistry<TContext>>;
+    /**
+     * Optional fallback for unknown component types.
+     * Defaults to the widget's built-in unknown renderer.
+     */
+    unknownRenderer?: UISpecDomUnknownRenderer<TContext>;
+    /**
+     * Full UISpec rendering override.
+     * Use this to replace the default rendering methodology entirely.
+     */
+    renderUISpec?: (spec: UISpec, context: TContext, helpers: UISpecRenderHelpers<TContext>) => HTMLElement;
+}

package/dist/common/renderer/registry.d.ts

@@ -0,0 +1,2 @@
+import type { UISpecDomRegistry } from './types.js';
+export declare function mergeUISpecRegistry<TContext>(base: UISpecDomRegistry<TContext>, overrides?: Partial<UISpecDomRegistry<TContext>>): UISpecDomRegistry<TContext>;

package/dist/common/renderer/types.d.ts

@@ -0,0 +1,19 @@
+import type { UISpec, UIElement } from '../types.js';
+export interface UISpecDomComponentRenderParams<TContext> {
+    elementId: string;
+    element: UIElement;
+    spec: UISpec;
+    context: TContext;
+    renderElement: (elementId: string) => HTMLElement | null;
+}
+export type UISpecDomComponentRenderer<TContext> = (params: UISpecDomComponentRenderParams<TContext>) => HTMLElement | null;
+export type UISpecDomRegistry<TContext> = Record<string, UISpecDomComponentRenderer<TContext>>;
+export type UISpecDomUnknownRendererParams<TContext> = UISpecDomComponentRenderParams<TContext>;
+export type UISpecDomUnknownRenderer<TContext> = (params: UISpecDomUnknownRendererParams<TContext>) => HTMLElement | null;
+export interface RenderUISpecWithRegistryOptions<TContext> {
+    spec: UISpec;
+    context: TContext;
+    registry: UISpecDomRegistry<TContext>;
+    containerClassName: string;
+    unknownRenderer?: UISpecDomUnknownRenderer<TContext>;
+}

package/dist/common/safe-html.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DOMParser-based HTML sanitizer.
+ *
+ * Backend sends HTML in assistant messages (e.g. KVKK notice).
+ * This module strips dangerous elements/attributes while preserving
+ * safe formatting tags.
+ *
+ * WARNING: Any new injection point that uses innerHTML must call this function first.
+ */
+/** Check if an image URL uses a safe protocol or same-origin absolute path. */
+export declare function isSafeImageUrl(url: string): boolean;
+/**
+ * Check if a URL is safe for use in href/src attributes.
+ * Allows http:, https:, and relative paths (starting with `/`).
+ */
+export declare function isSafeUrl(url: string): boolean;
+/**
+ * Safely set an attribute on an element.
+ * For `href` and `src` attributes, validates the URL against safe protocols.
+ */
+export declare function safeSetAttribute(el: HTMLElement, attr: string, value: string): void;
+export declare function sanitizeHtml(raw: string): string;

package/dist/common/sdk-version.d.ts

@@ -0,0 +1,3 @@
+export declare const GENGAGE_VERSION: string;
+export declare const GENGAGE_BUILD_FLAVOR: string;
+export declare function logSdkRuntimeInfoOnce(): void;

package/dist/common/streaming.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Wire protocol streaming utilities.
+ *
+ * The Gengage backend streams responses as Newline-Delimited JSON (NDJSON)
+ * over a single HTTP response. This module provides utilities to consume
+ * that stream and parse events in real time.
+ *
+ * Protocol shape:
+ *   {"type":"metadata","sessionId":"...","model":"..."}
+ *   {"type":"text_chunk","content":"Hello "}
+ *   {"type":"text_chunk","content":"there!","final":true}
+ *   {"type":"ui_spec","widget":"chat","spec":{...}}
+ *   {"type":"action","action":{"kind":"navigate","url":"..."}}
+ *   {"type":"done"}
+ */
+import type { StreamEvent } from './types.js';
+export type StreamEventHandler = (event: StreamEvent) => void;
+export interface StreamOptions {
+    /** Called for each parsed StreamEvent. */
+    onEvent: StreamEventHandler;
+    /** Called once when the stream closes normally. */
+    onDone?: () => void;
+    /** Called if the stream errors or the response is non-2xx. */
+    onError?: (err: Error) => void;
+    /** AbortController signal to cancel mid-stream. */
+    signal?: AbortSignal;
+    /**
+     * Max milliseconds to wait between chunks before treating the stream as dead.
+     * Prevents the UI from hanging indefinitely when the backend stops sending
+     * data without closing the connection. Default: 60_000 (60 s).
+     */
+    idleTimeoutMs?: number;
+}
+/**
+ * Consume an NDJSON streaming response and call onEvent for each line.
+ *
+ * Usage:
+ *   const controller = new AbortController();
+ *   await consumeStream(response, {
+ *     onEvent: (event) => { ... },
+ *     signal: controller.signal,
+ *   });
+ */
+export declare function consumeStream(response: Response, options: StreamOptions): Promise<void>;
+/**
+ * Convenience: POST to a streaming endpoint and consume the response.
+ *
+ * @returns an AbortController that cancels the stream when aborted.
+ */
+export declare function streamPost(url: string, body: unknown, options: StreamOptions & {
+    headers?: Record<string, string>;
+}): AbortController;