@forgecharts/sdk 1.1.23 → 1.1.28

package/dist/types/IChart.d.ts

@@ -0,0 +1,48 @@
+import type { SeriesOptions } from '@forgecharts/types';
+import type { ISeries } from './ISeries';
+import type { CoordTransform } from '../core/CoordTransform';
+export interface IChart {
+    /**
+     * Adds a new series to the chart and returns a handle for data management.
+     */
+    addSeries(options: SeriesOptions): ISeries;
+    /**
+     * Removes a previously added series.
+     */
+    removeSeries(series: ISeries): void;
+    /**
+     * Registers a plugin that participates in the render loop.
+     */
+    addPlugin(plugin: IChartPlugin): void;
+    /**
+     * Deregisters a plugin.
+     */
+    removePlugin(plugin: IChartPlugin): void;
+    /**
+     * Applies partial chart options at runtime (theme, scale options, etc.).
+     */
+    applyOptions(options: import('@forgecharts/types').ChartOptions): void;
+    /**
+     * Manually sets the canvas dimensions. Usually called from ResizeObserver.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Tears down all resources and removes canvas elements from the DOM.
+     */
+    destroy(): void;
+    /**
+     * Returns the coordinate transform for pixel ↔ data conversions.
+     * The returned instance is kept up-to-date across resizes; callers may
+     * hold a stable reference.
+     */
+    transform(): CoordTransform;
+}
+export interface IChartPlugin {
+    /** Called once when the plugin is added to a chart. */
+    onAttach(chart: IChart): void;
+    /** Called once when the plugin is removed from a chart. */
+    onDetach(): void;
+    /** Called every animation frame after series are rendered. */
+    onRender(): void;
+}
+//# sourceMappingURL=IChart.d.ts.map

package/dist/types/IChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IChart.d.ts","sourceRoot":"","sources":["../../src/types/IChart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAE3C;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAEpC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,oBAAoB,EAAE,YAAY,GAAG,IAAI,CAAC;IAEvE;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5C;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;IAEhB;;;;OAIG;IACH,SAAS,IAAI,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,IAAI,IAAI,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,IAAI,IAAI,CAAC;CAClB"}

package/dist/types/IChart.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IChart.js.map

package/dist/types/IChart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IChart.js","sourceRoot":"","sources":["../../src/types/IChart.ts"],"names":[],"mappings":""}

package/{src/types/IRenderer.ts → dist/types/IRenderer.d.ts}

@@ -1,16 +1,10 @@
 import type { OHLCV, SeriesOptions, Viewport, Rect } from '@forgecharts/types';
-
 /**
  * IRenderer — contract for all series drawing strategies.
  * Each renderer receives only what it needs: bars, viewport, and target rect.
  * No DOM or Chart references — pure canvas drawing.
  */
 export interface IRenderer {
-  draw(
-    ctx: CanvasRenderingContext2D,
-    bars: readonly OHLCV[],
-    viewport: Viewport,
-    rect: Rect,
-    options: SeriesOptions,
-  ): void;
+    draw(ctx: CanvasRenderingContext2D, bars: readonly OHLCV[], viewport: Viewport, rect: Rect, options: SeriesOptions): void;
 }
+//# sourceMappingURL=IRenderer.d.ts.map

package/dist/types/IRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRenderer.d.ts","sourceRoot":"","sources":["../../src/types/IRenderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CACF,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,SAAS,KAAK,EAAE,EACtB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,GACrB,IAAI,CAAC;CACT"}

package/dist/types/IRenderer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IRenderer.js.map

package/dist/types/IRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRenderer.js","sourceRoot":"","sources":["../../src/types/IRenderer.ts"],"names":[],"mappings":""}

package/dist/types/ISeries.d.ts

@@ -0,0 +1,26 @@
+import type { OHLCV, SeriesOptions } from '@forgecharts/types';
+export interface ISeries {
+    /**
+     * Replaces the entire dataset. Data need not be pre-sorted.
+     */
+    setData(data: readonly OHLCV[]): void;
+    /**
+     * Appends or updates the last bar.
+     * If bar.time === last bar's time, the bar is updated (real-time tick).
+     * Otherwise, the bar is appended.
+     */
+    update(bar: OHLCV): void;
+    /**
+     * Returns the current dataset (sorted ascending by time).
+     */
+    data(): readonly OHLCV[];
+    /**
+     * Merges partial options into the series configuration.
+     */
+    applyOptions(options: Partial<SeriesOptions>): void;
+    /**
+     * Returns the current fully-resolved series options.
+     */
+    options(): SeriesOptions;
+}
+//# sourceMappingURL=ISeries.d.ts.map

package/dist/types/ISeries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISeries.d.ts","sourceRoot":"","sources":["../../src/types/ISeries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI,CAAC;IAEtC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,IAAI,IAAI,SAAS,KAAK,EAAE,CAAC;IAEzB;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IAEpD;;OAEG;IACH,OAAO,IAAI,aAAa,CAAC;CAC1B"}

package/dist/types/ISeries.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ISeries.js.map

package/dist/types/ISeries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISeries.js","sourceRoot":"","sources":["../../src/types/ISeries.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecharts/sdk",
-  "version": "1.1.23",
+  "version": "1.1.28",
   "description": "ForgeCharts SDK — canvas-based charting engine, no third-party chart libraries",
   "repository": {
     "type": "git",
@@ -23,8 +23,22 @@
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js",
       "require": "./dist/internal.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.js"
+    },
+    "./react/internal": {
+      "types": "./dist/react/internal.d.ts",
+      "import": "./dist/react/internal.js",
+      "require": "./dist/react/internal.js"
     }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsup --no-dts && tsc --build --force tsconfig.json",
@@ -36,12 +50,26 @@
     "clean": "rimraf dist tsconfig.tsbuildinfo"
   },
   "dependencies": {
-    "@forgecharts/shared": "*",
-    "@forgecharts/types": "*",
-    "@forgecharts/utils": "*",
     "pixi.js": "^8.16.0"
   },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@forgecharts/shared": "*",
+    "@forgecharts/types": "*",
+    "@forgecharts/utils": "*",
+    "@types/react": "*",
+    "@types/react-dom": "*",
     "rimraf": "^5.0.10",
     "tsup": "^8.2.4",
     "typescript": "*",

package/src/__tests__/backwardCompatibility.test.ts

@@ -1,191 +0,0 @@
-/**
- * Backward compatibility — unit tests
- *
- * Verifies that the introduction of licensing, unmanaged mode, and managed
- * foundations does NOT break the existing SDK contract:
- *
- *   1. All expected exports exist and have the correct shape/type
- *   2. CandleEngine works unchanged (no side-effects from new code)
- *   3. Default mode is unmanaged (safe default — nothing breaks by default)
- *   4. The RapidAPI datafeed path is unaffected (DatafeedConnector still exports)
- *   5. New modules export correctly from the package root (index.ts)
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import { LicenseManager } from '../licensing/LicenseManager';
-import { CandleEngine } from '../engine/CandleEngine';
-import type { RawOHLCV } from '../engine/CandleEngine';
-
-// ─── License cleanup ──────────────────────────────────────────────────────────
-
-beforeEach(() => {
-  LicenseManager.getInstance().clear();
-});
-
-// ─── Existing exports remain intact ──────────────────────────────────────────
-
-describe('Backward compatibility — SDK exports', () => {
-  it('CandleEngine is exported', async () => {
-    const mod = await import('../engine/CandleEngine');
-    expect(mod.CandleEngine).toBeDefined();
-    expect(typeof mod.CandleEngine).toBe('function');
-  });
-
-  it('timeframeToMs and getBucketStart are exported', async () => {
-    const mod = await import('../engine/timeframeUtils');
-    expect(typeof mod.timeframeToMs).toBe('function');
-    expect(typeof mod.getBucketStart).toBe('function');
-  });
-
-  it('LicenseManager is exported', async () => {
-    const mod = await import('../licensing/LicenseManager');
-    expect(mod.LicenseManager).toBeDefined();
-  });
-
-  it('ChartRuntimeResolver is exported', async () => {
-    const mod = await import('../licensing/ChartRuntimeResolver');
-    expect(mod.ChartRuntimeResolver).toBeDefined();
-    expect(typeof mod.isManagedMode).toBe('function');
-    expect(typeof mod.isUnmanagedMode).toBe('function');
-    expect(typeof mod.canRenderOrderEntry).toBe('function');
-    expect(typeof mod.canRenderManagedTradingControls).toBe('function');
-    expect(typeof mod.canRenderExternalOverlayOnlyMode).toBe('function');
-  });
-
-  it('TradingOverlayStore is exported', async () => {
-    const mod = await import('../trading/TradingOverlayStore');
-    expect(mod.TradingOverlayStore).toBeDefined();
-    expect(typeof mod.TradingOverlayStore).toBe('function');
-  });
-
-  it('UnmanagedIngestion is exported', async () => {
-    const mod = await import('../trading/UnmanagedIngestion');
-    expect(mod.UnmanagedIngestion).toBeDefined();
-    expect(typeof mod.UnmanagedIngestion).toBe('function');
-  });
-
-  it('ManagedTradingController is exported', async () => {
-    const mod = await import('../trading/managed/ManagedTradingController');
-    expect(mod.ManagedTradingController).toBeDefined();
-    expect(typeof mod.ManagedTradingController).toBe('function');
-  });
-
-  it('DatafeedConnector is exported (default RapidAPI path intact)', async () => {
-    const mod = await import('../datafeed/DatafeedConnector');
-    expect(mod.DatafeedConnector).toBeDefined();
-    expect(typeof mod.DatafeedConnector).toBe('function');
-  });
-});
-
-// ─── CandleEngine unchanged ───────────────────────────────────────────────────
-
-describe('Backward compatibility — CandleEngine still works with no license', () => {
-  // T0 = 2024-07-03T10:00:00Z in seconds
-  const T0 = 1_719_997_200;
-  const T1 = T0 + 60;
-
-  function raw(time: number, close: number): RawOHLCV {
-    return { time, open: 100, high: close + 5, low: close - 5, close, volume: 1 };
-  }
-
-  it('can be instantiated and used without any license', () => {
-    const engine = new CandleEngine();
-    expect(() => engine.initialize([], '1m')).not.toThrow();
-  });
-
-  it('basic OHLCV update works — no licensing side-effects', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(raw(T0, 100));
-    engine.applyLiveUpdate(raw(T0, 105));
-    engine.applyLiveUpdate(raw(T1, 110));
-
-    expect(engine.getBars()).toHaveLength(2);
-    expect(engine.getBars()[0]!.close).toBe(105);
-    expect(engine.getBars()[1]!.close).toBe(110);
-  });
-
-  it('initialize() resets state completely', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-    engine.applyLiveUpdate(raw(T0, 100));
-    engine.initialize([], '5m');
-    expect(engine.getBars()).toHaveLength(0);
-  });
-});
-
-// ─── Default license mode — safe unmanaged defaults ──────────────────────────
-
-describe('Backward compatibility — default mode is unmanaged', () => {
-  it('LicenseManager.getMode() returns unmanaged with no license', () => {
-    const lm = LicenseManager.getInstance();
-    expect(lm.getMode()).toBe('unmanaged');
-    expect(lm.getLicense()).toBeNull();
-  });
-
-  it('isUnmanagedMode() is true with no license', async () => {
-    const { isUnmanagedMode } = await import('../licensing/ChartRuntimeResolver');
-    expect(isUnmanagedMode()).toBe(true);
-  });
-
-  it('isManagedMode() is false with no license', async () => {
-    const { isManagedMode } = await import('../licensing/ChartRuntimeResolver');
-    expect(isManagedMode()).toBe(false);
-  });
-
-  it('canRenderCandles() is true with no license', async () => {
-    const { canRenderCandles } = await import('../licensing/ChartRuntimeResolver');
-    expect(canRenderCandles()).toBe(true);
-  });
-
-  it('canRenderorderEntry() is false with no license', async () => {
-    const { canRenderOrderEntry } = await import('../licensing/ChartRuntimeResolver');
-    expect(canRenderOrderEntry()).toBe(false);
-  });
-
-  it('canRenderManagedTradingControls() is false with no license', async () => {
-    const { canRenderManagedTradingControls } = await import('../licensing/ChartRuntimeResolver');
-    expect(canRenderManagedTradingControls()).toBe(false);
-  });
-});
-
-// ─── Unmanaged ingestion is additive — does not replace the existing datafeed ─
-
-describe('Backward compatibility — unmanaged ingestion is opt-in and additive', () => {
-  it('UnmanagedIngestion can be instantiated without affecting CandleEngine state', async () => {
-    const standaloneEngine = new CandleEngine();
-    standaloneEngine.initialize([], '1m');
-
-    // Creating an UnmanagedIngestion constructs its OWN internal CandleEngine
-    const { UnmanagedIngestion } = await import('../trading/UnmanagedIngestion');
-    const ing = new UnmanagedIngestion('1m');
-
-    // The standalone engine is still clean
-    expect(standaloneEngine.getBars()).toHaveLength(0);
-    // The ingestion engine also starts empty
-    expect(ing.getBars()).toHaveLength(0);
-  });
-
-  it('DatafeedConnector can still be constructed independently', async () => {
-    const { DatafeedConnector } = await import('../datafeed/DatafeedConnector');
-    const mockDatafeed = {
-      getHistoricalBars: () => Promise.resolve({ bars: [], noData: true }),
-      subscribeBars:     () => {},
-      unsubscribeBars:   () => {},
-    };
-    const mockSeries = {
-      setData:      () => {},
-      update:       () => {},
-      data:         () => [],
-      applyOptions: () => {},
-      options:      () => ({} as never),
-    };
-    const mockCallbacks = {
-      onLoading: () => {},
-      onLoaded:  () => {},
-      onError:   () => {},
-    };
-    expect(() => new DatafeedConnector(mockDatafeed, mockSeries, mockCallbacks)).not.toThrow();
-  });
-});