@tony01/astroneum 0.4.1-beta.2 → 0.4.1-beta.24

package/docs/api.md

@@ -1,528 +1,655 @@
-# API Reference
-
-## Constructor
-
-```typescript
-<AstroneumChart ref={ref} {...options} />
-```
-
-### `AstroneumOptions`
-
-| Property | Type | Required | Default | Description |
-|---|---|---|---|---|
-| `symbol` | `SymbolInfo` | ✓ | — | Symbol to display on load |
-| `period` | `Period` | ✓ | — | Initial timeframe |
-| `datafeed` | `Datafeed` | ✓ | — | Data source implementation |
-| `theme` | `'light' \| 'dark'` | | `getSystemTheme()` | UI theme. Omit to auto-detect OS color scheme. |
-| `locale` | `string` | | `'en-US'` | UI locale key |
-| `timezone` | `string` | | `'Asia/Shanghai'` | IANA timezone identifier for the X-axis |
-| `watermark` | `string \| Node` | | Astroneum logo SVG | Watermark rendered in the chart center |
-| `styles` | `DeepPartial<Styles>` | | `{}` | Deep-partial engine style override |
-| `drawingBarVisible` | `boolean` | | `true` | Whether the left-side drawing toolbar is shown |
-| `periods` | `Period[]` | | `[1m,5m,15m,1H,2H,4H,D,W,M,Y]` | Timeframes available in the period bar |
-| `mainIndicators` | `IndicatorDef[]` | | `[{ name: 'EMA', calcParams: [7,25,99] }]` | Indicators overlaid on the main candle pane |
-| `subIndicators` | `string[]` | | `['VOL']` | Indicator names rendered in sub-panes below the chart |
-| `plugins` | `ChartPlugin[]` | | `[]` | Plugins mounted with chart lifecycle hooks (`onInit` / disposer) |
-
----
-
-## Instance methods
-
-### `setTheme(theme)`
-```typescript
-setTheme(theme: 'light' | 'dark'): void
-```
-Sets the UI theme. Updates both the `data-theme` attribute and the internal chart styles.
-
-### `getTheme()`
-```typescript
-getTheme(): string
-```
-Returns the current theme name.
-
-### `setStyles(styles)`
-```typescript
-setStyles(styles: DeepPartial<Styles>): void
-```
-Merges the given partial styles into the engine's current style tree.
-
-### `getStyles()`
-```typescript
-getStyles(): Styles
-```
-Returns the full resolved engine style object.
-
-### `setLocale(locale)`
-```typescript
-setLocale(locale: string): void
-```
-Switches the UI and engine locale. The locale key must have been registered with `loadLocales()` (for UI strings) and the engine's `registerLocale()` (for OHLC/indicator labels).
-
-### `getLocale()`
-```typescript
-getLocale(): string
-```
-Returns the current locale key.
-
-### `setTimezone(timezone)`
-```typescript
-setTimezone(timezone: string): void
-```
-Changes the IANA timezone used for the X-axis date labels.
-
-### `getTimezone()`
-```typescript
-getTimezone(): string
-```
-Returns the current timezone.
-
-### `setSymbol(symbol)`
-```typescript
-setSymbol(symbol: SymbolInfo): void
-```
-Loads a new symbol. Triggers a full data reload via the datafeed.
-
-### `getSymbol()`
-```typescript
-getSymbol(): SymbolInfo
-```
-Returns the currently active `SymbolInfo`.
-
-### `setPeriod(period)`
-```typescript
-setPeriod(period: Period): void
-```
-Switches the active timeframe. Triggers a full data reload.
-
-### `getPeriod()`
-```typescript
-getPeriod(): Period
-```
-Returns the currently active `Period`.
-
-### `serializeState()` / `loadState()`
-
-```typescript
-serializeState(): SerializedChartState
-loadState(state: SerializedChartState): void
-```
-
-Capture and restore the chart's user-visible state — theme, locale,
-timezone, symbol, period, styles, indicators, and drawing overlays —
-as a JSON-safe object.
-
-```ts
-// save
-localStorage.setItem('chart-state', JSON.stringify(chartRef.current!.serializeState()))
-
-// restore on mount
-const saved = localStorage.getItem('chart-state')
-if (saved) chartRef.current!.loadState(JSON.parse(saved))
-```
-
-`loadState()` is a best-effort restore: missing or unknown indicator /
-overlay names are silently skipped (matching the engine's behaviour for
-unregistered names). The `version` field lets the format evolve without
-breaking older payloads; payloads from a newer format than the current
-library understands are ignored.
-
----
-
-## Accessibility
-
-`<AstroneumChart>` accepts an `accessible` prop (default `false`) that
-opts the canvas into screen-reader and keyboard-focus support without
-changing visuals:
-
-- The container gets `tabindex=0`, `role="img"`, and an `aria-label`
-  (defaults to `"<ticker> <period text> chart"`; override via the
-  `ariaLabel` prop).
-- A visually-hidden `aria-live="polite"` region announces OHLCV on
-  crosshair changes, throttled to ~10 updates / second to avoid
-  flooding screen-reader queues.
-
-```tsx
-<AstroneumChart
-  symbol={{ ticker: 'BTC-USD' }}
-  period={{ multiplier: 1, timespan: 'minute', text: '1m' }}
-  datafeed={datafeed}
-  accessible
-  ariaLabel='Bitcoin / USD 1-minute candles'
-/>
-```
-
-For users who require a high-contrast UI, set `theme="high-contrast"`
-(or call `setTheme('high-contrast')`). The bundled theme uses a
-black background, white candles/grid, and yellow accents with strong
-focus rings.
-
----
-
-## Lazy locales
-
-Only `en-US` is bundled with the main entry. Load any other built-in
-locale on demand:
-
-```ts
-import { loadLocale, BUILTIN_LOCALES } from '@tony01/astroneum'
-
-await loadLocale('ja-JP')
-chartRef.current?.setLocale('ja-JP')
-
-console.log(BUILTIN_LOCALES) // ['en-US', 'zh-CN', 'ja-JP', ...]
-```
-
-`loadLocale(key)` resolves with the dictionary on success, or `null`
-when `key` is not a built-in locale. Concurrent calls for the same
-locale are de-duplicated. To register a fully custom locale,
-keep using `loadLocales(key, dictionary)`.
-
----
-
-## Subpath entry points
-
-Optional features are reachable through dedicated subpath imports so a
-consumer can pull in just what they need.
-
-| Subpath | Exports |
-| --- | --- |
-| `astroneum/replay` | `BarReplay`, types `BarReplayOptions`, `BarReplayState` |
-| `astroneum/multichart` | `MultiChartLayout`, types `MultiChartCount`, `MultiChartSlot`, `MultiChartLayoutOptions` |
-| `astroneum/watchlist` | `WatchlistManager`, types `Watchlist`, `WatchSymbol` |
-| `astroneum/portfolio` | `PortfolioTracker`, types `Position`, `PositionSide`, `PnLResult` |
-| `astroneum/alerts` | `AlertManager`, full alert type surface |
-| `astroneum/script` | `ScriptEngine`, types `CompiledIndicator`, `StudyOptions`, `PlotOptions`, `InputOptions` |
-| `astroneum/datafeeds/polygon` | `DefaultDatafeed`, `WebSocketDatafeed`, `WebSocketDatafeedOptions` |
-| `astroneum/datafeeds/crypto` | `createStandardCryptoDatafeed`, `StandardCryptoDatafeed`, `STANDARD_CRYPTO_SYMBOLS`, `DATAFEED_ERROR_EVENT`, `BinanceAdapter`, `BitgetAdapter`, `OkxAdapter`, plus types |
-
-All listed symbols also re-export from the root `astroneum` entry today,
-but the root re-exports for these modules will be removed in **v1.0**
-(see the [Roadmap](../README.md#v10--stability)). Migrate to the subpath
-import to be forward-compatible.
-
-```ts
-// recommended — forward-compatible with v1.0
-import { BarReplay } from '@tony01/astroneum/replay'
-import { createStandardCryptoDatafeed } from '@tony01/astroneum/datafeeds/crypto'
-
-// legacy — works today, will be removed in v1.0
-import { BarReplay, createStandardCryptoDatafeed } from '@tony01/astroneum'
-```
-
----
-
-## Exported utilities
-
-### Brand cast helpers
-
-```typescript
-import { asPrice, asVolume, asTimestamp } from '@tony01/astroneum'
-
-const p: Price = asPrice(100.50)
-const v: Volume = asVolume(1_250_000)
-const t: Timestamp = asTimestamp(Date.now())
-```
-
-These are type-safe cast functions. They assert that a plain `number` belongs to a specific financial domain without any runtime overhead.
-
-### `rafCoalesce`
-
-```typescript
-import { rafCoalesce } from '@tony01/astroneum'
-
-const dispatch = rafCoalesce((tick: CandleData) => chart.updateBar(tick))
-webSocket.onmessage = e => dispatch(parse(e.data)) // safe to call 100×/s
-```
-
-Returns a dispatcher that schedules `fn` on the next `requestAnimationFrame`, coalescing rapid calls so only the **last** value is delivered per frame. Use this when you only care about the latest state (e.g. price display). For financial accuracy across bursts, use `rafMergeTick` instead.
-
-### `rafMergeTick`
-
-```typescript
-import { rafMergeTick } from '@tony01/astroneum'
-
-const cancel = rafMergeTick(incomingTick, (merged) => {
-  chart.updateBar(merged)
-})
-// Call cancel() to stop
-```
-
-OHLCV-aware frame coalescer for WebSocket burst handling. Merges all ticks arriving within the same `requestAnimationFrame` frame into one financially accurate bar:
-- `open` = first tick
-- `high` = max across ticks
-- `low` = min across ticks
-- `close` = last tick
-- `volume` = sum across ticks
-
-### `EventBus`
-
-```typescript
-import { EventBus } from '@tony01/astroneum'
-import type { ChartEventMap } from '@tony01/astroneum'
-
-const bus = new EventBus<ChartEventMap>()
-
-bus.on('tick', (candle) => console.log(candle.close))
-bus.emit('tick', bar)
-bus.off('tick', handler)
-```
-
-Zero-dependency, type-safe synchronous event bus.
-
-### `TickAnimator`
-
-```typescript
-import { TickAnimator } from '@tony01/astroneum'
-import type { TickAnimatorOptions } from '@tony01/astroneum'
-
-const opts: TickAnimatorOptions = { duration: 120 } // ms
-const animator = new TickAnimator(opts, (frame) => {
-  chart.updateLastBar(frame)
-})
-
-animator.push(newTick)
-animator.cancel()
-```
-
-Smooth ease-out cubic interpolation of the last bar's `close`/`high`/`low` over `duration` ms (default 120 ms). Zero allocations in the rAF loop.
-
-### `RingBuffer`
-
-```typescript
-import { RingBuffer } from '@tony01/astroneum'
-
-const buf = new RingBuffer<CandleData>(1000) // fixed capacity
-buf.push(candle)
-const arr = buf.toArray() // oldest → newest
-```
-
-Fixed-capacity O(1) circular buffer designed for streaming time-series data.
-
----
-
-## Exported types
-
-```typescript
-import type {
-  // Core
-  AstroneumOptions,
-  AstroneumHandle,
-  SerializedChartState,
-  Datafeed,
-  SymbolInfo,
-  Period,
-  CandleData,
-  DatafeedSubscribeCallback,
-
-  // Branded primitives
-  Price,
-  Volume,
-  Timestamp,
-
-  // Indicator
-  IndicatorDef,
-  IndicatorPlugin,
-  ChartPlugin,
-  ChartPluginContext,
-
-  // Events
-  ChartEventMap,
-
-  // Coordinate space
-  Viewport,
-
-  // Engine types
-  Styles,
-  DeepPartial,
-  Coordinate,
-  Bounding,
-
-  // Utility types
-  TickAnimatorOptions,
-  TimeframeText,
-  Timespan,
-
-  // MultiChartLayout
-  MultiChartCount,
-  MultiChartSlot,
-  MultiChartLayoutOptions,
-
-  // BarReplay
-  BarReplayOptions,
-  BarReplayState,
-
-  // Drawing templates
-  OverlayStylePreset,
-  DrawingStyleTemplate,
-
-  // AlertManager
-  Alert,
-  AlertCondition,
-  AlertStatus,
-  AlertFrequency,
-  AlertCreate,
-  AlertCheckInput,
-  AlertTriggeredCallback,
-
-  // Format helpers
-  FormatPriceOptions,
-  DateFormatStyle,
-  TimeFormatStyle,
-
-  // ScriptEngine
-  CompiledIndicator,
-  StudyOptions,
-  PlotOptions,
-  InputOptions,
-
-  // WatchlistManager
-  Watchlist,
-  WatchSymbol,
-
-  // PortfolioTracker
-  Position,
-  PositionSide,
-  PnLResult,
-
-  // PerformanceMode
-  PerformanceBar,
-} from '@tony01/astroneum'
-```
-
-### `IndicatorDef`
-
-```typescript
-interface IndicatorDef {
-  /** Registered indicator name, e.g. 'EMA', 'MA', 'RSI' */
-  name: string
-  /** Calculation parameters passed to the indicator engine */
-  calcParams?: number[]
-}
-```
-
-### `IndicatorPlugin<TOutput>`
-
-```typescript
-interface IndicatorPlugin<TOutput> {
-  name: string
-  shortName?: string
-  calcParams?: number[]
-  calc(data: CandleData[], params: number[]): TOutput[]
-  render2D?(ctx: CanvasRenderingContext2D, output: TOutput[], viewport: Viewport): void
-  renderGL?(gl: WebGL2RenderingContext, output: TOutput[], viewport: Viewport, vbo: WebGLBuffer): void
-}
-```
-
-Implement this interface to register a custom typed indicator.  
-Use `render2D` for lightweight overlays (< 10k points) and `renderGL` for high-density or GPU-accelerated rendering.
-When `renderGL` is present, Astroneum executes it on a dedicated WebGL2 layer and reuses a per-indicator `vbo`.
-If WebGL2 is unavailable, `render2D` is used as fallback when available.
-
-### `registerIndicatorPlugin(plugin)`
-
-```typescript
-registerIndicatorPlugin<TOutput>(plugin: IndicatorPlugin<TOutput>): void
-```
-
-Adapts `IndicatorPlugin` to the engine `IndicatorTemplate` format and registers it.
-
-### `registerIndicatorPlugins(plugins)`
-
-```typescript
-registerIndicatorPlugins(plugins: IndicatorPlugin<unknown>[]): void
-```
-
-Batch helper for registering multiple indicator plugins.
-
-### `createIndicatorTemplateFromPlugin(plugin)`
-
-```typescript
-createIndicatorTemplateFromPlugin<TOutput>(plugin: IndicatorPlugin<TOutput>): IndicatorTemplate
-```
-
-Returns the converted engine template without registering it. Useful when you want manual control over registration.
-
-### `ChartPlugin`
-
-```typescript
-interface ChartPlugin {
-  name?: string
-  indicators?: IndicatorPlugin<unknown>[]
-  onInit?: (context: ChartPluginContext) => void | (() => void)
-}
-```
-
-`indicators` are registered before chart indicator creation begins. `onInit` runs once after chart initialization and may return a disposer called during chart teardown.
-
-### `ChartPluginContext`
-
-```typescript
-interface ChartPluginContext {
-  chart: Chart
-  registerIndicatorPlugin: (plugin: IndicatorPlugin<unknown>) => void
-  registerIndicatorPlugins: (plugins: IndicatorPlugin<unknown>[]) => void
-}
-```
-
-### `ChartEventMap`
-
-```typescript
-interface ChartEventMap {
-  'symbol-change': SymbolInfo
-  'period-change': Period
-  'crosshair-move': Coordinate | null
-  'zoom': { scale: number; anchor: ZoomAnchor }
-  'data-load': { type: 'init' | 'forward' | 'backward'; count: number }
-  'tick': CandleData
-  'drawing-start': string
-  'drawing-end': string
-  'theme-change': string
-}
-```
-
-### `Viewport`
-
-```typescript
-interface Viewport {
-  priceMin: Price
-  priceMax: Price
-  timeMin: Timestamp
-  timeMax: Timestamp
-  resolution: readonly [width: number, height: number]
-}
-```
-
-Represents the currently visible region of the chart canvas. Used for coordinate-space transforms in custom `IndicatorPlugin` renderers.
-
----
-
-## Additional exports
-
-| Export | Description |
-|---|---|
-| `DefaultDatafeed` | Polygon.io REST + WebSocket datafeed |
-| `MultiChartLayout` | Multi-chart layout manager |
-| `BarReplay` | Historical bar replay engine |
-| `DrawingTemplates` | Save/load drawing style templates |
-| `AlertManager` | Price alert creation and monitoring |
-| `ScriptEngine` | Pine-like indicator scripting sandbox (`compile()` auto-registers indicators) |
-| `registerIndicator` | Register a raw engine `IndicatorTemplate` |
-| `getSupportedIndicators` | List all registered indicator names |
-| `registerOverlay` | Register a raw engine `OverlayTemplate` |
-| `getSupportedOverlays` | List all registered overlay names |
-| `registerXAxis` / `registerYAxis` | Register custom axis templates |
-| `registerIndicatorPlugin` | Register a typed `IndicatorPlugin` via adapter |
-| `registerIndicatorPlugins` | Batch register typed indicator plugins |
-| `createIndicatorTemplateFromPlugin` | Convert `IndicatorPlugin` to engine template |
-| `WatchlistManager` | Symbol watchlist with live prices |
-| `PortfolioTracker` | Position tracking and P&L calculation |
-| `PerformanceMode` | Reduced-render performance optimization |
-| `loadLocales` | Register UI locale strings |
-| `formatPrice` | Format a price number using symbol precision |
-| `formatVolume` | Format a volume number |
-| `formatPercent` | Format a percentage value |
-| `formatDate` / `formatTime` / `formatDateTime` | Date/time formatting helpers |
-| `formatDuration` | Format a duration in milliseconds as human-readable text |
-| `formatPeriod` | Format a `Period` as a human-readable string (e.g. `'1H'`) |
-| `detectPricePrecision` | Auto-detect decimal precision from price data |
-
+# API Reference
+
+## Strategy backtesting
+
+`runBacktest(bars, signals, config)` is a deterministic, bar-close simulation
+API. It returns `BacktestResult`, containing normalized trades, equity and
+drawdown points, and summary metrics. It does not place orders, persist data,
+or connect to brokers.
+
+`ScriptEngine.compileStrategy(source)` is intentionally bounded: scripts define
+`strategySignals({ open, high, low, close, volume, ta })` and return an array
+of `{ index, action: 'enter' | 'exit', side?: 'long' | 'short' }`. Its runner
+uses the same `runBacktest` core. It is not Pine-compatible `strategy.*`.
+
+## Headless engine
+
+The supported `@tony01/astroneum/headless` entry exposes the chart renderer
+without React, native Astroneum UI, stylesheets, datafeeds, keyboard shortcuts,
+or implicit network behavior.
+
+```typescript
+import {
+  asPrice,
+  asTimestamp,
+  createChart,
+  destroyChart,
+  registerBuiltInExtensions,
+} from '@tony01/astroneum/headless'
+
+registerBuiltInExtensions()
+const chart = createChart(container, { timezone: 'UTC', styles: 'dark' })
+
+chart.replaceBars([{
+  timestamp: asTimestamp(1_788_000_000_000),
+  open: asPrice(100),
+  high: asPrice(105),
+  low: asPrice(98),
+  close: asPrice(103),
+}])
+
+chart.updateBar({
+  timestamp: asTimestamp(1_788_000_060_000),
+  open: asPrice(103),
+  high: asPrice(106),
+  low: asPrice(102),
+  close: asPrice(104),
+})
+
+destroyChart(chart)
+```
+
+`createChart(container, options?)` owns one chart per supplied element. A second
+call for the same element is idempotent and returns the existing instance;
+options from the duplicate call are ignored. A container marked by another
+Astroneum module instance fails visibly rather than mounting duplicate DOM.
+`destroyChart(chartOrContainer)` is idempotent and releases all registry ownership.
+
+`replaceBars(bars)` validates the full input before mutation and requires finite,
+internally consistent OHLCV values with unique, strictly ascending safe-integer
+UTC-millisecond timestamps. `updateBar(bar)` accepts only the current last
+timestamp or a newer timestamp. Both methods copy accepted data, reject rather
+than repair invalid input, and switch the chart to host-owned data by detaching
+any explicitly configured engine loader. `getBars()` returns a copy.
+
+`HeadlessChart` also exposes viewport, coordinate conversion, pane, indicator,
+overlay, event, and resize primitives. `getViewportState()` returns the JSON-safe
+version-1 shape `{ version, barSpace, rightOffsetBarCount }`.
+`setViewportState()` accepts only version 1, finite bar spacing from 1 through 50,
+and a finite right-offset bar count; the offset is clamped to the current bars and
+container geometry. Apply recovery state after bars load. It is engine recovery
+data, not semantic chart state.
+
+Optional built-in indicators and drawings use process-wide registries and are
+installed only after `registerBuiltInExtensions()` is called. The headless entry
+also exports typed `registerIndicatorPlugin()` helpers plus raw
+`registerIndicator()` and `registerOverlay()` primitives for host-owned outputs.
+Browser coverage carries 16 study series and 16 overlay instances. Screenshot
+export composites ordered Canvas2D and accelerated canvas layers; browser pixel
+coverage verifies output dimensions and candle pixels from the accelerated layer.
+
+`HEADLESS_CAPABILITIES` is the immutable version-1 runtime capability manifest.
+The entry imports safely when browser globals are absent and does not require the
+package stylesheet. Destroy cancels active chart animations, unsubscribes an
+explicit loader, and rejects late loader callbacks before they mutate state.
+
+## Constructor
+
+```typescript
+<AstroneumChart ref={ref} {...options} />
+```
+
+### `AstroneumOptions`
+
+| Property | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `symbol` | `SymbolInfo` | ✓ | — | Symbol to display on load |
+| `period` | `Period` | ✓ | — | Initial timeframe |
+| `datafeed` | `Datafeed` | ✓ | — | Data source implementation |
+| `theme` | `'light' \| 'dark'` | | `getSystemTheme()` | UI theme. Omit to auto-detect OS color scheme. |
+| `locale` | `string` | | `'en-US'` | UI locale key |
+| `timezone` | `string` | | `'Asia/Shanghai'` | IANA timezone identifier for the X-axis |
+| `watermark` | `string \| Node` | | Astroneum logo SVG | Watermark rendered in the chart center |
+| `styles` | `DeepPartial<Styles>` | | `{}` | Deep-partial engine style override |
+| `drawingBarVisible` | `boolean` | | `true` | Whether the left-side drawing toolbar is shown |
+| `periods` | `Period[]` | | `[1m,5m,15m,1H,2H,4H,D,W,M,Y]` | Timeframes available in the period bar |
+| `mainIndicators` | `IndicatorDef[]` | | `[{ name: 'EMA', calcParams: [7,25,99] }]` | Indicators overlaid on the main candle pane |
+| `subIndicators` | `string[]` | | `['VOL']` | Indicator names rendered in sub-panes below the chart |
+| `plugins` | `ChartPlugin[]` | | `[]` | Plugins mounted with chart lifecycle hooks (`onInit` / disposer) |
+
+---
+
+## Instance methods
+
+### `setTheme(theme)`
+```typescript
+setTheme(theme: 'light' | 'dark'): void
+```
+Sets the UI theme. Updates both the `data-theme` attribute and the internal chart styles.
+
+### `getTheme()`
+```typescript
+getTheme(): string
+```
+Returns the current theme name.
+
+### `setStyles(styles)`
+```typescript
+setStyles(styles: DeepPartial<Styles>): void
+```
+Merges the given partial styles into the engine's current style tree.
+
+### `getStyles()`
+```typescript
+getStyles(): Styles
+```
+Returns the full resolved engine style object.
+
+### `setLocale(locale)`
+```typescript
+setLocale(locale: string): void
+```
+Switches the UI and engine locale. The locale key must have been registered with `loadLocales()` (for UI strings) and the engine's `registerLocale()` (for OHLC/indicator labels).
+
+### `getLocale()`
+```typescript
+getLocale(): string
+```
+Returns the current locale key.
+
+### `setTimezone(timezone)`
+```typescript
+setTimezone(timezone: string): void
+```
+Changes the IANA timezone used for the X-axis date labels.
+
+### `getTimezone()`
+```typescript
+getTimezone(): string
+```
+Returns the current timezone.
+
+### `setSymbol(symbol)`
+```typescript
+setSymbol(symbol: SymbolInfo): void
+```
+Loads a new symbol. Triggers a full data reload via the datafeed.
+
+### `getSymbol()`
+```typescript
+getSymbol(): SymbolInfo
+```
+Returns the currently active `SymbolInfo`.
+
+### `setPeriod(period)`
+```typescript
+setPeriod(period: Period): void
+```
+Switches the active timeframe. Triggers a full data reload.
+
+### `getPeriod()`
+```typescript
+getPeriod(): Period
+```
+Returns the currently active `Period`.
+
+### `serializeState()` / `loadState()`
+
+```typescript
+serializeState(): SerializedChartState
+loadState(state: SerializedChartState): void
+```
+
+Capture and restore the chart's user-visible state — theme, locale,
+timezone, symbol, period, styles, indicators, and drawing overlays —
+as a JSON-safe object.
+Indicator entries retain their calculation parameters, visibility, and styles.
+
+```ts
+// save
+localStorage.setItem('chart-state', JSON.stringify(chartRef.current!.serializeState()))
+
+// restore on mount
+const saved = localStorage.getItem('chart-state')
+if (saved) chartRef.current!.loadState(JSON.parse(saved))
+```
+
+`loadState()` is a best-effort restore: missing or unknown indicator /
+overlay names are silently skipped (matching the engine's behaviour for
+unregistered names). The `version` field lets the format evolve without
+breaking older payloads; payloads from a newer format than the current
+library understands are ignored.
+
+---
+
+## Accessibility
+
+`<AstroneumChart>` accepts an `accessible` prop (default `false`) that
+opts the canvas into screen-reader and keyboard-focus support without
+changing visuals:
+
+- The container gets `tabindex=0`, `role="img"`, and an `aria-label`
+  (defaults to `"<ticker> <period text> chart"`; override via the
+  `ariaLabel` prop).
+- A visually-hidden `aria-live="polite"` region announces OHLCV on
+  crosshair changes, throttled to ~10 updates / second to avoid
+  flooding screen-reader queues.
+
+```tsx
+<AstroneumChart
+  symbol={{ ticker: 'BTC-USD' }}
+  period={{ multiplier: 1, timespan: 'minute', text: '1m' }}
+  datafeed={datafeed}
+  accessible
+  ariaLabel='Bitcoin / USD 1-minute candles'
+/>
+```
+
+For users who require a high-contrast UI, set `theme="high-contrast"`
+(or call `setTheme('high-contrast')`). The bundled theme uses a
+black background, white candles/grid, and yellow accents with strong
+focus rings.
+
+---
+
+## Lazy locales
+
+Only `en-US` is bundled with the main entry. Load any other built-in
+locale on demand:
+
+```ts
+import { loadLocale, BUILTIN_LOCALES } from '@tony01/astroneum'
+
+await loadLocale('ja-JP')
+chartRef.current?.setLocale('ja-JP')
+
+console.log(BUILTIN_LOCALES) // ['en-US', 'zh-CN', 'ja-JP', ...]
+```
+
+`loadLocale(key)` resolves with the dictionary on success, or `null`
+when `key` is not a built-in locale. Concurrent calls for the same
+locale are de-duplicated. To register a fully custom locale,
+keep using `loadLocales(key, dictionary)`.
+
+---
+
+## Subpath entry points
+
+Optional features are reachable through dedicated subpath imports so a
+consumer can pull in just what they need.
+
+| Subpath | Exports |
+| --- | --- |
+| `@tony01/astroneum/headless` | `createChart`, `destroyChart`, `registerBuiltInExtensions`, `HEADLESS_CAPABILITIES`, registration/query helpers, branded bar types, engine host types |
+| `@tony01/astroneum/replay` | `BarReplay`, types `BarReplayOptions`, `BarReplayState` |
+| `@tony01/astroneum/multichart` | `MultiChartLayout`, types `MultiChartCount`, `MultiChartSlot`, `MultiChartLayoutOptions` |
+| `@tony01/astroneum/watchlist` | `WatchlistManager`, types `Watchlist`, `WatchSymbol`, `WatchlistColumn`, `WatchlistSort`, `WatchlistSortDirection` |
+| `@tony01/astroneum/portfolio` | `PortfolioTracker`, types `Position`, `PositionSide`, `PnLResult` |
+| `@tony01/astroneum/alerts` | `AlertManager`, full alert type surface |
+| `@tony01/astroneum/script` | `ScriptEngine`, types `CompiledIndicator`, `StudyOptions`, `PlotOptions`, `InputOptions` |
+| `@tony01/astroneum/datafeeds/polygon` | `DefaultDatafeed`, `WebSocketDatafeed`, `WebSocketDatafeedOptions` |
+| `@tony01/astroneum/datafeeds/crypto` | `createStandardCryptoDatafeed`, `StandardCryptoDatafeed`, `STANDARD_CRYPTO_SYMBOLS`, `DATAFEED_ERROR_EVENT`, `BinanceAdapter`, `BitgetAdapter`, `OkxAdapter`, plus types |
+
+All listed symbols also re-export from the root `@tony01/astroneum` entry today,
+but the root re-exports for these modules will be removed in **v1.0**
+(see the [Roadmap](../README.md#v10--stability)). Migrate to the subpath
+import to be forward-compatible.
+
+`MultiChartLayout` persists the grid, active pane, and complete serialized state
+for each pane when given a `storageKey`; an explicit `count` takes precedence
+over a stored grid size.
+
+```ts
+// recommended — forward-compatible with v1.0
+import { BarReplay } from '@tony01/astroneum/replay'
+import { createStandardCryptoDatafeed } from '@tony01/astroneum/datafeeds/crypto'
+
+// legacy — works today, will be removed in v1.0
+import { BarReplay, createStandardCryptoDatafeed } from '@tony01/astroneum'
+```
+
+---
+
+## Exported utilities
+
+### Brand cast helpers
+
+```typescript
+import { asPrice, asVolume, asTimestamp } from '@tony01/astroneum'
+
+const p: Price = asPrice(100.50)
+const v: Volume = asVolume(1_250_000)
+const t: Timestamp = asTimestamp(Date.now())
+```
+
+These are type-safe cast functions. They assert that a plain `number` belongs to a specific financial domain without any runtime overhead.
+
+### `rafCoalesce`
+
+```typescript
+import { rafCoalesce } from '@tony01/astroneum'
+
+const dispatch = rafCoalesce((tick: CandleData) => chart.updateBar(tick))
+webSocket.onmessage = e => dispatch(parse(e.data)) // safe to call 100×/s
+```
+
+Returns a dispatcher that schedules `fn` on the next `requestAnimationFrame`, coalescing rapid calls so only the **last** value is delivered per frame. Use this when you only care about the latest state (e.g. price display). For financial accuracy across bursts, use `rafMergeTick` instead.
+
+### `rafMergeTick`
+
+```typescript
+import { rafMergeTick } from '@tony01/astroneum'
+
+const cancel = rafMergeTick(incomingTick, (merged) => {
+  chart.updateBar(merged)
+})
+// Call cancel() to stop
+```
+
+OHLCV-aware frame coalescer for WebSocket burst handling. Merges all ticks arriving within the same `requestAnimationFrame` frame into one financially accurate bar:
+- `open` = first tick
+- `high` = max across ticks
+- `low` = min across ticks
+- `close` = last tick
+- `volume` = sum across ticks
+
+### `EventBus`
+
+```typescript
+import { EventBus } from '@tony01/astroneum'
+import type { ChartEventMap } from '@tony01/astroneum'
+
+const bus = new EventBus<ChartEventMap>()
+
+bus.on('tick', (candle) => console.log(candle.close))
+bus.emit('tick', bar)
+bus.off('tick', handler)
+```
+
+Zero-dependency, type-safe synchronous event bus.
+
+### `TickAnimator`
+
+```typescript
+import { TickAnimator } from '@tony01/astroneum'
+import type { TickAnimatorOptions } from '@tony01/astroneum'
+
+const opts: TickAnimatorOptions = { duration: 120 } // ms
+const animator = new TickAnimator(opts, (frame) => {
+  chart.updateLastBar(frame)
+})
+
+animator.push(newTick)
+animator.cancel()
+```
+
+Smooth ease-out cubic interpolation of the last bar's `close`/`high`/`low` over `duration` ms (default 120 ms). Zero allocations in the rAF loop.
+
+### `RingBuffer`
+
+```typescript
+import { RingBuffer } from '@tony01/astroneum'
+
+const buf = new RingBuffer<CandleData>(1000) // fixed capacity
+buf.push(candle)
+const arr = buf.toArray() // oldest → newest
+```
+
+Fixed-capacity O(1) circular buffer designed for streaming time-series data.
+
+---
+
+## Exported types
+
+```typescript
+import type {
+  // Core
+  AstroneumOptions,
+  AstroneumHandle,
+  SerializedChartState,
+  Datafeed,
+  SymbolInfo,
+  Period,
+  CandleData,
+  DatafeedSubscribeCallback,
+  QuoteSnapshot,
+
+  // Branded primitives
+  Price,
+  Volume,
+  Timestamp,
+
+  // Indicator
+  IndicatorDef,
+  IndicatorPlugin,
+  ChartPlugin,
+  ChartPluginContext,
+
+  // Events
+  ChartEventMap,
+
+  // Coordinate space
+  Viewport,
+
+  // Engine types
+  Styles,
+  DeepPartial,
+  Coordinate,
+  Bounding,
+
+  // Utility types
+  TickAnimatorOptions,
+  TimeframeText,
+  Timespan,
+
+  // MultiChartLayout
+  MultiChartCount,
+  MultiChartSlot,
+  MultiChartLayoutOptions,
+
+  // BarReplay
+  BarReplayOptions,
+  BarReplayState,
+
+  // Drawing templates
+  OverlayStylePreset,
+  DrawingStyleTemplate,
+
+  // AlertManager
+  Alert,
+  AlertCondition,
+  AlertStatus,
+  AlertFrequency,
+  AlertCreate,
+  AlertCheckInput,
+  AlertTriggeredCallback,
+
+  // Format helpers
+  FormatPriceOptions,
+  DateFormatStyle,
+  TimeFormatStyle,
+
+  // ScriptEngine
+  CompiledIndicator,
+  StudyOptions,
+  PlotOptions,
+  InputOptions,
+
+  // WatchlistManager
+  Watchlist,
+  WatchSymbol,
+  WatchlistColumn,
+  WatchlistSort,
+  WatchlistSortDirection,
+
+  // PortfolioTracker
+  Position,
+  PositionSide,
+  PnLResult,
+
+  // PerformanceMode
+  PerformanceBar,
+} from '@tony01/astroneum'
+```
+
+### `Datafeed.getQuotes` and `QuoteSnapshot`
+
+`getQuotes` is optional. Watchlist consumers call it with resolved `SymbolInfo` records and keep displaying `—` when a datafeed does not provide snapshots.
+
+```typescript
+interface Datafeed {
+  getQuotes?(symbols: SymbolInfo[]): Promise<QuoteSnapshot[]>
+}
+
+interface QuoteSnapshot {
+  ticker: string
+  last: Price
+  change?: number
+  changePercent?: number
+  volume?: Volume
+  open?: Price
+  high?: Price
+  low?: Price
+  timestamp?: Timestamp
+}
+```
+
+### `WatchlistManager`
+
+List contents and configuration persist to `localStorage`. Quote fields are runtime-only and deliberately excluded from persistence.
+
+```typescript
+manager.addSymbolFromInfo(listId, symbol)
+manager.moveSymbol(fromListId, toListId, ticker, toIndex?)
+manager.setSort(listId, column, direction?)
+manager.setColumns(listId, columns)
+manager.setColor(listId, color)
+manager.updateQuotes(snapshots)
+```
+
+### `IndicatorDef`
+
+```typescript
+interface IndicatorDef {
+  /** Registered indicator name, e.g. 'EMA', 'MA', 'RSI' */
+  name: string
+  /** Calculation parameters passed to the indicator engine */
+  calcParams?: number[]
+}
+```
+
+### `IndicatorPlugin<TOutput>`
+
+```typescript
+interface IndicatorPlugin<TOutput> {
+  name: string
+  shortName?: string
+  calcParams?: number[]
+  calc(data: CandleData[], params: number[]): TOutput[]
+  render2D?(ctx: CanvasRenderingContext2D, output: TOutput[], viewport: Viewport): void
+  renderGL?(gl: WebGL2RenderingContext, output: TOutput[], viewport: Viewport, vbo: WebGLBuffer): void
+}
+```
+
+Implement this interface to register a custom typed indicator.
+Use `render2D` for lightweight overlays (< 10k points) and `renderGL` for high-density or GPU-accelerated rendering.
+When `renderGL` is present, Astroneum executes it on a dedicated WebGL2 layer and reuses a per-indicator `vbo`.
+If WebGL2 is unavailable, `render2D` is used as fallback when available.
+
+### `registerIndicatorPlugin(plugin)`
+
+```typescript
+registerIndicatorPlugin<TOutput>(plugin: IndicatorPlugin<TOutput>): void
+```
+
+Adapts `IndicatorPlugin` to the engine `IndicatorTemplate` format and registers it.
+
+### `registerIndicatorPlugins(plugins)`
+
+```typescript
+registerIndicatorPlugins(plugins: IndicatorPlugin<unknown>[]): void
+```
+
+Batch helper for registering multiple indicator plugins.
+
+### `createIndicatorTemplateFromPlugin(plugin)`
+
+```typescript
+createIndicatorTemplateFromPlugin<TOutput>(plugin: IndicatorPlugin<TOutput>): IndicatorTemplate
+```
+
+Returns the converted engine template without registering it. Useful when you want manual control over registration.
+
+### `ChartPlugin`
+
+```typescript
+interface ChartPlugin {
+  name?: string
+  indicators?: IndicatorPlugin<unknown>[]
+  onInit?: (context: ChartPluginContext) => void | (() => void)
+}
+```
+
+`indicators` are registered before chart indicator creation begins. `onInit` runs once after chart initialization and may return a disposer called during chart teardown.
+
+### `ChartPluginContext`
+
+```typescript
+interface ChartPluginContext {
+  chart: Chart
+  registerIndicatorPlugin: (plugin: IndicatorPlugin<unknown>) => void
+  registerIndicatorPlugins: (plugins: IndicatorPlugin<unknown>[]) => void
+}
+```
+
+### `ChartEventMap`
+
+```typescript
+interface ChartEventMap {
+  'symbol-change': SymbolInfo
+  'period-change': Period
+  'crosshair-move': Coordinate | null
+  'zoom': { scale: number; anchor: ZoomAnchor }
+  'data-load': { type: 'init' | 'forward' | 'backward'; count: number }
+  'tick': CandleData
+  'drawing-start': string
+  'drawing-end': string
+  'theme-change': string
+}
+```
+
+### `Viewport`
+
+```typescript
+interface Viewport {
+  priceMin: Price
+  priceMax: Price
+  timeMin: Timestamp
+  timeMax: Timestamp
+  resolution: readonly [width: number, height: number]
+}
+```
+
+Represents the currently visible region of the chart canvas. Used for coordinate-space transforms in custom `IndicatorPlugin` renderers.
+
+---
+
+## Additional exports
+
+| Export | Description |
+|---|---|
+| `DefaultDatafeed` | Polygon.io REST + WebSocket datafeed |
+| `MultiChartLayout` | Multi-chart layout manager |
+| `BarReplay` | Historical bar replay engine |
+| `DrawingTemplates` | Save/load drawing style templates |
+| `AlertManager` | Price alert creation and monitoring |
+| `ScriptEngine` | Pine-like indicator scripting sandbox (`compile()` auto-registers indicators) |
+| `registerIndicator` | Register a raw engine `IndicatorTemplate` |
+| `getSupportedIndicators` | List all registered indicator names |
+| `registerOverlay` | Register a raw engine `OverlayTemplate` |
+| `getSupportedOverlays` | List all registered overlay names |
+| `registerXAxis` / `registerYAxis` | Register custom axis templates |
+| `registerIndicatorPlugin` | Register a typed `IndicatorPlugin` via adapter |
+| `registerIndicatorPlugins` | Batch register typed indicator plugins |
+| `createIndicatorTemplateFromPlugin` | Convert `IndicatorPlugin` to engine template |
+| `WatchlistManager` | Symbol watchlist with live prices |
+| `PortfolioTracker` | Position tracking and P&L calculation |
+| `PerformanceMode` | Reduced-render performance optimization |
+| `loadLocales` | Register UI locale strings |
+| `formatPrice` | Format a price number using symbol precision |
+| `formatVolume` | Format a volume number |
+| `formatPercent` | Format a percentage value |
+| `formatDate` / `formatTime` / `formatDateTime` | Date/time formatting helpers |
+| `formatDuration` | Format a duration in milliseconds as human-readable text |
+| `formatPeriod` | Format a `Period` as a human-readable string (e.g. `'1H'`) |
+| `detectPricePrecision` | Auto-detect decimal precision from price data |