@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/iframe/messageProtocol.d.ts

@@ -0,0 +1,545 @@
+/**
+ * WP-11: Iframe PostMessage Protocol Types
+ *
+ * Defines the typed message protocol for Host ↔ Iframe communication.
+ * Custom Data Adapters (callbacks) CANNOT be serialized over postMessage.
+ * Iframe mode only supports built-in adapters via JSON-serializable config.
+ */
+/** Base message envelope with correlation ID for request/response matching */
+export interface BaseMessage {
+    /** Unique message type identifier */
+    type: string;
+    /** Correlation ID for matching requests to responses */
+    correlationId: string;
+    /** Timestamp when message was sent */
+    timestamp: number;
+    /** Origin of the message (for security validation) */
+    origin: string;
+}
+/** Request message expecting a response */
+export interface RequestMessage<T = unknown> extends BaseMessage {
+    type: `request:${string}`;
+    payload: T;
+}
+/** Response message to a request */
+export interface ResponseMessage<T = unknown> extends BaseMessage {
+    type: `response:${string}`;
+    correlationId: string;
+    payload: T;
+    success: boolean;
+    error?: string;
+}
+/** Event notification (fire-and-forget, no response expected) */
+export interface EventMessage<T = unknown> extends BaseMessage {
+    type: `event:${string}`;
+    payload: T;
+}
+/** Built-in adapter types supported in Iframe mode */
+export type BuiltInAdapterType = "vninvest" | "tvfeed" | "yahoo" | "binance" | "coinbase" | "twelvedata" | "alphavantage" | "finnhub" | "polygon";
+/** Adapter configuration - MUST be JSON-serializable (no functions) */
+export interface AdapterConfig {
+    /** Built-in adapter type identifier */
+    type: BuiltInAdapterType;
+    /** Adapter-specific configuration options */
+    options?: Record<string, string | number | boolean | null>;
+    /** Authentication token (if required) */
+    token?: string;
+}
+/** Widget configuration for Iframe initialization */
+export interface WidgetConfig {
+    /** Symbol to display (e.g., "VNM", "AAPL") */
+    symbol: string;
+    /** Timeframe (e.g., "1D", "1H", "5m") */
+    timeframe: string;
+    /** Chart theme */
+    theme?: string;
+    /** Adapter configuration (built-in only, no custom callbacks) */
+    adapter?: AdapterConfig;
+    /** Initial visible range (e.g., "6M", "1Y", "ALL") */
+    range?: string;
+    /** Locale */
+    locale?: string;
+    /** Enable drawing tools UI */
+    drawingUiEnabled?: boolean;
+    /** Initial drawing tool */
+    drawingActiveTool?: string;
+    /** Pre-loaded drawings */
+    drawings?: readonly any[];
+    /** Drawing storage key for persistence */
+    drawingStorageKey?: string;
+    /** Show header with symbol search, fullscreen, etc. */
+    showHeader?: boolean;
+    /** Show footer with timeframe selector */
+    showFooter?: boolean;
+    /** Show drawing toolbar */
+    showToolbar?: boolean;
+    /** Measurement tool enabled */
+    measurementEnabled?: boolean;
+    /** Non-trading days visibility */
+    showNonTradingDays?: boolean;
+    /** Timezone */
+    timezone?: string;
+    /**
+     * E1: frame height. `"fill"` (default) = iframe fills the host container
+     * 100%/100% (host owns the frame — TradingView standard, zero resize
+     * messages). A number sets a fixed card height in px and enables the
+     * guarded `event:resized` reporter for bottom-panel expansion.
+     */
+    height?: number | "fill";
+    /** Custom panes configuration */
+    panes?: readonly any[];
+    /** Tenant PAT for SaaS features */
+    tenantPat?: string;
+    /** CS-3: host-pinned offline license key (`vni1.*`) */
+    licenseKey?: string;
+    /** Debug features override */
+    debugFeatures?: Record<string, boolean>;
+    /**
+     * E3: right dock in iframe. `show` maps to the widget `showDock` gate;
+     * `defaultTab` seeds the persisted dock tab; `watchlist` builds a static
+     * in-iframe adapter (JSON-only — custom adapters cannot cross postMessage).
+     */
+    dock?: {
+        show?: boolean;
+        defaultTab?: string;
+        watchlist?: string[];
+    };
+}
+/** Initialize widget with configuration */
+export interface InitializeCommand {
+    type: "request:initialize";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: WidgetConfig;
+}
+/** Update widget symbol */
+export interface SetSymbolCommand {
+    type: "request:setSymbol";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        symbol: string;
+    };
+}
+/** Update timeframe */
+export interface SetTimeframeCommand {
+    type: "request:setTimeframe";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        timeframe: string;
+    };
+}
+/** Update visible range */
+export interface SetRangeCommand {
+    type: "request:setRange";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        range: string;
+    };
+}
+/** Update theme */
+export interface SetThemeCommand {
+    type: "request:setTheme";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        theme: "light" | "dark";
+    };
+}
+/** Update drawings (full replacement) */
+export interface SetDrawingsCommand {
+    type: "request:setDrawings";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        drawings: readonly any[];
+    };
+}
+/** Add a single drawing */
+export interface AddDrawingCommand {
+    type: "request:addDrawing";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        drawing: any;
+    };
+}
+/** Remove a drawing by ID */
+export interface RemoveDrawingCommand {
+    type: "request:removeDrawing";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        drawingId: string;
+    };
+}
+/** Update drawing properties */
+export interface UpdateDrawingCommand {
+    type: "request:updateDrawing";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        drawingId: string;
+        updates: Partial<any>;
+    };
+}
+/** Set active drawing tool */
+export interface SetActiveToolCommand {
+    type: "request:setActiveTool";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        tool: string;
+    };
+}
+/** E3: switch the right-dock tab (no-op when the dock is closed or missing the tab) */
+export interface SetDockTabCommand {
+    type: "request:setDockTab";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        tab: string;
+    };
+}
+/** E3: replace the dock watchlist (static symbols; streaming arrives in E5) */
+export interface SetWatchlistCommand {
+    type: "request:setWatchlist";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        symbols: string[];
+    };
+}
+/** E5: host subscribes to live quotes fan-out */
+export interface SubscribeQuotesCommand {
+    type: "request:subscribeQuotes";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        symbols: string[];
+    };
+}
+/** E5: host unsubscribes (omitted symbols = all) */
+export interface UnsubscribeQuotesCommand {
+    type: "request:unsubscribeQuotes";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        symbols?: string[];
+    };
+}
+/** Export current drawings */
+export interface ExportDrawingsCommand {
+    type: "request:exportDrawings";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: Record<string, never>;
+}
+/** Get current visible range */
+export interface GetVisibleRangeCommand {
+    type: "request:getVisibleRange";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: Record<string, never>;
+}
+/** Get current pane snapshots */
+export interface GetPaneSnapshotsCommand {
+    type: "request:getPaneSnapshots";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: Record<string, never>;
+}
+/** Capture snapshot as image */
+export interface CaptureSnapshotCommand {
+    type: "request:captureSnapshot";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        format?: "png" | "jpeg";
+        quality?: number;
+    };
+}
+/** Toggle fullscreen */
+export interface ToggleFullscreenCommand {
+    type: "request:toggleFullscreen";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: Record<string, never>;
+}
+/** Set locale */
+export interface SetLocaleCommand {
+    type: "request:setLocale";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        locale: string;
+    };
+}
+/** Set timezone */
+export interface SetTimezoneCommand {
+    type: "request:setTimezone";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        timezone: string;
+    };
+}
+/** Destroy widget and cleanup */
+export interface DestroyCommand {
+    type: "request:destroy";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: Record<string, never>;
+}
+/** Union of all Host → Iframe commands */
+export type HostToIframeCommand = InitializeCommand | SetSymbolCommand | SetTimeframeCommand | SetRangeCommand | SetThemeCommand | SetDrawingsCommand | AddDrawingCommand | RemoveDrawingCommand | UpdateDrawingCommand | SetActiveToolCommand | SetDockTabCommand | SetWatchlistCommand | SubscribeQuotesCommand | UnsubscribeQuotesCommand | ExportDrawingsCommand | GetVisibleRangeCommand | GetPaneSnapshotsCommand | CaptureSnapshotCommand | ToggleFullscreenCommand | SetLocaleCommand | SetTimezoneCommand | DestroyCommand;
+/** Widget initialized and ready */
+export interface ReadyEvent {
+    type: "event:ready";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        version: string;
+        capabilities: string[];
+    };
+}
+/** Symbol changed */
+export interface SymbolChangedEvent {
+    type: "event:symbolChanged";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        symbol: string;
+        previousSymbol: string | null;
+    };
+}
+/** Timeframe changed */
+export interface TimeframeChangedEvent {
+    type: "event:timeframeChanged";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        timeframe: string;
+        previousTimeframe: string | null;
+    };
+}
+/** Visible range changed (pan/zoom) */
+export interface VisibleRangeChangedEvent {
+    type: "event:visibleRangeChanged";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        startIndex: number;
+        endIndex: number;
+        startDate: string;
+        endDate: string;
+        barCount: number;
+    };
+}
+/** Drawings changed */
+export interface DrawingsChangedEvent {
+    type: "event:drawingsChanged";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        drawings: readonly any[];
+        action: "add" | "remove" | "update" | "replace";
+    };
+}
+/** Drawing tool changed */
+export interface ActiveToolChangedEvent {
+    type: "event:activeToolChanged";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        tool: string;
+        previousTool: string | null;
+    };
+}
+/** Theme changed */
+export interface ThemeChangedEvent {
+    type: "event:themeChanged";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        theme: "light" | "dark";
+    };
+}
+/** Error occurred */
+export interface ErrorEvent {
+    type: "event:error";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        code: string;
+        message: string;
+        recoverable: boolean;
+    };
+}
+/** Snapshot captured */
+export interface SnapshotCapturedEvent {
+    type: "event:snapshotCaptured";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        dataUrl: string;
+        format: string;
+        width: number;
+        height: number;
+    };
+}
+/** Fullscreen toggled */
+export interface FullscreenToggledEvent {
+    type: "event:fullscreenToggled";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        isFullscreen: boolean;
+    };
+}
+/** SaaS feature gate error (premium feature blocked) */
+export interface SaaSErrorEvent {
+    type: "event:saasError";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        feature: string;
+        message: string;
+        requiresUpgrade: boolean;
+    };
+}
+/** Adapter error (data fetch failed) */
+export interface AdapterErrorEvent {
+    type: "event:adapterError";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        code: string;
+        message: string;
+        adapterType: string;
+    };
+}
+/** Frame resized (E1: card mode only — fill mode never emits this) */
+export interface ResizedEvent {
+    type: "event:resized";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        height: number;
+    };
+}
+/** E5: batched live quotes (latest-wins per symbol, ≥250ms cadence) */
+export interface QuotesEvent {
+    type: "event:quotes";
+    correlationId: string;
+    timestamp: number;
+    origin: string;
+    payload: {
+        updates: Array<{
+            symbol: string;
+            price?: number;
+            change?: number;
+            changePercent?: number;
+            sparkline?: number[];
+        }>;
+    };
+}
+/** Union of all Iframe → Host events */
+export type IframeToHostEvent = ReadyEvent | SymbolChangedEvent | TimeframeChangedEvent | VisibleRangeChangedEvent | DrawingsChangedEvent | ActiveToolChangedEvent | ThemeChangedEvent | ErrorEvent | SnapshotCapturedEvent | FullscreenToggledEvent | SaaSErrorEvent | AdapterErrorEvent | ResizedEvent | QuotesEvent;
+/** Initialize response */
+export interface InitializeResponse {
+    success: true;
+    widgetId: string;
+}
+/** Export drawings response */
+export interface ExportDrawingsResponse {
+    success: true;
+    drawings: readonly any[];
+}
+/** Get visible range response */
+export interface GetVisibleRangeResponse {
+    success: true;
+    range: {
+        startIndex: number;
+        endIndex: number;
+        startDate: string;
+        endDate: string;
+        barCount: number;
+    } | null;
+}
+/** Get pane snapshots response */
+export interface GetPaneSnapshotsResponse {
+    success: true;
+    snapshots: readonly any[];
+}
+/** Capture snapshot response */
+export interface CaptureSnapshotResponse {
+    success: true;
+    dataUrl: string;
+}
+/** Generic error response */
+export interface ErrorResponse {
+    success: false;
+    error: string;
+}
+/** Generic success response (for commands that don't return data) */
+export interface SuccessResponse {
+    success: true;
+}
+/** Union of all response payloads */
+export type ResponsePayload = InitializeResponse | ExportDrawingsResponse | GetVisibleRangeResponse | GetPaneSnapshotsResponse | CaptureSnapshotResponse | SuccessResponse | ErrorResponse;
+/** Check if message is a request */
+export declare function isRequestMessage(msg: unknown): msg is RequestMessage;
+/** Check if message is a response */
+export declare function isResponseMessage(msg: unknown): msg is ResponseMessage<ResponsePayload>;
+/** Check if message is an event */
+export declare function isEventMessage(msg: unknown): msg is EventMessage;
+/** Check if message is Host → Iframe command */
+export declare function isHostToIframeCommand(msg: unknown): msg is HostToIframeCommand;
+/** Check if message is Iframe → Host event */
+export declare function isIframeToHostEvent(msg: unknown): msg is IframeToHostEvent;
+/** Generate a unique correlation ID */
+export declare function generateCorrelationId(): string;
+/** Create a request message */
+export declare function createRequest<T>(type: `request:${string}`, payload: T, origin: string): RequestMessage<T>;
+/** Create a response message */
+export declare function createResponse<T>(request: RequestMessage, payload: T, success?: boolean, error?: string): ResponseMessage<T>;
+/** Create an event message */
+export declare function createEvent<T>(type: `event:${string}`, payload: T, origin: string): EventMessage<T>;

package/dist/dts/widget/iframe/quoteHub.d.ts

@@ -0,0 +1,20 @@
+import type { WatchlistAdapter, WatchlistQuoteUpdate } from "../types/watchlist";
+/**
+ * E5: in-iframe quote fan-out hub.
+ *
+ * Host subscribes once per symbol set (`request:subscribeQuotes`); the hub
+ * taps the current watchlist adapter's `subscribeQuotes` (when it supports
+ * streaming) and re-emits latest-wins batches (`event:quotes`, ≥250ms).
+ * Static adapters yield zero updates until a streaming VN adapter lands
+ * (credentials-blocked — see ledger E5).
+ */
+export interface QuoteHub {
+    subscribe(symbols: readonly string[]): void;
+    unsubscribe(symbols?: readonly string[]): void;
+    subscriberCount(): number;
+    dispose(): void;
+}
+export declare function createQuoteHub(source: {
+    getAdapter: () => WatchlistAdapter | null | undefined;
+    emit: (updates: WatchlistQuoteUpdate[]) => void;
+}): QuoteHub;

package/dist/dts/widget/iframe/useVNInvestChartsHost.d.ts

@@ -0,0 +1,8 @@
+import { type HostSDKConfig, type VNInvestChartsHostSDK } from "./hostSDK";
+export interface UseVNInvestChartsHostResult {
+    sdk: VNInvestChartsHostSDK | null;
+    controller: ReturnType<VNInvestChartsHostSDK["getController"]> | null;
+    connecting: boolean;
+    error: Error | null;
+}
+export declare function useVNInvestChartsHost(config: HostSDKConfig): UseVNInvestChartsHostResult;

package/dist/dts/widget/iife-entry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WP-10/11: IIFE entry point for <script> tag embedding.
+ *
+ * This is the standalone bundle that exposes `window.VNInvestCharts`.
+ * It bundles React, ReactDOM, d3, and all widget components.
+ * CSS is auto-injected into <head> or ShadowRoot on mount.
+ *
+ * Usage:
+ *   <script src="vninvestchart.iife.js"></script>
+ *   <script>
+ *     const { mount, VNInvestCharts, VNInvestDataAdapter } = window.VNInvestCharts;
+ *     const { unmount, widgetRef } = mount({ container: div, props: {...} });
+ *   </script>
+ */
+export * from "./index";
+export * from "./adapters";
+import React from "react";
+import { type Root } from "react-dom/client";
+import { type VNInvestMultiChartsProps } from "./VNInvestMultiCharts";
+import { type WidgetInstance } from "./iifeWidgetInstance";
+import { type IChartDataProvider } from "./types/dataProvider";
+/** Options for mounting the widget */
+export interface MountOptions {
+    /** Container element to mount into */
+    container: HTMLElement;
+    /** Widget props */
+    props: VNInvestMultiChartsProps;
+    /** Whether to use Shadow DOM for CSS isolation (default: true) */
+    useShadowDOM?: boolean;
+    /** Optional Bearer token for BFF proxy */
+    authToken?: string;
+    /** Optional custom data provider context */
+    dataProvider?: IChartDataProvider;
+    /** Optional custom portal container override */
+    portalContainer?: HTMLElement;
+}
+export type { WidgetInstance } from "./iifeWidgetInstance";
+/** Return value from mount function */
+export interface MountResult {
+    /** Unmount function - cleans up React root, styles, and listeners */
+    unmount: () => void;
+    /** React Root instance */
+    root: Root;
+    /** Portal root element */
+    portalRoot: HTMLElement;
+    /** Reference to the mounted widget instance (for bridge communication) */
+    widgetRef: React.RefObject<WidgetInstance | null>;
+}
+/**
+ * Mount VNInvestCharts widget into a container with optional Shadow DOM isolation.
+ * Returns unmount function and widget ref for external communication.
+ */
+export declare function mountVNInvestCharts(options: MountOptions): MountResult;
+declare global {
+    interface Window {
+        VNInvestCharts: {
+            mount: typeof mountVNInvestCharts;
+            [key: string]: any;
+        };
+    }
+}

package/dist/dts/widget/iifeWidgetInstance.d.ts

@@ -0,0 +1,60 @@
+import type { VNInvestMultiChartsRef } from "./VNInvestMultiCharts.types";
+import type { WidgetChartHandle } from "./utils/widgetHelpers";
+/**
+ * REL-04: adapter exposing single-chart-style imperative methods for the IIFE
+ * multi-workspace build.
+ *
+ * Why this exists: `iife-entry.ts` mounts `VNInvestMultiCharts`, whose real ref
+ * (`VNInvestMultiChartsRef`) only exposes chart-management/layout/sync methods.
+ * The previous `WidgetInstance` interface advertised `setSymbol`, `exportDrawings`,
+ * … which no ref ever implemented, so every documented call was a no-op or a
+ * TypeError. This adapter maps the documented names onto the real ref.
+ *
+ * Semantics (see RELEASE_DECISION_RECORD_2026-09-25 §D-03):
+ * every single-chart method targets the ACTIVE chart. Symbol/timeframe changes
+ * only propagate to linked charts when the workspace sync flag is enabled —
+ * the adapter passes no `sourceChartId`, so the engine's own sync layer decides.
+ */
+export interface WidgetInstance {
+    cleanupObjectUrls?: () => void;
+    cleanupGlobalListeners?: () => void;
+    /** Active chart targeting (canonical names). */
+    setActiveSymbol: (symbol: string) => void;
+    setActiveTimeframe: (timeframe: string) => void;
+    setActiveVisibleRange: (range: {
+        from: number;
+        to: number;
+    }) => void;
+    getActiveVisibleRange: () => ReturnType<WidgetChartHandle["getVisibleRange"]> | null;
+    getActivePaneSnapshots: () => readonly unknown[];
+    exportActiveDrawings: () => readonly unknown[];
+    importActiveDrawings: (drawings: never[]) => void;
+    saveActiveChartImage: () => void;
+    toggleFullscreen: () => void;
+    setTheme: (mode: "light" | "dark") => void;
+    /** Workspace-level (real `VNInvestMultiChartsRef` methods). */
+    setLayout: VNInvestMultiChartsRef["setLayout"];
+    getLayout: VNInvestMultiChartsRef["getLayout"];
+    setActiveChart: VNInvestMultiChartsRef["setActiveChart"];
+    getActiveChart: VNInvestMultiChartsRef["getActiveChart"];
+    getChartHandle: VNInvestMultiChartsRef["getChartHandle"];
+    getAllChartHandles: VNInvestMultiChartsRef["getAllChartHandles"];
+    /** @deprecated Use the `*Active*` names above. Kept for one release. */
+    setSymbol?: (symbol: string) => void;
+    setTimeframe?: (timeframe: string) => void;
+    setVisibleRange?: (range: {
+        from: number;
+        to: number;
+    }) => void;
+    exportDrawings?: () => readonly unknown[];
+    importDrawings?: (drawings: never[]) => void;
+    getVisibleRange?: () => ReturnType<WidgetChartHandle["getVisibleRange"]> | null;
+    getPaneSnapshots?: () => readonly unknown[];
+    saveAsImage?: () => void;
+}
+/**
+ * Build the IIFE `WidgetInstance` from the live multi ref.
+ * Safe to call with `null` (React ref before mount) — methods become no-ops that
+ * throw nothing, so a host calling too early degrades instead of crashing.
+ */
+export declare function createWidgetInstance(ref: () => VNInvestMultiChartsRef | null): WidgetInstance;