@iccandle/vuejs-widget 0.1.5 → 0.2.1

package/README.md

@@ -1,8 +1,8 @@
 # @iccandle/vuejs-widget
 
-Vue 3 component that wraps an existing [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/) widget and adds ICCandle’s **scanner UI**: a draggable popup to run pattern search over a user-selected bar range, with theming loaded from ICCandle’s API.
+Vue 3 scanner overlay for an existing [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/) widget. It adds ICCandle’s draggable scanner popup, pattern search, replay of predicted candles, and a results embed.
 
-Published as ESM and CommonJS; component styles are bundled and injected at runtime (no separate CSS import).
+Published as ESM and CommonJS. Component styles are bundled and injected at runtime — no separate CSS import.
 
 ## Install
 
@@ -12,73 +12,90 @@ npm install @iccandle/vuejs-widget
 pnpm add @iccandle/vuejs-widget
 ```
 
-### How to get an API key
+`vue` `^3.5.0` is a **peer dependency**. Install it in your app. `axios` is a runtime dependency of this package.
 
-1. Register or sign in at the [ICCandle corporate portal](https://corporate-iccandle.vercel.app/).
-2. Use **Create API key** in the dashboard.
-3. When selecting a service, choose **search** so the key is valid for this widget (remote theming, candle cache, and scanner validation).
+## Prerequisites
 
-Issued keys use the format `icc_search_` followed by 48 hexadecimal characters.
-
-### Prerequisites
-
-- **Vue 3.5+** — `vue` is a **peer dependency** (install it in your app).
-- **TradingView Charting Library** — obtain it under your own license from TradingView, host the static assets (e.g. under `/charting_library/` in your public folder), and load the library at runtime. **This package does not ship the charting library.**
-- **ICCandle API key** — required for theme, candle cache, and scanner validation; format `icc_search_` plus 48 hex characters. See [How to get an API key](#how-to-get-an-api-key) above.
+- **Vue 3.5+**
+- **TradingView Charting Library** — obtain it under your own license, host the static assets (for example `/charting_library/`), and load it at runtime via `library_path`. **This package does not ship the charting library.**
+- A **results iframe** (or equivalent) that loads ICCandle’s embed app. Scan/tracker actions require the user to sign in inside that embed; the widget stores the session as `iccandle_token` in `localStorage`.
 
 ## Quick start
 
 ```vue
 <script setup lang="ts">
-import { shallowRef } from "vue";
+import { ref, shallowRef, watch } from "vue";
 import type { IChartingLibraryWidget } from "charting_library/charting_library";
-import { WidgetIccandle } from "@iccandle/vuejs-widget";
+import {
+  WidgetIccandle,
+  WIDGET_RESULT_URL,
+  handleResultIframeLoad,
+} from "@iccandle/vuejs-widget";
 
 const chartWidget = shallowRef<IChartingLibraryWidget | null>(null);
-const widgetKey = "icc_search_..."; // ICCandle-issued key (48 hex chars after prefix)
-const iframeSrc = shallowRef("");
+const language = "en" as const;
+const theme = "dark" as const;
+
+const iframeSrc = ref(`${WIDGET_RESULT_URL}/${language}?theme=${theme}&header=true`);
+const iframeLoaded = ref(false);
+const resultIframeRef = ref<HTMLIFrameElement | null>(null);
+const resultIframeBox = { current: null as HTMLIFrameElement | null };
+
+watch(
+  resultIframeRef,
+  (el) => {
+    resultIframeBox.current = el;
+  },
+  { immediate: true },
+);
 
 function handleSubmit(src: string) {
   iframeSrc.value = src;
 }
+
+function handleIframeLoad() {
+  iframeLoaded.value = true;
+  handleResultIframeLoad(resultIframeRef.value);
+}
 </script>
 
 <template>
-  <WidgetIccandle
-    :chart-widget="chartWidget"
-    :widget-key="widgetKey"
-    theme="system"
-    user-id="your-user-id"
-    email="you@example.com"
-    :submit-callback="handleSubmit"
-  >
-    <template #default="{ chartRefs }">
-      <!-- Your chart container + TradingView bootstrap; set chartWidget when ready -->
-      <div id="tv_chart_container" style="height: 100%" />
-    </template>
-  </WidgetIccandle>
-  <iframe v-if="iframeSrc" :src="iframeSrc" title="ICCandle results" />
+  <div class="iccandle-selector-widget__container">
+    <div class="iccandle-selector-widget__chart-pane">
+      <WidgetIccandle
+        :chart-widget="chartWidget"
+        :submit-callback="handleSubmit"
+        :theme="theme"
+        :language="language"
+        :iframe-loaded="iframeLoaded"
+        :result-iframe-ref="resultIframeBox"
+      >
+        <!-- Bootstrap TradingView here and assign chartWidget when ready -->
+        <div id="tv_chart_container" style="height: 100%" />
+      </WidgetIccandle>
+    </div>
+    <iframe
+      ref="resultIframeRef"
+      :src="iframeSrc"
+      class="iccandle-selector-widget__iframe"
+      title="ICCandle results"
+      @load="handleIframeLoad"
+    />
+  </div>
 </template>
 ```
 
-Replace the chart placeholder with your TradingView initialization and pass the `IChartingLibraryWidget` instance when `onChartReady` (or equivalent) fires.
-
-## Usage guide
+Replace the chart placeholder with your TradingView initialization and pass the `IChartingLibraryWidget` instance when the widget is created (typically right after `new widget(options)`).
 
-### Step 1 — Install the package
+## Usage
 
-```bash
-npm install @iccandle/vuejs-widget
-```
+### 1. Host the Charting Library
 
-Ensure `vue` is installed and meets the peer version range.
+Copy the TradingView Charting Library build into a path your app can serve as static files (for example `public/charting_library/` in Vite). Point `library_path` at that URL. The library is **not** bundled inside `@iccandle/vuejs-widget`.
 
-### Step 2 — Host the Charting Library
+### 2. Bootstrap TradingView with replay support
 
-1. Copy the TradingView Charting Library build into a path your app can serve as static files (e.g. `public/charting_library/` in Vite).
-2. Import the library constructor from that path in your bundler setup (see TradingView’s integration docs for your framework). The library is **not** bundled inside `@iccandle/vuejs-widget`; it loads at runtime via `library_path` (or equivalent) on the widget options.
-
-### Step 3 — Bootstrap TradingView and capture the widget instance
+Wrap your datafeed with `withPlayChart` so the widget can inject predicted bars during replay. Register `getCustomIndicators` so those bars render as generated-candle studies:
 
 ```ts
 import { onMounted, onBeforeUnmount, ref, shallowRef } from "vue";
@@ -88,8 +105,9 @@ import type {
   ResolutionString,
 } from "charting_library/charting_library";
 import { widget } from "charting_library/charting_library";
+import { withPlayChart, getCustomIndicators } from "@iccandle/vuejs-widget";
 
-const LIBRARY_PATH = "/charting_library/"; // must match your hosted assets
+const LIBRARY_PATH = "/charting_library/";
 
 const containerRef = ref<HTMLDivElement | null>(null);
 const chartWidget = shallowRef<IChartingLibraryWidget | null>(null);
@@ -103,9 +121,14 @@ onMounted(() => {
     library_path: LIBRARY_PATH,
     symbol: "EURUSD",
     interval: "60" as ResolutionString,
-    datafeed: yourDatafeed,
+    datafeed: withPlayChart(yourDatafeed),
     locale: "en",
     autosize: true,
+    drawings_access: {
+      type: "black",
+      tools: [{ name: "Date Range" }],
+    },
+    custom_indicators_getter: () => getCustomIndicators("dark"),
   };
 
   const tv = new widget(options);
@@ -122,111 +145,193 @@ onMounted(() => {
 });
 ```
 
-You must supply a valid `datafeed`, `symbol`, `interval`, `locale`, and any other options required by your TradingView license and app.
+`withPlayChart` also accepts a factory plus its arguments: `withPlayChart(createDatafeed, arg1, arg2)`.
+
+You must supply a valid `datafeed`, `symbol`, `interval`, `locale`, and any other options required by your TradingView license.
 
-### Step 4 — Wrap the chart with `WidgetIccandle`
+### 3. Wrap the chart with `WidgetIccandle`
 
-`WidgetIccandle` must wrap the same subtree that contains the chart container so the scanner overlay positions correctly. Pass the live widget instance (or `null` while mounting):
+The component must wrap the same subtree that contains the chart container so the scanner overlay positions correctly. Pass `null` for `chartWidget` until the instance is ready.
 
 ```vue
 <WidgetIccandle
   :chart-widget="chartWidget"
-  :widget-key="widgetKey"
-  theme="system"
-  user-id="your-user-id"
-  email="you@example.com"
-  :submit-callback="(iframeSrc) => { /* see Step 5 */ }"
+  :submit-callback="handleSubmit"
+  theme="dark"
+  language="en"
+  :iframe-loaded="iframeLoaded"
+  :result-iframe-ref="resultIframeBox"
+  :available-intervals="['1', '5', '15', '30', '60']"
 >
   <div ref="containerRef" style="height: 100%; min-height: 400px" />
 </WidgetIccandle>
 ```
 
-### Step 5 — Handle the plugin iframe URL
+### 4. Handle the results iframe URL
 
-After a successful scan setup, `submitCallback` receives a **full HTTPS URL** for the ICCandle plugin iframe. The query string typically includes the bar window (timestamps / size), symbol, `candle_id`, `apiKey` (your widget key), resolved theme, and any active filters—use it as-is in an iframe `src` or deep link.
+After a successful scan, `submitCallback` receives a full HTTPS URL for the ICCandle embed. Typical query parameters include symbol, reference resolution, scan resolution, candle cache id (`cid`), time window (`from` / `to`), theme, and optional filters (`fs`, `period`, `model`, `temp`).
+
+**Split pane (recommended)** — keep an iframe beside the chart and update its `src`:
+
+```ts
+const submitCallback = (nextSrc: string) => {
+  iframeSrc.value = nextSrc;
+};
+```
 
 **Open in a new tab**
 
 ```ts
 submitCallback: (iframeSrc) => {
   window.open(iframeSrc, "_blank", "noopener,noreferrer");
-}
+};
 ```
 
-**Show in a modal or side panel**
+On iframe `load`, call `handleResultIframeLoad(iframe)` so the embed knows the parent origin (required for sign-in to write `iccandle_token`) and so a Stripe return of `?payment=success` can refresh the subscription without a full reload.
 
-Store the URL in state and render:
+`result-iframe-ref` is a mutable `{ current }` box, not a Vue `ref`. Sync it from the iframe element:
 
-```vue
-<iframe v-if="iframeSrc" title="ICCandle pattern search" :src="iframeSrc" />
+```ts
+const resultIframeRef = ref<HTMLIFrameElement | null>(null);
+const resultIframeBox = { current: null as HTMLIFrameElement | null };
+
+watch(resultIframeRef, (el) => {
+  resultIframeBox.current = el;
+}, { immediate: true });
 ```
 
-### Theme and remote branding
+### Sign-in
 
-- **`theme="light"` / `"dark"`** — forces that palette for the scanner chrome and for values forwarded into the plugin URL.
-- **`theme="system"`** — follows `prefers-color-scheme` for light/dark resolution.
-- On mount, the widget fetches your org’s tokens from ICCandle and sets CSS custom properties on the widget root, e.g. `--iccandle-primary`, `--iccandle-border`.
+Scan and Pattern Tracker require `localStorage.iccandle_token`. The results iframe posts `auth.signIn` / `auth.signOut`; the widget listens and stores or clears the token. Until the user signs in, those actions show a login prompt.
 
-### Full working example
+### Theme
 
-See [`src/App.vue`](src/App.vue) and [`src/tradingview/TradingviewChart.vue`](src/tradingview/TradingviewChart.vue) in this repository’s dev app for a concrete in-repo reference (custom datafeed, timezone, visibility handling).
+| `theme` | Behavior |
+| ------- | -------- |
+| `"light"` (default) | Light scanner chrome and embed theme. |
+| `"dark"` | Dark scanner chrome; adds `.iccandle-dark` on the root. |
+| `"system"` | Follows `prefers-color-scheme`. |
 
-## API
+The root uses CSS custom properties you can override: `--iccandle-primary`, `--iccandle-border`, `--iccandle-text`, `--iccandle-background`, `--iccandle-primary-gradient-end`, `--iccandle-font`.
 
-### Exports
+### Chart mask colors
 
-| Name | Kind | Description |
-| ---- | ---- | ----------- |
-| `WidgetIccandle` | Component | Scanner overlay around your chart subtree |
-| `SelectorWidget` | Component | Deprecated alias of `WidgetIccandle` |
-| `WidgetIccandleChartRefs` | Type | Chart study refs for generated candles |
-| `withPlayChart` | Function | Wrap a datafeed for replay / predicted candles |
-| `getCustomIndicators` | Function | TradingView custom indicators for generated candles |
-| `getGeneratedCandlesMaskColor` | Function | Theme-aware mask color for predicted bars |
+During replay the widget draws all predicted candles at once and hides the ones that have not been revealed yet by painting them in a solid "mask" color. The illusion only works if that color is identical to the chart pane background, otherwise the hidden bars show up as visible blocks ahead of the replay cursor.
 
-### `WidgetIccandle` props
+Defaults are `#ffffff` for `light` and `#0F0F0F` for `dark`. If your TradingView `paneProperties.background` differs, pass `chartMaskColors` with the matching value:
+
+```vue
+<WidgetIccandle
+  :chart-widget="chartWidget"
+  :submit-callback="handleSubmit"
+  theme="dark"
+  :chart-mask-colors="{ dark: '#2F2F2F', light: '#ffffff' }"
+>
+  <div ref="containerRef" style="height: 100%" />
+</WidgetIccandle>
+```
+
+Only the entry for the active theme is used, and each key is optional — omit one to keep its default. Any CSS color string the charting library accepts works, but avoid transparency: a translucent mask lets the real series bleed through. Changing the prop recreates the generated-candle studies, so it can be updated reactively when the host switches themes.
+
+### Language
 
-| Prop | Type | Required | Description |
-| ---- | ---- | -------- | ----------- |
-| `chartWidget` | `IChartingLibraryWidget \| null` | Yes | Live TradingView widget instance (`null` until ready). |
-| `widgetKey` | `string` | Yes | ICCandle API key (`icc_search_` + 48 hex chars). |
-| `submitCallback` | `(iframeSrc: string) => void` | Yes | Called after a successful scan setup with the plugin iframe URL. |
-| `userId` | `string` | Yes | User id forwarded to the results plugin. |
-| `email` | `string` | Yes | User email (pattern tracker). |
-| `widgetKeyPatternTracker` | `string` | No | Optional tracker API key (`icc_tracker_…`). |
-| `theme` | `"light" \| "dark" \| "system"` | No | Defaults to `"light"`. `"system"` follows `prefers-color-scheme`. |
-| `language` | `WidgetLanguage` | No | Scanner UI language (`en`, `zh`, `vi`, …). |
-| `onCloseResult` | `() => void` | No | Called when the results iframe posts `close-result`. |
-| `iframeLoaded` | `boolean` | No | Disables scanner actions while results iframe is loading. |
+`language` accepts `"en"` | `"zh"` | `"vi"` | `"th"` | `"ko"` | `"ja"` | `"mn"` | `"ru"`. Unknown values fall back to `"en"`. The value is used for scanner copy and is forwarded into embed URLs.
 
-Default slot receives `{ chartRefs }` for wiring custom indicators / generated-candle studies.
+### Layout helpers
 
-### Widget key and remote theming
+Injected CSS includes split-pane classes used in the demo:
 
-On mount, the component loads branding colors from ICCandle:
+| Class | Role |
+| ----- | ---- |
+| `.iccandle-selector-widget__container` | Flex row (stacks below 1024px). `--chart-pane-size` defaults to `60%`. |
+| `.iccandle-selector-widget__chart-pane` | Chart column. |
+| `.iccandle-selector-widget__resize-handle` | Drag handle; add `--stacked` for the stacked layout. |
+| `.iccandle-selector-widget__iframe` | Results pane. |
+
+### Full working example
 
-- **URL:** `https://api.iccandle.ai/corporate-client/v1/widgetStyle/search/user/?service_type=search`
-- **Header:** `api-key: <widgetKey>`
+See [`src/App.vue`](src/App.vue), [`src/tradingview/TradingviewChart.vue`](src/tradingview/TradingviewChart.vue), and [`src/tradingview/TradingviewChartContainer.vue`](src/tradingview/TradingviewChartContainer.vue) in this repository.
 
-CSS custom properties (`--iccandle-primary`, `--iccandle-border`, etc.) are applied on the widget root so the scanner matches your configured light/dark tokens.
+## API
 
-### Behavior summary
+### Exports
 
-- Subscribes to chart readiness, resolution, symbol changes, and drawing events.
-- Manages a `date_range` multipoint drawing so the user can adjust the bar window; window size and exported candles drive the scanner.
-- Posts candles to ICCandle’s cache endpoint before opening the plugin URL.
-- Listens for `window` `message` events for chart/news/pattern integration (replay, event marks, pattern selection) and can clear persisted news mark selections (`localStorage` keys `tv:selected-news-events`, `tv:clicked-news-event`) when starting a scan.
+| Name | Kind | Description |
+| ---- | ---- | ----------- |
+| `WidgetIccandle` | Component | Scanner overlay around your chart subtree. |
+| `WidgetIccandleProps` | Type | Public props of `WidgetIccandle`. |
+| `WidgetChartMaskColors` | Type | `{ light?: string; dark?: string }` for the `chartMaskColors` prop. |
+| `WidgetLanguage` | Type | Supported UI languages. |
+| `withPlayChart` | Function | Wrap a TradingView datafeed (or factory) so replay can inject bars and block live ticks. |
+| `getCustomIndicators` | Function | Returns custom studies used to draw generated / predicted candles. Pass `"light"` or `"dark"`. |
+| `GeneratedCandlesTheme` | Type | `"light"` \| `"dark"` for `getCustomIndicators`. |
+| `handleResultIframeLoad` | Function | Post parent origin (and optional payment-success) to the results iframe. |
+| `WIDGET_RESULT_URL` | Constant | Default embed origin: `https://embed-iccandle-app.iccandle.ai`. |
+| `OPEN_PRICING_MESSAGE_TYPE` | Constant | `"open-pricing"` postMessage type. |
+| `postOpenPricingToEmbed` | Function | Ask the results iframe to open pricing. Returns `false` if no `contentWindow`. |
+| `postOpenPricingToParent` | Function | Forward pricing to `window.parent` when this widget is itself embedded. |
+| `postOpenPricingToWindow` | Function | Post an `open-pricing` message to an arbitrary `Window`. |
+| `OpenPricingMessage` | Type | `{ type, theme?, language? }`. |
 
-## Optional: timescale marks (news/events)
+### `WidgetIccandle` props
 
-If your data feed implements `getTimescaleMarks`, you can surface stored events (e.g. from `localStorage` under `tv:selected-news-events`) as marks on the time axis. See the React sibling docs or `src/lib/data-feed.ts` in this repo for a working example.
+| Prop | Type | Required | Default | Description |
+| ---- | ---- | -------- | ------- | ----------- |
+| `chartWidget` | `IChartingLibraryWidget \| null` | Yes | — | Live TradingView widget (`null` until ready). |
+| `submitCallback` | `(iframeSrc: string) => void` | Yes | — | Called with the embed URL after a scan (and for some pricing / news navigations). |
+| `theme` | `"light" \| "dark" \| "system"` | No | `"light"` | Scanner and forwarded embed theme. |
+| `chartMaskColors` | `WidgetChartMaskColors` | No | `{ light: "#ffffff", dark: "#0F0F0F" }` | Per-theme color used to mask not-yet-revealed predicted candles. Must match your chart pane background. |
+| `language` | `WidgetLanguage` | No | `"en"` | Scanner UI language. |
+| `onCloseResult` | `() => void` | No | — | Called when the embed posts `selector.closeResult`. |
+| `iframeLoaded` | `boolean` | No | `true` | When `false`, Scan and Pattern Tracker are disabled. Set `true` after the results iframe has loaded. |
+| `resultIframeRef` | `{ current: HTMLIFrameElement \| null } \| null` | No | — | Results iframe box. Receives `open-pricing` and chart-resolution postMessages. |
+| `isShowScanButton` | `boolean` | No | `true` | Show Scan inside the popup. |
+| `isShowTrackerButton` | `boolean` | No | `true` | Show Pattern Tracker inside the popup. |
+| `isShowScannerPopup` | `boolean` | No | `true` | Show the scanner popup. |
+| `availableIntervals` | `string[]` | No | — | Resolutions allowed when drawing a pattern date range from embed selection. |
+| `onScanClick` | `() => void` | No | — | Fired when the user clicks Scan, before login / config / scan logic. |
+
+Default slot receives `{ chartRefs }` (`highlightBarsRef`, generated-candle study ids). The same object is exposed on the component instance as `chartRefs`.
+
+### Behavior
+
+- Subscribes to chart readiness, resolution, symbol, visible range, drawings, and timescale-mark clicks.
+- Draws a `date_range` shape for the scan window; bar count and exported candles drive the scanner.
+- Posts selected candles to ICCandle’s cache, then calls `submitCallback` with the embed URL.
+- Listens for `window` `message` events from the embed (replay, auth, news, pattern selection, navigation, loading).
+- Clears persisted news mark keys (`tv:selected-news-events`, `tv:clicked-news-event`) when a scan starts.
+
+### Embed `postMessage` names
+
+The widget handles JSON messages with a `name` (and optional `data`) from the results iframe:
+
+| Name | Effect |
+| ---- | ------ |
+| `chart.play` | Replay / predicted candles on the chart. |
+| `chart.stop` | Stop replay and restore live ticks. |
+| `chart.requestResolution` | Re-post the current chart resolution to the iframe. |
+| `selector.closeResult` | Invoke `onCloseResult`. |
+| `selector.loading` | Toggle scanner loading state. |
+| `auth.signIn` | Store `data.idToken` as `iccandle_token`. |
+| `auth.signOut` | Remove `iccandle_token`. |
+| `news.eventClicked` | Draw event marks / target window on the chart. |
+| `news.back` / `news.backToSimilarEvents` | Clear event overlay / replay. |
+| `pattern.classicPatternSelected` / `pattern.custom_pattern_selected` | Draw the compared pattern’s date range. |
+| `pattern.clearClassicPatternSelected` / `pattern.clear_custom_pattern_selected` | Clear pattern overlay. |
+| `nav.click` | Handle embed navigation (clears date range on `/news` routes). |
+
+The host → embed helpers use a different shape: `{ type: "parent-origin" | "payment-success" | "open-pricing" | "chart-resolution", ... }`.
+
+## Optional: timescale marks (news / events)
+
+If your datafeed implements `getTimescaleMarks`, you can surface stored events from `localStorage` (`tv:selected-news-events`, `tv:clicked-news-event`) as marks on the time axis. See [`src/lib/data-feed.ts`](src/lib/data-feed.ts) in this repo.
 
 ## Development (this repo)
 
 | Script | Command | Purpose |
 | ------ | ------- | ------- |
-| Dev demo | `pnpm dev` | Vite app with local charting library. |
-| Library build | `pnpm build` | Emits `dist/` (JS, CJS, bundled CSS injection, declarations). |
+| Dev demo | `pnpm dev` | Vite app with a local charting library. |
+| Library build | `pnpm build` | Emits `dist/` (ESM, CJS, injected CSS, declarations). |
 | App build | `pnpm build:app` | Full demo app build. |
 
 `prepublishOnly` runs `build` before publish.

package/dist/index.d.ts

@@ -24,6 +24,8 @@ declare type __VLS_Props = {
     chartWidget: IChartingLibraryWidget | null;
     submitCallback: (iframeSrc: string) => void;
     theme?: "light" | "dark" | "system";
+    /** Simulate-candle mask colors per theme. Defaults: light `#ffffff`, dark `#0F0F0F`. */
+    chartMaskColors?: WidgetChartMaskColors;
     language?: WidgetLanguage;
     onCloseResult?: () => void;
     iframeLoaded?: boolean;
@@ -39,6 +41,8 @@ declare type __VLS_Props = {
     isShowScannerPopup?: boolean;
     /** Chart resolutions allowed for pattern date-range drawing. */
     availableIntervals?: string[];
+    /** Called when the user clicks Scan in the scanner popup. */
+    onScanClick?: () => void;
 };
 
 declare function __VLS_template(): {
@@ -62,6 +66,9 @@ declare type __VLS_WithTemplateSlots<T, S> = T & {
     };
 };
 
+/** Same origin + path → soft update via postMessage (no iframe remount). */
+export declare function canSoftSelectorNavigate(iframe: HTMLIFrameElement | null | undefined, nextSrc: string): boolean;
+
 export declare type GeneratedCandlesTheme = "light" | "dark";
 
 export declare const getCustomIndicators: (theme?: GeneratedCandlesTheme) => Promise<readonly CustomIndicator[]>;
@@ -82,10 +89,33 @@ export declare function postOpenPricingToParent(options?: Pick<OpenPricingMessag
 
 export declare function postOpenPricingToWindow(target: Window, options?: Pick<OpenPricingMessage, "theme" | "language">): void;
 
+export declare function postSelectorLoadingToEmbed(iframe: HTMLIFrameElement | null | undefined, isLoading: boolean): boolean;
+
+export declare function postSelectorScanToEmbed(iframe: HTMLIFrameElement | null | undefined, url: string): boolean;
+
+export declare const SELECTOR_LOADING_MESSAGE_TYPE = "selector-loading";
+
+export declare const SELECTOR_SCAN_MESSAGE_TYPE = "selector-scan";
+
+export declare type SelectorLoadingMessage = {
+    type: typeof SELECTOR_LOADING_MESSAGE_TYPE;
+    isLoading: boolean;
+};
+
+export declare type SelectorScanMessage = {
+    type: typeof SELECTOR_SCAN_MESSAGE_TYPE;
+    url: string;
+};
+
 declare const WIDGET_LANGUAGES: readonly ["en", "zh", "vi", "th", "ko", "ja", "mn", "ru"];
 
 export declare const WIDGET_RESULT_URL = "https://embed-iccandle-app.iccandle.ai";
 
+export declare type WidgetChartMaskColors = {
+    light?: string;
+    dark?: string;
+};
+
 export declare const WidgetIccandle: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
 declare type WidgetIccandleChartRefs = {
@@ -105,6 +135,8 @@ export declare type WidgetIccandleProps = {
     chartWidget: IChartingLibraryWidget | null;
     submitCallback: (iframeSrc: string) => void;
     theme?: "light" | "dark" | "system";
+    /** Simulate-candle mask colors per theme. Defaults: light `#ffffff`, dark `#0F0F0F`. */
+    chartMaskColors?: WidgetChartMaskColors;
     language?: WidgetLanguage;
     onCloseResult?: () => void;
     iframeLoaded?: boolean;
@@ -120,6 +152,8 @@ export declare type WidgetIccandleProps = {
     isShowScannerPopup?: boolean;
     /** Chart resolutions allowed for pattern date-range drawing. */
     availableIntervals?: string[];
+    /** Called when the user clicks Scan in the scanner popup. */
+    onScanClick?: () => void;
 };
 
 export declare type WidgetLanguage = (typeof WIDGET_LANGUAGES)[number];