# @finchart

> A composable financial chart engine for TypeScript apps.

Build candles, indicators, drawings, and live charts on a DOM-free core. Add the browser shell and React wrapper when you need them, and inspect draw commands to test chart output without a browser.

## Table of Contents

### Guide

- [Getting Started](/guide/getting-started.md): Stand a candlestick chart up in one file, then add volume, a crosshair and real-time updates. The 60-second example, and what each line buys you.
- [Building your own indicator](/guide/extensions.md): Write an indicator against the same contracts the built-in ones use: derived series, computation nodes that compute once and feed many drawings, and custom draw commands.

### Advanced

- [Turning on the drawing tools](/guide/interaction.md): Mount @finchart/tools, the input stack it sits on, and the keyboard contract — Esc cancels, Delete removes, and why the chart element has to keep focus.
- [Wiring a live feed](/guide/live-feed.md): Wire a WebSocket + REST feed: trades fold into bars, a conflated feed delivers once per frame, a snapshot reconciles by x, and history pages in from the left — with what to do on reconnect.
- [Next.js and React apps](/guide/nextjs.md): Where the client boundary goes in a Next.js app, why deps is read once at mount, what SSR and hydration do and do not touch, and what StrictMode runs twice.
- [Time zones and sessions](/guide/time-zones.md): x is an instant and the axis decides the zone: tell timeTicks the exchange's zone and locale, aggregate on epoch-aligned bars or calendar-day sessions, anchor indicators to the session, and know what the runtime default hides.
- [Testing Charts](/guide/testing.md): Test a chart without a browser: the headless model, feeding synthetic input through routeInput, and asserting on emitted draw commands instead of pixels.
- [Workers](/guide/workers.md): Render a chart in a Web Worker on an OffscreenCanvas: what moves to the worker, how bundlers load it, bridging input, falling back to the main thread, and what live updates cost.
- [Shrinking the bundle](/guide/explicit-wiring.md): What a chart actually costs to download, and how to make it cost less — hand the pieces to createPlotDeps yourself instead of taking the browserDeps preset, and see what drops out, what it saves in bytes, and what stays behind regardless.

### Reference

- [Architecture](/guide/architecture.md): Why @finchart separates chart commands, browser rendering, framework bindings, indicators, and drawing tools.
- [Theming](/guide/theme.md): Every --chart-* CSS variable, the three-tier override > variable > fallback rule, typed theme objects, styling your own extensions, and the dark palette the docs validate against.
- [The Plot Contract: What Survives What](/guide/plot-contract.md): What every Plot method touches and what survives it — the table that says whether a call refits the domain, resets the viewport, or leaves your drawings alone.
- [Glossary](/guide/glossary.md): The vocabulary: plot, pane, series, decoration, plugin, scale, viewport, decimation, and how each differs from the one next to it.

### Examples

- [Examples](/examples.md): Nineteen runnable examples, each one page with the source it actually runs.
- [Candles + volume](/examples/candles-volume.md): The smallest trading screen — one candle pane, one volume pane, a crosshair.
- [Switching chart types — swapSeries changes only the presentation](/examples/chart-types.md): swapSeries changes the presentation and nothing else: candles to line to area and back, with the data, viewport and drawings untouched.
- [Heikin-Ashi — the proof of derived series](/examples/heikin-ashi.md): A derived series computed from the source candles, proving the derive contract on a transform every trader recognizes.
- [Price-axis transforms — Renko, Line Break, Kagi, Point & Figure](/examples/price-axis-transforms.md): Renko, Line Break, Kagi and Point & Figure derived from one ticking candle chart — series whose x is not a clock, sized by the tape's own ATR.
- [Overlay indicators](/examples/overlays.md): Moving averages, BBI and Bollinger bands sharing the price pane and its value axis.
- [Ichimoku](/examples/ichimoku.md): Five lines and a filled cloud from one computation node.
- [Oscillators — RSI · MFI · Stochastic RSI · CCI · %R](/examples/oscillators.md): RSI, MFI and Stochastic RSI sharing one 0–100 pane, Williams %R and CCI in their own — the definition decides each axis.
- [Channels — Keltner · Donchian](/examples/channels.md): Keltner and Donchian channels — bands drawn from the same source the price is.
- [Pivot Points — the period is the consumer's knowledge](/examples/pivots.md): Floor pivots with the period boundary supplied by the consumer, because only the app knows what a session is.
- [Volume Profile — the distribution of what you can see](/examples/volume-profile.md): Volume distributed over the visible price range, recomputed as you pan.
- [Own-pane indicators — MACD · ADX · OBV · CR](/examples/own-panes.md): MACD, ADX, OBV and CR, each making the pane it mounts into and tearing it down on dispose.
- [Real-time ticks](/examples/realtime.md): A live feed: the bar in progress replaced every tick, a new bar opened on the minute.
- [Infinite history — infiniteHistory](/examples/infinite-history.md): Infinite history: pan toward the left edge and older bars arrive page by page — infiniteHistory owns the cursor, the threshold, and the in-flight bookkeeping; in React, useInfiniteHistory holds the data and the loader's place.
- [Drawing tools](/examples/drawing.md): Horizontal lines, trend lines and Fibonacci retracements, drawn by hand and round-tripped through localStorage.
- [Bar-index coordinates](/examples/bar-index.md): Bar-index coordinates against continuous x — the same data with and without the weekend gaps.
- [Two synchronized charts — syncX](/examples/sync-x.md): Two charts linked with syncX, sharing a time window while keeping their own settings.
- [Custom series — volume dots](/examples/custom-series.md): A series the library does not ship, drawn through the custom command with a fallback for surfaces that do not know it.
- [Session shading — a custom draw command with a fallback](/examples/session-shading.md): A gradient band over the after-hours stretch, drawn through a custom command that travels with a flat fallback — the renderer that knows the command is injected; hours are read in UTC from the ticks.
- [Worker rendering](/examples/worker-render.md): Worker rendering: the whole chart runs in a Web Worker on an OffscreenCanvas, and falls back to the main thread when the browser or the worker can't.

### Showcase

- [React trading showcase](/showcase.md): An integrated React trading screen with live synthetic candles, indicators, drawing tools, and synchronized chart panels.

### API Reference

- [The Grammar of Names](/reference/naming.md): The rules the public API names follow — what is a get, a set, an apply, a use, and why each verb was chosen.