@christtrade/depth 0.19.0 → 0.20.0

package/README.md

@@ -1,25 +1,17 @@
 <h1>ChristTrade Depth</h1>
 
-A complete trading chart for React. Canvas-rendered, plugin-scriptable, and
-agnostic about where its data comes from.
+A trading chart for React: canvas rendering, a plugin and scripting runtime,
+a strategy backtester, and a local L3 matching engine. It's the chart behind
+[ChristTrade](https://christtrade.com).
 
-Depth is the chart that powers [ChristTrade](https://christtrade.com). It is not
-a plotting primitive you assemble a UI around - it ships the whole surface:
-toolbar, symbol switcher, drawing tools, indicators, order ticket, playback,
-settings. You give it a data adapter and a container with a height, and you have
-a trading terminal.
+Depth ships the whole terminal, not drawing primitives: toolbar, symbol
+switcher, drawing tools, indicators, order ticket, playback and settings. You
+pass it an `IDataAdapter` and a container with a height.
 
-## What it is, and what it isn't
-
-`depth.mjs` is about 1.2 MB minified. That's the honest number, and it's the
-right one to compare against a TradingView widget rather than against a
-lightweight plotting library. If you want 45 KB that draws a line, Depth is the
-wrong tool and [Lightweight Charts](https://github.com/tradingview/lightweight-charts)
-is a good one. If you want the thing your users already know how to use, keep
-reading.
-
-React 18 or 19 is the only runtime dependency you install. Everything else -
-Radix, Lucide, Luxon, the workers, the fonts - is compiled in.
+`depth.mjs` is ~1.2 MB minified. React 18 or 19 is the only peer dependency;
+Radix, Lucide, Luxon, the workers and the fonts are bundled. If you need a 45 KB
+line plotter, use [Lightweight Charts](https://github.com/tradingview/lightweight-charts)
+instead.
 
 ## Install
 
@@ -30,8 +22,8 @@ npm i react react-dom   # if you don't already have them
 
 ## Quick start
 
-`SimulatedMarketAdapter` generates synthetic market data, so this runs with no
-data source wired up:
+`SimulatedMarketAdapter` generates synthetic data, so this runs without a data
+source:
 
 ```jsx
 import { useDepthChart, SimulatedMarketAdapter } from '@christtrade/depth';
@@ -48,110 +40,197 @@ export default function MyChart() {
             start: Date.now() - 1000 * 60 * 60 * 24,
             end: Date.now(),
         },
-        // additional options...
     });
 
     return <div style={{ width: '100%', height: '100%' }}>{element}</div>;
 }
 ```
 
-`element` is the chart. `chart` is the controller handle - timeframes, symbols,
-drawings, plugins, serialization. Types ship with the package, so your editor
-has the full API.
-
-### Four things that trip people up
-
-- **Give the chart a real height.** It fills its container. A container with
-  `height: auto` collapses it to nothing.
-- **Dark mode is a `dark` class** on any ancestor, or on `<html>`. Without it
-  you get the light theme.
-- **`depth.css` includes a CSS reset** (Tailwind preflight), which is what you
-  want in a fresh app. If it fights your existing styles, import
-  `@christtrade/depth/depth.nopreflight.css` instead.
-- **Workers are embedded as blob URLs.** Under a strict CSP you need
-  `worker-src blob:`.
-
-If you started from `npm create vite`, add `class="dark"` to `<html>` and drop
-`import './index.css'` from `main.jsx` - the template stylesheet centres and pads
-`#root`, which fights the chart's layout.
-
-## What's in the box
-
-- **12 chart types** - candles, hollow candles, Heikin-Ashi, bars, line, area,
-  step, baseline, Renko, Kagi, line break, footprint. Plugins can register more.
-- **~50 drawing tools** - trendlines, channels, Fibonacci, Gann, patterns,
-  position tools, measurements, annotations.
-- **21 built-in indicators**, each written against the same plugin API third
-  parties use. There is no privileged internal path.
-- **Multi-pane and multi-chart layouts**, with synced crosshairs.
-- **Playback** - scrub, step, and replay historical sessions bar by bar.
-- **Trading** - order ticket, quick-trade buttons, position and P&L rendering,
+`element` is the chart. `chart` is the controller: timeframes, symbols,
+drawings, plugins, `serialize()` / `restore()`. Types ship with the package.
+
+### Setup gotchas
+
+- The chart fills its container. `height: auto` collapses it to 0.
+- Dark mode is a `dark` class on any ancestor or on `<html>`. Without it you
+  get the light theme.
+- `depth.css` includes Tailwind preflight (a CSS reset). If it fights your
+  styles, import `@christtrade/depth/depth.nopreflight.css` instead.
+- Workers are embedded as blob URLs, so a strict CSP needs `worker-src blob:`.
+- From `npm create vite`: add `class="dark"` to `<html>` and drop
+  `import './index.css'` from `main.jsx`. The template centres and pads
+  `#root`.
+
+## Features
+
+- Chart types: candles, hollow candles, Heikin-Ashi, bars, line, area, step,
+  baseline, and footprint on L3 data. Plugins can register more.
+- Drawing tools: trend line, ray, extended line, horizontal and vertical
+  lines and rays, cross line, info line, trend angle, parallel channel, Fib
+  retracement, rectangle, triangle, text, long/short position and fixed
+  volume profile.
+- 21 built-in indicators, written against the same plugin API third parties
+  get.
+- Multi-pane and multi-chart layouts with synced crosshairs.
+- Playback: scrub, step and replay sessions bar by bar.
+- Trading: order ticket, quick-trade buttons, positions and P&L on the chart,
   and a local L3 matching engine with real fee schedules for simulated fills.
-- **Sessions** - trading hours, holidays, subsessions, correct gaps.
-- **Serialization** - `chart.serialize()` / `chart.restore()` round-trips
-  layouts, drawings, plugins, and preferences.
+- Sessions: trading hours, holidays and subsessions. Closed time is cut out
+  of the x axis.
+- Themes: built-in dark and light themes, or register your own.
 
-## Data
+## Architecture
 
-A data source is an `IDataAdapter`. Implement it and pass it in:
+### Data
 
-```ts
-import type { IDataAdapter } from '@christtrade/depth';
-```
+An `IDataAdapter` implements `resolveSymbol`, `searchSymbols` and
+`fetchBars`, plus optional `subscribeRealtime` and `getCapabilities`. Each
+adapter declares the data level it serves:
+
+| Level | Data | Also serves |
+| --- | --- | --- |
+| `l3` | MBO events | `tick`, `ohlcv`, `l2` |
+| `tick` | trades | `ohlcv` |
+| `ohlcv` | bars | |
+| `l2` | book snapshots | |
+
+A plugin or feature declares the level it needs, and on a symbol that can't
+serve it, it's refused with a reason instead of breaking. The chunk processors
+(`processOhlcvChunk`, `processTickChunk`, `processL2Chunk`, `processL3Chunk`)
+are exported, so an adapter doesn't reimplement aggregation. Plugins can add
+data sources at runtime with `registerDataSource`, which is how
+bring-your-own-API-key providers work.
+
+The `DataEngine` keeps one store per symbol and pages history in as you pan.
+Every chart on that symbol reads the same store.
+
+### Storage
+
+OHLCV lives in a `BarStore`: six `Float64Array` columns (`time`, `open`,
+`high`, `low`, `close`, `volume`, plus bid/ask once a bar has them), sorted by
+`time`.
+
+- 48 bytes a bar. A `{ time, open, high, low, close, volume }` object is ~176,
+  and each one is something for the GC to walk.
+- Capacity doubles on growth, and the spare room is split between both ends,
+  so append and prepend are amortized O(bars added). Paging history in never
+  copies what's loaded.
+- `lowerBound` / `upperBound` binary search on `time`.
+- When a chart's timeframe is the resolution the data came in at, the chart
+  draws from the engine's store directly. Other timeframes get one
+  aggregated copy.
+
+The column views are replaced when the store grows. Read `bars.close` off the
+store each time, and key caches on `bars.version`, which bumps on every
+mutation.
+
+L3 events are packed into 20 bytes each in a `CompactBuffer` (BigInt64
+timestamp, int32 price, uint32 size, uint24 order id, packed action/side), so
+30M events take ~600 MB instead of ~5 GB as objects.
+
+### Rendering
+
+Four stacked canvases: `background`, `base` (candles, grid, indicators),
+`drawings` and `ui` (crosshair, axis labels, price pills). One rAF loop paints
+only the layers marked dirty, so an idle chart costs close to nothing.
+
+Time is BigInt nanoseconds. `SessionMapper` maps real time to "market time",
+with closed sessions taken out, and the transformer maps that to pixels.
+
+Per frame, drawing is O(visible bars), and lookups by time (status line,
+magnet snap, y-axis autofit) are O(log n) in loaded bars.
+
+### Workers
 
-Depth supports four data levels - OHLCV bars, ticks, L2 book snapshots, and MBO
-(L3) events - and each adapter declares which it serves. Higher levels unlock
-features that need them (footprint, depth-of-market, per-order replay); lower
-levels degrade cleanly rather than breaking. Chunk processors for each level are
-exported so adapter authors don't have to reimplement aggregation.
+- `script.worker`: user scripts and strategies, off the main thread.
+- `slice.worker`: decodes L3 ranges and merges history pages.
+- `heatmap.worker`: builds book snapshots and renders the depth heatmap to an
+  `OffscreenCanvas`.
+- An indicator worker for heavy indicator math.
 
-Plugins can also register data sources at runtime via `registerDataSource`,
-which is how bring-your-own-API-key providers work.
+## Performance
+
+Ryzen 5 7500F, Chrome, 1m bars.
+
+- 1M bars loaded, ~300 on screen: panning holds 240fps. Draw, status line,
+  autofit and snap cost the same as with 20k loaded (see the perf guard
+  below).
+- Heap with 1M bars loaded, in ChristTrade: ~480 MB.
+- Backtest over 2M bars (~4 years of BTC 1m) through the script worker:
+  207-265ms. Stats are running (Welford) and the equity curve is capped, so
+  it holds ~1.1 MB at 2M bars.
+- `processL3Chunk`: ~1.5M MBO events/sec on synthetic data.
+
+### Perf guard
+
+`npm run perf:guard` runs in CI. It bundles the draw, status line, autofit,
+snap and prepend paths with esbuild, times each at 20k and at 1M loaded bars
+with ~300 on screen, drawing to a no-op canvas, and fails if any is 5x slower
+at 1M, or if a `BarStore` paged in to 1M bars takes more than 72 bytes a bar
+including spare capacity:
+
+```
+ok   draw candles   118.0µs -> 85.4µs  0.7x
+ok   status line    0.8µs -> 0.9µs  1.1x
+ok   autofit        2.0µs -> 1.9µs  1.0x
+ok   magnet snap    1.0µs -> 0.9µs  0.9x
+ok   page prepend   0.96ms -> 1.04ms  1.1x
+ok   bytes/bar      66.7 at 1M, spare room included (max 72)
+```
+
+Left column is 20k bars, right is 1M.
 
 ## Plugins
 
-Plugins are declarative JavaScript, written in the built-in script editor on
-[christtrade.com](https://christtrade.com) or shipped as modules. They can add
-indicators, chart types, drawing tools, panels, toolbar items, data sources,
-and render overlays. Heavy computation can be offloaded to WebAssembly.
+Plugins are JavaScript modules, or scripts written in the built-in editor on
+[christtrade.com](https://christtrade.com). They can add indicators, chart
+types, drawing tools, panels, toolbar items, data sources and render overlays,
+and can offload heavy math to WebAssembly.
 
-A plugin declares the capabilities and network origins it needs, and `ctx` hands
-over nothing it did not ask for - so you can show a user what a plugin intends
-before they start it. That is a declaration mechanism, not a sandbox: plugin code
-runs in your page. Read [SECURITY.md](SECURITY.md) before you let other people's
-plugins run in your app.
+A plugin declares the capabilities and network origins it needs, and `ctx`
+only exposes those, so you can show a user what a plugin wants before it
+runs. It isn't a sandbox: plugin code runs in your page. Read
+[SECURITY.md](SECURITY.md) before running other people's plugins.
 
-Full plugin documentation lives at
-[docs.christtrade.com/depth](https://docs.christtrade.com/depth).
+Strategies run in the script worker. `StrategyEngine` does intrabar fills,
+parameter sweeps and walk-forward analysis.
+
+Full docs: [docs.christtrade.com/depth](https://docs.christtrade.com/depth).
+
+## Development
+
+```bash
+npm test              # node:test via tsx
+npm run perf:guard
+npx tsc -p tsconfig.json --noEmit
+npm run dist          # build dist/, smoke test it
+```
+
+CI runs tests, typecheck and the perf guard on Node 20 and 22.
 
 ## Status
 
-Depth is pre-1.0 and versioned accordingly. It runs in production at
-ChristTrade, so it is not experimental - but the public API is still moving, and
-minor versions may break it. **1.0 is the API freeze**, not the point where the
-library becomes usable.
+Pre-1.0. It runs in production at ChristTrade, but the public API still
+moves and minor versions can break it. 1.0 is the API freeze. Breaking changes
+are marked in [CHANGELOG.md](CHANGELOG.md).
 
 ## Contributing
 
-**Issues are welcome.** Bug reports, reproductions, and questions about the API
-all help, and I read them.
+Issues are welcome: bug reports, reproductions, API questions.
 
-**Pull requests are by invitation.** Depth is a single-author library and I
-intend to keep it that way. If you've found something broken, open an issue -
-if a PR is the right way to resolve it, I'll ask. Unsolicited PRs will usually
-be closed with thanks and reopened as issues, which isn't a comment on the code.
+Pull requests are by invitation. Depth is a single-author library. If you
+found something broken, open an issue, and if a PR is the right fix I'll ask
+for one. Unsolicited PRs usually get closed and reopened as issues, which
+isn't a comment on the code.
 
 ## Attribution
 
-Depth draws a small ChristTrade mark in the corner of the chart.
-
-The Apache License doesn't require you to keep it, and I'm not going to pretend
-otherwise - you can remove it and you'll be within your rights. I'm asking you
-not to. The mark is the only thing this library asks in return for being free,
-and it's how people find it.
+Depth draws a small ChristTrade mark in the corner of the chart. Apache-2.0
+doesn't require you to keep it, and you can remove it. I'm asking you not to:
+it's the only thing the library asks for, and it's how people find it.
 
-The name is a separate matter. Apache-2.0 grants no trademark rights (section
-6), so you can fork Depth but you can't ship it as "ChristTrade Depth." See
+The name is separate. Apache-2.0 grants no trademark rights (section 6), so
+you can fork Depth but can't ship it as "ChristTrade Depth". See
 [NOTICE](NOTICE).
 
 ## License