From 54cdc7efd51cfe0543b4425953eda5d49de50df7 Mon Sep 17 00:00:00 2001
From: Joe Blau <im@joeblau.com>
Date: Tue, 29 Sep 2026 19:06:19 -0700
Subject: [PATCH] feat: order flow, WebGL2 rendering, and extension points

Adds the order-flow stack and a WebGL2 backend to @bloxwap/chart, and
rebuilds the landing-page playground around them.

Library:
- Extension points: series registry, host panes (stacked/docked) and
  pane primitives drawn behind or above the series.
- Depth: DepthBook model, maintained L2 book manager (snapshot + diff
  deltas, gap resync, retry backoff) and the datafeed depth channel.
- Inline order book: ladder or mirrored layout, docked or overlaid on
  the plot edge, theme-token colors, side-colored labels, bold best
  levels, per-row label culling and an optional true-spread label.
- Liquidity heatmap with multi-stop color ramps; trade tape, trade
  prints, footprint series and delta/CVD indicators; session volume
  profile/TPO pane.
- Visible-range volume profile: round-price rows sized to the screen,
  mirrored up/down volume, POC outline, theme tokens and tweened
  transitions on a frame scheduler.
- WebGL2 renderer (renderer: 'webgl2') with automatic Canvas2D fallback.
- chart.scale.scrollPrice and vertical plot panning while autoscale is
  off; new range-profile and order-book icons.
- Fix: a throwing onBook no longer strands buffered depth deltas.

Playground / landing page:
- Controls move from the header into the left rail; a right-edge
  disclosure picks the volume profile, the full order book, or none.
- Order book from Hyperliquid l2Book (Binance REST is geo-blocked),
  stitching two precisions for full depth plus the bbo feed for the
  true spread; WebGL2 on by default (?renderer=canvas2d to compare).
- Mark, last-close and heatmap overlays are settings toggles, off by
  default.

Test suite: 1849 tests, 100% line/branch/function coverage.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/playground/index.html                    | 489 ++++++++++++-
 packages/chart/assets/icons/order-book.svg    |   1 +
 packages/chart/assets/icons/range-profile.svg |   1 +
 packages/chart/bench/webgl.bench.mjs          |  56 ++
 packages/chart/package.json                   |   2 +-
 packages/chart/src/config.ts                  | 118 ++-
 packages/chart/src/core/chart.ts              | 354 ++++++++-
 packages/chart/src/core/depth.ts              |  22 +
 packages/chart/src/core/footprint.ts          | 130 ++++
 packages/chart/src/core/heatmap.ts            | 195 +++++
 packages/chart/src/core/inline-book.ts        | 120 +++
 packages/chart/src/core/pane.ts               |   3 +-
 packages/chart/src/core/profile.ts            | 270 +++++++
 packages/chart/src/core/trade.ts              |  21 +
 packages/chart/src/datafeed/datafeed-chart.ts | 159 +++-
 packages/chart/src/datafeed/depth-book.ts     | 333 +++++++++
 packages/chart/src/datafeed/index.ts          |  22 +
 .../chart/src/datafeed/trade-aggregation.ts   | 166 +++++
 packages/chart/src/dom.ts                     | 276 ++++++-
 packages/chart/src/drawings/forecasting.ts    |  35 +-
 packages/chart/src/index.ts                   | 126 +++-
 packages/chart/src/indicators/cvd.ts          |  59 ++
 packages/chart/src/indicators/delta.ts        |  65 ++
 packages/chart/src/indicators/index.ts        |   2 +
 packages/chart/src/preset-theme.ts            |   5 +-
 packages/chart/src/presets.ts                 |  15 +-
 packages/chart/src/render/gl/backend.ts       | 226 ++++++
 packages/chart/src/render/gl/candles.ts       |  67 ++
 packages/chart/src/render/heatmap.ts          | 458 ++++++++++++
 packages/chart/src/render/inline-book.ts      | 454 ++++++++++++
 packages/chart/src/render/primitive.ts        |  55 ++
 packages/chart/src/render/range-profile.ts    | 327 +++++++++
 packages/chart/src/render/renderer.ts         | 118 ++-
 packages/chart/src/render/session-profile.ts  | 377 ++++++++++
 packages/chart/src/render/trade-prints.ts     | 132 ++++
 packages/chart/src/series/direction.ts        |   4 +-
 packages/chart/src/series/footprint.ts        | 191 +++++
 packages/chart/src/series/heikin-ashi.ts      |   3 +-
 packages/chart/src/series/index.ts            |  24 +-
 packages/chart/src/series/registry.ts         |  72 ++
 packages/chart/src/ui/controller.ts           |  20 +-
 packages/chart/src/ui/header.ts               |   4 +-
 packages/chart/src/ui/icons.ts                |   2 +
 packages/chart/src/ui/index.ts                |   2 +-
 packages/chart/test/chart-header.test.ts      |  14 +
 packages/chart/test/context-menu-core.test.ts |  28 +-
 packages/chart/test/controller.test.ts        |  20 +
 packages/chart/test/depth-book.test.ts        | 685 ++++++++++++++++++
 packages/chart/test/dom.test.ts               |  78 +-
 packages/chart/test/drawings.test.ts          |  15 +-
 packages/chart/test/extension-points.test.ts  | 237 ++++++
 packages/chart/test/footprint.test.ts         | 385 ++++++++++
 .../chart/test/heatmap-customization.test.ts  | 181 +++++
 packages/chart/test/heatmap.test.ts           | 447 ++++++++++++
 packages/chart/test/inline-book.test.ts       | 537 ++++++++++++++
 packages/chart/test/range-profile.test.ts     | 303 ++++++++
 packages/chart/test/session-profile.test.ts   | 394 ++++++++++
 packages/chart/test/settings-polish.test.ts   |   4 +-
 packages/chart/test/trades.test.ts            | 347 +++++++++
 packages/chart/test/webgl.test.ts             | 429 +++++++++++
 60 files changed, 9570 insertions(+), 115 deletions(-)
 create mode 100644 packages/chart/assets/icons/order-book.svg
 create mode 100644 packages/chart/assets/icons/range-profile.svg
 create mode 100644 packages/chart/bench/webgl.bench.mjs
 create mode 100644 packages/chart/src/core/depth.ts
 create mode 100644 packages/chart/src/core/footprint.ts
 create mode 100644 packages/chart/src/core/heatmap.ts
 create mode 100644 packages/chart/src/core/inline-book.ts
 create mode 100644 packages/chart/src/core/profile.ts
 create mode 100644 packages/chart/src/core/trade.ts
 create mode 100644 packages/chart/src/datafeed/depth-book.ts
 create mode 100644 packages/chart/src/datafeed/trade-aggregation.ts
 create mode 100644 packages/chart/src/indicators/cvd.ts
 create mode 100644 packages/chart/src/indicators/delta.ts
 create mode 100644 packages/chart/src/render/gl/backend.ts
 create mode 100644 packages/chart/src/render/gl/candles.ts
 create mode 100644 packages/chart/src/render/heatmap.ts
 create mode 100644 packages/chart/src/render/inline-book.ts
 create mode 100644 packages/chart/src/render/primitive.ts
 create mode 100644 packages/chart/src/render/range-profile.ts
 create mode 100644 packages/chart/src/render/session-profile.ts
 create mode 100644 packages/chart/src/render/trade-prints.ts
 create mode 100644 packages/chart/src/series/footprint.ts
 create mode 100644 packages/chart/src/series/registry.ts
 create mode 100644 packages/chart/test/depth-book.test.ts
 create mode 100644 packages/chart/test/extension-points.test.ts
 create mode 100644 packages/chart/test/footprint.test.ts
 create mode 100644 packages/chart/test/heatmap-customization.test.ts
 create mode 100644 packages/chart/test/heatmap.test.ts
 create mode 100644 packages/chart/test/inline-book.test.ts
 create mode 100644 packages/chart/test/range-profile.test.ts
 create mode 100644 packages/chart/test/session-profile.test.ts
 create mode 100644 packages/chart/test/trades.test.ts
 create mode 100644 packages/chart/test/webgl.test.ts

diff --git a/apps/playground/index.html b/apps/playground/index.html
index 11275b0..30f7e05 100644
--- a/apps/playground/index.html
+++ b/apps/playground/index.html
@@ -17,6 +17,11 @@
     #main { flex: 1; min-width: 0; display: flex; flex-direction: column; margin: 6px 6px 6px 0; border-radius: 12px; overflow: hidden; background: #171717; }
     body.light #main { background: #ffffff; }
     #header { flex: none; min-width: 0; }
+    /* Wide: the control rail carries the header's controls, so the plot starts at the top of the card. */
+    @media (min-width: 600px) { #header { display: none; } }
+    /* Rail text toggles (timeframe, Auto / % / Log) fit the 36px buttons; a pressed toggle takes the accent. */
+    #ctrl-rail .cts-btn-label { font-size: 11px; }
+    #ctrl-rail .rail-scale.cts-on { color: var(--cts-accent); background: var(--cts-accent-soft); }
     #stage { position: relative; flex: 1; min-height: 0; }
     #tools { flex: none; width: 52px; overflow: hidden; transition: width 240ms cubic-bezier(0.2, 0.8, 0.2, 1); }
     #tools.collapsed { width: 0; }
@@ -26,7 +31,7 @@
     canvas { display: block; width: 100%; height: 100%; touch-action: none; }
 
     /* bloxwap.pro chrome on dark for the rails, menus and dialogs: zero-stroke surfaces, #262626 hover fill, #00ff3f accent.
-       The header and the on-chart A / % / L strip take BLOXWAP_HEADER_THEME instead, which clears itself on light. */
+       The header takes BLOXWAP_HEADER_THEME instead, which clears itself on light. */
     body:not(.light) .cts-theme:not(.cts-light) {
       --cts-edge: transparent; --cts-panel-raised: #262626; --cts-accent: #00ff3f;
       --cts-accent-soft: #262626; --cts-on-accent: #0a0a0a;
@@ -70,12 +75,15 @@
   </div>
 
   <script type="module">
-    import { defineConfig, presetChartTheme } from '../dist/index.js';
-    import { createDatafeedChart, bucketStartMs } from '../dist/datafeed/index.js';
+    import {
+      defineConfig, presetChartTheme, createFootprintSeries, createDeltaIndicator, createCvdIndicator, attachRangeProfile, attachInlineBook,
+    } from '../dist/index.js';
+    import { createDatafeedChart, datafeedFootprintSource, bucketStartMs } from '../dist/datafeed/index.js';
     import {
       createDrawingToolbar, createChartSettings, createIndicatorsDialog, createThemeControl, createFrameScheduler,
-      createChartHeader, createScaleButtons, DEFAULT_TIMEFRAMES, attachScrollableRail, el, iconButton, setButtonIcon,
-      menuItem, menuLabel, menuSeparator, startCountdownTicker,
+      createChartHeader, DEFAULT_TIMEFRAMES, attachScrollableRail, el, iconButton, setButtonIcon,
+      menuItem, menuLabel, menuSeparator, startCountdownTicker, labelButton, setButtonLabel, ICONS,
+      DEFAULT_CHART_TYPES, CHART_TYPE_LABELS, SCALE_TOGGLES, toggleScale, scaleToggleState,
     } from '../dist/ui/index.js';
     import { BLOXWAP_HEADER_THEME } from '../dist/ui/index.js';
 
@@ -137,14 +145,146 @@
       return walkFor(symbol, intervalMs).filter((c) => c.time * 1000 >= fromMs && c.time * 1000 <= toMs);
     }
 
+    // ---------------- depth books: Hyperliquid for BTC, a synthetic book for the walks ----------------
+    // Hyperliquid pushes whole l2Book snapshots, so each one becomes a sequenced diff against the previous
+    // (size 0 removes a level). A snapshot read returns the latest pushed book, so the diffs line up with it.
+    // A subscription returns at most 20 levels a side, so the book stitches two precisions: fine levels sized to
+    // the timeframe (nSigFigs 4/3 ≈ $10/$100 at BTC prices) near the price, then coarse buckets (one step coarser)
+    // out to ±20 of those, for depth across the whole visible range.
+    let hlBook = null, hlSeq = 0, hlFigs = 4;
+    /** The latest raw book per precision, tagged with its nSigFigs. */
+    let hlFine = null, hlCoarse = null;
+    /** Hyperliquid's full-precision best bid/offer (the `bbo` feed): the true spread under aggregated levels. */
+    let hlBbo = null;
+    const hlFigsFor = (intervalMs) => (intervalMs <= 300_000 ? 4 : 3);
+    const hlSide = (levels) => levels.map((l) => [+l.px, +l.sz]);
+    /** Bucket size of `figs` significant figures at `price` (e.g. 3 → $100 at $83k). */
+    const hlStep = (price, figs) => 10 ** (Math.floor(Math.log10(price)) + 1 - figs);
+    function hlRaw(levels, figs, time) {
+      return { figs, bids: hlSide(levels[0]), asks: hlSide(levels[1]), time };
+    }
+    /**
+     * Fine levels, then each coarse bucket beyond them. Buckets round bids down ([px, px + step)) and asks up
+     * ((px - step, px]); the bucket straddling the fine edge keeps only the size the fine levels don't cover.
+     */
+    function hlStitch(fine, coarse) {
+      if (coarse === null || coarse.figs !== fine.figs - 1) return { figs: fine.figs, bids: fine.bids, asks: fine.asks, time: fine.time };
+      const price = fine.bids[0]?.[0] ?? fine.asks[0]?.[0];
+      const step = price > 0 ? hlStep(price, coarse.figs) : 0;
+      const side = (levels, buckets, bid) => {
+        if (levels.length === 0 || step === 0) return levels;
+        const edge = levels.at(-1)[0], out = levels.slice();
+        for (const [px, size] of buckets) {
+          if (bid ? px >= edge : px <= edge) continue; // wholly inside the fine range
+          const inside = levels.reduce((sum, [p, s]) => ((bid ? p >= px && p < px + step : p > px - step && p <= px) ? sum + s : sum), 0);
+          const rest = +(size - inside).toFixed(8);
+          if (rest > 0) out.push([px, rest]);
+        }
+        return out;
+      };
+      return { figs: fine.figs, bids: side(fine.bids, coarse.bids, true), asks: side(fine.asks, coarse.asks, false), time: Math.max(fine.time, coarse.time) };
+    }
+    async function fetchHyperliquidDepth({ signal }) {
+      const figs = hlFigs = hlFigsFor(datafeed.intervalMs ?? 900_000);
+      if (hlBook === null || hlBook.figs !== figs) {
+        const read = async (nSigFigs) => {
+          const res = await fetch('https://api.hyperliquid.xyz/info', {
+            method: 'POST', headers: { 'content-type': 'application/json' }, signal,
+            body: JSON.stringify({ type: 'l2Book', coin: COIN, nSigFigs }),
+          });
+          if (!res.ok) throw new Error(`Hyperliquid l2Book failed: ${res.status}`);
+          const { levels, time } = await res.json();
+          return hlRaw(levels, nSigFigs, time);
+        };
+        const [fine, coarse] = await Promise.all([read(figs), read(figs - 1)]);
+        // A push at this precision during the read is newer: keep it.
+        if (hlBook === null || hlBook.figs !== figs) {
+          hlFine = fine;
+          hlCoarse = coarse;
+          hlBook = hlStitch(fine, coarse);
+        }
+      }
+      return { lastUpdateId: hlSeq, bids: hlBook.bids, asks: hlBook.asks, time: hlBook.time };
+    }
+    function hlDiff(prev, next) {
+      const keep = new Set(next.map(([p]) => p));
+      return next.concat(prev.filter(([p]) => !keep.has(p)).map(([p]) => [p, 0]));
+    }
+    /** Pushes arrive untagged: a book whose every price sits on the coarse step is the coarse subscription's. */
+    function onHyperliquidBook(data, figs) {
+      if (figs !== hlFigs) return; // a superseded precision's push
+      const levels = data.levels[0].concat(data.levels[1]);
+      if (levels.length === 0) return;
+      const coarseStep = hlStep(+levels[0].px, figs - 1);
+      const coarse = levels.every((l) => Math.abs(+l.px / coarseStep - Math.round(+l.px / coarseStep)) < 1e-9);
+      const raw = hlRaw(data.levels, coarse ? figs - 1 : figs, data.time);
+      if (coarse) hlCoarse = raw;
+      else hlFine = raw;
+      if (hlFine === null || hlFine.figs !== figs) return; // the coarse half alone is no book yet
+      const next = hlStitch(hlFine, hlCoarse);
+      const prev = hlBook !== null && hlBook.figs === figs ? hlBook : null;
+      // Without a same-precision base the diff is unknown: skip an id so the push gaps and the book resyncs.
+      if (prev === null) hlSeq += 1;
+      hlBook = next;
+      hlSeq += 1;
+      datafeed.pushDepth({ firstUpdateId: hlSeq, finalUpdateId: hlSeq, time: next.time,
+        bids: hlDiff(prev?.bids ?? [], next.bids), asks: hlDiff(prev?.asks ?? [], next.asks) }, COIN);
+    }
+    // A walk symbol's book: 50 levels per side around the last close, mutated by synthDepthDelta.
+    const synthBooks = new Map();
+    function synthBook(symbol) {
+      const existing = synthBooks.get(symbol);
+      if (existing) return existing;
+      const mid = chart.getData().at(-1)?.close ?? 100;
+      const tick = Math.max(0.01, +(mid * 0.0002).toPrecision(1));
+      const rand = seeded(hash(`${symbol}@depth`));
+      const side = (dir) => Array.from({ length: 50 }, (_, i) => [+(mid + dir * (i + 1) * tick).toFixed(6), +(rand() * 8 + 0.05).toFixed(3)]);
+      const depth = { seq: 0, mid, tick, rand, bids: side(-1), asks: side(1) };
+      synthBooks.set(symbol, depth);
+      return depth;
+    }
+    async function fetchSynthDepth(symbol) {
+      const depth = synthBook(symbol);
+      return { lastUpdateId: depth.seq, bids: depth.bids.slice(), asks: depth.asks.slice() };
+    }
+    // A few random levels per tick; a drift past 20 ticks recenters by forcing a sequence gap, so the
+    // depth manager resyncs from a fresh snapshot (its Binance-style gap repair, exercised locally).
+    function synthDepthDelta(symbol) {
+      const depth = synthBooks.get(symbol);
+      if (!depth || symbol === null) return;
+      const mid = chart.getData().at(-1)?.close ?? depth.mid;
+      if (Math.abs(mid - depth.mid) > 20 * depth.tick) {
+        const side = (dir) => Array.from({ length: 50 }, (_, i) => [+(mid + dir * (i + 1) * depth.tick).toFixed(6), +(depth.rand() * 8 + 0.05).toFixed(3)]);
+        depth.mid = mid;
+        depth.bids = side(-1);
+        depth.asks = side(1);
+        depth.seq += 2;
+        datafeed.pushDepth({ firstUpdateId: depth.seq, finalUpdateId: depth.seq, bids: [], asks: [] }, symbol);
+        return;
+      }
+      const bids = [], asks = [];
+      for (let k = 0; k < 4; k++) {
+        const side = depth.rand() < 0.5 ? 'bids' : 'asks';
+        const levels = depth[side];
+        const i = Math.floor(depth.rand() * levels.length);
+        levels[i] = [levels[i][0], depth.rand() < 0.12 ? 0 : +(depth.rand() * 8 + 0.05).toFixed(3)];
+        (side === 'bids' ? bids : asks).push(levels[i]);
+      }
+      depth.seq += 1;
+      datafeed.pushDepth({ firstUpdateId: depth.seq, finalUpdateId: depth.seq, bids, asks }, symbol);
+    }
+
     await Promise.all([document.fonts.load('12px "Geist"'), document.fonts.load('12px "Geist Mono"')]).catch(() => {});
 
     // ---------------- chart + paging datafeed ----------------
     const canvas = $('chart');
     const stage = $('stage');
     const frames = createFrameScheduler(window, (update) => chart.batch(update));
+    // WebGL2 draws the candles and heatmap as instanced quads (2D fallback when unavailable); ?renderer=canvas2d compares.
+    const requestedRenderer = new URLSearchParams(location.search).get('renderer') === 'canvas2d' ? 'canvas2d' : 'webgl2';
     const { chart, datafeed } = createDatafeedChart({
       container: canvas,
+      renderer: requestedRenderer,
       preset: 'bloxwapDark',
       animation: { scheduler: frames, duration: matchMedia('(prefers-reduced-motion: reduce)').matches ? 0 : 240 },
       config: defineConfig({
@@ -153,32 +293,141 @@
         // Like bloxwap.pro: the mark and last lines below replace the built-in last-price line (its axis label stays).
         priceAxis: { lines: { lastPrice: false } },
         formatters: { price: (value) => value.toLocaleString('en-US', { minimumFractionDigits: 1, maximumFractionDigits: 1 }) },
+        // The heatmap paints the retained depth history behind the candles (same depth channel); off by default,
+        // Settings → Liquidity heatmap turns it on in the bloxwapDark palette.
+        heatmap: { enabled: false },
       }),
       fetchBars: (request) => (request.symbol === COIN ? fetchHyperliquid(request) : fetchSynthetic(request)),
+      fetchDepthSnapshot: (request) => (request.symbol === COIN ? fetchHyperliquidDepth(request) : fetchSynthDepth(request.symbol)),
       // Ticks fold as they arrive; their bars reach the chart once per frame, in the same batch as pointer work.
       scheduler: frames,
       onError: (error) => console.warn('chart data:', error),
     });
 
+    // ---------------- footprint: the trade tape → cells, delta and CVD sub-panes ----------------
+    // The source follows the datafeed's session (a symbol switch replaces the store), so the
+    // series and the indicators never hold a stale tape. Registered once; the settings toggle selects them.
+    const footprintSource = datafeedFootprintSource(datafeed);
+    chart.registerSeries('footprint', createFootprintSeries(footprintSource));
+    chart.indicators.register(createDeltaIndicator(footprintSource));
+    chart.indicators.register(createCvdIndicator(footprintSource));
+
+    let footprintOn = false, footprintIds = [], prevSeriesType = null;
+    // Binance futures aggTrade: p price, q qty, T trade time (ms), m = buyer is maker → the aggressor sold.
+    let tradeWs = null, tradeRetry = null, tradeDelay = 1000, tradeFrame = null;
+    function connectTrades() {
+      if (tradeWs) return;
+      const socket = tradeWs = new WebSocket('wss://fstream.binance.com/ws/btcusdt@aggTrade');
+      socket.onopen = () => { tradeDelay = 1000; };
+      socket.onmessage = (event) => {
+        const m = JSON.parse(event.data);
+        if (m.p === undefined) return;
+        datafeed.pushTrade({ time: m.T, price: +m.p, size: +m.q, side: m.m ? 'sell' : 'buy' }, COIN);
+        // pushTrade only fills the store; repaint at most once per frame, like the folded tick bars.
+        tradeFrame ??= frames.request(() => { tradeFrame = null; chart.render(); });
+      };
+      socket.onclose = () => {
+        if (tradeWs !== socket) return;
+        tradeWs = null;
+        tradeRetry = setTimeout(syncTradeFeed, tradeDelay = Math.min(tradeDelay * 2, 30_000));
+      };
+    }
+    function disconnectTrades() {
+      clearTimeout(tradeRetry);
+      if (tradeFrame !== null) { frames.cancel(tradeFrame); tradeFrame = null; }
+      const socket = tradeWs;
+      tradeWs = null;
+      socket?.close();
+    }
+    function syncTradeFeed() {
+      if (live && footprintOn && datafeed.symbol === COIN) connectTrades(); else disconnectTrades();
+    }
+    function setFootprint(on) {
+      if (on === footprintOn) return;
+      footprintOn = on;
+      if (on) {
+        prevSeriesType = chart.getConfig().series.type;
+        chart.updateConfig({ series: { type: 'footprint' } });
+        footprintIds = [chart.addIndicator({ name: 'delta' }), chart.addIndicator({ name: 'cvd' })];
+      } else {
+        chart.updateConfig({ series: { type: prevSeriesType ?? 'candlestick' } });
+        for (const id of footprintIds) chart.removeIndicator(id);
+        footprintIds = [];
+      }
+      footprintItem.classList.toggle('cts-active', on);
+      footprintItem.setAttribute('aria-checked', String(on));
+      syncTradeFeed();
+    }
+
     // ---------------- mark (live mid) and last (previous close) price lines, as bloxwap.pro draws them ----------------
     let markLine = null, lastLine = null;
     const lastLineColor = () => (document.body.classList.contains('light') ? 'rgba(19, 23, 34, 0.55)' : 'rgba(255, 255, 255, 0.6)');
+    // The mark (live mid) line is off by default (settings → Mark price line): its badge covered the chart's own
+    // current-price label, which now shows alone.
+    let markOn = false, markPrice = null;
     function setMarkLine(price) {
+      markPrice = price;
+      if (!markOn) return;
       if (markLine) markLine.applyOptions({ price });
-      else markLine = chart.series.createPriceLine({ price, color: '#35b5ff', lineWidth: 1, lineStyle: 'dashed', title: 'mark' });
+      else markLine = chart.series.createPriceLine({ price, color: '#35b5ff', lineWidth: 1, lineStyle: 'dashed' }); // untitled: just the price on the axis
     }
+    // The previous close ("last") is off by default (settings → Last close line): its badge sits under the mark's.
+    let lastOn = false, lastPrice = null;
     function setLastLine(price) {
+      lastPrice = price;
+      if (!lastOn) return;
       if (lastLine) lastLine.applyOptions({ price });
       else lastLine = chart.series.createPriceLine({ price, color: lastLineColor(), lineWidth: 1, lineStyle: 'dotted', title: 'last' });
     }
     function clearLines() {
       markLine?.remove(); lastLine?.remove();
-      markLine = lastLine = null;
+      markLine = lastLine = lastPrice = markPrice = null;
     }
+    // ---------------- visible-range volume profile: sell volume left, buy volume right, floating past the last bar ----------------
+    // Theme tokens by default: buy bars and sizes take the up color, sell bars and sizes the down color (bars as a
+    // dim tint behind the vivid numbers), the POC outline the theme text color, so the profile follows dark/light.
+    // Bars and shading tween on the frame scheduler.
+    const PROFILE = {
+      width: 200, inset: 48, scheduler: frames,
+      duration: matchMedia('(prefers-reduced-motion: reduce)').matches ? 0 : 180,
+    };
+    // ---------------- right-edge panel: the volume profile, the full order book, or neither (one at a time) ----------------
+    // The full live order book: a ladder growing out of the price axis over the plot's right edge, every level the
+    // depth channel below delivers. Its spread label reads Hyperliquid's full-precision best bid/offer, since the
+    // levels themselves are aggregated to the timeframe (walk symbols fall back to the gap between levels).
+    const BOOK = {
+      placement: 'overlay', layout: 'ladder', inset: 0, width: 160, maxLevels: 100,
+      spread: () => (datafeed.symbol === COIN && hlBbo !== null ? hlBbo.ask - hlBbo.bid : null),
+    };
+    let profile = attachRangeProfile(chart, PROFILE), book = null;
+    const sideMode = () => (profile !== null ? 'profile' : book !== null ? 'book' : 'none');
+    function setSideMode(mode) {
+      if (mode === 'profile' && profile === null) profile = attachRangeProfile(chart, PROFILE);
+      if (mode !== 'profile' && profile !== null) {
+        profile.remove();
+        profile = null;
+      }
+      if (mode === 'book' && book === null) book = attachInlineBook(chart, BOOK);
+      if (mode !== 'book' && book !== null) {
+        book.remove();
+        book = null;
+      }
+      clearSideSpace();
+      syncSideMode();
+    }
+    /** Leaves room past the latest bar so the panel floats in whitespace rather than over the newest candles. */
+    function clearSideSpace() {
+      if (chart.dataLength === 0) return;
+      const mode = sideMode();
+      const px = (mode === 'profile' ? PROFILE.width + PROFILE.inset : mode === 'book' ? BOOK.width : 0) + 24;
+      chart.scale.scrollTo(chart.dataLength - 1 + Math.ceil(px / chart.scale.barSpacing()));
+    }
+
     chart.subscribeDataLoad((e) => {
       const data = chart.getData();
       // A load shows the latest close; a bucket roll moves the line to the bar that just closed.
       if (e.reason === 'set') {
+        clearSideSpace();
         if (data.length > 0) setLastLine(data.at(-1).close);
         else clearLines();
         placeMarkers(data);
@@ -250,7 +499,61 @@
     }
     arrowsItem.setAttribute('role', 'checkbox');
     syncArrowsSetting();
-    settingsExtras.append(liveItem, arrowsItem, menuSeparator(document), menuLabel(document, 'Datasets'));
+    const heatmapItem = menuItem(document, { label: 'Liquidity heatmap', tick: true, onClick: () => {
+      chart.updateConfig({ heatmap: { enabled: !chart.getConfig().heatmap.enabled } });
+      syncHeatmapSetting();
+    } });
+    function syncHeatmapSetting() {
+      const enabled = chart.getConfig().heatmap.enabled;
+      heatmapItem.classList.toggle('cts-active', enabled);
+      heatmapItem.setAttribute('aria-checked', String(enabled));
+    }
+    heatmapItem.setAttribute('role', 'checkbox');
+    syncHeatmapSetting();
+    // The right-edge panel's settings items toggle their panel (switching the other off); the rail disclosure picks one.
+    const profileItem = menuItem(document, { label: 'Volume profile', tick: true,
+      onClick: () => setSideMode(sideMode() === 'profile' ? 'none' : 'profile') });
+    profileItem.setAttribute('role', 'checkbox');
+    const markItem = menuItem(document, { label: 'Mark price line', tick: true, onClick: () => {
+      markOn = !markOn;
+      if (markOn && markPrice !== null) setMarkLine(markPrice);
+      if (!markOn) { markLine?.remove(); markLine = null; }
+      markItem.classList.toggle('cts-active', markOn);
+      markItem.setAttribute('aria-checked', String(markOn));
+    } });
+    markItem.setAttribute('role', 'checkbox');
+    markItem.setAttribute('aria-checked', 'false');
+    const lastItem = menuItem(document, { label: 'Last close line', tick: true, onClick: () => {
+      lastOn = !lastOn;
+      if (lastOn && lastPrice !== null) setLastLine(lastPrice);
+      if (!lastOn) { lastLine?.remove(); lastLine = null; }
+      lastItem.classList.toggle('cts-active', lastOn);
+      lastItem.setAttribute('aria-checked', String(lastOn));
+    } });
+    lastItem.setAttribute('role', 'checkbox');
+    lastItem.setAttribute('aria-checked', 'false');
+    const bookItem = menuItem(document, { label: 'Order book', tick: true,
+      onClick: () => setSideMode(sideMode() === 'book' ? 'none' : 'book') });
+    bookItem.setAttribute('role', 'checkbox');
+    // The backend is fixed at creation, so switching reloads with the other ?renderer.
+    const glActive = chart.renderBackend === 'webgl2';
+    const glItem = menuItem(document, {
+      label: requestedRenderer === 'webgl2' && !glActive ? 'WebGL2 renderer (unavailable)' : 'WebGL2 renderer',
+      tick: true,
+      onClick: () => {
+        const url = new URL(location.href);
+        if (requestedRenderer === 'webgl2') url.searchParams.set('renderer', 'canvas2d');
+        else url.searchParams.delete('renderer');
+        location.replace(url);
+      },
+    });
+    glItem.setAttribute('role', 'checkbox');
+    glItem.classList.toggle('cts-active', glActive);
+    glItem.setAttribute('aria-checked', String(glActive));
+    const footprintItem = menuItem(document, { label: 'Footprint + delta/CVD', tick: true, onClick: () => setFootprint(!footprintOn) });
+    footprintItem.setAttribute('role', 'checkbox');
+    footprintItem.setAttribute('aria-checked', 'false');
+    settingsExtras.append(liveItem, arrowsItem, markItem, lastItem, profileItem, bookItem, heatmapItem, footprintItem, glItem, menuSeparator(document), menuLabel(document, 'Datasets'));
     const DATASETS = [
       { label: 'BTC perpetual · Hyperliquid', symbol: COIN, intervalMs: null }, // keeps the current timeframe
       { label: 'Random walk · 1m', symbol: WALK, intervalMs: 60_000 },
@@ -272,6 +575,7 @@
     chart.subscribeConfigChange(({ keys }) => {
       if (keys.includes('statusLine') || keys.includes('priceAxis')) syncCountdown();
       if (keys.includes('statusLine')) syncStatusSymbol();
+      if (keys.includes('heatmap')) syncHeatmapSetting();
     });
     const settings = createChartSettings({ chart, document, trigger: settingsBtn, extraContent: settingsExtras, chartTheme,
       onOpen: () => { toolbar.cancelNavigation(); flyouts.close(); indicators.close(); },
@@ -284,7 +588,104 @@
       onChange: () => { toolbar.cancelNavigation(); toolbar.refreshViewport(); },
     });
 
-    // ---------------- header: symbol, timeframes → datafeed, chart type, indicators, scale toggles ----------------
+    // ---------------- rail: timeframe, chart type, indicators, price scale (the wide layout's header) ----------------
+    // Flyouts open to the right of the rail; every control follows the datafeed and config like the header does.
+    const railMenu = (label) => {
+      const menu = flyouts.create();
+      menu.append(menuLabel(document, label));
+      return menu;
+    };
+    const radio = (menu, options) => {
+      const item = menuItem(document, { tick: true, ...options, onClick: () => { flyouts.close(); options.onClick(); } });
+      item.setAttribute('role', 'menuitemradio');
+      menu.append(item);
+      return item;
+    };
+    const check = (item, on) => {
+      item.classList.toggle('cts-active', on);
+      item.setAttribute('aria-checked', String(on));
+    };
+
+    const tfBtn = labelButton(document, '15m', 'Timeframe');
+    const tfMenu = railMenu('Timeframe');
+    const tfItems = DEFAULT_TIMEFRAMES.map((tf) => radio(tfMenu, { label: tf.label,
+      onClick: () => { if (tf.intervalMs !== datafeed.intervalMs) void load(datafeed.symbol ?? COIN, tf.intervalMs); } }));
+    flyouts.attach(tfBtn, tfMenu);
+    function syncRailTimeframe() {
+      const intervalMs = datafeed.intervalMs;
+      const label = DEFAULT_TIMEFRAMES.find((tf) => tf.intervalMs === intervalMs)?.label ?? '';
+      setButtonLabel(tfBtn, label);
+      tfBtn.title = `Timeframe: ${label}`;
+      tfBtn.setAttribute('aria-label', tfBtn.title);
+      DEFAULT_TIMEFRAMES.forEach((tf, i) => check(tfItems[i], tf.intervalMs === intervalMs));
+    }
+    datafeed.subscribeState(syncRailTimeframe);
+
+    const typeBtn = iconButton(document, 'chart-candlestick', 'Chart type', 20);
+    const typeMenu = railMenu('Chart type');
+    const typeItems = DEFAULT_CHART_TYPES.map((type) => radio(typeMenu, { icon: `chart-${type}`, label: CHART_TYPE_LABELS[type],
+      onClick: () => chart.updateConfig({ series: { type } }) }));
+    flyouts.attach(typeBtn, typeMenu);
+    function syncRailType() {
+      const type = chart.getConfig().series.type;
+      // A custom series (the footprint) keeps the candlestick glyph.
+      setButtonIcon(typeBtn, ICONS[`chart-${type}`] !== undefined ? `chart-${type}` : 'chart-candlestick', 20);
+      typeBtn.title = `Chart type: ${CHART_TYPE_LABELS[type] ?? type}`;
+      typeBtn.setAttribute('aria-label', typeBtn.title);
+      DEFAULT_CHART_TYPES.forEach((t, i) => check(typeItems[i], t === type));
+    }
+
+    const indicatorsBtn = iconButton(document, 'function-square', 'Indicators', 20);
+    indicatorsBtn.setAttribute('aria-haspopup', 'dialog');
+    indicatorsBtn.addEventListener('click', () => indicators.openPicker());
+
+    // Right-edge panel disclosure: the volume profile (both ways from a center line), the order book (out of the
+    // right edge), or none. The button shows the chosen panel's glyph and takes the accent while one shows.
+    const SIDE_MODES = [
+      { mode: 'profile', icon: 'range-profile', label: 'Volume profile' },
+      { mode: 'book', icon: 'order-book', label: 'Order book' },
+      { mode: 'none', icon: 'eye-off', label: 'None' },
+    ];
+    const sideBtn = iconButton(document, 'range-profile', 'Right-edge panel', 20);
+    const sideMenu = railMenu('Right edge');
+    const sideItems = SIDE_MODES.map(({ mode, icon, label }) => radio(sideMenu, { icon, label, onClick: () => setSideMode(mode) }));
+    flyouts.attach(sideBtn, sideMenu);
+    function syncSideMode() {
+      const mode = sideMode();
+      const current = SIDE_MODES.find((m) => m.mode === mode);
+      setButtonIcon(sideBtn, mode === 'none' ? 'range-profile' : current.icon, 20);
+      sideBtn.classList.toggle('cts-on', mode !== 'none');
+      sideBtn.title = `Right edge: ${current.label}`;
+      sideBtn.setAttribute('aria-label', sideBtn.title);
+      SIDE_MODES.forEach((m, i) => check(sideItems[i], m.mode === mode));
+      check(profileItem, mode === 'profile');
+      check(bookItem, mode === 'book');
+    }
+    syncSideMode();
+
+    const scaleBtns = SCALE_TOGGLES.map(({ key, label, title }) => {
+      const b = labelButton(document, label, title);
+      b.classList.add('rail-scale');
+      b.setAttribute('aria-label', title);
+      b.addEventListener('click', () => toggleScale(chart, key));
+      return b;
+    });
+    function syncRailScale() {
+      const state = scaleToggleState(chart.getConfig().priceAxis);
+      SCALE_TOGGLES.forEach(({ key }, i) => {
+        scaleBtns[i].classList.toggle('cts-on', state[key]);
+        scaleBtns[i].setAttribute('aria-pressed', String(state[key]));
+      });
+    }
+    chart.subscribeConfigChange(({ keys }) => {
+      if (keys.includes('series')) syncRailType();
+      if (keys.includes('priceAxis')) syncRailScale();
+    });
+    syncRailTimeframe();
+    syncRailType();
+    syncRailScale();
+
+    // ---------------- header (narrow screens): symbol, timeframes → datafeed, chart type, indicators, scale toggles ----------------
     const shotBtn = iconButton(document, 'image', 'Download snapshot', 18);
     shotBtn.innerHTML = CAMERA;
     shotBtn.addEventListener('click', () => void downloadSnapshot());
@@ -302,7 +703,6 @@
       onIndicators: () => indicators.openPicker(),
       slots: { right: [headerControls] },
     });
-    const scaleButtons = createScaleButtons({ chart, document, overlay: stage, tokens: BLOXWAP_HEADER_THEME });
 
     // Embeds can pin a host theme with ?lockedTheme=dark (or light). Without a saved choice, start on dark (bloxwapDark).
     const themeKey = 'chart-ts:theme';
@@ -318,7 +718,6 @@
         toolbar.setTheme(theme);
         settings.setTheme(theme);
         header.setTheme(theme);
-        scaleButtons.setTheme(theme);
         lastLine?.applyOptions({ color: lastLineColor() });
         placeMarkers(chart.getData()); // in the theme's candle colors
         indicators.setTheme(theme); // after the toolbar, so candle-following colors in open settings match
@@ -341,16 +740,19 @@
       railToggle.title = show ? 'Hide drawing toolbar' : 'Show drawing toolbar';
     });
 
-    // Wide: a control rail. Narrow (< 600px): the rail hides and its buttons join the header, which compacts and wraps.
-    const divider = el(document, 'div', 'cts-rail-divider');
+    // Wide: the control rail replaces the header. Narrow (< 600px): the rail hides, the header shows, and the
+    // shared buttons join it, compacting and wrapping. The rail-only controls stay put in the hidden rail.
+    const divider = () => el(document, 'div', 'cts-rail-divider');
     const narrow = matchMedia('(max-width: 599px)');
+    $('ctrl-scroll').append(tfBtn, typeBtn, indicatorsBtn, sideBtn, divider(), ...scaleBtns, divider());
+    const themeDivider = divider();
     const placeControls = () => {
-      const rail = [undoBtn, redoBtn, ...(themeControl.element ? [divider, themeControl.element] : [])];
+      const theme = themeControl.element ? [themeControl.element] : [];
       flyouts.close();
-      if (narrow.matches) headerControls.append(...rail.filter((node) => node !== divider), settingsBtn, railToggle);
+      if (narrow.matches) headerControls.append(shotBtn, undoBtn, redoBtn, ...theme, settingsBtn, railToggle);
       else {
-        $('ctrl-scroll').append(...rail);
-        $('ctrl-bottom').append(settingsBtn, railToggle);
+        $('ctrl-scroll').append(undoBtn, redoBtn, ...(theme.length > 0 ? [themeDivider, ...theme] : []));
+        $('ctrl-bottom').append(shotBtn, settingsBtn, railToggle);
       }
     };
     placeControls();
@@ -454,6 +856,53 @@
       ws = null;
       socket?.close();
     }
+    // ---------------- live depth: Hyperliquid l2Book for BTC, synthetic deltas for the walks ----------------
+    let depthWs = null, depthRetry = null, depthDelay = 1000;
+    function connectDepth(figs) {
+      if (depthWs?.figs === figs) return;
+      // A new precision needs its own subscription; the old socket's pushes and close are ignored.
+      const stale = depthWs;
+      const socket = depthWs = new WebSocket('wss://api.hyperliquid.xyz/ws');
+      stale?.close();
+      socket.figs = figs;
+      socket.onopen = () => {
+        depthDelay = 1000;
+        socket.send(JSON.stringify({ method: 'subscribe', subscription: { type: 'l2Book', coin: COIN, nSigFigs: figs } }));
+        socket.send(JSON.stringify({ method: 'subscribe', subscription: { type: 'l2Book', coin: COIN, nSigFigs: figs - 1 } }));
+        socket.send(JSON.stringify({ method: 'subscribe', subscription: { type: 'bbo', coin: COIN } }));
+      };
+      socket.onmessage = (event) => {
+        if (depthWs !== socket) return;
+        const message = JSON.parse(event.data);
+        if (message.channel === 'l2Book' && message.data?.coin === COIN) onHyperliquidBook(message.data, figs);
+        else if (message.channel === 'bbo' && message.data?.coin === COIN) {
+          const [bid, ask] = message.data.bbo;
+          hlBbo = bid && ask ? { bid: +bid.px, ask: +ask.px } : null;
+        }
+      };
+      socket.onclose = () => {
+        if (depthWs !== socket) return;
+        depthWs = null;
+        hlBook = hlFine = hlCoarse = hlBbo = null; // pushes are missed while disconnected: the next one resyncs the book
+        depthRetry = setTimeout(syncDepthFeed, depthDelay = Math.min(depthDelay * 2, 30_000));
+      };
+    }
+    function disconnectDepth() {
+      clearTimeout(depthRetry);
+      const socket = depthWs;
+      depthWs = null;
+      if (socket) hlBook = hlFine = hlCoarse = hlBbo = null;
+      socket?.close();
+    }
+    let depthTimer = null;
+    function syncDepthFeed() {
+      const symbol = datafeed.symbol;
+      if (live && symbol === COIN) connectDepth(hlFigsFor(datafeed.intervalMs ?? 900_000)); else disconnectDepth();
+      const synth = live && symbol !== null && symbol !== COIN;
+      if (synth && depthTimer === null) depthTimer = setInterval(() => synthDepthDelta(datafeed.symbol), 250);
+      if (!synth && depthTimer !== null) { clearInterval(depthTimer); depthTimer = null; }
+    }
+
     // The walk steps from its own last price: a hidden tab's bars reach the chart only once it shows again.
     let walkTimer = null, walkPrice = null;
     function syncFeed() {
@@ -467,8 +916,10 @@
         onMid(walkPrice, datafeed.symbol);
       }, 1000);
       if (!walking && walkTimer !== null) { clearInterval(walkTimer); walkTimer = null; }
+      syncDepthFeed(); // depth deltas for the loaded symbol; the datafeed ignores any other
+      syncTradeFeed(); // aggTrades while the footprint shows; ignored for any other symbol
     }
-    window.addEventListener('pagehide', disconnectFeed);
+    window.addEventListener('pagehide', () => { disconnectFeed(); disconnectDepth(); disconnectTrades(); });
 
     // ---------------- loading: Hyperliquid first, the random walk when it is unreachable ----------------
     async function load(symbol, intervalMs) {
@@ -497,7 +948,9 @@
         else if (step > 0) missingBuckets += Math.round(gap / step) - 1;
       }
       const { symbol, intervalMs, loading, exhausted, error } = datafeed.state;
+      const book = chart.depth;
       return { symbol, intervalMs, bars: data.length, duplicates, missingBuckets, exhausted, loading,
+        renderBackend: chart.renderBackend, bookLevels: book === null ? null : { bids: book.bids.length, asks: book.asks.length },
         error: error === null ? null : String(error), firstTime: data[0]?.time ?? null, lastTime: data.at(-1)?.time ?? null };
     };
 
diff --git a/packages/chart/assets/icons/order-book.svg b/packages/chart/assets/icons/order-book.svg
new file mode 100644
index 0000000..f1d035a
--- /dev/null
+++ b/packages/chart/assets/icons/order-book.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M20 3v18"/><path d="M14 5h6M8 9h12M4 13h16M11 17h9M16 21h4"/></svg>
diff --git a/packages/chart/assets/icons/range-profile.svg b/packages/chart/assets/icons/range-profile.svg
new file mode 100644
index 0000000..102a2a9
--- /dev/null
+++ b/packages/chart/assets/icons/range-profile.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3v18"/><path d="M10 5h4M7 9h10M4 13h16M8 17h8M10 21h4"/></svg>
diff --git a/packages/chart/bench/webgl.bench.mjs b/packages/chart/bench/webgl.bench.mjs
new file mode 100644
index 0000000..bf305f2
--- /dev/null
+++ b/packages/chart/bench/webgl.bench.mjs
@@ -0,0 +1,56 @@
+/**
+ * CPU submission time of the Canvas2D vs WebGL2 backends on recording
+ * contexts (MockContext2D / MockContextWebGL2), NOT GPU raster time or
+ * display FPS. The WebGL2 numbers cover quad packing and buffer staging; in a
+ * browser the rasterization the recording canvas skips here moves to the GPU.
+ */
+import { bench, candles, load } from './harness.mjs';
+const { createChart } = await load('index.js');
+const { MockDocument, MockGLDocument } = await load('dom.js');
+
+const data = candles(100_000);
+console.log('\nBackend benchmark (CPU submission; recording 2D context vs mock GL):');
+
+function depthBook(timeMs) {
+  const bids = [];
+  const asks = [];
+  for (let j = 0; j < 50; j++) {
+    bids.push([103.5 - j * 0.25, (j + 1) * 3]);
+    asks.push([104.5 + j * 0.25, (j + 1) * 2]);
+  }
+  return { bids, asks, time: timeMs };
+}
+
+for (const visible of [200, 5000, 20000]) {
+  // The minimum spacing is 0.5px/bar; size the canvas for the requested range.
+  const width = Math.max(1264, Math.ceil(visible * 0.5) + 64);
+  for (const [label, makeDoc, renderer] of [
+    ['canvas2d', () => new MockDocument(), undefined],
+    ['webgl2', () => new MockGLDocument(), 'webgl2'],
+  ]) {
+    const doc = makeDoc();
+    const chart = createChart({ document: doc, ...(renderer !== undefined ? { renderer } : {}),
+      config: { width, height: 900, data, wasm: false } });
+    chart.scale.zoomToRange(data.length - visible, data.length - 1);
+    const ctx = doc.created[0].context;
+    if (renderer !== undefined && chart.renderBackend !== 'webgl2') throw new Error('expected the webgl2 backend');
+    bench(`${visible} bars ${label}: full redraw`, () => { ctx.calls.length = 0; chart.render(); });
+    chart.destroy();
+  }
+}
+
+console.log('\nBackend benchmark with heatmap (500 buckets x 2 x 50 levels visible):');
+for (const [label, makeDoc, renderer] of [
+  ['canvas2d', () => new MockDocument(), undefined],
+  ['webgl2', () => new MockGLDocument(), 'webgl2'],
+]) {
+  const doc = makeDoc();
+  const chart = createChart({ document: doc, ...(renderer !== undefined ? { renderer } : {}),
+    config: { width: 2564, height: 900, data, wasm: false, heatmap: { enabled: true } } });
+  chart.scale.zoomToRange(data.length - 500, data.length - 1);
+  const end = data[data.length - 1].time * 1000;
+  for (let k = 500; k >= 1; k--) chart.setDepth(depthBook(end - k * 1000));
+  const ctx = doc.created[0].context;
+  bench(`heatmap ${label}: full redraw`, () => { ctx.calls.length = 0; chart.render(); });
+  chart.destroy();
+}
diff --git a/packages/chart/package.json b/packages/chart/package.json
index c3f9c98..be85534 100644
--- a/packages/chart/package.json
+++ b/packages/chart/package.json
@@ -79,7 +79,7 @@
     "test": "npm run build && npm run build:ts-test && node --test \"dist-test/**/*.test.js\"",
     "coverage": "npm run build && npm run build:ts-test && node scripts/check-coverage.mjs",
     "coverage:lcov": "npm run build && npm run build:ts-test && mkdir -p coverage && node --enable-source-maps --test --experimental-test-coverage --test-coverage-exclude='**/kernels.base64.*' --test-coverage-exclude='dist-test/**' --test-coverage-exclude='test/**' --test-reporter=dot --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info \"dist-test/**/*.test.js\" && node scripts/lcov-sanitize.mjs",
-    "bench": "npm run build && node bench/indicators.bench.mjs && node bench/rolling.bench.mjs && node bench/render.bench.mjs && node bench/workloads.bench.mjs",
+    "bench": "npm run build && node bench/indicators.bench.mjs && node bench/rolling.bench.mjs && node bench/render.bench.mjs && node bench/workloads.bench.mjs && node bench/webgl.bench.mjs",
     "prepublishOnly": "npm test",
     "prepack": "npm run build",
     "bench:browser": "npm run build && node bench/run-browser.mjs"
diff --git a/packages/chart/src/config.ts b/packages/chart/src/config.ts
index b6921e1..60018ed 100644
--- a/packages/chart/src/config.ts
+++ b/packages/chart/src/config.ts
@@ -9,6 +9,23 @@
  */
 
 import type { Candle } from './core/data.js';
+import {
+  DEFAULT_HEATMAP_BUCKET_MS,
+  DEFAULT_HEATMAP_COLOR_HIGH,
+  DEFAULT_HEATMAP_COLOR_LOW,
+  DEFAULT_HEATMAP_GAMMA,
+  DEFAULT_HEATMAP_MAX_BUCKETS,
+  DEFAULT_HEATMAP_MAX_LEVELS,
+  DEFAULT_HEATMAP_MIN_OPACITY,
+  DEFAULT_HEATMAP_OPACITY,
+  type HeatmapStop,
+} from './core/heatmap.js';
+import {
+  DEFAULT_INLINE_BOOK_ASK_COLOR,
+  DEFAULT_INLINE_BOOK_BID_COLOR,
+  DEFAULT_INLINE_BOOK_MAX_LEVELS,
+  DEFAULT_INLINE_BOOK_WIDTH,
+} from './core/inline-book.js';
 import type { CanvasImageSourceLike } from './dom.js';
 
 /** Built-in main-series renderers. */
@@ -16,7 +33,8 @@ export type SeriesType = 'candlestick' | 'line' | 'area' | 'bar' | 'histogram' |
 
 /** Main series appearance. Colors accept hex, rgb(a), and `color(display-p3 ...)`. */
 export interface SeriesConfig {
-  type: SeriesType;
+  /** A built-in {@link SeriesType}, or a type registered via {@link import('./core/chart.js').Chart.registerSeries}. */
+  type: SeriesType | (string & {});
   colorByPreviousClose: boolean;
   bodyVisible: boolean;
   borderVisible: boolean;
@@ -229,6 +247,76 @@ export interface VolumeConfig {
   height: number;
 }
 
+/**
+ * Inline order book: a live bid/ask depth ladder docked beside the price
+ * axis, fed by `Chart.setDepth` (the datafeed's depth channel). The chart
+ * attaches the pane while `enabled` holds and drops it when it clears.
+ */
+export interface InlineBookConfig {
+  /** Dock the inline book pane, sharing the main price scale. */
+  enabled: boolean;
+  /** Levels shown per side. */
+  maxLevels: number;
+  /** Bid bar color. */
+  bidColor: string;
+  /** Ask bar color. */
+  askColor: string;
+  /** Shade cumulative depth behind the level bars. */
+  cumulative: boolean;
+  /** Size label per row when the row is tall enough. */
+  showLabels: boolean;
+  /**
+   * `'dock'` gives the book its own strip beside the price axis, shrinking the
+   * plot; `'overlay'` paints it behind the series along the plot's right edge,
+   * so the plot keeps the full width.
+   */
+  placement: 'dock' | 'overlay';
+  /**
+   * `'ladder'` grows every level from the price-axis side; `'mirrored'` grows
+   * bids left and asks right from a central column of size labels.
+   */
+  layout: 'ladder' | 'mirrored';
+  /** Book width in CSS pixels: the dock strip, or the overlay band. */
+  width: number;
+  /** Overlay only: gap in CSS pixels between the band and the price axis. */
+  inset: number;
+}
+
+/**
+ * Liquidity heatmap (Bookmap-style): resting order-book size over time as a
+ * color field behind the main series, fed by `Chart.setDepth` (the datafeed's
+ * depth channel). While `enabled` holds, the chart retains a bounded window
+ * of time-bucketed book snapshots (`maxBuckets` × 2 × `maxLevels` level
+ * pairs) and drops it when `enabled` clears.
+ */
+export interface HeatmapConfig {
+  /** Paint the heatmap behind the candles. */
+  enabled: boolean;
+  /** Wall-clock bucket width in ms; at most one retained snapshot per bucket. */
+  bucketMs: number;
+  /** Retained buckets (the history window's capacity). */
+  maxBuckets: number;
+  /** Levels kept per side per snapshot. */
+  maxLevels: number;
+  /** Ramp color at zero intensity (used when `stops` is empty). */
+  colorLow: string;
+  /** Ramp color at full intensity (used when `stops` is empty). */
+  colorHigh: string;
+  /**
+   * A custom gradient from zero to full intensity, replacing `colorLow` →
+   * `colorHigh` when it has at least one usable color. Bare colors spread
+   * evenly; `{ color, at }` pins a stop to an intensity (0-1). A stop's own
+   * alpha scales the ramp alpha there. Empty (the default) keeps the two-color ramp.
+   */
+  stops: HeatmapStop[];
+  /** 0-1; peak cell alpha at full intensity. */
+  opacity: number;
+  /** 0-1; cell alpha at zero intensity, so thin liquidity can stay visible. Default 0. */
+  minOpacity: number;
+  /** Intensity curve exponent; below 1 lifts small sizes. */
+  gamma: number;
+}
+
 /** Label formatting hooks. */
 export interface FormattersConfig {
   price: (value: number) => string;
@@ -259,6 +347,10 @@ export interface ChartConfig {
   theme: ThemeConfig;
   watermark: WatermarkConfig;
   volume: VolumeConfig;
+  /** Inline order book docked beside the price axis. */
+  inlineBook: InlineBookConfig;
+  /** Liquidity heatmap behind the main series. */
+  heatmap: HeatmapConfig;
   formatters: FormattersConfig;
   /** Relative height of each indicator sub-pane (main pane weighs 3). */
   indicatorPaneWeight: number;
@@ -345,6 +437,30 @@ export const DEFAULT_CONFIG: ChartConfig = {
     fontFamily: '',
   },
   volume: { overlay: false, upColor: 'up', downColor: 'down', opacity: 0.5, height: 0.2 },
+  inlineBook: {
+    enabled: false,
+    maxLevels: DEFAULT_INLINE_BOOK_MAX_LEVELS,
+    bidColor: DEFAULT_INLINE_BOOK_BID_COLOR,
+    askColor: DEFAULT_INLINE_BOOK_ASK_COLOR,
+    cumulative: true,
+    showLabels: true,
+    placement: 'dock',
+    layout: 'ladder',
+    width: DEFAULT_INLINE_BOOK_WIDTH,
+    inset: 0,
+  },
+  heatmap: {
+    enabled: false,
+    bucketMs: DEFAULT_HEATMAP_BUCKET_MS,
+    maxBuckets: DEFAULT_HEATMAP_MAX_BUCKETS,
+    maxLevels: DEFAULT_HEATMAP_MAX_LEVELS,
+    colorLow: DEFAULT_HEATMAP_COLOR_LOW,
+    colorHigh: DEFAULT_HEATMAP_COLOR_HIGH,
+    stops: [],
+    opacity: DEFAULT_HEATMAP_OPACITY,
+    minOpacity: DEFAULT_HEATMAP_MIN_OPACITY,
+    gamma: DEFAULT_HEATMAP_GAMMA,
+  },
   formatters: { price: defaultPriceFormatter, time: defaultTimeFormatter },
   indicatorPaneWeight: 1,
 };
diff --git a/packages/chart/src/core/chart.ts b/packages/chart/src/core/chart.ts
index 5a4abc8..5e80801 100644
--- a/packages/chart/src/core/chart.ts
+++ b/packages/chart/src/core/chart.ts
@@ -17,14 +17,21 @@ import type { AutoResizeCanvas, CanvasImageSourceLike, ChartCanvas, ChartDocumen
 import { CHART_THEMES, type ThemeName } from '../themes.js';
 import { withPreset, type ChartPresetName } from '../presets.js';
 import { scaleFont } from '../render/scale-font.js';
+import { attachInlineBook, type InlineBookApi } from '../render/inline-book.js';
+import { attachHeatmap, type HeatmapApi } from '../render/heatmap.js';
 import { parseColor } from '../color.js';
 import { DataStore, type Candle } from './data.js';
+import type { DepthBook } from './depth.js';
 import { PriceScale, TimeScale, seriesMinMax, visibleMinMax, type VisibleRange } from './scale.js';
 import type { SlotRange } from './scale.js';
 import { layoutPanes, MAIN_PANE_WEIGHT, type PaneSpec } from './pane.js';
 import { Crosshair } from './crosshair.js';
-import { renderChart, renderOverlay, type RenderView, type PaneRenderInfo, type ResolvedDrawing } from '../render/renderer.js';
+import { renderChart, renderOverlay, type RenderView, type PaneRenderInfo, type DockedPaneRenderInfo, type ResolvedDrawing } from '../render/renderer.js';
+import { GLBackend, type GLFrame, type RenderBackend } from '../render/gl/backend.js';
 import { createIndicatorRegistry, IndicatorRegistry } from '../indicators/registry.js';
+import { createSeriesRegistry, SeriesRegistry } from '../series/registry.js';
+import type { SeriesDrawFn } from '../series/types.js';
+import { splitPrimitives, type PanePrimitive } from '../render/primitive.js';
 import { resolveIndicatorColors, type IndicatorDef, type IndicatorOutput } from '../indicators/types.js';
 import { indicatorLineLabels } from '../indicators/labels.js';
 import {
@@ -69,6 +76,15 @@ export interface CreateChartOptions {
   pixelRatio?: number;
   /** Cache static pixels during pointer movement on browser canvases. Default true. */
   crosshairCache?: boolean;
+  /**
+   * Render backend preference. `'webgl2'` paints the main pane's dense
+   * geometry (heatmap cells, candle bodies and wicks) as instanced quads on an
+   * offscreen WebGL2 canvas composited at the series layer; text, axes and
+   * overlays stay on Canvas2D. When the host cannot provide a WebGL2 context
+   * (workers, SSR, tests) or pipeline setup fails, the chart silently uses
+   * `'canvas2d'` — see {@link Chart.renderBackend}. Default `'canvas2d'`.
+   */
+  renderer?: RenderBackend;
   /** Opt-in live candle, indicator, pane and autoscale transitions using the host's frame clock. */
   animation?: { scheduler: FrameScheduler; duration?: number };
   /** A built-in color theme, applied under `config` (fields in `config` win). */
@@ -88,6 +104,7 @@ export interface CreateChartOptions {
   registries?: {
     indicators?: IndicatorRegistry;
     drawings?: DrawingRegistry;
+    series?: SeriesRegistry;
   };
 }
 
@@ -135,6 +152,52 @@ export interface DrawingDraft {
 /** Magnet strength for {@link Chart.snapPoint}: weak snaps only near a price. */
 export type MagnetMode = 'off' | 'weak' | 'strong';
 
+/** Where a host pane lives: stacked in the plot column or docked to a canvas edge. */
+export type CustomPanePlacement = 'stacked' | 'left' | 'right';
+
+/** Price range provider for a host pane's own scale; `null` falls back to 0–1. */
+export type CustomPaneAutoscale = (range: VisibleRange, candles: readonly Candle[]) => { min: number; max: number } | null;
+
+/** Default width in CSS pixels of a docked host pane. */
+export const DEFAULT_DOCK_WIDTH = 80;
+
+/** Input for {@link Chart.addPane}. */
+export interface CustomPaneOptions {
+  /** Unique id; generated by {@link Chart.addPane} when omitted. */
+  id?: string;
+  /** `'stacked'` (default) takes a weighted slice of the plot height; `'left'`/`'right'` dock a full-height strip at that canvas edge. */
+  placement?: CustomPanePlacement;
+  /** Stacked panes: height weight (the main pane weighs {@link MAIN_PANE_WEIGHT}). Default 1. */
+  weight?: number;
+  /** Docked panes: strip width in CSS pixels. Default {@link DEFAULT_DOCK_WIDTH}. */
+  width?: number;
+  /** Reuse the main pane's price range and mode instead of {@link CustomPaneOptions.autoscale}. Default false. */
+  sharePriceScale?: boolean;
+  /** Price range for the pane's own scale over the visible bars; `null` falls back to 0–1. */
+  autoscale?: CustomPaneAutoscale;
+}
+
+/** Handle of a host pane added via {@link Chart.addPane}. */
+export interface PaneApi {
+  readonly id: string;
+  /** Attaches a custom draw pass to the pane (z-order from the primitive) and re-renders. */
+  attachPrimitive(primitive: PanePrimitive): PanePrimitiveHandle;
+  /** Stacked panes: updates the height weight and re-renders. */
+  setWeight(weight: number): void;
+  /** Docked panes: updates the strip width in CSS pixels and re-renders. */
+  setWidth(width: number): void;
+  /** Removes the pane and its primitives and re-renders. */
+  remove(): void;
+}
+
+/** Handle of an attached primitive. */
+export interface PanePrimitiveHandle {
+  /** Detaches the primitive and re-renders. */
+  detach(): void;
+  /** Per-frame invalidation: repaints the chart with the primitive still attached. */
+  requestUpdate(): void;
+}
+
 /** Default drawing color. */
 export const DEFAULT_DRAWING_COLOR = '#2962ff';
 
@@ -158,6 +221,16 @@ interface CachedIndicator {
   output: IndicatorOutput;
 }
 
+interface CustomPaneState {
+  id: string;
+  placement: CustomPanePlacement;
+  weight: number;
+  width: number;
+  sharePriceScale: boolean;
+  autoscale: CustomPaneAutoscale | undefined;
+  primitives: PanePrimitive[];
+}
+
 function matchesIndicator(cached: CachedIndicator, cfg: IndicatorConfig, def: IndicatorDef, colors: readonly string[]): boolean {
   const keys = Object.keys(cfg.params);
   return cached.def === def && cached.compute === def.compute && cached.update === def.update &&
@@ -186,6 +259,12 @@ export interface ScaleApi {
   yToPrice(y: number): number;
   /** Price → CSS-pixel y on the main pane (NaN when no main pane is laid out). */
   priceToY(price: number): number;
+  /**
+   * Pans the main pane's price range by `dy` CSS pixels (positive drags the
+   * content down, revealing higher prices) and turns price autoscale off, like
+   * TradingView's vertical chart drag. A no-op before the main pane is laid out.
+   */
+  scrollPrice(dy: number): void;
   /** Current scale units per horizontal bar (per time slot with `timeScale.continuous`). */
   priceToBarRatio(): number;
   /**
@@ -208,6 +287,8 @@ export class Chart {
   readonly indicators: IndicatorRegistry;
   /** Drawing registry; register custom drawing models here. */
   readonly drawings: DrawingRegistry;
+  /** Series registry; register custom series renderers here (or via {@link Chart.registerSeries}). */
+  readonly seriesRenderers: SeriesRegistry;
   /** Resolves once WASM kernels are initialized (or JS fallback chosen). */
   readonly ready: Promise<Chart>;
 
@@ -242,6 +323,9 @@ export class Chart {
   private resizeObserver: ResizeObserverLike | null = null;
   private indicatorSeq = 0;
   private drawingSeq = 0;
+  private paneSeq = 0;
+  private readonly customPanes = new Map<string, CustomPaneState>();
+  private readonly mainPrimitives: PanePrimitive[] = [];
   private plotWidth = 0;
   private mainHeight = 0;
   private draft: DrawingDraft | null = null;
@@ -256,9 +340,22 @@ export class Chart {
   private lastView: RenderView | null = null;
   private plotLeft = 0;
   private lockedRatio: number | null = null;
+  /** The latest L2 book, kept outside the candle store; see {@link setDepth}. */
+  private depthBook: DepthBook | null = null;
+  /** The config-driven inline order book (`inlineBook.enabled`); see {@link syncInlineBook}. */
+  private inlineBook: InlineBookApi | null = null;
+  /** The `inlineBook.placement` the attached book was built for; a change re-attaches it. */
+  private inlineBookPlacement: ChartConfig['inlineBook']['placement'] | null = null;
+  /** The config-driven liquidity heatmap (`heatmap.enabled`); see {@link syncHeatmap}. */
+  private heatmap: HeatmapApi | null = null;
   private batchDepth = 0;
   private pendingRender = false;
   private pendingCrosshair = false;
+  /** The requested backend (`renderer: 'webgl2'`); the effective one is {@link renderBackend}. */
+  private readonly preferGL: boolean;
+  private glBackend: GLBackend | null = null;
+  /** Set once WebGL2 acquisition has failed; never retried. */
+  private glFailed = false;
   /** Primitives of each drawing from the last frame, topmost last (hit-testing). */
   private lastGeometry: { id: string; primitives: readonly DrawPrimitive[] }[] = [];
   /** Indicators of the last frame with their styled outputs (hit-testing). */
@@ -268,6 +365,7 @@ export class Chart {
 
   constructor(options: CreateChartOptions) {
     this.useCrosshairCache = options.crosshairCache !== false;
+    this.preferGL = options.renderer === 'webgl2';
     this.config = resolveConfig(withPreset(options.preset, options.theme !== undefined ? mergeDeep(CHART_THEMES[options.theme], options.config ?? {}) : options.config));
     if (options.animation !== undefined) {
       this.indicatorPresence = new Presence(options.animation.scheduler, () => this.render(),
@@ -277,6 +375,7 @@ export class Chart {
     }
     this.indicators = options.registries?.indicators ?? createIndicatorRegistry();
     this.drawings = options.registries?.drawings ?? createDrawingRegistry();
+    this.seriesRenderers = options.registries?.series ?? createSeriesRegistry();
     this.pixelRatio = options.pixelRatio ?? 1;
     this.snapshotDocument = options.document;
     this.clock = options.now ?? (() => Date.now());
@@ -292,6 +391,8 @@ export class Chart {
     }
     this.store.setData(this.config.data);
     this.timeSlots.sync(this.store.raw(), this.config.timeScale, 'data');
+    this.syncInlineBook();
+    this.syncHeatmap();
     if (this.config.wasm) {
       this.ready = initWasm().then((kernels) => {
         this.kernels = kernels;
@@ -419,6 +520,40 @@ export class Chart {
     this.render();
   }
 
+  /** The current L2 order book, or null when no depth feed is attached. Stored outside the candle store. */
+  get depth(): DepthBook | null {
+    return this.depthBook;
+  }
+
+  /** Replaces the L2 order book and re-renders; the depth channel calls it on every book update. */
+  setDepth(book: DepthBook | null): void {
+    this.depthBook = book;
+    this.render();
+  }
+
+  /** Attaches the inline order book while `inlineBook.enabled` holds in the config, and drops it when it clears. */
+  private syncInlineBook(): void {
+    const { enabled, placement } = this.config.inlineBook;
+    if (this.inlineBook !== null && (!enabled || placement !== this.inlineBookPlacement)) {
+      this.inlineBook.remove();
+      this.inlineBook = null;
+    }
+    if (enabled && this.inlineBook === null) {
+      this.inlineBook = attachInlineBook(this);
+      this.inlineBookPlacement = placement;
+    }
+  }
+
+  /** Attaches the liquidity heatmap while `heatmap.enabled` holds in the config, and drops it (and its history) when it clears. */
+  private syncHeatmap(): void {
+    if (this.config.heatmap.enabled && this.heatmap === null) {
+      this.heatmap = attachHeatmap(this);
+    } else if (!this.config.heatmap.enabled && this.heatmap !== null) {
+      this.heatmap.remove();
+      this.heatmap = null;
+    }
+  }
+
   /** Deep-merges a partial over the current config and re-renders. */
   updateConfig(partial: DeepPartial<ChartConfig>): void {
     if (partial.priceAxis?.lockPriceToBarRatio === true && !this.config.priceAxis.lockPriceToBarRatio) {
@@ -445,6 +580,8 @@ export class Chart {
     if (partial.data !== undefined || partial.timeScale !== undefined) {
       this.timeSlots.sync(this.store.raw(), this.config.timeScale, partial.data !== undefined ? 'data' : 'config');
     }
+    if (partial.inlineBook !== undefined) this.syncInlineBook();
+    if (partial.heatmap !== undefined) this.syncHeatmap();
     this.render();
   }
 
@@ -578,6 +715,110 @@ export class Chart {
     return true;
   }
 
+  /**
+   * Registers a custom main-series draw pass under `type` (replacing any
+   * previous registration), selectable via `series: { type }`, and re-renders.
+   */
+  registerSeries(type: string, drawFn: SeriesDrawFn): void {
+    this.seriesRenderers.register(type, drawFn);
+    this.render();
+  }
+
+  /**
+   * Adds a host pane and returns its handle. A `'stacked'` pane (the default)
+   * takes a weighted slice of the plot height between the main pane and the
+   * indicator sub-panes; `'left'`/`'right'` dock a full-height strip at that
+   * canvas edge, shrinking the plot (e.g. a depth panel right of the chart).
+   * Attach primitives to the handle to paint the pane.
+   *
+   * @throws When `id` names an existing host pane.
+   */
+  addPane(options: CustomPaneOptions = {}): PaneApi {
+    const state: CustomPaneState = {
+      id: options.id ?? `pane-${++this.paneSeq}`,
+      placement: options.placement ?? 'stacked',
+      weight: options.weight ?? 1,
+      width: options.width ?? DEFAULT_DOCK_WIDTH,
+      sharePriceScale: options.sharePriceScale ?? false,
+      autoscale: options.autoscale,
+      primitives: [],
+    };
+    if (this.customPanes.has(state.id)) throw new Error(`chart-ts: duplicate pane "${state.id}"`);
+    this.customPanes.set(state.id, state);
+    this.render();
+    const chart = this;
+    return {
+      id: state.id,
+      attachPrimitive(primitive) {
+        state.primitives.push(primitive);
+        chart.render();
+        return chart.primitiveHandle(state.primitives, primitive);
+      },
+      setWeight(weight) {
+        state.weight = weight;
+        chart.render();
+      },
+      setWidth(width) {
+        state.width = width;
+        chart.render();
+      },
+      remove() {
+        chart.removePane(state.id);
+      },
+    };
+  }
+
+  /** Removes a host pane added via {@link addPane}; returns whether it existed. */
+  removePane(id: string): boolean {
+    const removed = this.customPanes.delete(id);
+    if (removed) this.render();
+    return removed;
+  }
+
+  /** Attaches a custom draw pass to the main pane and re-renders. */
+  attachPrimitive(primitive: PanePrimitive): PanePrimitiveHandle {
+    this.mainPrimitives.push(primitive);
+    this.render();
+    return this.primitiveHandle(this.mainPrimitives, primitive);
+  }
+
+  private primitiveHandle(list: PanePrimitive[], primitive: PanePrimitive): PanePrimitiveHandle {
+    return {
+      detach: () => {
+        const index = list.indexOf(primitive);
+        if (index >= 0) {
+          list.splice(index, 1);
+          this.render();
+        }
+      },
+      requestUpdate: () => this.render(),
+    };
+  }
+
+  /** A host pane's price scale: the shared main range or its own autoscale (0–1 fallback). */
+  private customPaneScale(
+    state: CustomPaneState,
+    height: number,
+    range: VisibleRange,
+    candles: readonly Candle[],
+    shared: PriceScale | null,
+  ): PriceScale {
+    const scale = new PriceScale();
+    scale.height = height;
+    if (shared !== null) {
+      scale.mode = shared.mode;
+      scale.inverted = shared.inverted;
+      scale.basePrice = shared.basePrice;
+      scale.topMargin = shared.topMargin;
+      scale.bottomMargin = shared.bottomMargin;
+      scale.setRange(shared.minPrice, shared.maxPrice);
+    } else {
+      const mm = state.autoscale?.(range, candles) ?? null;
+      scale.setRange(mm?.min ?? 0, mm?.max ?? 1);
+    }
+    return scale;
+  }
+
   /**
    * Adds a drawing instance. Returns its id. Points pass through the
    * model's `normalize` hook (e.g. positions gain a default stop).
@@ -839,6 +1080,16 @@ export class Chart {
     indexToX: (index) => this.plotLeft + this.timeScale.indexToX(index, this.store.length),
     yToPrice: (y) => (this.mainPriceScale === null ? NaN : this.mainPriceScale.yToPrice(y)),
     priceToY: (price) => (this.mainPriceScale === null ? NaN : this.mainPriceScale.priceToY(price)),
+    scrollPrice: (dy) => {
+      const scale = this.mainPriceScale;
+      if (scale === null || scale.height <= 0 || dy === 0) return;
+      // Shift in scale units so log and percent axes pan evenly; the next render keeps the range while autoscale is off.
+      const lo = scale.toScale(scale.minPrice), hi = scale.toScale(scale.maxPrice);
+      const shift = (hi - lo) * dy / (scale.height * (1 - scale.topMargin - scale.bottomMargin)) * (scale.inverted ? -1 : 1);
+      scale.setRange(scale.fromScale(lo + shift), scale.fromScale(hi + shift));
+      if (this.config.priceAxis.autoScale) this.updateConfig({ priceAxis: { autoScale: false } });
+      else this.render();
+    },
     priceToBarRatio: () => {
       const scale = this.mainPriceScale;
       if (scale === null || scale.height <= 0) return 1;
@@ -978,6 +1229,10 @@ export class Chart {
   /** Tears down the chart; further renders become no-ops. */
   destroy(): void {
     this.destroyed = true;
+    this.inlineBook?.remove();
+    this.inlineBook = null;
+    this.heatmap?.remove();
+    this.heatmap = null;
     this.events.dispose();
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
@@ -985,8 +1240,11 @@ export class Chart {
     this.rangeAnimation?.clear();
     this.candleAnimation?.clear();
     this.store.clear();
+    this.depthBook = null;
     this.indicatorCache.clear();
     this.heikinAshi.clear();
+    this.customPanes.clear();
+    this.mainPrimitives.length = 0;
     this.lastView = null;
     this.crosshairView = null;
     if (this.crosshairCanvas !== null) {
@@ -997,6 +1255,36 @@ export class Chart {
     this.lastGeometry = [];
     this.lastIndicators = [];
     this.priceLineState.destroy();
+    this.glBackend?.dispose();
+    this.glBackend = null;
+  }
+
+  /**
+   * The effective render backend: `'webgl2'` only once a WebGL2 context was
+   * actually acquired (see {@link CreateChartOptions.renderer}), else `'canvas2d'`.
+   */
+  get renderBackend(): RenderBackend {
+    return this.glBackend !== null ? 'webgl2' : 'canvas2d';
+  }
+
+  /**
+   * Lazily builds the WebGL2 backend on an offscreen canvas from the injected
+   * DOM (the host canvas's `ownerDocument`, else the injected `ChartDocument`).
+   * Any failure is permanent for the chart's lifetime: the 2D path is kept.
+   */
+  private acquireGL(): GLBackend | null {
+    if (this.glBackend !== null || this.glFailed || !this.preferGL) return this.glBackend;
+    const ownerDocument = this.canvas.ownerDocument;
+    const glCanvas = ownerDocument?.createElement !== undefined
+      ? ownerDocument.createElement('canvas')
+      : this.snapshotDocument?.createCanvas(this.canvas.width, this.canvas.height);
+    const backend = glCanvas !== undefined ? GLBackend.create(glCanvas) : null;
+    if (backend === null) {
+      this.glFailed = true;
+      return null;
+    }
+    this.glBackend = backend;
+    return backend;
   }
 
   /** Full redraw. No-op after {@link destroy} or when no 2D context exists. */
@@ -1029,9 +1317,14 @@ export class Chart {
       ctx.restore();
     }
     axisWidth = Math.min(axisWidth, Math.max(0, cssWidth));
-    const plotWidth = Math.max(0, cssWidth - axisWidth);
+    const leftDocks = [...this.customPanes.values()].filter((pane) => pane.placement === 'left');
+    const rightDocks = [...this.customPanes.values()].filter((pane) => pane.placement === 'right');
+    const dockWidth = (pane: CustomPaneState): number => Math.max(0, pane.width);
+    const leftDockWidth = leftDocks.reduce((sum, pane) => sum + dockWidth(pane), 0);
+    const rightDockWidth = rightDocks.reduce((sum, pane) => sum + dockWidth(pane), 0);
+    const plotWidth = Math.max(0, cssWidth - axisWidth - leftDockWidth - rightDockWidth);
     const plotHeight = Math.max(0, cssHeight - (cfg.timeAxis.visible ? cfg.timeAxis.height : 0));
-    this.plotLeft = cfg.priceAxis.visible && cfg.priceAxis.position === 'left' ? axisWidth : 0;
+    this.plotLeft = leftDockWidth + (cfg.priceAxis.visible && cfg.priceAxis.position === 'left' ? axisWidth : 0);
     this.timeScale.setViewport(plotWidth);
 
     const candles = this.store.raw();
@@ -1070,8 +1363,11 @@ export class Chart {
     this.indicatorCache = nextCache;
     this.lastIndicators = computed;
 
-    // Pane specs: main + one sub-pane per sub indicator.
+    // Pane specs: main + stacked host panes + one sub-pane per sub indicator.
     const specs: PaneSpec[] = [{ id: 'main', kind: 'main', weight: MAIN_PANE_WEIGHT }];
+    for (const pane of this.customPanes.values()) {
+      if (pane.placement === 'stacked') specs.push({ id: pane.id, kind: 'custom', weight: pane.weight });
+    }
     for (const { cfg: indCfg, opacity } of computed) {
       if (indCfg.pane === 'sub') {
         specs.push({ id: indCfg.id, kind: 'indicator', weight: (cfg.indicatorPaneWeight > 0 ? cfg.indicatorPaneWeight : 1) * opacity });
@@ -1123,7 +1419,18 @@ export class Chart {
           if (Number.isFinite(lo) && Number.isFinite(hi)) priceScale.setRange(lo, hi);
         }
         panes.push({ layout, priceScale, indicators: mainIndicators.map((c) => c.output),
-          indicatorOpacities: mainIndicators.map((c) => c.opacity), indicatorLabels: mainIndicators.map((c) => c.labels) });
+          indicatorOpacities: mainIndicators.map((c) => c.opacity), indicatorLabels: mainIndicators.map((c) => c.labels),
+          ...(this.mainPrimitives.length > 0 ? { primitives: splitPrimitives(this.mainPrimitives) } : {}) });
+      } else if (layout.kind === 'custom') {
+        const state = this.customPanes.get(layout.id);
+        if (state === undefined) continue;
+        const shared = state.sharePriceScale ? panes[0]?.priceScale ?? null : null;
+        panes.push({
+          layout,
+          priceScale: this.customPaneScale(state, layout.height, range, candles, shared),
+          indicators: [],
+          primitives: splitPrimitives(state.primitives),
+        });
       } else {
         const subs = computed.filter((c) => c.cfg.id === layout.id);
         const subOutputs = subs.map((c) => c.output);
@@ -1232,6 +1539,40 @@ export class Chart {
       }
     }
 
+    // Host panes docked to the canvas edges, in absolute CSS pixels.
+    const dockedPanes: DockedPaneRenderInfo[] = [];
+    let leftX = 0;
+    for (const pane of leftDocks) {
+      const width = dockWidth(pane);
+      dockedPanes.push({
+        id: pane.id, placement: 'left', x: leftX, y: 0, width, height: plotHeight,
+        priceScale: this.customPaneScale(pane, plotHeight, range, candles, pane.sharePriceScale ? this.mainPriceScale : null),
+        primitives: splitPrimitives(pane.primitives),
+      });
+      leftX += width;
+    }
+    let rightX = cssWidth;
+    for (const pane of rightDocks) {
+      const width = dockWidth(pane);
+      rightX -= width;
+      dockedPanes.push({
+        id: pane.id, placement: 'right', x: rightX, y: 0, width, height: plotHeight,
+        priceScale: this.customPaneScale(pane, plotHeight, range, candles, pane.sharePriceScale ? this.mainPriceScale : null),
+        primitives: splitPrimitives(pane.primitives),
+      });
+    }
+
+    const seriesDraw = this.seriesRenderers.get(cfg.series.type);
+    // The WebGL2 backend renders the main pane's dense layers into an
+    // offscreen GL canvas that `renderChart` composites at the series layer.
+    let gl: GLFrame | undefined;
+    if (mainPane !== undefined) {
+      const backend = this.acquireGL();
+      if (backend !== null) {
+        backend.resize(this.canvas.width, this.canvas.height);
+        gl = backend.beginFrame(this.pixelRatio, plotWidth, mainPane.layout.height);
+      }
+    }
     const view: RenderView = {
       canvasWidth: cssWidth,
       canvasHeight: cssHeight,
@@ -1245,6 +1586,9 @@ export class Chart {
       range,
       timeScale: this.timeScale,
       panes,
+      ...(dockedPanes.length > 0 ? { dockedPanes } : {}),
+      ...(seriesDraw !== undefined ? { seriesDraw } : {}),
+      ...(gl !== undefined ? { gl } : {}),
       config: cfg,
       drawings: resolvedDrawings,
       crosshair: { active: this.crosshair.active, x: this.crosshair.x, y: this.crosshair.y },
diff --git a/packages/chart/src/core/depth.ts b/packages/chart/src/core/depth.ts
new file mode 100644
index 0000000..f7421d3
--- /dev/null
+++ b/packages/chart/src/core/depth.ts
@@ -0,0 +1,22 @@
+/**
+ * L2 order book model, held outside the candle store and updated through its
+ * own channel (`Chart.setDepth`), so every book change re-renders without
+ * touching the bar history.
+ *
+ * @module
+ */
+
+/** One price level of an order book side: `[price, size]`. */
+export type DepthLevel = readonly [price: number, size: number];
+
+/**
+ * An L2 order book: bids sorted best (highest) first, asks sorted best
+ * (lowest) first, every size positive. A zero-size level only appears in a
+ * diff, where it removes the price, never in the book itself.
+ */
+export interface DepthBook {
+  readonly bids: readonly DepthLevel[];
+  readonly asks: readonly DepthLevel[];
+  /** Wall clock in ms of the last applied update. */
+  readonly time: number;
+}
diff --git a/packages/chart/src/core/footprint.ts b/packages/chart/src/core/footprint.ts
new file mode 100644
index 0000000..0a7dd46
--- /dev/null
+++ b/packages/chart/src/core/footprint.ts
@@ -0,0 +1,130 @@
+/**
+ * Pure footprint math: per-level price bands inside a bar, the zoom
+ * level-of-detail pick, and per-candle delta aggregation over a footprint
+ * source. Rendering lives in `series/footprint.ts`; the delta and CVD
+ * sub-pane indicators in `indicators/delta.ts` and `indicators/cvd.ts`.
+ *
+ * @module
+ */
+
+import type { Candle } from './data.js';
+
+/** The level shape a footprint source serves (`FootprintLevel`-compatible). */
+export interface FootprintLevelLike {
+  readonly price: number;
+  readonly buySize: number;
+  readonly sellSize: number;
+}
+
+/** The bar shape a footprint source serves (`FootprintBar`-compatible). */
+export interface FootprintBarLike {
+  /** Bar open time in ms. */
+  readonly time: number;
+  /** Levels sorted by price ascending. */
+  readonly levels: readonly FootprintLevelLike[];
+  readonly buySize: number;
+  readonly sellSize: number;
+}
+
+/**
+ * A per-bar footprint lookup by ms timestamp. A `TradeAggregation` satisfies
+ * this directly; a `Datafeed` needs `datafeedFootprintSource` (its session
+ * replaces the store on every `setSymbol`, so a captured store would go stale).
+ */
+export interface FootprintSource {
+  /** The aggregated bar whose bucket contains `timeMs`, or null. */
+  bar(timeMs: number): FootprintBarLike | null;
+}
+
+/** What a footprint bar paints per level at the current zoom. */
+export type FootprintDisplay = 'bid-ask' | 'delta' | 'profile';
+
+/** The level of detail one footprint bar renders at. */
+export type FootprintLod = 'text' | 'bars' | 'delta';
+
+/** Pixel thresholds for {@link footprintLod}. */
+export interface FootprintLodThresholds {
+  /** Smallest row height that fits a bid×ask label. */
+  readonly textCellHeight: number;
+  /** Smallest bar width that fits a bid×ask label. */
+  readonly textBarWidth: number;
+  /** Smallest row height that fits a per-level bar; below it the bar collapses to delta coloring. */
+  readonly barCellHeight: number;
+}
+
+/** Default LOD thresholds in CSS pixels. */
+export const DEFAULT_FOOTPRINT_LOD: FootprintLodThresholds = { textCellHeight: 11, textBarWidth: 44, barCellHeight: 3 };
+
+/** One level's price band: midpoints toward the neighbors, half a step past the edges. */
+export interface FootprintBand {
+  readonly price: number;
+  readonly low: number;
+  readonly high: number;
+}
+
+/** Smallest positive gap between adjacent level prices; the fallback step for a single level. */
+function minGap(levels: readonly FootprintLevelLike[]): number | null {
+  let gap = Infinity;
+  for (let i = 1; i < levels.length; i++) {
+    const d = levels[i]!.price - levels[i - 1]!.price;
+    if (d > 0 && d < gap) gap = d;
+  }
+  return gap === Infinity ? null : gap;
+}
+
+/**
+ * Price bands of a footprint bar's levels (ascending). A band reaches the
+ * midpoint toward each neighbor, so a gap between traded prices widens the
+ * cells beside it instead of leaving dead space; edge levels extend half
+ * their own step (`fallback` for a single level). Levels with a non-finite
+ * price are dropped.
+ */
+export function footprintBands(levels: readonly FootprintLevelLike[]): FootprintBand[] {
+  const taken = levels.filter((level) => Number.isFinite(level.price));
+  const fallback = minGap(taken) ?? 1;
+  const bands: FootprintBand[] = [];
+  for (let i = 0; i < taken.length; i++) {
+    const price = taken[i]!.price;
+    const next = i + 1 < taken.length ? taken[i + 1]!.price - price : NaN;
+    const prev = i > 0 ? price - taken[i - 1]!.price : NaN;
+    const step = Number.isFinite(next) && next > 0 ? next : Number.isFinite(prev) && prev > 0 ? prev : fallback;
+    bands.push({
+      price,
+      low: i === 0 ? price - step / 2 : (taken[i - 1]!.price + price) / 2,
+      high: i === taken.length - 1 ? price + step / 2 : (price + taken[i + 1]!.price) / 2,
+    });
+  }
+  return bands;
+}
+
+/**
+ * The detail one bar renders at: a bid×ask label per level when the cells fit
+ * the text (`'bid-ask'` display only), per-level bars while rows stay visible,
+ * else a single column colored by the bar's delta.
+ */
+export function footprintLod(
+  barWidthPx: number,
+  cellHeightPx: number,
+  display: FootprintDisplay,
+  thresholds: FootprintLodThresholds = DEFAULT_FOOTPRINT_LOD,
+): FootprintLod {
+  if (display === 'bid-ask' && cellHeightPx >= thresholds.textCellHeight && barWidthPx >= thresholds.textBarWidth) return 'text';
+  if (cellHeightPx >= thresholds.barCellHeight) return 'bars';
+  return 'delta';
+}
+
+/** A footprint bar's traded delta: buy (ask-side) size minus sell (bid-side) size. */
+export function barDelta(bar: FootprintBarLike): number {
+  return bar.buySize - bar.sellSize;
+}
+
+/** A candle's traded delta from `source` (candle times are seconds, the source buckets in ms); no footprint bar counts 0. */
+export function candleDelta(candle: Candle, source: FootprintSource): number {
+  const bar = source.bar(candle.time * 1000);
+  return bar === null ? 0 : barDelta(bar);
+}
+
+/** Per-candle traded deltas, one per candle, in candle order. */
+export function candleDeltas(candles: readonly Candle[], source: FootprintSource): number[] {
+  return candles.map((candle) => candleDelta(candle, source));
+}
diff --git a/packages/chart/src/core/heatmap.ts b/packages/chart/src/core/heatmap.ts
new file mode 100644
index 0000000..b835157
--- /dev/null
+++ b/packages/chart/src/core/heatmap.ts
@@ -0,0 +1,195 @@
+/**
+ * Depth history for the liquidity heatmap: a bounded window of time-bucketed
+ * book snapshots plus the pure math the renderer needs (bucket placement on
+ * the time axis, intensity normalization). Rendering lives in
+ * `render/heatmap.ts`; the snapshots are plain data so a later WebGL2 pass
+ * can consume the same window.
+ *
+ * @module
+ */
+
+import type { Candle } from './data.js';
+import type { DepthBook, DepthLevel } from './depth.js';
+
+/** Default wall-clock bucket width: at most one retained snapshot per second. */
+export const DEFAULT_HEATMAP_BUCKET_MS = 1000;
+
+/** Default retained buckets; at 1s buckets about eight minutes of book history. */
+export const DEFAULT_HEATMAP_MAX_BUCKETS = 500;
+
+/** Default levels kept per side per snapshot (best-first). */
+export const DEFAULT_HEATMAP_MAX_LEVELS = 50;
+
+/** Default ramp color at zero intensity. */
+export const DEFAULT_HEATMAP_COLOR_LOW = '#2962ff';
+
+/** Default ramp color at full intensity. */
+export const DEFAULT_HEATMAP_COLOR_HIGH = '#ffd54f';
+
+/** Default peak cell alpha at full intensity. */
+export const DEFAULT_HEATMAP_OPACITY = 0.85;
+
+/** Default cell alpha at zero intensity (the ramp fades out entirely). */
+export const DEFAULT_HEATMAP_MIN_OPACITY = 0;
+
+/**
+ * One color stop of a custom heatmap gradient. A bare color string is placed
+ * evenly by its index among the stops; `at` pins a stop to an intensity (0-1).
+ * A stop color's own alpha scales the ramp's alpha there, so `rgba(...)`
+ * stops can fade parts of the gradient.
+ */
+export type HeatmapStop = string | { readonly color: string; readonly at?: number };
+
+/** Default intensity curve exponent; below 1 lifts small sizes (sqrt by default). */
+export const DEFAULT_HEATMAP_GAMMA = 0.5;
+
+/** One time bucket of the depth history: the newest book of the bucket, trimmed. */
+export interface HeatmapSnapshot {
+  /** Bucket start, wall clock ms (`floor(time / bucketMs) * bucketMs`). */
+  readonly time: number;
+  /** Bid levels, best (highest) first, trimmed to the history's `maxLevels`. */
+  readonly bids: readonly DepthLevel[];
+  /** Ask levels, best (lowest) first, trimmed to the history's `maxLevels`. */
+  readonly asks: readonly DepthLevel[];
+}
+
+/**
+ * A bounded FIFO window of time-bucketed book snapshots. `record` buckets a
+ * book by wall clock (`book.time`), keeps the newest book of each bucket, and
+ * evicts the oldest bucket past `maxBuckets`, so memory stays at roughly
+ * `maxBuckets` × 2 × `maxLevels` level pairs (~50k pairs, well under a
+ * megabyte of numbers, with the defaults). Repeat deliveries of one book
+ * (same `book.time`, e.g. re-renders that did not change the book) and
+ * out-of-order books are ignored.
+ */
+export class DepthHistory {
+  /** Wall-clock bucket width in ms. Applies to newly recorded books; retained buckets keep their original grid. */
+  bucketMs: number;
+  /** Window capacity in buckets; shrinking it evicts the oldest buckets. */
+  maxBuckets: number;
+  /** Levels kept per side per snapshot. Applies to newly recorded books. */
+  maxLevels: number;
+  private snapshots: HeatmapSnapshot[] = [];
+  /** `book.time` of the last recorded book. */
+  private lastBookTime = -Infinity;
+
+  constructor(options: { bucketMs?: number; maxBuckets?: number; maxLevels?: number } = {}) {
+    this.bucketMs = Math.max(1, Math.floor(options.bucketMs ?? DEFAULT_HEATMAP_BUCKET_MS));
+    this.maxBuckets = Math.max(1, Math.floor(options.maxBuckets ?? DEFAULT_HEATMAP_MAX_BUCKETS));
+    this.maxLevels = Math.max(1, Math.floor(options.maxLevels ?? DEFAULT_HEATMAP_MAX_LEVELS));
+  }
+
+  /** Retained bucket count. */
+  get length(): number {
+    return this.snapshots.length;
+  }
+
+  /** Bucket `index`, oldest first; undefined outside the window. */
+  at(index: number): HeatmapSnapshot | undefined {
+    return this.snapshots[index];
+  }
+
+  /** Start of the bucket containing `timeMs`. */
+  bucketStart(timeMs: number): number {
+    return Math.floor(timeMs / this.bucketMs) * this.bucketMs;
+  }
+
+  /** Index of the first bucket starting at or after `timeMs` (the length when none is). */
+  firstAtOrAfter(timeMs: number): number {
+    let lo = 0;
+    let hi = this.snapshots.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >>> 1;
+      if (this.snapshots[mid]!.time < timeMs) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+
+  /**
+   * Folds `book` into its time bucket, replacing the bucket's previous
+   * snapshot when the book is newer. Returns whether the window changed.
+   */
+  record(book: DepthBook | null): boolean {
+    if (book === null || !Number.isFinite(book.time) || book.time <= this.lastBookTime) return false;
+    const start = this.bucketStart(book.time);
+    const last = this.snapshots[this.snapshots.length - 1];
+    if (last !== undefined && start < last.time) return false;
+    const bids = trimLevels(book.bids, this.maxLevels);
+    const asks = trimLevels(book.asks, this.maxLevels);
+    if (last !== undefined && last.time === start) {
+      this.snapshots[this.snapshots.length - 1] = { time: start, bids, asks };
+    } else {
+      this.snapshots.push({ time: start, bids, asks });
+      while (this.snapshots.length > this.maxBuckets) this.snapshots.shift();
+    }
+    this.lastBookTime = book.time;
+    return true;
+  }
+
+  /** Applies new grid knobs to future records; shrinking `maxBuckets` evicts the oldest buckets now. */
+  configure(options: { bucketMs?: number; maxBuckets?: number; maxLevels?: number }): void {
+    if (options.bucketMs !== undefined) this.bucketMs = Math.max(1, Math.floor(options.bucketMs));
+    if (options.maxBuckets !== undefined) this.maxBuckets = Math.max(1, Math.floor(options.maxBuckets));
+    if (options.maxLevels !== undefined) this.maxLevels = Math.max(1, Math.floor(options.maxLevels));
+    while (this.snapshots.length > this.maxBuckets) this.snapshots.shift();
+  }
+
+  /** Drops all retained buckets. */
+  clear(): void {
+    this.snapshots = [];
+    this.lastBookTime = -Infinity;
+  }
+}
+
+/** Best-first valid levels (finite price, positive size), copied and capped. */
+function trimLevels(levels: readonly DepthLevel[], maxLevels: number): DepthLevel[] {
+  const out: DepthLevel[] = [];
+  for (const [price, size] of levels) {
+    if (out.length >= maxLevels) break;
+    if (Number.isFinite(price) && Number.isFinite(size) && size > 0) out.push([price, size]);
+  }
+  return out;
+}
+
+/**
+ * Intensity 0-1 of one level: `(size / max)^gamma`, clamped. Zero when the
+ * level or the normalizer is not positive.
+ */
+export function heatmapIntensity(size: number, max: number, gamma: number): number {
+  if (!(size > 0) || !(max > 0)) return 0;
+  return Math.min(1, size / max) ** Math.max(0.05, gamma);
+}
+
+/**
+ * Fractional position of a wall-clock time on the time axis: a fractional
+ * bar index in bar-indexed mode (`slots` null), or a fractional slot on a
+ * continuous axis, linear in candle time between neighbors (so a gap between
+ * two candles spans its full slot count). Past the last candle the position
+ * extrapolates along the last interval; before the first candle it is null
+ * (off the data's left edge). Convert with
+ * `width - (lastUnit - position - scrollOffset) * barSpacing - barSpacing / 2`.
+ */
+export function heatPosition(candles: readonly Candle[], slots: ArrayLike<number> | null, timeMs: number): number | null {
+  const n = candles.length;
+  if (n === 0) return null;
+  const t = timeMs / 1000;
+  if (t < candles[0]!.time) return null;
+  let lo = 0;
+  let hi = n - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (candles[mid]!.time <= t) lo = mid;
+    else hi = mid - 1;
+  }
+  if (lo === n - 1) {
+    const interval = n > 1 ? candles[n - 1]!.time - candles[n - 2]!.time : 0;
+    const extra = interval > 0 ? (t - candles[lo]!.time) / interval : 0;
+    // Past the data the axis lays out one slot per bar interval.
+    return slots === null ? lo + extra : slots[lo]! + extra;
+  }
+  const t0 = candles[lo]!.time;
+  const t1 = candles[lo + 1]!.time;
+  const frac = t1 > t0 ? (t - t0) / (t1 - t0) : 0;
+  return slots === null ? lo + frac : slots[lo]! + frac * (slots[lo + 1]! - slots[lo]!);
+}
diff --git a/packages/chart/src/core/inline-book.ts b/packages/chart/src/core/inline-book.ts
new file mode 100644
index 0000000..91a1349
--- /dev/null
+++ b/packages/chart/src/core/inline-book.ts
@@ -0,0 +1,120 @@
+/**
+ * Pure math for the inline order book: trimming a maintained L2 book to the
+ * visible ladder, cumulative depth per level, per-row price bands and the
+ * hover lookup. Rendering lives in `render/inline-book.ts`.
+ *
+ * @module
+ */
+
+import type { DepthBook, DepthLevel } from './depth.js';
+
+/** Levels shown per side of the ladder by default. */
+export const DEFAULT_INLINE_BOOK_MAX_LEVELS = 16;
+
+/** Default bid color: the `'up'` token, following the theme's `series.upColor`. */
+export const DEFAULT_INLINE_BOOK_BID_COLOR = 'up';
+
+/** Default ask color: the `'down'` token, following the theme's `series.downColor`. */
+export const DEFAULT_INLINE_BOOK_ASK_COLOR = 'down';
+
+/** Default width in CSS pixels of the docked inline book pane. */
+export const DEFAULT_INLINE_BOOK_WIDTH = 96;
+
+/** One ladder row: a book level with its cumulative depth and price band. */
+export interface InlineBookRow {
+  readonly price: number;
+  readonly size: number;
+  /** Total size from the best level through this row. */
+  readonly cumulative: number;
+  /** Lower price boundary of the row's band. */
+  readonly low: number;
+  /** Upper price boundary of the row's band. */
+  readonly high: number;
+}
+
+/** One side of the ladder, best-first. */
+export interface InlineBookSide {
+  readonly rows: readonly InlineBookRow[];
+  /** Largest single-level size; sizes normalize against it for bar widths. */
+  readonly maxSize: number;
+  /** Total size of the shown levels; cumulative depth normalizes against it. */
+  readonly maxCumulative: number;
+}
+
+/** A trimmed book ladder; see {@link computeInlineBookRows}. */
+export interface InlineBookRows {
+  readonly bids: InlineBookSide;
+  readonly asks: InlineBookSide;
+  readonly bestBid: number | null;
+  readonly bestAsk: number | null;
+  /** `bestAsk - bestBid`; null unless both sides have a level. */
+  readonly spread: number | null;
+}
+
+/** Smallest positive gap between adjacent levels of both sides; the fallback step for ragged books. */
+function minGap(book: DepthBook): number | null {
+  let gap = Infinity;
+  for (const side of [book.bids, book.asks]) {
+    for (let i = 1; i < side.length; i++) {
+      const d = Math.abs(side[i]![0] - side[i - 1]![0]);
+      if (d > 0 && d < gap) gap = d;
+    }
+  }
+  return gap === Infinity ? null : gap;
+}
+
+/**
+ * Rows of one side, best-first. `outward` is 1 for asks (prices rise away
+ * from the spread) and -1 for bids. A row's band reaches the midpoint toward
+ * each neighbor; edge rows extend half their own step (`fallback` when the
+ * side has a single level). Levels with a non-finite price or size, or a
+ * non-positive size, are dropped.
+ */
+function sideRows(levels: readonly DepthLevel[], maxLevels: number, outward: 1 | -1, fallback: number): InlineBookSide {
+  const taken = levels.filter(([p, s]) => Number.isFinite(p) && Number.isFinite(s) && s > 0).slice(0, maxLevels);
+  const rows: InlineBookRow[] = [];
+  let cumulative = 0;
+  let maxSize = 0;
+  for (let i = 0; i < taken.length; i++) {
+    const [price, size] = taken[i]!;
+    const next = i + 1 < taken.length ? (taken[i + 1]![0] - price) * outward : NaN;
+    const prev = i > 0 ? (price - taken[i - 1]![0]) * outward : NaN;
+    const step = Number.isFinite(next) && next > 0 ? next : Number.isFinite(prev) && prev > 0 ? prev : fallback;
+    const outer = price + (outward * step) / 2;
+    const inner = i === 0 ? price - (outward * step) / 2 : (taken[i - 1]![0] + price) / 2;
+    cumulative += size;
+    if (size > maxSize) maxSize = size;
+    rows.push({ price, size, cumulative, low: Math.min(inner, outer), high: Math.max(inner, outer) });
+  }
+  return { rows, maxSize, maxCumulative: cumulative };
+}
+
+/**
+ * Trims `book` to `maxLevels` per side and prices every row's band. A row
+ * reaches the midpoint toward each neighbor, so a gap between levels widens
+ * the rows beside it instead of leaving dead space; the best rows extend half
+ * a step into the spread. `maxLevels` clamps to a positive integer.
+ */
+export function computeInlineBookRows(book: DepthBook, maxLevels: number): InlineBookRows {
+  const levels = Math.max(1, Math.floor(maxLevels));
+  const step = minGap(book) ?? 1;
+  const bids = sideRows(book.bids, levels, -1, step);
+  const asks = sideRows(book.asks, levels, 1, step);
+  const bestBid = bids.rows[0]?.price ?? null;
+  const bestAsk = asks.rows[0]?.price ?? null;
+  return {
+    bids,
+    asks,
+    bestBid,
+    bestAsk,
+    spread: bestBid !== null && bestAsk !== null ? bestAsk - bestBid : null,
+  };
+}
+
+/** The row whose band contains `price`, or null when the side does not cover it. */
+export function inlineBookRowAt(side: InlineBookSide, price: number): InlineBookRow | null {
+  for (const row of side.rows) {
+    if (price >= row.low && price <= row.high) return row;
+  }
+  return null;
+}
diff --git a/packages/chart/src/core/pane.ts b/packages/chart/src/core/pane.ts
index 0800e7f..eca112a 100644
--- a/packages/chart/src/core/pane.ts
+++ b/packages/chart/src/core/pane.ts
@@ -7,7 +7,8 @@
 /** A pane before pixel layout. */
 export interface PaneSpec {
   readonly id: string;
-  readonly kind: 'main' | 'indicator';
+  /** `main` is the price pane, `indicator` a study sub-pane, `custom` a host pane from `Chart.addPane`. */
+  readonly kind: 'main' | 'indicator' | 'custom';
   readonly weight: number;
 }
 
diff --git a/packages/chart/src/core/profile.ts b/packages/chart/src/core/profile.ts
new file mode 100644
index 0000000..c3dcc0d
--- /dev/null
+++ b/packages/chart/src/core/profile.ts
@@ -0,0 +1,270 @@
+/**
+ * Volume-at-price and TPO (time-at-price) profile math shared by the fixed
+ * range volume profile drawing and the session profile pane. Profiles bin a
+ * bar range into price rows, find the point of control (POC) and grow a value
+ * area around it.
+ *
+ * @module
+ */
+
+import type { Candle } from './data.js';
+
+/** Point of control and value-area row bounds of a profile. */
+export interface ValueArea {
+  /** Row with the most volume/TPO (point of control). */
+  readonly poc: number;
+  /** Lowest row inside the value area. */
+  readonly low: number;
+  /** Highest row inside the value area. */
+  readonly high: number;
+}
+
+/** A price-row profile over a bar range. */
+export interface PriceProfile {
+  /** Lowest price of the profiled bars. */
+  readonly lo: number;
+  /** Highest price of the profiled bars. */
+  readonly hi: number;
+  /** Number of price rows. */
+  readonly rows: number;
+  /** Price height of one row. */
+  readonly step: number;
+  /** Total per row (volume, or TPO count). */
+  readonly totals: readonly number[];
+  /** Point of control row index. */
+  readonly poc: number;
+  /** Value-area low row index. */
+  readonly valueAreaLow: number;
+  /** Value-area high row index. */
+  readonly valueAreaHigh: number;
+  /** Mid-price of the POC row. */
+  readonly pocPrice: number;
+  /** Bottom price of the value area. */
+  readonly valueAreaLowPrice: number;
+  /** Top price of the value area. */
+  readonly valueAreaHighPrice: number;
+}
+
+/** A volume profile: per-row totals split by bar direction. */
+export interface VolumeProfile extends PriceProfile {
+  /** Rising-bar volume per row. */
+  readonly up: readonly number[];
+  /** Falling-bar volume per row. */
+  readonly down: readonly number[];
+}
+
+/** A run of consecutive bars belonging to one session. */
+export interface SessionRange {
+  /** Session bucket index: `floor(time_ms / sessionMs)`. */
+  readonly session: number;
+  /** First bar index (inclusive). */
+  readonly from: number;
+  /** Last bar index (inclusive). */
+  readonly to: number;
+  /** Session start as a UNIX timestamp in seconds. */
+  readonly start: number;
+}
+
+/** Fraction of volume/TPO the value area covers by default. */
+export const DEFAULT_VALUE_AREA_PERCENT = 0.7;
+
+/** Default session length: one day in milliseconds. */
+export const DEFAULT_SESSION_MS = 86_400_000;
+
+/** Row index containing `price`, clamped to `0..rows-1`. */
+export function profileRowAt(lo: number, step: number, rows: number, price: number): number {
+  return Math.min(rows - 1, Math.max(0, Math.floor((price - lo) / step)));
+}
+
+function bounds(candles: readonly Candle[], from: number, to: number, rows: number): { start: number; end: number; lo: number; hi: number; step: number } | null {
+  if (rows <= 0 || candles.length === 0) return null;
+  const start = Math.max(0, Math.min(from, to));
+  const end = Math.min(candles.length - 1, Math.max(from, to));
+  if (end < start) return null;
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let i = start; i <= end; i++) {
+    lo = Math.min(lo, candles[i]!.low);
+    hi = Math.max(hi, candles[i]!.high);
+  }
+  return { start, end, lo, hi, step: (hi - lo) / rows || 1 };
+}
+
+/**
+ * Per-row up/down volume for bars in `[from, to]`, spread uniformly over each
+ * bar's range; `null` for an empty range.
+ */
+export function volumeProfileRows(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  rows: number,
+): { lo: number; hi: number; up: number[]; down: number[] } | null {
+  const b = bounds(candles, from, to, rows);
+  if (!b) return null;
+  const up = new Array<number>(rows).fill(0);
+  const down = new Array<number>(rows).fill(0);
+  for (let i = b.start; i <= b.end; i++) {
+    const c = candles[i]!;
+    const r0 = profileRowAt(b.lo, b.step, rows, c.low);
+    const r1 = profileRowAt(b.lo, b.step, rows, c.high);
+    const share = (c.volume ?? 0) / (r1 - r0 + 1);
+    for (let r = r0; r <= r1; r++) (c.close >= c.open ? up : down)[r]! += share;
+  }
+  return { lo: b.lo, hi: b.hi, up, down };
+}
+
+/**
+ * Per-row TPO count for bars in `[from, to]`: one count per bar whose range
+ * covers the row; `null` for an empty range.
+ */
+export function tpoProfileRows(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  rows: number,
+): { lo: number; hi: number; counts: number[] } | null {
+  const b = bounds(candles, from, to, rows);
+  if (!b) return null;
+  const counts = new Array<number>(rows).fill(0);
+  for (let i = b.start; i <= b.end; i++) {
+    const c = candles[i]!;
+    const r0 = profileRowAt(b.lo, b.step, rows, c.low);
+    const r1 = profileRowAt(b.lo, b.step, rows, c.high);
+    for (let r = r0; r <= r1; r++) counts[r]! += 1;
+  }
+  return { lo: b.lo, hi: b.hi, counts };
+}
+
+/**
+ * Point of control (first row with the highest total) and the value area that
+ * grows from it until `percent` of the grand total is covered.
+ */
+export function valueArea(totals: readonly number[], percent = DEFAULT_VALUE_AREA_PERCENT): ValueArea {
+  let poc = 0;
+  for (let i = 1; i < totals.length; i++) if (totals[i]! > totals[poc]!) poc = i;
+  const sum = totals.reduce((s, x) => s + x, 0);
+  let low = poc;
+  let high = poc;
+  let acc = totals[poc] ?? 0;
+  while (acc < sum * percent && (low > 0 || high < totals.length - 1)) {
+    const below = low > 0 ? totals[low - 1]! : -1;
+    const above = high < totals.length - 1 ? totals[high + 1]! : -1;
+    if (above >= below) acc += totals[++high]!;
+    else acc += totals[--low]!;
+  }
+  return { poc, low, high };
+}
+
+function finishProfile(lo: number, hi: number, rows: number, totals: readonly number[], percent: number): PriceProfile {
+  const step = (hi - lo) / rows || 1;
+  const va = valueArea(totals, percent);
+  return {
+    lo,
+    hi,
+    rows,
+    step,
+    totals,
+    poc: va.poc,
+    valueAreaLow: va.low,
+    valueAreaHigh: va.high,
+    pocPrice: lo + step * (va.poc + 0.5),
+    valueAreaLowPrice: lo + step * va.low,
+    valueAreaHighPrice: lo + step * (va.high + 1),
+  };
+}
+
+/** Volume profile over bars `[from, to]` with POC and value area; `null` for an empty range. */
+export function computeVolumeProfile(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  rows: number,
+  valueAreaPercent = DEFAULT_VALUE_AREA_PERCENT,
+): VolumeProfile | null {
+  const prof = volumeProfileRows(candles, from, to, rows);
+  if (!prof) return null;
+  const totals = prof.up.map((u, i) => u + prof.down[i]!);
+  return { ...finishProfile(prof.lo, prof.hi, rows, totals, valueAreaPercent), up: prof.up, down: prof.down };
+}
+
+/** TPO profile over bars `[from, to]` with POC and value area; `null` for an empty range. */
+export function computeTpoProfile(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  rows: number,
+  valueAreaPercent = DEFAULT_VALUE_AREA_PERCENT,
+): PriceProfile | null {
+  const prof = tpoProfileRows(candles, from, to, rows);
+  if (!prof) return null;
+  return finishProfile(prof.lo, prof.hi, rows, prof.counts, valueAreaPercent);
+}
+
+/**
+ * Consecutive bar runs of `[from, to]` grouped into sessions of `sessionMs`
+ * milliseconds, bucketed by `floor(time / sessionMs)` in UTC.
+ */
+export function sessionRanges(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  sessionMs = DEFAULT_SESSION_MS,
+): SessionRange[] {
+  const start = Math.max(0, Math.min(from, to));
+  const end = Math.min(candles.length - 1, Math.max(from, to));
+  const ranges: SessionRange[] = [];
+  let current: { session: number; from: number; to: number; start: number } | null = null;
+  for (let i = start; i <= end; i++) {
+    const session = Math.floor((candles[i]!.time * 1000) / sessionMs);
+    if (current && current.session === session) {
+      current.to = i;
+    } else {
+      current = { session, from: i, to: i, start: (session * sessionMs) / 1000 };
+      ranges.push(current);
+    }
+  }
+  return ranges;
+}
+
+/**
+ * A round profile row step at or above `raw`: 1, 2, 2.5 or 5 times a power of ten,
+ * so profile rows land on round prices. Non-positive or non-finite input gives 1.
+ */
+export function profileStep(raw: number): number {
+  if (!(raw > 0) || !Number.isFinite(raw)) return 1;
+  const p = 10 ** Math.floor(Math.log10(raw));
+  const m = raw / p;
+  return (m <= 1 ? 1 : m <= 2 ? 2 : m <= 2.5 ? 2.5 : m <= 5 ? 5 : 10) * p;
+}
+
+/**
+ * Up/down volume of bars `[from, to]` (inclusive, clamped to the data) on a
+ * fixed price grid: `rows` rows of `step` from `lo`. Each bar's volume is
+ * spread evenly over every grid row its low–high range touches, including
+ * rows off the grid, so a bar reaching past the grid keeps only its on-grid
+ * share. Up bars (`close >= open`) fill `up`, the rest `down`.
+ */
+export function gridVolumeRows(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  lo: number,
+  step: number,
+  rows: number,
+): { up: number[]; down: number[] } {
+  const up = new Array<number>(rows).fill(0);
+  const down = new Array<number>(rows).fill(0);
+  const start = Math.max(0, from);
+  const end = Math.min(candles.length - 1, to);
+  for (let i = start; i <= end; i++) {
+    const c = candles[i]!;
+    const r0 = Math.floor((c.low - lo) / step);
+    const r1 = Math.floor((c.high - lo) / step);
+    if (!(r1 >= 0 && r0 < rows)) continue; // off the grid, or a NaN extreme
+    const share = (c.volume ?? 0) / (r1 - r0 + 1);
+    const side = c.close >= c.open ? up : down;
+    for (let r = Math.max(0, r0); r <= Math.min(rows - 1, r1); r++) side[r]! += share;
+  }
+  return { up, down };
+}
diff --git a/packages/chart/src/core/trade.ts b/packages/chart/src/core/trade.ts
new file mode 100644
index 0000000..ae62447
--- /dev/null
+++ b/packages/chart/src/core/trade.ts
@@ -0,0 +1,21 @@
+/**
+ * The tape record: one executed trade (price, size, aggressor side). Trades
+ * stream through their own datafeed channel (`pushTrade` / `subscribeTrades`)
+ * and aggregate outside the candle store for footprint use.
+ *
+ * @module
+ */
+
+/** The aggressor side of a trade: a `'buy'` lifted the ask, a `'sell'` hit the bid. */
+export type TradeSide = 'buy' | 'sell';
+
+/**
+ * One executed trade. `time` is wall clock in ms, matching the depth channel;
+ * candle `time` stays in UNIX seconds.
+ */
+export interface Trade {
+  readonly time: number;
+  readonly price: number;
+  readonly size: number;
+  readonly side: TradeSide;
+}
diff --git a/packages/chart/src/datafeed/datafeed-chart.ts b/packages/chart/src/datafeed/datafeed-chart.ts
index e17003b..5370e77 100644
--- a/packages/chart/src/datafeed/datafeed-chart.ts
+++ b/packages/chart/src/datafeed/datafeed-chart.ts
@@ -11,10 +11,15 @@
 
 import { createChart, type Chart, type CreateChartOptions } from '../core/chart.js';
 import type { Candle } from '../core/data.js';
+import type { DepthBook } from '../core/depth.js';
+import type { FootprintSource } from '../core/footprint.js';
 import { Emitter, type VisibleRangeChangeEvent } from '../core/events.js';
+import type { Trade } from '../core/trade.js';
 import type { FrameScheduler } from '../core/zoom.js';
 import { createAbortController, type AbortControllerLike, type DatafeedSignal } from './abort.js';
+import { createDepthBookManager, type DepthBookManager, type DepthDelta, type DepthSnapshot } from './depth-book.js';
 import { createLiveBarFolder, type FetchGap, type LiveBarFolder } from './live-bar-folder.js';
+import { createTradeAggregation, type FootprintBar, type TradeAggregation } from './trade-aggregation.js';
 import { barsInWindow, loadHistory, pageHistory, type FetchBars, type HistoryRead, type LoadHistoryOptions } from './pagination.js';
 
 /** Bars loaded by `setSymbol`: bloxwap.pro's `HISTORY_BARS`. */
@@ -49,6 +54,20 @@ export interface DatafeedGapRequest {
  */
 export type DatafeedFetchGap = (fromMs: number, toMs: number, request: DatafeedGapRequest) => Promise<readonly Candle[]>;
 
+/** Context handed to a {@link DatafeedFetchDepthSnapshot}. */
+export interface DatafeedDepthRequest {
+  readonly symbol: string;
+  /** Aborted when the symbol or interval changes, or the datafeed is destroyed. */
+  readonly signal: DatafeedSignal;
+}
+
+/**
+ * L2 book snapshot read for `request.symbol`: the initial load of the depth
+ * channel and every sequence-gap resync. The stream of diff-depth events goes
+ * to `Datafeed.pushDepth`.
+ */
+export type DatafeedFetchDepthSnapshot = (request: DatafeedDepthRequest) => Promise<DepthSnapshot>;
+
 /** Options for {@link attachDatafeed}. */
 export interface DatafeedOptions {
   /** Symbol to load right away (together with `intervalMs`). */
@@ -59,6 +78,16 @@ export interface DatafeedOptions {
   fetchBars: FetchBars;
   /** Gap repair for live folding. Default: `fetchBars` over the gap. */
   fetchGap?: DatafeedFetchGap;
+  /**
+   * L2 book snapshot source. Given, the datafeed maintains a depth book for
+   * the current symbol, stored outside the candle store: `pushDepth` folds
+   * Binance-style diff-depth events into it (snapshot load, then deltas, with
+   * sequence-gap resync and the same retry backoff as history reads), every
+   * book update re-renders through `chart.setDepth`, and `subscribeDepth`
+   * listeners receive it. Without it `pushDepth` is ignored and
+   * `subscribeDepth` never fires.
+   */
+  fetchDepthSnapshot?: DatafeedFetchDepthSnapshot;
   /** Bars loaded by `setSymbol` (a positive integer). Default {@link DEFAULT_INITIAL_BARS}. */
   initialBars?: number;
   /** Bars per lazy history page (a positive integer). Default {@link DEFAULT_PAGE_BARS}. */
@@ -156,6 +185,38 @@ export interface Datafeed extends DatafeedState {
    * batched `scheduler` frame, which that frame throws.
    */
   pushTick(price: number, symbol?: string): void;
+  /**
+   * Folds one diff-depth event into the current symbol's maintained L2 book.
+   * Ignored without `fetchDepthSnapshot`, and when `symbol` is given but is
+   * not the current one. Events arriving before the snapshot are buffered; a
+   * sequence gap resyncs from a fresh snapshot. Errors from publishing the
+   * book go to `onError`.
+   */
+  pushDepth(delta: DepthDelta, symbol?: string): void;
+  /**
+   * Calls `onBook` with each maintained L2 book of `symbol`: the snapshot
+   * first, then every applied delta. Books flow only while `symbol` is the
+   * current one. Returns an unsubscribe function.
+   */
+  subscribeDepth(symbol: string, onBook: (book: DepthBook) => void): () => void;
+  /**
+   * Folds one executed trade into the current session's footprint store and
+   * delivers it to `subscribeTrades` listeners. Ignored before the first
+   * `setSymbol`, and when `symbol` is given but is not the current one. The
+   * tape channel passes the trade through as received; the footprint store
+   * drops an invalid one (non-finite time, price or size, non-positive size).
+   * A trade listener's error goes to `onError`; `pushTrade` never throws.
+   */
+  pushTrade(trade: Trade, symbol?: string): void;
+  /**
+   * Calls `onTrade` with each trade pushed for `symbol`. Trades flow only
+   * while `symbol` is the current one. Returns an unsubscribe function.
+   */
+  subscribeTrades(symbol: string, onTrade: (trade: Trade) => void): () => void;
+  /** The current session's footprint bar whose bucket contains `timeMs`, or null. */
+  footprintBar(timeMs: number): FootprintBar | null;
+  /** The current session's footprint bars opening within `[fromMs, toMs]`, oldest first. */
+  footprintBars(fromMs: number, toMs: number): FootprintBar[];
   /** Calls `listener` with each new state. Returns an unsubscribe function. */
   subscribeState(listener: (state: DatafeedState) => void): () => void;
   /** Aborts every read, stops live folding and detaches from the chart (which stays alive). */
@@ -179,6 +240,10 @@ interface Session {
   readonly intervalMs: number;
   readonly controller: AbortControllerLike;
   folder: LiveBarFolder | null;
+  /** The symbol's maintained L2 book, or null without `fetchDepthSnapshot`. */
+  depth: DepthBookManager | null;
+  /** The symbol's (bar, price) trade aggregation, fed by `pushTrade`. */
+  tape: TradeAggregation;
   inflight: Promise<number> | null;
   /** The initial load has landed on the chart. */
   loaded: boolean;
@@ -201,7 +266,7 @@ interface Session {
  * `setSymbol`.
  */
 export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed {
-  const { fetchBars, fetchGap, pageSize, maxEmptyPages, lazyLoadThreshold, scheduler, onError } = options;
+  const { fetchBars, fetchGap, fetchDepthSnapshot, pageSize, maxEmptyPages, lazyLoadThreshold, scheduler, onError } = options;
   const newController = options.createAbortController ?? createAbortController;
   const initialBars = options.initialBars ?? DEFAULT_INITIAL_BARS;
   const pageBars = options.pageBars ?? DEFAULT_PAGE_BARS;
@@ -216,6 +281,10 @@ export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed
   if (pageSize !== undefined) pageOptions.pageSize = pageSize;
   if (maxEmptyPages !== undefined) pageOptions.maxEmptyPages = maxEmptyPages;
   const states = new Emitter<DatafeedState>();
+  /** Depth listeners by symbol; only the current symbol's emitter ever fires. */
+  const depthListeners = new Map<string, Emitter<DepthBook>>();
+  /** Trade listeners by symbol; only the current symbol's emitter ever fires. */
+  const tradeListeners = new Map<string, Emitter<Trade>>();
   let session: Session | null = null;
   let destroyed = false;
   let lastRange: VisibleRangeChangeEvent | null = null;
@@ -255,12 +324,27 @@ export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed
   function end(s: Session | null): void {
     s?.controller.abort();
     s?.folder?.dispose();
+    if (s?.depth != null) {
+      s.depth.dispose();
+      // A switch or destroy must not leave the previous symbol's book on screen.
+      chart.setDepth(null);
+    }
     queued.clear();
     if (!framePending) return;
     framePending = false;
     scheduler!.cancel(frame);
   }
 
+  /**
+   * Publishes a session's book to the chart (which re-renders) and its
+   * symbol's depth listeners. Only the current session publishes: `end`
+   * disposes a superseded session's manager, which stops its publishing.
+   */
+  function publishBook(s: Session, book: DepthBook): void {
+    chart.setDepth(book);
+    depthListeners.get(s.symbol)?.emit(book);
+  }
+
   /** Applies a live bar at once, or on the scheduler's next frame. */
   function publish(bar: Candle): void {
     if (scheduler === undefined) {
@@ -407,10 +491,21 @@ export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed
     if (destroyed) return Promise.resolve();
     end(session);
     const s: Session = {
-      symbol, intervalMs, controller: newController(), folder: null, inflight: null,
+      symbol, intervalMs, controller: newController(), folder: null, depth: null, inflight: null,
+      tape: createTradeAggregation({ intervalMs }),
       loaded: false, exhausted: false, error: null, failures: 0, retryAtMs: -Infinity,
     };
     session = s;
+    if (fetchDepthSnapshot !== undefined) {
+      const fetchSnapshot = fetchDepthSnapshot;
+      s.depth = createDepthBookManager({
+        fetchSnapshot: () => fetchSnapshot({ symbol: s.symbol, signal: s.controller.signal }),
+        onBook: (book) => publishBook(s, book),
+        now,
+        batch: (run) => chart.batch(run),
+        onError: report,
+      });
+    }
     return start(s, () => initialLoad(s)).then(() => undefined);
   }
 
@@ -452,6 +547,52 @@ export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed
         report(error);
       }
     },
+    pushDepth(delta, symbol) {
+      if (symbol !== undefined && symbol !== session?.symbol) return;
+      try {
+        session?.depth?.pushDelta(delta);
+      } catch (error) {
+        // A depth-feed callback is no place for a chart listener's failure.
+        report(error);
+      }
+    },
+    subscribeDepth(symbol, onBook) {
+      const existing = depthListeners.get(symbol);
+      const emitter = existing ?? new Emitter<DepthBook>();
+      if (existing === undefined) depthListeners.set(symbol, emitter);
+      const off = emitter.subscribe(onBook);
+      return () => {
+        off();
+        if (emitter.size === 0) depthListeners.delete(symbol);
+      };
+    },
+    pushTrade(trade, symbol) {
+      const s = session;
+      if (s === null || (symbol !== undefined && symbol !== s.symbol)) return;
+      try {
+        s.tape.push(trade);
+        tradeListeners.get(s.symbol)?.emit(trade);
+      } catch (error) {
+        // A trade-feed callback is no place for a tape listener's failure.
+        report(error);
+      }
+    },
+    subscribeTrades(symbol, onTrade) {
+      const existing = tradeListeners.get(symbol);
+      const emitter = existing ?? new Emitter<Trade>();
+      if (existing === undefined) tradeListeners.set(symbol, emitter);
+      const off = emitter.subscribe(onTrade);
+      return () => {
+        off();
+        if (emitter.size === 0) tradeListeners.delete(symbol);
+      };
+    },
+    footprintBar(timeMs) {
+      return session?.tape.bar(timeMs) ?? null;
+    },
+    footprintBars(fromMs, toMs) {
+      return session?.tape.barsInRange(fromMs, toMs) ?? [];
+    },
     subscribeState: (listener) => states.subscribe(listener),
     destroy() {
       if (destroyed) return;
@@ -461,6 +602,10 @@ export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed
       offRange();
       offData();
       states.clear();
+      for (const emitter of depthListeners.values()) emitter.clear();
+      depthListeners.clear();
+      for (const emitter of tradeListeners.values()) emitter.clear();
+      tradeListeners.clear();
     },
   };
 
@@ -478,6 +623,16 @@ export function attachDatafeed(chart: Chart, options: DatafeedOptions): Datafeed
   return datafeed;
 }
 
+/**
+ * A live {@link FootprintSource} over the datafeed's current session for the
+ * footprint series and the delta/CVD indicators. Unlike a captured
+ * `TradeAggregation` it follows `setSymbol`: each session replaces the store,
+ * and the lookup delegates to whichever session is current (null → no bar).
+ */
+export function datafeedFootprintSource(datafeed: Pick<Datafeed, 'footprintBar'>): FootprintSource {
+  return { bar: (timeMs) => datafeed.footprintBar(timeMs) };
+}
+
 /**
  * Creates a chart fed by a paging datafeed:
  *
diff --git a/packages/chart/src/datafeed/depth-book.ts b/packages/chart/src/datafeed/depth-book.ts
new file mode 100644
index 0000000..a9b35b9
--- /dev/null
+++ b/packages/chart/src/datafeed/depth-book.ts
@@ -0,0 +1,333 @@
+/**
+ * Maintained L2 order book: a snapshot load followed by Binance-style
+ * diff-depth deltas, with sequence-gap detection and resync. Deltas arriving
+ * while a snapshot is in flight are buffered and drained against it, so no
+ * update between the stream's start and the snapshot is lost.
+ *
+ * @module
+ */
+
+import type { DepthBook, DepthLevel } from '../core/depth.js';
+
+/** Deltas buffered while a snapshot is in flight; the oldest is evicted beyond this. */
+export const MAX_BUFFERED_DELTAS = 2_000;
+
+/**
+ * After a failed snapshot read, ms before the next delta retries it on its
+ * own; doubles with each failure in a row. Mirrors the datafeed's
+ * `RETRY_BACKOFF_MS`.
+ */
+export const DEPTH_RETRY_BACKOFF_MS = 1_000;
+
+/** Longest wait between snapshot retries, in ms. Mirrors the datafeed's `MAX_RETRY_BACKOFF_MS`. */
+export const DEPTH_MAX_RETRY_BACKOFF_MS = 30_000;
+
+/**
+ * A Binance-style diff-depth event: the levels changed between
+ * `firstUpdateId` and `finalUpdateId` (both inclusive). A level with size 0
+ * removes the price from the book.
+ */
+export interface DepthDelta {
+  readonly firstUpdateId: number;
+  readonly finalUpdateId: number;
+  readonly bids: readonly DepthLevel[];
+  readonly asks: readonly DepthLevel[];
+  /** Event time in ms; defaults to the manager's clock. */
+  readonly time?: number;
+}
+
+/**
+ * A full L2 book snapshot, sequenced by `lastUpdateId`: every delta with
+ * `finalUpdateId` at or below it is already included.
+ */
+export interface DepthSnapshot {
+  readonly lastUpdateId: number;
+  readonly bids: readonly DepthLevel[];
+  readonly asks: readonly DepthLevel[];
+  /** Snapshot time in ms; defaults to the manager's clock. */
+  readonly time?: number;
+}
+
+/** Loads the book snapshot; called once at creation and again for every gap resync. */
+export type FetchDepthSnapshot = () => Promise<DepthSnapshot>;
+
+/** First index of `price` in the sorted side, or -1. */
+function levelIndex(side: readonly DepthLevel[], price: number, descending: boolean): number {
+  let lo = 0, hi = side.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const p = side[mid]![0];
+    if (p === price) return mid;
+    if (descending ? p > price : p < price) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+
+/** Index where `price` belongs in the sorted side. */
+function insertionIndex(side: readonly DepthLevel[], price: number, descending: boolean): number {
+  let lo = 0, hi = side.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (descending ? side[mid]![0] > price : side[mid]![0] < price) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * Applies diff levels to a sorted side in place: a size of 0 removes the
+ * price, any other size upserts it. Levels with a non-finite price or size,
+ * or a negative size, are ignored.
+ */
+export function applyDepthLevels(side: DepthLevel[], levels: readonly DepthLevel[], descending: boolean): void {
+  for (const level of levels) {
+    const [price, size] = level;
+    if (!Number.isFinite(price) || !Number.isFinite(size) || size < 0) continue;
+    const at = levelIndex(side, price, descending);
+    if (size === 0) {
+      if (at >= 0) side.splice(at, 1);
+    } else if (at >= 0) {
+      side[at] = level;
+    } else {
+      side.splice(insertionIndex(side, price, descending), 0, level);
+    }
+  }
+}
+
+/** A sorted book side from raw levels: invalid and zero sizes dropped, duplicate prices resolved last-wins. */
+export function normalizeDepthSide(levels: readonly DepthLevel[], descending: boolean): DepthLevel[] {
+  const side: DepthLevel[] = [];
+  applyDepthLevels(side, levels, descending);
+  return side;
+}
+
+/** Options for {@link createDepthBookManager}. */
+export interface DepthBookManagerOptions {
+  /** Snapshot source, called at creation and on every sequence-gap resync. */
+  fetchSnapshot: FetchDepthSnapshot;
+  /** Receives each maintained book: the snapshot first, then every applied delta. */
+  onBook(book: DepthBook): void;
+  /** Wall clock in ms, also timing snapshot-retry backoff; defaults to `Date.now`. */
+  now?: () => number;
+  /** Cap on deltas buffered while a snapshot is in flight; the oldest is evicted. Defaults to {@link MAX_BUFFERED_DELTAS}. */
+  maxBufferedDeltas?: number;
+  /** First retry delay (ms) after a failed snapshot read, doubling per failure in a row. Defaults to {@link DEPTH_RETRY_BACKOFF_MS}. */
+  retryBackoffMs?: number;
+  /** Longest snapshot retry delay (ms). Defaults to {@link DEPTH_MAX_RETRY_BACKOFF_MS}. */
+  maxRetryBackoffMs?: number;
+  /**
+   * Wraps the synchronous burst of `onBook` calls when a snapshot lands (the
+   * snapshot itself, then each buffered delta), e.g. `(run) => chart.batch(run)`
+   * for one redraw per resync. Must call `run` synchronously, once. Defaults
+   * to calling it directly.
+   */
+  batch?: (run: () => void) => void;
+  /**
+   * Receives snapshot read failures (retried with backoff on the next delta)
+   * and errors thrown by `onBook` or `batch` while a snapshot settles, which
+   * would otherwise be lost in the async settle. An error it throws is dropped.
+   */
+  onError?(error: unknown): void;
+}
+
+/** A maintained L2 book; see {@link createDepthBookManager}. */
+export interface DepthBookManager {
+  /**
+   * Folds one diff-depth event into the book. Until the first snapshot lands
+   * the delta is buffered; afterwards a stale one (`finalUpdateId` at or below
+   * the book's) is dropped and one covering the next update id is applied. A
+   * later one reveals a sequence gap: the book resyncs from a fresh snapshot
+   * with the delta (and the ones behind it) buffered for the drain. An event
+   * with non-integer ids or `firstUpdateId` above `finalUpdateId` is ignored.
+   */
+  pushDelta(delta: DepthDelta): void;
+  /** The last published book, or null before the first snapshot. */
+  readonly book: DepthBook | null;
+  /** True while no live book exists: the snapshot is in flight or being retried, or a gap resync is. */
+  readonly syncing: boolean;
+  /** Stops all publishing, including a snapshot that lands later. Safe inside `onBook`. */
+  dispose(): void;
+}
+
+/** Default {@link DepthBookManagerOptions.batch}: runs the burst unwrapped. */
+function runNow(run: () => void): void {
+  run();
+}
+
+function isValidDelta(delta: DepthDelta): boolean {
+  return Number.isSafeInteger(delta.firstUpdateId) && Number.isSafeInteger(delta.finalUpdateId) &&
+    delta.firstUpdateId <= delta.finalUpdateId;
+}
+
+/**
+ * Creates a manager that keeps an L2 book current from a snapshot plus a
+ * diff-depth stream. The first snapshot load starts at once; deltas pushed
+ * meanwhile are buffered, then drained against it (dropping events the
+ * snapshot already covers). A live delta that does not cover the next update
+ * id reveals a gap: the sequence is dropped, a fresh snapshot is read at
+ * once, and the buffered deltas drain against it. A gap found while draining
+ * means the stream made no progress since the last settle, so the resync
+ * waits out the same backoff as a failed read and the next arriving delta
+ * drives it — a silent stream cannot tight-loop the source. A failed
+ * snapshot read is retried by the next arriving delta after a backoff that
+ * doubles per failure (capped at `maxRetryBackoffMs`); there are no timers.
+ * A settle's `onBook` burst runs inside `batch`, so a chart can redraw once
+ * per resync.
+ */
+export function createDepthBookManager(options: DepthBookManagerOptions): DepthBookManager {
+  const now = options.now ?? Date.now;
+  const maxBuffered = options.maxBufferedDeltas ?? MAX_BUFFERED_DELTAS;
+  const backoffMs = options.retryBackoffMs ?? DEPTH_RETRY_BACKOFF_MS;
+  const maxBackoffMs = options.maxRetryBackoffMs ?? DEPTH_MAX_RETRY_BACKOFF_MS;
+  const batch = options.batch ?? runNow;
+  const report = (error: unknown): void => {
+    try {
+      options.onError?.(error);
+    } catch {
+      // The handler failed too: nowhere left to send it, and nothing awaits the settle.
+    }
+  };
+  let bids: DepthLevel[] = [];
+  let asks: DepthLevel[] = [];
+  let lastUpdateId: number | null = null;
+  let book: DepthBook | null = null;
+  let buffered: DepthDelta[] = [];
+  let fetching = false;
+  let failures = 0;
+  let retryAtMs = -Infinity;
+  let disposed = false;
+
+  function publish(time?: number): void {
+    book = { bids: bids.slice(), asks: asks.slice(), time: time ?? now() };
+    options.onBook(book);
+  }
+
+  /** Applies one delta against the live book; false reveals a sequence gap. */
+  function applyDelta(delta: DepthDelta): boolean {
+    if (lastUpdateId === null || delta.finalUpdateId <= lastUpdateId) return true;
+    if (delta.firstUpdateId > lastUpdateId + 1) return false;
+    applyDepthLevels(bids, delta.bids, true);
+    applyDepthLevels(asks, delta.asks, false);
+    lastUpdateId = delta.finalUpdateId;
+    publish(delta.time);
+    return true;
+  }
+
+  function buffer(delta: DepthDelta): void {
+    buffered.push(delta);
+    if (buffered.length > maxBuffered) buffered.shift();
+  }
+
+  /** Drops the sequence and resyncs from a fresh snapshot, keeping `delta` and the ones behind it for the drain. */
+  function resync(delta?: DepthDelta): void {
+    lastUpdateId = null;
+    if (delta !== undefined) buffer(delta);
+    if (!fetching) void sync();
+  }
+
+  /**
+   * A gap found while draining means the stream made no progress since the
+   * last settle, so reading again at once could tight-loop the source (a
+   * silent stream gaps against every snapshot). Back off instead; the next
+   * arriving delta drives the read, by which time the snapshot has moved on.
+   */
+  function resyncAfterBackoff(): void {
+    lastUpdateId = null;
+    retryAtMs = now() + Math.min(maxBackoffMs, backoffMs * 2 ** failures++);
+  }
+
+  /**
+   * Applies the deltas buffered during the read; a gap re-queues the rest and
+   * resyncs. A throwing `onBook` does not strand the deltas behind it: the
+   * first error is rethrown once the drain ends.
+   */
+  function drain(): void {
+    const queued = buffered;
+    buffered = [];
+    let failure: { readonly error: unknown } | undefined;
+    for (let i = 0; i < queued.length; i++) {
+      if (disposed) break; // onBook may dispose re-entrantly
+      let applied: boolean;
+      try {
+        applied = applyDelta(queued[i]!);
+      } catch (error) {
+        // The failed delta already advanced the sequence when its publish threw.
+        failure ??= { error };
+        continue;
+      }
+      if (!applied) {
+        buffered = queued.slice(i).concat(buffered);
+        resyncAfterBackoff();
+        break;
+      }
+    }
+    if (failure !== undefined) throw failure.error;
+  }
+
+  async function sync(): Promise<void> {
+    fetching = true;
+    let snapshot: DepthSnapshot;
+    try {
+      snapshot = await options.fetchSnapshot();
+    } catch (error) {
+      fetching = false;
+      if (disposed) return;
+      // A delta storm would otherwise retry a rate-limited source on every event.
+      retryAtMs = now() + Math.min(maxBackoffMs, backoffMs * 2 ** failures++);
+      report(error);
+      return;
+    }
+    fetching = false;
+    if (disposed) return;
+    if (!Number.isSafeInteger(snapshot.lastUpdateId) || snapshot.lastUpdateId < 0) {
+      retryAtMs = now() + Math.min(maxBackoffMs, backoffMs * 2 ** failures++);
+      report(new Error(`chart-ts: depth snapshot lastUpdateId must be a nonnegative safe integer, got ${snapshot.lastUpdateId}`));
+      return;
+    }
+    failures = 0;
+    retryAtMs = -Infinity;
+    try {
+      batch(() => {
+        bids = normalizeDepthSide(snapshot.bids, true);
+        asks = normalizeDepthSide(snapshot.asks, false);
+        lastUpdateId = snapshot.lastUpdateId;
+        try {
+          publish(snapshot.time);
+        } finally {
+          // A failed snapshot publish must not strand the buffered deltas.
+          drain();
+        }
+      });
+    } catch (error) {
+      // Nothing awaits the settle: a throw here would be an unhandled rejection.
+      report(error);
+    }
+  }
+
+  function pushDelta(delta: DepthDelta): void {
+    if (disposed || !isValidDelta(delta)) return;
+    if (lastUpdateId === null) {
+      buffer(delta);
+      // Deltas keep arriving, so they drive the retry of a failed read: no timer.
+      if (!fetching && now() >= retryAtMs) void sync();
+      return;
+    }
+    if (!applyDelta(delta)) resync(delta);
+  }
+
+  void sync();
+  return {
+    pushDelta,
+    get book() {
+      return book;
+    },
+    get syncing() {
+      return fetching || lastUpdateId === null;
+    },
+    dispose() {
+      disposed = true;
+      buffered = [];
+    },
+  };
+}
diff --git a/packages/chart/src/datafeed/index.ts b/packages/chart/src/datafeed/index.ts
index 6519a45..75fc151 100644
--- a/packages/chart/src/datafeed/index.ts
+++ b/packages/chart/src/datafeed/index.ts
@@ -7,6 +7,25 @@
  */
 
 export type { Candle } from '../core/data.js';
+export type { DepthBook, DepthLevel } from '../core/depth.js';
+export type { Trade, TradeSide } from '../core/trade.js';
+export { createTradeAggregation, MAX_FOOTPRINT_BARS } from './trade-aggregation.js';
+export type { FootprintBar, FootprintLevel, TradeAggregation, TradeAggregationOptions } from './trade-aggregation.js';
+export {
+  createDepthBookManager,
+  applyDepthLevels,
+  normalizeDepthSide,
+  MAX_BUFFERED_DELTAS,
+  DEPTH_RETRY_BACKOFF_MS,
+  DEPTH_MAX_RETRY_BACKOFF_MS,
+} from './depth-book.js';
+export type {
+  DepthBookManager,
+  DepthBookManagerOptions,
+  DepthDelta,
+  DepthSnapshot,
+  FetchDepthSnapshot,
+} from './depth-book.js';
 export { bucketStartMs, candleTimeMs, applyTick, normalizeCandles } from './candles.js';
 export {
   createLiveBarFolder,
@@ -24,6 +43,7 @@ export type { AbortControllerLike, AbortSignalLike, DatafeedSignal } from './abo
 export {
   attachDatafeed,
   createDatafeedChart,
+  datafeedFootprintSource,
   DEFAULT_INITIAL_BARS,
   DEFAULT_PAGE_BARS,
   MIN_LAZY_LOAD_THRESHOLD,
@@ -34,6 +54,8 @@ export type {
   Datafeed,
   DatafeedChart,
   DatafeedChartOptions,
+  DatafeedDepthRequest,
+  DatafeedFetchDepthSnapshot,
   DatafeedFetchGap,
   DatafeedGapRequest,
   DatafeedOptions,
diff --git a/packages/chart/src/datafeed/trade-aggregation.ts b/packages/chart/src/datafeed/trade-aggregation.ts
new file mode 100644
index 0000000..ada977f
--- /dev/null
+++ b/packages/chart/src/datafeed/trade-aggregation.ts
@@ -0,0 +1,166 @@
+/**
+ * Trade aggregation for footprint charts: a store keyed by (bar, price) that
+ * folds the trade stream into per-bucket levels of buy and sell size and
+ * count. Pure and synchronous — no snapshot, no retry: trades are a fire-and-
+ * forget stream, so a gap is simply missing prints, never a resync.
+ *
+ * @module
+ */
+
+import type { Trade } from '../core/trade.js';
+import { bucketStartMs } from './candles.js';
+
+/** Bars retained by default; the oldest bucket is evicted beyond the cap. */
+export const MAX_FOOTPRINT_BARS = 2_000;
+
+/** One price level of a footprint bar: size and trade count per aggressor side. */
+export interface FootprintLevel {
+  readonly price: number;
+  readonly buySize: number;
+  readonly sellSize: number;
+  readonly buyCount: number;
+  readonly sellCount: number;
+}
+
+/** The trades of one bar bucket, aggregated per price level. */
+export interface FootprintBar {
+  /** Bar open time in ms (the epoch-aligned bucket start). */
+  readonly time: number;
+  /** Levels sorted by price ascending. */
+  readonly levels: readonly FootprintLevel[];
+  readonly buySize: number;
+  readonly sellSize: number;
+  readonly buyCount: number;
+  readonly sellCount: number;
+}
+
+/** Options for {@link createTradeAggregation}. */
+export interface TradeAggregationOptions {
+  /** Bar width in whole ms; trades bucket into epoch-aligned bars of this size. */
+  readonly intervalMs: number;
+  /** Cap on retained bars; the oldest bucket is evicted beyond it. Defaults to {@link MAX_FOOTPRINT_BARS}. */
+  readonly maxBars?: number;
+}
+
+/** A (bar, price) trade aggregation store; see {@link createTradeAggregation}. */
+export interface TradeAggregation {
+  /** Bar width in ms. */
+  readonly intervalMs: number;
+  /** Number of retained bars. */
+  readonly size: number;
+  /**
+   * Folds one trade into its (bar, price) level. A trade with a non-finite
+   * time, price or size, a non-positive size, or an unknown side is ignored.
+   */
+  push(trade: Trade): void;
+  /** The aggregated bar whose bucket contains `timeMs`, or null when no trade landed there. */
+  bar(timeMs: number): FootprintBar | null;
+  /** The aggregated bars opening within `[fromMs, toMs]` (inclusive), oldest first. */
+  barsInRange(fromMs: number, toMs: number): FootprintBar[];
+  /** Drops every retained bar. */
+  clear(): void;
+}
+
+interface MutableLevel {
+  price: number;
+  buySize: number;
+  sellSize: number;
+  buyCount: number;
+  sellCount: number;
+}
+
+interface MutableBar {
+  readonly time: number;
+  readonly levels: Map<number, MutableLevel>;
+  buySize: number;
+  sellSize: number;
+  buyCount: number;
+  sellCount: number;
+}
+
+function toFootprintBar(bar: MutableBar): FootprintBar {
+  return {
+    time: bar.time,
+    levels: [...bar.levels.values()].sort((a, b) => a.price - b.price),
+    buySize: bar.buySize,
+    sellSize: bar.sellSize,
+    buyCount: bar.buyCount,
+    sellCount: bar.sellCount,
+  };
+}
+
+/**
+ * Creates a store aggregating trades per (bar, price). Buckets are
+ * epoch-aligned bars of `intervalMs`; within one, each price accumulates buy
+ * and sell size and count. Reads return fresh, sorted snapshots.
+ *
+ * @throws When `intervalMs` or `maxBars` is not a positive integer.
+ */
+export function createTradeAggregation(options: TradeAggregationOptions): TradeAggregation {
+  const { intervalMs } = options;
+  const maxBars = options.maxBars ?? MAX_FOOTPRINT_BARS;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0) {
+    throw new Error(`chart-ts: intervalMs must be a positive integer number of ms, got ${intervalMs}`);
+  }
+  if (!Number.isSafeInteger(maxBars) || maxBars <= 0) {
+    throw new Error(`chart-ts: maxBars must be a positive integer, got ${maxBars}`);
+  }
+  const bars = new Map<number, MutableBar>();
+
+  function push(trade: Trade): void {
+    const { time, price, size, side } = trade;
+    if (!Number.isFinite(time) || !Number.isFinite(price) || !Number.isFinite(size) || size <= 0) return;
+    if (side !== 'buy' && side !== 'sell') return;
+    const bucket = bucketStartMs(time, intervalMs);
+    let bar = bars.get(bucket);
+    if (bar === undefined) {
+      bar = { time: bucket, levels: new Map(), buySize: 0, sellSize: 0, buyCount: 0, sellCount: 0 };
+      bars.set(bucket, bar);
+      if (bars.size > maxBars) {
+        let oldest = bucket;
+        for (const key of bars.keys()) if (key < oldest) oldest = key;
+        bars.delete(oldest);
+        // A late trade for an already-evicted bucket drops with its own bar.
+        if (oldest === bucket) return;
+      }
+    }
+    let level = bar.levels.get(price);
+    if (level === undefined) {
+      level = { price, buySize: 0, sellSize: 0, buyCount: 0, sellCount: 0 };
+      bar.levels.set(price, level);
+    }
+    if (side === 'buy') {
+      level.buySize += size;
+      level.buyCount += 1;
+      bar.buySize += size;
+      bar.buyCount += 1;
+    } else {
+      level.sellSize += size;
+      level.sellCount += 1;
+      bar.sellSize += size;
+      bar.sellCount += 1;
+    }
+  }
+
+  return {
+    intervalMs,
+    get size() {
+      return bars.size;
+    },
+    push,
+    bar(timeMs) {
+      const bar = bars.get(bucketStartMs(timeMs, intervalMs));
+      return bar === undefined ? null : toFootprintBar(bar);
+    },
+    barsInRange(fromMs, toMs) {
+      const out: FootprintBar[] = [];
+      for (const bar of bars.values()) {
+        if (bar.time >= fromMs && bar.time <= toMs) out.push(toFootprintBar(bar));
+      }
+      return out.sort((a, b) => a.time - b.time);
+    },
+    clear() {
+      bars.clear();
+    },
+  };
+}
diff --git a/packages/chart/src/dom.ts b/packages/chart/src/dom.ts
index c64472c..7291a39 100644
--- a/packages/chart/src/dom.ts
+++ b/packages/chart/src/dom.ts
@@ -68,15 +68,85 @@ export interface Canvas2DLike {
   scale(x: number, y: number): void;
 }
 
+/** Context attributes accepted when asking a canvas for a WebGL2 context. */
+export interface WebGLContextOptionsLike {
+  alpha?: boolean;
+  antialias?: boolean;
+  preserveDrawingBuffer?: boolean;
+}
+
+/**
+ * Minimal subset of `WebGL2RenderingContext` used by the WebGL2 backend
+ * (instanced axis-aligned quads). A real `WebGL2RenderingContext` is
+ * structurally assignable to this type; handles (`WebGLProgram`, buffers,
+ * vertex arrays, uniform locations) are opaque `unknown`s.
+ */
+export interface WebGL2Like {
+  readonly TRIANGLES: number;
+  readonly VERTEX_SHADER: number;
+  readonly FRAGMENT_SHADER: number;
+  readonly COMPILE_STATUS: number;
+  readonly LINK_STATUS: number;
+  readonly ARRAY_BUFFER: number;
+  readonly DYNAMIC_DRAW: number;
+  readonly FLOAT: number;
+  readonly BLEND: number;
+  readonly SRC_ALPHA: number;
+  readonly ONE_MINUS_SRC_ALPHA: number;
+  readonly SCISSOR_TEST: number;
+  readonly COLOR_BUFFER_BIT: number;
+  createShader(type: number): unknown;
+  shaderSource(shader: unknown, source: string): void;
+  compileShader(shader: unknown): void;
+  getShaderParameter(shader: unknown, pname: number): unknown;
+  getShaderInfoLog(shader: unknown): string | null;
+  deleteShader(shader: unknown): void;
+  createProgram(): unknown;
+  attachShader(program: unknown, shader: unknown): void;
+  linkProgram(program: unknown): void;
+  getProgramParameter(program: unknown, pname: number): unknown;
+  getProgramInfoLog(program: unknown): string | null;
+  useProgram(program: unknown): void;
+  deleteProgram(program: unknown): void;
+  getUniformLocation(program: unknown, name: string): unknown;
+  uniform2f(location: unknown, x: number, y: number): void;
+  createBuffer(): unknown;
+  bindBuffer(target: number, buffer: unknown): void;
+  bufferData(target: number, data: ArrayBufferView, usage: number): void;
+  deleteBuffer(buffer: unknown): void;
+  createVertexArray(): unknown;
+  bindVertexArray(vao: unknown): void;
+  deleteVertexArray(vao: unknown): void;
+  enableVertexAttribArray(index: number): void;
+  vertexAttribPointer(index: number, size: number, type: number, normalized: boolean, stride: number, offset: number): void;
+  vertexAttribDivisor(index: number, divisor: number): void;
+  viewport(x: number, y: number, width: number, height: number): void;
+  scissor(x: number, y: number, width: number, height: number): void;
+  enable(cap: number): void;
+  disable(cap: number): void;
+  blendFunc(sfactor: number, dfactor: number): void;
+  clearColor(red: number, green: number, blue: number, alpha: number): void;
+  clear(mask: number): void;
+  drawArraysInstanced(mode: number, first: number, count: number, instanceCount: number): void;
+  isContextLost?(): boolean;
+}
+
 /**
  * A canvas the renderer can draw into. `HTMLCanvasElement` satisfies this
  * interface because its `getContext('2d')` returns a superset of
- * {@link Canvas2DLike}.
+ * {@link Canvas2DLike} and its `getContext('webgl2')` a superset of
+ * {@link WebGL2Like}.
  */
 export interface ChartCanvas {
   width: number;
   height: number;
   getContext(contextId: '2d', options?: { colorSpace?: 'srgb' | 'display-p3' }): Canvas2DLike | null;
+  /**
+   * WebGL2 access for the GL backend. Returns `unknown` because host mocks
+   * often implement only the `'2d'` signature; the backend narrows the result
+   * and treats anything unusable as unavailable (Canvas2D fallback).
+   */
+  getContext(contextId: 'webgl2', options?: WebGLContextOptionsLike): unknown;
   addEventListener?(type: 'contextrestored', listener: () => void): void;
   removeEventListener?(type: 'contextrestored', listener: () => void): void;
   /** Optional browser document used to lazily allocate the crosshair's raster cache. */
@@ -251,7 +321,9 @@ export class MockCanvas implements ChartCanvas {
     this.height = height;
   }
 
-  getContext(contextId: '2d'): Canvas2DLike | null {
+  getContext(contextId: '2d'): Canvas2DLike | null;
+  getContext(contextId: 'webgl2'): WebGL2Like | null;
+  getContext(contextId: string): unknown {
     return contextId === '2d' ? this.context : null;
   }
 
@@ -277,3 +349,203 @@ export class MockDocument implements ChartDocument {
     return canvas;
   }
 }
+
+/**
+ * A recording stand-in for {@link WebGL2Like}. Constants carry their real GL
+ * values; shaders compile and programs link unless {@link compileStatus} /
+ * {@link linkStatus} are cleared; handles are sequential plain objects.
+ */
+export class MockContextWebGL2 implements WebGL2Like {
+  readonly TRIANGLES = 0x0004;
+  readonly VERTEX_SHADER = 0x8b31;
+  readonly FRAGMENT_SHADER = 0x8b30;
+  readonly COMPILE_STATUS = 0x8b81;
+  readonly LINK_STATUS = 0x8b82;
+  readonly ARRAY_BUFFER = 0x8892;
+  readonly DYNAMIC_DRAW = 0x88e8;
+  readonly FLOAT = 0x1406;
+  readonly BLEND = 0x0be2;
+  readonly SRC_ALPHA = 0x0302;
+  readonly ONE_MINUS_SRC_ALPHA = 0x0303;
+  readonly SCISSOR_TEST = 0x0c11;
+  readonly COLOR_BUFFER_BIT = 0x4000;
+
+  /** Returned by `getShaderParameter(COMPILE_STATUS)`; clear to simulate a compile failure. */
+  compileStatus = true;
+  /** Returned by `getProgramParameter(LINK_STATUS)`; clear to simulate a link failure. */
+  linkStatus = true;
+
+  /** Every method call in order. */
+  readonly calls: RecordedCall[] = [];
+
+  private handleSeq = 0;
+
+  private record(name: string, args: unknown[]): void {
+    this.calls.push([name, ...args]);
+  }
+
+  /** Counts how many times a method was called. */
+  countCalls(name: string): number {
+    return this.calls.filter((c) => c[0] === name).length;
+  }
+
+  /** Returns all calls to one method. */
+  callsNamed(name: string): RecordedCall[] {
+    return this.calls.filter((c) => c[0] === name);
+  }
+
+  private handle(): { id: number } {
+    return { id: ++this.handleSeq };
+  }
+
+  createShader(type: number): unknown {
+    this.record('createShader', [type]);
+    return this.handle();
+  }
+  shaderSource(shader: unknown, source: string): void {
+    this.record('shaderSource', [shader, source]);
+  }
+  compileShader(shader: unknown): void {
+    this.record('compileShader', [shader]);
+  }
+  getShaderParameter(shader: unknown, pname: number): unknown {
+    this.record('getShaderParameter', [shader, pname]);
+    return this.compileStatus;
+  }
+  getShaderInfoLog(shader: unknown): string | null {
+    this.record('getShaderInfoLog', [shader]);
+    return this.compileStatus ? null : 'mock compile error';
+  }
+  deleteShader(shader: unknown): void {
+    this.record('deleteShader', [shader]);
+  }
+  createProgram(): unknown {
+    this.record('createProgram', []);
+    return this.handle();
+  }
+  attachShader(program: unknown, shader: unknown): void {
+    this.record('attachShader', [program, shader]);
+  }
+  linkProgram(program: unknown): void {
+    this.record('linkProgram', [program]);
+  }
+  getProgramParameter(program: unknown, pname: number): unknown {
+    this.record('getProgramParameter', [program, pname]);
+    return this.linkStatus;
+  }
+  getProgramInfoLog(program: unknown): string | null {
+    this.record('getProgramInfoLog', [program]);
+    return this.linkStatus ? null : 'mock link error';
+  }
+  useProgram(program: unknown): void {
+    this.record('useProgram', [program]);
+  }
+  deleteProgram(program: unknown): void {
+    this.record('deleteProgram', [program]);
+  }
+  getUniformLocation(program: unknown, name: string): unknown {
+    this.record('getUniformLocation', [program, name]);
+    return this.handle();
+  }
+  uniform2f(location: unknown, x: number, y: number): void {
+    this.record('uniform2f', [location, x, y]);
+  }
+  createBuffer(): unknown {
+    this.record('createBuffer', []);
+    return this.handle();
+  }
+  bindBuffer(target: number, buffer: unknown): void {
+    this.record('bindBuffer', [target, buffer]);
+  }
+  /** `data` is recorded as its byte length to keep the call log small. */
+  bufferData(target: number, data: ArrayBufferView, usage: number): void {
+    this.record('bufferData', [target, data.byteLength, usage]);
+  }
+  deleteBuffer(buffer: unknown): void {
+    this.record('deleteBuffer', [buffer]);
+  }
+  createVertexArray(): unknown {
+    this.record('createVertexArray', []);
+    return this.handle();
+  }
+  bindVertexArray(vao: unknown): void {
+    this.record('bindVertexArray', [vao]);
+  }
+  deleteVertexArray(vao: unknown): void {
+    this.record('deleteVertexArray', [vao]);
+  }
+  enableVertexAttribArray(index: number): void {
+    this.record('enableVertexAttribArray', [index]);
+  }
+  vertexAttribPointer(index: number, size: number, type: number, normalized: boolean, stride: number, offset: number): void {
+    this.record('vertexAttribPointer', [index, size, type, normalized, stride, offset]);
+  }
+  vertexAttribDivisor(index: number, divisor: number): void {
+    this.record('vertexAttribDivisor', [index, divisor]);
+  }
+  viewport(x: number, y: number, width: number, height: number): void {
+    this.record('viewport', [x, y, width, height]);
+  }
+  scissor(x: number, y: number, width: number, height: number): void {
+    this.record('scissor', [x, y, width, height]);
+  }
+  enable(cap: number): void {
+    this.record('enable', [cap]);
+  }
+  disable(cap: number): void {
+    this.record('disable', [cap]);
+  }
+  blendFunc(sfactor: number, dfactor: number): void {
+    this.record('blendFunc', [sfactor, dfactor]);
+  }
+  clearColor(red: number, green: number, blue: number, alpha: number): void {
+    this.record('clearColor', [red, green, blue, alpha]);
+  }
+  clear(mask: number): void {
+    this.record('clear', [mask]);
+  }
+  drawArraysInstanced(mode: number, first: number, count: number, instanceCount: number): void {
+    this.record('drawArraysInstanced', [mode, first, count, instanceCount]);
+  }
+}
+
+/** Options for {@link MockGLDocument}: per-context compile/link outcomes. */
+export interface MockGLDocumentOptions {
+  /** Initial {@link MockContextWebGL2.compileStatus} of created contexts. Default true. */
+  compile?: boolean;
+  /** Initial {@link MockContextWebGL2.linkStatus} of created contexts. Default true. */
+  link?: boolean;
+}
+
+/** A {@link MockCanvas} whose `'webgl2'` context is a {@link MockContextWebGL2}. */
+export class MockGLCanvas extends MockCanvas {
+  readonly gl: MockContextWebGL2;
+
+  constructor(width = 0, height = 0, options: MockGLDocumentOptions = {}) {
+    super(width, height);
+    this.gl = new MockContextWebGL2();
+    this.gl.compileStatus = options.compile !== false;
+    this.gl.linkStatus = options.link !== false;
+  }
+
+  override getContext(contextId: '2d'): Canvas2DLike | null;
+  override getContext(contextId: 'webgl2'): WebGL2Like | null;
+  override getContext(contextId: string): unknown {
+    if (contextId === 'webgl2') return this.gl;
+    return contextId === '2d' ? this.context : null;
+  }
+}
+
+/** A {@link ChartDocument} that creates {@link MockGLCanvas} instances. */
+export class MockGLDocument implements ChartDocument {
+  /** All canvases created through this document. */
+  readonly created: MockGLCanvas[] = [];
+
+  constructor(private readonly options: MockGLDocumentOptions = {}) {}
+
+  createCanvas(width: number, height: number): ChartCanvas {
+    const canvas = new MockGLCanvas(width, height, this.options);
+    this.created.push(canvas);
+    return canvas;
+  }
+}
diff --git a/packages/chart/src/drawings/forecasting.ts b/packages/chart/src/drawings/forecasting.ts
index 073ae24..9fadd68 100644
--- a/packages/chart/src/drawings/forecasting.ts
+++ b/packages/chart/src/drawings/forecasting.ts
@@ -7,6 +7,7 @@
  */
 
 import type { DrawingPoint } from '../config.js';
+import { valueArea, volumeProfileRows } from '../core/profile.js';
 import { defineDrawing } from './define.js';
 import type { DrawingDef, DrawPrimitive } from './types.js';
 import {
@@ -270,23 +271,8 @@ export function volumeProfile(
   to: number,
   rows: number,
 ): { lo: number; hi: number; up: number[]; down: number[] } {
-  let lo = Infinity;
-  let hi = -Infinity;
-  for (let i = from; i <= to; i++) {
-    lo = Math.min(lo, v.candles[i]!.low);
-    hi = Math.max(hi, v.candles[i]!.high);
-  }
-  const step = (hi - lo) / rows || 1;
-  const up = new Array<number>(rows).fill(0);
-  const down = new Array<number>(rows).fill(0);
-  for (let i = from; i <= to; i++) {
-    const c = v.candles[i]!;
-    const r0 = Math.min(rows - 1, Math.floor((c.low - lo) / step));
-    const r1 = Math.min(rows - 1, Math.floor((c.high - lo) / step));
-    const share = (c.volume ?? 0) / (r1 - r0 + 1);
-    for (let r = r0; r <= r1; r++) (c.close >= c.open ? up : down)[r]! += share;
-  }
-  return { lo, hi, up, down };
+  const prof = volumeProfileRows(v.candles, from, to, rows);
+  return prof ?? { lo: 0, hi: 0, up: new Array<number>(rows).fill(0), down: new Array<number>(rows).fill(0) };
 }
 
 /** Fixed range volume profile (2 points): volume by price over bars a..b, with POC and value area. */
@@ -303,18 +289,9 @@ export const volumeProfileDrawing = defineDrawing({
     const prof = volumeProfile(v, from, to, VOLUME_PROFILE_ROWS);
     const totals = prof.up.map((u, i) => u + prof.down[i]!);
     const max = Math.max(...totals) || 1;
-    const poc = totals.indexOf(Math.max(...totals));
     // Value area: grow from the POC until 70% of volume is covered.
-    const sum = totals.reduce((s, x) => s + x, 0);
-    let lo = poc;
-    let hi = poc;
-    let acc = totals[poc]!;
-    while (acc < sum * 0.7 && (lo > 0 || hi < totals.length - 1)) {
-      const below = lo > 0 ? totals[lo - 1]! : -1;
-      const above = hi < totals.length - 1 ? totals[hi + 1]! : -1;
-      if (above >= below) acc += totals[++hi]!;
-      else acc += totals[--lo]!;
-    }
+    const va = valueArea(totals);
+    const poc = va.poc;
     const rowH = (prof.hi - prof.lo) / VOLUME_PROFILE_ROWS;
     const width = (right - left) * 0.7;
     const top = v.priceToY(prof.hi);
@@ -323,7 +300,7 @@ export const volumeProfileDrawing = defineDrawing({
     totals.forEach((total, r) => {
       const y0 = v.priceToY(prof.lo + rowH * (r + 1));
       const h = Math.max(1, v.priceToY(prof.lo + rowH * r) - y0 - 1);
-      const inVa = r >= lo && r <= hi;
+      const inVa = r >= va.low && r <= va.high;
       const uw = (prof.up[r]! / max) * width;
       const dw = (prof.down[r]! / max) * width;
       const alpha = inVa ? 0.55 : 0.25;
diff --git a/packages/chart/src/index.ts b/packages/chart/src/index.ts
index f7e1992..722971e 100644
--- a/packages/chart/src/index.ts
+++ b/packages/chart/src/index.ts
@@ -14,7 +14,7 @@
 export const version = '0.1.0';
 
 export { createChart, Chart } from './core/chart.js';
-export { DEFAULT_DRAWING_COLOR, LINE_STYLE_DASH, WEAK_MAGNET_PX } from './core/chart.js';
+export { DEFAULT_DRAWING_COLOR, LINE_STYLE_DASH, WEAK_MAGNET_PX, DEFAULT_DOCK_WIDTH } from './core/chart.js';
 export type {
   CreateChartOptions,
   AddIndicatorInput,
@@ -23,6 +23,11 @@ export type {
   DrawingDraft,
   MagnetMode,
   ScaleApi,
+  CustomPaneOptions,
+  CustomPanePlacement,
+  CustomPaneAutoscale,
+  PaneApi,
+  PanePrimitiveHandle,
 } from './core/chart.js';
 export type { IndicatorHit } from './core/indicator-hit.js';
 
@@ -53,10 +58,68 @@ export type {
   CrosshairMode,
   ThemeConfig,
   FormattersConfig,
+  InlineBookConfig,
+  HeatmapConfig,
 } from './config.js';
 
 export type { Candle } from './core/data.js';
 export { DataStore } from './core/data.js';
+export type { DepthBook, DepthLevel } from './core/depth.js';
+export {
+  computeInlineBookRows,
+  inlineBookRowAt,
+  DEFAULT_INLINE_BOOK_MAX_LEVELS,
+  DEFAULT_INLINE_BOOK_BID_COLOR,
+  DEFAULT_INLINE_BOOK_ASK_COLOR,
+  DEFAULT_INLINE_BOOK_WIDTH,
+} from './core/inline-book.js';
+export type { InlineBookRow, InlineBookSide, InlineBookRows } from './core/inline-book.js';
+export {
+  DepthHistory,
+  heatmapIntensity,
+  heatPosition,
+  DEFAULT_HEATMAP_BUCKET_MS,
+  DEFAULT_HEATMAP_MAX_BUCKETS,
+  DEFAULT_HEATMAP_MAX_LEVELS,
+  DEFAULT_HEATMAP_COLOR_LOW,
+  DEFAULT_HEATMAP_COLOR_HIGH,
+  DEFAULT_HEATMAP_OPACITY,
+  DEFAULT_HEATMAP_MIN_OPACITY,
+  DEFAULT_HEATMAP_GAMMA,
+} from './core/heatmap.js';
+export type { HeatmapSnapshot, HeatmapStop } from './core/heatmap.js';
+export {
+  computeVolumeProfile,
+  computeTpoProfile,
+  volumeProfileRows,
+  tpoProfileRows,
+  valueArea,
+  profileRowAt,
+  sessionRanges,
+  profileStep,
+  gridVolumeRows,
+  DEFAULT_SESSION_MS,
+  DEFAULT_VALUE_AREA_PERCENT,
+} from './core/profile.js';
+export type { PriceProfile, VolumeProfile, ValueArea, SessionRange } from './core/profile.js';
+export type { Trade, TradeSide } from './core/trade.js';
+export {
+  footprintBands,
+  footprintLod,
+  barDelta,
+  candleDelta,
+  candleDeltas,
+  DEFAULT_FOOTPRINT_LOD,
+} from './core/footprint.js';
+export type {
+  FootprintLevelLike,
+  FootprintBarLike,
+  FootprintSource,
+  FootprintDisplay,
+  FootprintLod,
+  FootprintLodThresholds,
+  FootprintBand,
+} from './core/footprint.js';
 
 export { TimeScale, PriceScale, priceTicks, niceStep, visibleMinMax, seriesMinMax } from './core/scale.js';
 export type { VisibleRange } from './core/scale.js';
@@ -81,9 +144,18 @@ export type {
 export type { LayoutChangeEvent } from './core/events.js';
 export type { ConfigChangeEvent } from './core/events.js';
 
-export type { ChartDocument, ChartCanvas, Canvas2DLike, CanvasImageSourceLike, TextMetricsLike, RecordedCall } from './dom.js';
-export { MockDocument, MockCanvas, MockContext2D } from './dom.js';
-export type { MockBlob } from './dom.js';
+export type {
+  ChartDocument,
+  ChartCanvas,
+  Canvas2DLike,
+  CanvasImageSourceLike,
+  TextMetricsLike,
+  RecordedCall,
+  WebGL2Like,
+  WebGLContextOptionsLike,
+} from './dom.js';
+export { MockDocument, MockCanvas, MockContext2D, MockContextWebGL2, MockGLCanvas, MockGLDocument } from './dom.js';
+export type { MockBlob, MockGLDocumentOptions } from './dom.js';
 
 export { parseColor, serializeColor, isValidColor, withAlpha, relativeLuminance, contrastingTextColor } from './color.js';
 export type { ParsedColor } from './color.js';
@@ -101,7 +173,35 @@ export { drawVolumeOverlay } from './render/volume-overlay.js';
 export { scaleFont, scaleFontSize } from './render/scale-font.js';
 
 export { renderChart } from './render/renderer.js';
-export type { RenderView, PaneRenderInfo, ResolvedDrawing } from './render/renderer.js';
+export type { RenderView, PaneRenderInfo, DockedPaneRenderInfo, ResolvedDrawing } from './render/renderer.js';
+export { splitPrimitives } from './render/primitive.js';
+export type { PanePrimitive, PanePrimitives, PrimitiveDrawTarget } from './render/primitive.js';
+export {
+  attachSessionProfile,
+  createSessionProfilePrimitive,
+  createSessionLevelsPrimitive,
+  DEFAULT_SESSION_PROFILE_WIDTH,
+} from './render/session-profile.js';
+export type {
+  SessionProfileOptions,
+  SessionLevelsOptions,
+  SessionProfileAttachOptions,
+  SessionProfileApi,
+} from './render/session-profile.js';
+export { attachRangeProfile, createRangeProfilePrimitive, formatProfileVolume, TEXT_COLOR, SIDE_COLOR } from './render/range-profile.js';
+export type { RangeProfileOptions, RangeProfileAttachOptions, RangeProfileApi } from './render/range-profile.js';
+export { attachInlineBook, createInlineBookPrimitive, formatBookSize } from './render/inline-book.js';
+export type {
+  InlineBook,
+  InlineBookOptions,
+  InlineBookAttachOptions,
+  InlineBookApi,
+} from './render/inline-book.js';
+export { attachHeatmap, createHeatmapPrimitive, heatmapRamp, heatmapRampRGBA, HEATMAP_RAMP_STEPS } from './render/heatmap.js';
+export type { Heatmap, HeatmapOptions, HeatmapApi, HeatmapRampShape } from './render/heatmap.js';
+export { GLBackend } from './render/gl/backend.js';
+export type { GLFrame, GLQuadSink, RenderBackend } from './render/gl/backend.js';
+export { packCandleQuads } from './render/gl/candles.js';
 export { drawDrawings, crisp } from './render/drawings.js';
 export type { DrawingPaint } from './render/drawings.js';
 export { drawTimeAxis, timeTickIndices } from './render/axis.js';
@@ -121,8 +221,19 @@ export type {
 } from './core/price-lines.js';
 export { drawPriceLines } from './render/price-lines.js';
 export { drawMarkers, firstMarkerAtOrAfter, MARKER_MIN_SIZE, MARKER_MAX_SIZE } from './render/markers.js';
+export {
+  createTradePrintsPrimitive,
+  MAX_TRADE_PRINTS,
+  TRADE_PRINT_MIN_RADIUS,
+  TRADE_PRINT_MAX_RADIUS,
+  TRADE_PRINT_BUY_COLOR,
+  TRADE_PRINT_SELL_COLOR,
+} from './render/trade-prints.js';
+export type { TradePrints, TradePrintsOptions } from './render/trade-prints.js';
 
-export { SERIES_RENDERERS, drawHistogramBars } from './series/index.js';
+export { SERIES_RENDERERS, SeriesRegistry, createSeriesRegistry, drawHistogramBars } from './series/index.js';
+export { createFootprintSeries, formatFootprintSize, FOOTPRINT_SERIES_TYPE } from './series/index.js';
+export type { FootprintSeriesOptions, FootprintSeriesSource } from './series/index.js';
 export type { SeriesDrawFn } from './series/index.js';
 export { heikinAshi, heikinAshiBar, updateHeikinAshi } from './series/heikin-ashi.js';
 
@@ -175,6 +286,9 @@ export {
   stochIndicator,
   stochRsiIndicator,
   psarIndicator,
+  createDeltaIndicator,
+  createCvdIndicator,
+  cvdValues,
   atrValues,
   trueRangeValues,
   rmaValues,
diff --git a/packages/chart/src/indicators/cvd.ts b/packages/chart/src/indicators/cvd.ts
new file mode 100644
index 0000000..36eb43d
--- /dev/null
+++ b/packages/chart/src/indicators/cvd.ts
@@ -0,0 +1,59 @@
+/**
+ * CVD — cumulative volume delta: the running sum of per-bar traded deltas
+ * (buySize − sellSize) over a {@link FootprintSource}, as a sub-pane line.
+ * Register the definition the factory returns:
+ *
+ * ```ts
+ * chart.indicators.register(createCvdIndicator(source));
+ * chart.addIndicator({ name: 'cvd' });
+ * ```
+ *
+ * @module
+ */
+
+import type { Candle } from '../core/data.js';
+import { candleDelta, type FootprintSource } from '../core/footprint.js';
+import type { IndicatorDef } from './types.js';
+
+/** Continues the running total from `values[from − 1]` (0 at the first candle). */
+function fillCvd(candles: readonly Candle[], source: FootprintSource, values: (number | null)[], from: number): void {
+  let total = from > 0 ? values[from - 1] as number : 0;
+  for (let i = from; i < candles.length; i++) {
+    total += candleDelta(candles[i]!, source);
+    values[i] = total;
+  }
+}
+
+/** Cumulative deltas over the loaded candles: starts at 0; bars without trades add 0. */
+export function cvdValues(candles: readonly Candle[], source: FootprintSource): number[] {
+  const values = new Array<number>(candles.length).fill(0);
+  fillCvd(candles, source, values, 0);
+  return values;
+}
+
+/**
+ * The CVD indicator definition over `source` (name `'cvd'`, sub pane, no
+ * params). Tail updates continue the running total.
+ */
+export function createCvdIndicator(source: FootprintSource): IndicatorDef {
+  return {
+    name: 'cvd',
+    label: 'Cumulative Volume Delta',
+    shortName: 'CVD',
+    defaultParams: {},
+    defaultColors: ['#2196f3'],
+    defaultPane: 'sub',
+    inputs: [],
+    styles: [{ key: 'cvd', label: 'CVD', colorIndex: 0, kind: 'line' }],
+    update(output, candles: readonly Candle[], from: number) {
+      fillCvd(candles, source, output.lines[0]!.values as (number | null)[], from);
+      return output;
+    },
+    compute(candles: readonly Candle[], _params: Record<string, number>, colors: readonly string[]) {
+      return {
+        pane: 'sub' as const,
+        lines: [{ key: 'cvd', values: cvdValues(candles, source), color: colors[0] ?? '#2196f3' }],
+      };
+    },
+  };
+}
diff --git a/packages/chart/src/indicators/delta.ts b/packages/chart/src/indicators/delta.ts
new file mode 100644
index 0000000..6878533
--- /dev/null
+++ b/packages/chart/src/indicators/delta.ts
@@ -0,0 +1,65 @@
+/**
+ * Delta — per-bar traded volume delta (buySize − sellSize) as a direction-
+ * colored histogram, computed from a {@link FootprintSource} rather than
+ * candle volume. Register the definition the factory returns:
+ *
+ * ```ts
+ * chart.indicators.register(createDeltaIndicator(source));
+ * chart.addIndicator({ name: 'delta' });
+ * ```
+ *
+ * Like every cached indicator the output recomputes when the candles change;
+ * trades folded into an already-loaded bar show on the next data-driven
+ * render.
+ *
+ * @module
+ */
+
+import type { Candle } from '../core/data.js';
+import { candleDelta, candleDeltas, type FootprintSource } from '../core/footprint.js';
+import { DOWN_COLOR, UP_COLOR, type IndicatorDef } from './types.js';
+
+/**
+ * The Delta indicator definition over `source` (name `'delta'`, sub pane, no
+ * params; colors = up/down bars following the candles by default). Tail
+ * updates re-read the source from the first changed candle.
+ */
+export function createDeltaIndicator(source: FootprintSource): IndicatorDef {
+  return {
+    name: 'delta',
+    label: 'Delta',
+    shortName: 'Delta',
+    defaultParams: {},
+    defaultColors: [UP_COLOR, DOWN_COLOR],
+    defaultPane: 'sub',
+    inputs: [],
+    styles: [
+      { key: 'delta', label: 'Buying', colorIndex: 0, kind: 'histogram' },
+      { key: 'delta', label: 'Selling', colorIndex: 1, kind: 'histogram' },
+    ],
+    update(output, candles: readonly Candle[], from: number) {
+      const values = output.bars!.values as number[];
+      const up = output.bars!.up as boolean[];
+      for (let i = from; i < candles.length; i++) {
+        const delta = candleDelta(candles[i]!, source);
+        values[i] = delta;
+        up[i] = delta >= 0;
+      }
+      return output;
+    },
+    compute(candles: readonly Candle[], _params: Record<string, number>, colors: readonly string[]) {
+      const values = candleDeltas(candles, source);
+      return {
+        pane: 'sub' as const,
+        lines: [],
+        bars: {
+          key: 'delta',
+          values,
+          up: values.map((delta) => delta >= 0),
+          upColor: colors[0] ?? '#26a69a',
+          downColor: colors[1] ?? '#ef5350',
+        },
+      };
+    },
+  };
+}
diff --git a/packages/chart/src/indicators/index.ts b/packages/chart/src/indicators/index.ts
index 2b6de9b..a2ad149 100644
--- a/packages/chart/src/indicators/index.ts
+++ b/packages/chart/src/indicators/index.ts
@@ -34,3 +34,5 @@ export { donchianIndicator, donchianValues } from './donchian.js';
 export { stochIndicator, stochValues } from './stoch.js';
 export { stochRsiIndicator, stochRsiValues } from './stochrsi.js';
 export { psarIndicator, psarValues } from './psar.js';
+export { createDeltaIndicator } from './delta.js';
+export { createCvdIndicator, cvdValues } from './cvd.js';
diff --git a/packages/chart/src/preset-theme.ts b/packages/chart/src/preset-theme.ts
index cf1ad7b..aaf2263 100644
--- a/packages/chart/src/preset-theme.ts
+++ b/packages/chart/src/preset-theme.ts
@@ -19,14 +19,15 @@ import { withPreset, type ChartPresetName } from './presets.js';
 import { CHART_THEMES, type ThemeName } from './themes.js';
 
 /**
- * The colors a theme owns: chrome, grid, crosshair and series. Volume colors
- * are left out; they follow the series colors by default.
+ * The colors a theme owns: chrome, grid, crosshair, series and the heatmap
+ * ramp. Volume colors are left out; they follow the series colors by default.
  */
 const THEME_COLORS: Readonly<Record<string, readonly string[]>> = {
   theme: ['background', 'textColor', 'borderColor'],
   grid: ['color'],
   crosshair: ['color', 'labelBackground', 'labelColor'],
   series: ['upColor', 'downColor', 'wickUpColor', 'wickDownColor', 'borderUpColor', 'borderDownColor', 'lineColor', 'areaFillColor', 'histogramColor'],
+  heatmap: ['colorLow', 'colorHigh', 'stops'],
 };
 
 type Groups = Record<string, Record<string, unknown> | undefined>;
diff --git a/packages/chart/src/presets.ts b/packages/chart/src/presets.ts
index e15934c..a1f15e9 100644
--- a/packages/chart/src/presets.ts
+++ b/packages/chart/src/presets.ts
@@ -33,7 +33,9 @@ const FONT = "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif";
  * The bloxwap.pro dark look: #171717 pane, faint grid, 11px system-ui scales
  * in #a1a1a1, borderless #00ff3f / #ff479c candles over a 50% volume overlay,
  * direction-colored last-price line and badge, a background-free system-ui
- * status line, invisible pane separators and a neutral crosshair.
+ * status line, invisible pane separators and a neutral crosshair. When the
+ * liquidity heatmap is turned on it ramps neutral greys (thin liquidity) into
+ * brand gold and yellow (walls), keeping clear of the candle colors.
  */
 export const bloxwapDark: DeepPartial<ChartConfig> = {
   theme: {
@@ -62,6 +64,17 @@ export const bloxwapDark: DeepPartial<ChartConfig> = {
   statusLine: { visible: true, volume: false },
   priceAxis: { labels: { lastPrice: true }, lines: { lastPrice: true } },
   volume: { overlay: true, upColor: UP_COLOR, downColor: DOWN_COLOR, opacity: 0.5 },
+  // Colors only; the heatmap stays off until a host or the user enables it. A linear
+  // intensity curve keeps mid-sized levels grey so the gold walls stand out.
+  heatmap: {
+    stops: [
+      { color: '#404040', at: 0 },
+      { color: '#737373', at: 0.4 },
+      { color: '#ffc83d', at: 0.85 },
+      { color: '#fffb38', at: 1 },
+    ],
+    gamma: 1,
+  },
 };
 
 /** Built-in presets by name; pass a name as `createChart({ preset })` or merge one with `updateConfig`. */
diff --git a/packages/chart/src/render/gl/backend.ts b/packages/chart/src/render/gl/backend.ts
new file mode 100644
index 0000000..826c259
--- /dev/null
+++ b/packages/chart/src/render/gl/backend.ts
@@ -0,0 +1,226 @@
+/**
+ * WebGL2 geometry backend. The dense layers (candle bodies/wicks, heatmap
+ * cells) are packed into instanced axis-aligned quads — one base quad per
+ * instance, corners derived from `gl_VertexID`, so a frame is one buffer
+ * upload and one instanced draw — then composited into the host canvas with
+ * `drawImage`, letting the Canvas2D pass paint text, axes and overlays on top
+ * (hybrid compositing: GL never rasterizes glyphs).
+ *
+ * The GL canvas is allocated by the caller through the injected DOM (the host
+ * canvas's `ownerDocument` or the injected `ChartDocument`) and is never
+ * attached to a document; it exists only as a `drawImage` source.
+ *
+ * @module
+ */
+
+import type { Canvas2DLike, ChartCanvas, WebGL2Like } from '../../dom.js';
+
+/** Render backend identifiers; see `CreateChartOptions.renderer`. */
+export type RenderBackend = 'canvas2d' | 'webgl2';
+
+/** Receives axis-aligned quads in pane-local CSS pixels with straight-alpha RGBA channels (0-1). */
+export interface GLQuadSink {
+  quad(x: number, y: number, width: number, height: number, r: number, g: number, b: number, a: number): void;
+}
+
+/**
+ * One frame of GL work on the main pane. Quads accumulate in submission order
+ * (heatmap cells below candles); {@link GLFrame.composite} flushes and draws
+ * the GL canvas at the 2D context's current transform, so it must be called
+ * from the pane-translated, pane-clipped series layer exactly once per frame.
+ */
+export interface GLFrame extends GLQuadSink {
+  /** Flushes pending quads and composites the GL canvas; a no-op when no quads were submitted. */
+  composite(ctx: Canvas2DLike): void;
+}
+
+const FLOATS_PER_QUAD = 8;
+const QUAD_STRIDE_BYTES = FLOATS_PER_QUAD * 4;
+
+const VERTEX_SHADER_SOURCE = `#version 300 es
+layout(location = 0) in vec4 aRect;
+layout(location = 1) in vec4 aColor;
+uniform vec2 uResolution;
+out vec4 vColor;
+void main() {
+  vec2 corner = vec2(
+    float(gl_VertexID == 1 || gl_VertexID == 4 || gl_VertexID == 5),
+    float(gl_VertexID == 2 || gl_VertexID == 3 || gl_VertexID == 5));
+  vec2 position = aRect.xy + corner * aRect.zw;
+  vec2 clip = position / uResolution * 2.0 - 1.0;
+  gl_Position = vec4(clip.x, -clip.y, 0.0, 1.0);
+  vColor = aColor;
+}`;
+
+const FRAGMENT_SHADER_SOURCE = `#version 300 es
+precision mediump float;
+in vec4 vColor;
+out vec4 fragColor;
+void main() {
+  fragColor = vColor;
+}`;
+
+function compileShader(gl: WebGL2Like, type: number, source: string): unknown {
+  const shader = gl.createShader(type);
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (gl.getShaderParameter(shader, gl.COMPILE_STATUS) !== true) {
+    gl.deleteShader(shader);
+    return null;
+  }
+  return shader;
+}
+
+function linkProgram(gl: WebGL2Like): unknown {
+  const vertex = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER_SOURCE);
+  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER_SOURCE);
+  if (vertex === null || fragment === null) return null;
+  const program = gl.createProgram();
+  gl.attachShader(program, vertex);
+  gl.attachShader(program, fragment);
+  gl.linkProgram(program);
+  gl.deleteShader(vertex);
+  gl.deleteShader(fragment);
+  if (gl.getProgramParameter(program, gl.LINK_STATUS) !== true) {
+    gl.deleteProgram(program);
+    return null;
+  }
+  return program;
+}
+
+/**
+ * Owns the offscreen GL canvas, the quad program and the instance buffer.
+ * Create through {@link GLBackend.create}; any failure (no WebGL2 context,
+ * shader compile or link error) yields `null` so the caller falls back to
+ * Canvas2D.
+ */
+export class GLBackend implements GLQuadSink {
+  /** The offscreen canvas; sized to the host canvas's backing store. */
+  readonly canvas: ChartCanvas;
+
+  private readonly gl: WebGL2Like;
+  private readonly program: unknown;
+  private readonly buffer: unknown;
+  private readonly vao: unknown;
+  private readonly resolution: unknown;
+  private staging = new Float32Array(FLOATS_PER_QUAD * 1024);
+  private count = 0;
+  private pixelRatio = 1;
+
+  private constructor(canvas: ChartCanvas, gl: WebGL2Like, program: unknown, buffer: unknown, vao: unknown, resolution: unknown) {
+    this.canvas = canvas;
+    this.gl = gl;
+    this.program = program;
+    this.buffer = buffer;
+    this.vao = vao;
+    this.resolution = resolution;
+  }
+
+  /** Acquires a WebGL2 context on `canvas` and builds the quad pipeline; `null` on any failure. */
+  static create(canvas: ChartCanvas): GLBackend | null {
+    const gl = canvas.getContext('webgl2', { alpha: true, antialias: false, preserveDrawingBuffer: false }) as WebGL2Like | null;
+    if (gl === null || gl === undefined || typeof gl.createShader !== 'function') return null;
+    try {
+      const program = linkProgram(gl);
+      if (program === null) return null;
+      const vao = gl.createVertexArray();
+      const buffer = gl.createBuffer();
+      gl.bindVertexArray(vao);
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+      gl.enableVertexAttribArray(0);
+      gl.vertexAttribPointer(0, 4, gl.FLOAT, false, QUAD_STRIDE_BYTES, 0);
+      gl.vertexAttribDivisor(0, 1);
+      gl.enableVertexAttribArray(1);
+      gl.vertexAttribPointer(1, 4, gl.FLOAT, false, QUAD_STRIDE_BYTES, 16);
+      gl.vertexAttribDivisor(1, 1);
+      gl.enable(gl.BLEND);
+      gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+      gl.useProgram(program);
+      return new GLBackend(canvas, gl, program, buffer, vao, gl.getUniformLocation(program, 'uResolution'));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Tracks the host canvas's backing store; resizing clears the drawing buffer. */
+  resize(width: number, height: number): void {
+    if (this.canvas.width !== width) this.canvas.width = width;
+    if (this.canvas.height !== height) this.canvas.height = height;
+  }
+
+  /**
+   * Starts a frame: clears to transparent and scissors to the main pane's
+   * plot rect (`width` × `height` CSS pixels from the canvas's top-left,
+   * before the 2D pass's plot/pane translations).
+   */
+  beginFrame(pixelRatio: number, width: number, height: number): GLFrame {
+    this.pixelRatio = pixelRatio;
+    this.count = 0;
+    const gl = this.gl;
+    const backingWidth = this.canvas.width;
+    const backingHeight = this.canvas.height;
+    gl.viewport(0, 0, backingWidth, backingHeight);
+    gl.uniform2f(this.resolution, backingWidth, backingHeight);
+    gl.enable(gl.SCISSOR_TEST);
+    gl.scissor(
+      0,
+      Math.max(0, backingHeight - Math.round(height * pixelRatio)),
+      Math.round(width * pixelRatio),
+      Math.round(height * pixelRatio),
+    );
+    gl.clearColor(0, 0, 0, 0);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    return {
+      quad: (x, y, w, h, r, g, b, a) => this.quad(x, y, w, h, r, g, b, a),
+      composite: (ctx) => this.composite(ctx),
+    };
+  }
+
+  /** Appends one quad (pane-local CSS pixels, straight-alpha RGBA) to the instance staging buffer. */
+  quad(x: number, y: number, width: number, height: number, r: number, g: number, b: number, a: number): void {
+    if ((this.count + 1) * FLOATS_PER_QUAD > this.staging.length) {
+      const next = new Float32Array(this.staging.length * 2);
+      next.set(this.staging);
+      this.staging = next;
+    }
+    const ratio = this.pixelRatio;
+    const o = this.count * FLOATS_PER_QUAD;
+    this.staging[o] = x * ratio;
+    this.staging[o + 1] = y * ratio;
+    this.staging[o + 2] = width * ratio;
+    this.staging[o + 3] = height * ratio;
+    this.staging[o + 4] = r;
+    this.staging[o + 5] = g;
+    this.staging[o + 6] = b;
+    this.staging[o + 7] = a;
+    this.count++;
+  }
+
+  /** Uploads and draws the staged quads; returns whether anything was drawn. */
+  private flush(): boolean {
+    if (this.count === 0) return false;
+    const gl = this.gl;
+    gl.bufferData(gl.ARRAY_BUFFER, this.staging.subarray(0, this.count * FLOATS_PER_QUAD), gl.DYNAMIC_DRAW);
+    gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, this.count);
+    this.count = 0;
+    return true;
+  }
+
+  private composite(ctx: Canvas2DLike): void {
+    if (!this.flush()) return;
+    ctx.drawImage(this.canvas, 0, 0, this.canvas.width / this.pixelRatio, this.canvas.height / this.pixelRatio);
+    // Self-clear so a re-render of the same frame (the crosshair cache paints
+    // the view again on a later task) never stacks quads onto a stale image.
+    this.gl.clear(this.gl.COLOR_BUFFER_BIT);
+  }
+
+  /** Releases GL resources and drops the canvas bitmap. */
+  dispose(): void {
+    const gl = this.gl;
+    gl.deleteBuffer(this.buffer);
+    gl.deleteVertexArray(this.vao);
+    gl.deleteProgram(this.program);
+    this.canvas.width = 0;
+    this.canvas.height = 0;
+  }
+}
diff --git a/packages/chart/src/render/gl/candles.ts b/packages/chart/src/render/gl/candles.ts
new file mode 100644
index 0000000..f3612fc
--- /dev/null
+++ b/packages/chart/src/render/gl/candles.ts
@@ -0,0 +1,67 @@
+/**
+ * Candlestick geometry for the WebGL2 backend: each wick and body becomes one
+ * instanced quad, mirroring {@link drawCandlesticks} pixel-for-pixel. Candle
+ * borders (`SeriesConfig.borderVisible`) are strokes, not quads, so bordered
+ * candles stay on the Canvas2D path (the caller checks the flag).
+ *
+ * @module
+ */
+
+import { parseColor } from '../../color.js';
+import type { Candle } from '../../core/data.js';
+import type { PriceScale, TimeScale, VisibleRange } from '../../core/scale.js';
+import type { SeriesConfig } from '../../config.js';
+import type { GLQuadSink } from './backend.js';
+
+type RGBA = readonly [number, number, number, number];
+
+/** Channels 0-1 regardless of the parsed color's space; `null` for unsupported syntax. */
+function glColor(input: string): RGBA | null {
+  const c = parseColor(input);
+  if (c === null) return null;
+  const d = c.space === 'srgb' ? 255 : 1;
+  return [c.r / d, c.g / d, c.b / d, c.a];
+}
+
+/**
+ * Packs the visible candles into `sink` as wick and body quads in pane-local
+ * CSS pixels (the sink applies the pixel ratio). Returns `false` without
+ * emitting anything when a series color is not parseable — the caller then
+ * draws the series with Canvas2D instead.
+ */
+export function packCandleQuads(
+  sink: GLQuadSink,
+  candles: readonly Candle[],
+  range: VisibleRange,
+  timeScale: TimeScale,
+  priceScale: PriceScale,
+  config: SeriesConfig,
+  liveCandle?: Candle,
+): boolean {
+  const up = glColor(config.upColor);
+  const down = glColor(config.downColor);
+  const wickUp = glColor(config.wickUpColor !== '' ? config.wickUpColor : config.upColor);
+  const wickDown = glColor(config.wickDownColor !== '' ? config.wickDownColor : config.downColor);
+  if (up === null || down === null || wickUp === null || wickDown === null) return false;
+  const bodyWidth = Math.max(1, Math.floor(timeScale.barSpacing * 0.7));
+  for (let i = range.from; i < range.to; i++) {
+    const c = (i === candles.length - 1 ? liveCandle : undefined) ?? candles[i];
+    const rising = c.close >= (config.colorByPreviousClose && i > 0 ? candles[i - 1].close : c.open);
+    const body = rising ? up : down;
+    const wick = rising ? wickUp : wickDown;
+    const x = Math.round(timeScale.indexToX(i, candles.length));
+    const yHigh = priceScale.priceToY(c.high);
+    const yLow = priceScale.priceToY(c.low);
+    const yOpen = priceScale.priceToY(c.open);
+    const yClose = priceScale.priceToY(c.close);
+    if (config.wickVisible) {
+      sink.quad(x, Math.min(yHigh, yLow), 1, Math.max(1, Math.abs(yLow - yHigh)), wick[0], wick[1], wick[2], wick[3]);
+    }
+    if (config.bodyVisible) {
+      const bodyTop = Math.min(yOpen, yClose);
+      const height = Math.max(1, Math.abs(yClose - yOpen));
+      sink.quad(x - Math.floor(bodyWidth / 2), bodyTop, bodyWidth, height, body[0], body[1], body[2], body[3]);
+    }
+  }
+  return true;
+}
diff --git a/packages/chart/src/render/heatmap.ts b/packages/chart/src/render/heatmap.ts
new file mode 100644
index 0000000..8fdbb8f
--- /dev/null
+++ b/packages/chart/src/render/heatmap.ts
@@ -0,0 +1,458 @@
+/**
+ * Liquidity heatmap (Bookmap-style): resting order-book size over time as a
+ * color field behind the candles. A {@link DepthHistory} window retains one
+ * trimmed book snapshot per wall-clock bucket; this primitive paints, per
+ * visible bucket, a column of cells whose color intensity is the level size
+ * over the visible window's largest size, so persistent resting liquidity
+ * shows as bright walls and pulled liquidity fades.
+ *
+ * Cells aggregate per pixel column and pixel row (max intensity wins), so
+ * zooming out merges sub-pixel buckets instead of stacking alpha. The depth
+ * channel re-renders the chart on every book update, so the draw pass records
+ * the current book (deduped by book time inside {@link DepthHistory}) before
+ * painting, exactly like the inline book reads `Chart.depth` at draw time.
+ *
+ * @module
+ */
+
+import { parseColor, serializeColor, type ParsedColor } from '../color.js';
+import { mergeDeep, type HeatmapConfig } from '../config.js';
+import type { Chart, PanePrimitiveHandle } from '../core/chart.js';
+import type { DepthBook, DepthLevel } from '../core/depth.js';
+import {
+  DepthHistory,
+  heatmapIntensity,
+  heatPosition,
+  DEFAULT_HEATMAP_BUCKET_MS,
+  DEFAULT_HEATMAP_COLOR_HIGH,
+  DEFAULT_HEATMAP_COLOR_LOW,
+  DEFAULT_HEATMAP_GAMMA,
+  DEFAULT_HEATMAP_MAX_BUCKETS,
+  DEFAULT_HEATMAP_MAX_LEVELS,
+  DEFAULT_HEATMAP_MIN_OPACITY,
+  DEFAULT_HEATMAP_OPACITY,
+  type HeatmapSnapshot,
+  type HeatmapStop,
+} from '../core/heatmap.js';
+import type { Canvas2DLike } from '../dom.js';
+import type { PanePrimitive, PrimitiveDrawTarget } from './primitive.js';
+
+/** Steps of the precomputed intensity ramp (fillStyle strings). */
+export const HEATMAP_RAMP_STEPS = 64;
+
+/** Options for {@link createHeatmapPrimitive} and {@link attachHeatmap}. */
+export interface HeatmapOptions {
+  /** Wall-clock bucket width in ms. Default {@link DEFAULT_HEATMAP_BUCKET_MS}. */
+  bucketMs?: number;
+  /** Retained buckets. Default {@link DEFAULT_HEATMAP_MAX_BUCKETS}. */
+  maxBuckets?: number;
+  /** Levels kept per side per snapshot. Default {@link DEFAULT_HEATMAP_MAX_LEVELS}. */
+  maxLevels?: number;
+  /** Ramp color at zero intensity. Default {@link DEFAULT_HEATMAP_COLOR_LOW}. */
+  colorLow?: string;
+  /** Ramp color at full intensity. Default {@link DEFAULT_HEATMAP_COLOR_HIGH}. */
+  colorHigh?: string;
+  /** A custom gradient replacing `colorLow` → `colorHigh`; see {@link HeatmapRampShape.stops}. */
+  stops?: readonly HeatmapStop[];
+  /** Peak cell alpha at full intensity, 0-1. Default {@link DEFAULT_HEATMAP_OPACITY}. */
+  opacity?: number;
+  /** Cell alpha at zero intensity, 0-1. Default {@link DEFAULT_HEATMAP_MIN_OPACITY}. */
+  minOpacity?: number;
+  /** Intensity curve exponent; below 1 lifts small sizes. Default {@link DEFAULT_HEATMAP_GAMMA}. */
+  gamma?: number;
+  /** Record into an existing history instead of a fresh one. */
+  history?: DepthHistory;
+}
+
+/** A pane primitive painting the depth history as a color field; see {@link createHeatmapPrimitive}. */
+export interface Heatmap extends PanePrimitive {
+  /** The window the primitive records into and paints. */
+  readonly history: DepthHistory;
+  /** Largest visible level size of the last draw (the intensity normalizer); 0 when nothing was visible. */
+  readonly visibleMax: number;
+}
+
+/** Handle of a heatmap attached via {@link attachHeatmap}. */
+export interface HeatmapApi {
+  /** The attached primitive. */
+  readonly primitive: Heatmap;
+  /** The retained depth history. */
+  readonly history: DepthHistory;
+  /** Merges new options and re-renders. */
+  update(options: HeatmapOptions): void;
+  /** Drops the config subscription and detaches the primitive. */
+  remove(): void;
+}
+
+interface ResolvedHeatmapOptions {
+  bucketMs: number;
+  maxBuckets: number;
+  maxLevels: number;
+  gamma: number;
+  lut: readonly string[];
+  /** The ramp as unit-channel RGBA float quads, parallel to `lut` (WebGL2 backend). */
+  lutRGBA: Float32Array;
+}
+
+/** Channels 0-1 regardless of the parsed color's space. */
+function unitChannels(c: ParsedColor): readonly [number, number, number] {
+  const d = c.space === 'srgb' ? 255 : 1;
+  return [c.r / d, c.g / d, c.b / d];
+}
+
+/** One ramp step: unit RGB channels plus alpha, in the ramp's color space. */
+type RampStep = readonly [number, number, number, number];
+
+interface RampSpec {
+  readonly p3: boolean;
+  readonly steps: RampStep[];
+}
+
+/** Shaping beyond the two-color ramp, for {@link heatmapRamp} and {@link heatmapRampRGBA}. */
+export interface HeatmapRampShape {
+  /**
+   * A custom gradient from zero to full intensity. Bare colors spread evenly
+   * by index; `{ color, at }` pins a stop to an intensity (clamped to 0-1).
+   * Unparseable colors are skipped, and a stop color's alpha scales the ramp
+   * alpha there. With no usable stop the ramp stays `colorLow` → `colorHigh`.
+   */
+  readonly stops?: readonly HeatmapStop[] | undefined;
+  /** Cell alpha at zero intensity, 0-1. Default {@link DEFAULT_HEATMAP_MIN_OPACITY}. */
+  readonly minOpacity?: number | undefined;
+}
+
+/** A parsed gradient stop at its intensity. */
+interface GradientStop {
+  readonly at: number;
+  readonly color: ParsedColor;
+}
+
+/** The usable stops, sorted by intensity. */
+function gradientStops(stops: readonly HeatmapStop[]): GradientStop[] {
+  const out: GradientStop[] = [];
+  stops.forEach((stop, i) => {
+    const spec = typeof stop === 'string' ? { color: stop } : stop;
+    const color = parseColor(spec.color);
+    if (color === null) return;
+    const at = spec.at !== undefined && Number.isFinite(spec.at) ? spec.at : stops.length > 1 ? i / (stops.length - 1) : 0;
+    out.push({ at: Math.min(1, Math.max(0, at)), color });
+  });
+  return out.sort((a, b) => a.at - b.at);
+}
+
+/** Unit channels and alpha of the gradient at intensity `t`, held flat past its end stops. */
+function sampleGradient(stops: readonly GradientStop[], t: number): RampStep {
+  let lo = stops[0]!, hi = lo;
+  for (const stop of stops) {
+    if (stop.at <= t) lo = stop;
+    if (stop.at >= t) { hi = stop; break; }
+  }
+  if (hi.at < t) hi = lo;
+  const span = hi.at - lo.at;
+  const f = span > 0 ? (t - lo.at) / span : 0;
+  const a = unitChannels(lo.color), b = unitChannels(hi.color);
+  const mix = (u: number, v: number) => u + (v - u) * f;
+  return [mix(a[0], b[0]), mix(a[1], b[1]), mix(a[2], b[2]), mix(lo.color.a, hi.color.a)];
+}
+
+/** The shared ramp math behind {@link heatmapRamp} and {@link heatmapRampRGBA}. */
+function rampSpec(colorLow: string, colorHigh: string, opacity: number, shape: HeatmapRampShape = {}): RampSpec {
+  const custom = gradientStops(shape.stops ?? []);
+  const stops = custom.length > 0 ? custom : [
+    { at: 0, color: parseColor(colorLow) ?? parseColor(DEFAULT_HEATMAP_COLOR_LOW)! },
+    { at: 1, color: parseColor(colorHigh) ?? parseColor(DEFAULT_HEATMAP_COLOR_HIGH)! },
+  ];
+  const p3 = stops.some((stop) => stop.color.space === 'display-p3');
+  const unit = (v: number) => Math.min(1, Math.max(0, v));
+  const peak = unit(opacity);
+  const floor = unit(shape.minOpacity ?? DEFAULT_HEATMAP_MIN_OPACITY);
+  const steps: RampStep[] = [];
+  for (let i = 0; i < HEATMAP_RAMP_STEPS; i++) {
+    const t = i / (HEATMAP_RAMP_STEPS - 1);
+    const [r, g, b, a] = sampleGradient(stops, t);
+    steps.push([r, g, b, (floor + (peak - floor) * t) * a]);
+  }
+  return { p3, steps };
+}
+
+/**
+ * The intensity ramp as `HEATMAP_RAMP_STEPS` fillStyle strings, lerping
+ * `colorLow` → `colorHigh` (or `shape.stops`) with alpha `shape.minOpacity`
+ * (default 0, so step 0 is fully transparent) → `opacity`, scaled by each
+ * color's own alpha. Unparseable endpoints fall back to the defaults; any
+ * Display-P3 color makes the whole ramp Display-P3.
+ */
+export function heatmapRamp(colorLow: string, colorHigh: string, opacity: number, shape: HeatmapRampShape = {}): string[] {
+  const { p3, steps } = rampSpec(colorLow, colorHigh, opacity, shape);
+  const scale = p3 ? 1 : 255;
+  return steps.map(([r, g, b, a]) => serializeColor({
+    space: p3 ? 'display-p3' : 'srgb',
+    r: r * scale,
+    g: g * scale,
+    b: b * scale,
+    a,
+  }));
+}
+
+/**
+ * The same ramp as `HEATMAP_RAMP_STEPS × 4` floats (unit channels, straight
+ * alpha) for the WebGL2 backend's quad colors. Display-P3 endpoints keep their
+ * P3 channel values; the GL canvas composites them in its default sRGB space.
+ */
+export function heatmapRampRGBA(colorLow: string, colorHigh: string, opacity: number, shape: HeatmapRampShape = {}): Float32Array {
+  const { steps } = rampSpec(colorLow, colorHigh, opacity, shape);
+  const lut = new Float32Array(HEATMAP_RAMP_STEPS * 4);
+  for (let i = 0; i < HEATMAP_RAMP_STEPS; i++) {
+    lut.set(steps[i]!, i * 4);
+  }
+  return lut;
+}
+
+function resolveHeatmapOptions(o: HeatmapOptions): ResolvedHeatmapOptions {
+  const colorLow = o.colorLow ?? DEFAULT_HEATMAP_COLOR_LOW;
+  const colorHigh = o.colorHigh ?? DEFAULT_HEATMAP_COLOR_HIGH;
+  const opacity = o.opacity ?? DEFAULT_HEATMAP_OPACITY;
+  const shape: HeatmapRampShape = { stops: o.stops, minOpacity: o.minOpacity };
+  return {
+    bucketMs: Math.max(1, Math.floor(o.bucketMs ?? DEFAULT_HEATMAP_BUCKET_MS)),
+    maxBuckets: Math.max(1, Math.floor(o.maxBuckets ?? DEFAULT_HEATMAP_MAX_BUCKETS)),
+    maxLevels: Math.max(1, Math.floor(o.maxLevels ?? DEFAULT_HEATMAP_MAX_LEVELS)),
+    gamma: Math.max(0.05, o.gamma ?? DEFAULT_HEATMAP_GAMMA),
+    lut: heatmapRamp(colorLow, colorHigh, opacity, shape),
+    lutRGBA: heatmapRampRGBA(colorLow, colorHigh, opacity, shape),
+  };
+}
+
+/** Smallest positive gap between adjacent levels of both sides; the fallback step for ragged books. */
+function minGap(snapshot: HeatmapSnapshot): number {
+  let gap = Infinity;
+  for (const side of [snapshot.bids, snapshot.asks]) {
+    for (let i = 1; i < side.length; i++) {
+      const d = Math.abs(side[i]![0] - side[i - 1]![0]);
+      if (d > 0 && d < gap) gap = d;
+    }
+  }
+  return gap === Infinity ? 1 : gap;
+}
+
+/**
+ * Visits every level band of one side with `(size, yTop, yBottom)` in pane
+ * pixels. Bands reach the midpoint toward each neighbor, like the inline
+ * book's rows; edge rows extend half their own step.
+ */
+function eachSideBand(levels: readonly DepthLevel[], outward: 1 | -1, fallback: number, target: PrimitiveDrawTarget, visit: (size: number, yTop: number, yBottom: number) => void): void {
+  for (let i = 0; i < levels.length; i++) {
+    const [price, size] = levels[i]!;
+    const next = i + 1 < levels.length ? (levels[i + 1]![0] - price) * outward : NaN;
+    const prev = i > 0 ? (price - levels[i - 1]![0]) * outward : NaN;
+    const step = Number.isFinite(next) && next > 0 ? next : Number.isFinite(prev) && prev > 0 ? prev : fallback;
+    const outer = price + (outward * step) / 2;
+    const inner = i === 0 ? price - (outward * step) / 2 : (levels[i - 1]![0] + price) / 2;
+    const yA = target.priceScale.priceToY(Math.max(inner, outer));
+    const yB = target.priceScale.priceToY(Math.min(inner, outer));
+    visit(size, Math.min(yA, yB), Math.max(yA, yB));
+  }
+}
+
+/** Every level band of both sides of `snapshot`. */
+function eachBand(snapshot: HeatmapSnapshot, fallback: number, target: PrimitiveDrawTarget, visit: (size: number, yTop: number, yBottom: number) => void): void {
+  eachSideBand(snapshot.bids, -1, fallback, target, visit);
+  eachSideBand(snapshot.asks, 1, fallback, target, visit);
+}
+
+function drawHeatmap(
+  ctx: Canvas2DLike,
+  target: PrimitiveDrawTarget,
+  book: () => DepthBook | null,
+  history: DepthHistory,
+  o: ResolvedHeatmapOptions,
+  scratch: { rows: Uint8Array; xs: Float64Array },
+  state: { visibleMax: number },
+): void {
+  state.visibleMax = 0;
+  history.record(book());
+  const count = history.length;
+  const candles = target.candles;
+  const n = candles.length;
+  if (count === 0 || n === 0) return;
+  const ts = target.timeScale;
+  const rawSlots = ts.slots;
+  const slots = rawSlots !== null && rawSlots.length === n ? rawSlots : null;
+  const lastUnit = slots !== null ? slots[n - 1]! : n - 1;
+  const height = target.height;
+  const rows = Math.max(1, Math.ceil(height));
+  if (scratch.rows.length < rows) scratch.rows = new Uint8Array(rows);
+  const grid = scratch.rows;
+
+  // X pixels of every bucket from the one straddling the range's left edge.
+  const from = Math.max(0, Math.min(n - 1, Math.floor(target.range.from)));
+  const start = history.firstAtOrAfter(candles[from]!.time * 1000 - history.bucketMs);
+  if (scratch.xs.length < count - start) scratch.xs = new Float64Array(count - start);
+  const xs = scratch.xs;
+  let end = count;
+  for (let k = start; k < count; k++) {
+    const position = heatPosition(candles, slots, history.at(k)!.time);
+    const x = position === null ? NaN : ts.width - (lastUnit - position - ts.scrollOffset) * ts.barSpacing - ts.barSpacing / 2;
+    xs[k - start] = x;
+    if (x > ts.width) {
+      end = k;
+      break;
+    }
+  }
+  const intervalMs = n > 1 ? (candles[n - 1]!.time - candles[n - 2]!.time) * 1000 : 0;
+  const columnPx = intervalMs > 0 ? Math.max(1, (ts.barSpacing * history.bucketMs) / intervalMs) : Math.max(1, ts.barSpacing);
+
+  // Pass 1: the rolling normalizer — largest level size inside the window.
+  let max = 0;
+  for (let k = start; k < end; k++) {
+    const x = xs[k - start]!;
+    if (Number.isNaN(x) || x + columnPx <= 0) continue;
+    const snapshot = history.at(k)!;
+    const fallback = minGap(snapshot);
+    eachBand(snapshot, fallback, target, (size, yTop, yBottom) => {
+      if (size > max && yBottom > 0 && yTop < height) max = size;
+    });
+  }
+  if (max <= 0) return;
+  state.visibleMax = max;
+
+  // Pass 2: aggregate per pixel column × pixel row (max intensity wins), one fill per run.
+  // With a GL frame on the target (WebGL2 backend) runs become quads instead of fillRects.
+  const gl = target.gl;
+  let column = -1;
+  let lo = rows;
+  let hi = -1;
+  const flush = (nextColumn: number): void => {
+    if (column >= 0 && hi >= lo) {
+      const w = Math.max(1, nextColumn - column);
+      let r = lo;
+      while (r <= hi) {
+        const step = grid[r]!;
+        if (step === 0) {
+          r++;
+          continue;
+        }
+        let r1 = r + 1;
+        while (r1 <= hi && grid[r1] === step) r1++;
+        if (gl !== undefined) {
+          const c4 = step * 4;
+          gl.quad(column, r, w, r1 - r, o.lutRGBA[c4]!, o.lutRGBA[c4 + 1]!, o.lutRGBA[c4 + 2]!, o.lutRGBA[c4 + 3]!);
+        } else {
+          ctx.fillStyle = o.lut[step]!;
+          ctx.fillRect(column, r, w, r1 - r);
+        }
+        r = r1;
+      }
+    }
+    if (hi >= lo) grid.fill(0, lo, hi + 1);
+    lo = rows;
+    hi = -1;
+  };
+  for (let k = start; k < end; k++) {
+    const x = xs[k - start]!;
+    if (Number.isNaN(x) || x + columnPx <= 0) continue;
+    const c = Math.floor(x);
+    if (c !== column) {
+      flush(c);
+      column = c;
+    }
+    const snapshot = history.at(k)!;
+    const fallback = minGap(snapshot);
+    eachBand(snapshot, fallback, target, (size, yTop, yBottom) => {
+      if (yBottom <= 0 || yTop >= height) return;
+      const step = Math.round(heatmapIntensity(size, max, o.gamma) * (HEATMAP_RAMP_STEPS - 1));
+      if (step === 0) return;
+      // yTop < height ≤ rows, so r0 is always a valid row; a zero-height band still paints one.
+      const r0 = Math.max(0, Math.floor(yTop));
+      let r1 = Math.min(rows, Math.ceil(yBottom));
+      if (r1 <= r0) r1 = r0 + 1;
+      for (let r = r0; r < r1; r++) if (step > grid[r]!) grid[r] = step;
+      if (r0 < lo) lo = r0;
+      if (r1 - 1 > hi) hi = r1 - 1;
+    });
+  }
+  flush(column + Math.max(1, Math.round(columnPx)));
+}
+
+/** The shared-resolved primitive; `attachHeatmap` mutates `resolved` to live-update. */
+function heatmapPrimitive(book: () => DepthBook | null, resolved: ResolvedHeatmapOptions, history: DepthHistory): Heatmap {
+  const scratch = { rows: new Uint8Array(0), xs: new Float64Array(0) };
+  const state = { visibleMax: 0 };
+  return {
+    zOrder: 'behind',
+    get history() {
+      return history;
+    },
+    get visibleMax() {
+      return state.visibleMax;
+    },
+    draw(ctx, target) {
+      drawHeatmap(ctx, target, book, history, resolved, scratch, state);
+    },
+  };
+}
+
+/**
+ * A primitive painting the depth history behind the main pane's series. The
+ * book `book` returns (null paints nothing new) is recorded at draw time;
+ * options resolve over the defaults. Pixel-column aggregation keeps the fill
+ * count proportional to the viewport rather than the bucket count.
+ */
+export function createHeatmapPrimitive(book: () => DepthBook | null, options: HeatmapOptions = {}): Heatmap {
+  const resolved = resolveHeatmapOptions(options);
+  return heatmapPrimitive(book, resolved, options.history ?? new DepthHistory(resolved));
+}
+
+/** The config section as primitive options; `enabled` is handled by the attach. */
+function configOptions(config: HeatmapConfig): HeatmapOptions {
+  return {
+    bucketMs: config.bucketMs,
+    maxBuckets: config.maxBuckets,
+    maxLevels: config.maxLevels,
+    colorLow: config.colorLow,
+    colorHigh: config.colorHigh,
+    stops: config.stops,
+    opacity: config.opacity,
+    minOpacity: config.minOpacity,
+    gamma: config.gamma,
+  };
+}
+
+/**
+ * Attaches the liquidity heatmap to the main pane (z-order below the series),
+ * recording `chart.depth` on every render. Options resolve over the config's
+ * `heatmap` section, and an attached heatmap follows later
+ * `updateConfig({ heatmap })` writes (ramp, opacity, gamma, bucket grid).
+ */
+export function attachHeatmap(chart: Chart, options: HeatmapOptions = {}): HeatmapApi {
+  let explicit: HeatmapOptions = options;
+  const resolved = resolveHeatmapOptions(mergeDeep(configOptions(chart.getConfig().heatmap), explicit));
+  const history = options.history ?? new DepthHistory(resolved);
+  const primitive = heatmapPrimitive(() => chart.depth, resolved, history);
+  const handle: PanePrimitiveHandle = chart.attachPrimitive(primitive);
+
+  /** Rebuilds the ramp and re-grids future records, keeping the retained window. */
+  const apply = (): void => {
+    const next = resolveHeatmapOptions(mergeDeep(configOptions(chart.getConfig().heatmap), explicit));
+    Object.assign(resolved, next);
+    history.configure(next);
+    handle.requestUpdate();
+  };
+
+  const offConfig = chart.subscribeConfigChange(({ keys }) => {
+    if (keys.includes('heatmap')) apply();
+  });
+
+  return {
+    primitive,
+    history,
+    update(next) {
+      explicit = mergeDeep(explicit, next);
+      apply();
+    },
+    remove() {
+      offConfig();
+      handle.detach();
+    },
+  };
+}
diff --git a/packages/chart/src/render/inline-book.ts b/packages/chart/src/render/inline-book.ts
new file mode 100644
index 0000000..922b038
--- /dev/null
+++ b/packages/chart/src/render/inline-book.ts
@@ -0,0 +1,454 @@
+/**
+ * Inline order book: a live bid/ask depth ladder docked beside the plot,
+ * sharing the main pane's price scale so every row aligns with the price axis
+ * and rescales with zoom/pan. Bars grow from the dock's inner edge with width
+ * proportional to the level size, behind optional cumulative-depth shading;
+ * the spread row is highlighted and the crosshair-hovered level gets an
+ * outline plus a price/size/cumulative tooltip.
+ *
+ * The primitive reads the chart's book (`Chart.setDepth`, fed by the
+ * datafeed's depth channel) at draw time: the depth channel already
+ * re-renders the chart on every book update, so the ladder repaints through
+ * the regular render instead of a second store pushed with `requestUpdate`.
+ * Only the hover highlight uses `requestUpdate`, once per level crossing.
+ *
+ * @module
+ */
+
+import { contrastingTextColor } from '../color.js';
+import { DEFAULT_CONFIG, mergeDeep, type ChartConfig, type InlineBookConfig } from '../config.js';
+import { DOWN_COLOR, UP_COLOR } from '../indicators/types.js';
+import { SIDE_COLOR, TEXT_COLOR } from './range-profile.js';
+import type { Chart, PaneApi, PanePrimitiveHandle } from '../core/chart.js';
+import type { DepthBook } from '../core/depth.js';
+import {
+  computeInlineBookRows,
+  inlineBookRowAt,
+  DEFAULT_INLINE_BOOK_ASK_COLOR,
+  DEFAULT_INLINE_BOOK_BID_COLOR,
+  DEFAULT_INLINE_BOOK_MAX_LEVELS,
+  type InlineBookRow,
+  type InlineBookRows,
+  type InlineBookSide,
+} from '../core/inline-book.js';
+import type { Canvas2DLike } from '../dom.js';
+import type { PanePrimitive, PrimitiveDrawTarget } from './primitive.js';
+
+/** Options for {@link createInlineBookPrimitive}. */
+export interface InlineBookOptions {
+  /** Levels shown per side. Default {@link DEFAULT_INLINE_BOOK_MAX_LEVELS}. */
+  maxLevels?: number;
+  /** Bid bar color. Default {@link DEFAULT_INLINE_BOOK_BID_COLOR}. */
+  bidColor?: string;
+  /** Ask bar color. Default {@link DEFAULT_INLINE_BOOK_ASK_COLOR}. */
+  askColor?: string;
+  /** Shade cumulative depth behind the level bars. Default true. */
+  cumulative?: boolean;
+  /** Level-bar opacity; low values tint the rows behind vivid labels. Default 0.2. */
+  opacity?: number;
+  /** Cumulative shading opacity. Default 0.08. */
+  cumulativeOpacity?: number;
+  /**
+   * `'ladder'` (default) grows every level from the dock's inner edge;
+   * `'mirrored'` grows bids left and asks right from a central label column.
+   */
+  layout?: 'ladder' | 'mirrored';
+  /** Highlight the spread row and label the spread when it fits. Default true. */
+  showSpread?: boolean;
+  /**
+   * The true spread for the label, e.g. from a full-precision best bid/offer
+   * feed when the book's levels are aggregated (the band still spans the gap
+   * between the aggregated best levels). A null, negative or non-finite value
+   * falls back to that gap. Default: the gap.
+   */
+  spread?: () => number | null;
+  /** Spread-row color; `'text'` follows the theme text color. Default `'text'`. */
+  spreadColor?: string;
+  /** Size label per row when the row is tall enough. Default true. */
+  showLabels?: boolean;
+  /**
+   * Row label color; `'side'` colors each size like its side, `'text'` follows
+   * the theme text color. The best bid and ask are bold. Default `'side'`.
+   */
+  labelColor?: string;
+  /** Outline the crosshair-hovered level and show its tooltip. Default true. */
+  showHover?: boolean;
+}
+
+/** Input for {@link attachInlineBook}. */
+export interface InlineBookAttachOptions extends InlineBookOptions {
+  /** Host pane id. Default `'inline-book'`. */
+  id?: string;
+  /**
+   * Canvas edge the book docks to, or `'overlay'` to paint it behind the
+   * series along the main plot's right edge. Default `'overlay'` when the
+   * config's `inlineBook.placement` is, else `'right'`.
+   */
+  placement?: 'left' | 'right' | 'overlay';
+  /** Book width in CSS pixels. Default the config's `inlineBook.width`. */
+  width?: number;
+  /** Overlay only: gap in CSS pixels between the band and the price axis. Default the config's `inlineBook.inset`. */
+  inset?: number;
+}
+
+/** Handle of an inline book attached via {@link attachInlineBook}. */
+export interface InlineBookApi {
+  /** The docked book pane; null for an overlay. */
+  readonly pane: PaneApi | null;
+  /** Merges new options (and dock `width`) and re-renders. */
+  update(options: InlineBookAttachOptions): void;
+  /** Drops the hover/config subscriptions, detaches the primitive and removes the pane. */
+  remove(): void;
+}
+
+/** A pane primitive drawing the depth ladder; see {@link createInlineBookPrimitive}. */
+export interface InlineBook extends PanePrimitive {
+  /** The ladder the last draw computed, or null when no book is set. */
+  readonly rows: InlineBookRows | null;
+  /** Sets the crosshair-hovered price for the next draw; null clears the highlight. */
+  setHover(price: number | null): void;
+}
+
+interface ResolvedInlineBookOptions {
+  maxLevels: number;
+  spread: (() => number | null) | null;
+  layout: 'ladder' | 'mirrored';
+  bidColor: string;
+  askColor: string;
+  cumulative: boolean;
+  opacity: number;
+  cumulativeOpacity: number;
+  showSpread: boolean;
+  spreadColor: string;
+  showLabels: boolean;
+  labelColor: string;
+  showHover: boolean;
+}
+
+function resolveInlineBookOptions(o: InlineBookOptions): ResolvedInlineBookOptions {
+  return {
+    maxLevels: Math.max(1, Math.floor(o.maxLevels ?? DEFAULT_INLINE_BOOK_MAX_LEVELS)),
+    spread: o.spread ?? null,
+    layout: o.layout ?? 'ladder',
+    bidColor: o.bidColor ?? DEFAULT_INLINE_BOOK_BID_COLOR,
+    askColor: o.askColor ?? DEFAULT_INLINE_BOOK_ASK_COLOR,
+    cumulative: o.cumulative ?? true,
+    opacity: o.opacity ?? 0.2,
+    cumulativeOpacity: o.cumulativeOpacity ?? 0.08,
+    showSpread: o.showSpread ?? true,
+    spreadColor: o.spreadColor ?? TEXT_COLOR,
+    showLabels: o.showLabels ?? true,
+    labelColor: o.labelColor ?? SIDE_COLOR,
+    showHover: o.showHover ?? true,
+  };
+}
+
+/** Compact level size: `0.0250`, `12.40`, `1.25K`, `3.40M`. */
+export function formatBookSize(size: number): string {
+  const abs = Math.abs(size);
+  if (abs >= 1_000_000) return `${(size / 1_000_000).toFixed(2)}M`;
+  if (abs >= 1_000) return `${(size / 1_000).toFixed(2)}K`;
+  if (abs >= 1) return size.toFixed(2);
+  return size.toFixed(4);
+}
+
+/** Y pixels of a row band's top and bottom edges. */
+function rowY(target: PrimitiveDrawTarget, row: InlineBookRow): { y0: number; y1: number } {
+  return { y0: target.priceScale.priceToY(row.high), y1: target.priceScale.priceToY(row.low) };
+}
+
+/** Colors and label font a draw resolved from the options' tokens and the chart theme. */
+interface BookPaint {
+  readonly bid: string;
+  readonly ask: string;
+  readonly bidLabel: string;
+  readonly askLabel: string;
+  readonly spread: string;
+  readonly font: string;
+  /** The chart's price formatter, for the spread label and hover tooltip. */
+  readonly price: (value: number) => string;
+}
+
+function token(value: string, config: ChartConfig): string {
+  return value === UP_COLOR ? config.series.upColor : value === DOWN_COLOR ? config.series.downColor
+    : value === TEXT_COLOR ? config.theme.textColor : value;
+}
+
+function bookPaint(o: ResolvedInlineBookOptions, config: ChartConfig): BookPaint {
+  const bid = token(o.bidColor, config), ask = token(o.askColor, config);
+  const side = o.labelColor === SIDE_COLOR;
+  const label = token(o.labelColor, config);
+  return {
+    bid, ask,
+    bidLabel: side ? bid : label,
+    askLabel: side ? ask : label,
+    spread: token(o.spreadColor, config),
+    font: `11px ${config.theme.monoFamily}`,
+    price: config.formatters.price,
+  };
+}
+
+/** Rows shorter than this skip their size label. */
+const LABEL_MIN_ROW_PX = 11;
+
+/** Width of the mirrored layout's central size-label column. */
+const MIRROR_SPINE_PX = 34;
+
+/** Where one side's bars grow: from `anchor` toward `dir` over at most `span` pixels, labelled at `labelX`. */
+interface SideGeometry {
+  readonly anchor: number;
+  readonly dir: -1 | 1;
+  readonly span: number;
+  readonly labelX: number;
+  readonly labelAlign: 'right' | 'center';
+}
+
+/** Ladder: every level grows leftward from the inner edge. Mirrored: bids left and asks right of the spine. */
+function sideGeometry(target: PrimitiveDrawTarget, layout: ResolvedInlineBookOptions['layout'], ask: boolean): SideGeometry {
+  if (layout === 'ladder') return { anchor: target.width, dir: -1, span: target.width, labelX: target.width - 4, labelAlign: 'right' };
+  const spine = Math.min(MIRROR_SPINE_PX, target.width);
+  const half = (target.width - spine) / 2;
+  return ask
+    ? { anchor: half + spine, dir: 1, span: half, labelX: target.width / 2, labelAlign: 'center' }
+    : { anchor: half, dir: -1, span: half, labelX: target.width / 2, labelAlign: 'center' };
+}
+
+function drawSide(
+  ctx: Canvas2DLike,
+  target: PrimitiveDrawTarget,
+  side: InlineBookSide,
+  color: string,
+  labelColor: string,
+  font: string,
+  maxSize: number,
+  maxCumulative: number,
+  o: ResolvedInlineBookOptions,
+  g: SideGeometry,
+): void {
+  const alpha = ctx.globalAlpha;
+  ctx.textAlign = g.labelAlign;
+  ctx.textBaseline = 'middle';
+  const bar = (w: number): number => (g.dir < 0 ? g.anchor - w : g.anchor);
+  side.rows.forEach((row, i) => {
+    const { y0, y1 } = rowY(target, row);
+    if (y0 >= target.height || y1 <= 0) return;
+    const h = Math.max(1, y1 - y0 - 0.5);
+    ctx.fillStyle = color;
+    if (o.cumulative) {
+      const cw = (row.cumulative / maxCumulative) * g.span;
+      ctx.globalAlpha = alpha * o.cumulativeOpacity;
+      ctx.fillRect(bar(cw), y0, cw, h);
+    }
+    const w = (row.size / maxSize) * g.span;
+    ctx.globalAlpha = alpha * o.opacity;
+    ctx.fillRect(bar(w), y0, w, h);
+    // Each row labels itself only when tall enough, so dense fine levels beside coarse ones never overlap.
+    if (o.showLabels && y1 - y0 >= LABEL_MIN_ROW_PX) {
+      ctx.globalAlpha = alpha;
+      ctx.fillStyle = labelColor;
+      // Medium weight keeps thin glyphs vivid over the tint; the best level is bold.
+      ctx.font = i === 0 ? `bold ${font}` : `500 ${font}`;
+      ctx.fillText(formatBookSize(row.size), g.labelX, (y0 + y1) / 2);
+    }
+  });
+  ctx.globalAlpha = alpha;
+}
+
+/** The band between the best prices, drawn under the rows, with edge ticks and a spread label when it fits. */
+function drawSpread(ctx: Canvas2DLike, target: PrimitiveDrawTarget, rows: InlineBookRows, paint: BookPaint, o: ResolvedInlineBookOptions): void {
+  const bid = rows.bids.rows[0];
+  const ask = rows.asks.rows[0];
+  if (bid === undefined || ask === undefined || rows.spread === null) return;
+  const y0 = target.priceScale.priceToY(ask.price);
+  const y1 = target.priceScale.priceToY(bid.price);
+  const y = Math.min(y0, y1);
+  const h = Math.max(1, Math.abs(y1 - y0));
+  const alpha = ctx.globalAlpha;
+  ctx.fillStyle = paint.spread;
+  ctx.globalAlpha = alpha * 0.12;
+  ctx.fillRect(0, y, target.width, h);
+  ctx.globalAlpha = alpha * 0.5;
+  ctx.fillRect(0, y - 0.5, target.width, 1);
+  ctx.fillRect(0, y + h - 0.5, target.width, 1);
+  if (h >= 12) {
+    ctx.globalAlpha = alpha;
+    ctx.font = paint.font;
+    ctx.textAlign = 'right';
+    ctx.textBaseline = 'middle';
+    const exact = o.spread?.() ?? null;
+    const spread = exact !== null && Number.isFinite(exact) && exact >= 0 ? exact : rows.spread;
+    ctx.fillText(`Δ ${paint.price(spread)}`, target.width - 4, y + h / 2);
+  }
+  ctx.globalAlpha = alpha;
+}
+
+/** Outline of the hovered level plus a `price · size  Σ cumulative` tooltip beside it. */
+function drawHover(ctx: Canvas2DLike, target: PrimitiveDrawTarget, rows: InlineBookRows, price: number, paint: BookPaint): void {
+  const side = rows.bestAsk !== null && price >= rows.bestAsk ? rows.asks
+    : rows.bestBid !== null && price <= rows.bestBid ? rows.bids
+      : null;
+  const row = side === null ? null : inlineBookRowAt(side, price);
+  if (row === null || side === null) return;
+  const color = side === rows.asks ? paint.ask : paint.bid;
+  const { y0, y1 } = rowY(target, row);
+  ctx.strokeStyle = color;
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  ctx.rect(0.5, y0 + 0.5, target.width - 1, Math.max(1, y1 - y0 - 1));
+  ctx.stroke();
+  const text = `${paint.price(row.price)} · ${formatBookSize(row.size)}  Σ ${formatBookSize(row.cumulative)}`;
+  ctx.font = paint.font;
+  const th = 16;
+  const tw = Math.min(ctx.measureText(text).width + 8, target.width);
+  const ty = Math.min(Math.max(0, (y0 + y1) / 2 - th / 2), Math.max(0, target.height - th));
+  ctx.fillStyle = color;
+  ctx.fillRect(0, ty, tw, th);
+  ctx.fillStyle = contrastingTextColor(color);
+  ctx.textAlign = 'left';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(text, 4, ty + th / 2);
+}
+
+/**
+ * A primitive painting the depth ladder of the book `book` returns (null
+ * draws nothing): asks above the spread, bids below, both anchored to the
+ * dock's inner edge. Rows sit at their exact prices on the shared scale, so
+ * the ladder rescales with the main pane on zoom and pan.
+ */
+export function createInlineBookPrimitive(book: () => DepthBook | null, options: InlineBookOptions = {}): InlineBook {
+  return inlineBookPrimitive(book, resolveInlineBookOptions(options), () => DEFAULT_CONFIG);
+}
+
+/** The shared-resolved primitive; `attachInlineBook` mutates `resolved` to live-update. */
+function inlineBookPrimitive(book: () => DepthBook | null, resolved: ResolvedInlineBookOptions, theme: () => ChartConfig): InlineBook {
+  let hover: number | null = null;
+  let rows: InlineBookRows | null = null;
+
+  function draw(ctx: Canvas2DLike, target: PrimitiveDrawTarget): void {
+    const current = book();
+    rows = current === null ? null : computeInlineBookRows(current, resolved.maxLevels);
+    if (rows === null) return;
+    const maxSize = Math.max(rows.bids.maxSize, rows.asks.maxSize);
+    if (maxSize <= 0) return;
+    // Cumulative depth is at least the largest level, so it is positive here.
+    const maxCumulative = Math.max(rows.bids.maxCumulative, rows.asks.maxCumulative);
+    const paint = bookPaint(resolved, theme());
+    ctx.save();
+    if (resolved.showSpread) drawSpread(ctx, target, rows, paint, resolved);
+    drawSide(ctx, target, rows.asks, paint.ask, paint.askLabel, paint.font, maxSize, maxCumulative, resolved, sideGeometry(target, resolved.layout, true));
+    drawSide(ctx, target, rows.bids, paint.bid, paint.bidLabel, paint.font, maxSize, maxCumulative, resolved, sideGeometry(target, resolved.layout, false));
+    if (resolved.showHover && hover !== null) drawHover(ctx, target, rows, hover, paint);
+    ctx.restore();
+  }
+
+  return {
+    get rows() {
+      return rows;
+    },
+    setHover(price) {
+      hover = price;
+    },
+    draw,
+  };
+}
+
+/**
+ * Paints `book` behind the series in a `width()`-pixel band of the main pane,
+ * `inset()` pixels in from the price axis, so the book takes no plot width.
+ */
+function overlayPrimitive(book: InlineBook, width: () => number, inset: () => number): PanePrimitive {
+  return {
+    zOrder: 'behind',
+    draw(ctx, target) {
+      const w = Math.min(width(), target.width);
+      ctx.save();
+      ctx.translate(Math.max(0, target.width - w - inset()), 0);
+      book.draw(ctx, { ...target, width: w });
+      ctx.restore();
+    },
+  };
+}
+
+/** The config section as primitive options; `enabled` and `width` are handled by the attach. */
+function configOptions(config: InlineBookConfig): InlineBookOptions {
+  return {
+    maxLevels: config.maxLevels,
+    layout: config.layout,
+    bidColor: config.bidColor,
+    askColor: config.askColor,
+    cumulative: config.cumulative,
+    showLabels: config.showLabels,
+  };
+}
+
+/**
+ * Docks the live inline order book at `placement` (sharing the main price
+ * scale), reading `chart.depth` on every render. Options resolve over the
+ * config's `inlineBook` section, and an attached book follows later
+ * `updateConfig({ inlineBook })` writes (level count, colors, cumulative
+ * shading, labels, width). The crosshair hover repaints once per level
+ * crossing, not per pointer move.
+ */
+export function attachInlineBook(chart: Chart, options: InlineBookAttachOptions = {}): InlineBookApi {
+  let explicit: InlineBookAttachOptions = options;
+  const resolved = resolveInlineBookOptions(mergeDeep(configOptions(chart.getConfig().inlineBook), explicit));
+  const placement = options.placement ?? (chart.getConfig().inlineBook.placement === 'overlay' ? 'overlay' : 'right');
+  let dockWidth = options.width ?? chart.getConfig().inlineBook.width;
+  const primitive = inlineBookPrimitive(() => chart.depth, resolved, () => chart.getConfig());
+  let pane: PaneApi | null = null;
+  let handle: PanePrimitiveHandle;
+  if (placement === 'overlay') {
+    handle = chart.attachPrimitive(overlayPrimitive(primitive, () => dockWidth,
+      () => explicit.inset ?? chart.getConfig().inlineBook.inset));
+  } else {
+    pane = chart.addPane({ id: options.id ?? 'inline-book', placement, width: dockWidth, sharePriceScale: true });
+    handle = pane.attachPrimitive(primitive);
+  }
+  const resize = (width: number): void => {
+    dockWidth = width;
+    pane?.setWidth(width);
+  };
+  let hoverKey: string | null = null;
+
+  /** Repaints the hover only when the pointer crosses into another level. */
+  const offCrosshair = chart.subscribeCrosshairMove((event) => {
+    const price = event.active ? event.price : null;
+    let key: string | null = null;
+    if (price !== null && primitive.rows !== null) {
+      const rows = primitive.rows;
+      const side = rows.bestAsk !== null && price >= rows.bestAsk ? rows.asks
+        : rows.bestBid !== null && price <= rows.bestBid ? rows.bids
+          : null;
+      const row = side === null ? null : inlineBookRowAt(side, price);
+      if (row !== null) key = `${side === rows.asks ? 'a' : 'b'}:${row.price}`;
+    }
+    if (key === hoverKey) return;
+    hoverKey = key;
+    primitive.setHover(key === null ? null : price);
+    handle.requestUpdate();
+  });
+
+  const offConfig = chart.subscribeConfigChange(({ keys }) => {
+    if (!keys.includes('inlineBook')) return;
+    const config = chart.getConfig().inlineBook;
+    Object.assign(resolved, resolveInlineBookOptions(mergeDeep(configOptions(config), explicit)));
+    if (explicit.width === undefined && config.width !== dockWidth) resize(config.width);
+    handle.requestUpdate();
+  });
+
+  return {
+    pane,
+    update(next) {
+      explicit = mergeDeep(explicit, next);
+      Object.assign(resolved, resolveInlineBookOptions(mergeDeep(configOptions(chart.getConfig().inlineBook), explicit)));
+      if (next.width !== undefined && next.width !== dockWidth) resize(next.width);
+      handle.requestUpdate();
+    },
+    remove() {
+      offCrosshair();
+      offConfig();
+      handle.detach();
+      pane?.remove();
+    },
+  };
+}
diff --git a/packages/chart/src/render/primitive.ts b/packages/chart/src/render/primitive.ts
new file mode 100644
index 0000000..01fe46b
--- /dev/null
+++ b/packages/chart/src/render/primitive.ts
@@ -0,0 +1,55 @@
+/**
+ * Pane primitives: host draw passes attached to a pane, in the spirit of
+ * TradingView's `IPanePrimitive`. A primitive paints on the pane's own canvas
+ * layer, below or above its series and indicators.
+ *
+ * @module
+ */
+
+import type { Candle } from '../core/data.js';
+import type { PriceScale, TimeScale, VisibleRange } from '../core/scale.js';
+import type { Canvas2DLike } from '../dom.js';
+import type { GLQuadSink } from './gl/backend.js';
+
+/** What a primitive sees when it draws. All sizes are CSS pixels. */
+export interface PrimitiveDrawTarget {
+  /** Pane width; the context is translated to the pane's top-left and clipped to `width` × `height`. */
+  readonly width: number;
+  readonly height: number;
+  readonly priceScale: PriceScale;
+  readonly timeScale: TimeScale;
+  /** Bar range the pane's content draws (may extend past the viewport on a continuous axis). */
+  readonly range: VisibleRange;
+  readonly candles: readonly Candle[];
+  readonly pixelRatio: number;
+  /**
+   * Set only on the main pane when the WebGL2 backend is active. Primitives
+   * that can emit their geometry as quads (e.g. the heatmap) submit them here
+   * instead of painting `ctx`; the frame composites at the series layer.
+   */
+  readonly gl?: GLQuadSink;
+}
+
+/** A custom canvas layer attached to a pane. */
+export interface PanePrimitive {
+  /** `'behind'` draws under the pane's series and indicators, `'above'` (default) over them. */
+  readonly zOrder?: 'behind' | 'above';
+  /** Paints the layer into the pane-clipped, pane-translated context. */
+  draw(ctx: Canvas2DLike, target: PrimitiveDrawTarget): void;
+}
+
+/** Primitives of one pane, split by z-order for the renderer. */
+export interface PanePrimitives {
+  readonly behind: readonly PanePrimitive[];
+  readonly above: readonly PanePrimitive[];
+}
+
+/** Splits primitives into `behind`/`above` draw passes, preserving order. */
+export function splitPrimitives(primitives: readonly PanePrimitive[]): PanePrimitives {
+  const behind: PanePrimitive[] = [];
+  const above: PanePrimitive[] = [];
+  for (const primitive of primitives) {
+    (primitive.zOrder === 'behind' ? behind : above).push(primitive);
+  }
+  return { behind, above };
+}
diff --git a/packages/chart/src/render/range-profile.ts b/packages/chart/src/render/range-profile.ts
new file mode 100644
index 0000000..48eecb5
--- /dev/null
+++ b/packages/chart/src/render/range-profile.ts
@@ -0,0 +1,327 @@
+/**
+ * Visible-range volume profile floating over the plot's right edge: one row
+ * per round price step (sized so rows stay about `rowHeight` pixels tall)
+ * across the visible price range, down volume growing left and up volume
+ * right from a central column of size labels. Each row is shaded by its share
+ * of the busiest row, and the point of control (POC) is outlined. It is
+ * rebuilt from the candles in view on every render, so it follows zoom, pan
+ * and live bars; candles draw over it.
+ *
+ * Colors default to theme tokens (`'up'` / `'down'` follow the series colors,
+ * `'text'` the theme text color), resolved on every draw so the profile
+ * tracks theme switches. With a frame scheduler, bar widths and shading tween
+ * to each new value; a row that appears after a re-bucket starts from the
+ * previous frame's shape at its price, so a zoom morphs rather than flickers.
+ *
+ * @module
+ */
+
+import { DEFAULT_CONFIG, type ChartConfig } from '../config.js';
+import type { Chart, PanePrimitiveHandle } from '../core/chart.js';
+import { gridVolumeRows, profileStep } from '../core/profile.js';
+import type { FrameScheduler } from '../core/zoom.js';
+import type { Canvas2DLike } from '../dom.js';
+import { DOWN_COLOR, UP_COLOR } from '../indicators/types.js';
+import type { PanePrimitive, PrimitiveDrawTarget } from './primitive.js';
+
+/** Color token resolving to the chart theme's text color. */
+export const TEXT_COLOR = 'text';
+
+/** Label color token: each size takes its own side's bar color (down left, up right). */
+export const SIDE_COLOR = 'side';
+
+/** Options for {@link createRangeProfilePrimitive} and {@link attachRangeProfile}. */
+export interface RangeProfileOptions {
+  /** Profile width in CSS pixels. Default 200. */
+  width?: number;
+  /** Gap in CSS pixels between the profile and the price axis. Default 48. */
+  inset?: number;
+  /** Target row height in CSS pixels; the price step rounds to 1/2/2.5/5 × 10ⁿ. Default 14. */
+  rowHeight?: number;
+  /** Gap in CSS pixels between rows. Default 1. */
+  rowGap?: number;
+  /** Up-volume (buy) bar color, growing right; `'up'` follows `series.upColor`. Default `'up'`. */
+  upColor?: string;
+  /** Down-volume (sell) bar color, growing left; `'down'` follows `series.downColor`. Default `'down'`. */
+  downColor?: string;
+  /** Opacity of the busiest row's bars; low values tint the rows behind vivid labels. Default 0.35. */
+  opacity?: number;
+  /** Opacity of the quietest row as a fraction of `opacity`. Default 0.3. */
+  minOpacity?: number;
+  /** Down/up size labels beside the center line when rows are tall enough. Default true. */
+  showLabels?: boolean;
+  /**
+   * Label color; `'side'` colors each size like its side's bars, `'text'` follows
+   * the theme text color. The POC row's sizes are bold. Default `'side'`.
+   */
+  labelColor?: string;
+  /** Label size in CSS pixels, in the theme's mono family at medium weight. Default 11. */
+  fontSize?: number;
+  /** Outline the point of control (the busiest row). Default true. */
+  showPoc?: boolean;
+  /** POC outline color; `'text'` follows the theme text color. Default `'text'`. */
+  pocColor?: string;
+  /** Transition length in ms when a scheduler drives the profile; 0 applies changes at once. Default 180. */
+  duration?: number;
+  /** Transition timing. Default `'linear'`. */
+  easing?: 'linear' | 'ease-out';
+}
+
+/** Input for {@link attachRangeProfile}. */
+export interface RangeProfileAttachOptions extends RangeProfileOptions {
+  /** Drives the transitions (e.g. `createFrameScheduler`); without one, changes apply at once. */
+  scheduler?: FrameScheduler;
+}
+
+/** Handle of a profile attached via {@link attachRangeProfile}. */
+export interface RangeProfileApi {
+  /** Merges new options and re-renders. */
+  update(options: RangeProfileOptions): void;
+  /** Detaches the profile and cancels a pending transition frame. */
+  remove(): void;
+}
+
+type ResolvedRangeProfileOptions = Required<RangeProfileOptions>;
+
+/** Colors the tokens resolve to. */
+interface ProfileTheme {
+  readonly up: string;
+  readonly down: string;
+  readonly text: string;
+  readonly font: string;
+}
+
+/** Clock and frame request of an animated profile. */
+interface ProfileClock {
+  now(): number;
+  frame(): void;
+}
+
+/** A row's displayed geometry: bar widths in pixels and its 0–1 shading. */
+interface Shape {
+  readonly down: number;
+  readonly up: number;
+  readonly shade: number;
+}
+
+interface Tween {
+  readonly from: Shape;
+  readonly to: Shape;
+  readonly start: number;
+}
+
+/** A row as last drawn, by price bounds, for re-bucket starts. */
+interface DrawnRow {
+  readonly lo: number;
+  readonly hi: number;
+  readonly shape: Shape;
+}
+
+/** Most rows one profile draws; a guard against a degenerate price scale. */
+const MAX_ROWS = 2_000;
+
+/** Rows shorter than this skip their labels. */
+const LABEL_MIN_ROW_PX = 9;
+
+const EMPTY: Shape = { down: 0, up: 0, shade: 0 };
+
+function resolve(o: RangeProfileOptions): ResolvedRangeProfileOptions {
+  return {
+    width: o.width ?? 200,
+    inset: o.inset ?? 48,
+    rowHeight: Math.max(2, o.rowHeight ?? 14),
+    rowGap: Math.max(0, o.rowGap ?? 1),
+    upColor: o.upColor ?? UP_COLOR,
+    downColor: o.downColor ?? DOWN_COLOR,
+    opacity: Math.min(1, Math.max(0, o.opacity ?? 0.35)),
+    minOpacity: Math.min(1, Math.max(0, o.minOpacity ?? 0.3)),
+    showLabels: o.showLabels ?? true,
+    labelColor: o.labelColor ?? SIDE_COLOR,
+    fontSize: o.fontSize ?? 11,
+    showPoc: o.showPoc ?? true,
+    pocColor: o.pocColor ?? TEXT_COLOR,
+    duration: Math.max(0, o.duration ?? 180),
+    easing: o.easing ?? 'linear',
+  };
+}
+
+function themeOf(config: ChartConfig): ProfileTheme {
+  return { up: config.series.upColor, down: config.series.downColor, text: config.theme.textColor, font: config.theme.monoFamily };
+}
+
+function color(value: string, theme: ProfileTheme): string {
+  return value === UP_COLOR ? theme.up : value === DOWN_COLOR ? theme.down : value === TEXT_COLOR ? theme.text : value;
+}
+
+/** Compact volume label: `823`, `3K`, `12K`, `1.2M`. */
+export function formatProfileVolume(volume: number): string {
+  const abs = Math.abs(volume);
+  if (abs >= 1_000_000) return `${(volume / 1_000_000).toFixed(1)}M`;
+  if (abs >= 1_000) return `${Math.round(volume / 1_000)}K`;
+  return String(Math.round(volume));
+}
+
+function lerp(a: Shape, b: Shape, t: number): Shape {
+  return { down: a.down + (b.down - a.down) * t, up: a.up + (b.up - a.up) * t, shade: a.shade + (b.shade - a.shade) * t };
+}
+
+const sameShape = (a: Shape, b: Shape): boolean => a.down === b.down && a.up === b.up && a.shade === b.shade;
+
+/** The primitive; `resolved` is read on every draw so `update` restyles in place. */
+function rangeProfilePrimitive(resolved: ResolvedRangeProfileOptions, theme: () => ProfileTheme, clock: ProfileClock | null): PanePrimitive {
+  let tweens = new Map<number, Tween>();
+  let drawn: DrawnRow[] = [];
+
+  /** Progress of `tween` at `now`, eased. */
+  const progress = (tween: Tween, now: number): number => {
+    const t = Math.min(1, (now - tween.start) / resolved.duration);
+    return resolved.easing === 'linear' ? t : 1 - (1 - t) ** 3;
+  };
+  /** The previous frame's shape at `price`: a re-bucketed row starts where the profile was. */
+  const shapeAt = (price: number): Shape => drawn.find((row) => price >= row.lo && price < row.hi)?.shape ?? EMPTY;
+
+  function draw(ctx: Canvas2DLike, target: PrimitiveDrawTarget): void {
+    const o = resolved;
+    const { priceScale, height } = target;
+    const a = priceScale.yToPrice(0), b = priceScale.yToPrice(height);
+    const pMin = Math.min(a, b), pMax = Math.max(a, b);
+    const step = profileStep(((pMax - pMin) / height) * o.rowHeight);
+    const lo = Math.floor(pMin / step) * step;
+    const rows = pMax > pMin ? Math.min(MAX_ROWS, Math.ceil((pMax - lo) / step)) : 0; // none in a zero-height pane
+    const { up, down } = gridVolumeRows(target.candles, target.range.from, target.range.to - 1, lo, step, rows);
+    // Bars scale to the largest single side, so it spans its half; shading and the POC follow row totals.
+    let max = 0, poc = -1, sideMax = 0;
+    for (let r = 0; r < rows; r++) {
+      const total = up[r]! + down[r]!;
+      sideMax = Math.max(sideMax, up[r]!, down[r]!);
+      if (total > max) {
+        max = total;
+        poc = r;
+      }
+    }
+    if (max <= 0) {
+      tweens = new Map();
+      drawn = [];
+      return;
+    }
+
+    const animate = clock !== null && o.duration > 0;
+    const colors = theme();
+    const w = Math.min(o.width, target.width);
+    const x0 = Math.max(0, target.width - w - o.inset);
+    const cx = x0 + w / 2;
+    const half = w / 2;
+    const alpha = ctx.globalAlpha;
+    const now = animate ? clock.now() : 0;
+    const nextTweens = new Map<number, Tween>();
+    const nextDrawn: DrawnRow[] = [];
+    let moving = false;
+    const size = `${o.fontSize}px ${colors.font}`;
+    const font = `500 ${size}`; // medium weight keeps thin glyphs vivid over the tint
+    const downLabel = color(o.labelColor === SIDE_COLOR ? o.downColor : o.labelColor, colors);
+    const upLabel = color(o.labelColor === SIDE_COLOR ? o.upColor : o.labelColor, colors);
+    ctx.save();
+    ctx.font = font;
+    ctx.textBaseline = 'middle';
+    for (let r = 0; r < rows; r++) {
+      const rowLo = lo + r * step;
+      const total = up[r]! + down[r]!;
+      const goal: Shape = { down: (down[r]! / sideMax) * half, up: (up[r]! / sideMax) * half, shade: total / max };
+      let shape = goal;
+      if (animate) {
+        const key = Number(rowLo.toPrecision(12));
+        const prev = tweens.get(key);
+        const tween = prev === undefined ? { from: shapeAt(rowLo + step / 2), to: goal, start: now }
+          : sameShape(prev.to, goal) ? prev
+            : { from: lerp(prev.from, prev.to, progress(prev, now)), to: goal, start: now };
+        const t = progress(tween, now);
+        shape = lerp(tween.from, tween.to, t);
+        if (t < 1) moving = true;
+        nextTweens.set(key, tween);
+      }
+      nextDrawn.push({ lo: rowLo, hi: rowLo + step, shape });
+      const visible = shape.down + shape.up > 0;
+      if (total <= 0 && !visible) continue; // an empty row, or one done shrinking
+      const ya = priceScale.priceToY(rowLo), yb = priceScale.priceToY(rowLo + step);
+      const y0 = Math.min(ya, yb), y1 = Math.max(ya, yb);
+      const h = Math.max(1, y1 - y0 - o.rowGap);
+      if (visible) {
+        ctx.globalAlpha = alpha * o.opacity * (o.minOpacity + (1 - o.minOpacity) * shape.shade);
+        ctx.fillStyle = color(o.downColor, colors);
+        ctx.fillRect(cx - shape.down, y0, shape.down, h);
+        ctx.fillStyle = color(o.upColor, colors);
+        ctx.fillRect(cx, y0, shape.up, h);
+      }
+      if (total <= 0) continue; // shrinking out: bars only, no labels
+      if (o.showLabels && h >= LABEL_MIN_ROW_PX) {
+        ctx.globalAlpha = alpha;
+        if (r === poc) ctx.font = `bold ${size}`;
+        ctx.fillStyle = downLabel;
+        ctx.textAlign = 'right';
+        ctx.fillText(formatProfileVolume(down[r]!), cx - 3, y0 + h / 2);
+        ctx.fillStyle = upLabel;
+        ctx.textAlign = 'left';
+        ctx.fillText(formatProfileVolume(up[r]!), cx + 3, y0 + h / 2);
+        if (r === poc) ctx.font = font;
+      }
+      if (o.showPoc && r === poc) {
+        ctx.globalAlpha = alpha;
+        ctx.strokeStyle = color(o.pocColor, colors);
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        ctx.rect(x0 + 0.5, y0 + 0.5, w - 1, Math.max(1, h - 1));
+        ctx.stroke();
+      }
+    }
+    ctx.restore();
+    tweens = nextTweens;
+    drawn = nextDrawn;
+    if (moving) clock!.frame();
+  }
+
+  return { zOrder: 'behind', draw };
+}
+
+/**
+ * A main-pane primitive painting the visible-range profile; attach it with
+ * `chart.attachPrimitive`. Color tokens resolve against the default theme and
+ * changes apply at once; {@link attachRangeProfile} follows the chart's theme
+ * and can animate.
+ */
+export function createRangeProfilePrimitive(options: RangeProfileOptions = {}): PanePrimitive {
+  return rangeProfilePrimitive(resolve(options), () => themeOf(DEFAULT_CONFIG), null);
+}
+
+/**
+ * Attaches a visible-range profile to the main pane. Color tokens follow the
+ * chart's live config; with a `scheduler`, changes tween over `duration`.
+ * {@link RangeProfileApi.update} restyles it live.
+ */
+export function attachRangeProfile(chart: Chart, options: RangeProfileAttachOptions = {}): RangeProfileApi {
+  const { scheduler, ...style } = options;
+  let current: RangeProfileOptions = style;
+  const resolved = resolve(current);
+  let pending: number | null = null;
+  const clock: ProfileClock | null = scheduler === undefined ? null : {
+    now: () => scheduler.now(),
+    frame: () => {
+      pending ??= scheduler.request(() => {
+        pending = null;
+        handle.requestUpdate();
+      });
+    },
+  };
+  const handle: PanePrimitiveHandle = chart.attachPrimitive(rangeProfilePrimitive(resolved, () => themeOf(chart.getConfig()), clock));
+  return {
+    update(next) {
+      current = { ...current, ...next };
+      Object.assign(resolved, resolve(current));
+      handle.requestUpdate();
+    },
+    remove() {
+      if (pending !== null) scheduler!.cancel(pending);
+      pending = null;
+      handle.detach();
+    },
+  };
+}
diff --git a/packages/chart/src/render/renderer.ts b/packages/chart/src/render/renderer.ts
index 9a135f1..dab08d3 100644
--- a/packages/chart/src/render/renderer.ts
+++ b/packages/chart/src/render/renderer.ts
@@ -9,11 +9,15 @@
 import type { Candle } from '../core/data.js';
 import type { PriceScale, TimeScale, VisibleRange } from '../core/scale.js';
 import type { PaneLayout } from '../core/pane.js';
-import type { ChartConfig } from '../config.js';
+import type { ChartConfig, SeriesType } from '../config.js';
 import type { IndicatorOutput } from '../indicators/types.js';
 import type { Canvas2DLike } from '../dom.js';
 import { contrastingTextColor } from '../color.js';
-import { SERIES_RENDERERS } from '../series/index.js';
+import { SERIES_RENDERERS, drawCandlesticks } from '../series/index.js';
+import type { SeriesDrawFn } from '../series/types.js';
+import type { PanePrimitives, PrimitiveDrawTarget } from './primitive.js';
+import { packCandleQuads } from './gl/candles.js';
+import type { GLFrame, GLQuadSink } from './gl/backend.js';
 import { drawWatermark } from '../watermark.js';
 import { drawTimeAxis, timeTickIndices } from './axis.js';
 import { drawDrawings, type ResolvedDrawing } from './drawings.js';
@@ -39,6 +43,21 @@ export interface PaneRenderInfo {
   readonly indicatorOpacities?: readonly number[];
   /** Sub-pane opacity, including its grid, separator and axis. Defaults to 1. */
   readonly opacity?: number;
+  /** Custom draw passes attached to the pane (`behind` runs under its series/indicators, `above` over them). */
+  readonly primitives?: PanePrimitives;
+}
+
+/** A host pane docked to a canvas edge (`Chart.addPane` with `placement: 'left' | 'right'`). */
+export interface DockedPaneRenderInfo {
+  readonly id: string;
+  readonly placement: 'left' | 'right';
+  /** Absolute canvas rectangle in CSS pixels. */
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly priceScale: PriceScale;
+  readonly primitives: PanePrimitives;
 }
 
 /** Everything {@link renderChart} needs for one frame. All sizes are CSS pixels. */
@@ -64,8 +83,15 @@ export interface RenderView {
   readonly displayCandles?: readonly Candle[];
   readonly range: VisibleRange;
   readonly timeScale: TimeScale;
-  /** First entry is the main pane; the rest are indicator sub-panes. */
+  /** First entry is the main pane; the rest are indicator sub-panes and stacked host panes. */
   readonly panes: readonly PaneRenderInfo[];
+  /** Host panes docked to the left/right canvas edge, painted above the base layers in order. */
+  readonly dockedPanes?: readonly DockedPaneRenderInfo[];
+  /**
+   * Draw pass for `config.series.type`; defaults to the {@link SERIES_RENDERERS}
+   * lookup. `Chart.registerSeries` resolves custom types through this.
+   */
+  readonly seriesDraw?: SeriesDrawFn;
   readonly config: ChartConfig;
   readonly drawings: readonly ResolvedDrawing[];
   readonly crosshair: { readonly active: boolean; readonly x: number; readonly y: number };
@@ -75,6 +101,12 @@ export interface RenderView {
   readonly markers?: readonly SeriesMarker[];
   /** Wall clock in ms for the bar-close countdown; without it the countdown is hidden. */
   readonly now?: () => number;
+  /**
+   * WebGL2 frame for the main pane's dense geometry (heatmap cells, candle
+   * bodies/wicks), composited where the series layer sits. Absent on the
+   * Canvas2D backend, which paints everything through `ctx`.
+   */
+  readonly gl?: GLFrame;
 }
 
 function drawIndicatorOutput(
@@ -126,6 +158,9 @@ function renderLayers(ctx: Canvas2DLike, view: RenderView, overlay: boolean): vo
   ctx.fillStyle = config.theme.background;
   ctx.fillRect(0, 0, view.canvasWidth, view.canvasHeight);
   const plotLeft = view.plotLeft ?? 0;
+  const canvasView = view;
+  ctx.save();
+  try {
   if (plotLeft > 0) {
     ctx.translate(plotLeft, 0);
     view = { ...view, crosshair: { ...view.crosshair, x: view.crosshair.x - plotLeft } };
@@ -169,25 +204,39 @@ function renderLayers(ctx: Canvas2DLike, view: RenderView, overlay: boolean): vo
     ctx.rect(0, 0, plotWidth, mainPane.layout.height);
     ctx.clip();
     drawVolumeOverlay(ctx, view, mainPane.layout.height);
-    SERIES_RENDERERS[config.series.type](
-      ctx,
-      view.displayCandles ?? view.candles,
-      drawRange,
-      view.timeScale,
-      mainPane.priceScale,
-      config.series,
-      view.liveCandle,
-    );
+    const target = primitiveTarget(view, plotWidth, mainPane.layout.height, mainPane.priceScale, drawRange, view.gl);
+    for (const primitive of mainPane.primitives?.behind ?? []) primitive.draw(ctx, target);
+    const drawSeries = view.seriesDraw ?? SERIES_RENDERERS[config.series.type as SeriesType];
+    const gl = view.gl;
+    if (gl !== undefined && drawSeries === drawCandlesticks && !config.series.borderVisible &&
+        packCandleQuads(gl, view.displayCandles ?? view.candles, drawRange, view.timeScale, mainPane.priceScale, config.series, view.liveCandle)) {
+      // Candles joined the heatmap's quads; the GL image composites at the series layer.
+      gl.composite(ctx);
+    } else {
+      // A 2D series still paints over the GL-composited heatmap, if any.
+      gl?.composite(ctx);
+      drawSeries?.(
+        ctx,
+        view.displayCandles ?? view.candles,
+        drawRange,
+        view.timeScale,
+        mainPane.priceScale,
+        config.series,
+        view.liveCandle,
+      );
+    }
     drawMarkers(ctx, view, mainPane.priceScale);
     // Layer 4a: main-pane indicators overlay the series.
     for (const [index, output] of mainPane.indicators.entries()) {
       ctx.globalAlpha = mainPane.indicatorOpacities?.[index] ?? 1;
       drawIndicatorOutput(ctx, output, drawRange, view.timeScale, mainPane.priceScale, view.candles.length);
     }
+    ctx.globalAlpha = 1;
+    for (const primitive of mainPane.primitives?.above ?? []) primitive.draw(ctx, target);
     ctx.restore();
   }
 
-  // Layer 4b: sub-pane indicators.
+  // Layer 4b: sub-pane indicators and stacked host panes.
   for (const pane of view.panes.slice(1)) {
     ctx.save();
     ctx.globalAlpha = pane.opacity ?? 1;
@@ -195,9 +244,12 @@ function renderLayers(ctx: Canvas2DLike, view: RenderView, overlay: boolean): vo
     ctx.beginPath();
     ctx.rect(0, 0, plotWidth, pane.layout.height);
     ctx.clip();
+    const target = primitiveTarget(view, plotWidth, pane.layout.height, pane.priceScale, drawRange);
+    for (const primitive of pane.primitives?.behind ?? []) primitive.draw(ctx, target);
     for (const output of pane.indicators) {
       drawIndicatorOutput(ctx, output, drawRange, view.timeScale, pane.priceScale, view.candles.length);
     }
+    for (const primitive of pane.primitives?.above ?? []) primitive.draw(ctx, target);
     ctx.restore();
   }
 
@@ -271,6 +323,46 @@ function renderLayers(ctx: Canvas2DLike, view: RenderView, overlay: boolean): vo
   drawPriceReferences(ctx, view);
   drawPriceLines(ctx, view);
   if (overlay) renderOverlayLayers(ctx, view);
+  } finally {
+    ctx.restore();
+  }
+
+  // Layer 9: host panes docked to the canvas edges, in absolute coordinates.
+  drawDockedPanes(ctx, canvasView);
+}
+
+function primitiveTarget(
+  view: RenderView,
+  width: number,
+  height: number,
+  priceScale: PriceScale,
+  range: VisibleRange,
+  gl?: GLQuadSink,
+): PrimitiveDrawTarget {
+  return {
+    width,
+    height,
+    priceScale,
+    timeScale: view.timeScale,
+    range,
+    candles: view.candles,
+    pixelRatio: view.pixelRatio,
+    ...(gl !== undefined ? { gl } : {}),
+  };
+}
+
+function drawDockedPanes(ctx: Canvas2DLike, view: RenderView): void {
+  for (const dock of view.dockedPanes ?? []) {
+    ctx.save();
+    ctx.translate(dock.x, dock.y);
+    ctx.beginPath();
+    ctx.rect(0, 0, dock.width, dock.height);
+    ctx.clip();
+    const target = primitiveTarget(view, dock.width, dock.height, dock.priceScale, view.range);
+    for (const primitive of dock.primitives.behind) primitive.draw(ctx, target);
+    for (const primitive of dock.primitives.above) primitive.draw(ctx, target);
+    ctx.restore();
+  }
 }
 
 /** Repaints hover-dependent status text and crosshair above a cached base. */
diff --git a/packages/chart/src/render/session-profile.ts b/packages/chart/src/render/session-profile.ts
new file mode 100644
index 0000000..78b8461
--- /dev/null
+++ b/packages/chart/src/render/session-profile.ts
@@ -0,0 +1,377 @@
+/**
+ * Session volume profile / TPO as a first-class pane: an auto-updating
+ * profile docked beside the plot (composite or split per session) plus POC
+ * and value-area high/low lines projected on the main pane. Built on
+ * `Chart.addPane` + pane primitives, so it re-renders with every data,
+ * range or scale change.
+ *
+ * @module
+ */
+
+import { defaultPriceFormatter } from '../config.js';
+import type { Chart, PaneApi, PanePrimitiveHandle } from '../core/chart.js';
+import {
+  computeTpoProfile,
+  computeVolumeProfile,
+  DEFAULT_SESSION_MS,
+  DEFAULT_VALUE_AREA_PERCENT,
+  profileRowAt,
+  sessionRanges,
+  type PriceProfile,
+  type VolumeProfile,
+} from '../core/profile.js';
+import type { Candle } from '../core/data.js';
+import type { Canvas2DLike } from '../dom.js';
+import type { PanePrimitive, PrimitiveDrawTarget } from './primitive.js';
+
+/** Options shared by the profile pane and the main-pane level projections. */
+export interface SessionProfileOptions {
+  /** `'volume'` bins volume-at-price; `'tpo'` builds a market profile of time-at-price counts. Default `'volume'`. */
+  mode?: 'volume' | 'tpo';
+  /** Price rows per profile. Default 24. */
+  rows?: number;
+  /** Session length in milliseconds. Default one day ({@link DEFAULT_SESSION_MS}). */
+  sessionMs?: number;
+  /** Aggregate all visible sessions into one composite profile instead of one column per session. Default false. */
+  composite?: boolean;
+  /** Fraction of volume/TPO inside the value area. Default {@link DEFAULT_VALUE_AREA_PERCENT}. */
+  valueAreaPercent?: number;
+  /** Highlight the value-area rows. Default true. */
+  showValueArea?: boolean;
+  /** Mark the point-of-control row. Default true. */
+  showPoc?: boolean;
+  /** Rising-bar volume color in `'volume'` mode. Default `'#26a69a'`. */
+  upColor?: string;
+  /** Falling-bar volume color in `'volume'` mode. Default `'#ef5350'`. */
+  downColor?: string;
+  /** Letter/block color in `'tpo'` mode. Default `'#2962ff'`. */
+  tpoColor?: string;
+  /** Point-of-control line color. Default `'#f23645'`. */
+  pocColor?: string;
+  /** Value-area high/low line color. Default `'#787b86'`. */
+  valueAreaColor?: string;
+  /** Row opacity outside the value area. Default 0.25. */
+  opacity?: number;
+  /** Row opacity inside the value area. Default 0.55. */
+  valueAreaOpacity?: number;
+}
+
+/** Options for the main-pane POC / value-area projections. */
+export interface SessionLevelsOptions extends SessionProfileOptions {
+  /** How many of the most recent visible sessions project lines. Default 1. */
+  sessions?: number;
+  /** Draw price labels next to the projected lines. Default true. */
+  showLabels?: boolean;
+}
+
+/** Input for {@link attachSessionProfile}. */
+export interface SessionProfileAttachOptions extends SessionProfileOptions {
+  /** Host pane id. Default `'session-profile'`. */
+  id?: string;
+  /** Canvas edge the profile pane docks to. Default `'right'`. */
+  placement?: 'left' | 'right';
+  /** Dock strip width in CSS pixels. Default {@link DEFAULT_SESSION_PROFILE_WIDTH}. */
+  width?: number;
+  /** Project POC and value-area high/low lines onto the main pane. Default true. */
+  projectLevels?: boolean;
+  /** How many of the most recent visible sessions project lines. Default 1. */
+  projectedSessions?: number;
+  /** Draw price labels next to the projected lines. Default true. */
+  showLabels?: boolean;
+}
+
+/** Handle of a session profile attached via {@link attachSessionProfile}. */
+export interface SessionProfileApi {
+  /** The docked profile pane. */
+  readonly pane: PaneApi;
+  /** Merges new options (and dock `width`) and re-renders. */
+  update(options: SessionProfileAttachOptions): void;
+  /** Detaches the projections and removes the pane. */
+  remove(): void;
+}
+
+/** Default width in CSS pixels of the docked session profile pane. */
+export const DEFAULT_SESSION_PROFILE_WIDTH = 120;
+
+/** Letter cycle for TPO brackets, one per bar inside a session. */
+const TPO_LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+interface ResolvedSessionProfileOptions {
+  mode: 'volume' | 'tpo';
+  rows: number;
+  sessionMs: number;
+  composite: boolean;
+  valueAreaPercent: number;
+  showValueArea: boolean;
+  showPoc: boolean;
+  upColor: string;
+  downColor: string;
+  tpoColor: string;
+  pocColor: string;
+  valueAreaColor: string;
+  opacity: number;
+  valueAreaOpacity: number;
+}
+
+interface ResolvedSessionLevelsOptions extends ResolvedSessionProfileOptions {
+  enabled: boolean;
+  sessions: number;
+  showLabels: boolean;
+}
+
+function resolveProfileOptions(o: SessionProfileOptions): ResolvedSessionProfileOptions {
+  return {
+    mode: o.mode ?? 'volume',
+    rows: Math.max(1, Math.floor(o.rows ?? 24)),
+    sessionMs: o.sessionMs ?? DEFAULT_SESSION_MS,
+    composite: o.composite ?? false,
+    valueAreaPercent: o.valueAreaPercent ?? DEFAULT_VALUE_AREA_PERCENT,
+    showValueArea: o.showValueArea ?? true,
+    showPoc: o.showPoc ?? true,
+    upColor: o.upColor ?? '#26a69a',
+    downColor: o.downColor ?? '#ef5350',
+    tpoColor: o.tpoColor ?? '#2962ff',
+    pocColor: o.pocColor ?? '#f23645',
+    valueAreaColor: o.valueAreaColor ?? '#787b86',
+    opacity: o.opacity ?? 0.25,
+    valueAreaOpacity: o.valueAreaOpacity ?? 0.55,
+  };
+}
+
+/** Inclusive bar range the pane draws, clamped to the data; `null` when empty. */
+function visibleBars(target: PrimitiveDrawTarget): { from: number; to: number } | null {
+  const last = target.candles.length - 1;
+  if (last < 0) return null;
+  const from = Math.max(0, Math.floor(target.range.from));
+  const to = Math.min(last, Math.ceil(target.range.to) - 1);
+  return to >= from ? { from, to } : null;
+}
+
+function buildProfile(
+  candles: readonly Candle[],
+  from: number,
+  to: number,
+  o: ResolvedSessionProfileOptions,
+): PriceProfile | null {
+  return o.mode === 'tpo'
+    ? computeTpoProfile(candles, from, to, o.rows, o.valueAreaPercent)
+    : computeVolumeProfile(candles, from, to, o.rows, o.valueAreaPercent);
+}
+
+/** Y pixels of row `r`'s top and bottom edges. */
+function rowY(target: PrimitiveDrawTarget, profile: PriceProfile, r: number): { y0: number; y1: number } {
+  return {
+    y0: target.priceScale.priceToY(profile.lo + profile.step * (r + 1)),
+    y1: target.priceScale.priceToY(profile.lo + profile.step * r),
+  };
+}
+
+function rowAlpha(ctx: Canvas2DLike, base: number, profile: PriceProfile, r: number, o: ResolvedSessionProfileOptions): void {
+  const inVa = o.showValueArea && r >= profile.valueAreaLow && r <= profile.valueAreaHigh;
+  ctx.globalAlpha = base * (inVa ? o.valueAreaOpacity : o.opacity);
+}
+
+function drawVolumeColumn(
+  ctx: Canvas2DLike,
+  target: PrimitiveDrawTarget,
+  profile: VolumeProfile,
+  x0: number,
+  barW: number,
+  o: ResolvedSessionProfileOptions,
+): void {
+  const max = Math.max(...profile.totals) || 1;
+  const alpha = ctx.globalAlpha;
+  for (let r = 0; r < profile.rows; r++) {
+    if (profile.totals[r]! <= 0) continue;
+    const { y0, y1 } = rowY(target, profile, r);
+    if (y0 >= target.height || y1 <= 0) continue;
+    const h = Math.max(1, y1 - y0 - 0.5);
+    rowAlpha(ctx, alpha, profile, r, o);
+    const uw = (profile.up[r]! / max) * barW;
+    const dw = (profile.down[r]! / max) * barW;
+    if (uw > 0) {
+      ctx.fillStyle = o.upColor;
+      ctx.fillRect(x0, y0, uw, h);
+    }
+    if (dw > 0) {
+      ctx.fillStyle = o.downColor;
+      ctx.fillRect(x0 + uw, y0, dw, h);
+    }
+  }
+  ctx.globalAlpha = alpha;
+}
+
+function drawTpoColumn(
+  ctx: Canvas2DLike,
+  target: PrimitiveDrawTarget,
+  profile: PriceProfile,
+  from: number,
+  to: number,
+  x0: number,
+  barW: number,
+  o: ResolvedSessionProfileOptions,
+): void {
+  const max = Math.max(...profile.totals) || 1;
+  const advance = barW / max;
+  const letters = advance >= 5;
+  const alpha = ctx.globalAlpha;
+  if (letters) {
+    ctx.font = '9px sans-serif';
+    ctx.textAlign = 'left';
+    ctx.textBaseline = 'top';
+  }
+  ctx.fillStyle = o.tpoColor;
+  const slots = new Array<number>(profile.rows).fill(0);
+  for (let i = from; i <= to; i++) {
+    const c = target.candles[i]!;
+    const letter = TPO_LETTERS[(i - from) % TPO_LETTERS.length]!;
+    const r0 = profileRowAt(profile.lo, profile.step, profile.rows, c.low);
+    const r1 = profileRowAt(profile.lo, profile.step, profile.rows, c.high);
+    for (let r = r0; r <= r1; r++) {
+      const slot = slots[r]!++;
+      const { y0, y1 } = rowY(target, profile, r);
+      if (y0 >= target.height || y1 <= 0) continue;
+      rowAlpha(ctx, alpha, profile, r, o);
+      const x = x0 + slot * advance;
+      if (letters) ctx.fillText(letter, x, y0);
+      else ctx.fillRect(x, y0, Math.max(1, advance - 0.5), Math.max(1, y1 - y0 - 0.5));
+    }
+  }
+  ctx.globalAlpha = alpha;
+}
+
+function drawSessionProfile(ctx: Canvas2DLike, target: PrimitiveDrawTarget, o: ResolvedSessionProfileOptions): void {
+  const bars = visibleBars(target);
+  if (!bars) return;
+  const sessions = o.composite
+    ? [bars]
+    : sessionRanges(target.candles, bars.from, bars.to, o.sessionMs).map(({ from, to }) => ({ from, to }));
+  const colW = target.width / sessions.length;
+  const barW = colW * 0.95;
+  const alpha = ctx.globalAlpha;
+  sessions.forEach((s, k) => {
+    // Sessions are nonempty ranges inside the data, so a profile always exists.
+    const profile = buildProfile(target.candles, s.from, s.to, o)!;
+    const x0 = k * colW;
+    if (o.mode === 'tpo') drawTpoColumn(ctx, target, profile, s.from, s.to, x0, barW, o);
+    else drawVolumeColumn(ctx, target, profile as VolumeProfile, x0, barW, o);
+    if (o.showPoc) {
+      const { y0, y1 } = rowY(target, profile, profile.poc);
+      ctx.globalAlpha = alpha;
+      ctx.fillStyle = o.pocColor;
+      ctx.fillRect(x0, (y0 + y1) / 2 - 0.5, barW, 1);
+    }
+  });
+  ctx.globalAlpha = alpha;
+}
+
+function levelLine(
+  ctx: Canvas2DLike,
+  target: PrimitiveDrawTarget,
+  price: number,
+  color: string,
+  dash: number[],
+  label: string | null,
+): void {
+  const y = Math.round(target.priceScale.priceToY(price)) + 0.5;
+  if (y < 0 || y > target.height) return;
+  ctx.strokeStyle = color;
+  ctx.lineWidth = 1;
+  ctx.setLineDash(dash);
+  ctx.beginPath();
+  ctx.moveTo(0, y);
+  ctx.lineTo(target.width, y);
+  ctx.stroke();
+  ctx.setLineDash([]);
+  if (label) {
+    ctx.font = '10px sans-serif';
+    ctx.textAlign = 'right';
+    ctx.textBaseline = 'bottom';
+    ctx.fillStyle = color;
+    ctx.fillText(label, target.width - 4, y - 1);
+  }
+}
+
+function drawSessionLevels(ctx: Canvas2DLike, target: PrimitiveDrawTarget, o: ResolvedSessionLevelsOptions): void {
+  if (!o.enabled) return;
+  const bars = visibleBars(target);
+  if (!bars) return;
+  const sessions = sessionRanges(target.candles, bars.from, bars.to, o.sessionMs).slice(-Math.max(1, o.sessions));
+  for (const s of sessions) {
+    const profile = buildProfile(target.candles, s.from, s.to, o)!;
+    if (o.showPoc) {
+      levelLine(ctx, target, profile.pocPrice, o.pocColor, [], o.showLabels ? `POC ${defaultPriceFormatter(profile.pocPrice)}` : null);
+    }
+    if (o.showValueArea) {
+      levelLine(ctx, target, profile.valueAreaHighPrice, o.valueAreaColor, [4, 4], o.showLabels ? `VAH ${defaultPriceFormatter(profile.valueAreaHighPrice)}` : null);
+      levelLine(ctx, target, profile.valueAreaLowPrice, o.valueAreaColor, [4, 4], o.showLabels ? `VAL ${defaultPriceFormatter(profile.valueAreaLowPrice)}` : null);
+    }
+  }
+}
+
+/**
+ * A primitive painting session volume profiles (or a TPO market profile)
+ * into a pane that shares the main price scale — one column per visible
+ * session, or a single composite column with `composite`.
+ */
+export function createSessionProfilePrimitive(options: SessionProfileOptions = {}): PanePrimitive {
+  const resolved = resolveProfileOptions(options);
+  return { draw: (ctx, target) => drawSessionProfile(ctx, target, resolved) };
+}
+
+/**
+ * A main-pane primitive projecting POC (solid) and value-area high/low
+ * (dashed) lines of the most recent visible sessions across the plot.
+ */
+export function createSessionLevelsPrimitive(options: SessionLevelsOptions = {}): PanePrimitive {
+  const resolved: ResolvedSessionLevelsOptions = {
+    ...resolveProfileOptions(options),
+    enabled: true,
+    sessions: Math.max(1, Math.floor(options.sessions ?? 1)),
+    showLabels: options.showLabels ?? true,
+  };
+  return { draw: (ctx, target) => drawSessionLevels(ctx, target, resolved) };
+}
+
+/**
+ * Adds an auto-updating session volume profile / TPO pane docked at
+ * `placement` (sharing the main price scale) and, unless `projectLevels` is
+ * false, projects POC and value-area high/low lines of the most recent
+ * visible sessions onto the main pane. Both redraw on every data, range and
+ * scale change.
+ */
+export function attachSessionProfile(chart: Chart, options: SessionProfileAttachOptions = {}): SessionProfileApi {
+  const profile = resolveProfileOptions(options);
+  const levels: ResolvedSessionLevelsOptions = {
+    ...profile,
+    enabled: options.projectLevels ?? true,
+    sessions: Math.max(1, Math.floor(options.projectedSessions ?? 1)),
+    showLabels: options.showLabels ?? true,
+  };
+  const pane = chart.addPane({
+    id: options.id ?? 'session-profile',
+    placement: options.placement ?? 'right',
+    width: options.width ?? DEFAULT_SESSION_PROFILE_WIDTH,
+    sharePriceScale: true,
+  });
+  const profileHandle = pane.attachPrimitive({ draw: (ctx, target) => drawSessionProfile(ctx, target, profile) });
+  const levelsHandle = chart.attachPrimitive({ draw: (ctx, target) => drawSessionLevels(ctx, target, levels) });
+  return {
+    pane,
+    update(next) {
+      Object.assign(profile, resolveProfileOptions({ ...options, ...next }));
+      Object.assign(levels, profile, {
+        enabled: next.projectLevels ?? options.projectLevels ?? true,
+        sessions: Math.max(1, Math.floor(next.projectedSessions ?? options.projectedSessions ?? 1)),
+        showLabels: next.showLabels ?? options.showLabels ?? true,
+      });
+      if (next.width !== undefined) pane.setWidth(next.width);
+      profileHandle.requestUpdate();
+    },
+    remove() {
+      levelsHandle.detach();
+      profileHandle.detach();
+      pane.remove();
+    },
+  };
+}
diff --git a/packages/chart/src/render/trade-prints.ts b/packages/chart/src/render/trade-prints.ts
new file mode 100644
index 0000000..292fb06
--- /dev/null
+++ b/packages/chart/src/render/trade-prints.ts
@@ -0,0 +1,132 @@
+/**
+ * Trade prints: a pane primitive painting recent trades as circles pinned to
+ * their bar and price, colored by aggressor side and sized by trade size.
+ * Attach it to the main pane (`chart.attachPrimitive`) and push trades from
+ * the datafeed's tape channel, calling the handle's `requestUpdate` to repaint.
+ *
+ * @module
+ */
+
+import type { Trade } from '../core/trade.js';
+import type { Canvas2DLike } from '../dom.js';
+import type { PanePrimitive, PrimitiveDrawTarget } from './primitive.js';
+
+/** Trades retained by default; the oldest is evicted beyond the cap. */
+export const MAX_TRADE_PRINTS = 1_000;
+
+/** Smallest print radius in CSS pixels. */
+export const TRADE_PRINT_MIN_RADIUS = 2;
+
+/** Largest print radius in CSS pixels. */
+export const TRADE_PRINT_MAX_RADIUS = 8;
+
+/** Buy-side default, the default theme's `series.upColor`. */
+export const TRADE_PRINT_BUY_COLOR = '#089981';
+
+/** Sell-side default, the default theme's `series.downColor`. */
+export const TRADE_PRINT_SELL_COLOR = '#f23645';
+
+/** Options for {@link createTradePrintsPrimitive}. */
+export interface TradePrintsOptions {
+  /** Cap on retained trades; the oldest is evicted beyond it. Defaults to {@link MAX_TRADE_PRINTS}. */
+  readonly maxTrades?: number;
+  /** Buy-side print color. Defaults to {@link TRADE_PRINT_BUY_COLOR}. */
+  readonly buyColor?: string;
+  /** Sell-side print color. Defaults to {@link TRADE_PRINT_SELL_COLOR}. */
+  readonly sellColor?: string;
+  /** Smallest print radius in CSS pixels. Defaults to {@link TRADE_PRINT_MIN_RADIUS}. */
+  readonly minRadius?: number;
+  /** Largest print radius in CSS pixels. Defaults to {@link TRADE_PRINT_MAX_RADIUS}. */
+  readonly maxRadius?: number;
+}
+
+/** A pane primitive drawing trade prints; see {@link createTradePrintsPrimitive}. */
+export interface TradePrints extends PanePrimitive {
+  /** Number of retained trades. */
+  readonly size: number;
+  /**
+   * Retains one trade for the next paint. A trade with a non-finite time,
+   * price or size, a non-positive size, or an unknown side is ignored.
+   */
+  push(trade: Trade): void;
+  /** Drops every retained trade. */
+  clear(): void;
+}
+
+/** Index of the last candle with `time <= timeSec`, or -1 before the first one. */
+function barAtOrBefore(candles: PrimitiveDrawTarget['candles'], timeSec: number): number {
+  let lo = 0, hi = candles.length - 1, found = -1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    if (candles[mid]!.time <= timeSec) {
+      found = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return found;
+}
+
+/**
+ * Creates a primitive painting each retained trade as a circle at its bar's
+ * slot and its price: buys in `buyColor`, sells in `sellColor`, radius the
+ * square root of the trade size clamped to `[minRadius, maxRadius]`. A trade
+ * belongs to the last bar at or before its time (as markers do), so a live
+ * tape lands on the forming bar; one before the first bar never paints. Only
+ * trades on bars inside the visible range paint. Prints draw above the pane's
+ * series; the store is bounded by `maxTrades`, so a fast tape costs a bounded
+ * ring, not the whole session.
+ *
+ * @throws When `maxTrades` is not a positive integer or a radius is negative
+ * or not finite, or `minRadius` exceeds `maxRadius`.
+ */
+export function createTradePrintsPrimitive(options: TradePrintsOptions = {}): TradePrints {
+  const maxTrades = options.maxTrades ?? MAX_TRADE_PRINTS;
+  const buyColor = options.buyColor ?? TRADE_PRINT_BUY_COLOR;
+  const sellColor = options.sellColor ?? TRADE_PRINT_SELL_COLOR;
+  const minRadius = options.minRadius ?? TRADE_PRINT_MIN_RADIUS;
+  const maxRadius = options.maxRadius ?? TRADE_PRINT_MAX_RADIUS;
+  if (!Number.isSafeInteger(maxTrades) || maxTrades <= 0) {
+    throw new Error(`chart-ts: maxTrades must be a positive integer, got ${maxTrades}`);
+  }
+  if (!(Number.isFinite(minRadius) && minRadius >= 0) || !(Number.isFinite(maxRadius) && maxRadius >= minRadius)) {
+    throw new Error(`chart-ts: expected 0 <= minRadius <= maxRadius, got ${minRadius} and ${maxRadius}`);
+  }
+  let trades: Trade[] = [];
+
+  function draw(ctx: Canvas2DLike, target: PrimitiveDrawTarget): void {
+    const { candles, range, timeScale, priceScale } = target;
+    if (trades.length === 0 || candles.length === 0 || range.to <= range.from) return;
+    ctx.save();
+    for (const trade of trades) {
+      const bar = barAtOrBefore(candles, trade.time / 1000);
+      if (bar < range.from || bar >= range.to) continue;
+      const x = timeScale.indexToX(bar, candles.length);
+      const y = priceScale.priceToY(trade.price);
+      const radius = Math.min(maxRadius, Math.max(minRadius, Math.sqrt(trade.size)));
+      ctx.beginPath();
+      ctx.fillStyle = trade.side === 'buy' ? buyColor : sellColor;
+      ctx.ellipse(x, y, radius, radius, 0, 0, Math.PI * 2);
+      ctx.fill();
+    }
+    ctx.restore();
+  }
+
+  return {
+    get size() {
+      return trades.length;
+    },
+    push(trade) {
+      const { time, price, size, side } = trade;
+      if (!Number.isFinite(time) || !Number.isFinite(price) || !Number.isFinite(size) || size <= 0) return;
+      if (side !== 'buy' && side !== 'sell') return;
+      trades.push(trade);
+      if (trades.length > maxTrades) trades.shift();
+    },
+    clear() {
+      trades = [];
+    },
+    draw,
+  };
+}
diff --git a/packages/chart/src/series/direction.ts b/packages/chart/src/series/direction.ts
index 2b42701..c10c1b8 100644
--- a/packages/chart/src/series/direction.ts
+++ b/packages/chart/src/series/direction.ts
@@ -6,10 +6,10 @@
  */
 
 import type { Candle } from '../core/data.js';
-import type { SeriesConfig, SeriesType } from '../config.js';
+import type { SeriesConfig } from '../config.js';
 
 /** Series types whose renderers honour `colorByPreviousClose`. */
-const PREVIOUS_CLOSE_OPTIONAL: ReadonlySet<SeriesType> = new Set<SeriesType>(['candlestick', 'bar', 'histogram']);
+const PREVIOUS_CLOSE_OPTIONAL: ReadonlySet<string> = new Set(['candlestick', 'bar', 'histogram']);
 
 /**
  * Whether bar `index` of `candles` draws in the up color. Hollow candles (and
diff --git a/packages/chart/src/series/footprint.ts b/packages/chart/src/series/footprint.ts
new file mode 100644
index 0000000..dc089ab
--- /dev/null
+++ b/packages/chart/src/series/footprint.ts
@@ -0,0 +1,191 @@
+/**
+ * Footprint series renderer: traded bid×ask volume per price cell inside each
+ * bar, fed by a {@link FootprintSource} (the trade aggregation behind the
+ * datafeed's `pushTrade`). Zoomed in, each level shows its `sell × buy` label
+ * (bid × ask: seller-initiated size first); when the cells no longer fit the
+ * text the bar degrades to per-level volume bars, and zoomed further out to a
+ * single column colored by the bar's delta (see {@link footprintLod}).
+ *
+ * The source is a factory option rather than a draw argument: register the
+ * result via `Chart.registerSeries('footprint', createFootprintSeries(source))`
+ * and select it with `series: { type: 'footprint' }`. Reads happen at draw
+ * time, so the cells repaint through the regular render like the inline book
+ * reads `Chart.depth`.
+ *
+ * @module
+ */
+
+import type { SeriesConfig } from '../config.js';
+import {
+  barDelta,
+  footprintBands,
+  footprintLod,
+  DEFAULT_FOOTPRINT_LOD,
+  type FootprintBand,
+  type FootprintBarLike,
+  type FootprintDisplay,
+  type FootprintLevelLike,
+  type FootprintLodThresholds,
+  type FootprintSource,
+} from '../core/footprint.js';
+import type { Canvas2DLike } from '../dom.js';
+import type { PriceScale } from '../core/scale.js';
+import type { SeriesDrawFn } from './types.js';
+
+/** The conventional type string for the footprint series. */
+export const FOOTPRINT_SERIES_TYPE = 'footprint';
+
+/** Options for {@link createFootprintSeries}. */
+export interface FootprintSeriesOptions {
+  /** Per-level content: bid×ask labels (collapsing with zoom), delta bars, or plain volume bars. Default `'bid-ask'`. */
+  display?: FootprintDisplay;
+  /** Buy-side (ask, delta-positive) color. Default the series config's `upColor`. */
+  upColor?: string;
+  /** Sell-side (bid, delta-negative) color. Default the series config's `downColor`. */
+  downColor?: string;
+  /** Cell label color; default null colors each label by the level's delta sign. */
+  textColor?: string | null;
+  /** LOD overrides in CSS pixels; missing entries keep {@link DEFAULT_FOOTPRINT_LOD}. */
+  lodThresholds?: Partial<FootprintLodThresholds>;
+}
+
+/** A fixed store, or a getter for swapping sessions without re-registering. */
+export type FootprintSeriesSource = FootprintSource | (() => FootprintSource | null);
+
+interface ResolvedFootprintOptions {
+  display: FootprintDisplay;
+  upColor: string;
+  downColor: string;
+  textColor: string | null;
+  thresholds: FootprintLodThresholds;
+}
+
+function resolveFootprintOptions(o: FootprintSeriesOptions, config: SeriesConfig): ResolvedFootprintOptions {
+  return {
+    display: o.display ?? 'bid-ask',
+    upColor: o.upColor ?? config.upColor,
+    downColor: o.downColor ?? config.downColor,
+    textColor: o.textColor ?? null,
+    thresholds: { ...DEFAULT_FOOTPRINT_LOD, ...o.lodThresholds },
+  };
+}
+
+/** Compact level size: `0`, `0.0250`, `12.40`, `1.25K`, `3.40M`. */
+export function formatFootprintSize(size: number): string {
+  const abs = Math.abs(size);
+  if (abs === 0) return '0';
+  if (abs >= 1_000_000) return `${(size / 1_000_000).toFixed(2)}M`;
+  if (abs >= 1_000) return `${(size / 1_000).toFixed(2)}K`;
+  if (abs >= 1) return size.toFixed(2);
+  return size.toFixed(4);
+}
+
+interface CellRow {
+  band: FootprintBand;
+  level: FootprintLevelLike;
+  y0: number;
+  y1: number;
+}
+
+function cellRows(bar: FootprintBarLike, priceScale: PriceScale): { rows: CellRow[]; cellPx: number } {
+  const levels = bar.levels.filter((level) => Number.isFinite(level.price));
+  const bands = footprintBands(levels);
+  const rows: CellRow[] = [];
+  let cellPx = Infinity;
+  for (let i = 0; i < bands.length; i++) {
+    const y0 = priceScale.priceToY(bands[i]!.high);
+    const y1 = priceScale.priceToY(bands[i]!.low);
+    rows.push({ band: bands[i]!, level: levels[i]!, y0, y1 });
+    if (y1 - y0 < cellPx) cellPx = y1 - y0;
+  }
+  return { rows, cellPx };
+}
+
+/** Zoomed all the way out: one column over the bar's traded range, colored by the bar's delta. */
+function drawDeltaColumn(ctx: Canvas2DLike, bar: FootprintBarLike, rows: readonly CellRow[], x: number, w: number, o: ResolvedFootprintOptions): void {
+  const alpha = ctx.globalAlpha;
+  ctx.globalAlpha = alpha * 0.35;
+  ctx.fillStyle = barDelta(bar) >= 0 ? o.upColor : o.downColor;
+  ctx.fillRect(x, rows[rows.length - 1]!.y0, w, Math.max(1, rows[0]!.y1 - rows[rows.length - 1]!.y0));
+  ctx.globalAlpha = alpha;
+}
+
+/** Per-level volume bars: bid×ask halves split at the center, delta bars, or plain volume bars. */
+function drawLevelBars(ctx: Canvas2DLike, rows: readonly CellRow[], x: number, w: number, o: ResolvedFootprintOptions): void {
+  let maxTotal = 0, maxSide = 0, maxDelta = 0;
+  for (const { level } of rows) {
+    const total = level.buySize + level.sellSize;
+    if (total > maxTotal) maxTotal = total;
+    if (level.buySize > maxSide) maxSide = level.buySize;
+    if (level.sellSize > maxSide) maxSide = level.sellSize;
+    const delta = Math.abs(level.buySize - level.sellSize);
+    if (delta > maxDelta) maxDelta = delta;
+  }
+  const normalizer = o.display === 'delta' ? maxDelta : o.display === 'profile' ? maxTotal : maxSide;
+  if (normalizer <= 0) return;
+  for (const { level, y0, y1 } of rows) {
+    const h = Math.max(1, y1 - y0 - 0.5);
+    if (o.display === 'bid-ask') {
+      const half = w / 2;
+      const sellW = (level.sellSize / normalizer) * half;
+      const buyW = (level.buySize / normalizer) * half;
+      if (sellW > 0) {
+        ctx.fillStyle = o.downColor;
+        ctx.fillRect(x + half - sellW, y0, sellW, h);
+      }
+      if (buyW > 0) {
+        ctx.fillStyle = o.upColor;
+        ctx.fillRect(x + half, y0, buyW, h);
+      }
+    } else {
+      const delta = level.buySize - level.sellSize;
+      const size = o.display === 'delta' ? Math.abs(delta) : level.buySize + level.sellSize;
+      ctx.fillStyle = delta >= 0 ? o.upColor : o.downColor;
+      ctx.fillRect(x, y0, (size / normalizer) * w, h);
+    }
+  }
+}
+
+/** Zoomed in: a `sell × buy` label per level over a faint delta-signed tint. */
+function drawTextCells(ctx: Canvas2DLike, rows: readonly CellRow[], x: number, w: number, o: ResolvedFootprintOptions): void {
+  const alpha = ctx.globalAlpha;
+  ctx.font = '10px sans-serif';
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  for (const { level, y0, y1 } of rows) {
+    const h = Math.max(1, y1 - y0 - 0.5);
+    const up = level.buySize >= level.sellSize;
+    ctx.globalAlpha = alpha * 0.12;
+    ctx.fillStyle = up ? o.upColor : o.downColor;
+    ctx.fillRect(x, y0, w, h);
+    ctx.globalAlpha = alpha;
+    ctx.fillStyle = o.textColor ?? (up ? o.upColor : o.downColor);
+    ctx.fillText(`${formatFootprintSize(level.sellSize)}×${formatFootprintSize(level.buySize)}`, x + w / 2, (y0 + y1) / 2);
+  }
+}
+
+/**
+ * A {@link SeriesDrawFn} painting the footprint of each visible bar. Bars
+ * without a footprint bucket (no trades, or a source without the session's
+ * history) draw nothing. The source maps candle times (seconds) to the
+ * store's ms buckets, so its `intervalMs` should match the chart's bars.
+ */
+export function createFootprintSeries(source: FootprintSeriesSource, options: FootprintSeriesOptions = {}): SeriesDrawFn {
+  const resolve = typeof source === 'function' ? source : () => source;
+  return (ctx, candles, range, timeScale, priceScale, config) => {
+    const store = resolve();
+    if (store === null) return;
+    const o = resolveFootprintOptions(options, config);
+    const w = Math.max(1, timeScale.barSpacing - 1);
+    for (let i = range.from; i < range.to; i++) {
+      const bar = store.bar(candles[i]!.time * 1000);
+      if (bar === null || bar.levels.length === 0) continue;
+      const { rows, cellPx } = cellRows(bar, priceScale);
+      const x = Math.round(timeScale.indexToX(i, candles.length) - w / 2);
+      const lod = footprintLod(timeScale.barSpacing, cellPx, o.display, o.thresholds);
+      if (lod === 'text') drawTextCells(ctx, rows, x, w, o);
+      else if (lod === 'bars') drawLevelBars(ctx, rows, x, w, o);
+      else drawDeltaColumn(ctx, bar, rows, x, w, o);
+    }
+  };
+}
diff --git a/packages/chart/src/series/heikin-ashi.ts b/packages/chart/src/series/heikin-ashi.ts
index 22b6f48..45a7281 100644
--- a/packages/chart/src/series/heikin-ashi.ts
+++ b/packages/chart/src/series/heikin-ashi.ts
@@ -7,7 +7,6 @@
  */
 
 import type { Candle } from '../core/data.js';
-import type { SeriesType } from '../config.js';
 import { drawCandlesticks } from './candlestick.js';
 import type { SeriesDrawFn } from './types.js';
 
@@ -81,7 +80,7 @@ export class HeikinAshiCache {
    * The main series' bars as displayed for `type`: HA bars for
    * `'heikin-ashi'`, otherwise `candles` itself (releasing any cached bars).
    */
-  display(candles: readonly Candle[], type: SeriesType): readonly Candle[] {
+  display(candles: readonly Candle[], type: string): readonly Candle[] {
     if (type === 'heikin-ashi') return this.get(candles);
     this.clear();
     return candles;
diff --git a/packages/chart/src/series/index.ts b/packages/chart/src/series/index.ts
index 253e283..5ce9cc0 100644
--- a/packages/chart/src/series/index.ts
+++ b/packages/chart/src/series/index.ts
@@ -4,16 +4,6 @@
  * @module
  */
 
-import type { SeriesType } from '../config.js';
-import type { SeriesDrawFn } from './types.js';
-import { drawCandlesticks } from './candlestick.js';
-import { drawLine } from './line.js';
-import { drawArea } from './area.js';
-import { drawBars } from './bar.js';
-import { drawHistogram } from './histogram.js';
-import { drawHeikinAshi } from './heikin-ashi.js';
-import { drawHollowCandlesticks } from './hollow-candlestick.js';
-
 export type { SeriesDrawFn } from './types.js';
 export { drawCandlesticks } from './candlestick.js';
 export { drawLine } from './line.js';
@@ -22,14 +12,6 @@ export { drawBars } from './bar.js';
 export { drawHistogram, drawHistogramBars } from './histogram.js';
 export { drawHeikinAshi, heikinAshi, heikinAshiBar, heikinAshiLive, updateHeikinAshi, HeikinAshiCache } from './heikin-ashi.js';
 export { drawHollowCandlesticks } from './hollow-candlestick.js';
-
-/** Maps {@link SeriesType} strings to their pure draw functions. */
-export const SERIES_RENDERERS: Record<SeriesType, SeriesDrawFn> = {
-  candlestick: drawCandlesticks,
-  line: drawLine,
-  area: drawArea,
-  bar: drawBars,
-  histogram: drawHistogram,
-  'heikin-ashi': drawHeikinAshi,
-  'hollow-candlestick': drawHollowCandlesticks,
-};
+export { createFootprintSeries, formatFootprintSize, FOOTPRINT_SERIES_TYPE } from './footprint.js';
+export type { FootprintSeriesOptions, FootprintSeriesSource } from './footprint.js';
+export { SERIES_RENDERERS, SeriesRegistry, createSeriesRegistry } from './registry.js';
diff --git a/packages/chart/src/series/registry.ts b/packages/chart/src/series/registry.ts
new file mode 100644
index 0000000..832861d
--- /dev/null
+++ b/packages/chart/src/series/registry.ts
@@ -0,0 +1,72 @@
+/**
+ * Series registry: built-in renderers plus user-registered custom series.
+ *
+ * @module
+ */
+
+import type { SeriesType } from '../config.js';
+import type { SeriesDrawFn } from './types.js';
+import { drawCandlesticks } from './candlestick.js';
+import { drawLine } from './line.js';
+import { drawArea } from './area.js';
+import { drawBars } from './bar.js';
+import { drawHistogram } from './histogram.js';
+import { drawHeikinAshi } from './heikin-ashi.js';
+import { drawHollowCandlesticks } from './hollow-candlestick.js';
+
+/** Maps the built-in {@link SeriesType} strings to their pure draw functions. */
+export const SERIES_RENDERERS: Record<SeriesType, SeriesDrawFn> = {
+  candlestick: drawCandlesticks,
+  line: drawLine,
+  area: drawArea,
+  bar: drawBars,
+  histogram: drawHistogram,
+  'heikin-ashi': drawHeikinAshi,
+  'hollow-candlestick': drawHollowCandlesticks,
+};
+
+/** A mutable registry of series draw functions keyed by type string. */
+export class SeriesRegistry {
+  private readonly fns = new Map<string, SeriesDrawFn>();
+
+  /** Registers (or replaces) a draw function. Returns `this` for chaining. */
+  register(type: string, drawFn: SeriesDrawFn): this {
+    this.fns.set(type, drawFn);
+    return this;
+  }
+
+  /** Looks up a draw function by type string. */
+  get(type: string): SeriesDrawFn | undefined {
+    return this.fns.get(type);
+  }
+
+  /** True when `type` is registered. */
+  has(type: string): boolean {
+    return this.fns.has(type);
+  }
+
+  /** Removes a draw function; returns whether it existed. */
+  unregister(type: string): boolean {
+    return this.fns.delete(type);
+  }
+
+  /** All registered type strings. */
+  names(): string[] {
+    return [...this.fns.keys()];
+  }
+}
+
+/**
+ * Creates a registry pre-loaded with the built-in {@link SeriesType} renderers.
+ *
+ * @param withBuiltins - Pass `false` for an empty registry.
+ */
+export function createSeriesRegistry(withBuiltins = true): SeriesRegistry {
+  const registry = new SeriesRegistry();
+  if (withBuiltins) {
+    for (const type of Object.keys(SERIES_RENDERERS)) {
+      registry.register(type, SERIES_RENDERERS[type as SeriesType]);
+    }
+  }
+  return registry;
+}
diff --git a/packages/chart/src/ui/controller.ts b/packages/chart/src/ui/controller.ts
index 1af2567..632b142 100644
--- a/packages/chart/src/ui/controller.ts
+++ b/packages/chart/src/ui/controller.ts
@@ -31,6 +31,14 @@ export const GLYPH_TOOLS: readonly string[] = ['emoji', 'sticker', 'icon'];
 /** Pixels of pointer travel before a press becomes a drag. */
 export const DRAG_THRESHOLD_PX = 4;
 
+/**
+ * Vertical travel before a navigation drag pans the price range. Only with
+ * autoscale off: while it is on, drags scroll time and the price range keeps
+ * fitting the bars. The drag must also be at least twice as vertical as it is
+ * horizontal, so a sideways pan never shifts prices.
+ */
+export const VERTICAL_PAN_PX = 12;
+
 /** Minimum box-zoom width in pixels. */
 export const MIN_ZOOM_BOX_PX = 6;
 
@@ -72,7 +80,7 @@ export interface ZoomBox {
 }
 
 type Drag =
-  | { kind: 'pan'; lastX: number }
+  | { kind: 'pan'; lastX: number; lastY: number; x0: number; y0: number; vertical: boolean }
   | { kind: 'handle'; id: string; index: number; checkpointed: boolean }
   | { kind: 'move'; id: string; lastX: number; lastY: number; checkpointed: boolean }
   | { kind: 'zoom'; x0: number; x1: number }
@@ -500,7 +508,7 @@ export class DrawingController {
       return;
     }
     this.select(null);
-    this.drag = this.navigation ? { kind: 'pan', lastX: x } : null;
+    this.drag = this.navigation ? { kind: 'pan', lastX: x, lastY: y, x0: x, y0: y, vertical: false } : null;
   }
 
   pointerMove(x: number, y: number): void {
@@ -514,7 +522,15 @@ export class DrawingController {
       case 'pan': {
         const spacing = Math.max(0.5, this.chart.scale.barSpacing());
         this.chart.scale.scrollBy((x - d.lastX) / spacing);
+        // With autoscale off, a clearly vertical drag pans the price range; autoscale on keeps the bars in frame.
+        const dy = Math.abs(y - d.y0);
+        if (!d.vertical && dy > VERTICAL_PAN_PX && dy >= 2 * Math.abs(x - d.x0) && !this.chart.getConfig().priceAxis.autoScale) {
+          d.vertical = true;
+          d.lastY = d.y0;
+        }
+        if (d.vertical) this.chart.scale.scrollPrice(y - d.lastY);
         d.lastX = x;
+        d.lastY = y;
         this.emit('viewport', undefined);
         break;
       }
diff --git a/packages/chart/src/ui/header.ts b/packages/chart/src/ui/header.ts
index 8107276..fa0c637 100644
--- a/packages/chart/src/ui/header.ts
+++ b/packages/chart/src/ui/header.ts
@@ -346,14 +346,14 @@ export function createChartHeader(options: ChartHeaderOptions): ChartHeader {
   const typeBtn = button('cts-header-type', icon('chart-candlestick', 18), 'Chart type');
   const typeItems = chartTypes.map((type) => radioItem(typeMenu, typeBtn, CHART_TYPE_LABELS[type], `chart-${type}`, () => pickType(type)));
   dropdown(typeBtn, typeMenu, typeItems);
-  let shownType: SeriesType | null = null;
+  let shownType: string | null = null;
 
   function syncType(): void {
     const type = chart.getConfig().series.type;
     if (type === shownType) return;
     shownType = type;
     setButtonIcon(typeBtn, `chart-${type}`, 18);
-    typeBtn.title = `Chart type: ${CHART_TYPE_LABELS[type]}`;
+    typeBtn.title = `Chart type: ${CHART_TYPE_LABELS[type as SeriesType] ?? type}`;
     typeBtn.setAttribute('aria-label', typeBtn.title);
     chartTypes.forEach((t, i) => {
       typeItems[i].classList.toggle('cts-active', t === type);
diff --git a/packages/chart/src/ui/icons.ts b/packages/chart/src/ui/icons.ts
index 806c126..fc1fcf3 100644
--- a/packages/chart/src/ui/icons.ts
+++ b/packages/chart/src/ui/icons.ts
@@ -96,6 +96,7 @@ export const ICONS: Readonly<Record<string, string>> = {
   "monitor": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"2\" y=\"3\" width=\"20\" height=\"14\" rx=\"2\"/><path d=\"M8 21h8\"/><path d=\"M12 17v4\"/></svg>",
   "moon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M20.5 13.5A8.5 8.5 0 1 1 10.5 3.5a7 7 0 0 0 10 10z\"/></svg>",
   "note": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M5 3h14a2 2 0 0 1 2 2v10l-6 6H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z\"/><path d=\"M15 21v-4a2 2 0 0 1 2-2h4\"/></svg>",
+  "order-book": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M20 3v18\"/><path d=\"M14 5h6M8 9h12M4 13h16M11 17h9M16 21h4\"/></svg>",
   "palette": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"13.5\" cy=\"6.5\" r=\".5\" fill=\"currentColor\"/><circle cx=\"17.5\" cy=\"10.5\" r=\".5\" fill=\"currentColor\"/><circle cx=\"8.5\" cy=\"7.5\" r=\".5\" fill=\"currentColor\"/><circle cx=\"6.5\" cy=\"12.5\" r=\".5\" fill=\"currentColor\"/><path d=\"M12 2.5C6.5 2.5 2.5 6.5 2.5 12s4 9.5 9.5 9.5c.75 0 1.5-.5 1.5-1.5 0-.5-.25-.75-.5-1s-.5-.5-.5-1a1.5 1.5 0 0 1 1.5-1.5h2c3 0 5.5-2.5 5.5-5.5C21.5 6 17.5 2.5 12 2.5z\"/></svg>",
   "panel-left-close": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"4\" width=\"18\" height=\"16\" rx=\"2\"/><path d=\"M9 4v16\"/><path d=\"m14.5 9-3 3 3 3\"/></svg>",
   "panel-left-open": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"4\" width=\"18\" height=\"16\" rx=\"2\"/><path d=\"M9 4v16\"/><path d=\"m11.5 9 3 3-3 3\"/></svg>",
@@ -113,6 +114,7 @@ export const ICONS: Readonly<Record<string, string>> = {
   "price-note": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"5\" cy=\"18\" r=\"2\"/><path d=\"M6.5 16.5 11 12\"/><rect x=\"11\" y=\"5\" width=\"11\" height=\"7\" rx=\"2\"/></svg>",
   "price-range": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M12 4v16M9 7l3-3 3 3M9 17l3 3 3-3\"/><path d=\"M4 3h16M4 21h16\"/></svg>",
   "projection": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M3 20 9 6l6 10 6-8\"/><path d=\"M15 16a7 7 0 0 0-6-10\" stroke-dasharray=\"2 2.5\"/></svg>",
+  "range-profile": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M12 3v18\"/><path d=\"M10 5h4M7 9h10M4 13h16M8 17h8M10 21h4\"/></svg>",
   "ray": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"5\" cy=\"17\" r=\"2\"/><circle cx=\"12\" cy=\"13.5\" r=\"2\"/><path d=\"M6.75 16l3.5-1.75M13.75 12.5 21 9\"/></svg>",
   "rect": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\"/></svg>",
   "redo": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M20 8H9a5 5 0 0 0 0 10h7\"/><path d=\"m16 4 4 4-4 4\"/></svg>",
diff --git a/packages/chart/src/ui/index.ts b/packages/chart/src/ui/index.ts
index 2294f15..686bfdd 100644
--- a/packages/chart/src/ui/index.ts
+++ b/packages/chart/src/ui/index.ts
@@ -24,7 +24,7 @@ export { createChartContextMenu } from './context-menu.js';
 export type {
   ChartContextMenu, ChartContextMenuHooks, ChartContextMenuOptions, ContextMenuAction, ContextMenuEntry, ContextMenuTarget,
 } from './context-menu.js';
-export { DrawingController, ZOOM_TOOL, GLYPH_TOOLS, DRAG_THRESHOLD_PX, MIN_ZOOM_BOX_PX, groupOf } from './controller.js';
+export { DrawingController, ZOOM_TOOL, GLYPH_TOOLS, DRAG_THRESHOLD_PX, VERTICAL_PAN_PX, MIN_ZOOM_BOX_PX, groupOf } from './controller.js';
 export type { ControllerEvents, CursorMode, Hint, ZoomBox, DrawingControllerOptions } from './controller.js';
 export { DrawingHistory, HISTORY_LIMIT } from './history.js';
 export {
diff --git a/packages/chart/test/chart-header.test.ts b/packages/chart/test/chart-header.test.ts
index 5d42778..665c35e 100644
--- a/packages/chart/test/chart-header.test.ts
+++ b/packages/chart/test/chart-header.test.ts
@@ -274,6 +274,20 @@ describe('chart header: chart type menu', () => {
     m.chart.updateConfig({ series: { type: 'line' } });
     assert.equal(type.title, 'Chart type: Bars', 'destroyed headers stop following');
   });
+
+  it('falls back to the raw type string for a custom series without a label', () => {
+    const m = mount({ chartTypes: ['candlestick', 'line'] });
+    m.chart.registerSeries('stairs', () => undefined);
+    m.chart.updateConfig({ series: { type: 'stairs' } });
+    const type = m.q('.cts-header-type');
+    assert.equal(type.title, 'Chart type: stairs', 'no CHART_TYPE_LABELS entry, so the type itself shows');
+    assert.equal(type.getAttribute('aria-label'), 'Chart type: stairs');
+    assert.equal(m.qa('.cts-header-menu')[1]!.querySelectorAll('.cts-active').length, 0, 'no offered type matches');
+    assert.deepEqual([...m.qa('.cts-header-menu')[1]!.querySelectorAll('.cts-item')].map((n) => (n as HTMLElement).getAttribute('aria-checked')), ['false', 'false']);
+    m.header.setChartType('line');
+    assert.equal(type.title, 'Chart type: Line', 'labelled types still use CHART_TYPE_LABELS');
+    m.header.destroy();
+  });
 });
 
 describe('chart header: keyboard', () => {
diff --git a/packages/chart/test/context-menu-core.test.ts b/packages/chart/test/context-menu-core.test.ts
index 205521c..4331b29 100644
--- a/packages/chart/test/context-menu-core.test.ts
+++ b/packages/chart/test/context-menu-core.test.ts
@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { createChart, MockDocument, type Chart, type FrameScheduler, type IndicatorHit } from '../dist/index.js';
+import { createChart, MockCanvas, MockDocument, type Chart, type FrameScheduler, type IndicatorHit } from '../dist/index.js';
 import type { Candle } from '../dist/core/data.js';
 import type { ChartConfig, DeepPartial } from '../dist/config.js';
 import type { IndicatorDef, IndicatorLine, IndicatorOutput } from '../dist/indicators/index.js';
@@ -44,6 +44,32 @@ class TestFrames implements FrameScheduler {
   cancel = () => {};
 }
 
+describe('chart.scale.scrollPrice', () => {
+  it('pans the range in scale units, turning autoscale off once, and ignores no-ops', () => {
+    const chart = make({ width: 640, height: 400 });
+    const price = chart.scale.yToPrice(200);
+    chart.scale.scrollPrice(0);
+    assert.equal(chart.getConfig().priceAxis.autoScale, true, 'a zero pan changes nothing');
+    chart.scale.scrollPrice(40);
+    assert.equal(chart.getConfig().priceAxis.autoScale, false);
+    assert.ok(Math.abs(chart.scale.priceToY(price) - 240) < 1e-6);
+    chart.scale.scrollPrice(-40); // autoscale already off: a plain re-render
+    assert.ok(Math.abs(chart.scale.priceToY(price) - 200) < 1e-6);
+    chart.updateConfig({ priceAxis: { mode: 'logarithmic', inverted: true } });
+    const logPrice = chart.scale.yToPrice(100);
+    chart.scale.scrollPrice(30);
+    assert.ok(Math.abs(chart.scale.priceToY(logPrice) - 130) < 1e-6, 'log and inverted axes follow the pointer too');
+    chart.destroy();
+  });
+
+  it('is a no-op before the main pane is laid out', () => {
+    const chart = createChart({ container: new MockCanvas(0, 0), config: { wasm: false } });
+    chart.scale.scrollPrice(10);
+    assert.equal(chart.getConfig().priceAxis.autoScale, true);
+    chart.destroy();
+  });
+});
+
 describe('chart.resetScale', () => {
   it('restores the initial bar spacing and scrolls back to the latest bar', () => {
     const chart = make();
diff --git a/packages/chart/test/controller.test.ts b/packages/chart/test/controller.test.ts
index 51dcb31..771d2e2 100644
--- a/packages/chart/test/controller.test.ts
+++ b/packages/chart/test/controller.test.ts
@@ -372,6 +372,26 @@ describe('DrawingController eraser, zoom and navigation', () => {
     c.pointerLeave();
     c.pointerUp(1, 1); // stray up with no drag
   });
+  it('keeps autoscale fitting the bars on every drag while it is on', () => {
+    const { c, chart } = setup();
+    c.pointerDown(400, 200);
+    c.pointerMove(400, 300); // straight down
+    c.pointerUp(400, 300);
+    assert.equal(chart.getConfig().priceAxis.autoScale, true);
+  });
+  it('with autoscale off, pans the price range only once a drag is clearly vertical', () => {
+    const { c, chart } = setup();
+    chart.updateConfig({ priceAxis: { autoScale: false } });
+    c.pointerDown(400, 200);
+    c.pointerMove(460, 225); // 25px down but mostly sideways: a time pan
+    const price = chart.scale.yToPrice(200);
+    assert.ok(Math.abs(chart.scale.priceToY(price) - 200) < 1e-6, 'prices hold');
+    c.pointerMove(420, 260);
+    c.pointerUp(420, 260);
+    // The content followed the pointer: the price under it now sits 60px lower.
+    assert.ok(Math.abs(chart.scale.priceToY(price) - 260) < 1e-6);
+    assert.equal(chart.getConfig().priceAxis.autoScale, false);
+  });
   it('navigation off leaves the viewport alone', () => {
     const { c, chart } = setup({ navigation: false });
     const before = chart.scale.visibleRange();
diff --git a/packages/chart/test/depth-book.test.ts b/packages/chart/test/depth-book.test.ts
new file mode 100644
index 0000000..4ebdcce
--- /dev/null
+++ b/packages/chart/test/depth-book.test.ts
@@ -0,0 +1,685 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  DEPTH_MAX_RETRY_BACKOFF_MS,
+  DEPTH_RETRY_BACKOFF_MS,
+  MAX_BUFFERED_DELTAS,
+  MAX_RETRY_BACKOFF_MS,
+  RETRY_BACKOFF_MS,
+  applyDepthLevels,
+  createDatafeedChart,
+  createDepthBookManager,
+  normalizeDepthSide,
+  type Candle,
+  type DatafeedChartOptions,
+  type DatafeedDepthRequest,
+  type DepthBook,
+  type DepthDelta,
+  type DepthLevel,
+  type DepthSnapshot,
+} from '../dist/datafeed/index.js';
+import { createChart } from '../dist/index.js';
+import { MockCanvas } from '../dist/dom.js';
+
+const MIN = 60_000;
+const T0 = 1_700_000_040_000; // a 1m boundary
+
+const bar = (tMs: number): Candle => ({ time: tMs / 1000, open: 100, high: 101, low: 99, close: 100, volume: 1 });
+
+function snap(lastUpdateId: number, bids: DepthLevel[] = [], asks: DepthLevel[] = [], time?: number): DepthSnapshot {
+  return { lastUpdateId, bids, asks, ...(time === undefined ? {} : { time }) };
+}
+
+function delta(firstUpdateId: number, finalUpdateId: number, bids: DepthLevel[] = [], asks: DepthLevel[] = [], time?: number): DepthDelta {
+  return { firstUpdateId, finalUpdateId, bids, asks, ...(time === undefined ? {} : { time }) };
+}
+
+interface Clock {
+  now(): number;
+  set(ms: number): void;
+  advance(ms: number): void;
+}
+
+function clock(start = T0): Clock {
+  let t = start;
+  return {
+    now: () => t,
+    set: (ms) => {
+      t = ms;
+    },
+    advance: (ms) => {
+      t += ms;
+    },
+  };
+}
+
+interface HeldRead {
+  readonly item: DepthSnapshot | Error;
+  resolve(snapshot: DepthSnapshot): void;
+  reject(error: unknown): void;
+}
+
+/** A snapshot source reading planned items in order (the fallback when the plan runs out), optionally held until settled. */
+class FakeSnapshotSource {
+  reads = 0;
+  hold = false;
+  private queue: Array<DepthSnapshot | Error> = [];
+  private held: HeldRead[] = [];
+
+  constructor(private readonly fallback: DepthSnapshot) {}
+
+  plan(...items: Array<DepthSnapshot | Error>): void {
+    this.queue.push(...items);
+  }
+
+  readonly fetch = (): Promise<DepthSnapshot> => {
+    this.reads++;
+    const item = this.queue.length > 0 ? this.queue.shift()! : this.fallback;
+    if (!this.hold) return item instanceof Error ? Promise.reject(item) : Promise.resolve(item);
+    let resolve!: (snapshot: DepthSnapshot) => void;
+    let reject!: (error: unknown) => void;
+    const promise = new Promise<DepthSnapshot>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.held.push({ item, resolve, reject });
+    return promise;
+  };
+
+  get pending(): number {
+    return this.held.length;
+  }
+
+  /** Settles the oldest held read with its planned item. */
+  settleNext(): void {
+    const read = this.held.shift();
+    if (read === undefined) throw new Error('no held snapshot read');
+    if (read.item instanceof Error) read.reject(read.item);
+    else read.resolve(read.item);
+  }
+}
+
+/** Lets every settled read run to completion. */
+async function idle(): Promise<void> {
+  for (let i = 0; i < 5; i++) await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+function setup(opts: {
+  src: FakeSnapshotSource;
+  clock?: Clock;
+  onBook?: (book: DepthBook) => void;
+  maxBufferedDeltas?: number;
+}) {
+  const clk = opts.clock ?? clock();
+  const books: DepthBook[] = [];
+  const errors: unknown[] = [];
+  const manager = createDepthBookManager({
+    fetchSnapshot: opts.src.fetch,
+    onBook: (book) => {
+      books.push(book);
+      opts.onBook?.(book);
+    },
+    now: clk.now,
+    onError: (error) => errors.push(error),
+    ...(opts.maxBufferedDeltas === undefined ? {} : { maxBufferedDeltas: opts.maxBufferedDeltas }),
+  });
+  return { manager, books, errors, clock: clk };
+}
+
+function setupFeed(opts: {
+  src: FakeSnapshotSource | null;
+  clock?: Clock;
+  options?: Partial<DatafeedChartOptions>;
+}): ReturnType<typeof createDatafeedChart> & {
+  src: FakeSnapshotSource | null;
+  requests: DatafeedDepthRequest[];
+  errors: unknown[];
+  canvas: MockCanvas;
+  clock: Clock;
+} {
+  const clk = opts.clock ?? clock();
+  const src = opts.src;
+  const requests: DatafeedDepthRequest[] = [];
+  const errors: unknown[] = [];
+  const canvas = new MockCanvas(800, 400);
+  const options: DatafeedChartOptions = {
+    container: canvas,
+    config: { wasm: false },
+    fetchBars: async ({ toMs }) => (toMs >= T0 - MIN ? [bar(T0 - MIN), bar(T0)] : []),
+    symbol: 'BTC',
+    intervalMs: MIN,
+    now: clk.now,
+    onError: (error) => errors.push(error),
+  };
+  if (src !== null) {
+    options.fetchDepthSnapshot = (request) => {
+      requests.push(request);
+      return src.fetch();
+    };
+  }
+  const df = createDatafeedChart({ ...options, ...opts.options });
+  return { ...df, src, requests, errors, canvas, clock: clk };
+}
+
+let unhandled: unknown[] = [];
+const onUnhandled = (reason: unknown): void => {
+  unhandled.push(reason);
+};
+before(() => {
+  process.on('unhandledRejection', onUnhandled);
+});
+after(() => {
+  process.off('unhandledRejection', onUnhandled);
+  assert.deepEqual(unhandled, [], 'no unhandled rejections');
+});
+
+describe('depth constants', () => {
+  it('mirror the datafeed retry backoff', () => {
+    assert.equal(MAX_BUFFERED_DELTAS, 2_000);
+    assert.equal(DEPTH_RETRY_BACKOFF_MS, RETRY_BACKOFF_MS);
+    assert.equal(DEPTH_MAX_RETRY_BACKOFF_MS, MAX_RETRY_BACKOFF_MS);
+  });
+});
+
+describe('normalizeDepthSide', () => {
+  it('sorts bids descending and asks ascending', () => {
+    assert.deepEqual(normalizeDepthSide([[99, 1], [101, 2], [100, 3]], true), [[101, 2], [100, 3], [99, 1]]);
+    assert.deepEqual(normalizeDepthSide([[99, 1], [101, 2], [100, 3]], false), [[99, 1], [100, 3], [101, 2]]);
+  });
+  it('drops zero, negative and non-finite sizes and resolves duplicates last-wins', () => {
+    assert.deepEqual(normalizeDepthSide([[100, 1], [100, 5], [99, 0], [101, Number.NaN]], true), [[100, 5]]);
+    assert.deepEqual(normalizeDepthSide([[100, 0]], false), []);
+  });
+});
+
+describe('applyDepthLevels', () => {
+  it('upserts, inserts in order and removes at size 0', () => {
+    const bids: DepthLevel[] = [[100, 1], [98, 1]];
+    applyDepthLevels(bids, [[100, 5], [99, 2], [101, 1], [98, 0], [97, 0]], true);
+    assert.deepEqual(bids, [[101, 1], [100, 5], [99, 2]]);
+  });
+  it('ignores levels with a non-finite or negative size or price', () => {
+    const asks: DepthLevel[] = [[101, 1]];
+    applyDepthLevels(asks, [[Number.NaN, 1], [102, -1], [101, Number.POSITIVE_INFINITY], [102, 3]], false);
+    assert.deepEqual(asks, [[101, 1], [102, 3]]);
+  });
+});
+
+describe('createDepthBookManager', () => {
+  it('loads the snapshot and publishes a sorted book', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[99, 1], [100, 2]], [[102, 3], [101, 4]]));
+    const t = setup({ src });
+    assert.equal(t.manager.syncing, true);
+    assert.equal(t.manager.book, null);
+    await idle();
+    assert.equal(src.reads, 1);
+    assert.equal(t.manager.syncing, false);
+    assert.deepEqual(t.books.length, 1);
+    assert.deepEqual(t.books[0]!.bids, [[100, 2], [99, 1]]);
+    assert.deepEqual(t.books[0]!.asks, [[101, 4], [102, 3]]);
+    assert.equal(t.manager.book, t.books[0]);
+    assert.deepEqual(t.errors, []);
+  });
+
+  it('buffers deltas until the snapshot lands, then drains them in order', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2], [99, 1]], [[101, 4], [102, 3]]));
+    src.hold = true;
+    const t = setup({ src });
+    t.manager.pushDelta(delta(90, 100, [[100, 9]])); // covered by the snapshot: dropped
+    t.manager.pushDelta(delta(101, 101, [[100, 5]], [[101, 0]], T0 + 1));
+    assert.equal(t.books.length, 0);
+    src.settleNext();
+    await idle();
+    assert.deepEqual(t.books.length, 2);
+    assert.deepEqual(t.books[1]!.bids, [[100, 5], [99, 1]]);
+    assert.deepEqual(t.books[1]!.asks, [[102, 3]]);
+    assert.equal(t.books[1]!.time, T0 + 1);
+    assert.deepEqual(t.errors, []);
+  });
+
+  it('applies live deltas and drops stale ones without publishing', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], [[101, 4]]));
+    const t = setup({ src });
+    await idle();
+    t.manager.pushDelta(delta(101, 102, [[100, 5]], [[101, 0]]));
+    t.manager.pushDelta(delta(50, 99, [[100, 9]])); // stale
+    t.manager.pushDelta(delta(101, 102, [[100, 9]])); // already applied
+    assert.deepEqual(t.books.length, 2);
+    assert.deepEqual(t.books[1]!.bids, [[100, 5]]);
+    assert.deepEqual(t.books[1]!.asks, []);
+    assert.equal(src.reads, 1, 'stale deltas never resync');
+  });
+
+  it('resyncs from a fresh snapshot on a sequence gap', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], [[101, 4]]));
+    const t = setup({ src });
+    await idle();
+    t.manager.pushDelta(delta(101, 101, [[100, 3]]));
+    assert.deepEqual(t.books.length, 2);
+    src.plan(snap(200, [[50, 1]], [[60, 1]]));
+    t.manager.pushDelta(delta(105, 105, [[100, 7]]));
+    assert.equal(t.manager.syncing, true);
+    await idle();
+    assert.equal(src.reads, 2);
+    assert.equal(t.manager.syncing, false);
+    // The gapped delta is stale against the new snapshot: the book never shows bid 100 @ 7.
+    assert.deepEqual(t.books.length, 3);
+    assert.deepEqual(t.books[2]!.bids, [[50, 1]]);
+    assert.deepEqual(t.books[2]!.asks, [[60, 1]]);
+    assert.deepEqual(t.errors, []);
+  });
+
+  it('a gap inside the drain resyncs after the backoff and keeps the remaining deltas', async () => {
+    const clk = clock();
+    const src = new FakeSnapshotSource(snap(10, [[10, 1]], [[20, 1]]));
+    src.hold = true;
+    src.plan(snap(10, [[10, 1]], [[20, 1]]), snap(14, [[11, 1]], [[21, 1]]));
+    const t = setup({ src, clock: clk });
+    t.manager.pushDelta(delta(11, 11, [[10, 2]]));
+    t.manager.pushDelta(delta(15, 15, [[11, 5]]));
+    t.manager.pushDelta(delta(16, 16, [], [[21, 0]]));
+    src.settleNext();
+    await idle();
+    assert.deepEqual(t.books.length, 2, 'the drain stops at the gap');
+    assert.deepEqual(t.books[1]!.bids, [[10, 2]]);
+    assert.equal(t.manager.syncing, true);
+    // The stream made no progress since the settle, so the resync waits out the backoff instead of hammering the source.
+    assert.equal(src.reads, 1, 'no immediate re-read');
+    t.manager.pushDelta(delta(17, 17, [[12, 1]]));
+    assert.equal(src.reads, 1, 'the backoff has not elapsed');
+    clk.advance(DEPTH_RETRY_BACKOFF_MS);
+    t.manager.pushDelta(delta(18, 18, [[12, 2]]));
+    assert.equal(src.reads, 2, 'the first delta after the backoff drives the resync');
+    src.settleNext();
+    await idle();
+    assert.equal(t.manager.syncing, false);
+    assert.deepEqual(t.books.length, 7);
+    const last = t.books.at(-1)!;
+    assert.deepEqual(last.bids, [[12, 2], [11, 5]]);
+    assert.deepEqual(last.asks, [], 'the ask added by the second snapshot is removed again');
+    assert.deepEqual(t.errors, []);
+  });
+
+  it('retries a failed snapshot read with doubling backoff, driven by arriving deltas', async () => {
+    const clk = clock();
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.plan(new Error('offline'), new Error('offline'));
+    const t = setup({ src, clock: clk });
+    await idle();
+    assert.equal(src.reads, 1);
+    assert.deepEqual(t.errors.length, 1);
+    assert.equal(t.manager.syncing, true);
+    t.manager.pushDelta(delta(101, 101, [[100, 5]]));
+    assert.equal(src.reads, 1, 'the backoff has not elapsed');
+    clk.advance(DEPTH_RETRY_BACKOFF_MS);
+    t.manager.pushDelta(delta(102, 102, [[100, 6]]));
+    await idle();
+    assert.equal(src.reads, 2);
+    assert.deepEqual(t.errors.length, 2);
+    clk.advance(DEPTH_RETRY_BACKOFF_MS);
+    t.manager.pushDelta(delta(103, 103, [[100, 7]]));
+    assert.equal(src.reads, 2, 'the doubled backoff has not elapsed');
+    clk.advance(DEPTH_RETRY_BACKOFF_MS);
+    t.manager.pushDelta(delta(104, 104, [[100, 8]]));
+    await idle();
+    assert.equal(src.reads, 3, 'retried once the doubled backoff elapsed');
+    assert.equal(t.manager.syncing, false);
+    const last = t.books.at(-1)!;
+    assert.deepEqual(last.bids, [[100, 8]], 'every buffered delta drained in order after the retry');
+    assert.deepEqual(t.errors.length, 2, 'a success reports nothing');
+  });
+
+  it('ignores deltas with invalid update ids', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    const t = setup({ src });
+    await idle();
+    t.manager.pushDelta(delta(Number.NaN, 101));
+    t.manager.pushDelta(delta(105, 101));
+    t.manager.pushDelta(delta(101.5, 101));
+    assert.equal(t.books.length, 1);
+    assert.equal(src.reads, 1, 'an invalid delta is neither applied nor a gap');
+  });
+
+  it('stops publishing after dispose, including a snapshot that lands later', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.hold = true;
+    const t = setup({ src });
+    t.manager.dispose();
+    src.settleNext();
+    await idle();
+    t.manager.pushDelta(delta(101, 101, [[100, 5]]));
+    assert.deepEqual(t.books, []);
+    assert.equal(t.manager.book, null);
+    assert.deepEqual(t.errors, []);
+  });
+
+  it('caps the deltas buffered while the snapshot is in flight, evicting the oldest', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.hold = true;
+    const t = setup({ src, maxBufferedDeltas: 2 });
+    t.manager.pushDelta(delta(99, 99, [[100, 9]]));
+    t.manager.pushDelta(delta(100, 100, [[100, 8]]));
+    t.manager.pushDelta(delta(101, 101, [[100, 5]]));
+    src.settleNext();
+    await idle();
+    const last = t.books.at(-1)!;
+    assert.deepEqual(last.bids, [[100, 5]], 'the evicted delta never applies');
+  });
+
+  it('an onBook throw in a live push reaches the caller', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    const clk = clock();
+    const errors: unknown[] = [];
+    let fail = false;
+    const manager = createDepthBookManager({
+      fetchSnapshot: src.fetch,
+      onBook: () => {
+        if (fail) throw new Error('boom');
+      },
+      now: clk.now,
+      onError: (error) => errors.push(error),
+    });
+    await idle();
+    fail = true;
+    assert.throws(() => manager.pushDelta(delta(101, 101, [[100, 5]])));
+    assert.deepEqual(errors, []);
+  });
+
+  it('an onBook throw while the snapshot settles is reported, and the drain still applies', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], [[101, 4]]));
+    src.hold = true;
+    const clk = clock();
+    const books: DepthBook[] = [];
+    const errors: unknown[] = [];
+    let fail = true;
+    const manager = createDepthBookManager({
+      fetchSnapshot: src.fetch,
+      onBook: (book) => {
+        if (fail) {
+          fail = false;
+          throw new Error('boom');
+        }
+        books.push(book);
+      },
+      now: clk.now,
+      onError: (error) => errors.push(error),
+    });
+    manager.pushDelta(delta(101, 101, [[100, 5]], [[101, 0]]));
+    src.settleNext();
+    await idle();
+    assert.deepEqual(errors.length, 1, "the snapshot publish's error is reported");
+    assert.deepEqual(books.length, 1, 'the buffered delta still published');
+    assert.deepEqual(books[0]!.bids, [[100, 5]]);
+    assert.deepEqual(books[0]!.asks, []);
+  });
+
+  it('an onBook throw on a drained delta is reported, and the deltas behind it still apply', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.hold = true;
+    const books: DepthBook[] = [];
+    const errors: unknown[] = [];
+    const manager = createDepthBookManager({
+      fetchSnapshot: src.fetch,
+      onBook: (book) => {
+        books.push(book);
+        if (books.length === 2) throw new Error('boom');
+      },
+      now: clock().now,
+      onError: (error) => errors.push(error),
+    });
+    manager.pushDelta(delta(101, 101, [[100, 5]]));
+    manager.pushDelta(delta(102, 102, [[100, 6]]));
+    manager.pushDelta(delta(103, 103, [[100, 7]]));
+    src.settleNext();
+    await idle();
+    assert.deepEqual(errors.length, 1, "the drained delta's publish error is reported");
+    assert.deepEqual(books.length, 4, 'the drain continued past the throw');
+    assert.deepEqual(manager.book!.bids, [[100, 7]]);
+    manager.pushDelta(delta(104, 104, [[100, 8]]));
+    assert.deepEqual(manager.book!.bids, [[100, 8]], 'the sequence continues live');
+    assert.equal(src.reads, 1, 'no resync');
+  });
+
+  it('a drain that both throws and gaps reports the throw and resyncs after the backoff', async () => {
+    const clk = clock();
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.hold = true;
+    const errors: unknown[] = [];
+    let publishes = 0;
+    const manager = createDepthBookManager({
+      fetchSnapshot: src.fetch,
+      onBook: () => {
+        if (++publishes === 2) throw new Error('boom');
+      },
+      now: clk.now,
+      onError: (error) => errors.push(error),
+    });
+    manager.pushDelta(delta(101, 101, [[100, 5]]));
+    manager.pushDelta(delta(105, 105, [[100, 6]]));
+    src.settleNext();
+    await idle();
+    assert.equal(errors.length, 1);
+    assert.equal(manager.syncing, true, 'the gap resyncs');
+    assert.equal(src.reads, 1, 'after the backoff');
+  });
+
+  it('dispose from onBook mid-drain stops the remaining deltas', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.hold = true;
+    const books: DepthBook[] = [];
+    const manager = createDepthBookManager({
+      fetchSnapshot: src.fetch,
+      onBook: (book) => {
+        books.push(book);
+        if (books.length === 2) manager.dispose();
+      },
+      now: clock().now,
+    });
+    manager.pushDelta(delta(101, 101, [[100, 5]]));
+    manager.pushDelta(delta(102, 102, [[100, 6]]));
+    src.settleNext();
+    await idle();
+    assert.deepEqual(books.length, 2, 'the second buffered delta never publishes');
+    assert.deepEqual(books[1]!.bids, [[100, 5]]);
+  });
+
+  it('a snapshot read failing after dispose is neither reported nor retried', async () => {
+    const src = new FakeSnapshotSource(snap(100));
+    src.hold = true;
+    src.plan(new Error('offline'));
+    const t = setup({ src });
+    t.manager.dispose();
+    src.settleNext();
+    await idle();
+    t.manager.pushDelta(delta(101, 101));
+    assert.deepEqual(t.errors, []);
+    assert.equal(src.reads, 1);
+  });
+
+  it('rejects a snapshot with an invalid lastUpdateId and retries it after the backoff', async () => {
+    const clk = clock();
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.plan(snap(-1), snap(1.5));
+    const t = setup({ src, clock: clk });
+    await idle();
+    assert.equal(t.errors.length, 1);
+    assert.match(String(t.errors[0]), /lastUpdateId must be a nonnegative safe integer, got -1/);
+    assert.deepEqual(t.books, []);
+    assert.equal(t.manager.syncing, true);
+    t.manager.pushDelta(delta(101, 101));
+    assert.equal(src.reads, 1, 'the backoff has not elapsed');
+    clk.advance(DEPTH_RETRY_BACKOFF_MS);
+    t.manager.pushDelta(delta(102, 102));
+    await idle();
+    assert.equal(src.reads, 2);
+    assert.match(String(t.errors[1]), /got 1\.5/);
+    clk.advance(2 * DEPTH_RETRY_BACKOFF_MS);
+    t.manager.pushDelta(delta(103, 103, [[100, 5]]));
+    await idle();
+    assert.equal(src.reads, 3);
+    assert.equal(t.manager.syncing, false);
+    assert.deepEqual(t.manager.book!.bids, [[100, 5]]);
+  });
+
+  it('drops errors thrown by onError itself, and defaults the clock to Date.now', async () => {
+    const src = new FakeSnapshotSource(snap(100));
+    src.plan(new Error('offline'));
+    let calls = 0;
+    const manager = createDepthBookManager({
+      fetchSnapshot: src.fetch,
+      onBook: () => {},
+      onError: () => {
+        calls++;
+        throw new Error('handler failed');
+      },
+    });
+    await idle();
+    assert.equal(calls, 1);
+    manager.pushDelta(delta(101, 101));
+    assert.equal(src.reads, 1, 'Date.now has not moved past the default backoff');
+    manager.dispose();
+  });
+});
+
+describe('chart depth channel', () => {
+  it('stores the book outside the candle store and re-renders on every update', () => {
+    const canvas = new MockCanvas(800, 400);
+    const chart = createChart({ container: canvas, config: { wasm: false } });
+    assert.equal(chart.depth, null);
+    const book: DepthBook = { bids: [[100, 1]], asks: [[101, 1]], time: T0 };
+    const before = canvas.context.calls.length;
+    chart.setDepth(book);
+    assert.equal(chart.depth, book);
+    assert.ok(canvas.context.calls.length > before, 'a book update re-renders');
+    chart.setDepth(null);
+    assert.equal(chart.depth, null);
+    chart.destroy();
+    assert.equal(chart.depth, null);
+  });
+});
+
+describe('datafeed depth channel', () => {
+  it('maintains a book for the current symbol, delivers it to subscribeDepth and re-renders on every update', async () => {
+    const t = setupFeed({ src: new FakeSnapshotSource(snap(100, [[100, 2], [99, 1]], [[101, 4]])) });
+    const books: DepthBook[] = [];
+    t.datafeed.subscribeDepth('BTC', (book) => books.push(book));
+    await idle();
+    assert.equal(t.requests.length, 1);
+    assert.equal(t.requests[0]!.symbol, 'BTC');
+    assert.deepEqual(books.length, 1);
+    assert.equal(t.chart.depth, books[0]);
+    t.datafeed.pushDepth(delta(101, 101, [[100, 5]]));
+    assert.deepEqual(books.length, 2);
+    assert.deepEqual(books[1]!.bids, [[100, 5], [99, 1]]);
+    assert.equal(t.chart.depth, books[1]);
+    const before = t.canvas.context.calls.length;
+    t.datafeed.pushDepth(delta(102, 102, [[99, 0]]));
+    assert.ok(t.canvas.context.calls.length > before, 'every L2 update re-renders');
+    assert.deepEqual(t.chart.depth!.bids, [[100, 5]]);
+    assert.deepEqual(t.errors, []);
+    t.destroy();
+  });
+
+  it('ignores depth events tagged with another symbol', async () => {
+    const t = setupFeed({ src: new FakeSnapshotSource(snap(100, [[100, 2]], [])) });
+    const books: DepthBook[] = [];
+    t.datafeed.subscribeDepth('BTC', (book) => books.push(book));
+    await idle();
+    t.datafeed.pushDepth(delta(101, 101, [[100, 9]]), 'ETH');
+    assert.deepEqual(books.length, 1);
+    assert.deepEqual(t.chart.depth!.bids, [[100, 2]]);
+    t.destroy();
+  });
+
+  it('resyncs through the datafeed after a sequence gap', async () => {
+    const t = setupFeed({ src: new FakeSnapshotSource(snap(100, [[100, 2]], [[101, 4]])) });
+    const books: DepthBook[] = [];
+    t.datafeed.subscribeDepth('BTC', (book) => books.push(book));
+    await idle();
+    t.datafeed.pushDepth(delta(105, 105, [[100, 9]]));
+    await idle();
+    assert.equal(t.requests.length, 2, 'the gap re-read the snapshot');
+    const last = books.at(-1)!;
+    assert.deepEqual(last.bids, [[100, 2]], 'the gapped delta never reached the book');
+    assert.deepEqual(t.errors, []);
+    t.destroy();
+  });
+
+  it('a symbol switch clears the book and restarts depth for the new symbol', async () => {
+    const t = setupFeed({ src: new FakeSnapshotSource(snap(100, [[100, 2]], [[101, 4]])) });
+    const btc: DepthBook[] = [];
+    const eth: DepthBook[] = [];
+    t.datafeed.subscribeDepth('BTC', (book) => btc.push(book));
+    t.datafeed.subscribeDepth('ETH', (book) => eth.push(book));
+    await idle();
+    assert.deepEqual(btc.length, 1);
+    const switching = t.datafeed.setSymbol('ETH', MIN);
+    assert.equal(t.chart.depth, null, 'the previous book leaves the chart at once');
+    await switching;
+    await idle();
+    assert.equal(t.requests.length, 2);
+    assert.equal(t.requests[1]!.symbol, 'ETH');
+    assert.deepEqual(btc.length, 1, "the old symbol's listener hears nothing more");
+    assert.deepEqual(eth.length, 1);
+    assert.equal(t.chart.depth, eth[0]);
+    t.destroy();
+  });
+
+  it('unsubscribe stops delivery but not the chart channel', async () => {
+    const t = setupFeed({ src: new FakeSnapshotSource(snap(100, [[100, 2]], [])) });
+    const books: DepthBook[] = [];
+    const off = t.datafeed.subscribeDepth('BTC', (book) => books.push(book));
+    await idle();
+    off();
+    t.datafeed.pushDepth(delta(101, 101, [[100, 5]]));
+    assert.deepEqual(books.length, 1);
+    assert.deepEqual(t.chart.depth!.bids, [[100, 5]]);
+    t.destroy();
+  });
+
+  it('destroy aborts the snapshot read and stops the depth channel', async () => {
+    const src = new FakeSnapshotSource(snap(100, [[100, 2]], []));
+    src.hold = true;
+    const t = setupFeed({ src });
+    const books: DepthBook[] = [];
+    t.datafeed.subscribeDepth('BTC', (book) => books.push(book));
+    await idle();
+    assert.equal(src.pending, 1);
+    t.datafeed.destroy();
+    assert.equal(t.requests[0]!.signal.aborted, true);
+    assert.equal(t.chart.depth, null);
+    src.settleNext();
+    await idle();
+    assert.deepEqual(books, [], 'a late snapshot never publishes');
+    assert.deepEqual(t.errors, []);
+    t.chart.destroy();
+  });
+
+  it('reports a depth listener failure instead of throwing into the feed callback', async () => {
+    const t = setupFeed({ src: new FakeSnapshotSource(snap(100, [[100, 2]], [])) });
+    let fail = false;
+    t.datafeed.subscribeDepth('BTC', () => {
+      if (fail) throw new Error('listener failed');
+    });
+    await idle();
+    fail = true;
+    assert.doesNotThrow(() => t.datafeed.pushDepth(delta(101, 101, [[100, 5]])));
+    assert.equal(t.errors.length, 1);
+    assert.match(String(t.errors[0]), /listener failed/);
+    assert.deepEqual(t.chart.depth!.bids, [[100, 5]], 'the chart still received the book');
+    t.destroy();
+  });
+
+  it('without fetchDepthSnapshot, pushDepth is ignored and subscribeDepth never fires', async () => {
+    const t = setupFeed({ src: null });
+    const books: DepthBook[] = [];
+    t.datafeed.subscribeDepth('BTC', (book) => books.push(book));
+    await idle();
+    t.datafeed.pushDepth(delta(1, 1, [[100, 2]]));
+    await idle();
+    assert.deepEqual(books, []);
+    assert.equal(t.chart.depth, null);
+    assert.deepEqual(t.errors, []);
+    t.destroy();
+  });
+});
diff --git a/packages/chart/test/dom.test.ts b/packages/chart/test/dom.test.ts
index e44c5f3..80338ea 100644
--- a/packages/chart/test/dom.test.ts
+++ b/packages/chart/test/dom.test.ts
@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { MockCanvas, MockContext2D, MockDocument } from '../dist/dom.js';
+import { MockCanvas, MockContext2D, MockContextWebGL2, MockDocument, MockGLCanvas, MockGLDocument } from '../dist/dom.js';
 
 describe('MockDocument / MockCanvas', () => {
   it('creates canvases with requested sizes and tracks them', () => {
@@ -79,3 +79,79 @@ describe('MockContext2D', () => {
     assert.equal(ctx.globalAlpha, 0.5);
   });
 });
+
+describe('MockContextWebGL2', () => {
+  it('reports shader compile status and info log for success and failure', () => {
+    const gl = new MockContextWebGL2();
+    const shader = gl.createShader(gl.VERTEX_SHADER);
+    assert.equal(gl.getShaderParameter(shader, gl.COMPILE_STATUS), true);
+    assert.equal(gl.getShaderInfoLog(shader), null);
+    gl.compileStatus = false;
+    assert.equal(gl.getShaderParameter(shader, gl.COMPILE_STATUS), false);
+    assert.equal(gl.getShaderInfoLog(shader), 'mock compile error');
+    assert.equal(gl.countCalls('getShaderInfoLog'), 2);
+  });
+  it('reports program link status and info log for success and failure', () => {
+    const gl = new MockContextWebGL2();
+    const program = gl.createProgram();
+    assert.equal(gl.getProgramParameter(program, gl.LINK_STATUS), true);
+    assert.equal(gl.getProgramInfoLog(program), null);
+    gl.linkStatus = false;
+    assert.equal(gl.getProgramParameter(program, gl.LINK_STATUS), false);
+    assert.equal(gl.getProgramInfoLog(program), 'mock link error');
+    assert.deepEqual(gl.callsNamed('getProgramInfoLog').map((c) => c[0]), ['getProgramInfoLog', 'getProgramInfoLog']);
+  });
+  it('records enable, disable and blend state calls', () => {
+    const gl = new MockContextWebGL2();
+    gl.enable(gl.BLEND);
+    gl.disable(gl.SCISSOR_TEST);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.clearColor(0, 0, 0, 1);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.viewport(0, 0, 10, 10);
+    gl.scissor(1, 2, 3, 4);
+    const names = gl.calls.map((c) => c[0]);
+    assert.deepEqual(names, ['enable', 'disable', 'blendFunc', 'clearColor', 'clear', 'viewport', 'scissor']);
+    assert.deepEqual(gl.callsNamed('disable')[0], ['disable', gl.SCISSOR_TEST]);
+  });
+});
+
+describe('MockGLCanvas / MockGLDocument', () => {
+  it('getContext returns the GL context for webgl2, 2d context for 2d, null otherwise', () => {
+    const canvas = new MockGLCanvas(20, 10);
+    assert.ok(canvas.getContext('webgl2') instanceof MockContextWebGL2);
+    assert.ok(canvas.getContext('2d') instanceof MockContext2D);
+    assert.equal(canvas.getContext('webgl' as '2d'), null);
+    assert.equal(canvas.width, 20);
+    assert.equal(canvas.height, 10);
+  });
+  it('honors compile/link options for every combination', () => {
+    const fallback = new MockGLCanvas(0, 0, {});
+    assert.equal(fallback.gl.compileStatus, true);
+    assert.equal(fallback.gl.linkStatus, true);
+    const noCompile = new MockGLCanvas(0, 0, { compile: false });
+    assert.equal(noCompile.gl.compileStatus, false);
+    assert.equal(noCompile.gl.linkStatus, true);
+    const noLink = new MockGLCanvas(0, 0, { link: false });
+    assert.equal(noLink.gl.compileStatus, true);
+    assert.equal(noLink.gl.linkStatus, false);
+    const explicit = new MockGLCanvas(0, 0, { compile: true, link: true });
+    assert.equal(explicit.gl.compileStatus, true);
+    assert.equal(explicit.gl.linkStatus, true);
+  });
+  it('MockGLDocument creates tracked canvases with default options', () => {
+    const doc = new MockGLDocument();
+    const canvas = doc.createCanvas(8, 6);
+    assert.equal(doc.created.length, 1);
+    assert.ok(canvas instanceof MockGLCanvas);
+    assert.equal(doc.created[0]!.gl.compileStatus, true);
+    assert.equal(doc.created[0]!.gl.linkStatus, true);
+  });
+  it('MockGLDocument forwards compile/link options to created canvases', () => {
+    const doc = new MockGLDocument({ compile: false, link: false });
+    const canvas = doc.createCanvas(8, 6);
+    assert.equal(doc.created.length, 1);
+    assert.equal((canvas as MockGLCanvas).gl.compileStatus, false);
+    assert.equal((canvas as MockGLCanvas).gl.linkStatus, false);
+  });
+});
diff --git a/packages/chart/test/drawings.test.ts b/packages/chart/test/drawings.test.ts
index 1933a41..2044205 100644
--- a/packages/chart/test/drawings.test.ts
+++ b/packages/chart/test/drawings.test.ts
@@ -12,8 +12,9 @@ import {
   hlineDrawing,
   rectDrawing,
   trendlineDrawing,
+  volumeProfile,
 } from '../dist/drawings/index.js';
-import type { DrawingDef, DrawingView, DrawPrimitive } from '../dist/drawings/index.js';
+import type { DrawingDef, DrawingView, DrawPrimitive, FullView } from '../dist/drawings/index.js';
 import type { Candle } from '../dist/core/data.js';
 
 // Identity pixel view: index → x * 10, price → y = 100 - price.
@@ -276,6 +277,18 @@ describe('forecasting', () => {
     const prims = def.geometry([{ index: 55, price: 1 }], { ...fullView, candles: sampleCandles.map((c) => ({ ...c, volume: 0 })) });
     assert.ok(prims.some((p) => p.type === 'text' && p.text.startsWith('VWAP ')));
   });
+  it('anchored VWAP weights bars without a volume field as 1', () => {
+    const def = BUILTIN_DRAWINGS.find((d) => d.name === 'anchored-vwap')!;
+    const prims = def.geometry([{ index: 55, price: 1 }], {
+      ...fullView,
+      candles: sampleCandles.map(({ volume: _v, ...c }) => c),
+    });
+    assertFinite(prims, 'volume-less vwap');
+    assert.ok(prims.some((p) => p.type === 'text' && p.text.startsWith('VWAP ')));
+  });
+  it('volumeProfile falls back to a zero grid for a degenerate row count', () => {
+    assert.deepEqual(volumeProfile(fullView as FullView, 0, 10, 0), { lo: 0, hi: 0, up: [], down: [] });
+  });
   it('projection shows a dash for a flat first leg', () => {
     const def = BUILTIN_DRAWINGS.find((d) => d.name === 'projection')!;
     const prims = def.geometry([{ index: 1, price: 50 }, { index: 5, price: 50 }, { index: 9, price: 60 }], view);
diff --git a/packages/chart/test/extension-points.test.ts b/packages/chart/test/extension-points.test.ts
new file mode 100644
index 0000000..c567578
--- /dev/null
+++ b/packages/chart/test/extension-points.test.ts
@@ -0,0 +1,237 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createChart } from '../dist/index.js';
+import { MockDocument } from '../dist/dom.js';
+import { createSeriesRegistry } from '../dist/series/index.js';
+import type { Candle } from '../dist/core/data.js';
+import type { PrimitiveDrawTarget } from '../dist/render/primitive.js';
+
+function candles(n: number): Candle[] {
+  return Array.from({ length: n }, (_, i) => ({
+    time: 1700000000 + i * 3600,
+    open: 100 + i,
+    high: 102 + i,
+    low: 99 + i,
+    close: 101 + i,
+    volume: 1000 + i,
+  }));
+}
+
+describe('SeriesRegistry', () => {
+  it('pre-loads the built-in renderers', () => {
+    const registry = createSeriesRegistry();
+    for (const type of ['candlestick', 'line', 'area', 'bar', 'histogram', 'heikin-ashi', 'hollow-candlestick']) {
+      assert.ok(registry.has(type), type);
+    }
+    assert.equal(registry.names().length, 7);
+  });
+
+  it('starts empty without built-ins and supports register/unregister', () => {
+    const registry = createSeriesRegistry(false);
+    assert.equal(registry.names().length, 0);
+    const draw = (): void => {};
+    assert.equal(registry.register('custom', draw), registry);
+    assert.equal(registry.get('custom'), draw);
+    assert.ok(registry.has('custom'));
+    assert.deepEqual(registry.names(), ['custom']);
+    assert.ok(registry.unregister('custom'));
+    assert.equal(registry.get('custom'), undefined);
+    assert.ok(!registry.unregister('custom'));
+  });
+});
+
+describe('Chart.registerSeries', () => {
+  it('draws a custom series type through the registered function', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400, series: { type: 'stairs' } },
+    });
+    const seen: { candles: number; from: number; to: number }[] = [];
+    chart.registerSeries('stairs', (_ctx, data, range) => {
+      seen.push({ candles: data.length, from: range.from, to: range.to });
+    });
+    assert.equal(seen.length, 1);
+    assert.equal(seen[0]!.candles, 20);
+    assert.ok(seen[0]!.to > seen[0]!.from);
+    chart.destroy();
+  });
+
+  it('ignores an unregistered series type instead of throwing', () => {
+    assert.doesNotThrow(() => {
+      const chart = createChart({
+        document: new MockDocument(),
+        config: { wasm: false, data: candles(5), series: { type: 'no-such-type' } },
+      });
+      chart.destroy();
+    });
+  });
+
+  it('keeps drawing built-in types without registration', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(10), series: { type: 'line' } },
+    });
+    assert.ok(chart.seriesRenderers.has('line'));
+    chart.destroy();
+  });
+});
+
+describe('Chart.addPane', () => {
+  it('stacks a host pane between the main pane and sub-panes', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    chart.addIndicator({ name: 'rsi' });
+    const pane = chart.addPane({ id: 'host', weight: 1 });
+    assert.equal(pane.id, 'host');
+    // plotHeight 376, weights 3:1:1 → main 225, host 75, rsi 76 (remainder).
+    assert.equal(chart.paneAt(10), 'main');
+    assert.equal(chart.paneAt(226), 'host');
+    const hostPaneBottom = 225 + 75;
+    assert.equal(chart.paneAt(hostPaneBottom + 1), chart.getConfig().indicators[0]!.id);
+    assert.throws(() => chart.addPane({ id: 'host' }), /duplicate pane/);
+    chart.destroy();
+  });
+
+  it('scales a stacked pane with its autoscale callback', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const pane = chart.addPane({ id: 'host', autoscale: () => ({ min: 10, max: 20 }) });
+    const seen: PrimitiveDrawTarget[] = [];
+    pane.attachPrimitive({ draw: (_ctx, t) => { seen.push(t); } });
+    assert.equal(seen.length, 1);
+    assert.equal(seen[0]!.priceScale.minPrice, 10);
+    assert.equal(seen[0]!.priceScale.maxPrice, 20);
+    chart.destroy();
+  });
+
+  it('shares the main pane price scale when asked', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const mainSeen: PrimitiveDrawTarget[] = [];
+    chart.attachPrimitive({ draw: (_ctx, t) => { mainSeen.push(t); } });
+    const pane = chart.addPane({ id: 'host', sharePriceScale: true });
+    const hostSeen: PrimitiveDrawTarget[] = [];
+    pane.attachPrimitive({ draw: (_ctx, t) => { hostSeen.push(t); } });
+    assert.ok(mainSeen.length > 0 && hostSeen.length > 0);
+    assert.equal(hostSeen[0]!.priceScale.minPrice, mainSeen[0]!.priceScale.minPrice);
+    assert.equal(hostSeen[0]!.priceScale.maxPrice, mainSeen[0]!.priceScale.maxPrice);
+    chart.destroy();
+  });
+
+  it('docks a pane at the canvas edge and shrinks the plot', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const fullWidth = chart.plotArea.width;
+    const left = chart.addPane({ id: 'book', placement: 'left', width: 120 });
+    assert.equal(chart.plotArea.left, 120);
+    assert.equal(chart.plotArea.width, fullWidth - 120);
+    const leftSeen: PrimitiveDrawTarget[] = [];
+    left.attachPrimitive({ draw: (_ctx, t) => { leftSeen.push(t); } });
+    assert.equal(leftSeen.length, 1);
+    assert.equal(leftSeen[0]!.width, 120);
+    assert.equal(leftSeen[0]!.height, 376);
+    const right = chart.addPane({ id: 'depth', placement: 'right', width: 100 });
+    assert.equal(chart.plotArea.width, fullWidth - 220);
+    assert.equal(chart.plotArea.left, 120);
+    const rightSeen: PrimitiveDrawTarget[] = [];
+    right.attachPrimitive({ draw: (_ctx, t) => { rightSeen.push(t); } });
+    assert.equal(rightSeen.length, 1);
+    assert.equal(rightSeen[0]!.width, 100);
+    right.setWidth(60);
+    assert.equal(chart.plotArea.width, fullWidth - 180);
+    chart.destroy();
+  });
+
+  it('defaults to a sequential stacked pane and re-lays out on setWeight', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const pane = chart.addPane();
+    assert.equal(pane.id, 'pane-1');
+    assert.equal(chart.addPane().id, 'pane-2');
+    chart.removePane('pane-2');
+    // plotHeight 376, weights 3:1 → main 282.
+    assert.equal(chart.paneAt(250), 'main');
+    pane.setWeight(3);
+    // weights 3:3 → main 188.
+    assert.equal(chart.paneAt(250), 'pane-1');
+    chart.destroy();
+  });
+
+  it('removes panes by handle or id and restores the plot', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const fullWidth = chart.plotArea.width;
+    const pane = chart.addPane({ id: 'depth', placement: 'right', width: 100 });
+    pane.remove();
+    assert.equal(chart.plotArea.width, fullWidth);
+    chart.addPane({ id: 'again', placement: 'right', width: 100 });
+    assert.ok(chart.removePane('again'));
+    assert.ok(!chart.removePane('again'));
+    assert.equal(chart.plotArea.width, fullWidth);
+    chart.destroy();
+  });
+});
+
+describe('pane primitives', () => {
+  it('draws behind and above passes on the main pane with per-frame invalidation', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const calls: string[] = [];
+    chart.attachPrimitive({ zOrder: 'behind', draw: () => { calls.push('behind'); } });
+    const above = chart.attachPrimitive({ draw: () => { calls.push('above'); } });
+    assert.deepEqual(calls, ['behind', 'behind', 'above']);
+    above.requestUpdate();
+    assert.deepEqual(calls, ['behind', 'behind', 'above', 'behind', 'above']);
+    above.detach();
+    assert.deepEqual(calls, ['behind', 'behind', 'above', 'behind', 'above', 'behind']);
+    chart.destroy();
+  });
+
+  it('gives main-pane primitives the pane geometry and scales', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const seen: PrimitiveDrawTarget[] = [];
+    chart.attachPrimitive({ draw: (_ctx, t) => { seen.push(t); } });
+    assert.equal(seen.length, 1);
+    assert.equal(seen[0]!.width, chart.plotArea.width);
+    assert.equal(seen[0]!.height, chart.plotArea.height);
+    assert.equal(seen[0]!.candles.length, 20);
+    assert.ok(seen[0]!.priceScale.maxPrice > seen[0]!.priceScale.minPrice);
+    chart.destroy();
+  });
+
+  it('detaches a stacked pane primitive without touching the pane', () => {
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: candles(20), width: 640, height: 400 },
+    });
+    const pane = chart.addPane({ id: 'host' });
+    let count = 0;
+    const handle = pane.attachPrimitive({ draw: () => { count++; } });
+    assert.equal(count, 1);
+    handle.requestUpdate();
+    assert.equal(count, 2);
+    handle.detach();
+    assert.equal(count, 2);
+    handle.requestUpdate();
+    assert.equal(count, 2);
+    assert.equal(chart.paneAt(chart.plotArea.height + 1), 'host');
+    chart.destroy();
+  });
+});
diff --git a/packages/chart/test/footprint.test.ts b/packages/chart/test/footprint.test.ts
new file mode 100644
index 0000000..52e03ba
--- /dev/null
+++ b/packages/chart/test/footprint.test.ts
@@ -0,0 +1,385 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  DEFAULT_FOOTPRINT_LOD,
+  FOOTPRINT_SERIES_TYPE,
+  PriceScale,
+  TimeScale,
+  barDelta,
+  candleDelta,
+  candleDeltas,
+  createChart,
+  createCvdIndicator,
+  createDeltaIndicator,
+  createFootprintSeries,
+  cvdValues,
+  footprintBands,
+  footprintLod,
+  formatFootprintSize,
+  type Candle,
+  type FootprintBarLike,
+  type FootprintLevelLike,
+} from '../dist/index.js';
+import { DEFAULT_CONFIG, type SeriesConfig } from '../dist/config.js';
+import { MockContext2D, MockDocument } from '../dist/dom.js';
+import {
+  createDatafeedChart,
+  createTradeAggregation,
+  datafeedFootprintSource,
+  type DatafeedChartOptions,
+  type Trade,
+} from '../dist/datafeed/index.js';
+
+const MIN = 60_000;
+const T0 = 1_700_000_040_000; // a 1m boundary
+
+const candle = (tMs: number): Candle => ({ time: tMs / 1000, open: 100, high: 103, low: 99, close: 101, volume: 1 });
+const trade = (time: number, price: number, size: number, side: Trade['side'] = 'buy'): Trade => ({ time, price, size, side });
+
+/** A tape with one bar at T0: 2×1 at 100, 5×0 at 101, 0×3 at 102 (buy×sell). */
+function makeTape(): ReturnType<typeof createTradeAggregation> {
+  const tape = createTradeAggregation({ intervalMs: MIN });
+  tape.push(trade(T0 + 1_000, 101, 5));
+  tape.push(trade(T0 + 2_000, 100, 2));
+  tape.push(trade(T0 + 3_000, 100, 1, 'sell'));
+  tape.push(trade(T0 + 4_000, 102, 3, 'sell'));
+  return tape;
+}
+
+function makeScales(barSpacing: number, min: number, max: number, height = 300): { ts: TimeScale; ps: PriceScale } {
+  const ts = new TimeScale(barSpacing, 600);
+  const ps = new PriceScale();
+  ps.height = height;
+  ps.topMargin = 0;
+  ps.bottomMargin = 0;
+  ps.setRange(min, max);
+  return { ts, ps };
+}
+
+function cfg(partial: Partial<SeriesConfig> = {}): SeriesConfig {
+  return { ...DEFAULT_CONFIG.series, ...partial };
+}
+
+async function idle(): Promise<void> {
+  for (let i = 0; i < 5; i++) await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+describe('footprintBands', () => {
+  it('prices each level band by midpoints, extending edge levels half a step', () => {
+    const levels: FootprintLevelLike[] = [
+      { price: 100, buySize: 2, sellSize: 1 },
+      { price: 101, buySize: 5, sellSize: 0 },
+      { price: 103, buySize: 0, sellSize: 3 },
+    ];
+    assert.deepEqual(footprintBands(levels), [
+      { price: 100, low: 99.5, high: 100.5 },
+      { price: 101, low: 100.5, high: 102 },
+      { price: 103, low: 102, high: 104 },
+    ]);
+  });
+
+  it('falls back to a unit step for a single level and drops non-finite prices', () => {
+    assert.deepEqual(footprintBands([{ price: 50, buySize: 1, sellSize: 0 }]), [{ price: 50, low: 49.5, high: 50.5 }]);
+    assert.deepEqual(footprintBands([{ price: NaN, buySize: 1, sellSize: 0 }, { price: 50, buySize: 1, sellSize: 0 }]), [
+      { price: 50, low: 49.5, high: 50.5 },
+    ]);
+  });
+});
+
+describe('footprintLod', () => {
+  it('picks text only for bid-ask display with cells that fit the label', () => {
+    assert.equal(footprintLod(60, 14, 'bid-ask'), 'text');
+    assert.equal(footprintLod(60, 14, 'delta'), 'bars');
+    assert.equal(footprintLod(60, 14, 'profile'), 'bars');
+  });
+
+  it('collapses to bars below the text thresholds and to delta coloring below the bar threshold', () => {
+    assert.equal(footprintLod(DEFAULT_FOOTPRINT_LOD.textBarWidth - 1, 14, 'bid-ask'), 'bars');
+    assert.equal(footprintLod(60, DEFAULT_FOOTPRINT_LOD.textCellHeight - 1, 'bid-ask'), 'bars');
+    assert.equal(footprintLod(60, DEFAULT_FOOTPRINT_LOD.barCellHeight - 1, 'bid-ask'), 'delta');
+    assert.equal(footprintLod(60, DEFAULT_FOOTPRINT_LOD.barCellHeight - 1, 'delta'), 'delta');
+  });
+
+  it('honors threshold overrides', () => {
+    assert.equal(footprintLod(20, 14, 'bid-ask', { ...DEFAULT_FOOTPRINT_LOD, textBarWidth: 20 }), 'text');
+  });
+});
+
+describe('delta math', () => {
+  it('computes per-bar and per-candle deltas, counting bars without trades as 0', () => {
+    const tape = makeTape();
+    assert.equal(barDelta(tape.bar(T0)!), 3);
+    assert.equal(candleDelta(candle(T0), tape), 3);
+    assert.equal(candleDelta(candle(T0 + MIN), tape), 0);
+    assert.deepEqual(candleDeltas([candle(T0), candle(T0 + MIN), candle(T0 + 2 * MIN)], tape), [3, 0, 0]);
+  });
+});
+
+describe('formatFootprintSize', () => {
+  it('formats zero, fractional, unit, K, and M sizes', () => {
+    assert.equal(formatFootprintSize(0), '0');
+    assert.equal(formatFootprintSize(0.025), '0.0250');
+    assert.equal(formatFootprintSize(-0.025), '-0.0250');
+    assert.equal(formatFootprintSize(12.4), '12.40');
+    assert.equal(formatFootprintSize(1250), '1.25K');
+    assert.equal(formatFootprintSize(-2500), '-2.50K');
+    assert.equal(formatFootprintSize(3_400_000), '3.40M');
+    assert.equal(formatFootprintSize(-2_500_000), '-2.50M');
+  });
+});
+
+describe('createFootprintSeries', () => {
+  it('draws a sell × buy label per level when the cells fit the text', () => {
+    const tape = makeTape();
+    const draw = createFootprintSeries(tape);
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    const texts = ctx.callsNamed('fillText').map((c) => c[1]);
+    assert.deepEqual(texts, ['1.00×2.00', '0×5.00', '3.00×0']);
+    // A faint background rect per level on top of the labels.
+    assert.equal(ctx.countCalls('fillRect'), 3);
+  });
+
+  it('draws split bid×ask level bars when the text no longer fits', () => {
+    const tape = makeTape();
+    const draw = createFootprintSeries(tape);
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 159); // 5px rows: bars LOD
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 0);
+    // Level 101 has no sell side: 2 + 1 + 1 bars.
+    assert.equal(ctx.countCalls('fillRect'), 4);
+  });
+
+  it('collapses to one delta-colored column per bar when rows fall below the bar threshold', () => {
+    const tape = makeTape();
+    tape.push(trade(T0 + MIN + 500, 100, 4));
+    const draw = createFootprintSeries(tape);
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 399); // 1px rows: delta LOD
+    draw(ctx, [candle(T0), candle(T0 + MIN)], { from: 0, to: 2 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 0);
+    assert.equal(ctx.countCalls('fillRect'), 2);
+  });
+
+  it('draws per-level delta bars in delta display', () => {
+    const tape = makeTape();
+    const draw = createFootprintSeries(tape, { display: 'delta' });
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 0);
+    assert.equal(ctx.countCalls('fillRect'), 3);
+  });
+
+  it('skips candles without a footprint bar and no-ops on a null source', () => {
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    createFootprintSeries(makeTape())(ctx, [candle(T0 + MIN)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.calls.length, 0);
+    createFootprintSeries(() => null)(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.calls.length, 0);
+  });
+
+  it('resolves the source lazily, following a swapped store', () => {
+    let store: ReturnType<typeof createTradeAggregation> | null = null;
+    const draw = createFootprintSeries(() => store);
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 0);
+    store = makeTape();
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 3);
+  });
+
+  it('honors upColor, downColor, and textColor overrides', () => {
+    const tape = makeTape();
+    const draw = createFootprintSeries(tape, { upColor: '#up', downColor: '#dn', textColor: '#tx' });
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 3);
+    // The label color is the last fillStyle assigned before each fillText.
+    assert.equal(ctx.fillStyle, '#tx');
+  });
+
+  it('honors lodThresholds overrides', () => {
+    const tape = makeTape();
+    const draw = createFootprintSeries(tape, { lodThresholds: { textBarWidth: 100 } });
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103); // 60px bars fail the 100px text threshold
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 0);
+    assert.equal(ctx.countCalls('fillRect'), 4);
+  });
+
+  it('draws full-width volume bars in profile display', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(T0 + 1_000, 100, 1));
+    tape.push(trade(T0 + 2_000, 101, 10, 'sell'));
+    const draw = createFootprintSeries(tape, { display: 'profile' });
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 159); // 5px rows: bars LOD
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.countCalls('fillText'), 0);
+    assert.equal(ctx.countCalls('fillRect'), 2);
+  });
+
+  it('colors the collapsed delta column with downColor for a negative bar delta', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(T0 + 500, 100, 4, 'sell'));
+    const draw = createFootprintSeries(tape);
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 399, 300); // 1px rows: delta LOD
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg({ downColor: '#dn' }));
+    assert.equal(ctx.countCalls('fillRect'), 1);
+    assert.equal(ctx.fillStyle, '#dn');
+  });
+
+  it('draws nothing for a bar whose levels have no traded size', () => {
+    const empty: FootprintBarLike = { time: T0, levels: [{ price: 100, buySize: 0, sellSize: 0 }], buySize: 0, sellSize: 0 };
+    const draw = createFootprintSeries({ bar: () => empty }, { display: 'delta' });
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.calls.length, 0);
+  });
+
+  it('skips a footprint bar with no levels', () => {
+    const levelless: FootprintBarLike = { time: T0, levels: [], buySize: 0, sellSize: 0 };
+    const draw = createFootprintSeries({ bar: () => levelless });
+    const ctx = new MockContext2D();
+    const { ts, ps } = makeScales(60, 99, 103);
+    draw(ctx, [candle(T0)], { from: 0, to: 1 }, ts, ps, cfg());
+    assert.equal(ctx.calls.length, 0);
+  });
+});
+
+describe('footprint series on a chart', () => {
+  it('renders through Chart.registerSeries and the series.type config', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    const data = Array.from({ length: 5 }, (_, i) => candle(T0 + i * MIN));
+    for (let i = 0; i < 5; i++) {
+      tape.push(trade(T0 + i * MIN + 100, 101, 5));
+      tape.push(trade(T0 + i * MIN + 200, 100, 2, 'sell'));
+    }
+    const document = new MockDocument();
+    const chart = createChart({
+      document,
+      config: { wasm: false, data, width: 640, height: 400, series: { type: FOOTPRINT_SERIES_TYPE } },
+    });
+    chart.registerSeries(FOOTPRINT_SERIES_TYPE, createFootprintSeries(tape));
+    assert.ok(chart.seriesRenderers.has(FOOTPRINT_SERIES_TYPE));
+    chart.scale.zoom(20); // 120px bars: text LOD
+    const ctx = document.created[0]!.context;
+    assert.ok(ctx.countCalls('fillText') > 0);
+    chart.destroy();
+  });
+});
+
+describe('delta indicator', () => {
+  it('computes a direction-colored histogram from the footprint source', () => {
+    const tape = makeTape();
+    tape.push(trade(T0 + MIN + 500, 100, 4, 'sell'));
+    const def = createDeltaIndicator(tape);
+    assert.equal(def.name, 'delta');
+    assert.equal(def.defaultPane, 'sub');
+    const candles = [candle(T0), candle(T0 + MIN), candle(T0 + 2 * MIN)];
+    const out = def.compute(candles, {}, ['#0f0', '#f00'], null);
+    assert.equal(out.pane, 'sub');
+    assert.deepEqual(out.bars!.values, [3, -4, 0]);
+    assert.deepEqual(out.bars!.up, [true, false, true]);
+    assert.equal(out.bars!.upColor, '#0f0');
+    assert.equal(out.bars!.downColor, '#f00');
+  });
+
+  it('tail-updates from the first changed candle', () => {
+    const tape = makeTape();
+    const def = createDeltaIndicator(tape);
+    const candles = [candle(T0), candle(T0 + MIN)];
+    const out = def.compute(candles, {}, [], null);
+    tape.push(trade(T0 + MIN + 500, 100, 2));
+    const next = def.update!(out, candles, 1, {}, [], null)!;
+    assert.deepEqual(next.bars!.values, [3, 2]);
+  });
+
+  it('registers and renders as a sub-pane on a chart', () => {
+    const tape = makeTape();
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: [candle(T0), candle(T0 + MIN)], width: 640, height: 400 },
+    });
+    chart.indicators.register(createDeltaIndicator(tape));
+    const id = chart.addIndicator({ name: 'delta' });
+    assert.ok(chart.getIndicator(id) !== undefined);
+    // plotHeight 376, weights 3:1 → main 282, delta sub-pane below it.
+    assert.equal(chart.paneAt(300), id);
+    chart.destroy();
+  });
+});
+
+describe('cvd indicator', () => {
+  it('accumulates per-candle deltas', () => {
+    const tape = makeTape();
+    tape.push(trade(T0 + MIN + 500, 100, 4, 'sell'));
+    tape.push(trade(T0 + 2 * MIN + 500, 100, 1));
+    const candles = [candle(T0), candle(T0 + MIN), candle(T0 + 2 * MIN), candle(T0 + 3 * MIN)];
+    assert.deepEqual(cvdValues(candles, tape), [3, -1, 0, 0]);
+  });
+
+  it('computes a sub-pane line and continues the running total on tail updates', () => {
+    const tape = makeTape();
+    const def = createCvdIndicator(tape);
+    assert.equal(def.name, 'cvd');
+    assert.equal(def.defaultPane, 'sub');
+    const candles = [candle(T0), candle(T0 + MIN)];
+    const out = def.compute(candles, {}, [], null);
+    assert.deepEqual(out.lines[0]!.values, [3, 3]);
+    tape.push(trade(T0 + MIN + 500, 100, 2));
+    const next = def.update!(out, candles, 1, {}, [], null)!;
+    assert.deepEqual(next.lines[0]!.values, [3, 5]);
+  });
+
+  it('registers and renders as a sub-pane on a chart', () => {
+    const tape = makeTape();
+    const chart = createChart({
+      document: new MockDocument(),
+      config: { wasm: false, data: [candle(T0), candle(T0 + MIN)], width: 640, height: 400 },
+    });
+    chart.indicators.register(createCvdIndicator(tape));
+    const id = chart.addIndicator({ name: 'cvd' });
+    assert.equal(chart.paneAt(300), id);
+    chart.destroy();
+  });
+});
+
+describe('datafeedFootprintSource', () => {
+  function setupFeed(overrides: Partial<DatafeedChartOptions> = {}) {
+    const errors: unknown[] = [];
+    const df = createDatafeedChart({
+      container: new MockDocument().createCanvas(800, 400),
+      config: { wasm: false },
+      fetchBars: async ({ toMs }) => (toMs >= T0 - MIN ? [candle(T0 - MIN), candle(T0)] : []),
+      symbol: 'BTC',
+      intervalMs: MIN,
+      onError: (error) => errors.push(error),
+      ...overrides,
+    });
+    return { ...df, errors };
+  }
+
+  it('reads the current session’s tape and follows a symbol switch', async () => {
+    const { datafeed, destroy } = setupFeed();
+    await idle();
+    const source = datafeedFootprintSource(datafeed);
+    datafeed.pushTrade(trade(T0 + 500, 100, 2));
+    datafeed.pushTrade(trade(T0 + 600, 100, 1, 'sell'));
+    assert.equal(source.bar(T0)!.buySize, 2);
+    assert.equal(source.bar(T0)!.sellSize, 1);
+    await datafeed.setSymbol('ETH', MIN);
+    assert.equal(source.bar(T0), null);
+    destroy();
+  });
+});
diff --git a/packages/chart/test/heatmap-customization.test.ts b/packages/chart/test/heatmap-customization.test.ts
new file mode 100644
index 0000000..93ae8d7
--- /dev/null
+++ b/packages/chart/test/heatmap-customization.test.ts
@@ -0,0 +1,181 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { bloxwapDark, createChart, presetChartTheme, resolveConfig, DEFAULT_HEATMAP_MIN_OPACITY } from '../dist/index.js';
+import { MockContext2D, MockDocument } from '../dist/dom.js';
+import type { Candle } from '../dist/core/data.js';
+import type { DepthBook } from '../dist/core/depth.js';
+import type { PrimitiveDrawTarget } from '../dist/render/primitive.js';
+import { attachHeatmap, createHeatmapPrimitive, heatmapRamp, heatmapRampRGBA, HEATMAP_RAMP_STEPS } from '../dist/render/heatmap.js';
+import { PriceScale, TimeScale } from '../dist/core/scale.js';
+
+const LAST = HEATMAP_RAMP_STEPS - 1;
+const t = (i: number) => i / LAST;
+
+/** RGBA floats of step `i`. */
+function step(lut: Float32Array, i: number): number[] {
+  return Array.from(lut.subarray(i * 4, i * 4 + 4));
+}
+
+function close(actual: number[], expected: number[], message?: string): void {
+  actual.forEach((v, i) => assert.ok(Math.abs(v - expected[i]!) < 1e-6, `${message ?? ''} channel ${i}: ${v} vs ${expected[i]}`));
+}
+
+/** Records the fillStyle in force at each fillRect. */
+class StyleContext extends MockContext2D {
+  readonly fills: string[] = [];
+  override fillRect(x: number, y: number, w: number, h: number): void {
+    this.fills.push(String(this.fillStyle));
+    super.fillRect(x, y, w, h);
+  }
+}
+
+function candles(n: number): Candle[] {
+  return Array.from({ length: n }, (_, i) => ({ time: 1700000000 + i * 60, open: 100, high: 105, low: 95, close: 100, volume: 10 }));
+}
+
+function book(time: number): DepthBook {
+  return { bids: [[99, 1], [98, 2], [97, 4]], asks: [[100, 2], [101, 4], [102, 8]], time };
+}
+
+function target(data: Candle[]): PrimitiveDrawTarget {
+  const priceScale = new PriceScale();
+  priceScale.height = 400;
+  priceScale.setRange(90, 110);
+  return { width: 640, height: 400, priceScale, timeScale: new TimeScale(6, 640), range: { from: 0, to: data.length }, candles: data, pixelRatio: 1 };
+}
+
+describe('heatmap ramp shaping', () => {
+  it('keeps the two-color ramp unchanged without stops', () => {
+    const plain = heatmapRamp('#000000', '#ffffff', 0.5);
+    assert.deepEqual(heatmapRamp('#000000', '#ffffff', 0.5, {}), plain);
+    assert.deepEqual(heatmapRamp('#000000', '#ffffff', 0.5, { stops: [] }), plain);
+    assert.deepEqual(Array.from(heatmapRampRGBA('#000000', '#ffffff', 0.5, { stops: [] })), Array.from(heatmapRampRGBA('#000000', '#ffffff', 0.5)));
+  });
+
+  it('spreads bare stop colors evenly and replaces colorLow → colorHigh', () => {
+    const lut = heatmapRampRGBA('#123456', '#654321', 1, { stops: ['#000000', '#ff0000', '#ffffff'] });
+    close(step(lut, 0), [0, 0, 0, 0], 'first');
+    close(step(lut, LAST), [1, 1, 1, 1], 'last');
+    // Below the middle stop the ramp runs black → red; above it red → white.
+    close(step(lut, 20), [t(20) * 2, 0, 0, t(20)], 'lower half');
+    close(step(lut, 50), [1, (t(50) - 0.5) * 2, (t(50) - 0.5) * 2, t(50)], 'upper half');
+  });
+
+  it('pins stops with `at`, sorts them, and holds the end colors flat', () => {
+    const lut = heatmapRampRGBA('#000000', '#ffffff', 1, {
+      stops: [{ color: '#ffffff', at: 1 }, { color: '#ff0000', at: 0.5 }],
+    });
+    close(step(lut, 10), [1, 0, 0, t(10)], 'flat before the first stop');
+    close(step(lut, LAST), [1, 1, 1, 1], 'last');
+    const clamped = heatmapRampRGBA('#000000', '#ffffff', 1, { stops: [{ color: '#0000ff', at: -3 }, { color: '#00ff00', at: 9 }] });
+    close(step(clamped, 0), [0, 0, 1, 0], 'at clamps to 0');
+    close(step(clamped, LAST), [0, 1, 0, 1], 'at clamps to 1');
+    const early = heatmapRampRGBA('#000000', '#ffffff', 1, { stops: [{ color: '#000000', at: 0 }, { color: '#ff0000', at: 0.5 }] });
+    close(step(early, 50), [1, 0, 0, t(50)], 'flat after the last stop');
+  });
+
+  it('paints a single bare stop as one flat color', () => {
+    const lut = heatmapRampRGBA('#000000', '#ffffff', 1, { stops: ['#00ff00'] });
+    close(step(lut, 0), [0, 1, 0, 0]);
+    close(step(lut, LAST), [0, 1, 0, 1]);
+  });
+
+  it('spreads stops without a usable `at` by index', () => {
+    const lut = heatmapRampRGBA('#000000', '#ffffff', 1, {
+      stops: [{ color: '#000000' }, { color: '#ffffff', at: Number.NaN }],
+    });
+    close(step(lut, 21), [t(21), t(21), t(21), t(21)]);
+  });
+
+  it('scales the ramp alpha by each stop color’s own alpha', () => {
+    const lut = heatmapRampRGBA('#000000', '#ffffff', 0.8, { stops: ['rgba(255, 0, 0, 0)', 'rgba(255, 0, 0, 1)'] });
+    close(step(lut, 32), [1, 0, 0, 0.8 * t(32) * t(32)]);
+  });
+
+  it('lifts the zero-intensity alpha to minOpacity and clamps both alphas', () => {
+    const lut = heatmapRampRGBA('#000000', '#ffffff', 0.9, { minOpacity: 0.2 });
+    assert.ok(Math.abs(step(lut, 0)[3]! - 0.2) < 1e-6);
+    assert.ok(Math.abs(step(lut, LAST)[3]! - 0.9) < 1e-6);
+    close([step(lut, 21)[3]!], [0.2 + 0.7 * t(21)]);
+    const wild = heatmapRampRGBA('#000000', '#ffffff', 7, { minOpacity: -1 });
+    assert.equal(step(wild, 0)[3], 0);
+    assert.equal(step(wild, LAST)[3], 1);
+    assert.equal(DEFAULT_HEATMAP_MIN_OPACITY, 0);
+  });
+
+  it('skips unparseable stops, falls back to the two colors, and paints a lone stop flat', () => {
+    assert.deepEqual(heatmapRamp('#000000', '#ffffff', 1, { stops: ['nope', 'also-nope'] }), heatmapRamp('#000000', '#ffffff', 1));
+    const lone = heatmapRampRGBA('#000000', '#ffffff', 1, { stops: ['bad', '#00ff00'] });
+    close(step(lone, 0), [0, 1, 0, 0]);
+    close(step(lone, 40), [0, 1, 0, t(40)]);
+  });
+
+  it('turns Display-P3 when any stop is Display-P3', () => {
+    const ramp = heatmapRamp('#000000', '#ffffff', 1, { stops: ['#000000', 'color(display-p3 0 1 0)', '#ffffff'] });
+    assert.ok(ramp.every((c) => c.startsWith('color(display-p3')));
+  });
+});
+
+describe('heatmap customization through config and attach', () => {
+  const stops = ['#000000', '#ff0000'];
+
+  it('defaults to no stops and a transparent floor', () => {
+    const { heatmap } = resolveConfig();
+    assert.deepEqual(heatmap.stops, []);
+    assert.equal(heatmap.minOpacity, 0);
+  });
+
+  it('paints primitive cells from the custom ramp', () => {
+    const data = candles(10);
+    const ctx = new StyleContext();
+    createHeatmapPrimitive(() => book(data[0]!.time * 1000), { stops, minOpacity: 0.1, opacity: 1, gamma: 1 }).draw(ctx, target(data));
+    const ramp = heatmapRamp('#2962ff', '#ffd54f', 1, { stops, minOpacity: 0.1 });
+    assert.ok(ctx.fills.length > 0);
+    assert.ok(ctx.fills.every((fill) => ramp.includes(fill)), 'every cell uses a step of the custom ramp');
+    // The largest level (the 8-lot ask) reaches the top step.
+    assert.ok(ctx.fills.includes(ramp[LAST]!));
+  });
+
+  it('follows config stops while attached through the chart', () => {
+    const doc = new MockDocument();
+    const chart = createChart({ document: doc, config: { wasm: false, data: candles(50), width: 640, height: 400 } });
+    const ctx = new StyleContext();
+    const canvas = doc.created[0]!;
+    (canvas as unknown as { getContext: () => StyleContext }).getContext = () => ctx;
+    const api = attachHeatmap(chart);
+    const time = chart.getData().at(-1)!.time * 1000;
+    chart.updateConfig({ heatmap: { stops, gamma: 1, opacity: 1 } });
+    ctx.fills.length = 0;
+    chart.setDepth(book(time));
+    const ramp = heatmapRamp('#2962ff', '#ffd54f', 1, { stops });
+    assert.ok(ctx.fills.includes(ramp[LAST]!), 'the heaviest level paints the custom top color');
+    chart.updateConfig({ heatmap: { stops: [] } });
+    ctx.fills.length = 0;
+    chart.setDepth(book(time + 1000));
+    assert.ok(ctx.fills.includes(heatmapRamp('#2962ff', '#ffd54f', 1)[LAST]!), 'clearing stops restores the two-color ramp');
+    api.remove();
+    chart.destroy();
+  });
+});
+
+describe('bloxwapDark heatmap palette', () => {
+  it('ships brand stops without enabling the heatmap', () => {
+    assert.deepEqual(bloxwapDark.heatmap?.stops, [
+      { color: '#404040', at: 0 },
+      { color: '#737373', at: 0.4 },
+      { color: '#ffc83d', at: 0.85 },
+      { color: '#fffb38', at: 1 },
+    ]);
+    assert.equal(bloxwapDark.heatmap?.gamma, 1);
+    const chart = createChart({ document: new MockDocument(), preset: 'bloxwapDark', config: { wasm: false } });
+    assert.equal(chart.getConfig().heatmap.enabled, false);
+    assert.equal(chart.getConfig().heatmap.stops.length, 4);
+    chart.destroy();
+  });
+
+  it('keeps the palette on the preset theme and resets it on the other theme', () => {
+    const chartTheme = presetChartTheme('bloxwapDark');
+    assert.deepEqual(chartTheme('dark').heatmap, { stops: bloxwapDark.heatmap!.stops });
+    assert.deepEqual(chartTheme('light').heatmap, { stops: [] });
+  });
+});
diff --git a/packages/chart/test/heatmap.test.ts b/packages/chart/test/heatmap.test.ts
new file mode 100644
index 0000000..fd4e890
--- /dev/null
+++ b/packages/chart/test/heatmap.test.ts
@@ -0,0 +1,447 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createChart } from '../dist/index.js';
+import { MockContext2D, MockDocument } from '../dist/dom.js';
+import type { Candle } from '../dist/core/data.js';
+import type { DepthBook, DepthLevel } from '../dist/core/depth.js';
+import type { PrimitiveDrawTarget } from '../dist/render/primitive.js';
+import {
+  DepthHistory,
+  heatmapIntensity,
+  heatPosition,
+  DEFAULT_HEATMAP_BUCKET_MS,
+  DEFAULT_HEATMAP_MAX_BUCKETS,
+  DEFAULT_HEATMAP_MAX_LEVELS,
+} from '../dist/core/heatmap.js';
+import { resolveConfig } from '../dist/config.js';
+import {
+  attachHeatmap,
+  createHeatmapPrimitive,
+  heatmapRamp,
+  HEATMAP_RAMP_STEPS,
+} from '../dist/render/heatmap.js';
+import { PriceScale, TimeScale } from '../dist/core/scale.js';
+
+function book(time: number, overrides: Partial<DepthBook> = {}): DepthBook {
+  return {
+    bids: [[99, 1], [98, 2], [97, 4]],
+    asks: [[100, 2], [101, 4], [102, 8]],
+    time,
+    ...overrides,
+  };
+}
+
+describe('DepthHistory', () => {
+  it('buckets books by wall clock and keeps the newest book of a bucket', () => {
+    const history = new DepthHistory({ bucketMs: 1000 });
+    assert.ok(history.record(book(1000)));
+    assert.ok(history.record(book(1400, { bids: [[99, 9]] })));
+    assert.equal(history.length, 1);
+    assert.deepEqual(history.at(0)!.time, 1000);
+    assert.deepEqual(history.at(0)!.bids, [[99, 9]]);
+    assert.ok(history.record(book(2000)));
+    assert.equal(history.length, 2);
+  });
+
+  it('ignores repeat deliveries of one book and out-of-order books', () => {
+    const history = new DepthHistory({ bucketMs: 1000 });
+    assert.ok(history.record(book(2000)));
+    assert.equal(history.record(book(2000, { bids: [[99, 9]] })), false);
+    assert.equal(history.record(book(1500)), false);
+    assert.equal(history.length, 1);
+    assert.equal(history.record(null), false);
+  });
+
+  it('evicts the oldest bucket past maxBuckets', () => {
+    const history = new DepthHistory({ bucketMs: 1000, maxBuckets: 3 });
+    for (let t = 1000; t <= 5000; t += 1000) history.record(book(t));
+    assert.equal(history.length, 3);
+    assert.deepEqual([0, 1, 2].map((i) => history.at(i)!.time), [3000, 4000, 5000]);
+  });
+
+  it('trims levels to maxLevels and drops invalid ones, copying the arrays', () => {
+    const bids: DepthLevel[] = [[99, 1], [98, 0], [NaN, 2], [97, 3], [96, 4]];
+    const history = new DepthHistory({ bucketMs: 1000, maxLevels: 2 });
+    history.record(book(1000, { bids }));
+    assert.deepEqual(history.at(0)!.bids, [[99, 1], [97, 3]]);
+    bids.push([95, 5]);
+    assert.equal(history.at(0)!.bids.length, 2);
+  });
+
+  it('finds the first bucket at or after a time', () => {
+    const history = new DepthHistory({ bucketMs: 1000 });
+    for (let t = 1000; t <= 5000; t += 1000) history.record(book(t));
+    assert.equal(history.firstAtOrAfter(0), 0);
+    assert.equal(history.firstAtOrAfter(2500), 2);
+    assert.equal(history.firstAtOrAfter(3000), 2);
+    assert.equal(history.firstAtOrAfter(9000), 5);
+  });
+
+  it('re-grids future records and evicts on configure', () => {
+    const history = new DepthHistory({ bucketMs: 1000, maxBuckets: 4 });
+    for (let t = 1000; t <= 4000; t += 1000) history.record(book(t));
+    history.configure({ maxBuckets: 2 });
+    assert.equal(history.length, 2);
+    history.configure({ bucketMs: 500 });
+    assert.ok(history.record(book(4300)));
+    assert.equal(history.at(history.length - 1)!.time, 4000);
+    assert.equal(history.bucketStart(4300), 4000);
+  });
+
+  it('ignores a newer book that a coarser grid would bucket before the last bucket', () => {
+    const history = new DepthHistory({ bucketMs: 500 });
+    assert.ok(history.record(book(1700))); // bucket 1500
+    history.configure({ bucketMs: 1000 });
+    assert.equal(history.record(book(1800)), false); // bucket 1000 < 1500
+    assert.equal(history.length, 1);
+    assert.equal(history.at(0)!.time, 1500);
+  });
+
+  it('clears the window', () => {
+    const history = new DepthHistory();
+    history.record(book(1000));
+    history.clear();
+    assert.equal(history.length, 0);
+    assert.ok(history.record(book(500))); // lastBookTime resets too
+  });
+});
+
+describe('heatmapIntensity', () => {
+  it('is the size over the max, curved by gamma and clamped to 1', () => {
+    assert.equal(heatmapIntensity(5, 10, 1), 0.5);
+    assert.equal(heatmapIntensity(10, 10, 0.5), 1);
+    assert.ok(Math.abs(heatmapIntensity(5, 10, 0.5) - Math.sqrt(0.5)) < 1e-12);
+    assert.equal(heatmapIntensity(20, 10, 1), 1);
+  });
+
+  it('is zero without a positive size or normalizer', () => {
+    assert.equal(heatmapIntensity(0, 10, 1), 0);
+    assert.equal(heatmapIntensity(5, 0, 1), 0);
+    assert.equal(heatmapIntensity(5, NaN, 1), 0);
+  });
+});
+
+describe('heatPosition', () => {
+  const data: Candle[] = [100, 160, 220].map((time) => ({ time, open: 1, high: 1, low: 1, close: 1, volume: 1 }));
+
+  it('interpolates linearly in candle time between neighbors', () => {
+    assert.equal(heatPosition(data, null, 100_000), 0);
+    assert.equal(heatPosition(data, null, 130_000), 0.5);
+    assert.equal(heatPosition(data, null, 220_000), 2);
+  });
+
+  it('extrapolates past the last candle along the last interval and is null before the first', () => {
+    assert.equal(heatPosition(data, null, 280_000), 3);
+    assert.equal(heatPosition(data, null, 99_000), null);
+    assert.equal(heatPosition([], null, 100_000), null);
+  });
+
+  it('maps to slots on a continuous axis, so a gap spans its full slot count', () => {
+    const slots = [0, 1, 4]; // one bar, then a three-slot gap
+    assert.equal(heatPosition(data, slots, 190_000), 2.5);
+    assert.equal(heatPosition(data, slots, 100_000), 0);
+    assert.equal(heatPosition(data, slots, 280_000), 5); // one slot per interval past the data
+  });
+
+  it('does not extrapolate past a lone candle, which has no interval', () => {
+    assert.equal(heatPosition(data.slice(0, 1), null, 190_000), 0);
+  });
+
+  it('pins to the left candle when its neighbor has no usable time', () => {
+    const ragged = [data[0]!, { ...data[1]!, time: NaN }, data[2]!];
+    assert.equal(heatPosition(ragged, null, 150_000), 0);
+  });
+});
+
+describe('heatmapRamp', () => {
+  it('ramps alpha 0 → opacity over the color lerp', () => {
+    const ramp = heatmapRamp('#000000', '#ffffff', 0.5);
+    assert.equal(ramp.length, HEATMAP_RAMP_STEPS);
+    assert.equal(ramp[0], 'rgba(0, 0, 0, 0)');
+    assert.equal(ramp[HEATMAP_RAMP_STEPS - 1], 'rgba(255, 255, 255, 0.5)');
+  });
+
+  it('falls back to the defaults for unparseable colors', () => {
+    const ramp = heatmapRamp('nope', '#ffffff', 1);
+    assert.equal(ramp[0], 'rgba(41, 98, 255, 0)');
+    const high = heatmapRamp('#000000', 'nope', 1);
+    assert.equal(high[HEATMAP_RAMP_STEPS - 1], 'rgb(255, 213, 79)');
+  });
+
+  it('turns Display-P3 when either endpoint is Display-P3', () => {
+    const ramp = heatmapRamp('#000000', 'color(display-p3 1 1 1)', 1);
+    assert.ok(ramp.every((step) => step.startsWith('color(display-p3')));
+    assert.equal(ramp[HEATMAP_RAMP_STEPS - 1], heatmapRamp('color(display-p3 0 0 0)', 'color(display-p3 1 1 1)', 1)[HEATMAP_RAMP_STEPS - 1]);
+  });
+});
+
+function candles(n: number, start = 1700000000, step = 60): Candle[] {
+  return Array.from({ length: n }, (_, i) => ({
+    time: start + i * step,
+    open: 100,
+    high: 105,
+    low: 95,
+    close: 100,
+    volume: 10,
+  }));
+}
+
+function fakeTarget(data: Candle[], width = 640, height = 400, min = 90, max = 110): PrimitiveDrawTarget {
+  const priceScale = new PriceScale();
+  priceScale.height = height;
+  priceScale.setRange(min, max);
+  const timeScale = new TimeScale(6, width);
+  return {
+    width,
+    height,
+    priceScale,
+    timeScale,
+    range: { from: 0, to: data.length },
+    candles: data,
+    pixelRatio: 1,
+  };
+}
+
+describe('createHeatmapPrimitive', () => {
+  it('records the book into time buckets on draw and paints cells behind the series', () => {
+    const data = candles(10);
+    const current = book(data[0]!.time * 1000);
+    const ctx = new MockContext2D();
+    const primitive = createHeatmapPrimitive(() => current);
+    assert.equal(primitive.zOrder, 'behind');
+    primitive.draw(ctx, fakeTarget(data));
+    assert.equal(primitive.history.length, 1);
+    assert.equal(primitive.visibleMax, 8);
+    const fills = ctx.callsNamed('fillRect');
+    assert.ok(fills.length > 0);
+    // The one bucket sits at bar 0: x = 640 - (10 - 1 - 0) * 6 - 3 = 583.
+    assert.ok(fills.every((c) => c[1] === 583));
+    assert.ok(fills.every((c) => (c[2] as number) >= 0 && (c[2] as number) < 400));
+  });
+
+  it('paints one column per bucket at bar-indexed x positions', () => {
+    const data = candles(10);
+    const t0 = data[0]!.time * 1000;
+    let current = book(t0);
+    const primitive = createHeatmapPrimitive(() => current);
+    const ctx = new MockContext2D();
+    primitive.draw(ctx, fakeTarget(data));
+    current = book(t0 + 60_000); // bar 1's bucket
+    primitive.draw(ctx, fakeTarget(data));
+    assert.equal(primitive.history.length, 2);
+    const xs = new Set(ctx.callsNamed('fillRect').map((c) => c[1]));
+    assert.ok(xs.has(583));
+    assert.ok(xs.has(589)); // 583 + 6px of bar spacing
+  });
+
+  it('dedupes repeat renders of one book and replaces within a bucket', () => {
+    const data = candles(10);
+    const t0 = data[0]!.time * 1000;
+    let current = book(t0);
+    const primitive = createHeatmapPrimitive(() => current);
+    primitive.draw(new MockContext2D(), fakeTarget(data));
+    primitive.draw(new MockContext2D(), fakeTarget(data));
+    assert.equal(primitive.history.length, 1);
+    current = book(t0 + 100, { bids: [[99, 9]] });
+    primitive.draw(new MockContext2D(), fakeTarget(data));
+    assert.equal(primitive.history.length, 1);
+    assert.equal(primitive.visibleMax, 9);
+  });
+
+  it('draws nothing without a book or outside the visible price range', () => {
+    const data = candles(10);
+    const t0 = data[0]!.time * 1000;
+    const empty = createHeatmapPrimitive(() => null);
+    const ctx = new MockContext2D();
+    empty.draw(ctx, fakeTarget(data));
+    assert.equal(ctx.countCalls('fillRect'), 0);
+    assert.equal(empty.visibleMax, 0);
+    const far = createHeatmapPrimitive(() => book(t0, { bids: [[50, 5]], asks: [[150, 5]] }));
+    const ctx2 = new MockContext2D();
+    far.draw(ctx2, fakeTarget(data));
+    assert.equal(ctx2.countCalls('fillRect'), 0);
+    assert.equal(far.visibleMax, 0);
+  });
+
+  it('aggregates sub-pixel buckets per pixel column instead of overpainting', () => {
+    const data = candles(10);
+    const t0 = data[0]!.time * 1000;
+    let current = book(t0);
+    // 100ms buckets: 60 of them share bar 0's 6px column span.
+    const primitive = createHeatmapPrimitive(() => current, { bucketMs: 100 });
+    const target = fakeTarget(data);
+    primitive.draw(new MockContext2D(), target);
+    for (let t = 100; t < 1000; t += 100) {
+      current = book(t0 + t);
+      primitive.draw(new MockContext2D(), target);
+    }
+    assert.equal(primitive.history.length, 10);
+    const ctx = new MockContext2D();
+    primitive.draw(ctx, target);
+    const xs = new Set(ctx.callsNamed('fillRect').map((c) => c[1]));
+    assert.ok(xs.size <= 6, `expected ≤6 pixel columns, got ${xs.size}`);
+  });
+
+  it('respects a caller-supplied history', () => {
+    const data = candles(10);
+    const history = new DepthHistory({ bucketMs: 1000, maxBuckets: 2 });
+    const t0 = data[0]!.time * 1000;
+    let current = book(t0);
+    const primitive = createHeatmapPrimitive(() => current, { history });
+    primitive.draw(new MockContext2D(), fakeTarget(data));
+    current = book(t0 + 1000);
+    primitive.draw(new MockContext2D(), fakeTarget(data));
+    current = book(t0 + 2000);
+    primitive.draw(new MockContext2D(), fakeTarget(data));
+    assert.equal(history.length, 2);
+    assert.equal(history.at(0)!.time, t0 + 1000);
+  });
+
+  it('places buckets by slot on a continuous axis, and by bar index when the slots do not fit the data', () => {
+    const data = candles(10);
+    const current = book(data[0]!.time * 1000);
+    const continuous = fakeTarget(data);
+    continuous.timeScale.setSlots(data.map((_, i) => i * 2));
+    const ctx = new MockContext2D();
+    createHeatmapPrimitive(() => current).draw(ctx, continuous);
+    // Bar 0 at slot 0 of 18: x = 640 - (18 - 0) * 6 - 3 = 529.
+    assert.ok(ctx.callsNamed('fillRect').every((c) => c[1] === 529));
+    const stale = fakeTarget(data);
+    stale.timeScale.setSlots([0, 2, 4]);
+    const ctx2 = new MockContext2D();
+    createHeatmapPrimitive(() => current).draw(ctx2, stale);
+    assert.ok(ctx2.callsNamed('fillRect').every((c) => c[1] === 583));
+  });
+
+  it('skips buckets before the first candle and stops at the first one past the right edge', () => {
+    const data = candles(10);
+    const t0 = data[0]!.time * 1000;
+    const history = new DepthHistory({ bucketMs: 1000 });
+    history.record(book(t0 - 500)); // left of the data: no position
+    history.record(book(t0));
+    history.record(book(t0 + 20 * 60_000)); // bar 20: x = 640 + 11 * 6 - 3, off the right edge
+    const primitive = createHeatmapPrimitive(() => null, { history });
+    const ctx = new MockContext2D();
+    primitive.draw(ctx, fakeTarget(data));
+    const fills = ctx.callsNamed('fillRect');
+    assert.ok(fills.length > 0);
+    assert.ok(fills.every((c) => c[1] === 583), 'only the bar-0 bucket paints');
+  });
+
+  it('uses the bar spacing as the column width for a lone candle', () => {
+    const data = candles(1);
+    const ctx = new MockContext2D();
+    createHeatmapPrimitive(() => book(data[0]!.time * 1000)).draw(ctx, fakeTarget(data));
+    const fills = ctx.callsNamed('fillRect');
+    assert.ok(fills.length > 0);
+    // x = 640 - 0 - 3 = 637, flushed with the 6px bar spacing.
+    assert.ok(fills.every((c) => c[1] === 637 && c[3] === 6));
+  });
+
+  it('leaves levels too small to reach the first ramp step unpainted', () => {
+    const data = candles(10);
+    const ctx = new MockContext2D();
+    const primitive = createHeatmapPrimitive(() => book(data[0]!.time * 1000, { bids: [[99, 1e-6]], asks: [[100, 8]] }));
+    primitive.draw(ctx, fakeTarget(data));
+    const bidY = fakeTarget(data).priceScale.priceToY(99);
+    const fills = ctx.callsNamed('fillRect');
+    assert.ok(fills.length > 0);
+    assert.ok(fills.every((c) => !((c[2] as number) <= bidY && bidY < (c[2] as number) + (c[4] as number))), 'the bid band stays empty');
+  });
+
+  it('paints a zero-height band as one pixel row', () => {
+    const data = candles(10);
+    const flat = { ...fakeTarget(data), priceScale: { priceToY: () => 200 } as unknown as PriceScale };
+    const ctx = new MockContext2D();
+    createHeatmapPrimitive(() => book(data[0]!.time * 1000)).draw(ctx, flat);
+    const fills = ctx.callsNamed('fillRect');
+    assert.equal(fills.length, 1);
+    assert.deepEqual(fills[0]!.slice(1), [583, 200, 1, 1]);
+  });
+});
+
+describe('attachHeatmap', () => {
+  function chartWith(config: Record<string, unknown> = {}) {
+    const doc = new MockDocument();
+    const chart = createChart({ document: doc, config: { wasm: false, data: candles(50), width: 640, height: 400, ...config } });
+    return { doc, chart };
+  }
+
+  function liveBook(chart: ReturnType<typeof createChart>): DepthBook {
+    const last = chart.getData().at(-1)!;
+    return book(last.time * 1000);
+  }
+
+  it('attaches a behind primitive painting depth history on setDepth', () => {
+    const { doc, chart } = chartWith();
+    const api = attachHeatmap(chart);
+    assert.equal(api.primitive.zOrder, 'behind');
+    const ctx = doc.created[0]!.context;
+    const before = ctx.countCalls('fillRect');
+    chart.setDepth(liveBook(chart));
+    assert.ok(ctx.countCalls('fillRect') > before);
+    assert.equal(api.history.length, 1);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('follows config heatmap writes while attached', () => {
+    const { chart } = chartWith();
+    const api = attachHeatmap(chart);
+    chart.setDepth(liveBook(chart));
+    assert.equal(api.history.length, 1);
+    assert.doesNotThrow(() => chart.updateConfig({ heatmap: { opacity: 0.3, gamma: 1, colorHigh: '#ff0000' } }));
+    chart.updateConfig({ heatmap: { maxBuckets: 1 } });
+    assert.equal(api.history.maxBuckets, 1);
+    api.update({ bucketMs: 60_000 });
+    assert.equal(api.history.bucketMs, 60_000);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('attaches and removes with the config heatmap.enabled flag', () => {
+    const { doc, chart } = chartWith({ heatmap: { enabled: true } });
+    const ctx = doc.created[0]!.context;
+    chart.setDepth(liveBook(chart));
+    const drawn = ctx.countCalls('fillRect');
+    assert.ok(drawn > 0);
+    // While disabled a setDepth render adds only the candle redraw, no cells.
+    chart.updateConfig({ heatmap: { enabled: false } });
+    let base = ctx.countCalls('fillRect');
+    chart.setDepth({ ...liveBook(chart), time: liveBook(chart).time + 1000 });
+    const disabledDelta = ctx.countCalls('fillRect') - base;
+    chart.updateConfig({ heatmap: { enabled: true } });
+    base = ctx.countCalls('fillRect');
+    chart.setDepth({ ...liveBook(chart), time: liveBook(chart).time + 2000 });
+    const enabledDelta = ctx.countCalls('fillRect') - base;
+    assert.ok(enabledDelta > disabledDelta);
+    chart.destroy();
+  });
+
+  it('re-enabling starts a fresh history', () => {
+    const { chart } = chartWith({ heatmap: { enabled: true } });
+    chart.setDepth(liveBook(chart));
+    chart.updateConfig({ heatmap: { enabled: false } });
+    chart.updateConfig({ heatmap: { enabled: true } });
+    chart.setDepth({ ...liveBook(chart), time: liveBook(chart).time + 1000 });
+    chart.destroy();
+  });
+
+  it('destroys cleanly', () => {
+    const { chart } = chartWith({ heatmap: { enabled: true } });
+    chart.setDepth(liveBook(chart));
+    assert.doesNotThrow(() => chart.destroy());
+  });
+});
+
+describe('heatmap config', () => {
+  it('defaults to disabled with the documented grid and ramp knobs', () => {
+    const heatmap = resolveConfig().heatmap;
+    assert.equal(heatmap.enabled, false);
+    assert.equal(heatmap.bucketMs, DEFAULT_HEATMAP_BUCKET_MS);
+    assert.equal(heatmap.maxBuckets, DEFAULT_HEATMAP_MAX_BUCKETS);
+    assert.equal(heatmap.maxLevels, DEFAULT_HEATMAP_MAX_LEVELS);
+    assert.ok(heatmap.opacity > 0 && heatmap.opacity <= 1);
+    assert.ok(heatmap.gamma > 0);
+  });
+});
diff --git a/packages/chart/test/inline-book.test.ts b/packages/chart/test/inline-book.test.ts
new file mode 100644
index 0000000..6200c73
--- /dev/null
+++ b/packages/chart/test/inline-book.test.ts
@@ -0,0 +1,537 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createChart, resolveConfig } from '../dist/index.js';
+import { MockContext2D, MockDocument } from '../dist/dom.js';
+import type { Candle } from '../dist/core/data.js';
+import type { DepthBook } from '../dist/core/depth.js';
+import type { PrimitiveDrawTarget } from '../dist/render/primitive.js';
+import {
+  computeInlineBookRows,
+  inlineBookRowAt,
+  DEFAULT_INLINE_BOOK_MAX_LEVELS,
+  DEFAULT_INLINE_BOOK_WIDTH,
+} from '../dist/core/inline-book.js';
+import {
+  attachInlineBook,
+  createInlineBookPrimitive,
+  formatBookSize,
+} from '../dist/render/inline-book.js';
+import { PriceScale, TimeScale } from '../dist/core/scale.js';
+
+function book(overrides: Partial<DepthBook> = {}): DepthBook {
+  return {
+    bids: [[99, 1], [98, 2], [97, 4]],
+    asks: [[100, 2], [101, 4], [102, 8]],
+    time: 1,
+    ...overrides,
+  };
+}
+
+describe('computeInlineBookRows', () => {
+  it('trims to maxLevels per side, best first, with cumulative depth from the best', () => {
+    const rows = computeInlineBookRows(book(), 2);
+    assert.equal(rows.bids.rows.length, 2);
+    assert.equal(rows.asks.rows.length, 2);
+    assert.deepEqual(rows.bids.rows.map((r) => r.price), [99, 98]);
+    assert.deepEqual(rows.asks.rows.map((r) => r.price), [100, 101]);
+    assert.deepEqual(rows.asks.rows.map((r) => r.cumulative), [2, 6]);
+    assert.equal(rows.asks.maxSize, 4);
+    assert.equal(rows.asks.maxCumulative, 6);
+  });
+
+  it('prices row bands at the midpoints between neighbors', () => {
+    const rows = computeInlineBookRows(book(), 16);
+    // Ask rows: [99.5, 100.5], [100.5, 101.5], [101.5, 102.5] — contiguous.
+    assert.deepEqual(rows.asks.rows.map((r) => [r.low, r.high]), [
+      [99.5, 100.5],
+      [100.5, 101.5],
+      [101.5, 102.5],
+    ]);
+    // Bid rows mirror: [98.5, 99.5], [97.5, 98.5], [96.5, 97.5].
+    assert.deepEqual(rows.bids.rows.map((r) => [r.low, r.high]), [
+      [98.5, 99.5],
+      [97.5, 98.5],
+      [96.5, 97.5],
+    ]);
+  });
+
+  it('widens the rows beside a price gap instead of leaving dead space', () => {
+    const rows = computeInlineBookRows(book({ asks: [[100, 1], [104, 2]] }), 16);
+    assert.deepEqual(rows.asks.rows.map((r) => [r.low, r.high]), [
+      [98, 102],
+      [102, 106],
+    ]);
+  });
+
+  it('reports best bid/ask and the spread', () => {
+    const rows = computeInlineBookRows(book(), 16);
+    assert.equal(rows.bestBid, 99);
+    assert.equal(rows.bestAsk, 100);
+    assert.equal(rows.spread, 1);
+    assert.equal(computeInlineBookRows(book({ asks: [] }), 16).spread, null);
+  });
+
+  it('drops invalid levels and clamps maxLevels to a positive integer', () => {
+    const rows = computeInlineBookRows(book({ bids: [[99, 1], [98, 0], [NaN, 2], [97, -1]] }), 0);
+    assert.deepEqual(rows.bids.rows.map((r) => r.price), [99]);
+    // A single-level side still gets a band (the fallback step from the other side).
+    assert.ok(rows.bids.rows[0]!.high > rows.bids.rows[0]!.low);
+  });
+});
+
+describe('inlineBookRowAt', () => {
+  it('finds the row whose band contains the price', () => {
+    const rows = computeInlineBookRows(book(), 16);
+    assert.equal(inlineBookRowAt(rows.asks, 100.4)!.price, 100);
+    assert.equal(inlineBookRowAt(rows.asks, 100.6)!.price, 101);
+    assert.equal(inlineBookRowAt(rows.bids, 97)!.price, 97);
+    assert.equal(inlineBookRowAt(rows.asks, 500), null);
+    assert.equal(inlineBookRowAt(rows.bids, 100), null);
+  });
+});
+
+describe('formatBookSize', () => {
+  it('formats compact sizes', () => {
+    assert.equal(formatBookSize(0.025), '0.0250');
+    assert.equal(formatBookSize(12.4), '12.40');
+    assert.equal(formatBookSize(1234), '1.23K');
+    assert.equal(formatBookSize(2_500_000), '2.50M');
+  });
+});
+
+function candles(n: number, start = 1700000000, step = 60): Candle[] {
+  return Array.from({ length: n }, (_, i) => ({
+    time: start + i * step,
+    open: 100,
+    high: 105,
+    low: 95,
+    close: 100,
+    volume: 10,
+  }));
+}
+
+function fakeTarget(width = 96, height = 400, min = 90, max = 110): PrimitiveDrawTarget {
+  const priceScale = new PriceScale();
+  priceScale.height = height;
+  priceScale.setRange(min, max);
+  const data = candles(10);
+  return {
+    width,
+    height,
+    priceScale,
+    timeScale: new TimeScale(),
+    range: { from: 0, to: data.length },
+    candles: data,
+    pixelRatio: 1,
+  };
+}
+
+describe('createInlineBookPrimitive', () => {
+  it('paints per-level bars with depth-proportional width anchored to the inner edge', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { showSpread: false, showLabels: false, cumulative: false });
+    primitive.draw(ctx, fakeTarget());
+    const bars = ctx.callsNamed('fillRect');
+    // 3 bids + 3 asks; the size-8 ask is the max, so it spans the full width.
+    assert.equal(bars.length, 6);
+    assert.ok(bars.some((c) => c[1] === 0 && c[3] === 96));
+    // The size-4 levels span half the width, anchored at the right edge.
+    assert.equal(bars.filter((c) => c[1] === 48 && c[3] === 48).length, 2);
+    assert.equal(primitive.rows!.spread, 1);
+  });
+
+  it('mirrors bids left and asks right of a central label spine', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { layout: 'mirrored', showSpread: false, cumulative: false });
+    // 130px band: a 34px spine leaves 48px per side.
+    primitive.draw(ctx, fakeTarget(130));
+    const bars = ctx.callsNamed('fillRect');
+    assert.equal(bars.length, 6);
+    // The size-8 ask spans its whole side from the spine's right edge; the size-4 bid grows left from the spine.
+    assert.ok(bars.some((c) => c[1] === 82 && c[3] === 48));
+    assert.ok(bars.some((c) => c[1] === 24 && c[3] === 24));
+    for (const c of bars) assert.ok((c[1] as number) + (c[3] as number) <= 48 || (c[1] as number) >= 82, 'no bar enters the spine');
+    const labels = ctx.callsNamed('fillText');
+    assert.ok(labels.length > 0 && labels.every((c) => c[2] === 65), 'size labels sit on the spine');
+  });
+
+  it('takes theme colors, colors each size like its side, right-aligns sizes and bolds the best levels', () => {
+    const styles: string[] = [];
+    const ctx = new (class extends MockContext2D {
+      override fillText(text: string, x: number, y: number): void {
+        styles.push(`${String(this.fillStyle)}|${this.textAlign}|${this.font}`);
+        super.fillText(text, x, y);
+      }
+    })();
+    const defaults = resolveConfig();
+    createInlineBookPrimitive(() => book(), { cumulative: false }).draw(ctx, fakeTarget(96, 400, 96, 104));
+    const mono = defaults.theme.monoFamily;
+    const sizes = ctx.callsNamed('fillText').filter((c) => !String(c[1]).startsWith('Δ'));
+    assert.ok(sizes.length > 0 && sizes.every((c) => c[2] === 92), 'sizes sit against the price-axis edge');
+    assert.ok(styles.includes(`${defaults.series.downColor}|right|bold 11px ${mono}`), 'the best ask is bold, in the ask (down) color');
+    assert.ok(styles.includes(`${defaults.series.upColor}|right|bold 11px ${mono}`), 'the best bid is bold, in the bid (up) color');
+    assert.ok(styles.includes(`${defaults.series.upColor}|right|500 11px ${mono}`), 'deeper bids are medium weight');
+    assert.ok(styles.some((st) => st.startsWith(`${defaults.theme.textColor}|right|`)), 'the spread label follows the theme text color');
+
+    const plain: string[] = [];
+    const ctx2 = new (class extends MockContext2D {
+      override fillText(text: string, x: number, y: number): void {
+        plain.push(String(this.fillStyle));
+        super.fillText(text, x, y);
+      }
+    })();
+    createInlineBookPrimitive(() => book(), { labelColor: '#123456', bidColor: '#00ff00', showSpread: false }).draw(ctx2, fakeTarget(96, 400, 96, 104));
+    assert.ok(plain.length > 0 && plain.every((c) => c === '#123456'), 'a fixed label color applies to both sides');
+  });
+
+  it('shades cumulative depth behind the bars when enabled', () => {
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(() => book(), { showSpread: false, showLabels: false }).draw(ctx, fakeTarget());
+    // 6 level bars + 6 cumulative shades; the deepest ask row is fully cumulative-covered.
+    assert.equal(ctx.countCalls('fillRect'), 12);
+  });
+
+  it('highlights the spread row with a band and a label', () => {
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(() => book(), { showLabels: false, cumulative: false }).draw(ctx, fakeTarget());
+    const texts = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(texts.some((t) => t.startsWith('Δ ')));
+  });
+
+  it('labels the true spread when given one, falling back to the level gap on a bad value', () => {
+    const label = (spread?: () => number | null): number => {
+      const ctx = new MockContext2D();
+      createInlineBookPrimitive(() => book(), { showLabels: false, cumulative: false, ...(spread ? { spread } : {}) }).draw(ctx, fakeTarget());
+      return Number(ctx.callsNamed('fillText').map((c) => String(c[1])).find((t) => t.startsWith('Δ '))!.slice(2));
+    };
+    assert.equal(label(), 1, 'the gap between the best levels');
+    assert.equal(label(() => 0.5), 0.5);
+    assert.equal(label(() => 0), 0);
+    for (const bad of [null, -1, Number.NaN, Infinity]) assert.equal(label(() => bad), 1, `falls back for ${bad}`);
+  });
+
+  it('labels only the rows tall enough for text, and none when showLabels is off', () => {
+    // Bids a tenth apart near the spread (the middle one a thin row), then one far level (a tall row).
+    const ragged = (): DepthBook => book({ bids: [[99, 1], [98.9, 2], [98.8, 3], [60, 5]] });
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(ragged, { showSpread: false, cumulative: false }).draw(ctx, fakeTarget(96, 400, 40, 120));
+    const sizes = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(sizes.includes('5.00'), 'the tall far row is labelled');
+    assert.ok(!sizes.includes('2.00'), 'a row too thin for text is not, though its side has a tall row');
+    const off = new MockContext2D();
+    createInlineBookPrimitive(ragged, { showSpread: false, showLabels: false }).draw(off, fakeTarget(96, 400, 60, 180));
+    assert.equal(off.countCalls('fillText'), 0);
+  });
+
+  it('labels row sizes when the rows are tall enough', () => {
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(() => book(), { showSpread: false }).draw(ctx, fakeTarget());
+    const texts = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(texts.includes('1.00'));
+    assert.ok(texts.includes('8.00'));
+  });
+
+  it('draws nothing without a book or with an empty one', () => {
+    const ctx = new MockContext2D();
+    const empty = createInlineBookPrimitive(() => null);
+    empty.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('fillRect'), 0);
+    assert.equal(empty.rows, null);
+    const ctx2 = new MockContext2D();
+    createInlineBookPrimitive(() => book({ bids: [], asks: [] })).draw(ctx2, fakeTarget());
+    assert.equal(ctx2.countCalls('fillRect'), 0);
+  });
+
+  it('outlines the hovered level and shows a price/size/cumulative tooltip', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { showLabels: false });
+    primitive.setHover(101);
+    primitive.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('stroke'), 1);
+    const texts = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(texts.some((t) => t.includes('101.00') && t.includes('Σ 6.00')));
+  });
+
+  it('ignores hover prices inside the spread', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { showLabels: false, showSpread: false });
+    primitive.setHover(99.5);
+    primitive.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('stroke'), 0);
+  });
+
+  it('skips levels outside the visible price range', () => {
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(() => book({ bids: [[200, 1], [201, 2]], asks: [[202, 1], [203, 2]] }), { showSpread: false }).draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('fillRect'), 0);
+    const ctx2 = new MockContext2D();
+    createInlineBookPrimitive(() => book({ bids: [[50, 1], [49, 2]], asks: [[48, 1], [47, 2]] }), { showSpread: false }).draw(ctx2, fakeTarget());
+    assert.equal(ctx2.countCalls('fillRect'), 0);
+  });
+
+  it('draws the spread band without a label when the band is too thin', () => {
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(() => book(), { showLabels: false, cumulative: false }).draw(ctx, fakeTarget(96, 400, 0, 400));
+    const texts = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(!texts.some((t) => t.startsWith('Δ ')));
+    assert.ok(ctx.countCalls('fillRect') >= 3);
+  });
+
+  it('omits the spread band when either side of the book is empty', () => {
+    const ctx = new MockContext2D();
+    createInlineBookPrimitive(() => book({ asks: [] }), { showLabels: false, cumulative: false }).draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('fillRect'), 3);
+    const ctx2 = new MockContext2D();
+    createInlineBookPrimitive(() => book({ bids: [] }), { showLabels: false, cumulative: false }).draw(ctx2, fakeTarget());
+    assert.equal(ctx2.countCalls('fillRect'), 3);
+  });
+
+  it('outlines a hovered bid level with the bid color', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { showLabels: false });
+    primitive.setHover(98);
+    primitive.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('stroke'), 1);
+    const texts = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(texts.some((t) => t.includes('98.00') && t.includes('Σ 3.00')));
+  });
+
+  it('ignores hover prices beyond the outermost level', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { showLabels: false, showSpread: false });
+    primitive.setHover(500);
+    primitive.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('stroke'), 0);
+  });
+
+  it('never outlines a level when showHover is false', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), { showHover: false });
+    primitive.setHover(101);
+    primitive.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('stroke'), 0);
+  });
+
+  it('hovers the only side of a one-sided book', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book({ asks: [] }), { showLabels: false, showSpread: false });
+    primitive.setHover(98);
+    primitive.draw(ctx, fakeTarget());
+    assert.equal(ctx.countCalls('stroke'), 1);
+    const ctx2 = new MockContext2D();
+    const primitive2 = createInlineBookPrimitive(() => book({ bids: [] }), { showLabels: false, showSpread: false });
+    primitive2.setHover(50);
+    primitive2.draw(ctx2, fakeTarget());
+    assert.equal(ctx2.countCalls('stroke'), 0);
+  });
+
+  it('uses the explicitly provided style options', () => {
+    const ctx = new MockContext2D();
+    const primitive = createInlineBookPrimitive(() => book(), {
+      maxLevels: 3,
+      bidColor: '#111111',
+      askColor: '#222222',
+      cumulative: true,
+      opacity: 0.7,
+      cumulativeOpacity: 0.3,
+      showSpread: true,
+      spreadColor: '#333333',
+      showLabels: true,
+      labelColor: '#444444',
+      showHover: true,
+    });
+    primitive.setHover(99);
+    primitive.draw(ctx, fakeTarget());
+    assert.ok(ctx.countCalls('fillRect') > 0);
+    assert.equal(ctx.countCalls('stroke'), 1);
+  });
+});
+
+describe('attachInlineBook', () => {
+  function chartWith(config: Record<string, unknown> = {}) {
+    const doc = new MockDocument();
+    const chart = createChart({ document: doc, config: { wasm: false, data: candles(50), width: 640, height: 400, ...config } });
+    return { doc, chart };
+  }
+
+  it('docks a book pane sharing the main price scale', () => {
+    const { chart } = chartWith();
+    const fullWidth = chart.plotArea.width;
+    const api = attachInlineBook(chart);
+    assert.equal(api.pane!.id, 'inline-book');
+    assert.equal(chart.plotArea.width, fullWidth - DEFAULT_INLINE_BOOK_WIDTH);
+    const mainSeen: PrimitiveDrawTarget[] = [];
+    chart.attachPrimitive({ draw: (_ctx, t) => { mainSeen.push(t); } });
+    const paneSeen: PrimitiveDrawTarget[] = [];
+    api.pane!.attachPrimitive({ draw: (_ctx, t) => { paneSeen.push(t); } });
+    assert.equal(paneSeen[0]!.priceScale.minPrice, mainSeen[0]!.priceScale.minPrice);
+    assert.equal(paneSeen[0]!.priceScale.maxPrice, mainSeen[0]!.priceScale.maxPrice);
+    assert.equal(paneSeen[0]!.width, DEFAULT_INLINE_BOOK_WIDTH);
+    api.remove();
+    assert.equal(chart.plotArea.width, fullWidth);
+    chart.destroy();
+  });
+
+  it('repaints from chart.setDepth without extra wiring', () => {
+    const { doc, chart } = chartWith();
+    const api = attachInlineBook(chart);
+    const ctx = doc.created[0]!.context;
+    const before = ctx.countCalls('fillRect');
+    chart.setDepth(book());
+    assert.ok(ctx.countCalls('fillRect') > before);
+    chart.setDepth(null);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('updates options and dock width live', () => {
+    const { chart } = chartWith();
+    const fullWidth = chart.plotArea.width;
+    const api = attachInlineBook(chart, { maxLevels: 2 });
+    assert.doesNotThrow(() => api.update({ bidColor: '#00ff00', cumulative: false }));
+    api.update({ width: 60 });
+    assert.equal(chart.plotArea.width, fullWidth - 60);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('rejects a duplicate pane id', () => {
+    const { chart } = chartWith();
+    const api = attachInlineBook(chart);
+    assert.throws(() => attachInlineBook(chart), /duplicate pane/);
+    api.remove();
+    attachInlineBook(chart).remove();
+    chart.destroy();
+  });
+
+  it('follows config inlineBook writes while attached', () => {
+    const { chart } = chartWith();
+    const fullWidth = chart.plotArea.width;
+    const api = attachInlineBook(chart);
+    assert.doesNotThrow(() => chart.updateConfig({ inlineBook: { maxLevels: 1, askColor: '#ff0000' } }));
+    chart.updateConfig({ inlineBook: { width: 72 } });
+    assert.equal(chart.plotArea.width, fullWidth - 72);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('hovers the book level under the crosshair', () => {
+    const { doc, chart } = chartWith();
+    const api = attachInlineBook(chart);
+    const ctx = doc.created[0]!.context;
+    /** Tooltips of a fresh frame, so a frame painted before the hover moved never counts. */
+    const tooltips = (): string[] => {
+      ctx.calls.length = 0;
+      chart.render();
+      return ctx.callsNamed('fillText').map((c) => String(c[1])).filter((t) => t.includes('Σ'));
+    };
+    const hoverAt = (price: number): string[] => {
+      chart.setCrosshair(100, chart.scale.priceToY(price));
+      return tooltips();
+    };
+    assert.deepEqual(hoverAt(101), [], 'no book yet: nothing to hover');
+    chart.setDepth(book());
+    assert.ok(hoverAt(101.1).some((t) => t.includes('101.00')), 'an ask level');
+    assert.ok(hoverAt(100.9).some((t) => t.includes('101.00')), 'the same level keeps its hover');
+    assert.ok(hoverAt(98).some((t) => t.includes('98.00')), 'a bid level');
+    assert.deepEqual(hoverAt(99.5), [], 'inside the spread');
+    assert.deepEqual(hoverAt(104), [], 'beyond the outermost ask');
+    assert.ok(hoverAt(97).some((t) => t.includes('97.00')));
+    chart.clearCrosshair();
+    assert.deepEqual(tooltips(), [], 'a hidden crosshair drops the hover');
+    api.remove();
+    chart.destroy();
+  });
+
+  it('hovers the only side of a one-sided attached book', () => {
+    const { doc, chart } = chartWith();
+    const api = attachInlineBook(chart);
+    const ctx = doc.created[0]!.context;
+    const hoverAt = (price: number): string[] => {
+      chart.setCrosshair(100, chart.scale.priceToY(price));
+      ctx.calls.length = 0;
+      chart.render();
+      return ctx.callsNamed('fillText').map((c) => String(c[1])).filter((t) => t.includes('Σ'));
+    };
+    chart.setDepth(book({ asks: [] }));
+    assert.ok(hoverAt(98).some((t) => t.includes('98.00')), 'no asks: a bid still hovers');
+    chart.setDepth(book({ bids: [] }));
+    assert.deepEqual(hoverAt(98), [], 'no bids: below the asks hovers nothing');
+    api.remove();
+    chart.destroy();
+  });
+
+  it('ignores config writes to other sections', () => {
+    const { chart } = chartWith();
+    const fullWidth = chart.plotArea.width;
+    const api = attachInlineBook(chart);
+    chart.updateConfig({ series: { upColor: '#00ff00' } });
+    assert.equal(chart.plotArea.width, fullWidth - DEFAULT_INLINE_BOOK_WIDTH);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('overlays the book behind the series along the plot edge, keeping the plot width', () => {
+    const { doc, chart } = chartWith({ inlineBook: { placement: 'overlay' } });
+    const fullWidth = chart.plotArea.width;
+    const api = attachInlineBook(chart);
+    assert.equal(api.pane, null);
+    assert.equal(chart.plotArea.width, fullWidth, 'no dock strip');
+    const ctx = doc.created[0]!.context;
+    const edge = () => {
+      ctx.calls.length = 0;
+      chart.setDepth(book());
+      return ctx.callsNamed('translate').map((c) => c[1] as number);
+    };
+    assert.ok(edge().includes(fullWidth - DEFAULT_INLINE_BOOK_WIDTH), 'the band hugs the right edge');
+    chart.updateConfig({ inlineBook: { width: 60 } });
+    assert.ok(edge().includes(fullWidth - 60));
+    api.update({ width: 40 });
+    assert.ok(edge().includes(fullWidth - 40));
+    assert.equal(chart.plotArea.width, fullWidth);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('insets the overlay band from the price axis, clamped to the plot', () => {
+    const { doc, chart } = chartWith({ inlineBook: { placement: 'overlay', inset: 50 } });
+    const plot = chart.plotArea.width;
+    const api = attachInlineBook(chart);
+    const ctx = doc.created[0]!.context;
+    const edge = () => {
+      ctx.calls.length = 0;
+      chart.setDepth(book());
+      return ctx.callsNamed('translate').map((c) => c[1] as number);
+    };
+    assert.ok(edge().includes(plot - DEFAULT_INLINE_BOOK_WIDTH - 50));
+    api.update({ inset: 10 });
+    assert.ok(edge().includes(plot - DEFAULT_INLINE_BOOK_WIDTH - 10), 'the attach option wins over the config');
+    api.update({ inset: 10_000 });
+    assert.ok(edge().includes(0), 'never past the plot left edge');
+    api.remove();
+    chart.destroy();
+  });
+
+  it('re-attaches the config book when its placement changes', () => {
+    const { chart } = chartWith({ inlineBook: { enabled: true, width: 88 } });
+    const docked = chart.plotArea.width;
+    chart.updateConfig({ inlineBook: { placement: 'overlay' } });
+    assert.equal(chart.plotArea.width, docked + 88, 'the overlay takes no plot width');
+    chart.updateConfig({ inlineBook: { maxLevels: 5 } });
+    assert.equal(chart.plotArea.width, docked + 88, 'other writes keep the attached book');
+    chart.updateConfig({ inlineBook: { placement: 'dock' } });
+    assert.equal(chart.plotArea.width, docked);
+    chart.destroy();
+  });
+
+  it('attaches and removes with the config inlineBook.enabled flag', () => {
+    const { chart } = chartWith({ inlineBook: { enabled: true, width: 88 } });
+    const fullWidth = 640 - 88 - chart.getConfig().priceAxis.width;
+    assert.equal(chart.plotArea.width, fullWidth);
+    chart.updateConfig({ inlineBook: { enabled: false } });
+    assert.equal(chart.plotArea.width, fullWidth + 88);
+    chart.updateConfig({ inlineBook: { enabled: true } });
+    assert.equal(chart.plotArea.width, fullWidth);
+    chart.destroy();
+  });
+});
diff --git a/packages/chart/test/range-profile.test.ts b/packages/chart/test/range-profile.test.ts
new file mode 100644
index 0000000..b8c7682
--- /dev/null
+++ b/packages/chart/test/range-profile.test.ts
@@ -0,0 +1,303 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  attachRangeProfile,
+  createChart,
+  createRangeProfilePrimitive,
+  formatProfileVolume,
+  gridVolumeRows,
+  profileStep,
+  resolveConfig,
+  type Chart,
+  type ChartConfig,
+  type PanePrimitive,
+} from '../dist/index.js';
+import { MockContext2D, MockDocument } from '../dist/dom.js';
+import type { Candle } from '../dist/core/data.js';
+import type { PrimitiveDrawTarget } from '../dist/render/primitive.js';
+import { PriceScale, TimeScale } from '../dist/core/scale.js';
+
+const bar = (low: number, high: number, up: boolean, volume?: number): Candle => ({
+  time: 1_700_000_000, open: up ? low : high, high, low, close: up ? high : low, ...(volume === undefined ? {} : { volume }),
+});
+
+/** A 400px pane showing 90–110: at the default 14px rows that is 0.7 per row, rounded up to a step of 1. */
+function target(candles: Candle[], options: { height?: number; width?: number; inverted?: boolean } = {}): PrimitiveDrawTarget {
+  const height = options.height ?? 400;
+  const priceScale = new PriceScale();
+  priceScale.height = height;
+  priceScale.topMargin = 0;
+  priceScale.bottomMargin = 0;
+  priceScale.inverted = options.inverted ?? false;
+  priceScale.setRange(90, 110);
+  return {
+    width: options.width ?? 600, height, priceScale, timeScale: new TimeScale(),
+    range: { from: 0, to: candles.length }, candles, pixelRatio: 1,
+  };
+}
+
+describe('profileStep', () => {
+  it('rounds up to 1, 2, 2.5 or 5 times a power of ten', () => {
+    assert.equal(profileStep(0.7), 1);
+    assert.equal(profileStep(1), 1);
+    assert.equal(profileStep(1.5), 2);
+    assert.equal(profileStep(2.2), 2.5);
+    assert.equal(profileStep(3), 5);
+    assert.equal(profileStep(70), 100);
+    assert.equal(profileStep(0), 1);
+    assert.equal(profileStep(Number.NaN), 1);
+    assert.equal(profileStep(Infinity), 1);
+  });
+});
+
+describe('gridVolumeRows', () => {
+  it('spreads each bar over the rows it touches, split by direction', () => {
+    const { up, down } = gridVolumeRows([bar(100, 101.5, true, 20), bar(102, 102.5, false, 6)], 0, 1, 100, 1, 4);
+    assert.deepEqual(up, [10, 10, 0, 0]);
+    assert.deepEqual(down, [0, 0, 6, 0]);
+  });
+
+  it('keeps only the on-grid share of a bar reaching past the grid, and skips off-grid bars', () => {
+    const candles = [bar(98, 101.5, true, 40), bar(200, 201, true, 5), bar(10, 11, false, 5), bar(Number.NaN, 101, true, 5), bar(100, 100.5, true)];
+    const { up, down } = gridVolumeRows(candles, -3, 99, 100, 1, 2);
+    assert.deepEqual(up, [10, 10], '4 rows touched, 2 on the grid; no volume counts 0');
+    assert.deepEqual(down, [0, 0]);
+  });
+});
+
+describe('formatProfileVolume', () => {
+  it('compacts to units, K and M', () => {
+    assert.equal(formatProfileVolume(823.4), '823');
+    assert.equal(formatProfileVolume(3_000), '3K');
+    assert.equal(formatProfileVolume(12_400), '12K');
+    assert.equal(formatProfileVolume(1_230_000), '1.2M');
+  });
+});
+
+describe('createRangeProfilePrimitive', () => {
+  it('mirrors down volume left and up volume right of the center, labelled and shaded by size, with the POC outlined', () => {
+    const ctx = new MockContext2D();
+    // Rows of 1 between 90 and 110; 20 volume up at 100, 5 down and 10 up at 95.
+    createRangeProfilePrimitive({ inset: 50 }).draw(ctx, target([bar(100, 100.5, true, 20), bar(95, 95.5, false, 5), bar(95, 95.5, true, 10)]));
+    // 200px wide, 50px in from the 600px edge: x 350..550, center 450, 100px per side.
+    const bars = ctx.callsNamed('fillRect');
+    assert.equal(bars.length, 4, 'two rows, down and up each');
+    assert.ok(bars.some((c) => c[1] === 450 && c[3] === 100), 'the busiest up bar spans its whole side');
+    assert.ok(bars.some((c) => c[1] === 425 && c[3] === 25), 'down volume grows left of the center');
+    assert.ok(bars.some((c) => c[1] === 450 && c[3] === 50), 'widths follow the largest single side, not row totals');
+    const labels = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.deepEqual(labels.sort(), ['0', '10', '20', '5']);
+    const rects = ctx.callsNamed('rect');
+    assert.equal(rects.length, 1);
+    assert.equal(rects[0]![1], 350.5, 'the POC outline spans the profile');
+    assert.equal(ctx.countCalls('stroke'), 1);
+  });
+
+  it('skips labels on short rows and the POC outline when disabled, and draws nothing without volume', () => {
+    const ctx = new MockContext2D();
+    createRangeProfilePrimitive({ rowHeight: 4, showPoc: false }).draw(ctx, target([bar(100, 100.5, true, 20)], { inverted: true }));
+    assert.equal(ctx.countCalls('fillText'), 0, '4px rows are too short for labels');
+    assert.equal(ctx.countCalls('stroke'), 0);
+    assert.ok(ctx.countCalls('fillRect') > 0);
+
+    const quiet = new MockContext2D();
+    createRangeProfilePrimitive({ showLabels: false }).draw(quiet, target([bar(100, 100.5, true, 0)]));
+    assert.equal(quiet.countCalls('fillRect'), 0);
+    const flat = new MockContext2D();
+    createRangeProfilePrimitive().draw(flat, target([bar(100, 100.5, true, 20)], { height: 0 }));
+    assert.equal(flat.countCalls('fillRect'), 0, 'a zero-height pane draws nothing');
+  });
+});
+
+describe('attachRangeProfile', () => {
+  it('draws on the main pane behind the series, restyles live and detaches', () => {
+    const doc = new MockDocument();
+    const data = Array.from({ length: 40 }, (_, i) => ({
+      time: 1_700_000_000 + i * 60, open: 100 + (i % 5), high: 103 + (i % 5), low: 99 + (i % 5), close: 101 + (i % 3), volume: 10 + i,
+    }));
+    const chart = createChart({ document: doc, config: { wasm: false, data, width: 800, height: 500 } });
+    const ctx = doc.created[0]!.context;
+    const paint = (): number => {
+      ctx.calls.length = 0;
+      chart.render();
+      return ctx.callsNamed('rect').length;
+    };
+    const base = paint(); // the pane clip
+    const api = attachRangeProfile(chart);
+    assert.equal(paint(), base + 1, 'the POC outline');
+    api.update({ showPoc: false });
+    assert.equal(paint(), base);
+    api.remove();
+    ctx.calls.length = 0;
+    chart.render();
+    assert.equal(ctx.callsNamed('fillText').filter((c) => /^\d+K?$/.test(String(c[1]))).length > 0, false, 'no profile labels once removed');
+    chart.destroy();
+  });
+});
+
+/** A mock context that also records the fill/stroke color behind every draw call. */
+class StyledContext extends MockContext2D {
+  readonly styles: string[] = [];
+  override fillRect(x: number, y: number, w: number, h: number): void {
+    this.styles.push(String(this.fillStyle));
+    super.fillRect(x, y, w, h);
+  }
+  override fillText(text: string, x: number, y: number): void {
+    this.styles.push(String(this.fillStyle));
+    super.fillText(text, x, y);
+  }
+  override stroke(): void {
+    this.styles.push(String(this.strokeStyle));
+    super.stroke();
+  }
+}
+
+/** A chart stand-in capturing the attached primitive, with a live config and a manual frame clock. */
+function harness(partial: Parameters<typeof resolveConfig>[0] = {}) {
+  let config: ChartConfig = resolveConfig(partial);
+  let primitive: PanePrimitive | null = null;
+  let updates = 0;
+  const chart = {
+    attachPrimitive(p: PanePrimitive) {
+      primitive = p;
+      return { requestUpdate: () => { updates++; }, detach: () => { primitive = null; } };
+    },
+    getConfig: () => config,
+  } as unknown as Chart;
+  let time = 0;
+  const frames: (() => void)[] = [];
+  const cancelled: number[] = [];
+  const scheduler = {
+    now: () => time,
+    request: (cb: (t: number) => void) => frames.push(() => cb(time)),
+    cancel: (handle: number) => { cancelled.push(handle); },
+  };
+  const paint = (candles: Candle[], options: { height?: number } = {}): StyledContext => {
+    const ctx = new StyledContext();
+    primitive!.draw(ctx, target(candles, options));
+    return ctx;
+  };
+  return {
+    chart, scheduler, paint, frames, cancelled,
+    get attached() { return primitive !== null; },
+    get updates() { return updates; },
+    advance: (ms: number) => { time += ms; },
+    setConfig: (next: Parameters<typeof resolveConfig>[0]) => { config = resolveConfig(next); },
+  };
+}
+
+/** Widths of the bars `ctx` filled, rounded. */
+const widths = (ctx: MockContext2D): number[] => ctx.callsNamed('fillRect').map((c) => Math.round(c[3] as number));
+
+describe('range profile theme tokens', () => {
+  it('follows the series and text colors of the live config, and passes custom colors through', () => {
+    const h = harness({ series: { upColor: '#00ff3f', downColor: '#ff479c' }, theme: { textColor: '#a1a1a1', monoFamily: 'Geist Mono' } });
+    attachRangeProfile(h.chart);
+    const candles = [bar(100, 100.5, true, 20), bar(95, 95.5, false, 5)];
+    let ctx = h.paint(candles);
+    assert.ok(ctx.styles.includes('#00ff3f'), 'up bars take series.upColor');
+    assert.ok(ctx.styles.includes('#ff479c'), 'down bars take series.downColor');
+    assert.ok(ctx.styles.includes('#a1a1a1'), 'the POC outline takes theme.textColor');
+    const labels = ctx.callsNamed('fillText');
+    const labelStyles = ctx.styles.filter((_, i) => ctx.calls.filter((c) => ['fillRect', 'fillText', 'stroke'].includes(c[0] as string))[i]![0] === 'fillText');
+    assert.equal(labels.length, 4);
+    assert.deepEqual(labelStyles, ['#ff479c', '#00ff3f', '#ff479c', '#00ff3f'], 'each size takes its side color');
+    assert.ok(ctx.calls.some((c) => c[0] === 'set:font' && c[1] === '500 11px Geist Mono'), 'labels use the theme mono family at medium weight');
+    assert.ok(ctx.calls.some((c) => c[0] === 'set:font' && c[1] === 'bold 11px Geist Mono'), 'the POC row is bold');
+    h.setConfig({ series: { upColor: '#123456' } });
+    ctx = h.paint(candles);
+    assert.ok(ctx.styles.includes('#123456'), 'a theme switch recolors the next draw');
+
+    const custom = harness();
+    attachRangeProfile(custom.chart, { upColor: '#abcdef', labelColor: '#fedcba' });
+    const styled = custom.paint(candles);
+    assert.ok(styled.styles.includes('#abcdef') && styled.styles.includes('#fedcba'));
+  });
+
+  it('resolves tokens against the default theme when used as a bare primitive', () => {
+    const ctx = new StyledContext();
+    createRangeProfilePrimitive().draw(ctx, target([bar(100, 100.5, true, 20)]));
+    assert.ok(ctx.styles.includes(resolveConfig().series.upColor));
+  });
+});
+
+describe('range profile transitions', () => {
+  it('tweens new rows in linearly over the duration, one frame request at a time', () => {
+    const h = harness();
+    attachRangeProfile(h.chart, { scheduler: h.scheduler, showLabels: false, showPoc: false });
+    const candles = [bar(100, 100.5, true, 20)];
+    assert.deepEqual(widths(h.paint(candles)), [], 'a new row starts empty');
+    assert.equal(h.frames.length, 1, 'and asks for a frame');
+    h.paint(candles); // a repaint mid-flight reuses the pending frame
+    assert.equal(h.frames.length, 1);
+    h.advance(90);
+    h.frames.shift()!();
+    assert.equal(h.updates, 1, 'the frame re-renders the pane');
+    assert.deepEqual(widths(h.paint(candles)), [0, 50], 'half way: half the width');
+    h.advance(90);
+    h.frames.shift()!();
+    assert.deepEqual(widths(h.paint(candles)), [0, 100]);
+    assert.equal(h.frames.length, 0, 'settled: no more frames');
+  });
+
+  it('retargets a moving row from where it is, eases out on request, and shrinks vanished volume to nothing', () => {
+    const h = harness();
+    const api = attachRangeProfile(h.chart, { scheduler: h.scheduler, showPoc: false, easing: 'ease-out' });
+    const a = [bar(100, 100.5, true, 20)];
+    h.paint(a);
+    h.advance(90);
+    // Ease-out cubic at t=0.5 covers 87.5% of the way.
+    assert.deepEqual(widths(h.paint(a)), [0, 88]);
+    api.update({ width: 100 }); // new goal (50px) while moving: the next draw retargets from 87.5
+    assert.deepEqual(widths(h.paint(a)), [0, 88], 'no jump on retarget');
+    h.advance(45);
+    // A quarter way, eased: 1 - 0.75³ ≈ 0.578 of 87.5 → 50.
+    assert.deepEqual(widths(h.paint(a)), [0, 66]);
+    h.advance(1000);
+    h.paint(a);
+    // The busy row moves: 100 now has no volume but still shrinks from its drawn width, unlabelled.
+    const b = [bar(100, 100.5, true, 0), bar(95, 95.5, true, 20)];
+    const ctx = h.paint(b);
+    assert.ok(widths(ctx).includes(50), 'the old row starts at its drawn width');
+    assert.equal(ctx.countCalls('fillText'), 2, 'only the row with volume is labelled');
+  });
+
+  it('starts re-bucketed rows from the previous shape at their price', () => {
+    const h = harness();
+    const api = attachRangeProfile(h.chart, { scheduler: h.scheduler, showLabels: false, showPoc: false });
+    const candles = [bar(92.6, 93.9, true, 20)];
+    h.paint(candles);
+    h.advance(500);
+    h.paint(candles); // settled on 1-wide rows 92 and 93
+    api.update({ rowHeight: 44 }); // 2.2 per row → a step of 2.5: row 92.5 is a new key
+    const ctx = h.paint(candles);
+    assert.deepEqual(widths(ctx), [0, 100], 'no flash to empty: row 92.5 starts from the old shape at its price');
+  });
+
+  it('applies changes at once with a zero duration, and cancels a pending frame on remove', () => {
+    const still = harness();
+    attachRangeProfile(still.chart, { scheduler: still.scheduler, duration: 0, showLabels: false, showPoc: false });
+    assert.deepEqual(widths(still.paint([bar(100, 100.5, true, 20)])), [0, 100]);
+    assert.equal(still.frames.length, 0);
+
+    const h = harness();
+    const api = attachRangeProfile(h.chart, { scheduler: h.scheduler });
+    h.paint([bar(100, 100.5, true, 20)]);
+    assert.equal(h.frames.length, 1);
+    api.remove();
+    assert.deepEqual(h.cancelled, [1]);
+    assert.equal(h.attached, false);
+    api.remove(); // nothing pending: nothing to cancel
+    assert.deepEqual(h.cancelled, [1]);
+  });
+
+  it('forgets its tweens when the view holds no volume', () => {
+    const h = harness();
+    attachRangeProfile(h.chart, { scheduler: h.scheduler, showLabels: false, showPoc: false });
+    h.paint([bar(100, 100.5, true, 20)]);
+    h.advance(500);
+    h.paint([bar(100, 100.5, true, 20)]);
+    h.paint([bar(100, 100.5, true, 0)]);
+    assert.deepEqual(widths(h.paint([bar(100, 100.5, true, 20)])), [], 'the row grows in again from empty');
+  });
+});
diff --git a/packages/chart/test/session-profile.test.ts b/packages/chart/test/session-profile.test.ts
new file mode 100644
index 0000000..f76687b
--- /dev/null
+++ b/packages/chart/test/session-profile.test.ts
@@ -0,0 +1,394 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createChart } from '../dist/index.js';
+import { MockContext2D, MockDocument } from '../dist/dom.js';
+import type { Candle } from '../dist/core/data.js';
+import type { PrimitiveDrawTarget } from '../dist/render/primitive.js';
+import {
+  computeTpoProfile,
+  computeVolumeProfile,
+  profileRowAt,
+  sessionRanges,
+  tpoProfileRows,
+  valueArea,
+  volumeProfileRows,
+  DEFAULT_SESSION_MS,
+} from '../dist/core/profile.js';
+import {
+  attachSessionProfile,
+  createSessionLevelsPrimitive,
+  createSessionProfilePrimitive,
+  DEFAULT_SESSION_PROFILE_WIDTH,
+} from '../dist/render/session-profile.js';
+import { PriceScale, TimeScale } from '../dist/core/scale.js';
+
+function candles(n: number, start = 1700000000, step = 3600): Candle[] {
+  return Array.from({ length: n }, (_, i) => ({
+    time: start + i * step,
+    open: 100 + i,
+    high: 102 + i,
+    low: 99 + i,
+    close: 101 + i,
+    volume: 1000 + i * 10,
+  }));
+}
+
+describe('volumeProfileRows', () => {
+  it('bins volume over the bar range and splits by direction', () => {
+    const data = candles(10);
+    const prof = volumeProfileRows(data, 0, 9, 10)!;
+    assert.equal(prof.lo, 99);
+    assert.equal(prof.hi, 111);
+    const total = data.reduce((s, c) => s + (c.volume ?? 0), 0);
+    const binned = prof.up.reduce((s, x) => s + x, 0) + prof.down.reduce((s, x) => s + x, 0);
+    assert.ok(Math.abs(binned - total) < 1e-9);
+    assert.ok(prof.up.every((v) => v >= 0));
+  });
+
+  it('returns null for empty or invalid ranges', () => {
+    assert.equal(volumeProfileRows([], 0, 5, 10), null);
+    assert.equal(volumeProfileRows(candles(5), 3, 1, 10) === null, false); // swapped bounds are normalized
+    assert.equal(volumeProfileRows(candles(5), 0, 4, 0), null);
+  });
+
+  it('returns null when the whole range lies beyond the data', () => {
+    assert.equal(volumeProfileRows(candles(5), 10, 20, 10), null);
+    assert.equal(tpoProfileRows(candles(5), 10, 20, 10), null);
+  });
+
+  it('treats a missing volume as zero and bins falling bars into down', () => {
+    const data: Candle[] = [
+      { time: 1, open: 12, high: 13, low: 10, close: 11 }, // falling, no volume
+      { time: 2, open: 13, high: 14, low: 11, close: 12, volume: 90 }, // falling
+      { time: 3, open: 11, high: 13, low: 10, close: 12, volume: 30 }, // rising
+    ];
+    const prof = volumeProfileRows(data, 0, 2, 4)!;
+    const up = prof.up.reduce((s, x) => s + x, 0);
+    const down = prof.down.reduce((s, x) => s + x, 0);
+    assert.equal(up, 30);
+    assert.equal(down, 90);
+  });
+
+  it('falls back to a unit step when all bars are flat', () => {
+    const flat: Candle[] = Array.from({ length: 4 }, (_, i) => ({
+      time: 1700000000 + i * 3600,
+      open: 50,
+      high: 50,
+      low: 50,
+      close: 50,
+      volume: 10,
+    }));
+    const vol = computeVolumeProfile(flat, 0, 3, 8)!;
+    assert.equal(vol.step, 1);
+    const tpo = computeTpoProfile(flat, 0, 3, 8)!;
+    assert.equal(tpo.step, 1);
+    assert.equal(tpo.totals[0], 4);
+  });
+});
+
+describe('tpoProfileRows', () => {
+  it('counts one TPO per bar covering a row', () => {
+    const data: Candle[] = [
+      { time: 1, open: 10, high: 11.5, low: 10, close: 11 },
+      { time: 2, open: 11, high: 13, low: 11, close: 12 },
+    ];
+    const prof = tpoProfileRows(data, 0, 1, 3)!;
+    assert.equal(prof.lo, 10);
+    assert.equal(prof.hi, 13);
+    assert.deepEqual(prof.counts, [1, 2, 1]);
+  });
+});
+
+describe('valueArea', () => {
+  it('grows from the POC until the percent is covered', () => {
+    const totals = [1, 2, 10, 3, 2, 1, 1];
+    const va = valueArea(totals, 0.7);
+    assert.equal(va.poc, 2);
+    const covered = totals.slice(va.low, va.high + 1).reduce((s, x) => s + x, 0);
+    assert.ok(covered >= 0.7 * totals.reduce((s, x) => s + x, 0));
+    assert.ok(va.low <= va.poc && va.high >= va.poc);
+  });
+
+  it('handles an all-zero profile', () => {
+    const va = valueArea([0, 0, 0]);
+    assert.deepEqual(va, { poc: 0, low: 0, high: 0 });
+  });
+
+  it('handles empty totals', () => {
+    assert.deepEqual(valueArea([]), { poc: 0, low: 0, high: 0 });
+  });
+
+  it('expands only upward when the POC is the first row', () => {
+    assert.deepEqual(valueArea([10, 1, 1], 0.99), { poc: 0, low: 0, high: 2 });
+  });
+
+  it('expands downward when the POC is the last row', () => {
+    assert.deepEqual(valueArea([1, 1, 10], 0.99), { poc: 2, low: 0, high: 2 });
+  });
+
+  it('prefers the lower side when it holds more than the row above', () => {
+    const va = valueArea([5, 10, 8, 1], 0.9);
+    assert.equal(va.poc, 1);
+    assert.equal(va.low, 0);
+    assert.ok(va.high >= 2);
+  });
+});
+
+describe('computeVolumeProfile / computeTpoProfile', () => {
+  it('prices the POC row and value-area bounds', () => {
+    const data = candles(20);
+    const prof = computeVolumeProfile(data, 0, 19, 20)!;
+    assert.ok(prof.pocPrice >= prof.lo + prof.step * prof.poc);
+    assert.ok(prof.pocPrice <= prof.lo + prof.step * (prof.poc + 1));
+    assert.ok(prof.valueAreaLowPrice <= prof.pocPrice);
+    assert.ok(prof.valueAreaHighPrice >= prof.pocPrice);
+    assert.equal(prof.totals.length, 20);
+    assert.equal(prof.up.length, 20);
+  });
+
+  it('builds a TPO profile with count totals', () => {
+    const data = candles(12); // 99..113 → step 1 at 14 rows; bars span 4 rows, the last bar's high clamps to the top row
+    const prof = computeTpoProfile(data, 0, 11, 14)!;
+    assert.equal(prof.step, 1);
+    assert.equal(prof.totals.reduce((s, x) => s + x, 0), 11 * 4 + 3);
+    assert.equal(prof.totals[prof.poc], Math.max(...prof.totals));
+  });
+
+  it('returns null for empty data', () => {
+    assert.equal(computeVolumeProfile([], 0, 5, 10), null);
+    assert.equal(computeTpoProfile([], 0, 5, 10), null);
+  });
+});
+
+describe('profileRowAt', () => {
+  it('clamps to the row range', () => {
+    assert.equal(profileRowAt(100, 2, 10, 99), 0);
+    assert.equal(profileRowAt(100, 2, 10, 101), 0);
+    assert.equal(profileRowAt(100, 2, 10, 103), 1);
+    assert.equal(profileRowAt(100, 2, 10, 500), 9);
+  });
+});
+
+describe('sessionRanges', () => {
+  it('splits bars into daily sessions', () => {
+    const data = candles(72, 1699920000); // 3 days of hourly bars from a UTC midnight
+    const sessions = sessionRanges(data, 0, 71);
+    assert.equal(sessions.length, 3);
+    assert.deepEqual(sessions.map((s) => [s.from, s.to]), [
+      [0, 23],
+      [24, 47],
+      [48, 71],
+    ]);
+    assert.equal(sessions[1]!.start - sessions[0]!.start, DEFAULT_SESSION_MS / 1000);
+  });
+
+  it('honors a custom session length and clamps the range', () => {
+    const data = candles(48); // 2 days of hourly bars
+    const sessions = sessionRanges(data, -10, 100, DEFAULT_SESSION_MS / 24); // hourly sessions
+    assert.equal(sessions.length, 48);
+    assert.equal(sessions[0]!.from, 0);
+    assert.equal(sessions[47]!.to, 47);
+  });
+});
+
+function fakeTarget(data: Candle[], width = 120, height = 400, min = 90, max = 130): PrimitiveDrawTarget {
+  const priceScale = new PriceScale();
+  priceScale.height = height;
+  priceScale.setRange(min, max);
+  return {
+    width,
+    height,
+    priceScale,
+    timeScale: new TimeScale(),
+    range: { from: 0, to: data.length },
+    candles: data,
+    pixelRatio: 1,
+  };
+}
+
+describe('createSessionProfilePrimitive', () => {
+  it('paints volume rows and a POC marker per session', () => {
+    const ctx = new MockContext2D();
+    const primitive = createSessionProfilePrimitive();
+    primitive.draw(ctx, fakeTarget(candles(72)));
+    assert.ok(ctx.countCalls('fillRect') > 24);
+  });
+
+  it('paints one composite column over all visible sessions', () => {
+    const ctx = new MockContext2D();
+    createSessionProfilePrimitive({ composite: true }).draw(ctx, fakeTarget(candles(72)));
+    const pocLines = ctx.callsNamed('fillRect').filter((c) => c[4] === 1 && c[3] === 120 * 0.95);
+    assert.equal(pocLines.length, 1);
+  });
+
+  it('draws nothing for empty data', () => {
+    const ctx = new MockContext2D();
+    createSessionProfilePrimitive().draw(ctx, fakeTarget([]));
+    assert.equal(ctx.countCalls('fillRect'), 0);
+    assert.equal(ctx.countCalls('fillText'), 0);
+  });
+
+  it('draws TPO letters when the columns are wide enough', () => {
+    const ctx = new MockContext2D();
+    createSessionProfilePrimitive({ mode: 'tpo', sessionMs: DEFAULT_SESSION_MS * 3 }).draw(ctx, fakeTarget(candles(72), 800));
+    assert.ok(ctx.countCalls('fillText') > 0);
+    const letters = new Set(ctx.callsNamed('fillText').map((c) => c[1]));
+    assert.ok(letters.has('A') && letters.has('B'));
+  });
+
+  it('falls back to TPO blocks in narrow columns', () => {
+    const ctx = new MockContext2D();
+    createSessionProfilePrimitive({ mode: 'tpo', rows: 6 }).draw(ctx, fakeTarget(candles(72, 1699920000), 30));
+    assert.equal(ctx.countCalls('fillText'), 0);
+    assert.ok(ctx.countCalls('fillRect') > 0);
+  });
+
+  it('draws nothing when the visible range lies beyond the data', () => {
+    const ctx = new MockContext2D();
+    const target = { ...fakeTarget(candles(24)), range: { from: 100, to: 200 } };
+    createSessionProfilePrimitive().draw(ctx, target);
+    assert.equal(ctx.countCalls('fillRect'), 0);
+  });
+
+  it('paints the down segment of rows with falling-bar volume', () => {
+    const ctx = new MockContext2D();
+    const falling: Candle[] = Array.from({ length: 24 }, (_, i) => ({
+      time: 1699920000 + i * 3600,
+      open: 102 + i,
+      high: 103 + i,
+      low: 99 + i,
+      close: 100 + i,
+      volume: 50,
+    }));
+    createSessionProfilePrimitive({ composite: true, showPoc: false }).draw(ctx, fakeTarget(falling, 120, 400, 95, 135));
+    // Every row fill comes from the down branch: up volume is zero everywhere.
+    assert.ok(ctx.countCalls('fillRect') > 0);
+  });
+
+  it('skips zero-volume rows and falls back to a unit max', () => {
+    const ctx = new MockContext2D();
+    const silent: Candle[] = Array.from({ length: 24 }, (_, i) => ({
+      time: 1699920000 + i * 3600,
+      open: 100 + i,
+      high: 102 + i,
+      low: 99 + i,
+      close: 101 + i,
+      volume: 0,
+    }));
+    createSessionProfilePrimitive({ composite: true, showPoc: false }).draw(ctx, fakeTarget(silent, 120, 400, 95, 135));
+    assert.equal(ctx.countCalls('fillRect'), 0);
+  });
+
+  it('falls back to a unit TPO max when no bar has a finite range', () => {
+    const ctx = new MockContext2D();
+    const blank: Candle[] = Array.from({ length: 24 }, (_, i) => ({
+      time: 1699920000 + i * 3600,
+      open: 100,
+      high: Number.NaN,
+      low: Number.NaN,
+      close: 100,
+      volume: 10,
+    }));
+    createSessionProfilePrimitive({ mode: 'tpo', composite: true, showPoc: false }).draw(ctx, fakeTarget(blank, 800));
+    assert.equal(ctx.countCalls('fillText'), 0);
+    assert.equal(ctx.countCalls('fillRect'), 0);
+  });
+
+  it('clips rows outside the visible price range', () => {
+    const data = candles(24, 1699920000);
+    const above = new MockContext2D();
+    createSessionProfilePrimitive({ composite: true, showPoc: false }).draw(above, fakeTarget(data, 120, 400, 200, 300));
+    assert.equal(above.countCalls('fillRect'), 0);
+    const below = new MockContext2D();
+    createSessionProfilePrimitive({ composite: true, showPoc: false }).draw(below, fakeTarget(data, 120, 400, 0, 50));
+    assert.equal(below.countCalls('fillRect'), 0);
+  });
+});
+
+describe('createSessionLevelsPrimitive', () => {
+  it('projects POC and value-area lines with labels for the latest session', () => {
+    const ctx = new MockContext2D();
+    createSessionLevelsPrimitive().draw(ctx, fakeTarget(candles(72), 640, 400, 140, 180));
+    assert.equal(ctx.countCalls('stroke'), 3);
+    const labels = ctx.callsNamed('fillText').map((c) => String(c[1]));
+    assert.ok(labels.some((t) => t.startsWith('POC ')));
+    assert.ok(labels.some((t) => t.startsWith('VAH ')));
+    assert.ok(labels.some((t) => t.startsWith('VAL ')));
+  });
+
+  it('projects more sessions on request and supports TPO mode', () => {
+    const ctx = new MockContext2D();
+    createSessionLevelsPrimitive({ sessions: 3, mode: 'tpo', showLabels: false }).draw(ctx, fakeTarget(candles(72), 640, 400, 95, 180));
+    assert.equal(ctx.countCalls('stroke'), 9);
+    assert.equal(ctx.countCalls('fillText'), 0);
+  });
+
+  it('skips level lines outside the visible price range', () => {
+    const ctx = new MockContext2D();
+    createSessionLevelsPrimitive().draw(ctx, fakeTarget(candles(72), 640, 400, 500, 600));
+    assert.equal(ctx.countCalls('stroke'), 0);
+    assert.equal(ctx.countCalls('fillText'), 0);
+  });
+
+  it('draws nothing without visible bars', () => {
+    const ctx = new MockContext2D();
+    createSessionLevelsPrimitive().draw(ctx, fakeTarget([]));
+    assert.equal(ctx.countCalls('stroke'), 0);
+  });
+});
+
+describe('attachSessionProfile', () => {
+  it('docks an auto-updating profile pane sharing the main price scale', () => {
+    const doc = new MockDocument();
+    const chart = createChart({ document: doc, config: { wasm: false, data: candles(72), width: 640, height: 400 } });
+    const fullWidth = chart.plotArea.width;
+    const api = attachSessionProfile(chart);
+    assert.equal(api.pane.id, 'session-profile');
+    assert.equal(chart.plotArea.width, fullWidth - DEFAULT_SESSION_PROFILE_WIDTH);
+    const mainSeen: PrimitiveDrawTarget[] = [];
+    chart.attachPrimitive({ draw: (_ctx, t) => { mainSeen.push(t); } });
+    const paneSeen: PrimitiveDrawTarget[] = [];
+    api.pane.attachPrimitive({ draw: (_ctx, t) => { paneSeen.push(t); } });
+    assert.equal(paneSeen[0]!.priceScale.minPrice, mainSeen[0]!.priceScale.minPrice);
+    assert.equal(paneSeen[0]!.priceScale.maxPrice, mainSeen[0]!.priceScale.maxPrice);
+    assert.equal(paneSeen[0]!.width, DEFAULT_SESSION_PROFILE_WIDTH);
+    // The pane drew profile rows and the main pane projected labeled levels.
+    const ctx = doc.created[0]!.context;
+    assert.ok(ctx.callsNamed('fillText').some((c) => String(c[1]).startsWith('POC ')));
+    api.remove();
+    assert.equal(chart.plotArea.width, fullWidth);
+    chart.destroy();
+  });
+
+  it('updates options and dock width live', () => {
+    const chart = createChart({ document: new MockDocument(), config: { wasm: false, data: candles(72), width: 640, height: 400 } });
+    const fullWidth = chart.plotArea.width;
+    const api = attachSessionProfile(chart, { mode: 'tpo', composite: true });
+    assert.doesNotThrow(() => api.update({ mode: 'volume', showPoc: false }));
+    api.update({ width: 60 });
+    assert.equal(chart.plotArea.width, fullWidth - 60);
+    api.remove();
+    chart.destroy();
+  });
+
+  it('skips the main-pane projections when projectLevels is false', () => {
+    const doc = new MockDocument();
+    const chart = createChart({ document: doc, config: { wasm: false, data: candles(72), width: 640, height: 400 } });
+    const api = attachSessionProfile(chart, { projectLevels: false });
+    const ctx = doc.created[0]!.context;
+    assert.ok(!ctx.callsNamed('fillText').some((c) => String(c[1]).startsWith('POC ')));
+    api.update({ projectLevels: true });
+    assert.ok(ctx.callsNamed('fillText').some((c) => String(c[1]).startsWith('POC ')));
+    api.remove();
+    chart.destroy();
+  });
+
+  it('rejects a duplicate pane id', () => {
+    const chart = createChart({ document: new MockDocument(), config: { wasm: false, data: candles(72), width: 640, height: 400 } });
+    const api = attachSessionProfile(chart);
+    assert.throws(() => attachSessionProfile(chart), /duplicate pane/);
+    api.remove();
+    attachSessionProfile(chart).remove();
+    chart.destroy();
+  });
+});
diff --git a/packages/chart/test/settings-polish.test.ts b/packages/chart/test/settings-polish.test.ts
index d85f4ac..7c94c99 100644
--- a/packages/chart/test/settings-polish.test.ts
+++ b/packages/chart/test/settings-polish.test.ts
@@ -406,7 +406,8 @@ describe('presetChartTheme', () => {
       grid: { color: 'rgba(255, 255, 255, 0.05)' },
       crosshair: { color: '#737373', labelBackground: '#262626', labelColor: '#fafafa' },
       series: { upColor: '#00ff3f', downColor: '#ff479c', wickUpColor: '#00ff3f', wickDownColor: '#ff479c', borderUpColor: '#00ff3f', borderDownColor: '#ff479c' },
-    }, 'no fonts, sizes, toggles or volume');
+      heatmap: { stops: bloxwapDark.heatmap!.stops },
+    }, 'no fonts, sizes, toggles, volume or heatmap curve');
   });
 
   it('gives the other theme its built-in colors, with the preset-only colors back at their defaults', () => {
@@ -416,6 +417,7 @@ describe('presetChartTheme', () => {
       grid: CHART_THEMES.light.grid,
       crosshair: { color: CHART_THEMES.light.crosshair!.color, labelBackground: DEFAULT_CONFIG.crosshair.labelBackground, labelColor: 'auto' },
       series: { upColor: '#089981', downColor: '#f23645', wickUpColor: '', wickDownColor: '', borderUpColor: '', borderDownColor: '' },
+      heatmap: { stops: [] },
     });
   });
 
diff --git a/packages/chart/test/trades.test.ts b/packages/chart/test/trades.test.ts
new file mode 100644
index 0000000..53fd6af
--- /dev/null
+++ b/packages/chart/test/trades.test.ts
@@ -0,0 +1,347 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  MAX_FOOTPRINT_BARS,
+  createDatafeedChart,
+  createTradeAggregation,
+  type Candle,
+  type DatafeedChartOptions,
+  type Trade,
+} from '../dist/datafeed/index.js';
+import {
+  PriceScale,
+  TimeScale,
+  createChart,
+  createTradePrintsPrimitive,
+  type PrimitiveDrawTarget,
+} from '../dist/index.js';
+import { MockCanvas, MockContext2D } from '../dist/dom.js';
+
+const MIN = 60_000;
+const T0 = 1_700_000_040_000; // a 1m boundary
+
+const bar = (tMs: number): Candle => ({ time: tMs / 1000, open: 100, high: 101, low: 99, close: 100, volume: 1 });
+
+const trade = (time: number, price: number, size: number, side: Trade['side'] = 'buy'): Trade => ({ time, price, size, side });
+
+async function idle(): Promise<void> {
+  for (let i = 0; i < 5; i++) await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+function setupFeed(options: Partial<DatafeedChartOptions> & { noSymbol?: boolean } = {}) {
+  const { noSymbol = false, ...overrides } = options;
+  const errors: unknown[] = [];
+  const canvas = new MockCanvas(800, 400);
+  const df = createDatafeedChart({
+    container: canvas,
+    config: { wasm: false },
+    fetchBars: async ({ toMs }) => (toMs >= T0 - MIN ? [bar(T0 - MIN), bar(T0)] : []),
+    ...(noSymbol ? {} : { symbol: 'BTC', intervalMs: MIN }),
+    onError: (error) => errors.push(error),
+    ...overrides,
+  });
+  return { ...df, errors, canvas };
+}
+
+describe('trade aggregation', () => {
+  it('folds trades into (bar, price) levels of buy and sell size and count', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(T0 + 1_000, 101, 5));
+    tape.push(trade(T0 + 2_000, 100, 2));
+    tape.push(trade(T0 + 3_000, 100, 1, 'sell'));
+    const bar0 = tape.bar(T0)!;
+    assert.equal(bar0.time, T0);
+    assert.deepEqual(bar0.levels, [
+      { price: 100, buySize: 2, sellSize: 1, buyCount: 1, sellCount: 1 },
+      { price: 101, buySize: 5, sellSize: 0, buyCount: 1, sellCount: 0 },
+    ]);
+    assert.equal(bar0.buySize, 7);
+    assert.equal(bar0.sellSize, 1);
+    assert.equal(bar0.buyCount, 2);
+    assert.equal(bar0.sellCount, 1);
+  });
+
+  it('buckets trades into epoch-aligned bars', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(T0 + MIN - 1, 100, 1));
+    tape.push(trade(T0 + MIN, 100, 1));
+    assert.equal(tape.size, 2);
+    assert.equal(tape.bar(T0 + MIN - 1)!.time, T0);
+    assert.equal(tape.bar(T0 + MIN)!.time, T0 + MIN);
+  });
+
+  it('returns null for an empty bucket and filters and sorts barsInRange', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(T0 + 2 * MIN, 100, 1));
+    tape.push(trade(T0, 100, 1));
+    tape.push(trade(T0 + 4 * MIN, 100, 1));
+    assert.equal(tape.bar(T0 + MIN), null);
+    assert.deepEqual(
+      tape.barsInRange(T0 - MIN, T0 + 3 * MIN).map((b) => b.time),
+      [T0, T0 + 2 * MIN],
+    );
+    assert.deepEqual(tape.barsInRange(T0 + MIN, T0 + 2 * MIN - 1), []);
+  });
+
+  it('ignores invalid trades', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(Number.NaN, 100, 1));
+    tape.push(trade(T0, Number.NaN, 1));
+    tape.push(trade(T0, 100, Number.NaN));
+    tape.push(trade(T0, 100, 0));
+    tape.push(trade(T0, 100, -1));
+    tape.push(trade(T0, 100, 1, 'hold' as Trade['side']));
+    assert.equal(tape.size, 0);
+  });
+
+  it('evicts the oldest bar beyond maxBars', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN, maxBars: 2 });
+    tape.push(trade(T0, 100, 1));
+    tape.push(trade(T0 + MIN, 100, 1));
+    tape.push(trade(T0 + 2 * MIN, 100, 1));
+    assert.equal(tape.size, 2);
+    assert.equal(tape.bar(T0), null);
+    assert.notEqual(tape.bar(T0 + 2 * MIN), null);
+  });
+
+  it('drops a late trade for an already-evicted bucket', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN, maxBars: 1 });
+    tape.push(trade(T0, 100, 1));
+    tape.push(trade(T0 + MIN, 100, 1));
+    tape.push(trade(T0, 100, 9));
+    assert.equal(tape.size, 1);
+    assert.equal(tape.bar(T0), null, 'the late trade does not resurrect the evicted bar');
+    assert.equal(tape.bar(T0 + MIN)!.buySize, 1);
+  });
+
+  it('throws on invalid options', () => {
+    assert.throws(() => createTradeAggregation({ intervalMs: 0 }), /intervalMs/);
+    assert.throws(() => createTradeAggregation({ intervalMs: 1.5 }), /intervalMs/);
+    assert.throws(() => createTradeAggregation({ intervalMs: MIN, maxBars: 0 }), /maxBars/);
+  });
+
+  it('clear() empties the store', () => {
+    const tape = createTradeAggregation({ intervalMs: MIN });
+    tape.push(trade(T0, 100, 1));
+    tape.clear();
+    assert.equal(tape.size, 0);
+    assert.equal(tape.bar(T0), null);
+    assert.ok(MAX_FOOTPRINT_BARS > 0);
+  });
+});
+
+describe('datafeed trades channel', () => {
+  it('delivers pushed trades to subscribeTrades and folds them into the footprint', async () => {
+    const t = setupFeed();
+    await idle();
+    const trades: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    t.datafeed.pushTrade(trade(T0 + 1_000, 100, 2));
+    t.datafeed.pushTrade(trade(T0 + 2_000, 101, 3, 'sell'));
+    assert.deepEqual(trades, [trade(T0 + 1_000, 100, 2), trade(T0 + 2_000, 101, 3, 'sell')]);
+    const bar0 = t.datafeed.footprintBar(T0)!;
+    assert.deepEqual(bar0.levels, [
+      { price: 100, buySize: 2, sellSize: 0, buyCount: 1, sellCount: 0 },
+      { price: 101, buySize: 0, sellSize: 3, buyCount: 0, sellCount: 1 },
+    ]);
+    assert.deepEqual(t.datafeed.footprintBars(T0 - MIN, T0).map((b) => b.time), [T0]);
+    assert.equal(t.datafeed.footprintBar(T0 + MIN), null);
+    assert.deepEqual(t.errors, []);
+    t.destroy();
+  });
+
+  it('ignores trades tagged with another symbol', async () => {
+    const t = setupFeed();
+    await idle();
+    const trades: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    t.datafeed.pushTrade(trade(T0, 100, 1), 'ETH');
+    assert.deepEqual(trades, []);
+    assert.equal(t.datafeed.footprintBar(T0), null);
+    t.destroy();
+  });
+
+  it('passes the tape through as received, even a trade the footprint drops', async () => {
+    const t = setupFeed();
+    await idle();
+    const trades: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    t.datafeed.pushTrade(trade(T0, 100, 0));
+    assert.deepEqual(trades, [trade(T0, 100, 0)]);
+    assert.equal(t.datafeed.footprintBar(T0), null);
+    t.destroy();
+  });
+
+  it("a trade listener's error goes to onError and pushTrade does not throw", async () => {
+    const t = setupFeed();
+    await idle();
+    const trades: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', () => {
+      throw new Error('boom');
+    });
+    t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    t.datafeed.pushTrade(trade(T0, 100, 1));
+    assert.deepEqual(trades, [trade(T0, 100, 1)], 'a throwing listener does not starve the rest');
+    assert.deepEqual(t.errors.length, 1);
+    assert.notEqual(t.datafeed.footprintBar(T0), null, 'the trade still folded into the footprint');
+    t.destroy();
+  });
+
+  it('unsubscribe stops delivery but not the footprint', async () => {
+    const t = setupFeed();
+    await idle();
+    const trades: Trade[] = [];
+    const off = t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    off();
+    t.datafeed.pushTrade(trade(T0, 100, 1));
+    assert.deepEqual(trades, []);
+    assert.notEqual(t.datafeed.footprintBar(T0), null);
+    t.destroy();
+  });
+
+  it('a symbol switch starts a fresh footprint and silences the old symbol', async () => {
+    const t = setupFeed();
+    await idle();
+    const btc: Trade[] = [];
+    const eth: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', (trade) => btc.push(trade));
+    t.datafeed.subscribeTrades('ETH', (trade) => eth.push(trade));
+    t.datafeed.pushTrade(trade(T0, 100, 1));
+    await t.datafeed.setSymbol('ETH', MIN);
+    assert.equal(t.datafeed.footprintBar(T0), null, 'the new session has its own footprint');
+    t.datafeed.pushTrade(trade(T0, 200, 2), 'BTC');
+    t.datafeed.pushTrade(trade(T0, 200, 2));
+    assert.deepEqual(btc, [trade(T0, 100, 1)], "the old symbol's listener hears nothing more");
+    assert.deepEqual(eth, [trade(T0, 200, 2)]);
+    assert.equal(t.datafeed.footprintBar(T0)!.buySize, 2);
+    t.destroy();
+  });
+
+  it('before the first setSymbol, pushTrade is ignored and footprint queries are empty', () => {
+    const t = setupFeed({ noSymbol: true });
+    const trades: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    t.datafeed.pushTrade(trade(T0, 100, 1));
+    assert.deepEqual(trades, []);
+    assert.equal(t.datafeed.footprintBar(T0), null);
+    assert.deepEqual(t.datafeed.footprintBars(0, Number.MAX_SAFE_INTEGER), []);
+    t.destroy();
+  });
+
+  it('destroy stops the trades channel', async () => {
+    const t = setupFeed();
+    await idle();
+    const trades: Trade[] = [];
+    t.datafeed.subscribeTrades('BTC', (trade) => trades.push(trade));
+    t.datafeed.destroy();
+    t.datafeed.pushTrade(trade(T0, 100, 1));
+    assert.deepEqual(trades, []);
+    assert.equal(t.datafeed.footprintBar(T0), null);
+    t.chart.destroy();
+  });
+});
+
+describe('trade prints primitive', () => {
+  const candles = [bar(T0), bar(T0 + MIN), bar(T0 + 2 * MIN)];
+
+  function target(): PrimitiveDrawTarget {
+    const timeScale = new TimeScale(10, 800);
+    const priceScale = new PriceScale();
+    priceScale.height = 400;
+    priceScale.setRange(99, 101);
+    return { width: 800, height: 400, priceScale, timeScale, range: { from: 0, to: 3 }, candles, pixelRatio: 1 };
+  }
+
+  it('paints each retained trade at its bar and price, sized by the square root of its size', () => {
+    const prints = createTradePrintsPrimitive();
+    prints.push(trade(T0 + 30_000, 100, 25));
+    prints.push(trade(T0 + MIN + 30_000, 101, 1, 'sell'));
+    const ctx = new MockContext2D();
+    prints.draw(ctx, target());
+    const ellipses = ctx.callsNamed('ellipse');
+    assert.deepEqual(ellipses.length, 2);
+    const t0 = target();
+    assert.deepEqual(ellipses[0], ['ellipse', t0.timeScale.indexToX(0, 3), t0.priceScale.priceToY(100), 5, 5, 0, 0, Math.PI * 2]);
+    assert.deepEqual(ellipses[1], ['ellipse', t0.timeScale.indexToX(1, 3), t0.priceScale.priceToY(101), 2, 2, 0, 0, Math.PI * 2]);
+  });
+
+  it('clamps the radius to [minRadius, maxRadius]', () => {
+    const prints = createTradePrintsPrimitive();
+    prints.push(trade(T0, 100, 10_000));
+    prints.push(trade(T0, 100, 0.0001));
+    const ctx = new MockContext2D();
+    prints.draw(ctx, target());
+    const radii = ctx.callsNamed('ellipse').map((c) => c[3]);
+    assert.deepEqual(radii, [8, 2]);
+  });
+
+  it('skips trades before the first bar and invalid trades, and pins a late trade to the last bar', () => {
+    const prints = createTradePrintsPrimitive();
+    prints.push(trade(T0 - MIN, 100, 1)); // before the first bar
+    prints.push(trade(T0 + 10 * MIN, 100, 1)); // past the last bar: the live-tape case
+    prints.push(trade(Number.NaN, 100, 1));
+    prints.push(trade(T0, 100, -1));
+    assert.equal(prints.size, 2, 'only valid trades are retained');
+    const ctx = new MockContext2D();
+    prints.draw(ctx, target());
+    const ellipses = ctx.callsNamed('ellipse');
+    assert.deepEqual(ellipses.length, 1);
+    assert.equal(ellipses[0]![1], target().timeScale.indexToX(2, 3), 'the late trade pins to the last bar');
+    prints.draw(ctx, { ...target(), range: { from: 0, to: 0 } });
+    assert.deepEqual(ctx.callsNamed('ellipse').length, 1, 'an empty range paints nothing more');
+  });
+
+  it('ignores a trade with an unknown side', () => {
+    const prints = createTradePrintsPrimitive();
+    prints.push(trade(T0, 100, 1, 'hold' as Trade['side']));
+    assert.equal(prints.size, 0);
+    const ctx = new MockContext2D();
+    prints.draw(ctx, target());
+    assert.deepEqual(ctx.calls, []);
+  });
+
+  it('bounds the ring by maxTrades, evicting the oldest', () => {
+    const prints = createTradePrintsPrimitive({ maxTrades: 2 });
+    prints.push(trade(T0, 99, 1));
+    prints.push(trade(T0, 100, 1));
+    prints.push(trade(T0, 101, 1));
+    assert.equal(prints.size, 2);
+    const ctx = new MockContext2D();
+    prints.draw(ctx, target());
+    const prices = ctx.callsNamed('ellipse').map((c) => target().priceScale.yToPrice(c[2] as number));
+    assert.deepEqual(prices, [100, 101]);
+  });
+
+  it('clear() drops every retained trade', () => {
+    const prints = createTradePrintsPrimitive();
+    prints.push(trade(T0, 100, 1));
+    prints.clear();
+    assert.equal(prints.size, 0);
+    const ctx = new MockContext2D();
+    prints.draw(ctx, target());
+    assert.deepEqual(ctx.calls, []);
+  });
+
+  it('throws on invalid options', () => {
+    assert.throws(() => createTradePrintsPrimitive({ maxTrades: 0 }), /maxTrades/);
+    assert.throws(() => createTradePrintsPrimitive({ minRadius: -1 }), /minRadius/);
+    assert.throws(() => createTradePrintsPrimitive({ minRadius: 5, maxRadius: 4 }), /minRadius/);
+  });
+
+  it('draws through the chart on attachPrimitive and requestUpdate', () => {
+    const canvas = new MockCanvas(800, 400);
+    const chart = createChart({ container: canvas, config: { wasm: false, data: candles } });
+    const prints = createTradePrintsPrimitive();
+    const handle = chart.attachPrimitive(prints);
+    const before = canvas.context.countCalls('ellipse');
+    prints.push(trade(T0 + 30_000, 100, 4));
+    prints.push(trade(T0 + MIN + 30_000, 100.5, 4, 'sell'));
+    handle.requestUpdate();
+    assert.equal(canvas.context.countCalls('ellipse') - before, 2, 'one print per retained trade');
+    handle.detach();
+    const after = canvas.context.countCalls('ellipse');
+    handle.requestUpdate();
+    assert.equal(canvas.context.countCalls('ellipse'), after, 'a detached primitive no longer paints');
+    chart.destroy();
+  });
+});
diff --git a/packages/chart/test/webgl.test.ts b/packages/chart/test/webgl.test.ts
new file mode 100644
index 0000000..fa92bc1
--- /dev/null
+++ b/packages/chart/test/webgl.test.ts
@@ -0,0 +1,429 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createChart } from '../dist/index.js';
+import { MockCanvas, MockContext2D, MockContextWebGL2, MockDocument, MockGLCanvas, MockGLDocument } from '../dist/dom.js';
+import type { ChartCanvas } from '../dist/dom.js';
+import { GLBackend } from '../dist/render/gl/backend.js';
+import { parseColor } from '../dist/color.js';
+import type { Candle } from '../dist/core/data.js';
+import type { DepthBook } from '../dist/core/depth.js';
+import { PriceScale, TimeScale } from '../dist/core/scale.js';
+import { resolveConfig } from '../dist/config.js';
+import { drawCandlesticks } from '../dist/series/candlestick.js';
+import { packCandleQuads } from '../dist/render/gl/candles.js';
+import { heatmapRamp, heatmapRampRGBA, HEATMAP_RAMP_STEPS } from '../dist/render/heatmap.js';
+
+const candles: Candle[] = Array.from({ length: 60 }, (_, i) => ({
+  time: 1700000000 + i * 60,
+  open: 100 + i * 0.1,
+  high: 101.5 + i * 0.1,
+  low: 98.5 + i * 0.1,
+  close: 100.5 + i * 0.1 * (i % 2 === 0 ? 1 : -1),
+  volume: 1000 + i,
+}));
+
+function book(timeMs: number): DepthBook {
+  const bids: [number, number][] = [];
+  const asks: [number, number][] = [];
+  for (let j = 0; j < 10; j++) {
+    bids.push([103.5 - j * 0.5, (j + 1) * 3]);
+    asks.push([104.5 + j * 0.5, (j + 1) * 2]);
+  }
+  return { bids, asks, time: timeMs };
+}
+
+function glInstances(gl: { callsNamed(name: string): readonly (readonly [string, ...unknown[]])[] }): number {
+  return gl.callsNamed('drawArraysInstanced').reduce((sum, call) => sum + (call[4] as number), 0);
+}
+
+describe('webgl2 backend selection', () => {
+  it('falls back to canvas2d when the canvas has no webgl2 context, with identical 2D output', () => {
+    const plain = new MockDocument();
+    const plainChart = createChart({ document: plain, config: { width: 800, height: 500, data: candles, wasm: false } });
+    const fallback = new MockDocument();
+    const fallbackChart = createChart({ document: fallback, renderer: 'webgl2', config: { width: 800, height: 500, data: candles, wasm: false } });
+    assert.equal(fallbackChart.renderBackend, 'canvas2d');
+    assert.deepEqual(fallback.created[0]!.context.calls, plain.created[0]!.context.calls);
+    plainChart.destroy();
+    fallbackChart.destroy();
+  });
+
+  it('selects webgl2 when the document provides a context', () => {
+    const doc = new MockGLDocument();
+    const chart = createChart({ document: doc, renderer: 'webgl2', config: { width: 800, height: 500, data: candles, wasm: false } });
+    assert.equal(chart.renderBackend, 'webgl2');
+    assert.equal(doc.created.length, 2);
+    const ctx = doc.created[0]!.context;
+    const gl = doc.created[1]!.gl;
+    ctx.calls.length = 0;
+    gl.calls.length = 0;
+    chart.render();
+    const range = chart.scale.visibleRange();
+    const visible = Math.ceil(range.to) - Math.floor(range.from);
+    assert.equal(glInstances(gl), visible * 2); // wick + body per candle
+    assert.equal(gl.countCalls('bufferData'), 1);
+    assert.equal(ctx.countCalls('drawImage'), 1);
+    assert.equal(ctx.countCalls('fillRect'), 1); // background only; candles are quads
+    chart.destroy();
+    assert.ok(gl.countCalls('deleteProgram') === 1);
+    assert.ok(gl.countCalls('deleteBuffer') === 1);
+    assert.ok(gl.countCalls('deleteVertexArray') === 1);
+  });
+
+  it('self-clears after compositing so repaints of one frame never stack quads', () => {
+    const doc = new MockGLDocument();
+    const chart = createChart({ document: doc, renderer: 'webgl2', config: { width: 800, height: 500, data: candles, wasm: false } });
+    const gl = doc.created[1]!.gl;
+    gl.calls.length = 0;
+    chart.render();
+    chart.setCrosshair(100, 100); // repaints the cached view without a beginFrame
+    const composites = gl.countCalls('drawArraysInstanced');
+    assert.ok(composites >= 2);
+    // One clear at beginFrame plus one after each composite.
+    assert.equal(gl.countCalls('clear'), composites + 1);
+    chart.destroy();
+  });
+
+  it('falls back to canvas2d when the GL pipeline fails to build', () => {
+    for (const options of [{ compile: false }, { link: false }]) {
+      const doc = new MockGLDocument(options);
+      const chart = createChart({ document: doc, renderer: 'webgl2', config: { width: 800, height: 500, data: candles, wasm: false } });
+      assert.equal(chart.renderBackend, 'canvas2d');
+      assert.ok(doc.created[0]!.context.countCalls('fillRect') > candles.length);
+      chart.destroy();
+    }
+  });
+
+  it("builds the GL canvas from the container's ownerDocument", () => {
+    const glCanvases: MockGLCanvas[] = [];
+    const container = Object.assign(new MockCanvas(800, 500), {
+      ownerDocument: {
+        createElement: (_tag: 'canvas') => {
+          const canvas = new MockGLCanvas();
+          glCanvases.push(canvas);
+          return canvas;
+        },
+      },
+    });
+    const chart = createChart({ container, renderer: 'webgl2', config: { width: 800, height: 500, data: candles, wasm: false } });
+    assert.equal(chart.renderBackend, 'webgl2');
+    assert.equal(glCanvases.length, 1);
+    assert.ok(glInstances(glCanvases[0]!.gl) > 0);
+    chart.destroy();
+  });
+
+  it('stays on canvas2d when neither the container nor an injected document can make a canvas', () => {
+    const container = new MockCanvas(800, 500);
+    const chart = createChart({ container, renderer: 'webgl2', config: { width: 800, height: 500, data: candles, wasm: false } });
+    assert.equal(chart.renderBackend, 'canvas2d');
+    assert.ok(container.context.countCalls('fillRect') > candles.length);
+    chart.destroy();
+  });
+
+  it('keeps bordered candles and unparseable colors on the Canvas2D series path', () => {
+    const bordered = new MockGLDocument();
+    const borderedChart = createChart({
+      document: bordered,
+      renderer: 'webgl2',
+      config: { width: 800, height: 500, data: candles, wasm: false, series: { borderVisible: true } },
+    });
+    assert.equal(borderedChart.renderBackend, 'webgl2');
+    const ctx = bordered.created[0]!.context;
+    assert.ok(ctx.countCalls('stroke') >= candles.length); // borders stroke per candle
+    assert.ok(ctx.countCalls('fillRect') > candles.length); // bodies stay 2D
+    assert.equal(ctx.countCalls('drawImage'), 0); // no quads, no composite
+    borderedChart.destroy();
+
+    const badColor = new MockGLDocument();
+    const badColorChart = createChart({
+      document: badColor,
+      renderer: 'webgl2',
+      config: { width: 800, height: 500, data: candles, wasm: false, series: { upColor: 'not-a-color' } },
+    });
+    assert.equal(badColorChart.renderBackend, 'webgl2');
+    assert.ok(badColor.created[0]!.context.countCalls('fillRect') > candles.length);
+    badColorChart.destroy();
+  });
+});
+
+describe('webgl2 heatmap', () => {
+  function feedHeatmap(doc: MockDocument | MockGLDocument, renderer?: 'webgl2') {
+    const chart = createChart({
+      document: doc,
+      ...(renderer !== undefined ? { renderer } : {}),
+      config: { width: 800, height: 500, data: candles, wasm: false, heatmap: { enabled: true } },
+    });
+    for (let k = 0; k < candles.length; k++) chart.setDepth(book((1700000000 + k * 60) * 1000 + 500));
+    return chart;
+  }
+
+  it('emits one quad per Canvas2D heatmap run', () => {
+    const plainDoc = new MockDocument();
+    const plain = feedHeatmap(plainDoc);
+    const glDoc = new MockGLDocument();
+    const glChart = feedHeatmap(glDoc, 'webgl2');
+    assert.equal(glChart.renderBackend, 'webgl2');
+
+    const ctx = plainDoc.created[0]!.context;
+    ctx.calls.length = 0;
+    plain.render();
+    const fills2d = ctx.countCalls('fillRect') - 1; // minus the background
+
+    const glCtx = glDoc.created[0]!.context;
+    const gl = glDoc.created[1]!.gl;
+    glCtx.calls.length = 0;
+    gl.calls.length = 0;
+    glChart.render();
+    assert.equal(glInstances(gl), fills2d);
+    assert.equal(glCtx.countCalls('fillRect'), 1); // background only
+    assert.equal(glCtx.countCalls('drawImage'), 1);
+    plain.destroy();
+    glChart.destroy();
+  });
+});
+
+describe('packCandleQuads', () => {
+  class RectRecorder extends MockContext2D {
+    readonly rects: { x: number; y: number; w: number; h: number; fill: string }[] = [];
+    override fillRect(x: number, y: number, w: number, h: number): void {
+      this.rects.push({ x, y, w, h, fill: this.fillStyle as string });
+      super.fillRect(x, y, w, h);
+    }
+  }
+
+  function scales() {
+    const timeScale = new TimeScale(6, 0);
+    timeScale.setViewport(500);
+    const priceScale = new PriceScale();
+    priceScale.height = 400;
+    priceScale.setRange(90, 110);
+    return { timeScale, priceScale };
+  }
+
+  it('mirrors drawCandlesticks geometry and colors quad-for-quad', () => {
+    const { timeScale, priceScale } = scales();
+    const config = resolveConfig({}).series;
+    const range = { from: 0, to: candles.length };
+    const liveCandle: Candle = { ...candles[candles.length - 1]!, close: 90 };
+
+    const recorder = new RectRecorder();
+    drawCandlesticks(recorder, candles, range, timeScale, priceScale, config, liveCandle);
+
+    const quads: number[][] = [];
+    const ok = packCandleQuads(
+      { quad: (...q) => quads.push(q) },
+      candles,
+      range,
+      timeScale,
+      priceScale,
+      config,
+      liveCandle,
+    );
+    assert.equal(ok, true);
+    assert.equal(quads.length, recorder.rects.length);
+    assert.ok(quads.length > 0);
+    for (const [i, rect] of recorder.rects.entries()) {
+      const quad = quads[i]!;
+      assert.deepEqual(quad.slice(0, 4), [rect.x, rect.y, rect.w, rect.h]);
+      const parsed = parseColor(rect.fill)!;
+      assert.ok(Math.abs(quad[4]! - parsed.r / 255) < 1e-6);
+      assert.ok(Math.abs(quad[5]! - parsed.g / 255) < 1e-6);
+      assert.ok(Math.abs(quad[6]! - parsed.b / 255) < 1e-6);
+      assert.ok(Math.abs(quad[7]! - parsed.a) < 1e-6);
+    }
+  });
+
+  it('returns false without emitting when a color is unparseable', () => {
+    const { timeScale, priceScale } = scales();
+    const config = { ...resolveConfig({}).series, upColor: 'not-a-color' };
+    const quads: number[][] = [];
+    const ok = packCandleQuads({ quad: (...q) => quads.push(q) }, candles, { from: 0, to: candles.length }, timeScale, priceScale, config);
+    assert.equal(ok, false);
+    assert.equal(quads.length, 0);
+  });
+
+  it('returns false when any one of down/wick colors is unparseable', () => {
+    const { timeScale, priceScale } = scales();
+    const variants = [
+      { downColor: 'not-a-color' },
+      { wickUpColor: 'not-a-color' },
+      { wickDownColor: 'not-a-color' },
+    ];
+    for (const variant of variants) {
+      const config = { ...resolveConfig({}).series, ...variant };
+      const quads: number[][] = [];
+      const ok = packCandleQuads({ quad: (...q) => quads.push(q) }, candles, { from: 0, to: candles.length }, timeScale, priceScale, config);
+      assert.equal(ok, false);
+      assert.equal(quads.length, 0);
+    }
+  });
+
+  it('uses explicit wick colors when they are not empty strings', () => {
+    const { timeScale, priceScale } = scales();
+    const config = {
+      ...resolveConfig({}).series,
+      upColor: '#00ff00',
+      downColor: '#ff0000',
+      wickUpColor: '#0000ff',
+      wickDownColor: '#ffff00',
+    };
+    const quads: number[][] = [];
+    const ok = packCandleQuads({ quad: (...q) => quads.push(q) }, candles, { from: 0, to: candles.length }, timeScale, priceScale, config);
+    assert.equal(ok, true);
+    const wicks = quads.filter((q) => q[2] === 1); // wick quads are 1px wide
+    assert.ok(wicks.length > 0);
+    const blues = wicks.filter((q) => q[6] === 1).length; // wickUpColor blue channel
+    const yellows = wicks.filter((q) => q[4] === 1 && q[5] === 1).length; // wickDownColor
+    assert.ok(blues > 0);
+    assert.ok(yellows > 0);
+  });
+
+  it('packs without a live candle, falling back to the candle at the last index', () => {
+    const { timeScale, priceScale } = scales();
+    const config = resolveConfig({}).series;
+    const quads: number[][] = [];
+    const ok = packCandleQuads({ quad: (...q) => quads.push(q) }, candles, { from: 0, to: candles.length }, timeScale, priceScale, config);
+    assert.equal(ok, true);
+    assert.equal(quads.length, candles.length * 2);
+  });
+
+  it('colors by the previous close when colorByPreviousClose is set', () => {
+    const { timeScale, priceScale } = scales();
+    const flat: Candle[] = [
+      { time: 1, open: 100, high: 102, low: 98, close: 101, volume: 1 },
+      { time: 2, open: 99, high: 103, low: 98, close: 100.5, volume: 1 }, // above open but below previous close
+      { time: 3, open: 99, high: 103, low: 98, close: 100.5, volume: 1 }, // equal to previous close: up
+    ];
+    const base = resolveConfig({}).series;
+    const plain: number[][] = [];
+    packCandleQuads({ quad: (...q) => plain.push(q) }, flat, { from: 0, to: flat.length }, timeScale, priceScale, { ...base, wickVisible: false });
+    const colored: number[][] = [];
+    const ok = packCandleQuads(
+      { quad: (...q) => colored.push(q) },
+      flat,
+      { from: 0, to: flat.length },
+      timeScale,
+      priceScale,
+      { ...base, wickVisible: false, colorByPreviousClose: true },
+    );
+    assert.equal(ok, true);
+    assert.equal(colored.length, flat.length);
+    const up = parseColor(base.upColor)!;
+    const down = parseColor(base.downColor)!;
+    assert.equal(colored[0]![4], up.r / 255); // first candle has no previous close: compares to open
+    assert.equal(colored[1]![4], down.r / 255); // close 100.5 < previous close 101
+    assert.equal(colored[2]![4], up.r / 255); // close 100.5 >= previous close 100.5
+    assert.equal(plain[1]![4], up.r / 255); // without the flag the same candle rises against its open
+  });
+
+  it('emits only wicks when bodyVisible is false and only bodies when wickVisible is false', () => {
+    const { timeScale, priceScale } = scales();
+    const base = resolveConfig({}).series;
+    const range = { from: 0, to: candles.length };
+
+    const wicksOnly: number[][] = [];
+    const okWicks = packCandleQuads({ quad: (...q) => wicksOnly.push(q) }, candles, range, timeScale, priceScale, { ...base, bodyVisible: false });
+    assert.equal(okWicks, true);
+    assert.equal(wicksOnly.length, candles.length);
+    assert.ok(wicksOnly.every((q) => q[2] === 1));
+
+    const bodiesOnly: number[][] = [];
+    const okBodies = packCandleQuads({ quad: (...q) => bodiesOnly.push(q) }, candles, range, timeScale, priceScale, { ...base, wickVisible: false });
+    assert.equal(okBodies, true);
+    assert.equal(bodiesOnly.length, candles.length);
+    const bodyWidth = Math.max(1, Math.floor(timeScale.barSpacing * 0.7));
+    assert.ok(bodiesOnly.every((q) => q[2] === bodyWidth));
+  });
+
+  it('passes wide-gamut colors through with a channel divisor of 1', () => {
+    const { timeScale, priceScale } = scales();
+    const config = { ...resolveConfig({}).series, upColor: 'color(display-p3 0.25 0.5 0.75)' };
+    const quads: number[][] = [];
+    const one: Candle[] = [{ time: 1, open: 100, high: 102, low: 98, close: 101, volume: 1 }];
+    const ok = packCandleQuads({ quad: (...q) => quads.push(q) }, one, { from: 0, to: 1 }, timeScale, priceScale, config);
+    assert.equal(ok, true);
+    const body = quads.find((q) => q[2] !== 1)!;
+    assert.ok(Math.abs(body[4]! - 0.25) < 1e-6);
+    assert.ok(Math.abs(body[5]! - 0.5) < 1e-6);
+    assert.ok(Math.abs(body[6]! - 0.75) < 1e-6);
+  });
+});
+
+describe('heatmapRampRGBA', () => {
+  it('matches the string ramp step for step', () => {
+    const strings = heatmapRamp('#2962ff', '#ffd54f', 0.85);
+    const floats = heatmapRampRGBA('#2962ff', '#ffd54f', 0.85);
+    assert.equal(strings.length, HEATMAP_RAMP_STEPS);
+    for (let i = 0; i < HEATMAP_RAMP_STEPS; i++) {
+      const parsed = parseColor(strings[i]!)!;
+      assert.ok(Math.abs(floats[i * 4]! - parsed.r / 255) <= 0.5 / 255 + 1e-6);
+      assert.ok(Math.abs(floats[i * 4 + 1]! - parsed.g / 255) <= 0.5 / 255 + 1e-6);
+      assert.ok(Math.abs(floats[i * 4 + 2]! - parsed.b / 255) <= 0.5 / 255 + 1e-6);
+      assert.ok(Math.abs(floats[i * 4 + 3]! - parsed.a) < 1e-6);
+    }
+    assert.equal(floats[3], 0); // step 0 is fully transparent
+  });
+});
+
+describe('GLBackend.create failure modes', () => {
+  function canvasWith(context: unknown): ChartCanvas {
+    return {
+      width: 16,
+      height: 16,
+      getContext: (contextId: string) => (contextId === 'webgl2' ? context : null),
+    } as unknown as ChartCanvas;
+  }
+
+  it('returns null when the context is undefined or not a GL context', () => {
+    assert.equal(GLBackend.create(canvasWith(undefined)), null);
+    assert.equal(GLBackend.create(canvasWith({})), null); // no createShader method
+  });
+
+  it('returns null when only the fragment shader fails to compile', () => {
+    class FragmentFailGL extends MockContextWebGL2 {
+      private readonly shaderTypes = new Map<unknown, number>();
+      override createShader(type: number): unknown {
+        const shader = super.createShader(type);
+        this.shaderTypes.set(shader, type);
+        return shader;
+      }
+      override getShaderParameter(shader: unknown, pname: number): unknown {
+        if (pname === this.COMPILE_STATUS) return this.shaderTypes.get(shader) !== this.FRAGMENT_SHADER;
+        return super.getShaderParameter(shader, pname);
+      }
+    }
+    assert.equal(GLBackend.create(canvasWith(new FragmentFailGL())), null);
+  });
+
+  it('returns null when pipeline setup throws', () => {
+    class ThrowingGL extends MockContextWebGL2 {
+      override createVertexArray(): unknown {
+        throw new Error('context lost');
+      }
+    }
+    assert.equal(GLBackend.create(canvasWith(new ThrowingGL())), null);
+  });
+});
+
+describe('GLBackend frame lifecycle', () => {
+  it('keeps the canvas size when resize is a no-op and composites nothing without quads', () => {
+    const canvas = new MockGLCanvas(32, 24);
+    const backend = GLBackend.create(canvas)!;
+    assert.ok(backend !== null);
+    backend.resize(32, 24); // same size: no backing-store reset
+    assert.equal(canvas.width, 32);
+    assert.equal(canvas.height, 24);
+    backend.resize(40, 24); // width only
+    backend.resize(40, 30); // height only
+    assert.equal(canvas.width, 40);
+    assert.equal(canvas.height, 30);
+    backend.resize(32, 24);
+    const frame = backend.beginFrame(1, 32, 24);
+    const ctx = new MockContext2D();
+    frame.composite(ctx); // no quads submitted: flush is a no-op, no drawImage
+    assert.equal(ctx.countCalls('drawImage'), 0);
+    backend.dispose();
+    assert.equal(canvas.width, 0);
+    assert.equal(canvas.height, 0);
+  });
+});