@iccandle/reactjs-widget 0.1.5 → 0.1.6

package/README.md

@@ -1,181 +1,40 @@
 # @iccandle/reactjs-widget
 
-React 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.
+React overlay for the [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/) that adds ICCandle’s **pattern scanner**, **results iframe**, **pattern tracker**, and **news/event** integration.
 
-Published as ESM and CommonJS; component styles are bundled and injected at runtime (no separate CSS import).
+The package ships ESM + CommonJS. Component styles are injected at runtime (no separate CSS import).
 
-## Install
-
-```bash
-npm install @iccandle/reactjs-widget
-```
-
-### How to get an API key
-
-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).
-
-Issued keys use the format `icc_search_` followed by 48 hexadecimal characters.
-
-### Prerequisites
-
-- **React 18+** — `react` and `react-dom` are **peer dependencies** (install them 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.
-
-## Quick start
-
-```tsx
-import { useState } from "react";
-import type { IChartingLibraryWidget } from "charting_library/charting_library";
-import { WidgetIccandle } from "@iccandle/reactjs-widget";
+## What it does
 
-function App() {
-  const [chartWidget, setChartWidget] = useState<IChartingLibraryWidget | null>(
-    null,
-  );
-  const widgetKey = "icc_search_..."; // ICCandle-issued key (48 hex chars after prefix)
+`WidgetIccandle` wraps your chart and renders:
 
-  return (
-    <WidgetIccandle
-      chartWidget={chartWidget}
-      widgetKey={widgetKey}
-      theme="system"
-      submitCallback={(iframeSrc) => {
-        // Full URL for the ICCandle plugin iframe (open in modal, new window, etc.)
-        console.log(iframeSrc);
-      }}
-    >
-      {/* Your chart container + TradingView bootstrap; call setChartWidget when ready */}
-      <div id="tv_chart_container" style={{ height: "100%" }} />
-    </WidgetIccandle>
-  );
-}
-```
+| Surface | Role |
+| -------- | ---- |
+| **Scanner popup** | Draggable overlay over the chart. Select a bar window with TradingView’s Date Range tool, then run a scan or subscribe to pattern alerts. |
+| **Results iframe** | Side-by-side panel hosting the ICCandle embed app (`embed-iccandle-app.iccandle.ai`) — search results, similar events, auth, billing. |
+| **Chart sync** | Bidirectional `postMessage` bridge: pattern selection, chart replay, news marks, sign-in tokens, loading state. |
 
-Replace the chart placeholder with your TradingView initialization and pass the `IChartingLibraryWidget` instance when `onChartReady` (or equivalent) fires.
+Typical flow:
 
-## Usage guide
+1. User draws a **Date Range** on the chart (or activates the scanner).
+2. Scanner caches the selected candles and opens the results iframe with search parameters.
+3. The embed app returns matches; selecting a pattern redraws the range on the chart. Replay / news flows inject predicted candles via custom indicators.
 
-### Step 1 — Install the package
+## Install
 
 ```bash
 npm install @iccandle/reactjs-widget
+# or
+pnpm add @iccandle/reactjs-widget
 ```
 
-Ensure `react` and `react-dom` are installed and meet the peer version range.
-
-### Step 2 — Host the Charting Library
-
-1. Copy the TradingView Charting Library build into a path your app can serve as static files (e.g. `public/charting_library/` in Vite or Create React App).
-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/reactjs-widget`; it loads at runtime via `library_path` (or equivalent) on the widget options.
-
-### Step 3 — Bootstrap TradingView and capture the widget instance
-
-Create a ref for the chart DOM node, instantiate the widget in `useEffect`, store the instance in React state, and remove it on cleanup:
-
-```tsx
-import { useEffect, useRef, useState } from "react";
-import type {
-  ChartingLibraryWidgetOptions,
-  IChartingLibraryWidget,
-  ResolutionString,
-} from "charting_library/charting_library";
-import { widget } from "charting_library/charting_library";
-
-const LIBRARY_PATH = "/charting_library/"; // must match your hosted assets
-
-// Inside your component:
-const containerRef = useRef<HTMLDivElement>(null);
-const [chartWidget, setChartWidget] = useState<IChartingLibraryWidget | null>(
-  null,
-);
-
-useEffect(() => {
-  const el = containerRef.current;
-  if (!el) return;
-
-  const options: ChartingLibraryWidgetOptions = {
-    container: el,
-    library_path: LIBRARY_PATH,
-    symbol: "EURUSD",
-    interval: "60" as ResolutionString,
-    datafeed: yourDatafeed,
-    locale: "en",
-    autosize: true,
-  };
-
-  const tv = new widget(options);
-  setChartWidget(tv);
-
-  return () => {
-    try {
-      tv.remove();
-    } catch {
-      /* no-op */
-    }
-    setChartWidget(null);
-  };
-}, [/* library_path, datafeed identity, or other inputs that should recreate the chart */]);
-```
-
-You must supply a valid `datafeed`, `symbol`, `interval`, `locale`, and any other options required by your TradingView license and app. Import paths for `widget` and types differ by setup (`charting_library/charting_library`, `./public/charting_library`, etc.—follow TradingView’s docs for your bundler). If your integration only exposes the instance after `onChartReady`, call `setChartWidget` inside that callback instead of immediately after `new widget(...)`.
-
-### Step 4 — 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):
-
-```tsx
-import { WidgetIccandle } from "@iccandle/reactjs-widget";
-
-const widgetKey = "icc_search_..."; // your ICCandle key
-
-<WidgetIccandle
-  chartWidget={chartWidget}
-  widgetKey={widgetKey}
-  theme="system"
-  submitCallback={(iframeSrc) => {
-    /* see Step 5 */
-  }}
->
-  <div ref={containerRef} style={{ height: "100%", minHeight: 400 }} />
-</WidgetIccandle>
-```
-
-### Step 5 — Handle the plugin 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.
-
-**Open in a new tab**
-
-```ts
-submitCallback={(iframeSrc) => {
-  window.open(iframeSrc, "_blank", "noopener,noreferrer");
-}}
-```
-
-**Show in a modal or side panel**
-
-Store the URL in state and render:
-
-```tsx
-{iframeSrc ? (
-  <iframe title="ICCandle pattern search" src={iframeSrc} className="..." />
-) : null}
-```
-
-**TypeScript:** import `WidgetIccandleProps` if you wrap `WidgetIccandle` in your own component and want explicit prop typing. Import `IChartingLibraryWidget` from **your** Charting Library typings path (`charting_library/charting_library` or the path your project uses)—this package does not re-export TradingView types.
-
-### Theme and remote branding
-
-- **`theme="light"` / `"dark"`** — forces that palette for the scanner chrome and for values forwarded into the plugin URL.
-- **`theme="system"`** (recommended when you don’t control parent theme) — follows `prefers-color-scheme` for light/dark resolution.
-- On mount, the widget fetches your org’s tokens from ICCandle (see [Widget key and remote theming](#widget-key-and-remote-theming)) and sets CSS custom properties on the widget root, e.g. `--iccandle-primary`, `--iccandle-border`, so the in-chart scanner matches your configured light/dark branding. The same resolved theme is reflected in the iframe URL so the plugin UI stays consistent.
+### Prerequisites
 
-### Full working example
+- **React 18+** — `react` and `react-dom` are peer dependencies.
+- **TradingView Charting Library** — obtain under your own license, host the static assets (e.g. `/charting_library/`), and bootstrap the widget yourself. **This package does not ship the charting library.**
+- **Auth token** — API calls (candle cache, pattern tracker) use `Bearer` auth from `localStorage` key `iccandle_token`. The embedded results app sets this via a `sign-in-success` `postMessage` after login.
 
-Minimal end-to-end pattern: chart container ref, widget lifecycle, `WidgetIccandle`, and iframe after submit. Replace `yourDatafeed` and widget options with your real datafeed and TradingView settings.
+## Quick start
 
 ```tsx
 import { useEffect, useRef, useState } from "react";
@@ -185,18 +44,44 @@ import type {
   ResolutionString,
 } from "charting_library/charting_library";
 import { widget } from "charting_library/charting_library";
-import { WidgetIccandle } from "@iccandle/reactjs-widget";
+import {
+  WidgetIccandle,
+  withPlayChart,
+  getCustomIndicators,
+} from "@iccandle/reactjs-widget";
 
 const LIBRARY_PATH = "/charting_library/";
-const WIDGET_KEY = "icc_search_your48hexcharactershere............";
 
-export function ChartWithIccandleScanner() {
+function App() {
   const containerRef = useRef<HTMLDivElement>(null);
   const [chartWidget, setChartWidget] = useState<IChartingLibraryWidget | null>(
     null,
   );
-  const [pluginSrc, setPluginSrc] = useState("");
 
+  return (
+    <div style={{ height: "100vh", width: "100%" }}>
+      <WidgetIccandle chartWidget={chartWidget} theme="light" language="en">
+        {(chartRefs) => (
+          <ChartHost
+            containerRef={containerRef}
+            chartRefs={chartRefs}
+            onReady={setChartWidget}
+          />
+        )}
+      </WidgetIccandle>
+    </div>
+  );
+}
+
+function ChartHost({
+  containerRef,
+  chartRefs,
+  onReady,
+}: {
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  chartRefs: import("@iccandle/reactjs-widget").WidgetIccandleChartRefs;
+  onReady: (w: IChartingLibraryWidget | null) => void;
+}) {
   useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -206,18 +91,18 @@ export function ChartWithIccandleScanner() {
       library_path: LIBRARY_PATH,
       symbol: "EURUSD",
       interval: "60" as ResolutionString,
-      datafeed: yourDatafeed,
+      datafeed: withPlayChart(yourDatafeed), // enables chart replay injection
       locale: "en",
       autosize: true,
-      fullscreen: false,
       drawings_access: {
         type: "black",
         tools: [{ name: "Date Range" }],
       },
+      custom_indicators_getter: () => getCustomIndicators("light"),
     };
 
     const tv = new widget(options);
-    setChartWidget(tv);
+    onReady(tv);
 
     return () => {
       try {
@@ -225,108 +110,139 @@ export function ChartWithIccandleScanner() {
       } catch {
         /* no-op */
       }
-      setChartWidget(null);
+      onReady(null);
     };
-  }, []);
+  }, [containerRef, chartRefs, onReady]);
 
-  return (
-    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
-      <div style={{ height: 500, width: "100%" }}>
-        <WidgetIccandle
-          chartWidget={chartWidget}
-          widgetKey={WIDGET_KEY}
-          theme="system"
-          submitCallback={(iframeSrc) => setPluginSrc(iframeSrc)}
-        >
-          <div ref={containerRef} style={{ height: "100%", width: "100%" }} />
-        </WidgetIccandle>
-      </div>
-      {pluginSrc ? (
-        <iframe
-          title="ICCandle search"
-          src={pluginSrc}
-          style={{ width: "100%", height: 600, border: "1px solid #ccc" }}
-        />
-      ) : null}
-    </div>
-  );
+  return <div ref={containerRef} style={{ height: "100%", width: "100%" }} />;
 }
 ```
 
-For a concrete in-repo reference (custom datafeed, timezone, visibility handling), see [`src/tradingview/TradingviewChart.tsx`](src/tradingview/TradingviewChart.tsx) in this repository’s dev app.
+Use a **render-prop `children`** when you need `chartRefs` for generated-candle studies (replay / predict). A plain React node also works if you do not need those refs.
 
-### Common patterns
+For a full in-repo reference, see [`src/tradingview/TradingviewChart.tsx`](src/tradingview/TradingviewChart.tsx).
 
-| Pattern | Approach |
-| -------- | -------- |
-| **Modal iframe** | On `submitCallback`, set state and render `<iframe src={url} />` inside a `<dialog>`, Radix Dialog, MUI Modal, etc. |
-| **New tab** | `window.open(iframeSrc, "_blank", "noopener,noreferrer")`. |
-| **Split layout** | Keep the chart in one column and mount the iframe in another when `pluginSrc` is set (as in the example above). |
-| **News / events on the time axis** | If your datafeed implements `getTimescaleMarks`, you can sync marks with `localStorage` — see [Optional: timescale marks (news/events)](#optional-timescale-marks-newsevents). |
+## Features
 
-### Troubleshooting
+### Pattern scanner
 
-| Issue | What to check |
-| ----- | --------------- |
-| Chart area stays blank | `library_path` must point to the folder URL where TradingView static files are served; container ref must be mounted before `new widget(...)`. |
-| `chartWidget` is always `null` | Ensure you call `setChartWidget` after the widget is created (or inside `onChartReady` if your integration requires it). |
-| Scanner or theme looks wrong | Confirm `widgetKey` is valid; theme fetch uses `api-key: <widgetKey>`. Network or auth failures may leave defaults. |
-| CORS / network errors on theme API | In local dev, browser calls to `api.iccandle.ai` may be blocked by CORS unless you proxy; the widget should still function with fallback styling—verify in production or behind your proxy. |
-| Date range tool missing | Enable the Date Range drawing in `drawings_access` (see full example) so users can select the bar window the scanner uses. |
+- Subscribes to chart readiness, symbol, resolution, and drawing events.
+- Manages a `date_range` multipoint drawing so the user can adjust the bar window (default window size: **25** bars).
+- On scan: posts candles to `https://scan-service.iccandle.ai/cacheCandle`, then navigates the results iframe with query params (`ws`, `tk`, `et`, `symbol`, `tf`, `cid`, filters, theme).
+- Optional **advanced filters** (symbols, top-k, lookback period, probability window) stored in `localStorage` under `search-filter`.
+
+### Results iframe
+
+- Loads `https://embed-iccandle-app.iccandle.ai/{language}?theme=...` by default.
+- After scan / news navigation, the `src` updates with search or similar-events paths.
+- On iframe load, the parent posts `{ type: "parent-origin", origin }` so Stripe checkout can return to the host domain. If the host URL has `?payment=success`, it also posts `{ type: "payment-success" }` so the embed can refresh subscription state.
+
+### Pattern tracker
+
+From the scanner popup, users can open a subscription modal to track a custom pattern (name + timeframes + symbols). Requires a valid `iccandle_token`.
+
+### News / economic events
+
+- Clicking a timescale mark can open an **event info** modal (currency calendar events; skips holidays / early / sentiment-only marks).
+- “Go to detail” loads similar events in the iframe and draws a vertical line on the chart.
+- Marks can be driven from `localStorage` keys `tv:selected-news-events` and `tv:clicked-news-event` if your datafeed implements `getTimescaleMarks` (see below).
+
+### Chart replay (play candles)
+
+Wrap your datafeed with `withPlayChart` and register custom indicators via `getCustomIndicators` so the embed can inject predicted / replay bars without live ticks fighting the playback.
 
 ## API
 
 ### Exports
 
-| Name                 | Kind   | Description                                  |
-| -------------------- | ------ | -------------------------------------------- |
-| `WidgetIccandle`     | Component | Scanner overlay around your chart subtree |
-| `WidgetIccandleProps`| Type   | Props for `WidgetIccandle`                   |
+| Name | Kind | Description |
+| ---- | ---- | ----------- |
+| `WidgetIccandle` | Component | Chart overlay + results iframe |
+| `WidgetIccandleProps` | Type | Props for `WidgetIccandle` |
+| `WidgetIccandleChartRefs` | Type | Refs for highlight bars / generated-candle studies |
+| `WidgetLanguage` | Type | Supported locale codes |
+| `withPlayChart` | Function | Wraps a TradingView datafeed for replay bar injection |
+| `getCustomIndicators` | Function | Returns ICCandle custom indicators (generated candles) |
+| `getGeneratedCandlesMaskColor` | Function | Theme-aware mask color for generated candles |
 
 ### `WidgetIccandle` props
 
-| Prop              | Type                                    | Required | Description |
-| ----------------- | --------------------------------------- | -------- | ----------- |
-| `chartWidget`     | `IChartingLibraryWidget \| null`        | Yes      | Live TradingView widget instance (`null` until ready). |
-| `children`        | `ReactNode`                             | Yes      | Your chart UI (e.g. container + library bootstrap). |
-| `widgetKey`       | `string`                                | Yes      | ICCandle API key (`icc_search_` + 48 hex chars). Used for theme fetch, candle cache, and scanner validation. |
-| `submitCallback`  | `(iframeSrc: string) => void`           | Yes      | Called after a successful scan setup with the **plugin iframe URL** (query string includes window size, timestamps, symbol, `candle_id`, `apiKey`, theme, optional filters). |
-| `theme`           | `"light" \| "dark" \| "system"`         | No       | Defaults to sensible behavior; `"system"` follows `prefers-color-scheme`. Affects resolved theme tokens and the plugin URL. |
+| Prop | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `chartWidget` | `IChartingLibraryWidget \| null` | Yes | Live TradingView widget (`null` until ready). |
+| `children` | `ReactNode \| ((chartRefs) => ReactNode)` | Yes | Chart UI, or render prop receiving `WidgetIccandleChartRefs`. |
+| `theme` | `"light" \| "dark" \| "system"` | No | Scanner chrome + iframe theme. `"system"` follows `prefers-color-scheme`. |
+| `language` | `WidgetLanguage` | No | UI + iframe locale. One of: `en`, `zh`, `vi`, `th`, `ko`, `ja`, `mn`, `ru`. Defaults to `en`. |
+| `onCloseResult` | `() => void` | No | Called when the embed posts `close-result`. |
+| `iframeLoaded` | `boolean` | No | When `false`, disables scan / track actions until the results iframe is ready. Defaults to enabled behavior in the scanner. |
 
-### Widget key and remote theming
+`IChartingLibraryWidget` must be imported from **your** Charting Library typings — this package does not re-export TradingView types.
 
-On mount, the component loads branding colors from ICCandle:
+### `withPlayChart(datafeed)`
 
-- **URL:** `https://api.iccandle.ai/corporate-client/v1/widgetStyle/search/user/?service_type=search`
-- **Header:** `api-key: <widgetKey>`
+Wraps `subscribeBars` so ICCandle can push replay bars and optionally block live ticks during playback.
 
-CSS custom properties (`--iccandle-primary`, `--iccandle-border`, etc.) are applied on the widget root so the scanner matches your configured light/dark tokens.
+```ts
+import { withPlayChart } from "@iccandle/reactjs-widget";
 
-**Theme prop vs. API tokens:** The `theme` prop (`"light"` \| `"dark"` \| `"system"`) chooses which variant of those tokens to apply and is also forwarded in the plugin iframe URL. `"system"` tracks `prefers-color-scheme` so the scanner and plugin stay aligned with the user’s OS preference when you don’t pass an explicit light/dark mode from your app shell.
+datafeed: withPlayChart(myDatafeed),
+// or factory + args:
+datafeed: withPlayChart(createDatafeed, arg1, arg2),
+```
 
-### Behavior summary
+### `getCustomIndicators(theme?)`
 
-- 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 (see scanner implementation for details).
-- Listens for `window` `message` events for chart/news integration and can clear persisted news mark selections (`localStorage` key `tv:selected-news-events`) when starting a scan.
+Returns a Promise of TradingView `CustomIndicator[]` used for generated / predicted candle overlays. Pass `"light"` or `"dark"` to match chart theme. Wire it into widget options:
+
+```ts
+custom_indicators_getter: () => getCustomIndicators("light"),
+```
+
+## Auth and storage
+
+| Key | Purpose |
+| --- | ------- |
+| `iccandle_token` | Bearer token for scan cache, pattern tracker, and related APIs. Set by the embed via `sign-in-success`. |
+| `search-filter` | Scanner advanced options (symbols, top_k, period, probability). |
+| `tv:selected-news-events` | JSON array of news events used as timescale marks. |
+| `tv:clicked-news-event` | Last clicked calendar event for mark highlighting. |
+| `tv:latest-symbol` | Last chart symbol (used by the demo app / fallbacks). |
+
+## postMessage bridge
+
+Messages are accepted only from the results origin (`https://embed-iccandle-app.iccandle.ai`).
+
+| Direction | Type / action | Effect |
+| --------- | ------------- | ------ |
+| Embed → parent | `play-chart` | Inject / clear replay candles on the chart |
+| Embed → parent | `loading` | Toggle scanner loading UI |
+| Embed → parent | `sign-in-success` | Persist `iccandle_token` from `payload.id_token` |
+| Embed → parent | `close-result` | Clears play state; calls `onCloseResult` |
+| Embed → parent | `pattern_selected` / `custom_pattern_selected` | Draw date range for the compared pattern |
+| Embed → parent | `clear_pattern_selected` / `clear_custom_pattern_selected` | Remove pattern date range |
+| Embed → parent | `eventClicked` | Center chart, draw event line, show mark |
+| Embed → parent | `replay` | Start / stop event replay candles |
+| Embed → parent | `back` / `back-to-similar-events` | Clear event line / replay |
+| Embed → parent | `nav-click` | Hide scanner on `/news`; restore otherwise |
+| Parent → embed | `parent-origin` | Host origin for Stripe return |
+| Parent → embed | `payment-success` | Refresh subscription after checkout |
 
 ## Optional: timescale marks (news/events)
 
-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. Example shape:
+If your datafeed implements `getTimescaleMarks`, surface stored events as marks:
 
 ```ts
 getTimescaleMarks: async (
-  symbolInfo: LibrarySymbolInfo,
-  from: number,
-  to: number,
-  onResult: GetMarksCallback<TimescaleMark>,
+  symbolInfo,
+  from,
+  to,
+  onResult,
 ) => {
-  const marks: TimescaleMark[] = [];
+  const marks = [];
   try {
     const allNewsEvents = JSON.parse(
       localStorage.getItem("tv:selected-news-events") || "[]",
-    ) as NewsEventType[];
+    );
 
     allNewsEvents?.forEach(({ id, timestamp, event_name, currency }) => {
       if (!id || !Number.isFinite(timestamp) || timestamp <= 0) return;
@@ -349,17 +265,43 @@ getTimescaleMarks: async (
 };
 ```
 
-Adjust paths and types to match your app and TradingView typings.
+## Theming
+
+Scanner UI uses CSS variables on `.iccandle-selector-widget`:
+
+- `--iccandle-primary`
+- `--iccandle-primary-gradient-end`
+- `--iccandle-background`
+- `--iccandle-border`
+- `--iccandle-text`
+- `--iccandle-secondary`
+- `--iccandle-font`
+
+Light and dark defaults live in the bundled stylesheet. The `theme` prop toggles the `.iccandle-dark` class and is forwarded to the iframe.
 
 ## Development (this repo)
 
-| Script        | Command      | Purpose |
-| ------------- | ------------ | ------- |
-| Dev demo      | `npm run dev` | Vite app with local charting library (see `vite.config.ts`). |
-| Library build | `npm run build` | Emits `dist/` (JS, CJS, bundled CSS injection, declarations). |
-| Lint          | `npm run lint` | ESLint. |
+| Script | Command | Purpose |
+| ------ | ------- | ------- |
+| Dev demo | `pnpm run dev` | Vite app with local charting library |
+| Library build | `pnpm run build` | Emits `dist/` (ESM, CJS, injected CSS, `.d.ts`) |
+| Web build | `pnpm run build:web` | SPA build to `dist-web/` |
+| Deploy web | `pnpm run deploy:web` | Build + Vercel production deploy |
+| Lint | `pnpm run lint` | ESLint |
+| Preview web | `pnpm run preview` | Preview the web build |
+
+`prepublishOnly` runs `build` before npm publish.
+
+## Troubleshooting
 
-`prepublishOnly` runs `build` before publish.
+| Issue | What to check |
+| ----- | --------------- |
+| Chart stays blank | `library_path` must serve TradingView static files; container must be mounted before `new widget(...)`. |
+| `chartWidget` is always `null` | Call `setChartWidget` after create (or inside `onChartReady` if required). |
+| Scan fails / 401 | Ensure the user signed in via the results iframe so `iccandle_token` is set. |
+| Date Range tool missing | Enable it in `drawings_access` (see Quick start). |
+| Replay bars do not appear | Wrap the datafeed with `withPlayChart` and register `getCustomIndicators`. |
+| Scanner actions disabled | Pass `iframeLoaded={true}` once the results iframe has loaded, or omit the prop if you do not gate on load. |
 
 ## License